

CVODE Software Package by Scott D. Cohen and Alan C. Hindmarsh
-------------------------------------------------------------------------------


I. Brief Description of the Contents of this Directory (named CVODE):

(1) file README - this file

(2) file Makefile - contains commands to create lib/cvodelib.a

(3) sub-directory doc - contains cvuguide.ps, the CVODE User Guide

(4) sub-directory source - contains all CVODE source (.c) files

(5) sub-directory include - contains all CVODE header (.h) files

(6) sub-directory lib - contains the library cvodelib.a created by make

(7) sub-directory examples - contains 5 sub-directories band_ex, dense_ex,
    krylov_ex, direct_dem, and krylov_dem, each of which contains the source
    and Makefile for a CVODE example program


II. Installation

At the same level as this README file, type "make" to create the CVODE
library lib/cvodelib.a. The Makefile at the top level of the CVODE directory
is setup to use the gcc compiler with no special compiler options. The
compiler used can be changed by modifying the COMPILER variable. Compiler
options (such as -g to produce debugging information for GDB) can be
added by modifying the OPTS variable.


III. Checking Installation

The directories examples/direct_dem and examples/krylov_dem are devoted to
CVODE demonstration programs that can be run to check that you have
correctly installed CVODE. The direct_dem directory contains a Makefile,
the program source cvdemd.c, and a copy of our output file cvdemd.out. The
krylov_dem directory contains a Makefile, the program source cvdemk.c, and
the output file cvdemk.out. Both the direct and Krylov demonstration
programs should not report any errors. In each case, the output should look
like the output that we provide, possibly with relatively small differences
throughout.


From the directory examples/direct_dem,

(1) type "make" to create the executable cvdemd

(2) run cvdemd (you can send the output to a file checkd.out by typing
    "cvdemd > checkd.out")

(3) compare the output obtained to our output file cvdemd.out


From the directory examples/krylov_dem,

(1) type "make" to create the executable cvdemk

(2) run cvdemk (this may take a few minutes to complete)

(3) compare the output obtained to our output file cvdemk.out


IV. Using the CVODE Package

We have written a detailed user guide to help users write their CVODE
programs:
  Scott D. Cohen and Alan C. Hindmarsh, CVODE User Guide, 
  LLNL Report UCRL-MA-118618, September 1994.
The postcript file cvuguide.ps contains this document. It was created
as a two-sided LaTeX document. It can be printed on one side, but as a
one-sided hard copy, the page headers will seem a bit strange.

The Makefile in any of the example program directories can be modified
to serve as the Makefile for one of your own programs. Suppose you start
from the Makefile in examples/dense_ex and that your main program file is
called user.c. Then the following changes should be made:

(1) Replace all occurrences of "cvdx.c" with "user.c", "cvdx.o" with "user.o",
    and "cvdx" with "user" in order to create the executable called "user".

(2) The list of CVODE .h files in the HDRS variable should be modified
    to reflect the header files needed in your user.c program.

(3) You need to change the INC and LIB variables. These variables are used to
    tell the compiler where to look for CVODE header files and the CVODE
    library cvodelib.a. In the example program directories, these variables
    have paths relative to the examples directory. These must be changed to
    the full paths to reach the include and lib CVODE sub-directories.
    Naturally, these paths depend on where you put the CVODE directory on
    your machine.

(4) Finally, you can change the compiler and/or compiler options by modifying
    the COMPILER variable and/or the OPTS variable (e.g. adding -g to produce
    debugging information for GDB). 

Note: Do NOT remove the linking of the standard math library (-lm) from the
line which creates the executable (even if your program file user.c does not
use standard math library functions). The standard math library is required by
the CVODE library.

The programs cvbx.c, cvdx.c, and cvkx.c are intended to be models for
programs which use the CVBAND, CVDENSE, and CVSPGMR linear solvers,
respectively. Depending on your problem needs, you may wish to write your
program by starting with one of these files and modifying it appropriately.



				Scott D. Cohen and Alan C. Hindmarsh
				Numerical Mathematics Group
				Center for Computational Sciences & Engineering
				L-316
				Lawrence Livermore National Lab
				Livermore, CA 94551
				email: alanh@llnl.gov
