From aa795c305c490789046596ff534564f87339cf63 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:31:54 +0200 Subject: [PATCH 01/16] time series --- docs/source/cpp/diffusive_abm.rst | 4 ++-- docs/source/cpp/glct.rst | 2 +- docs/source/cpp/ide.rst | 10 +++++----- docs/source/cpp/lct_creation.rst | 4 ++-- docs/source/cpp/mobility_based_abm.rst | 2 +- docs/source/cpp/models/isecir.rst | 4 ++-- docs/source/cpp/models/iseir.rst | 2 +- docs/source/cpp/models/lsecir.rst | 2 +- docs/source/cpp/models/lsecir2d.rst | 2 +- docs/source/cpp/models/osecir.rst | 4 ++-- docs/source/cpp/models/osecirts.rst | 4 ++-- docs/source/cpp/models/osecirvvs.rst | 2 +- docs/source/cpp/models/oseir.rst | 2 +- docs/source/cpp/models/oseirdb.rst | 2 +- docs/source/python/m-simulation_expanding_bindings.rst | 4 ++-- docs/source/python/m-simulation_model_usage.rst | 4 ++-- 16 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index 57fb3a2471..cfd4b26d14 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -161,7 +161,7 @@ The model holds a vector containing all agents that can be accessed via sim.get_model().populations -Additionally, the agents are automatically aggregated by region and infection state in a ``mio::TimeSeries`` object which can be accessed and printed as follows: +Additionally, the agents are automatically aggregated by region and infection state in a :code:`mio::TimeSeries` object which can be accessed and printed as follows: .. code-block:: cpp @@ -171,7 +171,7 @@ Additionally, the agents are automatically aggregated by region and infection st //Print result object to console. Infection state "Xi" with i=0,...,3 is the number of agents having infection state X in region i result.print_table({"S0", "E0", "C0", "I0", "R0", "D0", "S1", "E1", "C1", "I1", "R1", "D1", "S2", "E2", "C2", "I2", "R2", "D2", "S3", "E3", "C3", "I3", "R3", "D3"}) -If one wants to interpolate the aggregated results to a ``mio::TimeSeries`` containing only full days, this can be done by +If one wants to interpolate the aggregated results to a :code:`mio::TimeSeries` containing only full days, this can be done by .. code-block:: cpp diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 05e6ef7c34..858d29d259 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -85,7 +85,7 @@ You can run a simulation using either fixed or adaptive integration schemes with Output ------ -The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each subcompartment at each time point. +The output of the **Simulation** is a :code:`mio::TimeSeries` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/ide.rst b/docs/source/cpp/ide.rst index e09b0d06d0..c220bf5b17 100644 --- a/docs/source/cpp/ide.rst +++ b/docs/source/cpp/ide.rst @@ -74,10 +74,10 @@ Parameters can get accessed via ``model.parameters.get>()`` an Initial conditions ------------------ -The initial conditions consist of a **TimeSeries** that contains the flows per time step for some time interval before +The initial conditions consist of a time series that contains the flows per time step for some time interval before the simulation start. The length of this time interval depends on the chosen transition distributions and takes into account how long there is a relevant fraction of individuals remaining in the compartments. For more information, see -the documentation of **StateAgeFunction**. Note that the last time point of the initial **TimeSeries** determines the +the documentation of ``StateAgeFunction``. Note that the last time point of the initial time series determines the start time of the simulation. @@ -117,9 +117,9 @@ uses a nonstandard numerical scheme to solve the IDEs that is implemented in MEm Output ------ -The output of the **Simulation** ``sim`` is a ``TimeSeries`` containing the sizes of each compartment at each time point -and a ``TimeSeries`` containing the flows within a time step for each time point. A simple table can be printed using the -``print_table()`` function of the ``TimeSeries`` class. The compartment sizes can be printed with +The output of the simulation ``sim`` is a :code:`mio::TimeSeries` containing the sizes of each compartment at each time point +and a :code:`mio::TimeSeries` containing the flows within a time step for each time point. A simple table can be printed using the +``print_table()`` function of the :code:`mio::TimeSeries` class. The compartment sizes can be printed with ``sim.get_result().print_table()`` and the flows with ``sim.get_transitions().print_table()``. As the time step may be small it may be useful to obtain outputs on days or user-defined time points. You can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``. diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index 5a9a0f0f17..18bea1cf93 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -177,8 +177,8 @@ The function ``get_derivatives()`` evaluates the right-hand-side of the ODE :mat It is also useful to implement the following methods within the model: -- A function ``calculate_compartments()`` that accumulates the TimeSeries containing simulation results that are divided -into subcompartments to a TimeSeries that conatins the simulation results according to the infection states without subcompartments. +- A function ``calculate_compartments()`` that accumulates the :code:`TimeSeries` containing simulation results that are divided +into subcompartments to a :code:`TimeSeries` that conatins the simulation results according to the infection states without subcompartments. For an example, see the implementation within the LCT-SECIR model. - A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. For an example, see the implementation within the LCT-SECIR model. diff --git a/docs/source/cpp/mobility_based_abm.rst b/docs/source/cpp/mobility_based_abm.rst index 090c0fd8bb..b5ab66c01a 100644 --- a/docs/source/cpp/mobility_based_abm.rst +++ b/docs/source/cpp/mobility_based_abm.rst @@ -326,7 +326,7 @@ Here, we run the simulation: sim.advance(tmax); Alternatively, if we want to track things in the simulation, we need to set up a -`history `_, for example, to track all the Infection states of each simulation step into a Timeseries. +`history `_, for example, to track all the Infection states of each simulation step into a :code:`Timeseries`. .. code-block:: cpp diff --git a/docs/source/cpp/models/isecir.rst b/docs/source/cpp/models/isecir.rst index 9df8194094..d921424a0a 100644 --- a/docs/source/cpp/models/isecir.rst +++ b/docs/source/cpp/models/isecir.rst @@ -305,7 +305,7 @@ until :math:`t_{\max}`, which is done as follows. Output ------ -The output of the simulation are two `TimeSeries` objects, one containing the size of the compartments at all time +The output of the simulation are two :code:`TimeSeries` objects, one containing the size of the compartments at all time points and one containing the number of transitions within a time step. You can access the results as follows: .. code-block:: cpp @@ -318,7 +318,7 @@ points and one containing the number of transitions within a time step. You can The order of the compartments and transitions follows the definition in the **InfectionState** and **InfectionTransition** enums, respectively. -You can access the data in the `TimeSeries` objects as follows: +You can access the data in the :code:`TimeSeries` objects as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index d1b6714848..1f918049c6 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -125,7 +125,7 @@ The values of the remaining compartments :math:`E`, :math:`I` and :math:`R` are Output ------ -The output of the simulationis a `TimeSeries` object containing the size of the compartments at all time +The output of the simulationis a :code:`TimeSeries` object containing the size of the compartments at all time points. You can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 3ccbc98152..20cf643951 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -307,7 +307,7 @@ The simulation result is stratefied by subcompartments. The function ``calculate mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the `mio::TimeSeries` object as follows: +You can access the data in the :code:`mio::TimeSeries` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index ad96e8cda6..4991a7324a 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -408,7 +408,7 @@ The simulation result is stratefied by subcompartments. The function ``calculate mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the `mio::TimeSeries` object as follows: +You can access the data in the :code:`mio::TimeSeries` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 50f651c698..27e8f35bfe 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -320,7 +320,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a `TimeSeries` object containing the sizes of each compartment at each time point. For a basic simulation, you can access the results as follows: +The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a basic simulation, you can access the results as follows: .. code-block:: cpp @@ -335,7 +335,7 @@ The output of the simulation is a `TimeSeries` object containing the sizes of ea Eigen::VectorXd last_value = secir.get_last_value(); double last_time = secir.get_last_time(); -For flow simulations, the result consists of two `mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index d8fec1bfec..4aee07d2e2 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -363,7 +363,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a `mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a :code:`mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp @@ -406,4 +406,4 @@ To get started with the ODE-SECIRTS model, check out the code example in the MEm `examples/ode_secirts.cpp `_. -The code documentation for the model can be found at :CPP-API:`mio::osecirts` . \ No newline at end of file +The code documentation for the model can be found at :CPP-API:`mio::osecirts` . diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index 6733210fe8..59555d8280 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -377,7 +377,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a `mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a :code:`mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index a22075ea7d..b399540681 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -206,7 +206,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two `mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index 809dbda49c..f0ba5c71af 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -215,7 +215,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two `mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/python/m-simulation_expanding_bindings.rst b/docs/source/python/m-simulation_expanding_bindings.rst index 6a6f8f8191..4e28d01d7d 100755 --- a/docs/source/python/m-simulation_expanding_bindings.rst +++ b/docs/source/python/m-simulation_expanding_bindings.rst @@ -16,7 +16,7 @@ For a deeper look at common patterns you may encounter with the C++ MEmilio libr Expanding the simulation packages --------------------------------- -All bindings are located inside the folder `bindings `_. The simulation package is defined over modules. A main module `memilio.simulation` contains the general functionalities of the MEmilio library like the TimeSeries class, different integrators, dampings or IO functions. +All bindings are located inside the folder `bindings `_. The simulation package is defined over modules. A main module `memilio.simulation` contains the general functionalities of the MEmilio library like the :code:`TimeSeries` class, different integrators, dampings or IO functions. Additionally, each model is located into its own submodule, where model specific bindings are written. Python doesn't provide an interface for templates. Therefore, templated functions or classes need to be defined explicitly for each template argument that should be usable. @@ -41,4 +41,4 @@ then the following steps should give an overview of what needs to be done: * Write new tests and examples. * (Add the package to the documentation and stubs generation.) -MEmilio also provides the package :doc:`memilio-generation ` for automatic generation of model specific Python bindings. \ No newline at end of file +MEmilio also provides the package :doc:`memilio-generation ` for automatic generation of model specific Python bindings. diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index 885f66600a..ad10e7ec92 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -236,8 +236,8 @@ The integrator can be changed as the last parameter of the simulate function. Output and visualization ------------------------- -The result returned from the simulation is a TimeSeries object containing the number of people per age group in each infection state at each time step. -The TimeSeries provides alot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more +The result returned from the simulation is a :code:`TimeSeries` object containing the number of people per age group in each infection state at each time step. +The :code:`TimeSeries` provides alot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more pythonic interface. .. code-block:: python From 7c1465f54addf38349f7b6d928d11131b51d7679 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:35:38 +0200 Subject: [PATCH 02/16] CompartmentalModel --- docs/source/cpp/glct.rst | 2 +- docs/source/cpp/lct.rst | 2 +- docs/source/cpp/lct_creation.rst | 2 +- docs/source/cpp/models/omseirs4.rst | 2 +- docs/source/cpp/models/osir.rst | 2 +- docs/source/cpp/ode.rst | 6 +++--- docs/source/cpp/ode_creation.rst | 8 ++++---- docs/source/cpp/sde.rst | 4 ++-- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 858d29d259..cd784efc82 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -27,7 +27,7 @@ parameter to the model. using LctStateGroup1 = mio::LctInfectionState; -The model is implemented as **CompartmentalModel**. +The model is implemented as :code:`CompartmentalModel`. Parameters diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index c13d3fbf7f..3d8d55c38d 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -29,7 +29,7 @@ parameter to the model. `Number of subcompartments of State2`, `...`>; -The model is implemented as **CompartmentalModel**. +The model is implemented as :code:`CompartmentalModel`. diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index 18bea1cf93..b056e00425 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -119,7 +119,7 @@ example being adding age groups. Define the model ^^^^^^^^^^^^^^^^ -Now we can define the model as a **CompartmentalModel** in the file "model.h": +Now we can define the model as a :code:`CompartmentalModel` in the file "model.h": .. code-block:: cpp diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 17b7cb216a..2be495e5ee 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -39,7 +39,7 @@ All infectious classes (I1..I4) contribute equally to transmission in the basic Infection State Transitions --------------------------- -The model is implemented as a **CompartmentalModel**, which defines the derivative of the aggregated compartment +The model is implemented as a :code:`CompartmentalModel`, which defines the derivative of the aggregated compartment values in time. The following transitions occur: - Births enter M and some enter S1 diff --git a/docs/source/cpp/models/osir.rst b/docs/source/cpp/models/osir.rst index c7d0ce4614..4bced9aa77 100644 --- a/docs/source/cpp/models/osir.rst +++ b/docs/source/cpp/models/osir.rst @@ -35,7 +35,7 @@ The model contains the following list of **InfectionState**\s: Infection State transitions --------------------------- -The ODE-SIR model is implemented as a **CompartmentalModel**, which defines the derivative of the aggregated compartment +The ODE-SIR model is implemented as a :code:`CompartmentalModel`, which defines the derivative of the aggregated compartment values in time. diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 07ad5fb76d..599308537e 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -28,11 +28,11 @@ Every model contains a list of **InfectionState**\s that define particular featu Infection state transitions --------------------------- -Our ODE-based models are either implemented as **FlowModel** or as **CompartmentalModel**. In a **FlowModel**, flows -``Flow`` between **InfectionState**\s **State1** and **State2** are defined. Instead of a standard +Our ODE-based models are either implemented as :code:`FlowModel` or as :code:`CompartmentalModel`. In a :code:`FlowModel`, flows +``Flow`` between :code:`InfectionState`\s **State1** and **State2** are defined. Instead of a standard solution of an ODE-based model, this implementation additionally realizes the solution of the transitions or flows between states and directly enables users to access new transmissions or hospitalizations at any time point. -The simpler class **CompartmentalModel** only considers the states of the system and not the flows. +The simpler class :code:`CompartmentalModel` only considers the states of the system and not the flows. Sociodemographic stratification diff --git a/docs/source/cpp/ode_creation.rst b/docs/source/cpp/ode_creation.rst index e8f305e65f..b7666509ea 100644 --- a/docs/source/cpp/ode_creation.rst +++ b/docs/source/cpp/ode_creation.rst @@ -24,9 +24,9 @@ states **S**\usceptible, **I**\nfectious, **R**\ecovered, **D**\eceased, also ca How to implement an ODE model ----------------------------- -To define an ODE model in MEmilio, there are two options. You can define a CompartmentalModel or a FlowModel, which +To define an ODE model in MEmilio, there are two options. You can define a :code:`CompartmentalModel` or a :code:`FlowModel`, which use different methods to define the right-hand side of the mathematical model above. Both classes need definitions for -the infection states, population and parameters it uses. The FlowModel additionally requires a list of flows. +the infection states, population and parameters it uses. The :code:`FlowModel` additionally requires a list of flows. We start by creating a new directory for our model under "cpp/models", in this case we can call it "ode_sird". The name must be unique and start with "ode\_", so the type of model is obvious. The rest usually contains the compartments or @@ -162,8 +162,8 @@ 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 CompartmentalModel class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Define a :code:`CompartmentalModel` class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now we can define the model: diff --git a/docs/source/cpp/sde.rst b/docs/source/cpp/sde.rst index 65bccb9872..9770ef087b 100644 --- a/docs/source/cpp/sde.rst +++ b/docs/source/cpp/sde.rst @@ -7,8 +7,8 @@ additional function to compute the random noise, as can be seen :doc:`here `. -The class used for implementing SDE models is called **StochasticModel**. It is derived from a **CompartmentalModel** -(or optionally a **FlowModel**) for the representation of the deterministic part of the model equations. Check out +The class used for implementing SDE models is called **StochasticModel**. It is derived from a :code:`CompartmentalModel` +(or optionally a :code:`FlowModel`) for the representation of the deterministic part of the model equations. Check out :doc:`SDE model creation ` for more details. .. _Simulation SDE: From 50004e2bb54695822a0d4b150661f17ca7dd27ec Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:37:07 +0200 Subject: [PATCH 03/16] InfectionStates --- docs/source/cpp/models/omseirs4.rst | 2 +- docs/source/getting_started.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 2be495e5ee..38cb173e86 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -17,7 +17,7 @@ This implementation is designed for Respiratory Syncytial Virus (RSV) and is bas Infection States ---------------- -The model contains the following InfectionStates: +The model contains the following :code:`InfectionStates`: - `MaternalImmune` (M) - `S1`, `S2`, `S3`, `S4` (susceptible classes by infection history) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 1031123289..efac8673ec 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -71,7 +71,7 @@ An additional overview on MEmilio's elementary model structure is given by the f :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. +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 :code:`InfectionStates`. For :code:`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. From 911c2d74aa52c31e37ff25385e384b5914542262 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:39:51 +0200 Subject: [PATCH 04/16] FlowModel --- docs/source/cpp/models/osecir.rst | 2 +- docs/source/cpp/models/osecirts.rst | 2 +- docs/source/cpp/models/osecirvvs.rst | 2 +- docs/source/cpp/models/oseir.rst | 2 +- docs/source/cpp/models/oseirdb.rst | 2 +- docs/source/cpp/models/oseirv.rst | 2 +- docs/source/cpp/ode.rst | 4 ++-- docs/source/cpp/sde.rst | 4 ++-- docs/source/python/m-simulation_model_usage.rst | 2 +- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 27e8f35bfe..82910f1a70 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -40,7 +40,7 @@ current implementation and detection is only modeled implicitly through detectio Infection State Transitions --------------------------- -The ODE-SECIR model is implemented as a **FlowModel**, which defines the derivatives of each flow between compartments. +The ODE-SECIR model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, and hospitalizations. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 4aee07d2e2..f99324ff08 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -66,7 +66,7 @@ The model extends the ODE-SECIRVVS model by adding temporary immunity states and Infection State Transitions --------------------------- -The ODE-SECIRTS model is implemented as a **FlowModel**, which defines the derivatives of each flow between compartments. A key difference from the ODE-SECIRVVS model is that vaccinations in the ODE-SECIRTS model are implemented as flows within the ODE system rather than discrete events. +The ODE-SECIRTS model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. A key difference from the ODE-SECIRVVS model is that vaccinations in the ODE-SECIRTS model are implemented as flows within the ODE system rather than discrete events. The model has the following state trnsitions: diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index 59555d8280..ab829b9f9b 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -57,7 +57,7 @@ All compartments with the same base state (e.g., ExposedNaive, ExposedPartialImm Infection State Transitions --------------------------- -The ODE-SECIRVVS model is implemented as a **FlowModel**, which defines the derivatives of each flow between compartments. The model follows the same flow pattern as the basic ODE-SECIR model but with three parallel sets of compartments representing different immunity levels. +The ODE-SECIRVVS model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. The model follows the same flow pattern as the basic ODE-SECIR model but with three parallel sets of compartments representing different immunity levels. The key characteristic of this model is that recovered individuals always end up in the improved immunity level, regardless of their starting immunity level. This represents the immunity gained after infection. diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index b399540681..2e98413941 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -33,7 +33,7 @@ The model contains the following list of **InfectionState**\s: Infection State Transitions --------------------------- -The ODE-SEIR model is implemented as a **FlowModel**, which defines the derivatives of each flow between compartments. +The ODE-SEIR model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, and recoveries. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index f0ba5c71af..485130551f 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -28,7 +28,7 @@ The model contains the following list of **InfectionState**\s: Infection State Transitions --------------------------- -The ODE-SEIRDB model is implemented as a **FlowModel**, which defines the derivatives of each flow between compartments. +The ODE-SEIRDB model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, recoveries, deaths, and burials. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index b0bff91a3b..47b5f64767 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -31,7 +31,7 @@ The model contains the following **InfectionState**\s: Infection State Transitions --------------------------- -The SEIRV model is implemented as a **FlowModel**. Thus, in each time step, the flows (new infections, progressions, +The SEIRV model is implemented as a :code:`FlowModel`. Thus, in each time step, the flows (new infections, progressions, recoveries) are computed explicitly in addition to compartment values. The defined transitions `FromState, ToState` are: .. code-block:: RST diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 599308537e..da217b879c 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -105,8 +105,8 @@ Simulation ---------- Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with an initial step size ``dt`` using the -``mio::simulate()`` function. This will run a simulation of type **Simulation** that saves the sizes of each compartment over time. -To also save the flow information, make sure to use a **FlowModel** and run a simulation of type **FlowSimulation** with the ``mio::simulate_flows()`` function. +``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each compartment over time. +To also save the flow information, make sure to use a :code:`FlowModel` and run a simulation of type :code:`FlowSimulation` with the ``mio::simulate_flows()`` function. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive integration scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. diff --git a/docs/source/cpp/sde.rst b/docs/source/cpp/sde.rst index 9770ef087b..fbca03c3d8 100644 --- a/docs/source/cpp/sde.rst +++ b/docs/source/cpp/sde.rst @@ -16,11 +16,11 @@ Simulation ---------- Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with an initial step size ``dt`` -using the ``mio::simulate_stochastic()`` function. This will run a simulation of type **StochasticSimulation** that +using the ``mio::simulate_stochastic()`` function. This will run a simulation of type :code:`StochasticSimulation` that saves the sizes of each compartment over time. The simulation uses an Euler-Maruyama scheme by default, so the step size does not change over time. -Flow information cannot be obtained even when the **StochasticModel** is defined using a **FlowModel**, as the +Flow information cannot be obtained even when the :code:`StochasticModel` is defined using a :code:`FlowModel`, as the integrator may need to rescale results with respect to compartments to avoid negative values. List of models diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index ad10e7ec92..dde8118089 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -251,7 +251,7 @@ Additional resources --------------------- Further examples are provided at `examples/simulation `_. -They include the usage of a FlowModel, introducing a graph model for regional differences or parameter studies for simulating under uncertainty. +They include the usage of a :code:`FlowModel`, introducing a graph model for regional differences or parameter studies for simulating under uncertainty. From 5ff1d8a0bd740e5b98e0271abd91fbde4c1adf2d Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 10:16:13 +0200 Subject: [PATCH 05/16] misc --- docs/source/cpp/diffusive_abm.rst | 6 ++--- docs/source/cpp/glct.rst | 18 +++++++------- docs/source/cpp/ide.rst | 19 +++++++-------- docs/source/cpp/lct.rst | 20 ++++++++-------- docs/source/cpp/models/glsecir.rst | 2 +- docs/source/cpp/models/isecir.rst | 10 ++++---- docs/source/cpp/models/iseir.rst | 2 +- docs/source/cpp/models/lsecir.rst | 2 +- docs/source/cpp/models/lsecir2d.rst | 2 +- docs/source/cpp/models/osecir.rst | 8 +++---- docs/source/cpp/models/osecirts.rst | 6 ++--- docs/source/cpp/models/osecirvvs.rst | 8 +++---- docs/source/cpp/models/oseir.rst | 10 ++++---- docs/source/cpp/models/oseirdb.rst | 10 ++++---- docs/source/cpp/models/oseirv.rst | 6 ++--- docs/source/cpp/models/osir.rst | 8 +++---- docs/source/cpp/ode.rst | 24 +++++++++---------- docs/source/cpp/sbml.rst | 2 +- docs/source/cpp/sde.rst | 2 +- docs/source/cpp/smm.rst | 4 ++-- .../python/m-simulation_model_usage.rst | 2 +- 21 files changed, 85 insertions(+), 86 deletions(-) diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index cfd4b26d14..fff666f55f 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -10,7 +10,7 @@ The features of an agent are its position and its infection state. The evolution with :math:`X` the vector of all agents' positions and :math:`Z` the vector of all agents' infection states. The operator :math:`G` defines the infection state adoptions and only acts on :math:`Z`, while :math:`L` defines movement, i.e. location changes, only acting on :math:`X`. Infection state adoptions are modeled with independent Poisson processes given by adoption rate functions. Movement is modeled with independent diffusion processes. A temporal Gillespie algorithm (a direct method without rejection sampling) is used for simulation. Therefore, :math:`G` and :math:`L` are not implemented explicitly, instead their effects are sampled via the `move` and `adoption_rate` functions, respectively. -The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes **QuadWell** and **SingleWell** respectively are implemented, but any other suitable potential can be used as implementation. +The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes :code:`QuadWell` and :code:`SingleWell` respectively are implemented, but any other suitable potential can be used as implementation. In the following, we present more details of the diffusive agent-based model, including code examples. An overview of nonstandard but often used data types can be found under :doc:`data_types`. @@ -40,7 +40,7 @@ Using the infection states Susceptible (S), Exposed (E), Carrier (C), Infected ( Infection state transitions --------------------------- -The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the **Influence**\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior. +The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the :code:`Influence`\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior. Using the infection states from above and only one region, there are five first-order and one second-order adoption rate that can be set via: @@ -134,7 +134,7 @@ Simulation The simulation runs in discrete time steps. In every step the model is advanced until the next infection state adoption event. Then the corresponding agent's infection state is adopted and a new waiting time until the next adoption event is drawn. If the waiting time until the next adoption event is bigger than the remaining time in the time step, we advance the model until the end of the time step. -To simulate the model from `t0` to `tmax` with given step size `dt`, a **Simulation** has to be created and advanced until `tmax`, which is done as follows: +To simulate the model from `t0` to `tmax` with given step size `dt`, a :code:`Simulation` has to be created and advanced until `tmax`, which is done as follows: .. code-block:: cpp diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index cd784efc82..1e8d95846b 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -11,7 +11,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -The model contains a list of **InfectionState**\s that define particular features of the subpopulations in the particular state. +The model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -19,8 +19,8 @@ The model contains a list of **InfectionState**\s that define particular feature `State2` `...` -To make use of the GLCT, we additionally need to define the numbers of subcompartments for each **InfectionState**. -This is done by creating an **LctInfectionState** object for each group. These objects are then passed as template +To make use of the GLCT, we additionally need to define the numbers of subcompartments for each :code:`InfectionState`. +This is done by creating an :code:`LctInfectionState` object for each group. These objects are then passed as template parameter to the model. .. code-block:: cpp @@ -38,10 +38,10 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, -we use a parameter denoted **ContactPatterns** of type **UncertainContactMatrix**. The **UncertainContactMatrix** contains an +we use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains an arbitrary large set of contact matrices which can e.g. represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the **ContactPatterns**, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization and it is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions GLCT`. @@ -52,14 +52,14 @@ Parameters can be accessed via ``model.parameters.get>()`` and set Initial conditions ------------------ -The initial conditions of the model are represented by a class **LctPopulations** that gives the number of individuals in each sociodemographic group and each subcompartment of each **InfectionState**. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each **InfectionState** and sociodemographic group must be set. +The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment of each :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each :code:`InfectionState` and sociodemographic group must be set. .. _Nonpharmaceutical Interventions GLCT: Nonpharmaceutical interventions ------------------------------- -Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding **Damping**\s to the **ContactPatterns** of the model. A **Damping** is defined by a time point at which the intervention starts and a matrix of the same size as the **ContactMatrix**. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. +Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A :code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the :code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. .. dropdown:: :fa:`gears` Expert's settings @@ -78,14 +78,14 @@ Contact rates can be adjusted during the simulation to model nonpharmaceutical i Simulation ---------- -Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type **Simulation** that saves the sizes of each subcompartment over time. +Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each subcompartment over time. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive solution scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. For more details on the possible integration schemes, see . Output ------ -The output of the **Simulation** is a :code:`mio::TimeSeries` containing the sizes of each subcompartment at each time point. +The output of the :code:`Simulation` is a :code:`mio::TimeSeries` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/ide.rst b/docs/source/cpp/ide.rst index c220bf5b17..4ad3f6869f 100644 --- a/docs/source/cpp/ide.rst +++ b/docs/source/cpp/ide.rst @@ -15,7 +15,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -Every model contains a list of **InfectionState**\s that define particular features of the subpopulations in the particular state. +Every model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -27,8 +27,8 @@ Every model contains a list of **InfectionState**\s that define particular featu Infection state transitions --------------------------- -Additionally, we define **InfectionTransition**\s that define the possible transitions between the **InfectionState**\s. -When solving the model, we obtain results for the **InfectionTransition**\s as well. +Additionally, we define :code:`InfectionTransition`\s that define the possible transitions between the :code:`InfectionState`\s. +When solving the model, we obtain results for the :code:`InfectionTransition`\s as well. .. code-block:: RST @@ -40,8 +40,7 @@ When solving the model, we obtain results for the **InfectionTransition**\s as w Sociodemographic stratification ------------------------------- -For the IDE-SECIR model, the population can also be stratified by one sociodemographic dimension. This dimension is denoted -**AgeGroup** but can also be used for other interpretations. +For the IDE-SECIR model, the population can also be stratified by one sociodemographic dimension. This dimension is denoted :code:`AgeGroup` but can also be used for other interpretations. Parameters ---------- @@ -51,11 +50,11 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different sociodemographic groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each group. To model different contact rates between different sociodemographic groups, we -use a parameter denoted **ContactPatterns** of type **UncertainContactMatrix**. The **UncertainContactMatrix** contains an +use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the **ContactPatterns**, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` and group :math:`j`. The dimension of the matrix is automatically defined by the model initiation and it is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions IDE`. @@ -86,9 +85,9 @@ Nonpharmaceutical interventions ------------------------------- Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, -school closures, or social distancing. This is done by adding **Damping**\s to the **ContactPatterns** of the model. A -**Damping** is defined by a time point at which the intervention starts and a matrix of the same size as the -**ContactMatrix**. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also +school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A +:code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the +:code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index 3d8d55c38d..afba95a756 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -11,7 +11,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -The model contains a list of **InfectionState**\s that define particular features of the subpopulations in the particular state. +The model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -19,8 +19,8 @@ The model contains a list of **InfectionState**\s that define particular feature `State2` `...` -To make use of the LCT, we additionally need to define the numbers of subcompartments for each **InfectionState**. -This is done by creating an **LctInfectionState** object for each group. These objects are then passed as template +To make use of the LCT, we additionally need to define the numbers of subcompartments for each :code:`InfectionState`. +This is done by creating an :code:`LctInfectionState` object for each group. These objects are then passed as template parameter to the model. .. code-block:: cpp @@ -47,10 +47,10 @@ The parameters of the model are defined as structs and are combined in a class ` We use different types of parameters to represent epidemiological parameters such as the mean stay times in a compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. -To model different contact rates between different sociodemographic groups, we use a parameter denoted **ContactPatterns** of type **UncertainContactMatrix**. -The **UncertainContactMatrix** contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like +To model different contact rates between different sociodemographic groups, we use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. +The :code:`UncertainContactMatrix` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the **ContactPatterns**, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. +In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization and is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions LCT`. @@ -61,14 +61,14 @@ Parameters can be accessed via ``model.parameters.get>()`` and set Initial conditions ------------------ -The initial conditions of the model are represented by a class **LctPopulations** that gives the number of individuals in each sociodemographic group and each subcompartment for each **InfectionState**. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each **InfectionState** and sociodemographic group must be set. +The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment for each :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each :code:`InfectionState` and sociodemographic group must be set. .. _Nonpharmaceutical Interventions LCT: Nonpharmaceutical interventions ------------------------------- -Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding **Damping**\s to the **ContactPatterns** of the model. A **Damping** is defined by a time point at which the intervention starts and a matrix of the same size as the **ContactMatrix**. +Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A :code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the :code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. @@ -90,14 +90,14 @@ reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. Simulation ---------- -Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type **Simulation** that saves the sizes of each subcompartment over time. +Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each subcompartment over time. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive solution scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. For more details on the possible integration schemes, see . Output ------ -The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each subcompartment at each time point. +The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index f7a1072fa8..2148d96db3 100644 --- a/docs/source/cpp/models/glsecir.rst +++ b/docs/source/cpp/models/glsecir.rst @@ -17,7 +17,7 @@ For the concept see: Infection States ---------------- -The model contains the following list of **InfectionState**\s: +The model contains the following list of :code:`InfectionState`\s: .. code-block:: RST diff --git a/docs/source/cpp/models/isecir.rst b/docs/source/cpp/models/isecir.rst index d921424a0a..b8b1ab4e4c 100644 --- a/docs/source/cpp/models/isecir.rst +++ b/docs/source/cpp/models/isecir.rst @@ -26,7 +26,7 @@ A detailed investigation of the IDE-SECIR model and numerical experiments can be Infection States ---------------- -The model contains the following list of **InfectionState**\s: +The model contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -42,7 +42,7 @@ The model contains the following list of **InfectionState**\s: Infection State Transitions --------------------------- -The possible transitions between the **InfectionState**\s are: +The possible transitions between the :code:`InfectionState`\s are: .. code-block:: RST @@ -62,7 +62,7 @@ Sociodemographic Stratification ------------------------------- In the IDE-SECIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -**AgeGroup** but can also be used for other interpretations. +:code:`AgeGroup` but can also be used for other interpretations. Parameters @@ -291,7 +291,7 @@ Before the simulation, we check if all constraints of the model are satisfied so model.check_constraints(dt); To simulate the model from :math:`t_0` (that is determined by the initial flows provided to the constructor) to -:math:`t_{\max}` with given step size :math:`dt`, a object of the **Simulation** class has to be created and advanced +:math:`t_{\max}` with given step size :math:`dt`, a object of the :code:`Simulation` class has to be created and advanced until :math:`t_{\max}`, which is done as follows. .. code-block:: cpp @@ -316,7 +316,7 @@ points and one containing the number of transitions within a time step. You can // Access transitions between compartments. auto transitions = sim.get_transitions(); -The order of the compartments and transitions follows the definition in the **InfectionState** and **InfectionTransition** enums, respectively. +The order of the compartments and transitions follows the definition in the :code:`InfectionState` and :code:`InfectionTransition` enums, respectively. You can access the data in the :code:`TimeSeries` objects as follows: diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index 1f918049c6..f6c244f895 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -19,7 +19,7 @@ Bachelor's thesis, University of Cologne. `https://elib.dlr.de/143504/ `. @@ -137,7 +137,7 @@ The model implements the following parameters: Initial conditions ------------------ -The initial conditions of the model are represented by the class **Populations** which defines the number of individuals in each sociodemographic group and **InfectionState**. Before running a simulation, you need to set the initial values for each compartment: +The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -259,7 +259,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d contact_dampings.push_back(social_events(start_lockdown, 0.6, 0.8)); contact_dampings.push_back(physical_distancing(start_lockdown, 0.4, 0.6)); -A more advanced structure to automatically activate interventions based on threshold criteria is given by **DynamicNPIs**. +A more advanced structure to automatically activate interventions based on threshold criteria is given by :code:`DynamicNPIs`. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get activated for a defined duration when the threshold is exceeded. As above, different dampings `contact_dampings` can be assigned to different contact locations diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index f99324ff08..63176b83fa 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -20,7 +20,7 @@ Below is an overview of the model architecture and its compartments. Infection States ---------------- -The model extends the ODE-SECIRVVS model by adding temporary immunity states and flow paths for waning immunity. It contains the following list of **InfectionState**\s: +The model extends the ODE-SECIRVVS model by adding temporary immunity states and flow paths for waning immunity. It contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -115,7 +115,7 @@ Sociodemographic Stratification ------------------------------- Like the other ODE-SECIR models, the ODE-SECIRTS model can be stratified by one sociodemographic dimension, typically age groups. This stratification is important for modeling different vaccination rates, symptom severities, mortality risks, and immunity waning rates across age groups. The dimension is denoted -**AgeGroup** but can also be used for other interpretations. +:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. Parameters @@ -234,7 +234,7 @@ The model includes all parameters from the ODE-SECIRVVS model as well as additio Initial conditions ------------------ -The initial conditions of the model are represented by the class **Populations** which defines the number of individuals in each sociodemographic group and **InfectionState**. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: +The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index ab829b9f9b..7fd1aeb7d5 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -15,7 +15,7 @@ Below is an overview of the model architecture and its compartments. Infection States ---------------- -The model extends the basic ODE-SECIR model by dividing the compartments based on immunity levels. It contains the following list of **InfectionState**\s: +The model extends the basic ODE-SECIR model by dividing the compartments based on immunity levels. It contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -83,13 +83,13 @@ For each immunity level (Naive, PartialImmunity, ImprovedImmunity), the followin Where * stands for the immunity level suffix (Naive, PartialImmunity, or ImprovedImmunity). -**Important:** Vaccinations are not implemented as flows between compartments but are handled discretely by the simulation. At the beginning of each simulated day, susceptible individuals are moved between immunity levels according to the specified daily vaccination parameters. This discrete process is separate from the ODE system and is managed by the `apply_vaccination` function in the model specific **Simulation** class. +**Important:** Vaccinations are not implemented as flows between compartments but are handled discretely by the simulation. At the beginning of each simulated day, susceptible individuals are moved between immunity levels according to the specified daily vaccination parameters. This discrete process is separate from the ODE system and is managed by the `apply_vaccination` function in the model specific :code:`Simulation` class. Sociodemographic Stratification ------------------------------- Like the basic ODE-SECIR model, the ODE-SECIRVVS model can be stratified by one sociodemographic dimension, typically age groups. This stratification is important for modeling different vaccination rates, symptom severities, and mortality risks across age groups. The dimension is denoted -**AgeGroup** but can also be used for other interpretations. +:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. Parameters @@ -220,7 +220,7 @@ The model includes all parameters from the basic ODE-SECIR model plus additional Initial conditions ------------------ -The initial conditions of the model are represented by the class **Populations** which defines the number of individuals in each sociodemographic group and **InfectionState**. Before running a simulation, you should set the initial values for each compartment across all immunity levels. +The initial conditions of the model are represented by the class **Populations** which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you should set the initial values for each compartment across all immunity levels. Below is an example showing how to initialize all compartments for the ODE-SECIRVVS model: diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index 2e98413941..5eaec823bb 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -21,7 +21,7 @@ The infection states and the transitions are visualized in the following graph. Infection States ---------------- -The model contains the following list of **InfectionState**\s: +The model contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -48,7 +48,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SEIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -**AgeGroup** but can also be used for other interpretations. For stratifications with two or more dimensions, see +:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with @@ -90,8 +90,8 @@ The model implements the following parameters: Initial Conditions ------------------ -The initial conditions of the model are defined by the class **Populations** which defines the number of individuals in -each sociodemographic group and **InfectionState**. Before running a simulation, you need to set the initial values for +The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -190,7 +190,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index 485130551f..37b5a87ec4 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -14,7 +14,7 @@ The infection states and the transitions are visualized in the following graph. Infection States ---------------- -The model contains the following list of **InfectionState**\s: +The model contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -45,7 +45,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SEIRDB model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -**AgeGroup** but can also be used for other interpretations. For stratifications with two or more dimensions, see +:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with @@ -96,8 +96,8 @@ The model implements the following parameters: Initial Conditions ------------------ -The initial conditions of the model are defined by the class **Populations** which defines the number of individuals in -each sociodemographic group and **InfectionState**. Before running a simulation, you need to set the initial values for +The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -199,7 +199,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index 47b5f64767..346b618b1c 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -14,7 +14,7 @@ The infection states and transitions are illustrated in the following figure. Infection States ---------------- -The model contains the following **InfectionState**\s: +The model contains the following :code:`InfectionState`\s: .. code-block:: RST @@ -47,7 +47,7 @@ recoveries) are computed explicitly in addition to compartment values. The defin Sociodemographic Stratification -------------------------------- -The population can be stratified by one sociodemographic dimension denoted **AgeGroup** (can be interpreted more +The population can be stratified by one sociodemographic dimension denoted :code:`AgeGroup` (can be interpreted more broadly). The number of age groups is specified in the constructor: .. code-block:: cpp @@ -123,7 +123,7 @@ differential infection hazards. Initial Conditions ------------------ -Initial conditions are handled via the **Populations** class. Example for a single age group: +Initial conditions are handled via the :code:`Populations` class. Example for a single age group: .. code-block:: cpp diff --git a/docs/source/cpp/models/osir.rst b/docs/source/cpp/models/osir.rst index 4bced9aa77..c26c426b90 100644 --- a/docs/source/cpp/models/osir.rst +++ b/docs/source/cpp/models/osir.rst @@ -23,7 +23,7 @@ The infection states and the transitions are visualized in the following image. Infection States ---------------- -The model contains the following list of **InfectionState**\s: +The model contains the following list of :code:`InfectionState`\s: .. code-block:: RST @@ -43,7 +43,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -**AgeGroup** but can also be used for other interpretations. For stratification with two or more dimensions, see +:code:`AgeGroup` but can also be used for other interpretations. For stratification with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with: @@ -82,8 +82,8 @@ The model implements the following parameters. Initial conditions ------------------ -The initial conditions of the model are defined by the class **Populations** which defines the number of individuals in -each sociodemographic group and **InfectionState**. Before running a simulation, you need to set the initial values for +The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index da217b879c..9f37d3e725 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -16,7 +16,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -Every model contains a list of **InfectionState**\s that define particular features of the subpopulations in the particular state. +Every model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -38,7 +38,7 @@ The simpler class :code:`CompartmentalModel` only considers the states of the sy Sociodemographic stratification ------------------------------- -For most ODE-based models, the population can be stratified by one sociodemographic dimension. This dimension is denoted **AgeGroup** but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation `. +For most ODE-based models, the population can be stratified by one sociodemographic dimension. This dimension is denoted :code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation `. Parameters @@ -49,10 +49,10 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, we -use a parameter denoted **ContactPatterns** of type **UncertainContactMatrix**. The **UncertainContactMatrix** contains +use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains a set of contact matrices of arbitrary length which can represent different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the **ContactPatterns** parameter, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the :code:`ContactPatterns` parameter, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` and group :math:`j`. The dimension of the matrix is automatically defined by the model initiation and it is reduced to one value if no stratifcation is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions`. @@ -69,10 +69,10 @@ Parameters can get accessed via ``model.parameters.get>()`` and se Initial conditions ------------------ -The initial conditions of the model are represented by a class **Populations** that gives the number of individuals in -each sociodemographic group and **InfectionState**. For more details, see :doc:`Model Creation `. Before +The initial conditions of the model are represented by a class :code:`Populations` that gives the number of individuals in +each sociodemographic group and :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before the simulation, set the initial conditions via ``model.populations[{AgeGroup::Age, InfectionState::State}] = value`` for -each **InfectionState** and sociodemographic group. +each :code:`InfectionState` and sociodemographic group. .. _Nonpharmaceutical Interventions: @@ -81,9 +81,9 @@ Nonpharmaceutical interventions ------------------------------- Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, -school closures, or social distancing. This is done by adding **Damping**\s to the **ContactPatterns** of the model. A -**Damping** is defined by a time point at which the intervention starts and a matrix of the same size as the -**ContactMatrix**. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also +school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A +:code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the +:code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. @@ -117,9 +117,9 @@ Additionally, a feedback simulation is available, which allows for dynamic adjus Output ------ -The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. A +The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. A simple table can be printed using the ``print_table()`` function of the ``TimeSeries`` class. The output of the -**FlowSimulation** additionally contains the flows between compartments at each time point. The compartment sizes can +:code:`FlowSimulation` additionally contains the flows between compartments at each time point. The compartment sizes can be printed with ``result[0].print_table()`` and the flows with ``result[1].print_table()``. As adaptive step size methods are used by default, the output will not be available on equidistant time points like `dt` or days. To obtain outputs on days or user-defined time points, you can interpolate the results to days or diff --git a/docs/source/cpp/sbml.rst b/docs/source/cpp/sbml.rst index 8fd9ca576b..3db8ac2851 100644 --- a/docs/source/cpp/sbml.rst +++ b/docs/source/cpp/sbml.rst @@ -65,7 +65,7 @@ The following features are the most important not supported features: - The ``^`` operator for exponentiation in functions. This will produce errors during compilation of the generated code, but can then be changed manually. As in an SBML file all species have to be given separately, it is unfortunately also not possible to automatically use -the **Population** in MEmilio to stratify the population into different compartments. +the :code:`Population` in MEmilio to stratify the population into different compartments. In general: Please check your models after the conversion to ensure that everything is working as expected. diff --git a/docs/source/cpp/sde.rst b/docs/source/cpp/sde.rst index fbca03c3d8..0dd83f9a4f 100644 --- a/docs/source/cpp/sde.rst +++ b/docs/source/cpp/sde.rst @@ -7,7 +7,7 @@ additional function to compute the random noise, as can be seen :doc:`here `. -The class used for implementing SDE models is called **StochasticModel**. It is derived from a :code:`CompartmentalModel` +The class used for implementing SDE models is called :code:`StochasticModel`. It is derived from a :code:`CompartmentalModel` (or optionally a :code:`FlowModel`) for the representation of the deterministic part of the model equations. Check out :doc:`SDE model creation ` for more details. diff --git a/docs/source/cpp/smm.rst b/docs/source/cpp/smm.rst index bf37788a75..dcb156bc16 100644 --- a/docs/source/cpp/smm.rst +++ b/docs/source/cpp/smm.rst @@ -52,7 +52,7 @@ Infection state transitions The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection -states, the **Influence**\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening +states, the :code:`Influence`\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same infection state transition which can be useful when having e.g. region-dependent interventions or contact behavior. @@ -179,7 +179,7 @@ are drawn. Then the time is advanced until the time point of the next event - wh infection state adoption - and the event takes places. The waiting times of the other events are updated and a new waiting time for the event that just happened is drawn. The simulation saves the system state in discrete time steps. -To simulate the model from ``t0`` to ``tmax`` with given step size ``dt``, a **Simulation** has to be created and advanced +To simulate the model from ``t0`` to ``tmax`` with given step size ``dt``, a :code:`Simulation` has to be created and advanced until ``tmax``. The step size is only used to regularly save the system state during the simulation. .. code-block:: cpp diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index dde8118089..8112862362 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -180,7 +180,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d dampings.append(physical_distancing_home_school(start_spring, 0.4, 0.6)) dampings.append(physical_distancing_work_other(start_spring, 0.4, 0.6)) -A more advances structure to automatically activate interventions based on threshold criteria is given by **DynamicNPIs**. +A more advances structure to automatically activate interventions based on threshold criteria is given by :code:`DynamicNPIs`. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get activated for a defined duration when the threshold is exceeded. As above, different dampings `dampings` can be assigned to different contact locations From 26416eb58587d20b74bb45b96e205b11423925c1 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 14:53:20 +0200 Subject: [PATCH 06/16] Apply suggestions from code review Co-authored-by: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> --- docs/source/cpp/diffusive_abm.rst | 2 +- docs/source/cpp/glct.rst | 2 +- docs/source/cpp/ide.rst | 6 +++--- docs/source/cpp/lct.rst | 2 +- docs/source/cpp/models/lsecir.rst | 2 +- docs/source/cpp/models/lsecir2d.rst | 2 +- docs/source/cpp/models/osecir.rst | 2 +- docs/source/cpp/models/osecirts.rst | 2 +- docs/source/cpp/models/osecirvvs.rst | 4 ++-- docs/source/cpp/models/oseir.rst | 4 ++-- docs/source/cpp/models/oseirdb.rst | 4 ++-- docs/source/cpp/ode.rst | 2 +- docs/source/cpp/sbml.rst | 2 +- 13 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index fff666f55f..2f1680ab0a 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -161,7 +161,7 @@ The model holds a vector containing all agents that can be accessed via sim.get_model().populations -Additionally, the agents are automatically aggregated by region and infection state in a :code:`mio::TimeSeries` object which can be accessed and printed as follows: +Additionally, the agents are automatically aggregated by region and infection state in a :code:`TimeSeries` object which can be accessed and printed as follows: .. code-block:: cpp diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 1e8d95846b..38bbbc78c7 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -85,7 +85,7 @@ You can run a simulation using either fixed or adaptive integration schemes with Output ------ -The output of the :code:`Simulation` is a :code:`mio::TimeSeries` containing the sizes of each subcompartment at each time point. +The output of the :code:`Simulation` is a :code:`TimeSeries` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/ide.rst b/docs/source/cpp/ide.rst index 4ad3f6869f..3ead8c7977 100644 --- a/docs/source/cpp/ide.rst +++ b/docs/source/cpp/ide.rst @@ -116,9 +116,9 @@ uses a nonstandard numerical scheme to solve the IDEs that is implemented in MEm Output ------ -The output of the simulation ``sim`` is a :code:`mio::TimeSeries` containing the sizes of each compartment at each time point -and a :code:`mio::TimeSeries` containing the flows within a time step for each time point. A simple table can be printed using the -``print_table()`` function of the :code:`mio::TimeSeries` class. The compartment sizes can be printed with +The output of the simulation ``sim`` is a :code:`TimeSeries` containing the sizes of each compartment at each time point +and a :code:`TimeSeries` containing the flows within a time step for each time point. A simple table can be printed using the +``print_table()`` function of the :code:`TimeSeries` class. The compartment sizes can be printed with ``sim.get_result().print_table()`` and the flows with ``sim.get_transitions().print_table()``. As the time step may be small it may be useful to obtain outputs on days or user-defined time points. You can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``. diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index afba95a756..fcf699499a 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -97,7 +97,7 @@ You can run a simulation using either fixed or adaptive integration schemes with Output ------ -The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each subcompartment at each time point. +The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 64428d931a..0f62be5f8a 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -307,7 +307,7 @@ The simulation result is stratefied by subcompartments. The function ``calculate mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the :code:`mio::TimeSeries` object as follows: +You can access the data in the :code:`TimeSeries` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index beaae401ee..488eb9a974 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -408,7 +408,7 @@ The simulation result is stratefied by subcompartments. The function ``calculate mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the :code:`mio::TimeSeries` object as follows: +You can access the data in the :code:`TimeSeries` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 5e2e1eda9a..17a40617b3 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -335,7 +335,7 @@ The output of the simulation is a :code:`TimeSeries` object containing the sizes Eigen::VectorXd last_value = secir.get_last_value(); double last_time = secir.get_last_time(); -For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 63176b83fa..4d99884307 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -363,7 +363,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a :code:`mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index 7fd1aeb7d5..d03a4a54e7 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -220,7 +220,7 @@ The model includes all parameters from the basic ODE-SECIR model plus additional Initial conditions ------------------ -The initial conditions of the model are represented by the class **Populations** which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you should set the initial values for each compartment across all immunity levels. +The initial conditions of the model are represented by the class ``Populations`` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you should set the initial values for each compartment across all immunity levels. Below is an example showing how to initialize all compartments for the ODE-SECIRVVS model: @@ -377,7 +377,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a :code:`mio::TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index 5eaec823bb..cb9b315059 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -190,7 +190,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp @@ -206,7 +206,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index 37b5a87ec4..d5fc28475a 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -199,7 +199,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp @@ -215,7 +215,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two :code:`mio::TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 9f37d3e725..139655a465 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -117,7 +117,7 @@ Additionally, a feedback simulation is available, which allows for dynamic adjus Output ------ -The output of the :code:`Simulation` is a ``mio::TimeSeries`` containing the sizes of each compartment at each time point. A +The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. A simple table can be printed using the ``print_table()`` function of the ``TimeSeries`` class. The output of the :code:`FlowSimulation` additionally contains the flows between compartments at each time point. The compartment sizes can be printed with ``result[0].print_table()`` and the flows with ``result[1].print_table()``. diff --git a/docs/source/cpp/sbml.rst b/docs/source/cpp/sbml.rst index 3db8ac2851..6e0cfe7c40 100644 --- a/docs/source/cpp/sbml.rst +++ b/docs/source/cpp/sbml.rst @@ -65,7 +65,7 @@ The following features are the most important not supported features: - The ``^`` operator for exponentiation in functions. This will produce errors during compilation of the generated code, but can then be changed manually. As in an SBML file all species have to be given separately, it is unfortunately also not possible to automatically use -the :code:`Population` in MEmilio to stratify the population into different compartments. +the :code:`Populations` in MEmilio to stratify the population into different compartments. In general: Please check your models after the conversion to ensure that everything is working as expected. From 63352287894fe2fceeaeb07d8c496f5adcf59643 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Tue, 21 Apr 2026 15:57:07 +0200 Subject: [PATCH 07/16] replace :code: by `` --- docs/source/cpp/data_types.rst | 6 ++-- docs/source/cpp/diffusive_abm.rst | 10 +++--- docs/source/cpp/glct.rst | 20 ++++++------ docs/source/cpp/ide.rst | 24 +++++++------- docs/source/cpp/io.rst | 6 ++-- docs/source/cpp/lct.rst | 20 ++++++------ docs/source/cpp/lct_creation.rst | 12 +++---- docs/source/cpp/mobility_based_abm.rst | 2 +- docs/source/cpp/models/glsecir.rst | 2 +- docs/source/cpp/models/isecir.rst | 14 ++++---- docs/source/cpp/models/iseir.rst | 4 +-- docs/source/cpp/models/lsecir.rst | 4 +-- docs/source/cpp/models/lsecir2d.rst | 4 +-- docs/source/cpp/models/omseirs4.rst | 2 +- docs/source/cpp/models/osecir.rst | 10 +++--- docs/source/cpp/models/osecirts.rst | 8 ++--- docs/source/cpp/models/osecirvvs.rst | 10 +++--- docs/source/cpp/models/oseir.rst | 10 +++--- docs/source/cpp/models/oseirdb.rst | 10 +++--- docs/source/cpp/models/oseirv.rst | 4 +-- docs/source/cpp/models/osir.rst | 8 ++--- docs/source/cpp/ode.rst | 32 +++++++++---------- docs/source/cpp/ode_creation.rst | 4 +-- docs/source/cpp/sde.rst | 4 +-- docs/source/cpp/smm.rst | 2 +- docs/source/getting_started.rst | 2 +- .../m-simulation_expanding_bindings.rst | 2 +- .../python/m-simulation_model_usage.rst | 4 +-- 28 files changed, 120 insertions(+), 120 deletions(-) diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 417cf04558..5be935c5f8 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -21,7 +21,7 @@ The following list explains the nonstandard data types that are used throughout - A contiguous array whose values can be accessed by a multi-index, e.g. a :code:`mio::Index` with one or more categories. This datatype is, for example, used in the parameter :code:`mio::abm::TimeExposedToNoSymptoms` making it dependent on :code:`mio::abm::VirusVariant` and :code:`mio::AgeGroup`. Its values can then be set for a specific :code:`virus_variant` and :code:`age_group` using :code:`model.parameters.template get()[{virus_variant, age_group}]`. * - :code:`Populations` - Is a :code:`mio::CustomIndexArray` with :code:`mio::UncertainValue` as values. Adds some convenient functions like :code:`get_group_total`. - * - :code:`TimeSeries` + * - ``TimeSeries`` - Stores vectors of values at time points. Each time point has a vector of values of the same size with operations like adding time points, retrieving values, exporting to CSV, etc. It's also used for storing and analyzing simulation results over time. * - :code:`Graph` - A generic graph structure that represents a network of nodes connected by edges. Each node and edge can have associated properties. The graph is used to model geographical regions connected by mobility patterns (e.g., commuting), where each node is represented by its own epidemiological model. @@ -41,9 +41,9 @@ The following list explains the nonstandard data types that are used throughout - Parameters that influence mobility between nodes, including coefficients and dynamic nonpharmaceutical interventions (NPIs). * - :code:`MobilityEdge` - Represents mobility between two nodes in a graph. Handles the movement of populations between nodes, tracks mobile populations, and applies mobility returns according to epidemiological models. - * - :code:`ContactMatrix` + * - ``ContactMatrix`` - Time-dependent contact frequencies between groups, derived from ``DampingMatrixExpression``. Models how the contact rates between different age groups change over time due to interventions. - * - :code:`ContactMatrixGroup` + * - ``ContactMatrixGroup`` - A collection of contact matrices that represent different contexts (e.g., home, school, work) whose sum is the total number of contacts, derived from ``DampingMatrixExpressionGroup``. * - :code:`DampingMatrixExpression` - Represents a coefficient-wise matrix expression :math:`B - D \odot (B - M)`, where :math:`B` is a baseline matrix, :math:`M` is a minimum matrix, :math:`D` is a time-dependent complex damping factor, and :math:`\odot` is element wise multiplication. Used as the base for time-dependent contact matrices. diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index 2f1680ab0a..8863ce6bad 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -10,7 +10,7 @@ The features of an agent are its position and its infection state. The evolution with :math:`X` the vector of all agents' positions and :math:`Z` the vector of all agents' infection states. The operator :math:`G` defines the infection state adoptions and only acts on :math:`Z`, while :math:`L` defines movement, i.e. location changes, only acting on :math:`X`. Infection state adoptions are modeled with independent Poisson processes given by adoption rate functions. Movement is modeled with independent diffusion processes. A temporal Gillespie algorithm (a direct method without rejection sampling) is used for simulation. Therefore, :math:`G` and :math:`L` are not implemented explicitly, instead their effects are sampled via the `move` and `adoption_rate` functions, respectively. -The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes :code:`QuadWell` and :code:`SingleWell` respectively are implemented, but any other suitable potential can be used as implementation. +The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes ``QuadWell`` and ``SingleWell`` respectively are implemented, but any other suitable potential can be used as implementation. In the following, we present more details of the diffusive agent-based model, including code examples. An overview of nonstandard but often used data types can be found under :doc:`data_types`. @@ -40,7 +40,7 @@ Using the infection states Susceptible (S), Exposed (E), Carrier (C), Infected ( Infection state transitions --------------------------- -The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the :code:`Influence`\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior. +The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the ``Influence``\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior. Using the infection states from above and only one region, there are five first-order and one second-order adoption rate that can be set via: @@ -134,7 +134,7 @@ Simulation The simulation runs in discrete time steps. In every step the model is advanced until the next infection state adoption event. Then the corresponding agent's infection state is adopted and a new waiting time until the next adoption event is drawn. If the waiting time until the next adoption event is bigger than the remaining time in the time step, we advance the model until the end of the time step. -To simulate the model from `t0` to `tmax` with given step size `dt`, a :code:`Simulation` has to be created and advanced until `tmax`, which is done as follows: +To simulate the model from `t0` to `tmax` with given step size `dt`, a ``Simulation`` has to be created and advanced until `tmax`, which is done as follows: .. code-block:: cpp @@ -161,7 +161,7 @@ The model holds a vector containing all agents that can be accessed via sim.get_model().populations -Additionally, the agents are automatically aggregated by region and infection state in a :code:`TimeSeries` object which can be accessed and printed as follows: +Additionally, the agents are automatically aggregated by region and infection state in a ``TimeSeries`` object which can be accessed and printed as follows: .. code-block:: cpp @@ -171,7 +171,7 @@ Additionally, the agents are automatically aggregated by region and infection st //Print result object to console. Infection state "Xi" with i=0,...,3 is the number of agents having infection state X in region i result.print_table({"S0", "E0", "C0", "I0", "R0", "D0", "S1", "E1", "C1", "I1", "R1", "D1", "S2", "E2", "C2", "I2", "R2", "D2", "S3", "E3", "C3", "I3", "R3", "D3"}) -If one wants to interpolate the aggregated results to a :code:`mio::TimeSeries` containing only full days, this can be done by +If one wants to interpolate the aggregated results to a ``TimeSeries`` containing only full days, this can be done by .. code-block:: cpp diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 38bbbc78c7..4743ec24e4 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -11,7 +11,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -The model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. +The model contains a list of ``InfectionState``\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -19,15 +19,15 @@ The model contains a list of :code:`InfectionState`\s that define particular fea `State2` `...` -To make use of the GLCT, we additionally need to define the numbers of subcompartments for each :code:`InfectionState`. -This is done by creating an :code:`LctInfectionState` object for each group. These objects are then passed as template +To make use of the GLCT, we additionally need to define the numbers of subcompartments for each ``InfectionState``. +This is done by creating an ``LctInfectionState`` object for each group. These objects are then passed as template parameter to the model. .. code-block:: cpp using LctStateGroup1 = mio::LctInfectionState; -The model is implemented as :code:`CompartmentalModel`. +The model is implemented as ``CompartmentalModel``. Parameters @@ -38,10 +38,10 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, -we use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains an +we use a parameter denoted ``ContactPatterns`` of type ``UncertainContactMatrix``. The ``UncertainContactMatrix`` contains an arbitrary large set of contact matrices which can e.g. represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the ``ContactPatterns``, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization and it is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions GLCT`. @@ -52,14 +52,14 @@ Parameters can be accessed via ``model.parameters.get>()`` and set Initial conditions ------------------ -The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment of each :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each :code:`InfectionState` and sociodemographic group must be set. +The initial conditions of the model are represented by a class ``LctPopulations`` that gives the number of individuals in each sociodemographic group and each subcompartment of each ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each ``InfectionState`` and sociodemographic group must be set. .. _Nonpharmaceutical Interventions GLCT: Nonpharmaceutical interventions ------------------------------- -Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A :code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the :code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. +Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding ``Damping``\s to the ``ContactPatterns`` of the model. A ``Damping`` is defined by a time point at which the intervention starts and a matrix of the same size as the ``ContactMatrix``. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. .. dropdown:: :fa:`gears` Expert's settings @@ -78,14 +78,14 @@ Contact rates can be adjusted during the simulation to model nonpharmaceutical i Simulation ---------- -Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each subcompartment over time. +Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type ``Simulation`` that saves the sizes of each subcompartment over time. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive solution scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. For more details on the possible integration schemes, see . Output ------ -The output of the :code:`Simulation` is a :code:`TimeSeries` containing the sizes of each subcompartment at each time point. +The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/ide.rst b/docs/source/cpp/ide.rst index 3ead8c7977..deea022a86 100644 --- a/docs/source/cpp/ide.rst +++ b/docs/source/cpp/ide.rst @@ -15,7 +15,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -Every model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. +Every model contains a list of ``InfectionState``\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -27,8 +27,8 @@ Every model contains a list of :code:`InfectionState`\s that define particular f Infection state transitions --------------------------- -Additionally, we define :code:`InfectionTransition`\s that define the possible transitions between the :code:`InfectionState`\s. -When solving the model, we obtain results for the :code:`InfectionTransition`\s as well. +Additionally, we define ``InfectionTransition``\s that define the possible transitions between the ``InfectionState``\s. +When solving the model, we obtain results for the ``InfectionTransition``\s as well. .. code-block:: RST @@ -40,7 +40,7 @@ When solving the model, we obtain results for the :code:`InfectionTransition`\s Sociodemographic stratification ------------------------------- -For the IDE-SECIR model, the population can also be stratified by one sociodemographic dimension. This dimension is denoted :code:`AgeGroup` but can also be used for other interpretations. +For the IDE-SECIR model, the population can also be stratified by one sociodemographic dimension. This dimension is denoted ``AgeGroup`` but can also be used for other interpretations. Parameters ---------- @@ -50,11 +50,11 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different sociodemographic groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each group. To model different contact rates between different sociodemographic groups, we -use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains an +use a parameter denoted ``ContactPatterns`` of type ``UncertainContactMatrix``. The ``UncertainContactMatrix`` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the ``ContactPatterns``, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` and group :math:`j`. The dimension of the matrix is automatically defined by the model initiation and it is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions IDE`. @@ -85,9 +85,9 @@ Nonpharmaceutical interventions ------------------------------- Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, -school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A -:code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the -:code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also +school closures, or social distancing. This is done by adding ``Damping``\s to the ``ContactPatterns`` of the model. A +``Damping`` is defined by a time point at which the intervention starts and a matrix of the same size as the +``ContactMatrix``. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. @@ -116,9 +116,9 @@ uses a nonstandard numerical scheme to solve the IDEs that is implemented in MEm Output ------ -The output of the simulation ``sim`` is a :code:`TimeSeries` containing the sizes of each compartment at each time point -and a :code:`TimeSeries` containing the flows within a time step for each time point. A simple table can be printed using the -``print_table()`` function of the :code:`TimeSeries` class. The compartment sizes can be printed with +The output of the simulation ``sim`` is a ``TimeSeries`` containing the sizes of each compartment at each time point +and a ``TimeSeries`` containing the flows within a time step for each time point. A simple table can be printed using the +``print_table()`` function of the ``TimeSeries`` class. The compartment sizes can be printed with ``sim.get_result().print_table()`` and the flows with ``sim.get_transitions().print_table()``. As the time step may be small it may be useful to obtain outputs on days or user-defined time points. You can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``. diff --git a/docs/source/cpp/io.rst b/docs/source/cpp/io.rst index b43a391e37..466ade165a 100644 --- a/docs/source/cpp/io.rst +++ b/docs/source/cpp/io.rst @@ -6,11 +6,11 @@ MEmilio provides a set of input/output (IO) functionalities to read and write da Aggregated output ----------------- -All aggregated models save their results in a :code:`mio::TimeSeries` that contains all subpopulations for every time -point, see :doc:`data_types` for a description of the :code:`mio::TimeSeries` data type. The time series can be printed +All aggregated models save their results in a ``TimeSeries`` that contains all subpopulations for every time +point, see :doc:`data_types` for a description of the ``TimeSeries`` data type. The time series can be printed to the terminal with the :code:`TimeSeries::print_table()` function and exported to a CSV file using :code:`TimeSeries::export_csv`. As e.g. for the ODE-based models adaptive step size methods are used, the time series will not be necessarily available -on equidistant time points or days. To obtain a :code:`mio::TimeSeries` interpolated on days or user-defined time points, +on equidistant time points or days. To obtain a ``TimeSeries`` interpolated on days or user-defined time points, the :code:`mio::interpolate_simulation_result()` can be used. This document describes utilities for reading and writing data from and to files in different formats, in cases where diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index fcf699499a..805a6e071d 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -11,7 +11,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -The model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. +The model contains a list of ``InfectionState``\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -19,8 +19,8 @@ The model contains a list of :code:`InfectionState`\s that define particular fea `State2` `...` -To make use of the LCT, we additionally need to define the numbers of subcompartments for each :code:`InfectionState`. -This is done by creating an :code:`LctInfectionState` object for each group. These objects are then passed as template +To make use of the LCT, we additionally need to define the numbers of subcompartments for each ``InfectionState``. +This is done by creating an ``LctInfectionState`` object for each group. These objects are then passed as template parameter to the model. .. code-block:: cpp @@ -29,7 +29,7 @@ parameter to the model. `Number of subcompartments of State2`, `...`>; -The model is implemented as :code:`CompartmentalModel`. +The model is implemented as ``CompartmentalModel``. @@ -47,10 +47,10 @@ The parameters of the model are defined as structs and are combined in a class ` We use different types of parameters to represent epidemiological parameters such as the mean stay times in a compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. -To model different contact rates between different sociodemographic groups, we use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. +To model different contact rates between different sociodemographic groups, we use a parameter denoted ``ContactPatterns`` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the :code:`ContactPatterns`, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. +In the ``ContactPatterns``, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization and is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions LCT`. @@ -61,14 +61,14 @@ Parameters can be accessed via ``model.parameters.get>()`` and set Initial conditions ------------------ -The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment for each :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each :code:`InfectionState` and sociodemographic group must be set. +The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment for each ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each ``InfectionState`` and sociodemographic group must be set. .. _Nonpharmaceutical Interventions LCT: Nonpharmaceutical interventions ------------------------------- -Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A :code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the :code:`ContactMatrix`. +Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding ``Damping``\s to the ``ContactPatterns`` of the model. A ``Damping`` is defined by a time point at which the intervention starts and a matrix of the same size as the ``ContactMatrix``. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. @@ -90,14 +90,14 @@ reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. Simulation ---------- -Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each subcompartment over time. +Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type ``Simulation`` that saves the sizes of each subcompartment over time. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive solution scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. For more details on the possible integration schemes, see . Output ------ -The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. +The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the ``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index b056e00425..782413f7ec 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -87,8 +87,8 @@ We also define a parameter ``ContactPatterns`` determining the contacts of the d Avoid using the mathematical symbol of a constant as name for the struct. Their connection can be noted down in the documentation of these structs. -Finally, define a type :code:`Parameters` by listing all parameter structs as template arguments of a -:code:`mio::ParameterSet`: +Finally, define a type ``Parameters`` by listing all parameter structs as template arguments of a +``mio::ParameterSet``: .. code-block:: cpp @@ -96,7 +96,7 @@ Finally, define a type :code:`Parameters` by listing all parameter structs as te using Parameters = mio::ParameterSet; -For more complex models, :code:`Parameters` allows passing arguments from its constructor to the :code:`get_default` +For more complex models, ``Parameters`` allows passing arguments from its constructor to the :code:`get_default` functions. Make sure that all of these functions take the exact types as function arguments that you want to pass to the constructor. @@ -119,7 +119,7 @@ example being adding age groups. Define the model ^^^^^^^^^^^^^^^^ -Now we can define the model as a :code:`CompartmentalModel` in the file "model.h": +Now we can define the model as a ``CompartmentalModel`` in the file "model.h": .. code-block:: cpp @@ -177,8 +177,8 @@ The function ``get_derivatives()`` evaluates the right-hand-side of the ODE :mat It is also useful to implement the following methods within the model: -- A function ``calculate_compartments()`` that accumulates the :code:`TimeSeries` containing simulation results that are divided -into subcompartments to a :code:`TimeSeries` that conatins the simulation results according to the infection states without subcompartments. +- A function ``calculate_compartments()`` that accumulates the ``TimeSeries`` containing simulation results that are divided +into subcompartments to a ``TimeSeries`` that conatins the simulation results according to the infection states without subcompartments. For an example, see the implementation within the LCT-SECIR model. - A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. For an example, see the implementation within the LCT-SECIR model. diff --git a/docs/source/cpp/mobility_based_abm.rst b/docs/source/cpp/mobility_based_abm.rst index b5ab66c01a..74ac617933 100644 --- a/docs/source/cpp/mobility_based_abm.rst +++ b/docs/source/cpp/mobility_based_abm.rst @@ -326,7 +326,7 @@ Here, we run the simulation: sim.advance(tmax); Alternatively, if we want to track things in the simulation, we need to set up a -`history `_, for example, to track all the Infection states of each simulation step into a :code:`Timeseries`. +`history `_, for example, to track all the Infection states of each simulation step into a ``TimeSeries``. .. code-block:: cpp diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index 2148d96db3..e6bf29f047 100644 --- a/docs/source/cpp/models/glsecir.rst +++ b/docs/source/cpp/models/glsecir.rst @@ -17,7 +17,7 @@ For the concept see: Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST diff --git a/docs/source/cpp/models/isecir.rst b/docs/source/cpp/models/isecir.rst index b8b1ab4e4c..fc93b78a96 100644 --- a/docs/source/cpp/models/isecir.rst +++ b/docs/source/cpp/models/isecir.rst @@ -26,7 +26,7 @@ A detailed investigation of the IDE-SECIR model and numerical experiments can be Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -42,7 +42,7 @@ The model contains the following list of :code:`InfectionState`\s: Infection State Transitions --------------------------- -The possible transitions between the :code:`InfectionState`\s are: +The possible transitions between the ``InfectionState``\s are: .. code-block:: RST @@ -62,7 +62,7 @@ Sociodemographic Stratification ------------------------------- In the IDE-SECIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. +``AgeGroup`` but can also be used for other interpretations. Parameters @@ -291,7 +291,7 @@ Before the simulation, we check if all constraints of the model are satisfied so model.check_constraints(dt); To simulate the model from :math:`t_0` (that is determined by the initial flows provided to the constructor) to -:math:`t_{\max}` with given step size :math:`dt`, a object of the :code:`Simulation` class has to be created and advanced +:math:`t_{\max}` with given step size :math:`dt`, a object of the ``Simulation`` class has to be created and advanced until :math:`t_{\max}`, which is done as follows. .. code-block:: cpp @@ -305,7 +305,7 @@ until :math:`t_{\max}`, which is done as follows. Output ------ -The output of the simulation are two :code:`TimeSeries` objects, one containing the size of the compartments at all time +The output of the simulation are two ``TimeSeries`` objects, one containing the size of the compartments at all time points and one containing the number of transitions within a time step. You can access the results as follows: .. code-block:: cpp @@ -316,9 +316,9 @@ points and one containing the number of transitions within a time step. You can // Access transitions between compartments. auto transitions = sim.get_transitions(); -The order of the compartments and transitions follows the definition in the :code:`InfectionState` and :code:`InfectionTransition` enums, respectively. +The order of the compartments and transitions follows the definition in the ``InfectionState`` and ``InfectionTransition`` enums, respectively. -You can access the data in the :code:`TimeSeries` objects as follows: +You can access the data in the ``TimeSeries`` objects as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index f6c244f895..3e73c35706 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -19,7 +19,7 @@ Bachelor's thesis, University of Cologne. `https://elib.dlr.de/143504/ population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the :code:`TimeSeries` object as follows: +You can access the data in the ``TimeSeries`` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index 488eb9a974..77904f13e5 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -60,7 +60,7 @@ due to extensive isolation of the hospitalized individuals. Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -408,7 +408,7 @@ The simulation result is stratefied by subcompartments. The function ``calculate mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the :code:`TimeSeries` object as follows: +You can access the data in the ``TimeSeries`` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 38cb173e86..30402d1ee8 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -39,7 +39,7 @@ All infectious classes (I1..I4) contribute equally to transmission in the basic Infection State Transitions --------------------------- -The model is implemented as a :code:`CompartmentalModel`, which defines the derivative of the aggregated compartment +The model is implemented as a ``CompartmentalModel``, which defines the derivative of the aggregated compartment values in time. The following transitions occur: - Births enter M and some enter S1 diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 17a40617b3..95f669d182 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -19,7 +19,7 @@ The infection states and the transitions (also see next two sections) are visual Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -67,7 +67,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SECIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, +``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. @@ -137,7 +137,7 @@ The model implements the following parameters: Initial conditions ------------------ -The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for each compartment: +The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -320,7 +320,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a basic simulation, you can access the results as follows: +The output of the simulation is a ``TimeSeries`` object containing the sizes of each compartment at each time point. For a basic simulation, you can access the results as follows: .. code-block:: cpp @@ -335,7 +335,7 @@ The output of the simulation is a :code:`TimeSeries` object containing the sizes Eigen::VectorXd last_value = secir.get_last_value(); double last_time = secir.get_last_time(); -For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two ``TimeSeries`` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 4d99884307..68ced426c4 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -20,7 +20,7 @@ Below is an overview of the model architecture and its compartments. Infection States ---------------- -The model extends the ODE-SECIRVVS model by adding temporary immunity states and flow paths for waning immunity. It contains the following list of :code:`InfectionState`\s: +The model extends the ODE-SECIRVVS model by adding temporary immunity states and flow paths for waning immunity. It contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -115,7 +115,7 @@ Sociodemographic Stratification ------------------------------- Like the other ODE-SECIR models, the ODE-SECIRTS model can be stratified by one sociodemographic dimension, typically age groups. This stratification is important for modeling different vaccination rates, symptom severities, mortality risks, and immunity waning rates across age groups. The dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. +``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. Parameters @@ -234,7 +234,7 @@ The model includes all parameters from the ODE-SECIRVVS model as well as additio Initial conditions ------------------ -The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: +The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: .. code-block:: cpp @@ -363,7 +363,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a ``TimeSeries`` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index d03a4a54e7..b90578bb1b 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -15,7 +15,7 @@ Below is an overview of the model architecture and its compartments. Infection States ---------------- -The model extends the basic ODE-SECIR model by dividing the compartments based on immunity levels. It contains the following list of :code:`InfectionState`\s: +The model extends the basic ODE-SECIR model by dividing the compartments based on immunity levels. It contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -83,13 +83,13 @@ For each immunity level (Naive, PartialImmunity, ImprovedImmunity), the followin Where * stands for the immunity level suffix (Naive, PartialImmunity, or ImprovedImmunity). -**Important:** Vaccinations are not implemented as flows between compartments but are handled discretely by the simulation. At the beginning of each simulated day, susceptible individuals are moved between immunity levels according to the specified daily vaccination parameters. This discrete process is separate from the ODE system and is managed by the `apply_vaccination` function in the model specific :code:`Simulation` class. +**Important:** Vaccinations are not implemented as flows between compartments but are handled discretely by the simulation. At the beginning of each simulated day, susceptible individuals are moved between immunity levels according to the specified daily vaccination parameters. This discrete process is separate from the ODE system and is managed by the `apply_vaccination` function in the model specific ``Simulation`` class. Sociodemographic Stratification ------------------------------- Like the basic ODE-SECIR model, the ODE-SECIRVVS model can be stratified by one sociodemographic dimension, typically age groups. This stratification is important for modeling different vaccination rates, symptom severities, and mortality risks across age groups. The dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. +``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. Parameters @@ -220,7 +220,7 @@ The model includes all parameters from the basic ODE-SECIR model plus additional Initial conditions ------------------ -The initial conditions of the model are represented by the class ``Populations`` which defines the number of individuals in each sociodemographic group and :code:`InfectionState`. Before running a simulation, you should set the initial values for each compartment across all immunity levels. +The initial conditions of the model are represented by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you should set the initial values for each compartment across all immunity levels. Below is an example showing how to initialize all compartments for the ODE-SECIRVVS model: @@ -377,7 +377,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the simulation is a :code:`TimeSeries` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: +The output of the simulation is a ``TimeSeries`` object containing the sizes of each compartment at each time point. For a standard simulation, you can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index cb9b315059..fdc757a5b2 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -21,7 +21,7 @@ The infection states and the transitions are visualized in the following graph. Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -48,7 +48,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SEIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see +``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with @@ -91,7 +91,7 @@ Initial Conditions ------------------ The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in -each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for +each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -190,7 +190,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp @@ -206,7 +206,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two ``TimeSeries`` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index d5fc28475a..0766192a64 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -14,7 +14,7 @@ The infection states and the transitions are visualized in the following graph. Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -45,7 +45,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SEIRDB model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see +``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with @@ -97,7 +97,7 @@ Initial Conditions ------------------ The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in -each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for +each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -199,7 +199,7 @@ For both simulation types, you can also specify a custom integrator: Output ------ -The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A +The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each compartment at each time point. For A standard simulation, you can access the results as follows: .. code-block:: cpp @@ -215,7 +215,7 @@ standard simulation, you can access the results as follows: Eigen::VectorXd last_value = result_sim.get_last_value(); double last_time = result_sim.get_last_time(); -For flow simulations, the result consists of two :code:`TimeSeries` objects, one for compartment sizes and one for flows: +For flow simulations, the result consists of two ``TimeSeries`` objects, one for compartment sizes and one for flows: .. code-block:: cpp diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index 346b618b1c..d6680298ac 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -14,7 +14,7 @@ The infection states and transitions are illustrated in the following figure. Infection States ---------------- -The model contains the following :code:`InfectionState`\s: +The model contains the following ``InfectionState``\s: .. code-block:: RST @@ -47,7 +47,7 @@ recoveries) are computed explicitly in addition to compartment values. The defin Sociodemographic Stratification -------------------------------- -The population can be stratified by one sociodemographic dimension denoted :code:`AgeGroup` (can be interpreted more +The population can be stratified by one sociodemographic dimension denoted ``AgeGroup`` (can be interpreted more broadly). The number of age groups is specified in the constructor: .. code-block:: cpp diff --git a/docs/source/cpp/models/osir.rst b/docs/source/cpp/models/osir.rst index c26c426b90..fd439d7497 100644 --- a/docs/source/cpp/models/osir.rst +++ b/docs/source/cpp/models/osir.rst @@ -23,7 +23,7 @@ The infection states and the transitions are visualized in the following image. Infection States ---------------- -The model contains the following list of :code:`InfectionState`\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: RST @@ -35,7 +35,7 @@ The model contains the following list of :code:`InfectionState`\s: Infection State transitions --------------------------- -The ODE-SIR model is implemented as a :code:`CompartmentalModel`, which defines the derivative of the aggregated compartment +The ODE-SIR model is implemented as a ``CompartmentalModel``, which defines the derivative of the aggregated compartment values in time. @@ -43,7 +43,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SIR model, the population can be stratified by one sociodemographic dimension. This dimension is denoted -:code:`AgeGroup` but can also be used for other interpretations. For stratification with two or more dimensions, see +``AgeGroup`` but can also be used for other interpretations. For stratification with two or more dimensions, see :doc:`Model Creation <../ode_creation>`. The number of age groups is specified in the model constructor and the model can be initialized with: @@ -83,7 +83,7 @@ Initial conditions ------------------ The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in -each sociodemographic group and :code:`InfectionState`. Before running a simulation, you need to set the initial values for +each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 139655a465..a958a94d96 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -16,7 +16,7 @@ An overview of nonstandard but often used data types can be found under :doc:`da Infection states ---------------- -Every model contains a list of :code:`InfectionState`\s that define particular features of the subpopulations in the particular state. +Every model contains a list of ``InfectionState``\s that define particular features of the subpopulations in the particular state. .. code-block:: RST @@ -28,17 +28,17 @@ Every model contains a list of :code:`InfectionState`\s that define particular f Infection state transitions --------------------------- -Our ODE-based models are either implemented as :code:`FlowModel` or as :code:`CompartmentalModel`. In a :code:`FlowModel`, flows -``Flow`` between :code:`InfectionState`\s **State1** and **State2** are defined. Instead of a standard +Our ODE-based models are either implemented as :code:`FlowModel` or as ``CompartmentalModel``. In a :code:`FlowModel`, flows +``Flow`` between ``InfectionState``\s **State1** and **State2** are defined. Instead of a standard solution of an ODE-based model, this implementation additionally realizes the solution of the transitions or flows between states and directly enables users to access new transmissions or hospitalizations at any time point. -The simpler class :code:`CompartmentalModel` only considers the states of the system and not the flows. +The simpler class ``CompartmentalModel`` only considers the states of the system and not the flows. Sociodemographic stratification ------------------------------- -For most ODE-based models, the population can be stratified by one sociodemographic dimension. This dimension is denoted :code:`AgeGroup` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation `. +For most ODE-based models, the population can be stratified by one sociodemographic dimension. This dimension is denoted ``AgeGroup`` but can also be used for other interpretations. For stratifications with two or more dimensions, see :doc:`Model Creation `. Parameters @@ -49,10 +49,10 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, we -use a parameter denoted :code:`ContactPatterns` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains +use a parameter denoted ``ContactPatterns`` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains a set of contact matrices of arbitrary length which can represent different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. -In the :code:`ContactPatterns` parameter, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic +In the ``ContactPatterns`` parameter, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` and group :math:`j`. The dimension of the matrix is automatically defined by the model initiation and it is reduced to one value if no stratifcation is used. The values can be adjusted during the simulation, e.g., through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions`. @@ -70,9 +70,9 @@ Initial conditions ------------------ The initial conditions of the model are represented by a class :code:`Populations` that gives the number of individuals in -each sociodemographic group and :code:`InfectionState`. For more details, see :doc:`Model Creation `. Before +each sociodemographic group and ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, set the initial conditions via ``model.populations[{AgeGroup::Age, InfectionState::State}] = value`` for -each :code:`InfectionState` and sociodemographic group. +each ``InfectionState`` and sociodemographic group. .. _Nonpharmaceutical Interventions: @@ -81,9 +81,9 @@ Nonpharmaceutical interventions ------------------------------- Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, -school closures, or social distancing. This is done by adding :code:`Damping`\s to the :code:`ContactPatterns` of the model. A -:code:`Damping` is defined by a time point at which the intervention starts and a matrix of the same size as the -:code:`ContactMatrix`. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also +school closures, or social distancing. This is done by adding ``Damping``\s to the ``ContactPatterns`` of the model. A +``Damping`` is defined by a time point at which the intervention starts and a matrix of the same size as the +``ContactMatrix``. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`. @@ -105,8 +105,8 @@ Simulation ---------- Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with an initial step size ``dt`` using the -``mio::simulate()`` function. This will run a simulation of type :code:`Simulation` that saves the sizes of each compartment over time. -To also save the flow information, make sure to use a :code:`FlowModel` and run a simulation of type :code:`FlowSimulation` with the ``mio::simulate_flows()`` function. +``mio::simulate()`` function. This will run a simulation of type ``Simulation`` that saves the sizes of each compartment over time. +To also save the flow information, make sure to use a :code:`FlowModel` and run a simulation of type ``FlowSimulation`` with the ``mio::simulate_flows()`` function. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive integration scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. @@ -117,9 +117,9 @@ Additionally, a feedback simulation is available, which allows for dynamic adjus Output ------ -The output of the :code:`Simulation` is a ``TimeSeries`` containing the sizes of each compartment at each time point. A +The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each compartment at each time point. A simple table can be printed using the ``print_table()`` function of the ``TimeSeries`` class. The output of the -:code:`FlowSimulation` additionally contains the flows between compartments at each time point. The compartment sizes can +``FlowSimulation`` additionally contains the flows between compartments at each time point. The compartment sizes can be printed with ``result[0].print_table()`` and the flows with ``result[1].print_table()``. As adaptive step size methods are used by default, the output will not be available on equidistant time points like `dt` or days. To obtain outputs on days or user-defined time points, you can interpolate the results to days or diff --git a/docs/source/cpp/ode_creation.rst b/docs/source/cpp/ode_creation.rst index b7666509ea..134d5b2b6e 100644 --- a/docs/source/cpp/ode_creation.rst +++ b/docs/source/cpp/ode_creation.rst @@ -24,7 +24,7 @@ states **S**\usceptible, **I**\nfectious, **R**\ecovered, **D**\eceased, also ca How to implement an ODE model ----------------------------- -To define an ODE model in MEmilio, there are two options. You can define a :code:`CompartmentalModel` or a :code:`FlowModel`, which +To define an ODE model in MEmilio, there are two options. You can define a ``CompartmentalModel`` or a :code:`FlowModel`, which use different methods to define the right-hand side of the mathematical model above. Both classes need definitions for the infection states, population and parameters it uses. The :code:`FlowModel` additionally requires a list of flows. @@ -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 :code:`CompartmentalModel` class +Define a ``CompartmentalModel`` class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now we can define the model: diff --git a/docs/source/cpp/sde.rst b/docs/source/cpp/sde.rst index 0dd83f9a4f..0875df4862 100644 --- a/docs/source/cpp/sde.rst +++ b/docs/source/cpp/sde.rst @@ -7,7 +7,7 @@ additional function to compute the random noise, as can be seen :doc:`here `. -The class used for implementing SDE models is called :code:`StochasticModel`. It is derived from a :code:`CompartmentalModel` +The class used for implementing SDE models is called :code:`StochasticModel`. It is derived from a ``CompartmentalModel`` (or optionally a :code:`FlowModel`) for the representation of the deterministic part of the model equations. Check out :doc:`SDE model creation ` for more details. @@ -16,7 +16,7 @@ Simulation ---------- Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with an initial step size ``dt`` -using the ``mio::simulate_stochastic()`` function. This will run a simulation of type :code:`StochasticSimulation` that +using the ``mio::simulate_stochastic()`` function. This will run a simulation of type ``StochasticSimulation`` that saves the sizes of each compartment over time. The simulation uses an Euler-Maruyama scheme by default, so the step size does not change over time. diff --git a/docs/source/cpp/smm.rst b/docs/source/cpp/smm.rst index dcb156bc16..a478dac00f 100644 --- a/docs/source/cpp/smm.rst +++ b/docs/source/cpp/smm.rst @@ -179,7 +179,7 @@ are drawn. Then the time is advanced until the time point of the next event - wh infection state adoption - and the event takes places. The waiting times of the other events are updated and a new waiting time for the event that just happened is drawn. The simulation saves the system state in discrete time steps. -To simulate the model from ``t0`` to ``tmax`` with given step size ``dt``, a :code:`Simulation` has to be created and advanced +To simulate the model from ``t0`` to ``tmax`` with given step size ``dt``, a ``Simulation`` has to be created and advanced until ``tmax``. The step size is only used to regularly save the system state during the simulation. .. code-block:: cpp diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index efac8673ec..b034415e8e 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -71,7 +71,7 @@ An additional overview on MEmilio's elementary model structure is given by the f :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 :code:`InfectionStates`. For :code:`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. +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. diff --git a/docs/source/python/m-simulation_expanding_bindings.rst b/docs/source/python/m-simulation_expanding_bindings.rst index 4e28d01d7d..3f42b9546f 100755 --- a/docs/source/python/m-simulation_expanding_bindings.rst +++ b/docs/source/python/m-simulation_expanding_bindings.rst @@ -16,7 +16,7 @@ For a deeper look at common patterns you may encounter with the C++ MEmilio libr Expanding the simulation packages --------------------------------- -All bindings are located inside the folder `bindings `_. The simulation package is defined over modules. A main module `memilio.simulation` contains the general functionalities of the MEmilio library like the :code:`TimeSeries` class, different integrators, dampings or IO functions. +All bindings are located inside the folder `bindings `_. The simulation package is defined over modules. A main module `memilio.simulation` contains the general functionalities of the MEmilio library like the ``TimeSeries`` class, different integrators, dampings or IO functions. Additionally, each model is located into its own submodule, where model specific bindings are written. Python doesn't provide an interface for templates. Therefore, templated functions or classes need to be defined explicitly for each template argument that should be usable. diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index 8112862362..d673dff302 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -236,8 +236,8 @@ The integrator can be changed as the last parameter of the simulate function. Output and visualization ------------------------- -The result returned from the simulation is a :code:`TimeSeries` object containing the number of people per age group in each infection state at each time step. -The :code:`TimeSeries` provides alot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more +The result returned from the simulation is a ``TimeSeries`` object containing the number of people per age group in each infection state at each time step. +The ``TimeSeries`` provides alot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more pythonic interface. .. code-block:: python From 56039d12a03462c966de8c9f55890d65c2b930ee Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Wed, 22 Apr 2026 12:28:52 +0200 Subject: [PATCH 08/16] Apply suggestions from code review Co-authored-by: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> --- docs/source/cpp/models/glsecir.rst | 4 ++-- docs/source/cpp/models/isecir.rst | 4 ++-- docs/source/cpp/models/iseir.rst | 2 +- docs/source/cpp/models/lsecir.rst | 4 ++-- docs/source/cpp/models/lsecir2d.rst | 4 ++-- docs/source/cpp/models/osecirts.rst | 2 +- docs/source/cpp/models/osecirvvs.rst | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index e6bf29f047..7a18be9e6b 100644 --- a/docs/source/cpp/models/glsecir.rst +++ b/docs/source/cpp/models/glsecir.rst @@ -420,13 +420,13 @@ You can also specify a custom integrator: Output ------ -The simulation result is divided by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by `InfectionState`\s . +The simulation result is divided by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states . .. code-block:: cpp mio::TimeSeries population_no_subcompartments = model.calculate_compartments(result); -You can access the data in the `mio::TimeSeries` object as follows: +You can access the data in the ``TimeSeries`` object as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/isecir.rst b/docs/source/cpp/models/isecir.rst index fc93b78a96..8a9e17fa50 100644 --- a/docs/source/cpp/models/isecir.rst +++ b/docs/source/cpp/models/isecir.rst @@ -184,13 +184,13 @@ There are different options for initializing a fictional scenario. Regardless of In that case, we have three possible options for initializing: - - You can set the number of people in the `Susceptible` compartment at time :math:`t_0` via `populations`. Initial values of the other compartments are derived in the model before starting the simulation. + - You can set the number of people in the `Susceptible` compartment at time :math:`t_0` via ``populations``. Initial values of the other compartments are derived in the model before starting the simulation. .. code-block:: cpp model.populations.get_last_value()[(Eigen::Index)mio::isecir::InfectionState::Susceptible] = 1000.; - - You can set the number of people in the `Recovered` compartment at time :math:`t_0` via `populations`. Initial values of the other compartments are derived in the model before starting the simulation. + - You can set the number of people in the `Recovered` compartment at time :math:`t_0` via ``populations``. Initial values of the other compartments are derived in the model before starting the simulation. .. code-block:: cpp diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index 3e73c35706..910e3578aa 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -141,7 +141,7 @@ points. You can access the results as follows: Eigen::VectorX last_value = result.get_last_value(); ScalarType last_time = result.get_last_time(); -The order of the compartments follows the definition in the `InfectionState` enum. +The order of the compartments follows the definition in the ``InfectionState`` enum. You can print the simulation results as a formatted table: diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 864e5d32cc..3888d7d918 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -149,7 +149,7 @@ We start with constructing a vector ``initial_populations`` that we will pass on std::vector> initial_populations = {{750}, {30, 20}, {20, 10, 10}, {50}, {50}, {10, 10, 5, 3, 2}, {20}, {10}}; -We assert that the vector has the correct size by checking that the number of `InfectionState`\s and the numbers of subcompartments are correct. +We assert that the vector has the correct size by checking that the number of infection states and the numbers of subcompartments are correct. .. code-block:: cpp @@ -301,7 +301,7 @@ You can also specify a custom integrator: Output ------ -The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by `InfectionState`\s. +The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index 77904f13e5..e3f1da7acd 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -304,7 +304,7 @@ that contains a vector with initial values for the respective subcompartments. {0}, {0}, {100}, {0, 0}, {0, 0}, {0, 0}, {0}, {0}}; -We assert that the vector has the correct size by checking that the number of `InfectionState`\s and the numbers of subcompartments are correct. +We assert that the vector has the correct size by checking that the number of infection states and the numbers of subcompartments are correct. .. code-block:: cpp @@ -402,7 +402,7 @@ We can simulate the model from :math:`t_0` to :math:`t_{\max}` with initial step Output ------ -The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by `InfectionState`\s. +The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 68ced426c4..b8056d1311 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -384,7 +384,7 @@ You can print the simulation results as a formatted table: // Print results to console with default formatting result.print_table(); -The order of the compartments follows the definition in the `InfectionState` enum. +The order of the compartments follows the definition in the ``InfectionState`` enum. Additionally, you can export the results to a CSV file for further analysis or visualization: diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index b90578bb1b..004527fce9 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -402,7 +402,7 @@ You can print the simulation results as a formatted table: std::vector labels = {"S_naive", ... }; result.print_table(std::cout, labels); -The order of the compartments is as defined in the `InfectionState` enum. +The order of the compartments is as defined in the ``InfectionState`` enum. Additionally, you can export the results to a CSV file for further analysis or visualization: From 2b650e83049fb3d369c6af512d3794ceb2545eb1 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Wed, 22 Apr 2026 12:54:31 +0200 Subject: [PATCH 09/16] replace :code by `` --- docs/source/cpp/lct.rst | 6 +++--- docs/source/cpp/models/omseirs4.rst | 2 +- docs/source/cpp/models/osecir.rst | 6 +++--- docs/source/cpp/models/osecirts.rst | 4 ++-- docs/source/cpp/models/osecirvvs.rst | 2 +- docs/source/cpp/models/oseir.rst | 4 ++-- docs/source/cpp/models/oseirdb.rst | 4 ++-- docs/source/cpp/models/oseirv.rst | 4 ++-- docs/source/cpp/models/osir.rst | 2 +- docs/source/cpp/ode.rst | 8 ++++---- docs/source/cpp/ode_creation.rst | 10 +++++----- docs/source/cpp/sbml.rst | 2 +- docs/source/cpp/sde.rst | 6 +++--- docs/source/python/m-simulation_model_usage.rst | 4 ++-- 14 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index 805a6e071d..b560ec632a 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -47,8 +47,8 @@ The parameters of the model are defined as structs and are combined in a class ` We use different types of parameters to represent epidemiological parameters such as the mean stay times in a compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. -To model different contact rates between different sociodemographic groups, we use a parameter denoted ``ContactPatterns`` of type :code:`UncertainContactMatrix`. -The :code:`UncertainContactMatrix` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like +To model different contact rates between different sociodemographic groups, we use a parameter denoted ``ContactPatterns`` of type ``UncertainContactMatrix``. +The ``UncertainContactMatrix`` contains an arbitrary large set of contact matrices which can represent the different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. In the ``ContactPatterns``, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization and is reduced to one value if no stratification is used. @@ -61,7 +61,7 @@ Parameters can be accessed via ``model.parameters.get>()`` and set Initial conditions ------------------ -The initial conditions of the model are represented by a class :code:`LctPopulations` that gives the number of individuals in each sociodemographic group and each subcompartment for each ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each ``InfectionState`` and sociodemographic group must be set. +The initial conditions of the model are represented by a class ``LctPopulations`` that gives the number of individuals in each sociodemographic group and each subcompartment for each ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, the initial conditions for each ``InfectionState`` and sociodemographic group must be set. .. _Nonpharmaceutical Interventions LCT: diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 30402d1ee8..16f34451be 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -17,7 +17,7 @@ This implementation is designed for Respiratory Syncytial Virus (RSV) and is bas Infection States ---------------- -The model contains the following :code:`InfectionStates`: +The model contains the following ``InfectionState``\s: - `MaternalImmune` (M) - `S1`, `S2`, `S3`, `S4` (susceptible classes by infection history) diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 95f669d182..406da0939d 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -40,7 +40,7 @@ current implementation and detection is only modeled implicitly through detectio Infection State Transitions --------------------------- -The ODE-SECIR model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. +The ODE-SECIR model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, and hospitalizations. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: @@ -137,7 +137,7 @@ The model implements the following parameters: Initial conditions ------------------ -The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: +The initial conditions of the model are represented by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: .. code-block:: cpp @@ -259,7 +259,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d contact_dampings.push_back(social_events(start_lockdown, 0.6, 0.8)); contact_dampings.push_back(physical_distancing(start_lockdown, 0.4, 0.6)); -A more advanced structure to automatically activate interventions based on threshold criteria is given by :code:`DynamicNPIs`. +A more advanced structure to automatically activate interventions based on threshold criteria is given by ``DynamicNPIs``. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get activated for a defined duration when the threshold is exceeded. As above, different dampings `contact_dampings` can be assigned to different contact locations diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index b8056d1311..0b2c0554a9 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -66,7 +66,7 @@ The model extends the ODE-SECIRVVS model by adding temporary immunity states and Infection State Transitions --------------------------- -The ODE-SECIRTS model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. A key difference from the ODE-SECIRVVS model is that vaccinations in the ODE-SECIRTS model are implemented as flows within the ODE system rather than discrete events. +The ODE-SECIRTS model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. A key difference from the ODE-SECIRVVS model is that vaccinations in the ODE-SECIRTS model are implemented as flows within the ODE system rather than discrete events. The model has the following state trnsitions: @@ -234,7 +234,7 @@ The model includes all parameters from the ODE-SECIRVVS model as well as additio Initial conditions ------------------ -The initial conditions of the model are represented by the class :code:`Populations` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: +The initial conditions of the model are represented by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, the initial values for each compartment across all immunity levels have to be set. This can be done via: .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index 004527fce9..e72aa09be1 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -57,7 +57,7 @@ All compartments with the same base state (e.g., ExposedNaive, ExposedPartialImm Infection State Transitions --------------------------- -The ODE-SECIRVVS model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. The model follows the same flow pattern as the basic ODE-SECIR model but with three parallel sets of compartments representing different immunity levels. +The ODE-SECIRVVS model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. The model follows the same flow pattern as the basic ODE-SECIR model but with three parallel sets of compartments representing different immunity levels. The key characteristic of this model is that recovered individuals always end up in the improved immunity level, regardless of their starting immunity level. This represents the immunity gained after infection. diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index fdc757a5b2..6dddcc49b1 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -33,7 +33,7 @@ The model contains the following list of ``InfectionState``\s: Infection State Transitions --------------------------- -The ODE-SEIR model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. +The ODE-SEIR model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, and recoveries. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: @@ -90,7 +90,7 @@ The model implements the following parameters: Initial Conditions ------------------ -The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +The initial conditions of the model are defined by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index 0766192a64..7968955b6e 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -28,7 +28,7 @@ The model contains the following list of ``InfectionState``\s: Infection State Transitions --------------------------- -The ODE-SEIRDB model is implemented as a :code:`FlowModel`, which defines the derivatives of each flow between compartments. +The ODE-SEIRDB model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. This allows for explicit computation of new transmissions, infections, recoveries, deaths, and burials. Additionally, the aggregated compartment values can be computed with minimal overhead. The defined transitions `FromState, ToState` are: @@ -96,7 +96,7 @@ The model implements the following parameters: Initial Conditions ------------------ -The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +The initial conditions of the model are defined by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index d6680298ac..c50750aba2 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -31,7 +31,7 @@ The model contains the following ``InfectionState``\s: Infection State Transitions --------------------------- -The SEIRV model is implemented as a :code:`FlowModel`. Thus, in each time step, the flows (new infections, progressions, +The SEIRV model is implemented as a ``FlowModel``. Thus, in each time step, the flows (new infections, progressions, recoveries) are computed explicitly in addition to compartment values. The defined transitions `FromState, ToState` are: .. code-block:: RST @@ -123,7 +123,7 @@ differential infection hazards. Initial Conditions ------------------ -Initial conditions are handled via the :code:`Populations` class. Example for a single age group: +Initial conditions are handled via the ``Populations`` class. Example for a single age group: .. code-block:: cpp diff --git a/docs/source/cpp/models/osir.rst b/docs/source/cpp/models/osir.rst index fd439d7497..7d2b136d07 100644 --- a/docs/source/cpp/models/osir.rst +++ b/docs/source/cpp/models/osir.rst @@ -82,7 +82,7 @@ The model implements the following parameters. Initial conditions ------------------ -The initial conditions of the model are defined by the class :code:`Populations` which defines the number of individuals in +The initial conditions of the model are defined by the class ``Populations`` which defines the number of individuals in each sociodemographic group and ``InfectionState``. Before running a simulation, you need to set the initial values for each compartment: diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index a958a94d96..474054d83e 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -28,7 +28,7 @@ Every model contains a list of ``InfectionState``\s that define particular featu Infection state transitions --------------------------- -Our ODE-based models are either implemented as :code:`FlowModel` or as ``CompartmentalModel``. In a :code:`FlowModel`, flows +Our ODE-based models are either implemented as ``FlowModel`` or as ``CompartmentalModel``. In a ``FlowModel``, flows ``Flow`` between ``InfectionState``\s **State1** and **State2** are defined. Instead of a standard solution of an ODE-based model, this implementation additionally realizes the solution of the transitions or flows between states and directly enables users to access new transmissions or hospitalizations at any time point. @@ -49,7 +49,7 @@ We use different types of parameters to represent epidemiological parameters suc compartment or the contact rates between different age groups. Most model parameters are constants that describe pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, we -use a parameter denoted ``ContactPatterns`` of type :code:`UncertainContactMatrix`. The :code:`UncertainContactMatrix` contains +use a parameter denoted ``ContactPatterns`` of type ``UncertainContactMatrix``. The ``UncertainContactMatrix`` contains a set of contact matrices of arbitrary length which can represent different contact locations in the model like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example. In the ``ContactPatterns`` parameter, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic @@ -69,7 +69,7 @@ Parameters can get accessed via ``model.parameters.get>()`` and se Initial conditions ------------------ -The initial conditions of the model are represented by a class :code:`Populations` that gives the number of individuals in +The initial conditions of the model are represented by a class ``Populations`` that gives the number of individuals in each sociodemographic group and ``InfectionState``. For more details, see :doc:`Model Creation `. Before the simulation, set the initial conditions via ``model.populations[{AgeGroup::Age, InfectionState::State}] = value`` for each ``InfectionState`` and sociodemographic group. @@ -106,7 +106,7 @@ Simulation Once the model is set up, one can run a simple simulation from time ``t0`` to ``tmax`` with an initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type ``Simulation`` that saves the sizes of each compartment over time. -To also save the flow information, make sure to use a :code:`FlowModel` and run a simulation of type ``FlowSimulation`` with the ``mio::simulate_flows()`` function. +To also save the flow information, make sure to use a ``FlowModel`` and run a simulation of type ``FlowSimulation`` with the ``mio::simulate_flows()`` function. You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive integration scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. diff --git a/docs/source/cpp/ode_creation.rst b/docs/source/cpp/ode_creation.rst index 134d5b2b6e..5820756bbb 100644 --- a/docs/source/cpp/ode_creation.rst +++ b/docs/source/cpp/ode_creation.rst @@ -24,9 +24,9 @@ states **S**\usceptible, **I**\nfectious, **R**\ecovered, **D**\eceased, also ca How to implement an ODE model ----------------------------- -To define an ODE model in MEmilio, there are two options. You can define a ``CompartmentalModel`` or a :code:`FlowModel`, which +To define an ODE model in MEmilio, there are two options. You can define a ``CompartmentalModel`` or a ``FlowModel``, which use different methods to define the right-hand side of the mathematical model above. Both classes need definitions for -the infection states, population and parameters it uses. The :code:`FlowModel` additionally requires a list of flows. +the infection states, population and parameters it uses. The ``FlowModel`` additionally requires a list of flows. We start by creating a new directory for our model under "cpp/models", in this case we can call it "ode_sird". The name must be unique and start with "ode\_", so the type of model is obvious. The rest usually contains the compartments or @@ -106,7 +106,7 @@ The template :code:`FP` and the type :code:`UncertainValue` in these example :code:`FP` is a floating point type, usually :code:`double`. An :code:`UncertainValue` holds a value of type :code:`FP` as well as (optionally) a distribution to sample new values from, e.g. for a parameter study. -Finally, define a type :code:`Parameters` by listing all parameter structs as template arguments of a +Finally, define a type ``Parameters`` by listing all parameter structs as template arguments of a :code:`mio::ParameterSet`: .. code-block:: cpp @@ -115,7 +115,7 @@ Finally, define a type :code:`Parameters` by listing all parameter structs as te using Parameters = mio::ParameterSet, RecoveryRate, LethalityRate, ContactRate, TransmissionRisk>; -For more complex models, :code:`Parameters` allows passing arguments from its constructor to the :code:`get_default` +For more complex models, ``Parameters`` allows passing arguments from its constructor to the :code:`get_default` functions. Make sure that all of these functions take the exact types as function arguments that you want to pass to the constructor. @@ -131,7 +131,7 @@ The population will be stored in a vector, with a component for each infection s using Population = mio::Populations; Importantly, this class allows further stratifying the population vector, with the most common -example being adding :code:`mio::AgeGroups` to the template. +example being adding ``mio::AgeGroup``\s to the template. .. dropdown:: :fa:`gears` Expert's settings diff --git a/docs/source/cpp/sbml.rst b/docs/source/cpp/sbml.rst index 6e0cfe7c40..4a71edb230 100644 --- a/docs/source/cpp/sbml.rst +++ b/docs/source/cpp/sbml.rst @@ -65,7 +65,7 @@ The following features are the most important not supported features: - The ``^`` operator for exponentiation in functions. This will produce errors during compilation of the generated code, but can then be changed manually. As in an SBML file all species have to be given separately, it is unfortunately also not possible to automatically use -the :code:`Populations` in MEmilio to stratify the population into different compartments. +the ``Populations`` in MEmilio to stratify the population into different compartments. In general: Please check your models after the conversion to ensure that everything is working as expected. diff --git a/docs/source/cpp/sde.rst b/docs/source/cpp/sde.rst index 0875df4862..d2a516d041 100644 --- a/docs/source/cpp/sde.rst +++ b/docs/source/cpp/sde.rst @@ -7,8 +7,8 @@ additional function to compute the random noise, as can be seen :doc:`here `. -The class used for implementing SDE models is called :code:`StochasticModel`. It is derived from a ``CompartmentalModel`` -(or optionally a :code:`FlowModel`) for the representation of the deterministic part of the model equations. Check out +The class used for implementing SDE models is called ``StochasticModel``. It is derived from a ``CompartmentalModel`` +(or optionally a ``FlowModel``) for the representation of the deterministic part of the model equations. Check out :doc:`SDE model creation ` for more details. .. _Simulation SDE: @@ -20,7 +20,7 @@ using the ``mio::simulate_stochastic()`` function. This will run a simulation of saves the sizes of each compartment over time. The simulation uses an Euler-Maruyama scheme by default, so the step size does not change over time. -Flow information cannot be obtained even when the :code:`StochasticModel` is defined using a :code:`FlowModel`, as the +Flow information cannot be obtained even when the ``StochasticModel`` is defined using a ``FlowModel``, as the integrator may need to rescale results with respect to compartments to avoid negative values. List of models diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index d673dff302..2763ddaee2 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -180,7 +180,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d dampings.append(physical_distancing_home_school(start_spring, 0.4, 0.6)) dampings.append(physical_distancing_work_other(start_spring, 0.4, 0.6)) -A more advances structure to automatically activate interventions based on threshold criteria is given by :code:`DynamicNPIs`. +A more advances structure to automatically activate interventions based on threshold criteria is given by ``DynamicNPIs``. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get activated for a defined duration when the threshold is exceeded. As above, different dampings `dampings` can be assigned to different contact locations @@ -251,7 +251,7 @@ Additional resources --------------------- Further examples are provided at `examples/simulation `_. -They include the usage of a :code:`FlowModel`, introducing a graph model for regional differences or parameter studies for simulating under uncertainty. +They include the usage of a ``FlowModel``, introducing a graph model for regional differences or parameter studies for simulating under uncertainty. From 5ac65089bed8d162ab3606a712082d0a10c10de9 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Wed, 22 Apr 2026 13:07:13 +0200 Subject: [PATCH 10/16] code environ --- docs/source/cpp/glct.rst | 2 +- docs/source/cpp/io.rst | 36 +++++++------- docs/source/cpp/lct.rst | 2 +- docs/source/cpp/models/lsecir.rst | 2 +- docs/source/cpp/models/omseirs4.rst | 2 +- docs/source/cpp/models/oseirv.rst | 2 +- docs/source/cpp/performance_monitoring.rst | 58 +++++++++++----------- docs/source/cpp/smm.rst | 4 +- docs/source/cpp/temporal_hybrid.rst | 4 +- 9 files changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 4743ec24e4..eba11ca5a7 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -88,7 +88,7 @@ Output The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the -``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. +``TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. As adaptive step size methods are used by default, the output will not be available on equidistant time points like `dt` or days. To obtain outputs on days or user-defined time points, you can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``. diff --git a/docs/source/cpp/io.rst b/docs/source/cpp/io.rst index 466ade165a..9be7535bc7 100644 --- a/docs/source/cpp/io.rst +++ b/docs/source/cpp/io.rst @@ -329,7 +329,7 @@ Main functions and types ~~~~~~~~~~~~~~~~~~~~~~~~ - **Functions serialize and deserialize**: - Main entry points to the framework to write and read values, respectively. The functions expect an `IOContext` + Main entry points to the framework to write and read values, respectively. The functions expect an ``IOContext`` (see :ref:`Concepts` below) that stores the serialized data. (De-)serialization can be customized by providing a (de-)serialize_internal overload or a (de-)serialize member function for the type. See the section :ref:`Adding a new data type to be serialized` or the documentation for ``serialize`` and ``deserialize``. @@ -396,15 +396,15 @@ Concepts Stores data that describes serialized objects of any type in some unspecified format and provides structured access to the data for deserialization. Implementations of this concept may store the data in any format they want including binary. The data may also be written directly to disk. The context also keeps track - of errors. An IOContext object ``io`` allows the following operations: + of errors. An ``IOContext`` object ``io`` allows the following operations: - ``io.create_object("Type")``: - Returns an IOObject for the type called ``"Type"``. The IOObject (see below) allows adding data that describes + Returns an ``IOObject`` for the type called ``"Type"``. The ``IOObject`` (see below) allows adding data that describes the object to be serialized. The function must return something that can be assigned to a local - variable, e.g., a temporary or copyable function. IOObject may store references to the context internally, - so the lifetime of the local IOObject may not exceed the lifetime of the IOContext that created it. + variable, e.g., a temporary or copyable function. ``IOObject`` may store references to the context internally, + so the lifetime of the local ``IOObject`` may not exceed the lifetime of the ``IOContext`` that created it. - ``io.expect_object("Type")``: - Returns an IOObject for the type called ``"Type"``. The IOObject (see below) provides access to the data needed + Returns an ``IOObject`` for the type called ``"Type"``. The ``IOObject`` (see below) provides access to the data needed for deserialization. - ``io.flags()``: Returns the flags that determine the behavior of serialization; see IOFlags. @@ -413,7 +413,7 @@ Concepts check this manually but can be used to report the error faster and avoid expensive operations that would be wasted anyway. - ``io.set_error(s)`` with some ``IOStatus`` object: - Stores an error that was generated outside of the IOContext, e.g., if a value that was deserialized is outside an + Stores an error that was generated outside of the ``IOContext``, e.g., if a value that was deserialized is outside an allowed range. 2. **IOObject** @@ -421,21 +421,21 @@ Concepts Gives structured access to serialized data. During serialization, data can be added with ``add_...`` operations. During deserialization, data can be retrieved with ``expect_...`` operations. Data must be retrieved in the same order as it was added since, e.g., binary format does not allow lookup by key. The following operations are supported - for an IOObject ``obj``: + for an ``IOObject obj``: - ``obj.add_element("Name", t)``: - Stores an object ``t`` in the IOObject under the key "Name". If ``t`` is of basic type (i.e., int, string), - IOObject is expected to handle it directly. Otherwise, the object uses ``mio::serialize`` to get the data for ``t``. + Stores an object ``t`` in the ``IOObject`` under the key "Name". If ``t`` is of basic type (i.e., int, string), + ``IOObject`` is expected to handle it directly. Otherwise, the object uses ``mio::serialize`` to get the data for ``t``. - ``obj.add_list("Name", b, e)``: Stores the elements in the range represented by iterators ``b`` and ``e`` under the key "Name". The individual - elements are not named. The elements are either handled directly by the IOObject or using ``mio::serialize`` just + elements are not named. The elements are either handled directly by the ``IOObject`` or using ``mio::serialize`` just like ``add_element``. - ``obj.add_optional("Name", p)``: Stores the element pointed to by pointer ``p`` under the key "Name". The pointer may be null. Otherwise identical to add_element. - ``obj.expect_element("Name", Tag{})``: If an object of type T can be found under the key "Name" and can be deserialized, returns the object. Otherwise - returns an error. Analogously to serialization, the IOObject is expected to handle basic types directly and use + returns an error. Analogously to serialization, the ``IOObject`` is expected to handle basic types directly and use ``mio::deserialize`` otherwise. - ``obj.expect_list("Name", Tag{})``: If a list of objects of type T can be found under the key "Name" and can be deserialized, returns a range that can @@ -454,9 +454,9 @@ Errors are handled by returning error codes. The type ``IOStatus`` contains an e additional information. The type ``IOResult`` contains either a value or an ``IOStatus`` that describes an error. Operations that can fail return an ``IOResult`` where T is the type of the value that is produced by the operation if it is successful. Except where necessary because of dependencies, the MEmilio framework does neither throw nor catch any exceptions. -IOContext and IOObject implementations are expected to store errors. During serialization, ``add_...`` operations fail -without returning errors, but the error is stored in the IOObject and subsequent calls are usually no-ops. During -deserialization, the values produced must usually be used or inspected, so ``expect_...`` operations return an IOResult. +``IOContext`` and ``IOObject`` implementations are expected to store errors. During serialization, ``add_...`` operations fail +without returning errors, but the error is stored in the ``IOObject`` and subsequent calls are usually no-ops. During +deserialization, the values produced must usually be used or inspected, so ``expect_...`` operations return an ``IOResult``. The ``apply`` utility function provides a simple way to inspect the result of multiple ``expect_...`` operations and use the values if all are successful. See the documentation of ``IOStatus``, ``IOResult`` and ``apply`` below for more details. @@ -468,8 +468,8 @@ Adding a new data type to be serialized Serialization of a new type T can be customized by providing *either* member functions ``serialize`` and ``deserialize`` *or* free functions ``serialize_internal`` and ``deserialize_internal``. -The ``void serialize(IOContext& io)`` member function takes an IOContext and uses ``create_object`` and ``add_...`` -operations to add data. The static ``IOResult deserialize(IOContext& io)`` member function takes an IOContext and +The ``void serialize(IOContext& io)`` member function takes an ``IOContext`` and uses ``create_object`` and ``add_...`` +operations to add data. The static ``IOResult deserialize(IOContext& io)`` member function takes an ``IOContext`` and uses ``expect_...`` operations to retrieve the data. The ``apply`` utility function can be used to inspect the result of the ``expect_...`` operations and construct the object of type T. E.g.: @@ -498,7 +498,7 @@ for examples where this was done for, e.g., Eigen3 matrices and STL containers. Adding a new format ~~~~~~~~~~~~~~~~~~~ -Implement concepts IOContext and IOObject that provide the operations listed above. Your implementation should handle +Implement concepts ``IOContext`` and ``IOObject`` that provide the operations listed above. Your implementation should handle all built-in types as well as ``std::string``. It may handle other types (e.g., STL containers) as well if it can do so more efficiently than the provided general free functions. diff --git a/docs/source/cpp/lct.rst b/docs/source/cpp/lct.rst index b560ec632a..18d330915c 100644 --- a/docs/source/cpp/lct.rst +++ b/docs/source/cpp/lct.rst @@ -100,7 +100,7 @@ Output The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the -``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. +``TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. As adaptive step size methods are used by default, the output will not be available on equidistant time points like `dt` or days. To obtain outputs on days or user-defined time points, you can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``. diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 3888d7d918..5db18ab4a6 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -192,7 +192,7 @@ The initial populations in the model are set via: In addition to setting the initial populations manually, MEmilio provides two other ways of setting the initial populations: - The file `parameters_io `_ provides functionality to compute an initial value vector for the LCT-SECIR model based on reported data. -- The file `initializer_flows `_ provides functionality to compute an initial value vector for the LCT-SECIR model based on initial data in the form of a ``mio::TimeSeries`` of InfectionTransitions. For the concept of the InfectionTransitions or flows, see also the IDE-SECIR model. This method can be particularly useful if a comparison is to be made with an IDE model with matching initialization or if the reported data is in the form of flows. +- The file `initializer_flows `_ provides functionality to compute an initial value vector for the LCT-SECIR model based on initial data in the form of a ``TimeSeries`` of InfectionTransitions. For the concept of the InfectionTransitions or flows, see also the IDE-SECIR model. This method can be particularly useful if a comparison is to be made with an IDE model with matching initialization or if the reported data is in the form of flows. .. _Nonpharmaceutical Interventions: diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 16f34451be..d290f3d308 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -131,7 +131,7 @@ Run a standard simulation via: Output ------ -The output is a ``mio::TimeSeries`` of compartment sizes over time. Use ``print_table`` or export to CSV as needed. +The output is a ``TimeSeries`` of compartment sizes over time. Use ``print_table`` or export to CSV as needed. Notes ----- diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index c50750aba2..53d1d2733f 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -189,7 +189,7 @@ Flow simulation (when explicit flows are required): Output ------ -The result of a standard simulation is a ``mio::TimeSeries``: +The result of a standard simulation is a ``TimeSeries``: .. code-block:: cpp diff --git a/docs/source/cpp/performance_monitoring.rst b/docs/source/cpp/performance_monitoring.rst index 6edfb1c2b5..59cb97da99 100644 --- a/docs/source/cpp/performance_monitoring.rst +++ b/docs/source/cpp/performance_monitoring.rst @@ -36,11 +36,11 @@ Here we present MEmilio's own timing framework. Timer usage ~~~~~~~~~~~ -In this section we present how to use the AutoTimer class. This is the preferred way of using the timing framework, as +In this section we present how to use the ``AutoTimer`` class. This is the preferred way of using the timing framework, as the class takes care of running the timer, managing its lifetime for later evaluation, and ensuring thread safety with -OpenMP. The AutoTimer class uses some other classes that are listed and explained in :ref:`Classes and their responsibilities`. +OpenMP. The ``AutoTimer`` class uses some other classes that are listed and explained in :ref:`Classes and their responsibilities`. -An AutoTimer starts when it is created, and stops when it is destroyed - which usually happens at the next closing +An ``AutoTimer`` starts when it is created, and stops when it is destroyed - which usually happens at the next closing bracket :code:`}` or the next :code:`return`. This design, automating the starting and stopping of a timer, is intentionally limiting, because it helps to avoid several issues or mistakes that can arise when manually running timers. @@ -84,7 +84,7 @@ Timing in the library ^^^^^^^^^^^^^^^^^^^^^ Adding timers in the library is not much different to adding timers in main, but avoiding name collisions can be more -difficult. Hence, we use the optional second template argument of AutoTimer to specify its scope, as shown in the +difficult. Hence, we use the optional second template argument of ``AutoTimer`` to specify its scope, as shown in the following examples. To measure the time a class member function takes, add a timer like this: @@ -121,7 +121,7 @@ Or, when timing a free function: } // namespace foo -The first string given to AutoTimer is the timer's name, the second the scope it is in. They are used in combination +The first string given to ``AutoTimer`` is the timer's name, the second the scope it is in. They are used in combination to identify the timer, similar to a map key, so they must be unique. This can be effectively guaranteed, if the name matches the function and the scope contains all enclosing namespaces, like in the examples above. @@ -143,9 +143,9 @@ General recommendations - **Time entire functions.** Adding scopes for timing parts of main is fine, but you should avoid segmenting functions, either with scopes for - AutoTimer or with manually run timers. The reason for this is related less to timers and more to code design, because + ``AutoTimer`` or with manually run timers. The reason for this is related less to timers and more to code design, because if you can segment the function into multiple distinct parts, it is probably doing too many things, and should be - separated into smaller functions. Also, adding scope (and thus indents) for AutoTimer does make code slightly harder + separated into smaller functions. Also, adding scope (and thus indents) for ``AutoTimer`` does make code slightly harder to read. @@ -157,8 +157,8 @@ without having to plan around them. This means that accessing, starting and stop possible, while the interfaces of the classes or functions that are to be timed should not change. Additionally, the timer should work in parallel environments. -The solution to this is AutoTimer, whose usage was already shown above. There are, of course, some drawbacks. For -example, NamedTimer (the class used by AutoTimer) cannot be instantiated dynamically, as their name (and scope) have to +The solution to this is ``AutoTimer``, whose usage was already shown above. There are, of course, some drawbacks. For +example, ``NamedTimer`` (the class used by ``AutoTimer``) cannot be instantiated dynamically, as their name (and scope) have to be known at compile time. This also means that adding a lot of timers will impact the time it takes to compile the code, though a couple hundred timers should only take around an additional second. @@ -170,46 +170,46 @@ In this section, we describe the main components of the timing framework and how specific component, view its API documentation. - **BasicTimer**: - The foundation of the timing framework. BasicTimer is a very simple class, that defines the methods start, stop, + The foundation of the timing framework. ``BasicTimer`` is a very simple class, that defines the methods start, stop, reset, and get_elapsed_time. These are used by all other classes in this framework. It uses a wall clock, so if compute resources are shared with other tasks, the timing results may be higher than expected. In debug builds, it will log errors whenever a member function was used incorrectly, e.g. when start was called twice. - **TimerRegistration**: This simple struct is used to keep track of timers and some additional information, but does not manage their storage. - It consists of two strings for name and scope, a reference to a BasicTimer, and a thread id. The thread id specifies + It consists of two strings for name and scope, a reference to a ``BasicTimer``, and a thread id. The thread id specifies which thread the timer is used in, which could differ from the thread it is created by. - **Printer**: - A pure virtual class defining a print method to evaluate and output timing results via a list of TimerRegistrations. - Implemented by TablePrinter and ListPrinter. + A pure virtual class defining a print method to evaluate and output timing results via a list of ``TimerRegistration``s. + Implemented by ``TablePrinter`` and ``ListPrinter``. - **TimerRegistrar**: - Keeps track of timers via a list of TimerRegistrations, and holds a Printer that can be used to display all - registered timers after the end of main. Timers can be registered by passing a TimerRegistration to its add_timer + Keeps track of timers via a list of ``TimerRegistration``s, and holds a ``Printer`` that can be used to display all + registered timers after the end of main. Timers can be registered by passing a ``TimerRegistration`` to its add_timer method. Uses a singleton pattern to provide global access to the same object, that is, the only way to obtain a TimerRegistrar object is by using its get_instance method, which returns a reference to a static object. Importantly, this class does not manage or own timer objects, and there is intentionally no methods that retrieve or delete - TimerRegistrations. + ``TimerRegistration``s. - **NamedTimer**: - Inherits from BasicTimer, with the main purpose of managing the lifetime, access, and registration of a timer. + Inherits from ``BasicTimer``, with the main purpose of managing the lifetime, access, and registration of a timer. This is done using a singleton pattern, similar to TimerRegistrar, but the reference returned by get_instance is - thread_local as well as static. The template parameters Name and Scope allow using more than one NamedTimer, since + thread_local as well as static. The template parameters Name and Scope allow using more than one ``NamedTimer``, since different template arguments define a different type. This effectively creates a global compile-time map, mapping a - Name and Scope to a BasicTimer. Additionally, the NamedTimer registers itself automatically, and will only be + Name and Scope to a ``BasicTimer``. Additionally, the ``NamedTimer`` registers itself automatically, and will only be destroyed after the TimerRegistrar. - **AutoTimer**: Automates running an existing timer, by calling start in its constructor, and stop in its destructor. The timer used - can be either specified via the Name and Scope template, fetching the corresponding NamedTimer internally, or by - passing an lvalue reference to a BasicTimer. + can be either specified via the Name and Scope template, fetching the corresponding ``NamedTimer`` internally, or by + passing an lvalue reference to a ``BasicTimer``. -Using NamedTimer and BasicTimer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using ``NamedTimer`` and ``BasicTimer`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Preferably, you should use AutoTimer where possible, as its limiting design helps to avoid common errors, for example -with parallel regions. But, if you have to, you can use a NamedTimer directly without any extra work: +Preferably, you should use ``AutoTimer`` where possible, as its limiting design helps to avoid common errors, for example +with parallel regions. But, if you have to, you can use a ``NamedTimer`` directly without any extra work: .. code-block:: cpp @@ -229,11 +229,11 @@ with parallel regions. But, if you have to, you can use a NamedTimer directly wi } // namespace foo -This will behave exactly like the AutoTimer in the example above, while also allowing you to use the reset or -get_elapsed_time methods defined by BasicTimer. +This will behave exactly like the ``AutoTimer`` in the example above, while also allowing you to use the reset or +get_elapsed_time methods defined by ``BasicTimer``. -Last but not least, you can also use a BasicTimer directly. This means that you will have to manually take care of -the timer object, threading and evaluation. If you add such a BasicTimer to the TimerRegistrar, you will probably need +Last but not least, you can also use a ``BasicTimer`` directly. This means that you will have to manually take care of +the timer object, threading and evaluation. If you add such a ``BasicTimer`` to the TimerRegistrar, you will probably need to disable the final timer summary, and call print manually. Of course, you can also make your own list of registrations and use a Printer directly. diff --git a/docs/source/cpp/smm.rst b/docs/source/cpp/smm.rst index a478dac00f..334ea4e819 100644 --- a/docs/source/cpp/smm.rst +++ b/docs/source/cpp/smm.rst @@ -197,7 +197,7 @@ until ``tmax``. The step size is only used to regularly save the system state du Output ------ -Subpopulations stratified by region and infection state are saved in a ``mio::TimeSeries`` object which can be accessed and printed as follows: +Subpopulations stratified by region and infection state are saved in a ``TimeSeries`` object which can be accessed and printed as follows: .. code-block:: cpp @@ -207,7 +207,7 @@ Subpopulations stratified by region and infection state are saved in a ``mio::Ti //Print result object to console. Infection state "Xi" with i=0,1 is the number of agents having infection state X in region i result.print_table({"S0", "E0", "C0", "I0", "R0", "D0", "S1", "E1", "C1", "I1", "R1", "D1"}) -If one wants to interpolate the aggregated results to a ``mio::TimeSeries`` containing only full days, this can be done by +If one wants to interpolate the aggregated results to a ``TimeSeries`` containing only full days, this can be done by .. code-block:: cpp diff --git a/docs/source/cpp/temporal_hybrid.rst b/docs/source/cpp/temporal_hybrid.rst index 46900751d7..abf03ada6c 100644 --- a/docs/source/cpp/temporal_hybrid.rst +++ b/docs/source/cpp/temporal_hybrid.rst @@ -112,7 +112,7 @@ Before advancing the simulation until `tmax`, a switching condition has to be de double tmax = 30.; hybrid_sim.advance(tmax, condition); -The result ``mio::TimeSeries`` objects of the two models used (which are returned by the above defined result functions) can be accessed and printed via +The result ``TimeSeries`` objects of the two models used (which are returned by the above defined result functions) can be accessed and printed via .. code-block:: cpp @@ -123,7 +123,7 @@ The result ``mio::TimeSeries`` objects of the two models used (which are returne ts_abm.print_table({"S", "E", "Ins", "Isy", "Isev", "Icri", "R", "D"}); ts_ode.print_table({"S", "E", "Ins", "Ins_confirmed", "Isy", "Isy_confirmed", "Isev", "Icri", "R", "D"}); -Additionally, the individual results of the models can be merged to one joint ``mio::TimeSeries``: +Additionally, the individual results of the models can be merged to one joint ``TimeSeries``: .. code-block:: cpp From a5be547eca56f236a0bcfa4aaa06c34ec4ca3a1f Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Thu, 23 Apr 2026 09:16:00 +0200 Subject: [PATCH 11/16] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/source/cpp/io.rst | 2 +- docs/source/cpp/lct_creation.rst | 2 +- docs/source/cpp/models/iseir.rst | 2 +- docs/source/cpp/models/lsecir.rst | 2 +- docs/source/cpp/models/lsecir2d.rst | 2 +- docs/source/cpp/models/osecirts.rst | 2 +- docs/source/getting_started.rst | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/cpp/io.rst b/docs/source/cpp/io.rst index 9be7535bc7..1fa35cc835 100644 --- a/docs/source/cpp/io.rst +++ b/docs/source/cpp/io.rst @@ -10,7 +10,7 @@ All aggregated models save their results in a ``TimeSeries`` that contains all s point, see :doc:`data_types` for a description of the ``TimeSeries`` data type. The time series can be printed to the terminal with the :code:`TimeSeries::print_table()` function and exported to a CSV file using :code:`TimeSeries::export_csv`. As e.g. for the ODE-based models adaptive step size methods are used, the time series will not be necessarily available -on equidistant time points or days. To obtain a ``TimeSeries`` interpolated on days or user-defined time points, +on equidistant time points or days. To obtain a ``TimeSeries`` interpolated on days or user-defined time points, the :code:`mio::interpolate_simulation_result()` can be used. This document describes utilities for reading and writing data from and to files in different formats, in cases where diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index 782413f7ec..a83162d3b8 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -178,7 +178,7 @@ The function ``get_derivatives()`` evaluates the right-hand-side of the ODE :mat It is also useful to implement the following methods within the model: - A function ``calculate_compartments()`` that accumulates the ``TimeSeries`` containing simulation results that are divided -into subcompartments to a ``TimeSeries`` that conatins the simulation results according to the infection states without subcompartments. +into subcompartments to a ``TimeSeries`` that contains the simulation results according to the infection states without subcompartments. For an example, see the implementation within the LCT-SECIR model. - A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. For an example, see the implementation within the LCT-SECIR model. diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index 910e3578aa..e2516a2400 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -125,7 +125,7 @@ The values of the remaining compartments :math:`E`, :math:`I` and :math:`R` are Output ------ -The output of the simulationis a ``TimeSeries`` object containing the size of the compartments at all time +The output of the simulation is a ``TimeSeries`` object containing the size of the compartments at all time points. You can access the results as follows: .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 5db18ab4a6..3dafb697b4 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -301,7 +301,7 @@ You can also specify a custom integrator: Output ------ -The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. +The simulation result is stratified by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. .. code-block:: cpp diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index e3f1da7acd..02b7a5a6a6 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -402,7 +402,7 @@ We can simulate the model from :math:`t_0` to :math:`t_{\max}` with initial step Output ------ -The simulation result is stratefied by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. +The simulation result is stratified by subcompartments. The function ``calculate_compartments()`` aggregates the subcompartments by infection states. .. code-block:: cpp diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 0b2c0554a9..735077abd2 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -68,7 +68,7 @@ Infection State Transitions The ODE-SECIRTS model is implemented as a ``FlowModel``, which defines the derivatives of each flow between compartments. A key difference from the ODE-SECIRVVS model is that vaccinations in the ODE-SECIRTS model are implemented as flows within the ODE system rather than discrete events. -The model has the following state trnsitions: +The model has the following state transitions: .. code-block:: RST diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index b034415e8e..ed3ea87c4b 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -71,7 +71,7 @@ An additional overview on MEmilio's elementary model structure is given by the f :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. +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 ``InfectionState``\s. For ``FlowModel``\s (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. From e0d444ad9516a139a9b5b2865afa37d5113d49a6 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Thu, 23 Apr 2026 09:17:12 +0200 Subject: [PATCH 12/16] typos --- docs/source/python/m-simulation_model_usage.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index 2763ddaee2..e49b09f581 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -180,7 +180,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d dampings.append(physical_distancing_home_school(start_spring, 0.4, 0.6)) dampings.append(physical_distancing_work_other(start_spring, 0.4, 0.6)) -A more advances structure to automatically activate interventions based on threshold criteria is given by ``DynamicNPIs``. +A more advanced structure to automatically activate interventions based on threshold criteria is given by ``DynamicNPIs``. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get activated for a defined duration when the threshold is exceeded. As above, different dampings `dampings` can be assigned to different contact locations @@ -237,7 +237,7 @@ Output and visualization ------------------------- The result returned from the simulation is a ``TimeSeries`` object containing the number of people per age group in each infection state at each time step. -The ``TimeSeries`` provides alot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more +The ``TimeSeries`` provides a lot of interfaces to interact with it, but can also be transformed into a multidimensional numpy matrix for a more pythonic interface. .. code-block:: python From fb0ddb027f6807447a1b4ad576bf690049a80da6 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:14:00 +0200 Subject: [PATCH 13/16] Apply suggestions from code review Co-authored-by: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> --- docs/source/cpp/lct_creation.rst | 6 ++++-- docs/source/cpp/ode.rst | 2 +- docs/source/cpp/ode_creation.rst | 2 +- docs/source/cpp/performance_monitoring.rst | 6 +++--- docs/source/python/m-simulation_model_usage.rst | 6 +++--- 5 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index a83162d3b8..03fc5e793e 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -179,9 +179,11 @@ It is also useful to implement the following methods within the model: - A function ``calculate_compartments()`` that accumulates the ``TimeSeries`` containing simulation results that are divided into subcompartments to a ``TimeSeries`` that contains the simulation results according to the infection states without subcompartments. -For an example, see the implementation within the LCT-SECIR model. +For an example, see the implementation within the :CPP-API:`LCT-SECIR model `. + + - A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. -For an example, see the implementation within the LCT-SECIR model. +For an example, see the implementation within the :CPP-API:`LCT-SECIR model `.. .. dropdown:: :fa:`gears` Expert's settings diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 474054d83e..a316eb911e 100644 --- a/docs/source/cpp/ode.rst +++ b/docs/source/cpp/ode.rst @@ -29,7 +29,7 @@ Infection state transitions --------------------------- Our ODE-based models are either implemented as ``FlowModel`` or as ``CompartmentalModel``. In a ``FlowModel``, flows -``Flow`` between ``InfectionState``\s **State1** and **State2** are defined. Instead of a standard +``Flow`` between ``InfectionState``\s ``State1`` and ``State2`` are defined. Instead of a standard solution of an ODE-based model, this implementation additionally realizes the solution of the transitions or flows between states and directly enables users to access new transmissions or hospitalizations at any time point. The simpler class ``CompartmentalModel`` only considers the states of the system and not the flows. diff --git a/docs/source/cpp/ode_creation.rst b/docs/source/cpp/ode_creation.rst index 5820756bbb..5fa3d6301a 100644 --- a/docs/source/cpp/ode_creation.rst +++ b/docs/source/cpp/ode_creation.rst @@ -131,7 +131,7 @@ The population will be stored in a vector, with a component for each infection s using Population = mio::Populations; Importantly, this class allows further stratifying the population vector, with the most common -example being adding ``mio::AgeGroup``\s to the template. +example being adding ``AgeGroup``\s to the template. .. dropdown:: :fa:`gears` Expert's settings diff --git a/docs/source/cpp/performance_monitoring.rst b/docs/source/cpp/performance_monitoring.rst index 59cb97da99..79deff659c 100644 --- a/docs/source/cpp/performance_monitoring.rst +++ b/docs/source/cpp/performance_monitoring.rst @@ -188,17 +188,17 @@ specific component, view its API documentation. Keeps track of timers via a list of ``TimerRegistration``s, and holds a ``Printer`` that can be used to display all registered timers after the end of main. Timers can be registered by passing a ``TimerRegistration`` to its add_timer method. Uses a singleton pattern to provide global access to the same object, that is, the only way to obtain a - TimerRegistrar object is by using its get_instance method, which returns a reference to a static object. Importantly, + ``TimerRegistrar`` object is by using its get_instance method, which returns a reference to a static object. Importantly, this class does not manage or own timer objects, and there is intentionally no methods that retrieve or delete ``TimerRegistration``s. - **NamedTimer**: Inherits from ``BasicTimer``, with the main purpose of managing the lifetime, access, and registration of a timer. - This is done using a singleton pattern, similar to TimerRegistrar, but the reference returned by get_instance is + This is done using a singleton pattern, similar to ``TimerRegistrar``, but the reference returned by get_instance is thread_local as well as static. The template parameters Name and Scope allow using more than one ``NamedTimer``, since different template arguments define a different type. This effectively creates a global compile-time map, mapping a Name and Scope to a ``BasicTimer``. Additionally, the ``NamedTimer`` registers itself automatically, and will only be - destroyed after the TimerRegistrar. + destroyed after the ``TimerRegistrar``. - **AutoTimer**: Automates running an existing timer, by calling start in its constructor, and stop in its destructor. The timer used diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index e49b09f581..28cb27436d 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -92,8 +92,8 @@ Nonpharmaceutical interventions One important topic of interest in infectious disease dynamics are nonpharmaceutical interventions (NPIs), which aim to mitigate the dynamics of the disease spread. In our models, NPIs are implemented through dampings to the contact matrix. These dampings reduce the contact rates between different groups to simulate interventions. -The basic contact matrix is defined through its baseline `ContactPatterns` (and a potential minimum pattern which does not need to be set and which is not used by default). -For a model with a single age group, the contact matrix is simply value, a 1x1 matrix and `num_groups=1`. For `num_groups>1`, the contact matrix is a square matrix of size `num_groups x num_groups`, +The basic contact matrix is defined through its baseline ``ContactPatterns`` (and a potential minimum pattern which does not need to be set and which is not used by default). +For a model with a single age group, the contact matrix is simply value, a 1x1 matrix and ``num_groups=1``. For ``num_groups>1``, the contact matrix is a square matrix of size ``num_groups x num_groups``, where each entry represents the contact frequency between two age groups. .. code-block:: python @@ -183,7 +183,7 @@ A complex lockdown scenario with multiple interventions starting on a specific d A more advanced structure to automatically activate interventions based on threshold criteria is given by ``DynamicNPIs``. Dynamic NPIs can be configured to trigger when the number of symptomatic infected individuals exceeds a certain relative threshold in the population. In contrast to static NPIs which are active as long as no other NPI gets implemented, dynamic NPIs are checked at regular intervals and get -activated for a defined duration when the threshold is exceeded. As above, different dampings `dampings` can be assigned to different contact locations +activated for a defined duration when the threshold is exceeded. As above, different dampings ``dampings`` can be assigned to different contact locations and are then triggered all at once the threshold is exceeded. The following example shows how to set up dynamic NPIs based on the number of 200 symptomatic infected individuals per 100,000 population. It will be active for at least 14 days and checked every 3 days. If the last check after day 14 is negative, the NPI will be deactivated. From 7b58a754fdf4a5f4882eee1edd3ec11e7bdb9a45 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 23 Apr 2026 12:57:23 +0200 Subject: [PATCH 14/16] FIX: typo --- docs/source/development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index 189a4095f0..55e325f884 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -369,7 +369,7 @@ rst files can be generated as in the following examples: :CPP-API:`mio::osir` :CPP-API:`mio::geo::Distance::kilometers` :CPP-API:`Graph Constructor ` - .. opening angle brackets in the function defintion need to be escaped, the following line is also sensitive to the space between the closing brackets + .. opening angle brackets in the function definition need to be escaped, the following line is also sensitive to the space between the closing brackets :CPP-API:`mio::details::SimulationBase\< FP, M, SystemIntegrator\< FP, Integrands... > >` From 930748719562754e9c05065e8b18c6d49254114a Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 23 Apr 2026 13:07:54 +0200 Subject: [PATCH 15/16] FIX: repair formatting and links --- docs/source/cpp/lct_creation.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/source/cpp/lct_creation.rst b/docs/source/cpp/lct_creation.rst index 03fc5e793e..2d5bf4a4b6 100644 --- a/docs/source/cpp/lct_creation.rst +++ b/docs/source/cpp/lct_creation.rst @@ -177,13 +177,8 @@ The function ``get_derivatives()`` evaluates the right-hand-side of the ODE :mat It is also useful to implement the following methods within the model: -- A function ``calculate_compartments()`` that accumulates the ``TimeSeries`` containing simulation results that are divided -into subcompartments to a ``TimeSeries`` that contains the simulation results according to the infection states without subcompartments. -For an example, see the implementation within the :CPP-API:`LCT-SECIR model `. - - -- A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. -For an example, see the implementation within the :CPP-API:`LCT-SECIR model `.. +- A function ``calculate_compartments()`` that accumulates the ``TimeSeries`` containing simulation results that are divided into subcompartments to a ``TimeSeries`` that contains the simulation results according to the infection states without subcompartments. For an example, see the implementation within the :CPP-API:`LCT-SECIR model `. +- A function ``check_constraints()`` that checks that the model satisfies sensible constraints regarding parameters and initial conditions. For an example, see the implementation within the :CPP-API:`LCT-SECIR model `. .. dropdown:: :fa:`gears` Expert's settings From d45a3fdcbddce54ce750f108a7f9a9a0c8ad9d22 Mon Sep 17 00:00:00 2001 From: jubicker <113909589+jubicker@users.noreply.github.com> Date: Thu, 23 Apr 2026 13:16:03 +0200 Subject: [PATCH 16/16] [ci skip] typ --- docs/source/python/m-simulation_model_usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/python/m-simulation_model_usage.rst b/docs/source/python/m-simulation_model_usage.rst index 28cb27436d..5daef8d840 100755 --- a/docs/source/python/m-simulation_model_usage.rst +++ b/docs/source/python/m-simulation_model_usage.rst @@ -195,7 +195,7 @@ It will be active for at least 14 days and checked every 3 days. If the last che dampings = [] # increased from [0.4, 0.6] in Nov dampings.append(contacts_at_home(0, 0.6, 0.8)) - dampings.append(school_closure(0, 0.25, 0.25)) # see paper + dampings.append(school_closure(0, 0.25, 0.25)) #see paper dampings.append(home_office(0, 0.2, 0.3)) dampings.append(social_events(0, 0.6, 0.8)) dampings.append(social_events_work(0, 0.1, 0.2))