Simulation/Traffic Lights

From Sumo
Jump to: navigation, search

Normally, NETCONVERT and NETGENERATE generate traffic lights and programs 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 possible to run SUMO/SUMO-GUI with additional program definitions. Also, SUMO/SUMO-GUI allow loading definitions which describe when and how a set of traffic lights can switch from one program to another. Both will be discussed in the following subchapters. Another possiblity is to edit traffic light plans visually in NETEDIT.

Defining New TLS-Programs

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

   <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"/>

To get started you can copy the tlLogic elements for all traffic lights you wish to edit from a .net.xml file and put them into a new file. Then you only need to change the programID attribute and the program is ready to be modified and loaded

<tlLogic> Attributes

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

Attribute Name Value Type Description
id id (string) The id of the traffic light. This must be an existing traffic light id in the .net.xml file. Typically the id for a traffic light is identical with the junction id. The name may be obtained by right-clicking the red/green bars in front of a controlled intersection.
type enum (static, actuated, delay_based) The type of the traffic light (fixed phase durations, phase prolongation based on time gaps between vehicles (actuated), or on accumulated time loss of queued vehicles (delay_based) )
programID id (string) The id of the traffic light program; This must be a new program name for the traffic light id. Please note that "off" is reserved, see below.
offset int The initial time offset of the program

<phase> Attributes

Each phase is defined using the following attributes:

Attribute Name Value Type Description
duration time (int) The duration of the phase
state list of signal states The traffic light states for this phase, see below
minDur time (int) The minimum duration of the phase when using type actuated. Optional, defaults to duration.
maxDur time (int) The maximum duration of the phase when using type actuated. Optional, defaults to duration.

Signal state definitions

Each character within a phase's state describes the state of one signal of the traffic light. Please note, that a single lane may contain several signals - for example one for vehicles turning left and one for vehicles which move straight. This means that a signal does not control lanes, but links - each connecting a lane which is incoming into a junction and one which is outgoing from this junction. In SUMO, a one-to-n dependency between signals and links is implemented, this means each signal may control more than a single link - though networks generated by NETCONVERT or NETGENERATE usually use one signal per link. Please note also, that a traffic light may control lanes incoming into different junctions. The information about which link is controlled by which traffic light signal may be obtained using the "show link tls index" option within SUMO-GUI's visualisation settings or from the according linkIndex attribute of the <connection> elements in the .net.xml file.

The following signal colors are used:

Character Description
r 'red light' for a signal - vehicles must stop
y 'amber (yellow) light' for a signal - vehicles will start to decelerate if far away from the junction, otherwise they pass
g 'green light' for a signal, no priority - vehicles may pass the junction if no vehicle uses a higher priorised foe stream, otherwise they decelerate for letting it pass
G 'green light' for a signal, priority - vehicles may pass the junction
u 'red+yellow light' for a signal, may be used to indicate upcoming green phase but vehicles may not drive yet (shown as orange in the gui)
o 'off - blinking' signal is switched off, blinking light indicates vehicles have to yield
O 'off - no signal' signal is switched off, vehicles have the right of way

Traci tutorial tls.png
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. The link numbers are enabled via SUMO-GUI settings by activating show link tls index.

Actuated Traffic Lights

Based on Time Gaps

SUMO supports gap-based actuated traffic control This control scheme is common in Germany and works by prolonging traffic phases whenever a continuous stream of traffic is detected. It switches to the next phase after detecting a sufficent time gap between sucessive vehicles. This allows for better distribution of green-time among phases and also affects cycle duration in response to dynamic traffic conditions.

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

<tlLogic id="0" programID="my_program" offset="0" type="actuated">
   <param key="max-gap" value="3.1"/>
   <param key="detector-gap" value="3.0"/>
   <param key="show-detectors" value="false"/>
   <param key="file" value="NULL"/>
   <param key="freq" value="300"/>
   <param key="splitByType" value="false"/>

   <phase duration="31" minDur="5" maxDur="45" state="GGggrrrrGGggrrrr"/>

The value of max-gap describes the maximum time gap between successive vehicle that will cause the current phase to be prolonged (within limits). detector-gap determines the time distance between the (automatially generated) detector and the stop line in seconds (at each lanes maximum speed). If show-detectors is set to true, the generated detectors are shown in SUMO-GUI. The parameters file, freq and splitByType have the same meaning as for regular induction loop detectors. The examples values are the default values for these parameters.

Based on Time Loss

Similar to the control by time gaps between vehicles, a phase prolongation can also be triggered by the presence of vehicles with time loss. 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"/>
   <phase duration="31" minDur="5" maxDur="45" state="GGggrrrrGGggrrrr"/>

Here, the detectorRange specifies the upstream detection range in meters measured from the stop line. Per default (if the parameter is left undefined) the underlying E2 detector is assumed to cover the first approaching lanes completely. The time loss for a vehicle is accumulated as soon as it enters the detector range. If its accumulated time loss exceeds the value of minTimeLoss (current default is one second) seconds a prolongation of the corresponding green phase is requested if it is active. The instantaneous time loss of a vehicle is defined as 1 - v/v_max, where v is its current velocity and v_max the allowed maximal velocity. See [Oertel, Robert, and Peter Wagner. "Delay-time actuated traffic signal control for an isolated intersection." Transportation Research Board 2011 (90th Annual Meeting). 2011.] for details.

