Skip to content

Commit

Permalink
Feature: New Low Order Methods (#439)
Browse files Browse the repository at this point in the history
- 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 <[email protected]>
Co-authored-by: David Gardner <[email protected]>
  • Loading branch information
3 people authored May 12, 2024
1 parent d10ca84 commit b060541
Show file tree
Hide file tree
Showing 37 changed files with 2,706 additions and 221 deletions.
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
193 changes: 193 additions & 0 deletions doc/arkode/guide/source/Butcher.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit b060541

Please sign in to comment.