Rust Q-Sim

This is a port of Matsim's Q-Sim to Rust. My current notes on the project are here

The most recent release can be cited with the following reference

The project is described in two conference papers, which were presented at ISPDC 24 in Chur, Switzerland, July 2024:

• High-Performance Simulations for Urban Planning: Implementing Parallel Distributed Multi-Agent Systems in MATSim
• Real-Time Routing in Traffic Simulations: A Distributed Event Processing Approach

Set Up Rust

Install Rust for your operating system as described here. For WSL this would be

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Set Up Prerequisites

The project relies on METIS and MPI as external dependencies. This means those dependencies are not compiled with the project, but need to be present on the operating system.

METIS

The project uses the metis crate as a dependency which is a wrapper for the METIS C Library. The C-Library is expected to be present on the machine. Also, the metis crate requires libclang on the machine this project is built on.

MPI

The project uses MPI for message passing between processes. The message passing is implemented using the rsmpi crate as an interface around a corresponding C-library on the system.

We maintain our own fork of the project because we depend on a more recent commit than the last release on crates.io, due to some bingen issue with MacOS 13.4 or higher.

The actual implementation of the message passing library is up to the system the project is run on. A good candiate is open-mpi.

Install dependencies

The dependencies named above need to be installed before the project can be buit

Linux - apt

Install dev versions of required packages because dev stuff is required during compilation

sudo apt -y install libclang-dev llvm-dev libmetis-dev libopenmpi-dev

MacOs

The dependencies are available via homebrew on macOS.

brew install metis open-mpi

The project contains a config.toml which tries to set the CPATH and the RUSTFLAGS environment variable. In case this doesn't work, they need to be set like the following:

export CPATH=$HOMEBREW_PREFIX/include
export RUSTFLAGS="-L$HOMEBREW_PREFIX/lib"

Both variables are necessary to compile the METIS and MPI wrapper libraries.

Math Cluster

The math cluster has all dependencies installed. They need to be enabled via the module system:

module load metis-5.1 ompi/gcc/4.1.2

HLRN

Setup conda

Unfortunately, there is no libclang dependency installed. You need to install it yourself via conda. If you use it for the first time, load the conda module and initialize it, such that it is available in your shell whenever you login:

module load anaconda3/2023.09
conda init bash

Then create your own environment and install libclang:

conda create -n your_env_name
conda activate your_env_name
conda install libclang 

Load dependencies

The HLRN cluster has some dependencies installed. They need to be enabled via the module system:

module load intel/2024.2 openmpi/gcc/5.0.3

So, before you run the project, you need to activate the environment:

conda activate your_env_name

The activation automatically updates the environment variables such that libclang files can be found by the compiler.

Source: https://nhr-zib.atlassian.net/wiki/spaces/PUB/pages/430343/Anaconda+conda+and+Mamba

Run the project

The project is built using cargo.

cargo build --release

Then a simulation can be started like the following:

mpirun -np 2 ./target/release/mpi_qsim --config-path /path/to/config.yml

It is also possible to execute a build before running by executing the following. This is way, one doesn't forget to re-compile before running.

cargo mpirun --np 2 --release --bin mpi_qsim -- --config-path /path/to/config.yaml

We also have a

Test

Run $ cargo test to execute all tests. To have immediate output use $ cargo test -- --nocapture

Create input files

You need to create protobuf files from the xml files. This can be done with the following command:

cargo run --bin convert_to_binary --release -- --network network.xml --population population.xml --vehicles vehicles.xml --output-dir output --run-id run