Propagated SUNAdaptController class and usage from feature/oo-adaptiv…

…ity branch

CHANGELOG.md

@@ -3,6 +3,13 @@
 
 ## Changes to SUNDIALS in release X.X.X
 
+Added the `SUNAdaptController` base class, ported ARKODE's internal 
+implementations of time step controllers into implementations of this class, 
+and updated ARKODE to use these objects instead of its own implementations.  
+Added `ARKStepSetAdaptController` and `ERKStepSetAdaptController` routines 
+so that users can modify controller parameters, or even provide custom 
+implementations.
+
 Fixed a regression introduced by the stop time bug fix in v6.6.1 where ARKODE,
 CVODE, CVODES, IDA, and IDAS would return at the stop time rather than the
 requested output time if the stop time was reached in the same step in which the

doc/arkode/guide/source/Constants.rst

@@ -444,6 +444,8 @@ contains the ARKODE output constants.
    | :index:`ARK_RELAX_JAC_FAIL`         | -46  | The relaxation Jacobian function returned an unrecoverable |
    |                                     |      | error                                                      |
    +-------------------------------------+------+------------------------------------------------------------+
+   | :index:`ARK_CONTROLLER_ERR`         | -47  | An error with a SUNAdaptController object was encountered. |
+   +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_UNRECOGNIZED_ERROR`     | -99  | An unknown error was encountered.                          |
    +-------------------------------------+------+------------------------------------------------------------+
    |                                                                                                         |

doc/arkode/guide/source/Introduction.rst

@@ -133,6 +133,13 @@ Changes from previous versions
 Changes in vX.X.X
 -----------------
 
+Added the :c:type:`SUNAdaptController` base class, ported ARKODE's internal 
+implementations of time step controllers into implementations of this class, 
+and updated ARKODE to use these objects instead of its own implementations.  Added
+:c:func:`ARKStepSetAdaptController` and :c:func:`ERKStepSetAdaptController`
+routines so that users can modify controller parameters, or even provide custom 
+implementations.
+
 Fixed a regression introduced by the stop time bug fix in v6.6.1 where ARKODE
 steppers would return at the stop time rather than the requested output time if
 the stop time was reached in the same step in which the output time was passed.

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

@@ -1691,26 +1691,43 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
 
 .. cssclass:: table-bordered
 
-========================================================   ======================================  ========
-Optional input                                             Function name                           Default
-========================================================   ======================================  ========
-Set a custom time step adaptivity function                 :c:func:`ARKStepSetAdaptivityFn()`      internal
-Choose an existing time step adaptivity method             :c:func:`ARKStepSetAdaptivityMethod()`  0
-Explicit stability safety factor                           :c:func:`ARKStepSetCFLFraction()`       0.5
-Time step error bias factor                                :c:func:`ARKStepSetErrorBias()`         1.5
-Bounds determining no change in step size                  :c:func:`ARKStepSetFixedStepBounds()`   1.0  1.5
-Maximum step growth factor on convergence fail             :c:func:`ARKStepSetMaxCFailGrowth()`    0.25
-Maximum step growth factor on error test fail              :c:func:`ARKStepSetMaxEFailGrowth()`    0.3
-Maximum first step growth factor                           :c:func:`ARKStepSetMaxFirstGrowth()`    10000.0
-Maximum allowed general step growth factor                 :c:func:`ARKStepSetMaxGrowth()`         20.0
-Minimum allowed step reduction factor on error test fail   :c:func:`ARKStepSetMinReduction()`      0.1
-Time step safety factor                                    :c:func:`ARKStepSetSafetyFactor()`      0.96
-Error fails before MaxEFailGrowth takes effect             :c:func:`ARKStepSetSmallNumEFails()`    2
-Explicit stability function                                :c:func:`ARKStepSetStabilityFn()`       none
-========================================================   ======================================  ========
+=========================================================   ======================================  ========
+Optional input                                              Function name                           Default
+=========================================================   ======================================  ========
+Provide a :c:type:`SUNAdaptController` for ARKStep to use   :c:func:`ARKStepSetAdaptController()`   PID
+Set a custom time step adaptivity function                  :c:func:`ARKStepSetAdaptivityFn()`      internal
+Choose an existing time step adaptivity method              :c:func:`ARKStepSetAdaptivityMethod()`  0
+Explicit stability safety factor                            :c:func:`ARKStepSetCFLFraction()`       0.5
+Time step error bias factor                                 :c:func:`ARKStepSetErrorBias()`         1.5
+Bounds determining no change in step size                   :c:func:`ARKStepSetFixedStepBounds()`   1.0  1.5
+Maximum step growth factor on convergence fail              :c:func:`ARKStepSetMaxCFailGrowth()`    0.25
+Maximum step growth factor on error test fail               :c:func:`ARKStepSetMaxEFailGrowth()`    0.3
+Maximum first step growth factor                            :c:func:`ARKStepSetMaxFirstGrowth()`    10000.0
+Maximum allowed general step growth factor                  :c:func:`ARKStepSetMaxGrowth()`         20.0
+Minimum allowed step reduction factor on error test fail    :c:func:`ARKStepSetMinReduction()`      0.1
+Time step safety factor                                     :c:func:`ARKStepSetSafetyFactor()`      0.96
+Error fails before MaxEFailGrowth takes effect              :c:func:`ARKStepSetSmallNumEFails()`    2
+Explicit stability function                                 :c:func:`ARKStepSetStabilityFn()`       none
+=========================================================   ======================================  ========
 
 
 
+.. c:function:: int ARKStepSetAdaptController(void* arkode_mem, SUNAdaptController C)
+
+   Sets a user-supplied time-step controller object.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the ARKStep memory block.
+      * *C* -- user-supplied time adaptivity controller.  If ``NULL`` then the PID controller will be created (see :numref:`SUNAdaptController.PID`).
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
+      * *ARK_MEM_FAIL* if *C* was ``NULL`` and the PID controller could not be allocated.
+
+   .. versionadded:: x.x.x
+
+
 .. c:function:: int ARKStepSetAdaptivityFn(void* arkode_mem, ARKAdaptFn hfun, void* h_data)
 
    Sets a user-supplied time-step adaptivity function.
@@ -1732,6 +1749,11 @@ Explicit stability function                                :c:func:`ARKStepSetSt
       :c:func:`ARKStepSetStabilityFn()` should be used instead.
 
 
