4.1. Introduction

CVODES [136] is part of a software family called SUNDIALS: SUite of Nonlinear and DIfferential/ALgebraic equation Solvers [84]. This suite consists of CVODE, ARKODE, KINSOL, and IDA, and variants of these with sensitivity analysis capabilities. CVODES is a solver for stiff and nonstiff initial value problems (IVPs) for systems of ordinary differential equation (ODEs). In addition to solving stiff and nonstiff ODE systems, CVODES has sensitivity analysis capabilities, using either the forward or the adjoint methods.

4.1.1. Historical Background

Fortran solvers for ODE initial value problems are widespread and heavily used. Two solvers that have been written at LLNL in the past are VODE [25] and VODPK [31]. VODE is a general purpose solver that includes methods for both stiff and nonstiff systems, and in the stiff case uses direct methods (full or banded) for the solution of the linear systems that arise at each implicit step. Externally, VODE is very similar to the well known solver LSODE [117]. VODPK is a variant of VODE that uses a preconditioned Krylov (iterative) method, namely GMRES, for the solution of the linear systems. VODPK is a powerful tool for large stiff systems because it combines established methods for stiff integration, nonlinear iteration, and Krylov (linear) iteration with a problem-specific treatment of the dominant source of stiffness, in the form of the user-supplied preconditioner matrix [26]. The capabilities of both VODE and VODPK have been combined in the C-language package CVODE [42].

At present, CVODE may utilize a variety of Krylov methods provided in SUNDIALS that can be used in conjunction with Newton iteration: these include the GMRES (Generalized Minimal RESidual) [129], FGMRES (Flexible Generalized Minimum RESidual) [128], Bi-CGStab (Bi-Conjugate Gradient Stabilized) [164], TFQMR (Transpose-Free Quasi-Minimal Residual) [65], and PCG (Preconditioned Conjugate Gradient) [78] linear iterative methods. As Krylov methods, these require almost no matrix storage for solving the Newton equations as compared to direct methods. However, the algorithms allow for a user-supplied preconditioner matrix, and for most problems preconditioning is essential for an efficient solution. For very large stiff ODE systems, the Krylov methods are preferable over direct linear solver methods, and are often the only feasible choice. Among the Krylov methods in SUNDIALS, we recommend GMRES as the best overall choice. However, users are encouraged to compare all options, especially if encountering convergence failures with GMRES. Bi-CGStab and TFQMR have an advantage in storage requirements, in that the number of workspace vectors they require is fixed, while that number for GMRES depends on the desired Krylov subspace size. FGMRES has an advantage in that it is designed to support preconditioners that vary between iterations (e.g., iterative methods). PCG exhibits rapid convergence and minimal workspace vectors, but only works for symmetric linear systems.

In the process of translating the VODE and VODPK algorithms into C, the overall CVODE organization has been changed considerably. One key feature of the CVODE organization is that the linear system solvers comprise a layer of code modules that is separated from the integration algorithm, allowing for easy modification and expansion of the linear solver array. A second key feature is a separate module devoted to vector operations; this facilitated the extension to multiprosessor environments with minimal impacts on the rest of the solver, resulting in PVODE [34], the parallel variant of CVODE.

CVODES is written with a functionality that is a superset of that of the pair CVODE/PVODE. Sensitivity analysis capabilities, both forward and adjoint, have been added to the main integrator. Enabling forward sensitivity computations in CVODES will result in the code integrating the so-called sensitivity equations simultaneously with the original IVP, yielding both the solution and its sensitivity with respect to parameters in the model. Adjoint sensitivity analysis, most useful when the gradients of relatively few functionals of the solution with respect to many parameters are sought, involves integration of the original IVP forward in time followed by the integration of the so-called adjoint equations backward in time. CVODES provides the infrastructure needed to integrate any final-condition ODE dependent on the solution of the original IVP (in particular the adjoint system).

Development of CVODES was concurrent with a redesign of the vector operations module across the SUNDIALS suite. The key feature of the N_Vector module is that it is written in terms of abstract vector operations with the actual vector functions attached by a particular implementation (such as serial or parallel) of N_Vector. This allows writing the SUNDIALS solvers in a manner independent of the actual N_Vector implementation (which can be user-supplied), as well as allowing more than one N_Vector module to be linked into an executable file. SUNDIALS (and thus CVODES) is supplied with serial, MPI-parallel, and both OpenMP and Pthreads thread-parallel N_Vector implementations.

There were several motivations for choosing the C language for CVODE, and later for CVODES. First, a general movement away from Fortran and toward C in scientific computing was apparent. Second, the pointer, structure, and dynamic memory allocation features in C are extremely useful in software of this complexity. Finally, we prefer C over C++ for CVODES because of the wider availability of C compilers, the potentially greater efficiency of C, and the greater ease of interfacing the solver to applications written in extended Fortran.

