Feature: Option to disable interpolation in ARKODE

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
+### Major Features
+
+### New Features and Enhancements
+
+Added CMake infrastructure that enables externally maintained addons/plugins to
+be *optionally* built with SUNDIALS. See the [Contributing
+Guide](./CONTRIBUTING.md) for more details.
+
+Users may now disable interpolated output in ARKODE steppers by passing
+`ARK_INTERP_NONE` to the `SetInterpolantType` functions:
+
+* `ARKStepSetInterpolantType`
+* `ERKStepSetInterpolantType`
+* `MRIStepSetInterpolantType`
+* `SPRKStepSetInterpolantType`
+
+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, `Evolve` functions called 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 MRIStep.
+
+### 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).
@@ -20,9 +49,21 @@ with the Cray Fortran compiler.
 Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
 from evolving the inner stepper.
 
-Added CMake infrastructure that enables externally maintained addons/plugins
-to be *optionally* built with SUNDIALS. See the [Contributing Guide](./CONTRIBUTING.md)
-for more details.
+### Deprecation Notices
+
+Compiler warning messages have been added to the following previously deprecated
+functions:
+
+* `ARKStepSetDenseOrder`
+* `ERKStepSetDenseOrder`
+* `MRIStepSetDenseOrder`
+
+These functions will be removed in the next major release and users should
+transition to the follow functions:
+
+* `ARKStepSetInterpolantDegree`
+* `ERKStepSetInterpolantDegree`
+* `MRIStepSetInterpolantDegree`
 
 ## Changes to SUNDIALS in release v7.0.0
 

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

@@ -721,9 +721,11 @@ 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 is returned.
 
         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
@@ -907,13 +909,41 @@ Set max number of constraint failures             :c:func:`ARKStepSetMaxNumConst
 
 .. 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).
+   Specifies the interpolation module (used for dense output -- interpolation of
+   solution output values and implicit method predictors). By default, the
+   Hermite interpolation module will be used.
+
+   This routine must 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`.
+
+   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:`ARKStepEvolve` 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 MRIStep.
+
+   This routine frees any previously-allocated interpolation module, and
+   re-creates one according to the specified argument.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the ARKStep memory block.
-      * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
+      * *itype* -- requested interpolant type: ``ARK_INTERP_HERMITE``,
+        ``ARK_INTERP_LAGRANGE``, or ``ARK_INTERP_NONE``.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
@@ -922,21 +952,12 @@ Set max number of constraint failures             :c:func:`ARKStepSetMaxNumConst
       * *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()`.
+   .. versionchanged:: x.y.z
 
-      If this routine is not called, the Hermite interpolation module will be used.
+      Added the ``ARK_INTERP_NONE`` option to disable interpolation.
 
+      Values set by a previous call to :c:func:`ARKStepSetInterpolantDegree` are
+      no longer nullified by a call to :c:func:`ARKStepSetInterpolantType`.
 
 
 .. c:function:: int ARKStepSetInterpolantDegree(void* arkode_mem, int degree)
@@ -983,9 +1004,10 @@ Set max number of constraint failures             :c:func:`ARKStepSetMaxNumConst
 
 .. c:function:: int ARKStepSetDenseOrder(void* arkode_mem, int dord)
 
-   *This function is deprecated, and will be removed in a future release.
-   Users should transition to calling* :c:func:`ARKStepSetInterpolantDegree()`
-   *instead.*
+   .. deprecated:: 5.2.0
+
+      This function will be removed in the next major release. Users should
+      transition to calling :c:func:`ARKStepSetInterpolantDegree()`.
 
 
 

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

@@ -346,10 +346,11 @@ has requested rootfinding.
         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 (using one
-        of the dense output routines 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 is returned.
 
         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
@@ -530,13 +531,39 @@ 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).
+   Specifies the interpolation module (used for dense output -- interpolation of
+   solution output values). By default, the Hermite interpolation module will be
+   used.
+
+   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`.
+
+   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 and
+   interpolation at stop times cannot be used (interpolating at stop times is
+   disabled by default). With interpolation disabled, calling
+   :c:func:`ERKStepEvolve` 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.
+
+   This routine frees any previously-allocated interpolation module, and
+   re-creates one according to the specified argument.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the ERKStep memory block.
-      * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
+      * *itype* -- requested interpolant type: ``ARK_INTERP_HERMITE``,
+        ``ARK_INTERP_LAGRANGE``, or ``ARK_INTERP_NONE``.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
@@ -545,21 +572,12 @@ Optional inputs for ERKStep
       * *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()`.
+   .. versionchanged:: x.y.z
 
-      If this routine is not called, the Hermite interpolation module will be used.
+      Added the ``ARK_INTERP_NONE`` option to disable interpolation.
 
+      Values set by a previous call to :c:func:`ERKStepSetInterpolantDegree` are
+      no longer nullified by a call to :c:func:`ERKStepSetInterpolantType`.
 
 
 .. c:function:: int ERKStepSetInterpolantDegree(void* arkode_mem, int degree)
@@ -606,9 +624,10 @@ Optional inputs for ERKStep
 
 .. c:function:: int ERKStepSetDenseOrder(void* arkode_mem, int dord)
 
-   *This function is deprecated, and will be removed in a future release.
-   Users should transition to calling* :c:func:`ERKStepSetInterpolantDegree()`
-   *instead.*
+   .. deprecated:: 5.2.0
+
+      This function will be removed in the next major release. Users should
+      transition to calling :c:func:`ERKStepSetInterpolantDegree()`.
 
 
 

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

@@ -540,9 +540,11 @@ 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 is returned.
 
         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
@@ -728,15 +730,42 @@ 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).
+   Specifies the interpolation module (used for dense output -- interpolation of
+   solution output values and implicit method predictors). By default, the
+   Hermite interpolation module will be used.
+
+   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`.
+
+   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:`MRIStepEvolve` 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.
+
+   This routine frees any previously-allocated interpolation module, and
+   re-creates one according to the specified argument.
 
    **Arguments:**
 
    * *arkode_mem* -- pointer to the MRIStep memory block.
 
-   * *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
+   * *itype* -- requested interpolant type: ``ARK_INTERP_HERMITE``,
+     ``ARK_INTERP_LAGRANGE``, or ``ARK_INTERP_NONE``.
 
    **Return value:**
 
@@ -749,20 +778,12 @@ Optional inputs for MRIStep
    * *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`.
+   .. 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:`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.
+      Added the ``ARK_INTERP_NONE`` option to disable interpolation.
 
+      Values set by a previous call to :c:func:`MRIStepSetInterpolantDegree` are
+      no longer nullified by a call to :c:func:`MRIStepSetInterpolantType`.
 
 
 .. c:function:: int MRIStepSetInterpolantDegree(void* arkode_mem, int degree)
@@ -814,9 +835,10 @@ Optional inputs for MRIStep
 
 .. c:function:: int MRIStepSetDenseOrder(void* arkode_mem, int dord)
 
-   *This function is deprecated, and will be removed in a future release.
-   Users should transition to calling* :c:func:`MRIStepSetInterpolantDegree()`
-   *instead.*
+   .. deprecated:: 5.2.0
+
+      This function will be removed in the next major release. Users should
+      transition to calling :c:func:`MRIStepSetInterpolantDegree()`.