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

Steps

AdminExpressStep

Abstract Step to retrieve data from the ADMIN EXPRESS database.

Data is retrieved from local files when the admin_express_directory parameter is defined, otherwise data is requested from the WFS API.

 

AggregateResultsStep

Generates a JSON file with various aggregate results on the simulation.

NOTE: The developpement of this step is still in progress. More output will be added in the future. Do not hesitate to suggest additional output.

Currently available output:

  • vehicle-kilometers (total, weighted by PCE, by mode)
  • mode shares (by trip count, by trip Euclidean distance)

 

AllFreeFlowTravelTimesStep

Computes travel time of the fastest path under (car) free-flow conditions, for all node pairs of the road network.

 

AllRoadDistancesStep

Computes distance of the shortest path, for all node pairs of the road network.  

BicycleODNodesFromCoordinatesStep

Identifies nodes on the bicycle network to be used as origins and destinations of the trips.

First, this Step finds the nearest edge to the origin / destination coordinates. Edges whose type is specified in the forbidden_types parameter are excluded from that search. Then, the origin / destination node is either the source or target of that nearest edge, whichever is closer.

 

BicyclePreferencesFromPopulationStep

Generates the preference parameters of traveling by bicycle, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by bicycle, per trip
  • value of time / alpha: penalty per hour spent traveling by bicycle

The modes.bicycle.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each bicycle trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by bicycle (default is 0 when omitted)
  • mode: if present, only rows with mode = "bicycle" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
bicycle,true,-2,15
bicycle,false,-1,12

 

BicyclePreferencesStep

Generates the preference parameters of traveling by bicycle, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by bicycle, per trip
  • value of time / alpha: penalty per hour spent traveling by bicycle

The values can be constant over trips or sampled from a specific distribution.  

BicycleTravelTimesFromDistanceStep

Computes travel time by bicycle for each trip, from a given distance and a constant speed.

The parameter modes.bicycle.distance.type specifies how the bicycle distance is computed. For now, the only option is "pedestrian" which uses the distance of the shortest path on the pedestrian network (Step TripsPedestrianDistancesStep).

The parameter modes.bicycle.speed controls the speed at which bicycles run.

If the parameter modes.bicycle.distance.with_snap is set to true, the snap distance at origin and destination is added to the bicycle travel time, with a speed given by modes.bicycle.snap_speed (equal to modes.bicycle.speed by default). The snap distance corresponds to the distance between the trips’ origin and destination and the network (See Step PedestrianODNodesFromCoordinatesStep).

 

CarAccessEgressStep

Identifies the access and egress parts of car trips based on the primary road network.

For each car trip, this step determines:

  • Access part: The sequence of edges taken before the first primary edge in the trip.
  • Egress part: The sequence of edges taken after the last primary edge in the trip.

The access and egress parts are derived from the free-flow route of the trip and the set of primary edges. Trips that consist solely of primary edges or solely of secondary edges will not have access or egress parts.

The output includes the following information for each trip:

  • access_node: The node where the primary part of the trip begins.
  • access_path: The list of edges in the access part.
  • access_time: The total free-flow travel time for the access part.
  • access_length: Length of the access part (meters).
  • egress_node: The node where the primary part of the trip ends.
  • egress_path: The list of edges in the egress part.
  • egress_time: The total free-flow travel time for the egress part.
  • egress_length: Length of the egress part (meters).

 

CarDriverPreferencesFromPopulationStep

Generates the preference parameters of traveling by car_driver, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by car_driver, per trip
  • value of time / alpha: penalty per hour spent traveling by car_driver

The modes.car_driver.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each car_driver trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by car_driver (default is 0 when omitted)
  • mode: if present, only rows with mode = "car_driver" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
car_driver,true,-2,15
car_driver,false,-1,12

 

CarDriverPreferencesStep

Generates the preference parameters of traveling by car_driver, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by car_driver, per trip
  • value of time / alpha: penalty per hour spent traveling by car_driver

The values can be constant over trips or sampled from a specific distribution.  

CarDriverWithPassengersPreferencesFromPopulationStep

Generates the preference parameters of traveling by car_driver_with_passengers, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by car_driver_with_passengers, per trip
  • value of time / alpha: penalty per hour spent traveling by car_driver_with_passengers

The modes.car_driver_with_passengers.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each car_driver_with_passengers trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by car_driver_with_passengers (default is 0 when omitted)
  • mode: if present, only rows with mode = "car_driver_with_passengers" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
car_driver_with_passengers,true,-2,15
car_driver_with_passengers,false,-1,12

 

CarDriverWithPassengersPreferencesStep

Generates the preference parameters of traveling by car_driver_with_passengers, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by car_driver_with_passengers, per trip
  • value of time / alpha: penalty per hour spent traveling by car_driver_with_passengers

The values can be constant over trips or sampled from a specific distribution.  

CarFuelStep

Generates the fuel consumption and price of each car trips by applying a constant emission factor to the free-flow fastest-path length, combined with a fuel price.

 

CarPassengerPreferencesFromPopulationStep

Generates the preference parameters of traveling by car_passenger, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by car_passenger, per trip
  • value of time / alpha: penalty per hour spent traveling by car_passenger

The modes.car_passenger.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each car_passenger trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by car_passenger (default is 0 when omitted)
  • mode: if present, only rows with mode = "car_passenger" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
car_passenger,true,-2,15
car_passenger,false,-1,12

 