4.1.2. Changes to SUNDIALS in release X.Y.Z

Major Features

New Features and Enhancements

Added the function SUNLogger_SetQueueAndFlushMsgFns() to allow for user-defined functions to queue and flush log messages.

Updated examples/cvode/petsc/cv_petsc_ex7.c to support PETSc 3.25.0.

Added the ARKODE_SSP_ERK_3_1_2, ARKODE_SSP_ERK_4_1_2, ARKODE_SSP_ERK_4_2_3, ARKODE_SSP_ERK_10_3_4, ARKODE_SSP_LSPUM_ERK_3_1_2, and ARKODE_ASCHER_ERK_3_1_2 embedded explicit Runge-Kutta Butcher tables.

Added the ARKODE_SSP_DIRK_3_1_2, ARKODE_SSP_LSPUM_SDIRK_3_1_2, ARKODE_ESDIRK_4_2_3, and ARKODE_ASCHER_SDIRK_3_1_2 embedded diagonally implicit Runge-Kutta Butcher tables.

Of these, embedded additive Runge-Kutta methods may be formed using ARKODE_SSP_ERK_3_1_2 + ARKODE_SSP_DIRK_3_1_2, ARKODE_SSP_ERK_4_2_3 + ARKODE_ESDIRK_4_2_3, ARKODE_SSP_LSPUM_ERK_3_1_2 + ARKODE_SSP_LSPUM_SDIRK_3_1_2, and ARKODE_ASCHER_ERK_3_1_2 + ARKODE_ASCHER_SDIRK_3_1_2.

Added the ARKODE_IMEX_MRI_GARK_ASCHER_ARK2 and ARKODE_IMEX_MRI_GARK_ARK2 embedded implicit-explicit MRI-GARK coupling tables.

When info or debug logging is enabled, i.e., SUNDIALS_LOGGING_LEVEL is at least 3, it will now print to stdout by default. Previously, the default was to produce no output, and this behavior can be restored by setting the environment variables SUNLOGGER_INFO_FILENAME and SUNLOGGER_DEBUG_FILENAME to an empty string.

Improved the performance of logging when enabled but no file pointer was set.

Bug Fixes

Fixed a bug in the sundials4py wrappers for user-provided SUNStepper evolve and one_step functions.

Fixed a bug where an unrecognized error return flag from a user-provided SUNLinearSolver module would register as a successful linear solve.

Fixed a minor bug where the number of required stages for STS methods in the LSRKStep module was incorrectly computed using the spectral radius instead of the real part of the Jacobian eigenvalues.

Fixed a minor bug where the negative real extent of the stability region for the RKC method was not being properly computed, which could result in an underestimation of the number of stages required for stability.

Fixed a minor bug where STS methods were limited to one fewer than the maximum allowed number of stages. STS can now use the full maximum number of stages.

Fixed a bug that caused SUNDomEigEstimator_Initialize to overwrite the user-provided initial guess from SUNDomEigEstimator_SetInitialGuess. These routines are now order-independent.

Fixed memory leaks in CVODES, IDAS, and KINSOL in the unlikely event of a failed malloc.

Fixed minor bug in reporting the maximum number of stages in ARKodeGetStageIndex() when running SSP methods in LSRKStep.

Removed duplicate logging output that would cause the Python logging tools to fail with a repeated key error.

