Extend documentation and fix typos and bugs in documentation

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
 
 

cpp/memilio/compartments/flow_model.h

@@ -236,9 +236,9 @@ class FlowModel : public CompartmentalModel<FP, Comp, Pop, Params>
 };
 
 /**
- * @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 <class Model, typename FP>

cpp/memilio/compartments/flow_simulation.h

@@ -42,7 +42,7 @@ class FlowSimulation : public details::FlowSimulationBase<FP, M, OdeIntegrator<F
 
     /**
      * @brief Set up the simulation with an ODE solver.
-     * @param[in] model An instance of a flow model.
+     * @param[in] model An instance of a FlowModel.
      * @param[in] t0 Start time.
      * @param[in] dt Initial step size of integration.
      */

cpp/memilio/compartments/flow_simulation_base.h

@@ -48,7 +48,7 @@ class FlowSimulationBase : public SimulationBase<FP, M, Integrands...>
 
     /**
      * @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.

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

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

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

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<ode>` 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.

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<cpp/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<cpp/metapop>`) as shown in the following figure. :doc:`Agent-based models<cpp/individual_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. 

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 <https://github.com/RRZE-HPC/likwid/wiki/likwid-perfctr>`_.