Introduction

METROPOLIS2

METROPOLIS2 is an agent-based transport simulator.

Its main features are:

• 🚘 Mode choice (with an arbitrary number of modes, road vehicles are explicitly modeled)
• ⏱️ Continuous-time departure-time choice
• 🛣️ Deterministic route choice (for road vehicles)
• 👫 Agent based (each agent is an autonomous entity with its own characteristics and choices)
• 🚦 Modeling of road congestion (using speed-density functions and bottlenecks)
• ⏸️ Intermediary stops (with schedule preferences and stopping time at each intermediary point)

METROPOLIS2 is composed of

• Metropolis-Core: a command line tool to run the transport simulations, written in Rust 🚀
• Pymetropolis: a command line tool to interact with METROPOLIS2’s input and output data, written in Python 🐍

What is this book?

This is the official documentation of METROPOLIS2, intended for anyone wanting to learn how to use the simulator and how it works.

It is divided in 2 parts: Pymetropolis (chapters 1 to 5) and Metropolis-Core (chapters 6 to 10).

Getting started

Pymetropolis is a Python command line tool that provides an automatic pipeline to generate, calibrate, run and analyze METROPOLIS2 simulation instances.

Pymetropolis can run many operations like:

• Importing a road network from OpenStreetMap data.
• Generating trips from an origin-destination matrix.
• Computing the walking distance of a set of trips.
• Calibrate some parameters to match mode shares from a travel survey.
• Generate the input files for the Metropolis-Core simulator.
• Run the Metropolis-Core simulator.
• Generate graphs from the results of the simulation.

Requirements ☑️

• Recent Python version (3.13+).
• Metropolis-Core executables (metropolis_cli and routing_cli).

Installation 🔧

Pymetropolis’ releases are hosted on PyPI. If you have pip installed (it is usually installed alongside Python), you can install Pymetropolis by simply running:

pip install pymetropolis

To update Pymetropolis to a newer version, run:

pip install --upgrade pymetropolis

To check the version of pymetropolis that is installed on your system, run pymetropolis --version.

How it works 🤷‍♂️

Pymetropolis automates complex simulation workflows by executing a sequence of interdependent Steps. Each Step performs a specific computation and produces one or more MetroFiles (typically Parquet files) containing the results. Steps can also optionally consume MetroFiles as input, enabling flexible data processing.

Steps vary in complexity and functionality. They can:

• Import road networks from OpenStreetMap
• Generate trips from origin-destination matrices
• Compute walking distance for trips
• Run the Metropolis-Core simulator
• Build graphs from simulation results

Pymetropolis automatically determines the execution order of Steps and identifies which ones need re-running if changes occur.

A TOML configuration file defines the simulation instance, including:

• Which area is simulated?
• How the trips are generated?
• How the road network is imported?
• Which modes are available?
• What calibration is performed?
• Etc.

The Steps to execute are automatically derived from this configuration.

Once your configuration is ready, run:

pymetropolis my-config.toml

For large-scale simulations, execution may take hours or even days. If interrupted, Pymetropolis resumes from where it left off, skipping already completed Steps.

When you modify the configuration and re-run the command, Pymetropolis only executes the Steps affected by your changes (e.g., re-importing the road network is unnecessary if only the origin-destination matrix is updated).

Next steps 🧭

Explore practical examples and detailed documentation to get started:

• Case Studies: Step-by-step guides for running simulations, from toy networks to real-world, large-scale cities.
• Reference: Dive deeper into Pymetropolis components:
  • Steps: Available processing steps.
  • Parameters: All the parameters that can be used in the configuration.
  • MetroFiles: Types of files generated and used by Pymetropolis.

Advanced use ⚙️

If you only want to see the Steps that need to be executed without actually running them, use the --dry-run argument:

pymetropolis my-config.toml --dry-run

By default, Pymetropolis tries to execute all the Steps which are properly defined. If you only require a specific Step to be executed, use the --step argument with the Step name:

pymetropolis my-config.toml --step PostprocessRoadNetworkStep

Getting help 🛟

Although Pymetropolis tries to be as reliable and universal as possible, various issues can arise due to the complexity of the process involved and the variety of datasets around the world. Many error messages have been included in the library to explain as clearly the issues that might have occurred.

If you found a bug or if there is a problem that you cannot fix, feel free to open an issue on the GitHub repository.

Concepts

Glossary

Modes

car_driver

The agent is traveling by car. They are driver and presumably have no passenger.

• PCE = 1
• HOV lanes cannot be taken
• Fuel cost = 100%

car_driver_with_passengers

The agent is traveling by car. They are driver and have at least one passenger.

• PCE = 1
• HOV lanes cannot be taken
• Fuel cost = configurable

car_passenger

The agent is traveling by car but they are not driver.

• PCE = 0
• HOV lanes can be taken
• Fuel cost = configurable

car_ridesharing

The agent is traveling by car. There are m persons in the car. It is not known whether the agent is driver or passenger.

• PCE = 1 / m
• HOV lanes can be taken
• Fuel cost = 1 / m

public_transit

walking

bicycle

outside_option

Departure time

Warning

This page is a work-in-progress.

TODO: presentation of the different departure-time choice models in METROPOLIS2 + modeling considerations.

Setting departure_time_choice.mu to a very small value can lead to computational and convergence issues, especially when agents are similar (similar preference parameters, similar origins and destinations). In METROPOLIS2, the utility function is modeled as a piecewise linear function. It is thus not desirable for agents to choose the exact utility-maximizing departure time, as this often falls on breakpoints, causing instability. Therefore, using the Continuous Logit with a sufficiently large departure_time_choice.mu is recommended in all scenarios, even when agents differ. For further details, see Javaudin and de Palma (2024).

Javaudin, L., & de Palma, A. (2024). METROPOLIS2: Bridging theory and simulation in agent-based transport modeling. Technical report, THEMA, CY Cergy Paris Université.

Simulation convergence

• Definition of equilibrium and convergence
• What is a satisfying convergence?
• Which parameters influence convergence?
• How to choose the learning factor parameter?
• How to choose the correct number of iterations?

Modeling congestion

• Bottlenecks

• Spillback

• Speed-density functions

• Passenger Car Equivalent

• Headway

Case studies

Bottleneck model

The simplest simulation that Pymetropolis can run:

• A single road with a bottleneck
• Identical agents with alpha-beta-gamma preferences

Check it out!

Circular City (coming soon)

• A configurable toy network representing a simplified city, with ring and radial roads.
• A gravity origin-destination matrix to easily simulate many trips.

Check it out!

Chambéry, France (coming soon)

• A real-case scenario for a medium-size French city.
• The road network is imported from OpenStreetMap data.
• The public-transit network is imported from GTFS data.
• A synthetic population is used to generate persons with a chain of activities.
• The simulation is calibrated to replicate TomTom and travel survey data.

Check it out!

Bottleneck (Toy model)

Estimated time to complete: 1 hour

The bottleneck model (Vickrey, 1969; Arnott, de Palma et Lindsey, 1990) is a foundational framework in transportation science, designed to analyze how traffic flow dynamics are constrained by capacity limitations at a single bottleneck within a road network.

This case study demonstrates how the bottleneck model with stochastic departure-time choice, as developed by de Palma, Ben-Akiva, Lefèvre, and Litinas (1983), can be replicated using METROPOLIS2. Note that, replicating the deterministic departure-time version remains challenging due to numerical limitations (see Javaudin and de Palma, 2024).

Theoretical framework

The bottleneck model features a single road with a free-flow travel time \(t^f\) and a bottleneck with capacity \(s\) (the maximum rate at which vehicles can cross the bottleneck).

\(N\) agents needs to cross the road and the bottleneck to travel from their origin to their destination. The number of agents is fixed and there is no alternative route which means that departure time is the only choice that matters.

Given a departure time \(t\), the deterministic utility of the agents is \[ v(t) = -\alpha T(t) - \beta [t^* - t - T(t)]^+ - \gamma [t + T(t) - t^*]^+ \tag{1} \] with

• \( \alpha \) the value of time,
• \(T\) the travel-time function,
• \( t^* \) the desired arrival time at destination,
• \( \beta \) the penalty for early arrivals,
• \( \gamma \) the penalty for late arrivals.

Using a Continuous Logit model, the probability that an agent chooses departure time \(t\) is given by \[ p(t) = \frac{ e^{v(t) / \mu} }{ \int_{t^0}^{t^1} e^{v(u) / \mu} d u } \tag{2} \] where \(\mu\) represents the randomness of departure-time choice and \([t^0, t^1]\) represents the period of possible departure times.

Preparation

Simulating the bottleneck model with Pymetropolis is straightforward: you first need to create a TOML configuration file that defines the model parameters and then you need to run Pymetropolis against this file.

Begin by creating a TOML file, such as config-bottleneck.toml, in your preferred directory. This file will contain all the necessary settings for your simulation.

First, specify the directory where all simulation files will be stored using the main_directory parameter.

