Covasim
Citation: Covasim: an agent-based model of COVID-19 dynamics and interventions
Covasim performs projections of indicators such as numbers of infections and peak hospital demand, and explores interventions including social distancing, school closures, testing, contact tracing, quarantine, and vaccination.
How this model is classified mathematically and dynamically.
- Model class
- Formalism
- Determinism
- Stochastic
- Time dynamics
- Discrete
- Spatial
- Non-spatial
- Multiscale
- No
Organisms, entities and processes this model represents.
- Organisms
- Infectious agents
- Health conditions
- Not recorded
- Biological processes
- Molecular entities
- Not recorded
- Proteins / genes
- Not recorded
The data this model consumes and produces when executed.
Parameters
| Name | Default | Unit | Meaning |
|---|---|---|---|
| pop_size | 20000 | count | population size |
| pop_infected | 20 | count | initial infections |
| pop_type | random | dimensionless unit | Population data type: random or hybrid. |
| start_day | 2020-03-01 | day | Start day of the simulation. |
| n_days | 60 | day | Number of days to run when end_day is not specified. |
| rand_seed | 1 | dimensionless unit | Random seed; None means do not reset. |
| pop_scale | 1 | dimensionless unit | Factor by which to scale the population. |
| rescale | true | dimensionless unit | Enable dynamic rescaling of the population. |
| beta | 0.016 | dimensionless unit | transmissibility |
| n_imports | 0 | count | Average daily number of imported cases; actual number is drawn from a Poisson distribution. |
| use_waning | true | dimensionless unit | immunity |
Initial conditions
| Name | Value | Unit |
|---|---|---|
| initial_infected_agents | 20 | count |
Outputs
| Name | Quantity | Unit | Format |
|---|---|---|---|
| epidemic_time_series | epidemiological indicators | count | Not recorded |
| simulation_plot | epidemiological indicators | Not recorded | PNG |
| results_workbook | epidemiological indicators | Not recorded | xlsx |
Experiment protocol
A typical run constructs cv.Sim with default parameters, advances the simulation for 60 days at a one-day timestep, and may plot or save results.
- Timestep
- 1 day
- Duration
- 60 day
- Observables
- new infectionscumulative infectionsdeathseffective reproduction number
Runtime environment, dependencies, and compute requirements.
- Language
- Python >=3.11
- Environment
- native
Covasim advances with a one-day timestep. Fire-based bin scripts expose function arguments as CLI options; the package also provides an importable Python API (cv.Sim).
Compute requirements
- GPU
- Not required
- Parallelism
- multi-process
Dependencies
- runtime
- numpy
- numba
- pandas
- scipy
- statsmodels
- matplotlib
- sciris >=3.4.0
- starsim >=3.7.2
- optional
- fire
- pytest >=7.3
Containers
- docker · docker.io/mismplatform/envbuild@sha256:cff512c840c7ed43e47f7918d5ae83808450feef7d9853b2bad3c05ca4c0fe5f · docker.io
Image approved · envbuild-agent · Oct 2026
Entry points
python bin/covasimRun a Covasim simulation through the Fire CLI
covasim-migrate3to4 <paths>Migrate Covasim v3 scripts to v4
- paths
- Files or folders to migrate
- --apply
- Change files instead of only showing changes
python bin/covascensRun Covasim scenarios through the Fire CLI
python examples/run_sim.pyRun and plot a configured simulation example
python examples/run_scenarios.pyRun intervention scenarios and plot uncertainty
python examples/calibration/sweep.pyRun a calibration sweep
python examples/cruise_ship/cruise_ship.pyRun the Diamond Princess cruise ship application
Tests
pytestcd tests && pytest
Artifacts stored with this model.
Identifiers and integrity.
- Metadata review
- Approved · 1da614bf-946a-4400-a0be-4fd0f1d00f74 · Oct 2026
- Contacts
- Covasim project · info@covasim.org
- Publications
- External IDs
- url:https://github.com/starsimhub/covasim