Merge branch 'feature/arkode-sts' of github.com:LLNL/sundials into fe…

…ature/arkode-sts

doc/arkode/guide/source/Mathematics.rst

@@ -737,12 +737,12 @@ LSRKStep -- Low-Storage Runge--Kutta methods
 ============================================
 
 The LSRKStep time-stepping module in ARKODE supports a variety of so-called
-"low-storage" Runge--Kutta methods.  This category includes traditional explicit 
-fixed-step and low-storage RK methods, adaptive and mixed implicit-explicit 
-low-storage RK methods, and others.  These are characterized by coefficient tables
+"low-storage" Runge--Kutta methods, :cite:p:`VSH:04, MBA:14, K:08, FCS:22`.  This category includes traditional explicit 
+fixed-step and low-storage Runge--Kutta methods, adaptive  
+low-storage Runge--Kutta methods, and others.  These are characterized by coefficient tables
 that have an exploitable structure, such that their implementation does not require
 that all stages be stored simultaneously.  At present, this module supports explicit, 
-adaptive "super-time-stepping (STS)" and "strong-stability-preserving (SSP)" methods.
+adaptive "super-time-stepping" (STS) and "strong-stability-preserving" (SSP) methods.
 
 The LSRK time-stepping module in ARKODE currently supports IVP
 of the form :eq:`ARKODE_IVP_simple_explicit`, i.e., unlike the more general problem form :eq:`ARKODE_IMEX_IVP`, LSRKStep
@@ -751,7 +751,7 @@ and that the right-hand side function is not split into separate
 components.
 
 LSRKStep currently supports two families of second-order, explicit, and temporally adaptive STS methods: 
-Runge--Kutta--Chebyshev (RKC) and Runge--Kutta--Legendre (RKL).   These methods have the form
+Runge--Kutta--Chebyshev (RKC), :cite:p:`VSH:04` and Runge--Kutta--Legendre (RKL), :cite:p:`MBA:14`.   These methods have the form
 
 .. math::
    z_0 &= y_n,\\
@@ -760,17 +760,19 @@ Runge--Kutta--Chebyshev (RKC) and Runge--Kutta--Legendre (RKL).   These methods
    y_{n+1} &= z_s.
    :label: ARKODE_RKC_RKL
 
-The corresponding coefficients can be found in :cite:p:`VSH:04, MBA:14`, respectively.
+The corresponding coefficients can be found in :cite:p:`VSH:04` and :cite:p:`MBA:14`, respectively.
 
 LSRK methods of STS type are designed for stiff problems characterized by 
 having Jacobians with eigenvalues that have large real and small imaginary parts. 
 While those problems are traditionally treated using implicit methods, STS methods
 are explicit.  To achieve stability for these stiff problems, STS methods use more stages than 
-conventional Runge-Kutta (RK) methods to extend the stability region along the negative 
+conventional Runge-Kutta methods to extend the stability region along the negative 
 real axis. The extent of this stability region is proportional to the square of the number 
 of stages used.
 
-The SSPRK methods in ARKODE use the following Shu and Osher representation of explicit RK methods:
+LSRK methods of the SSP type are designed to preserve the so-called "strong-stability" properties of advection-type equations. 
+For details, see :cite:p:`K:08`.
+The SSPRK methods in ARKODE use the following Shu--Osher representation :cite:p:`SO:88` of explicit Runge--Kutta methods:
 
 .. math::
    z_1 &= y_n,\\
@@ -781,10 +783,7 @@ The SSPRK methods in ARKODE use the following Shu and Osher representation of ex
 In particular, the methods SSP(s,2), SSP(s,3), and SSP(10,4) implemented herein and presented in 
 :cite:p:`K:08` have "almost" all zero coefficients appearing in :math:`\alpha_{i,i-1}` and 
 :math:`\beta_{i,i-1}`. This feature facilitates their implementation in a low-storage manner. The 
-corresponding coefficients and embedding weights can be found in :cite:p:`K:08` and 
-:cite:p:`FCS:22`, respectively.
-
-LSRK methods of the SSP type are designed to preserve the so-called "strong-stability" properties of advection-type equations. For details, see :cite:p:`K:08`.
+corresponding coefficients and embedding weights can be found in :cite:p:`K:08` and :cite:p:`FCS:22`, respectively.
 
 .. _ARKODE.Mathematics.Error.Norm:
 

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

@@ -2321,7 +2321,7 @@ Optional inputs for matrix-based ``SUNLinearSolver`` modules
       * *ARKLS_SUCCESS*  if successful
       * *ARKLS_MEM_NULL*  if the ARKStep memory was ``NULL``
       * *ARKLS_MASSMEM_NULL* if the mass matrix solver memory was ``NULL``
