Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.12+).
  • Metropolis-Core executables (download the zipfile for your OS and extract metropolis_cli and routing_cli from the execs/ directory).

Tip

If you don’t have Python installed, or you are not sure which version you have, you don’t need to install it yourself: the uv option below can download and manage a compatible Python version for you automatically.

Installation 🔧

Pymetropolis’ releases are hosted on PyPI.

With pip

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

Pymetropolis can be run as:

pymetropolis my-config.toml

With uv

If you use uv, you can run Pymetropolis without installing it first, using uvx (a shorthand for uv tool run):

uvx pymetropolis my-config.toml

The first time you run this command, uv downloads Pymetropolis (and a compatible Python version, if needed) into a cache and runs it; subsequent runs reuse the cached install, so this stays fast.

If you would rather install Pymetropolis once and have the pymetropolis command permanently available on your PATH, similarly to pip install, use uv tool install instead:

uv tool install pymetropolis

To update it to a newer version, run:

uv tool upgrade pymetropolis

Checking your installation

Regardless of how you installed it, you can check the version of Pymetropolis that is installed on your system by running:

pymetropolis --version

(or uvx pymetropolis --version if you are using uvx without installing).

Configuring the Metropolis-Core executables 🔌

Pymetropolis needs to know where the metropolis_cli and routing_cli executables you downloaded in Requirements are, so it can run the simulation and compute free-flow travel times.

By default, Pymetropolis reads the paths of the two executables from the METROPOLIS_EXEC_PATH and METROPOLIS_ROUTING_EXEC_PATH environment variables. This is the recommended way of configuring the executable paths. For that, you can define the two environment variables directly in your shell, or, more conveniently, write them once in a .env file:

# File: .env
METROPOLIS_EXEC_PATH=/absolute/path/to/metropolis_cli
METROPOLIS_ROUTING_EXEC_PATH=/absolute/path/to/routing_cli

The .env file should be located in the current working directory where Pymetropolis runs, or a directory higher up.

Tip

If setting environment variables is inconvenient, you can instead set the metropolis_core.exec_path and metropolis_core.routing_exec_path parameters directly in each configuration file, with paths relative to the configuration file itself:

[metropolis_core]
exec_path = "execs/metropolis_cli"
routing_exec_path = "execs/routing_cli"

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

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

Warning

Pymetropolis does not detect code changes that would require a Step to be re-run. Therefore, after updating Pymetropolis, it is recommended to delete the main output directory, so that all steps are re-run.

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. This is the fastest way to get a working simulation: the Bottleneck case study takes about an hour and requires no external data.
  • Concepts: Explanations of the modeling concepts behind Pymetropolis and METROPOLIS2.
  • 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.
  • Examples: Ready-to-run configuration files, including companions to the case studies above and a few extra ones.

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

You can use the --step [StepName] argument to force a given Step to be executed, even though Pymetropolis considers that it is up to date. If the given Step is not in the sequence (as shown by --dry-run), Pymetropolis will tell you why (e.g., input file not generated, missing configuration parameter).

pymetropolis my-config.toml --step PostprocessRoadNetworkStep

If you want to inspect the outputs of each Step as it runs, or simply want more control over a long sequence of Steps, use the --step-by-step argument to pause and ask for confirmation before running each Step:

pymetropolis my-config.toml --step-by-step

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.