Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Parameters

This page lists all the parameters that can be used in the Toml configuration file.

The parameters’ names are separated by dots representing the (potentially nested) tables in which they must be defined. For example, the parameter modes.car_driver.alpha must be defined as:

[modes]
[modes.car_driver]
alpha = 10.0

For each parameter, the documentation specifies the types of values allowed. These types mostly follows the Toml specification (String, Integer, Float, Boolean), with the following special types:

  • Time: time of the day. It can be specified either as a valid Toml time (e.g., 07:30:00) or as a number of seconds after midnight (e.g., 27000). For times past midnight (24:00:00), only the latter specification is possible.
  • Duration: a time duration (e.g., 1 hour 30 minutes, 10 seconds). It can be specified either as a string with a valid ISO8601 duration (e.g., "PT1H30M10S") or as a number of seconds (e.g., 5410).
  • List: a Toml array (e.g., [1, 2, 3]). When specified, the array elements must be of a specific type. There can also be constraints on the number of elements. For example, the simulation_parameters.period parameter must be an array with exactly two elements of type Time.
  • Table: a Toml table. It can be specified either as a complete table or as an inline table.

For example, many parameters can take as input a special table representing a distribution. These parameters can be specified as

[modes]
[modes.car_driver]
[modes.car_driver.alpha]
mean = 10.0
std = 1.0
distribution = "Normal"

or as

[modes]
[modes.car_driver]
alpha = { mean = 10.0, std = 1.0, distribution = "Normal" }

The documentation also lists all the steps that uses the defined parameter as input.

Warning

For parameters specifying a distribution (e.g., modes.car_driver.alpha), the meaning of the std value depends on the selected distribution.

For "Uniform" distributions, the values are uniformly distributed in the interval [mean - std, mean + std], so the actual standard-deviation is std / √3.

For "Lognormal" distributions, mean and std represent the mean and standard-deviation of the underlying normal distribution.

main_directory

  • Description: Directory where all the generated MetroFiles are stored.
  • Allowed values: String representing a valid path
  • Example: “my_simulation/”
  • Note: If the directory does not exist, it will be automatically created when running Pymetropolis.
  • Steps: All

crs

  • Description: Projected coordinate system to be used for spatial operations.
  • Allowed values: any value accepted by pyproj.CRS.from_user_input()
  • Example: “EPSG:2154” (Lambert projection adapted for France)
  • Note: You can use the epsg.io website to find a projected coordinate system that is adapted for your study area. It is strongly recommended that the unit of measure is meter. If you use a coordinate system for an area of use that is not adapted or with an incorrect unit of measure, then some operations might fail or the results might be erroneous (like road length being overestimated).
  • Steps: SimulationAreaFromAAVStep, SimulationAreaFromBboxStep, SimulationAreaFromOSMStep, SimulationAreaFromPolygonsStep

osm_file

  • Description: Path to the OpenStreetMap file (.osm or .osm.pbf) with data for the simulation area.
  • Allowed values: String representing a valid path to an existing file [possible extensions: .pbf, .osm]
  • Example: "data/osm/france-250101.osm.pbf"
  • Note: You can download extract of OpenStreetMap data for any region in the world through the Geofabrik website. You can also download data directly from the OSM website, using the “Export” button, although it is limited to small areas.
  • Steps: SimulationAreaFromOSMStep

random_seed

circular_network.entry_ramps_length

  • Description: Length of entry ramps, in meters.
  • Allowed values: Float
  • Steps: CircularNetworkStep

circular_network.exit_ramps_length

  • Description: Length of exit ramps, in meters.
  • Allowed values: Float
  • Steps: CircularNetworkStep

circular_network.nb_radials

circular_network.nb_rings

circular_network.radial_inter_ramp_length

  • Description: Length of the radial road segments (tunnels) between the clockwise and counter-clockwise ramps, in meters.
  • Allowed values: Float
  • Steps: CircularNetworkStep

circular_network.radius

  • Description: Radius of each ring, in meters.
  • Allowed values: float or list of floats
  • Note: If a scalar, the distance between each ring. If a list, the (cumulative) distance of each ring to the center
  • Steps: CircularNetworkStep

circular_network.resolution

  • Description: The number of points in the geometry of the ring roads.
  • Allowed values: Integer
  • Steps: CircularNetworkStep

circular_network.ring_inter_ramp_length

  • Description: Length of the ring road segments (bridges) between the left and right ramps, in meters.
  • Allowed values: Float
  • Steps: CircularNetworkStep

circular_network.with_ramps

  • Description: Whether entry / exit ramps to the ring roads should be added.
  • Allowed values: Boolean
  • Steps: CircularNetworkStep

custom_road_import.edges_file

  • Description: Path to the geospatial file containing the edges definition.
  • Allowed values: String representing a valid path to an existing file
  • Example: "data/my_edges.geojson"
  • Steps: CustomRoadImportStep

