Vivarium Simulation of Sodium Reduction through Front-of-package Labeling

Vivarium model repository for the vivarium_sodium_reduction project.

Contents

• Installation
• Usage
• Running Simulations

Installation

You will need git, git-lfs and conda to get this repository and install all of its requirements. You should follow the instructions for your operating system at the following places:

• git
• git-lfs
• conda

Once you have all three installed, you should open up your normal shell (if you're on linux or OSX) or the git bash shell if you're on windows. You'll then make an environment, clone this repository, then install all necessary requirements with source evironment.sh.

Cloning the repository should take a fair bit of time as git must fetch the data artifact associated with the demo (several GB of data) from the large file system storage (git-lfs). If your clone works quickly, you are likely only retrieving the checksum file that github holds onto, and your simulations will fail. If you are only retrieving checksum files you can explicitly pull the data by executing git-lfs pull.

The (vivarium_sodium_reduction_simulation) that precedes your shell prompt will probably show up by default, though it may not. It's just a visual reminder that you are installing and running things in an isolated programming environment so it doesn't conflict with other source code and libraries on your system.

Usage

You'll find six directories inside the main src/vivarium_sodium_reduction package directory:

• artifacts

  This directory contains all input data used to run the simulations. You can open these files and examine the input data using the vivarium artifact tools. A tutorial can be found at https://vivarium.readthedocs.io/en/latest/tutorials/artifact.html#reading-data

• components

  This directory is for Python modules containing custom components for the vivarium_sodium_reduction project. You should work with the engineering staff to help scope out what you need and get them built.

• data

  If you have small scale external data for use in your sim or in your results processing, it can live here. This is almost certainly not the right place for data, so make sure there's not a better place to put it first.

• model_specifications

  This directory should hold all model specifications and branch files associated with the project.

• results_processing

  Any post-processing and analysis code or notebooks you write should be stored in this directory.

• tools

  This directory hold Python files used to run scripts used to prepare input data or process outputs.

Running Simulations

Before running a simulation, you should have a model specification file. A model specification is a complete description of a vivarium model in a yaml format. An example model specification is provided with this repository in the model_specifications directory.

With this model specification file and your conda environment active, you can then run simulations by, e.g.:

(vivarium_sodium_reduction) :~$ simulate run -v /<REPO_INSTALLATION_DIRECTORY>/vivarium_sodium_reduction/src/vivarium_sodium_reduction/model_specifications/model_spec.yaml

The -v flag will log verbosely, so you will get log messages every time step. For more ways to run simulations, see the tutorials at https://vivarium.readthedocs.io/en/latest/tutorials/running_a_simulation/index.html and https://vivarium.readthedocs.io/en/latest/tutorials/exploration.html

To run multiple simulations in parallel, you can use the psimulate command:

psimulate run -vvv -m 10 -P proj_simscience src/vivarium_sodium_reduction/model_specifications/model_spec.yaml sr

c/vivarium_sodium_reduction/model_specifications/branches/scenarios.yaml