Chapter 6. Performing the Simulation

Chapter 6. Performing the Simulation
Prev		Next

Chapter 6. Performing the Simulation

Having the network description and the routes you have everything to perform a simulation. The fastest way to get results - their different types will be described within the following sub-chapters - is to use the SUMO - command line simulation. This command line tool does not generate any graphical output as the SUMO-GUI does, but is much faster in execution.

To start a simulation, you have to supply the following information:

The file that contains the network
Use the --net-file (or --net or -n) <FILE> option to pass the simulation the name of the network to use. The network must be one build using NETCONVERT or NETGEN.
The routes to use
Use the --route-files (or --routes or -r) <FILE>[,<FILE>]* option to specify which files shall be used to read routes from. In this case, the name is not ambigous - multiple files can be used.
The simulation time the simulation begins at
This is the first time step the simulation has to perform. Be aware, that this time should fit to the time your routes start. Pass it to SUMO using --begin (or -b) <INT> where <INT> is the time step in seconds.
The simulation time the simulation ends at
This is the last step of the simulation. When this time step is reached, the simulation will end. Pass it to SUMO using --end (or -e) <INT> where <INT> is the time step in seconds.

All these values must be given in order to perform a simulation. Still, no output is generated. Generating output is described in the next chapter. Besides this, there are also some other additional structures which may be applied to the simulation scenario and of course there are some more questions to answer about inserting vehicles into the net.

6.1. Output Generation

Due to its scientific purpose, SUMO tasks lie beyond simple visualisation of traffic. The results of a simulation must be available and one must be able to process them. In the next subchapters, possibilities to generate output are described.

6.1.1. Detectors

One possibility to generate output is to use so called "detectors". You will find detectors one knows from the real world such as induction loops but also some virtual ones. Basically, the main distinction between detector types SUMO offers is their dimension. The next list shows all available detector types. Their type names "E*" have their origin in the German word "Erfassungsbereich" meaning "detection area".

E1: Induction loops
Induction loops have a position only and no areal dimensions. They are meant to be a slice plane through a single lane and measure only the vehicles passing them.
E2: Areal, lane-based detectors
These detectors describe a part of a lane or alternatively a part of the network made up of consecutive lanes (a begin lane and his predecessors). The measured values are derived from the movements over the whole part of the network the detector is lying at.
E3: Multi-Origin/Multi-Destination detectors
E3-detectors measure vehicles passing a set of entry and an according set of exit points. Each of these points is a position on a lane. Measured are values that may be derived from the movements of vehicles between any of the entry and any of the exit points.

In addition to this, SUMO offers further detectors, which are not bound to certain places within the network.

VTypeProbe: Dumps vehicle states for a given vehicle type
VTypeProbes write information about all vehicles of a certain, defined type every n seconds. The vehicles' speed and position is written, where position is encoded as the current lane and position on this lane, cartesian x- and y-coordinate, and, if the network contains a projection, as lat-/lon-coordinates.

To supply the definitions of these structures to the simulation, we use an additional file and pass it to SUMO or GUISIM using the --additional-files (-a) - option. Each of these files may contain all the definitions about additional structures such as detectors, emitters, etc., in random order.

	Caution
	Please note that all output have not yet been verified for sub second simulation.

6.1.1.1. E1-Detectors (Induction Loops)

An induction loop is defined this way within an additional file:

<e1-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   freq="<AGGREGATION_TIME>" file="<OUTPUT_FILE>" [friendly_pos="x"]/>

The "id" is any string by which you can name the detector. The attributes "lane" and "pos" describe on which lane and at which position on this lane the detector shall lay. The "freq"-attribute describes the period over which collected values shalle be aggregated. The "file" attribute tells the simulation to which file the detector shall write his results into. The file will be generated, does not have to exist earlier and will be overwritten if existing without any warning. The folder the output file shall be generated in must exist.

The attributes:

id: A string holding the id of the detector
lane: The id of the lane the detector shall be laid on. The lane must be a part of the network used.
pos: The position on the lane the detector shall be laid on in meters. The position must be a value between -1*lane's length and the lane's length. In the case of a negative value, the position will be computed backward from the lane's end (the position the vehicles drive towards).
freq: The aggregation period the values the detector collects shall be summed up.
file: The path to the output file. The path may be relative.
friendly_pos: If set, no error will be reported if the detector is placed behind the lane. Instead, the detector will be placed 0.1 meters from the lane's end or at position 0.1, if the position was negative and larger than the lane's length after multiplication with -1.

A single data line within the output of a simulated e1-detector looks as following (the line is not broken within the output):

<interval begin="<BEGIN_TIME>" end="<END_TIME>" id="<DETECTOR_ID>" \
   nVehContrib="<MEASURED_VEHICLES>" flow="<FLOW>" \
   occupancy="<OCCUPANCY>" speed="<MEAN_SPEED>" length="<MEAN_LENGTH>" \
   nVehEntered="<ENTERED_VEHICLES>"/>

The values are described in the following table.

Table 6.1. Definition of values generated by e1-detectors

Name	Measure	Description
`begin`	`(simulation) seconds`	The first time step the values were collected in
`end`	`(simulation) seconds`	The last time step the values were collected in (may be equal to begin)
`id`	`-`	The id of the detector (needed if several detectors share an output file)
`nVehContrib`	`#vehicles`	The number of vehicles that have completely passed the detector within the interval
`flow`	`vehicles/hour`	The number of contributing vehicles extrpolated to an hour
`occupancy`	`%`	The percentage (0-100%) of the time a vehicle was at the detector.
`speed`	`m/s`	The mean velocity of all completely collected vehicles.
`length`	`m`	The mean length of all completely collected vehicles.
`nVehEntered`	`#vehicles`	All vehicles that have touched the detector. Includes vehicles which have not passed the vehicle completely (and which do not contribute to collected values).

Recent changes:

The attribute "friendly_pos" is available since version 0.9.4.
As detectors have been reworked for version 0.9.8, some used measures may have changed. Please consult the table above.
Since version 0.9.8, the attribute "style" is marked as deprecated, a warning is generated
Using element name "detector" together with a type is marked as deprecated since version 0.9.8, a warning is generated
The usage of attribute "friendly_pos" was reworked for version 0.9.8

6.1.1.2. E2-Detectors (Areal, lane-based Detectors)

An e2-detector is defined the following way within an additional file:

