SUMO - Simulation of Urban MObility - User Documentation

SUMO is a microscopic road traffic simulation package. In the near future it will be extended to model other transit modes simultaneously with ordinary car traffic.

1.2. Why open source?

Two thoughts stood behind the release of the package as open source. At first the fact that every traffic research organisation is forced to implement an own simulation package; some people are interested in traffic light optimisation, other try to find mistakes made during the design of a road network. Both need some kind of a simulation package and have to implement a framework containing input and output functions and other things from scratch. So the first idea was to give them a basic framework - containing all needed methods for a simulation - they can put own ideas into. The second idea is to supply a common test bed for models, especially car models, to the community to make them comparable. Due to different architectures of traffic simulations such comparisons on a wide scale are not possible by now.

1.3. Features

High portability (using standard - c++ and portable libraries only)
Collision free vehicle movement
Different vehicle types
Single-vehicle routing
Multi-lane streets with lane changing
Junction-based right-of-way rules
Hierarchy of junction types
A fast openGL graphical user interface
Dynamic routing
Manages networks with several 10.000 edges (streets)
Fast execution speed (up to 100.000 vehicle updates/s on a 1GHz machine)
Supports import of many network formats (Visum, Vissim, ArcView, XML-Descriptions)

1.4. About this Document

This document describes how to use each of the applications that come with the SUMO-package. We should remark, that this document only covers the usage of the software and some descriptions of the used models.

1.4.1. Described Applications

Table 1.1. Applications described within this document

Application	Application Name (Windows)	Application Name (Linux/UNIX)	Description	Described in Chapter
NETCONVERT	netconvert.exe	sumo-netconvert	A network converter/importer	Chapter 4
NETGEN	netgen.exe	sumo-netgen	A generator of abstract networks	Chapter 4
DFROUTER	dfrouter.exe	sumo-dfrouter	A router using detector flows	Chapter 5
DUAROUTER	duarouter.exe	sumo-durarouter	A router for dynamic user assignment	Chapter 5
JTRROUTER	jtrrouter.exe	sumo-jtrrouter	A router using junction turning ratios	Chapter 5
SUMO	sumo.exe	sumo	The microscopic simulation	Chapter 6
GUISIM	guisim.exe	sumo-guisim	The gui-version of the microscopic simulation	Chapter 7
POLYCONVERT	polyconvert.exe	sumo-polyconvert	A tool for importing polygons from other formats	Chapter 8.3.1
other	---	---	---	Chapter 8

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.

1.4.2. Notation

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.

1.4.3. Status

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.

1.5. Call for Help

Please let us know when either the document remains at any point unclear or any of the applications does not behave as expected. We would be very happy if you report broken links or misspelled words. We also seek for some participants and further users, not only to share the development tasks, but also to gain some feedback and critics or some usage examples.

To summarize: every help is appreciated. Thank you.

Chapter 2. First Steps

Table of Contents

2.1. Installing SUMO
2.2. Running the Examples

2.1. Installing SUMO

From version 0.8 on, we want not only supply the sources, but also the compiled binaries for MS Windows. We have abandonned the idea of releasing binaries for Linux due to large variety of the target systems.

If you are a Windows user, you should decide whether you primary want to use the software only or also extend it. In the first case, you should download the binaries. All needed libraries are included. In the latter case, please download the source distribution and compile it for your own. The description of the building process is found within a separate document located here. If you have built the package on a system not included within our binary distribution, please let us know and send it to us, so that we can include it into the pages.

When using Linux, you probably have to compile SUMO from the sources. A description about how to do this is located here.

The SUMO-package also contains some further scripts which are located within the tools-folder. To execute them you'll need to have python and/or perl installed.

2.2. Running the Examples

You may find some examples within the folder <SUMO_DIST>/data and its subfolders. Please remark that almost all applications are command line tools, what means that no window pops up if you start it, you have to open a shell window first.

Most of the examples come with a configuration-file so that may be directly run from the command line. Read chapter "Using Configuration Files" for further information on how to use configuration files.

We apologize that a documentation on the examples does not exist (yet). Nonetheless please feel invited to take a look at the tutorial(s) available at our wiki.

Chapter 3. Traffic Simulations and SUMO

Table of Contents

3.1. A short Introduction to Traffic Simulation Theory

3.1.1. Simulation types
3.1.2. Needed Data

3.2. The Workflow of Preparing a Simulation

