1233 further enhance read the docs

.github/pull_request_template.md

@@ -22,7 +22,7 @@ Please check our [git workflow](https://memilio.readthedocs.io/en/latest/develop
 - [ ] New code adheres to [coding guidelines](https://memilio.readthedocs.io/en/latest/development.html#coding-guidelines)
 - [ ] No large data files have been added (files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.)
 - [ ] Tests are added for new functionality and a local test run was successful (with and without OpenMP)
-- [ ] Appropriate **documentation** for new functionality has been added (Doxygen in the code and Markdown files if necessary)
+- [ ] Appropriate **documentation** for new functionality has been added (Doxygen in the code and explanations in the online documentation)
 - [ ] Proper attention to licenses, especially no new third-party software with conflicting license has been added
 - [ ] (For ABM development) Checked [benchmark results](https://memilio.readthedocs.io/en/latest/development.html#agent-based-model-development) and ran and posted a local test above from before and after development to ensure performance is monitored.
 

.gitignore

@@ -283,4 +283,7 @@ docs/xml
 docs/source/api
 docs/source/generated
 
+# VS Code
+.vscode/
+
 # End of https://www.gitignore.io/api/c++,node,python

README.md

@@ -15,36 +15,19 @@ 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`
+- Agent-based models (ABMs): Kerkmann D, Korf S, Nguyen K, Abele D, Schengen A, et al. (2025). *Agent-based modeling for realistic reproduction of human mobility and contact behavior to evaluate test and isolation strategies in epidemic infectious disease spread*. *Computers in Biology and Medicine* 193: 110269. `DOI:10.1016/j.compbiomed.2025.110269 <https://doi.org/10.1016/j.compbiomed.2025.110269>`_
 - 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**
 
-MEmilio builds upon different model types, equation-based and agent-based. Furthermore, there are hybrid, graph-ODE-based models. Among the equation-based models, we provide ordinary differential equation (ODE) and integro-differential equation (IDE) based models. In order to provide highly efficient model implementations, MEmilio builds upon a C++ backend for its model and simulation-related content. Data acquisition, plotting, and machine-learnt models are provided in Python.
 
-Details of the C++ implementation of the epidemiological models can be found in the cpp directory (see the [README](cpp/README.md) there). 
-
-Some regularly used data for simulations of a pathogen's spread in Germany, like contact and inter-county mobility, can be found in [data](data/README.md).
-
-In pycode, different MEmilio python packages are defined. Via our [memilio-simulation](pycode/memilio-simulation) package, you can run our C++ backend from python; this package uses [pybind11](https://github.com/pybind/pybind11) to bind our C++ model code. The [memilio-epidata](pycode/memilio-epidata) package provides tools to download and structure important data such as infection or mobility data. More about the python packages can be found in [Python README](pycode/README.rst).
-
-**Documentation**
-
-Each important part of the project described above is described in detail in the README in the corresponding directory. The README contains e.g. configuration and usage instructions for users and developers.
-
-Also, the code is documented with doxygen and instructions on how to obtain it can be found in the docs folder.
-The documentation of the code of the main branch can be found at the following URL:
-
-https://scicompmod.github.io/memilio/documentation/index.html
-
-**Installation, Usage and Requirements**
-
-Each part has different requirements and usage. Detailed instruction can be found in the corresponding READMEs.
+The documentation for MEmilio can be found at 
+https://memilio.readthedocs.io/en/latest/index.html
 
 **Development**
 
-* [Git workflow and change process](https://github.com/SciCompMod/memilio/wiki/git-workflow)
-* [Coding Guidelines](https://github.com/SciCompMod/memilio/wiki/coding-guidelines)
+The coding guidelines and git workflow description can be found in the documentation at 
+https://memilio.readthedocs.io/en/latest/development.html

cpp/README.md

@@ -59,6 +59,7 @@ Options can be specified with `cmake .. -D<OPTION>=<VALUE>` or by editing the `b
 - `MEMILIO_ENABLE_WARNINGS`: enable compilation warnings (beyond those enabled in the compiler by default). ON or OFF, default ON.
 - `MEMILIO_ENABLE_WARNINGS_AS_ERRORS`: compilation warnings are treated as compilation errors. ON or OFF, default ON.
 - `MEMILIO_ENABLE_PROFILING`: compile with runtime profiling support. ON or OFF, default OFF. See [here](benchmarks/profiling.md) for information.
+- `MEMILIO_ENABLE_LIKWID_MARKER`: compile MEmilio with likwid markers. ON or OFF, default OFF.
 
 Other important options may need:
 - `CMAKE_BUILD_TYPE`: controls compiler optimizations and diagnostics, Debug, Release, or RelWithDebInfo; not available for Multi-Config CMake Generators like Visual Studio, set the build type in the IDE or when running the compiler.

cpp/memilio/compartments/simulation.h

@@ -119,10 +119,6 @@ class Simulation
         return m_result;
     }
 
-    /**
-     * @brief get_result returns the final simulation result
-     * @return a TimeSeries to represent the final simulation result
-     */
     const TimeSeries<FP>& get_result() const
     {
         return m_result;

cpp/models/abm/README.md

@@ -1,158 +1,8 @@
 # Agent-Based Model
 
-This module models and simulates the epidemic using an agent-based model (*ABM*) approach. Unlike compartmental models like the [SECIR](../ode_secir/README.md) model that uses a system of ODEs, this model simulates the spread of COVID-19 in a population with discrete persons (the agents) moving throughout locations in the model and interacting with (infecting) each other.
+This directory contains the agent based model. 
+To get started, check out the [official documentation](https://memilio.readthedocs.io/en/latest/cpp/mobility_based_abm.html) 
+or the code examples
 
-## Structure
-
-The model consists of the following major classes:
-
-1. Person: represents an agent of the model. A person has an ID, i.e. a unique number, an age, a location and a list with their assigned locations, i.e. the locations it can visit during the simulation. They can perform tests and wear masks. Every person has lists with past and current infections and vaccinations.
-2. Infection: collection of all information about a persons' infection, i.e. infectiousness, infection course, virus variant. The infection course is drawn stochastically from the infection states that are similar to the compartments of the SECIR model.
-3. Location: represents places in the model where people meet and interact, e.g. home, school, work, social event sites. A location can be split into cells to model parts of a location, like classrooms in a school. Some infection parameters are location-specific and one can activate NPIs like mandatory masks or tests to enter the location.
-4. Model: collection of all persons and locations. It also holds information about the testing strategy of the simulation and holds the rules for the mobility phase.
-5. Simulation: runs the simulation and stores results.
-
-## Simulation
-
-The simulation runs in discrete time steps. Each step has two phases, an interaction phase and a mobility phase.
-
-### Interaction Phase
-
-In this phase, each person interacts with the other persons at the same location. This interaction determines the transmission of the disease. A susceptible person can become infected by contact with an infected person. The probability of infection depends on a multitude of factors, such as the viral load and infectiousness of the infected and the immunity level of the susceptible person at the time of transmission.
-
-### Mobility Phase
-
-During the mobility phase, each person may change their location. Mobility follows complex [rules](../abm/mobility_rules.cpp), considering the current location, time of day, and properties of the person (e.g. age). Some location changes are deterministic and regular (e.g. going to work), others are random (e.g. going to shopping or to a social event in the evening/on the weekend). When agents are tested positive, they are quarantined and cannot leave their home, unless their infection becomes worse and they have to go to the hospital or the ICU. In general, if an agent suffers from severe or critical symptoms, it will move to the hospital or ICU with highest priority. Some mobility rules can be restricted by allowing only a proportion of people to enter specific locations.
-
-Another way of mobility we use in the simulation of Braunschweig (simulations/abm_braunschweig.cpp) is using trips. A trip consists of the ID of the person that performs this trip, a time point when this trip is performed and where the person is heading to. At the beginning of the simulation, a list with all trips is initialized and followed during the simulation. There can be different trips on the weekend than during the week, but other than that, the agents do the same trips every day. As before, agents that are in quarantine or in the hospital cannot change their location.
-
-## Get Started
-
-This section gives an introduction to how to use the ABM and set up your own simulation. For a quick overview, can find a full example in the [ABM minimal example](../../examples/abm_minimal.cpp) and a more detailed Doxygen documentation [here](https://scicompmod.github.io/memilio/documentation/index.html ). For a guide on installation and running the simulations and examples, see this [README](../../README.md).
-
-Every person in the ABM belongs to an AgeGroup, which we can define as follows:  
-
-```cpp  
-size_t num_age_groups         = 4;  
-const auto age_group_0_to_4   = mio::AgeGroup(0);  
-const auto age_group_5_to_14  = mio::AgeGroup(1);  
-...                           = ...  
-```  
-
-Note that every age group has to have values strictly smaller than the number of age groups `num_age_groups`.  
-With this number we create an empty model:  
-
-```cpp
-auto model = mio::abm::Model(num_age_groups);
-```
-
-We can set several general parameters, which you can find [here](../abm/parameters.h). Here is an example where we set the time to go from Exposed to InfectedNoSymptoms to 4 days:
-
-```cpp
-model.parameters.get<mio::abm::TimeExposedToNoSymptoms>() =  mio::ParameterDistributionConstant(4.);
-```
-
-To add a location to the model, we have to specify the kind of location.
-
-```cpp
-auto home = model.add_location(mio::abm::LocationType::Home);
-```
-
-People are added with an age. Then we have to assign them, so the model knows they can travel to this location.
-
-```cpp
-auto person = model.add_person(home, age_group_0_to_4);
-person.set_assigned_location(home);
-```
-
-For adding more people to the model, we create households. A Household holds a vector of HouseholdMembers, which in turn hold a weighted distribution, such that we can randomly draw the age of each Person belonging to the Household. To manage multiple Households of the same type, we can use a HouseholdGroup.
-In our example, we categorize individuals into two groups: children and parents.
-
-- Children: They can either belong to AgeGroup(0) or AgeGroup(1). The probability of a child belonging to either group is 0.5.
-- Parents: They can either belong to AgeGroup(2) or AgeGroup(3). The probability of a parent belonging to either group is also 0.5.
-
-We then form households in two ways:
-
-1. Households with one parent and one child.
-2. Households with two parents and one child.
-
-```cpp
-auto child = mio::abm::HouseholdMember(num_age_groups);
-child.set_age_weight(age_group_0_to_4, 1);
-child.set_age_weight(age_group_0_to_4, 1);
-
-auto parent = mio::abm::HouseholdMember(num_age_groups);
-parent.set_age_weight(age_groups_15_to_34, 1);
-parent.set_age_weight(age_groups_35_to_59, 1);
-
-// Two-person household with one parent and one child.
-auto twoPersonHousehold_group = mio::abm::HouseholdGroup();
-auto twoPersonHousehold_full  = mio::abm::Household();
-twoPersonHousehold_full.add_members(child, 1);
-twoPersonHousehold_full.add_members(parent, 1);
-twoPersonHousehold_group.add_households(twoPersonHousehold_full, n_households);
-add_household_group_to_model(model, twoPersonHousehold_group);
-
-```
-
-During the simulation, people can get tested, and we have to specify the scheme for that:
-
-```cpp
-auto probability      = 0.5;
-auto start_date       = mio::abm::TimePoint(0);
-auto end_date         = mio::abm::TimePoint(0) + mio::abm::days(30);
-auto test_type        = mio::abm::AntigenTest();
-auto test_at_work     = std::vector<mio::abm::LocationType>{mio::abm::LocationType::Work};
-auto testing_criteria_work =
-    std::vector<mio::abm::TestingCriteria>{mio::abm::TestingCriteria({}, test_at_work, {})};
-auto testing_scheme_work =
-    mio::abm::TestingScheme(testing_criteria_work, start_date, end_date, test_type, probability);
-model.get_testing_strategy().add_testing_scheme(testing_scheme_work);
-```
-
-For some infections to happen during the simulation, we have to initialize people with infections.
-
-```cpp
-person.add_new_infection(mio::abm::Infection(rng, mio::abm::VirusVariant::Wildtype, person.get_age(), model.parameters, start_date, infection_state));
-```
-
-We can add restrictions for people after a specific date. For example, only 10% of the people go to social events after day 10.
-
-```cpp
-auto t_lockdown = mio::abm::TimePoint(0) + mio::abm::days(10);
-mio::abm::close_social_events(t_lockdown, 0.9, model.parameters);
-```
-
-Then we run the simulation.
-
-```cpp
-sim.advance(mio::abm::TimePoint(0) + mio::abm::days(30));
-```
-
-Alternitavely, if we want to track things in the simulation, we need to set up a [history](../../memilio/io/README.md#the-history-object), for example, to track all the Infection states of each simulation step.
-
-```cpp
-    mio::History<mio::abm::TimeSeriesWriter, mio::abm::LogInfectionState> history;
-```
-
-Then we can run the simulation with the history object and one can access the data it through get_log.
-
-```cpp
-    sim.advance(tmax, history);
-    auto log = history.get_log();
-```
-
-Finally we can print the data to a text file.
-
-```cpp
-    std::ofstream outfile("abm_minimal.txt");
-    std::get<0>(log).print_table({"S", "E", "I_NS", "I_Sy", "I_Sev", "I_Crit", "R", "D"}, 7, 4, outfile);
-    std::cout << "Results written to abm_minimal.txt" << std::endl;
-```
-
-## Current Limitations
-
-Currently, a few things are not yet implemented, such as:
-
-- Different trips for each day.
-- Test and Trace functionality
+- [examples/abm.cpp](../../examples/abm_minimal.cpp)
+- [examples/abm_minimal.cpp](../../examples/abm_history_object.cpp)

cpp/models/d_abm/README.md

@@ -1,19 +1,5 @@
 # Diffusive Agent-Based Model
 
-This agent-based model uses a Markov process to simulate disease dynamics. The features of an agent are position and infection state. The evolution of the system state is determined by the following master equation
-
-```math
-\partial_t p(X,Z;t) = G p(X,Z;t) + L p(X,Z;t)
-```
-The operator $G$ defines the infection state adoptions and only acts on $Z$, while $L$ defines location changes, only acting on $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 is used for simulation, a direct method without rejection sampling. Therefore, $G$ and $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. We here implemented a quadwell potential given in the class QuadWellModel, but any other suitable potential can be used as implementation. 
-
-## Simulation
-
-The simulation runs in discrete time steps. In every step we advance the model until the next infection state adoption event, then adopt the corresponding agent's infection state and draw a new waiting time until the next adoption event. 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.
-
-For a detailed description and application of the model, see:
-
-- Bicker J, Schmieding R, et al. (2025) Hybrid metapopulation agent-based epidemiological models for efficient insight on the individual scale: A contribution to green computing.
-Infectious Disease Modelling, Volume 10, Issue 2. https://doi.org/10.1016/j.idm.2024.12.015
+This directory contains the diffusive agent based model implementation. 
+To get started, check out the [official documentation](https://memilio.readthedocs.io/en/latest/cpp/diffusive_abm.html) 
+or the [code examples](../../examples/d_abm.cpp).