SUNDIALS: SUite of Nonlinear and DIfferential/ALgebraic Equation Solvers
CVODES

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).

CVODES is a superset of CVODE and hence all options available to CVODE (with the exception of the FCVODE interface module) are also available for CVODES. Both integration methods (Adams-Moulton and BDF) and the corresponding nonlinear iteration methods, as well as all linear solver and preconditioner modules, are available for the integration of the original ODEs, the sensitivity systems, or the adjoint system.

Depending on the number of model parameters and the number of functional outputs, one of two sensitivity methods is more appropriate. The forward sensitivity analysis (FSA) method is mostly suitable when the gradients of many outputs (for example the entire solution vector) with respect to relatively few parameters are needed. In this approach, the model is differentiated with respect to each parameter in turn to yield an additional system of the same size as the original one, the result of which is the solution sensitivity. The gradient of any output function depending on the solution can then be directly obtained from these sensitivities by applying the chain rule of differentiation. The adjoint sensitivity analysis (ASA) method is more practical than the forward approach when the number of parameters is large and the gradients of only few output functionals are needed. In this approach, the solution sensitivities need not be computed explicitly. Instead, for each output functional of interest, an additional system, adjoint to the original one, is formed and solved. The solution of the adjoint system can then be used to evaluate the gradient of the output functional with respect to any set of model parameters.

The FSA module in CVODES implements a simultaneous corrector method as well as two flavors of staggered corrector methods–for the case when sensitivity right hand sides are generated all at once or separated for each model parameter. The ASA module provides the infrastructure required for the backward integration in time of systems of differential equations dependent on the solution of the original ODEs. It employs a checkpointing scheme for efficient interpolation of forward solutions during the backward integration.

See Software page for download and documentation.
 

cvodes Release History
 

What’s new in v2.9.0?

  • New features and/or enhancements
    • Two new NVECTOR modules added: for Hypre ParVector and PETSc.
    • In vector API, added new required function, N_VGetVectorID.
    • Upgrades to sparse solver interfaces; now support CSR matrix type with KLU solver.
    • Example codes were changed from using NV_DATA macro to using N_VGetArrayPointer_* when using the native vectors shipped with SUNDIALS.
    • Updated to return integers from linear solver and preconditioner ‘free’ functions.
    • Added cvsRoberts_FSA_klu.c, cvsRoberts_FSA_sps.c, cvsRoberts_ASAi_klu.c, cvsRoberts_ASAi_sps.c sparse direct solver examples. Also, added cvsAdvDiff_bnd_omp.c OpenMP example.
    • Changed each **FreeB() to type int; added return(0) to each.  
    • In interpolation routines for backward problems, added logic to bypass sensitivity interpolation if input sensitivity argument is NULL.
  • Bug fixes
    • Fixed memory leak in banded preconditioner interface.
    • Fixed some examples w.r.t. switch to new macro/function names SUNRexp etc.
    • Various minor fixes to installation-related files.
    • Corrected name N_VCloneEmptyVectorArray to N_VCloneVectorArrayEmpty in all documentation files.
    • Minor corrections and additions to User Guide, including removal of references to specific NVECTOR names in usage skeletons.

What’s new in v2.8.0?

  • New features
    • Added interface to the sparse direct solver KLU.
    • Added interface to SuperLU_MT.
  • Bug fixes
    • Fixed minor bug in cvRootfind involving rootdir input.
    • Fixed line setting smu in CVLapackBand.
    • Fixed line setting cv_mem->cv_fQS_data in CVodeQuadSensInit.
    • Fixed an error in example cvsHessian_ASA_FSA, in function fB2.
  • Changes to user interface
    • Added user Jacobian option functions CVDlsSetDenseJacFnBS and CVDlsSetBandJacFnBS.
  • Changes to documentation
    • Added paragraphs on CVodeAdjReInit and CVodeGetAdjY.
  • Changes related to the build system
    • Dropped support and documentation of the Autotools mode of installation.

What’s new in v2.7.0?

  • Bug fixes
    • fixed major logic errors in integration of backward problems.
    • logic in CVSetTqBDF changed to avoid a divide by zero.
    • linear solver memory set to zero after being created.
    • linear solver memory is freed on an error return.
  • Changes to user interface
    • Problem size and related integers (bandwidth parameters etc.) all have type long int, except for those in user calls specifying BLAS/LAPACK routines.
    • index ‘which’ changed from type long int to int.