CarPassengerPreferencesStep

Generates the preference parameters of traveling by car_passenger, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by car_passenger, per trip
  • value of time / alpha: penalty per hour spent traveling by car_passenger

The values can be constant over trips or sampled from a specific distribution.  

CarRidesharingPreferencesFromPopulationStep

Generates the preference parameters of traveling by car_ridesharing, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by car_ridesharing, per trip
  • value of time / alpha: penalty per hour spent traveling by car_ridesharing

The modes.car_ridesharing.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each car_ridesharing trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by car_ridesharing (default is 0 when omitted)
  • mode: if present, only rows with mode = "car_ridesharing" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
car_ridesharing,true,-2,15
car_ridesharing,false,-1,12

 

CarRidesharingPreferencesStep

Generates the preference parameters of traveling by car_ridesharing, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by car_ridesharing, per trip
  • value of time / alpha: penalty per hour spent traveling by car_ridesharing

The values can be constant over trips or sampled from a specific distribution.  

CircularNetworkStep

Generates a toy road network of circular form with radial and ring roads.

The network is inspired by de Palma, A., Kilani, M., & Lindsey, R. (2005). Congestion pricing on a road network: A study using the dynamic equilibrium simulator METROPOLIS. Transportation Research Part A: Policy and Practice, 39(7-9), 588-611.

The network has a center node, called “CBD”. From the center, bidirectional radial roads are going in all directions. The number of radial roads is controled by the nb_radials parameters and they are evenly spaced (in the polar dimension). At fixed distances from the center (controled by the parameter radius), bidirectional rings are connecting the radial roads together. The number of rings is controled by the nb_rings parameter.

There is one node at each crossing of a ring road with a radial road. The number of nodes is thus nb_radials * nb_rings + 1. The number of edges is 4 * nb_radials * nb_rings.

Node ids are set to "{D}-{i}", where D is the direction (N, S, E, W, NW, NE, SW, SE, or D1, D2, etc. when the number of radials is different from 2, 4, or 8) and i is the ring index (starting at 1). For example, node "NW-1" is at the intersection of the Northwest radial with the first ring (closest ring to the center). Node "D1-2" is at the intersection of the first radial road (radial roads are generated starting from the east direction and going in a counterclockwise direction, like the unit circle) with the second ring. By convention, the center node is denoted "CBD".

Edge ids for radial roads are set to "In{i}-{D}" for edges going toward the center and "Out{i}-{D}" for edges going away from the center, with the same definition of D and i than for the nodes. For example, edge "In2-S" is the radial edge on the South axis, between the first and second ring (its source node is "S-2" and its target node is "S-1").

Edge ids for ring roads are set to {D1}-{D2}-{i}, where D1 is the direction the edge is starting from, D2 is the direction the edge is going to, and i is the ring index. For example, edge "S-SE-1" is the ring edge from node "S-1" to node "SE-1".

Road types are set to "Radial {i}" for radial roads and "Ring {i}" for ring roads.

The parameter with_ramps allows to split each node of the road network (except the CBD node) in four different nodes (inner, outer, left, and right) connected by edges representing entry / exit ramps in and out of highways.

 

ConvergencePlotStep

Generates various graphs to analyze the convergence of the simulation.  

CustomODMatrixStep

Generates car driver origin-destination pairs from the provided origin-destination matrix.

The origin-destination matrix is provided in a CSV or Parquet file with the following columns:

  • origin: id of the origin node,
  • destination: id of the destination node,
  • size: number of trips to be generated from origin to destination.

The size variable can be integers or floats. For float values, stochastic rounding is used to convert the value to an integer: e.g., 3.3 is converted to 3 with probability 70% and to 4 with probability 30%.

 

CustomRoadImportStep

Imports a road network from a geospatial file.

The file must have the same schema has the RawEdgesFile.

 

CustomZonesStep

Reads zones from a geospatial file.

The input file can have these three columns:

  • geometry: Polygon or MultiPolygon of the zones
  • zone_id: Identifier of the zone (integer or sting)
  • name: Name of the zone (string)

The two first columns are mandatory.

 

EdgesFreeFlowTravelTimesStep

Generates free-flow travel times for each edge of the road network.

The free-flow travel time of an edge is:

constant_penalty + length / speed

 

EqasimImportStep

Imports a synthetic population from the output of the Eqasim pipeline.

To use this step, you first need to generate a synthetic population following the instructions here: https://github.com/eqasim-org/eqasim-france.

A few extra steps need to be done for Pymetropolis:

  • Set the departements or regions configuration parameter so that it englobs the simulation area. Pymetropolis will automatically restricts the population to the simulation area (if defined).
  • Use parquet and geoparquet as output formats (optional): 
    output_formats:
  - "parquet"
  - "geoparquet"
  • Use MobiSurvStd for the Household Travel Survey (optional): 
    hts: mobisurvstd
mobisurvstd:
  path: path/to/compatible/hts/
  • Use urban_type and professional_activity as extra matching attributes (optional): 
    use_urban_type: true
matching_attributes: ["professional_activity", "urban_type", "*default*"]
    • Add extra attributes to the generated persons (optional): 
      extra_enriched_attributes:
  - "education_level"
  - "detailed_education_level"
  • Do not activate mode choice (unused): 
    mode_choice: false

 

ExogenousBicycleEdgeCostsStep

Generates costs for the bicycle network edges, from exogenous values.  

ExogenousCapacitiesStep

