Build an Epidemic Simulator: From SIR Models to Agent-Based Runs

Build an Epidemic Simulator: From SIR Models to Agent-Based Runs

Introduction Epidemic simulators let you explore how infectious diseases spread, test interventions, and understand system dynamics before real-world deployment. This guide walks through building simulators at two levels of fidelity: compartmental SIR models (fast, analytic) and agent-based models (ABMs — detailed, stochastic). You’ll get conceptual explanations, implementation outlines, sample code snippets, and suggestions for experiments and validation.

Why build a simulator

• Understanding dynamics: Clarifies how reproduction number, immunity, and interventions shape outbreaks.
• Policy testing: Compare vaccination, social distancing, contact tracing strategies.
• Education and research: Reproducible experiments and scenario exploration.

Part 1 — SIR models: fast, interpretable

1. Model overview
   • Compartments: Susceptible (S), Infectious (I), Recovered ®.
   • Key parameters: transmission rate β, recovery rate γ, basic reproduction number R0 = β/γ.
   • Deterministic ODEs:
     dS/dt = -βS * I / NdI/dt = β * S * I / N - γ * IdR/dt = γ * I

2. Implementation outline (numerical)
   • Choose time-step dt and integrate ODEs (Euler or Runge–Kutta).
   • Inputs: N, initial I0, β, γ, simulation horizon.
   • Outputs: time-series S(t), I(t), R(t); peak infection, attack rate, timing.
3. Simple Python example (using scipy.integrate)
   python

   import numpy as npfrom scipy.integrate import odeint def sir(y, t, beta, gamma, N): S, I, R = y dSdt = -beta * S * I / N dIdt = beta * S * I / N - gamma * I dRdt = gamma * I return dSdt, dIdt, dRdt N = 100000I0 = 10R0 = 0S0 = N - I0 - R0beta = 0.3gamma = 1/10t = np.linspace(0, 160, 160)y0 = S0, I0, R0sol = odeint(sir, y0, t, args=(beta, gamma, N))S, I, R = sol.T

4. Extensions
   • SEIR (adds Exposed), age-structured compartments, time-varying β for interventions, stochastic SIR with Gillespie.

Part 2 — Agent-Based Models: individual-level detail

1. Why ABMs
   • Capture heterogeneity in contacts, behavior, spatial movement, explicit networks, and stochasticity.
2. Core design choices
   • Agents’ attributes: health state, age, susceptibility, compliance.
   • Contact model: random mixing, fixed network (graph), locations (homes, workplaces, schools), mobility.
   • Disease progression: incubation, infectiousness profile, symptomatic probability, isolation.
   • Time-stepping: discrete daily updates or event-driven simulation.
3. Implementation outline
   • Initialize agents with attributes and build contact structure.
   • Each timestep: for each infectious agent, sample contacts and attempt transmission with per-contact probability; update states (progression, recovery); apply interventions (quarantine, vaccination).
   • Collect metrics: incidence, prevalence, secondary attack rates, hospitalizations.
4. Sample pseudocode (discrete-time, network)
   python

   for day in range(days): for agent in agents: if agent.state == “infectious”: contacts = sample_contacts(agent) for c in contacts: if c.state == “susceptible” and random() < transmission_prob(agent, c): c.infect(day) for agent in agents: agent.update_state(day)

5. Performance and scaling
   • Use sparse networks, vectorized operations, Cython/Numba, or distributed frameworks.
   • For millions of agents consider metapopulation models or hybrid: compartmental within subpopulations + agent-level for key groups.

Part 3 — Calibration, validation, and uncertainty

• Calibrate to observed data (cases, hospitalizations) using parameter search (grid, MCMC, ABC).
• Validate by out-of-sample forecasts and sensitivity analyses.
• Quantify uncertainty with ensemble runs and probabilistic outputs.

Part 4 — Interventions and scenarios

• Non-pharmaceutical: social distancing (reduce contacts), masks (reduce transmission probability), school closures (remove contacts), testing & isolation (move agents to reduced-contact state).
• Pharmaceutical: vaccination (move agents to recovered/immune or reduce susceptibility), antivirals (reduce infectiousness/duration).
• Economic/social trade-offs: add cost metrics, compliance fatigue, and behavioral feedback loops.

Part 5 — Visualization and reporting

• Plot SIR curves, incidence heatmaps, network snapshots, and geographic maps.
• Provide dashboards for scenario toggles and uncertainty bands.

Part 6 — Ethics, data, and reproducibility

• Protect privacy when using real contact or mobility data.
• Share code, parameters, and random seeds; document data sources and assumptions.

Part 7 — Suggested project roadmap (8 weeks)

1. Week 1: Implement deterministic SIR and basic plots.
2. Week 2: Add SEIR and stochastic SIR.
3. Week 3–4: Build simple ABM with households and workplaces.
4. Week 5: Add interventions and parameter inputs.
5. Week 6: Calibrate to a small dataset and run ensembles.
6. Week 7: Optimize performance and add visualizations.
7. Week 8: Prepare documentation, tests, and reproducible examples.

Further reading and tools

• Use libraries