Feautre/adapt opt

doc/arkode/guide/source/Usage/User_callable.rst

@@ -1084,8 +1084,9 @@ Set max number of constraint failures             :c:func:`ARKodeSetMaxNumConstr
       :c:func:`ARKodeSetMinReduction`,
       :c:func:`ARKodeSetSafetyFactor`,
       :c:func:`ARKodeSetSmallNumEFails`,
-      :c:func:`ARKodeSetStabilityFn`, and
-      :c:func:`ARKodeSetAdaptController`
+      :c:func:`ARKodeSetStabilityFn`,
+      :c:func:`ARKodeSetAdaptController`, and
+      :c:func:`ARKodeSetAdaptControllerByName`
       will be ignored, since temporal adaptivity is disabled.
 
       If both :c:func:`ARKodeSetFixedStep` and
@@ -1114,7 +1115,7 @@ Set max number of constraint failures             :c:func:`ARKodeSetMaxNumConstr
                    selects forward integration, a negative value selects
                    backward integration, and zero leaves the current direction
                    unchanged.
-                   
+
 
    :retval ARK_SUCCESS: the function exited successfully.
    :retval ARK_MEM_NULL: ``arkode_mem`` was ``NULL``.
@@ -1454,6 +1455,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
 Optional input                                              Function name                               Default
 =========================================================   ==========================================  ========
 Provide a :c:type:`SUNAdaptController` for ARKODE to use    :c:func:`ARKodeSetAdaptController`          PID
+Specify a :c:type:`SUNAdaptController` for ARKODE to use    :c:func:`ARKodeSetAdaptControllerByName`    PID
 Adjust the method order used in the controller              :c:func:`ARKodeSetAdaptivityAdjustment`     -1
 Explicit stability safety factor                            :c:func:`ARKodeSetCFLFraction`              0.5
 Time step error bias factor                                 :c:func:`ARKodeSetErrorBias`                1.5