main_directory = "bottleneck-sim/"

You can provide either an absolute path or a relative path for this directory.

Caution

If you use a relative path, it will be interpreted relative to the working directory from which you run Pymetropolis, which might differ from the directory where the configuration file is located.

To ensure your simulation results are reproducible, you can set a random seed using the random_seed parameter.

random_seed = 123454321

If you omit this parameter, your results may vary slightly each time you run the simulation, even with the same configuration.

Supply side

The supply side of the bottleneck model represents the transport infrastructure available for agents to travel. In this model, the infrastructure consists of a single road, connecting a unique origin to a unique destination, featuring a bottleneck.

This single-road network can be conceptualized as a simplified grid network with one row and two columns. You can define this network in the configuration using the GridNetworkStep.

[grid_network]
nb_rows = 1
nb_columns = 2
length = 1000
right_to_left = false

The road length is set to 1 000 meters (1 km). In the bottleneck model, the length only influences the free-flow travel time of the road, which also depends on the road speed (see below). In this model, the free-flow travel time only shifts departure times without affecting the equilibrium itself. For this reason, it is common in the literature to normalize it to zero. You can do so by setting the length to 0 meters.

The parameter right_to_left is set to false to ensure the network consists of a single road from the left node (origin) to the right node (destination). If set to true, an additional road in the opposite direction would be created.

To complete the road configuration, you need to define the speed limit and bottleneck capacity. This is done using steps PostprocessRoadNetworkStep and ExogenousCapacitiesStep.

Two parameters control this configuration:

• road_network.default_speed_limit: Sets the speed limit on the road (in km/h). Here, it is set to 120 km/h, resulting in a 30-second free-flow travel time from origin to destination.
• road_network.capacities: Defines the bottleneck capacity (in vehicles per hour per lane). In this example, it is set to 16 000 vehicles per hour per lane, meaning a vehicle can cross the bottleneck every 0.24 seconds (3600 / 16000).

[road_network]
default_speed_limit = 120
capacities = 16000

Note

The bottleneck capacity of 16 000 vehicles per hour per lane is unrealistic (real-world lanes typically handle no more than one car per second, or 3 600 cars per hour). However, this toy model serves as a simplified representation of real-world scenarios. It could represent a network of roads connecting suburbs to a city center. Alternatively, it could model a multi-lane corridor (e.g., 8 lanes with a capacity of 2 000 each).

You can explicitly define the number of lanes using the road_network.default_nb_lanes parameter. However, since the total capacity is the critical factor, it is often more straightforward to keep the number of lanes at 1 (the default) and set road_network.capacities directly to the desired total capacity.

Tip

By default, METROPOLIS2 assumes a bottleneck at both the start and end of each road, limiting entry and exit flows. However, when all vehicles travel at the same speed, only the entry bottleneck matters. This is because vehicles reach the end of the road at the same rate they cross the entry bottleneck. In the bottleneck model, the location of the bottleneck does not affect the equilibrium so the default METROPOLIS2 behavior can be unchanged.

Demand side

The demand side of the model represents the agents (commuters) and their travel behavior. Each agent makes a single trip. The first step is to generate these trips.

You can use ODMatrixEachStep to generate a fixed number of trips for each pair of nodes in the road network. The number of trips per origin-destination pair is controlled by the node_od_matrix.each parameter.

[node_od_matrix]
each = 10000

Tip

Pymetropolis automatically detects that the left node has no incoming edge and the right node has no outgoing edge. As a result, trips are only generated from the left node to the right node, not in the reverse direction.

Since no additional population details are specified, Pymetropolis assumes that each trip is made by a unique person. Therefore, it will automatically generate as many persons as trips, with standard characteristics.

Following the standard bottleneck model, it is initially assumed that agents can only travel by car. To specify the available modes, use the mode_choice.modes parameter.

[mode_choice]
modes = ["car_driver"]

Preferences for each mode are configured in the modes.* tables. For the car driver mode, the value of time (in euros per hour) is defined using the modes.car_driver.alpha parameter. This value represents a negative utility: larger values penalize more longer travel times.

[modes]
[modes.car_driver]
alpha = 10

Tip

In this documentation, utilities and costs are typically expressed in euros. However, you can use any currency or unit of your choice. You just need to ensure consistency across all values. For example, if one value is specified in dollars, all utility and cost values must also be in dollars.

The additional preference parameters of the bottleneck model (\( \beta \), \( \gamma \), \( t^* \)) are not mode-specific and therefore not defined in the modes.car_driver table. Instead, these parameters are configured in the departure_time.linear_schedule table. “Linear schedule” refers here to a form of utility function that penalize linearly early and late arrivals relative to a “desired arrival time” (\( t^* \)).

Parameters departure_time.linear_schedule.beta and departure_time.linear_schedule.gamma are both specified in euros per hour and represent negative utilities: higher values represent greater penalties for delays. The parameter departure_time.linear_schedule.tstar represent the desired arrival time, specified in HH:MM:SS value.

[departure_time.linear_schedule]
beta = 5
gamma = 7
tstar = 07:30:00

This configuration indicates that agents aim to arrive at 7:30 a.m., with a larger penalty applied for late arrivals compared to early arrivals.

The parameters specified so far fully specify the utility function (Equation 1). The next step is to define how agents choose their departure time, i.e., the optimization process they use to select a departure time based on their utility.

In METROPOLIS2, the Continuous Logit model is the recommended approach for departure-time choice. This model assumes that agents select their departure time based on probabilities derived from Equation (2). The Continous Logit introduces unobserved heterogeneity, ensuring that even identical agents do no choose the exact same departure time, which helps avoid convergence issues. For further details, see the page on departure-time choice in METROPOLIS.

To use a Continuous Logit model, set the departure_time_choice.model parameter to "ContinuousLogit". The departure_time_choice.mu parameter controls the level of randomness in the choice: smaller values make agents choose departure times closer to the utility-maximizing value; larger values introduce more randomness in their choice.

[departure_time_choice]
model = "ContinuousLogit"
mu = 1

Simulation

Before running the simulation, a few final parameters must be configured in the simulation table.

First, the simulation.period parameter defines the time window of the simulation as a list of two elements: the start time and the end time. This period constrains when agents can depart, though some trips may finish after the end time.

The period also determines the time window during which road-level travel times are recorded. Travel times are stored as piecewise linear functions, with the time between breakpoints controlled by the simulation.recording_interval parameter.

For the bottleneck simulation, it is recommended to set a one-hour period (e.g., from 7 a.m. to 8 a.m.) and to use a small recording interval (e.g., 60 seconds or less) to ensure that agents have precise travel time information when choosing their departure time.

Note

Setting the simulation period to one hour is a form of normalization. If you double the period, recording interval, number of agents, and departure-time mu, then the results will remain qualitatively similar.

Also, if you shift both the simulation period and the desired arrival time earlier or later by the same duration, then the departure and arrival times of the agents will shift accordingly.

Finally, two parameters are chosen to ensure the simulation converges satisfactorily:

• simulation.learning_factor controls how quickly agents learns about travel times, a value of 0.1 is recommended;
• simulation.nb_iterations determines the number of iterations the simulation runs, a value of 200 is typically sufficient here.

[simulation]
period = [07:00:00, 08:00:00]
recording_interval = 60
learning_factor = 0.1
nb_iterations = 200

Tip

For bottleneck simulations with a higher ratio of agents to bottleneck capacity, consider decreasing the learning factor or increasing the number of iterations.

For more details on simulation convergence, refer to the relevant page.

Also ensure that you have downloaded the last version of Metropolis-Core and set the metropolis_core.exec_path parameter to point to the metropolis_cli executable. By convention, the executable is typically placed in an execs/ directory within the directory where Pymetropolis is executed.

[metropolis_core]
exec_path = "execs/metropolis_cli"

Note

For Windows user, you do not need to add the ".exe" extension to metropolis_cli in exec_path. It is actually recommended not to do so, so that your configuration can be shared easily with MacOS and Linux users.

Running

Once your configuration file is ready, you can execute Pymetropolis directly from the terminal. Simply run the pymetropolis command, specifying the path to your configuration file as an argument.

Optionally, before running the full simulation, you can check what Pymetropolis is planning to do by using the --dry-run option. This will check for typos or issues and display the list of steps that will be executed:

pymetropolis config-bottleneck.toml --dry-run

If there everything is correctly configured, you should see an output similar to this.

1. WriteMetroParametersStep
2. GridNetworkStep
3. PostprocessRoadNetworkStep
4. AllRoadDistancesStep
5. ODMatrixEachStep
6. CarShortestDistancesStep
7. ExogenousCapacitiesStep
8. EdgesFreeFlowTravelTimesStep
9. AllFreeFlowTravelTimesStep
10. CarFreeFlowDistancesStep
11. GenericPopulationStep
12. WriteMetroEdgesStep
13. WriteMetroVehicleTypesStep
14. CarDriverPreferencesStep
15. LinearScheduleStep
16. WriteMetroAgentsStep
17. HomogeneousTstarStep
18. WriteMetroTripsStep
19. UniformDrawsStep
20. WriteMetroAlternativesStep
21. RunSimulationStep
22. IterationResultsStep
23. ConvergencePlotStep
24. RoadNetworkCongestionFunctionPlotsStep
25. TripResultsStep
26. TripDepartureTimeDistributionStep

