• Basic Definition

In the following, the inputs needed by the simulation modules sumo and sumo-gui are described.

Input Files#

Road Network#

For a simulation, a SUMO Road Network must be given using the option --net-file <NETWORK_FILE> (or -n <NETWORK_FILE>). The network is normally built using netconvert or netgenerate.

Traffic Demand (Routes)#

The vehicles to simulate must be given. Their description normally includes vehicle types, vehicles, and vehicle routes. Routes are normally given to the simulation modules using the option --route-files <ROUTES_FILE>[,<ROUTES_FILE>]* (or -r <ROUTES_FILE>[,<ROUTES_FILE>]*). As you can see, you can use more than one route file within a single simulation run.

The reason is that route files are read incrementally to conserve memory and enable large simulations. All files given as parameter to --route-files <ROUTES_FILE>[,<ROUTES_FILE>]* are read step-wise. Starting at the begin time step, new routes are loaded every n time steps for the next n time steps. n may be controlled using the --route-steps <INT> where <=0 forces sumo/sumo-gui to load the file completely. Fetching routes for the next steps only implies that the vehicle types - or maybe "global" routes - must be given in prior to the routes that use them.

You may also give routes including vehicle definitions as additional-file to sumo/sumo-gui.

Additional Files#

One or more additional-file(s) are used to load additional entities:

• infrastructure related things: traffic light programs, induction loops and bus stops
• additional visualization: POIs and polygons (i.e. rivers and houses)
• dynamic simulation control structures: variable speed signs and rerouters
• demand related entities: vehicle types and routes

All these additional structures / definitions are given to the simulation using the --additional-files <FILE>[,<FILE>]*. Each file is read completely into memory and the list of files is processed from left to right.

Parsing Order#

To ensure the correct resolution of references, it is important to know what is loaded when. The order is as follows:

1. the network is read
2. the additional files are read (completely from top to bottom) in the order in which they are given in the option
3. the route files are opened and the first n steps are read
4. each n time steps, the routes for the next n time steps are read

Defining the Time Period to Simulate#

Each simulation requires the definition about the time period to be simulated. This is given to sumo or sumo-gui using the options --begin <TIME> (or -b <TIME> for short) and --end <TIME> (-e <TIME>). Please note that whether the option --end was given influences the simulation's behavior. The details are described below.

The simulation starts at the time given in --begin, which defaults to 0. All vehicles with a departure time (depart) lower than the begin time are discarded.

The simulation performs each time step one-by-one.

The simulation ends in the following cases:

• The final time step was given using --end and this time step was reached (time after a step is >= end).
• No value for --end has been given and all vehicles have been simulated. The state of the simulation is the one in which the last vehicle has left the simulated area. If a TraCI connection is active, the simulation will continue even after the last vehicle (potentially "forever").
• A close command has been received via TraCI

Defining the Time Step Length#

sumo/sumo-gui use a time step of one second per default. You may override this using the --step-length <TIME> option. <TIME> is by giving a value in seconds between [0.001 and 1.0].

Example: --step-length 0.01 will run the simulation using time steps of 10ms.

Setting a lower step-length has many consequences:

• the simulation takes longer to simulate a given amount of time (because it needs more steps to do so)
• the generated movements are generally smoother
• vehicle insertion and lane changing succeed more often in a given amount of time since the conditions are checked more often
• the frequency of vehicle speed adaptation increases unless prevented by setting action-step-length (see below)

Defining the Action Step Length#

Specifying the option --default.action-step-length <TIME> implies that vehicles perform calculations for the adaption of accelerations or lane-change maneuvers only at intervals of the given length and not within every simulations step (which is the default). Using an action-step-length different from the simulation step length automatically switches the integration method to 'ballistic'.

Choosing the action step length larger than the simulation step length may speed up the simulation, but note that a value larger than the assumed reaction time tau may induce collisions. See the description of vehicle type and car-following parameters for details.

Defining the Integration Method#

There are two numerical integration methods available, which control the dynamical update of the simulation. Currently, the default is an Euler update, which considers the vehicle's speed constant during one time step. As an alternative, SUMO offers the ballistic update, which considers the acceleration constant during one time step. It can be activated by giving the option --step-method.ballistic or including the following into the configuration file:

<processing>
   <step-method.ballistic value="true"/>
</processing>

Especially for larger time-steps (e.g. 1sec.) ballistic update yields more realistic dynamics for car-following models based on continuous dynamics. See also Martin Treiber, Venkatesan Kanagaraj, Comparing Numerical Integration Schemes for Time-Continuous Car-Following Models.

Ballistic update causes positions to be updated with the average speed between time steps instead of the speed of the current time step. Consider this example with step-length 1s:

Vehicle at position x drives with speed 4.5m/s in step t and brakes to speed 0 in step t+1.

• Euler-update: Vehicle is stopped at position x in step t+1 (instant deceleration)
• Ballistic-update: Vehicle is stopped at position x + 2.25 in step t+1 (continuous deceleration)