From b26c39f129aca2e0576b9732c89082fe2d631ce9 Mon Sep 17 00:00:00 2001 From: "Daniel R. Reynolds" Date: Thu, 26 Sep 2024 12:55:48 -0500 Subject: [PATCH] Applied changes suggested in code review --- .../source/Usage/ERKStep/User_callable.rst | 6 +-- .../Custom_Inner_Stepper/Description.rst | 25 ------------- .../source/Usage/MRIStep/MRIStepCoupling.rst | 36 +++++++++--------- .../source/Usage/MRIStep/User_callable.rst | 2 +- .../SUNAdaptController_Description.rst | 37 +------------------ .../SUNAdaptController_MRIHTol.rst | 17 ++------- 6 files changed, 26 insertions(+), 97 deletions(-) diff --git a/doc/arkode/guide/source/Usage/ERKStep/User_callable.rst b/doc/arkode/guide/source/Usage/ERKStep/User_callable.rst index 6b6107781c..8ac01ce4b6 100644 --- a/doc/arkode/guide/source/Usage/ERKStep/User_callable.rst +++ b/doc/arkode/guide/source/Usage/ERKStep/User_callable.rst @@ -650,7 +650,7 @@ Optional inputs for ERKStep **Return value:** * *ARK_SUCCESS* if successful - * *ARK_MEM_NULL* if the ARKStep memory is ``NULL`` + * *ARK_MEM_NULL* if the ERKStep memory is ``NULL`` .. versionadded:: 5.6.0 @@ -1874,7 +1874,7 @@ Main solver optional output functions **Return value:** * *ARK_SUCCESS* if successful - * *ARK_MEM_NULL* if the ARKStep memory was ``NULL`` + * *ARK_MEM_NULL* if the ERKStep memory was ``NULL`` .. versionadded:: 5.3.0 @@ -2199,7 +2199,7 @@ wrap an ERKStep memory block as an :c:type:`MRIStepInnerStepper`. /* setup ERKStep */ . . . - /* create MRIStepInnerStepper wrapper for the ARKStep memory block */ + /* create MRIStepInnerStepper wrapper for the ERKStep memory block */ flag = ERKStepCreateMRIStepInnerStepper(inner_arkode_mem, &stepper); /* create an MRIStep object, setting the slow (outer) right-hand side diff --git a/doc/arkode/guide/source/Usage/MRIStep/Custom_Inner_Stepper/Description.rst b/doc/arkode/guide/source/Usage/MRIStep/Custom_Inner_Stepper/Description.rst index 9dc117a91e..c9eb478cd6 100644 --- a/doc/arkode/guide/source/Usage/MRIStep/Custom_Inner_Stepper/Description.rst +++ b/doc/arkode/guide/source/Usage/MRIStep/Custom_Inner_Stepper/Description.rst @@ -239,12 +239,6 @@ Setting Member Functions :retval ARK_SUCCESS: if successful :retval ARK_ILL_INPUT: if the stepper is ``NULL`` - **Example usage:** - - .. code-block:: C - - /* set the inner stepper accumulated error 'get' function */ - flag = MRIStepInnerStepper_SetAccumulatedErrorGetFn(inner_stepper, MyAccumErr); .. c:function:: int MRIStepInnerStepper_SetAccumulatedErrorResetFn(MRIStepInnerStepper stepper, MRIStepInnerResetAccumulatedError fn) @@ -257,12 +251,6 @@ Setting Member Functions :retval ARK_SUCCESS: if successful :retval ARK_ILL_INPUT: if the stepper is ``NULL`` - **Example usage:** - - .. code-block:: C - - /* set the inner stepper accumulated error 'reset' function */ - flag = MRIStepInnerStepper_SetAccumulatedErrorResetFn(inner_stepper, MyResetAccumErr); .. c:function:: int MRIStepInnerStepper_SetRTolFn(MRIStepInnerStepper stepper, MRIStepInnerSetRTol fn) @@ -275,12 +263,6 @@ Setting Member Functions :retval ARK_SUCCESS: if successful :retval ARK_ILL_INPUT: if the stepper is ``NULL`` - **Example usage:** - - .. code-block:: C - - /* set the inner stepper relative tolerance function */ - flag = MRIStepInnerStepper_SetRTolFn(inner_stepper, MySetRTol); .. _ARKODE.Usage.MRIStep.CustomInnerStepper.Description.BaseMethods.Forcing: @@ -309,13 +291,6 @@ data necessary to construct the inner (fast) forcing polynomial. :retval ARK_SUCCESS: if successful :retval ARK_ILL_INPUT: if the stepper is ``NULL`` - **Example usage:** - - .. code-block:: C - - /* compute the forcing term and add it the fast RHS vector */ - flag = MRIStepInnerStepper_AddForcing(inner_stepper, t, f_fast); - **Example codes:** * ``examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp`` diff --git a/doc/arkode/guide/source/Usage/MRIStep/MRIStepCoupling.rst b/doc/arkode/guide/source/Usage/MRIStep/MRIStepCoupling.rst index da7479dfcc..72222704bb 100644 --- a/doc/arkode/guide/source/Usage/MRIStep/MRIStepCoupling.rst +++ b/doc/arkode/guide/source/Usage/MRIStep/MRIStepCoupling.rst @@ -26,22 +26,22 @@ constructing a coupling table and attaching it with the MRI methods supported by MRIStep. The family of MRI method encoded by the table is determined by an enumerated type, :c:type:`ARKODE_MRIType`: -.. c:type:: ARKODE_MRIType +.. c:enum:: ARKODE_MRIType This may take any of the following constants: - * :index:`MRISTEP_EXPLICIT` -- indicates an MRI-GARK method that + * :enumerator:`MRISTEP_EXPLICIT` -- indicates an MRI-GARK method that does not support a slow implicit operator, :math:`f^I`. - * :index:`MRISTEP_IMPLICIT` -- indicates an MRI-GARK method that + * :enumerator:`MRISTEP_IMPLICIT` -- indicates an MRI-GARK method that does not support a slow explicit operator, :math:`f^E`. - * :index:`MRISTEP_IMEX` -- indicates an IMEX-MRK-GARK method. + * :enumerator:`MRISTEP_IMEX` -- indicates an IMEX-MRK-GARK method. - * :index:`MRISTEP_MERK` -- indicates a MERK method, that by definition + * :enumerator:`MRISTEP_MERK` -- indicates a MERK method, that by definition does not support a slow implicit operator, :math:`f^I`. - * :index:`MRISTEP_MRISR` -- indicates an IMEX-MRI-SR method. + * :enumerator:`MRISTEP_MRISR` -- indicates an IMEX-MRI-SR method. The MRI coupling tables themselves are stored in an :c:func:`MRIStepCoupling` object which is a pointer to a @@ -383,14 +383,14 @@ with values specified for each method below (e.g., ``ARKODE_MIS_KW3``). ====================================== ================== =============== ============== ===================== Table name Method Order Embedding Order Slow RHS Calls Reference ====================================== ================== =============== ============== ===================== - :index:`ARKODE_MRI_GARK_FORWARD_EULER` :math:`1^*` 0 1 + :index:`ARKODE_MRI_GARK_FORWARD_EULER` :math:`1^*` -- 1 :index:`ARKODE_MRI_GARK_ERK22a` :math:`2^{\circ}` 1 2 :cite:p:`Sandu:19` :index:`ARKODE_MRI_GARK_ERK22b` :math:`2^*` 1 2 :cite:p:`Sandu:19` - :index:`ARKODE_MRI_GARK_RALSTON2` 2 0 2 :cite:p:`Roberts:22` + :index:`ARKODE_MRI_GARK_RALSTON2` 2 1 2 :cite:p:`Roberts:22` :index:`ARKODE_MERK21` 2 1 2 :cite:p:`Luan:20` - :index:`ARKODE_MIS_KW3` :math:`3^*` 0 3 :cite:p:`Schlegel:09` + :index:`ARKODE_MIS_KW3` :math:`3^*` -- 3 :cite:p:`Schlegel:09` :index:`ARKODE_MRI_GARK_ERK33a` :math:`3^{\circ}` 2 3 :cite:p:`Sandu:19` - :index:`ARKODE_MRI_GARK_RALSTON3` 3 0 3 :cite:p:`Roberts:22` + :index:`ARKODE_MRI_GARK_RALSTON3` 3 -- 3 :cite:p:`Roberts:22` :index:`ARKODE_MERK32` 3 2 3 :cite:p:`Luan:20` :index:`ARKODE_MRI_GARK_ERK45a` :math:`4^{*\circ}` 3 5 :cite:p:`Sandu:19` :index:`ARKODE_MERK43` 4 3 6 :cite:p:`Luan:20` @@ -408,9 +408,9 @@ with values specified for each method below (e.g., ``ARKODE_MIS_KW3``). ========================================== ================== =============== =============== ================== Table name Method Order Embedding Order Implicit Solves Reference ========================================== ================== =============== =============== ================== - :index:`ARKODE_MRI_GARK_BACKWARD_EULER` :math:`1^{*\circ}` 0 1 + :index:`ARKODE_MRI_GARK_BACKWARD_EULER` :math:`1^{*\circ}` -- 1 :index:`ARKODE_MRI_GARK_IRK21a` :math:`2^{*\circ}` 1 1 :cite:p:`Sandu:19` - :index:`ARKODE_MRI_GARK_IMPLICIT_MIDPOINT` 2 0 2 + :index:`ARKODE_MRI_GARK_IMPLICIT_MIDPOINT` 2 -- 2 :index:`ARKODE_MRI_GARK_ESDIRK34a` :math:`3^{*\circ}` 2 3 :cite:p:`Sandu:19` :index:`ARKODE_MRI_GARK_ESDIRK46a` :math:`4^{*\circ}` 3 5 :cite:p:`Sandu:19` ========================================== ================== =============== =============== ================== @@ -426,13 +426,13 @@ with values specified for each method below (e.g., ``ARKODE_MIS_KW3``). ========================================= ================= =============== =============== =================== Table name Method Order Embedding Order Implicit Solves Reference ========================================= ================= =============== =============== =================== - :index:`ARKODE_IMEX_MRI_GARK_EULER` :math:`1^*` 0 1 - :index:`ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL` :math:`2^*` 0 1 - :index:`ARKODE_IMEX_MRI_GARK_MIDPOINT` 2 0 2 + :index:`ARKODE_IMEX_MRI_GARK_EULER` :math:`1^*` -- 1 + :index:`ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL` :math:`2^*` -- 1 + :index:`ARKODE_IMEX_MRI_GARK_MIDPOINT` 2 -- 2 :index:`ARKODE_IMEX_MRI_SR21` :math:`2^{\circ}` 1 3 :cite:p:`Fish:24` - :index:`ARKODE_IMEX_MRI_GARK3a` :math:`3^*` 0 2 :cite:p:`ChiRen:21` - :index:`ARKODE_IMEX_MRI_GARK3b` 3 0 2 :cite:p:`ChiRen:21` + :index:`ARKODE_IMEX_MRI_GARK3a` :math:`3^*` -- 2 :cite:p:`ChiRen:21` + :index:`ARKODE_IMEX_MRI_GARK3b` 3 -- 2 :cite:p:`ChiRen:21` :index:`ARKODE_IMEX_MRI_SR32` :math:`3^{\circ}` 2 4 :cite:p:`Fish:24` - :index:`ARKODE_IMEX_MRI_GARK4` :math:`4^*` 0 5 :cite:p:`ChiRen:21` + :index:`ARKODE_IMEX_MRI_GARK4` :math:`4^*` -- 5 :cite:p:`ChiRen:21` :index:`ARKODE_IMEX_MRI_SR43` :math:`4^{\circ}` 3 5 :cite:p:`Fish:24` ========================================= ================= =============== =============== =================== diff --git a/doc/arkode/guide/source/Usage/MRIStep/User_callable.rst b/doc/arkode/guide/source/Usage/MRIStep/User_callable.rst index 5df668e962..cbfdb19e4f 100644 --- a/doc/arkode/guide/source/Usage/MRIStep/User_callable.rst +++ b/doc/arkode/guide/source/Usage/MRIStep/User_callable.rst @@ -815,7 +815,7 @@ Optional inputs for IVP method selection Select the default MRI method of a given order. - The default order is 3. An order less than 1 or greater than 4 will result in + The default order is 3. An order less than 1 will result in using the default. :param arkode_mem: pointer to the MRIStep memory block. diff --git a/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst b/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst index 3ac3add4e6..8d1158a778 100644 --- a/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst +++ b/doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst @@ -260,7 +260,7 @@ note these requirements below. Additionally, we note the behavior of the base SU .. note:: - If the current [slow] time scale has relative tolerance :math:`rtol`, then the + If the current time scale has relative tolerance :math:`rtol`, then the next-faster time scale will be called with relative tolerance :math:`tolfac * rtol`. Usage: @@ -277,11 +277,6 @@ note these requirements below. Additionally, we note the behavior of the base SU :param C: the :c:type:`SUNAdaptController` object. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_Reset(C); .. c:function:: SUNErrCode SUNAdaptController_SetDefaults(SUNAdaptController C) @@ -290,11 +285,6 @@ note these requirements below. Additionally, we note the behavior of the base SU :param C: the :c:type:`SUNAdaptController` object. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_SetDefaults(C); .. c:function:: SUNErrCode SUNAdaptController_Write(SUNAdaptController C, FILE* fptr) @@ -304,11 +294,6 @@ note these requirements below. Additionally, we note the behavior of the base SU :param fptr: the output stream to write the parameters to. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_Write(C, stdout); .. c:function:: SUNErrCode SUNAdaptController_SetErrorBias(SUNAdaptController C, sunrealtype bias) @@ -321,11 +306,6 @@ note these requirements below. Additionally, we note the behavior of the base SU the default value for the controller. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_SetErrorBias(C, 1.2); .. c:function:: SUNErrCode SUNAdaptController_UpdateH(SUNAdaptController C, sunrealtype h, sunrealtype dsm) @@ -340,11 +320,6 @@ note these requirements below. Additionally, we note the behavior of the base SU :param dsm: the successful temporal error estimate. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_UpdateH(C, h, dsm); .. c:function:: SUNErrCode SUNAdaptController_UpdateMRITol(SUNAdaptController C, sunrealtype H, sunrealtype tolfac, sunrealtype DSM, sunrealtype dsm) @@ -361,11 +336,6 @@ note these requirements below. Additionally, we note the behavior of the base SU :param dsm: the successful fast temporal error estimate. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_UpdateMRITol(C, H, tolfac, DSM, dsm); .. c:function:: SUNErrCode SUNAdaptController_Space(SUNAdaptController C, long int *lenrw, long int *leniw) @@ -380,11 +350,6 @@ note these requirements below. Additionally, we note the behavior of the base SU `long int` words. :return: :c:type:`SUNErrCode` indicating success or failure. - Usage: - - .. code-block:: c - - retval = SUNAdaptController_Space(C, &lenrw, &leniw); diff --git a/doc/shared/sunadaptcontroller/SUNAdaptController_MRIHTol.rst b/doc/shared/sunadaptcontroller/SUNAdaptController_MRIHTol.rst index 56678205bb..de17e2d3ab 100644 --- a/doc/shared/sunadaptcontroller/SUNAdaptController_MRIHTol.rst +++ b/doc/shared/sunadaptcontroller/SUNAdaptController_MRIHTol.rst @@ -32,7 +32,7 @@ results from two types of error: #. "Slow" temporal errors introduced at the current time scale, .. math:: - \varepsilon^s_{n} = C(t_n) \left(h_n^s\right)^P, + \varepsilon^s_{n} = C(t_n) \left(h_n^s\right)^{P+1}, :label: slow_error_assumption where :math:`C(t)` is independent of the current time scale step size :math:`h^s` @@ -60,7 +60,7 @@ results from two types of error: :math:`\kappa(t_n) = c(t_n) \text{reltol}^s \left(t_{F,i}-t_{0,i}\right)` is independent of the relative tolerance factor, :math:`\text{tolfac}_n^f`. -Single-rate controllers are constructed to adapt a single order parameter, e.g., +Single-rate controllers are constructed to adapt a single parameter, e.g., :math:`\delta`, under an assumption that solution error :math:`\varepsilon` depends asymptotically on this parameter via the form @@ -69,7 +69,7 @@ asymptotically on this parameter via the form Both :eq:`slow_error_assumption` and :eq:`inner_solver_assumption` fit this form, with control parameters :math:`h^s` and :math:`\text{tolfac}^f_n`, and "orders" -:math:`P` and :math:`1`, respectively. Thus an MRIHTol controller employs +:math:`P` and :math:`0`, respectively. Thus an MRIHTol controller employs *HControl* to adapt :math:`h_n^s` to control the current time scale error :math:`\varepsilon^s_n`, and it employs *TolControl* to adapt :math:`\text{tolfac}_n^f` to control the accumulated inner solver error @@ -140,11 +140,6 @@ also provides the following additional user-callable routines: :return: if successful, a usable :c:type:`SUNAdaptController` object; otherwise it will return ``NULL``. - Usage: - - .. code-block:: c - - SUNAdaptController C = SUNAdaptController_MRIHTol(sunctx, HControl, TolControl); .. c:function:: SUNErrCode SUNAdaptController_SetParams_MRIHTol(SUNAdaptController C, sunrealtype inner_max_relch, sunrealtype inner_min_tolfac, sunrealtype inner_max_tolfac) @@ -157,9 +152,3 @@ also provides the following additional user-callable routines: :param inner_min_tolfac: the parameter :math:`\text{tolfac}_{min}`. :param inner_max_tolfac: the parameter :math:`\text{tolfac}_{max}`. :return: :c:type:`SUNErrCode` indicating success or failure. - - Usage: - - .. code-block:: c - - retval = SUNAdaptController_SetParams_MRIHTol(C, 20.0, 1e-5, 1.0);