<e2-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   length="<DETECTOR_LENGTH>" freq="<AGGREGATION_TIME>" 
   file="<OUTPUT_FILE>" [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [friendly_pos="x"]/>

Most of the attributes have the same meaning as for induction loops. As an areal detector has a certain length, "length" must be supplied as a further parameter. It may be a negative number which lets the detector be extended upstream to the given beginning position. The optional parameter "cont" let's the detector continue over the current lane onto this lane's predecessors when the detector's length plus his position is larger than the place available on the lane.

	Caution
	For detectors that span over more than a single edge, only the attribute QUEUE_LENGTH_AHEAD_OF_TRAFFIC_LIGHTS_IN_VEHICLES is defined all other may return strange values.

Again, the explicit list of available attributes:

id: A string holding the id of the detector
lane: The id of the lane the detector shall be laid on. The lane must be a part of the network used.
pos: The position on the lane the detector shall be laid on in meters. See information about the same attribute within the detector loop description for further information.
length: The length of the detector in meters. If the detector grows over the lane's end (begin in fact), it is either cut off at the lane's length if the "cont"-attribute is false or not given or is continued on the predeceding lanes in the case the "cont"-attribute is set to true.
freq: The aggregation period the values the detector collects shall be summed up.
file: The path to the output file. The path may be relative.

And the optional ones:

cont: Holds the information whether detectors longer than a lane shall be cut off or continued (set it to true for the second case) default: false (detector lies on one lane only).
time_treshold: The time-based threshold that describes how much time has to pass until a vehicle is recognized as halting (in s, default: 1s).
speed_treshold: The speed-based threshold that describes how slow a vehicle has to be to be recognized as halting (in m/s, default: 5/3.6m/s).
jam_treshold: The minimum distance to the next standing vehicle in order to make this vehicle count as a participant to the jam (in m, default: 10m).
friendly_pos: If set, no error will be reported if the detector is placed behind the lane. Instead, the detector will be placed 0.1 meters from the lane's end or at position 0.1, if the position was negative and larger than the lane's length after multiplication with -1.

A single data line within the output of a simulated e2-detector looks as following (the line is not broken within the output):

<interval begin="<BEGIN_TIME>" end="<END_TIME>" id="<DETECTOR_ID>"  \
   nSamples="<DATA_SAMPLES>" meanSpeed="<MEAN_SPEED>"  \
   meanOccupancy="<MEAN_OCCUPANCY>" maxOccupancy="<MAX_OCCUPANCY>" \
   meanMaxJamLengthInVehicles="<VAL>" meanMaxJamLengthInMeters="<VAL>"  \
   maxJamLengthInVehicles="<VAL>" maxJamLengthInMeters="<VAL>"  \
   jamLengthInVehiclesSum="<VAL>" jamLengthInMetersSum="<VAL>" \
   meanHaltingDuration="<VAL>" maxHaltingDuration="<VAL>" haltingDurationSum="<VAL>" \
   meanIntervalHaltingDuration="<VAL>" maxIntervalHaltingDuration="<VAL>"
   intervalHaltingDurationSum="<VAL>" startedHalts="<VAL>" \
   meanVehicleNumber="<VAL>" maxVehicleNumber="<VAL>" />

To explain this vast amount of measures, a short note about how an e2-detector works is needfull. An e2-detector takes note about each vehicle that enters the area. As long as the vehicle does not leave the area completely, its state is collected in each time step during the interval. Each vehicle state in this case is called a "data sample" and the output of an e2-detector is made up from all data samples of all vehicles within the are during the complete data collection ("freq") interval.

As an e2-detector covers a lane and vehicles are sorted on these, it is possible to recognize jams along the detector's area and measure them. Because more than one jam may take place at the area at one time, the values cover as well averaged measures of all jams ("jamLengthIn...Sum") as explicite measures of the longest (maximum) jam. For the longest jam, both averaged ("meanMaxJamLengthIn...") and maximum ("maxJamLengthIn...") values are written.

	Note
	The jam length in meters may be more than a sum of the vehicles lengths, because the place between vehicle is also taken into account.

Besides jam computation, the durations vehicles are halting are collected. They are both collected over the whole time span a vehicle is on the detector area ("...HaltingDuration" and "haltingDurationSum"), and explicite for each interval ("...IntervalHaltingDuration" and "intervalHaltingDurationSum").

The values are described in the following table.

Table 6.2. Definition of values generated by e2-detectors

Name	Measure	Description
`begin`	`(simulation) seconds`	The first time step the values were collected in
`end`	`(simulation) seconds`	The last time step the values were collected in (may be equal to begin)
`id`	`-`	The id of the detector (needed if several detectors share an output file)
`nSamples`	`#`	The number of data samples that could be collected. A "data sample" means the state of a vehicle that was on the detector area during one of the simulation steps of the interval described by this data line.
`meanSpeed`	`m/s`	The mean velocity over all collected data samples.
`meanOccupancy`	`%`	The percentage (0-100%) of the detector's place that was occupied by vehicles, summed up for each time step and averaged by the interval duration.
`maxOccupancy`	`%`	The maximum percentage (0-100%) of the detector's place that was occupied by vehicles during the interval.
`meanMaxJamLengthInVehicles`	`#vehicles`	The length of the longest jams recognized during each step, averaged over the interval duration. In vehicles that have contributed to these jams.
`meanMaxJamLengthInMeters`	`m`	As prior, but in meters (see notes)
`maxJamLengthInVehicles`	`#vehicles`	The length of the longest jam recognized during the interval duration. In vehicles that have contributed to this jams.
`maxJamLengthInMeters`	`m`	As prior, but in meters (see notes)
`jamLengthInVehiclesSum`	`#vehicles`	The sum of all lengths of all jams recognized during the interval. In vehicles that have contributed to these jams.
`jamLengthInMetersSum`	`m`	As prior, but in meters (see notes)
`meanHaltingDuration`	`s`	The mean halting duration of vehicles that entered the area and are still inside.
`maxHaltingDuration`	`s`	The maximum halting duration of vehicles that entered the area and are still inside.
`haltingDurationSum`	`s`	The sum of all halting durations of vehicles that entered the area and are still inside.
`meanIntervalHaltingDuration`	`s`	The mean halting duration of vehicles that entered the area and are still inside, counted from the interval's begin.
`maxIntervalHaltingDuration`	`s`	The maximum halting duration of vehicles that entered the area and are still inside, counted from the interval's begin.
`intervalHaltingDurationSum`	`s`	The sum of all halting durations of vehicles that entered the area and are still inside, counted from the interval's begin.
`startedHalts`	`#`	The number of strated halts. Please note that during an interval a vehicle may stop halting and enter a new halting state.
`meanVehicleNumber`	`#`	The mean number of vehicles that were on the detector (averaged over the interval duration).
`maxVehicleNumber`	`#`	The maximum number of vehicles that were on the detector area during the interval.

Recent changes:

As detectors have been reworked for version 0.9.8, some used measures may have changed. Please consult the table above.
Since version 0.9.8, the attribute "style" is marked as deprecated, a warning is generated.
Using element name "detector" together with a type is marked as deprecated since version 0.9.8, a warning is generated.
The parameter "measures" is no longer supported since version 0.9.8, the detector writes always all values. A warning is generated.
The parameter "keep_for" is no longer supported since version 0.9.8, a warning is generated.
E2-detectors coupled to traffic lights are now described in "Coupled E2-Output".
The usage of attribute "friendly_pos" was reworked for version 0.9.8

6.1.1.3. E3-Detectors (Multi-Origin/Multi-Destination Detectors)

The descriptions of E3-detectors have to include the set of entry- and the set of exit-cross-sections. Due to this, it is not possible to use a single tag to specify a detector. Instead, the description consists of the following parts:

A beginning tag that describes some global attributes of the detector just as the descriptions of e1- and e2-detectors do. The format is:
```
<e3-detector id="<ID>" file="<OUTPUT_FILE>" freq="<AGGREGATION_TIME>"
   [time_treshold="<FLOAT>"] [speed_treshold="<FLOAT>"]>
```
As one can see, no information about the detector's position is stored herein. They are stored in embedded tags instead (2. and 3.)
A set of tags that describe the detector's entry points in the form:
```
<det_entry lane="<LANE_ID>" pos="<POSITION_ON_LANE>" [friendly_pos="x"]/>
```
A set of tags that describe the detector's exit points in the form:
```
<det_exit lane="<LANE_ID>" pos="<POSITION_ON_LANE>" [friendly_pos="x"]/>
```
A closing tag that must match the opening tag (1.):
```
</e3-detector>
```

The definition

<e3-detector id="e3_1" freq="300" file="./output/e3_1.xml">
   <det_entry lane="myEdge0_0" pos="0"/>
   <det_entry lane="myEdge0_1" pos="0"/>
   <det_exit lane="myEdge2_0" pos="0"/>
   <det_exit lane="myEdge2_1" pos="0"/>
</e3-detector>

will build an e3-detector starting at either lane 0 or 1 of the edge called "myEdge0" and end at the same lane of "myEdge2". All values will be computed as the default-value for measures is used and aggregated over a time of 300s. They will be written into the file "e3_1.xml" lying in the subfolder of the folder the configuration was read in/the program has been started within.

A single data line within the output of a simulated e3-detector looks as following (the line is not broken within the output):

<interval begin="<BEGIN_TIME>" end="<END_TIME>" id="<ID>" \
   meanTravelTime="<MEAN_TT>" meanSpeed="<MEAN_SPEED>" \
   meanHaltsPerVehicle="<MEAN_HALT_NUMBER>" vehicleSum="<#VEHICLES>" \
   meanSpeedWithin="<MEAN_SPEED>" meanHaltsPerVehicleWithin="<MEAN_HALT_NUMBER>" \
   meanDurationWithin="<MEAN_HALT_DURATION>" vehicleSumWithin="<#VEHICLES>" \
   meanIntervalSpeedWithin="<MEAN_SPEED>" \
   meanIntervalHaltsPerVehicleWithin="<MEAN_HALT_NUMBER>" \
   meanIntervalDurationWithin="<MEAN_HALT_DURATION>"/>

As for e2-detectors, the measures generated by e3-detectors may be grouped by the way they are computed. The plain measures take only those vehicles into account that have left the detector area within the described interval. Additionally, measures of the vehicles that are still inside the area are generated (postfix "Within"), containing both measures valid for the whole ride through the area and measures made up of only those samples that were collected within the current interval ("...Interval..."). The value are described one by one in the following table.

Table 6.3. Definition of values generated by e3-detectors

Name	Measure	Description
`begin`	`(simulation) seconds`	The first time step the values were collected in
`end`	`(simulation) seconds`	The last time step the values were collected in (may be equal to begin)
`id`	`-`	The id of the detector (needed if several detectors share an output file)
`meanTravelTime`	`s`	The time vehicles needed to pass the area. Averaged over all vehicles that have left the detector during the interval duration.
`meanSpeed`	`m/s`	The mean speed of vehicles that have passed the area. Averaged over the interval and vehicles.
`meanHaltsPerVehicle`	`#`	The number of halts of vehicles that have passed the area. Averaged over all vehicles that have left the detector during the interval duration.
`vehicleSum`	`#`	The number of vehicles that have left the area during the interval.
`meanSpeedWithin`	`m/s`	The mean speed of those vehicles that have entered, but not yet left the area. Averaged over the time each vehicle was in the area and vehicles.
`meanHaltsPerVehicleWithin`	`#`	The mean number of haltings of those vehicles that have entered, but not yet left the area. Averaged over the time each vehicle was in the area and vehicles.
`meanDurationWithin`	`s`	The mean duration is within the area of those vehicles that have entered, but not yet left the area. Averaged over the time each vehicle was in the area and vehicles.
`vehicleSumWithin`	`#`	The number of vehicles that have entered but not yet left the area.
`meanIntervalSpeedWithin`	`m/s`	The mean speed of those vehicles that have entered, but not yet left the area, collected during the written interval. Averaged over the interval and vehicles.
`meanIntervalHaltsPerVehicleWithin`	`#`	The number of vehicles that have left the area during the interval, collected during the written interval. Averaged over the interval and vehicles.
`meanIntervalDurationWithin`	`s`	The number of vehicles that have left the area during the interval, collected during the written interval. Averaged over the interval and vehicles.

Recent changes:

As detectors have been reworked for version 0.9.8, some used measures may have changed. Please consult the table above.
Using element name "detector" together with a type is marked as deprecated since version 0.9.8, a warning is generated
The parameter "measures" is no longer supported since version 0.9.8, the detector writes always all values. A warning is generated.
The parameter "keep_for" is no longer supported since version 0.9.8, a warning is generated.
The usage of attribute "friendly_pos" was reworked for version 0.9.8

6.1.1.4. VTypeProbes

A vtypeprobe is defined the following way:

<vtypeprobe id="<ID>" [ type="<VEHICLE_TYPE>" ] freq="<OUTPUT_FREQUENCY>" 
   file="<OUTPUT_FILE>"/>

type names the vehicle type to observe. Only the values of vehicles of this type will be written into the output. If type is empty, the information about all vehicles are included. In contrary to the detectors described above, the values are not aggregated. This means that frequency does not describe an aggregation interval but the frequency with which the values shall be collected and written.

Again, the explicit list of available attributes:

id: A string holding the id of the detector
type: The type the vehicles must be of in order to be reported.
freq: The frequency with which information shall be written.
file: The path to the output file. The path may be relative.

The output is devided into timestep-sections:

    <timestep time="<COLLECTION_TIME>" id="<DETECTOR_ID>" vtype="<OBSERVED_TYPE>">
        <vehicle id="<VEHICLE_ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>" \
            x="<X-COORDINATE>" y="<Y-COORDINATE>" \
            lat="<LAT-COORDINATE>" lon="<LON-COORDINATE>" \
            speed="<VEHICLE_SPEED>"/>
        ... further vehicles ...
    </timestep>
    ... further time steps ...

The values are described in the following table.

Table 6.4. Definition of values generated by e2-detectors

Name	Measure	Description
`time`	`(simulation) seconds`	The time the values were collected at
`timestep@id`	`-`	The id of the detector
`vtype`	`-`	The id of the vytpe observed by this detector
`vehicle@id`	`-`	The id of the described vehicle
`lane`	`-`	The id of the lane the vehicle was on.
`pos`	`m`	The position of the vehicle on `lane`
`x`	`m`	The x-position of the vehicle within the net
`y`	`m`	The y-position of the vehicle within the net
`lat`	`arcseconds`	The lat-position of the vehicle within the net
`lon`	`arcseconds`	The lon-position of the vehicle within the net
`speed`	`m/s`	The speed of the vehicle within the time step.

Recent changes:

Integrated in version 0.9.9.

6.1.2. Network State Dump

In the hope that every user wants to know different things and is able to write a tool that parses this information from a not aggregated output, the network dump was the first output capability we've implemented. To force SUMO to build a file that contains the network dump, extend your command line (or configuration) parameter by --netstate-dump (or --ndump or --netstate) <FILE>. <FILE> is hereby the name of the file the output will be written to. Any other file with this name will be overwritten, the destination folder must exist.

The network dump is a xml-file containing for each time step every edge of the network with every lane of this edge with all vehicles on this lane. For each vehicle, his name, speed and position on his lane are written. A network dump-file looks like this:

<sumo-netstate>
   <timestep time="<TIME_STEP>">
      <edge id="<EDGE_ID>">
         <lane id="<LANE_ID>">
            <vehicle id="<VEHICLE_ID>" pos="<VEH_POSITION>" speed="<VEH_SPEED>"/>

            ... more vehicles if any on this lane ...

         </lane>

         ... more lanes if the edge possesses more ...

      </edge>

      ... more edges ....

   </timestep>

... the next timestep ...

</sumo-netstate>

The values have the following meaning:

time: The time step described by the values within this timestep-element
id: The id of the edge/lane/vehicle
pos: The position of the vehicle at the lane within the described time step
speed: The speed of the vehicle within the described time step

As you may imagine, this output is very verbose. His main disadvantage is the size of the generated file. It's very easy to generate files that are several GB large within some minutes. It is of course possible to write some nice tools that parse the file (using a SAX-parser) and generate some meaningful information, but we do not know anyone who has made this. Another problem is that the simulation's execution speed of course breaks down when such an amount of data must be written.

Normally, all lanes are written, even if there is no vehicle on them. You can change this behaviour using the boolean switch --dump-empty-edges. In this case, only those edges and lanes will be written that contain vehicles.

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_rawdump/ shows how the raw output is used. The output is written into the subfolder "output".

Recent changes:

Please notice that this options has been earlier named --output (-o)

6.1.3. Aggregated Lane/Edge States (Edge/Lane-Dumps)

This output is far more feasible than the network dump. There are two different types of these files, one is edge-based, the other lane-based. Both describe the situation on all of the network's edges/lanes in terms of traffic science by giving macroscopic values such as the mean vehicle speed, the mean density, etc.

In the following, it is described how both outputs are generated and which values they contain. Then, the meanings of the values are given as well as a description of intervals. At last, some additional possibilities to constraint the outputs are given.

	Note
	Please remark that "aggregated lane/edge states" are also called "meandata" or "edge/lane-dumps".

	Note
	Some people find the number of information within the lane/edge states quite minimalist. This is because this output is used as input for the DUAROUTER during the computation of a dynamic user assignment (see "Dynamic User Assignment and Alternative Routes") and due to this is meant to be fast. That's why it only contains values that are fast to compute.

Recent changes:

The documentation has been updated to fit the real output when being rechecked for version 0.9.3
The (even invalid) documentation of the file printed previously at the begin of the file was removed in version 0.9.3
This documentation text was rewritten for version 0.9.5, because the previous text said that only those vehicles are regarded which have left the lane. The edge-dumps/lane-dumps contain instead the values of all vehicles that were on the edges/lanes within the interval.
Furthermore, computation of the density and the occupancy has been debugged for version 0.9.5.
Since version 0.10.0, edge/lane states are defined within additional files.

6.1.3.1. Edge-Based Network States

An edge-based state dump is defined this way:

<meandata-edge id="<DETECTOR_ID>" freq="<FREQUENCY>" file="<OUTPUT_FILE>" \
   excludeEmpty="true"/>

The "id" is any string by which you can name the detector. The "freq"-attribute describes the period over which collected values shalle be aggregated. The "file" attribute tells the simulation to which file the detector shall write his results into. The file will be generated, does not have to exist earlier and will be overwritten if existing without any warning. The folder the output file shall be generated in must exist. If "excludeEmpty" is set to true, no information aboute edges where no vehicle drove is written.

For edge-based state dumps, the output file will look like the following:

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 sampledSeconds="<COLLECTED_VEHICLE_SECONDS>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>" \
                 entered="<ENTERED_VEH_NUMBER>" emitted="<EMITTED_VEH_NUMBER>" \
                 left="<LEFT_VEH_NUMBER>"/>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

Please remark, that in contrary to the example above, for each edge, all values are reported in one line.

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_meandata_edges/ shows how to generate an edge-based aggregated state output. Herein, four outputs are written into the subfolder "output", one for each of the intervals 15s, 60s, 300s, and 900s.

6.1.3.2. Lane-Based Network States

A lane-based state dump is defined analogous to edge-dumps:

<meandata-lane id="<DETECTOR_ID>" freq="<FREQUENCY>" file="<OUTPUT_FILE>" \
   excludeEmpty="true"/>

The generated output looks like the following:

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>">
         <lane id="<LANE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 sampledSeconds="<COLLECTED_VEHICLE_SECONDS>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>" 
                 entered="<ENTERED_VEH_NUMBER>" emitted="<EMITTED_VEH_NUMBER>" \
                 left="<LEFT_VEH_NUMBER>"/>

         ... more lanes...

      </edge>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

Please remark, that in contrary to the example above, for each edge, all values are reported in one line.

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_meandata_lanes/ shows how to generate a lane-based aggregated state output. Herein, four outputs are written into the subfolder "output", one for each of the intervals 15s, 60s, 300s, and 900s.

6.1.3.3. Value Descriptions

Both the edge-dump and the lane-dump are computing the values the same way: every vehicle move - even those with v=0 - is recorded and saved during the interval. After the interval has passed, these values are written into the file after being normalized. In the case of the edge-dump the values are not only normalized by the number of the collected vehicle moves and the length of the lane, but also by the number of lanes of the edge.

The meanings of the written values are given in the following table.

Table 6.5. Definition of values generated by edgedump/lanedump-outputs

Name	Measure	Description
`begin`	`(simulation) seconds`	The first time step in which the reported values were collected
`end`	`(simulation) seconds`	The last time step in which the reported values were collected
`edge@id`	`ID`	The name of the reported edge
`lane@id`	`ID`	The name of the reported lane
`traveltime`	`s`	Time needed to pass the edge/lane
`sampledSeconds`	`s`	Number seconds vehicles were measured on the edge/lane (may be subseconds if a vehicle enters/leaves the edge/lane)
`density`	`#veh/km`	Vehicle density on the lane/edge
`occupancy`	`%`	Occupancy of the edge/lane in %
`noStops`	`#`	The number of stops counted at the edge/lane within the described interval
`speed`	`m/s`	The mean speed on the edge/lane within the reported interval
`entered`	`#`	The number of vehicles that have entered the edge/lane within the described interval
`emitted`	`#`	The number of vehicles that have been emitted onto the edge/lane within the described interval
`left`	`#`	The number of vehicles that have left the edge/lane within the described interval

The interval end is the interval begin + aggregation time - 1, meaning that values were collected within these steps. If the simulation ends before the last interval is over, the interval will be prunned.

6.1.3.4. Constraining the State Outputs

If you need only information about the network states during certain time periods, you may constraint generation of the dumps by giving attributes "begin="<TIME>[,<TIME>]+"" and "end="<TIME>[,<TIME>]+"". When at least one combination is given, dumps will be written only if an according begin/end-pair exists for the current time. This means, only those intervals will be saved for which begin[x]<=INTERVAL_END and end[x]>=INTERVAL_BEGIN. All dumps will cover the complete simulation if no values for begin/end are given..

6.1.3.5. Misc

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_meandata_constrained/ shows how to generate a restrained state output. Herein, eight outputs are written into the subfolder "output", four edge- and four lane-based, and for each of the intervals 15s, 60s, 300s, and 900s.

Recent changes:

The values have been revisited and partially changed for version 0.9.9

6.1.4. Net-Wide Vehicle Emission States & Travel Times

You can force the simulation to generate this output using --emissions-output <FILENAME> or --emissions <FILENAME>. This output contains the simulation-wide number of vehicles that are loaded, emitted, running, waiting to be emitted, have reached their destination and how long they needed to finish the route. The last value is normalised over all vehicles that have reached their destination so far. The information containing all those values is computed for each time step and the output file looks like following:

<emissions>
   <emission-state time="<SIMULATION_TIME>"
              loaded="<LOADED_VEHICLE_NUMBER>" \
              emitted="<EMITTED_VEHICLE_NUMBER>" \
              running="<RUNNING_VEHICLE_NUMBER>" \
              waiting="<NUMBER_OF_VEHICLES_WAITING_FOR_EMISSION>" \
              ended="<ENDED_VEHICLE_NUMBER>" \
              meanWaitingTime="<MEAN_WAITING_TIME>" \
              meanTravelTime="<MEAN_TRAVEL_TIME>"/>

   ... further time steps ...

</emissions>

Please remark, that in contrary to the example above, for each time step, all those values are reported in one line. A description of the values is given in the table below.

Table 6.6. Definition of values generated by emissions-output

Name	Measure	Description
`time`	`(simulation) seconds`	The time step described by the entry
`loaded`	`#`	Number of vehicles that were loaded into the simulation so far (including reported time step)
`emitted`	`#`	Number of vehicles emitted so far (including reported time step)
`running`	`#`	Number of vehicles that were running within the reported time step
`waiting`	`#`	Number of vehicles which were waiting for emission (could not be emitted) within the reported time step
`ended`	`#`	Number of vehicles that have reached their destination so far (including reported time step)
`meanWaitingTime`	`s`	The mean time all vehicles up to now and within the reported time step had to wait for being emitted;-1 if no vehicle has been emitted, yet
`meanTravelTime`	`s`	The mean travel time of all vehicles that have left the simulation within the previous and the reported time;-1 if no vehicle has been removed from the simulation, yet

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_emissions/ shows how the emissions output is used.

Recent changes:

In versions prior to 0.9.3, the attribute "time" was named "id"

6.1.5. Vehicle-Oriented Trip Information

The simulation is forced to generate this output using: --tripinfo-output <FILENAME> or --tripinfo <FILENAME>. This output contains the information about each vehicle's departure time, the time the vehicle wanted to start at (which may be lower than the real departure time) and the time the vehicle has arrived. Such an information is generated for each vehicle as soon as the vehicle has arrived its destination and is removed from the network. The format is as following:

<tripinfos>
    <tripinfo id="<VEHICLE_ID>" \
            depart="<DEPARTURE_TIME>" departLane="<DEPARTURE_LANE_ID>" \
            departPos="<DEPARTURE_POSITION>" departSpeed="<DEPARTURE_SPEED>" \
            departDelay="<DEPARTURE_DELAY>" \
            arrival="<ARRIVAL_TIME>" arrivalLane="<DEPARTURE_LANE_ID>" \
            arrivalPos="<ARRIVAL_POSITION>" arrivalSpeed="<ARRIVAL_SPEED>" \
            duration="<TRAVEL_TIME>" routeLength="<ROUTE_LENGTH>" \
            waitSteps="<STEPS_WITH_HALTS>" rerouteNo="<REROUTE_NUMBER>" \
            devices="<DEVICE_LIST>" vtype="<VEHICLE_TYPE_ID>"/>

   ... information about further vehicles ...

</tripinfos>

Please remark, that in contrary to the example above, for each time step, all those values are reported in one line. An entry is written each time a vehicle has arrived at his destination. In prior to this, the written values would not be known.

Table 6.7. Definition of values generated by tripinfo-output

Name	Measure	Description
`id`	`ID`	The name of the vehicle that is described by this entry
`depart`	`(simulation) seconds`	The real departure time (the time the vehicle was emitted into the network)
`departLane`	`ID`	The id of the lane the vehicle started its journey
`departPos`	`m`	The position on the lane the vehicle started its journey
`departSpeed`	`m/s`	The speed with which the vehicle started its journey
`departDelay`	`(simulation) seconds`	The time the vehicle had to wait before it could start his journey
`arrival`	`(simulation) seconds`	The time the vehicle reached his destination at
`arrivalLane`	`ID`	The id of the lane the vehicle was on when reaching his destination
`arrivalPos`	`m`	The position on the lane the vehicle was when reaching the destination
`arrivalSpeed`	`m/s`	The speed the vehicle had when reaching the destination
`duration`	`(simulation) seconds`	The time the vehicle needed to accomplish the route
`routeLength`	`m`	The length of the vehicle's route
`waitSteps`	`simulation steps`	The number of steps in which the vehicle speed was below 0.1m/s
`rerouteNo`	`#`	The number the vehicle has been rerouted
`devices`	`[ID]*`	List of devices the vehicle had. Each device is separated from the others by a ';'.
`vtype`	`ID`	The type of the vehicle

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_tripinfo/ shows how the tripinfo output is used. The output is written into the subfolder "output".

Recent changes:

In versions prior to 0.9.3, the attribute "vehicle_id" was named "id"
The documentation has been updated before releasing version 0.9.3
The reroutes attribute was added for version 0.9.6
The devices list attribute was added for version 0.9.6
The vtype attribute was added for version 0.9.6
The vehicle_id attribute was renamed to id in version 0.9.9
The start attribute was renamed to depart in version 0.9.9
The attributes departLane, departPos, departSpeed were added in version 0.9.9
The end attribute was renamed to arrival in version 0.9.9
The attributes arrivalLane, arrivalPos, arrivalSpeed were added in version 0.9.9
In version 0.9.9, the attribute waited was removed; instead departDelay was introduced
The attributes routeLength and waitSteps were added in version 0.9.9
The reroutes attribute was renamed to rerouteNo in version 0.9.9

6.1.6. Vehicle Routes

The vehicle routes output contains information about which route a vehicle took and if his route was replaced at any time by a new one, each of the previous routes together with the edge at the time their replacement took place is reported. Furthermore, the vehicle emission and ending time is stored herein.

The generated file look like this:

<routes>
   <vehicle id="<VEHICLE_ID>" depart="<EMISSION_TIME>" arrival="<ARRIVAL_TIME>">
      <route replacedOnEdge="<EDGE_ID>" replacedAtTime="<TIME>" edges="<PREVIOUS_ROUTE>"/>

      ... further replaced routes ...

      <route edges="<LAST_ROUTE>"/>
   </vehicle>

   ... information about further vehicles ...

</routes>

The values have the following meanings:

id: the id of the vehicle this entry describes
depart: The time the vehicle was emitted into the network)
arrival: The time the vehicle was removed from the simulation (due to arriving at the route end)
replacedOnEdge: The edge the vehicle was on when the described route was replaced
replacedAtTime: The time step of this replacement
<PREVIOUS_ROUTE>: The replaced route
<LAST_ROUTE>: The final vehicle route

