This release is a pre-release and may not be stable for production use.
Starsim
Note: Starsim v4 is now available. It's quite different from v3, with a new and simpler syntax for creating diseases, and support for compartmental and geospatial models. Models written for v3 will need to be migrated; see the changelog for details, or contact us for help. To continue using Starsim v3, use
pip install starsim<4; the v3 docs are also still available. But really, please upgrade to v4! You'll be glad you did!
Starsim is a fast, flexible disease modeling framework, from compartments to agents. It supports modeling multiple co-transmitting diseases, including infectious and non-infectious diseases plus other health states (such as pregnancy and birth), and captures their biological and behavioral interactions. It lets users compare intervention strategies, such as vaccines or treatments, across delivery methods like mass campaigns or targeted outreach. It also includes built-in tools for scenario analyses and calibrating models to real-world data.
Starsim builds on our previous suite of disease-specific models, including Covasim and HPVsim, as well as many other disease modeling frameworks (see below). It can model different levels of detail, including agent-based, metapopulation, and deterministic or stochastic compartmental modeling. It is designed to be simple and fast enough to enable rapid or exploratory analyses (from project start to calibrated model and scenario analyses in hours to days), while also being flexible enough to support complex, long-term research projects (such as intrahost immunity, data-driven spatial network transmission, and health economics optimization).
For more information, see the documentation or the code. For Starsim for R, see r.starsim.org. For Starsim's AI tools, see ai.starsim.org.
Starsim features
Starsim includes an extensive library of features aimed to support a broad diversity of disease modeling needs. The full set is covered in the documentation. Because the features are modular and written in Python, you can mix-and-match Starsim features with custom-written code, and you only use what you need. Highlights include:
- Modeling modalities: Switch between compartmental, stochastic compartmental, metapopulation, and agent-based modeling using a flag (
solver='abm') without needing to rewrite any code (solvers); - Performance: Numeric kernels are heavily optimized, with Numba and Rust kernels that give the same numbers, plus GPU support (via JAX) (performance);
- Diseases: A large library of already-implemented diseases including COVID, flu, measles, malaria, syphilis, gonorrhea, cholera, Ebola and many others (plus HIV, TB, COVID, HPV, chlamydia, typhoid, and others in the models below); diseases support coinfection between different diseases, as well as multiple strains of a single disease (library diseases, diseases);
- Networks: Contact networks including age-stratified contact matrices, sexual (including male-female, male-male, and commercial), respiratory (household/workplace/school); also supports other forms of disease transmission including environmental and vector-borne (networks, library networks);
- Interventions: Flexible options for representing interventions, including screening, diagnostics, treatments, vaccination, and care cascades; health system considerations such as prioritization, capacity constraints, and clinic visits (interventions, products);
- Costing: Support for intervention- and disease-related costs, health outcomes like disability-adjusted life years (DALYs), and budget optimization (costs, optimization);
- Time: Unit-aware time and date handling, including natural dates for data and plotting, module-specific timesteps, and timestep-aware conversion of rates and probabilities (time);
- Data and places: Extensive built-in data, including population and age structures for 187 countries and territories, contact matrices (Prem et al., 2021), and geospatial boundaries, with maps and animations of results by place (population data, geography);
- Fitting: Automatic gradients for compartmental models, plus Bayesian fitting and calibrating algorithms including no-U-turn sampling (NUTS) and the tree-structured Parzen estimator (Optuna) (fitting, methods);
- Scientific rigor: Automatic checking of units to prevent common programming errors; common random numbers that allow exact comparison between even stochastic model runs (time, random numbers);
- Intercompatibility: Automated import from more than a dozen other disease modeling frameworks, and export to SBML and odin (import and export); interoperable with other disease modeling tools like GeoPops and HubVerse;
- AI support: Extensive set of skills and plugins that help implement Starsim models (AI integration), including no-code chat interfaces for policymakers (EpiChat).
Starsim "stands on the shoulders of giants", and aims to build on the best aspects of other disease modeling frameworks. It is especially indebted to EpiModel, MEmilio, SimInf, summer2, camdl, epidemics, and epydemix (see the full list). If there's a feature you think Starsim should support, please get in touch.
Starsim models
Starsim is the basis of several other established disease modeling frameworks. These include:
- Covasim, for modeling COVID-19;
- HPVsim, for modeling human papillomavirus and cervical cancer;
- STIsim, for modeling HIV, syphilis, gonorrhea, chlamydia, trichomoniasis, and bacterial vaginosis (including co-transmission);
- TBsim, for modeling tuberculosis, including drug resistance;
- FPsim, for modeling family planning and women's life courses.
- Typhoidsim, for modeling typhoid, including environmental transmission.
A full list of diseases modeled using Starsim is available in the documentation.
Installation
If you're new to Python, check out our getting started guide. You can also use our installer, which will install Python along with all required dependencies. On Linux and macOS, run:
curl -LsSf https://docs.starsim.org/install.sh | sh
On Windows, download install.bat and double-click it.
Requirements
Python 3.12-3.14 or R.
We recommend, but do not require, installing Starsim in a virtual environment, such as uv or conda.
Python
Starsim is most easily installed via PyPI:
pip install "starsim[jax]"
starsim init
JAX is recommended if you'll be calibrating compartmental models -- otherwise you can skip it, i.e. pip install starsim.
starsim init compiles numeric kernels if needed (usually it's not). It also asks if you want to install Starsim's AI skills (so you can type /starsim in your agent to use them). To do either the compile or the AI install, run starsim init compile or starsim init ai.
You can also of course install with uv:
uv init example
cd example
uv add "starsim[jax]"
To work on Starsim itself, clone this repository, then run:
pip install -e .
starsim init dev
This installs the optional dependencies for testing and documentation, and JAX; installs Rust if it is missing; and builds Starsim's kernels. See the developer guide for details.
R
R-Starsim can be installed with:
# install.packages("devtools")
devtools::install_github("starsimhub/rstarsim")
library(starsim)
init_starsim()
See r.starsim.org for more information.
Documentation
Full documentation, including tutorials and an API reference, is available at docs.starsim.org.
Usage
You can run a simple demo via:
import starsim as ss
ss.demo()
Here's a minimal SIR model, with an infection rate of β = 0.3 per day and an infectious period of 10 days, written much as you'd write it on paper:
import starsim as ss
S, I, R = ss.states('S I R') # Create the SIR states
infection = S >> I @ 0.3*I # From S to I, at a rate of β times the fraction infectious
recovery = I >> R @ ss.days(10) # From I to R, after 10 days on average
sir = ss.Disease(infection, recovery) # Create the disease from the transitions
sim = ss.Sim(sir)
sim.run()
sim.sir.plot()
The same model, written out in full:
import starsim as ss
S = ss.State(label='Susceptible')
I = ss.State(label='Infectious')
R = ss.State(name='Recovered')
beta = ss.perday(0.3)
dur_inf = ss.expon(mean=ss.days(10))
sir = ss.Disease(
name = 'SIR',
transitions = [
ss.Transition(source=S, dest=I, rate=beta*I, name='infection'),
ss.Transition(source=I, dest=R, dur=dur_inf, name='recovery'),
],
)
sim = ss.Sim(diseases=sir, solver='ode')
sim.run()
sim.plot()
These run as a compartmental model (an ODE). To run the same model as agents, give the number of agents, e.g. ss.Sim(sir, n_agents=5_000).
You can also run the same example from R:
library(starsim)
states("S I R")
sir <- Disease(
infection = Transition(S, I, rate = 0.3 * I), # From S to I, at a rate of β times the fraction infectious
recovery = Transition(I, R, dur = days(10)) # From I to R, after 10 days on average
)
sim <- Sim(sir)
sim$run()
sim$plot()
More usage examples are available in the tutorials and user guide.
AI integration
Starsim comes with skills for AI coding agents (Claude Code, Codex, and others), which always match the version installed: how to write, check, and run a model, and how to import a model from another framework or upgrade one from Starsim v3. starsim init ai links them into your project, and starsim ai install --global sets them up for all your projects instead. You can also install them with other standard tools, such as uvx library-skills. starsim ai "how would I model a leaky vaccine?" asks your agent a question about Starsim (-i for an interactive session), and starsim help RandomNet looks a name or term up in the docs, without an agent. For anything else, llms.txt is a map of the docs and the API for agents.
Contributing
We welcome contributions of all kinds! Questions or comments can be directed to info@starsim.org , or on this project's GitHub page. Full information about Starsim is provided in the documentation.
AI disclaimer
We believe in being transparent about AI use. Each page comes with a little note estimating the human vs. AI contribution; hover to get more info. For this page:
Metadata
Release files for starsim 4.0.0rc4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| starsim-4.0.0rc4.tar.gz | 3.7 MB | With provenance | Details for starsim-4.0.0rc4.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| starsim-4.0.0rc4-cp312-abi3-win_arm64.whl | CPython 3.12 | abi3 | Windows ARM64 | Details for starsim-4.0.0rc4-cp312-abi3-win_arm64.whl |
| starsim-4.0.0rc4-cp312-abi3-win_amd64.whl | CPython 3.12 | abi3 | Windows x86-64 | Details for starsim-4.0.0rc4-cp312-abi3-win_amd64.whl |
| starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.28+ x86-64 | Details for starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_x86_64.whl |
| starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_aarch64.whl | CPython 3.12 | abi3 | Linux glibc 2.28+ ARM64 | Details for starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_aarch64.whl |
| starsim-4.0.0rc4-cp312-abi3-macosx_11_0_arm64.whl | CPython 3.12 | abi3 | macOS 11.0+ ARM64 | Details for starsim-4.0.0rc4-cp312-abi3-macosx_11_0_arm64.whl |
Total release size: 18.1 MB
Release files / starsim-4.0.0rc4.tar.gz
| Download URL | starsim-4.0.0rc4.tar.gz |
|---|---|
| Size | 3.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc2d5b87fdcc29e1d9317f36c2d47d3722c06ed0c9a060edb383768b2d9c9cd6
|
|
BLAKE2b-256 checksum How to use checksums |
5753171d5b08bc9be31ff8c3c6f13998098a2f089d44abbbdce41da706720857
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / starsim-4.0.0rc4-cp312-abi3-win_arm64.whl
| Download URL | starsim-4.0.0rc4-cp312-abi3-win_arm64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.12 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
5ee2144c984e522a92aa6bcb3c7079713fdc69b5e1f4efd609702e75566fd6c2
|
|
BLAKE2b-256 checksum How to use checksums |
e0e53dbaa6ba8c62dda467cb8a9a264c6ccf0c02b317893787edc3d0532437bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / starsim-4.0.0rc4-cp312-abi3-win_amd64.whl
| Download URL | starsim-4.0.0rc4-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a244cdea4f7cda7758d8edfaff7b6634a988b8cd6dc06e853971451b9049eb97
|
|
BLAKE2b-256 checksum How to use checksums |
648d53f1302b5327ed6b836c983b77786343e71419f6094d73bf284c6471e57b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_x86_64.whl
| Download URL | starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
60e28b7daad7fbe3488e16ea2fdd97d9693ba43da4196955cf03e243c6c8da0c
|
|
BLAKE2b-256 checksum How to use checksums |
71589b8456b29bb52bdd3d564fbaaf33c9a2f97551cc8b9ab55d3be59f22ef58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_aarch64.whl
| Download URL | starsim-4.0.0rc4-cp312-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
7938f1a014d7648f10ee077e21fa11ae6d668bea9e17cfd80efce4436994863d
|
|
BLAKE2b-256 checksum How to use checksums |
46344139a3024c6f7f7570dc4ae5728118a4ef9905ffec0dd742ae375522bd93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / starsim-4.0.0rc4-cp312-abi3-macosx_11_0_arm64.whl
| Download URL | starsim-4.0.0rc4-cp312-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.12 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a19bf0694aaa3a1a8ea48a164f5d42fe73f48665310254ab8753baba6b27ae88
|
|
BLAKE2b-256 checksum How to use checksums |
09a30050f9086491ee5d495ba50bcd1d23047521db9d2caafced2b4cbdd8a946
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for starsim 4.0.0rc4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for starsim-4.0.0rc4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.