@@ -1499,6 +1501,34 @@ Reset accumulated error                                     :c:func:`ARKodeReset
    .. versionadded:: 6.1.0
 
 
+.. c:function:: int ARKodeSetAdaptControllerByName(void* arkode_mem, const char* cname)
+
+   Sets a user-supplied time-step controller object by name.
+
+   :param arkode_mem: pointer to the ARKODE memory block.
+   :param cname: name of the time adaptivity controller to use.  Allowable values
+                 currently include ``"Soderlind"``, ``"PID"``, ``"PI"``, ``"I"``,
+                 ``"ExpGus"``, ``"ImpGus"``, ``"H0211"``, ``"H211"``, ``"H312"``. For
+                 information on these options, see :numref:`SUNAdaptController.Soderlind`.
+
+   :retval ARK_SUCCESS: the function exited successfully.
+   :retval ARK_ILL_INPUT: *cname* did not match an allowed value.
+   :retval ARK_MEM_NULL: ``arkode_mem`` was ``NULL``.
+   :retval ARK_STEPPER_UNSUPPORTED: adaptive step sizes are not supported
+                                    by the current time-stepping module.
+
+   .. note::
+
+      This is only compatible with time-stepping modules that support temporal adaptivity.
+
+      It is not possible to adjust the internal controller parameters when using this
+      function.  Users who wish to adjust these parameters should create and configure
+      the :c:type:`SUNAdaptController` object manually, and then call
+      :c:func:`ARKodeSetAdaptController`.
+
+  .. versionadded:: x.y.z
+
+
 .. c:function:: int ARKodeSetAdaptivityAdjustment(void* arkode_mem, int adjust)
 
    Called by a user to adjust the method order supplied to the temporal adaptivity

doc/shared/FAQ.rst

@@ -288,6 +288,50 @@ CVODE(S) / IDA(S) / ARKODE
    integrals (very often a large number of them) need to be computed for adjoint sensitivity.
 
 
+.. collapse:: When should I select a non-default temporal adaptivity controller in ARKODE?
+
+   The default temporal adaptivity controller in ARKODE was selected due to its robust performance on test
+   problems that ranged in difficulty and stiffness, and when running with a wide range of solution tolerances
+   and method orders.  While we hope that this default runs well on most applications, it is unlikely to be
+   optimal.  A prime indicator that an alternate adaptivity controller may be useful is if the default results
+   in a large number of rejected steps.  Alternately, for higher-cost calculations where a reduction of 10%-20%
+   in the number of time steps would be important, users may want to try another controller option.
+
+   The default temporal adaptivity controller in ARKODE is the industry-standard *I* controller:
+
+   .. math::
+      h' = h_n \varepsilon_n^{-1/(p+1)}
+
+   where :math:`\varepsilon_n = \text{bias}*\text{dsm}_n`, and :math:`\text{dsm}_n` is the WRMS norm of the
+   local temporal error when using the time step :math:`h_n`, weighted by the user-requested tolerances.
+   However, the :ref:`SUNAdaptController class <SUNAdaptController>` in SUNDIALS provides a range of more
+   advanced temporal error controllers that could be applied to a given application problem, including the
+   :math:`H_{0}321`, :math:`H_{0}211`,  :math:`H211`, and :math:`H312` controllers from :cite:p:`Sod:03`,
+   as well as a variety of controllers (*PI*, *PID*, *ExpGus*, *ImpGus*, and *ImExGus*) that were included
+   in the initial ARKODE release.
+
+   The adaptive time-stepping controllers introduced by Soderlind in :cite:p:`Sod:03` can be classified into
+   two groups; *deadbeat* controllers and *non-deadbeat* controllers. A controller is known as deadbeat if
+   the roots of its characteristic equation are located at the origin. These controllers are generalized
+   forms of the *I* controller, are denoted with a zero subscript as part of the controller name (e.g.,
+   :math:`H_{0}321`), and are generally recommended for applications with smooth solutions as a function of time.
+
+   While it is impossible to exhaustively explore the question of controller optimality for all application
+   problems, we have performed tests on the range of provided controllers on a variety of stiff and non-stiff
+   problems, at varying tolerances (:math:`10^{-9} \to 10^{-3}`), and for Runge--Kutta methods at a wide range
+   of orders of accuracy (ERK orders 2-9, and DIRK orders 2-5). From our experiments, stiff problems benefitted
+   from the *I*, *PI*, :math:`H_{0}211`, :math:`H_{0}321`, and *ImpGus* controllers.  On the other hand,
+   non-stiff test problems ran most efficiently when using the *PID*, *I*, *ExpGus*, :math:`H211`, and
+   :math:`H312` controllers.
+
+   Lastly, we note that the internal controller parameters for the legacy ARKODE controllers (*PI*, *PID*,
+   *ExpGus*, *ImpGus*, and *ImExGus*) were determined via numerical optimization over a given set of test
+   problems.  As a result, although those controllers work very well for some applications, they may not
+   work well with others.  For users who are interested in exploring novel controller methods, we point out
+   that the :ref:`"Soderlind" <SUNAdaptController.Soderlind>` SUNAdaptController allows complete control
+   over all internal parameters via the :c:func:`SUNAdaptController_SetParams_Soderlind` function.
+
+
 KINSOL
 ------
 

doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst

@@ -27,10 +27,12 @@ and :cite:p:`Sod:06`.  This controller has the form
 
 with default parameter values :math:`k_1 = 1.25`, :math:`k_2 = 0.5`,
 :math:`k_3 = -0.75`, :math:`k_4 = 0.25`, and :math:`k_5 = 0.75`, where
-:math:`p` is the global order of the time integration method.  During the first
+:math:`p` is the global order of the time integration method.  We note that
+this combination of parameters corresponds with the :math:`H_{0}321`
+controller described in :cite:p:`Sod:03`.  During the first
 two steps (when :math:`\varepsilon_{n-2}`, :math:`\varepsilon_{n-1}`,
 :math:`h_{n-2}`, and :math:`h_{n-2}` may be unavailable), the I controller
-:math:`h' = h_n \varepsilon_1^{-1/(p+1)}` is used.
+:math:`h' = h_n \varepsilon_n^{-1/(p+1)}` is used.
 
 The SUNAdaptController_Soderlind controller is implemented as a derived
 SUNAdaptController class, and defines its *content* field as:
@@ -71,11 +73,11 @@ The header file to be included when using this module is
 ``sunadaptcontroller/sunadaptcontroller_soderlind.h``.
 
 We note that through appropriate selection of the parameters :math:`k_*`,
-this controller may create a wide range of proposed temporal adaptivity controllers,
-including the PID, PI, I, as well as Gustafsson's explicit and implicit controllers,
-:cite:p:`Gust:91` and :cite:p:`Gust:94`.  As a convenience, utility routines to
-create these controllers and set their parameters (as special cases of the
-SUNAdaptController_Soderlind) are provided.
+this controller may create a wide range of proposed temporal adaptivity
+controllers, including the :math:`H_{0}321`, I, PI, PID, as well as Gustafsson's
+explicit and implicit controllers, :cite:p:`Gust:91` and :cite:p:`Gust:94`,
+among others.  As a convenience, utility routines to create a variety of these
+controllers and set their parameters (as special cases of SUNAdaptController_Soderlind) are provided.
 
 The SUNAdaptController_Soderlind class provides implementations of all operations
 relevant to a ``SUN_ADAPTCONTROLLER_H`` controller listed in
@@ -242,7 +244,7 @@ also provides the following additional user-callable routines:
 .. c:function:: SUNErrCode SUNAdaptController_SetParams_ExpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
 
    This user-callable function provides control over the relevant parameters
-   above for the explicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`. 
+   above for the explicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`.
    This should be called *before* the time integrator is called to evolve the problem.
 
    .. note::
@@ -312,3 +314,54 @@ also provides the following additional user-callable routines:
    .. code-block:: c
 
       retval = SUNAdaptController_SetParams_ImpGus(C, 0.98, 0.95);
+
+.. c:function:: SUNAdaptController SUNAdaptController_H0211(SUNContext sunctx)
+
+   This constructor creates and allocates memory for a
+   SUNAdaptController_Soderlind object, set up to replicate the :math:`H_{0}211`
+   controller from :cite:p:`Sod:03`, corresponding with the parameters :math:`k_1=0.5`,
+   :math:`k_2=0.5`, :math:`k_4=-0.5`, and :math:`k_3=k_5=0`.
+
+   :param sunctx: the current :c:type:`SUNContext` object.
+   :return: if successful, a usable :c:type:`SUNAdaptController` object;
+            otherwise it will return ``NULL``.
+
+   Usage:
+
+   .. code-block:: c
+
+      SUNAdaptController C = SUNAdaptController_H0211(sunctx);
+
+.. c:function:: SUNAdaptController SUNAdaptController_H211(SUNContext sunctx)
+
+   This constructor creates and allocates memory for a
+   SUNAdaptController_Soderlind object, set up to replicate the :math:`H211`
+   controller from :cite:p:`Sod:03`, corresponding with the parameters :math:`k_1=0.25`,
+   :math:`k_2=0.25`, :math:`k_4=-0.25`, and :math:`k_3=k_5=0`.
+
+   :param sunctx: the current :c:type:`SUNContext` object.
+   :return: if successful, a usable :c:type:`SUNAdaptController` object;
+            otherwise it will return ``NULL``.
+
+   Usage:
+
+   .. code-block:: c
+
+      SUNAdaptController C = SUNAdaptController_H211(sunctx);
+
+.. c:function:: SUNAdaptController SUNAdaptController_H312(SUNContext sunctx)
+
+   This constructor creates and allocates memory for a
+   SUNAdaptController_Soderlind object, set up to replicate the :math:`H312`
+   controller from :cite:p:`Sod:03`, corresponding with the parameters :math:`k_1=0.125`,
+   :math:`k_2=0.25`, :math:`k_3=0.125`, :math:`k_4=-0.375`, and :math:`k_5=-0.125`.
+
+   :param sunctx: the current :c:type:`SUNContext` object.
+   :return: if successful, a usable :c:type:`SUNAdaptController` object;
+            otherwise it will return ``NULL``.
+
+   Usage:
+
+   .. code-block:: c
+
+      SUNAdaptController C = SUNAdaptController_H312(sunctx);

examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp

@@ -63,6 +63,7 @@
 #include <limits>
 #include <random>
 #include <sstream>
+#include <string>
 
 // Include MPI
 #include "mpi.h"
@@ -282,10 +283,10 @@ struct UserData
   // Shared IMEX and MRI settings
   // ----------------------------
 
-  int controller   = 0;     // step size adaptivity method (0 = use default)
-  int maxsteps     = 0;     // max steps between outputs (0 = use default)
-  bool linear      = true;  // enable/disable linearly implicit option
-  bool diagnostics = false; // output diagnostics
+  string controller = "PID"; // step size adaptivity method
+  int maxsteps      = 0;     // max steps between outputs (0 = use default)
+  bool linear       = true;  // enable/disable linearly implicit option
+  bool diagnostics  = false; // output diagnostics
 
   // -----------------------------------------
   // Nonlinear solver settings
@@ -379,11 +380,10 @@ static int SetupDecomp(UserData* udata);
 
 // Integrator setup functions
 static int SetupARK(SUNContext ctx, UserData* udata, N_Vector u,
-                    SUNLinearSolver LS, SUNAdaptController* Ctrl,
-                    void** arkode_mem);
+                    SUNLinearSolver LS, void** arkode_mem);
 static int SetupMRI(SUNContext ctx, UserData* udata, N_Vector u,
-                    SUNLinearSolver LS, SUNAdaptController* Ctrl,
-                    void** arkode_mem, MRIStepInnerStepper* stepper);
+                    SUNLinearSolver LS, void** arkode_mem,
+                    MRIStepInnerStepper* stepper);
 static int SetupMRICVODE(SUNContext ctx, UserData* udata, N_Vector u,
                          SUNLinearSolver LS, SUNNonlinearSolver* NLS,
                          void** arkode_mem, MRIStepInnerStepper* stepper);
@@ -557,18 +557,15 @@ int main(int argc, char* argv[])
   // Inner stepper nonlinear solver (CVODE)
   SUNNonlinearSolver NLS = NULL;
 
