1224 extend read the docs documentation (#1231)

Co-authored-by: jubicker <[email protected]>
Co-authored-by: HenrZu <[email protected]>
Co-authored-by: Martin Joachim Kühn <[email protected]>
Co-authored-by: Anna Wendler <[email protected]>
Co-authored-by: MaxBetzDLR <[email protected]>
Co-authored-by: Sascha Korf <[email protected]>
Co-authored-by: reneSchm <[email protected]>

Author: 8 people

README.md

@@ -7,11 +7,19 @@
 
 MEmilio implements various models for infectious disease dynamics, from simple compartmental models through Integro-Differential equation-based models to agent- or individual-based models. Its modular design allows the combination of different models with different mobility patterns. Through efficient implementation and parallelization, MEmilio brings cutting edge and compute intensive epidemiological models to a large scale, enabling a precise and high-resolution spatiotemporal infectious disease dynamics. MEmilio will be extended continuously. It is available open-source and we encourage everyone to make use of it.
 
-If you use MEmilio, please cite our works:
+If you use MEmilio, please cite our work
 
-- Kühn, Martin Joachim und Abele, Daniel und Kerkmann, David und Korf, Sascha Alexander und Zunker, Henrik und Wendler, Anna Clara und Bicker, Julia und Nguyen, Dang Khoa und Klitz, Margrit und Koslow, Wadim und Siggel, Martin und Kleinert, Jan und Rack, Kathrin und Binder, Sebastian und Plötzke, Lena und Schmieding, René und Lenz, Patrick und Betz, Maximilian Franz und Lutz, Annette und Gerstein, Carlotta und Schmidt, Agatha und Meyer-Hermann, Michael und Basermann, Achim  (2022) MEmilio - a high performance Modular EpideMIcs simuLatIOn software (2022). https://github.com/SciCompMod/memilio, https://elib.dlr.de/192140/.
+- Kühn, Martin Joachim et al. (2024). *MEmilio - a High Performance Modular Epidemics Simulation Software (2022)*. Available at `https://github.com/SciCompMod/memilio` and `https://elib.dlr.de/209739/`.
 
-- Koslow W, Kühn MJ, Binder S, Klitz M, Abele D, et al. (2022) Appropriate relaxation of non-pharmaceutical interventions minimizes the risk of a resurgence in SARS-CoV-2 infections in spite of the Delta variant. PLOS Computational Biology 18(5): e1010054. https://doi.org/10.1371/journal.pcbi.1010054
+and, in particular, for
+
+- Ordinary differential equation-based (ODE) and Graph-ODE models: Zunker H, Schmieding R, Kerkmann D, Schengen A, Diexer S, et al. (2024). *Novel travel time aware metapopulation models and multi-layer waning immunity for late-phase epidemic and endemic scenarios*. *PLOS Computational Biology* 20(12): e1012630. `https://doi.org/10.1371/journal.pcbi.1012630`
+- Integro-differential equation-based (IDE) models: Wendler AC, Plötzke L, Tritzschak H, Kühn MJ. (2024). *A nonstandard numerical scheme for a novel SECIR integro differential equation-based model with nonexponentially distributed stay times*. Submitted for publication. `https://arxiv.org/abs/2408.12228`
+- Agent-based models (ABMs): Kerkmann D, Korf S, Nguyen K, Abele D, Schengen A, et al. (2024). *Agent-based modeling for realistic reproduction of human mobility and contact behavior to evaluate test and isolation strategies in epidemic infectious disease spread*. arXiv. `https://arxiv.org/abs/2410.08050`
+- Hybrid agent-metapopulation-based models: Bicker J, Schmieding R, Meyer-Hermann M, Kühn MJ. (2025). *Hybrid metapopulation agent-based epidemiological models for efficient insight on the individual scale: A contribution to green computing*. *Infectious Disease Modelling* 10(2): 571-590. `https://doi.org/10.1016/j.idm.2024.12.015`
+- Graph Neural Networks: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2024). *Towards Graph Neural Network Surrogates Leveraging Mechanistic Expert Knowledge for Pandemic Response*. arXiv. `https://arxiv.org/abs/2411.06500`
+- ODE-based models with Linear Chain Trick: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2024). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. Submitted for publication. `https://doi.org/10.48550/arXiv.2412.09140`
+- Behavior-based ODE models: Zunker H, Dönges P, Lenz P, Contreras S, Kühn MJ. (2025). *Risk-mediated dynamic regulation of effective contacts de-synchronizes outbreaks in metapopulation epidemic models*. arXiv. `https://arxiv.org/abs/2502.14428`
 
 **Getting started**
 

