                             KINSOL
                      Release 2.3.0, April 2005
            Allan G. Taylor, Alan C. Hindmarsh, Radu Serban
             Center for Applied Scientific Computing, LLNL

KINSOL is a solver for nonlinear algebraic systems which can be
described as F(u) = 0.  It is newly rewritten in the C language and based
on the previous Fortran package NKSOL [4], written by Peter Brown and
Youcef Saad.  In addition to the basic solver, this
package includes a module called KINBBDPRE, which provides a
band-block-diagonal preconditioner for the parallel version.

KINSOL can be used both on serial and parallel (MPI) computers.
The difference is only in the NVECTOR module of vector functions.
The desired version is obtained when compiling the example files
by linking with the appropriate library of NVECTOR functions.  In the
parallel version, communication between processes is done via the MPI 
(Message Passage Interface) system.

When used with the parallel NVECTOR module, KINSOL provides a
preconditioner module called KINBBDPRE, which provides a
band-block-diagonal preconditioner for use with the Krylov linear
solver.  However, within KINSOL any NVECTOR module may be combined
with an appropriate user-supplied preconditioning module for
acceleration of the Krylov solver.

KINSOL is part of a software family called SUNDIALS: SUite of Nonlinear
and DIfferential/ALgebraic equation Solvers.  This suite consists of
CVODE, KINSOL, and IDA, and variants of these.  The directory
structure of the package supplied reflects this family relationship.

For use with Fortran applications, a set of Fortran/C interface routines,
called FKINSOL, is also supplied.  These are written in C, but assume that
the user calling program and all user-supplied routines are in Fortran.

The notes below provide the location of documentation, directions for the 
installation of the KINSOL package, and relevant references. Following that 
is a brief history of revisions to the package.

A. Documentation
----------------

/sundials/kinsol/doc contains PostScript and PDF files for the 
KINSOL User Guide [1] (kin_guide.ps and kin_guide.pdf) and the KINSOL
Examples [2] (kin_examples.ps and kin_examples.pdf) documents.

B. Installation
---------------

For basic installation instructions see the file /sundials/INSTALL_NOTES. 
For complete installation instructions see the "KINSOL Installation Procedure"
chapter in the KINSOL User Guide [1].

C. References
-------------

[1] A. M. Collier, A. C. Hindmarsh, R. Serban, and C. S. Woodward,
    "User Documentation for KINSOL v2.2.0," LLNL technical report
    UCRL-SM-208116, November 2004. 

[2] A. M. Collier and R. Serban, "Example Programs for KINSOL v2.2.0,"
    LLNL technical report UCRL-SM-208114, November 2004.

[3] A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, 
    D. E. Shumaker, and C. S. Woodward, "SUNDIALS, Suite of Nonlinear and 
    Differential/Algebraic Equation Solvers," ACM Trans. Math. Softw., 
    to appear.

[4] Peter N. Brown and Youcef Saad, "Hybrid Krylov Methods for
    Nonlinear Systems of Equations," SIAM J. Sci. Stat. Comput., 
    Vol 11, no 3, pp. 450-481, May 1990.  

[5] A. G. Taylor and A. C. Hindmarsh, "User Documentation for KINSOL,
    A Nonlinear Solver for Sequential and Parallel Computers," LLNL
    technical report UCRL-ID-131185, July 1998.

D. Releases
-----------

v. 2.3.0   - Apr. 2005
v. 2.2.2   - Mar. 2005
v. 2.2.1   - Jan. 2005
v. 2.2.0   - Dec. 2004
v. 2.0     - Jul. 2002 (first SUNDIALS release)
v. 1.0     - Aug. 1998 (date written)


E. Revision History
-------------------

v. 2.2.2 (Mar. 2005) ---> v. 2.3.0 (Apr. 2005)
----------------------------------------------

- Changes to user interface
   - KINSOL now stores an actual copy of the constraints vector rather than
     just a pointer in order to resolve potential scoping issues
   - several optional input functions were combined into a single function:
       - KINSpgmrSetPrecSetupFn, KINSpgmrSetPrecSolveFn and KINSpgmrSetPrecData
         were combined into KINSpgmrSetPreconditioner
       - KINSpgmrSetJacTimesVecFn and KINSpgmrSetJacData were combined into
         KINSpgmrSetJacTimesVecFn

- Changes to FKINSOL module:
   - FKINSPGMRSETPSET and FKINSPGMRSETPSOL were combined into FKINSPGMRSETPREC
   - due to changes to the main solver, if FKPSOL is provided, then FKPSET
     must also be defined, even if it is empty

v. 2.2.1 (Jan. 2005) ---> v. 2.2.2 (Mar. 2005)
----------------------------------------------

- Bug fixes
   - fixed bug in computation of the scaled step length
   - fixed bug in logic for disabling the call to the preconditioner setup function 
     at the first iteration
   - modified FCMIX files to avoid C++ compiler errors
   - changed implicit type conversion to explicit in check_flag() routine in
     examples to avoid C++ compiler errors

