Metropolis-Core

Metropolis-Core is the Rust-based core of the METROPOLIS2 simulator.
Explore the docs »

Website · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Citation
   • Built With
   • Semver
2. Getting Started
   • Pre-Built Binaries
   • Compiling From Source
3. Usage
4. Contributing
5. License
6. Contact
7. Acknowledgments

About The Project

METROPOLIS2 is a dynamic multi-modal agent-based transport simulator.

Citation

If you use this project in your research, please cite it as follows:

de Palma, A. & Javaudin, L. (2025). METROPOLIS2. https://metropolis2.org

Javaudin, L., & de Palma, A. (2024). METROPOLIS2: Bridging theory and simulation in agent-based transport modeling. Technical report, THEMA (THéorie Economique, Modélisation et Applications).

Refer to CITATION.cff and CITATION.bib for details.

Built With

Metropolis-Core make use of the Rust standard library and some awesome Rust crates, including:

• anyhow for error handling
• arrow / parquet for input / output operations
• clap for command line interface
• hashbrown for hash collections
• indicatif / log / simplelog for logging and progress bar
• num-traits for generic mathematics
• petgraph for graphs
• rayon for parallelization

Semver

Metropolis-Core is following Semantic Versioning 2.0.

Each new version is given a number MAJOR.MINOR.PATCH. An increase of the MAJOR number indicates backward incompatibilities with previous versions. An increase of the MINOR number indicates new features, that are backward-compatible. An increase of the PATCH number indicates bug fixes.

(back to top)

Getting Started

Pre-Built Binaries

1. Go to the Releases Tab and download the Zip file corresponding to your operating system (Windows, MacOS, or Linux).
2. Extract the Zip file in a folder.
3. The metropolis cli executable (or metropolis_cli.exe for Windows) is available in the execs directory. You can move it to any location or your choice.

Compiling From Source

1. Install Rust, either using the official rustup installer or any package manager you may use.

2. Clone this repository on your PC, you can use "git clone", if you have git installed, like this:

   git clone https://github.com/Metropolis2/Metropolis-Core.git

   Otherwise in the right up side of the repository page you will see a download button, download the repository as zip and extract it in a folder.

3. Open a new terminal in the folder you extracted the repository in.

4. Run this command in the terminal:

   cargo build --release -p metropolis-core

   This can take a few minutes depending on your system, but be patient.

5. The metropolis cli executable (or metropolis_cli.exe for Windows) is now available in the target/release/ directory.

(back to top)

Usage

Before running a METROPOLIS2 simulation with Metropolis-Core, you first need to create the simulation input which consists of a JSON file and multiple Parquet or CSV files.

Example input files are provided in the examples/data/ directory, in CSV and Parquet version. This files represent a simulation with no meaningful interpretation. It makes use of all the possible input values so it is a great way to test if the simulator is running properly.

Then, to run the simulation, open a terminal, locate the metropolis_cli executable and execute it with (on Linux or MacOS):

./metropolis_cli [path_to_parameters.json]

or (on Windows):

.\metropolis_cli.exe [path_to_parameters.json]

For more details, please refer to the Documentation.

(back to top)

Contributing

If you would like to add a feature to Metropolis-Core, start by opening an issue with the tag "enhancement" so that we can discuss its feasibility.

If your suggestion is accepted, you can then create a Pull Request:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For more details, please read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

(back to top)

License

Metropolis-Core is free and open-source software licensed under the GNU General Public License v3.0.

You are free to:

• Modify and redistribute this software
• Use it for any purpose, personal or commercial

Under the following conditions:

• You retain the original copyright notice
• You distribute you modifications under the same license (GPL-3.0 or later)
• You document any significant changes you make

For the full license text and legal details, see the LICENSE.txt file.

(back to top)

Contact

If you have any questions, either post an issue or send an e-mail to any of these addresses:

• METROPOLIS2 team - contact@metropolis2.org
• Lucas Javaudin - metropolis@lucasjavaudin.com

Project Link: https://github.com/Metropolis2/Metropolis-Core

(back to top)

Acknowledgments

METROPOLIS2 takes its name and inspiration from the METROPOLIS simulator developed by André de Palma, Fabrice Marchal and Yurii Nesterov.

de Palma, A., Marchal, F., & Nesterov, Y. (1997). METROPOLIS: Modular system for dynamic traffic simulation. Transportation Research Record, 1607(1), 178-184.

(back to top)