Overview

MEmilio contains several Python modules offering an easy-to-use interface to the efficiently implemented C++ models and to complement these by data preparation, code generation, machine learning, or plotting functionality. Please see the individual package documentation for more details on the functionality and usage.

MEmilio Python Interface

This package provides a Python interface for parts of the C++ main library, with the goal of exposing fast mathematical-epidemiological models to a bigger user base.

To the Python bindings

MEmilio EpiData Package

This package provides tools to download and structure important data such as infection or derived mobility data.

To the data package

Machine Learning Surrogate Models

This package contains machine learning-based surrogate models that were trained based on the MEmilio simulation outputs.

To the intro of surrogate models

Visualization

Generalized visualization functions for MEmilio specific plots.

To the visualization

Interface Generation

Easy to use tool for helping with the creation of Python bindings or interfaces to (new) C++ models.

To the generation package

Package installation

You can run simulations, download data, or create plots with our Python packages. First, however, you need a working Python installation. If you are not sure that you have one, head to Setup: Required tools for the Python setup, then continue here.

Note

We highly recommend using a virtual environment for installing any Python package (including ours)! You can find instructions on how to create one here. You can freely choose name and location of the environment, just make sure that you can find it again later. And remember to activate the environment before using MEmilio!

The Python packages can be installed in two ways, depending on your use case. We will use pip here, but you can use the Python package manager of your choice as well.

Option 1: Install from PyPI

Note

Currently only supported for memilio-simulation.

If you just want to run simulations with the latest released version, install the pre-built wheel directly from PyPI:

python -m pip install memilio-simulation

This is the recommended way to install a package as a user. If you want to develop or contribute to the project, check out the second option (installing from source).

Pre-built wheels are provided for Linux, Windows and MacOS(ARM).

Option 2: Install from source

If you need the latest (unreleased) code, or want to contribute to the package, you need to build from source. To get the source code, follow Download the MEmilio source code. Additionally, the memilio-simulation, memilio-surrogatemodel and memilio-generation packages require a C++ compiler, a generator and CMake, as they use scikit-build-core to compile Python bindings and/or parts of the C++ library. If you want to install these packages, follow section Setup: Required tools for setting up these additional dependencies.

Each package provides a pyproject.toml in the respective directory pycode/memilio-{package_name}, that installs the package and its Python dependencies with pip.

The dependencies of the individual packages are denoted in their documentation. The installation can be run with the following command from the directory containing the pyproject.toml file

cd pycode/memilio-{package_name}
python -m pip install .

This installs the package and the required dependencies to your site-packages. If you want to avoid changing directories too often, simply run python -m pip install pycode/memilio-{package_name} from the project root.

Tip

For Contributors: Installing development packages

The -e flag installs the package in a mode, which links the installation to your local source code directory. This allows working on the Python code without having to reinstall the package after every change. If you plan to contribute to any package, install all development dependencies by adding [dev]:

python -m pip install -e .[dev]

Warning

C++ code changes always require re-running this command for the changes to take effect.

Expert’s knowledge: Build options and files for scikit-build-core

When installing a package that uses scikit-build-core, all the CMake configuration options of the C++ library are available as well. Additionally, the CMake configuration for the Python bindings (i.e., memilio-simulation) provides the following CMake options:

  • MEMILIO_USE_BUNDLED_PYBIND11: ON or OFF, default ON. If ON, downloads Pybind11 automatically from a repository during

CMake configuration. If OFF, Pybind11 needs to be installed on the system.

When building the bindings, CMake options can be forwarded with configuration settings, e.g.

By default, the cmake build files are put into pycode/build/memilio-{package_name} to save on time during package development. If you get unexpected CMake errors, you can try deleting the respective build directory. If you do not want to store the build files at all, you can remove the build_dir entry from the section [tool.scikit-build] in the pyproject.toml. Then skbuild will use a temporary directory instead.

Testing

Each package provides a test suite under pycode/memilio-{package_name}/tests. To run the tests, simply use the following command inside the package directory after installation:

cd tests
python -m unittest

This works for both the normal and the editable (with “-e”) installations.

Alternatively, you can start the tests from outside the source directory, but you need to tell the unittest module where to look. From the MEmilio project directory, run for example

python -m unittest discover -s pycode/memilio-simulation/tests

Coverage Report

Dependencies for coverage report:

  • coverage

To get the coverage report, run the following in a package directory

python -m coverage run -m unittest discover -s tests
python -m coverage report
python -m coverage xml -o coverage_python.xml
python -m coverage html -d coverage_python

Inspection via pylint

The following packages have to be installed to run pylint:

  • pylint

  • pylint-json2html

Run pylint with the commands in the package directory

python ../run_pylint.py
pylint-json2html -f jsonextended -o build_pylint/pylint.html < build_pylint/pylint_extended.json

From the repository root you can also target a package explicitly, for example python pycode/run_pylint.py --package-dir memilio-plot.