Metadata-Version: 2.4
Name: starsim
Version: 4.0.0rc2
Summary: A fast, flexible disease modeling framework, from compartments to agents
Author: Cliff Kerr, Robyn Stuart, Romesh Abeysuriya, Paula Sanz-Leon, Jamie Cohen, Daniel Klein
Author-email: Starsim Development Team <info@starsim.org>
License-Expression: MIT
Project-URL: Website, https://starsim.org
Project-URL: Source, https://github.com/starsimhub/starsim/
Keywords: disease modeling,epidemiology,infectious disease,simulation,compartmental model,stochastic model,metapopulation model,agent-based model
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=3.0
Requires-Dist: sciris>=3.7.0
Requires-Dist: numba>=0.59.0
Requires-Dist: scipy
Requires-Dist: networkx
Requires-Dist: matplotlib
Requires-Dist: optuna
Requires-Dist: starsim_data>=2.1.0
Provides-Extra: jax
Requires-Dist: jax>=0.8; extra == "jax"
Requires-Dist: blackjax; extra == "jax"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-env; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pylint; extra == "test"
Provides-Extra: doc
Requires-Dist: quartopydoc; extra == "doc"
Requires-Dist: sphobjinv; extra == "doc"
Requires-Dist: jupyter; extra == "doc"
Requires-Dist: jupytext; extra == "doc"
Requires-Dist: starsim_data[spatial]; extra == "doc"
Provides-Extra: dev
Requires-Dist: starsim[doc,jax,test]; extra == "dev"
Provides-Extra: fastmath
Requires-Dist: mkl; extra == "fastmath"
Requires-Dist: intel-cmplr-lib-rt; extra == "fastmath"
Provides-Extra: lock
Requires-Dist: absl-py==2.5.1; extra == "lock"
Requires-Dist: alembic==1.20.1; extra == "lock"
Requires-Dist: blackjax==1.7.1; extra == "lock"
Requires-Dist: colorlog==6.12.0; extra == "lock"
Requires-Dist: contourpy==1.4.0; extra == "lock"
Requires-Dist: cycler==0.12.1; extra == "lock"
Requires-Dist: dill==0.4.1; extra == "lock"
Requires-Dist: et-xmlfile==2.0.0; extra == "lock"
Requires-Dist: fonttools==4.68.0; extra == "lock"
Requires-Dist: gitdb==4.0.12; extra == "lock"
Requires-Dist: gitpython==3.2.1; extra == "lock"
Requires-Dist: h5py==3.16.0; extra == "lock"
Requires-Dist: jax==0.12.0.1; extra == "lock"
Requires-Dist: jaxlib==0.12.0.1; extra == "lock"
Requires-Dist: jellyfish==1.3.0; extra == "lock"
Requires-Dist: jsonpickle==4.1.4; extra == "lock"
Requires-Dist: kiwisolver==1.5.1; extra == "lock"
Requires-Dist: line-profiler==5.1.0; extra == "lock"
Requires-Dist: llvmlite==0.50.0; extra == "lock"
Requires-Dist: mako==1.4.3; extra == "lock"
Requires-Dist: markupsafe==3.0.4; extra == "lock"
Requires-Dist: matplotlib==3.11.2; extra == "lock"
Requires-Dist: memory-profiler==0.61.0; extra == "lock"
Requires-Dist: ml-dtypes==0.6.0; extra == "lock"
Requires-Dist: multiprocess==0.70.19; extra == "lock"
Requires-Dist: networkx==3.7; extra == "lock"
Requires-Dist: numba==0.68.1; extra == "lock"
Requires-Dist: numpy==2.5.4; extra == "lock"
Requires-Dist: openpyxl==3.1.5; extra == "lock"
Requires-Dist: opt-einsum==3.4.0; extra == "lock"
Requires-Dist: optax==0.2.8; extra == "lock"
Requires-Dist: optuna==5.0.0; extra == "lock"
Requires-Dist: packaging==26.3; extra == "lock"
Requires-Dist: pandas==3.1.0; extra == "lock"
Requires-Dist: pillow==13.0.0; extra == "lock"
Requires-Dist: psutil==7.2.2; extra == "lock"
Requires-Dist: pyparsing==3.3.3; extra == "lock"
Requires-Dist: python-dateutil==3.0.0; extra == "lock"
Requires-Dist: pyyaml==6.0.3; extra == "lock"
Requires-Dist: scipy==1.18.1; extra == "lock"
Requires-Dist: sciris==3.7.0; extra == "lock"
Requires-Dist: setuptools==84.2.1; extra == "lock"
Requires-Dist: six==1.17.0; extra == "lock"
Requires-Dist: smmap==5.0.3; extra == "lock"
Requires-Dist: sqlalchemy==2.1.6; extra == "lock"
Requires-Dist: starsim-data==2.2.0; extra == "lock"
Requires-Dist: tqdm==4.70.1; extra == "lock"
Requires-Dist: typing-extensions==4.16.0; extra == "lock"
Requires-Dist: tzdata==2026.6; extra == "lock"
Requires-Dist: xlsxwriter==3.3.1; extra == "lock"
Requires-Dist: zstandard==0.25.0; extra == "lock"
Provides-Extra: optuna
Requires-Dist: scikit-learn; extra == "optuna"
Dynamic: license-file

