DASPK Package - 1995 Revision
                            P. N. Brown
                            A. C. Hindmarsh
                            L. R. Petzold


DASPK is a solver [1] for systems of differential-algebraic equations.  
It includes options for both direct and iterative (Krylov) methods for
the solution of the linear systems arising at each (implicit) time step.

The 1995 revision to DASPK includes a completely new procedure [2] for
calculating consistent initial conditions for a large class of
problems (which includes semi-explicit index-1 systems).  This
procedure includes options for inequality constraints on selected
components.  The package also includes a new option to omit the
algebraic components from the local error control.

Along with the solver itself, the DASPK package includes four example
programs and a set of general-purpose preconditioner files.  These are
described in more detail below.  The package includes separate single
and double precision versions of all source files.


Package Contents
----------------

1. The DASPK package is being distributed in the form of a tar file,
which expands to a directory, DASPK.  The DASPK directory contains
this README file and three subdirectories.

2. The subdirectory DASPK/solver contains the following source files:

     ddaspk.f = main solver source, double precision
     dlinpk.f = required LINPACK/BLAS routines, double precision
     daux.f   = machine constant and error handler, double precision

     sdaspk.f = main solver source, single precision
     slinpk.f = required LINPACK/BLAS routines, single precision
     saux.f   = machine constant and error handler, single precision

The LINPACK/BLAS files are provided for the sake of completeness, but
the target machine/system of interest may already have optimized
versions of these routines, which should be used instead for the sake
of efficiency.

A complete usage document is included as the initial prologue of the
source file *daspk.f.

3. The subdirectory DASPK/examples contains the following files:

     dheat.f    = heat equation example program, double precision, using
                  the Krylov option with banded preconditioner
     dheatilu.f = heat equation example program, double precision, using
                  the Krylov option with sparse ILU preconditioner
     dweb.f     = food web system example program, double precision, using
                  the direct (band) option, and the Krylov option with a
                  product preconditioner based on reaction-transport form
     dwebilu.f  = food web system example program, double precision, using
                  the Krylov option with sparse ILU preconditioner
     makedh     = Make-file to compile and load dheat program
     makedhilu  = Make-file to compile and load dheatilu program
     makedw     = Make-file to compile and load dweb program
     makedwilu  = Make-file to compile and load dwebilu program

     sheat.f    = heat equation example program, single precision, using
                  the Krylov option with banded preconditioner
     sheatilu.f = heat equation example program, single precision, using
                  the Krylov option with sparse ILU preconditioner
     sweb.f     = food web system example program, single precision, using
                  the direct (band) option, and the Krylov option with a
                  product preconditioner based on reaction-transport form
     swebilu.f  = food web system example program, single precision, using
                  the Krylov option with sparse ILU preconditioner
     makesh     = Make-file to compile and load sheat program
     makeshilu  = Make-file to compile and load sheatilu program
     makesw     = Make-file to compile and load sweb program
     makeswilu  = Make-file to compile and load swebilu program

     dheat.out    = output from dheat.f program
     dheatilu.out = output from dheatilu.f program
     dweb.out     = output from dweb.f program
     dwebilu.out  = output from dwebilu.f program

All of these examples make use of preconditioner routines, provided in
the files described below, when calling DASPK with the Krylov method
option.  All are heavily commented and intended for use as models for
real user applications of DASPK.

4. The subdirectory DASPK/preconds contains the following source files:

     dbanpre.f = preconditioner for banded problems, double precision
     drbdpre.f = routines for a reaction-based block-diagonal precond-
                 itioner for DAEs arising from a reaction-transport
                 system, without block-grouping, double precision
     drbgpre.f = routines for a reaction-based block-diagonal precond-
                 itioner for DAEs arising from a reaction-transport
                 system, with block-grouping, double precision
     dilupre.f = preconditioner routines for sparse ILU preconditioning,
                 double precision, intended for general DAE problems.
     dsparsk.f = routines from SPARSKIT, Y. Saad (Univ. of Minnesota),
                 double precision, used by dilupre.f

     sbanpre.f = preconditioner for banded problems, single precision
     srbdpre.f = routines for a reaction-based block-diagonal precond-
                 itioner for DAEs arising from a reaction-transport
                 system, without block-grouping, single precision
     srbgpre.f = routines for a reaction-based block-diagonal precond-
                 itioner for DAEs arising from a reaction-transport
                 system, with block-grouping, single precision
     silupre.f = preconditioner routines for sparse ILU preconditioning,
                 single precision, intended for general DAE problems.
     ssparsk.f = routines from SPARSKIT, Y. Saad (Univ. of Minnesota),
                 single precision, used by silupre.f

At the beginning of each of these source files is a prologue which
documents the contents of the file and the usage of the routines in it.


Installation and Usage Notes
----------------------------

1. The single and double precision versions of the SPARSKIT subset, in
the files ssparsk.f and dsparsk.f in DASPK/preconds, cannot be
installed together as a single library, because of name duplications
among the individual routines.  If such a combined installation is
desired, first change the names of all precision-dependent subroutines
in either ssparsk.f or dsparsk.f, so as to have unique names across
the two files.  Then make the same name changes in the corresponding
file silupre.f or dilupre.f which calls those SPARSKIT routines.

2. The four example problems can be compiled and loaded using the
appropriate make-file in DASPK/examples.  First check the compiler and
flags in the make-file, however.  Each make-file finds the required
solver and preconditioner source or object files in ../solver and
../preconds.  The output files for all four examples, as run in double
precision on a Sun Sparc-10 Workstation, are provided in the files
d*.out.  The results on other systems may differ slightly.

3. The example programs that use ILU preconditioning, if altered to
use the option JACOUT = 1, write an additional output file containing
the initial Jacobian and residual vector in Boeing-Harwell format.  A
map of the Jacobian as a postscript file can then be generated using
the SPARSKIT routines readmt and pspltm.  Details are available from
the authors on request.

4. Users of DASPK with a sparse ILU preconditioner are encouraged to
experiment with the many options available in the SPARSKIT package,
as accessed through the dilupre.f/silupre.f modules provided.  See the
prologue in those files, and the two examples that use ILU.

5. Important Note: The use of single precision on a 32-bit machine is
strongly discouraged.  The amplification of roundoff errors by the
integration and linear system solution algorithms is such that double
precision is generally required on short-wordlength machines.  In
particular, the food web example programs provided here do not run on
a 32-bit machine in single precision, with even the moderate tolerance
values of 1.0e-5.


References
----------
[1] P. N. Brown, A. C. Hindmarsh, and L. R. Petzold, Using Krylov
    Methods in the Solution of Large-Scale Differential-Algebraic
    Systems, SIAM J. Sci. Comp., 15 (1994), pp. 1467-1488.

[2] P. N. Brown, A. C. Hindmarsh, and L. R. Petzold, Consistent
    Initial Condition Calculation for Differential-Algebraic
    Systems, SIAM J. Sci. Comp. 19 (1998), pp. 1495-1512.


Last revised: 13 December 2000
------------------------------------------------------------------
Work performed under the auspices of the U.S. Department of Energy
by Lawrence Livermore National Laboratory under contract number 
W-7405-Eng-48.