https://github.com/thoughtworks/epirust
An agent-based epidemiology simulation framework built in Rust
https://github.com/thoughtworks/epirust
agent-based-modeling agent-based-simulation epidemiology rust
Last synced: 10 months ago
JSON representation
An agent-based epidemiology simulation framework built in Rust
- Host: GitHub
- URL: https://github.com/thoughtworks/epirust
- Owner: thoughtworks
- License: agpl-3.0
- Created: 2020-03-24T17:06:48.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-01T15:23:55.000Z (about 2 years ago)
- Last Synced: 2024-04-16T07:16:42.100Z (almost 2 years ago)
- Topics: agent-based-modeling, agent-based-simulation, epidemiology, rust
- Language: Rust
- Homepage:
- Size: 4.3 MB
- Stars: 96
- Watchers: 21
- Forks: 14
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# EpiRust
## An agent-based epidemiology simulation framework built in Rust
[](https://travis-ci.org/thoughtworks/epirust)
This is a monorepo containing code for the EpiRust framework -
1. engine - The main EpiRust engine, which can be run as a CLI app
2. 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.
### Quickstart
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.
#### Docker
Prerequisites:
- [Install Docker](https://docs.docker.com/install/) 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/ .
```
- Go to the visualization section to plot the copied CSV file
#### Local setup
Prerequisites:
- Install Rust and Cargo (version 1.40.0 or above). Refer to https://rustup.rs/ for rust installation
- Install `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 `pandas` and `matplotlib` libraries which can be installed using `pip` or `conda`.
- `pip install pandas matplotlib`
#### Running standalone simulations
To run in standalone mode, run this:
```bash
RUST_LOG=info cargo run --bin engine-app -- -i -c path/to/simulation-config
```
#### Visualization:
- After the simulation is run, it will generate a CSV file. We can plot this using a simple script included in the `engine/plot` directory
- Ensure you're in the `engine` directory
- Run `python plot/plot.py --data-path ` - this will plot the csv you provide.
Sample output:
#### 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](https://github.com/thoughtworks/epirust/wiki/Technical-Architecture#architecture-for-a-multi-city-simulation) on the wiki describes how this works at a high level.
Steps for running a multi-region simulation:
1. 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/config` directory for examples of the configuration.
2. To start with KAFKA on local, follow [this](LOCAL_SETUP_WITH_KAFKA.md)
3. To start with MPI on local, follow [this](LOCAL_SETUP_WITH_MPI.md)
4. To start with MPI on cloud, follow [this](CLOUD_SETUP_WITH_MPI.md)
5. To start with KAFKA on cloud, you have to set up KAFKA cluster on cloud. (follow [this](https://github.com/sapanaKale/epirust-cloud-setup/blob/main/epirust_cloud_setup.md))
It will generate output CSV and JSON files which you can use to for analysis and charting.
### License
EpiRust is an open source project licensed under [AGPL v3](https://www.gnu.org/licenses/agpl-3.0.en.html)