Feature: New Low Order Methods (#439)

- Adds new 1st-3rd order MRI methods. Most are from the literature, but
the rest are trivial to derive, e.g., Euler-based schemes.
- Adds some of the base ERK and IRK method tables too. Note that some
cannot be equipped with reasonable embeddings.
- Fixes an MRI reallocation bug when switching coupling coefficients to
one with more stages
- Fixes a workspace size bug for MRIStep
- Makes `MRIStepSetOrder` consistent with `ARKStepSetOrder` and
`ERKStepSetOrder` so that a negative value sets the default order and a
positive value out of range prints an error (when method initialization
occurs not when `SetOrder` is called).

---------

Co-authored-by: Daniel R. Reynolds <reynolds@smu.edu>
Co-authored-by: David Gardner <gardner48@llnl.gov>

CHANGELOG.md

@@ -14,6 +14,24 @@ Added "Resize" capability, as well as missing `SetRootDirection` and
 Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
 for users who wish to retain the current functionality.
 
+Added the following Runge-Kutta Butcher tables
+* `ARKODE_FORWARD_EULER_1_1`
+* `ARKODE_RALSTON_EULER_2_1_2`
+* `ARKODE_EXPLICIT_MIDPOINT_EULER_2_1_2`
+* `ARKODE_BACKWARD_EULER_1_1`
+* `ARKODE_IMPLICIT_MIDPOINT_1_2`
+* `ARKODE_IMPLICIT_TRAPEZOIDAL_2_2`
+
+Added the following MRI coupling tables
+* `ARKODE_MRI_GARK_FORWARD_EULER`
+* `ARKODE_MRI_GARK_RALSTON2`
+* `ARKODE_MRI_GARK_RALSTON3`
+* `ARKODE_MRI_GARK_BACKWARD_EULER`
+* `ARKODE_MRI_GARK_IMPLICIT_MIDPOINT`
+* `ARKODE_IMEX_MRI_GARK_EULER`
+* `ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL`
+* `ARKODE_IMEX_MRI_GARK_MIDPOINT`
+
 Updated the CMake variable `HIP_PLATFORM` default to `amd` as the previous
 default, `hcc`, is no longer recognized in ROCm 5.7.0 or newer. The new default
 is also valid in older version of ROCm (at least back to version 4.3.1).

doc/arkode/guide/source/Butcher.rst

@@ -150,6 +150,37 @@ specified via a unique ID and name:
 with values specified for each method below (e.g., ``ARKODE_HEUN_EULER_2_1_2``).
 
 
+.. _Butcher.Forward_Euler:
+
+Forward-Euler-1-1
+^^^^^^^^^^^^^^^^^
+
+.. index:: Forward-Euler-1-1 ERK method
+
+Accessible via the constant ``ARKODE_FORWARD_EULER_1_1`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_FORWARD_EULER_1_1"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`.
+This is the default 1st order explicit method (from :cite:p:`Euler:68`).
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|c}
+     0 & 0 \\
+     \hline
+     1 & 1
+   \end{array}
+
+.. figure:: /figs/arkode/forward_euler_erk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the forward Euler method.
+
+
 .. _Butcher.Heun_Euler:
 
 Heun-Euler-2-1-2
@@ -184,6 +215,74 @@ This is the default 2nd order explicit method.
    region is outlined in blue; the embedding's region is in red.
 
 
