README.md

crnsimulator

Simulate Chemical Recation Networks (CRNs) using Ordinary Differential Equations (ODEs).

Examples

Using the crnsimulator executable:

Create a test file with your CRN:

File: oscillator.crn

# Rock-Paper-Scissors Oscillator

A + B -> B + B [k = 0.2]
B + C -> C + C [k = 0.4]
C + A -> A + A [k = 0.7]

And pipe it into the crnsimulator:

~$ crnsimulator -o ozzy < oscillator.crn

This writes the ODE system to an executable python script: ozzy.py

Check the command line parameters of ozzy.py. You have to set initial species concentrations, and choose an output-format, e.g.:

~$ python ./ozzy.py --p0 A=0.1 B=1e-2 C=1e-3 --t8 10000 --pyplot ozzy.pdf

This example plots a simulation on a linear-time scale (0 - 10000) to the file ozzy.pdf .

Tips and Tricks:

You can pass the command line options for ozzy.py directly to crnsimulator. This will automatically simulate your ODE system. Use --force to overwrite an existing ozzy.py script.

~$ crnsimulator --p0 A=0.1 B=1e-2 C=1e-3 --t8 10000 -o ozzy --pyplot ozzy.pdf < oscillator.crn

You can specify the CRN in a single line:

~$ echo "A+B->2B [k=0.2]; B+C->2C [k=0.4]; C+A->2A" | crnsimulator --p0 A=0.1 B=1e-2 C=1e-3 --t8 10000 -o ozzy --pyplot ozzy.pdf

You can specify default initial concentrations of species:

~$ echo "A @i 0.1; B @i 1e-2; A+B->2B [k=0.2]; B+C->2C [k=0.4]; C+A->2A" | crnsimulator --p0 C=1e-3 --t8 10000 -o ozzy --pyplot ozzy.pdf

If you can set which species appear in the legend using --pyplot-lables. If you are writing a new executable (you may need --force), then you can also control the order:

~$ echo "A @i 0.1; B @i 1e-2; A+B->2B [k=0.2]; B+C->2C [k=0.4]; C+A->2A" | crnsimulator --p0 C=1e-3 --t8 10000 -o ozzy --pyplot ozzy.pdf --force --pyplot-labels C B

Using the crnsimulator library:

The easiest way to get started is by looking at the crnsimulator script itself. However, here is a small example using the above oscillating CRN.

>>> from crnsimulator import ReactionGraph
>>> crn  = [[['A', 'B'],['B','B'],0.2],
            [['B', 'C'],['C','C'],0.8],
            [['C', 'A'],['A','A'],0.9]]
>>> RG = ReactionGraph(crn)
>>> svars = ['B', 'C', 'A'] # let's enforce the order of species, because we can!
>>> filename, odename = RG.write_ODE_lib(filename='ozzy.py', sorted_vars = svars)
>>> print('Wrote ODE system file:', filename)
Wrote ODE system file: ozzy.py

Then go ahead and execute ozzy.py:

~$ python ./ozzy.py --p0 1=1e-6 2=2e-6 3=5e-6 --t8 1e8 --pyplot ozzy.pdf --atol 1e-10 --rtol 1e-10

... or load its functions by treating it as a python library:

# Import
>>> import numpy as np
>>> from scipy.integrate import odeint
>>> from crnsimulator import get_integrator
>>> odesys = get_integrator(filename, function = odename)
>>> odeplt = get_integrator(filename, function = 'ode_plotter')
# Simulate
>>> p0 = [1e-6, 2e-6, 5e-6] # order of svars
>>> time = np.linspace(0, 1e8, num = 10_000)
>>> ny = odeint(odesys, p0, time, (None,), atol = 1e-10, rtol = 1e-10).T
# Plot
>>> odeplt(`ozzy.pdf`, time, ny, svars)

... or include the prebuilt integrator in you own script (like the crnsimulator exectuable):

>>> from crnsimulator import get_integrator
>>> integrate = get_integrator(filename)
>>> integrate(args) # args = <argparse.ArgumentParser()>

Installation

~$ python setup.py install

Version

v0.9 -- code cleanup

• removed networkx dependency
• moved plotting libraries and functions into a separate file to avoid automatic import.

v0.8 -- beta status

• now using logging
• python >= 3.7 only
• improved header documentation
• using entry_points for crnsimulator script
• set defaultrate = 1 (new postprocessing strandard)
• new commandline arguments: labels, labels-strict
• support the constant concentration flag