CVODE Release 2.3.0, April 2005 Scott D. Cohen, Alan C. Hindmarsh, Radu Serban Center for Applied Scientific Computing, LLNL CVODE is a solver for stiff and nonstiff ODE systems (initial value problem) given in explicit form dy/dt = f(t,y). It is written in ANSI standard C. CVODE can be used both on serial and parallel (MPI) computers. The main difference is in the NVECTOR module of vector kernels. The desired version is obtained when compiling the example files by linking the appropriate library of NVECTOR kernels. In the parallel version, communication between processors is done with the MPI (Message Passage Interface) system. When used with the serial NVECTOR module, CVODE provides both direct (dense and band) and a preconditioned Krylov (iterative) linear solvers. When CVODE is used with the parallel NVECTOR module, only the Krylov linear solver is available. (An approximate diagonal Jacobian option is available with both versions.) For the serial version, there is a banded preconditioner module called CVBANDPRE available for use with the Krylov solver, while for the parallel version there is a preconditioner module called CVBBDPRE which provides a band-block-diagonal preconditioner. CVODE 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 FCVODE, 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 CVODE package, and relevant references. Following that is a brief history of revisions to the package. A. Documentation ---------------- /sundials/cvode/doc contains PostScript and PDF files for the CVODE User Guide (cv_guide.ps and cv_guide.pdf) and the CVODE Examples (cv_examples.ps and cv_examples.pdf) documents. B. Installation --------------- For basic installation instructions see the file /sundials/INSTALL_NOTES. For complete installation instructions see the "CVODE Installation Procedure" chapter in the CVODE User Guide. C. References ------------- [1] A. C. Hindmarsh and R. Serban, "User Documentation for CVODE v2.2.0," LLLNL technical report UCRL-SM-208108, November 2004. [2] A. C. Hindmarsh and R. Serban, "Example Programs for CVODE v2.2.0," LLNL technical report UCRL-SM-208110, November 2004. [3] S.D. Cohen and A.C. Hindmarsh, "CVODE, a Stiff/nonstiff ODE Solver in C," Computers in Physics, 10(2), pp. 138-143, 1996. [4] 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. 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 - Mar. 2002 (CVODE/PVODE -> combined) v. 1.0 (PVODE) - Jul. 1997 (date written) v. 1.0 (CVODE) - Sep. 1994 (date written) E. Revision History ------------------- v. 2.2.2 (Mar. 2005) ---> v. 2.3.0 (Apr. 2005) ---------------------------------------------- - New features - added option for user-provided error weight computation function (of type CVEwtFn specified through CVodeSetEwtFn). - Changes to user interface - CVODE now stores tolerances through values rather than references (to resolve potential scoping issues). - CVODE now passes information back to the user through values rather than references (error weights, estimated local errors, root info) - CVodeMalloc, CVodeReInit, CVodeSetTolerances: added option itol=CV_WF to indicate user-supplied function for computing the error weights; reltol is now declared as realtype. Note that it is now illegal to call CVodeSetTolerances before CVodeMalloc. It is now legal to deallocate the absolute tolerance N_Vector right after its use. - CVodeGetErrorWeights: the user is now responsible for allocating space for the N_Vector in which error weights will be copied. - CVodeGetEstLocalErrors: the user is now responsible for allocating space for the N_Vector in which estimated local errors will be copied. - CVodeGetRootInfo: the user is now responsible for allocating space for the int array in which root information will be copied. - Passing a value of 0 for the maximum step size, the minimum step size, or for maxsteps results in the solver using the corresponding default value (infinity, 0, 500, respectively) - Several optional input functions were combined into a single one (CVodeRootInit and CvodeSetGdata, CVDenseSetJacFn and CVDenseSetJacData, CVBandSetJacFn and CVBandSetJacData, CVSpgmrSetPrecSolveFn and CVSpgmrSetPrecSetFn and CVSpgmrSetPrecData, CVSpgmrSetJacTimesVecFn and CVSpgmrSetJacData). - Changes to the FCVODE module: - Added option for user-supplied error weight computation subroutine (FCVEWT). Use FCVEWTSET to indicate that FCVEWT is provided. - Due to the changes to the main solver, if FCVPSOL is provided then FCVPSET 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 CVode function: Initial setting of tretlast = *tret = tn removed (correcting erroneous behavior at first call to CVRcheck3). - removed redundant setting of tretlast = *tret = tn at CLOSE_ROOTS return from CVode. - 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 more detailed notes on the type of absolute tolerances - added more details on ownership of memory for the array returned by CVodeGetRootInfo - corrected/added descriptions of error returns. - 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 features - added option to specify a value of the independent variable (time) past which the integration is never to proceed. - added rootfinding capabilities. - added option to disable all error messages. - Changes related to the NVECTOR module (see also file sundials/shared/README) - removed machEnv, redefined table of vector operations (now contained in the N_Vector structure itself). - all CVODE functions create new N_Vector variables through cloning, using an N_Vector passed by the user as a template. - Changes to type names and CVODE constants - removed type 'integertype'; instead use int or long int, as appropriate. - restructured the list of return values from the various CVODE functions. - changed all CVODE constants (inputs and return values) to have the prefix 'CV_' (e.g. CV_SUCCESS). - renamed various function types to have the prefix 'CV' (e.g. CVRhsFn). - Changes to optional input/ouput - added CVodeSet* and CVodeGet* functions for optional inputs/outputs, replacing the arrays iopt and ropt. - added new optional inputs (e.g. maximum number of Newton iterations, maximum number of convergence failures, etc). - the value of the last return flag from any function within a linear solver module can be obtained as an optional output (e.g. CVDenseGetLastFlag). - Changes to user-callable functions - added new function CVodeCreate which initializes the CVODE solver object and returns a pointer to the CVODE memory block. - removed N (problem size) from all functions except the initialization functions for the direct linear solvers (CVDense and CVBand). - shortened argument lists of most CVODE functions (the arguments that were dropped can now be specified through CVodeSet* functions). - removed reinitialization functions for band/dense/SPGMR linear solvers (same functionality can be obtained using CV*Set* functions). - in CVBBDPRE, added a new function, CVBBDSpgmr to initialize the SPGMR linear solver with the BBD preconditioner. - function names changed in CVBANDPRE and CVBBDPRE for uniformity. - Changes to user-supplied functions - removed N (probem dimension) from argument lists. - shortened argument lists for user dense/band/SPGMR Jacobian routines. (Data needed to do difference quotients is accessible in other ways.) - in CVSPGMR, shortened argument lists for user preconditioner functions. - Changes to the FCVODE module - revised to use underscore and precision flags at compile time (from configure); example sources are preprocessed accordingly. - reorganized FCVODE into fewer files. - added tstop options, and interfaces to CVBANDPRE and rootfinding features. - use CV*Set* and CV*Get* functions from CVODE (although the optional I/O is still communicated to the user of FCVODE through arrays IOPT and ROPT). - added new optional inputs and outputs (e.g.tstop, nlscoef, maxnef, maxcor, maxncf, etc.) and rearranged locations in IOPT and ROPT for uniformity. Summary of previous revisions (YYYYMMDD) (significant revisions only) --------------------------------------------------------------------- Combined CVODE package (Mar. 2002 - Jul. 2002) ----------------------------------------------- 20020313 Modified to work with new NVECTOR abstraction. Changed name PVBBDPRE to CVBBDPRE, etc. 20020321 Revisions throughout to reflect usage changes for NVECTOR modules. Changed dense/band backsolve argument b type from N_Vector to real*. 20020328 In FCVODE, added interfaces to dense/band linear solvers. 20020626 Changed type names real/integer to realtype/integertype. PVODE (Jul. 1995 - Mar. 2002) ----------------------------- 19950726 DATE WRITTEN; MPI version of VECTOR module written, creating MPI_PVODE; makefiles written with defs. specific to IBM-SP. 19950929 Formed package directory structure; added Cray-T3D defs. to Makefiles. 19970219 FPVODE package of Fortran/C interfaces written, with examples. 19970724 Wrote preconditioner module BBDPRE and Fortran/C interface. 19970811 Type names changed to LLNL_FLOAT etc. 19970813 Changed first FFUN arg. in FPVODE to local length NLOC. 19971103 Added argc,argv to PVInitMPI call list; removed ICOMM argument to FPVINITMPI (pass MPI_COMM_WORLD). 19971201 Name changes: PVInitMPI/PVFreeMPI to PVecInitMPI/PVecFreeMPI. 19971208 Added optional argument dqrely to BBDPRE. 19971217 Revised FPVODE to use name mappings via parameters in fcmixpar.h. 19980120 Name changes: VECTOR to NVECTOR etc. 19980206 Name changes: BBDPRE to PVBBDPRE, FFUN to PVFUN, etc. 19980508 Wrappers on header files for C++ use; type bool changed to boole. 19980923 In PVBBDPRE and Fortran interface, added two half-bandwidth arguments. 20000316 SPGMR module modified for correct treatment of scalings. added new routine CVReInit for re-initialization of CVODE. 20000320 In NVECTOR module: removed comm = NULL option in PVecInitMPI. 20000321 Added interface FPVREINIT, and expanded diagkf example. 20000719 Fixed memory leak bugs in CVReInit and FPVREINIT. 20000808 Fixed bug in N_VMin routine. 20011114 Added option for stability limit detection algorithm STALD. 20011220 Default type 'integer' changed to 'long int' in llnltyps.h. 20011220 Optional input ropt[HMAX] examined on every call to CVode. 20011221 Optional input iopt[MXHNIL] = -1 means no t+h=t messages. 20011228 Added arguments to CVSpgmr: jtimes (user J*v routine), jac_data. Added optional jtimes to FPVODE. Revised examples accordingly. 20020114 Linear solver modules reorganized: specification routines CVDiag and CVSpgmr perform malloc operations and return a completion flag. Re-use of linear solver memory is allowed if linear solver choice and parameters are unchanged. Fortran interface routines modified analogously. All examples modified to receive and test new return flag. 20020301 Added CVReInitSpgmr routine to CVSPGMR module, and added Fortran interfaces to it. Revised cvdemk and pvdiagkf accordingly. 20020306 Added PVReInitBBD routine to PVBBDPRE, and added Fortran interface to it. Revised pvkxb and pvidagkbf examples accordingly. CVODE (1993 - Mar. 2002) ------------------------ 1993-94 DATE WRITTEN. First released 2 September 1994. 19970811 Type names changed to LLNL_FLOAT etc. 19980120 Name changes: VECTOR to NVECTOR etc. 19980508 Wrappers on header files for C++ use; type bool changed to boole. 20000316 SPGMR module modified for correct treatment of scalings. Added CVODE re-initialization routine CVReInit. 20000323 Added band preconditioner module CVBANDPRE. 20000719 Fixed memory leak bugs in CVReInit. 20000808 Fixed bug in N_VMin routine. 20011114 Added option for stability limit detection algorithm STALD. 20011115 Reorganized DENSE module, with smalldense.* files separate. 20011220 Default type 'integer' changed to 'long int' in llnltyps.h. 20011220 Optional input ropt[HMAX] examined on every call to CVode. 20011221 Optional input iopt[MXHNIL] = -1 means no t+h=t messages. 20011228 Added arguments to CVSpgmr: jtimes (user J*v routine), jac_data. 20020114 Linear solver modules reorganized: linear solver specification routines perform malloc operations and return a completion flag. Re-use of linear solver memory is allowed if linear solver choice and parameters are unchanged. All examples modified accordingly. 20020301 Added ReInit routine to CVDENSE, CVBAND, CVSPGMR modules. 20020305 Added CVReInitBandPre routine to CVBANDPRE module.