Vivarium E. coli

Background

Vivarium E. coli (vEcoli) is a port of the Covert Lab's E. coli Whole Cell Model (wcEcoli) to the Vivarium framework. Its main benefits over the original model are:

1. Modular processes: easily add/remove processes that interact with existing or new simulation state
2. Unified configuration: all configuration happens through JSON files, making it easy to run simulations/analyses with different options
3. Parquet output: simulation output is in a widely-supported columnar file format that enables fast, larger-than-RAM analytics with DuckDB
4. Google Cloud support: workflows too large to run on a local machine can be easily run on Google Cloud

As in wcEcoli, raw experimental data is first processed by the parameter calculator or ParCa to calculate model parameters (e.g. transcription probabilities). These parameters are used to configure processes that are linked together into a complete simulation.

Setup

Note: The following instructions assume a local Linux or MacOS system. Windows users can attempt to follow the same steps after setting up Windows Subsystem for Linux. Refer to the following pages for non-local setups: Sherlock, other HPC cluster, Google Cloud.

Prerequisites

If your system has git, curl (or wget), and a C compiler (e.g. clang, gcc), proceed to the next section.

On Ubuntu/Debian, apt can be used to install all three prerequisites:

sudo -s eval 'apt update && apt install git curl clang'

On MacOS, curl is preinstalled and git and clang come with the Xcode Command Line Tools:

xcode-select --install

Installation

Clone the repository:

git clone https://github.com/CovertLab/vEcoli.git

Tip: You can specify a directory to clone into after the URL of the repository. Otherwise, the above command will clone into a new directory called vEcoli in your current directory.

Follow these instructions to install uv, our Python package and project manager of choice. Once finished, close and reopen your terminal before continuing.

Navigate into the cloned repository and use uv to install the model:

cd vEcoli
uv sync --frozen

Finally, install nextflow following these instructions. If your system has wget but not curl, replace curl in the commands with wget -qO-. If you choose to install Java with SDKMAN!, after the Java installation finishes, close and reopen your terminal before continuing with the nextflow installation steps.

Tip: If any step in the nextflow installation fails, try rerunning a few times to see if that fixes the issue.

If you are installing the model for active development, we strongly recommend that you also install the development dependencies using:

uv sync --frozen --extra dev

After that, you can run uv run pre-commit install to install a pre-commit hook that will run the ruff linter and formatter before all of your commits.

The development dependencies also include pytest, which lets you run the test suite, and mypy, which can be invoked to perform static type checking.

Test Installation

To test your installation, from the top-level of the cloned repository, invoke:

uv run --env-file .env runscripts/workflow.py --config ecoli/composites/ecoli_configs/test_installation.json

Warning: Always use uv run --env-file .env to run scripts. We recommend adding the following to your ~/.bashrc or ~/.zshrc to create an alias for this: alias uvenv='uv run --env-file .env'. uvenv should work after restarting your terminal.

This will run the following basic simulation workflow:

1. Run the parameter calculator to generate simulation data.
2. Run the simulation for a single generation, saving output in out folder.
3. Analyze simulation output by creating a mass fraction plot.

Next Steps

Review the online user guide to learn how to configure and run your own simulation workflows.

If you encounter a problem that you cannot solve after searching the user guide (also linked in the repository sidebar), feel free to create a GitHub issue, and we will get back to you as soon as we can.