Core Simulation Models

We provide a collection of pre-built epidemiological model templates that implement classical compartmental structures and several specialized extensions for particular use cases such as network mixing, connected populations, and quarantine strategies. Each model is built on the same underlying Model<TSeq> interface, and all share the same simulation mechanics: agents are connected in a network, their infection status changes according to defined state update functions, and model-level parameters control the transition rates between compartments. Because these models are implemented as templates, users can either run them directly or use them as examples to define custom variants.

The models included in the core codebase cover a wide range of classical and extended systems:

SIS, SIR, SIRD, SEIR, and SEIRD models, which represent standard compartmental processes with increasing biological detail.
Mixing and connected population variants, such as SIRMixing, SEIRMixing, SEIRDConnected, and SIRConnected, which introduce multiple subpopulations or group interactions.
Behavioral and policy-based variants, including MeaslesMixing, MeaslesQuarantine, SEIRMixingQuarantine, and Surveillance, which combine epidemiological processes with specific control mechanisms.
Alternative dynamic structures, like SIRLogit, which use probabilistic transition functions rather than deterministic rates.
Supporting modules, including init-functions.hpp, which defines helper functions for initializing model states, and globalevents.hpp, which provides tools for defining time-dependent interventions.

Although each model defines a different set of compartments and transitions, they all use the same syntax for parameter definition and initialization. For example, in all models users can adjust parameters such as the transmission rate or recovery rate with:

model.add_param(0.2, "Transmission rate");
model.add_param(0.1, "Recovery rate");

and can initialize the starting infection prevalence using the constructor arguments or through initial_states() functions. The following sections describe the conceptual structure, assumptions, and configurable parameters for each of the main model families.

SIS Model¶

The Susceptible–Infected–Susceptible (SIS) model describes diseases for which infection does not confer immunity. Once an agent recovers, they immediately return to the susceptible pool, meaning reinfection is possible indefinitely. The model consists of two compartments: susceptible (S) and infected (I). Transitions occur through infection upon contact and recovery after a certain rate.

Constructor:

ModelSIS(
    ModelSIS<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate
);

Parameters: - vname: Name of the virus or agent of infection. - prevalence: Initial fraction of infected individuals in the population. - transmission_rate (β): Probability of infection per contact between susceptible and infected. - recovery_rate (γ): Probability of recovery per unit time.

Usage Example:

epiworld::ModelSIS<> model("Virus", 0.01, 0.3, 0.1);
model.agents_smallworld(1000, 10, false, 0.05);
model.run(100);

SIR Model¶

The Susceptible–Infected–Recovered (SIR) model adds immunity following recovery. Once an agent recovers, they move into the recovered (R) compartment and cannot be reinfected. This model captures epidemics that eventually die out when the susceptible population is depleted.

Constructor:

ModelSIR(
    ModelSIR<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate
);

Parameters: - transmission_rate (β): Probability of infection per contact. - recovery_rate (γ): Probability of recovery per day. - prevalence: Initial infection prevalence.

Example:

epiworld::ModelSIR<> model("Influenza", 0.01, 0.25, 0.1);
model.agents_smallworld(2000, 8, false, 0.05);
model.run(200);

SIRD Model¶

The SIRD model extends SIR by adding a Dead (D) compartment to represent disease-induced mortality. Upon infection, individuals may either recover or die based on their respective rates.

Constructor:

ModelSIRD(
    ModelSIRD<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate, 
    epiworld_double death_rate
);

Parameters: - death_rate (μ): Probability that an infected individual dies instead of recovering. - transmission_rate, recovery_rate, and prevalence as above.

Example:

epiworld::ModelSIRD<> model("Ebola", 0.005, 0.25, 0.1, 0.02);
model.run(150);

SEIR Model¶

The Susceptible–Exposed–Infected–Recovered (SEIR) model introduces an Exposed (E) compartment representing individuals who have been infected but are not yet infectious. This incubation period delays the onset of transmission.

Constructor:

ModelSEIR(
    ModelSEIR<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double avg_incubation_days,
    epiworld_double recovery_rate
);

Parameters: - avg_incubation_days: Mean duration (in days) of the latent period before infectiousness. - transmission_rate (β) and recovery_rate (γ) follow SIR definitions.

Example:

epiworld::ModelSEIR<> model("COVID-19", 0.01, 0.25, 4.0, 0.1);

SEIRD Model¶

The SEIRD model adds mortality to the SEIR framework, creating five compartments: susceptible, exposed, infected, recovered, and dead. It models diseases with both latency and fatality.

Constructor:

ModelSEIRD(
    ModelSEIRD<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double avg_incubation_days,
    epiworld_double recovery_rate,
    epiworld_double death_rate
);

Example:

epiworld::ModelSEIRD<> model("SARS-CoV-2", 0.005, 0.2, 3.5, 0.1, 0.01);

Connected Models¶

Connected models simulate interacting subpopulations or spatial regions linked by migration or mobility. Each subpopulation maintains its own dynamics but shares individuals or infections through a contact_rate parameter.

Examples:

ModelSIRCONN¶

ModelSIRCONN(
    ModelSIRCONN<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint n,
    epiworld_double prevalence,
    epiworld_double contact_rate,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate
);

ModelSEIRCONN¶

ModelSEIRCONN(
    ModelSEIRCONN<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint n,
    epiworld_double prevalence,
    epiworld_double contact_rate,
    epiworld_double transmission_rate,
    epiworld_double avg_incubation_days,
    epiworld_double recovery_rate
);

