SUNStepper basics based on MRIStepInnerStepper

CHANGELOG.md

@@ -6,6 +6,12 @@
 
 ### New Features and Enhancements
 
+Added the `SUNStepper` base class to represent a generic solution procedure for
+IVPs. This is used by the SplittingStep and ForcingStep modules of ARKODE. A
+SUNStepper can be created from an ARKODE memory block with the new function
+`ARKodeCreateSUNStepper`. To enable interoperability with `MRIStepInnerStepper`,
+the function `MRIStepInnerStepper_CreateFromSUNStepper` was added.
+
 The default value of `CMAKE_CUDA_ARCHITECTURES` is no longer set to `70` and is
 now determined automatically by CMake. The previous default was only valid for
 Volta GPUs while the automatically selected value will vary across compilers and

doc/arkode/guide/source/Constants.rst

@@ -538,6 +538,8 @@ contains the ARKODE output constants.
    | :index:`ARK_STEPPER_UNSUPPORTED`    | -48  | An operation was not supported by the current              |
    |                                     |      | time-stepping module.                                      |
    +-------------------------------------+------+------------------------------------------------------------+
+   | :index:`ARK_SUNSTEPPER_ERR`         | -49  | An error occurred in the SUNStepper module                 |
+   +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_UNRECOGNIZED_ERROR`     | -99  | An unknown error was encountered.                          |
    +-------------------------------------+------+------------------------------------------------------------+
    |                                                                                                         |

doc/arkode/guide/source/Usage/MRIStep/Custom_Inner_Stepper/Description.rst

@@ -79,6 +79,34 @@ Creating and Destroying an Object
       for details on how to attach member data and method function pointers.
 
 
+.. c:function:: int MRIStepInnerStepper_CreateFromSUNStepper(SUNStepper sunstepper, MRIStepInnerStepper* stepper)
+
+   This utility function wraps a :c:type:`SUNStepper` as an
+   :c:type:`MRIStepInnerStepper`.
+
+   **Arguments:**
+      * ``sunctx`` -- the SUNDIALS simulation context.
+      * ``sunstepper`` -- the c:type:`SUNStepper` to wrap.
+      * ``stepper`` -- a pointer to an MRI inner stepper object.
+
+   **Return value:**
+      * ARK_SUCCESS if successful
+      * ARK_MEM_FAIL if a memory allocation error occurs
+
+   **Example usage:**
+
+   .. code-block:: C
+
+      SUNStepper sunstepper = NULL;
+      SUNStepper_Create(ctx, &sunstepper);
+      /* Attach content and functions to the SUNStepper... */
+
+      MRIStepInnerStepper inner_stepper = NULL;
+      flag = MRIStepInnerStepper_Create(sunstepper, &inner_stepper);
+
+   .. versionadded:: x.y.z
+
+
 .. c:function:: int MRIStepInnerStepper_Free(MRIStepInnerStepper *stepper)
 
    This function destroys an :c:type:`MRIStepInnerStepper` object.

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

@@ -4685,3 +4685,26 @@ rescale the upcoming time step by the specified factor.  If a value
       * ``examples/arkode/C_serial/ark_heat1D_adapt.c``
 
    .. versionadded:: 6.1.0
+
+
+
+.. _ARKODE.Usage.SUNStepperInterface:
+
+Using an ARKODE solver as a SUNStepper
+--------------------------------------
+
+The utility function :c:func:`ARKodeCreateSUNStepper` wraps an ARKODE memory
+block as a :c:type:`SUNStepper`.
+
+.. c:function:: int ARKodeCreateSUNStepper(void *inner_arkode_mem, SUNStepper *stepper)
+
+   Wraps an ARKODE integrator as a :c:type:`SUNStepper`.
+
+   :param arkode_mem: pointer to the ARKODE memory block.
+   :param stepper: the :c:type:`SUNStepper` object.
+
+   :retval ARK_SUCCESS: the function exited successfully.
+   :retval ARK_MEM_FAIL: a memory allocation failed.
+   :retval ARK_SUNSTEPPER_ERR: the :c:type:`SUNStepper` initialization failed.
+
+   .. versionadded:: x.y.z

doc/arkode/guide/source/index.rst

@@ -65,6 +65,7 @@ with support by the `US Department of Energy <http://www.doe.gov>`_,
    sunlinsol/index.rst
    sunnonlinsol/index.rst
    sunadaptcontroller/index.rst