# Starsim

[![PyPI version](https://badgen.net/pypi/v/starsim/?color=blue)](https://pypi.org/project/starsim)
[![Downloads](https://static.pepy.tech/personalized-badge/starsim?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads)](https://pepy.tech/project/starsim)
[![Tests](https://github.com/starsimhub/starsim/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/starsimhub/starsim/actions/workflows/tests.yml)

[Starsim](https://starsim.org) 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](https://covasim.org) and [HPVsim](https://hpvsim.org), 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](https://docs.starsim.org) or the [code](https://github.com/starsimhub/starsim). For Starsim for R, see [r.starsim.org](https://r.starsim.org). For Starsim's AI tools, see [ai.starsim.org](https://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](https://docs.starsim.org/user_guide.html). 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](https://starsim.org/v4/user_guide/running_solvers.html));
- **Performance:** Numeric kernels are heavily optimized, with Numba and Rust kernels that give the same numbers, plus GPU support (via JAX) ([performance](https://starsim.org/v4/user_guide/running_performance.html));
- **Diseases:** A large library of already-implemented diseases including HIV, TB, malaria, COVID, flu, measles, syphilis, gonorrhea, typhoid, cholera, Ebola and many others (plus HPV, chlamydia, rotavirus, and others in the models below); diseases support coinfection between different diseases, as well as multiple strains of a single disease ([library diseases](https://starsim.org/v4/user_guide/library_diseases.html), [diseases](https://starsim.org/v4/user_guide/building_diseases.html));
- **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](https://starsim.org/v4/user_guide/populations_networks.html), [library networks](https://starsim.org/v4/user_guide/library_networks.html));
- **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](https://starsim.org/v4/user_guide/interventions_interventions.html), [products](https://starsim.org/v4/user_guide/interventions_products.html));
- **Costing:** Support for intervention- and disease-related costs, health outcomes like disability-adjusted life years (DALYs), and budget optimization ([costs](https://starsim.org/v4/user_guide/interventions_costs.html), [optimization](https://starsim.org/v4/user_guide/calibration_optimization.html));
- **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](https://starsim.org/v4/user_guide/building_time.html));
- **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](https://starsim.org/v4/user_guide/populations_data.html), [geography](https://starsim.org/v4/user_guide/populations_geography.html));
- **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](https://starsim.org/v4/user_guide/calibration_fitting.html), [methods](https://starsim.org/v4/user_guide/calibration_methods.html));
- **Scientific rigor:** Automatic checking of units to prevent common programming errors; common random numbers that allow exact comparison between even stochastic model runs ([time](https://starsim.org/v4/user_guide/building_time.html), [random numbers](https://starsim.org/v4/user_guide/mechanics_random.html));
- **Intercompatibility:** Automated import from more than a dozen other disease modeling frameworks, and export to SBML and odin ([import and export](https://starsim.org/v4/user_guide/conversion/index.html)); interoperable with other disease modeling tools like [GeoPops](https://github.com/starsimhub/geopops) and [HubVerse](https://hubverse.io/);
- **AI support:** Extensive set of skills and plugins that help implement Starsim models ([AI integration](#ai-integration)), including no-code chat interfaces for policymakers ([EpiChat](https://github.com/starsimhub/epichat)).
<!-- V4-PREVIEW: restore the starsim.org/v4 links above to docs.starsim.org for normal publishing -->

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](https://www.epimodel.org/), [MEmilio](https://github.com/SciCompMod/memilio), [SimInf](https://github.com/stewid/SimInf), [summer2](https://github.com/monash-emu/summer2), [camdl](https://github.com/vsbuffalo/camdl), [epidemics](https://epiverse-trace.github.io/epidemics/), and [epydemix](https://github.com/epistorm/epydemix) (see the [full list](https://starsim.org/v4/user_guide/library_landscape.html)). If there's a feature you think Starsim should support, please [get in touch](mailto:info@starsim.org).


## Starsim models

Starsim is the basis of several other established disease modeling frameworks. These include:

- [Covasim](https://covasim.org), for modeling COVID-19;
- [HPVsim](https://hpvsim.org), for modeling human papillomavirus and cervical cancer;
- [STIsim](https://stisim.org), for modeling HIV, syphilis, gonorrhea, chlamydia, trichomoniasis, and bacterial vaginosis (including co-transmission);
- [TBsim](https://starsim.org/tbsim), for modeling tuberculosis, including drug resistance;
- [FPsim](https://fpsim.org), for modeling family planning and women's life courses.

A full list of diseases modeled using Starsim is available in the [documentation](https://docs.starsim.org/user_guide/intro_models).


## Installation

If you're new to Python, check out our [getting started guide](https://starsim.org/getting-started/). You can also use our [installer](https://starsim.org/install.sh), which will install Python along with all required dependencies.

### Requirements

Python 3.12-3.14 or R.

We recommend, but do not require, installing Starsim in a virtual environment, such as [uv](https://github.com/astral-sh/uv) or [conda](https://conda-forge.org/download/).

### Python

Starsim is most easily installed via [PyPI](https://pypi.org):
```sh
pip install "starsim[jax]"
starsim init
```

JAX is recommended, for gradients, fitting with them, and long runs. It is optional since it has no builds for Windows on Arm: there, use `pip install starsim`, and everything else works. Intel Macs are not supported.

`starsim init` compiles Numba's kernels if the Rust ones are not available (which takes a few minutes, once, and makes the first runs faster; the wheels on PyPI include the Rust kernels, so there is usually nothing to compile) and, if an AI coding agent such as Claude Code or Codex is installed, links Starsim's skills into your project (type `/starsim` to use them). To do just one of these, run `starsim init compile` or `starsim init ai`.

Or with [uv](https://github.com/astral-sh/uv):
```sh
uv init example
cd example
uv add "starsim[jax]"
```

To work on Starsim itself, clone this repository, then run:
```sh
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](https://docs.starsim.org/contributing/developer.html) for details.

### R

R-Starsim can be installed with:

```R
# install.packages("devtools")
devtools::install_github("starsimhub/rstarsim")
library(starsim)
init_starsim()
```

See [r.starsim.org](https://r.starsim.org) for more information.


## Usage and documentation

Full documentation, including tutorials and an API reference, is available at [docs.starsim.org](https://docs.starsim.org).

You can run a simple demo via:

```py
import starsim as ss
ss.demo()
```

Here's how you'd write a minimal compartmental SIR model with an infection rate of 0.3 per step and a mean recovery duration of 10 steps:

```py
import starsim as ss

S, I, R = ss.states(3)
sir = ss.Disease(
    infection = ss.Transition(S, I, rate=0.3*I),
    recovery = ss.Transition(I, R, dur=10)
)

sim = ss.Sim(sir).run()
sim.sir.plot()
```

If you prefer something that looks more like equations rather than code, there's an even more compact notation available:

```py
import starsim as ss

S, I, R = ss.states(3) # Create model states
inf = S >> I @ 0.3*I   # Define infection at rate beta, mediated by I (*S/N implied)
rec = I >> R @ 0.1     # Define spontaneous recovery
ss.Sim(inf, rec).run().plot() # Create, run, and plot the simulation
```

The code above runs as a compartmental model by default, but you can also run it as an agent-based model (ABM) if you prefer. ABMs come with additional flexibility, such as defining explicit contact networks:

```py
import starsim as ss

# Define the parameters
pars = dict(
    n_agents = 5_000,     # Number of agents to simulate
    networks = dict(      # Networks define how agents interact with each other
        type = 'random',  # Use the built-in 'random' network
        n_contacts = 10   # Each person has 10 contacts with other people  
    ),
    diseases = dict(      # Define the disease dynamics
        type = 'sir',     # Use the built-in SIR disease (including built-in parameters)
        init_prev = 0.01, # Proportion of the population initially infected
        beta = 0.05,      # Probability of transmission between contacts
    )
)

# Make the sim, run and plot
sim = ss.Sim(pars)
sim.run() # Runs as an agent-based model since uses an explicit network
sim.plot() # Plot all the sim results
sim.sir.plot() # Plot the standard SIR curves
```

Or from R:

```R
library(starsim)
load_starsim()

# Define the parameters
pars <- list(
    n_agents = 5000,
    networks = list(type = 'random'),
    diseases = list(type = 'sir', beta = 0.1)
)

# Create, run, and plot the simulation
sim <- ss$Sim(pars)
sim$run()
sim$diseases$sir$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 3. `starsim init ai` (part of `starsim init`) links them into your project, and `starsim ai install --global` sets them up for all your projects instead; tools that read skills from installed packages, such as `uvx library-skills`, find them too. For anything else, [llms.txt](https://docs.starsim.org/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](mailto:info@starsim.org) , or on this project's [GitHub](https://github.com/starsimhub/starsim) page. Full information about Starsim is provided in the [documentation](https://docs.starsim.org).


## 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:

[*Authorship*: 🧠90%, 🤖10%](# "Humans wrote everything, except some of the code examples were AI-generated")