If the list of steps looks correct, you can proceed with the actual simulation by removing the --dry-run option.

pymetropolis config-bottleneck.toml

The simulation should complete in about one minute.

Convergence

Before diving into the results, the first step is to verify whether the simulation has converged satisfactorily. If the convergence is poor, further analysis may not be meaningful, and you may need to adjust the number of iterations or the learning factor (See Simulation convergence).

Pymetropolis automatically generates convergence graphs in the results/graphs/ directory (located within the main_directory you specified). These graphs are prefixed with convergence_.

For the bottleneck simulation, you can focus on these graphs:

• convergence_tour_departure_time.png shows by how much departure times vary over iterations;
• convergence_simulated_road_travel_times.png shows by how much the simulated travel-time function differs from the expected travel-time function over iterations.

If your graphs match the examples below, with the indicator consistently at zero in the final iterations, the simulation has perfectly converged and results are reliable for analysis.

Note

At each iteration of METROPOLIS2, all agents choose their preferred departure time, across the entire possible departure-time period, based on the current expected travel-time function. If the simulated travel-time function matches the expected travel-time function, it means that agents made optimal choices: they accurately anticipated travel conditions and have no reason to change their departure time. Therefore, when departure times and travel times are unchanged between iterations, the simulation has effectively reached an equilibrium.

Tip

In this example, the simulation achieves perfect convergence. However, in more complex scenarios, perfect convergence may not always be attainable. Instead, ensure that the convergence indicators remain consistently low in the final iterations. This suggests that the simulation approximate an equilibrium, even if minor fluctuations persist. Such level of stability is often sufficient for meaningful analysis.

Results

Pymetropolis generates a variety of output files that you can use to analyze the simulation results. The most relevant files for the bottleneck simulation are:

• results/iteration_results.parquet gives aggregate results across all iterations;
• results/trip_results.parquet gives trip-level results, including departure times, arrival times, utilities.

Feel free to explore these files to generate your own tables and graphs.

Pymetropolis also produces graphs to visualize key aspects of the simulation:

• results/graphs/trip_departure_time_distribution.png for the distribution of departure times;
• results/graphs/network_congestion_function_expected.png for the congestion function on the road.

For additional graphs and a comparison with analytical results, refer to Javaudin and de Palma (2024).

Extensions

Elastic demand

A simple way to extend the bottleneck model is to incorporate elastic demand by giving agents an alternative to traveling by car. This alternative could represent options like using public transit or choosing not to travel at all.

In Pymetropolis, you can model such an alternative using the "outside_option" mode. This mode provides a constant cost (or utility) alternative to the agents, without modeling departure times or travel times.

The modes.outside_option.constant parameter defines the constant cost associated to the outside option. Based on the previous simulation results, where agents’ surplus is around 7.25, you can set the outside option’s utility to 5 (i.e., its cost to -5) to ensure it remains less attractive than driving.

[modes.outside_option]
constant = -5

Caution

The [modes.outside_option] table must be nested within the [modes] section. If you are unsure about the syntax, refer to the TOML documentation or the complete configuration example below for guidance.

Adding the outside option introduces a new decision for agents: choosing between driving or not. You need to specify how agents choose between these two options, using the mode_choice.model parameter.

A standard approach is to use a Logit model, which allows agents to make probabilistic choices based on the utility of each option. Configure this by updating the [mode_choice] table in your configuration, setting mode_choice.model to "Logit".

[mode_choice]
modes = ["car_driver", "outside_option"]
model = "Logit"
mu = 1

The mode_choice.mu parameter controls the level of randomness in the choice: smaller values make agents more likely to choose the utility-maximizing option; larger values introduce more randomness in their decision. Also observe that you need to include "outside_option" in the list of modes available to the agents.

Distributed parameters

So far, the simulated agents were identical: they shared the same origin, destination, value of time, schedule-delay penalties, and desired arrival time. Crucially, some form of heterogeneity was introduced through the Continous Logit model (for departure-time choice) and the Logit model (for mode choice). This heterogeneity is essential to prevent all agents from choosing the same departure time, which would result in unrealistic congestion patterns.

You can introduce additional variability by defining preference parameters, such as modes.car_driver.alpha or departure_time.linear_schedule.beta, as distributions rather than fixed values. For example, to model the desired arrival time as a Normal distribution with a mean of 07:30:00 and a standard deviation of 10 minutes (600 seconds), you can use the following configuration.

tstar = { mean = 07:30:00, std = 600, distribution = "Normal" }

The same syntax can be applied to any preference parameter that supports distributions. For more details on the syntax and the available distributions, refer to the Parameters page.

Complete configuration

main_directory = "bottleneck-sim/"

random_seed = 123454321

[grid_network]
nb_rows = 1
nb_columns = 2
length = 1000
right_to_left = false

[road_network]
default_speed_limit = 120
capacities = 16_000

[node_od_matrix]
each = 10_000

[mode_choice]
modes = ["car_driver"]
# Uncomment to add the outside option alternative.
#modes = ["car_driver", "outside_option"]
#model = "Logit"
#mu = 1

[modes]
[modes.car_driver]
alpha = 10

# Uncomment to add the outside option alternative.
#[modes.outside_option]
#constant = -5

[departure_time_choice]
model = "ContinuousLogit"
mu = 1

[departure_time.linear_schedule]
beta = 5
gamma = 7
# Constant tstar over agents.
tstar = 07:30:00
# Normally distributed tstar over agents.
#tstar = { mean = 07:30:00, std = 600, distribution = "Normal" }

[simulation]
period = [07:00:00, 08:00:00]
recording_interval = 60
learning_factor = 0.1
nb_iterations = 200

[metropolis_core]
exec_path = "execs/metropolis_cli"

References

Arnott, R., de Palma, A., & Lindsey, R. (1990). Economics of a bottleneck. Journal of urban economics, 27(1), 111-130.

de Palma, A., Ben-Akiva, M., Lefevre, C., & Litinas, N. (1983). Stochastic equilibrium model of peak period traffic congestion. Transportation Science, 17(4), 430-453.

Javaudin, L., & de Palma, A. (2024). METROPOLIS2: Bridging theory and simulation in agent-based transport modeling. Technical report, THEMA, CY Cergy Paris Université.

Vickrey, W. S. (1969). Congestion theory and transport investment. The American economic review, 59(2), 251-260.

Circular City (Toy model)

Estimated time to complete: 2 hours

This case study presents a toy model designed to be both simple and feature-rich:

• Quick to run: Executes in just a few minutes.
• Concise configuration: Requires only a single TOML file (~100 lines).
• Comprehensive: Incorporates most of METROPOLIS2’s core features, including mode choice, departure-time choice, route choice, fuel consumption, spillback effects, and ridesharing.

The model simulates an imaginary circular city, featuring ring roads (circular roads) and radial roads (arterial roads).

This structure is inspired by the foundational work of de Palma, Kilani, and Lindsey (2005), though it is not an exact replication. Instead, it offers a modern adaptation tailored for METROPOLIS2.

Preparation

As for the Bottleneck case study, begin by creating a TOML configuration file (e.g., config-circular-city.toml) in your preferred directory. This file serves as the foundation for your simulation.

Start by defining the main_directory and random_seed parameters in your configuration file. The main_directory specifies where all simulation outputs will be saved, while the random_seed ensures your results are reproducible.

# config-circular-city.toml
main_directory = "circular-city/"

random_seed = 123454321

Supply side

The Circular City model uses the CircularNetworkStep to create a customizable road network composed of ring roads and radial roads.

The nb_radials parameter defines the number of directions for radial roads:

• nb_radials = 4: creates radial roads in the North, East, South, and West directions;
• nb_radials = 8: adds Northeast, Northwest, Southeast, and Southwest directions;
• nb_radials = n: n roads are automatically generated starting from the East direction and are evenly spaced around the circle.

Parameter nb_rings controls the number of concentric rings in the city and parameter radius defines the distance between rings (in meters). If radius is a single value, for example radius = 2000, each ring is space 2 km apart from the city center. If radius is a list, for example radius = [1000, 1500] (with nb_rings = 2), the first ring is 1 km from the center and the second is 1.5 km from the center (500 m apart).

Nodes are automatically created at the intersection of each ring and radial road.

For more details, including how node and edge ids are generated, refer to the CircularNetworkStep documentation.

For the same topological network as in de Palma et al. (2005), use the following configuration. Feel free to tweak it to your liking!

[circular_network]
nb_radials = 8
nb_rings = 4
radius = 4000

Tip

If you are more into American-style cities, consider creating a grid network instead.

