https://badge.fury.io/py/vivarium-cluster-tools.svg Documentation Status

Vivarium cluster tools is a python package that makes running vivarium simulations at scale on a Slurm cluster easy.

Supported Python versions: 3.10, 3.11, 3.12, 3.13

You can install vivarium-cluster-tools from PyPI with pip:

pip install vivarium-cluster-tools

or 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-tools

A 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.yaml

The simplest branches file defines a count of input data draws and random seeds to launch.

input_draw_count: 25
random_seed_count: 10

This 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.8

Defining 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.yaml

If a run fails partway through, resume it from its output directory, skipping steps that already completed, with

dagger restart /path/to/output

To 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!

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.6.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for vivarium from gravatar.com vivarium

Credits

Author: The vivarium developers

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD License (BSD-3-Clause)

Requires

Python >=3.10

Provides Extra

cluster test docs interactive lint dev ci-github ci-jenkins

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vivarium_cluster_tools-4.5.0.tar.gz (177.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vivarium_cluster_tools-4.5.0-py3-none-any.whl (95.3 kB view details)

Uploaded Python 3

File details

Details for the file vivarium_cluster_tools-4.5.0.tar.gz.

File metadata

  • Download URL: vivarium_cluster_tools-4.5.0.tar.gz
  • Upload date:
  • Size: 177.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vivarium_cluster_tools-4.5.0.tar.gz
Algorithm Hash digest
SHA256 eec62748e802dedbb42a9a2d98ae95ab95cbd575a268b99ecf354e1e32b0e690
MD5 7a83a2eb3d779c3b78bda49a6f5c665d
BLAKE2b-256 11d2e79106f723cd8d2a3aa9bf8d454517e3a40f8869ac5075ef26b2193d0d12

See more details on using hashes here.

Provenance

The following attestation bundles were made for vivarium_cluster_tools-4.5.0.tar.gz:

Publisher: release.yml on ihmeuw/vivarium-suite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vivarium_cluster_tools-4.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for vivarium_cluster_tools-4.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9817e475362a7267e7d5aac8eee3310851f0425f337429d9c6ebd0cf8346d415
MD5 1e6004e21eb0286a5e22e2fb72004058
BLAKE2b-256 9b1779147b9c9feca31bb929cf129ef897a3dfeb7c2c89c989fa8f1e6638c1a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vivarium_cluster_tools-4.5.0-py3-none-any.whl:

Publisher: release.yml on ihmeuw/vivarium-suite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.6.0

2 files

This release

4.5.0 This release

2 files

4.4.0

2 files

4.3.0

2 files

4.2.14

2 files

4.2.13

2 files

4.2.12

2 files

4.2.11

2 files

4.2.10

2 files

4.2.9

2 files

4.2.8

2 files

4.2.7

2 files

4.2.6

2 files

4.2.5

2 files

4.2.4

2 files

4.2.3

2 files

4.2.2

2 files

4.2.1

2 files

4.2.0

2 files

4.1.0

2 files

4.0.1

2 files

4.0.0

2 files

3.1.6

2 files

3.1.5

2 files

3.1.4

2 files

3.1.3

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

2.3.5

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.26

2 files

2.1.25

2 files

2.1.24

2 files

2.1.23

2 files

2.1.22

2 files

2.1.21

2 files

2.1.20

2 files

2.1.19

2 files

2.1.18

2 files

2.1.17

2 files

2.1.16

2 files

2.1.15

2 files

2.1.14

2 files

2.1.13

2 files

2.1.12

2 files

2.1.11

2 files

2.1.10

2 files

2.1.9

2 files

2.1.8

2 files

2.1.7

2 files

2.1.6

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.6

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.13

2 files

1.3.12

2 files

1.3.11

2 files

1.3.10

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.1

2 files

1.3.0

2 files

1.2.13

2 files

1.2.12

2 files

1.2.11

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.1

2 files

1.2.0

2 files

1.1.2

1 file

1.1.1

1 file

1.1.0

1 file

1.0.15

1 file

1.0.14

1 file

1.0.12

1 file

1.0.11

1 file

1.0.10

1 file

1.0.9

1 file

1.0.8

1 file

1.0.7

1 file

1.0.6

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page