Both the previous and the final routes are complete, that means that they contain all the edges the vehicle was meant to pass as long as the route was not replaced, yet. The information replacedOnEdge and replacedAtTime are available only for routes which were replaced.

In normal conditions, when all vehicles use predefined routes, the output does not contain any information that could not be retrieved from the routes and the tripinfo output. But as soon as you reroute your vehicles within the simulation, f.e. using rerouters (see "Rerouter"), it will contain new information.

The simulation is forced to generate this output using: --vehroutes-output <FILENAME> or --vehroutes <FILENAME>.

Examples:

<SUMO_DIST>/data/examples/output_tests/cross3ltl_vehroutes/ shows how the vehicle routes output is used. The output is written into the subfolder "output". This is just a basic example that the output is generated. Better take a look at <SUMO_DIST>/data/examples/extended/rerouter/.
<SUMO_DIST>/data/examples/extended/rerouter/ uses rerouters to change the vehicles' routes. A vehicle routes output into the output-subfolder.

Recent changes:

This output was finally finished and validated for version 0.9.3
The format was changed to fit a normal route file more closely in 0.10.0

6.1.7. Output coupled to Traffic Lights

SUMO offers some possibilities to save states of traffic lights during the simulation, a feature mainly used to evaluate adaptive traffic light algorithms. We will now describe these outputs.