-      * *ARKLS_ILL_INPUT* if an argument has an illegal value
+      * *ARKLS_ILL_INPUT* if an argument had an illegal value
 
    **Notes:**
       This routine must be called after the ARKLS mass matrix

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

@@ -98,7 +98,7 @@ Allowable Method Families
 
    Specifies the dominant eigenvalue approximation routine to
    be used for determining the number of stages that will be used by either the
-   Runge--Kutta--Chebyshev or Runge--Kutta--Legendre methods.
+   RKC or RKL methods.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
@@ -109,13 +109,13 @@ Allowable Method Families
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
       * *ARK_ILL_INPUT* ``dom_eig = NULL`` and LSRKStep does not currently estimate this internally.
 
-   .. note:: This function is currently required when either the RKC or RKL methods are used; it is ignored when using SSPRK methods.
+   .. note:: This function is currently required when either the RKC or RKL methods are used.
 
 
 .. c:function:: int LSRKStepSetDomEigFrequency(void* arkode_mem, int nsteps);
 
    Specifies the number of steps after which the dominant eigenvalue information is
-   considered out-of-date, and should be recomputed.
+   considered out-of-date, and should be recomputed. This only applies to RKL and RKC methods.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
@@ -127,51 +127,51 @@ Allowable Method Families
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``nsteps < 0``)
 
 
-.. c:function:: int LSRKStepSetMaxNumStages(void* arkode_mem, int stagemaxlimit);
+.. c:function:: int LSRKStepSetMaxNumStages(void* arkode_mem, int stage_max_limit);
 
    Specifies the maximum number of stages allowed within each time step.  This bound only applies to
-   RKL and RKC methods, and any inputs are ignored for SSPRK methods.
+   RKL and RKC methods.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *stagemaxlimit* -- maximum allowed number of stages :math:`(>1)`.
+      * *stage_max_limit* -- maximum allowed number of stages :math:`(>1)`.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
-      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``stagemaxlimit < 2``)
+      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``stage_max_limit < 2``)
 
 
-.. c:function:: int LSRKStepSetDomEigSafetyFactor(void* arkode_mem, sunrealtype domeigsfty);
+.. c:function:: int LSRKStepSetDomEigSafetyFactor(void* arkode_mem, sunrealtype dom_eig_sfty);
 
-   Specifies a safety factor to use for the result of the dominant eigenvalue estimation function.  This value is used to scale the magnitude of the dominant eigenvalue, in the hope of ensuring a sufficient number of stages for the method to be stable.  This input is only used for RKC and RKL methods, and is ignored by SSPRK methods.
+   Specifies a safety factor to use for the result of the dominant eigenvalue estimation function.  This value is used to scale the magnitude of the dominant eigenvalue, in the hope of ensuring a sufficient number of stages for the method to be stable.  This input is only used for RKC and RKL methods.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *domeigsfty* -- safety factor :math:`(\ge 1)`.
+      * *dom_eig_sfty* -- safety factor :math:`(\ge 1)`.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
-      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``domeigsfty < 1``)
+      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``dom_eig_sfty < 1``)
 
 
-.. c:function:: int LSRKStepSetSSPStageNum(void* arkode_mem, int numofstages);
+.. c:function:: int LSRKStepSetSSPStageNum(void* arkode_mem, int num_of_stages);
 
-   Sets the number of stages, ``s`` in ``SSP(s, p)`` methods.  This input is ignored by RKC and RKL methods.
+   Sets the number of stages, ``s`` in ``SSP(s, p)`` methods. This input is only utilized by SSPRK methods.
 
-      * ``ARKODE_LSRK_SSP_S_2``  -- ``numofstages`` must be greater than or equal to 2
-      * ``ARKODE_LSRK_SSP_S_3``  -- ``numofstages`` must be a perfect-square greater than or equal to 9
-      * ``ARKODE_LSRK_SSP_10_4`` -- ``numofstages`` cannot be modified from 10, so this function should not be called.
+      * ``ARKODE_LSRK_SSP_S_2``  -- ``num_of_stages`` must be greater than or equal to 2
+      * ``ARKODE_LSRK_SSP_S_3``  -- ``num_of_stages`` must be a perfect-square greater than or equal to 9
+      * ``ARKODE_LSRK_SSP_10_4`` -- ``num_of_stages`` cannot be modified from 10, so this function should not be called.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *numofstages* -- number of stages :math:`(>1)` for ``SSP(s,2)`` and :math:`(n^2 = s \geq 9)` for ``SSP(s,3)``.
+      * *num_of_stages* -- number of stages :math:`(>1)` for ``SSP(s,2)`` and :math:`(n^2 = s \geq 9)` for ``SSP(s,3)``.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
-      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``numofstages < 2``)
+      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. ``num_of_stages < 2``)
 
 
 .. _ARKODE.Usage.LSRKStep.OptionalOutputs:
