2.1. Introduction

The ARKODE infrastructure provides adaptive-step time integration modules for stiff, nonstiff and mixed stiff/nonstiff systems of ordinary differential equations (ODEs). ARKODE itself is structured to support a wide range of one-step (but multi-stage) methods, allowing for rapid development of parallel implementations of state-of-the-art time integration methods. At present, ARKODE is packaged with four time-stepping modules, ARKStep, ERKStep, SPRKStep, and MRIStep.

ARKStep supports ODE systems posed in split, linearly-implicit form,

(2.1)\[M(t)\, \dot{y} = f^E(t,y) + f^I(t,y), \qquad y(t_0) = y_0,\]

where \(t\) is the independent variable, \(y\) is the set of dependent variables (in \(\mathbb{R}^N\)), \(M\) is a user-specified, nonsingular operator from \(\mathbb{R}^N\) to \(\mathbb{R}^N\), and the right-hand side function is partitioned into up to two components:

  • \(f^E(t,y)\) contains the “nonstiff” time scale components to be integrated explicitly, and

  • \(f^I(t,y)\) contains the “stiff” time scale components to be integrated implicitly.

Either of these operators may be disabled, allowing for fully explicit, fully implicit, or combination implicit-explicit (ImEx) time integration.

The algorithms used in ARKStep are adaptive- and fixed-step additive Runge–Kutta methods. Such methods are defined through combining two complementary Runge–Kutta methods: one explicit (ERK) and the other diagonally implicit (DIRK). Through appropriately partitioning the ODE right-hand side into explicit and implicit components (2.1), such methods have the potential to enable accurate and efficient time integration of stiff, nonstiff, and mixed stiff/nonstiff systems of ordinary differential equations. A key feature allowing for high efficiency of these methods is that only the components in \(f^I(t,y)\) must be solved implicitly, allowing for splittings tuned for use with optimal implicit solver algorithms.

This framework allows for significant freedom over the constitutive methods used for each component, and ARKODE is packaged with a wide array of built-in methods for use. These built-in Butcher tables include adaptive explicit methods of orders 2-9, adaptive implicit methods of orders 2-5, and adaptive ImEx methods of orders 2-5.

ERKStep focuses specifically on problems posed in explicit form,

(2.2)\[\dot{y} = f(t,y), \qquad y(t_0) = y_0.\]

allowing for increased computational efficiency and memory savings. The algorithms used in ERKStep are adaptive- and fixed-step explicit Runge–Kutta methods. As with ARKStep, the ERKStep module is packaged with adaptive explicit methods of orders 2-9.

SPRKStep focuses on Hamiltonian systems posed in the form,

\[H(t, p, q) = T(t, p) + V(t, q)\]
(2.3)\[\dot{p} = f_1(t,q) = \frac{\partial V(t,q)}{\partial q}, \quad \dot{q} = f_2(t,p) = \frac{\partial T(t,p)}{\partial p},\]

allowing for conservation of quadratic invariants.

MRIStep focuses specifically on problems posed in additive form,

(2.4)\[\dot{y} = f^E(t,y) + f^I(t,y) + f^F(t,y), \qquad y(t_0) = y_0.\]

where here the right-hand side function is additively split into three components:

  • \(f^E(t,y)\) contains the “slow-nonstiff” components of the system (this will be integrated using an explicit method and a large time step \(h^S\)),

  • \(f^I(t,y)\) contains the “slow-stiff” components of the system (this will be integrated using an implicit method and a large time step \(h^S\)), and

  • \(f^F(t,y)\) contains the “fast” components of the system (this will be integrated using a possibly different method than the slow time scale and a small time step \(h^F \ll h^S\)).

For such problems, MRIStep provides fixed-step slow step multirate infinitesimal step (MIS), multirate infinitesimal GARK (MRI-GARK), and implicit-explicit MRI-GARK (IMEX-MRI-GARK) methods, allowing for evolution of the problem (2.4) using multirate methods having orders of accuracy 2-4.

For ARKStep or MRIStep problems that include nonzero implicit term \(f^I(t,y)\), the resulting implicit system (assumed nonlinear, unless specified otherwise) is solved approximately at each integration step, using a SUNNonlinearSolver module, supplied either by the user or from the underlying SUNDIALS infrastructure. For nonlinear solver algorithms that internally require a linear solver, ARKODE may use a variety of SUNLinearSolver modules provided with SUNDIALS, or again may utilize a user-supplied module.

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

2.1.2. Reading this User Guide

This user guide is a combination of general usage instructions and specific example programs. 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.

The structure of this document is as follows:

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