diff --git a/README.md b/README.md index 3e43d6499e..512500cf7d 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,12 @@ If you use MEmilio, please cite our work and, in particular, for -- Ordinary differential equation-based (ODE) and Graph-ODE models: Zunker H, Schmieding R, Kerkmann D, Schengen A, Diexer S, et al. (2024). *Novel travel time aware metapopulation models and multi-layer waning immunity for late-phase epidemic and endemic scenarios*. *PLOS Computational Biology* 20(12): e1012630. https://doi.org/10.1371/journal.pcbi.1012630 +- Ordinary differential equation-based (ODE) and Graph-ODE models: Zunker H, Schmieding R, Hasenauer J, Kühn M J (2026). *Efficient numerical computation of traveler states in explicit mobility-based metapopulation models: Mathematical theory and application to epidemics*. arXiv. https://doi.org/10.48550/arXiv.2603.11275 - Integro-differential equation-based (IDE) models: Wendler A, Plötzke L, Tritzschak H, Kühn MJ. (2026). *A nonstandard numerical scheme for a novel SECIR integro differential equation-based model with nonexponentially distributed stay times*. *Applied Mathematics and Computation* 509: 129636. https://doi.org/10.1016/j.amc.2025.129636 - Agent-based models (ABMs): Kerkmann D, Korf S, Nguyen K, Abele D, Schengen A, et al. (2025). *Agent-based modeling for realistic reproduction of human mobility and contact behavior to evaluate test and isolation strategies in epidemic infectious disease spread*. *Computers in Biology and Medicine* 193: 110269. https://doi.org/10.1016/j.compbiomed.2025.110269 - Hybrid agent-metapopulation-based models: Bicker J, Schmieding R, Meyer-Hermann M, Kühn MJ. (2025). *Hybrid metapopulation agent-based epidemiological models for efficient insight on the individual scale: A contribution to green computing*. *Infectious Disease Modelling* 10(2): 571-590. https://doi.org/10.1016/j.idm.2024.12.015 -- Graph Neural Networks: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2025). *Graph Neural Network Surrogates to leverage Mechanistic Expert Knowledge towards Reliable and Immediate Pandemic Response*. Submitted for publication. https://doi.org/10.48550/arXiv.2411.06500 -- ODE-based models with Linear Chain Trick: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2024). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. Submitted for publication. https://doi.org/10.48550/arXiv.2412.09140 +- Graph Neural Networks: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2025). *Graph Neural Network Surrogates to leverage Mechanistic Expert Knowledge towards Reliable and Immediate Pandemic Response*. *Scientific Reports* 16, 6361. https://doi.org/10.1038/s41598-026-39431-5 +- ODE-based models with Linear Chain Trick: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2026). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. *Mathematics and Computers in Simulation* 239, pp. 823-844. https://doi.org/10.1016/j.matcom.2025.07.045 - Behavior-based ODE models: Zunker H, Dönges P, Lenz P, Contreras S, Kühn MJ. (2025). *Risk-mediated dynamic regulation of effective contacts de-synchronizes outbreaks in metapopulation epidemic models*. Chaos, Solitons & Fractals. https://doi.org/10.1016/j.chaos.2025.116782 diff --git a/cpp/memilio/compartments/flow_model.h b/cpp/memilio/compartments/flow_model.h index 6b923e5f04..9484d15d3d 100644 --- a/cpp/memilio/compartments/flow_model.h +++ b/cpp/memilio/compartments/flow_model.h @@ -236,9 +236,9 @@ class FlowModel : public CompartmentalModel }; /** - * @brief Concept to check if a type is a valid flow model. + * @brief Concept to check if a type is a valid FlowModel. * Note that Model must be the first template argument - * @tparam Model A type that may or may not be a flow model. + * @tparam Model A type that may or may not be a FlowModel. * @tparam FP A floating point type, e.g. double. */ template diff --git a/cpp/memilio/compartments/flow_simulation.h b/cpp/memilio/compartments/flow_simulation.h index 8b9a52fcb0..1293b3ca56 100755 --- a/cpp/memilio/compartments/flow_simulation.h +++ b/cpp/memilio/compartments/flow_simulation.h @@ -42,7 +42,7 @@ class FlowSimulation : public details::FlowSimulationBase /** * @brief Create a FlowSimulationBase. - * @param[in] model An instance of a flow model. + * @param[in] model An instance of a FlowModel. * @param[in] integrator_core A unique pointer to an object derived from IntegratorCore. * @param[in] t0 Start time. * @param[in] dt Initial step size of integration. diff --git a/docs/source/cpp/aggregated_models.rst b/docs/source/cpp/aggregated_models.rst index 5ab44e9b07..613e41a29e 100644 --- a/docs/source/cpp/aggregated_models.rst +++ b/docs/source/cpp/aggregated_models.rst @@ -1,7 +1,11 @@ Aggregated models ================= -There are different equation-based models implemented in MEmilio that consider an aggregated population. +There are different equation-based or compartmental models implemented in MEmilio that consider an aggregated population as shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/aggregated.png + :alt: Overview on MEmilio's models using aggregated populations. + :width: 100% .. toctree:: :maxdepth: 1 diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index d56323f858..57fb3a2471 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -1,7 +1,7 @@ .. include:: ../literature.rst -Diffusive agent-based model -=========================== +Agent-based model (with diffusion) +=================================== This agent-based model uses a Markov process to simulate disease dynamics. The Markov process is given by agent movement and the evolution of disease dynamics i.e. disease transmission and progression. The features of an agent are its position and its infection state. The evolution of the system state is determined by the following master equation diff --git a/docs/source/cpp/mobility_based_abm.rst b/docs/source/cpp/mobility_based_abm.rst index 621f366d5d..7290a2329d 100644 --- a/docs/source/cpp/mobility_based_abm.rst +++ b/docs/source/cpp/mobility_based_abm.rst @@ -1,7 +1,7 @@ .. include:: ../literature.rst -Agent-based model -================= +Agent-based model (with activities and mobility) +================================================ This module models and simulates the epidemic using an agent-based model (*ABM*) approach. Unlike the compartmental models that use a system of ODEs, this model simulates the spread of an epidemic in a population with discrete persons (the agents) moving throughout locations in the diff --git a/docs/source/cpp/ode_creation.rst b/docs/source/cpp/ode_creation.rst index 6fc43bf365..c0c4b76f94 100644 --- a/docs/source/cpp/ode_creation.rst +++ b/docs/source/cpp/ode_creation.rst @@ -162,7 +162,7 @@ example being adding :code:`mio::AgeGroups` to the template. where we use ``populations.get_flat_index`` to get the correct index in the flat state and derivative vectors. You may also want to change the Parameters to use age groups, check out the available ODE models as reference. -Define a compartmental model class +Define a CompartmentalModel class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now we can define the model: @@ -219,7 +219,7 @@ Continue :doc:`here` to learn how to use this model, or read on if you want Implement the ODE model using flows ----------------------------------- -A flow model is a special case of a compartmental model, where the derivative of each compartment over time +A FlowModel is a special case of a CompartmentalModel, where the derivative of each compartment over time :math:`Z_i'(t)` can be written as .. math:: @@ -230,7 +230,7 @@ where the flows :math:`f_{Z_i \rightarrow Z_j} \gt 0` are the amount of populati :math:`Z_i` to :math:`Z_j` at time :math:`t`. So the first sum accumulates all inflows, the second subtracts all outflows. -The SIRD model from above can be expressed as a flow model with only three flows: +The SIRD model from above can be expressed as a FlowModel with only three flows: .. math:: @@ -245,7 +245,7 @@ Note that all other possible flows, like :math:`f_{I \rightarrow S}`, are consta Flows ~~~~~ -To use a flow model, we need to create a list of all flows. These are used by the model to automatically assemble the +To use a FlowModel, we need to create a list of all flows. These are used by the model to automatically assemble the compartments. We use a :code:`mio::TypeList` with a :code:`mio::Flow` for each mathematical flow. For the SIRD model we get: @@ -258,12 +258,12 @@ we get: The first term in each :code:`mio::Flow` is the source compartment, the second the target. As a convention, we always compute non-negative outflows. Hence, we only list the flow :math:`S \rightarrow I`, but not :math:`I \rightarrow S`. -Infection states, Parameters and Population +InfectionStates, Parameters and Population ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since a Flow model is just a special case of a compartmental model, all of these are defined exactly as described above. +Since a FlowModel is just a special case of a CompartmentalModel, all of these are defined exactly as described above. -Define a flow model class +Define a FlowModel class ~~~~~~~~~~~~~~~~~~~~~~~~~ With the flows and classes also used by the CompartmentalModel, we can define a FlowModel as such: @@ -294,7 +294,7 @@ With the flows and classes also used by the CompartmentalModel, we can define a } }; -This is mostly analogous to the definition of a compartmental model, with a few important differences. First, we now +This is mostly analogous to the definition of a CompartmentalModel, with a few important differences. First, we now inherit from ``FlowModel``, which gets the ``Flows`` as an additional template argument. The ``Base`` alias changes accordingly. Secondly, the function we implement is called ``get_flows`` and computes the derivative of y in terms of its flows. diff --git a/docs/source/cpp/overview.rst b/docs/source/cpp/overview.rst index d3fcdc02f0..893767595a 100644 --- a/docs/source/cpp/overview.rst +++ b/docs/source/cpp/overview.rst @@ -2,9 +2,20 @@ Overview ============ +Model structure +---------------- + +The MEmilio library uses a modular organization of models where :doc:`compartmental or aggregated models` based on ODEs (ordinary differential equations) without and with Linear Chain Trick, IDEs (integro-differential equations), and SDEs (stochastic differential equations) share a maximum properties and interfaces (implemented in the *memilio* folder) to allow simple and straightforward model adaption with, e.g., demographic or spatial stratification (e.g. found in the *memilio/mobility* folder to create :doc:`metapopulation models`) as shown in the following figure. :doc:`Agent-based models` are furthermore harmonized with most structures such as parameters, contact patterns, and non-pharmaceutical interventions (e.g. found in *memilio/epidemiology*). + +.. image:: http://martinkuehn.eu/research/images/memilio_backend.png + :alt: Overview on MEmilio's model backend + :width: 100% + +For a quick run through MEmilio's functionality see :doc:`installation`. + The MEmilio C++ project is organized as follows: -Main Directory Structure +Main directory structure --------------------------- The main directory structure in the ``cpp`` directory includes: @@ -33,31 +44,7 @@ The main directory structure in the ``cpp`` directory includes: - **benchmarks/**: Analyzing runtime performance -Model Structure ------------------ - -The MEmilio library uses a modular organization of models, where generic implementations are inherited by specific implementations: - -.. image:: http://martinkuehn.eu/research/images/overview.png - :alt: Model Hierarchy - :width: 100% - -**CompartmentalModel**: The base class for all compartment-based models in MEmilio. It defines the fundamental structure for epidemiological models with compartments (e.g., SEIR, SECIR) and provides methods like ``eval_right_hand_side`` and ``get_initial_values`` required for ODE solvers. - -**FlowModel**: Inherits from CompartmentalModel and extends it with the concept of flows between compartments. Instead of directly defining derivatives, it specifies the flows between compartments. - -**Specific Model Implementations**: - -- **ODE Model** (Ordinary Differential Equations): Deterministic models for continuous populations described by ordinary differential equations. - -- **IDE Model** (Integro-Differential Equations): Extends the ODE model integration terms. - -- **SDE Model** (Stochastic Differential Equations): Adds stochastic components to model uncertainties and random effects. - -**Individual-based Model**: Stands separate from the compartmental hierarchy and models each individual explicitly with its own properties and interactions. This enables more detailed simulations. - - -Build System +Build system ------------- The project uses CMake as a build system with various configuration options. diff --git a/docs/source/cpp/performance_monitoring.rst b/docs/source/cpp/performance_monitoring.rst index 10fcae20de..6edfb1c2b5 100644 --- a/docs/source/cpp/performance_monitoring.rst +++ b/docs/source/cpp/performance_monitoring.rst @@ -23,7 +23,7 @@ Run ``likwid-perfctr ./bin/my_example`` to measure the performance of the entire LIKWID_MARKER_CLOSE; -Set the CMake variable ``MEMILIO_USE_LIKWID=ON`` to enable LIKWID support and run ``likwid-perfctr -m ./bin/my_example``. +Set the CMake variable ``MEMILIO_ENABLE_LIKWID_MARKER=ON`` to enable LIKWID support and run ``likwid-perfctr -m ./bin/my_example``. For more details see the LIKWID documentation, available `here `_. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index cd5a521f7e..b26ea9984a 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -4,11 +4,11 @@ Getting started Overview -------- -.. note:: This project is under active development. +.. note:: This project is under active development with approximately 10 full time developers. Any content provided in the repository has been extensively reviewed and can be considered stable. Regular function extensions can be expected. New features are, if possible, integrated in a backward-stable manner but interfaces might change over time. MEmilio is an extensive framework for tasks around infectious disease modeling. It supports a multitude of :ref:`model ` types -including :doc:`equation-based`, :doc:`agent-based `, +including :doc:`equation-based or compartmental`, :doc:`agent-based `, and :doc:`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 :doc:`ordinary differential equations `, :doc:`the linear chain trick (LCT), ` and a recent :doc:`generalized LCT `, :doc:`integro-differential equations ` @@ -29,7 +29,7 @@ as infection or mobility data. More about this and our other Python packages can 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 +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 @@ -38,6 +38,12 @@ 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. +In the following figure, we representatively show an excerpt of Fig. 6 of `Bicker et al. (2026), DOI: 10.48550/arXiv.2602.11381 `_ showing the performance of population and metapopulation models implemented in R and in C++ in MEmilio. While for large numbers of regions, the R model based on the C-implemented routine desolve comes close to MEmilio's C++ routine performance, both interfaces (C++ and Python) of MEmilio realize significant speedups (factor 100 and more) for most applications. + +.. image:: http://martinkuehn.eu/research/images/speedup_memilio.png + :alt: Performance of population and metapopulation models implemented in R and in C++ in MEmilio. + :width: 100% + 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. :doc:`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. @@ -54,9 +60,172 @@ For Python, please see, e.g., :doc:`ODE-based SECIRTS model ` 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 :doc:`(mobility-based) agent-based model `. +A quick tour through MEmilio +----------------------------- -How to use MEmilio ------------------- +While MEmilio harmonizes much of its structures across all model classes, we first distinguish between :doc:`compartmental or aggregated models` based on ODEs (ordinary differential equations) without and with Linear Chain Trick, IDEs (integro-differential equations), and SDEs (stochastic differential equations) and :doc:`Agent-based models`. The following subsections give a brief overview on essential functionality, each presented in a particular and function-specific tutorial. While several tutorials build on previous tutorials, experienced users or users interested in other models might also want jump to later parts of this walkthrough guide. + +An additional overview on MEmilio's elementary model structure is given by the following figure. + +.. image:: http://martinkuehn.eu/research/images/model_structure.png + :alt: Overview on MEmilio's model structure. + :width: 100% + +MEmilio benefits from a harmonized description of its models in infection states and parameters, and, potentially, a list of flows between the compartments; see the following figure for a motivation. All models derive their infection states from a flexible and simple list of InfectionStates. For FlowModels (see below for an explanation), particular transitions are defined evenly flexible as a list of flows between the states. Parameters are also generally defined in an identical fashion. + +.. image:: http://martinkuehn.eu/research/images/uniform.png + :alt: MEmilio's uniform model description. + :width: 100% + +Below we guide you through several tutorials on using MEmilio's models through its Python interface. More experience users might directly start with the `Python exercises `_ which are derived versions from the tutorials or with `tutorial and exercises in C++ `_. For more advanced aggregated models using the Linear Chain Trick or IDE-formulations, we currently only provided tutorials and exercises in C++. For the individual- or agent-based model (ABM), we currently only provide `ABM tutorials in C++ `_. + + +Simple compartmental models +**************************** + +Most of MEmilio's compartmental or aggregated models share the same interface derived from a high-level **CompartmentalModel** (see above). It defines the fundamental structure for epidemiological models with compartments (e.g., SEIR, SECIR, SIRS, etc.). + +In `Tutorial 01 `_, we show how set up and simulate a simple setting for our :doc:`ODE-SECIR model `. The result of the tutorial is a figure of a well-known epidemic outcome. + +.. image:: http://martinkuehn.eu/research/images/tutorial01.png + :alt: A well-known epidemic outcome as a result of Tutorial 01. + :width: 100% + + +Flows between compartments +************************** + +Often, modelers might be interested not only in the estimated number of individuals in a state of the disease but also on the number of recent or current transitions between different states such as the number of new hospitalizations. As modelers could introduce additional compartments only following those transitions or do complex post-processing, MEmilio directly computes all transitions between compartments by default. This is realized through MEmilio's **FlowModel** structure which is a still generic but refined specification of the **CompartmentalModel**. Through an optimized backend, the overhead for computing transitions (i.e. flows) and compartmental values is less than 10 %. + +In `Tutorial 02 `_, we show how to obtain the numbers of newly symptomatic and hospitalized individuals for our :doc:`ODE-SECIR model `. TThe result of the tutorial is shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/tutorial02.png + :alt: Newly symptomatic and hospitalized individuals as obtained from Tutorial 02. + :width: 100% + + +Demography and contact structures +********************************* + +As motivated in the following figure, MEmilio's models are implemented in a way that they can be stratified by age groups (or other dimensions such as sex) in a single line. + +.. image:: http://martinkuehn.eu/research/images/contacts.png + :alt: Module for flexible demographic stratification by age groups. + :width: 100% + +In `Tutorial 05 `_, we show how to distinguish individuals of three different age groups by their susceptibility with respect to severe and critical infections and simulate outcomes for our :doc:`ODE-SECIR model `. The result of the tutorial is shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/tutorial05.png + :alt: Different epidemic curves for six different age groups. + :width: 100% + +Metapopulation and mobility +*************************** + +As motivated in the following figure, MEmilio's aggregated models can be extended to metapopulation models by using a graph structure. + +.. image:: http://martinkuehn.eu/research/images/mobility.png + :alt: Module for flexible spatial resolution in metapopulation models. + :width: 100% + +In `Tutorial 07 `_, we show how an epidemic with our :doc:`ODE-SECIR model ` evolves with a delay between two different spatial entities. The result of the tutorial is shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/tutorial07.png + :alt: Delayed epidemic spreading through metapopulation coupling of two regions. + :width: 100% + +Fixed time-point interventions +****************************** + +In order to control and mitigate epidemic developments, MEmilio provides the ability to introduce non-pharmaceutical interventions (NPIs) or measures as `Dampings` to the contact frequencies. In `Tutorial 03 `_, we show how an epidemic with our :doc:`ODE-SECIR model ` can be first mitigated before a reopening event takes place. The result of the tutorial is shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/tutorial03.png + :alt: Changed epidemic outcome through interventions at fixed time points. + :width: 100% + + +Location-specific interventions +******************************* + +Often interventions are targeted to specific types of locations such as schools, workplaces, or social gatherings. In order to most realistically model contact structures and NPIs across different locations, MEmilio uses simple and flexible lists of contact locations. In `Tutorial 10 `_, we explain with our :doc:`ODE-SECIR model ` contact structures can be stratified by locations and NPIs implemented in a location-specific way. The result of the tutorial is shown in the following figure. + +.. image:: http://martinkuehn.eu/research/images/tutorial10.png + :alt: Changed epidemic outcome through interventions at specific locations. + :width: 100% + +Dynamic interventions +********************* + +Eventually, NPIs might often be bound to a threshold or criterion upon which its get activated, e.g., the number of new symptomatic (here, reported) infections over the last days. In order to allow dynamic, threshold-dependent NPIs, MEmilio implements a structure denoted `DynamicNPIs`. In `Tutorial 11 `_, we explain with our :doc:`ODE-SECIR model ` how to set up and simulate dynamic interventions based on symptomatic infections. The result of the tutorial is shown in the following figure. + +Note that the DynamicNPI feature is currently fixed to interventions based on symptomatic infections but if you are interested in using it for other applications, please get in touch with us, as the change could be done by us in very short time. + +.. image:: http://martinkuehn.eu/research/images/tutorial11.png + :alt: Changed epidemic outcome through dynamically activated interventions. + :width: 100% + +Fitting MEmilio's models +************************ + +As parameter inference is a research topic of its own, MEmilio does not provide methods for parameter inference but instead provides well designed interfaces to established tools and packages dedicated to model calibration and parameter inference. + +`Tutorial 04 `_ and `Tutorial 06 `_, we introduce usage of Approximate Bayesian Computation (ABC) with MEmilio and `pyABC `_ for likelihood-free inference. + +The result of Tutorial 04 are the projections of the calibrated model using pyABC: + +.. image:: http://martinkuehn.eu/research/images/tutorial04.png + :alt: Projections of the calibrated model using pyABC. + :width: 100% + +The result of Tutorial 06 are the posterior distributions for the model parameters using pyABC: + +.. image:: http://martinkuehn.eu/research/images/tutorial06.png + :alt: Posterior distributions for the model parameters using pyABC. + :width: 100% + +In `Tutorial 09 `_ we use `Bayesflow `_, a state of the art python library for Bayesian inference with deep learning. The result of Tutorial 09 is the region- and age-specific calibration using BayesFlow: + +.. image:: http://martinkuehn.eu/research/images/tutorial09.png + :alt: Region- and age-specific calibration using BayesFlow. + :width: 100% + +Linear Chain Trick +******************* + +As among others shown in `Plötzke et al. (2026), DOI: 10.1016/j.matcom.2025.07.045 `_, exponentially distributed stay times can lead to (substantially) deviating peak timings and values; see also the following figure extracted from Fig. 8 of the mentioned paper. + +.. image:: http://martinkuehn.eu/research/images/lct.png + :alt: Deviating peaks with exponential distribution assumptions (ODE) versus Linear Chain Trick with Erlang/Gamma distributions. + :width: 100% + +In the `LCT Tutorial `_, we show a minimalistic example of an LCT model within MEmilio. Parameters, contact structures, and NPIs can basically be used as in the introductions to simple ODE models. If you are interested in using LCT models with different courses of the disease, please get in touch with us. + +IDE-based models +***************** + +While LCT models generalize assumptions from exponential to Gamma, IDE formulations such as presented `Wendler et al. (2026), DOI: 10.1016/j.amc.2025.129636 `_ allow the full flexibility to use any data-driven transition distribution. + +In the `IDE Tutorial `_, we show a minimalistic example of an IDE model within MEmilio. Parameters, contact structures, and NPIs can basically be used as in the introductions to simple ODE models. If you are interested in using IDE models with different courses of the disease, please get in touch with us. + + +Agent- or individual-based model +******************************** + +As motivated in Fig. 5 of `Bicker et al. (2026), DOI: 10.48550/arXiv.2602.11381 `_ and shown here below, different types of models with their implicit or flexible assumptions can lead to all type of epidemic projections. + +.. image:: http://martinkuehn.eu/research/images/model_comparisons.png + :alt: Results of infectious disease spread with different models and model assumptions. + :width: 100% + +A major advantage of agent-based models (ABMs) is the possibility to model individuals with individual properties. In the MEmilio-ABM populations are set up straightforward with household structures. Testing and vaccination strategies can be targeted to individuals at particular locations or of selected age groups. + +- In the `tutorial on households `_, we show how particular populations and household structures can be set up with the MEmilio-ABM. +- In the `tutorial on testing `_, we show how different testing strategies with particular testing schemes can be realized. +- In the `tutorial on vaccination `_, we show how different vaccination strategies can be realized. + + +Download and installation +------------------------- 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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 054ef15baa..52ef77fb7c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,7 +14,7 @@ Welcome MEmilio implements various models for infectious disease dynamics, ranging from simple compartmental models to complex Integro-Differential and agent-based models. Its modular design enables the combination of different models with distinct mobility patterns. Through efficient implementation and parallelization in C++ and an easy-to-use python interface, MEmilio delivers cutting-edge and compute-intensive epidemiological models to broad range of applications and users, providing precise and high-resolution spatiotemporal infectious disease dynamics. MEmilio is continuously extended and is available open-source for community use. -.. image:: http://martinkuehn.eu/research/images/MEmilio_small.png +.. image:: http://martinkuehn.eu/research/images/memilio_small_new.png :alt: Memilio Overview If you use MEmilio, please :doc:`cite our work`. diff --git a/docs/source/literature.rst b/docs/source/literature.rst index 7c4c513f2f..d76da272d2 100644 --- a/docs/source/literature.rst +++ b/docs/source/literature.rst @@ -18,11 +18,11 @@ .. |Hybrid_metapopulation_agent-based_DOI| replace:: DOI:10.1016/j.idm.2024.12.015 .. _Hybrid_metapopulation_agent-based_DOI: https://doi.org/10.1016/j.idm.2024.12.015 -.. |Graph_Neural_Network_Surrogates| replace:: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2026). *Graph neural network surrogates to leverage mechanistic expert knowledge towards reliable and immediate pandemic response*. *Scientific Reports*. |Graph_Neural_Network_Surrogates_DOI|_ +.. |Graph_Neural_Network_Surrogates| replace:: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2026). *Graph neural network surrogates to leverage mechanistic expert knowledge towards reliable and immediate pandemic response*. *Scientific Reports* 16, 6361. |Graph_Neural_Network_Surrogates_DOI|_ .. |Graph_Neural_Network_Surrogates_DOI| replace:: DOI:10.1038/s41598-026-39431-5 .. _Graph_Neural_Network_Surrogates_DOI: https://doi.org/10.1038/s41598-026-39431-5 -.. |Revisiting_the_Linear_Chain| replace:: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2024). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. Mathematics and Computers in Simulation 239, pp. 823-844 (2026). |Revisiting_the_Linear_Chain_DOI|_ +.. |Revisiting_the_Linear_Chain| replace:: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2026). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. *Mathematics and Computers in Simulation* 239, pp. 823-844. |Revisiting_the_Linear_Chain_DOI|_ .. |Revisiting_the_Linear_Chain_DOI| replace:: DOI:10.1016/j.matcom.2025.07.045 .. _Revisiting_the_Linear_Chain_DOI: https://doi.org/10.1016/j.matcom.2025.07.045 @@ -62,6 +62,11 @@ .. |Coupled_Epidemiological_and_Wastewater_DOI| replace:: DOI:10.1101/2025.09.25.25336633 .. _Coupled_Epidemiological_and_Wastewater_DOI: https://doi.org/10.1101/2025.09.25.25336633 -.. |Missing_Transmission_Chains| replace:: Korf S, Wagner S J, Köster G, Kühn M J (2025). *On the Effect of Missing Transmission Chain Information in Agent-Based Models: Outcomes of Superspreading Events and Workplace Transmission*. arXiv. |Missing_Transmission_Chains_DOI|_ -.. |Missing_Transmission_Chains_DOI| replace:: DOI:10.48550/ARXIV.2512.06189 -.. _Missing_Transmission_Chains_DOI: https://doi.org/10.48550/ARXIV.2512.06189 +.. |Missing_Transmission_Chains| replace:: Korf S, Wagner S J, Köster G, Kühn M J (2026). *On the Effect of Missing Transmission Chain Information in Agent-Based Models: Outcomes of Superspreading Events and Workplace Transmission*. *Chaos, Solitons & Fractals* 208 (2), July 2026, 118179. |Missing_Transmission_Chains_DOI|_ +.. |Missing_Transmission_Chains_DOI| replace:: DOI:10.1016/j.chaos.2026.118179 +.. _Missing_Transmission_Chains_DOI: https://doi.org/10.1016/j.chaos.2026.118179 + +.. |Traveler_estimation| replace:: Zunker H, Schmieding R, Hasenauer J, Kühn M J (2026). *Efficient numerical computation of traveler states in explicit mobility-based metapopulation models: Mathematical theory and application to epidemics*. arXiv. |Traveler_estimation_DOI|_ +.. |Traveler_estimation_DOI| replace:: DOI:10.1016/10.48550/arXiv.2603.11275 +.. _Traveler_estimation_DOI: https://doi.org/10.48550/arXiv.2603.11275 + diff --git a/docs/source/references.rst b/docs/source/references.rst index c18f4583ae..d040493273 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -10,7 +10,7 @@ Recently submitted publications - |MEmilio_citation| -- |Missing_Transmission_Chains| +- |Traveler_estimation| - |Coupled_Epidemiological_and_Wastewater| @@ -23,12 +23,14 @@ Peer-reviewed publications **2026** +- |Missing_Transmission_Chains| + +- |Graph_Neural_Network_Surrogates| + - |Revisiting_the_Linear_Chain| - |A_nonstandard_numerical_scheme| -- |Graph_Neural_Network_Surrogates| - **2025** - |Risk-mediated_dynamic_regulation| diff --git a/docs/source/team.rst b/docs/source/team.rst index be0f076150..884f1d7d89 100644 --- a/docs/source/team.rst +++ b/docs/source/team.rst @@ -30,6 +30,8 @@ Martin Kühn studied at University of Cologne, Germany, and Université de Montr :animate: fade-in-slide-down * |MEmilio_citation| + * |Traveler_estimation| + * |Missing_Transmission_Chains| * |Graph_Neural_Network_Surrogates| * |A_nonstandard_numerical_scheme| * |Revisiting_the_Linear_Chain| @@ -66,6 +68,7 @@ Henrik Zunker is a PhD student at the Institute of Software Technology at the Ge :animate: fade-in-slide-down * |MEmilio_citation| + * |Traveler_estimation| * |Risk-mediated_dynamic_regulation| * |Graph_Neural_Network_Surrogates| * |Novel_travel_time_aware_metapopulation_models| @@ -97,9 +100,9 @@ His background is in numerical mathematics, where he studied at the University o :animate: fade-in-slide-down * |MEmilio_citation| + * |Missing_Transmission_Chains| * |Agent-based_modeling_for| * |Integrating_Human_Mobility_Models| - * |Missing_Transmission_Chains| .. dropdown:: Links :animate: fade-in-slide-down @@ -251,6 +254,7 @@ equation-based models. :animate: fade-in-slide-down * |MEmilio_citation| + * |traveler_estimation| * |Novel_travel_time_aware_metapopulation_models| * |Hybrid_metapopulation_agent-based| * |Integrating_Human_Mobility_Models| @@ -314,6 +318,70 @@ Daniel Abele is a research software engineer at the Institute of Software Techno * `ORCID Profile: 0000-0001-7021-1573 `__ +Lena Plötzke +^^^^^^^^^^^ + +.. image:: _static/team/max_mustermann.jpg + :alt: NAME + :width: 150px + :align: left + :class: developer-photo + +**Research Focus:** High-Performance Computing, Mathematical Modeling, Scientific Computing, Linear Chain Trick (LCT), Integro-Differential Equations (IDEs) + +Lena Plötzke received her Bachelor's and Master's degrees from the University of Cologne in collaboration with the German Aerospace Center (DLR). Her bachelor's thesis examined models using integro-differential equations and her master's thesis focused on the Linear Chain Trick. She later authored a paper based on this research. Lena worked on the MEmilio software from September 2021 to January 2025. + +.. dropdown:: Selected Publications + :animate: fade-in-slide-down + + * |MEmilio_citation| + * |A_nonstandard_numerical_scheme| + * |Revisiting_the_Linear_Chain| + +.. dropdown:: Links + :animate: fade-in-slide-down + + * `ORCID Profile: 0000-0003-0440-1429 `__ + + + +Khoa Nguyen +^^^^^^^^^^^ + +.. image:: https://martinkuehn.eu/research/images/khoa.png + :alt: Khoa Nguyen + :width: 150px + :align: left + :class: developer-photo + +**Research Focus:** + +Agent-Based Modeling, Computational Social Science, Mobility and Energy Transitions, Epidemiological Simulation, Policy-Oriented Simulation, Behavioural Decision Modeling + +Khoa Nguyen obtained an MEng in Computing from Imperial College London and a PhD in Computer Science from Utrecht University, with a thesis on behavioural decision-making frameworks for agent-based models. He has held research positions at HES-SO Valais-Wallis, the Helmholtz Centre for Infection Research, and UniSanté in Lausanne, working at the intersection of computational modeling, public policy, and applied AI. His research focuses on the development and application of simulation models to study complex socio-technical systems, particularly in the domains of mobility, energy, infectious disease, and health services. Over the years, he contributed to developing and analyzing models for Swiss mobility demand (BedDeM), epidemic spread based on population mobility (PANDEMOS), and AI-driven digital navigation platforms in healthcare (UniSanté). His work spans multi-agent systems, micro–macro model coupling, and policy-oriented scenario analysis, leveraging agent-based, metapopulation-style, and hybrid approaches alongside modern data and AI pipelines. + + +.. dropdown:: Selected Publications + :animate: fade-in-slide-down + + * |MEmilio_citation| + * |Agent-based_modeling_for| + * Nguyen, K. (2023). A Behavioural Decision-Making Framework For Agent-Based Models. PhD thesis, Utrecht University. https://dspace.library.uu.nl/handle/1874/425798. + * Nguyen, K., Piana, V., and Schumann, R. (2022). Simulating bounded rationality in decision-making: an agent-based choice modelling of vehicle purchasing. In Conference of the European Social Simulation Association, pages 421–433. Springer. DOI: http://dx.doi.org/10.1007/978-3-031-34920-1_34 + * Nguyen, K. and Schumann, R. (2021). An exploratory comparison of behavioural determinants in mobility modal choices. In Ahrweiler, P. and Neumann, M., editors, Advances in Social Simulation, pages 569–581, Cham. Springer International Publishing. DOI: https://doi.org/10.1007/978-3-030-61503-1_54 + * Nguyen, K. and Schumann, R. (2021). A socio-psychological approach to simulate trust and reputation in modal choices. In Uchiya, T., Bai, Q., and Marsá Maestre, I., editors, PRIMA 2020: Principles and Practice of Multi-Agent Systems, Lecture Notes in Computer Science, pages 39–54, Cham. Springer International Publishing. https://doi.org/10.1007/978-3-030-69322-0_3 + * Nguyen, K. and Schumann, R. (2020). A socio-psychological modal choice approach to modelling mobility and energy demand for electric vehicles. In Nguyen, K., Roman, R., and Schumann, R., editors, Proceedings of the 9th DACH+ Conference on Energy Informatics, volume 3 of Energy Informatics. Springer. DOI: https://doi.org/10.1186/s42162-020-00123-7 + * Nguyen, K. and Schumann, R. (2020). On developing a more comprehensive decision-making architecture for empirical social research: Lesson from agent-based simulation of mobility demands in Switzerland. In Paolucci, M., Sichman, J. S., and Verhagen, H., editors, Multi-Agent-Based Simulation XX, volume XX of International Workshop on Multi-Agent Systems and Agent-Based Simulation, pages 39–54, Cham. Springer International Publishing. DOI: https://doi.org/10.1007/978-3-030-60843-9_4 + + +.. dropdown:: Links + :animate: fade-in-slide-down + + * `Google Scholar Profile `__ + * `ORCID Profile: 0000-0002-3123-602X `__ + + + Margrit Klitz ^^^^^^^^^^^^^ @@ -391,6 +459,32 @@ Paul Johannssen studied mathematics at the University of Bonn. He worked on the We thank all contributors, who have contributed to MEmilio. For a complete list of contributors, please see our `GitHub Contributors page `__. + +Vincent Wieland +^^^^^^^^^^^^^^^^ + +.. image:: https://martinkuehn.eu/research/images/vincent.png + :alt: Vincent Wieland + :width: 150px + :align: left + :class: developer-photo + +**Research Focus:** Stochastic Modeling, Bayesian Inference, Clinical Trajectory Analysis, Infectious Disease Modeling + +Vincent Wieland is a PhD student at the Center for Mathematical Life Sciences in Bonn since 2023. Vincent holds a B.Sc. and a M.Sc. in Mathematics from the University of Bonn. In his Masters he focused on stochastic analysis and joined the group of Prof. Jan Hasenauer for his Master thesis. After the completion, he continued his education as a PhD student in the group working on stochastic modelling of disease progression and application to clinical data. + +.. dropdown:: Selected Publications + :animate: fade-in-slide-down + + * |MEmilio_citation| + +.. dropdown:: Links + :animate: fade-in-slide-down + + * `Google Scholar Profile `__ + * `ORCID Profile: 0009-0003-9592-8871 `__ + + .. _collaboration: Contributing research groups and institutes