@@ -195,39 +195,39 @@ Optional output functions
       * *ARK_MEM_NULL* if the LSRKStep memory was ``NULL``
 
 
-.. c:function:: int LSRKStepGetNumDomEigUpdates(void* arkode_mem, long int* ndomeigupdates);
+.. c:function:: int LSRKStepGetNumDomEigUpdates(void* arkode_mem, long int* num_dom_eig_updates);
 
    Returns the number of dominant eigenvalue evaluations (so far).
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *ndomeigupdates* -- number of calls to the user's ``dom_eig`` function.
+      * *num_dom_eig_updates* -- number of calls to the user's ``dom_eig`` function.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARK_MEM_NULL* if the LSRKStep memory was ``NULL``
 
 
-.. c:function:: int LSRKStepGetMaxNumStages(void* arkode_mem, int* stagemax);
+.. c:function:: int LSRKStepGetMaxNumStages(void* arkode_mem, int* stage_max);
 
-   Returns the max number of stages taken in any single step (so far).
+   Returns the max number of stages used in any single step (so far).
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *stagemax* -- max number of stages taken.
+      * *stage_max* -- max number of stages used.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARK_MEM_NULL* if the LSRKStep memory was ``NULL``
 
 
-.. c:function:: int LSRKStepGetAverageStageNum(void* arkode_mem, sunrealtype* averstage);
+.. c:function:: int LSRKStepGetAverageStageNum(void* arkode_mem, sunrealtype* avg_stage);
 
    Returns the average number of stages per step (so far).
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *averstage* -- average number of stages.
+      * *avg_stage* -- average number of stages.
 
    **Return value:**
       * *ARK_SUCCESS* if successful

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

@@ -227,7 +227,7 @@ Optional inputs for SPRKStep
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. note::
 
@@ -262,7 +262,7 @@ Optional inputs for SPRKStep
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory or interpolation module are ``NULL``
    :retval ARK_INTERP_FAIL: if this is called after :c:func:`SPRKStepEvolve()`
-   :retval ARK_ILL_INPUT: if an argument has an illegal value or the
+   :retval ARK_ILL_INPUT: if an argument had an illegal value or the
                           interpolation module has already been initialized
 
    .. note::
@@ -298,7 +298,7 @@ Optional inputs for SPRKStep
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. deprecated:: 6.1.0
 
@@ -321,7 +321,7 @@ Optional inputs for SPRKStep
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. deprecated:: 6.1.0
 
@@ -348,7 +348,7 @@ Optional inputs for SPRKStep
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. deprecated:: 6.1.0
 
@@ -386,7 +386,7 @@ Optional inputs for SPRKStep
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. deprecated:: 6.1.0
 
@@ -430,7 +430,7 @@ Optional inputs for IVP method selection
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. warning::
 
@@ -451,7 +451,7 @@ Optional inputs for IVP method selection
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. note::
 
@@ -472,7 +472,7 @@ Optional inputs for IVP method selection
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. warning::
 
@@ -494,7 +494,7 @@ Optional inputs for IVP method selection
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
 
 
@@ -522,7 +522,7 @@ Rootfinding optional input functions
 
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
-   :retval ARK_ILL_INPUT: if an argument has an illegal value
+   :retval ARK_ILL_INPUT: if an argument had an illegal value
 
    .. deprecated:: 6.1.0
 
@@ -942,7 +942,7 @@ the RHS function should not incorporate the discontinuity.
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL:  if the SPRKStep memory was ``NULL``
    :retval ARK_MEM_FAIL:  if a memory allocation failed
-   :retval ARK_ILL_INPUT: if an argument has an illegal value.
+   :retval ARK_ILL_INPUT: if an argument had an illegal value.
 
 
 .. _ARKODE.Usage.SPRKStep.Reset:
@@ -968,7 +968,7 @@ SPRKStep reset function
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL:  if the SPRKStep memory was ``NULL``
    :retval ARK_MEM_FAIL:  if a memory allocation failed
-   :retval ARK_ILL_INPUTL: if an argument has an illegal value.
+   :retval ARK_ILL_INPUTL: if an argument had an illegal value.
 
    .. note::
 

doc/shared/sundials.bib

@@ -2410,3 +2410,14 @@ @article{FCS:22
 issn = {0377-0427},
 doi = {https://doi.org/10.1016/j.cam.2022.114325},
 author = {Imre Fekete and Sidafa Conde and John N. Shadid}}
+
+@article{SO:88,
+title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},
+journal={Journal of computational physics}, 
+volume={77},
+number={2},
+pages={439--471},
+year={1988},
+publisher={Elsevier},
+doi={10.1016/0021-9991(88)90177-5},
+author={Shu, Chi-Wang and Osher, Stanley}}