PatchSim documentation#

PatchSim#

PatchSim is a modular metapopulation simulation framework for compartmental epidemiology. It supports single-patch and multi-patch models, YAML-based configuration, and ODE-based simulation with network-coupled transmission.

What PatchSim provides#

Compartment models: SIR, SEIR, SIRS, SIS, and custom variants
Multi-patch networks: Weighted directed patch-to-patch transmission
YAML configuration: Model structure, parameters, seed data, and network inputs
CLI workflows: Scaffold, validate, run, inspect models, and export summaries
Results outputs: CSV time series, plots, and logs

Start here#

If you are new to the project, follow the docs in this order:

Getting Started — install, initialize, validate, and run
Configuration — every YAML field and a worked SEIR example
CLI Reference — command and flag reference
Mathematical Model — equations and the rate rule
Network Design — how multi-patch mixing works
Results — how to interpret CSVs, plots, and logs

Core concepts#

Compartments#

Compartments represent model states such as S, E, I, and R.

Parameters#

Parameters are per-capita rates like beta, sigma, gamma, and rho.

Transitions#

Transitions define movement between compartments using YAML expressions. See Mathematical Model for the rate multiplication rule.

Network structure#

Patch-to-patch transmission is represented by a weighted directed network. See Network Design for the expected CSV format.

Common workflows#

Use Getting Started for a fast first run
Use Configuration to edit model behavior
Use CLI Reference to see flags and outputs
Use Results to interpret output files

Output overview#

PatchSim writes results to the configured OutputDir:

runs/ — time series CSV output
plots/ — visualization images
logs/ — run logs with configuration and solver details