Merge remote-tracking branch 'origin/feature/sunstepper' into feature…

…/sunadjoint

CHANGELOG.md

@@ -6,6 +6,11 @@
 
 ### 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 ARKstep memory block with the new function
+`ARKStepCreateSUNStepper`.
+
 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/Usage/ARKStep/User_callable.rst

@@ -4400,3 +4400,25 @@ wrap an ARKStep memory block as an :c:type:`MRIStepInnerStepper`.
 
    **Example codes:**
       * ``examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp``
+
+
+.. _ARKStep_CInterface.SUNStepperInterface:
+
+Interfacing with SUNStepper
+---------------------------
+
+The utility function :c:func:`ARKStepCreateSUNStepper` can be used to wrap an
+ARKStep memory block as a :c:type:`SUNStepper`.
+
+.. c:function:: int ARKStepCreateSUNStepper(void *inner_arkode_mem, SUNStepper *stepper)
+
+   Wraps an ARKStep memory block as a :c:type:`SUNStepper`.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the ARKStep memory block.
+      * *stepper* -- the :c:type:`SUNStepper` object.
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_MEM_FAIL* if a memory allocation failed
+      * *ARK_ILL_INPUT* if an argument has an illegal value.

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
    sunadjoint/index.rst
    sunmemory/index.rst
    sundials/Install_link.rst

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 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,11 @@
 
 **New Features and Enhancements**
 
+Added the :c:type:`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 ARKstep memory block with the new
+function :c:func:`ARKStepCreateSUNStepper`.
+
 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