SUMO
Simulation of Urban MObility

- Home
- Download
- Documentation
- Wiki
- Trac
- Blog
- Contact
- SF-Project

# Definition of Vehicles, Vehicle Types, and Routes

Definition of Vehicles, Vehicle Types, and Routes
Filename extension | .rou.xml
Type of content | Vehicles, Vehicle Types, and Routes
Open format? | Yes
SUMO specific? | Yes
XML Schema | routes_file.xsd

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:

Attribute Name | Value Type | Description
--- | --- | ---
id | id (string) | The name of the vehicle type
accel | float | The acceleration ability of vehicles of this type (in m/s^2)
decel | float | The deceleration ability of vehicles of this type (in m/s^2)
sigma | float | The driver imperfection (between 0 and 1)
tau | float | The drivers reaction time in seconds, non-negative; default: 1
length | float | The vehicle's netto-length (length) (in m); default: 5m
minGap | float | Empty space after leader [m]; default: 2.5m
maxSpeed | float | The vehicle's maximum velocity (in m/s); default: 70.0m/s
speedFactor | float | The vehicles expected multiplicator for lane speed limits; defaults: 1.0
speedDev | float | The deviation of the speedFactor; default: 0.0; see below for details
color | RGB-color | This vehicle type's color; default: 1,1,0 (yellow)
vClass | class (enum) | An abstract vehicle class (see below); default: "unknown"
emissionClass | emission class (enum) | An abstract emission class (see below); default: "P_7_7"
guiShape | shape (enum) | How this vehicle is rendered; default: "unknown"
width | float | The vehicle's width [m] (only used for drawing); default: 2m
imgFile | filename (string) | Image file for rendering vehicles of this type (should be grayscale to allow functional coloring); default: ""

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.

Caution:
Using speed distributions is highly advisable to achieve realistic car following behaviour. If all vehicles have the same maximum speed on any given road, they will not be able to catch up with their lead vehicle causing unrealistic large headways

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

Caution:
Not all of these named shapes are implemented.

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.

Element | Short Name | Description
--- | --- | ---
carFollowing-Krauss | SUMOKrauß | The Krauß-model with some modifications which is the default model used in SUMO
carFollowing-KraussOrig1 | SKOrig | The original Krauß-model
carFollowing-PWagner2009 | PW2009 | A model by Peter Wagner, using Todosiev's action points
carFollowing-BKerner | Kerner | A model by Boris Kerner Caution: currently under work
carFollowing-IDM | IDM | The Intelligent Driver Model by Martin Treiber Caution: Problems with lane changing occur

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.

Attribute | Description | Models
--- | --- | ---
accel | The acceleration ability of vehicles of this type (in m/s^2) | SUMOKrauß, SKOrig, PW2009, Kerner, IDM
decel | The deceleration ability of vehicles of this type (in m/s^2) | SUMOKrauß, SKOrig, PW2009, Kerner, IDM
sigma | The driver imperfection (between 0 and 1) | SUMOKrauß, SKOrig
tau | The driver's reaction time in s | SUMOKrauß, SKOrig, PW2009, Kerner
timeHeadWay |  | IDM
minGap |  | SUMOKrauß, SKOrig, PW2009, Kerner, IDM
k |  | Kerner
phi |  | Kerner

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

Attribute Name | Value Type | Description
--- | --- | ---
id | id (string) | The name of the vehicle
type | float | The id of the vehicle type to use for this vehicle
route | id | The id of the route the vehicle shall drive along
color | color | This vehicle's color
depart | float (s) | The time step at which the vehicle shall enter the network
departLane | int/string (≥0, "random", "free", "allowed", "best") | The lane on which the vehicle shall be inserted.
departPos | float(m)/string ("random", "free", "random_free", "base", "pwagSimple", "pwagGeneric") | The position at which the vehicle shall enter the net; "free" means the point closest to the start of the departlane where it is possible to insert the vehicle. "random_free" tries forcefully to find a free random position and if that fails, places the vehicle at the next "free" position. "base" sets the vehicle's depart position to the vehicle's length + eps (eps=.1m), this means the vehicle is completely at the begin of the depart lane.
departSpeed | float(m/s)/string (≥0, "random", "max") | The speed with which the vehicle shall enter the network.
arrivalLane | int/string (≥0,"current") | The lane at which the vehicle shall leave the network
arrivalPos | float(m)/string (≥0(1), "random", "max") | The position at which the vehicle shall leave the network
arrivalSpeed | float(m/s)/string (≥0,"current") | The speed with which the vehicle shall leave the network

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

Attribute Name | Value Type | Description
--- | --- | ---
begin | float(s) | first vehicle departure time
end | float(s) | end of departure interval
vehsPerHour | float(#/h) | number of vehicles per hour (not together with period)
period | float(s) | repetition period (not together with vehsPerHour)
number | int(#) | total number of vehicles

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

Attribute Name | Value Type | Description
--- | --- | ---
id | id (string) | The name of the route
edges | id list | The edges the vehicle shall drive along, given as their ids, separated using spaces
color | color | This route's color

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.

Caution:
sumo may enter an infinite loop when given an unsorted route file with person definitions.

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

This page was last modified on 28 March 2013, at 11:32.