From Sumo
Revision as of 06:30, 3 August 2015 by Namdre (talk | contribs) (corrected option help)
Jump to navigation Jump to search

From 30.000 feet

SUMO is the simulation itself; it is a microscopic, space-continuous, and time-discrete traffic flow simulation.

Purpose: Simulates a defined scenario
System: portable (Linux/Windows is tested); runs on command line
Input (mandatory):
A) a road network as generated via NETCONVERT or NETGENERATE, see Building Networks
B) a set of routes (as generated by DUAROUTER, JTRROUTER, DFROUTER, or ACTIVITYGEN, see also Definition of Vehicles, Vehicle Types, and Routes)
Input (optional): Additional definitions of traffic lights, variable speed signs, output detectors etc.
Output: SUMO allows to generate a wide set of outputs; visualization is done using SUMO-GUI
Programming Language: C++

Usage Description


You may use a XML schema definition file for setting up a SUMO configuration: sumoConfiguration.xsd.


Option Description
-c <FILE>
--configuration-file <FILE>
Loads the named config on startup
--save-configuration <FILE> Saves current configuration into FILE
--save-template <FILE> Saves a configuration template (empty) into FILE
--save-schema <FILE> Saves the configuration schema into FILE
--save-commented <BOOL> Adds comments to saved template, configuration, or schema; default: false


Option Description
-n <FILE>
--net-file <FILE>
Load road network description from FILE
-r <FILE>
--route-files <FILE>
Load routes descriptions from FILE(s)
-a <FILE>
--additional-files <FILE>
Load further descriptions from FILE(s)
-w <FILE>
--weight-files <FILE>
Load edge/lane weights for online rerouting from FILE
--weight-attribute <STRING>
Name of the xml attribute which gives the edge weight; default: traveltime
--load-state <FILE> Loads a network state from FILE
--load-state.offset <TIME> Sets the time offset for vehicle segment exit times; default: 0


Option Description
--output-prefix <FILE> Prefix which is applied to all output files. The special string 'TIME' is replaced by the current time.
--netstate-dump <FILE> Save complete network states into FILE
--netstate-dump.empty-edges <BOOL> Write also empty edges completely when dumping; default: false
--netstate-dump.precision <INT> Write positions and speeds with the given precision (default 2); default: 2
--emission-output <FILE> Save the emission values of each vehicle
--fcd-output <FILE> Save the Floating Car Data
--fcd-output.geo <BOOL> Save the Floating Car Data using geo-coordinates (lon/lat); default: false
--fcd-output.signals <BOOL> Add the vehicle signal state to the FCD output (brake lights etc.); default: false
--full-output <FILE> Save a lot of information for each timestep (very redundant)
--queue-output <FILE> Save the vehicle queues at the junctions (experimental)
--vtk-output <FILE> Save complete vehicle positions inclusive speed values in the VTK Format (usage: /path/out will produce /path/out_$TIMESTEP$.vtp files)
--amitran-output <FILE> Save the vehicle trajectories in the Amitran format
--summary-output <FILE> Save aggregated vehicle departure info into FILE
--tripinfo-output <FILE> Save single vehicle trip info into FILE
--tripinfo-output.write-unfinished <BOOL> Write tripinfo output for vehicles which have not arrived at simulation end; default: false
--vehroute-output <FILE> Save single vehicle route info into FILE
--vehroute-output.exit-times <BOOL> Write the exit times for all edges; default: false
--vehroute-output.last-route <BOOL> Write the last route only; default: false
--vehroute-output.sorted <BOOL> Sorts the output by departure time; default: false
--vehroute-output.dua <BOOL> Write the output in the duarouter alternatives style; default: false
--vehroute-output.intended-depart <BOOL> Write the output with the intended instead of the real departure time; default: false
--vehroute-output.write-unfinished <BOOL> Write vehroute output for vehicles which have not arrived at simulation end; default: false
--link-output <FILE> Save links states into FILE
--bt-output <FILE> Save bt visibilities into FILE
--save-state.times {{DT_INT[]}} Use INT[] as times at which a network state written
--save-state.prefix <FILE> Prefix for network states; default: state
--save-state.files <FILE> Files for network states


Option Description
-b <TIME>
--begin <TIME>
Defines the begin time; The simulation starts at this time; default: 0
-e <TIME>
--end <TIME>
Defines the end time; The simulation ends at this time; default: -1
--step-length <TIME> Defines the step duration; default: 1


