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 57fb3a2471..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 **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 ``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 **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 **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 ``mio::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 ``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 05e6ef7c34..eba11ca5a7 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 ``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 **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 ``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 **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 **ContactPatterns** of type **UncertainContactMatrix**. The **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 **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 **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 ``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 **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 ``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,17 +78,17 @@ 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 ``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 ``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/ide.rst b/docs/source/cpp/ide.rst index e09b0d06d0..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 **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 **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 ``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,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 ``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 ``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 +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`. @@ -74,10 +73,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. @@ -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 ``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}`. @@ -117,7 +116,7 @@ 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 +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()``. diff --git a/docs/source/cpp/io.rst b/docs/source/cpp/io.rst index b43a391e37..1fa35cc835 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 @@ -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 c13d3fbf7f..18d330915c 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 ``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 ``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 **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 **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 ``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`. +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 **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: 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 ``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,17 +90,17 @@ 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 ``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 ``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/lct_creation.rst b/docs/source/cpp/lct_creation.rst index 5a9a0f0f17..2d5bf4a4b6 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 **CompartmentalModel** in the file "model.h": +Now we can define the model as a ``CompartmentalModel`` in the file "model.h": .. code-block:: cpp @@ -177,11 +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. -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. +- 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 diff --git a/docs/source/cpp/mobility_based_abm.rst b/docs/source/cpp/mobility_based_abm.rst index 090c0fd8bb..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 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 f7a1072fa8..7a18be9e6b 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 ``InfectionState``\s: .. code-block:: 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 9df8194094..8a9e17fa50 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 ``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 ``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. +``AgeGroup`` but can also be used for other interpretations. Parameters @@ -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 @@ -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 ``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 `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 **InfectionState** and **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 `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 d1b6714848..e2516a2400 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/ > 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 @@ -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: @@ -301,13 +301,13 @@ 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 stratified 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/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index ad96e8cda6..02b7a5a6a6 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 **InfectionState**\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: 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,13 +402,13 @@ 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 stratified 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/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 17b7cb216a..d290f3d308 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 ``InfectionState``\s: - `MaternalImmune` (M) - `S1`, `S2`, `S3`, `S4` (susceptible classes by infection history) @@ -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 ``CompartmentalModel``, which defines the derivative of the aggregated compartment values in time. The following transitions occur: - Births enter M and some enter S1 @@ -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/osecir.rst b/docs/source/cpp/models/osecir.rst index 50f651c698..406da0939d 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 **InfectionState**\s: +The model contains the following list of ``InfectionState``\s: .. code-block:: 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 ``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: @@ -67,7 +67,7 @@ Sociodemographic Stratification ------------------------------- In the ODE-SECIR 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, +``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 **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 **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 @@ -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 ``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 ``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..735077abd2 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 ``InfectionState``\s: .. code-block:: RST @@ -66,9 +66,9 @@ 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 ``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 @@ -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. +``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 ``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 `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 ``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 @@ -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: @@ -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..e72aa09be1 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 ``InfectionState``\s: .. code-block:: 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 ``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. @@ -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 ``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. +``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 ``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 `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 ``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 @@ -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: diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index a22075ea7d..6dddcc49b1 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 ``InfectionState``\s: .. code-block:: 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 ``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: @@ -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 +``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 ``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 @@ -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 ``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 `mio::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 809dbda49c..7968955b6e 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 ``InfectionState``\s: .. code-block:: 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 ``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: @@ -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 +``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 ``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 @@ -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 ``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 `mio::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 b0bff91a3b..53d1d2733f 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 ``InfectionState``\s: .. code-block:: 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 ``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 @@ -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 ``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 ``Populations`` class. Example for a single age group: .. code-block:: cpp @@ -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/models/osir.rst b/docs/source/cpp/models/osir.rst index c7d0ce4614..7d2b136d07 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 ``InfectionState``\s: .. code-block:: 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 ``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 -**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: @@ -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 ``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 diff --git a/docs/source/cpp/ode.rst b/docs/source/cpp/ode.rst index 07ad5fb76d..a316eb911e 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 ``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 **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 ``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. -The simpler class **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 **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 **ContactPatterns** of type **UncertainContactMatrix**. The **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 +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`. @@ -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 ``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. +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 **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 ``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 **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 ``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. 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 **Simulation** is a ``mio::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 -**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 e8f305e65f..5fa3d6301a 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 ``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 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 ``AgeGroup``\s to the template. .. dropdown:: :fa:`gears` Expert's settings @@ -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 ``CompartmentalModel`` class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now we can define the model: diff --git a/docs/source/cpp/performance_monitoring.rst b/docs/source/cpp/performance_monitoring.rst index 6edfb1c2b5..79deff659c 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, + ``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. - 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 + 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 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. + 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/sbml.rst b/docs/source/cpp/sbml.rst index 8fd9ca576b..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 **Population** 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 65bccb9872..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 **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 ``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: @@ -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 ``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 ``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/cpp/smm.rst b/docs/source/cpp/smm.rst index bf37788a75..334ea4e819 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 ``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 @@ -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 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... > >` diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 1031123289..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. diff --git a/docs/source/python/m-simulation_expanding_bindings.rst b/docs/source/python/m-simulation_expanding_bindings.rst index 6a6f8f8191..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 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. @@ -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..5daef8d840 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 @@ -180,10 +180,10 @@ 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 +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. @@ -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)) @@ -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 ``TimeSeries`` object containing the number of people per age group in each infection state at each time step. +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 @@ -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 ``FlowModel``, introducing a graph model for regional differences or parameter studies for simulating under uncertainty.