Updates and Fixes in the documentation #1481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

kilianvolmer wants to merge 32 commits into main from improve-the-documentation

CITATION.cff

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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."

README.md

-Original file line number
+Diff line change
@@ Expand Up @@
     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
@@ Expand Down @@

cpp/memilio/io/README.md

Large diffs are not rendered by default.

cpp/models/sde_seirvv/README.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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).

docs/Doxyfile

Large diffs are not rendered by default.

docs/source/cpp/graph_abm.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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

docs/source/cpp/graph_metapop.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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)

docs/source/cpp/models/osecirts.rst

-Original file line number
+Diff line change
@@ Expand Up @@
         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
     ----------
@@ Expand Down @@

docs/source/cpp/models/osecirvvs.rst

-Original file line number
+Diff line change
@@ -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 allowing 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.
@@ Expand Down Expand Up @@
                 num_vaccinations;
         }
-    .. _Nonpharmaceutical Interventions:
+    .. _Nonpharmaceutical Interventions OSECIRVVS:
     Nonpharmaceutical Interventions
     -------------------------------
@@ Expand Down @@

docs/source/cpp/models/oseirv.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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

docs/source/cpp/ode.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -76,6 +76,7 @@ each **InfectionState** and sociodemographic group. @@
     .. _Nonpharmaceutical Interventions:
     Nonpharmaceutical interventions
     -------------------------------
@@ Expand Down Expand Up / @@ -143,6 +144,7 @@ List of models @@
         models/oseirdb
         models/oseair
         models/osecir
+        models/oseirv
         models/osecirvvs
         models/osecirts
         models/omseirs4

docs/source/literature.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -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

docs/source/python/coupling_sbi.rst

-Original file line number
+Diff line change
@@ Expand Up @@
     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
@@ Expand Down Expand Up / @@ -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
@@ Expand Down Expand Up @@
             I_data = np.clip(I_data, 10 ** -14, N)
             return dict(cases=np.stack((I_data, )).T)
-    .. class:: details
-        test
     .. code-block:: python
@@ Expand Down Expand Up @@
     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:
@@ Expand Down @@

docs/source/python/m-simulation_expanding_bindings.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -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.
@@ Expand Down @@

docs/source/python/m-simulation_model_usage.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -108,7 +108,7 @@ Then, dampings can be added as a relative factor to (partially) reduce the conta
  
    .. code-block:: python

       model.parameters.ContactPatterns.cont_freq_mat.add_damping(

            Damping(coeffs=np.r_[0.9], t=30.0, level=0, type=0))

            mio.Damping(coeffs=np.r_[0.9], t=30.0, level=0, type=0))

    If a minimum pattern is set, the contact reduction will reduce the difference between the baseline and minimum patterns and subtract it from the baseline instead of only acting on the contact patterns baseline. That means that when the contact patterns are damped to 100%, the contact patterns will be equal to the minimum pattern instead of zero.

    @@ -217,7 +217,7 @@ Now, the infectious diesease dynamics can be simulated by calling ``simulate()``
  
    .. code-block:: python

       result = oseir.simulate(t0=0, tmax=60, dt=1, model)

       result = oseir.simulate(t0=0, tmax=60, dt=1, model=model)

    Similar to the MEmilio C++ library, the Python interface provides the option of adjusting the solver.

    Currently available are:

    @@ -231,7 +231,7 @@ The integrator can be changed as the last parameter of the simulate function.
  
    .. code-block:: python

       integrator = mio.RKIntegratorCore(dt_max=1)

       result = oseir.simulate(0, tmax=60, dt=1, model, integrator)

       result = oseir.simulate(0, tmax=60, dt=1, model = model, integrator = integrator)

    Output and visualization

    -------------------------

docs/source/python/python_packages.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -185,7 +185,3 @@ Run pylint with the commands in the package folder @@
     From the repository root you can also target a package explicitly, for example
     ``python pycode/run_pylint.py --package-dir memilio-plot``.
-    Pylint report for actual master:
-    `Pylint Report <https://dlr-sc.github.io/memilio/pylint/>`__

docs/source/references.rst

-Original file line number
+Diff line change
@@ Expand Up @@
     Recently submitted publications
     --------------------------------------
+    - |Missing_Transmission_Chains|
     - |Coupled_Epidemiological_and_Wastewater|
     - |Differentially_private_federated_learning|
@@ Expand Down @@

docs/source/team.rst

-Original file line number
+Diff line change
@@ Expand Up @@
        * |Agent-based_modeling_for|
        * |Integrating_Human_Mobility_Models|
+       * |Missing_Transmission_Chains|
     .. dropdown:: Links
        :animate: fade-in-slide-down
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates and Fixes in the documentation #1481

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Updates and Fixes in the documentation #1481

Are you sure you want to change the base?

Uh oh!

Updates and Fixes in the documentation #1481

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!