+.. _Butcher.Ralston_Euler:
+
+Ralston-Euler-2-1-2
+^^^^^^^^^^^^^^^^^^^^
+
+.. index:: Ralston-Euler-2-1-2 ERK method
+
+Accessible via the constant ``ARKODE_RALSTON_EULER_2_1_2`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_RALSTON_EULER_2_1_2"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`
+(primary method from :cite:p:`Ralston:62`).
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|cc}
+     0 & 0 & 0 \\
+     \frac{2}{3} & \frac{2}{3} & 0 \\
+     \hline
+     2 & \frac{1}{4} & \frac{3}{4} \\
+     1 & 1 & 0
+   \end{array}
+
+.. figure:: /figs/arkode/ralston_euler_erk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the Ralston-Euler method.  The method's
+   region is outlined in blue; the embedding's region is in red.
+
+
+.. _Butcher.Explicit_Midpoint_Euler:
+
+Explicit-Midpoint-Euler-2-1-2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: Explicit-Midpoint-Euler-2-1-2 ERK method
+
+Accessible via the constant ``ARKODE_EXPLICIT_MIDPOINT_EULER_2_1_2`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_EXPLICIT_MIDPOINT_EULER_2_1_2"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`
+(primary method from :cite:p:`Runge:95`).
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|cc}
+     0 & 0 & 0 \\
+     \frac{1}{2} & \frac{1}{2} & 0 \\
+     \hline
+     2 & 0 & 1 \\
+     1 & 1 & 0
+   \end{array}
+
+.. figure:: /figs/arkode/explicit_midpoint_euler_erk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the Explicit-Midpoint-Euler method.  The method's
+   region is outlined in blue; the embedding's region is in red.
+
+
 .. _Butcher.ARK2_ERK:
 
 ARK2-ERK-3-1-2
@@ -1123,6 +1222,37 @@ specified via a unique ID and name:
 with values specified for each method below (e.g., ``ARKODE_SDIRK_2_1_2``).
 
 
+.. _Butcher.Backward-Euler:
+
+Backward-Euler-1-1
+^^^^^^^^^^^^^^^^^^
+
+.. index:: Backward-Euler-1-1 method
+
+Accessible via the constant ``ARKODE_BACKWARD_EULER_1_1`` to
+:c:func:`ARKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadDIRK`.
+Accessible via the string ``"ARKODE_BACKWARD_EULER_1_1"`` to
+:c:func:`ARKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadDIRKByName`.
+This is the default 1st order implicit method.  The method is A-, L-, and B-stable.
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|c}
+     1 & 1 \\
+     \hline
+     1 & 1
+   \end{array}
+
+.. figure:: /figs/arkode/backward_euler_dirk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the backward Euler method.
+
+
 .. _Butcher.SDIRK-2-1:
 
 SDIRK-2-1-2
@@ -1194,6 +1324,69 @@ implicit portion of the ARK2 method from :cite:p:`giraldo2013implicit`).
    region is outlined in blue; the embedding's region is in red.
 
 
+.. _Butcher.Implicit_Midpoint:
+
+Implicit-Midpoint-1-2
+^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: Implicit-Midpoint-1-2 method
+
+Accessible via the constant ``ARKODE_IMPLICIT_MIDPOINT_1_2`` to
+:c:func:`ARKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadDIRK`.
+Accessible via the string ``"ARKODE_IMPLICIT_MIDPOINT_1_2"`` to
+:c:func:`ARKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadDIRKByName`.
+The method is A- and B-stable.
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|c}
+     \frac{1}{2} & \frac{1}{2} \\
+     \hline
+     2 & 1
+   \end{array}
+
+.. figure:: /figs/arkode/implicit_midpoint_dirk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the implicit midpoint method.
+
+
+.. _Butcher.Implicit_Trapezoidal:
+
+Implicit-Trapezoidal-2-2
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: Implicit-Trapezoidal-2-2 method
+
+Accessible via the constant ``ARKODE_IMPLICIT_TRAPEZOIDAL_2_2`` to
+:c:func:`ARKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadDIRK`.
+Accessible via the string ``"ARKODE_IMPLICIT_TRAPEZOIDAL_2_2"`` to
+:c:func:`ARKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadDIRKByName`.
+The method is A-stable.
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|cc}
+     0 & 0 & 0 \\
+     1 & \frac{1}{2} & \frac{1}{2} \\
+     \hline
+     2 & \frac{1}{2} & \frac{1}{2}
+   \end{array}
+
+.. figure:: /figs/arkode/implicit_trapezoidal_dirk_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the implicit trapezoidal method.
+
+
 .. _Butcher.Billington:
 
 Billington-3-3-2