Getting Started for Developers¶
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.
Creating Enclosing Directory¶
vivarium_work folder anywhere you like. But for installing
some third-party software, everything we do will occur inside this
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.
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.
Vivarium Core requires Python 3.8, 3.9, or 3.10.
$ python --version Python <version>
Make sure you see a version beginning with 3.8, 3.9, or 3.10.
Download the latest installer from the Python download page
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.
$ mongod --version db version v4.2.3 ...
Make sure you see a version at least 4.2.
If you are on Linux, see the MongoDB documentation’s instructions.
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/mongodbto avoid permissions issues if you are not running as an administrator.
Make a copy of the
mongodconfiguration 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.
vivarium_work/mongod.confchange the path after
dbPath:to point to
Create a shell script
vivarium_work/mongo.shwith 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:
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
All the code for Vivarium Core is inside this
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-corefolder created when you cloned the repository.
(optional) Create and activate a virtual environment using
pyenv virtualenv, e.g.:
$ python3 -m venv venv --prompt "vivarium-core" ... $ source venv/bin/activate
$ pip install -r requirements.txt
Now you are all set to begin developing! Be sure to review our contribution instructions before you get started.