6.1.7.1. TLS States

To enable writing tls state information you have to add the following definition into one of your additional files: <timed_event type="SaveTLSStates" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

type: type of the event trigger; always "SaveTLSStates" herein
source: The id of the traffic light which state shall be written
dest: The file to save the state into

The output looks like this:

<tls-states>
   <tlsstate time="<SIM_STEP>" id="<TLS_ID>" subid="<TLS_SUBID>"><STATE></tlsstate>
   ... further states ...
</tls-states>

The state is saved in each simulation second. The state itself is coded as a list of the characters 'G', 'Y', and 'R', standing for "green", "yellow", and "red", respectively. Each character describes a link controlled by the traffic light. Only the state of the current program is saved (see also "Adding new Programs"). The attributes have the following meaning:

time: The simulation time this entry was generated for
id: The id of the tls that is responsible for the link
subid: The sub-id of the tls that is (currently) responsible for the link

Missing:

An easy mapping from positions within the state to links.

Recent changes:

This output is available since a long time, still several issues may made him unworking before version 0.9.5
Since version 0.9.6 only the state of the current program is saved

6.1.7.2. TLS Switches

This output contains information about the green light phases of links (lane-to-lane connections). Each green light phase is describes by its begin, end and duration. An entry is written into the file as soon a green phase of a link ends. To enable writing tls switch information you have to add the following definition into one of your additional files: <timed_event type="SaveTLSSwitchTimes" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

