An agent-based epidemiology simulation framework built in Rust
This is a monorepo containing code for the EpiRust framework -
- engine - The main EpiRust engine, which can be run as a CLI app
- orchestrator - Coordinator for multiple engines to run large scale simulations
Note: We are no longer maintaining the Web UI for EpiRust which allows you to trigger simulations and grid visualization for upto 1000 agents. Hence, it has been removed from here. Please refer sims2020 branch for web.
The quickest way to run the application is using the CLI interface on the engine. Follow the docker or local setup to get the engine up and running.
- Install Docker on your local host machine
Build EpiRust engine docker image
docker build -t epirust-engine -f ./engine-app/Dockerfile .
Running EpiRust engine docker container
docker run --rm --name epirust-engine epirust-engine /bin/sh -c './epirust-engine -c config/default.json && ls *.csv'
- Copy the listed CSV produced from the container to the host machine
docker cp epirust-engine:/home/nonroot/app/<CSV_FILE> .
- Go to the visualization section to plot the copied CSV file
- Install Rust and Cargo (version 1.40.0 or above). Refer to https://rustup.rs/ for rust installation
cmake(version 3.16.4 or later). Installation instructions will depend on your platform. On MacOS you can install it using
brew install cmake. Refer to https://cmake.org/download/
- The following dependencies are needed on Debian:
ca-certificates curl file build-essential autoconf automake autotools-dev libtool xutils-dev cmake pkg-config libfreetype6-dev libfontconfig1-dev xclip
- Python 3 (for visualization and charting). We also need the
matplotliblibraries which can be installed using
pip install pandas matplotlib
- Go to the
RUST_LOG=info cargo run --release
- To modify the settings, or run with custom settings, use
cargo run --release -- -c config/[your-config].json. Refer to
default.jsonfor the available settings.
- After the simulation is run, it will generate a CSV file. We can plot this using a simple script included in the
- Ensure you're in the
python plot/plot.py --data-path <PATH_TO_CSV_FILE>- this will plot the csv you provide.
- Ensure you're in the
Running multi-region simulations
You can run EpiRust for multi-region simulations (e.g. to simulate a group of cities). This will require the orchestrator, and each engine representing a region. The architecture page on the wiki describes how this works at a high level.
Steps for running a multi-region simulation:
- Prepare a configuration. A configuration is a json file which consists of two parts:
- The simulation configuaration for each engine. (Note that currently there is some repetition needed in the configuration for each engine)
- The travel plan, which defines a matrix containing the daily travellers from one region to another.
You can take a look at the
orchestrator/configdirectory for examples of the configuration.
- Start Kafka. The engines and orchestrator will communicate using Kafka. (The topics should be created automatically when the first messages are sent).
- Start the engines. If there are n regions in the config, n engines should be started with the name specified in the config. E.g.
./epirust-engine -d -i [engine-name], where
epirust-engineis the engine-app binary.
- Start the orchestrator, pointing to the config file. E.g.
./epirust-orchestrator -c [path_to_config]. The simulation should now start.
It will generate output CSV and JSON files which you can use to for analysis and charting.
EpiRust is an open source project licensed under AGPL v3