From d4b188f330531c38f70037ad067e6527141081fb Mon Sep 17 00:00:00 2001 From: Paul Heinrich Date: Wed, 20 Nov 2024 15:51:02 +0100 Subject: [PATCH] adapt readme --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 66 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 43016a3..48fde70 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ The most recent release can be cited with the following reference [![DOI](https://zenodo.org/badge/498376436.svg)](https://zenodo.org/doi/10.5281/zenodo.13928119) 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](https://doi.org/10.1109/ISPDC62236.2024.10705395) - [Real-Time Routing in Traffic Simulations: A Distributed Event Processing Approach](https://doi.org/10.1109/ISPDC62236.2024.10705399) @@ -16,8 +17,8 @@ The project is described in two conference papers, which were presented at ISPDC Install Rust for your operating system as described [here](https://www.rust-lang.org/tools/install). For WSL this would be -``` -$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` ## Set Up Prerequisites @@ -28,8 +29,8 @@ compiled with the project, but need to be present on the operating system. ### METIS The project uses the [metis](https://crates.io/crates/metis) crate as a dependency which -is a wrapper for the [METIS C Library](https://github.com/KarypisLab/METIS). The C-Library is -expected to be present on the machine. Also, the `metis` crate requires `libclang` on the machine +is a wrapper for the [METIS C Library](https://github.com/KarypisLab/METIS). 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 @@ -51,23 +52,24 @@ The dependencies named above need to be installed before the project can be buit 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 +```shell +sudo apt -y install libclang-dev llvm-dev libmetis-dev libopenmpi-dev ``` #### MacOs The dependencies are available via [homebrew](https://brew.sh/) on macOS. -``` -$ brew install metis open-mpi +```shell +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" + +```shell +export CPATH=$HOMEBREW_PREFIX/include +export RUSTFLAGS="-L$HOMEBREW_PREFIX/lib" ``` Both variables are necessary to compile the METIS and MPI wrapper libraries. @@ -75,33 +77,68 @@ 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: + +```shell +module load metis-5.1 ompi/gcc/4.1.2 ``` -$ module load metis-5.1 ompi/gcc/4.1.2 -``` + #### HLRN -The HLRN cluster has all dependencies installed. They need to be enabled via the module system: +##### 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: + +```shell +module load anaconda3/2023.09 +conda init bash +``` + +Then create your own environment and install `libclang`: + +```shell +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: + +```shell +module load intel/2024.2 openmpi/gcc/5.0.3 ``` -$ module load gcc/9.3.0 llvm/9.0.0 openmpi/gcc.9/4.1.4 metis/5.1.0 + +So, before you run the project, you need to activate the environment: + +```shell +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 +```shell +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 + +```shell +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 + +```shell +cargo mpirun --np 2 --release --bin mpi_qsim -- --config-path /path/to/config.yaml ``` We also have a @@ -109,3 +146,11 @@ 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: + +```shell +cargo run --bin convert_to_binary --release -- --network network.xml --population population.xml --vehicles vehicles.xml --output-dir output --run-id run +``` \ No newline at end of file