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.