Generates bottleneck capacities for the road network edges, from exogenous values.

The bottleneck capacities can be:

  • constant over edges
  • constant by edge type
  • constant by combinations of edge type and urban flag

 

ExogenousEdgePenaltiesStep

Generates travel time penalties for the road network edges, from exogenous values.

The penalties can be:

  • constant over edges
  • constant by edge type
  • constant by combinations of edge type and urban flag

 

FrenchHouseholdsHomesZonesStep

Identifies the geographic zones where households’ homes are located in the French zoning system.

The French zoning system uses multiple levels of geographic zones:

  • Zone 1: Region
  • Zone 2: Department
  • Zone 3: EPCI (Établissement Public de Coopération Intercommunale)
  • Zone 4: INSEE commune
  • Zone 5: IRIS

Check the AdminExpressStep and IRISStep abstract steps to know how to configure this step.

 

FrenchTripsZonesStep

Identifies the geographic zones where trips’ origins and destinations are located in the French zoning system.

The French zoning system uses multiple levels of geographic zones:

  • Zone 1: Region
  • Zone 2: Department
  • Zone 3: EPCI (Établissement Public de Coopération Intercommunale)
  • Zone 4: INSEE commune
  • Zone 5: IRIS

Check the AdminExpressStep and IRISStep abstract steps to know how to configure this step.

 

GenericPopulationStep

Generates a population (persons and trips) from a list of car-driver origin-destination pairs.

Each person has a single trip.

 

GravityODMatrixStep

Generates car driver origin-destination pairs by generating trips from a gravity model.

The model is based on de Palma, A., Kilani, M., & Lindsey, R. (2005). Congestion pricing on a road network: A study using the dynamic equilibrium simulator METROPOLIS. Transportation Research Part A: Policy and Practice, 39(7-9), 588-611.

The total number of trips generated from each node is fixed (parameter trips_per_node). Then, the number of trips generated from node \(i\) to node \(j\) is proportional to:

\[ e^{-\lambda \cdot {tt}^0} \]

where \(\lambda\) is the decay rate (parameter exponential_decay) and \({tt}^0\) is the free-flow travel time by car from node \(i\) to node \(j\).

 

GridNetworkStep

Generates a toy road network from a grid.

The network is defined by a number of rows and columns. The first node is located at the bottom left, at coordinates (0, 0). Then, the node on the i-th column and j-th row has coordinates (i - 1, j - 1). The total number of nodes is nb_columns * nb_rows.

By default, edges are bidirectional, connecting all adjacent nodes. The total number of edges is thus 2 * nb_columns * (nb_rows - 1) + 2 * nb_rows * (nb_columns - 1).

The length parameter control the length of all edges.

With the parameters left_to_right, right_to_left, bottom_to_top, and top_to_bottom (by default all equal to true), it is possible to disable the creation of edges in some direction. For example, if right_to_left is set to false, all horizontal edges will be unidirectional (towards increasing x coordinate).

Be careful, if the edges are not all bidirectional, the grid network is not strongly connected which can cause issue later on in the simulation.

A network of successive roads can be created by setting nb_rows to 1, nb_columns to the desired number of roads + 1, and right_to_left to false.

Node ids are set to "Node_{x}_{y}", where x is the index of the column and y is the index of the row (starting at 0).

For row edges, ids are set to "Row_{y}:{x1}to{x2}" for row y, when connecting column x1 to column x2. For column edges, ids are set to "Col_{x}:{y1}to{y2}" for column x, when connecting row x1 to row x2.

Road types are set to the edge direction: "LeftToRight", "RightToLeft", "TopToBottom", or "BottomToTop".

 

HomogeneousTstarStep

Generates the desired start time of the activity following each trip, from exogenous values.

The desired start times can be constant over trips or sampled from a specific distribution. It is recommended to only use this Step when each person has one trip only.

This Step should be combined with a Step that generate schedule-utility parameters.

 

IRISStep

Abstract Step to retrieve data from the Contours IRIS database.

Data is retrieved from local file when the contours_iris_directory parameter is defined, otherwise data is requested from the WFS API.

 

IterationResultsStep

Reads the iteration-level results from the Metropolis-Core simulation and produces a clean file for the results.

 

LinearScheduleFromPurposeStep

Generates the preference parameters for schedule-delay utility of each trip, from constant values over purposes.

The following parameters are generated:

  • beta: the penalty for starting the following activity earlier than the desired time
  • gamma: the penalty for starting the following activity earlier than the desired time
  • delta: the length of the desired time window

The departure_time.linear_schedule.preferences_file parameter must point to a Parquet or CSV file with the beta, gamma and/or delta values for each purpose. The file can have the following columns:

  • purpose: purpose for which the given values apply
  • beta: early penalty, in euros per hour (default is 0 when omitted)
  • gamma: late penalty, in euros per hour (default is 0 when omitted)
  • delta: desired-time window length, given in number of seconds or directly as Duration dtype (default is 0 when omitted)

For example, to set the beta and gamma values for work and education purposes:

purpose,beta,gamma
work,5,15
education,4,10

 

LinearScheduleStep

Generates the preference parameters for schedule-delay utility of each trip, using a linear-penalty model (à la Arnott, de Palma, Lindsey), from exogenous values.

For each trip, the following parameters are created:

  • beta: the penalty for starting the following activity earlier than the desired time
  • gamma: the penalty for starting the following activity earlier than the desired time
  • delta: the length of the desired time window

