• SUMO Road Networks

Screenshot of a SUMO net file opened in sumo-gui. It shows the map of the German city Eichstätt.

A SUMO network file describes the traffic-related part of a map, the roads and intersections the simulated vehicles run along or across. At a coarse scale, a SUMO network is a directed graph. Nodes, usually named "junctions" in SUMO-context, represent intersections, and "edges" roads or streets. Note that edges are unidirectional. Specifically, the SUMO network contains the following information:

• every street (edge) as a collection of lanes, including the position, shape and speed limit of every lane,
• traffic light logics referenced by junctions,
• junctions, including their right of way regulation,
• connections between lanes at junctions (nodes).

Also, depending on the used input formats and set processing options, one can also find

• districts,
• roundabout descriptions.

Although being readable (XML) by human beings, a SUMO network file is not meant to be edited by hand. Rather you should use SUMO XML description files together with netconvert. You can also convert an existing map from various formats using netconvert or generate geometrically simple, abstract road maps with netgenerate. To modify an existing .net.xml-file you may load it with netconvert along with patch files You may also use netedit for building own road networks or for reworking the ones obtained from netconvert or netgenerate.

Network Format#

SUMO road networks are encoded as XML files. The contents are grouped by the instances in the following order:

• cartographic projection valid for this network
• edges; at first, internal edges are given, then plain edges; each edge contains the list of lanes that belong to it
• traffic light logics
• junctions, including their right-of-way definitions; plain junctions first, then internal junctions
• connections, plain first, then internal
• optionally roundabouts

Coordinates and alignment#

The networks are using cartesian, metric coordinates where the leftmost node is at x=0 and the node being most at the bottom is at y=0. This means that when being imported, netconvert and netgenerate are projecting the network, first, if the original network was not using cartesian and/or metric coordinates. Then, they move the road network to the origin at (0,0).

This process is documented within the generated network within the element location. You may find here the following attributes:

projParameter may have one of the following values:

For obtaining the original coordinates from the x/y-coordinates SUMO reports, one has to subtract the network offset first. Then, one has to apply an inverse transformation of the initial projection, regarding projParameter. For proj-projected networks, one can use proj's function named pj_inv which performs the inverse transformation. proj has to be initialised with the projection parameters from projParameter, first. For proj-projected networks this would look like:

Position2D cartesian = sumoXY(x, y);
projPJ myProjection = pj_init_plus(projParameter.c_str());
cartesian.sub(netOffset);
projUV p;
p.u = cartesian.x();
p.v = cartesian.y();
p = pj_inv(p, myProjection);
p.u *= RAD_TO_DEG;
p.v *= RAD_TO_DEG;
cartesian.set(p.u, p.v);

For networks with no projection (projParameter='!'), only the offset must be applied. For networks with "simple" projection (projParameter='-'), a back-projection method is currently not known.

SUMO road networks are meant to be aligned to the north. Of course, it is up to the user how he defines a road network, but when being imported from sources as Open Street Map or shape files, the up-direction is meant to correspond to north.

Edges and Lanes#

"plain" and "internal" edges are encoded almost the same way, but they differ by the mandatory and used attributes.

Normal Edges#

A "normal" edge is a connection between two nodes ("junctions").

<edge id="<ID>" from="<FROM_NODE_ID>" to="<TO_NODE_ID>" priority="<PRIORITY>">
    ... one or more lanes ...
</edge>

Here, the ID (<ID> in the example above) is an ID as read during the network import. Both the IDs of the begin and the end node are given within the attributes from and to, respectively. The priority is an abstract ordinal number that determines right-of-way rules. The function attribute was omitted in the example above, as it defaults to "normal", which is the example edge's function value.

The attributes of an edge are:

For the simulation, only the "function" attribute is of interest. It describes how the edge is used, and whether it is an edge that can be found within the real world or only a helper construct used for assignment. The following purposes are defined:

• normal: The edge is a plain part of a road network, like a highway or a normal street which connects two roads
• connector: The edge is a macroscopic connector - not a part of the real world road network. Still, within the simulation, no distinction is made between "connector" roads and "normal" nodes. Only sumo-gui allows to hide connector edges.
• internal: The edge is a part of an intersection (is located within the intersection), see above.
• crossing:
• walkingarea:

Lanes#