+   .. deprecated:: x.x.x
+
+      Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
+
+
 
 .. c:function:: int ARKStepSetAdaptivityMethod(void* arkode_mem, int imethod, int idefault, int pq, realtype* adapt_params)
 
@@ -1765,6 +1787,11 @@ Explicit stability function                                :c:func:`ARKStepSetSt
       a custom function through a call to :c:func:`ARKStepSetAdaptivityFn()`.
 
 
+   .. deprecated:: x.x.x
+
+      Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
+
+
 
 .. c:function:: int ARKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac)
 
@@ -1803,6 +1830,10 @@ Explicit stability function                                :c:func:`ARKStepSetSt
    **Notes:**
       Any value below 1.0 will imply a reset to the default value.
 
+      If both this and one of :c:func:`ARKStepSetAdaptivityMethod` or
+      :c:func:`ARKStepSetAdaptController` will be called, then this routine must be called
+      *second*.
+
 
 
 .. c:function:: int ARKStepSetFixedStepBounds(void* arkode_mem, realtype lb, realtype ub)

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

@@ -1162,6 +1162,8 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
    +-----------------------------------------------------------+----------------------------------------+-----------+
    | Optional input                                            | Function name                          | Default   |
    +-----------------------------------------------------------+----------------------------------------+-----------+
+   | Provide a :c:type:`SUNAdaptController` for ERKStep to use | :c:func:`ERKStepSetAdaptController()`  | PI        |
+   +-----------------------------------------------------------+----------------------------------------+-----------+
    | Set a custom time step adaptivity function                | :c:func:`ERKStepSetAdaptivityFn()`     | internal  |
    +-----------------------------------------------------------+----------------------------------------+-----------+
    | Choose an existing time step adaptivity method            | :c:func:`ERKStepSetAdaptivityMethod()` | 0         |
