Write Extensable Developer/Usage Documentation #97
Description
As the title says. I'm generally of the belief that developer and user documentation should be the same for things like these, so I'm likely going to combine them. The below is likely a good starting point.
-
Library Architecture
- Overview of file organization and class hierarchy
- Explanation of the bones-meat pattern used in the codebase
- Dependency diagrams
-
Performance Optimization Guide
- Profiling techniques
- Memory usage optimization
- Parallel execution strategies
- Benchmarking methodologies
-
Extending the Library
- Guide for creating custom agent behaviors
- Documentation for creating custom network structures
- Guide for implementing new global events
- Documentation for creating custom data collection strategies
-
Core Simulation Models
- Overview of each epidemiological model tested (SIR, SEIR, SIS, SIRD, SEIRD, ModelSIRCONN, ModelSEIRMixing, ModelMeaslesSchool, ModelMeaslesMixing, etc.).
- A clear description of the assumptions and parameters peculiar to each model (e.g. contact rate, transmission rate, recovery rate, incubation period).
-
Queuing System
- The mechanics of how agents become active/inactive in the queue
- Performance implications of different queuing strategies
- How to customize the queuing behavior
-
Random Graph Generation
- Document all random graph generation functions
- Parameters and their impact on network structure
- Performance characteristics of different network types
-
Data Collection and Analysis
- Database class usage and best practices
- Exporting simulation results to different formats
- Guidelines for statistical analysis of results
-
Random Number Generation and Statistical Functions
- Detail the different random distributions used (normal, uniform, gamma, exponential, lognormal, binomial, negative binomial, geometric, Poisson).
- Include documentation on how the random engine is seeded and how reproducibility is maintained.
-
Reproducibility and
run_multiple- Explain the difference between a single run (run) and multiple runs (run_multiple) of simulations.
- Document the purpose of the saver callback functions, how transition probabilities are recorded, and how the reproductive number (Rt, R0) is computed.
-
Mixing and Entity Distribution
- Describe the role of the mixing matrices and contact matrices.
- Explain the entity distribution functions (e.g. distribute_entity_randomly, dist_factory, distribute_*_to_set, etc.).
- Document how agents are partitioned into “groups” or “entities” and how that affects contact and transmission dynamics.
-
Virus and Tool Distribution Functions
- Show how viruses and tools are added to the model, how the distribution functions work, and document the “cloning” tests (see “00-cloning-model.cpp”).
- Emphasize that the single header file (epiworld.hpp) must not be modified per the project rules.
-
Generation Interval and Reproductive Number Calculation
- Provide a detailed explanation of the generation interval simulation versus analytical calculation (tests in “10-generation-interval.cpp”).
- Document the formulas used and how the mean generation interval is derived.
- Explain how Rt and R0 are derived from the transition matrices.
-
Events and Multi-Event Handling
- Explain how multiple update (or event) functions can be scheduled (see “16-multiple-events.cpp”).
- Document the mechanism of state changes when several events are applied in one simulation step.
-
Quarantine, Isolation, and Contact Tracing Modules
- Elaborate on models that support quarantine and isolation (including the mixing-quarantine models in files beginning with “17” and “19”).
- Document the parameters controlling quarantine (quarantine period, willingness, isolation period, etc.) and how they affect the transition probabilities and final outbreak sizes.
- Include discussion on global events (e.g. a “quarantine accounting” event) and how outbreak sizes are computed and compared.
-
Final Size, Transition Matrix, and Diagram Generation
- Explain how the final outbreak sizes are computed from the simulation state histograms (as seen in tests like “19a-measles-mixing.cpp” and the R script “transitions.R”).
- Document the process for generating and saving diagrams (e.g. Mermaid diagrams) from transition matrices; cover the purpose of “12-diagrams.cpp.”
-
Testing Infrastructure and Helper Functions
- Document the test helpers in “tests.hpp”: the utility functions to read files, compute averages, print transitions neatly, and calculate summary statistics (including the “test_compute_final_sizes” function).
- Describe how the tests are run together by including many .cpp files into a single Catch2 test runner (see “main.cpp”).
-
Code Examples and Usage Notes
- Include annotated examples from the tests to show how a user would set up a simulation model, manipulate parameters, and run a simulation.
- Provide inline documentation in code examples (using the provided code block format that includes file paths and line ranges).
-
Corner Cases and Memory Management
- Document the tests that check “nooks and crannies” like the virus handling counters in “18-test-virus-handling.cpp” to ensure correct copy/move semantics and that no memory leaks occur.
-
Integration with External Tools
- Document how to use the provided R script for transition matrix analysis.