Each edge includes the definitions of lanes it consists of. The following example shows a single edge with two lanes. Note, that coordinates may be 2D as well as 3D.

    <edge id="<ID>" from="<FROM_NODE_ID>" to="<TO_NODE_ID>" priority="<PRIORITY>">
        <lane id="<ID>_0" index="0" speed="<SPEED>" length="<LENGTH>" shape="0.00,495.05 248.50,495.05"/>
        <lane id="<ID>_1" index="1" speed="<SPEED>" length="<LENGTH>" shape="0.00,498.35,2.00 248.50,498.35,3.00"/>
    </edge>

As one can see, the id is composed by the ID of the edge the lane belongs to and a running number, both divided by an underline ('_'). The running number starts at zero for the right-most lane. The same number is also given in the "index" attribute. The lanes are sorted by this number, too. @note: this is highly duplicate

The attributes of a lane are:

It should be noted, that currently all lanes of an edge have the same length, even if it differs from the geometrical length of the shape. netconvert even explicitly allows to override the geometrical lengths. Additionally, even though the network is shifted to start at (0,0), it is not guaranteed that all of the network's parts have positive coordinates.

Internal Edges#

An internal edge lies within an intersection and connects and incoming normal edge with an outgoing normal edge. Internal edges are not included if the network was built using the --no-internal-links option. An example of an internal edge may look like this:

<edge id="<ID>" function="internal">
    ... one lane ...
</edge>

The id of an internal edge is composed as :<NODE_ID>_<EDGE_INDEX> where <NODE_ID> is the ID of the node the edge is located within and <EDGE_INDEX> is a running number running clockwise around the node (starting in the north). Please note that the ID has a ':' as prefix. If the incoming and outgoing edges connected by the internal edge have multiple lanes, the internal edge has multiple lanes as well (according to the number of connections between these two edges). In case of multi-lane internal edges, the INDEX jumps by the number of lanes so that EDGE_INDEX + LANE_INDEX = CONNECTION_INDEX.

The attributes are given in the following table.

When the network was built with internal edges, each connection will typically correspond to exactly one internal lane. If there are multiple connections that have the same pair of from and to edges, then the internal lanes for these edges will be part of the same internal edge. On connections marked as straight (dir="s"), lane changing on internal lanes is permitted.

Special cases are so called internal junctions. These mark places where vehicles wait within an intersection before passing through foe traffic. The most common occurrence for this are:

• left-turning vehicles that yield to oncoming traffic
• right-turning vehicles that yield to pedestrian crossings

The connection corresponding to such a movement are split into two internal lanes: one lane before the waiting position and one lane after the waiting position. The lanes after an internal junction always have their own internal edge.

Stop Offsets#

Each edge or lane may carry a stopOffset child element to specify an additional stopping offset for vehicles of certain classes. This can be used to define a bike box. The exact syntax is explained at stopOffset.

Traffic Light Programs#

A traffic light program defines the phases of a traffic light.

    <tlLogic id="<ID>" type="<ALGORITHM_ID>" programID="<PROGRAM_ID>" offset="<TIME_OFFSET>">
        <phase duration="<DURATION#1>" state="<STATE#1>"/>
        <phase duration="<DURATION#1>" state="<STATE#1>"/>
        ... further states ...
        <phase duration="<DURATION#n>" state="<STATE#n>"/>
    </tlLogic>

For an explanation of the attributes and semantics, please consult Simulation/Traffic Lights. Please note that usually, the generated program has the ID "0".

Junctions and Right-of-Way#

Plain Junctions#

Junctions represent the area where different streams cross, including the right-of-way rules vehicles have to follow when crossing the intersection. An example may be:

<junction id="<ID>" type="<JUNCTION_TYPE>" x="<X-POSITION>" y="<Y-POSITION>"
          incLanes="<INCOMING_LANES>" intLanes="<INTERNAL_LANES>"
          shape="<SHAPE>">
    ... requests ...
</junction>

The junction itself is described by the following attributes:

Please note, that the x/y-positions of the junction describe the given, not the computed center of the junction. It is allowed for two nodes to have the same position.

Requests#

What follows are "request"s, looking like:

  <request index="<INDEX>" response="<RELATIVE_MAJOR_LINKS>" foes="<FOE_LINKS>" cont="<MAY_ENTER>"/>

They describe, for each link (given as "index") which streams have a higher priority ("response") and force the vehicle on link "index" to stop, and which streams are in conflict ("foes"). "foes" is a super-set of "response", adding streams that have a lower priority than the stream referenced as "index".

One can read the requests as following: the index describes a certain connection, between an incoming and an outgoing lane, over the intersection. The indices are computed connection-wise and the order is as following: first, sort edges by their direction, starting with 0° (up); second, use lane order (right-most-first); third, order by the direction the connection follows, starting by the right-most.