To finalize the Circular City network configuration, you need to define the speed limits, number of lanes and bottleneck capacities. This is done using PostprocessRoadNetworkStep and ExogenousCapacitiesStep, similar to the Bottleneck case study.

The key parameters are:

• road_network.default_speed_limit sets the speed limit (in km/h);
• road_network.default_nb_lanes defines the number of lanes (in one direction);
• road_network.capacities specifies the bottleneck capacity (in vehicles per hour per lane).

The values can be specified per road type (see map) by providing a TOML table with the road-type labels as keys. To replicate the values from de Palma et al. (2005), use the following configuration.

[road_network]
[road_network.default_speed_limit]
"Radial 1" = 50
"Radial 2" = 50
"Radial 3" = 50
"Radial 4" = 50
"Ring 1" = 50
"Ring 2" = 70
"Ring 3" = 70
"Ring 4" = 70

[road_network.default_nb_lanes]
"Radial 1" = 2
"Radial 2" = 2
"Radial 3" = 2
"Radial 4" = 2
"Ring 1" = 1
"Ring 2" = 1
"Ring 3" = 1
"Ring 4" = 1

[road_network.capacities]
"Radial 1" = 1500
"Radial 2" = 2000
"Radial 3" = 2000
"Radial 4" = 2000
"Ring 1" = 2000
"Ring 2" = 2000
"Ring 3" = 2000
"Ring 4" = 2000

Demand side

To simulate trips in the Circular City model, you can use an origin-destination matrix, where road-network nodes serve as origins and destinations.

In real-world scenarios, the number of trips between two nodes typically decreases with distance. The GravityODMatrixStep models this effect by assuming that the number of trips between nodes decays exponentially with distance.

The key parameters for this step are defined below.

• trips_per_node defines the total number of trips originating from each node.
• exponential_decay controls how quickly the number of trips decreases with distance. With exponential_decay = 0, trips originating from a node are uniformly distributed across all destinations. With higher values, more trips are concentrated toward closer destinations.

[gravity_od_matrix]
trips_per_node = 8000
exponential_decay = 0.07

Tip

If you want different number of trips originating from each node, you can define trips_per_node as a distribution. For example:

trips_per_node = { mean = 8000, std = 1000, distribution = "Normal" }

Tip

For full control over trip generation, you can create your own origin-destination matrix and use it with the CustomODMatrixStep.

To align with de Palma et al. (2005), you can configure agents to choose between car and public transit using a Logit model. This setup allows agents to make probabilistic choices based on the utility of each mode.

[mode_choice]
modes = ["car_driver", "public_transit"]
model = "Logit"
mu = 1

The parameters are defined as follow.

• modes lists the available travel modes.
• model uses the Logit model for mode choice.
• mu controls the randomness in mode select. Lower values means that agents are more likely to choose the maximum-utility mode.

Tip

For more advanced scenarios, you can include ridesharing as an additional mode. This extension is explored further in the Extensions section.

Preferences for each mode are defined in the modes.* tables. Each mode includes two parameters.

• alpha represents the value of time (in euros per hour).
• constant represents a fixed cost associated with choosing the mode.

[modes]
[modes.car_driver]
constant = 0
alpha = 10

[modes.public_transit]
constant = 2.0
alpha = 15.0
road_network_speed = 40

The parameter road_network_speed simplifies public-transit travel time calculation by assuming a constant speed on the road network, avoiding the need to define a separate public-transit network. A value of 40 km/h matches the assumption from de Palma et al. (2005).

As in the Bottleneck case study, you can include schedule-delay penalties in the utility function using the departure_time.linear_schedule table. These penalties influence agents’ departure-time choice based on their desired arrival time.

• beta defines the penalty for early arrivals (in euros per hour).
• gamma defines the penalty for late arrivals (in euros per hour).
• tstar represent the desired arrival time at destination, specified in HH:MM:SS format.

[departure_time.linear_schedule]
beta = 6
gamma = 25
tstar = { mean = 08:00:00, std = 1800, distribution = "Uniform" }

This configuration means that agents have a desired arrival time uniformly distributed between 07:30:00 and 08:30:00. Late arrivals incur a higher penalty (25 euros per hour) compared to early arrivals (6 euros per hour).

To model how agents choose their departure time, it is recommended using the Continuous Logit model, which aligns with the approach in de Palma et al. (2005).

Set departure_time_choice.model to "ContinuousLogit" and use departure_time_choice.mu to control the randomness in agents’ choices: smaller values make agents choose departure times closer to the utility-maximizing value; larger values introduce more randomness in their choice.

[departure_time_choice]
model = "ContinuousLogit"
mu = 1

Simulation

Before running the simulation, configure the final parameters in the simulation table.

[simulation]
period = [06:00:00, 10:00:00]
recording_interval = 300
learning_factor = 0.005
nb_iterations = 200

The simulation.period parameter defines the time window of the simulation, specified as a list of start and end times. This period constrains when agents can depart.

For this simulation, focused on the morning peak period (with desired arrival times between 07:30 and 08:30), a period from 6 a.m. to 10 a.m. provides a sufficiently wide window for all agents to depart and reach their destinations.

Tip

If you notice a peak of departures at the very start or end of the simulation period, it may indicate that the period is too narrow. Extend the window to allow agents to choose departure times that align better with their desired arrival times.

The simulation.recording_interval parameter controls the time between breakpoints in the piecewise linear functions used to store travel times. A value of 300 seconds (5 minutes) offers a good balance between simulation speed and accuracy in travel-time functions.

To ensure the simulation converges satisfactorily, two key parameters are defined.

• simulation.learning_factor controls how quickly agents learns about travel times. A value of 0.005 is recommended for this simulation.
• simulation.nb_iterations determines the number of iterations the simulation runs. A value of 200 is typically sufficient.

Tip

For simulations with higher congestion, consider decreasing the learning factor or increasing the number of iterations to improve the convergence quality.

For more details on simulation convergence, refer to the relevant page.

Before running your simulation, ensure you have downloaded the last version of Metropolis-Core and configured the metropolis_core.exec_path parameter to point to the metropolis_cli executable. By convention, the executable is typically placed in an execs/ directory within the directory where Pymetropolis is executed.

[metropolis_core]
exec_path = "execs/metropolis_cli"

Running

Once your configuration file is ready, you can execute Pymetropolis directly from the terminal. Simply run the pymetropolis command, specifying the path to your configuration file as an argument.

Optionally, before running the full simulation, you can check what Pymetropolis is planning to do by using the --dry-run option. This will check for typos or issues and display the list of steps that will be executed:

pymetropolis config-circular-city.toml --dry-run

If there everything is correctly configured, you should see an output similar to this.

1. WriteMetroParametersStep
2. CircularNetworkStep
3. PostprocessRoadNetworkStep
4. AllRoadDistancesStep
5. ExogenousCapacitiesStep
6. EdgesFreeFlowTravelTimesStep
7. AllFreeFlowTravelTimesStep
8. GravityODMatrixStep
9. CarFreeFlowDistancesStep
10. CarShortestDistancesStep
11. GenericPopulationStep
12. WriteMetroEdgesStep
13. WriteMetroVehicleTypesStep
14. CarDriverPreferencesStep
15. PublicTransitPreferencesStep
16. PublicTransitTravelTimesFromRoadDistancesStep
17. RoadODMatrixStep
18. LinearScheduleStep
19. HomogeneousTstarStep
20. WriteMetroTripsStep
21. UniformDrawsStep
22. WriteMetroAgentsStep
23. WriteMetroAlternativesStep
24. RunSimulationStep
25. IterationResultsStep
26. ConvergencePlotStep
27. RoadNetworkCongestionFunctionPlotsStep
28. TripResultsStep
29. TripDepartureTimeDistributionStep

If the list of steps looks correct, you can proceed with the actual simulation by removing the --dry-run option.

pymetropolis config-circular-city.toml

The simulation should complete in about 20 minutes.

Convergence

Before diving into the results, the first step is to verify whether the simulation has converged satisfactorily. If the convergence is poor, further analysis may not be meaningful, and you may need to adjust the number of iterations or the learning factor (See Simulation convergence).

Pymetropolis automatically generates convergence graphs in the results/graphs/ directory (located within the main_directory you specified). These graphs are prefixed with convergence_ and fall into two main categories.

• Graphs with an indicator representing a change from one iteration to another. The indicator should be close to zero in the final iterations. Example graphs:
  • convergence_tour_departure_time.png: shifts in departure times,
  • convergence_route_length_diff.png: shifts in route selected,
  • convergence_simulated_road_travel_times.png: changes in road-level travel times.
• Graphs with an indicator representing an aggregate measure. The indicator should stabilize to an equilibrium value in the final iterations. Example graphs:
  • convergence_mean_surplus.png: mean surplus,
  • convergence_road_trips_share.png: share of road trips.

Results

Pymetropolis generates a variety of output files that you can use to analyze the simulation results. Some of the most relevant files are:

