epiworld

This C++ library provides a general framework for epidemiologic simulation. The core principle of epiworld is fast epidemiological prototyping for building complex models quickly. Here are some of its main features:

• It only depends on the standard library (C++11 required.)
• It is a template library.
• It is header-only (single file).
• Models can have an arbitrary set of states.
• Viruses and tools (e.g., vaccines, mask-wearing) can be designed to have arbitrary features.
• Multiple tools and viruses can live in the same simulation.
• It is FAST: Over 150 Million person/day simulations per second (see example below).

An evolving cross-framework benchmark compares epiworld, its R and Python wrappers, and other epidemic ABM engines. In the SEIRH network scenarios currently covered, the epiworld family is among the fastest, and native epiworld is among the lower-memory implementations. These results are a snapshot of the tested versions, workloads, and environment rather than a universal ranking; additional scenarios, engines, corrections, and implementation improvements are welcome through the benchmark's issues and pull requests.

Various examples can be found in the examples folder. This repository also hosts the measles library, which extends epiworld with Measles-specific models. The library is available under include/measles.

Hello world

Here is a simple SIR model implemented with epiworld. The source code can be found here, and you can compile the code as follows:

g++ -std=c++20 -O3 helloworld.cpp -o helloworld.o

As you can see in helloworld.cpp, to use epiworld you only need to incorporate the single header file epiworld.hpp:

#include "epiworld.hpp"

using namespace epiworld;

int main()
{

    // epiworld already comes with a couple
    // of models, like the SIR
    epimodels::ModelSIR<> hello(
        "COVID-19", // Name of the virus
        0.01,        // Initial prevalence
        0.1,        // Transmission probability
        0.3         // Recovery probability
        );

    // We can simulate agents using a smallworld network
    // with 100,000 individuals, in this case
    hello.agents_smallworld(100000, 10L, false, .01);

    // Running the model and printing the results
    // Setting the number of days (100) and seed (122)
    hello.run(100, 122);
    hello.print();

    return 0;

}

Compiling (with make helloworld.o) and running the problem yields the following result:

_________________________________________________________________________
Running the model...
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| done.
________________________________________________________________________________
________________________________________________________________________________
SIMULATION STUDY

Name of the model   : Susceptible-Infected-Recovered (SIR)
Population size     : 100000
Agents' data        : (none)
Number of entities  : 0
Days (duration)     : 100 (of 100)
Number of viruses   : 1
Last run elapsed t  : 69.00ms
Last run speed      : 143.87 million agents x day / second
Rewiring            : off

Global events:
 (none)

Virus(es):
 - COVID-19

Tool(s):
 (none)

Model parameters:
 - Recovery rate     : 0.3000
 - Transmission rate : 0.1000

Distribution of the population at time 100:
  - (0) Susceptible :  99000 -> 41957
  - (1) Infected    :   1000 -> 70
  - (2) Recovered   :      0 -> 57973

Transition Probabilities:
 - Susceptible  0.99  0.01     -
 - Infected        -  0.70  0.30
 - Recovered       -     -  1.00

Building from scratch

One of the best things about epiworld is the capability to build models from scratch. Here is one example (readme.cpp):

This is the beginning of the README. Read the rest at the original. Read the full README ↗