marouter

# From 30.000 feet

marouter computes a macroscopic user assignment (routes) to be loaded into sumo from various inputs (Origin-Destination-Matrices, trip files or route files).

- Purpose: Macroscopic route assignment
- 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) O/D matrix or trips
- Output: Definition of Vehicles, Vehicle Types, and Routes usable by sumo
- Programming Language: C++

# Usage Description

marouter computes a user assignment (routes) with a configurable assignment method (using option assignment-method):

- incremental

- UE: user equilibrium

  Caution

  Not yet implemented

- SUE: stochastic user equilibrium

marouter uses a hard-coded capacity-constraint function based on speed limit, lane number and edge priority to compute traveltimes and flows based on density. For details, see functions capacityConstraintFunction and getCapacity in <SUMO_HOME>/src/marouter/ROMAAssignments.cpp.

marouter reads OD matrices and creates route files. These route files contain route distributions between traffic assignment zones. Each route in the distribution is a fully specified list of network edges.

## Microscopic Outputs

One of the main usages of marouter is to compute a User Assignment. To this end it generates `<flow>` definitions with fully specified routes that can be loaded into sumo and sumo-gui.

## Macroscopic Outputs

marouter can create macroscopic traffic data for all network edges by using the option --netload-output. These values can either be written aggregated for the whole day (default) or split into intervals according to the time-granularity of the input data and the value of option --aggregation-interval).

For each interval and each edge the following values are written:

- travelTime: average travel time on that edge
- speed: average speed on that edge
- entered: the number of vehicles that entered the edge in the interval
- density: the number of vehicles per km
- laneDensity: the number of vehicles per km per lane
- flowCapacityRatio: the proportion of total capacity used in %

This output can visualized in sumo-gui to understand how the different traffic measures change over time.

## Options

You may use a XML schema definition file for setting up a marouter configuration: marouterConfiguration.xsd.

### Configuration

Option | Description
--- | ---
-c <FILE> --configuration-file <FILE> | Loads the named config on startup
-C <FILE> --save-configuration <FILE> | Saves current configuration into FILE
--save-configuration.relative <BOOL> | Enforce relative paths when saving the configuration; default: false
--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

### Input

Option | Description
--- | ---
-n <FILE> --net-file <FILE> | Use FILE as SUMO-network to route on
-d <FILE> --additional-files <FILE> | Read additional network data (districts, bus stops) from FILE(s)
-r <FILE> --route-files <FILE> | Read sumo routes, alternatives, flows, and trips from FILE(s)
--phemlight-path <FILE> | Determines where to load PHEMlight definitions from; default: ./PHEMlight/
--phemlight-year <INT> | Enable fleet age modelling with the given reference year in PHEMlight5; default: 0
--phemlight-temperature <FLOAT> | Set ambient temperature to correct NOx emissions in PHEMlight5; default: 1.79769e+308
-w <FILE> --weight-files <FILE> | Read network weights from FILE(s)
--lane-weight-files <FILE> | Read lane-based network weights from FILE(s)
-x <STRING> --weight-attribute <STRING> | Name of the xml attribute which gives the edge weight; default: traveltime
--junction-taz <BOOL> | Initialize a TAZ for every junction to use attributes toJunction and fromJunction; default: false
-m <FILE> --od-matrix-files <FILE> | Loads O/D-files from FILE(s)
--od-amitran-files <FILE> | Loads O/D-matrix in Amitran format from FILE(s)
-z <FILE> --tazrelation-files <FILE> | Loads O/D-matrix in tazRelation format from FILE(s)
--tazrelation-attribute <STRING> | Define data attribute for loading counts (default 'count'); default: count
--weight-adaption <FLOAT> | The travel time influence of prior intervals; default: 0
--taz-param | Parameter key(s) defining source (and sink) taz
--ignore-taz <BOOL> | Ignore attributes 'fromTaz' and 'toTaz'; default: false

### Output

Option | Description
--- | ---
-o <FILE> --output-file <FILE> | Write generated routes to FILE
--vtype-output <FILE> | Write used vehicle types into separate FILE
--keep-vtype-distributions <BOOL> | Keep vTypeDistribution ids when writing vehicles and their types; default: false
--emissions.volumetric-fuel <BOOL> | Return fuel consumption values in (legacy) unit l instead of mg; default: false
--named-routes <BOOL> | Write vehicles that reference routes by their id; default: false
--write-license <BOOL> | Include license info into every output file; default: false
--output-prefix <STRING> | Prefix which is applied to all output files. The special string 'TIME' is replaced by the current time.
--precision <INT> | Defines the number of digits after the comma for floating point output; default: 2
--precision.geo <INT> | Defines the number of digits after the comma for lon,lat output; default: 6
-H <BOOL> --human-readable-time <BOOL> | Write time values as hour:minute:second or day:hour:minute:second rather than seconds; default: false
--ignore-vehicle-type <BOOL> | Does not save vtype information; default: false
--netload-output <FILE> | Writes edge loads and final costs into FILE
--all-pairs-output <FILE> | Writes complete distance matrix into FILE
--exit-times <BOOL> | Write exit times (weights) for each edge; default: false

### Processing