type: type of the event trigger; always "SaveTLSSwitches" herein
source: The id of the traffic light which state shall be written
dest: The file to save the state into

The output looks like this:

<tls-switches>
   <tlsswitch tls="<JUNCTION_ID>" subid="<JUNCTION_SUB_ID>" \
      fromLane="<LINKS_SOURCE_LANE>" toLane="<LINK_DESTINATION_LANE>" \
      begin="<BEGIN_OF_GREEN_PHASE>" end="<END_OF_GREEN_PHASE>" \
      duration="<DURATION_OF_GREEN_PHASE>"/>
   ... further switch points ...
</tls-switches>

Each entry is written into a single line. The values have the following meanings:

junction: The id of the tls that is responsible for the link
subid: The sub-id of the tls that is (currently) responsible for the link
fromLane: The id of the lane the link starts at
toLane: The id of the lane the link ends at
begin: Begin of this link's last green phase
end: End of this link's last green phase
duration: Duration of this link's last green phase

Recent changes:

This output is available since version 0.9.5
The element "switch" was renamed to "tlsswitch" in version 0.9.6

6.1.7.3. TLS Switch States

This output saves tls-states as the TLS States - output does but not every second but only at times the phases or the program (see also "Adding new Programs") change. The output is instantiated by adding the following definition into one of your additional files: <timed_event type="SaveTLSSwitchStates" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

type: type of the event trigger; always "SaveTLSSwitches" herein
source: The id of the traffic light which state shall be written
dest: The file to save the state into

The output looks like this:

<tls-switch-states>
   <tlsstate time="<SIM_STEP>" id="<TLS_ID>" subid="<TLS_SUBID>"><STATE></tlsstate>
   ... further states ...
</tls-switch-states>

Each entry is written into a single line. The values have the following meanings:

time: The simulation time this entry was generated for
id: The id of the tls that is responsible for the link
subid: The sub-id of the tls that is (currently) responsible for the link

Recent changes:

This output is available since version 0.9.6

6.1.7.4. Coupled E2-Output

It is possible to add e2-detectors which are coupled to a traffic light. Then, the tls is used to determine the intervals (aggregation) time instead of giving a fixed aggregation time. In this case, output will be generated every time the traffic light switches. To use this feature, simply replace the freq-attribute within the description of an e2-detector by the id of the traffic light that should steer it (use the attribute "tl" to specify the id):

<e2-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   length="<DETECTOR_LENGTH>" tl="<TL-ID>" 
   file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

A further feature allows you to collect measures only for the time the light turns yellow for a certain link (connection between the incoming and the outgoing lane). This should allows measuring the maximum jam length in front of a red traffic light for this link. To enable this, one has to add the name of the following lane:to="<LANE_ID>" to the list of attributes. The incoming lane is already given by the "lane"-attribute.

<e2-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   length="<DETECTOR_LENGTH>" tl="<TL-ID>" to="<LANE_ID>"
   file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

Recent changes:

This output was refactored and retested for version 0.9.8

6.2. Vehicles Handling Revisited

In the normal case, SUMO is meant to simulate urban areas where vehicles may start their trips from any edge. Still, there also some other approaches to feed a simulation with a demand and some of them where implemented in SUMO. You have the following possibilities to add vehicles into your network:

Insert vehicles on any edge
In this case, a vehicle from the list will be inserted at the given time into the edge his route starts at. The position of the insertion is random (by now), the rightmost lane will be used.
Insert vehicles on feeding edges
This is approach is often used in conjunction with od-matrices; each of the districts described in such od-matrices contains a list of "feeding" or "source" edges. If you use feeding edges, your vehicles will be inserted similar to insertion on normal edges as described above, but they will be always inserted at the end of the edge and all lanes of the feeding edge will be used.
Using emitter
Emitter are used to insert vehicles into the network at a well defined position. An emitter may be placed on a certain lane and gets a list of vehicles (or a flow amount) to emit. We use this approach often to insert vehicles into the network at places where induction loops have measured the flows.

We will now describe the emitters more deeply.

6.2.1. Emitter

Emitters may be used to define flows using induction loops as input data. For such modelling attempt, you should place emitters at those positions on the network where the induction loops are located and convert the values retrieved from the induction loops to the format emitters may read. The format is described below, together with some additional methods to ease generation of emitter files. If you are working with such inputs extensively, you may be also interested in what the DFROUTER does (see "Using Detectors and DFROUTER" for a further documentation).

Recent changes:

Although emitters are available for a long time already, their description has been added while working on version 0.9.5
The attribute vehtype was renamed to type while working on version 0.9.9
Emitters are considered deprecated since version 0.10.0

6.2.1.1. Basic Definition

You can place an emitter onto a lane by adding the following declaration to one of your additional-files:

<emitter id="<ID>" pos="<POS>" lane="<LANE_ID>" \
   [friendly_pos="x"] file="<DEFINITION_FILE>"/>

The fields have the following meanings:

id: A string holding the id of the emitter.
pos: Position on the lane in meters; if positive, then the following must be ensured: 0<=<POS><<LANE_LENGTH>, if negative: 0><POS>>-<LANE_LENGTH>; in this case the position will be counted from the lane's end.
lane: The id of the lane the emitter shall be placed on
friendly_pos: optional; if this is set and the position (pos) is not valid, the detector will be placed at the lane's end (0.1meter away from it).
file: The file the emitter shall read the definition of what/how/when to emit from

An emitter needs further information to know when, how many and what kind of vehicles shall be emitted. All this information must be written into <DEFINITION_FILE>. The easiest way to describe vehicle emissions herein is to list all of them explicitely:

<triggeredsource>
   <emit id="veh1" time="0" type="my_type" route="my_route" speed="13.9"/>
   <emit id="veh2" time="4" type="my_type" route="my_route" speed="13.9"/>
   <emit id="veh3" time="8" type="my_type" route="my_route" speed="13.9"/>
</triggeredsource>

Using such a definition only would raise error because we have named the vehicle types and the routes but did not define them. We can either define them within another additional file or within a route file but we have to ensure that they're loaded before the emission definition is (see "Using the Files in a correct Way" on loading order). Let's assume we have done it. In this case, using such a definition we would emit three vehicles, having the names "veh1", "veh2", and "veh3" as given within the id-field, all being of type "my_type". All vehicles use the same route, "my_route", and will start with a velocity of 0 at the simulation seconds 0, 4, and 8. To summarize, a vehicle emission within an Emitter definition is described as following: <emit [id="<VEHICLE_ID>"] [type="<VEHICLE_TYPE>"] time="<EMISSION_TIME>" [route="<VEHICLE_ROUTE>"] [speed="<INITIAL_SPEED>"]/>. The meanings of these values are:

id: The id of the vehicle to emit
type: Name of the vehicle type the vehicle to emit shall have
time: The time at which the vehicle shall be emitted (in simulation seconds)
route: Name of the route the vehicle shall use
speed: The speed the vehicle shall be emitted with in m/s

As you can see, several of the fields are marked as optional. If no id is given, the id will be constructed automatically. The vehicle will then have a name made up from the emitter's id followed by the time step the vehicle shall be emitted at and a running number, all divided by a '_' ("<EMITTER_ID>_<DEPART>_<RUNNING>"). Also, the emission speed is optional. If not given, the minimum of the maximum speed allowed on the lane and the vehicle's maximum velocity is used. If the emission time lies before the simulation begin, the vehicle will be discarded. The following sections describe how one can omit explicite attributes for vehicle type and route.

Recent changes:

The definition has been renamed from "trigger" to "emitter" after version 0.9.10. In conjunction, the definition's attribute "objecttype" is not longer used.
The attribute "objectid" was renamed to "lane" after version 0.9.10.

6.2.1.2. Describing Route Distributions

To avoid computing and assigning a vehicle type and a route to each vehicle emission definition explicitely, you can define a probability distribution by which routes/types are chosen from a set. For the routes, you can do this as shown in the next example:

<triggeredsource>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <emit id="veh1" time="0" type="my_type" speed="13.9"/>
   <emit id="veh2" time="4" type="my_type" speed="13.9"/>
</triggeredsource>

Now, a random route is assigned to a vehicle, "my_route1" with a probability of .2, "my_route2" with a probability of .8. The probabilities are normed automatically, that means that you can also use numbers that do not sum to 1. Each occuring routedistelem will be added to the distribution (see also "Resetting the Distributions"). The meanings of the attributes of a routedistelem-element are:

id: The name of the route to use (the route must have been loaded in prior to the occurence of the routedistelem-element)
probability: The probability (value/sum of probabilities) of choosing the route

6.2.1.3. Describing Vehicle Type Distributions

Vehicle types may be assigned to vehicles from distributions, too:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".8"/>
   <vtypedistelem id="my_type2" probability=".8"/>

   <emit id="veh1" time="0" route="my_route" speed="13.9"/>
   <emit id="veh2" time="4" route="my_route" speed="13.9"/>
</triggeredsource>

In this example the probabilities for using one of the types are equal. The probabilities are normed automatically, that means that you can also use numbers that do not sum to 1. Each occuring vtypedistelem will be added to the distribution (see also "Resetting the Distributions"). The meanings of the attributes of a vtypedistelem-element are:

id: The name of the vehicle type to use (the vehicle type must have been loaded in prior to the occurence of the vtypedistelem-element)
probability: The probability (value/sum of probabilities) of choosing the vehicle type

6.2.1.4. Resetting the Distributions

As said before, all occurences of vtypedistelem are stored into the same distribution. This also holds for the occurences of routedistelem. Now, one maybe wants to model different distributions over time. To allow this, you can add a "reset"-element to your description:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".5"/>
   <vtypedistelem id="my_type2" probability=".5"/>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <emit time="10" speed="13.9"/>
   ... further vehicle emits ...
   <emit time="20" speed="13.9"/>

   <reset/>

   <vtypedistelem id="my_type3" probability=".5"/>
   <vtypedistelem id="my_type4" probability=".5"/>
   <routedistelem id="my_route3" probability=".2"/>
   <routedistelem id="my_route4" probability=".8"/>

   <emit time="30" speed="13.9"/>
   ... further vehicle emits ...
   <emit time="40" speed="13.9"/>

</triggeredsource>

This would force the emitter to reset all distributions after emitting the vehicle at time 20. While vehicles emitted within the times 10 and 20 would use the vehicle types "my_type1" and "my_type2" and routes "my_route1" and "my_route2", the vehicles emitted between time 30 and 40 - after the reset-element - would use the vehicle types "my_type3" and "my_type4" and the routes "my_route3" and "my_route4".

6.2.1.5. Using Flows

Instead of describing each vehicle emission explicitely, you can specify a flow to emit. In this case, vehicle type and routes distributions must be given:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".5"/>
   <vtypedistelem id="my_type2" probability=".5"/>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <flow no="1800" end="10"/>
   <flow no="900" end="20"/>
</triggeredsource>

The meaning of the attributes of a flow-element are:

no: The flow to use in veh/h.
end: The end of the interval for which this flow shall be emitted. If <0 (default) the flow will be used until the simulation's end.

6.3. Traffic Management and Other Structures

SUMO holds several additional structures to model speed limits, public transport etc. The structures are normally defined within additional files.

6.3.1. Traffic Lights

Normally, NETCONVERT will 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 traffic light programs from the reality, it is possible to load additional programs since version 0.9.4. Furthermore, one can describe when and how a set of traffic lights can switch from one program to another. Both will be discussed in the following subchapters.

Handling of traffic lights is not yet very user friendly. Besides the following descriptions, a further document, "SUMO - More on... Traffic Lights", exists which describes the usage of traffic lights more deeply.

6.3.1.1. Adding new TLS-Programs