• results/iteration_results.parquet gives aggregate results across all iterations;
• results/trip_results.parquet gives trip-level results, including departure times, arrival times, utilities.

Feel free to explore these files to generate your own tables and graphs.

Pymetropolis also produces graphs to visualize key aspects of the simulation:

• results/graphs/trip_departure_time_distribution.png for the distribution of departure times;
• results/graphs/network_congestion_function_expected.png for the congestion function on the road.

Complete configuration

main_directory = "circular-city/"

random_seed = 123454321

[circular_network]
nb_radials = 8
nb_rings = 4
radius = 4000

[road_network]
[road_network.default_speed_limit]
"Radial 1" = 50
"Radial 2" = 70
"Radial 3" = 70
"Radial 4" = 70
"Ring 1" = 50
"Ring 2" = 50
"Ring 3" = 50
"Ring 4" = 50

[road_network.default_nb_lanes]
"Radial 1" = 2
"Radial 2" = 2
"Radial 3" = 2
"Radial 4" = 2
"Ring 1" = 1
"Ring 2" = 1
"Ring 3" = 1
"Ring 4" = 1

[road_network.capacities]
"Radial 1" = 1500
"Radial 2" = 2000
"Radial 3" = 2000
"Radial 4" = 2000
"Ring 1" = 2000
"Ring 2" = 2000
"Ring 3" = 2000
"Ring 4" = 2000

[gravity_od_matrix]
exponential_decay = 0.07
trips_per_node = 8000

[mode_choice]
modes = ["car_driver", "public_transit"]
model = "Logit"
mu = 1

[modes]
[modes.car_driver]
constant = 0
alpha = 10

[modes.public_transit]
constant = 2
alpha = 15
road_network_speed = 40

[departure_time_choice]
model = "ContinuousLogit"
mu = 1

[departure_time.linear_schedule]
beta = 6
gamma = 25
tstar = { mean = 08:00:00, std = 1800, distribution = "Uniform" }

[simulation]
period = [06:00:00, 10:00:00]
recording_interval = 300
learning_factor = 0.005
nb_iterations = 200

[metropolis_core]
exec_path = "execs/metropolis_cli"

Extensions

Introducing ridesharing

In the current setup, agents traveling by car are assumed to be driving alone, with each agent generating congestion equivalent to a single car. However, in reality, people with similar origins and destinations often share rides to save on costs like fuel.

METROPOLIS2 proposes the "car_ridesharing" mode to model ridesharing. This mode represents agents traveling by car with others, without distinguishing between drivers and passengers.

To include this mode as an option for the agents, update the mode_choice.modes parameter.

[mode_choice]
modes = ["car_driver", "car_ridesharing", "public_transit"]

Note

The "car_ridesharing" mode is a basic representation of ridesharing in METROPOLIS2:

• It does not explicitly model the matching between drivers and passengers.
• It does not guarantee that agents choosing ridesharing have a compatible partner with the same origin, destination, and departure time.
• It does not account for detours drivers might take to pick up or drop off passengers.

For advanced ridesharing modeling in METROPOLIS2, including matching, refer to Ghoslya et al. (2025).

You can define preferences for the "car_ridesharing" mode different from the ones for "car_driver".

• constant represents the fixed cost of ridesharing (e.g., difficulty finding a match, detours, waiting time).
• alpha represents the value of time (which can be different from car alone due to inconvenience).

[modes.car_ridesharing]
constant = 2.0
alpha = 11.0

Since ridesharing involves multiple persons per car, the congestion generated must be adjusted. METROPOLIS2 simulates one car per ridesharing agent, but you can modify the Passenger Car Equivalent (PCE) and headway to reflect the reduced congestion impact of shared rides.

• If ridesharing agents travel in pairs, PCE and headway must be divided by 2.
• If they travel in groups of three, PCE and headway must be divided by 3.
• In general, if the average number of passengers per ridesharing car is n, PCE and headway must be divided by 1 + n.

The average number of passengers is controlled by the vehicle_types.car.ridesharing_passenger_count parameter. For France, this value is approximately 1.2.

[vehicle_types]
[vehicle_types.car]
ridesharing_passenger_count = 1.2

Tip

You can also use the "car_ridesharing" mode as a complete substitute for "car_driver" if you want to model ridesharing without distinguishing between solo and shared trips. In this case, you need to assume the same constant cost and value of time for all car trips. Additionally, ridesharing_passenger_count must be set to the average number of passengers per car (including solo drivers). For France, this value is around 0.4 (or lower during peak hours).

However, this approach is not adapted when you want to model different preferences for solo and shared trips and when you want to simulate HOV lanes.

Adding fuel costs to car trips

In the current setup, ridesharing offers no clear individual benefit in the model:

• Both the constant cost and the value of time are larger than for car alone.
• Travel times are identical for solo and shared trips.

The only reason some agents choose "car_ridesharing" is due to the Logit model’s randomness, which introduces variability in mode choice.

In reality, ridesharing is attractive because it allows sharing costs (e.g., fuel, tolls) among participants. METROPOLIS2 can model fuel costs using two parameters.

• fuel.consumption_factor represents the fuel consumption rate for car trips, in liters per kilometer. A value of 0.08 equals a consumption of 8 liters per 100 km.
• fuel.price defines the price per liter of fuel, in euros.

[fuel]
consumption_factor = 0.08
price = 1.8

With this configuration, fuel cost are included in the utility function for both "car_driver" and "car_ridesharing". However, for "car_ridesharing", the fuel cost is divided by the ridesharing_passenger_count, which can make ridesharing more attractive than driving alone.

Caution

METROPOLIS2 currently does not compute fuel consumption dynamically based on the selected route during each iteration. Instead, it uses pre-simulation free-flow consumption.

When fuel costs are included, the model shows an increase in both ridesharing and public-transit use.

Enhancing ridesharing with HOV lanes

High-Occupancy Vehicle (HOV) lanes are an effective way to make ridesharing more attractive. These lanes are restricted to cars with at least two passengers (including the driver). If they are less congested than regular lanes, they can reduce travel times for ridesharing user compared to solo drivers.

HOV lanes are defined using the road_network.hov_lanes parameter. This parameter works similarly to road_network.nb_lanes: you can specify a single value (applied to all edges) or you can use a table to define HOV lanes for specific road types.

[road_network.hov_lanes]
"Ring 1" = 1
"Ring 2" = 1

In his example, edges with road types "Ring 1" and "Ring 2" have one HOV lane, while, for other road types, the default value (no HOV lane) is used.

Caution

The road_network.hov_lanes does not add extra lanes to edges. Instead, it reserves lanes from the total defined by road_network.nb_lanes. An edge cannot have more HOV lanes than its total lanes (hov_lanes ≤ nb_lanes).

You can create edges with only HOV lanes (nb_lanes = hov_lanes), effectively banning solo drivers from those edges. However, ensure that solo drivers can still reach their destination via alternative routes.

Tip

Both road_network.nb_lanes and road_network.hov_lanes support non-integer values. For example, you can set hov_lanes = 0.5 to model HOV lanes in a “continuous” way.

Matching constant

Coming soon.

Nested Logit for mode choice

Coming soon-ish.

Complete configuration with ridesharing

main_directory = "circular-city-ridesharing/"

random_seed = 123454321

[circular_network]
nb_radials = 8
nb_rings = 4
radius = 4000

[road_network]
[road_network.default_speed_limit]
"Radial 1" = 50
"Radial 2" = 50
"Radial 3" = 50
"Radial 4" = 50
"Ring 1" = 50
"Ring 2" = 70
"Ring 3" = 70
"Ring 4" = 70

[road_network.default_nb_lanes]
"Radial 1" = 1
"Radial 2" = 1
"Radial 3" = 1
"Radial 4" = 1
"Ring 1" = 2
"Ring 2" = 2
"Ring 3" = 2
"Ring 4" = 2

[road_network.capacities]
"Radial 1" = 1500
"Radial 2" = 2000
"Radial 3" = 2000
"Radial 4" = 2000
"Ring 1" = 2000
"Ring 2" = 2000
"Ring 3" = 2000
"Ring 4" = 2000

[road_network.hov_lanes]
"Ring 1" = 1
"Ring 2" = 1

[gravity_od_matrix]
exponential_decay = 0.07
trips_per_node = 8000

[mode_choice]
modes = ["car_driver", "car_ridesharing", "public_transit"]
model = "Logit"
mu = 1.0

[modes]
[modes.car_driver]
constant = 0.0
alpha = 10.0

[modes.car_ridesharing]
constant = 2.0
alpha = 11.0

[modes.public_transit]
constant = 2.0
alpha = 15.0
road_network_speed = 40

[departure_time_choice]
model = "ContinuousLogit"
mu = 1.0

[departure_time.linear_schedule]
beta = 6.0
gamma = 25.0
tstar = { mean = 08:00:00, std = 1800, distribution = "Uniform" }

[vehicle_types]
[vehicle_types.car]
ridesharing_passenger_count = 1.2

