Revision and addition of documentation for workshop

Author: mknaranja

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/getting_started.rst

@@ -8,7 +8,7 @@ Overview
 
 
 MEmilio is an extensive framework for tasks around infectious disease modeling. It supports a multitude of :ref:`model <model-faq>` types 
-including :doc:`equation-based<cpp/aggregated_models>`, :doc:`agent-based <cpp/individual_models>`, 
+including :doc:`equation-based or compartmental<cpp/aggregated_models>`, :doc:`agent-based <cpp/individual_models>`, 
 and :doc:`hybrid graph-ODE-based models <cpp/graph_metapop>`. 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 <cpp/ode>`,
 :doc:`the linear chain trick (LCT), <cpp/lct>` and a recent :doc:`generalized LCT <cpp/glct>`, :doc:`integro-differential equations <cpp/ide>` 
@@ -54,9 +54,66 @@ For Python, please see, e.g., :doc:`ODE-based SECIRTS model <python/m-simulation
 
 When individual-level interactions and heterogeneity are crucial, :doc:`individual-based models <cpp/individual_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 :doc:`(mobility-based) agent-based model <cpp/mobility_based_abm>`.
 
+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<cpp/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<cpp/individual_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. 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 mostly 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 <https://github.com/SciCompMod/memilio-tutorials/tree/main/exercises>`_ which are derived versions from the tutorials or with `tutorial and exercises in C++ <https://github.com/SciCompMod/memilio-tutorials/tree/main/cpp-tutorials>`_. 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++ <
+https://github.com/SciCompMod/memilio-tutorials/tree/main/cpp-tutorials/abm>`_. 
+
+
+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 <https://github.com/SciCompMod/memilio-tutorials/blob/main/tutorial01.py>`_, we show how set up and simulate a simple setting for our :doc:`ODE-SECIR model <models/osecir>`. 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
+**************************
+
+**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.
+
+
+Demography and contact structures
+*********************************
+
+
+
+
+Metapopulation and mobility
+***************************
+
+
+
+Fixed time-point interventions
+******************************
+
+
+Dynamic interventions
+*********************
+
+
+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.

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