SUMO
Simulation of Urban MObility

- Home
- Download
- Documentation
- Wiki
- Trac
- Blog
- Contact
- SF-Project

# Simulation/Traffic Lights

Normally, NETCONVERT and NETGENERATE generate traffic lights and programs for junctions during the computation of the networks. Still, these computed programs differ quite often from those found in reality. To feed the simulation with real traffic light programs, it is possible to load additional programs. Also, SUMO/SUMO-GUI allow to load definition 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.

# Loading new TLS-Programs

You can load new definitions for traffic lights as a part of additional files. 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 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"/>
    </tlLogic>

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

Attribute Name | Value Type | Description
--- | --- | ---
id | id (string) | The id of the traffic light
type | enum (static, actuated) | The type of the traffic light (fixed phase durations, phase prolongation based time gaps between vehicles)
programID | id (string) | The id of the traffic light program; Please note that "off" is reserved, see below.
offset | int | The initial time offset of the program

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 (optional), defaults to duration
maxDur | time (int) | The maximum duration of the phase (optional), defaults to duration

Each character within a phases' 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, 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@connection attribute of the network.

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

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 as 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.

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

### Additional Parameters

Actuated traffic lights support some additional parameters. These may be given within the <tlLogic>-Element as follows:

    <tlLogic id="0" programID="my_program" offset="0" type="actuated">
       <param key="max-gap" value="3.1"/>
       <param key="passing-time" value="1.9"/>
       <param key="detector-gap" value="3.0"/>
       <phase duration="31" state="GGggrrrrGGggrrrr"/>
       ...
    </tlLogic>

The value of max-gap describes the maximum time gap between successive vehicle that will cause the current phase to be prolonged (within limits). The value of passing-time describes the minimum phase duration that will be added for each vehicle in the waiting queue (again within limits). detector-gap is the time distance between the detector and the stop line in seconds (at the lanes maximum speed). The examples values are the default values for these parameters.

## Tools for TLS programs import

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 "tls_csv2SUMO.py" exists which parses a csv-file which describes the program and builds an according 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_csv2SUMO.py <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, the program's subkey, and the offset at which the program shall start in seconds - normally 0:

    key;<KEY>
    subkey;<SUBKEY>
    offset;<OFFSET>

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:

    link;<LINK_NUMBER>;<FROM_EDGE>;;0
    link;<LINK_NUMBER>;<FROM_LANE>;;0
    link;<LINK_NUMBER>;<FROM_EDGE>;<TO_EDGE>;0
    link;<LINK_NUMBER>;<FROM_EDGE>;<TO_LANE>;0
    link;<LINK_NUMBER>;<FROM_LANE>;<TO_EDGE>;0
    link;<LINK_NUMBER>;<FROM_LANE>;<TO_LANE>;0

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

Then, the signals' states are given:

    <LINK_NUMBER>;<STATES>

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:

    1;g;g;g;g;y;r;r;r;r;r

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

Now, we only have to define the phase times:

    time;<TIMES>

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

    time;18;33;3;6;3;3;9;15;90

A complete CSV-description could look like:

    key;102
    subkey;utopia
    offset;0
    link;1;4643;;0
    link;1;3078;;0
    link;2;3074;;0
    link;2;-6494;;0
    1;g;g;y;r;r;r;r;r
    2;r;r;r;r;g;g;y;r
    3;r;r;r;r;g;y;y;r
    4;g;y;y;r;r;r;r;r
    min;21;3;3;2;20;9;3;2
    time;45;3;3;2;36;9;3;2
    max;78;3;3;2;62;9;3;2

### Example

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

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

    key;0
    subkey;own1
    offset;0
    link;1;4si;3o;0
    link;1;4si;1o;0
    link;1;3si;4o;0
    link;1;3si;2o;0
    link;2;4si;4o;0
    link;2;4si;2o;0
    link;2;3si;1o;0
    link;2;3si;3o;0
    link;3;1si;1o;0
    link;3;1si;4o;0
    link;3;2si;2o;0
    link;3;2si;3o;0
    link;4;1si;3o;0
    link;4;1si;2o;0
    link;4;2si;1o;0
    link;4;2si;4o;0
    1;g;y;r;r;r;r;r;r;r;r
    2;g;g;g;y;r;r;r;r;r;r
    3;r;r;r;r;r;g;y;r;r;r
    4;r;r;r;r;r;g;g;g;y;r
    min;10;3;5;3;3;10;3;5;3;3
    time;15;3;5;3;3;45;3;5;3;3
    max;30;3;15;3;3;60;3;15;3;3

This means, 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:

    key;0
    subkey;own2
    offset;0
    link;1;4si;3o;0
    link;1;4si;1o;0
    link;1;3si;4o;0
    link;1;3si;2o;0
    link;2;4si;4o;0
    link;2;4si;2o;0
    link;2;3si;1o;0
    link;2;3si;3o;0
    link;3;1si;2o;0
    link;3;1si;3o;0
    link;3;2si;1o;0
    link;3;2si;4o;0
    link;4;1si;4o;0
    link;4;1si;1o;0
    link;4;2si;3o;0
    link;4;2si;2o;0
    1;g;y;r;r;r;r;r;r
    2;g;g;g;y;r;r;r;r
    3;r;r;r;r;g;y;r;r
    4;r;r;r;r;g;g;g;y
    time;31;16;6;16;31;16;6;16

We convert those program definitions using

    tools/tls/tls_csv2SUMO.py lsa_def.csv,lsa_def2.csv input_net.net.xml

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

Figure: converted programs

### Comments

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.

# Defining Program switch Times and Procedure

In the reality, 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 ...
    </WAUT>

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.

# 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.

- 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>). 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 generateTLSE2Detectors.py are writing their measures to "e2output.xml", the multi-entry/multi-exit detectors generated by generateTLSE2Detectors.py 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>).

This page was last modified on 30 January 2013, at 18:37.