User

• Introduction
• The traffic simulation SUMO
• Basic Usage
• Notation in this Documentation
• Needed, basic Computer Skills
• Installing SUMO
• Using SUMO Command Line Applications
• Tutorials
• Network Building
• SUMO Road Networks
• Abstract networks generation
• Importing networks with NETCONVERT
• Defining own networks using XML
• Importing non-SUMO networks
• ... from OpenStreetMap
• ... from VISUM
• ... from Vissim
• ... from openDRIVE
• ... from MATsim
• ... from ArcView (shapefiles)
• ... from Elmar's GDF
• ... from Robocup Simulation League
• Importing SUMO networks
• Further NETCONVERT options
• Additional output
• Demand Modelling
• Introduction to SUMO Demand Modelling
• Definition of Vehicles, Vehicle Types, and Routes
• Simulation of public transport
• Simulation of individual persons and trip chains
• Importing O/D Matrices
• Random Trips
• Shortest or Optimal Path Routing
• Routing by Turn Probabilities
• Routes from Observation Points
• Activity-based Demand Generation
• Computing Dynamic User Assignment
• Importing foreign demands
• Other VISUM Demand Importers
• Other Vissim Demand Importers
• Routing in the Simulation
• Random Routes
• Simulation
• Basic Definition
• Traffic Management and Other Structures
• Traffic Lights
• Public Transport
• Variable Speed Signs
• Rerouter / Alternative Route Signage
• Vaporizer
• Simulation output
• TraCI (On-line Interaction)
• Shapes Visualisation
• Common Problems
• Why Vehicles are teleporting
• Theory
• Traffic simulations in general
• Appendices
• Glossary
• FAQ
• Additional Tools
• Known File Extensions
• Application Manuals
• SUMO
• SUMO-GUI
• NETCONVERT
• NETGENERATE
• OD2TRIPS
• DUAROUTER
• JTRROUTER
• DFROUTER
• POLYCONVERT
• ACTIVITYGEN
• Tool Manuals
• Tools/TraceExporter
• Translations
• Persian SUMO tutorial
• Persian tutorial on "Vehicular Adhoc Network Simulation With NS2, SUMO And MOVE"

Further Resources

• Example Networks
• Example Scenarios
• Traffic Data

Developer

• Developer Docs
• Daily Tests Status
• Doxygen Documentation
• Python Modules Documentation
• traci
• sumolib

The simplest way to get own routes is to edit a routes file by hand, but only if the number of different routes is not too high. Before starting, it is important to know that a vehicle in SUMO consists of three parts: a vehicle type which describes the vehicle's physical properties, a route the vehicle shall take, and the vehicle itself. Both routes and vehicle types can be shared by several vehicles.

Vehicle Types

At first a vehicle type will be defined:

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

Having this defined, one can build vehicles of type "type1". The values used above are the ones most of the examples use. They resemble a standard vehicle as used within the Stefan Krauß' thesis.

This definition is the initial one which includes both, the definition of the vehicle's "purely physical" parameters, such as its length, its color, or its max. velocity, and also the used car-following model's parameters. Please note that even though the car-following parameters are describing values such as max. acceleration, or max. deceleration, they mostly do not correspond to what one would assume. The maximum acceleration for example is not the car's maximum acceleration possibility but rather the maximum acceleration a driver choses - even if you have a Jaguar, you probably are not trying to go to 100km/h in 5s when driving through a city.

For allowing to use different car-following models than the one developed by Krauß, the vehicle type definition was extended. The initial one still can be used, but an extension allows to additionally choose a different model and give its parameter. Here is how the new description looks like (for the same vehicle type as above):

<routes>
    <vType id="type1" length="5" maxSpeed="70">
        <carFollowing-Krauss accel="0.8" decel="4.5" sigma="0.5"/>
    </vType>
</routes>

You may note that the car-following model's parameter are now listed in a child-element of the vehicle type definition. Please note that the values of the carFollowing-element are overwriting values given in the vType-element.

These values have the following meanings:

Besides values which describe the vehicle's car-following properties, one can find definitions of the assigned vehicles' shapes, emissions, and assignment to abstract vehicle classes. These concepts will be described in the following. Also, you may find further descriptions of implemented car-following models in the subsection #Car-Following Models.

Speed Distributions

The attributes speedFactor and speedDev are used to sample a vehicle specific chosenSpeedFactor from a normal distribution with mean speedFactor and deviation speedDev. Using speedFactor=1, speedDev=0.1 will result in a speed distribution where 95% of the vehicles drive between 80% and 120% of the legal speed limit. For flows, every inserted vehicle will draw an individual chosenSpeedMultiplier as well. The resulting values are capped at 0.1 to prevent extreme dawdling. A vehicle keeps its chosenSpeedMultiplier for the whole simulation and multiplies it with edge speeds to compute the actual speed for driving on this edge. Thus vehicles can exceed edge speeds. However, vehicle speeds are still capped at the vehicle type's maxSpeed.

