Definition of 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: 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.
 * a vehicle type which describes the vehicle's physical properties,
 * a route the vehicle shall take,
 * and the vehicle itself.

=Vehicles and Routes= As next, we will define a vehicle with a route owned by him only: 

 

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: 



 

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:

  

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 /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; BTW, I like "best" at most - dkrajzew
 * &ge;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

departPos
Determines the position on the chosen departure lane at which the vehicle is tried to be inserted;
 * &ge;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.

departSpeed
Determines the speed of the vehicle at insertion;
 * &ge;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.

=Vehicle Types= At first a vehicle type will be defined: 

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

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:

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.

Impatience
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 (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.

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. These shapes are used when setting the drawing mode for vehicles to simple shapes. 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" (8.25)
 * "bus/overland" (8.25)
 * "rail" (24.5)
 * "rail/light" (16.85)
 * "rail/city" (5.71)
 * "rail/slow" (9.44)
 * "rail/fast" (24.775)
 * "rail/cargo" (13.86)
 * "evehicle"

Some of these classes are drawn as a sequence of carriages. The length of a single carriage is indicated in brackes after the type. For these types, the length of the vehicleType is used as the overall length of the train (all carriages combined). For example, a vehicle with shape rail/cargo and length 70m will have 5 carriages. The number of carriages will always be a whole number and no carriage will be shorter than the length given in brackets but may be longer to meet the length requirements of the whole vehicle. When drawing vehicles with raster images, the image will be repeated for each carriage.

In addition, one can determine the width of the vehicle using the attribute width. 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.

To select a car following model the following syntax is used:  <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 (  ) 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:

   </vTypeDistribution>

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

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: <vehicle id="0" type="typedist1" route="routedist1" depart="0" color="1,0,0"/>

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

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

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. For a description on how to use them to simulate public transport see Simulation/Public Transport.