CVODES Release 2.3.0, May 2005 Alan C. Hindmarsh and Radu Serban Center for Applied Scientific Computing, LLNL CVODES is a solver for stiff and nonstiff ODE systems (initial value problem) given in explicit form y' = f(t,y,p) with sensitivity analysis capabilities (both forward and adjoint modes). It is written in ANSI standard C. CVODES 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, CVODES provides both direct (dense and band) and a preconditioned Krylov (iterative) linear solvers. When CVODES 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. CVODES is part of a software family called SUNDIALS: SUite of Nonlinear and DIfferential/ALgebraic equation Solvers [4]. This suite consists of CVODE, CVODES, IDA, and KINSOL. The directory structure of the package supplied reflects this family relationship. The notes below provide the location of documentation, directions for the installation of the CVODES package, and relevant references. Following that is a brief history of revisions to the package. A. Documentation ---------------- /sundials/cvodes/doc contains PostScript and PDF files for the CVODES User Guide [1] (cvs_guide.ps and cvs_guide.pdf) and the CVODES Examples [2] (cvs_examples.ps and cvs_examples.pdf) documents. B. Installation --------------- For basic installation instructions see /sundials/INSTALL_NOTES. For complete installation instructions see the "CVODES Installation Procedure" chapter in the CVODES User Guide. C. References ------------- [1] A. C. Hindmarsh and R. Serban, "User Documentation for CVODES v2.1.0," LLNL technical report UCRL-SM-208111, November 2004. [2] A. C. Hindmarsh and R. Serban, "Example Programs for CVODES v2.1.0," LLNL technical report UCRL-SM-208115, November 2004. [3] R. Serban and A. C. Hindmarsh, "CVODES: An ODE Solver with Sensitivity Analysis Capabilities," LLNL technical report UCRL-TR-xxxxxx, November 2004. [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., accepted, 2004. D. Releases ----------- v. 2.3.0 - May. 2005 v. 2.2.0 - Apr. 2005 v. 2.1.2 - Mar. 2005 v. 2.1.1 - Jan. 2005 v. 2.1.0 - Dec. 2004 v. 1.0 - Jul. 2002 (first SUNDIALS release) E. Revision History ------------------- v. 2.2.0 (Apr. 2005) ---> v. 2.3.0 (May. 2005) ---------------------------------------------- - Bug fixes - in the adjoint module, fixed bug in storing interpolation data at a point corresponding to a check point (improperly scaled y'). - Changes to user interface - removed CVadjGetcheckPointsList from the list of user-callable functions. v. 2.1.2 (Mar. 2005) ---> v. 2.2.0 (Apr. 2005) ---------------------------------------------- - New features - added option for user-provided error weight computation function for the solution vector (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, STAGGERED1 statistics, etc.) - 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. - 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). - Removed CVodeSetQuadtolerances. CVodeSetQuadErrCon now sets both the error control flag and the tolerances for quadratures. - CVodeSetQuadErrCon, CVodeSetSensTolerances: the relative tolerance must now be passed as a realtype. It is now illegal to call CVodeSetQuadErrCon before CVodeQuadMalloc or to call CVodeSetSensTolerances before CVodeSensMalloc. - CvodeSensMalloc: removed p and plist from argument list. - CVodeSensParams replaces CVodeSensPbar and sets p, pbar, and plist. NULL can be passed for any of them if it will not be needed given the current set of options. The array pbar must now contain Ns non-zero realtype values giving order of magnitude for the parameters with respect to which sensitivities will be computed. The array plist can now only have positive entries. - CVodeGetErrorWeights, CVodeGetQuadErrorWeights: 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. - CVodeGetNumStgrSensNonlinSolvIters, CVodeGetNumStgrSensNonlinSolvConvFails: the user is now responsible for allocating space for the long int arrays in which STAGGERED1 statistics will be copied. - CVodeMallocB, CVodeReInitB, CVodeSetQuadErrConB: the relative tolerance for the backward integration must now be passed as a realtype. It is now illegal to call CVodeSetQuadErrConB before CVQuadMallocB. - 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) - User-callable functions in the adjoint module were modified similarly to their corresponding counterparts for forward simulation. v. 2.1.1 (Jan. 2005) ---> v. 2.1.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. - fixed bug in CVCompleteStep related to quadrature and sensitivity variables (leading to wrong values at a BDF order increase) - in CVUpperBoundH0, fixed a potential, although not harmful, use of uninitialized memory - 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.1.0 (Dec. 2004) ---> v. 2.1.1 (Jan. 2005) ---------------------------------------------- - New features - added function CVodeSensToggle to allow activation/deactivation of sensitivity calculations without memory allocation/deallocation. - Bug fixes - fixed bug in CVCompleteStep related to quadrature and sensitivity variables (leading to wrong values at a BDF order increase). - in CVUpperBoundH0, fixed a potential, although not harmful, use of uninitialized memory. - fixed logic in testing for negative values of user-supplied absolute tolerances for sensitivity variables. - Changes related to the build system - changed order of compiler directives in header files to avoid compilation errors when using a C++ compiler. v. 1.0 (Jul. 2002) ---> v. 2.1.0 (Dec. 2004) -------------------------------------------- - New features - added quadrature integration capabilities. - added root finding capabilities. - added option for different user data structures for ODE r.h.s. and sensitivity r.h.s. - in adjoint module, added interface to CVBBDPRE for the backward phase. - in adjoint module, added option for using CVDIAG during backward phase. - in adjoint module, added option for ONE_STEP integration during backward phase. - in adjoint module, added option to reinitialize the backward integration phase (and perform a new backward integration using the same check points). - in adjoint module, relaxed assumption that t_final > t_0 (now accepts t_final < t_0). - Bug fixes - fixed bug in adjustment of sensitivity Nordsieck history array on an order decrease (when using BDF). - in adjoint module, fixed a potential use of memory before being set. - in adjoint module, fixed a bug related to data saved at check points. This addresses the case in which an order increase is deemed necessary at the very first step after a check-point. - Changes related to the 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 CVODES functions create new N_Vector variables through cloning, using an N_Vector passed by the user as a template. - Changes to type names and CVODES constants - removed type 'integertype'; instead use int or long int, as appropriate. - restructured the list of return values from the various CVODES functions. - changed all CVODES 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 - renamed header files to have prefix 'cv' instead of 'cvs' (e.g. cvdense.h replaces cvsdense.h). - added new function CVodeCreate which initializes the CVODES solver object and returns a pointer to the CVODES 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 CVODES 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. - in CVSPGMR, shortened argument lists for user preconditioner functions.