3.3. SUMO

3.3.1. Main Software Paradigms

3.1. A short Introduction to Traffic Simulation Theory

3.1.1. Simulation types

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

In traffic research four classes of traffic flow 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]), extended by some further assumptions (see !!!). Mesoscopic simulations are located at the boundary between microscopic and macroscopic simulations. 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 longer 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 to divide streets into 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 leading vehicle's speed. Although SUMO is meant to be a test bed for such vehicle models, only one is implemented by now, an extension to the one developed by Stefan Krauß (see !!! for furhter details). 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 reducing the benefit of using them. 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]).

3.1.2. Needed Data

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.

3.2. The Workflow of Preparing a Simulation

As shortly described above, you basically have to perform the following steps in order to make your simulation run:

Build your network
Use either own descriptions (described in chapter 4, "Building Networks from own XML-descriptions") or if you have some digital networks SUMO can import, convert them (described in chapter 4, "Converting other Input Data")
Build the demand
Build your own movements using either by a) describing explicit vehicle routes (see chapter 5, "Using Trip Definitions"), b) using flows and turning percentages only (see chapter 5, "Using the Junction Turning Ratio - Router"), c) generating random routes (see chapter 5, "Generating random Routes"), d) importing OD-matrices (see chapter "Using OD2TRIPS" or "Using Flow Definitions"), or e) importing routes you own (see chapter 5, "Importing Routes").
If needed, compute the dynamic user assignment (described in chapter 5, "Dynamic User Assignment")
Perform the simulation (described in chapter 6, "Performing the Simulation") to get your desired output

This process is also visualised within the next figure.

Figure 3.3. Process of simulation with SUMO; (rounded: definite data types; boxes: applications; octagons: abstract data types)

Please remark, that most of the tools are command-line tools by now. They do nothing if you just double-click them (besides printing errors). Do also notice, that the call parameter desribed in the following chapters may be also stored in so-called "configuration files" to allow their reuse. This possibility is described in chapter "Using Configuration Files".

3.3. SUMO

3.3.1. Main Software Paradigms

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.

Chapter 4. Network Generation

Table of Contents

4.1. Introduction

4.2. Building Networks from own XML-descriptions

4.2.1. Nodes Descriptions
4.2.2. Edges Descriptions
4.2.3. Types Descriptions
4.2.4. Connection Descriptions
4.2.5. Building the Network

4.3. Converting other Input Data

4.3.1. Importing ArcView-databases
4.3.2. Importing Artemis-simulation folders
4.3.3. Importing Cell/Fastlane-networks
4.3.4. Importing VISSIM-networks
4.3.5. Importing VISUM-networks
4.3.6. Importing Elmar's converted NavTech-Files
4.3.7. Importing TIGER-databases

4.4. Further NETCONVERT Options

4.4.1. Setting default Values
4.4.2. Adding Turnarounds
4.4.3. Removing Geometry Nodes
4.4.4. Using Edges' maximum Speed Definitions in km/h
4.4.5. Importing Networks without Traffic Light Logics
4.4.6. Guessing On- and Off-Ramps
4.4.7. Converting from Geocoordinates
4.4.8. Adding inner-junction Traffic
4.4.9. Constraining the Input
4.4.10. Additional Output

4.5. Automatic Network Generation

4.5.1. Grid-like Networks
4.5.2. Spider-net-like Networks
4.5.3. Random Networks

4.6. Closing Thoughts (so far)

4.7. Recent Changes

4.8. Missing

4.1. Introduction

As SUMO uses an own road network description, networks must be converted from an existing dataset. Although being readable (xml) by human beings, the format of road networks used by SUMO is not meant to be edited by hand and will also not be described herein due to its complexity. SUMO networks can be build by either converting an existing map or by using NETGEN to generate basic, abstract road maps. The following figure shows the function of NETCONVERT and NETGEN within the procedure of building and running a simulation.

Figure 4.1. Building a network

Having data describing a road network, you may convert them into a network description readable by SUMO using the NETCONVERT tool. By now, NETCONVERT is capable to parse the following formats:

