Getting Started for Developers¶

Note

This guide is for developers who want to contribute to Vivarium Core. If you just want to use Vivarium to build models, see the getting started guide.

Download and Installation¶

This guide assumes that you have access to an administrator or sudoer account on a macOS or Linux system.

Getting Organized¶

Creating Enclosing Directory¶

Create a vivarium_work folder anywhere you like. But for installing some third-party software, everything we do will occur inside this folder.

Setting PYTHONPATH¶

Vivarium Core needs the root of the repository to be in your PYTHONPATH environment variable so that Python can find Vivarium Core. To make this easy to set, we suggest adding this line to your shell startup file:

alias pycd='export PYTHONPATH="$PWD"'

Now when you are about to work on Vivarium Core, navigate to the root of the Vivarium Core repository (vivarium_work/vivarium-core) and run pycd in your terminal. You will need to do this for each terminal window you use.

Installing Dependencies¶

Below, we list the dependencies Vivarium Core requires, how to check whether you have them, how to install them, and in some cases, how to set them up for Vivarium Core. Make sure you have each of them installed.

Python 3¶

Vivarium Core requires Python 3.8, 3.9, or 3.10.

Check Installation

$ python --version
Python <version>

Make sure you see a version beginning with 3.8, 3.9, or 3.10.

Install

Download the latest installer from the Python download page

MongoDB¶

We use a MongoDB database to store the data collected from running simulations. This can be a remote server, but for this guide we will run a MongoDB server locally.

Note: MongoDB is only required if you want to store data in MongoDB or want to run experiments that do so. You don’t need MongoDB to work through this guide.

Check Installation

$ mongod --version
db version v4.2.3
...

Make sure you see a version at least 4.2.

Install

If you are on macOS, you can install MongoDB using Homebrew. You will need to add the MongoDB tap following the instructions here.

If you are on Linux, see the MongoDB documentation’s instructions.

Setup

You can get a MongoDB server up and running locally any number of ways. Here is one:

Create a folder vivarium_work/mongodb. This is where MongoDB will store the database We store the database here instead of at the default location in /usr/local/var/mongodb to avoid permissions issues if you are not running as an administrator.
Make a copy of the mongod configuration file so we can make changes:
```
$ cp /usr/local/etc/mongod.conf vivarium_work/mongod.conf
```
Note that your configuration file may be somewhere slightly different. Check the MongoDB documentation for your system.
In vivarium_work/mongod.conf change the path after dbPath: to point to vivarium_work/mongodb.
Create a shell script vivarium_work/mongo.sh with the following content:
```
#!/bin/bash

mongod --config mongodb.conf
```
Make the script executable:
```
$ chmod 700 vivarium_work/mongo.sh
```
Now you can launch MongoDB by running this script:
```
$ vivarium_work/mongo.sh
```

Download and Setup Vivarium Core¶

Download the Code¶

Note: These instructions give you the latest development version of Vivarium Core. If you want to use the most recent release, which is more stable, you can instead run pip install vivarium-core in the Installing Python Packages section below.

The Vivarium Core code is available on GitHub. Move into your vivarium_work directory and clone the repository to download the code

$ cd vivarium_work
$ git clone https://github.com/vivarium-collective/vivarium-core.git

This will create a vivarium-core folder inside vivarium_work. All the code for Vivarium Core is inside this vivarium-core folder.

Installing Python Packages¶

Above we installed all the non-Python dependencies, but we still have to install the Python packages Vivarium Core uses.

Move into the vivarium-core folder created when you cloned the repository.

(optional) Create and activate a virtual environment using venv or pyenv virtualenv, e.g.:

$ python3 -m venv venv --prompt "vivarium-core"
...
$ source venv/bin/activate

Install packages
```
$ pip install -r requirements.txt
```

Now you are all set to begin developing! Be sure to review our contribution instructions before you get started.