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 and their configurations.
  • 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.