MRI-adaptivity

CHANGELOG.md

@@ -31,6 +31,21 @@ The build system has been updated to utilize the CMake LAPACK imported target
 which should ease building SUNDIALS with LAPACK libraries that require setting
 specific linker flags e.g., MKL.
 
+Added support for multirate time step adaptivity controllers, based on the
+recently introduced `SUNAdaptController` base class, to ARKODE's MRIStep module.
+As a part of this, we added embeddings for existing MRI-GARK methods, as well as
+support for embedded MERK and IMEX-MRI-SR methods.  Added new default MRI methods
+for temporally adaptive versus fixed-step runs.  Added the function
+`MRIStepGetNumInnerStepperFails` to retrieve the number of recoverable
+failures reported by the MRIStepInnerStepper.
+
+Added functionality to ARKODE to accumulate a temporal error
+estimate over multiple time steps.  See the routines `ARKodeSetAccumulatedErrorType`,
+`ARKodeResetAccumulatedError`, and `ARKodeGetAccumulatedError` for details.
+
+Added a utility routine to wrap any valid ARKODE integrator for use as an MRIStep
+inner stepper object, `ARKodeCreateMRIStepInnerStepper`.
+
 ### Bug Fixes
 
 Fixed a [bug](https://github.com/LLNL/sundials/issues/581) in the sparse matrix
@@ -51,11 +66,19 @@ repeatedly.
 Fixed compilation errors when building the Trilinos Teptra NVector with CUDA
 support.
 
+Fixed loading the default IMEX-MRI method if `ARKodeSetOrder` is used to specify
+a third or fourth order method. Previously, the default second order method
+was loaded in both cases.
+
 Fixed a CMake configuration issue related to aliasing an `ALIAS` target when
 using `ENABLE_KLU=ON` in combination with a static-only build of SuiteSparse.
 
 ### Deprecation Notices
 
+Deprecated the ARKStep-specific utility routine for wrapping an ARKStep instance
+as an MRIStep inner stepper object, `ARKStepCreateMRIStepInnerStepper`. Use
+`ARKodeCreateMRIStepInnerStepper` instead.
+
 The ARKODE stepper specific functions to retrieve the number of right-hand side
 function evaluations have been deprecated. Use `ARKodeGetNumRhsEvals` instead.
 

doc/arkode/guide/source/Constants.rst

@@ -64,7 +64,7 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    |                                               |                                                            |
    +-----------------------------------------------+------------------------------------------------------------+
-   | **Relaxtion module input constants**          |                                                            |
+   | **Relaxation module input constants**         |                                                            |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARK_RELAX_BRENT`                      | Specifies Brent's method as the relaxation nonlinear       |
    |                                               | solver.                                                    |
@@ -331,20 +331,28 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_FORWARD_EULER`        | Use the forward Euler MRI-GARK method.                     |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`ARKODE_MRI_GARK_ERK22b`               | Use the ERK22b MRI-GARK method.                            |
-   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_ERK22a`               | Use the ERK22a MRI-GARK method.                            |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MRI_GARK_ERK22b`               | Use the ERK22b MRI-GARK method.                            |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_RALSTON2`             | Use the second order Ralston MRI-GARK method.              |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`ARKODE_MIS_MW3`                       | Use the Knoth-Wolke-3 MIS method.                          |
+   | :index:`ARKODE_MIS_KW3`                       | Use the Knoth-Wolke-3 MIS method (non-embedded).           |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_ERK33a`               | Use the ERK33a MRI-GARK method.                            |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_RALSTON3`             | Use the third order Ralston MRI-GARK method.               |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_ERK45a`               | Use the ERK45a MRI-GARK method.                            |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MERK21`                        | Use the MERK21 method.                                     |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MERK32`                        | Use the MERK32 method.                                     |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MERK43`                        | Use the MERK43 method.                                     |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MERK54`                        | Use the MERK54 method.                                     |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_BACKWARD_EULER`       | Use the backward Euler MRI-GARK method.                    |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_IRK21a`               | Use the IRK21a MRI-GARK method.                            |
@@ -361,47 +369,74 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_IMEX_MRI_GARK_MIDPOINT`        | Use the midpoint rule IMEX-MRI-GARK method.                |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`ARKODE_IMEX_MRI_GARK3a`               | Use the IMEX-MRI-GARK3a method.                            |
+   | :index:`ARKODE_IMEX_MRI_GARK3a`               | Use the IMEX-MRI-GARK3a method (non-embedded).             |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_IMEX_MRI_GARK3b`               | Use the IMEX-MRI-GARK3b method (non-embedded).             |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`ARKODE_IMEX_MRI_GARK3b`               | Use the IMEX-MRI-GARK3b method.                            |
+   | :index:`ARKODE_IMEX_MRI_GARK4`                | Use the IMEX-MRI-GARK4 method (non-embedded).              |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`ARKODE_IMEX_MRI_GARK4`                | Use the IMEX-MRI-GARK4 method.                             |
+   | :index:`ARKODE_IMEX_MRI_SR21`                 | Use the IMEX-MRI-SR21 method.                              |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_1`         | Use MRIStep's default 1st-order explicit method            |
-   |                                               | (MRI_GARK_FORWARD_EULER).                                  |
+   | :index:`ARKODE_IMEX_MRI_SR32`                 | Use the IMEX-MRI-SR32 method.                              |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_2`         | Use MRIStep's default 2nd-order explicit method            |
-   |                                               | (MRI_GARK_ERK22b).                                         |
+   | :index:`ARKODE_IMEX_MRI_SR43`                 | Use the IMEX-MRI-SR43 method.                              |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_3`         | Use MRIStep's default 3rd-order explicit method            |
-   |                                               | (MIS_MW3).                                                 |
+   | :index:`MRISTEP_DEFAULT_EXPL_1`               | Use MRIStep's default 1st-order explicit method            |
+   |                                               | (ARKODE_MRI_GARK_FORWARD_EULER).                           |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_4`         | Use MRIStep's default 4th-order explicit method            |
-   |                                               | (MRI_GARK_ERK45a).                                         |
+   | :index:`MRISTEP_DEFAULT_EXPL_2`               | Use MRIStep's default 2nd-order explicit method            |
+   |                                               | (ARKODE_MRI_GARK_ERK22b).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_1`      | Use MRIStep's default 1st-order solve-decoupled implicit   |
-   |                                               | method (MRI_GARK_BACKWARD_EULER).                          |
+   | :index:`MRISTEP_DEFAULT_EXPL_3`               | Use MRIStep's default 3rd-order explicit method            |
+   |                                               | (ARKODE_MIS_KW3).                                          |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_2`      | Use MRIStep's default 2nd-order solve-decoupled implicit   |
-   |                                               | method (MRI_GARK_IRK21a).                                  |
+   | :index:`MRISTEP_DEFAULT_EXPL_4`               | Use MRIStep's default 4th-order explicit method            |
+   |                                               | (ARKODE_MRI_GARK_ERK45a).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_3`      | Use MRIStep's default 3rd-order solve-decoupled implicit   |
-   |                                               | method (MRI_GARK_ESDIRK34a).                               |
+   | :index:`MRISTEP_DEFAULT_EXPL_2_AD`            | Use MRIStep's default 2nd-order adaptive explicit method   |
+   |                                               | (ARKODE_MRI_GARK_ERK22a).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_4`      | Use MRIStep's default 4th-order solve-decoupled implicit   |
-   |                                               | method (MRI_GARK_ESDIRK46a).                               |
+   | :index:`MRISTEP_DEFAULT_EXPL_3_AD`            | Use MRIStep's default 3rd-order adaptive explicit method   |
+   |                                               | (ARKODE_MRI_GARK_ERK33a).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_1`      | Use MRIStep's default 1st-order solve-decoupled ImEx       |
-   |                                               | method (IMEX_MRI_GARK_EULER).                              |
+   | :index:`MRISTEP_DEFAULT_EXPL_4_AD`            | Use MRIStep's default 4th-order adaptive explicit method   |
+   |                                               | (ARKODE_MRI_GARK_ERK45a).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_2`      | Use MRIStep's default 2nd-order solve-decoupled ImEx       |
+   | :index:`MRISTEP_DEFAULT_EXPL_5_AD`            | Use MRIStep's default 5th-order adaptive explicit method   |
+   |                                               | (ARKODE_MERK54).                                           |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMPL_SD_1`            | Use MRIStep's default 1st-order solve-decoupled implicit   |
+   |                                               | method (ARKODE_MRI_GARK_BACKWARD_EULER).                   |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMPL_SD_2`            | Use MRIStep's default 2nd-order solve-decoupled implicit   |
+   |                                               | method (ARKODE_MRI_GARK_IRK21a).                           |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMPL_SD_3`            | Use MRIStep's default 3rd-order solve-decoupled implicit   |
+   |                                               | method (ARKODE_MRI_GARK_ESDIRK34a).                        |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMPL_SD_4`            | Use MRIStep's default 4th-order solve-decoupled implicit   |
+   |                                               | method (ARKODE_MRI_GARK_ESDIRK46a).                        |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_1`            | Use MRIStep's default 1st-order solve-decoupled ImEx       |
+   |                                               | method (ARKODE_IMEX_MRI_GARK_EULER).                       |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_2`            | Use MRIStep's default 2nd-order solve-decoupled ImEx       |
    |                                               | method (ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL).                 |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_3`      | Use MRIStep's default 3rd-order solve-decoupled ImEx       |
-   |                                               | method (IMEX_MRI_GARK3b).                                  |
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_3`            | Use MRIStep's default 3rd-order solve-decoupled ImEx       |
+   |                                               | method (ARKODE_IMEX_MRI_GARK3b).                           |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_4`            | Use MRIStep's default 4th-order solve-decoupled ImEx       |
+   |                                               | method (ARKODE_IMEX_MRI_GARK4).                            |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_2_AD`         | Use MRIStep's default 2nd-order solve-decoupled adaptive   |
+   |                                               | ImEx method (ARKODE_IMEX_MRI_SR21).                        |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_3_AD`         | Use MRIStep's default 3rd-order solve-decoupled adaptive   |
+   |                                               | ImEx method (ARKODE_IMEX_MRI_SR32).                        |
    +-----------------------------------------------+------------------------------------------------------------+
-   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_4`      | Use MRIStep's default 4th-order solve-decoupled ImEx       |
-   |                                               | method (IMEX_MRI_GARK4).                                   |
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_4_AD`         | Use MRIStep's default 4th-order solve-decoupled adaptive   |
+   |                                               | ImEx method (ARKODE_IMEX_MRI_SR43).                        |
    +-----------------------------------------------+------------------------------------------------------------+