[fuel]
consumption_factor = 0.08
price = 1.8

[simulation]
period = [06:00:00, 10:00:00]
recording_interval = 300
learning_factor = 0.005
nb_iterations = 200

[metropolis_core]
exec_path = "execs/metropolis_cli"

References

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.

Ghoslya, S., Javaudin, L., Palma, A. D., & Delle Site, P. (2025). Ride-sharing, congestion, departure-time and mode choices: A social optimum perspective. Available at SSRN 5465467.

Chambéry, France

Caution

This case study is incomplete and outdated.

Chambéry

Chambéry is a French city in the Savoie department, near the Alps. In 2021, the population of Chambéry was 59,856.

It is the largest city of the Chambéry Metropolitan area (Aire d’attraction de Chambéry) which has a population of 261,463 and an area of 1,147 km² (2021). The Metropolitan area of Chambéry consists of 115 French municipalities.

Chambéry has been selected for this case study due to its small size (reducing running times) and the availability of a recent travel survey (2022).

General Configuration

Before running the metropy pipeline, we need to create the TOML configuration file that specifies all the parameters of the simulation.

Create the config-chambery.toml file with the following content:

# File: config-chambery.toml
main_directory = "./chambery/output/"
crs = "EPSG:2154"
osm_file = "./chambery/data/rhone-alpes-250101.osm.pbf"

The main_directory variable represents the directory in which all the output files generated by the pipeline will be saved. The directory will be created automatically if it does not exist yet.

The crs variable represents the projected coordinate system to be used for all operations with the spatial data (such as measuring the length of the road links). The value "EPSG:2154" represents the Lambert-93 projection, which is adapted for any area in Metropolitan France.

The osm_file variable specifies the path to the OpenStreetMap input file that will be used to import the road and walking network. We use the extract of the Rhône-Alpes French administrative region from 2025-01-01, that can be downloaded from Geofabrik (click on raw directory index to access older versions). The Rhône-Alpes region is adapted for our case study given that the Chambéry urban area is full contained within it.

Simulation Area

• Step: simulation-area
• Running time: 2 seconds

We define the simulation area as the Chambéry Metropolitan area (aire d’attraction) so that we get an area large enough to encompass most of the trips from and to Chambéry’s municipality.

To tell metropy to create the simulation area from the Chambéry Metropolitan area, add the following section to the configuration:

[simulation_area]
aav_name = "Chambéry"
buffer = 8000

The buffer = 8000 line tells metropy to extend the area by 8 kilometers in all directions. This is used to include roads in the simulation that are not inside the Metropolitan area but that could be taken when traveling between two municipalities within the area.

The output file ./chambery/output/simulation_area.parquet can be opened with QGIS to draw a map.

OpenStreetMap Road Import

• Step: osm-road-import
• Running time: 2 minutes

We use the osm-road-import step to import the road network from OpenStreetMap. The step will read the osm_file variable previously defined.

Add the following section to the configuration:

[osm_road_import]
highways = [
  "motorway",
  "motorway_link",
  "trunk",
  "trunk_link",
  "primary",
  "primary_link",
  "secondary",
  "secondary_link",
  "tertiary",
  "tertiary_link",
  "living_street",
  "unclassified",
  "residential",
]
urban_landuse = [
  "commercial",
  "construction",
  "education",
  "industrial",
  "residential",
  "retail",
  "village_green",
  "recreation_ground",
  "garages",
  "religious",
]
urban_buffer = 50

The highways parameter lists all the OSM highway tags to be imported. In this case, all the standard tags are considered, including living streets, residential streets and unclassified streets. We do not consider however the service and road tags, which usually represent car park alleys or other special roads we are not interested in.

The urban_landuse parameter lists all the OSM landuse tags to be classified as urban. The roads which are fully contained within urban areas will be classified as “urban”. The urban areas are extended by 50 meters, through the urban_buffer parameter, so that roads partially outside urban areas are also classified as “urban”.

After the step is completed, some statistics are reported in the file ./chambery/output/osm-road-import/output.txt. They show that the imported road network has:

• 37 088 nodes
• 77 884 edges
• The total length of edges is 13 990 km
• 69.4 % of edges are classified as “urban”
• 2.2 % of edges are roundabouts
• 0.5 % of edges have traffic signals
• 1.0 % of edges have a stop sign
• 1.3 % of edges have a give-way sign
• 1.0 % of edges have tolls
• 68.7 % of edges do not have a speed limit reported
• 84.4 % of edges do not have a number of lanes reported

The directory ./chambery/output/graphs/osm-road-import/ also contains some graphs generated from the imported data. For example, the following pie chart reports the share of edges by road type (the category “other” regroup all road types with few observations).

The two output files ./chambery/output/osm-road-import/edges_raw.parquet and ./chambery/output/osm-road-import/urban_areas.parquet can be opened with QGIS to draw a map of edges…

and urban areas…

References

Steps

AllFreeFlowTravelTimesStep

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

• Input files: CleanEdgesFile, EdgesFreeFlowTravelTimeFile

• Output files: AllFreeFlowTravelTimesFile

AllRoadDistancesStep

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

• Input files: CleanEdgesFile

• Output files: AllRoadDistancesFile

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.

• Parameters: modes.car_driver.alpha, modes.car_driver.constant, random_seed

• Input files: PersonsFile

• Output files: CarDriverPreferencesFile

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.

• Parameters: modes.car_driver_with_passengers.alpha, modes.car_driver_with_passengers.constant, random_seed

• Input files: PersonsFile

• Output files: CarDriverWithPassengersPreferencesFile

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

• Input files: CarODsFile, CleanEdgesFile, EdgesFreeFlowTravelTimeFile

• Output files: CarFreeFlowDistancesFile

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.

• Parameters: fuel.consumption_factor, fuel.price

• Input files: CarFreeFlowDistancesFile

• Output files: CarFuelFile

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.

• Parameters: modes.car_passenger.alpha, modes.car_passenger.constant, random_seed

• Input files: PersonsFile

• Output files: CarPassengerPreferencesFile

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.

• Parameters: modes.car_ridesharing.alpha, modes.car_ridesharing.constant, random_seed

• Input files: PersonsFile

• Output files: CarRidesharingPreferencesFile

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

• Input files: AllRoadDistancesFile, CarODsFile

• Output files: CarShortestDistancesFile

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.

• Parameters: circular_network.entry_ramps_length, circular_network.exit_ramps_length, circular_network.nb_radials, circular_network.nb_rings, circular_network.radial_inter_ramp_length, circular_network.radius, circular_network.resolution, circular_network.ring_inter_ramp_length, circular_network.with_ramps

• Output files: RawEdgesFile

ConvergencePlotStep

Generates various graphs to analyze the convergence of the simulation.

• Input files: IterationResultsFile

• Output files: ExpectedRoadTravelTimesConvergencePlotFile, SimulatedRoadTravelTimesConvergencePlotFile, TourDepartureTimeConvergencePlotFile

CustomODMatrixStep

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

• Parameters: od_matrix.file, random_seed

• Input files: CleanEdgesFile

• Output files: CarODsFile

CustomRoadImportStep

Imports a road network from a geospatial file.

The file must have the same schema has the RawEdgesFile.

• Parameters: custom_road_import.edges_file

• Output files: 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.

• Parameters: zones.custom_zones

• Output files: ZonesFile

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

• Input files: CleanEdgesFile, EdgesPenaltiesFile (optional)

• Output files: EdgesFreeFlowTravelTimeFile

ExogenousCapacitiesStep

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

The bottleneck capacities can be:

• constant over edges

• constant by road type

• constant by combinations of road type and urban flag

• Parameters: road_network.capacities

• Input files: CleanEdgesFile

• Output files: EdgesCapacitiesFile

ExogenousEdgePenaltiesStep

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

The penalties can be:

• constant over edges

• constant by road type

• constant by combinations of road type and urban flag

• Parameters: road_network.penalties

• Input files: CleanEdgesFile

• Output files: EdgesPenaltiesFile

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.

• Input files: CarODsFile

• Output files: HouseholdsFile, PersonsFile, TripsFile

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

• Parameters: gravity_od_matrix.exponential_decay, gravity_od_matrix.nodes_regex, gravity_od_matrix.trips_per_node, random_seed

• Input files: AllFreeFlowTravelTimesFile

• Output files: CarODsFile

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

• Parameters: grid_network.bottom_to_top, grid_network.left_to_right, grid_network.length, grid_network.nb_columns, grid_network.nb_rows, grid_network.right_to_left, grid_network.top_to_bottom

• Output files: RawEdgesFile

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.

• Parameters: departure_time.linear_schedule.tstar, random_seed

• Input files: TripsFile

• Output files: TstarsFile

IterationResultsStep

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

• Input files: MetroIterationResultsFile

• Output files: IterationResultsFile

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.

• Parameters: departure_time.linear_schedule.beta, departure_time.linear_schedule.delta, departure_time.linear_schedule.gamma, random_seed

• Input files: TripsFile

