Skip to content

Commit

Permalink
Feature: Add adaptive MRI-GARK, MRI-SR, and MERK methods (#564)
Browse files Browse the repository at this point in the history 
Add slow time scale adaptivity to MRI-GARK methods
Add adaptive MRI-SR and MERK methods

---------

Co-authored-by: David J. Gardner <[email protected]>
Co-authored-by: Steven Roberts <[email protected]>
  • Loading branch information
@drreynolds @gardner48 @Steven-Roberts
3 people authored Dec 4, 2024
1 parent 122f709 commit a5850b9
Show file tree
Hide file tree
Showing 168 changed files with 24,685 additions and 4,211 deletions.
28 changes: 28 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,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
Expand All @@ -62,6 +77,15 @@ 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 bug in MRIStep where the data supplied to the Hermite interpolation module did
not include contributions from the fast right-hand side function. With this fix, users
will see one additional fast right-hand side function evaluation per slow step with the
Hermite interpolation option.

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.

Expand All @@ -71,6 +95,10 @@ See details in GitHub Issue [#538](https://github.com/LLNL/sundials/issues/538).

### 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.

Expand Down
95 changes: 65 additions & 30 deletions doc/arkode/guide/source/Constants.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -350,20 +350,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. |
Expand All @@ -380,47 +388,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). |
+-----------------------------------------------+------------------------------------------------------------+


Expand Down
Loading

0 comments on commit a5850b9

Please sign in to comment.