New Low Order MRI Methods

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
+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

doc/arkode/guide/source/Constants.rst

@@ -299,30 +299,59 @@ contains the ARKODE output constants.
    +-----------------------------------------------+------------------------------------------------------------+
    | **MRI coupling table specification**          |                                                            |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :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_RALSTON2`             | Use the second order Ralston MRI-GARK method.              |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MIS_MW3`                       | Use the Knoth-Wolke-3 MIS method.                          |
    +-----------------------------------------------+------------------------------------------------------------+
    | :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_MRI_GARK_BACKWARD_EULER`       | Use the backward Euler MRI-GARK method.                    |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_IRK21a`               | Use the IRK21a MRI-GARK method.                            |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_MRI_GARK_IMPLICIT_MIDPOINT`    | Use the implicit midpoint MRI-GARK method.                 |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_ESDIRK34a`            | Use the ESDIRK34a MRI-GARK method.                         |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_MRI_GARK_ESDIRK46a`            | Use the ESDIRK46a MRI-GARK method.                         |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_IMEX_MRI_GARK_EULER`           | Use the Euler IMEX-MRI-GARK method.                        |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL`     | Use the trapezoidal rule IMEX-MRI-GARK method.             |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :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_GARK3b`               | Use the IMEX-MRI-GARK3b method.                            |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`ARKODE_IMEX_MRI_GARK4`                | Use the IMEX-MRI-GARK4 method.                             |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_1`         | Use MRIStep's default 1st-order explicit method            |
+   |                                               | (MRI_GARK_FORWARD_EULER).                                  |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_EXPL_TABLE_2`         | Use MRIStep's default 2nd-order explicit method            |
+   |                                               | (MRI_GARK_ERK22b).                                         |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`MRISTEP_DEFAULT_EXPL_TABLE_3`         | Use MRIStep's default 3rd-order explicit method            |
    |                                               | (MIS_MW3).                                                 |
    +-----------------------------------------------+------------------------------------------------------------+
    | :index:`MRISTEP_DEFAULT_EXPL_TABLE_4`         | Use MRIStep's default 4th-order explicit method            |
    |                                               | (MRI_GARK_ERK45a).                                         |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_1`      | Use MRIStep's default 1st-order solve-decoupled implicit   |
+   |                                               | method (MRI_GARK_BACKWARD_EULER).                          |
+   +-----------------------------------------------+------------------------------------------------------------+
    | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_2`      | Use MRIStep's default 2nd-order solve-decoupled implicit   |
    |                                               | method (MRI_GARK_IRK21a).                                  |
    +-----------------------------------------------+------------------------------------------------------------+
@@ -332,6 +361,12 @@ contains the ARKODE output constants.
    | :index:`MRISTEP_DEFAULT_IMPL_SD_TABLE_4`      | Use MRIStep's default 4th-order solve-decoupled implicit   |
    |                                               | method (MRI_GARK_ESDIRK46a).                               |
    +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_1`      | Use MRIStep's default 1st-order solve-decoupled ImEx       |
+   |                                               | method (IMEX_MRI_GARK_EULER).                              |
+   +-----------------------------------------------+------------------------------------------------------------+
+   | :index:`MRISTEP_DEFAULT_IMEX_SD_TABLE_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).                                  |
    +-----------------------------------------------+------------------------------------------------------------+

doc/arkode/guide/source/Usage/MRIStep_c_interface/MRIStepCoupling.rst

@@ -304,36 +304,46 @@ with values specified for each method below (e.g., ``ARKODE_MIS_KW3``).
 .. table:: Explicit MRI-GARK coupling tables. The default method for each order
            is marked with an asterisk (:math:`^*`).
 