departure_time.linear_schedule.beta

  • Description: Penalty for starting an activity earlier than the desired time (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: LinearScheduleStep

departure_time.linear_schedule.delta

  • Description: Length of the desired time window.
  • Allowed values: Duration or a table with keys mean (Duration), std (Duration), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: LinearScheduleStep

departure_time.linear_schedule.gamma

  • Description: Penalty for starting an activity later than the desired time (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: LinearScheduleStep

departure_time.linear_schedule.tstar

  • Description: Desired start time of the following activity.
  • Allowed values: Time or a table with keys mean (Time), std (Duration), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: HomogeneousTstarStep

departure_time_choice.model

  • Description: Type of choice model for departure-time choice
  • Allowed values: Either 'ContinuousLogit', 'Exogenous'
  • Steps: WriteMetroAlternativesStep

departure_time_choice.mu

  • Description: Value of mu for the Continuous Logit departure-time choice model
  • Allowed values: Float
  • Note: Only required when departure-time choice model is ContinuousLogit
  • Steps: WriteMetroAlternativesStep

fuel.consumption_factor

  • Description: Fuel consumption, in liters per km.
  • Allowed values: Float
  • Steps: CarFuelStep

fuel.price

  • Description: Price of fuel, in € per liter.
  • Allowed values: Float
  • Steps: CarFuelStep

gravity_od_matrix.exponential_decay

  • Description: Exponential decay rate of flows as a function of free-flow travel times (rate per minute)
  • Allowed values: Float
  • Steps: GravityODMatrixStep

gravity_od_matrix.nodes_regex

  • Description: Regular expression specifying the nodes to be selected as possible origin / destination.
  • Allowed values: String
  • Note: If not specified, any node can be an origin / destination.
  • Steps: GravityODMatrixStep

gravity_od_matrix.trips_per_node

  • Description: Number of trips to be generated originating from each node
  • Allowed values: Integer or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: GravityODMatrixStep

grid_network.bottom_to_top

  • Description: Whether edges going from bottom to top should be generated.
  • Allowed values: Boolean
  • Steps: GridNetworkStep

grid_network.left_to_right

  • Description: Whether edges going from left to right should be generated.
  • Allowed values: Boolean
  • Steps: GridNetworkStep

grid_network.length

  • Description: Length of an edge, in meters.
  • Allowed values: Float
  • Steps: GridNetworkStep

grid_network.nb_columns

  • Description: Number of columns (i.e., number of nodes on each row).
  • Allowed values: Integer
  • Steps: GridNetworkStep

grid_network.nb_rows

  • Description: Number of rows (i.e., number of nodes on each column).
  • Allowed values: Integer
  • Steps: GridNetworkStep

grid_network.right_to_left

  • Description: Whether edges going from right to left should be generated.
  • Allowed values: Boolean
  • Steps: GridNetworkStep

grid_network.top_to_bottom

  • Description: Whether edges going from top to bottom should be generated.
  • Allowed values: Boolean
  • Steps: GridNetworkStep

metropolis_core.exec_path

  • Description: Path to the metropolis_cli executable.
  • Allowed values: String representing a valid path
  • Note: On Windows, you can omit the “.exe” extension
  • Steps: RunSimulationStep

mode_choice.model

  • Description: Type of choice model for mode choice
  • Allowed values: Either 'DrawnNestedLogit', 'DrawnLogit', 'Deterministic', 'Logit'
  • Steps: WriteMetroAgentsStep

mode_choice.modes

mode_choice.mu

  • Description: Value of mu for the Logit choice model
  • Allowed values: Float
  • Note: Only required when mode choice model is Logit
  • Steps: WriteMetroAgentsStep

modes.car_driver.alpha

  • Description: Value of time as a car driver (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarDriverPreferencesStep

modes.car_driver.constant

  • Description: Constant penalty for each trip as a car driver (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarDriverPreferencesStep

modes.car_driver_with_passengers.alpha

  • Description: Value of time as a car driver with passengers (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarDriverWithPassengersPreferencesStep

modes.car_driver_with_passengers.constant

  • Description: Constant penalty for each trip as a car driver with passengers (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarDriverWithPassengersPreferencesStep

modes.car_passenger.alpha

  • Description: Value of time as a car passenger (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarPassengerPreferencesStep

modes.car_passenger.constant

  • Description: Constant penalty for each trip as a car passenger (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarPassengerPreferencesStep

modes.car_ridesharing.alpha

  • Description: Value of time by car ridesharing (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarRidesharingPreferencesStep

modes.car_ridesharing.constant

  • Description: Constant penalty for each trip by car ridesharing (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: CarRidesharingPreferencesStep

modes.outside_option.alpha

  • Description: Value of time for the outside option (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Note: This is usually not relevant as the outside option does not imply traveling.
  • Steps: OutsideOptionPreferencesStep

modes.outside_option.constant

  • Description: Constant penalty of the outside option (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Note: Use negative values to represent benefits (i.e., a positive utility).
  • Steps: OutsideOptionPreferencesStep

modes.outside_option.road_network_speed

modes.public_transit.alpha

  • Description: Value of time in public transit (€/h).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: PublicTransitPreferencesStep

modes.public_transit.constant

  • Description: Constant penalty for each trip in public transit (€).
  • Allowed values: Float or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: PublicTransitPreferencesStep

modes.public_transit.road_network_speed

node_od_matrix.each

  • Description: Number of trips to generate for each origin-destination pair.
  • Allowed values: Integer or a table with keys mean (Float), std (Float), and distribution (one of 'Uniform', 'Gaussian', 'Normal', 'Lognormal')
  • Steps: ODMatrixEachStep

od_matrix.file

  • Description: Path to the CSV or Parquet file containing the origin-destination matrix.
  • Allowed values: String representing a valid path to an existing file
  • Note: Required columns are: origin (id of origin node), destination (id of destination node), and size (int or float, number of trips).
  • Steps: CustomODMatrixStep

road_network.capacities

  • Description: Bottleneck capacity (in PCE/h) of edges.
  • Allowed values: float (constant capacity for all edges), table with road types as keys and capacities as values, or table with “urban” and “rural” as keys and road_type->value tables as values (see example)
  • Example:
[road_network.capacities]
[road_network.capacities.urban]
motorway = 2000
road = 1000
[road_network.capacities.rural]
motorway = 2000
road = 1500

road_network.default_nb_lanes

  • Description: Default number of lanes to use for edges with no specified value.
  • Allowed values: float (constant number of lanes for all edges), table with road types as keys and number of lanes as values, or table with “urban” and “rural” as keys and road_type->value tables as values (see example)
  • Example:
[road_network.default_nb_lanes]
[road_network.default_nb_lanes.urban]
motorway = 2
road = 1
[road_network.default_nb_lanes.rural]
motorway = 3
road = 1

road_network.default_speed_limit

  • Description: Default speed limit (in km/h) to use for edges with no specified value.
  • Allowed values: float (constant speed limit for all edges), table with road types as keys and speed limits as values, or table with “urban” and “rural” as keys and road_type->value tables as values (see example)
  • Example:
[road_network.default_speed_limit]
[road_network.default_speed_limit.urban]
motorway = 110
road = 50
[road_network.default_speed_limit.rural]
motorway = 110
road = 80
  • Note: The value is either a scalar value to be applied to all edges with no specified value, a table road_type -> speed_limit or two tables road_type -> speed_limit, for urban and rural edges.
  • Steps: PostprocessRoadNetworkStep

road_network.ensure_connected

  • Description: Whether the network should be restricted to the largest strongly connected component of the underlying graph.
  • Allowed values: Boolean
  • Note: If False, it is the user’s responsibility to ensure that all origin-destination pairs are feasible.
  • Steps: PostprocessRoadNetworkStep

road_network.hov_lanes

  • Description: Number of HOV lanes on edges.
  • Allowed values: float (constant number of HOV lanes for all edges), table with road types as keys and number of lanes as values, or table with “urban” and “rural” as keys and road_type->value tables as values (see example)
  • Example:
[road_network.default_nb_lanes]
[road_network.default_nb_lanes.urban]
motorway = 2
road = 1
[road_network.default_nb_lanes.rural]
motorway = 3
road = 1
  • Note: The HOV lanes are included in the total number of lanes on the edges so there cannot be more HOV lanes than there are lanes.
  • Steps: PostprocessRoadNetworkStep

road_network.min_length

road_network.min_nb_lanes

road_network.min_speed_limit

road_network.penalties

  • Description: Constant time penalty (in seconds) of edges.
  • Allowed values: float (constant penalty for all edges), table with road types as keys and penalties as values, or table with “urban” and “rural” as keys and road_type->value tables as values (see example)
  • Example:
[road_network.penalties]
[road_network.penalties.urban]
motorway = 0
road = 5
[road_network.penalties.rural]
motorway = 0
road = 2

road_network.reindex

  • Description: If true, the edges are re-index after the postprocessing so that they are indexed from 0 to n-1.
  • Allowed values: Boolean
  • Steps: PostprocessRoadNetworkStep

road_network.remove_duplicates

  • Description: Whether the duplicate edges (edges with same source and target) should be removed.
  • Allowed values: Boolean
  • Note: If True, the edge with the smallest travel time is kept.
  • Steps: PostprocessRoadNetworkStep

simulation.backward_wave_speed

  • Description: Speed at which the holes created by a vehicle leaving a road is propagating backward (in km/h).
  • Allowed values: Float
  • Steps: WriteMetroParametersStep

simulation.departure_time_interval

  • Description: Interval between two breakpoints in the utility function for departure-time choice.
  • Allowed values: Duration
  • Note: Smaller values make the simulation faster but can lead to approximations in the departure-time choice.
  • Steps: WriteMetroParametersStep

simulation.learning_factor

  • Description: Value of the smoothing factor for the exponential learning model.
  • Allowed values: Float
  • Note: Value must be between 0 and 1. Smaller values lead to slower but steadier convergences.
  • Steps: WriteMetroParametersStep

simulation.max_pending_duration

  • Description: Maximum amount of time that a vehicle can spend waiting to enter the next road, in case of spillback.
  • Allowed values: Duration
  • Steps: WriteMetroParametersStep

simulation.nb_iterations

simulation.period

  • Description: Time window to be simulated.
  • Allowed values: List of Time [exactly 2 elements]
  • Example: [00:00:00, 24:00:00]
  • Steps: WriteMetroParametersStep

simulation.recording_interval

  • Description: Time interval between two breakpoints for the travel-time functions.
  • Allowed values: Duration
  • Steps: WriteMetroParametersStep

simulation.routing_algorithm

  • Description: Algorithm type to use when computing the origin-destination travel-time functions.
  • Allowed values: Either 'TCH', 'Intersect', 'Best'
  • Note: Possible values: “Best”, “Intersect”, “TCH”
  • Steps: WriteMetroParametersStep

simulation.spillback

  • Description: Whether the number of vehicles on a road should be limited by the total road length.
  • Allowed values: Boolean
  • Steps: WriteMetroParametersStep

simulation_area.aav_filename

  • Description: Path to the shapefile of the French’s Aires d’attraction des villes.
  • Allowed values: String representing a valid path to an existing file [possible extensions: .zip, .shp]
  • Example: "data/aav2020_2024.zip"
  • Note: When the value is not specified, pymetropolis will attempt to automatically download the shapefile.
  • Steps: SimulationAreaFromAAVStep

simulation_area.aav_name

  • Description: Name of the Aire d’attraction des villes to be selected.
  • Allowed values: String
  • Example: Paris
  • Note: The value must appears in the column libaav20xx of the aav_filename file.
  • Steps: SimulationAreaFromAAVStep

simulation_area.bbox

  • Description: Bounding box to be used as simulation area.
  • Allowed values: List of Float [exactly 4 elements]
  • Example: [1.4777, 48.3955, 3.6200, 49.2032]
  • Note: Note: The values need to be specified as [minx, miny, maxx, maxy], in the simulation’s CRS. If bbox_wgs = true, the values need to be specified in WGS 84 (longitude, latitude).
  • Steps: SimulationAreaFromBboxStep

simulation_area.bbox_wgs

  • Description: Whether the bbox values are specified in the simulation CRS (false) or in WGS84 (true)
  • Allowed values: Boolean
  • Steps: SimulationAreaFromBboxStep

simulation_area.buffer

simulation_area.osm_admin_level

  • Description: Administrative level to be considered when reading administrative boundaries.
  • Allowed values: Integer
  • Note: See https://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#Table_:_Admin_level_for_all_countries for a table with the meaning of all possible value for each country.
  • Steps: SimulationAreaFromOSMStep

simulation_area.osm_name

  • Description: List of subdivision names to be considered when reading administrative boundaries.
  • Allowed values: string or list of strings
  • Example: "Madrid"
  • Note: The values are compared with the name=* tag of the OpenStreetMap features. Be careful, the name can sometimes be in the local language.
  • Steps: SimulationAreaFromOSMStep

simulation_area.polygon_file

  • Description: Path to the geospatial file containing polygon(s) of the simulation area.
  • Allowed values: String representing a valid path to an existing file
  • Example: "data/my_area.geojson"
  • Steps: SimulationAreaFromPolygonsStep

vehicle_types.car.headway

  • Description: Typical length between two cars, from head to head, in meters
  • Allowed values: Float
  • Steps: WriteMetroVehicleTypesStep

vehicle_types.car.pce

vehicle_types.car.ridesharing_passenger_count

  • Description: Average number of passengers in the car (excluding the driver).
  • Allowed values: Float
  • Note: This is only relevant for the car_ridesharing mode. Larger values increase probability to select this mode (fuel cost is shared between more persons) and decrease congestion generated (more persons are traveling in each car).
  • Steps: WriteMetroTripsStep, WriteMetroVehicleTypesStep

zones.custom_zones

  • Description: Path to the geospatial file containing the zones definition.
  • Allowed values: String representing a valid path to an existing file
  • Example: "data/my_zones.geojson"
  • Steps: CustomZonesStep