Metadata-Version: 2.4
Name: vivarium-cluster-tools
Version: 4.0.0
Summary: A set of tools for running simulation using vivarium on cluster.
Author-email: The vivarium developers <vivarium.dev@gmail.com>
License: BSD-3-Clause
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: vivarium-dependencies[click,loguru,numpy_lt_2,pandas,pyarrow,pyyaml,requests,tables]
Requires-Dist: vivarium-build-utils<4.0.0,>=3.0.2
Requires-Dist: vivarium-engine>=5.0.0
Requires-Dist: vivarium-config-tree>=5.0.0
Requires-Dist: dill
Requires-Dist: psutil
Provides-Extra: cluster
Requires-Dist: jobmon_installer_ihme; extra == "cluster"
Provides-Extra: test
Requires-Dist: vivarium-dependencies[pytest]; extra == "test"
Requires-Dist: vivarium-testing-utils>=0.3.4; extra == "test"
Provides-Extra: docs
Requires-Dist: vivarium-dependencies[ipython,matplotlib,sphinx,sphinx-click]; extra == "docs"
Provides-Extra: interactive
Requires-Dist: vivarium-dependencies[interactive]; extra == "interactive"
Provides-Extra: lint
Requires-Dist: vivarium-dependencies[lint]; extra == "lint"
Requires-Dist: types-setuptools; extra == "lint"
Requires-Dist: types-psutil; extra == "lint"
Requires-Dist: pyarrow-stubs; extra == "lint"
Provides-Extra: dev
Requires-Dist: vivarium-cluster-tools[cluster,docs,interactive,lint,test]; extra == "dev"
Provides-Extra: ci-github
Requires-Dist: vivarium-cluster-tools[docs,lint,test]; extra == "ci-github"
Provides-Extra: ci-jenkins
Requires-Dist: vivarium-cluster-tools[ci_github,cluster]; extra == "ci-jenkins"
Dynamic: license-file

Vivarium Cluster Tools
=======================

.. image:: https://badge.fury.io/py/vivarium-cluster-tools.svg
    :target: https://badge.fury.io/py/vivarium-cluster-tools

.. image:: https://readthedocs.org/projects/vivarium-cluster-tools/badge/?version=latest
    :target: https://vivarium-cluster-tools.readthedocs.io/en/latest/?badge=latest
    :alt: 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:

.. code-block:: bash

   pip install vivarium-cluster-tools

or build it from source by cloning the monorepo and installing this package:

.. code-block:: bash

   git clone https://github.com/ihmeuw/vivarium-suite.git
   cd vivarium-suite
   pip install libs/cluster-tools

.. note::

    The ``[cluster]`` extra (i.e. `pip install libs/cluster-tools[cluster]`) pulls
    in ``jobmon_installer_ihme`` (hosted on IHME's internal PyPI mirror), which
    is required to actually submit jobs on the IHME cluster. The base install
    (``pip install vivarium-cluster-tools``) resolves on public PyPI and is sufficient
    for read-only inspection of results / docs generation, but ``psimulate run``
    etc. need the cluster extra.

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.

.. code-block:: console

    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.

.. code-block:: yaml

    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

.. code-block:: yaml

    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

.. code-block:: yaml

    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.

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! <https://vivarium-cluster-tools.readthedocs.io/en/latest/>`_
---------------------------------------------------------------------------------
