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

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

.. image:: https://github.com/ihmeuw/vivarium_cluster_tools/actions/workflows/build.yml/badge.svg?branch=main
    :target: https://github.com/ihmeuw/vivarium_cluster_tools
    :alt: Latest Version

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

Installation
------------

You can install this package with

.. code-block:: console

    pip install vivarium-cluster-tools

In addition, this tool needs the redis client. This must be installed using conda.

.. code-block:: console

    conda install redis

A simple example
----------------

If you have a ``vivarium`` model specifcation 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()
          - Mortality()
        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/>`_
---------------------------------------------------------------------------------