The values can be constant over trips or sampled from a specific distribution.

This Step should be combined with a Step that generate desired activity start times.

 

ODMatrixEachStep

Generates car driver origin-destination pairs by generating a fixed number of trips for each node pair of the road network.

Nodes selected as eligible origins are all nodes with at least one outgoing edge. Nodes selected as eligible destinations are all nodes with at least one incoming edge.

If the road network is not strongly connected, there is no guarantee that all the origin-destination pairs generated are feasible (i.e., there is a path from origin to destination).

 

OpenStreetMapBicycleImportStep

Imports a bicycle network from OpenStreetMap data.

Edges of the bicycle network are read from the OpenStreetMap ways with tag highway:*.

The osm_bicycle_import.highways parameter is used to define the highway values which are part of the bicycle network. For example, values "cycleway" and "path" should usually be included, while value "motorway" should be excluded as it does not represent ways accessible by bicycles.

In addition to the highways parameter, this step requires both the osm_file and crs parameters to be set.

For example, to import the cycleways in Paris, you can use:

osm_file = "path/to/paris.osm.pbf"
crs = "epsg:2154"

[osm_bicycle_import]
highways = [
  "tertiary",
  "tertiary_link",
  "residential",
  "cycleway",
  "path",
]

An OpenStreetMap way is selected as valid cycleway edge if it satisfies all the conditions below:

  • Tag highway matches one of the value given in highways parameter.
  • The way has no tag bicycle or tag bicycle is not "no".
  • The way’s geometry is a valid LineString.
  • The way intersects with the simulation area (if simulation_area_filter is true).

When filtering with the simulation area, the simulation_area_buffer parameter can be used to extend or shrink the area by a given distance. This can be useful to include edges outside the area that might be used when traveling between two points inside the area.

Various processing operations are done to clean the edges:

  • Duplicate oneway=false ways in two opposing edges.
  • Split ways at nodes where another way is intersecting.

Edges attributes are defined as follows: TODO

  • edge_id: OSM id of the way, with “r” appended if the edge is going backward, with “-[idx]” appended if the edge is split in multiple segments (with idx the segment index).
  • source: OSM id of the source node.
  • target: OSM id of the target node.
  • original_id: OSM id of the way (note that values are generally not unique).
  • length: computed as geometric operation on the ways’ LineString, after conversion to the simulation CRS.
  • edge_type: highway tag value.
  • name: name tag value if any, otherwise addr:street tag value if any, otherwise ref tag value if any.
  • speed_limit: read from maxspeed, maxspeed:forward, or maxspeed:backward tag, as appropriate.
  • lanes: read from lanes, lanes:forward, or lanes:backward tag, as appropriate.
  • oneway: oneway tag value.
  • roundabout: True if junction=roundabout.
  • toll: True if toll=yes.
  • give_way: way has a node with highway=give_way, in the correct direction.
  • stop: way has a node with highway=stop, in the correct direction.
  • traffic_signals: way has a node with highway=traffic_signals, in the correct direction.

 

OpenStreetMapPedestrianImportStep

Imports a pedestrian network from OpenStreetMap data.

Edges of the pedestrian network are read from the OpenStreetMap ways with tag highway:*.

The osm_pedestrian_import.highways parameter is used to define the highway values which are part of the pedestrian network. For example, values "footway" and "path" should usually be included, while value "motorway" should be excluded as motorways are generally not allowed for pedestrians.

In addition to the highways parameter, this step requires both the osm_file and crs parameters to be set.

For example, to import the pedestrian network of Paris, you can use:

osm_file = "path/to/paris.osm.pbf"
crs = "epsg:2154"

[osm_pedesrian_import]
highways = [
    "primary",
    "primary_link",
    "secondary",
    "secondary_link",
    "tertiary",
    "tertiary_link",
    "living_street",
    "unclassified",
    "residential",
    "road",
    "service",
    "track",
    "footway",
    "path",
    "pedestrian",
]

An OpenStreetMap way is selected as valid pedestrian-network edge if it satisfies all the conditions below:

  • Tag highway matches one of the value given in highways parameter.
  • The way has no tag access or tag access is not "private".
  • The way’s geometry is a valid LineString.
  • The way intersects with the simulation area (if simulation_area_filter is true).

When filtering with the simulation area, the simulation_area_buffer parameter can be used to extend or shrink the area by a given distance. This can be useful to include edges outside the area that might be used when traveling between two points inside the area.

Edges attributes are defined as follows:

  • edge_id: OSM id of the way, with “r” appended if the edge is going backward, with “-[idx]” appended if the edge is split in multiple segments (with idx the segment index).
  • source: OSM id of the source node.
  • target: OSM id of the target node.
  • original_id: OSM id of the way (note that values are generally not unique).
  • length: computed as geometric operation on the ways’ LineString, after conversion to the simulation CRS.
  • edge_type: highway tag value.
  • name: name tag value if any, otherwise addr:street tag value if any, otherwise ref tag value if any.

 

OpenStreetMapRoadImportStep

Imports a road network from OpenStreetMap data.

Edges of the road network are read from the OpenStreetMap ways with tag highway:*.

The osm_road_import.highways parameter is used to define the highway values which are part of the road network. For example, values "motorway" and "motorway_link" should usually be included, while value "footway" should be excluded as it does not represent ways accessible by road vehicles.

In addition to the highways parameter, this step requires both the osm_file and crs parameters to be set.

