REACT(1)                                                              REACT(1)



NAME
       react  - a program for simulation of the time course of a set of chemi-
       cal reactions, by numerical integration of  the  relevant  differential
       equations

SYNOPSIS
       react    filename_prefix

DESCRIPTION
       The program react, posted on CCL (Computational Chemistry List) by Mike
       Whitbeck in 1991, is a reaction simulator.   Given  a  reaction  model,
       reaction  rate  constants,  and  initial reactant concentrations, react
       calculates a time series giving the course of  the  reaction  (reactant
       concentrations  at  a  set of time points).  The usefulness of react is
       that the reaction model is input as a set of chemical reactions,  writ-
       ten  in the usual fashion.  The input is parsed by the program, to gen-
       erate data passed to a differential equation solver. Thus, the  simula-
       tor  can be used for essentially any chemical reaction, without modifi-
       cation of the source code.

       The program react (or another  simulator)  is  particularly  useful  in
       teaching  kinectics -- the student can manipulate rates, concentrations
       and the model mechanism.  The simulator is yet more useful if tied to a
       graphics  display  of multidimensional data, such as xgobi (Rgobi), and
       to a GUI for input.  Examples are given of wrapping react  in  a  shell
       script  that  writes  default  input  files and pipes output to a crude
       graphics display in an xterm window.

       This version of react requires one and only one command-line parameter:
       the  basename,  filename_prefix, for three files, two that describe the
       reaction mechanism and are read by react as its  only  input,  and  one
       that is written by react as its only output.  These files are:

          filename_prefix.m    -  a  description  of the mechanism as a set of
            reactions.  The first word of each line is a rate constant and the
            rest  of  the  line,  a  reaction written in the standard chemical
            notation: reactants, arrow (->),  products.   A  sample  mechanism
            file for the lysoyme reaction follows:


                 6.e7    E + S -> X1
                 1.e4    X1 -> E + S
                 1.5     X1 -> X2
                 30      X2 -> X1
                 0.043   X2 -> X3 + P1
                 50      X3 -> E + P2


          filename_prefix.p    -  a  file  of  parameter  values, which are in
            order:

               1st line: one value, 0, to flag use of default  control  values
                 for the integrator;
               2nd  line:  four values, plus optionally two additional values:
                 the start and end time of the simulation, generally 0  and  a
                 large  value;  the  time  interval  between  output values; a
                 default tolerance used by the integrator; if the time  inter-
                 val  value is zero, two additional paramters are read: a time
                 for first output (first time point) and  a  factor  by  which
                 this time interval is multiplied successively at each output.
               following lines: a pair of values, the reaction species and its
                 initial  concentration; optionally two additional values, for
                 the integrator tolerances to be used for a species if differ-
                 ent  than  the default tolerance (see the source file parse.c
                 and the documentation file lsoda.doc for details).

            A sample paramter file  for  the  lysoyme  reaction  follows;  the
            interval  between output time points is successively multiplied by
            the factor 1.258...:


                 0
                 0       1.0e6   0       1.0e-10 1.e-9   1.2589254117
                 E       1.e-4   1.e-10  1.e-9
                 S       1.e-4   1.e-10  1.e-9
                 X1      0       1.e-10  1.e-9
                 X2      0       1.e-10  1.e-9
                 X3      0       1.e-10  1.e-9
                 P1      0       1.e-10  1.e-9
                 P2      0       1.e-10  1.e-9


          filename_prefix.r   -  the results of the calculation.   The  header
            of  this  file lists the input values from files filename_prefix.m
            and filename_prefix.p, followed by a header  line  for  the  time-
            point  values.   Each  line following corresponds to a time point:
            first value, the time; remainder of the line, concentration values
            for  each  of  the  species  identified in the set of reactions of
            filename_prefix.m, in the order of first appearance in that  file.
            The  time-point  header and the first and last lines (time points)
            of the results file for the lysozyme reaction,  described  by  the
            two input file examples above, is:


                           time                      E                      S
                             X1                     X2                     X3
                             P1                     P2
           0.00000000000000e+00   1.00000000000000e-04   1.00000000000000e-04
           0.00000000000000e+00   0.00000000000000e+00   0.00000000000000e+00
           0.00000000000000e+00   0.00000000000000e+00
           ....
           ....
           9.99999988780042e+05   1.00000000000014e-04  -1.36854900769062e-24
          -8.21159643110425e-25  -4.09965524742097e-26  -3.52573919659433e-29
           1.00000000000011e-04   1.00000000000011e-04


       react  uses lsoda, the livermore solver for ordinary differential equa-
       tions, with automatic method switching for stiff and nonstiff problems.
       lsoda  solves  the  initial  value  problem  for systems of first-order
       ode's:

                dy/dt = f(t,y)

       For a chemical mechanism, y is the vector of concentrations at the time
       t  for  the  reactant  and  product species, and the function f is con-
       structed from sums of products of a  reaction  rate  and  one  or  more
       species  concentrations (the product of y and a matrix of psuedo-first-
       order elements).

