SUMO - Simulation of Urban MObility - User Documentation

Please remark that you may also find the applications "NETEDIT" and "GIANT" within the source distribution. Both are not supported, not working properly and will be not discussed, herein.

This document uses coloring to differ between different type of information. If you encounter something like this:

netconvert --visum=MyVisumNet.inp --output-file=MySUMONet.net.xml

you should know that this is a call on the command line. There may be also a '\' at the end of a line. This indicates that you have to continue typing without pressing return (ignoring both the '\' and the following newline). The following example means exactly the same as the one above:

netconvert --visum=MyVisumNet.inp \
   --output-file=MySUMONet.net.xml

Command line option names are normally coloured this way. Their values if optional <LIKE THIS>. XML-elements and attributes are shown are coloured like this. Their values if optional <LIKE THIS>. Complete examples of XML-Files are shown like the following:

<MyType>

   <MyElem myAttr1="0" myAttr2="0.0"/>
   <MyElem myAttr1="1" myAttr2="-500.0"/>

</MyType>

You may also find some notations from the EBNF; brackets '[' and ']' indicate that the enclosed information is optional. Brackets '<' and '>' indicate a type - insert your own value in here... All applications are shown like THIS. <SUMO_DIST> is the path you have saved your SUMO-package into.

This document is still under development and grows with the software. Due to this, you may find it together with the sources within the SUMO repository at sourceforge (http://sumo.sourceforge.net/). It should always describe the current version.

SUMO is a microscopic, space continuous and time discrete traffic simulation.

In traffic research four classes of models are distinguished according to the level of detail of the simulation. In macroscopic models traffic flow is the basic entity. Microscopic models simulate the movement of every single vehicle on the street, mostly assuming that the behaviour of the vehicle depends on both, the vehicle's physical abilities to move and the driver's controlling behaviour (see [Chowdhury, Santen, Schadschneider, 2000]). Within SUMO, the microscopic model developed by Stefan Krauß is used (see [Krauss1998_1], [Krauss1998_2]). Mesoscopic simulations are located at the boundary between microscopic and macroscopic ones. Herein, vehicle movement is mostly simulated using queue approaches and single vehicles are moved between such queues. Sub-microscopic models regard single vehicles like microscopic but extend them by dividing them into further substructures, which describe the engine's rotation speed in relation to the vehicle's speed or the driver's preferred gear switching actions, for instance. This allows more detailed computations compared to simple microscopic simulations. However, sub-microscopic models require large computation times. This restrains the size of the networks to be simulated.

Figure 3.1. The different simulation granularities; from left to right: macroscopic, microscopic, sub-microscopic (within the circle: mesoscopic)

Within a space-continuous simulation each vehicle has a certain position described by a floating-point number. In contrast, space-discrete simulations are a special kind of cellular automata. They use cells and vehicles driving on the simulated streets "jump" from one cell to another.

Figure 3.2. The difference between a space-continuous (top) and a space-discrete (bottom) simulation

Almost every simulation package uses an own model for vehicle movement. Almost all models are so-called "car-following-models": the behaviour of the driver is herein meant to be dependent on his distance to the vehicle in front of him and of this vehicle's speed. Although SUMO is meant to be a test bed for such vehicle models, only one is implemented by now, which was developed by Stefan Krauß. Other obstacles such as traffic lights are of course considered herein, too.

It seems obvious, that each driver is trying to use to shortest path through the network. But when all are trying to do this, some of the roads - mainly the arterial roads - would get congested and their benefit would sink. Solutions for this problem are known to traffic research as dynamic user assignment. For solving this, several approaches are available and SUMO uses the dynamic user assignment approach developed by Christian Gawron (see [Gawron1998_1]).

At first, you need the network the traffic to simulate takes place on. As SUMO is meant to work with large networks, we mainly concentrated our work on importing networks and the computation of further needed values. Due to this, no graphical editor for networks is available, yet. Beside information about a network's roads, information about traffic lights is needed.

Further, you need information about the traffic demand. While most traffic simulation use a statistical distribution which is laid over the network, each vehicle within SUMO knows its route. Within this approach, the route is a list of edges to pass. Although this approach is more realistic, it also induces a large amount of data needed to describe the vehicle movements. By now, routes are not compressed within SUMO and so may be several MB large. We will possibly change this in future.

Two basic design goals are approached: the software shall be fast and it shall be portable. Due to this, the very first versions were developed to be run from the command line only - no graphical interface was supplied at first and all parameter had to be inserted by hand. This should increase the execution speed by leaving off slow visualisation. Also, due to these goals, the software was split into several parts. Each of them has a certain purpose and must be run individually. This is something that makes SUMO different to other simulation packages where the dynamical user assignment is made within the simulation itself, not via an external application like here. This split allows an easier extension of each of the applications within the package because each is smaller than a monolithic application doing everything. Also, it also allows the usage of faster data structures, each adjusted to the current purpose, instead of using complicated and ballast-loaded ones. Still, this makes the usage of SUMO a little bit uncomfortable in comparison to other simulation packages. As there are still other things to do, we are not thinking of a redesign towards an integrated approach by now.

Within the nodes-files, normally having the extension ".nod.xml" (see Appendix "Naming Conventions"), every node is described in a single line which looks like this: <node id="<STRING>" x="<FLOAT>" y="<FLOAT>" [type="<TYPE>"]/> - the straight brackets ('[' and ']') indicate that the parameter is optional. Each of these attributes has a certain meaning and value range:

When writing your nodes-file, please do not forget to embed your node definitions into an opening and a closing "tag". A complete file should like the example below, which is the node file "cross3l.nod.xml" for the examples "<SUMO_DIST>/data/examples/netbuild/types/cross_usingtypes/" and "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" example.

<nodes> <!-- The opening tag -->

   <node id="0" x="0.0" y="0.0" type="traffic_light"/> <!-- def. of node "0" -->

   <node id="1" x="-500.0" y="0.0" type="priority"/> <!-- def. of node "1" -->
   <node id="2" x="+500.0" y="0.0" type="priority"/> <!-- def. of node "2" -->
   <node id="3" x="0.0" y="-500.0" type="priority"/> <!-- def. of node "3" -->
   <node id="4" x="0.0" y="+500.0" type="priority"/> <!-- def. of node "4" -->

   <node id="m1" x="-250.0" y="0.0" type="priority"/> <!-- def. of node "m1" -->
   <node id="m2" x="+250.0" y="0.0" type="priority"/> <!-- def. of node "m2" -->
   <node id="m3" x="0.0" y="-250.0" type="priority"/> <!-- def. of node "m3" -->
   <node id="m4" x="0.0" y="+250.0" type="priority"/> <!-- def. of node "m4" -->

</nodes> <!-- The closing tag -->

As you may notice, only the first node named "0", which is the node in the middle of the network, is a traffic light controlled junction. All other nodes are uncontrolled. You may also notice, that each of both ends of a street needs an according node. This is not really necessary as you may see soon, but it eases the understanding of the concept: every edge (street/road) is a connection between two nodes (junctions).

You should also know something about the coordinate system: the higher a node on the screen shall be (the nearer to the top of your monitor), the higher his y-value must be. The more to left it shall be, the higher his x-value.

Figure 4.2. Coordinate system used in SUMO

Since version 0.9.4 you can also give the x- and y-coordinates using geocoordinates. In this case, the coordinates will be interpreted as long/lat in degrees. Read more on this in "Converting from Geocoordinates".

Edges are described quite the same way as nodes, but posses other parameter. Within the edges file, each description of a single edge looks like this: <edge id="<STRING>" (fromnode="<NODE_ID>" tonode="<NODE_ID>" | xfrom="<FLOAT>" yfrom="<FLOAT>" xto="<FLOAT>" yto="<FLOAT>") [(type="<STRING>" | nolanes="<INT>" speed="<FLOAT>" priority="<FLOAT>" length="<FLOAT>")] [shape="<2D_POINT> [ <2D_POINT>]* <2D_POINT>"] [spread_type="center"] [function=( "source" | "sink" | "normal" ) ]/>.

What does it mean? Every one who knows how XML-files look like should have noticed brackets ('(' and ')') and pipes ('|') within the definition and these characters are not allowed within XML... What we wanted to show which parameter is optional. So for the definition of the origin and the destination node, you can either give their names using fromnode="<NODE_ID>" tonode="<NODE_ID>" or you give their positions using xfrom="<FLOAT>" yfrom="<FLOAT> xto="<FLOAT>" yto="<FLOAT>". In the second case, nodes will be build automatically at the given positions. Each edge is unidirectional and starts at the "from"-node and ends at the "to"-node. If a name of one of the nodes can not be dereferenced (because they have not been defined within the nodes file) an error is generated (see also the documentation on "--omit-corrupt-edges" in subchapter "Building the Network").

For each edge, some further attributes should be supplied, being the number of lanes the edge has, the maximum speed allowed on the edge, the length the edge has (in meters) and a priority value. These values - beside the length in fact - may either be given for each edge using according attributes or you can omit them by giving the edge a "type". In this case, you should also write a type-file (see subchapter "Types Descriptions"). A type with this name should of course be within the generated type-file, otherwise an error is reported. Even if you supply a type, you can still override the type's values by supplying any of the parameter nolanes, speed and priority. You may also leave the edge parameter completely unset. In this case, default-values will be used and the edge will have a single lane, a priority of 0 (zero) and the maximum allowed speed on this edge will be 13.9m/s being around 50km/h. The length of this edge will be computed as the distance between the starting and the end point.

As an edge may have a more complicated geometry, you may supply the edge's shape within the shape tag. If the length of the edge is not given otherwise, the distances of the shape elements will be summed. The information spread_type="center" forces NETCONVERT to spread lanes to both sides of the connection between the begin node and the end node or from the list of lines making up the shape. If not given, lanes are spread to right, as default. Using function you can define whether the edge is a "normal" edge, a "source", or a "sink" edge. The default is "normal", of course. This information is used for routing purposes (see "Using the Junction Turning Ratio - Router") and for vehicle emission (see "Vehicles Handling Revisited"). Briefly, vehicles may be inserted on normal and source edges (although the insertion procedure changes, see "Vehicles Handling Revisited") and may leave the network on normal and sink edges.

Let's list an edge's attributes again:

The priority plays a role during the computation of the way-giving rules of a node. Larger values for the priority of an edge allow vehicles using it to pass without waiting - if no traffic light is on the node. Also, the priority is responsible for determining how many of the street's lanes are used to get to the next edges (see also "Automatic Lane-2-Lane Connections").

Also the definitions of edges must be embedded into an opening and a closing tag and for the example "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" the whole edges-file looks like this ("cross3l.edg.xml"):

<edges>

   <edge id="1fi" fromnode="1" tonode="m1" priority="2" nolanes="2" speed="11.11"/>
   <edge id="1si" fromnode="m1" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="1o" fromnode="0" tonode="1" priority="1" nolanes="1" speed="11.11"/>

   <edge id="2fi" fromnode="2" tonode="m2" priority="2" nolanes="2" speed="11.11"/>
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="2o" fromnode="0" tonode="2" priority="1" nolanes="1" speed="11.11"/>

   <edge id="3fi" fromnode="3" tonode="m3" priority="2" nolanes="2" speed="11.11"/>
   <edge id="3si" fromnode="m3" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="3o" fromnode="0" tonode="3" priority="1" nolanes="1" speed="11.11"/>

   <edge id="4fi" fromnode="4" tonode="m4" priority="2" nolanes="2" speed="11.11"/>
   <edge id="4si" fromnode="m4" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="4o" fromnode="0" tonode="4" priority="1" nolanes="1" speed="11.11"/>

</edges>

Within this example, we have used explicit definitions of edges. An example for using types is described in the chapter "Types Descriptions".

	Caution
	There are some constraints about the streets' ids. They must not contain any of the following characters: '_' (underline - used for lane ids), '[' and ']' (used for enumerations), ' ' (space - used as list divider), '*' (star, used as wildcard), ':' (used as marker for internal lanes).

Recent changes:

4.2.2.1. Defining allowed Vehicle Types

Since version 0.9.5 you may allow/forbid explicite vehicle classes to use a lane. The information which vehicle classes are allowed on a lane may be specified within an edges descriptions file by embedding the list of lanes together with vehicle classes allowed/forbidden on them into these lanes' edge. Assume you want to allow only busses to use the leftmost lane of edge "2si" from the example above. Simply change this edge's definition into:

... previous definitions ...
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89">
      <lane id="2" allow="bus"/>
   <edge>
... further definitions ...

If you would like to disallow passenger cars and taxis, the following snipplet would do it:

... previous definitions ...
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89">
      <lane id="2" disallow="passenger;taxis"/>
   <edge>
... further definitions ...

The definition of a lane contains by now the following attributes:

• id: The enumeration id of the lane (0 is the rightmost lane, <NUMBER_LANES>-1 is the leftmost one)
  
• allow: The list of explicitely allowed vehicle classes
  
• disallow: The list of explicitely disallowed vehicle classes
  

Both the allowed and the disallowed attributes assume to get a list of vehicle class names devided by a ';'. See "Vehicle Classes" for further information about allowed vehicle classes and their usage.

	Caution
	This is a new feature. Its usage and the way it works will surely change in the future.

Examples: none yet

Recent changes:

• The possibility to define which vehicle classes are allowed on a lane was added in version 0.9.5
  

As mentioned, road types are meant to be used to ease the definition of edges. As described above, the description of an edge should include information about the number of lanes, the maximum speed allowed on this edge and the edge's priority. To avoid the explicit definition of each parameter for every edge, one can use road types, which encapsulate these parameter under a given name. The format of this definition is: <type id="<STRING>" nolanes="<INT>" speed="<FLOAT>" priority="<FLOAT>" [function=( "source" | "sink" | "normal" )]/>.

The attributes of a type are of course exactly the same as for edges themselves:

The information about the nodes the edge starts and ends at is not given within the types' descriptions. They can only be set within the edge's attributes. Here's an example on referencing types in edge definitions:

<edges>

   <edge id="1fi" fromnode="1" tonode="m1" type="b"/>
   <edge id="1si" fromnode="m1" tonode="0" type="a"/>
   <edge id="1o" fromnode="0" tonode="1" type="c"/>

   <edge id="2fi" fromnode="2" tonode="m2" type="b"/>
   <edge id="2si" fromnode="m2" tonode="0" type="a"/>
   <edge id="2o" fromnode="0" tonode="2" type="c"/>

   <edge id="3fi" fromnode="3" tonode="m3" type="b"/>
   <edge id="3si" fromnode="m3" tonode="0" type="a"/>
   <edge id="3o" fromnode="0" tonode="3" type="c"/>

   <edge id="4fi" fromnode="4" tonode="m4" type="b"/>
   <edge id="4si" fromnode="m4" tonode="0" type="a"/>
   <edge id="4o" fromnode="0" tonode="4" type="c"/>

</edges>

The according types file looks like this:

<types>

   <type id="a" priority="3" nolanes="3" speed="13.889"/>
   <type id="b" priority="2" nolanes="2" speed="11.111"/>
   <type id="c" priority="1" nolanes="1" speed="11.111"/>

</types>

As you can see, we have joined the edges into three classes "a", "b", and "c" and have generated a description for each of these classes. Doing this, the generated net is similar to the one generated using the settings described above (example "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" ).

Examples:

Recent changes:

If you have tried the version 0.7 you have possibly missed the possibility to specify the connections between the edges for yourself. This is now possible using a further file, the connections file. The connection file specifies which edges outgoing from a junction may be reached by a certain edge incoming into this junction and optionally also which lanes shall be used on both sides.

If you only want to describe which edges may be reached from a certain edge, this definition could look something like this: <connection from="<FROM_EDGE_ID>" to="<T0_EDGE_ID>"/>. This tells NETCONVERT not only that vehicles shall be allowed to drive from the edge named <FROM_EDGE_ID> to the edge named <TO_EDGE_ID>, but also prohibits all movements to other edges from <FROM_EDGE_ID>, unless they are specified within this file. Let's repeat the parameters:

When using this kind of input, NETCONVERT will compute which lanes shall be used if any of the connected edges has more than one lane. If you also want to override this computation and set the lanes by hand, use the following: <connection from="<FROM_EDGE_ID>" to="<T0_EDGE_ID>" lane="<INT_1>:<INT_2>"/>. Here, a connection from the edge's "<FROM_EDGE_ID>" lane with the number <INT_1> is build to the lane <INT_2> of the edge "<TO_EDGE_ID>". Lanes are counted from the right (outer) to the left (inner) side of the road beginning with 0. Again the parameter:

There are two examples within the distribution. Both use the nodes and edges descriptions from the example located in "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/". The junction in the center of this example looks like shown within the next figure. We will now call it the "unconstrained network" because all connections and turnarounds are computed using the default values.

Figure 4.3. Unconstrained Network

The example <SUMO_DIST>/data/examples/netbuild/connections/cross3l_edge2edge_conns/" shows what happens when one uses connections to limit the number of reachable edges. To do this we built a connections file where we say that the horizontal edges ("1si" and "2si") have only connections to the edges right to them and the edge in straight direction. The file looks like this:

<connections>

   <connection from="1si" to="3o"/>
   <connection from="1si" to="2o"/>

   <connection from="2si" to="4o"/>
   <connection from="2si" to="1o"/>

</connections>

As you may see in the next picture, the horizontal edges within the result network contain no left-moving connections.

Figure 4.4. Network with explicit edge-2-edge connections

In the second example located in <SUMO_DIST>/data/examples/netbuild/connections/cross3l_laneslane_conns/" we additionally describe which lanes shall be connected. The according connections file says that the connections going straight shall be start at the second lane of the incoming edges:

<connections>

   <connection from="1si" to="3o" lane="0:0"/>
   <connection from="1si" to="2o" lane="2:0"/>

   <connection from="2si" to="4o" lane="0:0"/>
   <connection from="2si" to="1o" lane="2:0"/>

</connections>

The built network looks like this:

Figure 4.5. Network with explicit lane-2-lane connections

	Warning
	Please do not use both types of connection declarations (those with an lane attribute and those without) for the same from-edge! The behaviour is not verified and tested for these settings.

Examples (compare both to <SUMO_DIST>/data/examples/netbuild/netbuild/cross_notypes/):

Recent Changes:

After you have generated the files you need being at least the edges and the nodes-files and optionally also a type and/or a connections file you should run NETCONVERT to build the network. The call should look like:

netconvert --xml-node-files=MyNodes.nod.xml --xml-edge-files=MyEdges.edg.xml \
   --output-file=MySUMONet.net.xml

if you only use edges and nodes. Types and connections may be given as:

netconvert --xml-node-files=MyNodes.nod.xml --xml-edge-files=MyEdges.edg.xml \
   --xml-connection-files=MyConnections.con.xml --xml-type-files=MyTypes.typ.xml \
   --output-file=MySUMONet.net.xml

Maybe your edge definitions are incomplete or buggy. If you still want to import your network, you can try passing "--omit-corrupt-edges" to NETCONVERT. In this case, edges which are not defined properly, are omitted, but NETCONVERT tries to build the network anyway. You may also flip the network around the horizontal axis. Use option "--flip-y" for this.

You may also use abbreviations for the option names. These abbreviations and options used when building SUMO-networks from own XML-descriptions are:

See also:

Examples:

Almost all networks within the <SUMO_DIST>/data/ - folder. Additionally some examples that cover the mentioned topics are:

Recent changes:

NETCONVERT is able to directly read binary NavTech's ArcView databases. To convert such databases, you need at least three files: a file with the extension ".dbf", one with the extension ".shp" and one with the extension ".shx". Additionally, having a projection file with the extension ".proj" is of benefit. Since version 0.9.2 we do not suply the possibility to use different names for the files, so all files should have the same name besides the extension. To build your network from an ArcView-database use the option "--arcview=<FILENAME_WITHOUT_EXTENSION>":

netconvert --arcview=MyArcViewDB --output-file=MySUMONet.net.xml

This call will force NETCONVERT to read the files "MyArcViewDB.dbf", "MyArcViewDB.shx", and "MyArcViewDB.shp" (and possibly "MyArcViewDB.proj" and to generate a network named "MySUMONet.net.xml". We have been asked which fields are read from ArcView-files. As said before, the reader was build to read ArcView-files containing road networks from NavTech. Due to this the following fields are used as default:

The problem is, that not all networks stored as ArcView-databases also use this naming scheme. During some further work with ArcView-networks, some further options got necessary which allow to name the fields the used database contains. The column the street name shall be read from may be specified using --arcview.street-id <STREET_NAME_COLUMN_NAME>. You can also name the columns the names of the edges' origin and destination nodes shall be read from using --arcview.from-id <START_NODE_ID_COLUMN_NAME> and --arcview.to-id <END_NODE_ID_COLUMN_NAME>. If the no information about the starting/ending nodes is given and your database does not contain the columns "REF_IN_ID" and "NREF_IN_ID", nodes will be placed into the network at the positions the streets end.

Since version 0.9.2 we also allow to override the rather "fuzzy" information about an edge's attributes from NavTech using own fields:

This idea came from John Michael Calandrino.

Some databases do not contain explicite information about the edges' attributes (number of lanes, priority, allowed speed) at all. Since version 0.9.4 you can use types as described in "Types Descriptions" to describe your edges' attributes. You have to name the column to retrieve the information about a street's type from using --arcview.type-id <TYPE_ID_COLUMN_NAME>. Of course, you have then to supply a type-file using --xml-type-files <TYPES_FILE> (or --types or -t ). If something fails with the types or the explicite values, you can catch it using --arcview.use-defaults-on-failure. Besides this, you can specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

ArcView-networks are (mostly?) encoded using geocoordinates which have to be converted to the cartesian coordinates system used by SUMO. Our current implementation is not yet fully developed, it works for the most cases, but you should not be surprised if it fails with a certain network. Contact us in this case, please. To describe how to convert the coordinates, you should know in which UTM-zone your network is located. Pass this to NETCONVERT using --arcview.utm <ORIGINAL_UTM_ZONE>. If the conversion can not be initialised, you may additionally use --arcview.guess-projection to let NETCONVERT guess the conversion by him own.

Specific options:

See also:

Examples: none yet

Recent changes:

To import Artemis-network descriptions, start NETCONVERT with the following parameter:

netconvert --artemis=<PATH> --output-file=MySUMOFile.net.xml

This should build the network "MySUMOFile.net.xml" which contains the build network that may be used by SUMO. <PATH> is the path to (the name of) the folder that contains the files that make up the description of an ARTEMIS-simulation.

Imported information:

We have to import the HVdests to know which sources and sinks we have to build.

Known problems:

Artemis simulation description also holds definitions of the traffic flows to use. They are not parsed by the NETCONVERT - module, but may be passed to ROUTER to gain the according routes.

Specific options:

Known problems:

	Caution
	The import of ARTEMIS is not longer supplied and seems to be buggy.

Examples: none yet (we do not own a network we could give away for legal reasons)

FastLane, developed at the ZAIK, is a mesoscopic traffic simulation. The network description consists of a file containing edges and a second one containing nodes. Due to this, you need to supply two values as input parameter and the call looks like this:

netconvert --cell-nodes=<CELL_NODE_FILE> --cell-edges=<CELL_EDGE_FILE> \
   --output-file=MySUMOFile.net.xml

Of course, both files must belong to the same network. As FastLane is a mesoscopic simulation, sometime the number of an edge's lanes is not given. Instead, FastLane uses the capacity. In such cases, the number of lanes is computed roughly using the edge's capacity. We assume a linear dependency for this, currently, although this may not be the best solution. So, the number of lanes is computed as EDGE_CAPACITY/NORM. You may change the norm from its default of 20000 using the option --capacity-norm.

You can also supply a type-file using --xml-type-files <TYPES_FILE> (or --types or -t, see "Types Descriptions" ) and specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

Specific options:

See also:

Examples: none yet (we do not own a network we could give away for legal reasons)

Although Vissim is a microscopic simulation as SUMO is, it follows a completely different concept of modelling traffic. Due to this, the import is quite clumsy and may not work with all networks. Also, we have to insert additional edges into our networks to simulate the Vissim-parking places, originally being nodes, which we do not have. An usage example could be this one:

netconvert --vissim=<VISSIM_FILE> --output-file=MySUMOFile.net.xml

Vissim-networks do possibly not contain explicit definitions of an edge's speed. We have to propagate once set velocities, but even then some edges' speeds may not be defined. The option "--vissim-default-speed" may change the default speed used in the case an edge's speed is not defined. The default value for this parameter is 13.89m/s, being around 50km/h. The second parameter "--vissim-speed-norm" describes the factor to multiply a described flows maximum velocity to gain the velocity to use. The default value is 1.

Furthermore, as we have to use geometrical heuristics, a further factor steers the process of converting Vissim-networks: simply spoken, "--vissim-offset" holds the information how near two nodes must be (in meters) to be joined.

During import, different actions must be done which may yield in some loss of data and may be watched in part by setting the verbose option. The additional warnings the import of Vissim-networks generates will be described in a further document.

Specific options:

Known problems:

Examples: none yet (we do not own a network we could give away for legal reasons)

Visum is a macroscopic simulation developed by ptv. NETCONVERT is capable to read VISUM-networks written as .net files. An usage import call could be this one:

netconvert --visum=<VISUM_FILE> --output-file=MySUMOFile.net.xml

As the network description may not contain any information about the number of lanes, we have to generate it from the street's flow. The computation is done by dividing the flow through a fix value, 2000 by default. This yields in a realistic network but fails on 'feeder roads' where vehicles are emitted.

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

Not all parts of the Visum-Format are read; below you'll find a table which contains the information which Visum-tables are imported.

Specific options:

See also:

Examples: none yet (we do not own a network we could give away for legal reasons)

Recent changes:

You can convert both the splitted and the unsplitted version of files generated by Elmar from NavTech-files. There seems to be no difference between the results in the networks' topologies, but the names of junctions and roads change. The option --elmar loads the splitted definitions, --elmar2 the unsplitted. Both options await the prefix as generated by Elmar's converter, an optional path is allowed. Example:

netconvert --elmar=berlin_ --output-file=MySUMOFile.net.xml

Imports the descriptions of nodes from "berlin_nodes.txt" and the edges from "berlin_links.txt".

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

Specific options:

See also:

Examples: none yet (we do not own a network we could give away for legal reasons)

This import function is in a rather experimental state. We need someone who owns a network she/he knows and who could give us an advice whether the import work as expected. You still may try it out using the option --tiger=<FILE_PREFIX>.

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

See also:

Examples: none yet

We have mentioned, that edge parameter may be omitted and defaults will be used in this case. You have the possibility to define these defaults using the following options:

These options may be used while importing the following formats:

Examples: none yet

Normally, turnarounds are added as a possible edge continuations and play an important role during network building (see [Krajzewicz_et_al2005_2]). Still, one may want not to add them. In this cases, it is possible to disallow their appending using option "--no-turnarounds".

Specific option:

This options may be used while importing the following formats:

Recent changes:

Though you can define a certain priority value for edges (see "Edges Descriptions") which is used while computing how many and which lanes are used which of the connected roads, this value is not given for most of the imported road network formats. Setting a priority value for each of the roads is still very time consuming. Using the option --use-laneno-as-priority forces NETCONVERT to use the number of a street's lanes as this street's priority. We strongly recommend to enable this option when importing large networks.

Specific option:

This options may be used in conjunction with all import formats.

Recent changes:

In most input networks one may find nodes where one street comes in and one with the same attributes goes out or where two parallel edges come in and two (with the same attributes) come out. Such nodes have mostly no meaning (maybe besides the additional possibility to make a U-turn) and may be removed. The removal of such nodes increases the simulation speed due to a smaller number of edges to process during each time step. To remove such nodes and join the incoming and outgoing edges use "--remove-geometry". The removal of nodes preserves the geometry of edges by ading a further geometry point at the removed node's position.

Specific option:

This options may be used in conjunction with all import formats.

Recent changes:

Some people do not like to use speed definitions in m/s. If you want to define the speeds allowed on your edges in km/h instead, you should pass the following option to NETCONVERT:

This option may be used while importing the following formats:

Examples:

Recent changes:

Some of the supported network formats - Visum, Vissim and Artemis, supply information about the logic of the traffic lights, other do not. Due to this, we have to compute the traffic lights by our own. Doing this, we do not only have to compute the plans, but of course also, on which junction traffic lights are positioned. There are several options steering this procedure. At first, you have to tell NETCONVERT/NETGEN that you wish him to guess positions of traffic lights. This is done using the "--guess-tls"-option. Then, you have the possibility to describe the junctions at which you think a tls shall be placed using description of incoming and outgoing edges: "--tls-guess.no-incoming-min", "--tls-guess.no-incoming-max", "--tls-guess.no-outgoing-min" and "--tls-guess.no-outgoing-max" constraint the building of a tls by the number of the lanes incoming/outgoing edges have. All these four options require an int as parameter. Furthermore, you may constraint the junctions by giving the minimum/maximum of allowed speed on edges that participate: "--tls-guess.min-incoming-speed", "--tls-guess.max-incoming-speed", "--tls-guess.min-outgoing-speed", and "--tls-guess.max-outgoing-speed".

	Caution
	No, we do not have a validated set of these option's settings, yet.

You may also set junctions as tls-controlled using "--explicite-tls" or as uncontrolled using "--explicite-no-tls". Both options assume to get a list of node names divided by ';' as parameter. The behaviour when a node is in both lists is undefined.

If you want to know where traffic lights have been inserted and your network is too large to evaluate this by hand, you can force NETCONVERT to write a list of POIs where each POI is placed on a tls-controlled junction. This allows you to tae a look at all the positions tls have been inserted at. The option for doing this is --tls-poi-output <FILENAME> where <FILENAME> is the filename to write the POIs into.

Normally, only one traffic lights logic (phases definition) is computed per a traffic lights controlled junction, but the algorithm we use is able to compute several logics. To force the computation of all possible logics, use "--all-logics". Remind, that all logics will be written to the network file and that we have no tools for further procesing of these logics.

During the computation of tls-logics among other information we have to guess the duration of the phases. The options "--traffic-light-green" and "--traffic-light-yellow" allow you to give the durations of green and yellow lights. Both options assume the duration in s as an int as parameter. The duration of having red is dependant to the number of other phases and their green and yellow phase durations. The green phase length has a default of 20s, yellow lights are - if no value is set for this option - computed using the "--min-decel" - value described below.

One has to remind one thing: dead times are necessary to avoid collisions of vehicles which do not manage to break as they are too near to the traffic light when it switches to red. This time may be computed, and is, but depends on the maximum deceleration possibility of the vehicles used. As this parameter is not known to the network builder at all - the vehicle types are supported to the simulation only - the option "--min-decel" (or -D for short) is used to set the minimum deceleration of vehicles. The default is 3.0 in m/s^2.

There is no possibility to compute or estimate green light districts, yet. You have only the options to shift the computed phases by half of their duration or by a quarter of their duration. The options for this are: "--tl-logics.half-offset" and "--tl-logics.quarter-offset". Both options assume to get a list of node names divided by ';' as parameter. The behaviour when a node is in both lists or if the node is not meant to be controlled by a tls is undefined.

Specific options:

These options may be used while importing the following formats:

Examples: none yet

Most of the imported network descriptions do not have information about highway on- and off-ramps. You can force NETCONVERT to guess where on- and off-ramps shall be build. To enable this, use the option "--guess-ramps". The algorithm assumes that an on-ramp shall be build on highway junctions with one incoming and one outgoing highway edge and one incoming minor edge and that an off-ramp shall be build on highway junctions with one incoming and one outgoing highway edge and one outgoing minor edge. You can constrain what a highway is by giving its minimum speed of this edge using "--ramp-guess.min-highway-speed" and what a minor edge is by giving its maximum speed using "--ramp-guess.max-ramp-speed". Both options assume a float parameter being the speed. Furthermore, "--ramp-guess.ramp-length" tells NETCONVERT how long the added ramp shall be in meters.

	Note
	Normally, we keep --ramp-guess.ramp-length unset and let the geometry computation do the rest.

Specific options:

These options may be used in conjunction with all import formats.

Examples: none yet

Most professional networks are not stored using cartesian, but geo-coordinates. Since version 0.9.4 NETCONVERT is able to deal with such positions. NETCONVERT uses herefor the projection library "PROJ.4". This is important for you as a user, because you may have to describe the original projection of your file and when doing this, you have to describe it using the options offered by PROJ.4. In order to enable the reprojection use the option --use-projection. You can then add parameter for the projection using --proj <STRING>. The default for the projection is "+proj=utm +zone=33 +ellps=bessel +units=m". That means, that NETCONVERT assumes the network is a part of the UTM zone 33 and is described using the Bessel ellipsoid. Please remark, that when giving own description, you should embed it into "" for passing all the arguments to PROJ.4.

Specific options:

These options may be used in conjunction with the following import formats:

	Caution
	This is a new feature. Its usage and the way it works will surely change in the future.

Examples: none yet

If you already know SUMO or if you have taken a look at some of the examples you may have noticed that vehicles "jump" over a junction instead of driving over them. This behaviour was quite appropriate for simulating large scenarios as in these cases the simulation error could be neglected (at least we have neglected it). Since version 0.9.5 SUMO is capable to simulate traffic over the junctions in a way you know it from reality. Because inserting inner lanes into a network dramatically increases the network's size, junction-internal lanes are not build by default. You can allow their building using the option --add-internal-links (or -I for short).

	Note
	Please note that you also have to enable the usage of internal lanes within the simulation.

Specific Options:

Examples:

Meanwhile all of the examples included in the distribution are build with this option set.

Recent changes:

NETCONVERT offers you some possibillities to constrain the read edges what is quite needful if one has a large street network but only wants to simulate a part of it or only the major roads. The first possibility to constrain the input is to name all the edges you want to keep. You can either do this on the command line/within your configuration directly using --keep-edges <EDGE_ID>[;<EDGE_ID>]+ where each <EDGE_ID> represents the id of an edge you want to keep or you can save this list into a file where each id is stored in a seperate line and then let NETCONVERT read this file using --keep-edges.input-file <FILENAME>. In the case you are joining edges using --remove-geometry (see "Removing Geometry Nodes"), you may also be interested in the option --keep-edges.postload which forces NETCONVERT to join the edges first and remove the unwished afterwards.

It is also possible to constrain the imported edges by giving a minimum velocity that is allowed on an edge in order to include this edge into the generated network. Use --edges-min-speed <MIN_SPEED> for this where <MIN_SPEED> is the minimum velocity an edge must allow in order to be included in the output in m/s.

Specific options:

Examples: none yet

Recent changes:

NETCONVERT and NETGEN allow to generate additional output files beside writing the network file. We will present the possibilities in the following subchapters.

edge1<TAB>edge1:10<TAB>edge2:20<TAB>edge3:30

edge<TAB>edge:100

You are able to describe how many junctions in x- and in y-direction you want to be build and how far from each other they should be. The parameter for the number of junctions are --grid-x-number and --grid-y-number, the ones for the distance between the junctions --grid-x-length and --grid-y-length. If you want to build networks which have the same values for both axes, use --grid-number and --grid-length. The lengths are given in meters.

An example usage for building could be:

Figure 4.6. netgen --grid-net --grid-number=10 --grid-length=400 --output-file=MySUMOFile.net.xml

Another one:

Figure 4.7. netgen --grid-net --grid-x-number=20 --grid-y-number=5 --grid-y-length=40 --grid-x-length=200 --output-file=MySUMOFile.net.xml

Spider-net networks are defined by the number of axes dividing them (parameter --spider-arm-number or --arms), the number of the circles they are made of (--spider-circle-number or --circles) and the distance between the circles (--spider-space-rad or --radius).

	Caution
	As the number of edges within the middle of the spider net may be quite large, it is often not possible to build a traffic light junction here. Due to this, this junction is always a right-of-way-junction.

Two examples of usage:

Figure 4.8. netgen --spider-net --spider-arm-number=10 --spider-circle-number=10 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

and:

Figure 4.9. netgen --spider-net --spider-arm-number=4 --spider-circle-number=3 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

The random network generator does just what his name says, it builds random networks... Several settings may be changed:

An example:

Figure 4.10. netgen --random-net -o MySUMOFile.net.xml --rand-iterations=200 --abs-rand

There are three possibilities to describe own routes. The most trivial one is to do this by hand. The first one id the usage of trip definitions, the second one the usage of flow descriptions. Trip definitions describe the movement of a single vehicle giving the departure time, and both the origin and the destination edges via their id. Flow descriptions use these values too, but instead of describing only one vehicle, the description is used for a defined number of vehicles to be emitted within a described interval. Due to this, instead of the departure time, the period's begin and end times must be supplied and the number of vehicles to emit within this interval.

Figure 5.1. Building routes from trips

We will describe both data types less briefly, now.

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>
</routes>

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>

   <vehicle id="0" type="type1" depart="0" color="1,0,0">
      <route>beg middle end rend</route>
   </vehicle>

</routes>

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>

   <route id="route0" multi_ref="x" color="1,1,0">beg middle end rend</route>

   <vehicle id="0" type="type1" route="route0" depart="0" color="1,0,0"/>
   <vehicle id="1" type="type1" route="route0" depart="0" color="0,1,0"/>

</routes>

duarouter --trip-defs=<TRIP_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

<flow id="0" from="edge0" to="edge1" begin="0" end="3600" no="100"/>

<interval begin="0" end="3600">
   <flow id="0" from="edge0" to="edge1" no="100"/>
</interval>

duarouter --flow-defs=<FLOW_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

duarouter --flow-defs=<FLOW_DEFS> --trip-defs=<TRIP_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

Random routes are the easiest, but also the most inaccurate way to feed your network with vehicle movements. Using the following call ro DUAROUTER:

duarouter --net=<SUMO_NET> -R <FLOAT> --output-file=MySUMORoutes.rou.xml \
   -b <UINT> -e <UINT>

or the same for the JTRROUTER:

jtrrouter --net=<SUMO_NET> -R <FLOAT> --output-file=MySUMORoutes.rou.xml \
   -b <UINT> -e <UINT>

you will generate random routes for the time interval given by -b(egin) and -e(nd). In each time step as many vehicles will be emitted into the network as given by the value of -R (--random-per-second). You can also supply values smaller than one. In this case, a single vehicle will be emitted each 1/<-R> step. Example: -R 0.25 generates a route description, which, when loaded, forces the simulation to emit a single vehicle each fourth time step. It is also possible to use this parameter in combination with other route definitions, for example supplying some fix routes and additionally generate random routes.

Random routes are not the best way to generate routes. Take a look at the network displayed below. This network has two rural and many minor roads. Random routes are by now spread all over the network and each road is chosen to be the starting or the ending without respecting his function. Due to this, the network is filled over with cars, coming from and approaching directions, the normal traffic is not taking - the normal traffic would concentrate on rural roads.

Figure 5.2. A network where the usage of random routes causes an improper behaviour due to the mixture of rural and minor roads

There is also another problem with random routes: By definition, in 50% of the cases, the route starts in the opposite direction of the destination - on the wrong side of the road. This yields in a large amount of vehicles that want to turn back using the first possibility. This is of course also not common in the real world, especially not in areas as the one shown before. To avoid this, we remove the first and the last edge from the route per default when generating random routes.

Options:

The JTRROUTER is a routing applications which uses flows and turning percentages at junctions as input. The following parameter must be supplied: the network to route the vehicles through, the description of the turning ratios for the junctions (defaults may be used for this, too), and the descriptions of the flows.

A call may look like this:

jtrrouter --flow-defs=<FLOW_DEFS> --turns=<TURN_DEFINITIONS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

The definitions of the flow look like the ones for the DUAROUTER with just a single difference: as it is not known where the vehicle will leave the network as the route it uses is randomly computed, the destination parameter has no meaning for jtr-routing and so may be left off. A vehicle leaves the network as soon as it comes to a sink edge. As not all networks have sink edges set, one can support a list of edges to be declared as sinks using --sinks <EDGE_ID>[;<EDGE_ID>]*.

To describe the turn definitions, one has to build a further file. Within this file, for each interval and each edge the list of percentages to use a certain follower is to be given. An example:

<turn-defs>
   <interval begin="0" end="3600">
      <fromedge id="myEdge0">
         <toedge id="myEdge1" probability="0.2"/>
         <toedge id="myEdge2" probability="0.7"/>
         <toedge id="myEdge3" probability="0.1"/>
      </fromedge>

      ... any other edges ...

   </interval>

   ... some further intervals ...

</turn-defs>

The snippet defines that vehicles coming at the end of edge "myEdge0" within the time interval between 0s and 3600s will choose the edge "myEdge1" with a probability of 20%, "myEdge2" with a probability of 70% and "myEdge3" with a probability of 10%. The specification of such information is of course quite extensive and so the JTRROUTER is also able to read the turning ratios from a cvs file. The same information as above may be coded the following way:

begin;end;from;to;split
0;3600;myEdge0;myEdge1;0.2
0;3600;myEdge0;myEdge2;0.7
0;3600;myEdge0;myEdge3;0.1

	Caution
	Do not forget to give the order of the attributes in the first line of the file.

Another possibility to save time on preparing the description is to use default values. The parameter --turn-defaults (-T) <TURN_DEFAULTS> can be used to describe the default ratios that will be used for all junctions for all time steps. <TURN_DEFAULTS> is a list of doubles, separated by a ';'. To achieve the same behaviour as in the example above, use --turn-defaults=20;70;10. The values will be applied to an edge's following edges beginning at the right edge (20%) and ending at the leftmost edge (10%). As the number of possible followers changes for different edges, the values are resampled for edges which number of following edges differs from the number of given turning probability defaults. Given --turn-defaults=20;70;10 a vehicle using an edge that has two followers would use the follower to the right with 55% probability, the one to the left with 45%.

As theoretically a route may get infinitely long when a vehicle is forced to take always the same direction, it is possible to limit the route's size using max-edges-factor. This factor, multiplied with the number of the used network's edges is the maximum number of edges a route may have. With the default of 2.0, a route may contain twice as many edges as the network has. Any route longer than this size will be marked as invalid. We assume that for each network this number has to be chosen again.

The following options are accepted by JTRROUTER:

Recent changes:

Examples:

Several examples may be found in <SUMO_DIST>/data/examples/jtrrouter/.

OD2TRIPS computes trips tables from O/D (origin/destination) matrices. OD2TRIPS assumes the matrix/matrices to be coded as amounts of vehicles that drive from one district to another within a certain time period. Because the generated trips must start and end at edges, OD2TRIPS requires a mapping of districts to edges. During conversion of VISUM networks - the base of the OD2TRIPS development - districts stored in the VISUM input file are parsed and stored within the outputted SUMO network file. If you do not use VISUM as input, you must build a districts file by your own. The format is given in "Describing the Districts", one of the next subchapters. You have to pass the file containing the district definitions to OD2TRIPS using the --net-file (--net or -n for short) option.

Because OD2TRIPS was used only to import data stored in VISUM/VISION formats, it assumes O/D to be stored in one of the VISUM formats. Not all VISUM formats are supported, by now only two, namely the "VMR" and the "OR" format. If you do not own matrices stored in these formats, you still have three possibilities: a) convert them into one of the supported formats, b) write your own reader for OD2TRIPS, or c) convert them into flow definitions and then give them to DUAROUTER (see Chapter "Using Flow Definitions"). Both supported formats are described in "Describing the Matrix Cells", one of the next subchapters. You may either give a list of matrices to OD2TRIPS using the --od-files (--od or -d for short) option followed by the list of files separated using a ';', or - when importing a Vissim simulation - using --vissim <VISSIM_SIMULATION_FILE> to read the matrices referred in this network file.