Since version 0.9.4 you may attach a new program to a tls after the network has been loaded. Defining a tls program is not that straightforward, yet. If you are definitely interested in this, we advice you to read the "SUMO - More on... Traffic Lights" document where the format is described. Basically, a tls program definition looks like this:

<tl-logic type="static">
   <key>0</key>
   <subkey>0</subkey>
   <phaseno>8</phaseno>
   <offset>0</offset>
   <phase duration="20" phase="0000111100001111" brake="1111110011111100" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000110000001100" brake="1111111111111111" \
      yellow="0000001100000011"/>
   <phase duration="3" phase="0000110000001100" brake="1111001111110011" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000000000000000" brake="1111111111111111" \
      yellow="0000110000001100"/>
   <phase duration="20" phase="1111000011110000" brake="1100111111001111" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="1100000011000000" brake="1111111111111111" \
      yellow="0011000000110000"/>
   <phase duration="3" phase="1100000011000000" brake="0011111100111111" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000000000000000" brake="1111111111111111" \
      yellow="1100000011000000"/>
</tl-logic>

After you have defined a tls program, you can add it to one of your additional files. You may load several programs for a single tls into the simulation. The program loaded as last will be used (unless not defined using a WAUT description, see below). Please remark, that all subkeys of your programs must differ if they describe the same tls.

Recent changes:

Loading of additional tls programs is implemented since version 0.9.4
The inclanes tag has been removed from the network description since version 0.9.4
The tag keyno has been renamed to subkey since version 0.9.4

	Caution
	Please keep in mind that this feature is quite new and that du to this some things may not work as suspected and may get changed in the near future.

6.3.1.2. Defining the 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. Since version 0.9.4 you can define switch times between the programs using a WAUT (I am very sorry, but I do not know the English word for WAUT - this may be a matter of change).

Let's assume we would have 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. We'll give these programs the names "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:

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

and the fields in wautSwitch:

time: The time the switch will take place
to: 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 time must be sorted.

Additionally, we have to define which tls shall be switched by the WAUT. This is done as following:

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

Here, the attributes have the following meaning:

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

You may assign several tls to a single WAUT. YOu may also assign several WAUTs to a single junction in theory, but this is not done in reality. The switching procedures are currently under development.

Recent changes:

WAUTs are implemented since version 0.9.4

	Caution
	Please keep in mind that this feature is quite new and that du to this some things may not work as suspected and may get changed in the near future.

6.3.2. Public Transport

Possibilities to simulate public transport were firstly added in version 0.9.3. By now you may define positions of bus stops and let vehicles ("busses") stop at these positions for a pre-given time. Definitions of bus stop locations in SUMO have the following format: <busStop id="<BUS_STOP_ID>" lane="<LANE_ID>" from="<STARTING_POSITION>" to="<ENDING_POSITION>" [line="<LINE_ID>[;<LINE_ID>]*"]/>. That means that a bus stop is an area on a lane. The parameters have the following meanings:

id: id of the bus stop; must be unique
lane: the id of the lane the busstop shall be located at
from: the begin position on the lane (the lower position on the lane) in meters
to: the end position on the lane (the higher position on the lane) in meters
line: A list of names separated by a semicolon (';') meant to be the names of the bus lines that stop at this bus stop. This is only used for visualisation purposes.

Figure 6.1. Visualization of a bus stop in SUMO (from <SUMO_DIST>/data/examples/extended/busses1)

Vehicles must be informed that they must stop at a bus stop. The following example shows how this should be done (taken from <SUMO_DIST>/data/examples/extended/busses1):

    <vtype id="BUS" accel="2.6" decel="4.5" sigma="0.5" length="15" maxspeed="70"
            color="1,1,0"/>

    <vehicle id="0" type="BUS" depart="0" color="1,1,0">
        <route edges="2/0to2/1 2/1to1/1 1/1to1/2 1/2to0/2 0/2to0/1 0/1to0/0 0/0to1/0 1/0to2/0 2/0to2/1"/>
        <stop bus_stop="busstop1" duration="20"/>
        <stop bus_stop="busstop2" duration="20"/>
        <stop bus_stop="busstop3" duration="20"/>
        <stop bus_stop="busstop4" duration="20"/>
    </vehicle>

What we have here is a vehicle named "0" being a "BUS". "BUS" is a referenced type declared earlier. The vehicle has an embedded route (written by hand in this case) and a list of stop places. Each stop place is described by two attributes, "bus_stop" and "duration" where "bus_stop" is the name of the bus stop the vehicle shall halt at and "duration" is the time the vehicle shall wait at the bus stop in seconds. Please remark that the order of bus stops the vehicle shall halt at must be correct.

You may also let a vehicle stop at another position than a bus stop. The complete definition of a vehicle's stop is: <stop ( bus_stop="<BUS_STOP_ID>" | lane="<LANE_ID>" pos="<POSITION_AT_LANE>" ) duration="<HALTING_DURATION>"/>. This means you can either use a bus stop or a lane position to define where a vehicle has to stop.

Again the list of attributes for the "stop"-element of a vehicle:

Either:
- bus_stop: id of the bus stop the vehicle shall halt at; the bus stop must be previously declared
or:
- lane: id of the lane the vehicle shall stop at; the lane must be within the network
- pos: Position on the lane the vehicle shall stop at; double
duration: the time the vehicle shall halt at the bus stop in seconds; int, mandatory

Examples:

<SUMO_DIST>/data/examples/extended/busses1 shows a small example for defining bus stops and letting a bus halt at them
<SUMO_DIST>/data/examples/extended/3busses1 is almost the same as <SUMO_DIST>/data/examples/extended/busses1 but three busses are driving here and the first bus stop is longer than the others. This example shows how the length of bus stops determines how many busses actually can stop here.
<SUMO_DIST>/data/examples/extended/vehicle_stops shows a small example where a vehicle halts

Some extensions still to be done:

Definition of public transport lines instead of giving a list of stops for each vehicle?
Halting times dependent to the number of passengers within the vehicle
Optionally do not let vehicles halt if no person wants to leave/enter

Recent changes:

The definition has been renamed from "trigger" to "busStop" after version 0.9.10. In conjunction, the definition's attribute "objecttype" is not longer used.
The attribute "objectid" was renamed to "lane" after version 0.9.10.

6.3.3. Variable Speed Signs (VSS)

One of the trigger objects that may be specified within an additional file allows the simulation of variable speed signs. The syntax for such an object is: <variableSpeedSign id="<VSS_ID>" lanes="<LANE_ID>[;<LANE_ID>]*" file="<DEF_FILE>"/>.

You may have noticed that a file name must be supplied, called <DEF_FILE> within the schema above. This file must contain the information about when a certain speed shall be set onto the lane. This file has the following format:

<vss>
   <step time="<TIME>" speed="<SPEED>"/>
   <step time="<TIME>" speed="<SPEED>"/>

   ... further entries ...

   <step time="<TIME>" speed="<SPEED>"/>
</vss>

Each step is a combination of the time the next new speed shall be set and the speed to set itself.

A small example for usage of vss' within SUMO may be found in "data/examples/extended/variable_speed_signs".

Recent changes:

The definition has been renamed from "trigger" to "variableSpeedSign" after version 0.9.10. In conjunction, the definition's attributes "objecttype" and "attr" are not longer used.
The attribute "objectid" was renamed to "lanes" after version 0.9.10.

6.3.4. Rerouter

Rerouter change the route of a vehicle as soon as the vehicle moves onto a specified edge.

A rerouter is set into the simulated network by adding the following declaration line to an "additional file": <rerouter id="<REROUTER_ID>" edges="<EDGE_ID>[;<EDGE_ID>]*" file="<DEFINITION_FILE>" [probability="<PROBABILITY>"]/>. As you may see, rerouter may be placed on several edges, at least one edge is necessary. Furthermore, you may already define the probability for rerouting a vehicle by giving a number between 0 (none) and 1 (all). The declaration values are

id: the id of of the rerouter
edges: an edge id or a list of edge ids where vehicles shall be rerouted
file: path to the definition file
probability: the probability for vehicle rerouting (0-1)

In addition to this declaration a definition file (stored in <DEFINITION_FILE>) must be given which describes the behaviour of the rerouter over time. Each description of what a rerouter shall do is embedded in an interval definition which describes within which time period the rerouter shall work. This is set up as following:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      ... action description ...
   </interval>

   ... further intervals ...

</rerouter>

