🧠5% 🤖95%

User guide

Each page of the user guide covers one topic in full, to read through or to look up as you need it. To learn Starsim from the start, begin with the tutorials. For the exact arguments of a function, see the API.

Introduction

What is Starsim?: what it is for, when to use it instead of code of your own, and models built with it
Conceptual overview: how the parts of a model fit together
FAQ: short answers, with links

Building models

Writing models: the syntax, its defaults, and checking what was built
What can be declared: what a declaration can say, and mixing it with code
Diseases: transitions, durations, branches, and transmission
Parameters: naming, overriding, and varying values
Time: units, dates, steps, and values that change over time
Stratification: splitting states by age, sex, risk, or anything else
Outcomes: what is observed, such as reported cases
Results and plotting: reading, summarizing, exporting, and plotting
Custom modules: behavior written as code
Import/export: models from and to other frameworks

Populations and data

People and demographics: the population; births, deaths, migration, and pregnancy
Mixing: who meets whom: contact matrices, movement, and networks
Places and data: country data, places, and maps

Interventions and analyzers

Products: vaccines, treatments, and diagnostics
Interventions: delivering products, and changing parameters during a run
Analyzers: results the other modules don’t keep
Connectors: diseases that interact, and other links between modules

Running models

Running sims: settings, copying, saving, and resuming
Scenarios: paired comparisons, repeated runs, and uncertainty
Solvers and backends: which solver, and what needs agents
Speed and scale: finding the bottleneck, many runs, and clusters
Branching and rescaling: large populations and small outbreaks
Profiling and debugging: symptoms, causes, and fixes

Calibration

Fitting a model: data, likelihoods, and the fit
Fitting methods: choosing a method
Fit diagnostics: checking a fit, and what the data can pin down
Gradients: derivatives of results, and what they enable
Optimization: allocating a budget for the best outcome

Library

Library: what it is, and how far to trust it
Library: diseases: HIV, cholera, measles, and more, to adapt
Library: networks: household, spatial, and theoretical networks
Library: maternal-child health: fetal health, maternal infections, and neonatal outcomes
Library: health economics: the costs of interventions, DALYs, and cost per outcome averted

Mechanics

Array indexing: agents, UIDs, and arrays
Distributions: random draws, for parameters and for agents
Random numbers: common random numbers, and their limits

Architecture

How Starsim works inside: for contributors, and for anyone curious. No model needs these pages.

Overview: the layers, and what a module is
From declaration to run: the steps from a declared model to a run
Engines and transmission: the engines, and how transmission is computed

Running the user guide locally

The pages are in docs/user_guide in the Starsim repository. Clone it, install Starsim (pip install -e .), and open them in Jupyter (jupyter lab, with jupytext installed to open .qmd files directly).