ptv VISUM (a macroscopic traffic simulation package), see chapter "Importing VISUM-networks"
ptv VISSIM (a microscopic traffic simulation package), see chapter "Importing VISSIM-networks"
ARTEMIS by Prof. Peter Hidas (a microscopic traffic simulation package), see chapter "Importing Artemis-simulation folders"
FastLane by Christian Gawron (a mesoscopic traffic simulation package), see chapter "Importing Cell/Fastlane-networks"
ArcView-data base files, see chapter "Importing ArcView-databases"
XML-descriptions, see chapter "Building Networks from own XML-descriptions"
Elmar Brockfelds unsplitted and splitted NavTeq-data, see chapter "Importing Elmar's converted NavTech-Files"
TIGER databases, see chapter "Importing TIGER-databases"

In most of these cases, NETCOVERT needs only two parameter: the option named as the source application/format followed by the name of the file to convert and the name of the output file (using the --output-file option). So if you want to import a file generated by the VISUM simulation package, simply write the following:

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

The parameter --output-file has the default value "net.net.xml". That means that both NETCONVERT and NETGEN will save the generated file as "net.net.xml" if the option is not set. Please note, that NETCONVERT has to be started from the command line. There is no graphical interface available, yet.

The following subchapters will describe more deeply how NETCONVERT and NETGEN are used, also discussing some problems with each of the import formats NETCONVERT supports. Please remind the option to name the output generated by both applications:

( --output-file | --output | -o ) <OUTPUT_FILE>: Defines the file to write the computed network into. This file will contain the generated network if the conversion could be accomplished. Optional (pregiven), type:filename, default: "net.net.xml"

4.2. Building Networks from own XML-descriptions

All examples within the distribution were made by hand. For doing this, you need at least two files: one file for nodes and another one for the streets between them. Please notice that herein, "node" and "junction" mean the same as well as "edge" and "street" do. Besides defining the nodes and edges, you can also join edges by type and set explicit connections between lanes. We will describe how each of these four file types should look like in the following chapters.

Figure 4.2. Building a network from XML-descriptions

4.2.1. Nodes Descriptions

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:

id: The name of the node; may be any character string
x: The x-position of the node on the plane in meters; must be a floating point number
y: The y-position of the node on the plane in meters; must be a floating point number
type: An optional type for the node. If you leave out the type of the node, it is automatically guessed by NETCOVERT but may not be the one you intentionally thought of. The following types are possible, any other string is counted as an error and will yield in a program stop:
- priority: Vehicles have to wait until vehicles right to them have passed the junction.
- traffic_light: The junction is controlled by a traffic light. (TBD: would further types make sense?)

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

4.2.2. Edges Descriptions

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="<UINT>" 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). Furthermore, the priority may be defined optionally. All 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 default (unset) priority 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:

id: The name of the edge; may be any character string
Origin and destination node descriptions
Either:
- fromnode: The name of a node within the nodes-file the edge shall start at
- tonode: The name of a node within the nodes-file the edge shall end at
or:
- xfrom: The x-position of the node the edge shall start at in meters; must be a floating point number
- yfrom: The y-position of the node the edge shall start at in meters; must be a floating point number
- xto: The x-position of the node the edge shall end at in meters; must be a floating point number
- yto: The y-position of the node the edge shall end at in meters; must be a floating point number
Descriptions of the edge's type and atomic attributes:
Either:
- type: The name of a type within the types-file
or/and:
- nolanes: The number of lanes of the edge; must be an integer value
- speed: The maximum speed allowed on the edge in m/s; must be a floating point number (see also "Using Edges' maximum Speed Definitions in km/h")
- priority: The priority of the edge; must be a positive integer value
- length: The length of the edge in meter; must be an float value
- function: Information whether the edge is a plain edge, a source edge, or a sink edge. The value must be one of "normal", "sink", "source".
The edges shape:
- shape: List of positions; each position is encoded in x,y (do not separate the numbers with a space!) in meters; an edge's shape definition must of course be at least two positions long; an example: shape="0,0 0,100" describes a vertical edge of one hundred meters.
- spread_type: The description of how to spread the lanes; "center" spreads lanes to both directions of the shape, any other value will be interpreted as "right".

The priority plays a role during the computation of the way-giving rules of a node. Normally, the allowed speed on the edge and the edge's number of lanes are used to compute which edge has a greater priority on a junction. Using the priority attribute, you may increase the priority of the edge making more lanes yielding in it or making vehicles coming from this edge into the junction not wait.

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:

The function-tag was added for version 0.9.4 and was revalidated for version 0.9.5

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

4.2.3. Types Descriptions

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="<UINT>" [function=( "source" | "sink" | "normal" )]/>.

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