What’s new in v2.6.0?

  • New features
    • new linear solver module, based on Blas and Lapack for both dense and banded matrices.
    • option to specify which direction of zero-crossing is to be monitored while performing rootfinding.
    • support for integration of quadrature equations depending on both the states and forward sensitivity (and thus support for forward sensitivity analysis of quadrature equations).
    • support for simultaneous integration of multiple backward problems based on the same underlying ODE (e.g., for use in an forward-over-adjoint method for computing second order derivative information).
    • support for backward integration of ODEs and quadratures depending on both forward states and sensitivities (e.g., for use in computing second-order derivative information).
    • support for reinitialization of the adjoint module.
  • Changes to user interface
    • reorganization of all linear solver modules into two families (besides the existing family of scaled preconditioned iterative linear solvers, the direct solvers, including the new Lapack-based ones, were also organized into a direct family).
    • maintaining a single pointer to user data, optionally specified through a Set-type function.
    • general streamlining of the preconditioner modules distributed with the solver.
    • the prototypes of all functions related to integration of backward problems were modified to support the simultaneous integration of multiple problems.

What’s new in v2.5.0?

  • Bug fixes
    • fixed bug in final stopping times to resolve potential conflicts when tout is close to tstop.
    • fixed bug in adjoint module (function CVodeF): the solver was sometimes incorrectly taking an additional step before returning control to the user (in CV_NORMAL mode) thus leading to a failure in the interpolated output function .
    • fixed bug in adjoint module (function CVodeB): while searching for the current check point, the solver was sometimes reaching outside the integration interval resulting in a segmentation fault.
  • Changes related to the build system
    • rearranged the entire SUNDIALS source tree.
    • all exported header files are now installed in separate subdirectories of the installtion include directory.
    • header files are included now by specifying the relative path (e.g. #include <cvodes/cvodes.h>).

What’s new in v2.4.0?

  • New features
    • added CVSPBCG interface module to allow CVODES to interface with the shared SPBCG (scaled preconditioned Bi-CGSTAB) linear solver module.
    • added CVSPTFQMR interface module to allow CVODES to interface with the shared SPTFQMR (scaled preconditioned TFQMR) linear solver module.
    • added support for SPBCG and SPTFQMR to the CVBBDPRE and CVBANDPRE preconditioner modules.
    • added support for interpreting failures in user-supplied functions.
    • added a new variable-degree polynomial interpolation method as an an alternative to the current cubic Hermite interpolation for the adjoint module.
  • Changes to user interface
    • changed argument of CVodeFree, CVBandPrecFree, CVBBDPrecFree, and CVadjFree to be the address of the respective memory block pointer, so that its NULL value is propagated back to the calling function.
    • added CVSPBCG module which defines appropriate CVSpbcg* functions to allow CVODES to interface with the shared SPBCG linear solver module.
    • added CVBBDSpbcg function to CVBBDPRE module and CVBPSpbcg function to CVBANDPRE module to support SPBCG linear solver module.
    • added CVBBDSptfqmr function to CVBBDPRE module and CVBPSptfqmr function to CVBANDPRE module to support SPTFQMR linear solver module.
    • changed function type names to accomodate all the Scaled Preconditioned Iterative Linear Solvers now available:
      CVSpgmrJactimesVecFn -> CVSpilsJacTimesVecFn
      CVSpgmrPrecSetupFn -> CVSpilsPrecSetupFn
      CVSpgmrPrecSolveFn -> CVSpilsPrecSolveFn
    • changed function types so that all user-supplied functions return an integer flag.
    • changed some names for CVBANDPRE and CVBBDPRE function outputs.
    • added option for user-supplied error handler function.
    • added an argument to CVadjMalloc to specify the type of interpolation (possible values are CV_HERMITE for cubic Hermite and CV_POLYNOMIAL for variable-order polynomial interpolation).
    • renamed all exported header files (except for cvodes.h and cvodea.h all header files have the prefix cvodes_).
    • changed naming scheme for CVODES examples.
  • Changes related to the build system
    • the main CVODES header files (cvodes.h and cvodea.h) are still exported to the install include directory. However, all other CVODES header files are exported into a cvodes subdirectory of the install include directory.
    • the CVODES library now contains all shared object files (there is no separate libsundials_shared library any more).

What’s new in v2.3.0?

  • 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.

What’s new in v2.2.0?

  • 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.

What’s new in v2.1.2?

  • Bug fixes
    • fixed bug in CVode function: Initial setting of tretlast = *tret = tn removed (correcting erroneous behavior at first call to the rootfinding function CVRcheck3).
    • Removed redundant setting of tretlast = *tret = tn at CLOSE_ROOTS return from CVode.
  • 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.
  • 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.

What’s new in v2.1.1?

  • New features
    • added function CVodeSensToggle to allow activation/deactivation of sensitivity calculations without memory allocation/deallocation.
  • Bug fixes
    • fixed bug in sensitivity computations on an order increase (when using BDF).
    • fixed a potential, although not harmful, use of uninitialized memory in the calculation of initial step size.
    • 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.
    • changed method of generating sundials_config.h to avoid potential warnings of redefinition of preprocessor symbols.

What’s new in v2.1.0?

  • 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).
    • added option to disable all error messages.
  • 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
    • 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.