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

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.

CarDriverPreferencesStep

Generates the preference parameters of traveling as a car driver, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling as car driver, per trip
  • value of time / alpha: penalty per hour spent traveling as a car driver

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

CarDriverWithPassengersPreferencesStep

Generates the preference parameters of traveling as a car driver with passengers, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling as car driver with passengers, per trip
  • value of time / alpha: penalty per hour spent traveling as a car driver with passengers

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

CarFreeFlowDistancesStep

Generates the distance of the shortest path on the road network for each trip, given the origin and destination as a car driver.

The shortest-path distances are not computed but are read from the file containing the shortest-path distances of all node pairs (AllRoadDistancesFile).

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.

CarPassengerPreferencesStep

Generates the preference parameters of traveling as a car passenger, for each trip, from exogenous values.

The following parameters are generated:

  • constant: penalty of traveling as car passenger, per trip
  • value of time / alpha: penalty per hour spent traveling as a car passenger

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

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
  • passenger_count: number of passengers in the car (excluding the driver); it is used to define how fuel costs are shared and how congestion is computed

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

CarShortestDistancesStep

Generates the distance of the shortest path on the road network for each trip, given the origin and destination as a car driver.

The shortest-path distances are not computed but are read from the file containing the shortest-path distances of all node pairs (AllRoadDistancesFile).

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.

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

ExogenousCapacitiesStep

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

The bottleneck capacities can be:

ExogenousEdgePenaltiesStep

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

The penalties can be:

GenericPopulationStep

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

Each household is composed of a single person, with 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.

IterationResultsStep

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

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

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.

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, nb_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_duplacites 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 nb_lanes can be specified as

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.

RoadNetworkCongestionFunctionPlotsStep

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

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.

TripResultsStep

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

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.

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.