ModelSEIRDCONN¶

ModelSEIRDCONN(
    ModelSEIRDCONN<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint n,
    epiworld_double prevalence,
    epiworld_double contact_rate,
    epiworld_double transmission_rate,
    epiworld_double avg_incubation_days,
    epiworld_double recovery_rate,
    epiworld_double death_rate
);

Interpretation:
- contact_rate: Average number of contacts per individual per unit time.
- These models capture between-region spread or mobility-driven mixing.

Mixing Models¶

Mixing models introduce structured subpopulations governed by a contact matrix, allowing heterogeneous contact rates between groups (e.g., age-structured transmission).

ModelSIRMixing¶

ModelSIRMixing(
    ModelSIRMixing<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint n,
    epiworld_double prevalence,
    epiworld_double contact_rate,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate,
    std::vector< double > contact_matrix
);

ModelSEIRMixing¶

ModelSEIRMixing(
    ModelSEIRMixing<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint n,
    epiworld_double prevalence,
    epiworld_double contact_rate,
    epiworld_double transmission_rate,
    epiworld_double avg_incubation_days,
    epiworld_double recovery_rate,
    std::vector< double > contact_matrix
);

Example:

std::vector<double> cm = {1.0, 0.2, 0.2, 1.0};
epiworld::ModelSEIRMixing<> model("Influenza", 0.01, 1000, 8.0, 0.25, 3.0, 0.1, cm);

SEIRMixingQuarantine Model¶

This model adds quarantine and isolation dynamics to the SEIRMixing framework. It introduces policies that reduce contact rates following symptom detection or tracing. It allows modeling interventions such as mandatory quarantine, voluntary isolation, or contact tracing efficiency.

Constructor:

href="#__codelineno-17-1">ModelSEIRMixingQuarantine( ModelSEIRMixingQuarantine<TSeq> & model, const std::string & vname, epiworld_fast_uint n, epiworld_double prevalence, epiworld_double contact_rate, epiworld_double transmission_rate, epiworld_double avg_incubation_days, epiworld_double recovery_rate, std::vector< double > contact_matrix, epiworld_double hospitalization_rate, epiworld_double hospitalization_period, epiworld_double days_undetected, epiworld_fast_int quarantine_period, epiworld_double quarantine_willingness, epiworld_double isolation_willingness, epiworld_fast_int isolation_period, epiworld_double contact_tracing_success_rate = 1.0, epiworld_fast_uint contact_tracing_days_prior = 4u );

Policy Parameters: - days_undetected: Mean number of days before detection.
- quarantine_period and isolation_period: Duration of restricted contact.
- quarantine_willingness and isolation_willingness: Compliance probabilities.
- contact_tracing_success_rate: Fraction of contacts successfully traced.
- hospitalization_rate and hospitalization_period: Define medical intervention timing.

Use Case: Modeling public health policies like mandatory quarantines or tracing efficiency during outbreaks.

SIRLogit Model¶

The SIRLogit model uses logistic regression to determine infection and recovery probabilities as functions of covariates rather than fixed rates. This allows behavioral, demographic, or contextual effects to influence transitions.

Constructor:

ModelSIRLogit(
    ModelSIRLogit<TSeq> & model,
    const std::string & vname,
    double * data,
    size_t ncols,
    std::vector< double > coefs_infect,
    std::vector< double > coefs_recover,
    std::vector< size_t > coef_infect_cols,
    std::vector< size_t > coef_recover_cols,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate,
    epiworld_double prevalence
);

Notes:
- data is a matrix of covariates for all agents.
- coefs_infect and coefs_recover represent regression coefficients for infection and recovery probabilities.
- Transition probabilities are computed using the logistic function:
P(event) = 1 / (1 + exp(-Xβ)).

SISD Model¶

This is a mortality-augmented SIS model where infected individuals can either recover or die. It’s useful for recurrent infections that may also cause mortality.

Constructor:

ModelSISD(
    ModelSISD<TSeq> & model,
    const std::string & vname,
    epiworld_double prevalence,
    epiworld_double transmission_rate,
    epiworld_double recovery_rate,
    epiworld_double death_rate
);

Surveillance Model¶

The SURV (Surveillance) model integrates vaccination, infection, immunity, and observation processes. It extends basic SEIR logic with vaccination efficacy and detection mechanisms, supporting testing and reporting simulations.

Constructor:

ModelSURV(
    ModelSURV<TSeq> & model,
    const std::string & vname,
    epiworld_fast_uint prevalence               = 50,
    epiworld_double efficacy_vax          = 0.9,
    epiworld_double latent_period         = 3u,
    epiworld_double infect_period         = 6u,
    epiworld_double prob_symptoms         = 0.6,
    epiworld_double prop_vaccinated       = 0.25,
    epiworld_double prop_vax_redux_transm = 0.5,
    epiworld_double prop_vax_redux_infect = 0.5,
    epiworld_double surveillance_prob     = 0.001,
    epiworld_double prob_transmission     = 1.0,
    epiworld_double prob_death            = 0.001,
    epiworld_double prob_noreinfect       = 0.9
);

Interpretation: - Combines vaccination, infection, recovery, and death within a surveillance system.
- Tracks detected versus undetected infections.
- Includes immunity reduction parameters and reinfection probabilities.