OD2TRIPS reads all matrices and generates trip definitions as those described in "Using Trip Definitions". The generated trip definitions are numbered starting at zero. As usual, they are written to the output file named using the --output-file option (--output or -o for short). OD2TRIPS colors the trip definitions. To remove this feature, use --no-color. You can specify a vehicle type to be added to the trip definitions using --vtype followed by the type name. Please remark that vehicles will have no type unless not given in the O/D-matrices or defined using this option. This option overrides type names given in the O/D-matrices. The type itself will not be generated. You can also add a prefix to the generated trip definition names using --prefix. Vehicles will be generated for the time period between --begin (-b) and --end (-e), having 0 and 86400 as default values, respectively. The meaning is the simulation step in seconds, as usual.

Because each O/D-matrix cell describes the amount of vehicles to emit within a certain time period, OD2TRIPS has to compute the vehicle's explicite departure times. Normally, this is done by using a random time within the time interval the O/D-matrix cell is defined for. It still is possible to emit a cell's vehicles with an uniform time between their emissions. Use the option --spread.uniform to enable this.

You can scale the amounts stored in the O/D-matrices using the --scale option which assumes a float as parameter. All read flows will be multiplied with this values, the default is 1. When importing O/D-matrices that cover a whole day, you maybe want to apply a curve which resembles the spread of the trip begins found in reality. Please read the subchapter "Splitting large matrices" on this.

