Traffic Lights - SUMO Documentation (2024)

• Traffic Lights

Normally, netconvert andnetgenerate generate traffic lights andprograms for junctions during the computation of the networks. Still,these computed programs quite often differ from those found in reality.To feed the simulation with real traffic light programs, it is possibleto run sumo/sumo-gui withadditional program definitions. Also,sumo/sumo-gui allow loadingdefinitions which describe when and how a set of traffic lights canswitch from one program to another. Both will be discussed in thefollowing subchapters. Another possibility is to edit traffic light plansvisually in netedit.

• By default, all traffic lights are generated with a fixed cycle and a cycle time of 90s. This can be changed with the option --tls.cycle.time. The osmWebWizard generates actuated traffic lights by default (see below).
• The green time is split equally between the main phases
• All green phases are followed by a yellow phase. The length of the yellow phase is computed from the maximum speed of the incoming roads but may be customized with the option --tls.yellow.time
• If the speeds at the intersection are below the threshold of 70km/h (configurable via option tls.minor-left.max-speed), left-turns are allowed at the same time as oncoming straight traffic but have to yield. This is called green minor and indicated with a lower-case g in the state definition. Otherwise, the left-turning stream must use a protected left-turn phase (see below). If no such phase can be built because there is no dedicated turning lane, green minor is allowed anyway but a warning is issued.
• If a green phase allows for partially conflicting streams (i.e. straight going and left-turning from the opposite direction) and there is a dedicated turning lane, it is succeeded by another green phase with full priority to the partially conflicted streams (this would typically be a left-turning phase). The duration of this phase defaults to 6s and can be customized (or disabled) by setting the option --tls.left-green.time.
• The generated cycle starts at time 0 by default with a green phase for the first main direction (sorted by road priority, lane count and speed). This can be influenced for a specified list of traffic light ids using the options --tls.half-offset TLS1,TLS2,.. and --tls.quarter-offset TLS3,TLS4,.... (shifting the start of the first phase by the indicated fraction of the cycle time).
• In reality there are often phases where all streams have red to allow clearing an intersection. SUMO does not build these phases by default. To have each green phase preceded by an all-red phase, the option --tls.allred.time can be used.
• It is also possible to generate Actuated Traffic Lights by setting the option --tls.default-type. This will generated the same signal plans as above but with green phases that have a variable length of 5s-50s (both values can be set using the options --tls.min-dur, --tls.max-dur). - default type actuated: traffic light actuation is based on gaps measured by automatically generated induction loops - default type delay_based: actuation is based on vehicle delays
• The generated phase layout can be selected setting option --tls.layout to opposites (default) or incoming (see below).
• The generated phase layout is also influenced by the node type which may be either traffic_light or traffic_light_right_on_red (explained below)

Default 4-arm intersection (layout opposites)#

By default, programs are generated with 4 green phases:

1. a straight phase
2. a left-turning phase (only if there is a dedicated left-turn lane)
3. a straight phase for the direction orthogonal to the first one
4. a left-turning phase for the direction direction orthogonal to the first one (only if there is a dedicated left-turn lane)

Due to the default timings explained above, the green phases usuallyhave a duration of 31s.