- Changes to documentation
   - added section with numerical values of all input and output solver constants
   - added description of --with-mpi-flags option

- Changes related to the build system
   - fixed autoconf-related bug to allow configuration with the PGI Fortran compiler
   - modified to use customized detection of the Fortran name mangling scheme 
     (autoconf's AC_F77_WRAPPERS routine is problematic on some platforms)
   - added --with-mpi-flags as a configure option to allow user to specify
     MPI-specific flags
   - updated Makefiles for Fortran examples to avoid C++ compiler errors (now use
     CC and MPICC to link)

v. 2.2.0 (Dec. 2004) ---> v. 2.2.1 (Jan. 2005)
----------------------------------------------

- Changes related to the build system
   - changed order of compiler directives in header files to avoid compilation
     errors when using a C++ compiler.

v. 2.0 (Jul. 2002) ---> v. 2.2.0 (Dec. 2004)
--------------------------------------------

- New feature
   - added option to disable all error messages.

- Bug fixes
   - fixed constraints-related bug.
   - fixed bug in implementation of line-search method related to
     beta-condition.
   - corrected value of ealpha variable (related to forcing term).

- Changes related to NVECTOR module
  (see also the file sundials/shared/README)
   - removed machEnv, redefined table of vector operations (now contained
     in the N_Vector structure itself).
   - all KINSOL functions create new N_Vector variables through cloning,
     using an N_Vector passed by the user as a template.

- Changes to type names and KINSOL constants
   - removed type 'integertype'; instead use 'int' or 'long int', as
     appropriate.
   - restructured the list of return values from the various KINSOL
     functions.
   - changed all KINSOL constants (inputs and return values) to have
     the prefix 'KIN_' (e.g. KIN_SUCCESS).
   - renamed function type 'SysFn' to 'KINSysFn'.

- Changes to underlying algorithms
   - modified line-search backtracking scheme to use cubic interpolation
     after the first backtrack, if possible.
   - changed implementation of constraints:
       if constraints[i] =
         0  u[i] NOT constrained
        +1  u[i] >= 0
        -1  u[i] <= 0
        +2  u[i] >  0
        -2  u[i] <  0
       where u is the solution vector (see the KINSOL User Guide [1] for
       additional details).

- Changes to optional input/output
   - added KINSet* and KINGet* functions for optional inputs/outputs,
     replacing the arrays iopt and ropt.
   - added new optional inputs (e.g. maximum number of nonlinear iterations
     between calls to preconditioner setup routine, etc.).
   - the value of the last return flag from any function within the SPGMR
     linear solver module can be obtained as an optional output using
     KINSpgmrGetLastFlag.

- Changes to user-callable functions
   - added new function KINCreate which initializes the KINSOL solver object
     and returns a pointer to the KINSOL memory block.
   - removed N (problem size) from all functions.
   - shortened argument lists of most KINSOL functions (the arguments that
     were dropped can now be specified through KINSet* functions).
   - removed reinitialization functions for SPGMR linear solver (same
     functionality can be obtained using KINSpgmrSet* functions).

- Changes to user-supplied functions
   - removed N (problem dimension) from argument lists.
   - in KINSPGMR, shortened argument lists for user preconditioner functions.

- Changes to the FKINSOL module
   - revised to use underscore and precision flags at compile time (from
     configure); example sources are preprocessed accordingly.
   - use KIN*Set* and KIN*Get* functions from KINSOL (although the optional
     I/O is still communicated to the user of FKINSOL through arrays IOPT
     and ROPT).
   - added new optional inputs and outputs (e.g. last return flag from the
     linear solver, etc.).

v. 1.0 (Aug. 1998) ---> v. 2.0 (Jul. 2002)
------------------------------------------

YYYYMMDD

19980802   DATE WRITTEN - KINSOL released.
19981203   Implemented serial Fortran/C interface (fkinsols.c).
19990301   Fixed bug in nbktrk.
19990325   Removed machEnv as an argument to KINSol.
19991229   Fixed preconditioner evaluation logic;
           revised SPGMR module to treat scalings correctly.
20000324   Upgraded serial and parallel versions of NVECTOR module.
20000706   Fixed bug in use of vtemp1 in KINSpgmrSolve call to KINAtimes etc.
20000808   Fixed bug in N_VMin routine.
20010118   Minor corrections, notably:
           In fkinsol.h, KINUAtimes prototype fixed.  In fkinsols.c and
           fkinsolp.c, N_Vector's disposed with N_VDISPOSE after KINSol call. 
           In all fkin*.c, #include lines for header files corrected.
20011212   Corrected 4 N_VDISPOSE arguments in FKINSOL.
20011212   Added missing error flag print in KINSol, and changed 5 return
           values in KINStop to enum-defined expressions.
20011220   Default type 'integer' changed to 'long int' in llnltyps.h.
20011221   In FKINSOL, corrected type (integer) for Neq in KINPreco, KINPSol.
20020313   Modified to work with new NVECTOR abstraction.
20020627   Modified to reflect type name changes.