For example, to import the major roads of Paris, you can use:

osm_file = "path/to/paris.osm.pbf"
crs = "epsg:2154"

[osm_road_import]
highways = [
  "motorway",
  "motorway_link",
  "trunk",
  "trunk_link",
  "primary",
  "primary_link",
  "secondary",
  "secondary_link",
]

An OpenStreetMap way is selected as valid road-network edge if it satisfies all the conditions below:

  • Tag highway matches one of the value given in highways parameter.
  • The way has no tag access or tag access matches one of the value given in allowed_access.
  • The way’s geometry is a valid LineString.
  • The way intersects with the simulation area (if simulation_area_filter is true).

By default, the allowed tags for access are yes, permissive (non-public roads with allowed access), and destination (allowed for local traffic only).

When filtering with the simulation area, the simulation_area_buffer parameter can be used to extend or shrink the area by a given distance. This can be useful to include edges outside the area that might be used when traveling between two points inside the area.

Various processing operations are done to clean the edges:

  • Duplicate oneway=false ways in two opposing edges.
  • Split ways at nodes where another way is intersecting.

Edges attributes are defined as follows:

  • edge_id: OSM id of the way, with “r” appended if the edge is going backward, with “-[idx]” appended if the edge is split in multiple segments (with idx the segment index).
  • source: OSM id of the source node.
  • target: OSM id of the target node.
  • original_id: OSM id of the way (note that values are generally not unique).
  • length: computed as geometric operation on the ways’ LineString, after conversion to the simulation CRS.
  • edge_type: highway tag value.
  • name: name tag value if any, otherwise addr:street tag value if any, otherwise ref tag value if any.
  • speed_limit: read from maxspeed, maxspeed:forward, or maxspeed:backward tag, as appropriate.
  • lanes: read from lanes, lanes:forward, or lanes:backward tag, as appropriate.
  • oneway: oneway tag value.
  • roundabout: True if junction=roundabout.
  • toll: True if toll=yes.
  • give_way: way has a node with highway=give_way, in the correct direction.
  • stop: way has a node with highway=stop, in the correct direction.
  • traffic_signals: way has a node with highway=traffic_signals, in the correct direction.

 

OpenStreetMapUrbanAreasStep

Identifies urban areas from OpenStreetMap data.

Urban areas are read from the OpenStreetMap areas with tag landuse:*.

The osm_urban_areas.urban_landuse_tags parameter is used to define the landuse values which are considered as urban. For example, values "residential", "industrial", "commercial", or "retail" should generally be included.

In addition to the urban_landuse_tags parameter, this step requires both the osm_file and crs parameters to be set.

For example, to identifies the urban areas of Brittany, you can use:

osm_file = "path/to/brittany.osm.pbf"
crs = "epsg:2154"

[osm_urban_areas]
urban_landuse_tags = [
  "residential",
  "industrial",
  "commercial",
  "retail",
]

The osm_urban_areas.buffer parameter can be used to extend (positive values) or shrink (negative values) the areas.

 

OutsideOptionPreferencesStep

Generates the preference parameters of the outside option alternative from exogenous values.

The following parameters are generated:

  • constant: utility of choosing the outside option alternative
  • value of time / alpha: penalty per hour spent traveling for the outside option (this usually irrelevant as the outside option does not imply traveling)

The values can be constant over tours or sampled from a specific distribution.

 

OutsideOptionTravelTimesFromRoadDistancesStep

Generates travel times for the outside option alternatives by applying a constant speed to the shortest-path distances of the car-driver trips.

If a tour has multiple trips, the outside option travel time of the tour depends on the sum of the shortest-path distances of all trips.

 

PedestrianODNodesFromCoordinatesStep

Identifies nodes on the pedestrian network to be used as origins and destinations of the trips.

First, this Step finds the nearest edge to the origin / destination coordinates. Edges whose type is specified in the forbidden_types parameter are excluded from that search. Then, the origin / destination node is either the source or target of that nearest edge, whichever is closer.

 

PopulationFromTripCoordinatesStep

Generates a population (persons and trips) from a list of trips with origin / destination coordinates.

Each person has a single trip.

The input file must have columns: trip_id, origin_lng, origin_lat, destination_lng, destination_lat.

 

PostprocessBicycleNetworkStep

Performs some operations on the “raw” bicycle network to make it suitable for simulation.

The operations performed are:

  • Remove all parallel edges (edges with same source and target nodes), keeping only the edge of minimum distance. This is only done if remove_duplicates is true.
  • Keep only the largest strongly connected component of the bicycle-network graph. This ensures that all origin-destination pairs are feasible. This is only done if ensure_connected is true.
  • Set edge ids to 1,...,n, where n is the number of edges. This is only done if reindex is true.

 

PostprocessPedestrianNetworkStep

Performs some operations on the “raw” pedestrian network to make it suitable for simulation.

The operations performed are:

  • Remove all parallel edges (edges with same source and target nodes), keeping only the edge of minimum distance. This is only done if remove_duplicates is true.
  • Keep only the largest strongly connected component of the pedestrian-network graph. This ensures that all origin-destination pairs are feasible. This is only done if ensure_connected is true.
  • Set edge ids to 1,...,n, where n is the number of edges. This is only done if reindex is true.

 

PostprocessRoadNetworkStep

Performs some operations on the “raw” road network to make it suitable for simulation.

