Welcome! We are thrilled you are interested in contributing to Starsim. There are many ways to help: asking a question, reporting a bug, suggesting a feature, improving the docs, or contributing code or models.
Feel free to open an issue on more or less anything: this project is small enough that we don’t need a formal triage system. Questions can also go to info@starsim.org, or to the Starsim Slack. We are serious about inclusion, and the Starsim community follows a code of conduct: by participating in this project, you agree to abide by its terms.
Reporting a problem
The most useful thing to include when asking for help or reporting a bug is a minimal reproducible example: the shortest complete script that shows the problem, which anyone can run as it is. Making one often finds the cause on the way.
How to make one
Start from what fails, in a fresh session. Restart the notebook’s kernel (or run the script from the command line) and check that the problem is still there: a notebook can hold values from cells changed or deleted since.
Remove what doesn’t matter, one thing at a time. Take out interventions, analyzers, extra diseases, networks, and data, checking after each that the problem is still there. If it goes away, what you just removed is part of the cause.
Make it small and quick. Use fewer agents (or none, if the problem shows in an ODE), a shorter run, and plain numbers in place of values read from files.
Replace private data with made-up data. A few rows typed in, or data drawn from a run of the model with sim.to_synthetic_data(), show the same problem without sharing anything.
Fix the random seed (rand_seed= in ss.Sim), so that a stochastic run gives the same numbers every time.
Say what you expected, and what you got. Print the numbers, or include the plot, and give the reason you expected something else (a known result, another model, a calculation by hand).
An example
A report that a vaccine works less well than expected might come down to this script, which runs in a second:
import starsim as ssS, I, R = ss.states('S I R')infection = S >> I @1.9*Irecovery = I >> R @ ss.days(8)measles = ss.Disease(infection, recovery, init_prev=0.001)vaccination = ss.vaccinate(efficacy=0.9, when=ss.days(0), coverage=0.9)sim = ss.Sim(measles, interventions=vaccination, total_pop=100_000, stop=ss.days(100), rand_seed=1)sim.run()# Expected: at most 19,000 infections (the 10% not vaccinated, plus the 10% of the vaccinated whom the vaccine doesn't protect)print('Infections:', round(sim.results.measles.infection.sum()))
Sim: measles, 100,000 people, as an ODE, days 0 to 100
measles: R0 = 15.2, with 100 infectious at the start
Done in 0.0083 s; measles: 67,471 infections; at most 13,315 infectious, on day 34
Infections: 67471
When a model is built by several functions or read from files, copy the parts that matter into one script, with the values written in, and check that it still shows the problem. A model imported from another framework is already one script: its code is sim.imported.code (see Import/export).
Pull requests should be made against main. Please follow the house style guide (Starsim more or less follows Google’s Python style guide, but with some exceptions), make sure the tests pass, and add an entry to the changelog. The developer guide has the details.
Models and modules are welcome too: a disease, network, or intervention that others could use may belong in the model library, and a complete model may belong in the gallery. Open an issue first to discuss it.