cpp/models/sde_seirvv/model.h

@@ -59,114 +59,175 @@ class Model : public FlowModel<ScalarType, InfectionState, Populations<ScalarTyp
     void get_flows(Eigen::Ref<const Eigen::VectorX<ScalarType>> pop, Eigen::Ref<const Eigen::VectorX<ScalarType>> y,
                    ScalarType t, Eigen::Ref<Eigen::VectorX<ScalarType>> flows) const
     {
+        std::cout << "calc flows" << std::endl;
         auto& params = this->parameters;
-        params.get<ContactPatterns>().get_matrix_at(t)(0, 0);
-        ScalarType coeffStoIV1 = params.get<ContactPatterns>().get_matrix_at(t)(0, 0) *
-                                 params.get<TransmissionProbabilityOnContactV1>() / populations.get_total();
-        ScalarType coeffStoIV2 = params.get<ContactPatterns>().get_matrix_at(t)(0, 0) *
-                                 params.get<TransmissionProbabilityOnContactV2>() / populations.get_total();
 
-        // Normal distributed values for the stochastic part of the flows, variables are encoded
-        // in the following way: x_y is the stochastic part for the flow from x to y. Variant
-        // specific compartments also get an addendum v1 or v2 denoting the relevant variant.
+        // Hole den Kontaktmuster-Wert aus der Matrix bei Zeit t
+        ScalarType cp_val = params.get<ContactPatterns>().get_matrix_at(t)(0, 0);
+        std::cout << "ContactPatterns value: " << cp_val << std::endl;
 
+        // Berechne Koeffizienten für die Transmission
+        ScalarType coeffStoIV1 = cp_val * params.get<TransmissionProbabilityOnContactV1>() / populations.get_total();
+        std::cout << "coeffStoIV1: " << coeffStoIV1 << std::endl;
+
+        ScalarType coeffStoIV2 = cp_val * params.get<TransmissionProbabilityOnContactV2>() / populations.get_total();
+        std::cout << "coeffStoIV2: " << coeffStoIV2 << std::endl;
+
+        // Normalverteilte Zufallszahlen für den stochastischen Anteil der Flows
         ScalarType s_ev1 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "s_ev1: " << s_ev1 << std::endl;
+
         ScalarType s_ev2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "s_ev2: " << s_ev2 << std::endl;
+
         ScalarType ev1_iv1 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "ev1_iv1: " << ev1_iv1 << std::endl;
+
         ScalarType ev2_iv2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "ev2_iv2: " << ev2_iv2 << std::endl;
+
         ScalarType iv1_rv1 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "iv1_rv1: " << iv1_rv1 << std::endl;
+
         ScalarType iv2_rv2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "iv2_rv2: " << iv2_rv2 << std::endl;
+
         ScalarType rv1_ev1v2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "rv1_ev1v2: " << rv1_ev1v2 << std::endl;
+
         ScalarType ev1v2_iv1v2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "ev1v2_iv1v2: " << ev1v2_iv1v2 << std::endl;
+
         ScalarType iv1v2_rv1v2 =
             mio::DistributionAdapter<std::normal_distribution<ScalarType>>::get_instance()(rng, 0.0, 1.0);
+        std::cout << "iv1v2_rv1v2: " << iv1v2_rv1v2 << std::endl;
 
-        // Assuming that no person can change its InfectionState twice in a single time step,
-        // take the minimum of the calculated flow and the source compartment, to ensure that
-        // no compartment attains negative values.
+        // Berechne Optimierungsgrößen
+        ScalarType inv_step_size = 1.0 / step_size;
+        std::cout << "inv_step_size: " << inv_step_size << std::endl;
 
-        // Calculate inv_step_size and inv_sqrt_step_size for optimization.
-        ScalarType inv_step_size      = 1.0 / step_size;
         ScalarType inv_sqrt_step_size = 1.0 / sqrt(step_size);
+        std::cout << "inv_sqrt_step_size: " << inv_sqrt_step_size << std::endl;
 
-        // Two outgoing flows from S so will clamp their sum to S * inv_step_size to ensure non-negative S.
+        // Berechne den ersten Outflow aus S
         const ScalarType outflow1 = std::clamp(
             coeffStoIV1 * y[(size_t)InfectionState::Susceptible] * pop[(size_t)InfectionState::InfectedV1] +
                 sqrt(coeffStoIV1 * y[(size_t)InfectionState::Susceptible] * pop[(size_t)InfectionState::InfectedV1]) *
                     inv_sqrt_step_size * s_ev1,
             0.0, y[(size_t)InfectionState::Susceptible] * inv_step_size);
+        std::cout << "outflow1: " << outflow1 << std::endl;
 
+        // Berechne den zweiten Outflow aus S
         const ScalarType outflow2 =
             std::clamp(coeffStoIV1 * y[(size_t)InfectionState::Susceptible] *
                                (pop[(size_t)InfectionState::InfectedV1V2] + pop[(size_t)InfectionState::InfectedV2]) +
                            sqrt(coeffStoIV2 * y[(size_t)InfectionState::Susceptible] *
                                 (pop[(size_t)InfectionState::InfectedV1V2] + pop[(size_t)InfectionState::InfectedV2])) *
                                inv_sqrt_step_size * s_ev2,
                        0.0, y[(size_t)InfectionState::Susceptible] * inv_step_size);
+        std::cout << "outflow2: " << outflow2 << std::endl;
 
+        // Summe der Outflows
         const ScalarType outflow_sum = outflow1 + outflow2;
+        std::cout << "outflow_sum: " << outflow_sum << std::endl;
+
         if (outflow_sum > 0) {
             const ScalarType scale =
                 std::clamp(outflow_sum, 0.0, y[(size_t)InfectionState::Susceptible] * inv_step_size) / outflow_sum;
+            std::cout << "scale: " << scale << std::endl;
             flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV1>()] = outflow1 * scale;
+            std::cout << "flow Sus -> ExpV1: "
+                      << flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV1>()]
+                      << std::endl;
             flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV2>()] = outflow2 * scale;
