Feature: Add option to disable interpolation in ARKODE

CHANGELOG.md

@@ -2,17 +2,20 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
-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.
+### Major Features
+
+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.
+
+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`
@@ -32,39 +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 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.
 
-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 a bug in the HIP execution policies where `WARP_SIZE` would not be set
+with ROCm 6.0.0 or newer.
 
-Added support for Kokkos Kernels v4.
+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 bug where `MRIStepEvolve` would not handle a recoverable error produced
+from evolving the inner stepper.
 
-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).
+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.
 
+### 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_c_interface/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_c_interface/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_c_interface/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_c_interface/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)

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

@@ -709,9 +709,12 @@ the user has set a stop time (with a call to the optional input function
                  time, *tout*, in the direction of integration,
                  i.e. :math:`t_{n-1} <` *tout* :math:`\le t_{n}` for forward
                  integration, or :math:`t_{n} \le` *tout* :math:`< t_{n-1}` for
-                 backward integration.  It will then compute an approximation
-                 to the solution :math:`y(tout)` by interpolation (as described
-                 in :numref:`ARKODE.Mathematics.Interpolation`).
+                 backward integration. If interpolation is enabled (on by
+                 default), it will then compute an approximation to the solution
+                 :math:`y(tout)` by interpolation (as described in
+                 :numref:`ARKODE.Mathematics.Interpolation`). Otherwise, the
+                 solution at the time reached by the solver is returned,
+                 :math:`y(tret)`.
 
                  The *ARK_ONE_STEP* option tells the solver to only take a
                  single internal step, :math:`y_{n-1} \to y_{n}`, and return the solution
@@ -922,36 +925,60 @@ Set max number of constraint failures             :c:func:`ARKodeSetMaxNumConstr
 
 .. c:function:: int ARKodeSetInterpolantType(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).
+   Specifies the interpolation type used for dense output (interpolation of
+   solution output values) and implicit method predictors. By default, the
+   Hermite interpolation is used expect with SPRK method where Lagrange
+   interpolation is the default.
+
+   This routine must be called *after* the calling a stepper constructor. After
+   the first call to :c:func:`ARKodeEvolve` the interpolation type may not be
+   changed without first calling a stepper ``ReInit`` function.
+
+   The Hermite interpolation module (``ARK_INTERP_HERMITE``) is described in
+   :numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange
+   interpolation module (``ARK_INTERP_LAGRANGE``) is described in
+   :numref:`ARKODE.Mathematics.Interpolation.Lagrange`. ``ARK_INTERP_NONE`` will
+   disable interpolation.
+
+   When interpolation is disabled using, 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
+   :c:func:`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 ARKStep as an
+   explicit fast time scale integrator with MRI methods.
+
+   This routine frees any previously-allocated interpolation module, and
+   re-creates one according to the specified argument.
 
    :param arkode_mem: pointer to the ARKODE memory block.
-   :param itype: requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``).
+   :param itype: requested interpolant type: ``ARK_INTERP_HERMITE``,
+                 ``ARK_INTERP_LAGRANGE``, or ``ARK_INTERP_NONE``
 
    :retval ARK_SUCCESS: the function exited successfully.
    :retval ARK_MEM_NULL: ``arkode_mem`` was ``NULL``.
    :retval ARK_MEM_FAIL: the interpolation module could not be allocated.
    :retval ARK_ILL_INPUT: 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`.
+   .. versionchanged:: x.y.z
 
-      This routine frees any previously-allocated interpolation module, and re-creates
-      one according to the specified argument.  Thus any previous calls to
-      :c:func:`ARKodeSetInterpolantDegree` will be nullified.
+      Added the ``ARK_INTERP_NONE`` option to disable interpolation.
 
-      After the first call to :c:func:`ARKodeEvolve` the interpolation type may
-      not be changed without first calling ``*StepReInit``.
-
-      If this routine is not called, the Hermite interpolation module will be used.
+      Values set by a previous call to :c:func:`ARKStepSetInterpolantDegree` are
+      no longer nullified by a call to :c:func:`ARKStepSetInterpolantType`.
 
    .. versionadded:: x.y.z
 
+      This function replaces stepper specific versions in ARKStep, ERKStep,
+      MRIStep, and SPRKStep.
+
 
 .. c:function:: int ARKodeSetInterpolantDegree(void* arkode_mem, int degree)