EXAMPLES
       Subdirectories under src/react/Examples have scripts that  apply  react
       to various mechanisms, mostly enzyme reactions.  These run under Mac OS
       X.  The examples are mostly tutorial to demonstrate  reaction  kinetics
       to  students.  The shell scripts generate the two input files for react
       (*.m and *.p); the steps comprising a particular enzyme  mechanism  and
       the  rate constant associated with each step are taken from the litera-
       ture.  Generally the simulation output, after some prepping,  is  piped
       to a crude display program, ttygraph, which generates a labeled plot in
       a 24x80 xterm window.  Of course, nicer displays are produced with  the
       use of S or xgobi or the corresponding R programs.


FILES
       src/react/reaction/   directory with react sources, this man page,  and
       shell scripts
       src/react/reaction/REACT_DIR/  directory with lsoda sources
       src/react/reaction/REACT_DIR/lsoda.doc   lsoda documentation
       src/react/DISTRIBUTION/react.tar.Z  react version 1  distribution  from
       CCL
       src/react/Docs/      directory with CCL postings, readme files, etc.
       src/react/Examples/run[123]    directories with applications to various
       [enzyme] mechanisms
       src/react/Examples/fd/fd.c     application of the lsoda  integrator  to
       driven oscillator model

REFERENCES AND NOTES
       Three  versions of react have been archived on CCL (Computational Chem-
       istry List) by Mike Whitbeck <whitbeck1@llnl.gov>,  Lawrence  Livermore
       National Laboratory, Livermore, CA 94550:
          react version 1 sources, 1991:
            http://www.ccl.net/cca/software/SOURCES/C/kinetics1/
          react version 2 sources, 1991-1995:
            http://www.ccl.net/cca/software/SOURCES/C/kinetics2/
          react version 3.2 binaries for Mac OS, 1995:
            http://kekule.osc.edu/cca/software/MAC/react/

       The react program described here is derived, with substantial modifica-
       tion,  from react version 1, of May 1991.  Subsequently, the  code  was
       ported from SGI 4d30 to SGI Octane to Mac OS X.  See files 0-CHANGES.*,
       0-NOTE*  and 0-README in src/react/reaction/, for details of the  modi-
       fications.

       The  fortran code for the lsoda integrator was translated into C by Hon
       Wah Tam, then at Wolfram Research, Inc.

AUTHORS
       The react program was conceived and the code written by:
            Dr. Michael Whitbeck
            L-369
            Lawrence Livermore National Laboratory
            POB 808
            Livermore, CA 94550
            whitbeck1@llnl.gov
            whitbeck1@popcorn.llnl.gov

       The program described here is a modification of react version 1 by:
            J. A. Rupley
            Dept of Biochemistry and Biophysics
            Univ. of Arizona, Tucson 85716
            rupley@u.arizona.edu



                                   July 2005                          REACT(1)