The operations performed are:

  • Replace NULL values with defaults for columns speed_limit, lanes, hov_lanes, and all the boolean columns.
  • Remove all parallel edges (edges with same source and target nodes), keeping only the edge of minimum free-flow travel time. This is only done if remove_duplicates is true.
  • Keep only the largest strongly connected component of the road-network graph. This ensures that all origin-destination pairs are feasible. This is only done if ensure_connected is true.
  • Set edge ids to 1,...,n, where n is the number of edges. This is only done if reindex is true.
  • Set a minimum value for the number of lanes, speed limit, and length of edges.
  • Compute in- and out-degrees of nodes.

The default values for speed_limit and lanes can be specified as

  • constant value over edges
  • constant value by edge type
  • constant value by combinations of edge type and urban flag

 

PublicTransitPreferencesFromPopulationStep

Generates the preference parameters of traveling by public_transit, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by public_transit, per trip
  • value of time / alpha: penalty per hour spent traveling by public_transit

The modes.public_transit.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each public_transit trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by public_transit (default is 0 when omitted)
  • mode: if present, only rows with mode = "public_transit" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
public_transit,true,-2,15
public_transit,false,-1,12

 

PublicTransitPreferencesStep

Generates the preference parameters of traveling by public_transit, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by public_transit, per trip
  • value of time / alpha: penalty per hour spent traveling by public_transit

The values can be constant over trips or sampled from a specific distribution.  

PublicTransitTravelTimesFromRoadDistancesStep

Generates travel times for the public-transit trips by applying a constant speed to the shortest-path distances of the car-driver trips.

 

RoadEdgesVariablesStep

This Step generates edge-level variables to be used in the calibration process.  

RoadNetworkCongestionFunctionPlotsStep

Generates plots of expected and simulated congestion function global over the entire road network.

 

RoadNetworkPrimaryEdgesStep

Identifies the edges which are part of the “primary” road network.

Only primary edges are simulated in Metropolis-Core, whereas the secondary edges are supposed to always be under free-flow conditions. By default, all edges are considered “primary”.

You can use the secondary_types parameter to define the list of edges’ types that should be considered “secondary”. For example, setting secondary_types to ["residential"] excludes residential edges from the primary network, which can be useful as these edges are rarely congested but often represent a large portion of the road network.

When secondary edges are defined, road trips are split in at most three parts:

  1. A sequence of secondary edges (access).
  2. A sequence of primary edges (simulated in Metropolis-Core).
  3. A sequence of secondary edges (egress).

Since only the primary part of the trip is simulated, secondary edges cannot appear in the middle of the primary part. If the ensure_primary_connected parameter is set to true, Pymetropolis will add secondary edges to the primary network to ensure that the fastest free-flow route for each trip can be completed without requiring more than three parts.

 

RoadODMatrixStep

Construct an origin-destination matrix (at the road-network node level) from the trips’ origins and destinations.

 

RoadODNodesFromCoordinatesStep

Identifies nodes on the road network to be used as origins and destinations of the trips.

First, this Step finds the nearest edge to the origin / destination coordinates. Edges whose type is specified in the forbidden_types parameter are excluded from that search. Then, the origin / destination node is either the source or target of that nearest edge, whichever is closer.

 

RouteResultsStep

Reads the results from the Metropolis-Core simulation and produces a clean file for route results of road trips.

 

RunSimulationStep

Runs the Metropolis-Core simulation.

This Step can take a few hours or even days to execute for large-scale simulations.

 

SimulationAreaFromAAVStep

Creates the simulation area from the boundaries of a Frech metropolitan area.

A French metropolitan area (aire d’attraction d’une ville) is a type of statistical area defined by the French national statistics office INSEE. It is defined by considering the commuting patterns between cities, making it well adapted to define areas for transport simulations.

The database for these aires d’attraction des villes is publicly available on the INSEE website. Pymetropolis can automatically download the database and read the polygon of an area if you set the aav_name parameter to one of the existing area. The areas’ name is usually the name of the biggest city in the area.

[simulation_area]
aav_name = "Paris"

If the automatic download does not work, you can download the file locally and tell Pymetropolis to use that version:

  • Go to the INSEE page of the aires d’attraction des villes database: https://www.insee.fr/fr/information/4803954
  • Download the zip file “Fonds de cartes des aires d’attraction des villes 2020 au 1er janvier 2024”
  • Unzip the file. You will get two zip files representing shapefiles: aav2020_2024.zip (polygons of the areas) and com_aav2020_2024.zip (polygons of the municipalities). Only the former is needed.
  • In the section [simulation_area] of the configuration, add the lines aav_filename = "path/to/aav2020_2024.zip" and aav_name = "YOUR_AAV_NAME".
[simulation_area]
aav_name = "Paris"
aav_filename = "path/to/aav2020_2024.zip"

 

SimulationAreaFromBboxStep

Creates the simulation area from a bounding box.

This is the easiest way to specify the simulation area. However, the area is thus limited to rectangles.

The bounding box needs to be specified as the bbox value, which expects a list of coordinates [minx, miny, maxx, maxy].

By default, the coordinates need to be specified in the simulation CRS. If you want to specify them in WGS84 (longitude, latitude), you can use bbox_wgs = true.

You can go to www.openstreetmap.org to identify the bounding box of a region (as WGS84 coordinates), using the “Export” button.

[simulation_area]
bbox = [1.4777, 48.3955, 3.6200, 49.2032]
bbox_wgs = true

 

