Feature/oo adaptivity

CHANGELOG.md

@@ -3,6 +3,14 @@
 
 ## Changes to SUNDIALS in release X.X.X
 
+Added `SUNAdaptController` and `SUNTimestepHeuristics` base classes.  Ported
+ARKODE's internal implementations of time step control and heuristic constraints
+into implementations of these classes, and updated ARKODE to use these objects
+instead of its own implementations.  Added `ARKStepSetAdaptController`,
+`ARKStepSetTimestepHeuristics`, `ERKStepSetAdaptController`, and
+`ERKStepSetTimestepHeuristics` routines so that users can modify
+controller/heuristic parameters, or even provide custom implementations.
+
 Fixed a bug in `ARKStepSetTableNum` wherein it did not recognize `ARKODE_ARK2_ERK_3_1_2` and
 `ARKODE_ARK2_DIRK_3_1_2` as a valid additive Runge--Kutta Butcher table pair.
 
@@ -13,6 +21,14 @@ Improved computational complexity of `SUNMatScaleAddI_Sparse` from `O(M*N)` to
 
 Fixed scaling bug in `SUNMatScaleAddI_Sparse` for non-square matrices.
 
+Changed the default fourth order DIRK method to `ARKODE_ARK436L2SA_DIRK_6_3_4`
+for improved accuracy and embedded stability. To revert to the previous default,
+use `ARKStepSetTableNum(arkode_mem, ARKODE_SDIRK_5_3_4, ARKODE_ERK_NONE)`.
+
+Added the ERK method `ARKODE_SOFRONIOU_SPALETTA_5_3_4` which is now the default
+fourth order ERK method. To revert to the previous default, use
+`ERKStepSetTableNum(arkode_mem, ARKODE_ZONNEVELD_5_3_4)`.
+
 Fixed missing soversions in some `SUNLinearSolver` CMake targets.
 
 ## Changes to SUNDIALS in release 6.6.1

cmake/macros/SundialsAddLibrary.cmake

@@ -165,6 +165,14 @@ macro(sundials_add_library target)
     if(SUNDIALS_RT_LIBRARY)
       target_link_libraries(${obj_target} PRIVATE "${SUNDIALS_RT_LIBRARY}")
     endif()
+    if(SUNDIALS_BUILD_WITH_PROFILING)
+      if(ENABLE_CALIPER)
+        target_link_libraries(${obj_target} PUBLIC caliper)
+      endif()
+      if(ENABLE_ADIAK)
+        target_link_libraries(${obj_target} PUBLIC adiak::adiak ${CMAKE_DL_LIBS})
+      endif()
+    endif()
     if(sundials_add_library_LINK_LIBRARIES)
       if(${_libtype} MATCHES "STATIC")
         append_static_suffix(sundials_add_library_LINK_LIBRARIES _all_libs)

doc/arkode/guide/source/Butcher.rst