If the node type is set to traffic_light_right_on_red rather thantraffic_light, then right turns from all sides are permitted in allphases (after coming to a stop before entering the traffic stream thatcurrently has the green light.

Intersection layout incoming#

• each incoming edge of the intersection gets a separate green phasewhere all directions of movement are allowed
• If the node type is set to traffic_light_right_on_red ratherthan traffic_light, then compatible right-turns are allowedsimultaneously

Intersection layout alternateOneWay#

This layout can be used to model alternating access to a road section which can only be used by one direction at a time.To make use of this layout, a joint traffic light must be defined for all junctions that border the restricted section. Alternating green phases are separated by an all-red phase that is long enough to clear the interior section.

Other Intersections#

• If there are more than 4 roads meeting at an intersection,additional green phases are generated
• If the roads meeting at an intersection have the highest roadpriorities on a turning stream, then layout incoming may begenerated instead of layout opposites.
• If a traffic-light junction does not have any conflicting roads(i.e. it models a pedestrian crossing) it will not get a red phaseby default. A single red phase may be generated by setting theoption --tls.red.time.

Improving Generated programs with knowledge about traffic demand#

Using actuated traffic lights#

To get traffic lights that adapt to demand dynamically, built thenetwork with option --tls.default-type actuated. This will automatically generate actuatedtraffic lights.

To convert an existing .net.xml file so that all traffic lights are actuated,perform the following call:

netconvert -s orig.net.xml --o new.net.xml --tls.rebuild --tls.default-type actuated

Adapting fixed timings (green split) to known traffic#

tlsCycleAdaptation.pycan be used to modify green phase durations to accommodate a giventraffic demand.

Coordinating fixed timings#

The tool tlsCoordinator.pycan be used to modify program offsets to generated green waves for agiven traffic demand.

You can load new definitions for traffic lights as a part of an additional-file. Whenloaded, the last program will be used. Switching between programs ispossible via WAUTs and/or TraCI. Also, one can switch between them usingthe GUI context menu. A definition of a traffic light program within an additional-filelooks like this:

<additional> <tlLogic id="0" programID="my_program" offset="0" type="static"> <phase duration="31" state="GGggrrrrGGggrrrr"/> <phase duration="5" state="yyggrrrryyggrrrr"/> <phase duration="6" state="rrGGrrrrrrGGrrrr"/> <phase duration="5" state="rryyrrrrrryyrrrr"/> <phase duration="31" state="rrrrGGggrrrrGGgg"/> <phase duration="5" state="rrrryyggrrrryygg"/> <phase duration="6" state="rrrrrrGGrrrrrrGG"/> <phase duration="5" state="rrrrrryyrrrrrryy"/> </tlLogic></additional>

<tlLogic> Attributes#

The following attributes/elements are used within the tlLogic element:

<phase> Attributes#

Each phase is defined using the following attributes:

Signal state definitions#

Each character within a phase's state describes the state of one signalof the traffic light. Please note, that a single lane may containseveral signals - for example one for vehicles turning left and one forvehicles which move straight. This means that a signal does not controllanes, but links - each connecting a lane which is incoming into ajunction and one which is outgoing from this junction. In SUMO, aone-to-n dependency between signals and links is implemented, this meanseach signal may control more than a single link - though networksgenerated by netconvert ornetgenerate usually use one signal per link.Please note also, that a traffic light may control lanes incoming intodifferent junctions. The information about which link is controlled bywhich traffic light signal may be obtained using the "show link tlsindex" option within sumo-gui's visualizationsettings or from the according linkIndexattribute of the <connection> elements in the .net.xml file.

The following signal colors are used:

Example: traffic light with the current state"GrGr". The leftmost letter "G" encodes the green light for link 0,followed by red for link 1, green for link 2 and red for link 3. Thelink numbers are enabled via sumo-gui settings byactivating show link tls index.

Default link indices#

For traffic lights that control a single intersection, the defaultindices generated generated bynetconvertare numbered in a clockwise pattern starting with 0 at 12 o'clock withright-turns ordered before straight connections and left turns.Pedestriancrossings are alwaysassigned at the very end, also in a clockwise manner.

If traffic lights are joined so that a single program controls multipleintersections, the ordering for each intersection stays the same but theindices are increased according the order of the controlled junctions inthe input file.

Accessing indices programmatically#

TLS Link indices can be access using either

• sumolib using tls.getConnections()
• or TraCI using traci.trafficlight.getControlledLinks()

Viewing TLS-Programs graphically#

In the sumo-gui you can right-click on a red/green stop bar and select showphases.

Interaction between signal plans and right-of-way rules#

Every traffic light intersection has the right-of-way rules of apriority intersection underneath of it. This becomes obvious whenswitching a traffic light off (either in sumo-guiwith a right-click on the traffic light or by loading the "off"program).

The right-of-way rules of this priority intersection come into play whendefining signal plans with simultaneous conflicting green streams (byusing g and G states). These signal plans only work correctly if theright-of-way rules force vehicles from the g stream to yield to theG stream. In most cases, this relationship was set correctly by thedefault signal plan.

However, when introducing new g/G relationships, correctness is onlyensured by loading the network and the new signal plan intonetconvert and thus updating the right-of-wayrules.

Generally, the designation "actuated" refers to traffic lights that switch in response to traffic (or lack thereof). The different controllers and their features are described below. SUMO supports several algorithms with this property and they are described below.

Type 'actuated'#

SUMO supports gap-based actuated traffic control. This control schemeis common in Germany and works by prolonging traffic phases whenever acontinuous stream of traffic is detected. It switches to the next phaseafter detecting a sufficient time gap between successive vehicles. Thisallows for better distribution of green-time among phases and alsoaffects cycle duration in response to dynamic traffic conditions.

To use this type of control, the <tlLogic>-element needs to receive the attributetype="actuated". It also requires the usage of the phase-attributes minDur and maxDur instead of duration todefine the allowed range of time durations for each phase (if thesevalues are equal or only duration is given, that phase will have constantduration). Additional parameters may be used to configure the controlalgorithm further. These may be given within the <tlLogic>-Element as follows:

Detectors#

The time gaps which determine the phase extensions are collected by induction loop detectors.These detectors are placed automatically at a configurable distance (see below). If the incoming lanes are too short and there is a sequence of unique predecessor lanes, the detector will be placed on a predecessor lane at the computed distance instead.

The detector names take the form TLSID_PROGRAMID_EDGEINDEX.LANEINDEX where

• TLSID is the id of the tlLogic element
• PROGRAMID is the value attribute 'programID'
• EDGEINDEX is a running index that starts at 0 for edge that approaches tls linkIndex 0 (typically the northern approach)
• LANEINDEX is a running index for the current edge that starts at the first vehicular lane (sidewalks do not count)

Each lane incoming to the traffic light will receive a detector. However, not all detectors can be used in all phases.In the current implementation, detectors for actuation are only used if all connections from the detector lane gets the unconditional green light ('G') in a particular phase. This is done to prevent useless phase extensions when the first vehicle on a given lane is not allowed to drive. A simple fix is often the provide dedicate left turn lanes.

Detector activation states can optionally be written to the TLS output.

Example#

<tlLogic id="0" programID="my_program" offset="0" type="actuated"> <param key="max-gap" value="3.0"/> <param key="detector-gap" value="2.0"/> <param key="passing-time" value="2.0"/> <param key="vTypes" value=""/> <param key="show-detectors" value="false"/> <param key="file" value="NUL"/> <param key="freq" value="300"/> <param key="jam-threshold" value="-1"/> <param key="detector-length" value="0"/> <phase duration="31" minDur="5" maxDur="45" state="GGggrrrrGGggrrrr"/> ...</tlLogic>

Parameters#

Several optional parameters can be used to control the behavior of actuated traffic lights. The examples values in the previous section are the default values for these parameters and their meaning is given below:

• max-gap: the maximum time gap between successive vehicles that will cause the current phase to be prolonged(within maxDur limit)
• detector-gap: determines the time distance between the (automatically generated) detector and the stop line in seconds (ateach lanes maximum speed).
• passing-time: estimates the headway between vehicles when passing the stop line. This sets an upper bound on the distance between detector and stop line according to the formula (minDur / passingTime + 0.5) * 7.5. The intent of this bound is to allow all vehicles between the detector and the stop line to pass the intersection within the minDur time. A warning will be issued if the minDur gives insufficient clearing time.
• linkMaxDur:X (where X is a traffic light index): This sets an additional maximum duration criterion based on individual signals green duration rather than phase duration.
• linkMinDur:X (where X is a traffic light index): This sets an additional minimum duration criterion based on individual signals green duration rather than phase duration.
• show-detectors controls whether generated detectors will be visible or hidden in sumo-gui. The default for all traffic lights can be set with option --tls.actuated.show-detectors. It is also possible to toggle this value from within the GUI by right-clicking on a traffic light.
• parameters vTypes, file and freq have the same meaning as for regularinduction loop detectors.
• coordinated (true/false) Influence there reference point for time-in-cycle when using coordination
• cycleTime sets the cycle time (in s) when using coordination. Defaults to the sum of all phase 'durations' values.
• jam-threshold: ignore detected vehicles if they have stood on a detector for the given time or more
• jam-threshold:LANEID: ignore detected vehicles if they have stood on the detector on the given LANEID for the given time or more
• detector-length: set detector length to the given value (to ensure robust request detection with varying gaps and vehicle positions)

Some parameters are only used when a signal plan with dynamic phase selection is active:

• inactive-threshold (default 180): The parameter sets the time in s after which an inactive phase will be entered preferentially.
• linkMinDur:X (where X is a traffic light index): This sets an additional minimum duration criterion based on individual signals rather than phase duration

Visualization#

By setting the sumo option --tls.actuated.show-detectors the default visibility of detectors can beset. Also, in sumo-gui detectors can beshown/hidden by right-clicking on an actuated traffic light andselecting the corresponding menu entry.

The detectors used by an actuated traffic light will be colored to indicate their status:- green color indicates that the detector is used to determine the length of the current phase- white color indicates that the detector is not used in the current phase- red color indicates that a vehicle was detected since the last time at which the controlled links at that lane had a green light (only if these links are currently red)- magenta color indicates and active override

Custom Detectors#

To use custom detectors (i.e. for custom placement or output) additional parameters can be defined where KEY is a lane that is incoming to the traffic light and VALUE is a user-defined inductionLoop (that could also lie on another upstream lane).

 <param key="gneE42_2" value="customDetector1"/>

By assigning the special value NO_DETECTOR, the detector for a given lane key can be completely disabled.

Custom detector activation states can optionally be written to the TLS output.

To include further detectors in the output and in the phase tracker dialog (i.e. when a custom logic uses laneArea detectors or multiple detectors on the same lane) the following declaration can be used to list all extra detectors:

 <param key="extra-detectors" value="customDetector1 customDetector2 ..."/>

Lane-specific detector settings#

To define a max-gap value that differs from the default you can use a param with key="max-gap:<LANE_ID>" where LANE_ID is a lane incoming to the traffic light (the detector might lie further upstream).

 <param key="max-gap:gneE42_2" value="2"/>

In the same way, a custom jam-threshold or detector-length may be set:

 <param key="jam-threshold:LANE_ID" value="5"/> <param key="detector-length:LANE_ID" value="2.5"/>

Coordination#

Actuated phases (minDur != maxDur) can be coordinated by adding attributes 'earliestEnd' and 'latestEnd'.If these values are used, each step in the traffic light plan is assigned a 'timeInCycle' value depending on the value of param 'coordinated' (default 'false').

• coordinated=true: timeInCycle = (simulationTime - offset) % cycleTime (where cycleTime is taken from the param with key=cycleTime)
• coordinated=false: timeInCycle = time since last switching into phase 0

If 'earliestEnd' is set, a phase can not end while timeInCycle < earliestEnd (effectively increasing minDur)If 'latestEnd' is set, a phase cannot be prolonged when timeInCycle = latestEnd (effectively reducing maxDur).

When setting 'latestEnd' < 'earliestEnd', the phase can be extended into the next cycle.If both values are defined and a phase has already started and ended in thecurrent cycle, both values will be shifted into the next cycle to avoid having aphase run more than once in the same cycle (this only happens when param'coordinated' is set to 'true').

<tlLogic id="0" programID="my_program" offset="10" type="actuated"> <param key="coordinated" value="true"/> <param key="cycleTime" value="60"/> <phase duration="31" minDur="5" maxDur="45" state="GGggrrrrGGggrrrr" earliestEnd="10" latestEnd="50"/> ...</tlLogic>

Dynamic Phase Selection (Phase Skipping)#

When a phase uses attribute 'next' with a list of indices. The next phase is chosen dynamically based on the detector status of all candidate phases according to the following algorithm:

• compute the priority for each phase given in 'next'. Priority is primarily given by the number of active detectors for that phase. Active means either of:
  • with detection gap below threshold
  • with a detection since the last time where the signal after this detector was green
• the current phase is implicitly available for continuation as long as its maxDur is not reached. Detectors of the current phase get a bonus priority
• the phase with the highest priority is used with phases coming earlier in the next list given precedence over those coming later
• if there is no traffic, the phases will run through a default cycle defined by the first value in the 'next' attribute
  • if the traffic light uses custom switching rules then the default phase is the last value of the 'next' attribute
• if a particular phase should remain active indefinitely in the absence of traffic it must have its own index in the 'next' list as well as a high maxDur value
• if an active detector was not served for a given time threshold (param inactive-threshold), this detector receives bonus priority according the time it was not served. This can be used to prevent starvation if other phases are consistently preferred due to serving more traffic

Examples for this type of traffic light logic can be found in <SUMO_HOME>/tests/sumo/tls/actuated/multiNext/dualring_simple.

The helper script buildTransitions.py can be used to generate such logics from simplified definitions.

Type 'actuated' with custom switching rules#

By default, all traffic light programs are governed by the same pre-defined rulesthat determine which detectors are used or ignored in each phase. If moreflexibility is needed, custom conditions can be defined by using the phaseattributes 'earlyTarget' and 'finalTarget' to define logical expressions.

If the controller is in an actuated phase (minDur < maxDur) and could switchinto a new phase, the attribute 'earlyTarget' of the new phase is evaluated. Ifthe expression evaluates to 'true', the controller switches into the new phase.Otherwise it remains in the current phase. If the current phase has multiple successors (attribute 'next'),the candidates are evaluated from left to right and the first candidate where 'earlyTarget' evaluates to true is used.

If the controller has reached the maximum duration of its current phase andmultiple successor phases are defined with attribute 'next', theattribute 'finalTarget' of all candidate phases is evaluated from left to right.The first phase where the expression evaluates to 'true' is used.Otherwise, the rightmost phase in the next-list is used.

The following elements are permitted in an expression for attributes'earlyTarget' and 'finalTarget':

• numbers
• comparators >,=,>=
• mathematical operators +,-,,/,*,%
• logical operators 'or', 'and', '!'
• parentheses (,)
• pre-defined functions:
  • 'z:DETID': returns the time gap since the last vehicle detection for inductionLoop detector with id 'DETID' or id 'TLSID_PROGRAMID_DETID' (DETID may omit the the prefix 'TLSID_PROGRAMID_')
  • 'a:DETID': returns number of vehicles on detector with id 'DETID'. Supports inductionLoop and laneAreaDetectors. Also supports omitting the prefix of the detector id. (see 'z:')
  • 'g:TLSINDEX': returns current green duration in seconds for link with the given index
  • 'r:TLSINDEX': returns current red duration in seconds for link with the given index
  • 'c:': returns the time within the current cycle
• use-defined functions FNAME:arg1,args2,...,argN where arg may be any expression that does not contain spaces (except within parentheses)
• Symbolic names for pre-defined expressions

The following constraints apply to expressions:

• all elements of an expression must be separated by a space character (' ') with the exception of the operator '!' (logical negation) which must precede its operand without a space.

Named Expressions#

To organize expressions, the element <condition> may be used as a child elementof <tlLogic> to define named expressions that can be referenced in other expressions:

<tlLogic id="example" type="actuated" ...> <condition id="C3" value="z:det5 > 5"/> <condition id="C4" value="C3 and z:det6 &lt; 2"/> <condition id="C5" value="g:3 > 20"/> ...

• id must be an alphanumeric string without spaces and without the ':'-character
• value may be any expression which is permitted for 'earlyTarget' or 'finalTarget'

Condition values can be visualized while the simulation is running. By default all conditions are listed (if the corresponding visualization option is active). If many conditions are defined, it may be useful to list only a subset in the tracker window. For this purpose either one of the following <param>-definitions may be used as child element of the <tlLogic>:

• <param key="show-conditions" value="C1 C4"/>: shows only the conditions with listed id.
• <param key="hide-conditions" value="C3 C4"/>: shows only the conditions which are not listed

The values of (visible) named expressions can optionally be written to the TLS output.

Examples#

Diverse Logical Conditions#

<tlLogic id="example" type="actuated" ...> <condition id="C3" value="z:Det2.0 > 5"/> <condition id="C4" value="C3 and z:Det0.0 < 2"/> <condition id="C5" value="r:0 > 60"/> <phase ... next="1 2"/> <phase ... earlyTarget="C3" finalTarget="!C4"/> <phase ... earlyTarget="(z:D2.0 > 3) and (z:D3.1 <= 4)" finalTarget="C5 or (z:Det3.1 = 0)"/></tlLogic>

Default Gap Control Logic#

The default gap control logic, replicated with custom conditions. A complete scenario including network and detector definitions can be downloaded here:

<tlLogic id="C" type="actuated" programID="P1" offset="0"> <phase duration="33" state="GgrrGgrr" minDur="5" maxDur="60" /> <phase duration="3" state="ygrrygrr" earlyTarget="NS"/> <phase duration="6" state="rGrrrGrr" minDur="5" maxDur="60" /> <phase duration="3" state="ryrrryrr" earlyTarget="NSL"/> <phase duration="33" state="rrGgrrGg" minDur="5" maxDur="60" /> <phase duration="3" state="rrygrryg" earlyTarget="EW"/> <phase duration="6" state="rrrGrrrG" minDur="5" maxDur="60" /> <phase duration="3" state="rrryrrry" earlyTarget="EWL"/> <condition id="NS" value="z:D0.0 > 3 and z:D2.0 > 3"/> <condition id="NSL" value="z:D0.1 > 3 and z:D2.1 > 3"/> <condition id="EW" value="z:D1.0 > 3 and z:D3.0 > 3"/> <condition id="EWL" value="z:D1.1 > 3 and z:D3.1 > 3"/> </tlLogic>

Bus prioritization#

 <!-- detect only buses --> <inductionLoop id="dBus" lane="SC_0" pos="-90" vTypes="busType" file="NUL"/> <tlLogic id="C" type="actuated" programID="P1" offset="0"> <phase duration="33" state="GgrrGgrr" minDur="5" maxDur="60" /> <phase duration="3" state="ygrrygrr"/> <phase duration="6" state="rGrrrGrr" minDur="5" maxDur="60" /> <phase duration="3" state="ryrrryrr"/> <phase duration="33" state="rrGgrrGg" minDur="5" maxDur="60" /> <phase duration="3" state="rrygrryg" earlyTarget="EW or NSbus"/> <phase duration="6" state="rrrGrrrG" minDur="5" maxDur="60" /> <phase duration="3" state="rrryrrry"/> <!-- the default switching rules (prolong phase depending on observed gaps) --> <condition id="EW" value="z:D1.0 > 3 and z:D3.0 > 3"/> <!-- prioritization for buses coming from the south --> <condition id="NSbus" value="3 > z:dBus"/> </tlLogic>

Overriding Phase Attributes with Expressions#

By default, the phase attributes 'minDur', 'maxDur', 'earliestEnd' and 'latestEnd' are defined numerically (or left undefined).It may be desireable to redefine these attributes with expressions (i.e. condition ids or condition values) for the following reasons:

• the switching logic may be expressed more succinctly if these values can change dynamically during the signals operation
• the phase definitions shall be reused for multiple programs and all variability shall be expressed in table of constants (defined via <conditions>s)

To override these attributes, their value in the <phase> must be defined as -1. For each phase and attribute a corresponding condition must be defined with the id = <ATTRNAME>:<PHASEINDEX> as in the example below:

<tlLogic id="C" type="actuated" programID="P1" offset="0"> <phase duration="33" state="GgrrGgrr" minDur="10" maxDur="65" name="NS"/> <phase duration="3" state="ygrrygrr" earlyTarget="NS"/> <phase duration="6" state="rGrrrGrr" minDur="10" maxDur="65" name="NSL"/> <phase duration="3" state="ryrrryrr" earlyTarget="NSL"/> <phase duration="33" state="rrGgrrGg" minDur="-1" maxDur="-1" name="EW" earliestEnd="-1" latestEnd="-1"/> <phase duration="3" state="rrygrryg" earlyTarget="EW"/> <phase duration="6" state="rrrGrrrG" minDur="10" maxDur="65" name="EWL"/> <phase duration="3" state="rrryrrry" earlyTarget="EWL"/> <condition id="minDur:4" value="10"/> <condition id="maxDur:4" value="65"/> <condition id="earliestEnd:4" value="60"/> <condition id="latestEnd:4" value="80"/> </tlLogic>

Storing and modifying custom data#

The <condition> elements described above can be used to define complex expressions as well as numerical constants that control program operation.It may sometimes be useful to store and modify numerical values that persist over consecutive invocations of the control logic. To this end the element <assignment> may be used as a child element of <tlLogic> to define conditional assignment of new values to named expressions:

<tlLogic id="example" type="actuated" ...> <condition id="NS" value="0"/> <condition id="nSw" value="0"/> <assignment id="nSw" check="1" value="nSw + 1"/> <assignment id="NS" check="1" value="0"/> <assignment id="NS" check="z:D0.0 > 3 and z:D2.0 > 3" value="1"/> ...</tlLogic>

• id may be any alphanumeric id
• check may be any expression which is permitted for condition values
• value may be any expression which is permitted for conditions values

Every time the control logic is executed, all assignments are executed in the order they are defined: If the the 'check'-expression evaluates to true (a non-0 value), the 'value'-expression is evaluated and the result is stored under the given id:

• if id is the id of a condition element, the value of that conditions is replaced by a string representation of the result (The accuracy of this representation is limited by simulation option --precision)
• if id is not the id of a condition element, a double valued variable with that id is created / updated in the current scope. If the assignment is not part of a use-defined functions, this is the global scope

The test case find_primes computes all prime numbers below 100 inside the traffic light controller as a capability demonstration.

Custom function definitions#

Custom functions are a mechanism that allows to execute multiple assignments with custom arguments.They are defined with the <function> element within a <tlLogic> as shown below:

<tlLogic id="example" type="actuated" ...> <function id="FNAME" nArgs="2"> <assignment id="COND1" check="1" value="$1 + $2"/> <assignment id="$0" check="1" value="COND1 * COND1"/> </function> <condition id="COND2" value="FNAME:3,4"/> ...</tlLogic>

• id may be any alphanumeric string
• nArgs is the number of arguments required by the function
• $0 is the value returned by the function
• $1 ... $n are the values of the functions arguments in the order they are supplied after the :
• when a function is evaluated, all its assignments are evaluated in definition order
• functions may not assign to any defined <condition> id
• assignments are local to the function
• a function call takes the form id:arg_1,arg_2,...arg_n and there must be no spaces between the arguments and the commas (except within parentheses)
• a function is evaluated within the calling scope (ids assigned to by a function are accessible in a nested function call but assignments are not propagated back to the caller)

in the above example COND2 receives a value of 49

Type 'delay_based'#

Similar to the control by time gaps between vehicles, a phaseprolongation can also be triggered by the presence of vehicles with timeloss. A TLS with this actuation type can be defined as follows:

<tlLogic id="0" programID="my_program" offset="0" type="delay_based"> <param key="detectorRange" value="100" /> <param key="minTimeLoss" value="1" /> <param key="file" value="NULL"/> <param key="freq" value="300"/> <param key="show-detectors" value="false"/> <param key="extendMaxDur" value="false"/> <phase duration="31" minDur="5" maxDur="45" state="GGggrrrrGGggrrrr"/> ...</tlLogic>

Here, the detectorRange specifies the upstream detection range in meters measuredfrom the stop line. Per default (if the parameter is left undefined) theunderlying E2detector isassumed to cover the first approaching lanes completely. The time lossfor a vehicle is accumulated as soon as it enters the detector range. Ifits accumulated time loss exceeds the value of minTimeLoss (current default is onesecond) seconds a prolongation of the corresponding green phase isrequested if it is active. The instantaneous time loss of a vehicle isdefined as 1 - v/v_max, where v is its current velocity and v_maxthe allowed maximal velocity. See [Oertel, Robert, and Peter Wagner."Delay-time actuated traffic signal control for an isolatedintersection." Transportation Research Board 2011 (90th Annual Meeting).2011.] for details.

Parameters#

Several optional parameters can be used to control the behavior of delay_based traffic lights. The example values in the previous section are the default values for these parameters and their meaning is given below:

• detector-range: the upstream detection range in meters measured from the stop line
• minTimeLoss: the minimum timeLoss of a vehicle (in s) that triggers phase prolongation
• extendMaxDur: whether phases may be prolonged beyond maxDur in the absence of traffic in other arms (this was the default behavior until 1.16.0)
• show-detectors controls whether generated detectors will be visible or hidden in sumo-gui. It is also possible to toggle this value from within the GUI by right-clicking on a traffic light.
• parameters vTypes, file and freq have the same meaning as for regularlane area detectors.

Custom Detectors#

To use custom detectors (i.e. for custom placement or output) additional parameters can be defined where KEY is a lane that is incoming to the traffic light and VALUE is a user-defined laneAreaDetector.

 <param key="gneE42_2" value="customDetector1"/>

Type 'NEMA'#

Since version 1.11.0, SUMO supports defining controllers with the namingconvention and control logic according to the 'National Electrical ManufacturersAssociation' commonly used throughout the United States.Detailed documentation is at NEMA.

Custom Detectors#

To use custom detectors (i.e. for custom placement or output) additional parameters can be defined where KEY is a lane that is incoming to the traffic light and VALUE is a user-defined laneAreaDetector.

 <param key="gneE42_2" value="customDetector1"/>

Detector activation states (for default and custom detectors) can optionally be written to the TLS output.

After having defined a tls program as above, it can be loaded as an additional-file; ofcourse, a single additional-file may contain several programs. It is possible to loadseveral programs for a single tls into the simulation. The programloaded last will be used (unless not defined differently using a WAUTdescription). All subkeys of the additional programs must differ if theydescribe the same tls.

Assuming the program as defined above is put in a file calledtls.add.xml it can be loaded insumo/sumo-gui like this

sumo-atls.add.xml...<other options for network and routes>

Switching TLS 'off'#

It is also possible to load a program which switches the tls off bygiving the programID the value"off".

<tlLogic id="0" type="static" programID="off"/>

!!! note: The 'off' program can always be used from TraCI.

An alternative way to switch all traffic lights to the 'off' program is to set sumo option --tls.all-off.

Default behavior when 'off'#

Once a traffic light has been switched off, its lights will change to to values of O (off, no signal) and o (off, blinking) and it will behave like a priority intersection. The connections (links) with state O will have priority whereas the connections o will yield.

The rules for configuring the priority direction in the off-state are the same as for an intersection without a traffic light.

All-way-stop when 'off'#

By setting junction (node) attribute rightOfWay="allwayStop", when building / editing the network file, the behavior when switched off will correspond to that of junction type allway_stop.

Description from real-world traffic light systems do not arrive in formof SUMO-traffic light descriptions normally. The main difference inpresentation comes from the fact that SUMO defines a new <phase> whenever anyof the controlled signals changes its state, whereas traffic engineersdifferentiate between phases and phase transitions.

For an easier import than editing the XML by hand, some tools exists in<SUMO_HOME>/tools/tls.

• tls_csv2SUMO.py: this tool simplifies descriptions because it allows to define the duration of phases for each controlled edge-to-edge connection. Splitting into smaller SUMO-phases because other signals change is done automatically.
• tls_csvSignalGroup.py: this tool further simplifies descriptions because it allows to define the start and end times of green-phases per signal group (up to 2 green phases, actually) and the transitions (yellow, red-yellow) are added automatically. The splitting into smaller SUMO-phases is also done automatically.

Alternatively netedit can be used to edit programsusing a graphical user interface.

To modify the program of a traffic light it is generally necessary toload a new program. However, inthe special case that only the offset shall be modified it is alsopossible to specify a new offset for an existing traffic light id andprogramID:

<additional> <tlLogic id="0" programID="0" offset="42"/></additional>

In SUMO, a traffic light controller can control an arbitrary number ofjunctions simultaneously. This is accomplished by one of the followingmethods:

• Defining the same tl attribute (the controller ID) for a set of nodes in .nod.xml file when building the network with netconvert
• Setting the same tl attribute for multiple nodes in netedit
• Setting the option --tls.join when building the network with netconvert. This will automatically join the traffic lights of nodes in close proximity within a default distance of 20m (customizable by setting option tls.join-dist <FLOAT>).

Note, that in this case the state vector for each phase will be as longas the total number of controlled intersections. Also, the tls indicesfor the connections will differ from the link indices (as the latterstarts with 0 for each intersection whereas the tls indices are uniquewithin a controller).

In SUMO every lane-to-lane connection at a controlled intersection isassigned an index called link tls index. This index is used todetermine the state for each phase by looking up the character code atthat index in the state vector. The link index can be shown insumo-gui by setting the junction visualizationoption show link tls index. By default link indices are unique foreach connection and assigned in a clockwise manner starting at the north(the same as the junction link index which is used for definingright-of-way rules). When defining jointTLS,the indices continue their numbering in the order of the controlledjunctions.

The tls index for each connection can be freely assigned in a.tll.fileor by setting attribute linkIndex in netedit. Byassigning the same index to multiple connection they form a signalgroup and always show the same state (simply because they reference thesame state index). This allows shortening and thus simplifying the statevector.

Automatic Creation of Signal Groups#

netconvert supports automatic definition of signal groups by setting option --tls.group-signals.To replace existing signal groups with a 1-to-1 assignment of connections to indices, the option --tls.ungroup-signals can be used.

netedit also supports creation and removal of signal groups using the functions 'Group Signals' and 'Ungroup Signals' in traffic light mode frame.

In practice, a tls often uses different programs during a day and maybealso for weekdays and for the weekend days. It is possible to load adefinition of switch times between the programs using a WAUT (short for"Wochenschaltautomatik" ~ weekly switch automatism).

Given a tls which knows four programs - two for weekdays and two forweekend days where from 22:00 till 6:00 the night plan shall be used andfrom 6:00 till 22:00 the day plan, and already defined programs, named"weekday_night", "weekday_day", "weekend_night", "weekend_day". Todescribe the switch process, we have to describe the switch at first,assuming our simulation runs from monday 0.00 (second 0) to monday 0.00(second 604800):

<WAUT refTime="0" id="myWAUT" startProg="weekday_night"> <wautSwitch time="21600" to="weekday_day"/> <!-- monday, 6.00 --> <wautSwitch time="79200" to="weekday_night"/> <!-- monday, 22.00 --> <wautSwitch time="108000" to="weekday_day"/> <!-- tuesday, 6.00 -->... further weekdays ... <wautSwitch time="453600" to="weekend_day"/> <!-- saturday, 6.00 -->... the weekend days ...</WAUT>

The fields in WAUT have the following meanings:

and the fields in wautSwitch:

Of course, programs with the used names must be defined before thisdefinition is read. Also, the switch steps must be sorted by theirexecution time.

Additionally, a definition about which tls shall be switched by the WAUTmust be given, as following:

<wautJunction wautID="myWAUT" junctionID="RCAS" [procedure="Stretch"] [synchron="t"]/>

Here, the attributes have the following meaning:

It is possible to assign several tls to a single WAUT. It is alsopossible to assign several WAUTs to a single junction in theory, butthis is not done in reality.

A complete definition within an additional-file is shown below. It would triggerswitching between programs S1 and S2 for traffic light logicX with an initial program called 0.

<additional> <tlLogic id="X" type="static" programID="S1" offset="0"> <phase duration="50" state="Gr"/> <phase duration="50" state="rG"/> </tlLogic> <tlLogic id="X" type="static" programID="S2" offset="0"> <phase duration="30" state="Gr"/> <phase duration="80" state="rG"/> </tlLogic> <WAUT startProg="0" refTime="100" id="w1"> <wautSwitch to="S1" time="300"></wautSwitch> <wautSwitch to="SS" time="800"></wautSwitch> </WAUT> <wautJunction junctionID="X" wautID="w1"></wautJunction><additional>

Some tools are available which help generating detector definitions forthe evaluation of traffic lights. All are located in <SUMO_HOME>/tools/output.

• generateTLSE2Detectors.py generates a file which includes areal detectors. All lanes incoming into an intersection are covered with these detectors. The offset from the intersection may be given using the option --distance-to-TLS <FLOAT> (or -d <FLOAT>), the default is .1m. The generated detectors end either after a given length, defined using --detector-length <FLOAT> (or -l <FLOAT>) where the default is 250m, or at the lane's end if the lane is shorter than this length.
• generateTLSE3Detectors.py generates a file which includes multi-entry/multi-exit detectors. Detectors are built for each edge incoming to the traffic light. All lanes of each of these edges are covered with exit points. These point's offset from the intersection may be given using the option --distance-to-TLS <FLOAT> (or -d <FLOAT>), the default is .1m. The incoming edges are followed upstream, either until a given length, defined using --detector-length <FLOAT> (or -l <FLOAT>) where the default is 250m, or another traffic light is reached or no further upstream edge exists. Entry points are generated at these points.

In both cases, the network must be given using the option --net-file <FILE> (or -n <FILE>). Thefile including the detector definitions to generate may be given usingthe option --output <FILE> (or -o <FILE>), default is "e2.add.xml" for areal detectors, and"e3.add.xml" for multi-entry/multi-exit detectors. Per default, theareal detectors generated by generateTLSE2Detectors.py are writingtheir measures to "e2output.xml", the multi-entry/multi-exit detectorsgenerated by generateTLSE2Detectors.py to "e3output.xml". Theoutput file name can be changed for both scripts using the option --results-file <FILE> (or -r <FILE>). The frequency of generated reports is 60s per default. It can bechanged using the option --frequency <INT> (or -f <INT>).

TraCI provides various functions for controlling trafficlights. And the basicapproaches are outline below

Setting the phase#

A common pattern for implementing adaptive control via TraCI is to loada program (usually from anadditional-file) where allgreen phases have a long duration (i.e. 1000s) to avoid switching bySUMO and then use the setPhase function to switch to the next phase(typically a yellow phase) whenever the green phase should end. Thenice thing about this approach is, that yellow phase and all-red phasescan still be handled automatically by SUMO and the control script simplydetermines the duration of the current green phase.

To implement controllers with branching phase transitions, providemultiple transitions to subsequent green phases and when callingsetPhase, select the yellow phase that starts the transition to thetarget green phase.

These additional transition phases can be added to the end of theprogram and the optional phase attribute "next" can be used to indicated thenext phase after the transition ends.

Tutorials for controlling traffic lights in this way can be found atTutorials#TraCI_Tutorials.

Setting the duration#

Using the function setPhaseDuration, the remaining duration for thecurrent phase can be modified. Note, that this does not take effect whenencountering the same phase again in the next phase cycle.

Setting the state#

Another method for controlling the traffic light is to set the signalstate for all links directly using the functionsetRedYellowGreenState. After using this function, SUMO will notmodify the state anymore (until switching to another program usingsetProgram). Consequently, the script must handle all phases andtransitions.

Setting the complete Program#

Using the method setProgramLogic, a staticsignal plan can be loaded. Since this method requires a complex datastructure as argument, it is recommend to first obtain a data structureusing getAllProgramLogics and then modify it.

Switching between pre-defined Programs#

SUMO can load multiple traffic light programs from the .net.mxl fileand from additional files. Usingthe TraCI function setProgram, a script can switch between them.

In sumo-gui, right-clicking on a traffic light allows opening up a menu that contains the items 'Show Phases' and 'Track Phases'.These items open up new windows which are explained below

Show Phases#

This shows the signal states of all controlled links for the complete list of defined phases. Here, time is on the x-axis and there is one row for each link index. The time axis in the bottom shows the time of each phase change starting at 0.

The time can be switched between the following styles- Seconds: absolute simulation time in seconds- MM::SS: current minute and second (values repeat every hour)- Time in Cycle: current second within the traffic light cycle (resets either when starting phase 0 or in some alignment to absolute simulation time).

Optionally, the green phase durations can be written for every phase.The top row contains the phase index but it is possible to change this so it shows phase names instead. (phase names are optional, and only the names of 'Green' phases are shown for brevity)

Track Phases#

This shows the evolution of signal states for all controlled links for the last X seconds of operation (set via the 'Range' value). The basic layout is the same as for the 'Show Phases' Window.

The following additional features may be activated via checkboxes:

• detector: shows activation states of all detectors that are controlling this traffic light
• conditions: shows the boolean value of conditions that are defined for this traffic light. A colored block wil be drawn when the numerical value of the condition is different from zero.