SimulationAreaFromOSMStep

Creates the simulation area by reading administrative boundaries from OpenStreetMap data.

Administrative boundaries of various subdivisions are specified directly on OpenStreetMap (e.g., states, counties, municipalities), with the tags admin_level=* and boundary=administrative. The OpenStreetMap wiki has a table indicating the meaning of each admin_level value by country. For example, admin_level=6 represents counties in the U.S. and départements in France.

You can use this Step to create the simulation area by reading one or more administrative boundaries from OpenStreetMap data. First, you need to set the osm_file value to the path to the OpenStreetMap file. In the [simulation_area] section, the osm_admin_level value represents the admin_level value to be used as filter and the osm_name value is a list of the subdivisions names to be selected.

For example, to get the polygon of Madrid, you can use:

osm_file = "path/to/spain.osm.pbf"

[simulation_area]
osm_admin_level = 8
osm_name = ["Madrid"]

Or, to get the polygon of Paris and the surrounding departments, you can use:

osm_file = "path/to/france.osm.pbf"

[simulation_area]
osm_admin_level = 6
osm_name = ["Paris", "Hauts-de-Seine", "Seine-Saint-Denis", "Val-de-Marne"]

 

SimulationAreaFromPolygonsStep

Creates the simulation by reading a geospatial file with polygon(s).

If you already have a set of polygons which jointly form the entire area (e.g., the administrative boundaries of all municipalities to be considered), you can simply provide as input a geospatial file with those polygons. Then, Pymetropolis will read the file and define the polygon of the simulation area as the union of all polygons. If there is a single polygon (e.g., the administrative boundary of the region to be considered), Pymetropolis will simply use it as the simulation area polygon.

The file can use any GIS format that can be read by geopandas (e.g., Parquet, Shapefile, GeoJson). It needs to be specified as the polygon_file value.

[simulation_area]
polygon_file = "path/to/polygon/filename"

 

TripDepartureTimeDistributionStep

Generates a histogram of departure-time distribution at the trip level.  

TripDistancesStep

Computes the Euclidean distances between origin and destination for each trip.  

TripModeSharesStep

Generates a plot of mode shares at the trip level.  

TripResultsStep

Reads the results from the Metropolis-Core simulation and produces a clean file for results at the trip level.

 

TripsBicycleCostStep

Computes the trips’ minimum cost on the bicycle network.

If the output_path is set to true, the list of bicycle edges along the minimum-cost path is stored in the bicycle_path column of the TripsBicycleCostsFile file.

 

TripsCarFreeFlowTravelTimesStep

Computes the trips’ travel time on the road network by car, under free-flow conditions.

The free-flow travel time is defined as the travel time of the fastest path from origin to destination node on the road network, using edge-level car free-flow travel times.

 

TripsOpenTripPlannerStep

Computes the trips’ travel time and generalized time by public transit with OpenTripPlanner.

This step requires having access to an OpenTripPlanner API server. You can run one on your machine by following the OpenTripPlanner documentation. This step has been tested with OpenTripPlanner v2.9.0.

If you want a simpler (but less flexible) way to compute public-transit travel times, check out TripsPublicTransitTravelTimeFromR5Step.

The OpenTripPlanner server must be running when you execute Pymetropolis and accessible from the URL opentripplanner.url ("http://0.0.0.0:8080" by default).

The date parameter controls the date used in the public-transit timetables, for all queries. You need to ensure that the GTFS file(s) have running services at this date.

The departure / arrival time of the trips is control by the time_type and time parameters. Five different cases are possible:

  • time_type = "departure": trips are departing at their ex-ante departure time, read from TripsFile (with time as a fallback value)
  • time_type = "arrival": trips are arriving at their ex-ante arrival time, read from TripsFile (with time as a fallback value)
  • time_type = "tstar": trips are arriving at their desired arrival time, read from TstarsFile (with time as a fallback value)
  • time_type = "custom_departure": trips are all departing at time time
  • time_type = "custom_arrival": trips are all arriving at time time

Note that the departure / arrival time represents a time window, controllable by OpenTripPlanner: for example, a trips with departure time 08:00:00 might actually depart at 08:04:00 to match the schedule of a bus.

The itinerary selected by OpenTripPlanner is the one that minimizes the “generalized time”, which is equal to the travel time with different weights applied to different modes.

You can control how the generalized time function is defined through several parameters:

  • walking_speed: walking speed on the pedestrian network, in km/h (default is 4 km/h).
  • transfer_cost: penalty for transfers, in seconds equivalent (default is 5 minutes).
  • multipliers.walk: multiplier for the value of time walking (default is 2).
  • multipliers.wait: multiplier for the value of time waiting (default is 1.1).
  • multipliers.bus: multiplier for the value of time in a bus (default is 1.2).
  • multipliers.tram: multiplier for the value of time in a tramway (default is 1).
  • multipliers.subway: multiplier for the value of time in a subway (default is 1).
  • multipliers.rail: multiplier for the value of time for rail transport (default is 1).

When running this step, the public-transit itineraries of all trips are hold in memory. If you are running out of memory, you can try to use the batch_size parameter to reduce RAM consumption. Reducing the batch size should reduce memory consumption, at the cost of an increase in running time. By default, all trips are run in a single batch.

Example of configuration for this step:

[opentripplanner]
url = "http://0.0.0.0:8080"
batch_size = 50000
date = 2026-05-28
time_type = "tstar"
walking_speed = 4.0
transfer_cost = 300
[opentripplanner.multipliers]
walk = 2
wait = 1.1
bus = 1.2
tram = 1
subway = 1
rail = 1

 

TripsPedestrianDistancesStep

Computes the trips’ distance on the pedestrian network.

The distance is defined as the length of the shortest path from origin to destination node on the pedestrian network.

If the output_path is set to true, the list of pedestrian edges along the shortest path is stored in the pedestrian_path column of the TripsPedestrianDistancesFile file.

 

TripsPublicTransitTravelTimeFromR5Step

Computes the trips’ travel time by public transit with r5py.

This is the easiest and (usually) fastest solution to compute public-transit travel times. However, it comes with some drawbacks:

  • Time spent in each public-transit modes cannot be weighted (walking vs waiting vs bus vs metro…).
  • The itineraries are not computed (needed for some post-simulation analysis).
  • Approximations are made to the origin / destination locations and to the departure time.
  • It is not possible to compute travel time for a given arrival time, only the departure time can be controlled.

If you want a more flexible solution, check out TripsOpenTripPlannerStep.

For this step, r5py build the public-transit network from an OpenStreetMap file (osm_file) and from GTFS file(s) (gtfs_files).

The date parameter controls the date used in the public-transit timetables, for all queries. You need to ensure that the GTFS file(s) have running services at this date.

The departure time of the trips is control by the time_type and time parameters. If time_type is "departure", then the departure time is given by the trips’ ex-ante departure times (usually generated by the synthetic population). If time_type is "custom", then the departure time is given by time.

The running time of r5py does not depend on the number of trips, but rather on the number of unique origins, destinations, and departure times. When trips’ origins and destinations are exact coordinates, as is the case with the Eqasim synthetic population, the running time of this step can be very long. Therefore, some approximations are done to “group” together similar origins, destinations, and departure times. You can control these approximations with the coordinates_rounding and time_rounding parameters. By default, origins and destinations are rounded to the nearest 500 meters and departure time is rounded to periods of 1 hour.

Example of configuration for this step:

osm_file = "data/ile-de-france-260101.osm.pbf"
gtfs_files = ["data/IDFM-gtfs.zip"]

[r5]
date = 2026-05-28
time_type = "departure"
coord_rounding = 1000
time_rounding = 1800

 

TstarFromArrivalTimeStep

Generates the desired start time of the activity following each trip, from the trip’s ex-ante arrival time.

This Step is useful to generate activity desired start times for the synthetic population imported from EqasimImportStep.

To enable this Step, you must set the departure_time.linear_schedule.tstar_type parameter to "arrival_time".

 

UniformDrawsStep

Draws random numbers for the inverse transform sampling of mode choice and departure time choice of each tour.

The random numbers are drawn from a uniform distribution between 0 and 1.

 

UrbanEdgesStep

Identifies edges which are part of urban areas.

An edge is classified as “urban” if it is fully contained within the urban areas of the simulation.

 

WalkingPreferencesFromPopulationStep

Generates the preference parameters of traveling by walking, for each trip, from constant values over population segments.

The following parameters are generated:

  • constant: penalty of traveling by walking, per trip
  • value of time / alpha: penalty per hour spent traveling by walking

The modes.walking.preferences_file parameter must point to a Parquet or CSV file with the constant and/or alpha value for the population segments. The file can have the following columns:

  • constant: constant penalty for each walking trip (default is 0 when omitted)
  • alpha or value_of_time: penalty per hour spent traveling by walking (default is 0 when omitted)
  • mode: if present, only rows with mode = "walking" are used
  • any column representing persons’ characteristics from PersonsFile

For example, to set different preferences for men and women, you can use the following CSV file:

mode,woman,constant,value_of_time
walking,true,-2,15
walking,false,-1,12

 

WalkingPreferencesStep

Generates the preference parameters of traveling by walking, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling by walking, per trip
  • value of time / alpha: penalty per hour spent traveling by walking

The values can be constant over trips or sampled from a specific distribution.  

WalkingTravelTimesFromDistanceStep

Computes travel time by walking for each trip, from a given distance and a constant speed.

The parameter modes.walking.distance.type specifies how the walking distance is computed. For now, the only option is "pedestrian" which uses the distance of the shortest path on the pedestrian network (Step TripsPedestrianDistancesStep).

The parameter modes.walking.speed controls the speed at which people walk.

If the parameter modes.walking.distance.with_snap is set to true, the snap distance at origin and destination is added to the walking travel time, with a speed given by modes.walking.snap_speed (equal to modes.walking.speed by default). The snap distance corresponds to the distance between the trips’ origin and destination and the network (See Step PedestrianODNodesFromCoordinatesStep).

 

WriteMetroAgentsStep

Generates the input agents file for the Metropolis-Core simulation.

If mode choice is enabled (more than 1 mode is simulated), the mode-choice parameters of the agents are initiated.

 

WriteMetroAlternativesStep

Generates the input alternatives file for the Metropolis-Core simulation.  

WriteMetroEdgesStep

Generates the input edges file for the Metropolis-Core simulation.  

WriteMetroParametersStep

Generates the input parameters file for the Metropolis-Core simulation.  

WriteMetroTripsStep

Generates the input trips file for the Metropolis-Core simulation.  

WriteMetroVehicleTypesStep

Generates the input vehicle-types file for the Metropolis-Core simulation.