+   sunstepper/index.rst
    sunmemory/index.rst
    sundials/Install_link.rst
    Constants

doc/arkode/guide/source/sunstepper/SUNStepper_links.rst

@@ -0,0 +1,14 @@
+.. ----------------------------------------------------------------
+   SUNDIALS Copyright Start
+   Copyright (c) 2002-2024, Lawrence Livermore National Security
+   and Southern Methodist University.
+   All rights reserved.
+
+   See the top-level LICENSE and NOTICE files for details.
+
+   SPDX-License-Identifier: BSD-3-Clause
+   SUNDIALS Copyright End
+   ----------------------------------------------------------------
+
+.. include:: ../../../../shared/sunstepper/SUNStepper_Description.rst
+.. include:: ../../../../shared/sunstepper/SUNStepper_Implementing.rst

doc/arkode/guide/source/sunstepper/index.rst

@@ -0,0 +1,44 @@
+.. ----------------------------------------------------------------
+   Programmer(s): Steven B. Roberts @ LLNL
+   ----------------------------------------------------------------
+   SUNDIALS Copyright Start
+   Copyright (c) 2002-2024, Lawrence Livermore National Security
+   and Southern Methodist University.
+   All rights reserved.
+
+   See the top-level LICENSE and NOTICE files for details.
+
+   SPDX-License-Identifier: BSD-3-Clause
+   SUNDIALS Copyright End
+   ----------------------------------------------------------------
+
+.. _SUNStepper:
+
+#####################################
+Stepper Data Structure
+#####################################
+
+This section presents the :c:type:`SUNStepper` base class which represents a
+generic solution procedure for IVPs of the form
+
+.. math::
+   \dot{v}(t) = f(t, v) + r(t), \qquad v(t_0) = v_0,
+   :label: SUNStepper_IVP
+
+on an interval :math:`t \in [t_0, t_f]`. The time dependent forcing term,
+:math:`r_i(t)`, is given by
+
+.. math::
+   r(t) = \sum_{k = 0}^{n_{\text{forcing}}}
+   \frac{t - t_{\text{shift}}}{t_{\text{scale}}} \widehat{f}_k.
+   :label: SUNStepper_forcing
+
+:c:type:`SUNStepper` provides an abstraction over SUNDIALS integrators, custom
+integrators, exact solution procedures, or other approaches for solving
+:eq:`SUNStepper_IVP`. These are used, for example, in operator splitting and
+forcing methods to solve inner IVPs in a flexible way.
+
+.. toctree::
+   :maxdepth: 1
+
+   SUNStepper_links.rst

doc/shared/RecentChanges.rst

@@ -2,6 +2,15 @@
 
 **New Features and Enhancements**
 
+Added the :c:type:`SUNStepper` base class to represent a generic solution
+procedure for IVPs. This is used by the
+:ref:`SplittingStep <ARKODE.Usage.SplittingStep>` and
+:ref:`ForcingStep <ARKODE.Usage.ForcingStep>` modules of ARKODE. A SUNStepper
+can be created from an ARKODE memory block with the new function
+:c:func:`ARKodeCreateSUNStepper`. To enable interoperability with
+:c:type:`MRIStepInnerStepper`, the function
+:c:func:`MRIStepInnerStepper_CreateFromSUNStepper` was added.
+
 The default value of :cmakeop:`CMAKE_CUDA_ARCHITECTURES` is no longer set to
 ``70`` and is now determined automatically by CMake. The previous default was
 only valid for Volta GPUs while the automatically selected value will vary