+            std::cout << "flow Sus -> ExpV2: "
+                      << flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV2>()]
+                      << std::endl;
         }
         else {
             flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV1>()] = 0;
+            std::cout << "flow Sus -> ExpV1 auf 0 gesetzt" << std::endl;
             flows[get_flat_flow_index<InfectionState::Susceptible, InfectionState::ExposedV2>()] = 0;
+            std::cout << "flow Sus -> ExpV2 auf 0 gesetzt" << std::endl;
         }
 
+        // Fluss von ExposedV1 zu InfectedV1
         flows[get_flat_flow_index<InfectionState::ExposedV1, InfectionState::InfectedV1>()] =
             std::clamp((1.0 / params.get<TimeExposedV1>()) * y[(size_t)InfectionState::ExposedV1] +
                            sqrt((1.0 / params.get<TimeExposedV1>()) * y[(size_t)InfectionState::ExposedV1]) *
                                inv_sqrt_step_size * ev1_iv1,
                        0.0, y[(size_t)InfectionState::ExposedV1] * inv_step_size);
+        std::cout << "flow ExpV1 -> InfV1: "
+                  << flows[get_flat_flow_index<InfectionState::ExposedV1, InfectionState::InfectedV1>()] << std::endl;
 
+        // Fluss von ExposedV2 zu InfectedV2
         flows[get_flat_flow_index<InfectionState::ExposedV2, InfectionState::InfectedV2>()] =
             std::clamp((1.0 / params.get<TimeExposedV2>()) * y[(size_t)InfectionState::ExposedV2] +
                            sqrt((1.0 / params.get<TimeExposedV2>()) * y[(size_t)InfectionState::ExposedV2]) *
                                inv_sqrt_step_size * ev2_iv2,
                        0.0, y[(size_t)InfectionState::ExposedV2] * inv_step_size);
+        std::cout << "flow ExpV2 -> InfV2: "
+                  << flows[get_flat_flow_index<InfectionState::ExposedV2, InfectionState::InfectedV2>()] << std::endl;
 
+        // Fluss von InfectedV1 zu RecoveredV1
         flows[get_flat_flow_index<InfectionState::InfectedV1, InfectionState::RecoveredV1>()] =
             std::clamp((1.0 / params.get<TimeInfectedV1>()) * y[(size_t)InfectionState::InfectedV1] +
                            sqrt((1.0 / params.get<TimeInfectedV1>()) * y[(size_t)InfectionState::InfectedV1]) *
                                inv_sqrt_step_size * iv1_rv1,
                        0.0, y[(size_t)InfectionState::InfectedV1] * inv_step_size);
