SetSTS and SetSSP methods

benchmarks/diffusion_2D/main_arkode.cpp

@@ -335,8 +335,8 @@ int main(int argc, char* argv[])
     else // Configure explicit STS solver
     {
       // Select LSRK method
-      flag = LSRKStepSetMethod(arkode_mem, uopts.lsrkmethod);
-      if (check_flag(&flag, "LSRKStepSetMethod", 1)) { return 1; }
+      flag = LSRKStepSetSTSMethod(arkode_mem, uopts.lsrkmethod);
+      if (check_flag(&flag, "LSRKStepSetSTSMethod", 1)) { return 1; }
 
       // Provide dominant eigenvalue function
       flag = LSRKStepSetDomEigFn(arkode_mem, dom_eig);

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

@@ -83,9 +83,9 @@ Optional input functions
 -------------------------
 
 
-.. c:function:: int LSRKStepSetMethod(void* arkode_mem, ARKODE_LSRKMethodType method);
+.. c:function:: int LSRKStepSetSTSMethod(void* arkode_mem, ARKODE_LSRKMethodType method);
 
-   This function selects the LSRK method that should be used.  The list of allowable 
+   This function selects the LSRK STS method that should be used.  The list of allowable 
    values for this input is below.
 
    **Arguments:**
@@ -96,7 +96,25 @@ Optional input functions
       * *ARK_SUCCESS* if successful
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method type).
 
-   .. note:: If this routine is not called, then LSRKStep will use the Runge--Kutta--Chebyshev method by default.
+   .. note:: If one of these set method routines is not called, then LSRKStep will use the 
+      :c:enumerator:`ARKODE_LSRK_RKC_2` by default.
+
+
+.. c:function:: int LSRKStepSetSSPMethod(void* arkode_mem, ARKODE_LSRKMethodType method);
+
+   This function selects the LSRK SSP method that should be used.  The list of allowable 
+   values for this input is below.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the LSRKStep memory block.
+      * *method* -- Type of the method.
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method type).
+
+   .. note:: If one of these set method routines is not called, then LSRKStep will use the 
+      :c:enumerator:`ARKODE_LSRK_SSP_S_2` by default.
 
 
 Allowable Method Families
@@ -124,9 +142,25 @@ Allowable Method Families
       Fourth order, 10-stage SSP(10,4) method
 
 
-.. c:function:: int LSRKStepSetMethodByName(void* arkode_mem, const char* emethod);
+.. c:function:: int LSRKStepSetSTSMethodByName(void* arkode_mem, const char* emethod);
+
+   This function selects the LSRK STS method by name.  The list of allowable values for this input is above.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the LSRKStep memory block.
+      * *emethod* -- Type of the method in strings.
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method type).
+
+   .. note:: If one of these set method routines is not called, then LSRKStep will use the 
+      :c:enumerator:`ARKODE_LSRK_RKC_2` by default.
+
+
+.. c:function:: int LSRKStepSetSSPMethodByName(void* arkode_mem, const char* emethod);
 
-   This function selects the LSRK method by name.  The list of allowable values for this input is below.
+   This function selects the LSRK SSP method by name.  The list of allowable values for this input is above.
 
    **Arguments:**
       * *arkode_mem* -- pointer to the LSRKStep memory block.
@@ -137,7 +171,7 @@ Allowable Method Families
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method type).
 
    .. note:: If one of these set method routines is not called, then LSRKStep will use the 
-      Runge--Kutta--Chebyshev method by default.
+      :c:enumerator:`ARKODE_LSRK_SSP_S_2` by default.
 
 
 .. c:function:: int LSRKStepSetDomEigFn(void* arkode_mem, ARKDomEigFn dom_eig);
@@ -214,7 +248,7 @@ Allowable Method Families
 .. 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 only utilized by SSPRK methods. Thus, 
-   this set routine must be called after calling :c:func:`LSRKStepSetMethod` with an SSPRK method.
+   this set routine must be called after calling :c:func:`LSRKStepSetSSPMethod` with an SSPRK method.
 
    * :c:enumerator:`ARKODE_LSRK_SSP_S_2`  -- ``num_of_stages`` must be greater than or equal to 2
    * :c:enumerator:`ARKODE_LSRK_SSP_S_3`  -- ``num_of_stages`` must be a perfect-square greater than or equal to 4

examples/arkode/CXX_manyvector/ark_sod_lsrk.cpp

@@ -106,8 +106,8 @@ int main(int argc, char* argv[])
     if (check_ptr(arkode_mem, "LSRKStepCreateSSP")) { return 1; }
 
     // Select SSPRK method type
