Metabolism is a project mainly written in C++ and R, based on the GPL-3.0 license.
An open-source chemical reaction modeling platform.
============================================================
An open-source chemical reaction modeling platform.
This project is available at: http://github.com/jpg18/metabolism/
This project was partially supported by NSF UBM DUE-0634612.
This project uses the following:
SIMD-oriented Fast Mersenne Twister (SFMT) A random number generator. The SFMT libraries have been modified for saving and restoring state and are included with the source code, but the project page can be found at http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/.
Qt An API for building graphical user interfaces. Used by default but not required (see 'Compilation Instructions'). Available at http://qt.nokia.com/.
Qwt A Qt library for creating plots. Required for building with Qt. Available at http://qwt.sourceforge.net/.
ncurses An API for building text user interfaces. Used by default but not required (see 'Compilation Instructions'). Available at http://www.gnu.org/software/ncurses/.
Boost Iostreams Library Provides a framework for defining streams, stream buffers and i/o filters. Required for building with Qt or ncurses. Available at http://www.boost.org/.
R Statistical computing software. Scripts provided for analysis. Not required for compiling or running the simulation. Available at http://www.r-project.org/.
deSolve General solvers for R for initial value problems of differential equations. Required by some scripts for analysis. The package can be installed in R using: install.packages("deSolve") The package is also available at http://cran.r-project.org/web/packages/deSolve/.
tikzDevice LaTeX graphics for R. Optional parameter 'outputtype' or 'uselatex' for each R script allows LaTeX documents to be built instead of PDFs or PNGs. The package can be installed in R using: install.packages("tikzDevice") The package is also available at http://cran.r-project.org/web/packages/tikzDevice/.
Compiles with g++ (Ubuntu 4.4.3-4ubuntu5) 4.4.3, gcc (Ubuntu 4.4.3-4ubuntu5) 4.4.3, Qt version 4.6.2.
Execute the following for a standard compilation:
cd metabolism/src make
The program created is called "metabolism" (or "metabolism.app" on Mac).
By default, Qt and ncurses are linked to the program. If developer's libraries are not available, the program can be compiled without ncurses, Qt, or both. Alternative make targets are:
make metabolism-qt for compiling with Qt and without ncurses make metabolism-ncurses for compiling with ncurses and without Qt make metabolism-minimal for compiling without either Qt or ncurses
Once compiled, try running the following from the metabolism/src directory:
./metabolism --gui-off --load ../load/michaelismenten.load --iters 2000
or on Mac:
metabolism.app/Contents/MacOS/metabolism --gui-off --load ../load/michaelismenten.load --iters 2000
This will run a quick simulation of the Michaelis-Menten enzyme kinetics system. Data is output to the files diffusion.out and census.out, and the simulation parameters are recorded in config.out. To plot the trajectory of the reaction, run:
../scripts/kinetics.R
A PDF file is generated containing plots of the changes in chemical species concentration against time. View the PDF:
evince plots.pdf
or on Mac:
open plots.pdf
Both observed (simulated) and expected trajectories are plotted for all chemical species. Expected trajectories are found through numerical integration of the rate laws. Notice that the simulated reactions occurred at a slightly slower rate than expected (in particular, note the rate of "Product" formation). This is because the chemicals need to be "mixed" or "stirred" to maximize the rate of collisions between reactants. Now try:
./metabolism --gui-off --load ../load/michaelismenten.load --iters 2000 --shuffle ../scripts/kinetics.R pdf true config.out census.out plots-shuffle evince plots-shuffle.pdf
or on Mac:
metabolism.app/Contents/MacOS/metabolism --gui-off --load ../load/michaelismenten.load --iters 2000 --shuffle ../scripts/kinetics.R pdf true config.out census.out plots-shuffle open plots-shuffle.pdf
(The extra parameters passed to the script are explained in the comments header of the file.) This will run the same simulation while shuffling the positions of all particles each iteration, thereby simulating mixing. Now the simulated reaction rates match the the expected trajectories much better.
All command line options are available via --help and can be used to specify simulation parameters such as the size of the lattice or the duration of the simulation. By default, the program produces a configuration file named config.out which records the simulation parameters. config files can be loaded to run exact reproductions of simulations using --load.
To change the types of particles in the lattice or the reactions that are defined in the reaction table, you will need to create a custom config file or use one of the provided files in the directory metabolism/load. Create a new file and fill it with any parameters you would like to specify using the format:
keyword value
with separate lines for each parameter. Parameters that can be specified and examples of valid values are:
iters 5000 seed 1234567890 x 2000 y 1000 shuffle on reactions off
In addition to these (which are described in more detail in --help), particle types, reactions, and conditions for terminating the simulation can be specified using the keywords "ele", "rxn", and "extinct". Add a line beginning with "ele" for each particle type ("element") using the following format:
ele name symbol color conc
"name" is a string that names the particle type. "symbol" is a single character that is used to represent particles of that type in the ncurses text interface. "color" is a string that names the color that will be used by the Qt gui to distinguish particles of that type. The following colors are used by the default settings and are distinguishable by users with and without color deficient vision: "teal", "hotpink", "darkorange", and "yellow". All valid color names can be found at http://www.w3.org/TR/SVG/types.html#ColorKeywords. Finally, "conc" is a real valued number between 0 and 1 that represents the starting concentration for the particle type.
An example will help clarify how to build a config file. The Michaelis-Menten enzyme kinetics system consists of three reactions: E + S -> ES, ES -> E + S, and ES -> E + P. The particle types for this system could be defined using:
ele Enzyme E yellow 0.1 ele Substrate S teal 0.3 ele ES C darkorange 0.0 ele Product P hotpink 0.0
(The starting concentrations were chosen arbitarily, and the concentration for Substrate is 3 times the concentration for Enzyme; no ES or Product will be initially present in the lattice.)
When specifying reactions, each unique reaction should receive its own line beginning with "rxn". Up to two reactants can be specified (reaction orders higher than 2 are not supported), and up to two products can be specified. Use the format:
rxn prob [n] reactant [+] [n] [reactant] -> [n] product [+] [n] [product]
"prob" is the probability between 0 and 1 of the reaction occurring when the reactants "collide". "reactant" and "product" are the names of particle types. If you would like to define a zeroth-order reaction, or if you would like your reactants to annihilate one another, use the placeholder symbol "" for the reactants or products, respectively (e.g., -> A, or A -> *). "n" is a stoichiometric coefficient. Since at most two reactants and two products can be specified, this number must be either "1" (in which case it may be omitted) or "2" (in which case there can be no other reaction participants listed on that side of the reaction arrow). Additionally, at most two separate reactions can be specified with the same set of reactants. All particle types must be listed in a config file before any reactions that use them.
For our example, the Michaelis-Menten reactions could be listed using:
rxn 0.50 Enzyme + Substrate -> ES rxn 0.01 ES -> Enzyme + Substrate rxn 0.01 ES -> Enzyme + Product
with "prob"'s = 0.5, 0.01, and 0.01.
Finally, the user can optionally define special conditions under which the simulation should terminate early. A set of particle types can be specified using:
extinct n name [...]
"n" is the number of types in the set, and "names"'s are the names of the particle types. If at any time during the simulation there exist no particles with types from this list, the simulation will end. More than one "extinct" line can be listed in a config file to specify alternative termination conditions. Types included in these lists must be defined earlier in the config file.
For our example, the system will no longer undergo any reactions when all Substrate and ES is depleted, and so we would not be interested in simulating beyond that point. Thus, we could use:
extinct 2 Substrate ES
to force the simulation to end when there are zero Substrate and zero ES particles in the lattice.
If a config file is not used, or if a config file is used that lacks any lines that begin with "ele", then the types "A", "B", "C", and "D" are defined by default. If the config file lacks any "rxn" lines and the default particle types are used, the reaction A + B -> C + D (prob = 0.5) is defined. If the config file does not have any "extinct" lines and the default particle types are used, then the simulation will terminate when either all the A particles or all the B particles are depleted.
============================================================