A simple example

If you have a vivarium model specification file that defines a model, you can use it with a branches file to launch many simulations at once, with variations in the input data, the random seed or the parameter settings.

psimulate run -M /path/to/model_specification.yaml -B /path/to/branches_file.yaml \
    -o /path/to/results -P proj_simscience

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

input_draw_count: 25
random_seed_count: 10

This branches file defines one simulation for each combination of 25 input draws and 10 random seeds, so it runs 250 simulations in total.

A branches file can also vary the model’s configuration. The model specification below defines a model of lower respiratory infections and a vaccine intervention.

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

This branches file varies the vaccine’s coverage and efficacy as well as the input draws and random seeds.

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]

Each combination of coverage and efficacy replaces the lri_vaccine configuration in the model specification, and each runs for every combination of input draw and random seed. That makes 25 * 10 * 5 * 3 = 3750 simulations.

Check out the docs!