Figure 5.3. Building trips from the OD-matrix

Specific options:

Examples: None yet.

Recent changes:

<districts>
   <district id="<DISTRICT_ID>">
      <dsource id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further source edges ...

      <dsink id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further destination edges ...
   </district>

   ... further districts ...

</districts>

$VMR
* vehicle type
4
* From-Time  To-Time
7.00 8.00
* Factor
1.00
*
* some
* additional
* comments
* District number
3
* names:
         1          2          3
*
* District 1 Sum = 6
         1          2          3
* District 1 Sum = 15
         4          5          6
* District 1 Sum = 24
         7          8          9 

$OR;D2
* From-Time  To-Time
7.00 8.00
* Factor
1.00
* some
* additional
* comments
         1          1       1.00
         1          2       2.00
         1          3       3.00
         2          1       4.00
         2          2       5.00
         2          3       6.00
         3          1       7.00
         3          2       8.00
         3          3       9.00

Although originally ARTEMIS-routes are stored within an OD-matrix, the import within SUMO is done using the DUAROUTER program.

This is basically done this way:

duarouter --artemis=<ARTEMIS_FOLDER> --net=<SUMO_NET> \
  --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

Remind that you have to specify the begin and the end of the simulation. This is quite inconsequent, as our mechanisms would allow import of repeatable routes, too. This is just not yet implemented.