• Output files: LinearScheduleFile

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

• Parameters: node_od_matrix.each, random_seed

• Input files: CleanEdgesFile

• Output files: CarODsFile

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.

• Parameters: modes.outside_option.alpha, modes.outside_option.constant, random_seed

• Input files: OutsideOptionTravelTimesFile (optional), TripsFile

• Output files: OutsideOptionPreferencesFile

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.

• Parameters: modes.outside_option.road_network_speed

• Input files: CarShortestDistancesFile, TripsFile

• Output files: OutsideOptionTravelTimesFile

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

• constant value over edges

• constant value by road type

• constant value by combinations of road type and urban flag

• Parameters: road_network.default_nb_lanes, road_network.default_speed_limit, road_network.ensure_connected, road_network.hov_lanes, road_network.min_length, road_network.min_nb_lanes, road_network.min_speed_limit, road_network.reindex, road_network.remove_duplicates

• Input files: RawEdgesFile

• Output files: CleanEdgesFile

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.

• Parameters: modes.public_transit.alpha, modes.public_transit.constant, random_seed

• Input files: PersonsFile

• Output files: PublicTransitPreferencesFile

PublicTransitTravelTimesFromRoadDistancesStep

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

• Parameters: modes.public_transit.road_network_speed

• Input files: CarShortestDistancesFile

• Output files: PublicTransitTravelTimesFile

RoadNetworkCongestionFunctionPlotsStep

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

• Input files: EdgesFreeFlowTravelTimeFile, MetroExpectedTravelTimeFunctionsFile, MetroSimulatedTravelTimeFunctionsFile

• Output files: ExpectedRoadNetworkCongestionFunctionPlotFile, SimulationRoadNetworkCongestionFunctionPlotFile

RunSimulationStep

Runs the Metropolis-Core simulation.

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

• Parameters: metropolis_core.exec_path

• Input files: MetroAgentsFile, MetroAlternativesFile, MetroEdgesFile, MetroParametersFile, MetroTripsFile (optional), MetroVehicleTypesFile

• Output files: MetroAgentResultsFile, MetroExpectedTravelTimeFunctionsFile, MetroIterationResultsFile, MetroNextExpectedTravelTimeFunctionsFile, MetroSimulatedTravelTimeFunctionsFile, MetroTripResultsFile

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"

• Parameters: crs, simulation_area.aav_filename, simulation_area.aav_name, simulation_area.buffer

• Output files: SimulationAreaFile

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

• Parameters: crs, simulation_area.bbox_wgs, simulation_area.bbox

• Output files: SimulationAreaFile

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"]

• Parameters: crs, osm_file, simulation_area.buffer, simulation_area.osm_admin_level, simulation_area.osm_name

• Output files: SimulationAreaFile

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"

• Parameters: crs, simulation_area.buffer, simulation_area.polygon_file

• Output files: SimulationAreaFile

TripDepartureTimeDistributionStep

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

• Input files: TripResultsFile

• Output files: TripDepartureTimeDistributionPlotFile

TripResultsStep

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

• Input files: MetroAgentResultsFile, MetroTripResultsFile

• Output files: TripResultsFile

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.

• Parameters: random_seed

• Input files: TripsFile

• Output files: UniformDrawsFile

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.

• Parameters: mode_choice.model, mode_choice.modes, mode_choice.mu

• Input files: TripsFile, UniformDrawsFile [if there are at least two modes]

• Output files: MetroAgentsFile

WriteMetroAlternativesStep

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

• Parameters: departure_time_choice.model, departure_time_choice.mu, mode_choice.modes

• Input files: OutsideOptionPreferencesFile [if the outside-option mode is defined], TripsFile [if at least one “trip-based” mode is defined], UniformDrawsFile [if at least one “trip-based” mode is defined and departure-time choice is “ContinuousLogit”]

• Output files: MetroAlternativesFile

WriteMetroEdgesStep

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

• Input files: CleanEdgesFile, EdgesCapacitiesFile (optional), EdgesPenaltiesFile (optional)

• Output files: MetroEdgesFile

WriteMetroParametersStep

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

• Parameters: simulation.backward_wave_speed, simulation.departure_time_interval, simulation.learning_factor, simulation.max_pending_duration, simulation.nb_iterations, simulation.period, simulation.recording_interval, simulation.routing_algorithm, simulation.spillback

• Output files: MetroParametersFile

WriteMetroTripsStep

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

• Parameters: mode_choice.modes, vehicle_types.car.ridesharing_passenger_count

• Input files: CarDriverPreferencesFile (optional) [if the “car_driver” mode is defined], CarDriverWithPassengersPreferencesFile (optional) [if the “car_driver_with_passengers” mode is defined], CarFuelFile (optional) [if any “car_*” mode is defined], CarODsFile [if the “car_driver” mode is defined], CarPassengerPreferencesFile (optional) [if the “car_passenger” mode is defined], CarRidesharingPreferencesFile (optional) [if the “car_driver” mode is defined], LinearScheduleFile (optional), PublicTransitPreferencesFile (optional) [if the “public_transit” mode is defined], PublicTransitTravelTimesFile [if the “public_transit” mode is defined], TripsFile, TstarsFile (optional)

• Output files: MetroTripsFile

WriteMetroVehicleTypesStep

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

• Parameters: mode_choice.modes, vehicle_types.car.headway, vehicle_types.car.pce, vehicle_types.car.ridesharing_passenger_count

• Input files: CleanEdgesFile [if the “car_driver” mode is defined]

• Output files: MetroVehicleTypesFile

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

• Description: Random seed used to initialize the random number generator.
• Allowed values: Integer
• Note: If the random seed is not defined, some operations are not deterministic, i.e., they can produce different results if re-run.
• Steps: CarDriverPreferencesStep, CarDriverWithPassengersPreferencesStep, CarPassengerPreferencesStep, CarRidesharingPreferencesStep, CustomODMatrixStep, GravityODMatrixStep, HomogeneousTstarStep, LinearScheduleStep, ODMatrixEachStep, OutsideOptionPreferencesStep, PublicTransitPreferencesStep, UniformDrawsStep

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

• Description: Number of radial axis.
• Allowed values: Integer
• Steps: CircularNetworkStep

circular_network.nb_rings

• Description: Number of rings.
• Allowed values: Integer
• Steps: CircularNetworkStep

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

• Description: List of modes the agents can used to travel.
• Allowed values: List of Either 'car_passenger', 'public_transit', 'car_driver_with_passengers', 'car_driver', 'outside_option', 'car_ridesharing' [at least 1 elements]
• Steps: WriteMetroAgentsStep, WriteMetroAlternativesStep, WriteMetroTripsStep, WriteMetroVehicleTypesStep

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

• Description: Constant speed on the road network to compute travel time for outside option trips (km/h).
• Allowed values: Float
• Steps: OutsideOptionTravelTimesFromRoadDistancesStep

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

• Description: Speed of public-transit vehicles on the road network (km/h).
• Allowed values: Float
• Steps: PublicTransitTravelTimesFromRoadDistancesStep

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

• Steps: ExogenousCapacitiesStep

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

• Steps: PostprocessRoadNetworkStep

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

• Description: Minimum length allowed on edges (in meters).
• Allowed values: Float
• Steps: PostprocessRoadNetworkStep

road_network.min_nb_lanes

• Description: Minimum number of lanes allowed on edges.
• Allowed values: Float
• Steps: PostprocessRoadNetworkStep

road_network.min_speed_limit

• Description: Minimum speed limit allowed on edges (in km/h).
• Allowed values: Float
• Steps: PostprocessRoadNetworkStep

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

• Steps: ExogenousEdgePenaltiesStep

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

• Description: Number of iterations to be simulated.
• Allowed values: Integer
• Steps: WriteMetroParametersStep

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

• Description: Distance by which the polygon of the simulation area must be extended or shrinked.
• Allowed values: Float
• Note: The value is expressed in the unit of measure of the CRS (usually meter). Positive values extend the area, while negative values shrink it.
• Steps: SimulationAreaFromAAVStep, SimulationAreaFromOSMStep, SimulationAreaFromPolygonsStep

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

• Description: Passenger car equivalent of a typical car
• Allowed values: Float
• Steps: WriteMetroVehicleTypesStep

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

MetroFiles

CarDriverPreferencesFile

Preferences to travel as a car driver, for each person.

• Path: demand/population/car_driver_preferences.parquet
• Type: DataFrame
• Steps: CarDriverPreferencesStep

CarShortestDistancesFile

Shortest path distance on the road network of each car trip.

• Path: demand/population/car_driver_shortest_distances.parquet
• Type: DataFrame
• Steps: CarShortestDistancesStep

CarDriverWithPassengersPreferencesFile

Preferences to travel as a car driver with passengers, for each person.

• Path: demand/population/car_driver_with_passengers_preferences.parquet
• Type: DataFrame
• Steps: CarDriverWithPassengersPreferencesStep

CarFreeFlowDistancesFile