id: The name of the road type; may be any character string
nolanes: The number of lanes of the referencing must be an integer value
speed: The maximum speed allowed on the referencing edge in m/s; must be a floating point number
priority: The priority of the referencing edge; must be a positive integer value
function: The function of the referencing edge; must be one of "source", "sink", or "normal". "normal" is the default.

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:

The basic usage of types is shown in <SUMO_DIST>/data/examples/netbuild/types/cross_notypes/ where the same network is constructed once not using types (subfolder "cross_notypes") and once using them (subfolder "cross_usingtypes").

Recent changes:

The function-tag was added for version 0.9.5

4.2.4. Connection Descriptions

4.2.4.1. Explicite setting which Edge / Lane is connected to which

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:

from: The name of the edge the vehicles leave
to: The name of the edge the vehicles may reach when leaving "from"

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:

from: The name of the edge the vehicles leave
to: The name of the edge the vehicles may reach when leaving "from"
lane: the numbers of the connected lanes, separated with ':'; lanes are counter from right to left beginning with 0

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.4. Unconstrained Network (zoom=2200)

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.5. 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.6. 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/connections/cross3l_unconstrained/):

<SUMO_DIST>/data/examples/netbuild/connections/cross3l_edge2edge_conns/ shows how edge-to-edge connections may be specified
<SUMO_DIST>/data/examples/netbuild/connections/cross3l_lane2lane_conns/ shows how lane-to-lane connections may be specified

Recent Changes:

A bug which sometimes yielded in a reassignment of connections is patched in version 0.9.3

4.2.4.2. Setting Connection Priorities

Since version 0.9.6 you can also let vehicles passing a connection between two edges wait for another stream. Let's take another look at "Network with explicit edge-2-edge connections" above. Here, all right-moving vehicles may drive. The following definition within the connections file lets vehicles on vertical edges moving right wait for those which move straight on horizontal edges:

<connections>

   <!-- The next four connection definitions are same as in 
        "Network with explicit edge-2-edge connections" -->
   <connection from="1si" to="3o"/>
   <connection from="1si" to="2o"/>

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

   <!-- now, let's prohibit the vertical connections by the horizontal -->
   <!-- prohibit moving right from top to left by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->1o"/>
   <!-- prohibit moving straight from top to bottom by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->3o"/>
   <!-- prohibit moving left from top to right by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->2o"/>

   <!-- prohibit moving right from bottom to right by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->2o"/>
   <!-- prohibit moving straight from bottom to top by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->4o"/>
   <!-- prohibit moving left from bottom to right by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->1o"/>

</connections>

As one may see, it was necessary to prohibit all connections from a vertical edge by the counter-clockwise straight connection on a horizontal edge because otherwise the vehicles on the horizontal edge want to wait due to right-before-left - rule. The network looks like this:

Figure 4.7. Network with explicite prohibitions

The syntax of a prohibition-tag is: <prohibition prohibitor="<PROHIBITING_FROM_EDGE_ID>-><PROHIBITING_TO_EDGE_ID>" prohibited="<PROHIBITED_FROM_EDGE_ID>-><PROHIBITED_TO_EDGE_ID>"/>. This means we define two connections (edge-to-edge), the prohibiting one (prohibitor) and the prohibited (prohibited). Each connection is defined by a from-edge and a to-edge, divided by "->".

Examples (compare to <SUMO_DIST>/data/examples/netbuild/connections/cross3l_unconstrained/):

<SUMO_DIST>/data/examples/netbuild/connections/cross3l_prohibitions/ shows how prohibitions may be specified

Recent Changes:

The possibility to add prohibitions was implemented for version 0.9.6

4.2.5. Building the Network

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:

( --xml-node-files | --xml-nodes | -n ) <NODES_FILE>: Uses the given file as the source of specification node positions and types. Optional, type:filename, default: none
( --xml-edge-files | --xml-edges | -e ) <EDGES_FILE>: Uses the given file as the source of specification of roads connecting nodes. Optional, type:filename, default: none
( --xml-connection-files | --xml-connections | -x ) <CONNECTIONS_FILE>: Uses the given file as the source of specification how roads are connected (which lanes may be reached from which lanes). Optional, type:filename, default: none
( --xml-type-files | --types | -t ) <TYPES_FILE>: Uses the given file as the source of edge types. Optional, type:filename, default: none
--omit-corrupt-edges: Continues with parsing although a corrupt edge occurred. This edge is not inserted and a warning is printed. Optional (pregiven), type:bool, default: false
--flip-y: Flips the y-position of nodes (and edges) along the y=zero-line. Optional (pregiven), type:bool, default: false

