Getting started

Overview

Note

This project is under active development.

MEmilio is an extensive framework for tasks around infectious disease modeling. It supports a multitude of model types including equation-based, agent-based, and hybrid graph-ODE-based models. It furthermore provides ready-to-use tools for data integration and visualizations. Among the equation-based models, we provide models based on ordinary differential equations, the linear chain trick (LCT), and a recent generalized LCT, integro-differential equations and stochastic differential equations. With simple definitions, models can be spatially or demographically resolved.

The MEmilio framework is written in two languages: C++ and Python.

• The C++ backend contains efficient and optimized model implementations that further use parallelization to speed up execution and reduce waiting times.

• Python is used for data acquisition, plotting, and machine-learning models.

• We, furthermore, provide Python interfaces to selected models (implemented in C++) to allow the use and study of advanced models by users with less experience in programming or computer science.

For more details on using models implemented in C++ directly, see the sections on model usage. For more details on implementing new infection dynamics models that could then be combined with, e.g., our mobility patterns, see model creation.

If you prefer using Python to call or run our models, you can use our memilio-simulation package to run simulations. The memilio-epidata package provides tools to download and structure important data such as infection or mobility data. More about this and our other Python packages can be found in the Python Interface Section of this documentation.

A few things are not represented in this documentation, but are part of the GitHub repository. In the data folder you can find some regularly used data for simulations of a pathogen’s spread, currently mostly for Germany.

Why to use MEmilio

In computationaly epidemiology and infectious disease dynamics, models are often implemented in Python or R. However, this approach often limits the possibility to build large-scale models including an advanced level of detail, e.g., in demography, spatial resolution, or even individual immunity or to run many simulations in a short time frame. MEmilio addresses this challenge by providing a high-performance framework implemented in C++ that allows for large-scale modeling in short time frames to be used in research, policy advice, and education.

The use of a particular model is generally driven by the research question at hand. The distinction of MEmilio is the provision of a wide range of models, from simple compartmental models to complex integro-differential and agent-based models, allowing users to select the most appropriate model for their specific needs.

Aggregated models are suitable for scenarios where population-level dynamics are of interest. They are computationally efficient and can be used for quick assessments or when data is limited. In our implementations, these models can easily be extended to address research questions that involve demographic dimensions such as age.

Standard models based on ordinary differential equations (ODE) allow the simplest description of population-level infection dynamics. However, these also implicitly assume exponentially distributed stay times. If the data suggest these to be unrealistic, ODE-based models with the linear chain trick (LCT) can be used. With the LCT, Gamma, or more precisely, Erlang distributions can be adapted to expected stay time and variance. We also offer a first implementation of a generalized LCT where more distributions can be approximated. For full flexibility, integro-differential equation-based (IDE) models can be used. These allow for arbitrary stay time distributions and are thus suitable when a more realistic timing of disease progression is crucial for the research question. However, IDE models are computationally more expensive than ODE-based models.

For spatio-temporal dynamics, graph-based metapopulation models, which leverage ODE-based models, are a good compromise between level of detail and computational effort. They allow for the incorporation of mobility patterns and spatial heterogeneity, making them suitable for studying the spread of diseases across different regions. They can also be used to, e.g., consider different intervention strategies in different regions or to study the effect of mobility restrictions. To study the effect of local interventions, we provide the option to implement pre-defined and dynamic NPIs which automatically enforce interventions on a local and regional level when an incidence threshold criteria by the user is exceeded. For details, see, e.g.,

• ODE-based SECIR model for early-phase epidemics or full immunity cases

• ODE-based SECIRVVS model for early- or mid-phase epidemics with three immunity layers

• ODE-based SECIRTS model for mid- or late-phase epidemics with three immunity layers and waning immunity

For Python, please see, e.g., ODE-based SECIRTS model.

When individual-level interactions and heterogeneity are crucial, individual-based models provide a detailed representation of disease dynamics. These models can capture complex behaviors and interactions, making them valuable for understanding transmission dynamics in specific settings. Individual-based models are computationally intensive but offer unparalleled detail for certain research questions such as in-household transmission or vaccination and testing strategies targeting individuals that satisfy specific properties with respect to age, previous infections, immunity levels, or particular workplaces. The most versatile individual-based model in MEmilio is the (mobility-based) agent-based model.

How to use MEmilio

The installation and use of MEmilio might look overwhelming at first due to the many features and models included. We have structured this documentation to guide you step-by-step through the installation and usage process. If you still need help, feel free to contact us or open an issue at GitHub and highlight @mknaranja and @HenrZu such that we can assist you as best as we can.

Installation

There are two main ways to set up MEmilio on your computer or on a remote cluster or supercomputer, depending on what you want to do:

1. Using the Python packages: This is the recommended path for many users not familiar with C++. Here, you can run simulations using python bindings.

2. Directly building the C++ Core: This is for developers who want to modify the functionality, contribute new models etc. by running C++ code directly.

In addition, we provide several Python packages to download epidemiological data or create plots from Python.

