• marouter
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).

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

The number of paths to choose from in each iteration can be configured using the --paths option. Marouter will use a penalty based method to find multiple paths which adds a given penalty to every edge of the previously shortest path and then recalculates. If the penalty is too small it might not find a new path by this method so the resulting number of paths may be smaller than the number wished for. You can configure the penalty using --paths.penalty (the default is 1).

Capacity-constraint (volume-delay) function#

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.

By setting option --capacities.default, the following constraint function is used:

capacity = edge->getNumLanes() * 800;
travelTime = edge->getLength() / edge->getSpeedLimit() * (1. + 1.*(flow / (capacity * 0.9)) * 3.);

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 <STRING[ ]> 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 <STRING[ ]> 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
--weights.tls-penalty <FLOAT> Apply the given time penalty when computing routing costs across a traffic light; default: 0
--weights.turnaround-penalty <FLOAT> Apply the given time penalty when computing routing costs for turnaround internal lanes; default: 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 <STRING[ ]> 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
--defaults-override <BOOL> Defaults will override given values; default: false
--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
--log.timestamps <BOOL> Writes timestamps in front of all messages; default: false
--log.processid <BOOL> Writes process ID in front of all messages; default: false
--language <STRING> Language to use in messages; default: C
--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