Option | Description
--- | ---
--max-alternatives <INT> | Prune the number of alternatives to INT; default: 5
--with-taz <BOOL> | Use origin and destination zones (districts) for in- and output; default: false
--routing-threads <INT> | The number of parallel execution threads used for routing; default: 0
--routing-algorithm <STRING> | Select among routing algorithms ['dijkstra', 'astar', 'CH', 'CHWrapper']; default: dijkstra
--restriction-params | Comma separated list of param keys to compare for additional restrictions
--weights.interpolate <BOOL> | Interpolate edge weights at interval boundaries; default: false
--weights.expand <BOOL> | Expand the end of the last loaded weight interval to infinity; default: false
--weights.minor-penalty <FLOAT> | Apply the given time penalty when computing routing costs for minor-link internal lanes; default: 1.5
--aggregation-interval <TIME> | Defines the time interval when aggregating single vehicle input; Defaults to one hour; default: 3600
--capacities.default <BOOL> | Ignore edge priorities when calculating capacities and restraints; default: false
--weights.priority-factor <FLOAT> | Consider edge priorities in addition to travel times, weighted by factor; default: 0
--bulk-routing.vtypes <BOOL> | Aggregate routing queries with the same origin for different vehicle types; default: false
--weight-period <TIME> | Aggregation period for the given weight files; triggers rebuilding of Contraction Hierarchy; default: 3600
-s <FLOAT> --scale <FLOAT> | Scales the loaded flows by FLOAT; default: 1
--vtype <STRING> | Defines the name of the vehicle type to use
--prefix <STRING> | Defines the prefix for vehicle flow names
--timeline | Uses STR[] as a timeline definition
--timeline.day-in-hours <BOOL> | Uses STR as a 24h-timeline definition; default: false
--additive-traffic <BOOL> | Keep traffic flows of all time slots in the net; default: false
--assignment-method <STRING> | Choose a assignment method: incremental, UE or SUE; default: incremental
--tolerance <FLOAT> | Use FLOAT as tolerance when checking for SUE stability; default: 0.001
--left-turn-penalty <FLOAT> | Use left-turn penalty FLOAT to calculate link travel time when searching routes; default: 0
--paths <INT> | Use INTEGER as the number of paths needed to be searched for each OD pair at each iteration; default: 1
--paths.penalty <FLOAT> | Penalize existing routes with FLOAT to find secondary routes; default: 1
--upperbound <FLOAT> | Use FLOAT as the upper bound to determine auxiliary link cost; default: 0.5
--lowerbound <FLOAT> | Use FLOAT as the lower bound to determine auxiliary link cost; default: 0.15
-i <INT> --max-iterations <INT> | maximal number of iterations for new route searching in incremental and stochastic user assignment; default: 20
--max-inner-iterations <INT> | maximal number of inner iterations for user equilibrium calculation in the stochastic user assignment; default: 1000
--route-choice-method <STRING> | Choose a route choice method: gawron, logit, or lohse; default: logit
--gawron.beta <FLOAT> | Use FLOAT as Gawron's beta; default: 0.3
--gawron.a <FLOAT> | Use FLOAT as Gawron's a; default: 0.05
--keep-all-routes <BOOL> | Save routes with near zero probability; default: false
--skip-new-routes <BOOL> | Only reuse routes from input, do not calculate new ones; default: false
--logit.beta <FLOAT> | Use FLOAT as (c-)logit's beta for the commonality factor; default: 0.15
--logit.gamma <FLOAT> | Use FLOAT as (c-)logit's gamma for the commonality factor; default: 1
--logit.theta <FLOAT> | Use FLOAT as (c-)logit's theta; default: 0.01

### Defaults

Option | Description
--- | ---
--flow-output.departlane <STRING> | Assigns a default depart lane; default: free
--flow-output.departpos <STRING> | Assigns a default depart position
--flow-output.departspeed <STRING> | Assigns a default depart speed; default: max
--flow-output.arrivallane <STRING> | Assigns a default arrival lane
--flow-output.arrivalpos <STRING> | Assigns a default arrival position
--flow-output.arrivalspeed <STRING> | Assigns a default arrival speed

### Time

Option | Description
--- | ---
-b <TIME> --begin <TIME> | Defines the begin time; Previous trips will be discarded; default: 0
-e <TIME> --end <TIME> | Defines the end time; Later trips will be discarded; Defaults to the maximum time that SUMO can represent; default: -1

### Report

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 or selected topics; default: false
-V <BOOL> --version <BOOL> | Prints the current version; default: false
-X <STRING> --xml-validation <STRING> | Set schema validation scheme of XML inputs ("never", "local", "auto" or "always"); default: local
--xml-validation.net <STRING> | Set schema validation scheme of SUMO network inputs ("never", "local", "auto" or "always"); default: never
--xml-validation.routes <STRING> | Set schema validation scheme of SUMO route inputs ("never", "local", "auto" or "always"); default: local
-W <BOOL> --no-warnings <BOOL> | Disables output of warnings; default: false
--aggregate-warnings <INT> | Aggregate warnings of the same type whenever more than INT occur; default: -1
-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
--ignore-errors <BOOL> | Continue if a route could not be build; default: false
--stats-period <INT> | Defines how often statistics shall be printed; default: -1
--no-step-log <BOOL> | Disable console output of route parsing step; default: false

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

#### Search

Enter your search terms:

#### Keyboard Shortcuts

Key | Action
--- | ---
`?` | Open this help dialog
`s` | Search the Documentation
`e` | Edit current page on GitHub