Feature: Add option to disable interpolation in ARKODE

CHANGELOG.md

@@ -2,25 +2,20 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
-Fixed the runtime library installation path for windows systems. This fix changes the
-default library installation path from `CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_LIBDIR` to
-`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_BINDIR`.
-
-Fixed conflicting `.lib` files between shared and static libs when using `MSVC` on Windows.
+### Major Features
 
-Fixed invalid `SUNDIALS_EXPORT` generated macro when building both shared and static libs.
+Created shared user interface functions for ARKODE to allow more uniform control
+over time-stepping algorithms, improved extensibility, and simplified code
+maintenance. The corresponding stepper-specific user-callable functions are now
+deprecated and will be removed in a future major release.
 
-Created shared user interface for ARKODE user-callable routines, to allow more
-uniform control over time-stepping algorithms, improved extensibility, and
-simplified code maintenance.  Marked the corresponding stepper-specific
-user-callable routines as deprecated; these will be removed in a future major
-release.
+Added CMake infrastructure that enables externally maintained addons/plugins to
+be *optionally* built with SUNDIALS. See the [Contributing
+Guide](./CONTRIBUTING.md) for more details.
 
-Added "Resize" capability, as well as missing `SetRootDirection` and
-`SetNoInactiveRootWarn` functions, to ARKODE's SPRKStep time-stepping module.
+### New Features and Enhancements
 
-Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
-for users who wish to retain the current functionality.
+Added support for Kokkos Kernels v4.
 
 Added the following Runge-Kutta Butcher tables
 * `ARKODE_FORWARD_EULER_1_1`
@@ -40,37 +35,66 @@ Added the following MRI coupling tables
 * `ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL`
 * `ARKODE_IMEX_MRI_GARK_MIDPOINT`
 
+Users may now disable interpolated output in ARKODE by passing `ARK_INTERP_NONE`
+to `ARKodeSetInterpolantType`. When interpolation is disabled, rootfinding is
+not supported, implicit methods must use the trivial predictor (the default
+option), and interpolation at stop times cannot be used (interpolating at stop
+times is disabled by default). With interpolation disabled, calling
+`ARKodeEvolve` in `ARK_NORMAL` mode will return at or past the requested output
+time (setting a stop time may still be used to halt the integrator at a specific
+time). Disabling interpolation will reduce the memory footprint of an integrator
+by two or more state vectors (depending on the interpolant type and degree)
+which can be beneficial when interpolation is not needed e.g., when integrating
+to a final time without output in between or using an explicit fast time scale
+integrator with an MRI method.
+
+Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
+
+### Bug Fixes
+
 Updated the CMake variable `HIP_PLATFORM` default to `amd` as the previous
 default, `hcc`, is no longer recognized in ROCm 5.7.0 or newer. The new default
 is also valid in older version of ROCm (at least back to version 4.3.1).
 