-    flag = LSRKStepSetMethodByName(arkode_mem, uopts.integrator.c_str());
-    if (check_flag(flag, "LSRKStepSetMethodByName")) { return 1; }
+    flag = LSRKStepSetSSPMethodByName(arkode_mem, uopts.integrator.c_str());
+    if (check_flag(flag, "LSRKStepSetSSPMethodByName")) { return 1; }
 
     // Select number of SSPRK stages
     if (uopts.stages > 0)

examples/arkode/CXX_parallel/ark_heat2D_lsrk_p.cpp

@@ -359,8 +359,8 @@ int main(int argc, char* argv[])
   if (check_flag(&flag, "ARKodeSetUserData", 1)) { return 1; }
 
   // Select LSRK method
-  flag = LSRKStepSetMethod(arkode_mem, udata->method);
-  if (check_flag(&flag, "LSRKStepSetMethod", 1)) { return 1; }
+  flag = LSRKStepSetSTSMethod(arkode_mem, udata->method);
+  if (check_flag(&flag, "LSRKStepSetSTSMethod", 1)) { return 1; }
 
   // Select LSRK spectral radius function and options
   flag = LSRKStepSetDomEigFn(arkode_mem, eig);

examples/arkode/CXX_serial/ark_heat2D_lsrk.cpp

@@ -270,8 +270,8 @@ int main(int argc, char* argv[])
   if (check_flag(&flag, "ARKodeSetUserData", 1)) { return 1; }
 
   // Select LSRK method
-  flag = LSRKStepSetMethod(arkode_mem, udata->method);
-  if (check_flag(&flag, "LSRKStepSetMethod", 1)) { return 1; }
+  flag = LSRKStepSetSTSMethod(arkode_mem, udata->method);
+  if (check_flag(&flag, "LSRKStepSetSTSMethod", 1)) { return 1; }
 
   // Select LSRK spectral radius function and options
   flag = LSRKStepSetDomEigFn(arkode_mem, eig);

examples/arkode/C_serial/ark_analytic_lsrk.c

@@ -155,8 +155,8 @@ int main(void)
   if (check_flag(&flag, "LSRKStepSetDomEigSafetyFactor", 1)) { return 1; }
 
   /* Specify the Runge--Kutta--Legendre LSRK method */
-  flag = LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_RKL_2);
-  if (check_flag(&flag, "LSRKStepSetMethod", 1)) { return 1; }
+  flag = LSRKStepSetSTSMethod(arkode_mem, ARKODE_LSRK_RKL_2);
+  if (check_flag(&flag, "LSRKStepSetSTSMethod", 1)) { return 1; }
 
   /* Open output stream for results, output comment line */
   UFID = fopen("solution.txt", "w");

examples/arkode/C_serial/ark_analytic_lsrk_varjac.c

@@ -179,8 +179,8 @@ int main(void)
   if (check_flag(&flag, "LSRKStepSetDomEigSafetyFactor", 1)) { return 1; }
 
   /* Specify the Runge--Kutta--Chebyshev LSRK method by name */
-  flag = LSRKStepSetMethodByName(arkode_mem, "ARKODE_LSRK_RKC_2");
-  if (check_flag(&flag, "LSRKStepSetMethodByName", 1)) { return 1; }
+  flag = LSRKStepSetSTSMethodByName(arkode_mem, "ARKODE_LSRK_RKC_2");
+  if (check_flag(&flag, "LSRKStepSetSTSMethodByName", 1)) { return 1; }
 
   /* Open output stream for results, output comment line */
   UFID = fopen("solution.txt", "w");

examples/arkode/C_serial/ark_analytic_ssprk.c

@@ -129,8 +129,8 @@ int main(void)
   if (check_flag(&flag, "ARKodeSetMaxNumSteps", 1)) { return 1; }
 
   /* Specify the SSP(s,3) LSRK method */
-  flag = LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_SSP_S_3);
-  if (check_flag(&flag, "LSRKStepSetMethod", 1)) { return 1; }
+  flag = LSRKStepSetSSPMethod(arkode_mem, ARKODE_LSRK_SSP_S_3);
+  if (check_flag(&flag, "LSRKStepSetSSPMethod", 1)) { return 1; }
 
   /* Specify the SSP number of stages */
   flag = LSRKStepSetSSPStageNum(arkode_mem, 9);

include/arkode/arkode_lsrkstep.h

