Vivarium cluster tools is a python package that makes running vivarium simulations at scale on a Slurm cluster easy.
Supported Python versions: 3.11, 3.12, 3.13
You can install vivarium-cluster-tools from PyPI with pip:
pip install vivarium-cluster-toolsor build it from source by cloning the monorepo and installing this package:
git clone https://github.com/ihmeuw/vivarium-suite.git
cd vivarium-suite
pip install libs/cluster-toolsA simple example
If you have a vivarium model specification file defining a particular model, you can use that along side a branches file to launch a run of many simulations at once with variations in the input data, random seed, or with different parameter settings.
psimulate run /path/to/model_specification.yaml /path/to/branches_file.yamlThe simplest branches file defines a count of input data draws and random seeds to launch.
input_draw_count: 25
random_seed_count: 10This branches file defines a set of simulations for all combinations of 25 input draws and 10 random seeds and so would run, in total, 250 simulations.
You can also define a set of parameter variations to run your model over. Say your original model specification looked something like
plugins:
optional: ...
components:
vivarium.public_health:
population:
- BasePopulation()
disease.models:
- SIS('lower_respiratory_infections')
my_lri_intervention:
components:
- GiveKidsVaccines()
configuration:
population:
population_size: 1000
age_start: 0
age_end: 5
lri_vaccine:
coverage: 0.2
efficacy: 0.8Defining a simple model of lower respiratory infections and a vaccine intervention. You could then write a branches file that varied over both input data draws and random seeds, but also over different levels of coverage and efficacy for the vaccine. That file would look like
input_draw_count: 25
random_seed_count: 10
branches:
- lri_vaccine:
coverage: [0.0, 0.2, 0.4, 0.8, 1.0]
efficacy: [0.4, 0.6, 0.8]The branches file would overwrite your original lri_vaccine configuration with each combination of coverage and efficacy in the branches file and launch a simulation. More, it would run each coverage-efficacy pair in the branches for each combination of input draw and random seed to produce 25 * 10 * 5 * 3 = 3750 unique simulations.
Multi-step workflows with dagger
For pipelines that chain several steps together, dagger runs a multi-step Jobmon workflow defined in a YAML configuration file. Each step lists its command and compute resources:
workflow:
name: my_pipeline
project: proj_simscience
queue: all.q
output_directory: /path/to/output
steps:
- name: launch_sims
command: psimulate run /path/to/model_specification.yaml /path/to/branches_file.yaml
resources:
memory_gb: 4
runtime: "01:00:00"
- name: post_process
command: my_post_processing_script /path/to/output
resources:
memory_gb: 8
runtime: "00:30:00"Launch the workflow with
dagger run -c /path/to/workflow.yamlIf a run fails partway through, resume it from its output directory, skipping steps that already completed, with
dagger restart /path/to/outputTo read about more of the available features and get a better understanding of how to correctly write your own branches files,
Check out the docs!
1 maintainer
Release files for vivarium-cluster-tools 4.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vivarium_cluster_tools-4.7.0.tar.gz | 185.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vivarium_cluster_tools-4.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 283.7 kB
Release files / vivarium_cluster_tools-4.7.0.tar.gz
| Download URL | vivarium_cluster_tools-4.7.0.tar.gz |
|---|---|
| Size | 185.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9286fd23a39e53ccf7ddd4f962eb32151d8987862a69123c04df09131f764b91
|
|
BLAKE2b-256 checksum How to use checksums |
1e9887acf90c2b4ba177748b1e3480ff0757b0211cf9219a9e186287acf901bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / vivarium_cluster_tools-4.7.0-py3-none-any.whl
| Download URL | vivarium_cluster_tools-4.7.0-py3-none-any.whl |
|---|---|
| Size | 98.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aa64f9b204e7b29059c63cdfc1cd71342263ef7aff50c38408850081132d4d29
|
|
BLAKE2b-256 checksum How to use checksums |
c9e2774c8a96b96699430f9353c9be75800f6acd373a66459a8a59b5858bc3b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