-Fixed a bug in the HIP execution policies where `WARP_SIZE` would not be set
-with ROCm 6.0.0 or newer.
-
 Changed the CMake version compatibility mode for SUNDIALS to `AnyNewerVersion`
 instead of `SameMajorVersion`. This fixes the issue seen
 [here](https://github.com/AMReX-Codes/amrex/pull/3835).
 
-Fixed a bug in some Fortran examples where `c_null_ptr` was passed as an argument
-to a function pointer instead of `c_null_funptr`. This caused compilation issues
-with the Cray Fortran compiler.
+Fixed a CMake bug that caused an MPI linking error for our C++ examples in some
+instances. Fixes [GitHub Issue
+#464](https://github.com/LLNL/sundials/issues/464).
 
-Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
-from evolving the inner stepper.
+Fixed the runtime library installation path for windows systems. This fix
+changes the default library installation path from
+`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_LIBDIR` to
+`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_BINDIR`.
 
-Added CMake infrastructure that enables externally maintained addons/plugins
-to be *optionally* built with SUNDIALS. See the [Contributing Guide](./CONTRIBUTING.md)
-for more details.
+Fixed conflicting `.lib` files between shared and static libs when using `MSVC`
+on Windows.
 
-Added support for Kokkos Kernels v4.
+Fixed invalid `SUNDIALS_EXPORT` generated macro when building both shared and
+static libs.
+
+Fixed a bug in some Fortran examples where `c_null_ptr` was passed as an
+argument to a function pointer instead of `c_null_funptr`. This caused
+compilation issues with the Cray Fortran compiler.
+
+Fixed a bug in the HIP execution policies where `WARP_SIZE` would not be set
+with ROCm 6.0.0 or newer.
 
-Fixed a bug that caused error messages to be cut off in some cases. Fixes [GitHub Issue #461](https://github.com/LLNL/sundials/issues/461).
+Fixed a bug that caused error messages to be cut off in some cases. Fixes
+[GitHub Issue #461](https://github.com/LLNL/sundials/issues/461).
 
-Fixed a memory leak when an error handler was added to a `SUNContext`. Fixes [GitHub Issue #466](https://github.com/LLNL/sundials/issues/466).
+Fixed a memory leak when an error handler was added to a `SUNContext`. Fixes
+[GitHub Issue #466](https://github.com/LLNL/sundials/issues/466).
 
-Fixed a CMake bug that caused an MPI linking error for our C++ examples in some instances. Fixes [GitHub Issue #464](https://github.com/LLNL/sundials/issues/464).
+Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
+from evolving the inner stepper.
+
+Added missing `SetRootDirection` and `SetNoInactiveRootWarn` functions to
+ARKODE's SPRKStep time-stepping module.
 
-Fixed a bug in `ARKodeSPRKTable_Create` where the coefficient arrays where not
+Fixed a bug in `ARKodeSPRKTable_Create` where the coefficient arrays were not
 allocated.
 
 Fix bug on LLP64 platforms (like Windows 64-bit) where `KLU_INDEXTYPE` could be
@@ -79,6 +103,15 @@ Fix bug on LLP64 platforms (like Windows 64-bit) where `KLU_INDEXTYPE` could be
 Check if size of `SuiteSparse_long` is 8 if the size of `sunindextype` is 8
 when using KLU.
 
+### Deprecation Notices
+
+Numerous ARKODE stepper-specific functions are now deprecated in favor of
+ARKODE-wide functions.
+
+Deprecated `ARKStepSetOptimalParams` function. This functions does not have an
+ARKODE-wide equivalent, instructions have been added to the user guide for how
+to retain the current functionality using other user-callable functions.
+
 ## Changes to SUNDIALS in release v7.0.0
 
 ### Major Feature

doc/arkode/guide/source/Constants.rst

@@ -52,6 +52,8 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    | **Interpolation module input constants**      |                                                            |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARK_INTERP_NONE`                      | Disables polynomial interpolation for dense output.        |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARK_INTERP_HERMITE`                   | Specifies use of the Hermite polynomial interpolation      |
    |                                               | module (for non-stiff problems).                           |
    +-----------------------------------------------+------------------------------------------------------------+

doc/arkode/guide/source/Usage/ARKStep/User_callable.rst

@@ -552,39 +552,10 @@ Optional inputs for ARKStep
 
 .. c:function:: int ARKStepSetInterpolantType(void* arkode_mem, int itype)
 
-   Specifies use of the Lagrange or Hermite interpolation modules (used for
-   dense output -- interpolation of solution output values and implicit
-   method predictors).
-
-   **Arguments:**
-      * *arkode_mem* -- pointer to the ARKStep memory block.
-      * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
-
-   **Return value:**
-      * *ARK_SUCCESS* if successful
-      * *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
-      * *ARK_MEM_FAIL* if the interpolation module cannot be allocated
-      * *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
-        interpolation module has already been initialized
-
-   **Notes:**
-      The Hermite interpolation module is described in
-      :numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
-      is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
-
-      This routine frees any previously-allocated interpolation module, and re-creates
-      one according to the specified argument.  Thus any previous calls to
-      :c:func:`ARKStepSetInterpolantDegree()` will be nullified.
-
-      This routine may only be called *after* the call to :c:func:`ARKStepCreate`.
-      After the first call to :c:func:`ARKStepEvolve()` the interpolation type may
-      not be changed without first calling :c:func:`ARKStepReInit()`.
-
-      If this routine is not called, the Hermite interpolation module will be used.
-
    .. deprecated:: x.y.z
 
-      Use :c:func:`ARKodeSetInterpolantType` instead.
+      This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
+      the documentation for that function instead.
 
 
 .. c:function:: int ARKStepSetInterpolantDegree(void* arkode_mem, int degree)

doc/arkode/guide/source/Usage/ERKStep/User_callable.rst

@@ -329,39 +329,10 @@ Optional inputs for ERKStep
 
 .. c:function:: int ERKStepSetInterpolantType(void* arkode_mem, int itype)
 
-   Specifies use of the Lagrange or Hermite interpolation modules (used for
-   dense output -- interpolation of solution output values and implicit
-   method predictors).
-
-   **Arguments:**
-      * *arkode_mem* -- pointer to the ERKStep memory block.
-      * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
-
-   **Return value:**
-      * *ARK_SUCCESS* if successful
-      * *ARK_MEM_NULL* if the ERKStep memory is ``NULL``
-      * *ARK_MEM_FAIL* if the interpolation module cannot be allocated
-      * *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
-        interpolation module has already been initialized
-
-   **Notes:**
-      The Hermite interpolation module is described in
-      :numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
-      is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
-
-      This routine frees any previously-allocated interpolation module, and re-creates
-      one according to the specified argument.  Thus any previous calls to
-      :c:func:`ERKStepSetInterpolantDegree()` will be nullified.
-
-      This routine must be called *after* the call to :c:func:`ERKStepCreate`.
-      After the first call to :c:func:`ERKStepEvolve()` the interpolation type may
-      not be changed without first calling :c:func:`ERKStepReInit()`.
-
-      If this routine is not called, the Hermite interpolation module will be used.
-
    .. deprecated:: x.y.z
 
-      Use :c:func:`ARKodeSetInterpolantType` instead.
+      This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
+      the documentation for that function instead.
 
 
 

doc/arkode/guide/source/Usage/MRIStep/User_callable.rst

@@ -462,44 +462,10 @@ Optional inputs for MRIStep
 
 .. c:function:: int MRIStepSetInterpolantType(void* arkode_mem, int itype)
 
-   Specifies use of the Lagrange or Hermite interpolation modules (used for
-   dense output -- interpolation of solution output values and implicit
-   method predictors).
-
-   **Arguments:**
-
-   * *arkode_mem* -- pointer to the MRIStep memory block.
-
-   * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
-
-   **Return value:**
-
-   * *ARK_SUCCESS* if successful
-
-   * *ARK_MEM_NULL* if the MRIStep memory is ``NULL``
-
-   * *ARK_MEM_FAIL* if the interpolation module cannot be allocated
-
-   * *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
-     interpolation module has already been initialized
-
-   **Notes:** The Hermite interpolation module is described in
-   :numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
-   is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
-
-   This routine frees any previously-allocated interpolation module, and re-creates
-   one according to the specified argument.  Thus any previous calls to
-   :c:func:`MRIStepSetInterpolantDegree()` will be nullified.
-
-   This routine must be called *after* the call to :c:func:`MRIStepCreate()`.
-   After the first call to :c:func:`MRIStepEvolve()` the interpolation type may
-   not be changed without first calling :c:func:`MRIStepReInit()`.
-
-   If this routine is not called, the Hermite interpolation module will be used.
-
    .. deprecated:: x.y.z
 
-      Use :c:func:`ARKodeSetInterpolantType` instead.
+      This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
+      the documentation for that function instead.
 
 
 

doc/arkode/guide/source/Usage/SPRKStep/User_callable.rst

@@ -244,42 +244,10 @@ Optional inputs for SPRKStep
 
 .. c:function:: int SPRKStepSetInterpolantType(void* arkode_mem, int itype)
 
-   Specifies use of the Lagrange or Hermite interpolation modules (used for
-   dense output -- interpolation of solution output values and implicit
-   method predictors).
-
-   :param arkode_mem: pointer to the SPRKStep memory block.
-   :param itype: requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
-
-   :retval ARK_SUCCESS: if successful
-   :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_MEM_FAIL: if the interpolation module cannot be allocated
-   :retval ARK_ILL_INPUT: if the *itype* argument is not recognized or the
-                          interpolation module has already been initialized
-
-   .. note::
-
-      The Hermite interpolation module is described in
-      :numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
-      is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
-
-      This routine frees any previously-allocated interpolation module, and re-creates
-      one according to the specified argument.  Thus any previous calls to
-      :c:func:`SPRKStepSetInterpolantDegree()` will be nullified.
-
-      This routine must be called *after* the call to :c:func:`SPRKStepCreate`.
-      After the first call to :c:func:`SPRKStepEvolve()` the interpolation type may
-      not be changed without first calling :c:func:`SPRKStepReInit()`.
-
-      If this routine is not called, the Lagrange interpolation module will be used.
-
-      Interpolated outputs may or may not conserve the Hamiltonian. Our testing
-      has shown that Lagrange interpolation typically performs well in this
-      regard, while Hermite interpolation does not.
-
    .. deprecated:: x.y.z
 
-      Use :c:func:`ARKodeSetInterpolantType` instead.
+      This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
+      the documentation for that function instead.
 
 
 .. c:function:: int SPRKStepSetInterpolantDegree(void* arkode_mem, int degree)