Option Description
-s <TIME>
--route-steps <TIME>
Load routes for the next number of seconds ahead; default: 200
--no-internal-links <BOOL> Disable (junction) internal links; default: false
--ignore-junction-blocker <TIME> Ignore vehicles which block the junction after they have been standing for SECONDS (-1 means never ignore); default: -1
--ignore-accidents <BOOL> Do not check whether accidents occur; default: false
--ignore-route-errors <BOOL> Do not check whether routes are connected; default: false
--max-num-vehicles <INT> Quit simulation if this number of vehicles is exceeded; default: -1
--scale <FLOAT> Scale demand by the given factor (by discarding or duplicating vehicles)
--time-to-teleport <TIME> Specify how long a vehicle may wait until being teleported, defaults to 300, non-positive values disable teleporting; default: 300
--time-to-teleport.highways <TIME> The waiting time after which vehicles on a fast road (speed > 69m/s) are teleported if they are on a non-continuing lane; default: 0
--max-depart-delay <TIME> How long vehicles wait for departure before being skipped, defaults to -1 which means vehicles are never skipped; default: -1
--sloppy-insert <BOOL> Whether insertion on an edge shall not be repeated in same step once failed; default: false
--eager-insert <BOOL> Whether each vehicle is checked separately for insertion on an edge; default: false
--random-depart-offset <TIME> Each vehicle receives a random offset to its depart value drawn uniformly from [0, TIME]; default: 0
--lanechange.allow-swap <BOOL> Whether blocking vehicles trying to change lanes may be swapped; default: false
--lanechange.duration <TIME> Duration of a lane change maneuver (default 0); default: 0
--lanechange.overtake-right <BOOL> Whether overtaking on the right on motorways is permitted; default: false
--pedestrian.model <STRING> Select among pedestrian models ['nonInteracting', 'striping']; default: striping
--pedestrian.striping.stripe-width <FLOAT> Width of parallel stripes for segmenting a sidewalk (meters) for use with model 'striping'; default: 0.65
--pedestrian.striping.dawdling <FLOAT> factor for random slow-downs [0,1] for use with model 'striping'; default: 0.2
--pedestrian.striping.jamtime <TIME> Time in seconds after which pedestrians start squeezing through a jam when using model 'striping' (non-positive values disable squeezing); default: 300


Option Description
--routing-algorithm <STRING> Select among routing algorithms ['dijkstra', 'astar', 'CH', 'CHWrapper']; default: dijkstra
--weights.random-factor <FLOAT> Edge weights for routing are dynamically disturbed by a random factor between [1,FLOAT]
--device.rerouting.probability <FLOAT> The probability for a vehicle to have a 'rerouting' device; default: 0
--device.rerouting.explicit <STRING> Assign a 'rerouting' device to named vehicles
--device.rerouting.deterministic <BOOL> The 'rerouting' devices are set deterministic using a fraction of 1000; default: false
--device.rerouting.period <TIME> The period with which the vehicle shall be rerouted; default: 0
--device.rerouting.pre-period <TIME> The rerouting period before depart; default: 1
--device.rerouting.adaptation-weight <FLOAT> The weight of prior edge weights; default: 0.5
--device.rerouting.adaptation-interval <TIME> The interval for updating the edge weights; default: 1
--device.rerouting.with-taz <BOOL> Use zones (districts) as routing end points; default: false
--device.rerouting.init-with-loaded-weights <BOOL> Use given weight files for initializing edge weights; default: false
--device.rerouting.shortest-path-file <FILE> Initialize lookup table for astar from the given distance matrix
--device.rerouting.threads <INT> The number of parallel execution threads used for rerouting; default: 0
--device.rerouting.output <FILE> Save adapting weights to FILE


Option Description
-v <BOOL>
--verbose <BOOL>
Switches to verbose output; default: false
--print-options <BOOL> Prints option values before processing; default: false
-? <BOOL>
--help <BOOL>
Prints this screen; default: false
--version <BOOL>
Prints the current version; default: false
--xml-validation <STRING>
Set schema validation scheme of XML inputs ("never", "auto" or "always"); default: auto <STRING> Set schema validation scheme of SUMO network inputs ("never", "auto" or "always"); default: never
--no-warnings <BOOL>
Disables output of warnings; default: false
-l <FILE>
--log <FILE>
Writes all messages to FILE (implies verbose)
--message-log <FILE> Writes all non-error messages to FILE (implies verbose)
--error-log <FILE> Writes all warnings and errors to FILE
--no-duration-log <BOOL> Disable performance reports for individual simulation steps; default: false
--no-step-log <BOOL> Disable console output of current simulation step; default: false