Vehicle Length

Due to the work on car following models, we decided to use two values for vehicle length. The length-attribute describes the length of the vehicle itself. Additionally, the minGap-attribute describes the offset to the leading vehicle when standing in a jam.

This is illustrated in the following image:

Within the simulation, each vehicle needs - when ignoring the safe gap - length+minGap. But only length of the road should be marked as being occupied.

Abstract Vehicle Class

A SUMO vehicle may be assigned to an "abstract vehicle class", defined by using the attribute vClass. These classes are used in lane definitions and allow/disallow the usage of lanes for certain vehicle types. One may think of having a road with three lanes, where the rightmost may only be used by "taxis" or "busses". The following vehicle classes exist:

• "private"
• "public_transport"
• "public_emergency"
• "public_authority"
• "public_army"
• "vip"
• "ignoring"
• "passenger"
• "hov"
• "taxi"
• "bus"
• "delivery"
• "transport"
• "lightrail"
• "cityrail"
• "rail_slow"
• "rail_fast"
• "motorcycle"
• "bicycle"
• "pedestrian"

These values are a "best guess" of somehow meaningful values, surely worth to be discussed. Though, in parts, they represent classes found in imported formats. They are "abstract" in the means that they are just names only, one could build a .5m long bus. They are only used for determining the usability of lanes.

Vehicle Emission Classes

The emission class represents a certain HBEFA-based emission class. It is defined using the emissionClass attribute. Possible values for this attribute can be found on page Simulation/Models/Emissions/HBEFA-based.

Visualization

For a nicer visualization of the traffic, the appearence of a vehicle type's vehicles may be changed by assigning them a certain shape using the guiShape attribute. The following shapes are known:

• "pedestrian"
• "bicycle"
• "motorcycle"
• "passenger"
• "passenger/sedan"
• "passenger/hatchback"
• "passenger/wagon"
• "passenger/van"
• "delivery"
• "transport"
• "transport/semitrailer"
• "transport/trailer"
• "bus"
• "bus/city"
• "bus/flexible"
• "bus/overland"
• "rail"
• "rail/light"
• "rail/city"
• "rail/slow"
• "rail/fast"
• "rail/cargo"
• "evehicle"

In addition, one can determine the width of the vehicle using the attribute guiWidth.

When using shapes, one should consider that different vehicle classes (passenger vehicles or buses) have different lengths. Passenger vehicles with more than 10m length look quite odd, buses with 2m length, too.

Car-Following Models

The car-following models currently implemented in SUMO are given in the following table.

Mostly, each model uses its own set of parameters. The following table lists which parameter are used by which model(s). Please note that car-following itself and the car-following models are not discussed, here. Their development and evaluation is one of our work's topics, so they should be described on a different page more verbose.

Vehicles and Routes

As next, we will define a vehicle with a route owned by him only:

<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 edges="beg middle end rend"/>
   </vehicle>

</routes>

By giving such a route definition to SUMO (or SUMO-GUI), SUMO will build a red (color=1,0,0) vehicle of type "type1" named "0" which starts at time 0. The vehicle will drive along the streets "beg", "middle", "end", and as soon as it has approached the edge "rend" it will be removed from the simulation.

This vehicle has an own, internal route which is not shared with other vehicles. It is also possible to define two vehicles using the same route. In this case the route must be "externalized" - defined before being referenced by the vehicles. Also, the route must be named by giving it an id. The vehicles using the route refer it using the "route"-attribute. The complete change looks like this:

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

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

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

A vehicle may be defined using the following attributes:

Repeated vehicles

It is possible to define repeated vehicle emissions ("flow"s), which have the same parameters as the vehicle except for the departure time. The id of the created vehicles is "flowId.runningNumber" and they are distributed equally in the given interval. The following additional parameters are known:

<flow id="type1" color="1,1,0"  begin="0" end= "7200" period="900" type="BUS">
    <route edges="beg middle end rend"/>
    <stop busStop="station1" duration="30"/>
</flow>

Routes

One may notice, that the route itself also got a color definition, so the attributes of a route are:

There are a few important things to consider when building your own routes:

• Routes have to be connected. At the moment the simulation does not raise an error if the next edge of the current route is not a successor of the current edge. The car will simply stop at the end of the current edge and will possibly be "teleported" to the next edge after a waiting time. This is very likely to change in future versions.
• Routes have to contain at least one edge.
• The starting edge has to be at least as long as the car starting on it. At the moment cars can only start at a position which makes them fit on the road completely.
• The route file has to be sorted by starting times. In fact this is only relevant, when you define a lot of routes or have large gaps between departure times. The simulation parameter --route-steps, which defaults to 200, defines the size of the time interval with which the simulation loads its routes. That means by default at startup only route with departure time <200 are loaded, if all the vehicles have departed, the routes up to departure time 400 are loaded etc. pp. This works only if the route file is sorted. This behaviour may be disabled by specifying --route-steps 0.

