Updates and Fixes in the documentation (#1481)

kilianvolmer · reneSchm · mknaranja · web-flow · commit b7f220f4d8ca · 2026-02-10T14:39:36.000+01:00
- Doxyfile was updated to newer version of doxygen
- Citations were updated
- Fixes to layout and content of documentation

Co-authored-by: reneSchm &lt;49305466+reneSchm@users.noreply.github.com&gt;
Co-authored-by: Kühn &lt;Martin.Kuehn@dlr.de&gt;
Co-authored-by: Henrik Zunker &lt;69154294+HenrZu@users.noreply.github.com&gt;
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,8 +1,8 @@
 cff-version: "1.2.0"
 message: "If you use this software, please cite it using the metadata below."
-title: "MEmilio v2.1.0 - A high performance Modular EpideMIcs simuLatIOn software"
-version: "2.1.0"
-date-released: "2025-08"
+title: "MEmilio v2.2.0 - A high performance Modular EpideMIcs simuLatIOn software"
+version: "2.2.0"
+date-released: "2025-11"
 authors:
   - given-names: "Julia"
     family-names: "Bicker"
@@ -59,5 +59,5 @@ keywords:
   - agent-based modeling
   - metapopulation models
   - mobility
-url: "https://elib.dlr.de/213614/"
+url: "https://elib.dlr.de/219141/"
 abstract: "MEmilio implements various models for infectious disease dynamics, from simple compartmental (ODE) models through Integro-Differential equation-based (IDE) models (sometimes also denoted 'age of infection models') to agent- or individual-based models (ABMs). Its modular design allows the combination of different models with different mobility patterns. Through efficient implementation and parallelization, MEmilio brings cutting edge and compute intensive epidemiological models to a large scale, enabling a precise and high-resolution spatiotemporal infectious disease dynamics."
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ MEmilio implements various models for infectious disease dynamics, from simple c
 
 If you use MEmilio, please cite our work
 
-- Bicker J, Kerkmann D, Korf S, Plötzke L, Schmieding R, Wendler A, Zunker H et al. (2025)  *MEmilio - a High Performance Modular Epidemics Simulation Software*. Available at https://github.com/SciCompMod/memilio and https://elib.dlr.de/213614/ .
+- Bicker J, Kerkmann D, Korf S, Plötzke L, Schmieding R, Wendler A, Zunker H et al. (2025)  *MEmilio - a High Performance Modular Epidemics Simulation Software*. Available at https://github.com/SciCompMod/memilio and https://elib.dlr.de/219141/ .
 
 and, in particular, for
 
diff --git a/cpp/memilio/io/README.md b/cpp/memilio/io/README.md
diff --git a/cpp/models/sde_seirvv/README.md b/cpp/models/sde_seirvv/README.md
@@ -1,5 +1,5 @@
 # SDE-based SEIR-type model with two variants
 
 This directory contains a model implementation based on an SDE formulation. 
-To get started, check out the [official documentation](https://memilio.readthedocs.io/en/latest/cpp/models/sseirvv.html) 
-or the [code example](../../examples/sde_seirvv.cpp).
+To get started, check out the [official documentation](https://memilio.readthedocs.io/en/latest/cpp/models/sseir.html) 
+or the [code example](../../examples/sde_seir.cpp).
diff --git a/docs/Doxyfile b/docs/Doxyfile
diff --git a/docs/source/cpp/graph_abm.rst b/docs/source/cpp/graph_abm.rst
@@ -9,7 +9,7 @@ as nodes in a directed graph. One local model represents a geographical region.
 and via the graph edges follows the same mobility rules that can be handed as argument to ``mio::GraphABModel``. 
 Therefore this graph-based agent-based (graph-ABM) model can be reduced to a single mobility-based agent-based model if 
 simulation time steps within the whole graph, i.e. the step size of each node and the step size of the edge exchange, are equal. 
-Preimplemented mobility rules can be found in `<https://github.com/SciCompMod/memilio/blob/main/cpp/models/abm/mobility_rules.h>`_. 
+Preimplemented mobility rules can be found in `cpp/models/abm/mobility_rules.h <https://github.com/SciCompMod/memilio/blob/main/cpp/models/abm/mobility_rules.h>`_. 
 The motivation behind the graph-ABM is to have multiple ABMs run independently from each other in parallel for different regions and only synchronize, 
 i.e. exchange agents via edges, in fixed time intervals. The synchronization time steps should be bigger than the internal 
 ABM time steps to reduce communication between nodes as much as possible.
@@ -148,8 +148,8 @@ Below, ``mio::abm::LogInfectionState`` is used as logger.
     graph.add_edge(model1.get_id(), model2.get_id());
     graph.add_edge(model2.get_id(), model1.get_id());
 
-To simulate the model from `start_date` to `end_date` with given graph step size `exchange_time_span`, a GraphSimulation has to be created. 
-The step size is used to regularly exchange agents via the graph edges. Advancing the simulation until `end_date` is done as follows:
+To simulate the model from ``start_date`` to ``end_date`` with given graph step size ``exchange_time_span``, a GraphSimulation has to be created. 
+The step size is used to regularly exchange agents via the graph edges. Advancing the simulation until ``end_date`` is done as follows:
 
 .. code-block:: cpp
 
diff --git a/docs/source/cpp/graph_metapop.rst b/docs/source/cpp/graph_metapop.rst
@@ -205,7 +205,7 @@ The following steps detail how to configure and execute a graph simulation:
         builder.add_edge(0, 1, 100);
         builder.add_edge(1, 0, 100);
         builder.add_edge(0, 1, 200);
-        auto graph = builder.build(true);
+        auto graph = std::move(builder).build(true); // Builder can not be reused
         // graph contains the edges (0, 1, 100) and (1, 0, 100)
 
 
diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst
@@ -1,10 +1,10 @@
-2 Diseases in LCT-based SECIR-type model
+Two diseases in LCT-based SECIR-type model
 ==========================
 
-| The LCT-SECIR-2-DISEASES model is an extension of the :doc:`model with one disease <lsecir>`.
-| The model is ODE-based and uses the Linear Chain Trick to allow for more general Erlang distributed stay times in each compartment instead of just exponentially distributed stay times induced by basic ODE-based models.
-| With the SECIR structure the model is particularly suited for pathogens with pre- or asymptomatic infection states and when severe or critical states are possible. 
-| For the two diseases or variants of one disease :math:`a` and :math:`b` the model assumes no co-infection, a certain independence in the sense that prior infection with one disease does not affect the infection with the other disease (e.g. probability to get infected, time spend in each state, chances of recovery etc.), and perfect immunity after recovery for both diseases.
+The LCT-SECIR-2-DISEASES model is an extension of the :doc:`model with one disease <lsecir>`.
+The model is ODE-based and uses the Linear Chain Trick to allow for more general Erlang distributed stay times in each compartment instead of just exponentially distributed stay times induced by basic ODE-based models.
+With the SECIR structure the model is particularly suited for pathogens with pre- or asymptomatic infection states and when severe or critical states are possible. 
+For the two diseases or variants of one disease :math:`a` and :math:`b` the model assumes no co-infection, a certain independence in the sense that prior infection with one disease does not affect the infection with the other disease (e.g. probability to get infected, time spend in each state, chances of recovery etc.), and perfect immunity after recovery for both diseases.
 
 
 There are two possibilities for a susceptible individual (since we assume no co-infection): 
@@ -16,7 +16,7 @@ so the full model is given by the combination of infections :math:`1a`, :math:`2
 
 Below is a visualization of the infection states split into LCT-states and transitions without a stratification according to sociodemographic groups.
 
-.. image:: ""
+.. image:: "http://martinkuehn.eu/research/images/lct_2d.png"
    :alt: tikz_lct-2d
 
 With infection states for :math:`i \in \{1,2\}, x \in \{a,b\}`:
@@ -98,12 +98,12 @@ The model contains the following list of **InfectionState**\s:
    
     `Recovered_ab`
 
-| It is possible to include subcompartments for the states `E`, `C`, `I`, `H`, and `U`, so compartments 
-| Exposed_1a, Exposed_2a, Exposed_1b, Exposed_2b,
-| InfectedNoSymptoms_1a, InfectedNoSymptoms_2a, InfectedNoSymptoms_1b, InfectedNoSymptoms_2b,
-| InfectedSymptoms_1a , InfectedSymptoms_2a, InfectedSymptoms_1b , InfectedSymptoms_2b, 
-| InfectedSevere_1a, InfectedSevere_2a , InfectedSevere_1b , InfectedSevere_2b,
-| InfectedCritical_1a, InfectedCritical_2a, InfectedCritical_1b, and InfectedCritical_2b. 
+It is possible to include subcompartments for the states `E`, `C`, `I`, `H`, and `U`, so compartments 
+Exposed_1a, Exposed_2a, Exposed_1b, Exposed_2b,
+InfectedNoSymptoms_1a, InfectedNoSymptoms_2a, InfectedNoSymptoms_1b, InfectedNoSymptoms_2b,
+InfectedSymptoms_1a , InfectedSymptoms_2a, InfectedSymptoms_1b , InfectedSymptoms_2b, 
+InfectedSevere_1a, InfectedSevere_2a , InfectedSevere_1b , InfectedSevere_2b,
+InfectedCritical_1a, InfectedCritical_2a, InfectedCritical_1b, and InfectedCritical_2b. 
  
 The number of subcompartments can be set individually for each compartment.
 
diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst
@@ -317,7 +317,7 @@ The model also supports dynamic NPIs based on epidemic thresholds:
     dynamic_npis.set_base_value(100'000);                // Per 100,000 population
     dynamic_npis.set_threshold(200.0, dampings);         // Trigger at 200 cases per 100,000
 
-For more complex scenarios, such as real-world venue closures or lockdown modeling, detailed NPIs with location-specific dampings can be implemented. For further details, see the documentation of the :doc:`ODE-SECIR model <cpp/osecir>`
+For more complex scenarios, such as real-world venue closures or lockdown modeling, detailed NPIs with location-specific dampings can be implemented. For further details, see the documentation of the :doc:`ODE-SECIR model <osecir>`
 
 Simulation
 ----------
diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst
@@ -1,7 +1,7 @@
 ODE-based SECIR-type model with COVID-19 variants and vaccinations
 ====================================================================
 
-This model extends the basic :doc:`ODE-SECIR model <cpp/osecir>`. by adding vaccinations and allowing the implicit modeling of a newly arriving variant that takes hold.
+This model extends the basic :doc:`ODE-SECIR model <osecir>`. by adding vaccinations and different immunity levels. Also, this model allows the implicit modeling of a newly arriving variant that takes hold.
 
 Vaccinations are modeled by adding compartments for partially and fully vaccinated persons. **Partially** and **fully vaccinated** is to be understood in this context as the person having received a first and second vaccine shot as in 2021. Persons that have recovered from the disease are treated as fully vaccinated from that time forward. Vaccinated persons are added on every day of simulation, see parameters ``DailyPartialVaccinations`` and ``DailyFullVaccinations``. All groups can get an infection or get reinfected. Vaccinated persons are less likely to develop symptoms. For example, the probability to develop symptoms when carrying the virus is the base probability from the ODE-SECIR model multiplied with the ``ReducInfectedSymptomsPartialImmunity`` parameter.
 
@@ -277,7 +277,8 @@ After setting the initial populations, you also need to set the vaccination para
             num_vaccinations;
     }
 
-.. _Nonpharmaceutical Interventions:
+.. _Nonpharmaceutical Interventions OSECIRVVS:
+
 Nonpharmaceutical Interventions
 -------------------------------
 
diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst
@@ -7,7 +7,7 @@ The model assumes perfect immunity after recovery
 
 The infection states and the transitions are visualized in the following graph.
 
-.. image:: https://martinkuehn.eu/research/images/ode_seirdb.png
+.. image:: https://martinkuehn.eu/research/images/seirdb.png
    :alt: SEIRDB_model
 
 
diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst
@@ -63,57 +63,57 @@ Parameters
 The model uses the following parameters (time unit: week):
 
 .. list-table::
-	 :header-rows: 1
-	 :widths: 20 25 55
-
-	 * - Mathematical Symbol
-		 - C++ Name / Type
-		 - Description
-	 * - :math:`R_e`
-		 - ``BaselineTransmissibility``
-		 - Baseline transmissibility (dimensionless); scales the normalized force of infection.
-	 * - :math:`T_E`
-		 - ``TimeExposed``
-		 - Mean time (weeks) in the exposed compartment; progression E -> I occurs with rate :math:`1/T_E`.
-	 * - :math:`T_I`
-		 - ``TimeInfected``
-		 - Mean infectious time (weeks); progression I -> R occurs with rate :math:`1/T_I` and the force of infection scales with :math:`1/T_I`.
-	 * - :math:`\delta`
-		 - ``SeasonalityAmplitude``
-		 - Amplitude of the seasonal modulation :math:`\exp(\delta\,\sin(2\pi(t/52 - t_z + t_s)))`.
-	 * - :math:`t_z`
-		 - ``SeasonalityShiftPerSubtype``
-		 - Coarse (subtype-specific) seasonal phase shift.
-	 * - :math:`t_s`
-		 - ``SeasonalityShiftPerSeason``
-		 - Fine seasonal phase adjustment per season.
-	 * - :math:`\lambda_0`
-		 - ``OutsideFoI``
-		 - External (additive) force of infection, can seed infections.
-	 * - :math:`\rho`
-		 - ``ClusteringExponent``
-		 - Clustering exponent on the infectious fraction.
-	 * - :math:`m`
-		 - ``SickMixing``
-		 - Mixing weight for symptomatic (“sick”) contacts in the blended contact matrix.
-	 * - :math:`C^{H}`
-		 - ``ContactPatternsHealthy``
-		 - Age-structured contact matrix (healthy). Can be time-dependent via damping.
-	 * - :math:`C^{S}`
-		 - ``ContactPatternsSick``
-		 - Age-structured contact matrix (symptomatic), combined using :math:`m`.
-	 * - :math:`\sigma_i`
-		 - ``CustomIndexArray``
-		 - Age-specific baseline susceptibility (pre-existing immunity modifier).
-	 * - :math:`VC_i`
-		 - ``VaccineCoverage``
-		 - Vaccination coverage per age group at season start (share vaccinated).
-	 * - :math:`VE_i`
-		 - ``VaccineEffectiveness``
-		 - Vaccine effectiveness (reducing effective susceptibility).
-	 * - :math:`\phi_0`
-		 - ``SusceptibleFraction``
-		 - Fraction of the total population forming the effectively susceptible pool at :math:`t_0`.
+    :header-rows: 1
+    :widths: 20 25 55
+
+    * - Mathematical Symbol
+      - C++ Name / Type
+      - Description
+    * - :math:`R_e`
+      - ``BaselineTransmissibility``
+      - Baseline transmissibility (dimensionless); scales the normalized force of infection.
+    * - :math:`T_E`
+      - ``TimeExposed``
+      - Mean time (weeks) in the exposed compartment; progression E -> I occurs with rate :math:`1/T_E`.
+    * - :math:`T_I`
+      - ``TimeInfected``
+      - Mean infectious time (weeks); progression I -> R occurs with rate :math:`1/T_I` and the force of infection scales with :math:`1/T_I`.
+    * - :math:`\delta`
+      - ``SeasonalityAmplitude``
+      - Amplitude of the seasonal modulation :math:`\exp(\delta\,\sin(2\pi(t/52 - t_z + t_s)))`.
+    * - :math:`t_z`
+      - ``SeasonalityShiftPerSubtype``
+      - Coarse (subtype-specific) seasonal phase shift.
+    * - :math:`t_s`
+      - ``SeasonalityShiftPerSeason``
+      - Fine seasonal phase adjustment per season.
+    * - :math:`\lambda_0`
+      - ``OutsideFoI``
+      - External (additive) force of infection, can seed infections.
+    * - :math:`\rho`
+      - ``ClusteringExponent``
+      - Clustering exponent on the infectious fraction.
+    * - :math:`m`
+      - ``SickMixing``
+      - Mixing weight for symptomatic (“sick”) contacts in the blended contact matrix.
+    * - :math:`C^{H}`
+      - ``ContactPatternsHealthy``
+      - Age-structured contact matrix (healthy). Can be time-dependent via damping.
+    * - :math:`C^{S}`
+      - ``ContactPatternsSick``
+      - Age-structured contact matrix (symptomatic), combined using :math:`m`.
+    * - :math:`\sigma_i`
+      - ``CustomIndexArray``
+      - Age-specific baseline susceptibility (pre-existing immunity modifier).
+    * - :math:`VC_i`
+      - ``VaccineCoverage``
+      - Vaccination coverage per age group at season start (share vaccinated).
+    * - :math:`VE_i`
+      - ``VaccineEffectiveness``
+      - Vaccine effectiveness (reducing effective susceptibility).
+    * - :math:`\phi_0`
+      - ``SusceptibleFraction``
+      - Fraction of the total population forming the effectively susceptible pool at :math:`t_0`.
 
 Note: ``VaccineCoverage`` and ``VaccineEffectiveness`` are only used for initialization. Transitions presently
 apply identical hazards to vaccinated and unvaccinated susceptible compartments. Future extensions may introduce
diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst
@@ -76,6 +76,7 @@ each **InfectionState** and sociodemographic group.
 
 
 .. _Nonpharmaceutical Interventions:
+
 Nonpharmaceutical interventions
 -------------------------------
 
@@ -143,6 +144,7 @@ List of models
     models/oseirdb
     models/oseair
     models/osecir
+    models/oseirv
     models/osecirvvs
     models/osecirts
     models/omseirs4
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -173,13 +173,23 @@ For experienced developers and C++ programmers, we offer the C++ backend to full
 
 Please see the full :doc:`C++ Build instructions <cpp/installation>` for more details and a list of compile options.
 
-1.  Run CMake. This tool *configures* the project for compilation on your specific system.
+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.
 
     .. code-block:: console
 
         cmake -S cpp -B cpp/build
 
-2.  Compile the code and create the executables. You can find them under *cpp/build/bin*.
+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):
+
+.. code-block:: bash
+
+   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.
 
     .. code-block:: console
 
diff --git a/docs/source/literature.rst b/docs/source/literature.rst
@@ -63,3 +63,7 @@
 .. |Coupled_Epidemiological_and_Wastewater| replace:: Bicker J, Tomza N, Wallrafen-Sam K, Schmid N, Hofmann A., et al. (2025). *Coupled Epidemiological and Wastwater Modeling at the Urban Scale: A Case Study for Munich*. medRxiv. |Coupled_Epidemiological_and_Wastewater_DOI|_
 .. |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
diff --git a/docs/source/python/coupling_sbi.rst b/docs/source/python/coupling_sbi.rst
@@ -7,6 +7,7 @@ Through pymio the data simulator can be incorporated into the learning process e
 and even further enable online training, i.e. generating training data on the spot during the learning phase.
 
 Most of the important includes for BayesFlow:
+
 .. code-block:: python
 
     import numpy as np
@@ -35,6 +36,7 @@ Most of the important includes for BayesFlow:
 
 
 Define the simulator function with the MEmilio python model. We will use a simple ODE SIR model for this example.
+
 .. code-block:: python
 
     import memilio.simulation as mio
@@ -117,8 +119,6 @@ Define the simulator function with the MEmilio python model. We will use a simpl
         I_data = np.clip(I_data, 10 ** -14, N)
         return dict(cases=np.stack((I_data, )).T)
 
-.. class:: details
-    test
 
 .. code-block:: python
 
@@ -155,6 +155,7 @@ Define the simulator function with the MEmilio python model. We will use a simpl
 
 
 Load data, first need to download them using epidata
+
 .. code-block:: python
     
     def load_observation_data(date_data_begin: datetime.date, T: int, data_path: str) -> np.ndarray:
diff --git a/docs/source/python/m-simulation_expanding_bindings.rst b/docs/source/python/m-simulation_expanding_bindings.rst
@@ -35,7 +35,7 @@ Adding a new model
 If currently a model is not available in the Python bindings or you added a new c++ model and want to bind it
 then the following steps should give an overview of what needs to be done:
 
-* Add new bindings including a model file in the `models <https://github.com/SciCompMod/memilio/blob/main/pycode/memilio-simulation/memilio/simulation/bindings/models/>`_folder that defines the new module.
+* Add new bindings including a model file in the `models <https://github.com/SciCompMod/memilio/blob/main/pycode/memilio-simulation/memilio/simulation/bindings/models/>`_ folder that defines the new module.
 * Add a Python module file similar to the other models, e.g., `osir.py <https://github.com/SciCompMod/memilio/blob/main/pycode/memilio-simulation/memilio/simulation/osir.py>`_ (needed for the structure of the Python package) and modify getter function in `__init__.py <https://github.com/SciCompMod/memilio/blob/main/pycode/memilio-simulation/memilio/simulation/__init__.py>`_.
 * Add the new module to the building process by modifying `CMakeLists.txt <https://github.com/SciCompMod/memilio/blob/main/pycode/memilio-simulation/CMakeLists.txt>`_.
 * Write new tests and examples.
diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst
diff --git a/docs/source/python/python_packages.rst b/docs/source/python/python_packages.rst
diff --git a/docs/source/references.rst b/docs/source/references.rst
diff --git a/docs/source/team.rst b/docs/source/team.rst
diff --git a/pycode/memilio-epidata/README.rst b/pycode/memilio-epidata/README.rst