Known problems:

One of the main concepts of FastLane is the Dynamic User Assignment by Christian Gawron. As this mechanism is based on single vehicle routes, those are given for a FastLane simulation. The router module has only to convert routes from the FastLane- into the SUMO-representation. Do this using the following command:

duarouter --cell=<CELL_FILE_NAME(NO_EXTENSION)> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

If you are familiar with FastLane, you may have noticed that you have only to supply one file name while FastLane uses two files to describe the routes: one "*.driver" and one "*.rinfo" file. As both files have the same name and only the extension differs, you have to give the name without the extension. So if your files have the names "foo.driver" and "foo.rinfo", write --cell=foo.

FastLanes stores routes within a very large file what makes the process quite slow. If you want to speed it up for the future, you can tell SUMO-ROUTER to save some temporary files using --save-cell-rindex. A further file named "<CELL_FILE_NAME>.rindex" will be generated. It speeds up the processing by a factor of ten or so.

As FastLane is portable, you may encounter files generated on a Windows-machine. Those files give some strange warnings, something that should not happen if you supply the right net. To avoid them, use the --intel-cell switch to tell DUAROUTER it has to turn the byte order.

You can also decide whether the best, not the last route a driver took shall be used: set the switch --no-last-cell for this.

See "Using OD2TRIPS" for information about how to import O/D-matrices in ptv format.

