Update default ARKODE methods

CHANGELOG.md

@@ -6,6 +6,25 @@
 
 ### New Features and Enhancements
 
+Added the `ARKODE_RALSTON_3_1_2` and `ARKODE_TSITOURAS_7_4_5` explicit
+Runge-Kutta Butcher tables.
+
+Improved the efficiency of default ARKODE methods with the following changes:
+
+| Type               | Old Default                                                      | New Default                                                        |
+| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
+| 2nd Order Explicit | `ARKODE_HEUN_EULER_2_1_2`                                        | `ARKODE_RALSTON_3_1_2`                                             |
+| 4th Order Explicit | `ARKODE_ZONNEVELD_5_3_4`                                         | `ARKODE_SOFRONIOU_SPALETTA_5_3_4`                                  |
+| 5th Order Explicit | `ARKODE_CASH_KARP_6_4_5`                                         | `ARKODE_TSITOURAS_7_4_5`                                           |
+| 6th Order Explicit | `ARKODE_VERNER_8_5_6`                                            | `ARKODE_VERNER_9_5_6`                                              |
+| 8th Order Explicit | `ARKODE_FEHLBERG_13_7_8`                                         | `ARKODE_VERNER_13_7_8`                                             |
+| 2nd Order Implicit | `ARKODE_SDIRK_2_1_2`                                             | `ARKODE_ARK2_DIRK_3_1_2`                                           |
+| 3rd Order Implicit | `ARKODE_ARK324L2SA_DIRK_4_2_3`                                   | `ARKODE_ESDIRK325L2SA_5_2_3`                                       |
+| 4th Order Implicit | `ARKODE_SDIRK_5_3_4`                                             | `ARKODE_ESDIRK436L2SA_6_3_4`                                       |
+| 5th Order Implicit | `ARKODE_ARK548L2SA_DIRK_8_4_5`                                   | `ARKODE_ESDIRK547L2SA2_7_4_5`                                      |
+| 4th Order ARK      | `ARKODE_ARK436L2SA_ERK_6_3_4` and `ARKODE_ARK436L2SA_DIRK_6_3_4` | `ARKODE_ARK437L2SA_ERK_7_3_4` and `ARKODE_ARK437L2SA_DIRK_7_3_4`   |
+| 5th Order ARK      | `ARKODE_ARK548L2SA_ERK_8_4_5` and `ARKODE_ARK548L2SA_DIRK_8_4_5` | `ARKODE_ARK548L2SAb_ERK_8_4_5` and `ARKODE_ARK548L2SAb_DIRK_8_4_5` |
+
 The default value of `CMAKE_CUDA_ARCHITECTURES` is no longer set to `70` and is
 now determined automatically by CMake. The previous default was only valid for
 Volta GPUs while the automatically selected value will vary across compilers and

doc/arkode/guide/source/Butcher.rst

@@ -181,6 +181,42 @@ This is the default 1st order explicit method (from :cite:p:`Euler:68`).
    Linear stability region for the forward Euler method.
 
 
+.. _Butcher.Ralston:
+
+Ralston-3-1-2
+^^^^^^^^^^^^^
+
+.. index:: Ralston-3-1-2 ERK method
+
+Accessible via the constant ``ARKODE_RALSTON_3_1_2`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum` or
+:c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_RALSTON_3_1_2"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`.
+This is the default 2nd order explicit method
+(primary method from :cite:p:`Ralston:62`).
+
+.. math::
+
+   \renewcommand{\arraystretch}{1.5}
+   \begin{array}{r|cc}
+     0 & 0 & 0 & 0 \\
+     \frac{2}{3} & \frac{2}{3} & 0 & 0 \\
+     1 & \frac{1}{4} & \frac{3}{4} & 0 \\
+     \hline
+     2 & \frac{1}{4} & \frac{3}{4} & 0 \\
+     1 & \frac{5}{37} & \frac{2}{3} & \frac{22}{111}
+   \end{array}
+
+.. figure:: /figs/arkode/ralston_stab_region.png
+   :scale: 50 %
+   :align: center
+
+   Linear stability region for the Ralston method.  The method's
+   region is outlined in blue; the embedding's region is in red.
+
+
 .. _Butcher.Heun_Euler:
 
 Heun-Euler-2-1-2
@@ -194,7 +230,7 @@ Accessible via the constant ``ARKODE_HEUN_EULER_2_1_2`` to
 Accessible via the string ``"ARKODE_HEUN_EULER_2_1_2"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 2nd order explicit method.
+(primary method from :cite:p:`Runge:95`).
 
 .. math::
 