Fixed a CMake issue that prevented finding third-party libraries installed in default search locations e.g., paths included in CMAKE_INSTALL_PREFIX (Issue #935).

Fixed a CMake issue that prevented automatically finding PETSc dependencies.

Fixed empty elseif() cases in the CMake files for the Fortran interfaces to the ManyVector and MPIPlusX vectors which could results in a missing include path when compiling if an MPI compiler wrapper is not found.

Fixed a bug where IDAS would incorrectly compute the quadrature predictor when IDACalcIC was used. In some cases, this lead to an inconsistent solution in the forward solve compared to the forward recomputation from a checkpoint, ultimately causing a segfault.

Fixed a CMake bug where Fortran modules were not created for LSRKStep, ForcingStep, and SplittingStep.

Corrected the version number used in version added, changed, and deprecated notes in the documentation to always use the SUNDIALS version number with the package version number as a parenthetical note when it differs from the SUNDIALS version number.

Fixed a bug in sundials4py where the CVodeGetRootInfo(), ARKodeGetRootInfo(), and IDAGetRootInfo() functions did not correctly return the rootsfound array. This addresses Issue #937.

Fixed a bug in ERKStep where calling ARKodeResize() before ARKodeEvolve() or ARKodeInit() would result in a segmentation fault.

Deprecation Notices

For changes in prior versions of SUNDIALS see §19.

4.1.3. Reading this User Guide

This user guide is a combination of general usage instructions. Specific example programs are provided as a separate document. We expect that some readers will want to concentrate on the general instructions, while others will refer mostly to the examples, and the organization is intended to accommodate both styles.

There are different possible levels of usage of CVODES. The most casual user, with a small IVP problem only, can get by with reading §4.2.1, then Chapter §4.4.1 up to §4.4.2 only, and looking at examples in [137]. In addition, to solve a forward sensitivity problem the user should read §4.2.7, followed by Chapter §4.4.3 and look at examples in [137].

In a different direction, a more expert user with an IVP problem may want to (a) use a package preconditioner (§4.4.2.7), (b) supply his/her own Jacobian or preconditioner routines (§4.4.1.4), (c) do multiple runs of problems of the same size (CVodeReInit()), (d) supply a new N_Vector module (§8), or even (e) supply new SUNLinearSolver and/or SUNMatrix modules (Chapters §9 and §10). An advanced user with a forward sensitivity problem may also want to (a) provide his/her own sensitivity equations right-hand side routine §4.4.3.3, (b) perform multiple runs with the same number of sensitivity parameters (§4.4.3.2.1, or (c) extract additional diagnostic information (§4.4.3.2.7). A user with an adjoint sensitivity problem needs to understand the IVP solution approach at the desired level and also go through §4.2.8 for a short mathematical description of the adjoint approach, Chapter §4.4.4 for the usage of the adjoint module in CVODES, and the examples in [137].

The structure of this document is as follows:

  • In Chapter §4.2, we give short descriptions of the numerical methods implemented by CVODES for the solution of initial value problems for systems of ODEs, continue with short descriptions of preconditioning §4.2.3, stability limit detection (§4.2.4), and rootfinding (§4.2.5), and conclude with an overview of the mathematical aspects of sensitivity analysis, both forward (§4.2.7) and adjoint (§4.2.8).

  • The following chapter describes the software organization of the CVODES solver (§4.3).

  • Chapter §4.4.1 is the main usage document for CVODES for simulation applications. It includes a complete description of the user interface for the integration of ODE initial value problems. Readers that are not interested in using CVODES for sensitivity analysis can then skip the next two chapters.

  • Chapter §4.4.3 describes the usage of CVODES for forward sensitivity analysis as an extension of its IVP integration capabilities. We begin with a skeleton of the user main program, with emphasis on the steps that are required in addition to those already described in Chapter §4.4.1. Following that we provide detailed descriptions of the user-callable interface routines specific to forward sensitivity analysis and of the additional optional user-defined routines.

  • Chapter §4.4.4 describes the usage of CVODES for adjoint sensitivity analysis. We begin by describing the CVODES checkpointing implementation for interpolation of the original IVP solution during integration of the adjoint system backward in time, and with an overview of a user’s main program. Following that we provide complete descriptions of the user-callable interface routines for adjoint sensitivity analysis as well as descriptions of the required additional user-defined routines.

  • Chapter §8 gives a brief overview of the generic N_Vector module shared among the various components of SUNDIALS, and details on the N_Vector implementations provided with SUNDIALS.

  • Chapter §9 gives a brief overview of the generic SUNMatrix module shared among the various components of SUNDIALS, and details on the SUNMatrix implementations provided with SUNDIALS: a dense implementation (§9.9), a banded implementation (§9.12) and a sparse implementation (§9.14).

  • Chapter §10 gives a brief overview of the generic SUNLinearSolver module shared among the various components of SUNDIALS. This chapter contains details on the SUNLinearSolver implementations provided with SUNDIALS. The chapter also contains details on the SUNLinearSolver implementations provided with SUNDIALS that interface with external linear solver libraries.

  • Finally, in the appendices, we provide detailed instructions for the installation of CVODES, within the structure of SUNDIALS (Appendix §1.1), as well as a list of all the constants used for input to and output from CVODES functions (Appendix §4.5).

Finally, the reader should be aware of the following notational conventions in this user guide: program listings and identifiers (such as CVodeInit) within textual explanations appear in typewriter type style; fields in C structures (such as content) appear in italics; and packages or modules, such as CVDLS, are written in all capitals.

Warning

Usage and installation instructions that constitute important warnings are marked in yellow boxes like this one.

4.1.4. SUNDIALS License and Notices

All SUNDIALS packages are released open source, under the BSD 3-Clause license for more details see the LICENSE and NOTICE files provided with all SUNDIALS packages.