
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 documentation files cvuguide.ps and 
    addenda.doc.

(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.  (In the case of /krylov_ex, there
    are two example programs; the Makefile names are Makecvkx and Makecvkxb.)


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 set up 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 in /doc 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.

A summary of modifications to CVODE since 1994, and their impact on
usage, is given in the file addenda.doc in the sub-directory /doc.

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 cvdx.c, cvbx.c, cvkx.c, and cvkxb.c are intended to be models
for programs which use the CVDENSE, CVBAND, CVSPGMR, and CVSPGMR/CVBANDPRE as
the 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
				Center for Applied Scientific Computing
				L-561
				Lawrence Livermore National Laboratory
				Livermore, CA 94551
				email: alanh@llnl.gov


				Last Revised: 28 March 2000