+        std::cout << "flow InfV1 -> RecV1: "
+                  << flows[get_flat_flow_index<InfectionState::InfectedV1, InfectionState::RecoveredV1>()] << std::endl;
 
+        // Fluss von InfectedV2 zu RecoveredV2
         flows[get_flat_flow_index<InfectionState::InfectedV2, InfectionState::RecoveredV2>()] =
             std::clamp((1.0 / params.get<TimeInfectedV2>()) * y[(size_t)InfectionState::InfectedV2] +
                            sqrt((1.0 / params.get<TimeInfectedV2>()) * y[(size_t)InfectionState::InfectedV2]) *
                                inv_sqrt_step_size * iv2_rv2,
                        0.0, y[(size_t)InfectionState::InfectedV2] * inv_step_size);
+        std::cout << "flow InfV2 -> RecV2: "
+                  << flows[get_flat_flow_index<InfectionState::InfectedV2, InfectionState::RecoveredV2>()] << std::endl;
 
+        // Fluss von RecoveredV1 zu ExposedV1V2
         flows[get_flat_flow_index<InfectionState::RecoveredV1, InfectionState::ExposedV1V2>()] =
             std::clamp(coeffStoIV2 * y[(size_t)InfectionState::RecoveredV1] *
                                (pop[(size_t)InfectionState::InfectedV1V2] + pop[(size_t)InfectionState::InfectedV2]) +
                            sqrt(coeffStoIV2 * y[(size_t)InfectionState::RecoveredV1] *
                                 (pop[(size_t)InfectionState::InfectedV1V2] + pop[(size_t)InfectionState::InfectedV2])) *
                                inv_sqrt_step_size * rv1_ev1v2,
                        0.0, y[(size_t)InfectionState::RecoveredV1] * inv_step_size);
+        std::cout << "flow RecV1 -> ExpV1V2: "
+                  << flows[get_flat_flow_index<InfectionState::RecoveredV1, InfectionState::ExposedV1V2>()]
+                  << std::endl;
 
+        // Fluss von ExposedV1V2 zu InfectedV1V2
         flows[get_flat_flow_index<InfectionState::ExposedV1V2, InfectionState::InfectedV1V2>()] =
             std::clamp((1.0 / params.get<TimeExposedV2>()) * y[(size_t)InfectionState::ExposedV1V2] +
                            sqrt((1.0 / params.get<TimeExposedV2>()) * y[(size_t)InfectionState::ExposedV1V2]) /
                                sqrt(step_size) * ev1v2_iv1v2,
                        0.0, y[(size_t)InfectionState::ExposedV1V2] * inv_step_size);
+        std::cout << "flow ExpV1V2 -> InfV1V2: "
+                  << flows[get_flat_flow_index<InfectionState::ExposedV1V2, InfectionState::InfectedV1V2>()]
+                  << std::endl;
 
+        // Fluss von InfectedV1V2 zu RecoveredV1V2
         flows[get_flat_flow_index<InfectionState::InfectedV1V2, InfectionState::RecoveredV1V2>()] =
             std::clamp((1.0 / params.get<TimeInfectedV2>()) * y[(size_t)InfectionState::InfectedV1V2] +
                            sqrt((1.0 / params.get<TimeInfectedV2>()) * y[(size_t)InfectionState::InfectedV1V2]) /
                                sqrt(step_size) * iv1v2_rv1v2,
                        0.0, y[(size_t)InfectionState::InfectedV1V2] * inv_step_size);
+        std::cout << "flow InfV1V2 -> RecV1V2: "
+                  << flows[get_flat_flow_index<InfectionState::InfectedV1V2, InfectionState::RecoveredV1V2>()]
+                  << std::endl;
+
+        std::cout << "calc flows done" << std::endl;
     }
 
     ScalarType step_size; ///< A step size of the model with which the stochastic process is realized.

docs/requirements.txt

@@ -1,7 +1,7 @@
 sphinx==7.1.2
 sphinx-rtd-theme==1.3.0rc1
-furo
 sphinx-copybutton
+sphinx_design
 breathe
 sphinx-hoverxref
 pycode/memilio-epidata