Distance of the fastest free-flow path on the road network of each car trip.

• Path: demand/population/car_free_flow_distances.parquet
• Type: DataFrame
• Steps: CarFreeFlowDistancesStep

CarFuelFile

Fuel consumption of each car trip, based on the length of the fastest free-flow path.

• Path: demand/population/car_fuel_consumption.parquet
• Type: DataFrame
• Steps: CarFuelStep

CarODsFile

Origin / destination on the road network for each trip, when traveling by car.

• Path: demand/population/car_origins_destinations.parquet
• Type: DataFrame
• Steps: CustomODMatrixStep, GravityODMatrixStep, ODMatrixEachStep

CarPassengerPreferencesFile

Preferences to travel as a car passenger, for each person.

• Path: demand/population/car_passenger_preferences.parquet
• Type: DataFrame
• Steps: CarPassengerPreferencesStep

CarRidesharingPreferencesFile

Preferences to travel by car ridesharing (driver or passenger), for each person.

• Path: demand/population/car_ridesharing_preferences.parquet
• Type: DataFrame
• Steps: CarRidesharingPreferencesStep

HouseholdsFile

Identifiers and characteristics of the simulated households.

• Path: demand/population/households.parquet
• Type: DataFrame
• Steps: GenericPopulationStep

LinearScheduleFile

Schedule preferences for each trip, for the linear model.

• Path: demand/population/linear_schedule_parameters.parquet
• Type: DataFrame
• Steps: LinearScheduleStep

OutsideOptionPreferencesFile

Utility of the outside option alternative, for each tour.

• Path: demand/population/outside_option_preferences.parquet
• Type: DataFrame
• Steps: OutsideOptionPreferencesStep

OutsideOptionTravelTimesFile

Travel time of the outside option alternative, for each tour.

• Path: demand/population/outside_option_travel_times.parquet
• Type: DataFrame
• Steps: OutsideOptionTravelTimesFromRoadDistancesStep

PersonsFile

Identifiers and characteristics of the simulated persons.

• Path: demand/population/persons.parquet
• Type: DataFrame
• Steps: GenericPopulationStep

PublicTransitPreferencesFile

Preferences to travel by public transit, for each person.

• Path: demand/population/public_transit_preferences.parquet
• Type: DataFrame
• Steps: PublicTransitPreferencesStep

PublicTransitTravelTimesFile

Travel time of each trip, when traveling by public transit.

• Path: demand/population/public_transit_travel_times.parquet
• Type: DataFrame
• Steps: PublicTransitTravelTimesFromRoadDistancesStep

TripZonesFile

Origin / destination zones of each trip.

• Path: demand/population/trip_zones.parquet
• Type: DataFrame

TripsFile

Identifiers and order of the trips for each person.

• Path: demand/population/trips.parquet
• Type: DataFrame
• Steps: GenericPopulationStep

TstarsFile

Desired start time for the activity following each trip.

• Path: demand/population/tstars.parquet
• Type: DataFrame
• Steps: HomogeneousTstarStep

UniformDrawsFile

Draws for the inverse transform sampling of mode choice and departure-time choice, of each tour.

• Path: demand/population/uniform_draws.parquet
• Type: DataFrame
• Steps: UniformDrawsStep

ZonesFile

Identifiers and characteristics of the zones in the simulated area.

• Path: demand/zones/zones.geo.parquet
• Type: GeoDataFrame
• Steps: CustomZonesStep

AllRoadDistancesFile

Shortest path distance for each pair of nodes on the road network.

• Path: network/road_network/all_distances.parquet
• Type: DataFrame
• Steps: AllRoadDistancesStep

AllFreeFlowTravelTimesFile

Free-flow travel time for each pair of nodes on the road network.

• Path: network/road_network/all_free_flow_travel_times.parquet
• Type: DataFrame
• Steps: AllFreeFlowTravelTimesStep

EdgesCapacitiesFile

Bottleneck capacity of each road-network edge.

• Path: network/road_network/edges_capacities.parquet
• Type: DataFrame
• Steps: ExogenousCapacitiesStep

CleanEdgesFile

Characteristics of the road-network edges, after clean up.

• Path: network/road_network/edges_clean.geo.parquet
• Type: GeoDataFrame
• Steps: PostprocessRoadNetworkStep

EdgesFreeFlowTravelTimeFile

Free-flow travel time of each road-network edge.

• Path: network/road_network/edges_free_flow_travel_time.parquet
• Type: DataFrame
• Steps: EdgesFreeFlowTravelTimesStep

EdgesPenaltiesFile

Free-flow time penalties of each road-network edge.

• Path: network/road_network/edges_penalties.parquet
• Type: DataFrame
• Steps: ExogenousEdgePenaltiesStep

RawEdgesFile

Characteristics of the road-network edges, before clean up.

• Path: network/road_network/edges_raw.geo.parquet
• Type: GeoDataFrame
• Steps: CircularNetworkStep, CustomRoadImportStep, GridNetworkStep

ExpectedRoadTravelTimesConvergencePlotFile

RMSE of expected edge-level travel times from one iteration to another.

• Path: results/graphs/convergence_expected_road_travel_times.png
• Type: Plot
• Steps: ConvergencePlotStep

SimulatedRoadTravelTimesConvergencePlotFile

RMSE of simulated edge-level travel times from one iteration to another.

• Path: results/graphs/convergence_simulated_road_travel_times.png
• Type: Plot
• Steps: ConvergencePlotStep

TourDepartureTimeConvergencePlotFile

RMSE of departure-time shift from one iteration to another.

• Path: results/graphs/convergence_tour_departure_time.png
• Type: Plot
• Steps: ConvergencePlotStep

ExpectedRoadNetworkCongestionFunctionPlotFile

Expected congestion function over all edges of the road network. Values are computed as Σ exp travel time / Σ free-flow travel time - 1, with the sumations over all edges.

• Path: results/graphs/network_congestion_function_expected.png
• Type: Plot
• Steps: RoadNetworkCongestionFunctionPlotsStep

SimulationRoadNetworkCongestionFunctionPlotFile

Simulated congestion function over all edges of the road network. Values are computed as Σ sim travel time / Σ free-flow travel time - 1, with the sumations over all edges.

• Path: results/graphs/network_congestion_function_simulated.png
• Type: Plot
• Steps: RoadNetworkCongestionFunctionPlotsStep

TripDepartureTimeDistributionPlotFile

Histogram of departure time distribution, over trips.

• Path: results/graphs/trip_departure_time_distribution.png
• Type: Plot
• Steps: TripDepartureTimeDistributionStep

IterationResultsFile

Clean aggregate results over iterations.

• Path: results/iteration_results.parquet
• Type: DataFrame
• Steps: IterationResultsStep

TripResultsFile

Clean results for each trip.

• Path: results/trip_results.parquet
• Type: DataFrame
• Steps: TripResultsStep

MetroAgentsFile

Simulated agents, as input to Metropolis-Core.

• Path: run/input/agents.parquet
• Type: DataFrame
• Steps: WriteMetroAgentsStep

MetroAlternativesFile

Simulated alternatives, as input to Metropolis-Core

• Path: run/input/alts.parquet
• Type: DataFrame
• Steps: WriteMetroAlternativesStep

MetroEdgesFile

Road-network edges, as input to Metropolis-Core.

• Path: run/input/edges.parquet
• Type: DataFrame
• Steps: WriteMetroEdgesStep

MetroTripsFile

Simulated trips, as input to Metropolis-Core.

• Path: run/input/trips.parquet
• Type: DataFrame
• Steps: WriteMetroTripsStep

MetroVehicleTypesFile

Simulated vehicle types, as input to Metropolis-Core.

• Path: run/input/vehicle_types.parquet
• Type: DataFrame
• Steps: WriteMetroVehicleTypesStep

MetroAgentResultsFile

Agent-level results from the Metropolis-Core Simulation.

• Path: run/output/agent_results.parquet
• Type: DataFrame
• Steps: RunSimulationStep

MetroIterationResultsFile

Aggregate results over iterations from the Metropolis-Core simulation.

• Path: run/output/iteration_results.parquet
• Type: DataFrame
• Steps: RunSimulationStep

MetroExpectedTravelTimeFunctionsFile

Expected travel time functions of the road-network edges for the last iteration, represented as a list of breakpoints.

• Path: run/output/net_cond_exp_edge_ttfs.parquet
• Type: DataFrame
• Steps: RunSimulationStep

MetroNextExpectedTravelTimeFunctionsFile

Expected travel time functions of the road-network edges for the next iteration, represented as a list of breakpoints.

• Path: run/output/net_cond_next_exp_edge_ttfs.parquet
• Type: DataFrame
• Steps: RunSimulationStep

MetroSimulatedTravelTimeFunctionsFile

Simulated travel time functions of the road-network edges for the last iteration, represented as a list of breakpoints.

• Path: run/output/net_cond_sim_edge_ttfs.parquet
• Type: DataFrame
• Steps: RunSimulationStep