The first three conditions can be checked using <SUMO_DIST>/tools/routecheck.py.

A Vehicle's depart and arrival parameter

Using the depart... and arrival...-attributes, it is possible to control how a vehicle is inserted into the network and how it leaves it.

departLane

Determines on which lane the vehicle is tried to be inserted;

• ≥0: the index of the lane, starting with rightmost=0
• "random": a random lane is chosen; please note that a vehicle insertion is not retried if it could not be inserted
• "free": the most free (least occupied) lane is chosen
• "allowed": the "free" lane (see above) of those lane of the depart edge which allow vehicles of the class the vehicle belongs to
• "best": the "free" lane of those who allow the vehicle the longest ride without the need to lane change

BTW, I like "best" at most - dkrajzew

departPos

Determines the position on the chosen departure lane at which the vehicle is tried to be inserted;

• ≥0: the position on the lane, starting at the lane's begin; must be smaller than the starting lane's length
• "random": a random position is chosen; it is not retried to insert the vehicle if the first try fails
• "free": a free position (if existing) is used
• "random_free": at first, the "random" position is tried, then the "free", if the first one failed
• "base": the vehicle is tried to be inserted at the position which lets its back be at the beginning of the lane (vehicle's front position=vehicle length)
• "pwagSimple": If no interacting leader exists, the vehicle is inserted with departSpeed="max" at the end of its departlane. Otherwise, the vehicle's speed and the distance to its leader are used to determine the position at which the vehicle can be inserted with maximum speed. This method tries to achieve a high flow by utilizing the room between vehicles better, avoiding scattering through time-discretisation.
  Caution:
  so far, it is a proof-of-concept, it may not work for all scenarios
  Caution:
  This method does not regard vehicles approaching from the back, it is meant to be used for inserting vehicles at the beginning of a network edge only
• "pwagGeneric": as "pwagSimple", but the position is determined iteratively.
  Caution:
  so far, it is rather a proof-of-concept, it may not work for all scenarios
  Caution:
  This method does not regard vehicles approaching from the back, it is meant to be used for inserting vehicles at the beginning of a network edge only

departSpeed

Determines the speed of the vehicle at insertion;

• ≥0: The vehicle is tried to be inserted using the given speed
• "random": A random speed between 0 and MIN(vehicle's maximum velocity, lane's maximum velocity) is used
• "max": The maximum velocity allowed for the vehicle on the chosen departure lane is used

arrivalLane

Not yet evaluated or incompletely implemented.

arrivalPos

Not yet evaluated or incompletely implemented.

arrivalSpeed

Not yet evaluated or incompletely implemented.

Route and vehicle type distributions

Instead of defining routes and vTypes explicitly for a vehicle SUMO can choose them at runtime from a given distribution. In order to use this feature just define distributions as following:

<routes>
    <vTypeDistribution id="typedist1">
        <vType id="type1" accel="0.8" length="5" maxSpeed="70" probability="0.9"/>
        <vType id="type2" accel="1.8" length="15" maxSpeed="50" probability="0.1"/>
    </vTypeDistribution>
</routes>

<routes>
    <routeDistribution id="routedist1">
        <route id="route0" color="1,1,0" edges="beg middle end rend" probability="0.9"/>
        <route id="route1" color="1,2,0" edges="beg middle end" probability="0.1"/>
    </routeDistribution>
</routes>

A distribution has only an id as (mandatory) attribute and needs a probability attribute for each of its child elements. The sum of the probability values needs not to be 1, they are scaled accordingly. At the moment the id for the childs is mandatory, this is likely to change in future versions.

A distribution can be used just as using individual types and routes:

<routes>
   <vehicle id="0" type="typedist1" route="routedist1" depart="0" color="1,0,0"/>
</routes>

Stops

Vehicles may be forced to stop for a defined time span or wait for persons by using the stop element either as part of a route or a vehicle definition as following:

<routes>
    <route id="route0" edges="beg middle end rend">
        <stop lane="middle_0" endPos="50" duration="20"/>
    </route>
    <vehicle id="v0" route="route0" depart="0">
        <stop lane="end_0" endPos="10" until="50"/>
    </vehicle>
</routes>

The resulting vehicle will stop twice, once at lane middle_0 because of the stop defined in its route and the second time because of the stop defined in the vehicle itself. The first stop will last 20 seconds the second one until simulation second 50. For a detailed list of attributes to stops see Specification#Stops. For a description on how to use them to simulate public transport see Simulation/Public Transport.