docs/source/_static/custom.css

@@ -0,0 +1,41 @@
+/* Newlines (\a) and spaces (\20) before each parameter
+.sig-param::before {
+    content: "\a\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20";
+    white-space: pre;
+}
+
+/* Newline after the last parameter (so the closing bracket is on a new line) 
+dt em.sig-param:last-of-type::after {
+    content: "\a";
+    white-space: pre;
+}
+
+/* To have blue background of width of the block (instead of width of content) 
+dl.class > dt:first-of-type {
+    display: block !important;
+} */
+
+/* Take out pointless vertical whitespace in the signatures. */
+.rst-content dl .sig dl,
+.rst-content dl .sig dd {
+  margin-bottom: 0;
+}
+
+/* Make signature boxes full-width, with view-source and header links right-aligned. */
+.rst-content dl .sig {
+  width: -webkit-fill-available;
+}
+.rst-content .viewcode-link {
+  display: inline-flex;
+  float: inline-end;
+  margin-right: 1.5em;
+}
+.rst-content .headerlink {
+  position: absolute;
+  right: 0.5em;
+}
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+  white-space: normal;
+}

docs/source/citation.rst

@@ -0,0 +1,16 @@
+Citing MEmilio
+===============
+
+If you use MEmilio, please cite our work
+
+- Kühn, Martin Joachim et al. (2024). *MEmilio - a High Performance Modular Epidemics Simulation Software (2022)*. Available at `https://github.com/SciCompMod/memilio <https://github.com/SciCompMod/memilio>`_ and `https://elib.dlr.de/209739/ <https://elib.dlr.de/209739/>`_.
+
+and, in particular, for
+
+- **Ordinary differential equation-based (ODE) and Graph-ODE models**: Zunker H, Schmieding R, Kerkmann D, Schengen A, Diexer S, et al. (2024). *Novel travel time aware metapopulation models and multi-layer waning immunity for late-phase epidemic and endemic scenarios*. *PLOS Computational Biology* 20(12): e1012630. `DOI:10.1371/journal.pcbi.1012630 <https://doi.org/10.1371/journal.pcbi.1012630>`_
+- **Integro-differential equation-based (IDE) models**: Wendler AC, Plötzke L, Tritzschak H, Kühn MJ. (2024). *A nonstandard numerical scheme for a novel SECIR integro differential equation-based model with nonexponentially distributed stay times*. Submitted for publication. `arXiv:2408.12228 <https://arxiv.org/abs/2408.12228>`_
+- **Agent-based models (ABMs)**: Kerkmann D, Korf S, Nguyen K, Abele D, Schengen A, et al. (2024). *Agent-based modeling for realistic reproduction of human mobility and contact behavior to evaluate test and isolation strategies in epidemic infectious disease spread*. arXiv. `arXiv:2410.08050 <https://arxiv.org/abs/2410.08050>`_
+- **Hybrid agent-metapopulation-based models**: Bicker J, Schmieding R, Meyer-Hermann M, Kühn MJ. (2025). *Hybrid metapopulation agent-based epidemiological models for efficient insight on the individual scale: A contribution to green computing*. *Infectious Disease Modelling* 10(2): 571-590. `DOI:10.1016/j.idm.2024.12.015 <https://doi.org/10.1016/j.idm.2024.12.015>`_
+- **Graph Neural Networks**: Schmidt A, Zunker H, Heinlein A, Kühn MJ. (2024).*Towards Graph Neural Network Surrogates Leveraging Mechanistic Expert Knowledge for Pandemic Response*. arXiv. `arXiv:2411.06500 <https://arxiv.org/abs/2411.06500>`_
+- **ODE-based models with Linear Chain Trick**: Plötzke L, Wendler A, Schmieding R, Kühn MJ. (2024). *Revisiting the Linear Chain Trick in epidemiological models: Implications of underlying assumptions for numerical solutions*. Submitted for publication. `DOI:10.48550/arXiv.2412.09140 <https://doi.org/10.48550/arXiv.2412.09140>`_
+- **Behavior-based ODE models**: Zunker H, Dönges P, Lenz P, Contreras S, Kühn MJ. (2025). *Risk-mediated dynamic regulation of effective contacts de-synchronizes outbreaks in metapopulation epidemic models*. arXiv. `arXiv:2502.14428 <https://arxiv.org/abs/2502.14428>`_