Skip to content

AI-generated content

This chapter was automatically generated by an AI agent and has not been reviewed by a human. Read with caution.

Introduction to Epiworld

Epiworld is a high-performance, header-only C++ library for agent-based epidemiological simulation. It is also available through interfaces in R and Python.

This chapter introduces the fundamental ideas you need to understand before writing your first simulation.

Key Abstractions

Every epiworld simulation revolves around four core concepts:

Concept Description
Model The top-level container that holds the population, viruses, tools, parameters, and the simulation clock.
Agent An individual in the population. Agents live on a contact network, carry viruses and tools, and transition between user-defined states.
Virus A disease agent that can spread between agents through contacts. Viruses have configurable transmissibility, incubation, and post-recovery behavior.
Tool An intervention or trait (e.g., a vaccine, mask, or immune system) that modifies an agent's susceptibility, transmissibility, recovery, or mortality.

States

Unlike many frameworks that ship a fixed set of compartments (S, I, R, …), epiworld lets you define an arbitrary set of states. Each state has an associated update function that controls what agents in that state do on each simulation day. This makes it possible to model anything from a basic SIR to a multi-stage clinical pathway with quarantine, hospitalization, and contact tracing.

Contact Network

Agents interact through a contact network — a graph where edges represent potential transmission pathways. Epiworld provides built-in generators for common topologies (small-world, scale-free, etc.) and also supports loading networks from adjacency lists.

How a Simulation Runs

A simulation advances in discrete days. On each day the following steps occur:

  1. Agent updates — Every active agent executes the update function for its current state.
  2. Global events — Optional model-wide functions run (e.g., implementing a lockdown or collecting statistics).
  3. Network rewiring — When configured, edges in the contact network are modified to model behavioral changes.
  4. Recording — The day counter increments and all changes are committed to the database.
  5. Mutation — When defined, viruses may mutate to produce new variants.

For a detailed walkthrough see Simulation Steps.

A Minimal Example

The fastest way to run a simulation is to use one of the built-in models. Here is an SIR model in C++ and R:

#include "epiworld.hpp"
using namespace epiworld;

int main() {
    epimodels::ModelSIR<> model(
        "COVID-19", // Virus name
        0.01,       // Initial prevalence
        0.1,        // Transmission rate
        0.3         // Recovery rate
    );

    model.agents_smallworld(100000, 10, false, 0.01);
    model.run(100, 122);
    model.print();

    return 0;
}

library(epiworldR)

model <- ModelSIR(
  name              = "COVID-19",
  prevalence        = 0.01,
  transmission_rate = 0.1,
  recovery_rate     = 0.3
)

agents_smallworld(model, n = 100000, k = 10, p = 0.01)
run(model, ndays = 100, seed = 122)
summary(model)

In both cases the library:

  1. Creates a population of 100,000 agents on a small-world network.
  2. Seeds 1 % of agents with a virus named "COVID-19".
  3. Simulates 100 days of SIR dynamics.
  4. Prints a summary of the final state distribution and transition probabilities.

What's Next