@@ -227,7 +263,7 @@ Accessible via the constant ``ARKODE_RALSTON_EULER_2_1_2`` to
 :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`
+:c:func:`ARKodeButcherTable_LoadERKByName`.
 (primary method from :cite:p:`Ralston:62`).
 
 .. math::
@@ -261,7 +297,7 @@ Accessible via the constant ``ARKODE_EXPLICIT_MIDPOINT_EULER_2_1_2`` to
 :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`
+:c:func:`ARKodeButcherTable_LoadERKByName`.
 (primary method from :cite:p:`Runge:95`).
 
 .. math::
@@ -477,6 +513,7 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_SOFRONIOU_SPALETTA_5_3_4"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
+This is the default 4th order explicit method.
 (from :cite:p:`Sof:04`).
 
 .. math::
@@ -516,7 +553,6 @@ Accessible via the constant ``ARKODE_ZONNEVELD_5_3_4`` to
 Accessible via the string ``"ARKODE_ZONNEVELD_5_3_4"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName`, or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 4th order explicit method
 (from :cite:p:`Zon:63`).
 
 .. math::
@@ -557,8 +593,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_ARK436L2SA_ERK_6_3_4"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the explicit portion of the default 4th order additive method (the
-explicit portion of the ARK4(3)6L[2]SA method from :cite:p:`KenCarp:03`).
+This is the explicit portion of the ARK4(3)6L[2]SA method from
+:cite:p:`KenCarp:03`.
 
 .. math::
 
@@ -598,8 +634,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_ARK437L2SA_ERK_7_3_4"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the explicit portion of the 4th order additive method (the explicit
-portion of the ARK4(3)7L[2]SA method from :cite:p:`KenCarp:19`).
+This is the explicit portion of the default 4th order additive method and the
+explicit portion of the ARK4(3)7L[2]SA method from :cite:p:`KenCarp:19`.
 
 .. only:: html
 
@@ -671,7 +707,50 @@ Accessible via the string ``"ARKODE_SAYFY_ABURUB_6_3_4"`` to
    region is outlined in blue; the embedding's region is in red.
 
 
+.. _Butcher.Tsitouras:
+
+Tsitouras-6-4-5
+^^^^^^^^^^^^^^^
+
+.. index:: Tsitouras-6-4-5 ERK method
+
+Accessible via the constant ``ARKODE_TSITOURAS_7_4_5`` to
+:c:func:`ARKStepSetTableNum`, :c:func:`ERKStepSetTableNum`
+or :c:func:`ARKodeButcherTable_LoadERK`.
+Accessible via the string ``"ARKODE_TSITOURAS_7_4_5"`` to
+:c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
+:c:func:`ARKodeButcherTable_LoadERKByName`.
+This is the default 5th order explicit method (from :cite:p:`Tsitouras:11`).
+
+.. only:: html
+
+   .. math::
+
+      \renewcommand{\arraystretch}{1.5}
+      \begin{array}{r|ccccccc}
+         0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+         0.1610000000000000 & 0.1610000000000000 & 0 & 0 & 0 & 0 & 0 & 0 \\
+         0.3270000000000000 & -0.008480655492356989 & 0.3354806554923570 & 0 & 0 & 0 & 0 & 0 \\
+         0.9000000000000000 & 2.897153057105493 & -6.359448489975075 & 4.362295432869581 & 0 & 0 & 0 & 0 \\
+         0.9800255409045097 & 5.325864828439257 & -11.74888356406283 & 7.495539342889836 & -0.09249506636175525 & 0 & 0 & 0 \\
+         1.000000000000000 & 5.861455442946420 & -12.92096931784711 & 8.159367898576159 & -0.07158497328140100 & -0.02826905039406838 & 0 & 0 \\
+         1.000000000000000 & 0.09646076681806523 & 0.01000000000000000 & 0.4798896504144996 & 1.379008574103742 & -3.290069515436081 & 2.324710524099774 & 0 \\
+         \hline
+         5 & 0.09646076681806523 & 0.01000000000000000 & 0.4798896504144996 & 1.379008574103742 & -3.290069515436081 & 2.324710524099774 & 0 \\
+         4 & 0.09352374858189271 & 0.008652883141566368 & 0.4928930991314319 & 1.140235412267858 & -2.329180192439365 & 1.568875049316616 & 0.02500000000000000
+      \end{array}
+
+.. only:: latex
+
+   The Butcher table is too large to fit in the PDF version of this documentation.  Please see the HTML documentation for the table coefficients.
+
+
+.. figure:: /figs/arkode/tsitouras_stab_region.png
+   :scale: 50 %
+   :align: center
 
+   Linear stability region for the Tsitouras method.  The method's
+   region is outlined in blue; the embedding's region is in red.
 
 
 .. _Butcher.Cash-Karp:
@@ -687,7 +766,7 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_CASH_KARP_6_4_5"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 5th order explicit method (from :cite:p:`CashKarp:90`).
+(from :cite:p:`CashKarp:90`).
 
 .. math::
 
@@ -813,8 +892,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_ARK548L2SA_ERK_8_4_5"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the explicit portion of the default 5th order additive method (the
-explicit portion of the ARK5(4)8L[2]SA method from :cite:p:`KenCarp:03`).
+This is the explicit portion of the ARK5(4)8L[2]SA method from
+:cite:p:`KenCarp:03`.
 
 .. only:: html
 
@@ -865,7 +944,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_ARK548L2SAb_ERK_8_4_5"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the explicit portion of the 5th order ARK5(4)8L[2]SA method from
+This is the explicit portion of the default 5th order additive method and the
+explicit portion of the 5th order ARK5(4)8L[2]SA method from
 :cite:p:`KenCarp:19`.
 
 .. only:: html
@@ -915,7 +995,7 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_VERNER_8_5_6"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 6th order explicit method (from :cite:p:`HEJ:76`).
+(from :cite:p:`HEJ:76`).
 
 .. math::
 
@@ -956,7 +1036,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_VERNER_9_5_6"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the 6th order explicit method IIIXb-6(5) from :cite:p:`Ver:10`.
+This is the default 6th order explicit method
+(method IIIXb-6(5) from :cite:p:`Ver:10`).
 
 .. only:: html
 
@@ -1057,7 +1138,7 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_FEHLBERG_13_7_8"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the default 8th order explicit method (from :cite:p:`Butcher:08`).
+(from :cite:p:`Butcher:08`).
 
 .. math::
 
@@ -1104,7 +1185,8 @@ or :c:func:`ARKodeButcherTable_LoadERK`.
 Accessible via the string ``"ARKODE_VERNER_13_7_8"`` to
 :c:func:`ARKStepSetTableName`, :c:func:`ERKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadERKByName`.
-This is the 8th order explicit method IIIX-8(7) from :cite:p:`Ver:10`.
+This is the default 8th order explicit method
+(method IIIX-8(7) from :cite:p:`Ver:10`).
 
 
 .. only:: html
@@ -1266,8 +1348,7 @@ Accessible via the constant ``ARKODE_SDIRK_2_1_2`` to
 Accessible via the string ``"ARKODE_SDIRK_2_1_2"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the default 2nd order implicit method.  Both the method and embedding
-are A- and B-stable.
+Both the method and embedding are A- and B-stable.
 
 .. math::
 
@@ -1301,8 +1382,9 @@ Accessible via the constant ``ARKODE_ARK2_DIRK_3_1_2`` to
 Accessible via the string ``"ARKODE_ARK2_DIRK_3_1_2"`` to
 :c:func:`ARKStepSetTableName`, or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the implicit portion of the default 2nd order additive method (the
-implicit portion of the ARK2 method from :cite:p:`giraldo2013implicit`).
+This is the default 2nd order implicit method and the implicit portion of the
+default 2nd order additive method
+(the implicit portion of the ARK2 method from :cite:p:`giraldo2013implicit`).
 
 .. math::
 
@@ -1499,7 +1581,8 @@ Accessible via the constant ``ARKODE_ESDIRK325L2SA_5_2_3`` to
 Accessible via the string ``"ARKODE_ESDIRK325L2SA_5_2_3"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the ESDIRK3(2)5L[2]SA method from :cite:p:`KenCarp:16`.
+This is the default 3rd order implicit method and the ESDIRK3(2)5L[2]SA method
+from :cite:p:`KenCarp:16`.
 Both the method and embedding are A- and L-stable.
 
 .. figure:: /figs/arkode/stab_region_26.png
@@ -1588,10 +1671,10 @@ Accessible via the constant ``ARKODE_ARK324L2SA_DIRK_4_2_3`` to
 Accessible via the string ``"ARKODE_ARK324L2SA_DIRK_4_2_3"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the default 3rd order implicit method, and the implicit portion of the
-default 3rd order additive method.  Both the method and embedding are A-stable;
-additionally the method is L-stable (this is the implicit portion of the
-ARK3(2)4L[2]SA method from :cite:p:`KenCarp:03`).
+This is the implicit portion of the default 3rd order additive method.  Both the
+method and embedding are A-stable; additionally the method is L-stable
+(this is the implicit portion of the ARK3(2)4L[2]SA method from
+:cite:p:`KenCarp:03`).
 
 .. math::
 
@@ -1715,9 +1798,8 @@ Accessible via the constant ``ARKODE_SDIRK_5_3_4`` to
 Accessible via the string ``"ARKODE_SDIRK_5_3_4"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the default 4th order implicit method.  Here, the method is both A- and
-L-stable, although the embedding has reduced stability
-(from :cite:p:`HaWa:91`).
+Here, the method is both A- and L-stable, although the embedding has reduced
+stability (from :cite:p:`HaWa:91`).
 
 .. math::
 
@@ -1808,9 +1890,9 @@ Accessible via the constant ``ARKODE_ARK436L2SA_DIRK_6_3_4`` to
 Accessible via the string ``"ARKODE_ARK436L2SA_DIRK_6_3_4"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the implicit portion of the default 4th order additive method. Both the
-method and embedding are A-stable; additionally the method is L-stable (this is
-the implicit portion of the ARK4(3)6L[2]SA method from :cite:p:`KenCarp:03`).
+Both the method and embedding are A-stable; additionally the method is L-stable
+(this is the implicit portion of the ARK4(3)6L[2]SA method from
+:cite:p:`KenCarp:03`).
 
 .. math::
 
@@ -1852,7 +1934,8 @@ Accessible via the constant ``ARKODE_ARK437L2SA_DIRK_7_3_4`` to
 Accessible via the string ``"ARKODE_ARK437L2SA_DIRK_7_3_4"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the implicit portion of the 4th order ARK4(3)7L[2]SA method from
+This is the implicit portion of the default 4th order additive method and the
+implicit portion of the 4th order ARK4(3)7L[2]SA method from
 :cite:p:`KenCarp:19`.  Both the method and embedding are A- and L-stable.
 
 .. math::
@@ -1891,8 +1974,8 @@ Accessible via the constant ``ARKODE_ESDIRK436L2SA_6_3_4`` to
 Accessible via the string ``"ARKODE_ESDIRK436L2SA_6_3_4"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the ESDIRK4(3)6L[2]SA method from :cite:p:`KenCarp:16`.
-Both the method and embedding are A- and L-stable.
+This is the default 4th order implicit method and the ESDIRK4(3)6L[2]SA method
+from :cite:p:`KenCarp:16`. Both the method and embedding are A- and L-stable.
 
 .. figure:: /figs/arkode/stab_region_28.png
    :scale: 50 %
@@ -2036,10 +2119,8 @@ Accessible via the constant ``ARKODE_ARK548L2SA_DIRK_8_4_5`` for
 Accessible via the string ``"ARKODE_ARK548L2SA_DIRK_8_4_5"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the default 5th order implicit method, and the implicit portion of the
-default 5th order additive method.  Both the method and embedding are A-stable;
-additionally the method is L-stable (the implicit portion of the ARK5(4)8L[2]SA
-method from :cite:p:`KenCarp:03`).
+Both the method and embedding are A-stable; additionally the method is L-stable
+(the implicit portion of the ARK5(4)8L[2]SA method from :cite:p:`KenCarp:03`).
 
 .. only:: html
 
@@ -2088,6 +2169,7 @@ Accessible via the constant ``ARKODE_ARK548L2SAb_DIRK_8_4_5`` for
 Accessible via the string ``"ARKODE_ARK548L2SAb_DIRK_8_4_5"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
+This is the implicit portion of the default 5th order additive method.
 Both the method and embedding are A-stable; additionally the method is L-stable
 (this is the implicit portion of the 5th order ARK5(4)8L[2]SA method from
 :cite:p:`KenCarp:19`).
@@ -2159,8 +2241,8 @@ Accessible via the constant ``ARKODE_ESDIRK547L2SA2_7_4_5`` to
 Accessible via the string ``"ARKODE_ESDIRK547L2SA2_7_4_5"`` to
 :c:func:`ARKStepSetTableName` or
 :c:func:`ARKodeButcherTable_LoadDIRKByName`.
-This is the ESDIRK5(4)7L[2]SA2 method from :cite:p:`KenCarp:19b`.
-Both the method and embedding are A- and L-stable.
+This is the default 5th order implicit method and the ESDIRK5(4)7L[2]SA2 method
+from :cite:p:`KenCarp:19b`. Both the method and embedding are A- and L-stable.
 
 .. figure:: /figs/arkode/stab_region_33.png
    :scale: 50 %