Evolve Oscillating Models

This software tool is used to generate oscillatory reaction networks. Please see Cesium database for an usage example generated by this tool:

• Tatka LT, Luk W, Elston TC, Hellerstein JL, Sauro HM. Cesium: A public database of evolved oscillatory reaction networks. Biosystems. 2023 Feb;224:104836. doi: 10.1016/j.biosystems.2023.104836. Epub 2023 Jan 11. PMID: 36640942; PMCID: PMC9997760. Cesium article

Related tool:

Reaction network evolution tool written in Julia: https://github.com/sys-bio/ReactionNetworkEvolution.jl This module allows the user to easily run an evolutionary algorithm to create mass-action chemical reaction networks with specific behaviors or to match time series data.

Installation

• Clone or fork this repo. To clone:

git clone https://github.com/sys-bio/evolution.git

• Or download and extract zip file of this repo on to your local machine.

If you do not want to build Sundials, but would rather use the Sundials binaries provided here, then go to Setting up environment.

Note: I wrote and tested everything in Linux (Ubuntu).

Tested on MS Windows 10 and 11. Not tested on other platforms.

Build sundials

Navigate to the evolution directory (cd evolution)

Run this code block to initialize the submodules, navigate to the build files in Sundials, build Sundials (the ODE solver), and then return to the evolution directory.

Be sure to replace with whatever system you're using (eg sundials-install-linux).

• Linux: linux
• Windows: win32

Your system is the output of the python command sys.platform

git submodule update --init --recursive

cd sundials

mkdir build
cd build
 
# If you are using the cluster, use 'module load cmake' here 

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../../sundials-install-<platform> ..
cmake --build . --target install --config Release -j 12

cd ../..

Setting up environment

To set up a conda evironment with all the dependencies conda env create -f environment.yml (This works in linux, but not sure if it will elsewhere...)

Use pip instead: If you do not want to use anaconda but would rather use pip, then just install the following python packages:

1. pip install numba Note: as of 10/2023, the numba package only works with python versions < 3.12.0
2. pip install distro
3. pip install tellurium

Quick start

To run a batch of evolution with the default parameters: (first make sure you're in the sub directory evolution, (eg. /home/yourname/evolution/evolution)

python batchrun.py

Optional arguments

There are four optional arguments that can be used in any combination and order.

python batchrun.py --runs 50 Change the number of times the evolution script is run. The default is 10.

python batchrun.py --numGenerations 500Change the number of generations evolved with each run. The default is 400.

python batchrun.py --probabilities 0.3 0.3 0.3 0.1 Change the probability of each reaction type when generating random networks. Order is UniUni, UniBi, BiUni, BiBi. The default is 0.1, 0.4, 0.4, 0.1

python batchrun.py --newConfigFile newParams.jsonUse a new configuration file (see 'Change parameters' section below for defaults and instructions.

Change parameters

Create a new .json file with desired parameters. Here's a template with the default configuration:

{"maxGenerations": 400,
  "sizeOfPopulation": 40,
  "massConserved": "False",
  "toZip": "True",
  "numSpecies": 10,
  "numReactions": 14,
  "rateConstantScale": 50,
  "probabilityMutateRateConstant": 0.7,
  "initialConditions": [1, 5, 9, 3, 10, 3, 7, 1, 6, 3, 10, 11, 4, 6, 2, 7, 1,9, 5, 7, 2, 4, 5, 10, 4, 1, 6, 7, 3, 2, 7, 8],
  "percentageCloned": 0.1,
  "percentageChangeInParameter": 0.15,
  "seed": -1,
  "threshold": 10.5,
  "frequencyOfOutput": 10}

To use your new configuration, pass it as an optional argument when running batchrun

python batchrun.py --newConfigFile <yourNewConfig>.json

Error Fixes

If you build and run the program on the cluster and come across this error:

This is annoying but the way I ended up fixing this was to clone the sundials repo from https://github.com/LLNL/sundials.git And then build using the following commands:

cd sundials

mkdir builddir
cd builddir

cmake -DCMAKE_INSTALL_PREFIX=../install-release -DCMAKE_BUILD_TYPE=Release -DEXAMPLES_ENABLE=ON -DBUILD_SHARED_LIBS=ON ..

make -j12

make install

You might want to check if this version of sundials works by running one of the examples.

Building sundials will create a directory called install-release. Note the location of this directory.

Then go back into the evolution directory and edit the uLoadCvode.py file. Edit the file so that the variable SUNDIALS_INSTALL_PREFIX is the path to the install-release directory.

This is super sketchy and I'll maybe make a more official fix later, but writing this down in case this issue comes up again.