Option Description
--phemlight-path <FILE> Determines where to load PHEMlight definitions from.; default: ./PHEMlight/
--device.emissions.probability <FLOAT> The probability for a vehicle to have a 'emissions' device; default: 0
--device.emissions.explicit <STRING> Assign a 'emissions' device to named vehicles
--device.emissions.deterministic <BOOL> The 'emissions' devices are set deterministic using a fraction of 1000; default: false


Option Description
--device.btreceiver.probability <FLOAT> The probability for a vehicle to have a 'btreceiver' device; default: 0
--device.btreceiver.explicit <STRING> Assign a 'btreceiver' device to named vehicles
--device.btreceiver.deterministic <BOOL> The 'btreceiver' devices are set deterministic using a fraction of 1000; default: false
--device.btreceiver.range <FLOAT> The range of the bt receiver; default: 300
--device.btreceiver.all-recognitions <BOOL> Whether all recognition point shall be written; default: false
--device.btreceiver.offtime <FLOAT> The offtime used for calculating detection probability (in seconds); default: 0.64
--device.btsender.probability <FLOAT> The probability for a vehicle to have a 'btsender' device; default: 0
--device.btsender.explicit <STRING> Assign a 'btsender' device to named vehicles
--device.btsender.deterministic <BOOL> The 'btsender' devices are set deterministic using a fraction of 1000; default: false

Example Device

Option Description
--device.example.explicit <STRING> Assign a device to named vehicles
--device.example.parameter <FLOAT> An exemplary parameter which can be used by all instances of the example device; default: 0

Traci Server

Option Description
--remote-port <INT> Enables TraCI Server if set; default: 0

Random Number

Option Description
--random <BOOL> Initialises the random number generator with the current system time; default: false
--seed <INT> Initialises the random number generator with the given value; default: 23423

Gui Only

Option Description
--gui-settings-file <FILE> Load visualisation settings from FILE
--quit-on-end <BOOL>
Quits the GUI when the simulation stops; default: false
--game <BOOL>
Start the GUI in gaming mode; default: false
--start <BOOL>
Start the simulation after loading; default: false
--disable-textures <BOOL>
Do not load background pictures; default: false

Loading order of input files

Whenever a simulation object A (such as a vehicle) defined in an input file refers to another simulation object B (such as a vehicle type), the corresponding object B must be defined before A either by being put into a file that is loaded earlier, or by being put into the same file on an earlier line.

This is of particular importance in regard to files loaded with the options --route-files <FILE> and --additional-files <FILE>. The most important feature of the option --route-files <FILE> is that it loads the files incrementally thus saving memory. The option --additional-files <FILE> is handled before option --route-files <FILE> and the given files are fully loaded before the simulation starts. Some objects must be available at the start of the simulation (such as output objects) and thus need to be loaded with this option, but is also useful for loading things referenced by route files. (Note, that all items which can be put into a route-file can also be put into an additional-file. When multiple files are given as a comma-separated list, they are loaded from left to right.

Format of additional files

Files loaded with the option --additional-files <FILE> may included a wide range of network elements such as traffic light programs, detector definitions, variable speed signs and bus stops. Also, any element permitted in a route file such as vTypes, routes and vehicles can be added. All elements may be put into the same additional file or they may be grouped into multiple files as convenient.

The additional file always needs a top level tag with arbitrary name (additional is customary). An example file is given below:

    <inductionLoop id="myLoop1" lane="foo_0" pos="42" freq="900" file="out.xml"/>
    <inductionLoop id="myLoop2" lane="foo_2" pos="42" freq="900" file="out.xml"/>
    <busStop id="station1" lane="foo_0" startPos="5" endPos="20"/>

    <vType id="bus" maxSpeed="20" length="12"/>

Insertion of vehicles

Vehicles are inserted into the simulation at the time of their departure (or with a slight delay if the option --random-depart-offset is used). If there is insufficient space for inserting the vehicle at that time it is put into an insertion queue and insertion is repeatedly attempted in subsequent simulation steps. If the option --max-depart-delay <TIME> is used, vehicles are discarded after <TIME> seconds.

There are two methods for inserting vehicles into the simulation:

  1. try to insert every vehicle in every simulation step
  2. for every edge with vehicles to insert, abort trying to insert vehicles after one of the vehicles could not be inserted

In an uncongested networks these methods behave similar but in a congested network with lots of vehicles which cannot be inserted variant 2) is much faster. In older version of sumo 1) was the default and one could switch to 2) using the option --sloppy-insert Since version 0.18.0, variant 2) is the default and one may switch to 1) using the option --eager-insert.