@@ -1189,6 +1191,22 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
 
 
 
+.. c:function:: int ERKStepSetAdaptController(void* arkode_mem, SUNAdaptController C)
+
+   Sets a user-supplied time-step controller object.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the ERKStep memory block.
+      * *C* -- user-supplied time adaptivity controller.  If ``NULL`` then the PID controller will be created (see :numref:`SUNAdaptController.PID`).
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_MEM_NULL* if the ERKStep memory is ``NULL``
+      * *ARK_MEM_FAIL* if *C* was ``NULL`` and the PID controller could not be allocated.
+
+   .. versionadded:: x.x.x
+
+
 .. c:function:: int ERKStepSetAdaptivityFn(void* arkode_mem, ARKAdaptFn hfun, void* h_data)
 
    Sets a user-supplied time-step adaptivity function.
@@ -1210,6 +1228,10 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
       :c:func:`ERKStepSetStabilityFn()` should be used instead.
 
 
+   .. deprecated:: x.x.x
+
+      Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
+
 
 .. c:function:: int ERKStepSetAdaptivityMethod(void* arkode_mem, int imethod, int idefault, int pq, realtype* adapt_params)
 
@@ -1243,6 +1265,10 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
       a custom function through a call to :c:func:`ERKStepSetAdaptivityFn()`.
 
 
+   .. deprecated:: x.x.x
+
+      Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
+
 
 .. c:function:: int ERKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac)
 
@@ -1281,6 +1307,10 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
    **Notes:**
       Any value below 1.0 will imply a reset to the default value.
 
+      If both this and one of :c:func:`ERKStepSetAdaptivityMethod` or
+      :c:func:`ERKStepSetAdaptController` will be called, then this routine must be called
+      *second*.
+
 
 
 .. c:function:: int ERKStepSetFixedStepBounds(void* arkode_mem, realtype lb, realtype ub)

doc/arkode/guide/source/index.rst

@@ -28,7 +28,7 @@ to have a similar user experience to the `CVODE
 solver, including user modes to allow adaptive integration to specified
 output times, return after each internal step and root-finding
 capabilities, and for calculations in serial, using shared-memory
-parallelism (via OpenMP, Pthreads, CUDA, Raja) or distributed-memory
+parallelism (e.g., via OpenMP, CUDA, Raja, Kokkos) or distributed-memory
 parallelism (via MPI).  The default integration and solver options
 should apply to most users, though control over nearly all internal
 parameters and time adaptivity algorithms is enabled through optional
@@ -64,6 +64,7 @@ with support by the `US Department of Energy <http://www.doe.gov>`_,
    sunmatrix/index.rst
    sunlinsol/index.rst
    sunnonlinsol/index.rst
+   sunadaptcontroller/index.rst
    sunmemory/index.rst
    Install_link.rst
    Constants

doc/arkode/guide/source/sunadaptcontroller/SUNAdaptController_links.rst

@@ -0,0 +1,19 @@
+.. ----------------------------------------------------------------
+   SUNDIALS Copyright Start
+   Copyright (c) 2002-2023, 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/sunadaptcontroller/SUNAdaptController_Description.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_PID.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_PI.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_I.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_ExpGus.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_ImpGus.rst
+.. include:: ../../../../shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst

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

@@ -0,0 +1,29 @@
+.. ----------------------------------------------------------------
+   SUNDIALS Copyright Start
+   Copyright (c) 2002-2023, 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
+   ----------------------------------------------------------------
+
+.. _SUNAdaptController:
+
+#####################################
+Time Step Adaptivity Controllers
+#####################################
+
+The SUNDIALS library comes packaged with a variety of :c:type:`SUNAdaptController`
+implementations, designed to support various forms of error-based time step
+adaptivity within SUNDIALS time integrators.  To support applications that may
+want to adjust or disable these heuristic controls, SUNDIALS provides a
+:c:type:`SUNAdaptController` base class, along with a variety of default
+implementations.
+
+.. toctree::
+   :maxdepth: 1
+
+   SUNAdaptController_links.rst