From e6a671f3617001cb09f23c8036919d35bc1c6943 Mon Sep 17 00:00:00 2001 From: "Daniel R. Reynolds" Date: Mon, 30 Oct 2023 22:05:26 -0500 Subject: [PATCH] Apply suggestions from code review Co-authored-by: David Gardner --- .../ARKStep_c_interface/User_callable.rst | 2 +- .../ERKStep_c_interface/User_callable.rst | 2 +- .../guide/source/sunadaptcontroller/index.rst | 6 +- .../SUNAdaptController_Description.rst | 41 ++++++------- .../SUNAdaptController_ImExGus.rst | 4 +- .../SUNAdaptController_Soderlind.rst | 60 +++++++++---------- 6 files changed, 56 insertions(+), 59 deletions(-) diff --git a/doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst b/doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst index 7b23cf149e..36a6472cca 100644 --- a/doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst +++ b/doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst @@ -1815,7 +1815,7 @@ Explicit stability function :c:func:`ARKStepSetS This should be called prior to calling :c:func:`ARKStepEvolve()`, and can only be reset following a call to :c:func:`ARKStepReInit()`. - + .. versionadded:: x.x.x .. c:function:: int ARKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac) diff --git a/doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst b/doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst index a3bf27c191..adae5325f0 100644 --- a/doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst +++ b/doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst @@ -1298,7 +1298,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`. This should be called prior to calling :c:func:`ERKStepEvolve()`, and can only be reset following a call to :c:func:`ERKStepReInit()`. - + .. versionadded:: x.x.x .. c:function:: int ERKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac) diff --git a/doc/arkode/guide/source/sunadaptcontroller/index.rst b/doc/arkode/guide/source/sunadaptcontroller/index.rst index c4d88d5ba2..bd4ab38d7b 100644 --- a/doc/arkode/guide/source/sunadaptcontroller/index.rst +++ b/doc/arkode/guide/source/sunadaptcontroller/index.rst @@ -19,9 +19,9 @@ Time Step Adaptivity Controllers The SUNDIALS library comes packaged with a variety of :c:type:`SUNAdaptController` implementations, designed to support various forms of error-based time step adaptivity within SUNDIALS time integrators. To support applications that may -want to adjust or disable these heuristic controls, SUNDIALS provides a -:c:type:`SUNAdaptController` base class, along with a variety of default -implementations. +want to adjust the controller parameters or provide their own implementations, +SUNDIALS defines the :c:type:`SUNAdaptController` base class, along with a +variety of default implementations. .. toctree:: :maxdepth: 1 diff --git a/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst b/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst index c1b88c837b..6199e802c0 100644 --- a/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst +++ b/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst @@ -25,7 +25,7 @@ temporal accuracy, while striving to maximize computational efficiency. We note that in the descriptions below, we frequently use *dsm* to represent temporal error. This is **not** the raw temporal error estimate; instead, it is a norm of the temporal error estimate after scaling by the user-supplied -accuracy tolerances (the SUNDIALS WRMS-norm), +accuracy tolerances (see :eq:`ARKODE_WRMS_NORM`), .. math:: \text{dsm} = \left( \frac{1}{N} \sum_{i=1}^N @@ -48,7 +48,7 @@ and the base class structure is defined as struct _generic_SUNAdaptController { void* content; - generic_SUNAdaptController_Ops_* ops; + generic_SUNAdaptController_Ops* ops; SUNContext sunctx; }; @@ -104,8 +104,8 @@ SUNAdaptController Operations The base SUNAdaptController class defines and implements all SUNAdaptController functions. Most of these routines are merely wrappers for the operations defined by a particular SUNAdaptController implementation, which are accessed through the *ops* field of the -``SUNAdaptController`` structure. However, the base SUNAdaptController class also provides the -convenience routine +``SUNAdaptController`` structure. The base SUNAdaptController class provides the +constructor .. c:function:: SUNAdaptController SUNAdaptController_NewEmpty(SUNContext sunctx) @@ -118,11 +118,10 @@ convenience routine :returns: If successful, a generic :c:type:`SUNAdaptController` object. If unsuccessful, a ``NULL`` pointer will be returned. -Each of the following routines are *optional* for any specific SUNAdaptController +Each of the following methods are *optional* for any specific SUNAdaptController implementation, however some may be required based on the implementation's :c:type:`SUNAdaptController_Type` (see Section :numref:`SUNAdaptController.Description.controllerTypes`). We -note these requirements, as well as the behavior of the base SUNAdaptController wrapper -routine, below. +note these requirements below. Additionally, we note the behavior of the base SUNAdaptController methods when they perform an action other than only a successful return. .. c:function:: SUNAdaptController_Type SUNAdaptController_GetType(SUNAdaptController C) @@ -140,8 +139,8 @@ routine, below. .. c:function:: int SUNAdaptController_Destroy(SUNAdaptController C) - Deallocates the controller *C*. If this is not provided by the - implementation, the base wrapper routine will free both the *content* and + Deallocates the controller *C*. If this method is not provided by the + implementation, the base class method will free both the *content* and *ops* objects -- this should be sufficient unless a controller implementation performs dynamic memory allocation of its own (note that the SUNDIALS-provided SUNAdaptController implementations do not need to supply this @@ -167,7 +166,7 @@ routine, below. :param h: the step size from the previous step attempt. :param p: the current order of accuracy for the time integration method. :param dsm: the local temporal estimate from the previous step attempt. - :param hnew: (output) pointer to the estimated step size. + :param hnew: (output) the estimated step size. :return: error code indicating success failure (see :numref:`SUNAdaptController.Description.errorCodes`). @@ -175,14 +174,12 @@ routine, below. .. code-block:: c - retval = SUNAdaptController_EstimateStep(C, hcur, dsm, &hnew); + retval = SUNAdaptController_EstimateStep(C, hcur, p, dsm, &hnew); .. c:function:: int SUNAdaptController_Reset(SUNAdaptController C) Resets the controller to its initial state, e.g., if it stores a small number - of previous *dsm* or *h* values. The return value is an integer flag denoting - success/failure of the routine (see - :numref:`SUNAdaptController.Description.errorCodes`). + of previous *dsm* or *h* values. :param C: the :c:type:`SUNAdaptController` object. :return: error code indicating success failure @@ -198,7 +195,7 @@ routine, below. Sets the controller parameters to their default values. - :param C: the :c:type:`SUNAdaptController` object.. + :param C: the :c:type:`SUNAdaptController` object. :return: error code indicating success failure (see :numref:`SUNAdaptController.Description.errorCodes`). @@ -213,7 +210,7 @@ routine, below. Writes all controller parameters to the indicated file pointer. :param C: the :c:type:`SUNAdaptController` object. - :param fptr: the output stream to write the parameters. + :param fptr: the output stream to write the parameters to. :return: error code indicating success failure (see :numref:`SUNAdaptController.Description.errorCodes`). @@ -301,18 +298,18 @@ SUNAdaptController functions return one of the following set of error codes: .. note:: The SUNDIALS time integrators do not rely on these specific return values (only - on whether the returned values are 0 (successful) or negative (failure). Thus, + on whether the returned values are 0 (successful) or non-zero (failure). Thus, user-defined implementations are not required to use these specific error codes, - so long as the zero/negative structure is followed. + so long as the zero/non-zero convention is followed. C/C++ API Usage --------------- Specific SUNDIALS adaptivity controller modules can be used in C and C++ programs by including -the corresponding header file for that module, e.g. ``sunadaptcontroller/sunadaptcontrollerXYZ.h``. +the corresponding header file for that module, e.g. ``sunadaptcontroller/sunadaptcontroller_XYZ.h``. -Example usage (here ``SUNAdaptControllerXYZ`` is a placeholder for an actual SUNAdaptController +Example usage (here ``SUNAdaptController_XYZ`` is a placeholder for an actual SUNAdaptController constructor): .. code-block:: c @@ -321,7 +318,7 @@ constructor): #include #include #include - #include + #include int main() { @@ -329,7 +326,7 @@ constructor): SUNContext sunctx = ...; /* Create a SUNAdaptController object */ - SUNAdaptController C = SUNAdaptControllerXYZ(sunctx); + SUNAdaptController C = SUNAdaptController_XYZ(sunctx); /* Use the control object */ diff --git a/doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst b/doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst index 3af855ae5b..c0a54fddf8 100644 --- a/doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst +++ b/doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst @@ -88,7 +88,7 @@ The header file to be included when using this module is The SUNAdaptController_ImExGus class provides implementations of all operations -relevant to a `SUN_ADAPTCONTROLLER_H` controller listed in +relevant to a ``SUN_ADAPTCONTROLLER_H`` controller listed in :numref:`SUNAdaptController.Description.operations`. The SUNAdaptController_ImExGus class also provides the following additional user-callable routines: @@ -96,7 +96,7 @@ routines: .. c:function:: SUNAdaptController SUNAdaptController_ImExGus(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_ImExGus + This constructor creates and allocates memory for a SUNAdaptController_ImExGus object, and inserts its default parameters. :param sunctx: the current :c:type:`SUNContext` object. diff --git a/doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst b/doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst index a3d49f24fd..525ca7e3c1 100644 --- a/doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst +++ b/doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst @@ -19,18 +19,18 @@ The SUNAdaptController_Soderlind Module The Soderlind implementation of the SUNAdaptController class, SUNAdaptController_Soderlind, implements a general structure for temporal -control proposed by G. Soderlind in :cite:p:`Sod:98`, :cite:p:`Sod:03` +control proposed by G. Soderlind in :cite:p:`Sod:98`, :cite:p:`Sod:03`, and :cite:p:`Sod:06`. This controller has the form .. math:: h' = h_n \varepsilon_n^{-k_1/(p+1)} \varepsilon_{n-1}^{-k_2/(p+1)} \varepsilon_{n-2}^{-k_3/(p+1)} \left(\dfrac{h_n}{h_{n-1}}\right)^{k_4} \left(\dfrac{h_{n-1}}{h_{n-2}}\right)^{k_5} 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:`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. In this estimate, -a floor of :math:`\varepsilon > 10^{-10}` is enforced to avoid division-by-zero +a floor of :math:`\varepsilon_* > 10^{-10}` is enforced to avoid division-by-zero errors. 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), +:math:`\varepsilon_{n-1}`, :math:`h_{n-2}`, and :math:`h_{n-2}` may be unavailable), the corresponding terms are merely omitted during estimation of :math:`h'`. The SUNAdaptController_Soderlind controller is implemented as a derived @@ -60,7 +60,7 @@ These entries of the *content* field contain the following information: estimate via :math:`\varepsilon = \text{bias}*\text{dsm}`. * ``ep, epp`` - storage for the two previous error estimates, - :math:`\varepsilon_{n-1}` and :math:`varepsilon_{n-2}`. + :math:`\varepsilon_{n-1}` and :math:`\varepsilon_{n-2}`. * ``hp, hpp`` - storage for the previous two step sizes, :math:`h_{n-1}` and :math:`h_{n-2}`. @@ -71,7 +71,7 @@ These entries of the *content* field contain the following information: 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_1 - k_5`, +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 @@ -79,14 +79,14 @@ create these controllers and set their parameters (as special cases of the SUNAdaptController_Soderlind) are provided. The SUNAdaptController_Soderlind class provides implementations of all operations -relevant to a `SUN_ADAPTCONTROLLER_H` controller listed in +relevant to a ``SUN_ADAPTCONTROLLER_H`` controller listed in :numref:`SUNAdaptController.Description.operations`. This class also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_Soderlind(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, and inserts its default parameters. :param sunctx: the current :c:type:`SUNContext` object. @@ -123,9 +123,9 @@ also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_PID(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, set up to replicate a PID controller, and inserts its default parameters - (:math:`k_1=0.58`, :math:`k_2=-0.21`, :math:`k_3=0.1`, and :math:`k_4=k_5=0`). + :math:`k_1=0.58`, :math:`k_2=-0.21`, :math:`k_3=0.1`, and :math:`k_4=k_5=0`. :param sunctx: the current :c:type:`SUNContext` object. :return: if successful, a usable :c:type:`SUNAdaptController` object; @@ -140,8 +140,8 @@ also provides the following additional user-callable routines: .. c:function:: int SUNAdaptController_SetParams_PID(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3) This user-callable function provides control over the relevant parameters - above, setting :math:`k_4 = k_5 = 0`. This should be called *before* the - time integrator is called to evolve the problem. + above for a PID controller, setting :math:`k_4 = k_5 = 0`. This should be + called *before* the time integrator is called to evolve the problem. :param C: the SUNAdaptController_Soderlind object. :param k1: parameter used within the controller time step estimate. @@ -158,9 +158,9 @@ also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_PI(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, set up to replicate a PI controller, and inserts its default parameters - (:math:`k_1=0.8`, :math:`k_2=-0.31`, and :math:`k_3=k_4=k_5=0`). + :math:`k_1=0.8`, :math:`k_2=-0.31`, and :math:`k_3=k_4=k_5=0`. :param sunctx: the current :c:type:`SUNContext` object. :return: if successful, a usable :c:type:`SUNAdaptController` object; @@ -175,8 +175,8 @@ also provides the following additional user-callable routines: .. c:function:: int SUNAdaptController_SetParams_PI(SUNAdaptController C, sunrealtype k1, sunrealtype k2) This user-callable function provides control over the relevant parameters - above, setting :math:`k_3 = k_4 = k_5 = 0`. This should be called *before* the - time integrator is called to evolve the problem. + above for a PI controller, setting :math:`k_3 = k_4 = k_5 = 0`. This should + be called *before* the time integrator is called to evolve the problem. :param C: the SUNAdaptController_Soderlind object. :param k1: parameter used within the controller time step estimate. @@ -192,9 +192,9 @@ also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_I(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, set up to replicate an I controller, and inserts its default parameters - (:math:`k_1=1.0` and :math:`k_2=k_3=k_4=k_5=0`). + :math:`k_1=1.0` and :math:`k_2=k_3=k_4=k_5=0`. :param sunctx: the current :c:type:`SUNContext` object. :return: if successful, a usable :c:type:`SUNAdaptController` object; @@ -209,8 +209,8 @@ also provides the following additional user-callable routines: .. c:function:: int SUNAdaptController_SetParams_I(SUNAdaptController C, sunrealtype k1) This user-callable function provides control over the relevant parameters - above, setting :math:`k_2 = k_3 = k_4 = k_5 = 0`. This should be called *before* the - time integrator is called to evolve the problem. + above for an I controller, setting :math:`k_2 = k_3 = k_4 = k_5 = 0`. This + should be called *before* the time integrator is called to evolve the problem. :param C: the SUNAdaptController_Soderlind object. :param k1: parameter used within the controller time step estimate. @@ -225,10 +225,10 @@ also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_ExpGus(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, set up to replicate Gustafsson's explicit controller :cite:p:`Gust:91`, and - inserts its default parameters (:math:`k_1=0.635`, :math:`k_2=-0.268`, and - :math:`k_3=k_4=k_5=0`). + inserts its default parameters :math:`k_1=0.635`, :math:`k_2=-0.268`, and + :math:`k_3=k_4=k_5=0`. :param sunctx: the current :c:type:`SUNContext` object. :return: if successful, a usable :c:type:`SUNAdaptController` object; @@ -243,8 +243,8 @@ also provides the following additional user-callable routines: .. c:function:: int SUNAdaptController_SetParams_ExpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat) This user-callable function provides control over the relevant parameters - above, setting :math:`k_3 = k_4 = k_5 = 0`. This should be called *before* the - time integrator is called to evolve the problem. + 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:: @@ -271,10 +271,10 @@ also provides the following additional user-callable routines: .. c:function:: SUNAdaptController SUNAdaptController_ImpGus(SUNContext sunctx) - This constructor function creates and allocates memory for a SUNAdaptController_Soderlind + This constructor creates and allocates memory for a SUNAdaptController_Soderlind object, set up to replicate Gustafsson's implicit controller :cite:p:`Gust:94`, and - inserts its default parameters (:math:`k_1=1.93`, :math:`k_2=-0.95`, :math:`k_4=1`, and - :math:`k_3=k_5=0`). + inserts its default parameters :math:`k_1=1.93`, :math:`k_2=-0.95`, :math:`k_4=1`, and + :math:`k_3=k_5=0`. :param sunctx: the current :c:type:`SUNContext` object. :return: if successful, a usable :c:type:`SUNAdaptController` object; @@ -289,8 +289,8 @@ also provides the following additional user-callable routines: .. c:function:: int SUNAdaptController_SetParams_ImpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat) This user-callable function provides control over the relevant parameters - above, setting :math:`k_3 = k_4 = k_5 = 0`. This should be called *before* the - time integrator is called to evolve the problem. + above for the implicit 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::