3.1. Introduction

CVODE is part of a software family called SUNDIALS: SUite of Nonlinear and DIfferential/ALgebraic equation Solvers [80]. This suite consists of CVODE, ARKODE, KINSOL, and IDA, and variants of these with sensitivity analysis capabilities.

3.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 [24] and VODPK [30]. 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 [112]. 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 [25]. The capabilities of both VODE and VODPK have been combined in the C-language package CVODE [41].

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) [121], FGMRES (Flexible Generalized Minimum RESidual) [120], Bi-CGStab (Bi-Conjugate Gradient Stabilized) [156], TFQMR (Transpose-Free Quasi-Minimal Residual) [63], and PCG (Preconditioned Conjugate Gradient) [75] 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 [33], the parallel variant of CVODE.

Around 2002, the functionality of CVODE and PVODE were combined into one single code, simply called CVODE. Development of this version of CVODE 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 kernels 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 linked into an executable file. SUNDIALS (and thus CVODE) is supplied with a wide range of different N_Vector implementations, including: serial, MPI-parallel, both OpenMP and Pthreads thread-parallel N_Vector implementations, a Hypre parallel implementation, a PETSc implementation, and various GPU-enabled implementations.

3.1.2. Changes to SUNDIALS in release 7.5.0

Major Features

Added the SUNDomEigEstimator interface for estimating the dominant eigenvalue value of a system. Two implementations are provided: Power Iteration and Arnoldi Iteration. The latter method requires building with LAPACK support enabled.

Added the function LSRKStepSetDomEigEstimator in LSRKStep to attach a SUNDomEigEstimator, when using Runge-Kutta-Chebyshev or Runge-Kutta-Legendre methods, as an alternative to supplying a user-defined function to compute the dominant eigenvalue.

New Features and Enhancements

A new SUNLinearSolver, SUNLINEARSOLVER_GINKGOBATCH, and corresponding SUNMatrix, SUNMATRIX_GINKGOBATCH, were added for solving block/batched linear systems with the Ginkgo linear solver library. As a result, Ginkgo 1.9.0 or newer is now required when enabling Ginkgo support.

The functions KINSetMAA() and KINSetOrthAA() have been updated to allow for setting the Anderson acceleration depth and orthogonalization method after KINInit(). Additionally, KINSetMAA() and KINSetNumMaxIters() may now be called in any order.

Bug Fixes

Fixed a bug in how MRIStep interacts with an MRIHTol SUNAdaptController object (the previous version essentially just reverted to a decoupled multirate controller). Removed the upper limit on inner_max_tolfac in SUNAdaptController_SetParams_MRIHTol().

The shared library version numbers for the oneMKL dense linear solver and matrix as well as the PETSc SNES nonlinear solver have been corrected.

Fixed a CMake bug where the MRI H-Tol controller was not included in the ARKODE Fortran module.

Fixed a bug in the CUDA and HIP implementations of SUNMemoryHelper_CopyAsync() where the execution stream is not extracted correctly from the helper when a stream is not provided to SUNMemoryHelper_CopyAsync().

Fixed a bug in MRIStep where a segfault would occur when an MRI coupling table is not explicitly set and an MRI integrator is nested inside another MRI integrator.

Fixed a bug in MRIStep where MERK methods with unordered stage groups (MERK43 and MERK54) would include stage right-hand side vectors that had not been computed yet in fast time scale forcing computations. These vectors were scaled by zero, so in most cases the extraneous computations would not impact results. However, in cases where these vectors contain inf or nan, this would lead to erroneous forcing terms.

Fixed a bug in ARKodeSetDefaults() with LSRKStep where the stored spectral radius data was reset to zero, flags to update the dominant eigenvalue were reset to true, and a flag indicating if an SSP is being used was reset to false.

Fixed a bug introduced in v7.3.0 in KINSOL when using Anderson acceleration and solving a problem multiple times with the same KINSOL instance. In this use case, the current Anderson acceleration depth from the initial solve was not reinitialized on subsequent solves.

Fixed a logging bug in KINSOL where logging messages would not be output.

Fixed a bug in the suntools.logs Python module where the get_history function, when given a step_status for filtering output from a multirate method, would only extract values from the fast time scale if the slow time scale step matched the given status filter. Fixed an additional bug in get_history with MRI-GARK methods where values would not be extracted from a fast time scale integration associated with an embedding.

For changes in prior versions of SUNDIALS see §18.

3.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 CVODE. The most casual user, with a small IVP problem only, can get by with reading §3.2.1, then §3.4 through §3.4.3.9 only, and looking at examples in [82].

In a different direction, a more expert user with an IVP problem may want to (a) use a package preconditioner (§3.4.5), (b) supply his/her own Jacobian or preconditioner routines (§3.4.4.6), (c) do multiple runs of problems of the same size (§3.4.3.13), (d) supply a new N_Vector module (§8), (e) supply new SUNLinearSolver and/or SUNMatrix modules (§9 and §10), or even (f) supply new SUNNonlinearSolver modules (§11).

The structure of this document is as follows:

  • In §3.2, we give short descriptions of the numerical methods implemented by CVODE for the solution of initial value problems for systems of ODEs, and continue with short descriptions of preconditioning (§3.2.3), stability limit detection (§3.2.4), and rootfinding (§3.2.5).

  • The following chapter describes the software organization of the CVODE solver (§3.3).

  • §3.4 is the main usage document for CVODE for C applications. It includes a complete description of the user interface for the integration of ODE initial value problems.

  • In §1.8, we describe the use of CVODE with Fortran applications.

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

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

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

  • §11 describes the SUNNonlinearSolver API and nonlinear solver implementations shared among the various components of SUNDIALS.

  • Finally, in the appendices, we provide detailed instructions for the installation of CVODE, within the structure of SUNDIALS (§1.1), as well as a list of all the constants used for input to and output from CVODE functions (§3.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 are hyperlinked to their definitions directly; fields in C structures (such as content) appear in italics; and packages or modules, such as CVLS, are written in all capitals.

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

3.1.5. Acknowledgments

We wish to acknowledge the contributions to previous versions of the CVODE and PVODE codes and their user guides by Scott D. Cohen [40] and George D. Byrne [32].