BETA Release

This project remains in the experimental stage and there are likely many tweaks to come that will improve/change outcomes.


RKnot is a simulation architecture for viral spread that aims to:

  1. Faithfully replicate spread in real world conditions
  2. Investigate the impacts of policy decisions and other interventions
  3. Provide visualization tools for ease-of-presentation

RKnot attempts to distinguish itself from prevailing models by:

  • allowing for customized population sizes and demographics
  • supporting more realistic movement and contact patterns
  • modulating transmission risk to account for varying subject behavior and location properties
  • influencing interactions via an array of interventions that can be used in any combination

RKnot utilizes parallelization via Ray and JIT-compilation via Numba for performance improvements amd Matplotlib for visualizaitons.


Documentation examples focus on **sars-cov-2**, however, **RKnot** can be used to simulate any virus, or anything that spreads like a virus.

Basic Example

A simulation and visualization can be completed in a few quick lines of code. The user need only specify a dictionary describing the population, group, and a handful of parameters describing the simulation space and viral characteristics.

Below we simulate:

  • a population of 1,000 subjects,

  • beginning with five initially infected;

  • a density of 1 subject per location

  • a maximum simulation length of 150 days

    • the simulation will automatically stop when there are no more infections

  • an initial reproduction number, \(R_0\), of 3

  • an infection duration of 14 days

  • an immunity duration of 365

from rknot import Sim, Chart

group = {'n': 1000, 'n_inf': 5}
params = {'R0': 3,'imndur': 365, 'infdur': 14, 'density': 1, 'days': 150}

sim = Sim(groups=group, **params)

chart = Chart(sim)


Peak 52.1%
HIT 72.7%
Total 92.2%
Fatalities 0.00%
% > 70 nan%
IFR 0.00%
Days to Peak 36

As per the chart, this simulation results in a peak at 29 days, with 53% of the population infected at the peak and a Herd Immunity Threshold of 70%. In total 93% of the population was infected and 0.4% of the population, or 4 subjects, died.