| Name | starsim JSON |
| Version |
3.0.3
JSON |
| download |
| home_page | None |
| Summary | A fast, flexible agent-based disease modeling framework |
| upload_time | 2025-10-08 03:20:52 |
| maintainer | None |
| docs_url | None |
| author | Cliff Kerr, Robyn Stuart, Romesh Abeysuriya, Paula Sanz-Leon, Jamie Cohen, Daniel Klein |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2023 - 2025 Bill & Melinda Gates Foundation
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
agent-based model
simulation
disease
epidemiology
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Starsim
[](https://pypi.org/project/starsim)
[](https://pepy.tech/project/starsim)
[](https://github.com/starsimhub/starsim/actions/workflows/tests.yaml)
[Starsim](https://starsim.org) is an agent-based modeling framework designed for simulating the spread of diseases among agents via dynamic transmission networks. Starsim supports the co-transmission of multiple diseases at once, capturing how they interact biologically and behaviorally. Additionally, users can also include non-infectious diseases either on their own or as factors affecting infectious diseases. To enable the study of birth-related diseases, Starsim allows detailed modeling of mother-child relationships starting from conception. Finally, Starsim lets users compare different intervention strategies, such as vaccines or treatments, to examine their impact through various delivery methods such as mass campaigns or targeted outreach.
Examples of systems that have already been implemented in Starsim include sexually transmitted infections (HIV, HPV, and syphilis, including co-transmission), respiratory infections (tuberculosis and RSV), other infectious diseases (Ebola and cholera), and underlying determinants of health (such as malnutrition).
Note: Starsim is a general-purpose, multi-disease framework that builds on our previous suite of disease-specific models, which included [Covasim](https://covasim.org), [HPVsim](https://hpvsim.org), and [FPsim](https://fpsim.org). In cases where a distinction needs to be made, Starsim is also known as "the Starsim framework" or "Starsim Core," while this collection of other models is known as the "Starsim suite."
For more information about Starsim, please see the [documentation](https://docs.starsim.org). Information about Starsim for R is available at [r.starsim.org](https://r.starsim.org).
## Requirements
Python 3.9-3.13 or R.
We recommend, but do not require, installing Starsim in a virtual environment, such as [Miniconda](https://docs.anaconda.com/miniconda/).
## Installation
### Python
Starsim is most easily installed via [PyPI](https://pypi.org):
```sh
pip install starsim
```
Or with [uv](https://github.com/astral-sh/uv):
```sh
uv init example
cd example
uv add starsim
```
Starsim can also be installed locally (including optional dependencies for testing and documentation). To do this, clone first this repository, then run:
```sh
pip install -e .[dev]
```
(Note: if after doing this, Starsim works, but you see "Import could not be resolved" in your editor, use `pip install -e . --config-settings editable_mode=strict` instead; more info [here](https://docs.basedpyright.com/v1.29.2/usage/import-resolution/#editable-installs).)
### R
R-Starsim is still under development. You can install it 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 is a slightly more realistic example of an SIR model with random connections between agents:
```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 w/ each other
type = 'random', # Here, we use a 'random' network
n_contacts = 10 # Each person has 10 contacts with other people
),
diseases = dict( # *Diseases* add detail on what diseases to model
type = 'sir', # Here, we're creating an SIR disease
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()
sim.plot() # Plot all the sim results
sim.diseases.sir.plot() # Plot the standard SIR curves
```
More usage examples are available in the tutorials, as well as the `tests` folder.
## AI integration
Starsim includes a [model context protocol](https://en.wikipedia.org/wiki/Model_Context_Protocol) (MCP) server that ensures your favorite AI-enabled editor/tool is Starsim-aware. For details, see the [Starsim AI](https://github.com/starsimhub/starsim_ai) project.
## Starsim structure
All core model code is located in the `starsim` subfolder; standard usage is `import starsim as ss`.
The model consists of core classes including `Sim`, `People`, `Disease`, `Network`, `Intervention`, and more. These classes contain methods for running, building simple or dynamic networks, generating random numbers, calculating results, plotting, etc.
The submodules of the Starsim folder are as follows:
- `analyzers.py`: The Analyzers class (for performing analyses on the sim while it's running), and other classes and functions for analyzing simulations.
- `arrays.py`: Classes to handle, store, and update states for people in networks in the simulation including living, mother, child, susceptible, infected, inoculated, recovered, etc.
- `calibration.py`: Class to handle automated calibration of the model to data.
- `connectors.py`: Classes for modulating interactions between modules (e.g. between two diseases).
- `debugtools.py`: Helper functions and classes to aid with debugging model results and performance.
- `demographics.py`: Classes to transform initial condition input parameters for use in building and utilizing networks.
- `diseases.py`: Classes to manage infection rate of spread, prevalence, waning effects, and other parameters for specific diseases.
- `distributions.py`: Classes that handle statistical distributions used throughout Starsim to produce random numbers.
- `interventions.py`: The Intervention class, for adding interventions and dynamically modifying parameters, and classes for each of the specific interventions derived from it.
- `loop.py`: The logic for the main simulation integration loop.
- `modules.py`: Class to handle "module" logic, such as updates (diseases, networks, etc).
- `networks.py`: Classes for creating simple and dynamic networks of people based on input parameters.
- `parameters.py`: Classes for creating the simulation parameters.
- `people.py`: The People class, for handling updates of state for each person.
- `products.py`: Classes to manage the deployment of vaccines and treatments.
- `results.py`: Classes to analyze and save results from simulations.
- `run.py`: Classes for running simulations (e.g. parallel runs and the Scenarios and MultiSim classes).
- `samples.py`: Class to store data from a large number of simulations.
- `settings.py`: User-customizable options for Starsim (e.g. default font size).
- `sim.py`: The Sim class, which performs most of the heavy lifting: initializing the model, running, and plotting.
- `time.py`: Time classes, such as dates, durations, probabilities, and frequencies.
- `timeline.py`: The Timeline class, which coordinates time between the Sim and different modules.
- `utils.py`: Helper functions.
- `version.py`: Version, date, and license information.
Starsim also includes a `starsim_examples` folder, which contains definitions of different examples of diseases, including STIs, Ebola, and cholera. **Note**: these are illustrative examples only for demonstrating Starsim usage and functionality; for actual scientific research, please see other Starsim models, e.g. [STIsim](https://stisim.org).
## Contributing
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).
## Disclaimer
The code in this repository was developed by [IDM](https://idmod.org), the [Burnet Institute](https://burnet.edu.au), and other collaborators to support our joint research on flexible agent-based modeling. We've made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as permitted under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "starsim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "agent-based model, simulation, disease, epidemiology",
"author": "Cliff Kerr, Robyn Stuart, Romesh Abeysuriya, Paula Sanz-Leon, Jamie Cohen, Daniel Klein",
"author_email": "Starsim Development Team <info@starsim.org>",
"download_url": "https://files.pythonhosted.org/packages/a1/fe/a0397ee5e8dbff24b388066053aa58f1ad073e4c37be949cd3042cbea878/starsim-3.0.3.tar.gz",
"platform": null,
"description": "# Starsim\n\n[](https://pypi.org/project/starsim)\n[](https://pepy.tech/project/starsim)\n[](https://github.com/starsimhub/starsim/actions/workflows/tests.yaml)\n\n[Starsim](https://starsim.org) is an agent-based modeling framework designed for simulating the spread of diseases among agents via dynamic transmission networks. Starsim supports the co-transmission of multiple diseases at once, capturing how they interact biologically and behaviorally. Additionally, users can also include non-infectious diseases either on their own or as factors affecting infectious diseases. To enable the study of birth-related diseases, Starsim allows detailed modeling of mother-child relationships starting from conception. Finally, Starsim lets users compare different intervention strategies, such as vaccines or treatments, to examine their impact through various delivery methods such as mass campaigns or targeted outreach.\n\nExamples of systems that have already been implemented in Starsim include sexually transmitted infections (HIV, HPV, and syphilis, including co-transmission), respiratory infections (tuberculosis and RSV), other infectious diseases (Ebola and cholera), and underlying determinants of health (such as malnutrition).\n\nNote: Starsim is a general-purpose, multi-disease framework that builds on our previous suite of disease-specific models, which included [Covasim](https://covasim.org), [HPVsim](https://hpvsim.org), and [FPsim](https://fpsim.org). In cases where a distinction needs to be made, Starsim is also known as \"the Starsim framework\" or \"Starsim Core,\" while this collection of other models is known as the \"Starsim suite.\"\n\nFor more information about Starsim, please see the [documentation](https://docs.starsim.org). Information about Starsim for R is available at [r.starsim.org](https://r.starsim.org).\n\n\n## Requirements\n\nPython 3.9-3.13 or R.\n\nWe recommend, but do not require, installing Starsim in a virtual environment, such as [Miniconda](https://docs.anaconda.com/miniconda/).\n\n\n## Installation\n\n### Python\n\nStarsim is most easily installed via [PyPI](https://pypi.org):\n```sh\npip install starsim\n```\n\nOr with [uv](https://github.com/astral-sh/uv):\n```sh\nuv init example\ncd example\nuv add starsim\n```\n\nStarsim can also be installed locally (including optional dependencies for testing and documentation). To do this, clone first this repository, then run:\n```sh\npip install -e .[dev]\n```\n\n(Note: if after doing this, Starsim works, but you see \"Import could not be resolved\" in your editor, use `pip install -e . --config-settings editable_mode=strict` instead; more info [here](https://docs.basedpyright.com/v1.29.2/usage/import-resolution/#editable-installs).)\n\n\n### R\n\nR-Starsim is still under development. You can install it with:\n\n```R\n# install.packages(\"devtools\")\ndevtools::install_github(\"starsimhub/rstarsim\")\nlibrary(starsim)\ninit_starsim()\n````\n\nSee [r.starsim.org](https://r.starsim.org) for more information.\n\n## Usage and documentation\n\nFull documentation, including tutorials and an API reference, is available at [docs.starsim.org](https://docs.starsim.org).\n\nYou can run a simple demo via:\n\n```py\nimport starsim as ss\nss.demo()\n```\n\nHere is a slightly more realistic example of an SIR model with random connections between agents:\n\n```py\nimport starsim as ss\n\n# Define the parameters\npars = dict(\n n_agents = 5_000, # Number of agents to simulate\n networks = dict( # Networks define how agents interact w/ each other\n type = 'random', # Here, we use a 'random' network\n n_contacts = 10 # Each person has 10 contacts with other people \n ),\n diseases = dict( # *Diseases* add detail on what diseases to model\n type = 'sir', # Here, we're creating an SIR disease\n init_prev = 0.01, # Proportion of the population initially infected\n beta = 0.05, # Probability of transmission between contacts\n )\n)\n\n# Make the sim, run and plot\nsim = ss.Sim(pars)\nsim.run()\nsim.plot() # Plot all the sim results\nsim.diseases.sir.plot() # Plot the standard SIR curves\n```\n\nMore usage examples are available in the tutorials, as well as the `tests` folder.\n\n## AI integration\n\nStarsim includes a [model context protocol](https://en.wikipedia.org/wiki/Model_Context_Protocol) (MCP) server that ensures your favorite AI-enabled editor/tool is Starsim-aware. For details, see the [Starsim AI](https://github.com/starsimhub/starsim_ai) project.\n\n\n## Starsim structure\n\nAll core model code is located in the `starsim` subfolder; standard usage is `import starsim as ss`.\n\nThe model consists of core classes including `Sim`, `People`, `Disease`, `Network`, `Intervention`, and more. These classes contain methods for running, building simple or dynamic networks, generating random numbers, calculating results, plotting, etc.\n\nThe submodules of the Starsim folder are as follows:\n\n- `analyzers.py`: The Analyzers class (for performing analyses on the sim while it's running), and other classes and functions for analyzing simulations.\n- `arrays.py`: Classes to handle, store, and update states for people in networks in the simulation including living, mother, child, susceptible, infected, inoculated, recovered, etc.\n- `calibration.py`: Class to handle automated calibration of the model to data.\n- `connectors.py`: Classes for modulating interactions between modules (e.g. between two diseases).\n- `debugtools.py`: Helper functions and classes to aid with debugging model results and performance.\n- `demographics.py`: Classes to transform initial condition input parameters for use in building and utilizing networks.\n- `diseases.py`: Classes to manage infection rate of spread, prevalence, waning effects, and other parameters for specific diseases.\n- `distributions.py`: Classes that handle statistical distributions used throughout Starsim to produce random numbers.\n- `interventions.py`: The Intervention class, for adding interventions and dynamically modifying parameters, and classes for each of the specific interventions derived from it. \n- `loop.py`: The logic for the main simulation integration loop.\n- `modules.py`: Class to handle \"module\" logic, such as updates (diseases, networks, etc). \n- `networks.py`: Classes for creating simple and dynamic networks of people based on input parameters.\n- `parameters.py`: Classes for creating the simulation parameters.\n- `people.py`: The People class, for handling updates of state for each person.\n- `products.py`: Classes to manage the deployment of vaccines and treatments.\n- `results.py`: Classes to analyze and save results from simulations.\n- `run.py`: Classes for running simulations (e.g. parallel runs and the Scenarios and MultiSim classes).\n- `samples.py`: Class to store data from a large number of simulations.\n- `settings.py`: User-customizable options for Starsim (e.g. default font size).\n- `sim.py`: The Sim class, which performs most of the heavy lifting: initializing the model, running, and plotting.\n- `time.py`: Time classes, such as dates, durations, probabilities, and frequencies.\n- `timeline.py`: The Timeline class, which coordinates time between the Sim and different modules.\n- `utils.py`: Helper functions.\n- `version.py`: Version, date, and license information.\n\nStarsim also includes a `starsim_examples` folder, which contains definitions of different examples of diseases, including STIs, Ebola, and cholera. **Note**: these are illustrative examples only for demonstrating Starsim usage and functionality; for actual scientific research, please see other Starsim models, e.g. [STIsim](https://stisim.org).\n\n## Contributing\n\nQuestions 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).\n\n## Disclaimer\n\nThe code in this repository was developed by [IDM](https://idmod.org), the [Burnet Institute](https://burnet.edu.au), and other collaborators to support our joint research on flexible agent-based modeling. We've made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as permitted under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 - 2025 Bill & Melinda Gates Foundation\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A fast, flexible agent-based disease modeling framework",
"version": "3.0.3",
"project_urls": {
"Source": "https://github.com/starsimhub/starsim/",
"Website": "https://starsim.org"
},
"split_keywords": [
"agent-based model",
" simulation",
" disease",
" epidemiology"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "05d2b6c98afc65de6e0026255af4922989cac09a29490d9bc71a8bc4ba4b6cf2",
"md5": "46038c0400369c770cf769f030141ff9",
"sha256": "dfb4826fadfab8bb1709ac1fb8e273f8176a794d76e74a7aa2de44f4e08a77c1"
},
"downloads": -1,
"filename": "starsim-3.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46038c0400369c770cf769f030141ff9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 933150,
"upload_time": "2025-10-08T03:20:50",
"upload_time_iso_8601": "2025-10-08T03:20:50.143666Z",
"url": "https://files.pythonhosted.org/packages/05/d2/b6c98afc65de6e0026255af4922989cac09a29490d9bc71a8bc4ba4b6cf2/starsim-3.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a1fea0397ee5e8dbff24b388066053aa58f1ad073e4c37be949cd3042cbea878",
"md5": "8ab645ada715cc1d12e16764101256c2",
"sha256": "d7575b20ed8ee872f5d1d2a50e501b6f87de242edf576b72148fe4df27032378"
},
"downloads": -1,
"filename": "starsim-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "8ab645ada715cc1d12e16764101256c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1576167,
"upload_time": "2025-10-08T03:20:52",
"upload_time_iso_8601": "2025-10-08T03:20:52.276297Z",
"url": "https://files.pythonhosted.org/packages/a1/fe/a0397ee5e8dbff24b388066053aa58f1ad073e4c37be949cd3042cbea878/starsim-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 03:20:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "starsimhub",
"github_project": "starsim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "starsim"
}