"dua-iterate.pl" helps you to perform the computation of a dynamic user assignment. The script needs at least two parameter: the path to the folder where you have located your SUMO-binaries in and the number of iteration steps to perform. When started with these to options, the script computes the given number of dua-steps. As input two files have to be located in the same folder as the script: a SUMO-network named "net.net.xml" and a set of trip definitions named "trips.trips.xml". if you want to start with another routes definition, you have to change this within the script's source code.

Within each iteration step, the script generates a configuration file for the DUAROUTER and starts DUAROUTER with this configuration file. Then, a configuration file for SUMO is built and SUMO ist started. Both configuration files are competely defined within the script itself. As default, for each time step, SUMO will generate three dump files with edge-dumps aggregated over 150, 300, and 900s, an emissions and a trip information output. The names of these outputs are numbered over the iteration steps. If you want to change the outputs, you also have to take a look into the script, but you should not disable the edge-based dump for aggregation over 900s, because this is read by the DUAROUTER in the next iteration steps in order to compute the DUA.

When started with a third parameter, the second parameter given will be interpreted as the start iteration step and the third as the end iteration step.

This useful script is located in <SUMO_DIST>/tools/dua_tools/.

Synopsis:

./dua-iterate.pl <PATH_TO_SUMO_BINARIES> [[<BEGIN_ITERATION_STEP>]] <END_ITERATION_STEP>