-   ==========================  ===========  =====================
-   Table name                  Order        Reference
-   ==========================  ===========  =====================
-   ``ARKODE_MIS_KW3``          :math:`3^*`  :cite:p:`Schlegel:09`
-   ``ARKODE_MRI_GARK_ERK33a``  3            :cite:p:`Sandu:19`
-   ``ARKODE_MRI_GARK_ERK45a``  :math:`4^*`  :cite:p:`Sandu:19`
-   ==========================  ===========  =====================
+   =================================  ===========  =====================
+   Table name                         Order        Reference
+   =================================  ===========  =====================
+   ``ARKODE_MRI_GARK_FORWARD_EULER``  :math:`1^*`
+   ``ARKODE_MRI_GARK_ERK22b``         :math:`2^*`  :cite:p:`Sandu:19`
+   ``ARKODE_MRI_GARK_ERK22a``         2            :cite:p:`Sandu:19`
+   ``ARKODE_MRI_GARK_RALSTON2``       2            :cite:p:`Roberts:22`
+   ``ARKODE_MIS_KW3``                 :math:`3^*`  :cite:p:`Schlegel:09`
+   ``ARKODE_MRI_GARK_ERK33a``         3            :cite:p:`Sandu:19`
+   ``ARKODE_MRI_GARK_RALSTON3``       3            :cite:p:`Roberts:22`
+   ``ARKODE_MRI_GARK_ERK45a``         :math:`4^*`  :cite:p:`Sandu:19`
+   =================================  ===========  =====================
 
 
 .. table:: Diagonally-implicit, solve-decoupled MRI-GARK coupling tables. The
            default method for each order is marked with an asterisk
            (:math:`^*`).
 
-   =============================  ===========  ===============  ==================
-   Table name                     Order        Implicit Solves  Reference
-   =============================  ===========  ===============  ==================
-   ``ARKODE_MRI_GARK_IRK21a``     :math:`2^*`  1                :cite:p:`Sandu:19`
-   ``ARKODE_MRI_GARK_ESDIRK34a``  :math:`3^*`  3                :cite:p:`Sandu:19`
-   ``ARKODE_MRI_GARK_ESDIRK46a``  :math:`4^*`  5                :cite:p:`Sandu:19`
-   =============================  ===========  ===============  ==================
+   =====================================  ===========  ===============  ==================
+   Table name                             Order        Implicit Solves  Reference
+   =====================================  ===========  ===============  ==================
+   ``ARKODE_MRI_GARK_BACKWARD_EULER``     :math:`1^*`  1
+   ``ARKODE_MRI_GARK_IRK21a``             :math:`2^*`  1                :cite:p:`Sandu:19`
+   ``ARKODE_MRI_GARK_IMPLICIT_MIDPOINT``  2            2
+   ``ARKODE_MRI_GARK_ESDIRK34a``          :math:`3^*`  3                :cite:p:`Sandu:19`
+   ``ARKODE_MRI_GARK_ESDIRK46a``          :math:`4^*`  5                :cite:p:`Sandu:19`
+   =====================================  ===========  ===============  ==================
 
 
 .. table:: Diagonally-implicit, solve-decoupled IMEX-MRI-GARK coupling tables.
            The default method for each order is marked with an asterisk
            (:math:`^*`).
 
-   ===========================  ===========  ===============  ===================
-   Table name                   Order        Implicit Solves  Reference
-   ===========================  ===========  ===============  ===================
-   ``ARKODE_IMEX_MRI_GARK3a``   :math:`3^*`  2                :cite:p:`ChiRen:21`
-   ``ARKODE_IMEX_MRI_GARK3b``   3            2                :cite:p:`ChiRen:21`
-   ``ARKODE_IMEX_MRI_GARK4``    :math:`4^*`  5                :cite:p:`ChiRen:21`
-   ===========================  ===========  ===============  ===================
+   ====================================  ===========  ===============  ===================
+   Table name                            Order        Implicit Solves  Reference
+   ====================================  ===========  ===============  ===================
+   ``ARKODE_IMEX_MRI_GARK_EULER``        :math:`1^*`  1
+   ``ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL``  :math:`2^*`  1
+   ``ARKODE_IMEX_MRI_GARK_MIDPOINT``     2            2
+   ``ARKODE_IMEX_MRI_GARK3a``            :math:`3^*`  2                :cite:p:`ChiRen:21`
+   ``ARKODE_IMEX_MRI_GARK3b``            3            2                :cite:p:`ChiRen:21`
+   ``ARKODE_IMEX_MRI_GARK4``             :math:`4^*`  5                :cite:p:`ChiRen:21`
+   ====================================  ===========  ===============  ===================