4.3. Converting other Input Data

Large maps cannot be written by hand. We use maps from NavTech stored in the ArcView database format and maps from other simulation suppliers such as ptv within our projects and both are too large for this. We will now explain how to convert such data. We will not give any introduction into the formats/simulations themselves or compare their quality, but we will describe what is being imported and what problems may arise during the conversion.

4.3.1. Importing ArcView-databases

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:

Table 4.1. Entries read by NETCONVERT

Entity Name	Description
LINK_ID	The id of an edge
ST_NAME	The name of an edge (not really used)
REF_IN_ID	The name of the node the edge starts at
NREF_IN_ID	The name of the node the edge ends at
ST_TYP_AFT	The type of the street (not really used)
SPEED_CAT	Speed category
LANE_CAT	Lane category
FUNC_CLASS	Road class, used to determine the priority

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:

Table 4.2. Possible entries to override NavTech-information

Entity Name	Description
SPEED	The speed in m/s (see also "Using Edges' maximum Speed Definitions in km/h")
NOLANES	The number of lanes
rnol	The number of lanes
PRIORITY	The priority

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:

--arcview <ARCVIEW_PREFIX>: Loads definitions from "<ARCVIEW_PREFIX>.shp", "<ARCVIEW_PREFIX>.dbf" and "<ARCVIEW_PREFIX>.shx". Optional, type:filename-prefix, default: none
--arcview.street-id <STREET_NAME_COLUMN_NAME>: This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of street names. If given, your database must contain this column, and the values must be unique for each street. Optional, type:string, default: none
--arcview.from-id <START_NODE_ID_COLUMN_NAME>: This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information from which node the street starts. If given, your database must contain this column. Optional, type:string, default: none
--arcview.to-id <END_NODE_ID_COLUMN_NAME>: This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information at which node the street ends. If given, your database must contain this column. Optional, type:string, default: none
--arcview.type-id <TYPE_ID_COLUMN_NAME>: This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information about the edge's type. Using this information, you can use type definitions as described in "Types Descriptions" to determine your edges' attributes. If given, your database must contain this column. Optional, type:string, default: none
--arcview.use-defaults-on-failure: If a type could not be resolved or is invalid or any of the explicite information about an edge was invalid, this option forces NETCONVERT to use the default type values for the current street. If not set, and one of the cases occures, the application's behaviour is not determined. Optional, type:bool, default: false
--arcview.all-bidi: Forces NETCONVERT to insert all edges bidirectional. Optional (pregiven), type:bool, default: false
--arcview.utm <ORIGINAL_UTM_ZONE>: This value describes in which UTM-zone your network is located. The default is 32 being a place somwhere in western Germany. You should change this value if importing networks located somewhere else in the world. Optional (pregiven), type:int, default: 32
--arcview.guess-projection: If building a converter using the given UTM-zone fails, this option tries to guess the project if set. Of course, this may also fail... Optional (pregiven), type:bool, default: false

4.3.2. Importing Artemis-simulation folders

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:

Nodes (id, position, type)
Links (origin, destination, id, speed, number of lanes, length)
Signals
Signal Groups (node id, group, connection, start & end phase)
Signal Phases (node id, start, phase, percentage)
Segments (link, position on link, geometrical position)
Lanes (lane number, section number, begin and end position)
HVdests (origin and destination lane)

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

Known problems:

The connections between lanes may be not the same as in the input
The positions of the lanes are not correct
The times the traffic lights switch at may not be the same as within the input
Additional source and sink links must be build
Possible speed changes at segments are not supported

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:

( --artemis-path | --artemis ) <PATH>: Loads definitions from the given path. Optional, type:path, default: none

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)

4.3.3. Importing Cell/Fastlane-networks

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:

( --cell-node-file | --cell-nodes ) <FILE>: Reads nodes definitions from <FILE>. Optional, type:path, default: none
( --cell-edge-file | --cell-edges ) <FILE>: Reads edges definitions from <FILE>. Optional, type:path, default: none
( --capacity-norm | -N ) <FLOAT>: Sets the capacity norm to the given value. Optional (pregiven), type:float, default: 20000