Difference between revisions of "Specification"

From Sumo
Jump to navigation Jump to search
m (its classed vclass in [Definition_of_Vehicles,_Vehicle_Types,_and_Routes])
(Stops: documenting minimum stop length)
Line 213: Line 213:
 
If "duration" ''and'' "until" are given, the vehicle will stop for at least "duration" seconds. If "duration" is 0 the vehicle will decelerate such that it may in principle reach velocity 0 but instead of braking to full stop it will start to accelerate again.
 
If "duration" ''and'' "until" are given, the vehicle will stop for at least "duration" seconds. If "duration" is 0 the vehicle will decelerate such that it may in principle reach velocity 0 but instead of braking to full stop it will start to accelerate again.
 
If "until" is given and "duration" is not and the vehicle arrives at the stop at or after the time step defined by "until" it will not even decelerate. If until is defined in the context of a repeated vehicle emission (flow) it will be incremented by the difference of vehicle creation time and "begin" of the flow. If neither "duration" nor "until" are given, "triggered" defaults to true. If "triggered" is set to false explicitly the vehicle will stop forever.
 
If "until" is given and "duration" is not and the vehicle arrives at the stop at or after the time step defined by "until" it will not even decelerate. If until is defined in the context of a repeated vehicle emission (flow) it will be incremented by the difference of vehicle creation time and "begin" of the flow. If neither "duration" nor "until" are given, "triggered" defaults to true. If "triggered" is set to false explicitly the vehicle will stop forever.
 +
{{Note|Bus stops must have a length of at least 10}}
  
 
==How the vehicle drives==
 
==How the vehicle drives==

Revision as of 09:37, 4 November 2010

This document focuses on the main parts of a traffic simulation, that is streets (edges) including lanes, junctions (nodes), and vehicles with their routes. It contains nothing about traffic lights, detectors, visualization or stuff like that. On the other hand this document aims at a precise description which serves as a template for implementation as well as for an xml schema for the input files. Therefore there is a table for all allowed attributes together with their type (and possibly unit). If the attribute is not mandatory, a default value is defined as well. The names of all elements and attributes consist of letters (lowercase or camelCaps) and underscores only. Keep in mind that the values of attributes which are ids should consist of letters, numbers, and underscores, hyphens, points and colons only, starting with a letter or an underscore (this is called "valid XML id" in the following). There is also a "follow-up" to this document on the simulation of persons and multi-modality

Vehicles

A single vehicle is not modeled, it is always the vehicle on a journey, that means once a vehicle has reached its destination it is deleted from the system and cannot be referenced any longer. The physical parameters of the vehicle are defined with its type, which also defines its membership in some vehicle categories. A vehicle is defined by the combination of its type and its route, together with parameters specifying the start and end behavior. Additional parameters such as color only serve visualization purposes. A vehicle can have routes and stops as child elements.

Attribute Type Range Default Remark
id string valid XML ids -
route string route or routedist id - either this id or a route child element are mandatory
type string vtype or vtypedist id default type
depart float(s) ≥0 -(1)
departlane int/string ≥0,"random","free","departlane" "departlane" "free" is the least occupied lane (by sum of the vehicle lengths)
departpos float(m)/string ≥0(2),"random","free","random_free","base" "base" "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" 0 "max" refers to the maximum velocity the vehicle can achieve when being inserted
arrivallane int/string ≥0,"current" "current"
arrivalpos float(m)/string ≥0(2),"random","max" "max"
arrivalspeed float(m/s)/string ≥0,"current" "current"
  • (1): The depart attribute may become optional once we have person simulation where the arrival of a person triggers the departure of a vehicle.
  • (2): in fact, negative positions are currently allowed, too. In this case, this value is added to the lane's length. This means, the position is counted from the end of the lane. Values lying beyond the edge borders (positive and negative) are silently moved to the closest edge border.
Caution:
Please note that departpos "base" is currently only available in the SVN. Up to including version 0.12, the default for departpos was 0.
This page should be revisited after the next release.

Flows (repeated emission)

A repeated vehicle emission has the same attributes and child elements as a single vehicle except for depart. The following additional attributes are known:

Attribute Type Range Default Remark
begin float(s) ≥0 simulation begin
end float(s) ≥begin simulation end
vehsPerHour float(#/h) >0 -
period float(s) ≥0 -
no int(#) >0 -

At most one of "vehsPerHour" and "period" has to be given. If one of them is given it is not allowed to define "period" and "end". The vehicles are equally distributed in the time interval. The number of vehicles emitted (if "no" is not given) is equal to ("end"-"begin")/"period" rounded to the nearest integer, thus if "period" is small enough, there might be no vehicle at all. Furthermore "period"=3600/"vehsPerHour". The first vehicle (if any) is always created at time "begin". The id of the created vehicles is "flowId.runningNumber".

Types

Types define physical parameters such as length, acceleration, decelaration and maximum speed and give a list of categories cars of this type belong to. All theses parameters are identical among all vehicles of a type.

Attribute Type Range Default Remark
id string valid XML ids - This attribute is mandatory.
vclass string list of category ids empty list
accel float(m/s2) ≥0 2.6 the real acceleration is calculated as (1-speed/maxspeed)*accel
decel float(m/s2) ≥0 4.5
sigma float 0≤sigma≤1 0.5
length float(m) >0 5
maxspeed float(m/s) >0 70
tau float >0 1
carFollowModel string model id (at the moment only Krauss) Krauss This is for future implementation of different driver behavior (car following) models
laneChangeModel string model id (at the moment only dkrajzew2008) dkrajzew2008 This is for future implementation of different driver behavior (lane changing) models
speedFactor float >0 1 the factor by which the driver multiplies the speed read from street signs to estimate "real" maximum allowed speed
speedDev float ≥0 0 the standard deviation of the estimated maximum speed (see speed factor) divided by this speed.
probability float >0 1 this is only useful in distributions

There is a default type defined with the id "DEFAULT_VEHTYPE", having all the default parameters above, which may be redefined once but only if it was not used beforehand (either by a vehicle or as a refid). Redefining the default type does not change the defaults if defining a new type, that means <vtype refid="DEFAULT_VEHTYPE"/> may be different from <vtype/>.

Type distributions

Type distributions define probability distributions of vehicle types. They should have at least two vtype childs, although defining only one child is valid as well. All vehicle type childs maybe referenced outside the distribution as well. The sum of the probabilities of the childs should be larger than zero.

Attribute Type Range Default Remark
id string valid XML ids - This attribute is mandatory

Categories

Categories define vehicle classes such as cars, trucks, busses, but also height, width and weight categories might (to some extent) be modeled here. The sole purpose of the category is to determine whether a car is allowed to (or prefers to) drive on a certain street or lane.

Attribute Type Range Default Remark
id string valid XML ids -
description string description of the category - serves only documentation and visualization purposes

Junctions

Strictly speaking, junctions or nodes need a unique id, which makes them referenceable by streets which start or end there. Since our network is always embedded into the plane, they also need x- and y-coordinates. A type may be given if the one determined by NETCONVERT is not correct.

Attribute Type Range Default Remark
id string valid XML ids -
x float(m) -10^6<x<10^6 -
y float(m) -10^6<y<10^6 -
type string priority, right_before_left, traffic_light - if no value is given, NETCONVERT tries to determine the type heuristically

Streets

Streets need a unique id, a starting node and an ending node. Since the nodes are embedded into the plane, the length is optional and (if not given) is calculated as the euclidean distance between starting node and end node. There may be further points in the plane (no junctions) given to describe the shape of the street respectively calculating its length as the cumulative distance. The length has to be strictly positive (not zero). This means that if starting node and end node are identical, the length has either to be given explicitly or there needs to be at least one shape node at a position different from the start/end node. Optionally a number of lanes may be given (defaulting to 1, respectively to the number of lane elements in the definition of the street). If the number of lanes given as an attribute is smaller than the number of lane child elements this is an error. All parameters which can be given to lanes can also be given to the street and serve as a default for the corresponding lane parameter. The maximum speed allowed on the edge is given in m/s.

Attribute Type Range Default Remark
id string valid XML ids -
refid string another edge id - all attributes and childs are copied from the given edge and maybe overwritten
from(1) string node id -
to(2) string node id -
function string normal,internal,ramp normal cannot be given as input, appears only in generated nets
length float(m) ≥0 -
nolanes int >0 - either this one or lane child elements are mandatory
speed float(m/s) >0 -
departlane int 0≤departlane<nolanes 0
  • (1) currently named "fromnode", in fact
  • (2) currently named "tonode", in fact

Lanes

Lanes have a maximum allowed speed, and lists of allowed, disallowed and preferred vehicle categories. The allowed list defaults to all vehicle categories and the disallowed list to none. A vehicle is allowed to drive on a lane if its category list contains no member of the disallowed list and contains some member of the allowed list.

Attribute Type Range Default Remark
index int 0≤index<edge.nolanes smallest non-explicit index
maxspeed float(m/s) ≥0 13.9
allow string list of category ids,all all
disallow string list of category ids empty list
prefer string list of category ids empty list

Routes

Routes give a description of the path a vehicle will follow, that is they merely consist of a non-empty list of streets which are consecutive. Optionally they can have a list of stops as child elements.

Attribute Type Range Default Remark
id string valid XML ids - The attribute is disallowed for routes defined inside a vehicle or a route distribution.
refid string another route id -
edges string list of edge ids -
repeat int >0 1 This is the same as connecting "repeat" times the edge list
frequency float >0 1 This only useful in connection with route distributions

Route distributions

Route distributions define probability distributions of routes. They should have at least two route childs.

Attribute Type Range Default Remark
id string valid XML ids -

Stops

Stops can be childs of vehicles, routes or persons.

Attribute Type Range Default Remark
bus_stop string valid busStop ids - if given, edge, lane, startpos and endpos are not allowed
edge string edge id - the edge has to be part of the corresponding route
lane int 0≤lane≤edge.nolanes 0
endpos float(m) ε≤endpos≤edge.length edge.length
startpos float(m) 0≤startpos≤endpos-ε endpos-ε
duration float(s) ≥0 -
until float(s) ≥0 - the time step at which the route continues
index int, "end", "fit" 0≤index≤number of stops in the route "end" where to insert the stop in the vehicle's list of stops
triggered bool true,false false whether a person may end the stop
parking bool true,false false whether the vehicle stops on the road or beside

If "duration" and "until" are given, the vehicle will stop for at least "duration" seconds. If "duration" is 0 the vehicle will decelerate such that it may in principle reach velocity 0 but instead of braking to full stop it will start to accelerate again. If "until" is given and "duration" is not and the vehicle arrives at the stop at or after the time step defined by "until" it will not even decelerate. If until is defined in the context of a repeated vehicle emission (flow) it will be incremented by the difference of vehicle creation time and "begin" of the flow. If neither "duration" nor "until" are given, "triggered" defaults to true. If "triggered" is set to false explicitly the vehicle will stop forever.

Note:
Bus stops must have a length of at least 10

How the vehicle drives

Before start

On route loading (which is not necessarily the same as application startup) Sumo checks the route for connectivity and for proper placement of stops. On vehicle loading it also checks whether the vehicle is allowed to drive on all edges of its route and whether all other parameters are in the allowed ranges. If any violation of parameter ranges occurs, the simulation stops immediately with an error message. (It is still in discussion whether it should be possible to disable some of the checks via a command-line option, resulting in a vehicle which stops at the end of the last "valid" edge.)

Departure

At the given departure time the simulation tries to insert the vehicle with the given parameters. If this is not possible because it would result in a collision, the simulation retries in the next simulation step. If "free" or "random" are specified for startpos and/or startlane, they are recalculated for the next try. The parameters are evaluated in the following order:

  1. Determination of the lane
  2. Determination of the position (even if lane and position are both set to "free", we do not choose a different lane if we cannot find a free position on the lane chosen)
  3. Determination of the start speed (if position is "free" and speed is "max" we do not choose the position where we can reach the highest speed but choose the highest speed we can use at the position chosen before).

When determining the maximum speed and the possibility of insertion the next vehicle(s) upstream and the next vehicle(s) downstream have to be respected even if they are located on the next road section. Thus it may be necessary to take all road sections into account which lead into or follow the current section.

For filling the simulation as fast as possible with vehicles, use the following parameters for the vehicle: depart="0" departspeed="0" departlane="free" departpos="random_free" period="0" repno="100". Thus, 101 vehicles will be emitted at timestep 0 on the first edge of the given route.

Driving

At each step the model calculates a new target speed and accelerates (decelerates) the vehicle accordingly. The acceleration is constant for the step such that a car which is at position s with speed v and gets during the step an acceleration of a has after a timestep of length t the new position s' = s + v*t + a*t^2/2 and v' = v + a*t.

Stops

A vehicle tries to reach the most downstream position of a stop area before it actually stops. It can only be forced to stop earlier by other vehicles blocking the rest of the stop area. The duration of the stop starts counting with the first step in which the vehicle's position is in the stop area and its speed is 0. That means if a vehicle stops at timestep 10 (reaches the area and speed 0) and has a stop duration of 2, it stays there for step 11 and 12 and has a new speed and position in step 13 (provided no other blocking occurs).

End

If the vehicle reaches the point of final destination it is removed from the simulation. That means if the s' as calculated above is larger or equal to the destination point, the vehicle gets removed in this step.