A rerouter may work in several different ways. Within a time period you may close an edge, or assign new destinations or pregiven routes to vehicles. The next subchapters will describe these possibilities and how to describe them within the rerouter's definition file in detail.

Recent changes:

A complete description of rerouters was added in version 0.9.5; in accordace, definitions of rerouters have changed
The description was reworked for version 0.9.8
The definition has been renamed from "trigger" to "rerouter" after version 0.9.10. In conjunction, the definition's attribute "objecttype" is not longer used.
The attribute "objectid" was renamed to "edges" after version 0.9.10.

6.3.4.1. Closing a Street

A "closing_reroute" forces the rerouter to close the edge <EDGE_ID>. Vehicles which normally would pass this edge will get a new route as soon as they reach one of the edges given in the edges-attribute of the rerouter's declaration. a closing_reroute definition may look like this:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <closing_reroute id="<EDGE_ID>"/>
   </interval>

   ... further intervals ...

</rerouter>

The attributes used within such definitions are:

id: the id of the closed edge; mandatory string, the id must be the id of an edge within the network

6.3.4.2. Assigning a new Destination

A "dest_prob_reroute" forces the rerouter to assign a new route to vehicles that pass one of the edges defined in the edges-attribute of the rerouter's declaration. A new route destination is used, defined by the name of a new destination in the according element:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <dest_prob_reroute id="<EDGE_ID1>" probability="<PROBABILITY1>"/>
      <dest_prob_reroute id="<EDGE_ID2>" probability="<PROBABILITY2>"/>
   </interval>

   ... further intervals ...

</rerouter>

The route is computed automatically using the Dijkstra-algorithm and starting at the edge the vehicle is located at and ending at the new destination. The new route will be the fastest route in the empty network.

The attributes used within a dest_prob_reroute are:

id: the id of the new destination; mandatory string, the id must be the id of an edge within the network
probability: the probability with which a vehicle will use the given edge as destination; mandatory float, should be between 0 and 1; the sum of the probabilities should be 1 (but this is not necessary)

6.3.4.3. Assigning a new Route

A "route_prob_reroute" forces the rerouter to assign a new route to vehicles which pass one of the edges defined in the edges-attribute of the rerouter's declaration. In this case, the id of a complete route must be supplied instead of a new destination:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <route_prob_reroute id="<ROUTE_ID1>" probability="<PROBABILITY1>"/>
      <route_prob_reroute id="<ROUTE_ID2>" probability="<PROBABILITY2>"/>
   </interval>

   ... further intervals ...

</rerouter>

The attributes used within such definitions are:

id: the id of a new route to assign; mandatory string, the id must be the id of a previously loaded route
probability: the probability with which a vehicle will use the given edge as destination; mandatory float, should be between 0 and 1; the sum of the probabilities should be 1

6.3.5. Vehicle Classes

Since version 0.9.5 SUMO is capable to handle vehicle classes. One can close a road or a lane for certain vehicle classes or explicitely allow certain vehicle classes on a road/lane. This is done by a combination of assigning allowed/disallowed vehicle classes to roads/lanes and additionally giving vehicles a further class attributes. Available vehicle classes as well as using them is described within the next subchapters.

Caution

Please keep in mind that this feature is quite new and that du to this some things may not work as suspected and may get changed in the near future.

We want to ask you to supply us any comments on this topic - it is not completely designed, yet.

Recent changes:

A first support for vehicle classes was added in version 0.9.5

6.3.5.1. Available Vehicle Classes

A vehicle class is made up of two parts. The first part describes to what kind of an authority the vehicle belongs. The next table shows what kind of authorities are defined currently:

Table 6.8. Allowed vehicle class authority descriptions

Table Name	Description
private	The vehicle belongs to a private person
public_transport	The vehicle is a public transport vehicle
public_emergency	The vehicle is an emergency vehicle
public_authority	The vehicle belongs to a public authority (police)
public_army	The vehicle is an army vehicle
vip	The vehicle is used to transport a vip (very important person)

The second part describes the kind of the vehicle. Currently possible values are shown within the next table:

Table 6.9. Allowed vehicle class vehicle kind descriptions

Table Name	Description
passenger	A plain passenger car
hov	A heavy occupied vehicle
taxi	A taxi
bus	A bus
delivery	A small delivery vehicle
transport	A truck
lightrail	A lightrail
cityrail	A cityrail
rail_slow	A slow transport rail
rail_fast	A fast passenger rail
motorcycle	A motorcycle
bicycle	A bicycle
pedestrian	A pedestrian

Please remark that both the authority descriptions and kind descriptions are only names, no model is stored behind them. By defining a vehicle type as "pedestrian" you will not get a person walking within the simulation - currently pedestrian are not modeled anyway. These values simply name possible types of vehicles found on a network to allow closing/opening lanes or edges for them currently.

6.3.5.2. Closing/Opening Roads/Lanes for certain Vehicle Classes

Roads/lanes are normally marked to allow/disallow a certain vehicle class while building the network using NETCONVERT. This process is described in chapter "Defining allowed Vehicle Types".

6.3.5.3. Assigning a Type to a Vehicle

You can assign a vehicle class to a vehicle by extending this vehicle's vehicle type. Assume you want to set a vehicle as being of the class "bus". A vehicle type definition could look like this:

    <vtype id="BUS" accel="2.6" decel="4.5" sigma="0.5" length="15" maxspeed="70"
            color="1,1,0" vclass="public_bus"/>

In this case, the vehicle will drive only on lanes/roads where all vehicle classes are allowed or where public busses are not disallowed or where public busses are explicitely allowed.

6.3.5.4. Mixing Closings/Openings of Roads for Vehicle Classes

The importer for XML-edge description uses two lanes attributes, allow and disallow (see Defining allowed Vehicle Types). Within the resulting network the values supplied this way are stored by listing all allowed and disallowed vehicle classes, divided by a ';'. Here, disallowed vehicle classes are marked by a leading '-'. This means that if a lane shall not allow pedestrians, it should have the attribute vclasses="-pedestrian".

A vehicle class may use a lane if

there is no vehicle class allowed/disallowed on this lane
the vehicle class matches a class allowed on this lane if any allowed class is defined for this lane
the vehicle class does not match any of the defined disallowed vehicle classes on for this lane

6.4. Using the Files in a correct Way

You may have noticed that beside the networks, SUMO additionally reads route files and "additional" files. Most of the structures (detectors, actors, route definitions, vehicle type definitions, tls definitions, etc.) may be placed in both route files and additional files. On the low application level the difference between the two file types is the order of loading them.

Normally, when the option route-steps is left to be not equal to zero, additional files are parsed first, in the order of their definition. This means if you set the option "-a file1.add.xml;file2.add.xml", at first "file1.add.xml" will be loaded, then "file2.ad..xml". Each file is read completely before the next file is parsed. This means that if you have some global routes and want to reference them by a changing set of vehicles, you should place these routes in a file which is loaded at first. After all additional files have been read, the route files are opened. Still, they are not read immediately but as soon as the simulation starts. Each of these files is read until a vehicle emission occures which is beyond the current time step + time defined in route-steps. Here, all route files are parsed in the order they occured within the call, too.

The things change a little bit if the option route-steps is set to zero. In this case, the route files are parsed as first, BEFORE the simulation starts. They also will be parsed completely before the additional files are parsed. If you need your additional files to be parsed at first, either use a route-steps value not equal to zero or place your additional files at the begin of the route-files list.

6.5. Other Topics

This chapter includes some problems not described, yet.

6.5.1. Simulation of Accidents

SUMO uses a collision-free traffic flow model. So if everything works as it should, no accidents should occure. If you want to model an accident you have the following possibilities:

Use variable speed signs to set a lane's maximum velocity down (see chapter "Variable Speed Signs")
Let a vehicle stop at a predefined position (see chapter "Public Transport")

Still, in some cases, for example if you insert a tls with no yellow phase, collisions may occure within the simulation. Earlier versions of SUMO reported an error in such cases and quit. We decided to change this behaviour. By now, the simulation reports a warning in such cases and tries to solve the problem internally, either by changing the position of the last car or - if this does not work because the lane the accident happened at is full - by removing one of the cars and trying to reinsert it as soon as possible. You still may force the simulation to quit as soon an "accident" happens using the option --quit-on-accident.

6.6. Missing

--route-steps

--check-accidents

--too-slow-rtf

--no-duration-log

--no-internal-links

--time-to-teleport

Prev		Next
Chapter 5. Route Generation	Home	Chapter 7. Simulation-GUI