0README

react
|-- DISTRIBUTION		1991 code from Mike Whitbeck
|-- Docs			docs from 1991 distribution + posts
|   |-- mail				email wrt react
}   |-- postings			1991 ccl and related postings
|   `-- web				urls for react version 1, 2, 3.2
|-- Examples			various applications of react or lsoda
|   |-- fd				driven oscillator
|   |-- run-1				std enzyme mechanisms: lysozyme, 
|   |						chymotrypsin, ldh, haldane ...
|   |-- run-2				temperature jump cf mixing
|   |   `-- S					related S functions
|   `-- run-3				more enzyme mechanism simulations
`-- reaction			react sources - modifn of 1991 distribution
    |-- 0-xgobi-prep			scripts to prep output for xgobi
    `-- REACT_DIR			lsoda sources -  ode integrator


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 literature.
     Generally  the simulation output,  after some prepping,  is piped into 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.

     See 0README file in Examples directory for list of wrappersm, i.e.,  the 
     mechanisms that are simulated.  The names should be selfexplanatory.  If 
     not, please look at the shell script.

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



John Rupley
 rupley@u.arizona.edu -or- jar@rupley.com
 30 Calle Belleza, Tucson AZ 85716 - (520) 325-4533; fax - (520) 325-4991
 Dept. Biochemistry & Molecular Biophysics, Univ. Arizona, Tucson AZ 85721