Below, we will give you a step-by-step guide for both methods. If you are new to MEmilio and more familiar with Python, Julia, or R than with C++, we recommend starting with the Python packages, as they provide an easy access to simulate infection dynamics models from and collect experiences with MEmilio.

Required tools

Before you can install MEmilio, you need to install some common development tools.

• Git: This is a version control system used to download the project’s source code.

  • Windows: By default, Git is not installed. Download and install it from git-scm.com.

  • macOS & Linux: Git is usually preinstalled. You can check by opening a terminal and typing git --version.

• Python: Required for the Python packages.

  • MEmilio is tested daily with Python 3.8 and 3.12. While other versions may also work, we recommend using the latest release of either of these. You can download it from the official website python.org.

• C++ Compiler and CMake:

  • Windows: The easiest way is to install Visual Studio Community. This includes a C++ compiler, CMake, and Git all in one.

  • macOS: One option is installing the Xcode Command Line Tools by running xcode-select --install in your terminal.

  • Linux: On Linux, essential build tools and CMake might be preinstalled. Otherwise, on Debian/Ubuntu, you could execute the installation by running sudo apt-get install cmake gcc g++ in your terminal.

Step 1: Download the MEmilio source code

Once the required tools are installed, open a terminal and download the MEmilio code with this command:

git clone https://github.com/SciCompMod/memilio.git

This command copies the entire MEmilio project into a new folder named memilio on your computer.

Note

A Quick Note on HTTPS vs. SSH

The git clone command above uses an HTTPS URL. This is the simplest method and works perfectly for downloading the code.

However, if you plan to contribute code back to the project (i.e., “push” your changes), we recommend using SSH. To set this up, you can follow GitHub’s official guide on adding an SSH key.

Now, navigate into that folder:

cd memilio

From here, choose one of the following options.

Option A: Installing the Python packages (Recommended for nonexperienced users or for data download and visualizations)

You can run simulations, download data, or create plots, by only installing our Python packages.

1. Navigate to the directory containing our Python code:

   cd pycode
   

2. To install the simulation package memilio-simulation, from here you can do:

   cd memilio-simulation
   pip install -e .
   

3. For afterwards installing the memilio-epidata package for data downloading and handling, run:

   cd ..  # Go back to the pycode directory
   cd memilio-epidata
   pip install -e .
   

Tip

For Contributors: Installing development packages

The -e flag installs the package in a mode, which links the installation to your local source code folder.

If you plan to contribute to MEmilio, you can also install all the necessary development dependencies by adding [dev] to the command:

pip install -e .[dev]

For regular use, the simple pip install -e . is sufficient.

To install other packages, see the items below Python Interface in the menu on the left hand side.

Option B: Building the C++ core (Advanced)

For experienced developers and C++ programmers, we offer the C++ backend to fully benefit from all functionality and parallel performance.

Please see the full C++ Build instructions for more details and a list of compile options.

1. Run CMake. This tool configures the project for compilation on your specific system. It takes around 10 seconds, depending on your internet connection as external libraries are fetched.

   cmake -S cpp -B cpp/build
   

2. Compile the code and create the executables. Run the build command from inside your build directory. To speed up the process, you can use the -j flag (e.g., using 4 cores):

cmake --build . -j 4

Note

On a standard 4-core (2024) laptop, compilation takes approximately 6 minutes. Upon completion, the executables are located in the cpp/build/bin directory.

cmake --build cpp/build

If you want to build a specific example, you can specify it with the --target flag:

cmake --build . --target <example_name>

If you experience errors, feel free to contact martin.kuehn@dlr.de or open a discussion on GitHub!

Running simulations

You can run simulations either via the C++ interface where they are originally implemented or via the python bindings. For the C++ Interface, you can find explanations of the models as well as guides on their usage in the C++ model usage section. In short, the executables for different model instantiations are built as described above and can be run via

./cpp/build/bin/<example_name>

Out of the box this works for all examples in the cpp/examples folder of our github repository, that do not depend on user-provided external libraries. Additional explanations for our models are linked at the corresponding sites of this documentation.

Simulations used in publications

For simulations used in publications, we maintain a separate repository: memilio-simulations. This repository contains simulations organized in separate folders, each with the specific version of MEmilio used for the published results. This ensures that simulation results can be easily reproduced.

The repository also includes additional scripts for plotting, data gathering, and pre-/post-processing that were used in publications.

Loading data

The memilio-epidata package provides tools to download epidemiological relevant datasets. Some datasets like contact matrices for Germany are also included in the data folder of the github repository and school holidays (for Germany) are directly included in the C++ code.

Creating new models

If you want to create new models, you can do so via the C++ interface. For this, we recommend to have a look at the C++ model creation section of this documentation.

Visualizations

For visualizations, we provide our python package MEmilio-plot. Apart from that, we have collected some scripts that we used for visualizations in the tools folder in our github repository. For the latter, no regular testing is conducted. If you encounter errors, please contact us.

Further questions

If you have any further questions, please take a look at our FAQ and feel free to contact us via e-mail or open an issue or discussion on GitHub.