The idea behind the DFROUTER assumes that a network is completely covered by detectors, meaning that all off- and on-ramps have an induction loop placed on them. Such an information whether an induction loop is a pure source or sink or whether it is placed between such is but not given initially. It must be computed. To do this, the DFROUTER needs the underlying network as well as a list of detector definitions where each describes the position of an induction loop. The network, being a previously build SUMO-network, is supplied to the DFROUTER as usually using the ( --net-file | --net | -n ) <SUMO_NET_FILE> - option, the list of induction loops using --detector-files (or --detectors or -d for short) <DETECTOR_FILE>[;<DETECTOR_FILE>]+. A detector file should look as following:

<detectors>
   <detector_definition id="<DETECTOR_ID>" lane="<LANE_ID>" pos="<POS>"/>
... further detectors ...
</detectors>

This means that each detector is initially described using its id, a lane it is placed on, and a position on the lane. To be exact:

Given a network and the list of detectors, DFROUTER assigns types to detectors (TBD: add a reference) and saves the so extended list into a file if the option --detectors-output <DETECTOR_OUTPUT_FILE> is given. This list looks like the input described above except that an aditional attribute is given for each detector, "type", which may have one of the following values: "source", "sink", "between", and "discarded". You can also generate a list of points of interests (POIs) which can be read by GUISIM where each POI represents a detector and is colored by the detector type: green for source detectors, red for sink detectors, blue for in-between detectors, and black for discarded detectors. To force DFROUTER to do this, use --detectors-poi-output <POI_FILENAME>.

