Documentation for LSRKStep

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### New Features and Enhancements
 
+Added low storage Runge--Kutta module, LSRKStep, to ARKODE.
+
 ### Bug Fixes
 
 Fixed the loading of ARKStep's default first order explicit method.

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

@@ -57,10 +57,11 @@ LSRKStep initialization functions
 
    **Return value:**
       If successful, a pointer to initialized problem memory
-      of type ``void*``, to be passed to all user-facing ERKStep routines
+      of type ``void*``, to be passed to all user-facing LSRKStep routines
       listed below.  If unsuccessful, a ``NULL`` pointer will be
       returned, and an error message will be printed to ``stderr``.
 
+   .. warning: LSRK module cannot support implicit treatment yet. fi function is there as a space holder for future releases.
 
 .. _ARKODE.Usage.LSRKStep.OptionalInputs:
 
@@ -74,13 +75,21 @@ Optional input functions
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
-      * *method* -- Type of the method: ``ARKODE_LSRK_RKC`` or ``ARKODE_LSRK_RKL``
+      * *method* -- Type of the method.
 
    **Return value:**
       * *ARK_SUCCESS* if successful
       * *ARK_ILL_INPUT* if an argument has an illegal value (e.g. typo in the method type).
 
 
+Allowable Method Families
+
+.. c:enum:: ARKODE_LSRKMethodType
+
+   * ``ARKODE_LSRK_RKC`` -- Runge--Kutta--Chebyshev
+   * ``ARKODE_LSRK_RKL`` -- Runge--Kutta--Legendre
+   * ``ARKODE_LSRK_RKG`` -- Runge--Kutta--Gegenbauer
+
 .. c:function:: int LSRKStepSetDomEigFn(void* arkode_mem, ARKDomEigFn DomEig);
 
    Specifies the Dominant Eigenvalue approximation routine to
@@ -266,7 +275,7 @@ vector.
    LSRKStep time-stepper module.
 
    **Arguments:**
-      * *arkode_mem* -- pointer to the ERKStep memory block.
+      * *arkode_mem* -- pointer to the LSRKStep memory block.
       * *fe* -- the name of the C function (of type :c:func:`ARKRhsFn()`)
         defining the explicit right-hand side function in :math:`\dot{y} = f^E(t,y)`.
       * *fi* -- the name of the C function (of type :c:func:`ARKRhsFn()`)

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

@@ -0,0 +1,48 @@
+.. ----------------------------------------------------------------
+   Programmer(s): Daniel R. Reynolds @ SMU
+                  David J. Gardner @ LLNL
+   ----------------------------------------------------------------
+   SUNDIALS Copyright Start
+   Copyright (c) 2002-2024, Lawrence Livermore National Security
+   and Southern Methodist University.
+   All rights reserved.
+
+   See the top-level LICENSE and NOTICE files for details.
+
+   SPDX-License-Identifier: BSD-3-Clause
+   SUNDIALS Copyright End
+   ----------------------------------------------------------------
+
+.. _LSRKSTEP.Usage.UserSupplied:
+
+User-supplied functions
+=============================
+
+The user-supplied functions for LSRKStep consist of:
+
+* at least one function :ref:`defining the dominant eigenvalue of the RHS <LSRKStep.Usage.DomEig>`
+  (required),
+
+
+
+
+.. _LSRKStep.Usage.DomEig:
+
+The dominant eigenvalue estimation
+----------------------------------
+
+The user must supply one dominant eigenvalue function of type :c:type:`ARKDomEigFn`:
+
+.. c:type:: int (*ARKDomEigFn)(sunrealtype* t, N_Vector y, sunrealtype* lambdaR, sunrealtype* lambdaI, void* user_data)
+
+   These functions compute the dominant eigenvalue of the Jacobian of the ODE right-hand side for a given
+   value of the independent variable :math:`t` and state vector :math:`y`.
+
+   :param t: the current value of the independent variable.
+   :param y: the current value of the dependent variable vector.
+   :param lambdaR: The real part of the dominant eigenvalue.
+   :param lambdaI: The imaginary part of the dominant eigenvalue.   
+   :param user_data: the `user_data` pointer that was passed to
+                     :c:func:`ARKodeSetUserData`.
+
+   :return: An *ARKDomEigFn* should return 0 if successful and any nonzero for a failure.

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

@@ -28,3 +28,5 @@ are specific to LSRKStep.
    :maxdepth: 1
 
    User_callable
+   User_supplied
+

doc/shared/RecentChanges.rst

@@ -2,6 +2,8 @@
 
 **New Features and Enhancements**
 
+Added low storage Runge--Kutta module, :ref:`LSRKStep <ARKODE.Usage.LSRKStep>`, to ARKODE. 
+
 **Bug Fixes**
 
 Fixed the loading of ARKStep's default first order explicit method.

include/arkode/arkode.h

@@ -140,6 +140,8 @@ extern "C" {
 
 #define ARK_STEPPER_UNSUPPORTED -48
 
+#define ARK_DOMEIG_FAIL -49
+
 #define ARK_UNRECOGNIZED_ERROR -99
 
 /* ------------------------------

src/arkode/arkode_io.c

@@ -2853,6 +2853,7 @@ char* ARKodeGetReturnFlagName(long int flag)
   case ARK_RELAX_JAC_FAIL: sprintf(name, "ARK_RELAX_JAC_FAIL"); break;
   case ARK_CONTROLLER_ERR: sprintf(name, "ARK_CONTROLLER_ERR"); break;
   case ARK_STEPPER_UNSUPPORTED: sprintf(name, "ARK_STEPPER_UNSUPPORTED"); break;
+  case ARK_DOMEIG_FAIL: sprintf(name, "ARK_DOMEIG_FAIL"); break;  
   case ARK_UNRECOGNIZED_ERROR: sprintf(name, "ARK_UNRECOGNIZED_ERROR"); break;
   default: sprintf(name, "NONE");
   }

src/arkode/arkode_lsrkstep.c

@@ -602,6 +602,7 @@ int lsrkStep_TakeStepRKC(ARKodeMem ark_mem, sunrealtype* dsmPtr, int* nflagPtr)
   if ((step_mem->newdomeig))
   {
     retval = lsrkStep_ComputeNewDomEig(ark_mem, step_mem);
+    if (retval != ARK_SUCCESS) { return (retval); }
     step_mem->ndomeigupdates++;
   }
 
@@ -794,6 +795,7 @@ int lsrkStep_TakeStepRKL(ARKodeMem ark_mem, sunrealtype* dsmPtr, int* nflagPtr)
   if ((step_mem->newdomeig))
   {
     retval = lsrkStep_ComputeNewDomEig(ark_mem, step_mem);
+    if (retval != ARK_SUCCESS) { return (retval); }
     step_mem->ndomeigupdates++;
   }
 
@@ -1001,6 +1003,13 @@ int lsrkStep_ComputeNewDomEig(ARKodeMem ark_mem, ARKodeLSRKStepMem step_mem)
   if ((step_mem->isextDomEig))
   {
     retval = step_mem->extDomEig(ark_mem->tn, &step_mem->lambdaR, &step_mem->lambdaI, ark_mem->user_data);
+    if (retval != ARK_SUCCESS)
+    {
+      arkProcessError(ark_mem, ARK_DOMEIG_FAIL, __LINE__, __func__, __FILE__,
+                     "Unable to estimate the dominant eigenvalue");
+      return (ARK_DOMEIG_FAIL);
+    }
+
     if(step_mem->lambdaR*ark_mem->h > ZERO)
     {
       printf("\nlambdaR*h must be nonpositive\n");