FAQ
Short answers to common questions, each with a link to the page that covers it in full.
Getting started
Do I need to understand all of Starsim to use it?
No! Starsim covers a lot (compartmental and agent-based models, networks, demographics, geography, calibration, and more), but you only need the parts your model uses, and the rest stays out of the way. (By analogy: you probably use pandas, but you’ve probably never used extractall.) A simple SIR model is a few lines, and needs nothing from the pages on networks or custom modules.
To get started, follow T1–T3, then the tutorials your model needs (the tutorials page helps you choose), and look things up in this user guide as you go. Agent-based models are written the same way; the “Advanced” sections of the tutorials show what changes as agents. No model needs the Architecture pages.
Can I use Starsim with an AI coding agent?
Yes. Run starsim init ai in your project: it gives your agent (Claude Code, Codex, and others) Starsim’s skills, which match the installed version, for writing, checking, running, and converting models. See ai.starsim.org.
Why is Starsim built this way?
We were fed up with the limitations of existing disease models (especially our own!), and asked: “Can we build a disease modeling framework that functions as a ‘lingua franca’, that pays homage to the best aspects of all the other disease models that have come before?” The answer is of course “lol no”, but we did our best! For an (extremely) detailed explanation of the design, see the Lingua Franca docs.
Where can I get help?
Email us! Profiling and debugging covers common pitfalls. To report a bug, open an issue on GitHub with the smallest script that shows it (see Contributing).
Building models
Should I build a compartmental model or an agent-based model?
You don’t have to decide up front. A model written as states and transitions can run either way: by default it runs as an ODE, and as agents once something in it needs individuals, such as a contact network or a value kept for each person. You can also ask for a solver by name (ss.Sim(..., solver='abm')), and run the same model both ways to see what the individual detail changes. Solvers and backends has a table of which to use for which question.
Can I write parts of a model as Python code?
Yes. A model can be fully declared (states, transitions, and rates), fully written as code, or a mix of the two, e.g. a declared disease with an intervention written as a function. Declared parts get diagrams, equations, every solver, and fast fitting without any more work; coded parts can do anything Python can. See What can be declared for how to mix them, and Custom modules for writing modules as code.
Are the models in the library ready to use?
They are starting points, not models of a particular setting. The library of diseases, networks, and maternal-child health modules is illustrative rather than validated: some parameter values are placeholders, and interfaces may change between versions. Copy one and adapt it, with parameters from the evidence for your setting and checks against data. The same goes for any runnable example in these docs.
I have a model in Starsim 3 or another framework. Can I bring it over?
In almost all cases, yes. Starsim imports models from more than a dozen frameworks, including EpiModel, odin, and epydemix, and Starsim 3 code can be rewritten with python -m starsim.converters.migrate. See Import/export and the migration guide. If a model doesn’t translate, email us or open an issue.
Running and fitting
Why is my first run slow?
The first run after installing Starsim may compile its kernels with Numba, which takes a few minutes, once; they are then kept on disk. (The wheels from pip install starsim include a Rust copy of the kernels, compiled ahead of time, which avoids this.) To compile everything up front, e.g. when building a Docker image or before a batch of runs on a cluster, run ss.compile(), or starsim init compile from the command line. See Solvers and backends.
How large a population can Starsim model?
As compartments, any size: a compartmental run takes the same time for a thousand people as for a billion (except with Gillespie’s method, which takes one event at a time). As agents, the time grows with the number of agents, so a large population is usually represented by having each agent stand for several people. See Branching and rescaling and Speed and scale.
How do I fit a model to data?
Give the parameters you want fitted bounds, give the sim data whose columns are named like its results, and call sim.fit(). There is no function to write that puts the values into the model or pulls out the results to compare. See T6 – Data and calibration to start, and Fitting a model for the details.
Why do two runs give different results, and how do I make them match?
A stochastic run (agents, or a stochastic compartmental solver) depends on its random seed, rand_seed: the same seed gives the same results, and different seeds give different ones. One stochastic run is not a result, so run several seeds and look at the spread. When comparing scenarios, Starsim uses common random numbers, so that two runs with the same seed differ much less by chance, and more of their difference comes from what was changed. See Scenarios and Random numbers.