@@ -61,10 +61,16 @@ SUNDIALS_EXPORT int LSRKStepReInitSSP(void* arkode_mem, ARKRhsFn rhs,
 
 /* Optional input functions -- must be called AFTER a creation routine above */
 
-SUNDIALS_EXPORT int LSRKStepSetMethod(void* arkode_mem,
+SUNDIALS_EXPORT int LSRKStepSetSTSMethod(void* arkode_mem,
                                       ARKODE_LSRKMethodType method);
 
-SUNDIALS_EXPORT int LSRKStepSetMethodByName(void* arkode_mem,
+SUNDIALS_EXPORT int LSRKStepSetSSPMethod(void* arkode_mem,
+                                      ARKODE_LSRKMethodType method);
+
+SUNDIALS_EXPORT int LSRKStepSetSTSMethodByName(void* arkode_mem,
+                                            const char* emethod);
+
+SUNDIALS_EXPORT int LSRKStepSetSSPMethodByName(void* arkode_mem,
                                             const char* emethod);
 
 SUNDIALS_EXPORT int LSRKStepSetDomEigFn(void* arkode_mem, ARKDomEigFn dom_eig);

src/arkode/arkode_lsrkstep.c

@@ -39,7 +39,7 @@ void* LSRKStepCreateSTS(ARKRhsFn rhs, sunrealtype t0, N_Vector y0,
   ark_mem = lsrkStep_Create_Commons(rhs, t0, y0, sunctx);
 
   /* set default ARKODE_LSRK_RKC_2 method */
-  retval = LSRKStepSetMethod((void*)ark_mem, ARKODE_LSRK_RKC_2);
+  retval = LSRKStepSetSTSMethod((void*)ark_mem, ARKODE_LSRK_RKC_2);
   if (retval != ARK_SUCCESS)
   {
     lsrkStep_Free(ark_mem);
@@ -59,7 +59,7 @@ void* LSRKStepCreateSSP(ARKRhsFn rhs, sunrealtype t0, N_Vector y0,
   ark_mem = lsrkStep_Create_Commons(rhs, t0, y0, sunctx);
 
   /* set default ARKODE_LSRK_SSP_S_2 method */
-  retval = LSRKStepSetMethod((void*)ark_mem, ARKODE_LSRK_SSP_S_2);
+  retval = LSRKStepSetSSPMethod((void*)ark_mem, ARKODE_LSRK_SSP_S_2);
   if (retval != ARK_SUCCESS)
   {
     lsrkStep_Free(ark_mem);

src/arkode/arkode_lsrkstep_io.c

@@ -28,14 +28,11 @@
   ===============================================================*/
 
 /*---------------------------------------------------------------
-  LSRKStepSetMethod sets method
+  LSRKStepSetSTSMethod sets method
     ARKODE_LSRK_RKC_2
     ARKODE_LSRK_RKL_2
-    ARKODE_LSRK_SSP_S_2
-    ARKODE_LSRK_SSP_S_3
-    ARKODE_LSRK_SSP_10_4
   ---------------------------------------------------------------*/
-int LSRKStepSetMethod(void* arkode_mem, ARKODE_LSRKMethodType method)
+int LSRKStepSetSTSMethod(void* arkode_mem, ARKODE_LSRKMethodType method)
 {
   ARKodeMem ark_mem;
   ARKodeLSRKStepMem step_mem;
@@ -64,6 +61,49 @@ int LSRKStepSetMethod(void* arkode_mem, ARKODE_LSRKMethodType method)
     step_mem->p = ark_mem->hadapt_mem->p = 2;
     step_mem->step_nst                   = 0;
     break;
+  case ARKODE_LSRK_SSP_S_2:
+  case ARKODE_LSRK_SSP_S_3:
+  case ARKODE_LSRK_SSP_10_4:
+    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                    "Invalid method option: Call LSRKStepCreateSSP to create an SSP method first.");
+    break;
+
+  default:
+    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                    "Invalid method option.");
+    return ARK_ILL_INPUT;
+  }
+
+  step_mem->LSRKmethod = method;
+
+  return ARK_SUCCESS;
+}
+
+/*---------------------------------------------------------------
+  LSRKStepSetSSPMethod sets method
+    ARKODE_LSRK_SSP_S_2
+    ARKODE_LSRK_SSP_S_3
+    ARKODE_LSRK_SSP_10_4
+  ---------------------------------------------------------------*/
+
+int LSRKStepSetSSPMethod(void* arkode_mem, ARKODE_LSRKMethodType method)
+{
+  ARKodeMem ark_mem;
+  ARKodeLSRKStepMem step_mem;
+  int retval;
+
+  /* access ARKodeMem and ARKodeLSRKStepMem structures */
+  retval = lsrkStep_AccessARKODEStepMem(arkode_mem, __func__, &ark_mem,
+                                        &step_mem);
+  if (retval != ARK_SUCCESS) { return retval; }
+
+  switch (method)
+  {
+  case ARKODE_LSRK_RKC_2:
+  case ARKODE_LSRK_RKL_2:
+    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                    "Invalid method option: Call LSRKStepCreateSTS to create an STS method first.");
+    break;
   case ARKODE_LSRK_SSP_S_2:
     ark_mem->step          = lsrkStep_TakeStepSSPs2;
     step_mem->is_SSP       = SUNTRUE;
@@ -100,27 +140,46 @@ int LSRKStepSetMethod(void* arkode_mem, ARKODE_LSRKMethodType method)
   return ARK_SUCCESS;
 }
 
-int LSRKStepSetMethodByName(void* arkode_mem, const char* emethod)
+int LSRKStepSetSTSMethodByName(void* arkode_mem, const char* emethod)
 {
   if (strcmp(emethod, "ARKODE_LSRK_RKC_2") == 0)
   {
-    return LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_RKC_2);
+    return LSRKStepSetSTSMethod(arkode_mem, ARKODE_LSRK_RKC_2);
   }
   if (strcmp(emethod, "ARKODE_LSRK_RKL_2") == 0)
   {
-    return LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_RKL_2);
+    return LSRKStepSetSTSMethod(arkode_mem, ARKODE_LSRK_RKL_2);
+  }
+  if ((strcmp(emethod, "ARKODE_LSRK_SSP_S_2") == 0) || (strcmp(emethod, "ARKODE_LSRK_SSP_S_3") == 0) || (strcmp(emethod, "ARKODE_LSRK_SSP_10_4") == 0))
+  {
+    arkProcessError(NULL, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                  "Invalid method option: Call LSRKStepCreateSTS to create an STS method first.");
+  }
+
+  arkProcessError(NULL, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                  "Unknown method type");
+
+  return ARK_ILL_INPUT;
+}
+
+int LSRKStepSetSSPMethodByName(void* arkode_mem, const char* emethod)
+{
+  if ((strcmp(emethod, "ARKODE_LSRK_RKC_2") == 0) || (strcmp(emethod, "ARKODE_LSRK_RKL_2") == 0))
+  {
+    arkProcessError(NULL, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                  "Invalid method option: Call LSRKStepCreateSSP to create an SSP method first."); 
   }
   if (strcmp(emethod, "ARKODE_LSRK_SSP_S_2") == 0)
   {
-    return LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_SSP_S_2);
+    return LSRKStepSetSSPMethod(arkode_mem, ARKODE_LSRK_SSP_S_2);
   }
   if (strcmp(emethod, "ARKODE_LSRK_SSP_S_3") == 0)
   {
-    return LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_SSP_S_3);
+    return LSRKStepSetSSPMethod(arkode_mem, ARKODE_LSRK_SSP_S_3);
   }
   if (strcmp(emethod, "ARKODE_LSRK_SSP_10_4") == 0)
   {
-    return LSRKStepSetMethod(arkode_mem, ARKODE_LSRK_SSP_10_4);
+    return LSRKStepSetSSPMethod(arkode_mem, ARKODE_LSRK_SSP_10_4);
   }
 
   arkProcessError(NULL, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
@@ -266,8 +325,7 @@ int LSRKStepSetDomEigSafetyFactor(void* arkode_mem, sunrealtype dom_eig_safety)
       ARKODE_LSRK_SSP_10_4 -- num_of_stages must be equal to 10 - no need to call!
 
    Sets the number of stages, s in SSP(s, p) methods. This input is only utilized by
-   SSPRK methods. Thus, this set routine must be called after calling LSRKStepSetMethod with an
-   SSPRK method.
+   SSPRK methods. Thus, this set routine must be called after calling LSRKStepSetSSPMethod.
 
    Calling this function with num_of_stages =< 0 resets the default value.
   ---------------------------------------------------------------*/
@@ -286,7 +344,7 @@ int LSRKStepSetSSPStageNum(void* arkode_mem, int num_of_stages)
   {
     arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
                     "Call this function only for SSP methods: Use "
-                    "LSRKStepSetMethod to declare SSP method type first!");
+                    "LSRKStepSetSSPMethod to declare SSP method type first!");
     return ARK_ILL_INPUT;
   }
 
@@ -302,7 +360,7 @@ int LSRKStepSetSSPStageNum(void* arkode_mem, int num_of_stages)
 
     default:
       arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__,
-                      __FILE__, "Call LSRKStepSetMethod to declare SSP method type first!");
+                      __FILE__, "Call LSRKStepSetSSPMethod to declare SSP method type first!");
       return ARK_ILL_INPUT;
       break;
     }
@@ -350,7 +408,7 @@ int LSRKStepSetSSPStageNum(void* arkode_mem, int num_of_stages)
 
     default:
       arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__,
-                      __FILE__, "Call LSRKStepSetMethod to declare SSP method type first!");
+                      __FILE__, "Call LSRKStepSetSSPMethod to declare SSP method type first!");
       return ARK_ILL_INPUT;
       break;
     }