When wished, if for example other parameters chage, the extended <DETECTOR_OUTPUT_FILE> can be fed back again into DFROUTER instead of the previous <DETECTOR_FILE>. In this case the detector types do not have to be computed again. To force DFROUTER to recompute the types though, use --revalidate-detectors.

Specific options:

Now that we do know where vehicles enter and where they leave the network, we may compute routes for each of the pairs. The DFROUTER is told to build and save routes using --routes-output <ROUTE_OUTPUT_FILE> where <ROUTE_OUTPUT_FILE> is the name of the file the computed routes shall be written to. The generated file only contains routes, no vehicle type definitions and no vehicles. In later runs, you can omit the routes computation by supplying previously generated routes using --routes-input (or -r) <ROUTE_FILE>. Again, as during the computation of the detector types, you can force DFROUTER to recompute the routes even if suppling them using --revalidate-routes.

Normally, only routes starting at source detectors and ending at sink detectors are computed. Using the option --routes-for-all you can force DFROUTER to also build routes that start at in-between detectors. The option --all-end-follower will make the routes not end at the edge the source detector is placed on, but on all edges that follow this edge (TBD: recheck this). --keep-unfound-ends will also keep those routes where a sink detector could not be found for what may be the case if the network is not completely covered with induction loops.

Specific options:

The next step is to use the computed routes and flow amounts from the real-world detectors to compute flows across the modelled network. The flows are given to DFROUTER using --detector-flow-files (or --detflows, -f for short) <DETECTOR_FLOWS>[;<DETECTOR_FLOWS>]+. They are assumed to be stored in CSV-format using ';' as dividing character. The file should look as following:

Detector;Time;qPKW;qLKW;vPKW;vLKW
myDet1;0;10;2;100;80
... further entries ...

This means the first time has to name the entries (columns). Their order is not of importance, but at least the following columns must be included:

These are not quite the values to be found in induction loop output. We had to constrain the <DETECTOR_FLOWS> files this way because DFROUTER is meant to read very many of such definitions and to do this as fast as possible. Because even this scheme was too slow for some purposes, flow amounts can also be marked as more valid using the option --fast-flows. If set, DFROUTER assumes that there is no header line and that the values are separated using spaces. In this case, the columns must be in the order time, detector name, qPKW, qLKW, vPKW, and vLKW.

Because in some cases one reads detector flow definitions starting at a certain time but wants his simulation begin at another, it is possible to add a time offset using --time-offset <TIME_OFFSET> which is subtracted from the read times. <TIME_OFFSET> is meant to be an int representing seconds.

(TBD: verify: how long is the time period, are speeds given in m/s, is qPKW/qLKW right, does qPKW/qLKW describe the amount within this period or within one hour)

Specific options:

If flow definitions were supplied, we can let the DFROUTER save the computed vehicles together with their routes. Because vehicles will be emitted at the source detectors which are placed at certain positions of the networks' lanes, emitters (see "Emitter") are used to insert those vehicles into the network. You can force the DFROUTER to generate such emitters using --emitters-output <EMITTER_OUTPUT_FILE>. This file will contain emitter declarations for each of the source detectors. If no value is given, emitters will not be written. Accompanying, there will be emitter definitions written named "emitter_<DETECTOR_ID>.def.xml" where <DETECTOR_ID> is the id of the according source detector. These definitions are called within the <EMITTER_OUTPUT_FILE> and contain vehicles which depart the emitter in accordance to the read flows and have routes computed using the flows.

As some approaches use a speed limit to avoid open-end boundary problems (TBD add a reference), the DFROUTER can generate a list of speed triggers (see "Variable Speed Signs (VSS)") placed on the positions of sink detectors. The name to save the declaration of these speed triggers into is given using the option --speed-trigger-output <VSS_OUTPUT_FILE>. The according speed trigger definitions will be written into files named "vss_<DETECTOR_ID>.def.xml" where <DETECTOR_ID> is the name of the according sink detector.

In order not to end vehicle routes on off-ramps, it is possible to place rerouters (see "Rerouter") at the positions of the sink detectors, too. Giving the option --end-reroute-output <REROUTER_OUTPUT_FILE> will generate a list of rerouter declarations. Please remark that in this case, no rerouter definitions are written, because the DFROUTER has no further information about possible routes beyond the area covered by the detectors.

It's quite nice to have the possibility to check whether the simulation does what one wants. To validate whether the same flows are found within the simulation as within the reality, the option --validation-output <SUMO_DETECTORS_OUTPUT> may be helpful. It generates a list of detector definitions (E1/induct loops, see "E1-Detectors (Induct Loops)") placed at the positions of sink and in-between detectors. Their output will be saved into files named "validation_det_<DETECTOR_ID>.xml" and should be easily comparable to the detector flows previously fed to the router. The option --validation-output.add-sources will let DFROUTER also build E1-detectors for source detectors which are place 1m behind the real-life detector's position.