Loading a new Program

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

Assuming the program as defined above is put in a file called tls.add.xml it can be loaded in SUMO/SUMO-GUI like this

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

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

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

Tools for Importing TLS Programs

Description from real-world traffic light systems do not arrive us in form of SUMO-traffic light descriptions normally. For an easier import than editing them by hand, a tool named "" exists which parses a csv-file which describes the program and builds a matching SUMO-traffic light description. The tool can be found in <SUMO_HOME>/tools/tls. This tool requires the program definition and the SUMO-network it shall be converted to: <TLS_CSV> <NET>

It prints the generated TLS definition on stdout (you can pipe it to a file).

The format of the CSV description is as following. At first, three header lines must be given, which name the tls (which is the id of the tlLogic in the network), the program's subkey, and the offset at which the program shall start in seconds - normally 0:


Then, it is defined which signal (number) in the program is responsible for which link. The link may be described either using the incoming edge only, or the incoming lane only, or also incorporating the outgoing edge/lane. This means the following lines are all valid:


It is also possible to assign more than one link to a single signal.

Then, the signals' states are given:


The states are encoded using the signal colors (please note that only lower-case letters are used, see below) described above, separated by ';'. An example signal phase definition (for signal 1) could be:


Please not that the number of states must be the same for all defined links.

Now, we only have to define the phase times:


The times are given in seconds, again separated using ';'. An example could be:


A complete CSV-description could look like:



The example shows what is tested in [1]. It is not a real-world program plan, only a demonstration for using the script.

We have a simple four-arms intersections which is controlled by traffic lights, see next figure.

Figure: example intersection

Tls2csv example net.svg

Now, we define two different programs for this intersection. The first:


This means that we have four streams: two for north/south (edges 3si and 4si) and two for east/west (edges 1si and 2si). Two, because we give green longer for the respective left-movers. The key is the ID of the traffic light ("0"), the subkey is the name of our program ("own1").

The second program looks like this:


We convert those program definitions using

tools/tls/ lsa_def.csv,lsa_def2.csv 

And obtain the following programs after loading them into SUMO-GUI:

Figure: converted programs

Program own1.png Program own2.png


This is definitely not the most comfortable way to define traffic lights. Some tools, as NETEDIT f.e., allow to edit them using a graphical user interface. Also, one could think of defining traffic lights by giving the begin and end times of green only. This is a quite usual approach within other traffic simulation packages. Any ideas on improving and/or patches to the script are welcome.

Modifying Existing TLS-Programs

To modify the program of a traffic light it is generally necessary to load a new program. However, in the special case that only the offset shall be modified it is also possible to specify a new offset for an existing traffic light id and programID:

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

Defining Program Switch Times and Procedure

In practice, a tls often uses different programs during a day and maybe also for weekdays and for the weekend days. It is possible to load a definition 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 for weekend days where from 22:00 till 6:00 the night plan shall be used and from 6:00 till 22:00 the day plan, and already defined programs, named "weekday_night", "weekday_day", "weekend_night", "weekend_day". To describe 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 ...

The fields in WAUT have the following meanings:

Attribute Name Value Type Description
id string id The name of the defined WAUT
refTime int A reference time which is used as offset to the switch times given later (in simulation seconds)
startProg string id The program that will be used at the simulation's begin

and the fields in wautSwitch:

Attribute Name Value Type Description
time int The time the switch will take place
to string id The name of the program the assigned tls shall switch to

Of course, programs with the used names must be defined before this definition is read. Also, the switch steps must be sorted by their execution time.

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

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

Here, the attributes have the following meaning:

Attribute Name Value Type Description
wautID string id The id of the WAUT the tls shall be switched by
junctionID string id The name of the tls to assign to the WAUT
procedure string enum The switching algorithm to use; If none is given, the programs will switch immediately (default)
synchron string enum Additional information whether the switch shall be done synchron (default: false)

It is possible to assign several tls to a single WAUT. It is also possible to assign several WAUTs to a single junction in theory, but this is not done in reality.

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


  <tlLogic id="X" type="static" programID="S1" offset="0">
    <phase duration="50" state="Gr"/>
    <phase duration="50" state="rG"/>
  <tlLogic id="X" type="static" programID="S2" offset="0">
    <phase duration="30" state="Gr"/>
    <phase duration="80" state="rG"/>

  <WAUT startProg="0" refTime="100" id="w1">
    <wautSwitch to="S1" time="300"></wautSwitch>
    <wautSwitch to="SS" time="800"></wautSwitch>

  <wautJunction junctionID="X" wautID="w1"></wautJunction>


Evaluation of Traffic Lights Performance

Tools For Automatic Detector Generation

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

The actuated traffic lights do not require detector definitions to be added as they generate their own detectors for internal use.
  • 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.
  • 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>). The file including the detector definitions to generate may be given using the 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, the areal detectors generated by are writing their measures to "e2output.xml", the multi-entry/multi-exit detectors generated by to "e3output.xml". The output 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 be changed using the option --frequency <INT> (or -f <INT>).