MRI-adaptivity

CHANGELOG.md

@@ -23,6 +23,19 @@ 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 functionality to ARKODE to accumulate a temporal error
+estimate over multiple time steps. See the routines `ARKodeSetAccumulatedErrorType`,
+`ARKodeResetAccumulatedError`, and `ARKodeGetAccumulatedError` for details.
+
+Added utility routine to wrap any valid ARKODE integrator for use as an MRIStep
+inner stepper object, `ARKodeCreateMRIStepInnerStepper`.
+
 ### Bug Fixes
 
 Fixed `ARKodeResize` not using the default `hscale` when an argument of `0` was
@@ -39,11 +52,18 @@ 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 ARKStep-specific utility routine for wrapping as an MRIStep
+inner stepper object, `ARKStepCreateMRIStepInnerStepper`.
+
 ## Changes to SUNDIALS in release 7.1.1
 
 ### Bug Fixes

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). |
  +-----------------------------------------------+------------------------------------------------------------+