-  // Timestep adaptivity controller
-  SUNAdaptController Ctrl = NULL;
-
   // Create integrator
   switch (udata.integrator)
   {
   case (0):
-    flag = SetupARK(ctx, &udata, u, LS, &Ctrl, &arkode_mem);
+    flag = SetupARK(ctx, &udata, u, LS, &arkode_mem);
     if (check_flag((void*)arkode_mem, "SetupARK", 0)) { return 1; }
     break;
   case (1):
-    flag = SetupMRI(ctx, &udata, u, LS, &Ctrl, &arkode_mem, &stepper);
+    flag = SetupMRI(ctx, &udata, u, LS, &arkode_mem, &stepper);
     if (check_flag((void*)arkode_mem, "SetupMRI", 0)) { return 1; }
     break;
   case (2):
@@ -700,7 +697,6 @@ int main(int argc, char* argv[])
   N_VDestroy(N_VGetLocalVector_MPIPlusX(u));
   N_VDestroy(u);
   FreeUserData(&udata);
-  (void)SUNAdaptController_Destroy(Ctrl);
   SUNContext_Free(&ctx);
   flag = MPI_Finalize();
   return 0;
@@ -906,8 +902,7 @@ static int SetupDecomp(UserData* udata)
 // -----------------------------------------------------------------------------
 
 static int SetupARK(SUNContext ctx, UserData* udata, N_Vector u,
-                    SUNLinearSolver LS, SUNAdaptController* Ctrl,
-                    void** arkode_mem)
+                    SUNLinearSolver LS, void** arkode_mem)
 {
   int flag;
 
@@ -968,17 +963,8 @@ static int SetupARK(SUNContext ctx, UserData* udata, N_Vector u,
   }
   else
   {
-    switch (udata->controller)
-    {
-    case (ARK_ADAPT_PID): *Ctrl = SUNAdaptController_PID(ctx); break;
-    case (ARK_ADAPT_PI): *Ctrl = SUNAdaptController_PI(ctx); break;
-    case (ARK_ADAPT_I): *Ctrl = SUNAdaptController_I(ctx); break;
-    case (ARK_ADAPT_EXP_GUS): *Ctrl = SUNAdaptController_ExpGus(ctx); break;
-    case (ARK_ADAPT_IMP_GUS): *Ctrl = SUNAdaptController_ImpGus(ctx); break;
-    case (ARK_ADAPT_IMEX_GUS): *Ctrl = SUNAdaptController_ImExGus(ctx); break;
-    }
-    flag = ARKodeSetAdaptController(*arkode_mem, *Ctrl);
-    if (check_flag(&flag, "ARKodeSetAdaptController", 1)) { return 1; }
+    flag = ARKodeSetAdaptControllerByName(*arkode_mem, udata->controller.c_str());
+    if (check_flag(&flag, "ARKodeSetAdaptControllerByName", 1)) { return 1; }
   }
 
   // Set max steps between outputs
@@ -993,8 +979,8 @@ static int SetupARK(SUNContext ctx, UserData* udata, N_Vector u,
 }
 
 static int SetupMRI(SUNContext ctx, UserData* udata, N_Vector y,
-                    SUNLinearSolver LS, SUNAdaptController* Ctrl,
-                    void** arkode_mem, MRIStepInnerStepper* stepper)
+                    SUNLinearSolver LS, void** arkode_mem,
+                    MRIStepInnerStepper* stepper)
 {
   int flag;
 
@@ -1026,17 +1012,9 @@ static int SetupMRI(SUNContext ctx, UserData* udata, N_Vector y,
   }
   else
   {
-    switch (udata->controller)
-    {
-    case (ARK_ADAPT_PID): *Ctrl = SUNAdaptController_PID(ctx); break;
-    case (ARK_ADAPT_PI): *Ctrl = SUNAdaptController_PI(ctx); break;
-    case (ARK_ADAPT_I): *Ctrl = SUNAdaptController_I(ctx); break;
-    case (ARK_ADAPT_EXP_GUS): *Ctrl = SUNAdaptController_ExpGus(ctx); break;
-    case (ARK_ADAPT_IMP_GUS): *Ctrl = SUNAdaptController_ImpGus(ctx); break;
-    case (ARK_ADAPT_IMEX_GUS): *Ctrl = SUNAdaptController_ImExGus(ctx); break;
-    }
-    flag = ARKodeSetAdaptController(inner_arkode_mem, *Ctrl);
-    if (check_flag(&flag, "ARKodeSetAdaptController", 1)) { return 1; }
+    flag = ARKodeSetAdaptControllerByName(inner_arkode_mem,
+                                          udata->controller.c_str());
+    if (check_flag(&flag, "ARKodeSetAdaptControllerByName", 1)) { return 1; }
   }
 
   // Set max steps between outputs
@@ -2221,10 +2199,7 @@ static int ReadInputs(int* argc, char*** argv, UserData* udata)
     else if (arg == "--h_slow") { udata->h_slow = stod((*argv)[arg_idx++]); }
     else if (arg == "--h_fast") { udata->h_fast = stod((*argv)[arg_idx++]); }
     // Shared IMEX and MRI settings
-    else if (arg == "--controller")
-    {
-      udata->controller = stoi((*argv)[arg_idx++]);
-    }
+    else if (arg == "--controller") { udata->controller = (*argv)[arg_idx++]; }
     else if (arg == "--nonlinear") { udata->linear = false; }
     else if (arg == "--diagnostics") { udata->diagnostics = true; }
     // Linear solver settings