(TBD: check whether everything is placed into the proper directory; check what's about PKWs/LKWs)

The results are obtained from the simulation using simulated detectors. You will find detectors one knows from the real world such as induct loops, but also some virtual ones that allow gaining values one can work with more easily.

Basically, the main distinction between detectors SUMO offers is their dimension. The next list shows all available detector types, some of which are still under development. The type names "E*" have their origin in the German word "Erfassungsbereich" meaning "detection area".

We will not replicate the exact computation of the detector's values. A document describing this should be found on our pages within the documentation part. The next subchapters hold the information about how to set detectors onto a network only.

To ease the usage and for backward compatibility, all detectors may be defined in two ways. The first one is by using the following notation: <detector id="<ID>" type="<TYPE>" ...further attributes.../>. Herein, the detector type is determined by the type-attribute which is "induct_loop" as default. The second possibility is: : <XX-detector id="<ID>" ...further attributes.../> where the tag name already defines the detector to build. Possible values for XX within the tag name and attributes needed to describe each detector are described in the following subchapters.

6.1.1.1. E1-Detectors (Induct Loops)

An induct loop is defined either this way:

<detector id="<ID>" type="(induct_loop|E1)" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   freq="<AGGREGATION_TIME>" [style="xml"] file="<OUTPUT_FILE>" [friendly_pos="x"]/>

or this way:

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

The id is any string that let's you know which detector is meant. The type indicates that a induct loop shall be build, here. The attributes "lane" and "pos" describe on which lane and at which position on him the detector shall lay. As induct loop detectors may aggregate the values they collect, the freq-attribute describes this period. The style-parameter is obsolete by now as the earlier possibility to use either "xml" or "cvs"-output is now not supported, the values are stored in xml-files only. 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.

	Caution
	The folder the output file shall be generated in must exist.

Let's review the attributes:

• id: A string holding the id of the detector
  
• type: Always "induct_loop" or "E1" for this type of detectors ("induct_loop" is the default value)
  
• 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.
  
• style: Obsolete/deprecated; Always "xml" by now
  
• 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 place 0.1 meters from the lane's end.
  

Recent changes:

• The attribute friendly_pos is available since version 0.9.4
  

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

An induct loop is defined the following way:

<detector id="<ID>" type="(areal|lane_based|E2)" lane="<LANE_ID>"
   pos="<POSITION_ON_LANE>" length="<DETECTOR_LENGTH>" freq="<AGGREGATION_TIME>"
   [style="xml"] file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

or:

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

Most of the attributes have the same meaning as for induct loops. As an areal detector has a certain length, this length must be supplied as a further parameter. It may also be a negative number which lets the detector be extended upstream to the given beginning position. The type must be set to either "areal", "lane_based" or "E2" to let the simulation know what's desired to build. 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. The attribute "measures" describes which values the detector shall compute. The optional values are described below.

	Caution
	The folder the output file shall be generated in must exist.

	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.

But there is also a further possibility to use E2-detectors. If you place them in front of a traffic light, you can use the traffic light to describe 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 your detector by the id of the traffic light that should steer it (use the attribute "tl" to specify the id) :

<detector id="<ID>" type="[(areal|lane_based|E2)" lane="<LANE_ID>" \
   pos="<POSITION_ON_LANE>" length="<DETECTOR_LENGTH>" tl="<TL-ID>"
   freq="<AGGREGATION_TIME>" [style="xml"] file="<OUTPUT_FILE>"
   [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

or:

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

A further feature allows you to output values not for all switches of the traffic light the detector is attached to, but only when the light turns red for the assigned link (connection between the incoming and the outgoing lane). This should allow you to measure the maximum jam length in front of a red traffic light for this link. To switch on this feature, you have to add the name of the following lane: to="<LANE_ID>". The incoming lane is already given by the "lane"-attribute.

E2-detectors may compute many different measures and the user has the possibility to describe which measures he actually wants to be generated. The "measures"-attribute must contain the measures divided by a ' ' (blank) in the case he does not want to compute all parameters. Computing all parameters is the default case but may also be set using 'measures="ALL"' . The available measures are:

• DENSITY: The density on the detector in vehicles/hour averaged over the requested interval.
  
• MAX_JAM_LENGTH_IN_VEHICLES: Every timestep, the maximum number of consecutivly jamming vehicles is detected. These values are averaged over the requested interval.
  
• MAX_JAM_LENGTH_IN_METERS: Every timestep, the maximum length demand of consecutivly jamming vehicles in meters is detected. These values are averaged over the requested interval.
  
• JAM_LENGTH_SUM_IN_VEHICLES: Every timestep, the sum of the lengths of all jams on the detector is measured (in vehicles). These values are averaged over the requested interval.
  
• JAM_LENGTH_SUM_IN_METERS: Every timestep, the sum of the lengths of all jams on the detector is measured (in meters). These values are averaged over the requested interval.
  
• QUEUE_LENGTH_AHEAD_OF_TRAFFIC_LIGHTS_IN_VEHICLES: This detector uses a MAX_JAM_LENGTH_IN_VEHICLES one as a helper. Every timestep, the "maximum-jam-length" (in vehicles) from MAX_JAM_LENGTH_IN_VEHICLES will be compared to the maximum of "maximum-jam-lengths" that occured since the last reset. If the new value is larger, the maximum of "maximum-jam-lengths" is updated. Between two resets, this detector records a monoton growing set of "maximum-jam-lengths". These values are averaged over the requested interval. The reset is performed by a traffic light.
  
• QUEUE_LENGTH_AHEAD_OF_TRAFFIC_LIGHTS_IN_METERS: As QUEUE_LENGTH_AHEAD_OF_TRAFFIC_LIGHTS_IN_VEHICLES, but in meters, not in vehicles.
  
• N_VEHICLES: Every timestep, the number of vehicles that populate the detector is recorded. These values are averaged over the requested interval.
  
• OCCUPANCY_DEGREE: Every timestep the length of the vehicles populating the detector is summed up. We divide this length by the detectorlength to get a value out of [0,1]. These values are averaged over the requested interval.
  
• SPACE_MEAN_SPEED: Every timestep, the mean-speed of the vehicles on the detector is calculated. These values are averaged over the requested interval.
  
• CURRENT_HALTING_DURATION_SUM_PER_VEHICLE: Every timestep, the halting-time of the vehicles on the detector is summed up and then averaged over the number of vehicles. These values are averaged over the requested interval.
  
• N_STARTED_HALTS: A vehicle on the detector that just started halting, will report the time when this event took place to the detector. All events during the requested interval are summed up.
  
• HALTING_DURATION_SUM: A vehicle that starts moving after a halt will report it's halting-duration (in seconds) and the time when this event took place to the detector. The halting-durations of all events during the requested interval are summed up.
  
• HALTING_DURATION_MEAN: Every vehicle sums up it's halting-durations (in seconds) during it's stay on the detector. When a vehicle leaves the detector, it's halting-duration-sum is stored by the detector. These values are averaged over the requested interval.Only vehicles that moved through the entire detector contribute.
  
• APPROACHING_VEHICLES_STATES: This detector is a special kind of E2 detector. It doesn't return a single value but a container of vehicle states. Here, a vehicle state is a tuple consisting of the distance from the vehicle front to the detector end and the vehicle's speed. There is no averaging or summing up but current output is provided. This detector is intended for internal use, e.g. as input to traffic-light-controls.
  

Again, the explicit list of available attributes:

• id: A string holding the id of the detector
  
• type: Always "lane_based" or "E2" for this type of detectors ("induct_loop" is the default value)
  
• 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.
  
• measures: Should contain the list of measures to compute (see above) or "ALL" to compute all measures.
  

And the optional ones:

• style: Obsolete/deprecated; Always xml by now
  
• 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).
  
• keep_for: Information for how long the memory of the detector has to be (in s, default: 1800s).
  
• measures: Should contain the list of measures to compute (see above) or "ALL" to compute all measures (default: ALL).
  

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

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:

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:

Recent changes:

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:

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 nSamples="<VEHICLE_NUMBER>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>"/>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>">
         <lane id="<LANE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 nSamples="<VEHICLE_NUMBER>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>"/>

         ... more lanes

      </edge>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

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.

The meanings of the written values are:

You can force the simulation to generate this output using --emissions-output <FILENAME> or --emissions <FILENAME>.

Examples:

Recent changes:

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 vehicle_id="<VEHICLE_ID>" start="<DEPARTURE_TIME>" \
            wished="<WISHED_DEPARTURE_TIME>" \
            end="<ARRIVAL_TIME>" \
            duration="<TRAVEL_TIME>" \
            waited="<WAITING_TIME>"/>

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

The meanings of the written values are:

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

Examples:

Recent changes:

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:

<vehicleroutes>
   <vehicle id="<VEHICLE_ID>" emitedAt="<EMISSION_TIME>" endedAt="<ARRIVAL_TIME>">
      <route replacedOnEdge="<EDGE_ID>" replacedAtTime="<TIME>"><PREVIOUS_ROUTE></route>

      ... further replaced routes ...

      <route><LAST_ROUTE></route>
   </vehicle>

   ... information about further vehicles ...

</tripinfos>

The values have the following meanings:

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:

Recent changes:

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.

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

<tls-switches>
   <switch 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>

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. (TBD add references) 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).

Examples:

Recent changes:

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

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

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

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

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

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

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

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.

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: <trigger id="<BUS_STOP_ID>" objecttype="bus_stop" objectid="<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:

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>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</route>
        <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:

Examples:

Some extensions still to be done:

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: <trigger id="<VSS_ID>" objecttype="lane" objectid="<LANE_ID>" attr="speed" file="<DEF_FILE>"/>. This trigger is typed to be a vss by the combination of the values of the attributes objecttype="lane" and attr="speed". Although no other combinations are implemented so far, this combination forces the simulation to change the attribute "speed" of a "lane"-object, exactly what vss do. Of course, the vehicles themselves do not override this maximum velocity what does not exactly represent the reality.

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

Rerouter change the route of vehicles as soon as a vehicle moves on a specified edge. Although implemented earlier, were firstly described and tested within version 0.9.5.

A rerouter is set into the simulated by adding the following line to an "additional file": <trigger id="<REROUTER_ID>" objecttype="rerouter" objectid="<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 give within this definition how many vehicles shall be rerouted by giving a number between 0 (none) and 1 (all). In addition to this definition a description file (<DEFINITION_FILE>) must be given which describes the behaviour of the rerouter over time. The definition values are

Each definition 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 in detail.

Examples:

Recent changes:

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

   ... further intervals ...

</rerouter>

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

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

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.

Examples:

Recent changes:

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

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:

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 (#TBD see also "Vehicle Teleportation" #). You still may force the simulation to quit as soon an "accident" happens using the option --quit-on-accident.