Definition of Vehicles, Vehicle Types, and Routes
|Type of content||Vehicles, Vehicle Types, and Routes|
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. It is not mandatory to define a vehicle type. If not given, a default type is used.
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|
|line||string||A string specifying the id of a public transport line which can be used when specifying person rides|
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>
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.
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.
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
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.
- "pwagGeneric": as "pwagSimple", but the position is determined iteratively.
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
Not yet evaluated or incompletely implemented.
Not yet evaluated or incompletely implemented.
Not yet evaluated or incompletely implemented.
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||Default||Description|
|id||id (string)||-||The name of the vehicle type|
|accel||float||2.6||The acceleration ability of vehicles of this type (in m/s^2)|
|decel||float||4.5||The deceleration ability of vehicles of this type (in m/s^2)|
|sigma||float||0.5||The driver imperfection (between 0 and 1)|
|tau||float||1.0||The drivers reaction time in seconds, non-negative|
|length||float||5.0||The vehicle's netto-length (length) (in m)|
|minGap||float||2.5||Empty space after leader [m]|
|maxSpeed||float||70.0||The vehicle's maximum velocity (in m/s)|
|speedFactor||float||1.0||The vehicles expected multiplicator for lane speed limits|
|speedDev||float||0.0||The deviation of the speedFactor; see below for details|
|color||RGB-color||"1,1,0" (yellow)||This vehicle type's color|
|vClass||class (enum)||"unknown"||An abstract vehicle class (see below)|
|emissionClass||emission class (enum)||"P_7_7"||An abstract emission class (see below)|
|guiShape||shape (enum)||"unknown"||How this vehicle is rendered|
|width||float||2.0||The vehicle's width [m] (only used for drawing)|
|imgFile||filename (string)||""||Image file for rendering vehicles of this type (should be grayscale to allow functional coloring)|
|impatience||float or 'off'||0.0||Willingess of drivers to impede vehicles with higher priority. See below for semantics.|
|laneChangeModel||lane changing model name (string)||'DK2008'||The model used for changing lanes|
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.
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.
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:
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 emission class. It is defined using the emissionClass attribute. Possible values are given in Models/Emissions and its subsections.
The impatience value represents a drivers willingness to impede vehicles with higher priority. At a value of 1 or above, the driver will use any gap that is safe in the sense of collision-avoidance even if it means that another vehicle has to brake as hard as it can. At a value of 0, the driver will not impede others initially. The impatience after waiting for n seconds is defined as vTypeImpatience + n/t where t is the value of --time-to-teleport (default 300 seconds). If a negative value is given, drivers will take even longer before reaching the maximum level of impatience. If impatience is set to off, drivers will not grow impatient.
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:
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.
The car-following models currently implemented in SUMO are given in the following table.
|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|
|carFollowing-IDM||IDM||The Intelligent Driver Model by Martin Treiber|
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.
|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|
|minGap||SUMOKrauß, SKOrig, PW2009, Kerner, IDM|
To select a car following model the following syntax is used:
<vType id="idm" length="5" minGap="2"> <carFollowing-IDM/> </vType>
Default Vehicle Type
If the type attribute of a vehicle is not defined it defaults to "DEFAULT_VEHTYPE". By defining a vehicle type with this id (<vType id="DEFAULT_VEHTYPE" ..../>) the default parameters for vehicles without an explicititly defined type can be changed.
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>
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.