The same order is applied in the "response" and the "foes" field, starting from right. This means:

  <request index="2" response="001" foes="011" cont="0"/>

The a vehicle using the connection with the index "2" has to wait for vehicles that use the connection "0". Connections "0" and "1" are its foes. The attributes of a request element are:

Internal Junctions#

"internal" junctions are used to define a waiting position within the intersection for some traffic relations. This is typically used for left-turning vehicles from the prioritized direction or for right-turning vehicles that have to wait for straight-going pedestrians.

Since version 0.25.0 the user can customize the positioning (and presence) of internal junctions

These junctions do not need a right-of-way matrix but only following information

• the lanes that are incoming into the junction the internal junction is located in and prohibit to pass the internal junction if a vehicle is approaching
• the internal lanes that must not be occupied for crossing the internal junction

An internal junction is encoded like this:

<junction id="<ID>" type="internal" x="<X-POSITION>" y="<Y-POSITION>"
          incLanes="<INCOMING_PROHIBITING_LANES>"
          intLanes="<INTERNAL_PROHIBITING_LANES>"/>

The ID is the same as the lane to use when crossing the internal junction itself. The type is always "internal". Please note that an internal junction is usually encoded in one line. The attributes of an internal junction are:

Connections#

Plain Connections#

Plain connections or "links" describe which outgoing lanes can be reached from an incoming lane. Additionally, the first lane to use for passing the intersection is given. Additional information describe the direction and the "state" of the connection. If the connection is controlled by a traffic light, the name of the traffic light and the index of the signal that controls this connection within the traffic light's phase definition is given. A connection is encoded as:

<connection from="<FROM_EDGE_ID>" to="<TO_EDGE_ID>" fromLane="<FROM_LANE_INDEX>" toLane="<TO_LANE_INDEX>"
            via="<VIA_LANE_ID>" tl="<TRAFFIC_LIGHT_ID>" linkIndex="12" dir="r" state="o"/>

The attributes are:

When creating these connections without netconvert (not recommended) it should be taken into account that a connection with an internal lane follows a special pattern. For example when lane 1_f_0 needs to be connected to 1_t_0 through 1_v_0, the following connection entries exist: [from=1_f_0, to=1_t_0 via=1_v_0] and [from=1_v_0 to=1_t_0]. If the latter is omitted, SUMO will not load the network. It will also not load if next to the necessary connections a connection [from=1_f_0 to=1_v_0] exists.

Indices of a connection#

Each connection has associated indices which can be shown in sumo-gui by customizing gui settings and activating Junctions->Show ... index. These indices are usually identical but may be configured independently of each other.

• Junction Index: This index is described in section #Requests. It cannot be modified. The index corresponds to the order of the <junctions>s incLanes-attribute and also to the order of the <connection> elements. These indices run clockwise (in a right-hand network) around the junction starting at the top.

• TLS Index: This index is assigned to connections which are controlled by a traffic light. For joined traffic lights (controlling multiple junctions) this index differs from the junction index because the latter is no longer unique. The TLS Index may be configured with a .con.xml file. Custom indices may be used to create signal groups (multiple connections that always have the same state and share the same index) and thus simplify the state definition for the traffic light phases.

Roundabouts#

Roundabouts in a network influence the right of way (encoded in the Requests <request> elements of a junction during network building). Their presence in the network file has two reasons:

• It facilitates re-importing a .net.xml-file with netconvert
• lane-changing models may take roundabouts into account

Each roundabout is defined (somewhat redundantly) by its nodes and edges:

<roundabout nodes="nodeID1 nodeID2 ..." edges="edgeID1 edgeID2 ..."/>

Software for Viewing, Editing and Processing#

To create a SUMO network file, netconvert helps to generate it from maps in other formats and netgenerate constructs a new map with simple geometries. sumo performs its simulation directly in the map of this file. Most other SUMO tools read such files to generate or import information that must be the mapped onto a road network.

Networks can be created and edited graphically using netedit.

The SUMO net file is not meant for manual editing. Convert it to the SUMO native XML descriptions with netconvert instead. You can then process these files by hand and rebuild the network with netconvert.

Further Documentation#

• Network Import
  • • Defining own networks using XML and netconvert
    • Importing networks from other applications using netconvert
  • netconvert manual
• Generation of abstract road networks
  • Generating abstract networks using netgenerate
  • netgenerate manual
• netedit manual
• Developer/Network Building Process