@@ -331,6 +331,43 @@ This is the default 3th order slow and fast MRIStep method (from
    Linear stability region for the Knoth-Wolke method
 
 
+.. _Butcher.Sofroniou_Spaletta:
+
+Sofroniou-Spaletta-5-3-4
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: Sofroniou-Spaletta-5-3-4 ERK method
+
+Accessible via the constant ``ARKODE_SOFRONIOU_SPALETTA_5_3_4`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum`
+or :c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_SOFRONIOU_SPALETTA_5_3_4"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`.
+This is the default 4th order explicit method
+(from :cite:p:`SoSp:04`).
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+     0 & 0 & 0 & 0 & 0 & 0 \\
+     \frac{2}{5} & \frac{2}{5} & 0 & 0 & 0 & 0 \\
+     \frac{3}{5} & -\frac{3}{20} & \frac{3}{4} & 0 & 0 & 0 \\
+     1 & \frac{19}{44} & -\frac{15}{44} & \frac{10}{11} & 0 & 0 \\
+     1 & \frac{11}{72} & \frac{25}{72} & \frac{25}{72} & \frac{11}{72} & 0 \\
+     4 & \frac{11}{72} & \frac{25}{72} & \frac{25}{72} & \frac{11}{72} & 0 \\
+     3 & \frac{1251515}{8970912} & \frac{3710105}{8970912} & \frac{2519695}{8970912} & \frac{61105}{8970912} & \frac{119041}{747576} \\
+   \end{array}
+
+.. figure:: /figs/arkode/sofroniou_spaletta_erk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the Sofroniou-Spaletta method.  The method's
+   region is outlined in blue; the embedding's region is in red.
+
+
+
 
 .. _Butcher.Zonneveld:
 
@@ -345,7 +382,6 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_ZONNEVELD_5_3_4"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 4th order explicit method
 (from :cite:p:`Zon:63`).
 
 .. math::

doc/arkode/guide/source/Constants.rst

@@ -80,6 +80,8 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_ARK324L2SA_ERK_4_2_3`          | Use the ARK-4-2-3 ERK method.                              |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_SOFRONIOU_SPALETTA_5_3_4`      | Use the Sofroniou-Spaletta-5-3-4 ERK method.               |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_ZONNEVELD_5_3_4`               | Use the Zonneveld-5-3-4 ERK method.                        |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_ARK436L2SA_ERK_6_3_4`          | Use the ARK-6-3-4 ERK method.                              |
@@ -111,7 +113,7 @@ contains the ARKODE output constants.
    |                                               | (ARKODE_BOGACKI_SHAMPINE_4_2_3).                           |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKSTEP_DEFAULT_ERK_4`                | Use ARKStep's default fourth-order ERK method              |
-   |                                               | (ARKODE_ZONNEVELD_5_3_4).                                  |
+   |                                               | (ARKODE_SOFRONIOU_SPALETTA_5_3_4).                         |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKSTEP_DEFAULT_ERK_5`                | Use ARKStep's default fifth-order ERK method               |
    |                                               | (ARKODE_CASH_KARP_6_4_5).                                  |
@@ -129,7 +131,7 @@ contains the ARKODE output constants.
    |                                               | (ARKODE_BOGACKI_SHAMPINE_4_2_3).                           |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ERKSTEP_DEFAULT_4`                    | Use ERKStep's default fourth-order ERK method              |
-   |                                               | (ARKODE_ZONNEVELD_5_3_4).                                  |
+   |                                               | (ARKODE_SOFRONIOU_SPALETTA_5_3_4).                         |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ERKSTEP_DEFAULT_5`                    | Use ERKStep's default fifth-order ERK method               |
    |                                               | (ARKODE_CASH_KARP_6_4_5).                                  |
@@ -433,7 +435,7 @@ contains the ARKODE output constants.
    +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_INVALID_TABLE`          | -41  | An invalid Butcher or MRI table was encountered.           |
    +-------------------------------------+------+------------------------------------------------------------+
-   | :index:`ARK_CONTEXT_ERR`            | -42  | An error occurred with the SUNDIALS context object         |
+   | :index:`ARK_CONTEXT_ERR`            | -42  | An error with the SUNContext object was encountered.       |
    +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_RELAX_FAIL`             | -43  | An error occurred in computing the relaxation parameter    |
    +-------------------------------------+------+------------------------------------------------------------+
@@ -444,6 +446,11 @@ 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_HEURISTICS_ERR`         | -48  | An error with the SUNTimestepHeuristics object was         |
+   |                                     |      | encountered.                                               |
+   +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_UNRECOGNIZED_ERROR`     | -99  | An unknown error was encountered.                          |
    +-------------------------------------+------+------------------------------------------------------------+
    |                                                                                                         |

doc/arkode/guide/source/Introduction.rst

@@ -133,6 +133,15 @@ Changes from previous versions
 Changes in vX.X.X
 -----------------
 
+Added :c:type:`SUNAdaptController` and :c:type:`SUNTimestepHeuristics` base classes.
+Ported ARKODE's internal implementations of time step control and heuristic
+constraints into implementations of these classes, and updated ARKODE to use
+these objects instead of its own implementations.  Added
+:c:func:`ARKStepSetAdaptController`,  :c:func:`ARKStepSetTimestepHeuristics`,
+:c:func:`ERKStepSetAdaptController`, and :c:func:`ERKStepSetTimestepHeuristics`
+routines so that users can modify controller/heuristic parameters, or even provide
+custom implementations.
+
 Fixed a bug in :c:func:`ARKStepSetTableNum` wherein it did not recognize
 `ARKODE_ARK2_ERK_3_1_2` and `ARKODE_ARK2_DIRK_3_1_2` as a valid additive
 Runge--Kutta Butcher table pair.
@@ -144,6 +153,14 @@ Fixed scaling bug in ``SUNMatScaleAddI_Sparse`` for non-square matrices.
 
 Fixed missing soversions in some ``SUNLinearSolver`` CMake targets.
 
+Changed the default fourth order DIRK method to `ARKODE_ARK436L2SA_DIRK_6_3_4`
+for improved accuracy and embedded stability. To revert to the previous default,
+use `ARKStepSetTableNum(arkode_mem, ARKODE_SDIRK_5_3_4, ARKODE_ERK_NONE)`.
+
+Added the ERK method `ARKODE_SOFRONIOU_SPALETTA_5_3_4` which is now the default
+fourth order ERK method. To revert to the previous default, use
+`ERKStepSetTableNum(arkode_mem, ARKODE_ZONNEVELD_5_3_4)`.
+
 Changes in v5.6.1
 -----------------