Maintenance/arkode UI

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
+Created shared user interface for ARKODE user-callable routines, to allow more
+uniform control over time-stepping algorithms, improved extensibility, and
+simplified code maintenance.  Marked the corresponding stepper-specific
+user-callable routines as deprecated; these will be removed in a future major
+release.
+
+Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
+
+Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
+for users who wish to retain the current functionality.
+
 Updated the CMake variable `HIP_PLATFORM` default to `amd` as the previous
 default, `hcc`, is no longer recognized in ROCm 5.7.0 or newer. The new default
 is also valid in older version of ROCm (at least back to version 4.3.1).

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

@@ -997,6 +997,148 @@ Optional inputs for ARKStep
       all problems are different, so these values may not be optimal for
       all users.
 
+   .. deprecated:: x.y.z
+
+      Adjust solver parameters individually instead.  For reference, this routine
+      sets the following non-default parameters:
+
+      * Explicit methods:
+
+        * :c:func:`SUNAdaptController_PI` with :c:func:`SUNAdaptController_SetErrorBias` of 1.2 and :c:func:`SUNAdaptController_SetParams_PI` of :math:`k_1=0.8` and :math:`k_2=-0.31`
+
+        * :c:func:`ARKodeSetSafetyFactor` of 0.99
+
+        * :c:func:`ARKodeSetMaxGrowth` of 25.0
+
+        * :c:func:`ARKodeSetMaxEFailGrowth` of 0.3
+
+      * Implicit methods:
+
+        * Order 3:
+
+          * :c:func:`SUNAdaptController_I` with :c:func:`SUNAdaptController_SetErrorBias` of 1.9
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.957
+
+          * :c:func:`ARKodeSetMaxGrowth` of 17.6
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.45
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.22
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.17
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.19
+
+        * Order 4:
+
+          * :c:func:`SUNAdaptController_PID` with :c:func:`SUNAdaptController_SetErrorBias` of 1.2 and :c:func:`SUNAdaptController_SetParams_PID` of :math:`k_1=0.535`, :math:`k_2=-0.209`, and :math:`k_3=0.148`
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.988
+
+          * :c:func:`ARKodeSetMaxGrowth` of 31.5
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.33
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.24
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.26
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.16
+
+          * :c:func:`ARKodeSetLSetupFrequency` of 31
+
+        * Order 5:
+
+          * :c:func:`SUNAdaptController_PID` with :c:func:`SUNAdaptController_SetErrorBias` of 3.3 and :c:func:`SUNAdaptController_SetParams_PID` of :math:`k_1=0.56`, :math:`k_2=-0.338`, and :math:`k_3=0.14`
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.937
+
+          * :c:func:`ARKodeSetMaxGrowth` of 22.0
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.44
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.25
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.4
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.32
+
+          * :c:func:`ARKodeSetLSetupFrequency` of 31
+
+      * ImEx methods:
+
+        * Order 2:
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.001
+
+          * :c:func:`ARKodeSetMaxNonlinIters` of 5
+
+        * Order 3:
+
+          * :c:func:`SUNAdaptController_PID` with :c:func:`SUNAdaptController_SetErrorBias` of 1.42 and :c:func:`SUNAdaptController_SetParams_PID` of :math:`k_1=0.54`, :math:`k_2=-0.36`, and :math:`k_3=0.14`
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.965
+
+          * :c:func:`ARKodeSetMaxGrowth` of 28.7
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.46
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.22
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.17
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.19
+
+          * :c:func:`ARKodeSetLSetupFrequency` of 60
+
+        * Order 4:
+
+          * :c:func:`SUNAdaptController_PID` with :c:func:`SUNAdaptController_SetErrorBias` of 1.35 and :c:func:`SUNAdaptController_SetParams_PID` of :math:`k_1=0.543`, :math:`k_2=-0.297`, and :math:`k_3=0.14`
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.97
+
+          * :c:func:`ARKodeSetMaxGrowth` of 25.0
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.47
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.24
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.26
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.16
+
+          * :c:func:`ARKodeSetLSetupFrequency` of 31
+
+        * Order 5:
+
+          * :c:func:`SUNAdaptController_PI` with :c:func:`SUNAdaptController_SetErrorBias` of 1.15 and :c:func:`SUNAdaptController_SetParams_PI` of :math:`k_1=0.8` and :math:`k_2=-0.35`
+
+          * :c:func:`ARKodeSetSafetyFactor` of 0.993
+
+          * :c:func:`ARKodeSetMaxGrowth` of 28.5
+
+          * :c:func:`ARKodeSetMaxEFailGrowth` of 0.3
+
+          * :c:func:`ARKodeSetNonlinConvCoef` of 0.25
+
+          * :c:func:`ARKodeSetNonlinCRDown` of 0.4
+
+          * :c:func:`ARKodeSetNonlinRDiv` of 2.3
+
+          * :c:func:`ARKodeSetDeltaGammaMax` of 0.32
+
+          * :c:func:`ARKodeSetLSetupFrequency` of 31
 
 
 .. c:function:: int ARKStepSetConstraints(void* arkode_mem, N_Vector constraints)
@@ -4030,8 +4172,10 @@ General usability functions
       for this pointer, since tables for all processes would be
       identical.
 
+   .. deprecated:: x.y.z
 
-
+      Use :c:func:`ARKStepGetCurrentButcherTables` and :c:func:`ARKodeButcherTable_Write`
+      instead.
 
 
 

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

@@ -217,9 +217,6 @@ Optional input functions
 Optional inputs for SPRKStep
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _ARKODE.Usage.SPRKStep.SPRKStepInputTable:
-.. table:: Optional inputs for SPRKStep
-
 
 .. c:function:: int SPRKStepSetDefaults(void* arkode_mem)
 

doc/shared/RecentChanges.rst

@@ -1,5 +1,16 @@
 **New Features**
 
+Created shared user interface for ARKODE user-callable routines, to allow more
+uniform control over time-stepping algorithms, improved extensibility, and
+simplified code maintenance.  Marked the corresponding stepper-specific
+user-callable routines as deprecated; these will be removed in a future major
+release.
+
+Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
+
+Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
+for users who wish to retain the current functionality.
+
 Added CMake infrastructure that enables externally maintained addons/plugins
 to be *optionally* built with SUNDIALS. See :ref:`Contributing` for details.
 

include/arkode/arkode_arkstep.h

@@ -108,14 +108,15 @@ int ARKStepRootInit(void* arkode_mem, int nrtfn, ARKRootFn g);
 /* Optional input functions -- must be called AFTER ARKStepCreate */
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetDefaults instead")
 int ARKStepSetDefaults(void* arkode_mem);
-SUNDIALS_EXPORT int ARKStepSetOptimalParams(void* arkode_mem);
+SUNDIALS_DEPRECATED_EXPORT_MSG("adjust parameters individually instead")
+int ARKStepSetOptimalParams(void* arkode_mem);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetOrder instead")
 int ARKStepSetOrder(void* arkode_mem, int maxord);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantType instead")
 int ARKStepSetInterpolantType(void* arkode_mem, int itype);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int ARKStepSetInterpolantDegree(void* arkode_mem, int degree);
-SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetDenseOrder instead")
+SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int ARKStepSetDenseOrder(void* arkode_mem, int dord);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetNonlinearSolver instead")
 int ARKStepSetNonlinearSolver(void* arkode_mem, SUNNonlinearSolver NLS);
@@ -331,7 +332,9 @@ char* ARKStepGetReturnFlagName(long int flag);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeWriteParameters instead")
 int ARKStepWriteParameters(void* arkode_mem, FILE* fp);
 
-SUNDIALS_EXPORT int ARKStepWriteButcher(void* arkode_mem, FILE* fp);
+SUNDIALS_DEPRECATED_EXPORT_MSG(
+  "use ARKStepGetCurrentButcherTables and ARKodeButcherTable_Write instead")
+int ARKStepWriteButcher(void* arkode_mem, FILE* fp);
 
 /* Grouped optional output functions */
 SUNDIALS_EXPORT int ARKStepGetTimestepperStats(

include/arkode/arkode_erkstep.h

@@ -80,7 +80,7 @@ SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantType instead")
 int ERKStepSetInterpolantType(void* arkode_mem, int itype);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int ERKStepSetInterpolantDegree(void* arkode_mem, int degree);
-SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetDenseOrder instead")
+SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int ERKStepSetDenseOrder(void* arkode_mem, int dord);
 SUNDIALS_EXPORT int ERKStepSetTable(void* arkode_mem, ARKodeButcherTable B);
 SUNDIALS_EXPORT int ERKStepSetTableNum(void* arkode_mem,

include/arkode/arkode_mristep.h

@@ -170,7 +170,7 @@ SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantType instead")
 int MRIStepSetInterpolantType(void* arkode_mem, int itype);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int MRIStepSetInterpolantDegree(void* arkode_mem, int degree);
-SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetDenseOrder instead")
+SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetInterpolantDegree instead")
 int MRIStepSetDenseOrder(void* arkode_mem, int dord);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetNonlinearSolver instead")
 int MRIStepSetNonlinearSolver(void* arkode_mem, SUNNonlinearSolver NLS);
@@ -223,8 +223,8 @@ SUNDIALS_EXPORT int MRIStepSetPostInnerFn(void* arkode_mem,
                                           MRIStepPostInnerFn postfn);
 SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetStagePredictFn instead")
 int MRIStepSetStagePredictFn(void* arkode_mem, ARKStagePredictFn PredictStage);
-SUNDIALS_EXPORT int MRIStepSetDeduceImplicitRhs(void* arkode_mem,
-                                                sunbooleantype deduce);
+SUNDIALS_DEPRECATED_EXPORT_MSG("use ARKodeSetDeduceImplicitRhs instead")
+int MRIStepSetDeduceImplicitRhs(void* arkode_mem, sunbooleantype deduce);
 
 /* Linear solver interface optional input functions -- must be called
    AFTER MRIStepSetLinearSolver */

src/arkode/arkode.c

@@ -120,14 +120,15 @@ ARKodeMem arkCreate(SUNContext sunctx)
   ark_mem->step_setnonlinconvcoef         = NULL;
   ark_mem->step_setstagepredictfn         = NULL;
   ark_mem->step_getnumlinsolvsetups       = NULL;
+  ark_mem->step_getestlocalerrors         = NULL;
   ark_mem->step_getcurrentgamma           = NULL;
   ark_mem->step_getnonlinearsystemdata    = NULL;
   ark_mem->step_getnumnonlinsolviters     = NULL;
   ark_mem->step_getnumnonlinsolvconvfails = NULL;
   ark_mem->step_getnonlinsolvstats        = NULL;
   ark_mem->step_mem                       = NULL;
   ark_mem->step_supports_adaptive         = SUNFALSE;
-  ark_mem->step_supports_algebraic        = SUNFALSE;
+  ark_mem->step_supports_implicit         = SUNFALSE;
   ark_mem->step_supports_massmatrix       = SUNFALSE;
   ark_mem->step_supports_relaxation       = SUNFALSE;
 
@@ -558,6 +559,7 @@ int ARKodeWFtolerances(void* arkode_mem, ARKEwtFn efun)
     return (ARK_MEM_NULL);
   }
   ark_mem = (ARKodeMem)arkode_mem;
+
   if (ark_mem->MallocDone == SUNFALSE)
   {
     arkProcessError(ark_mem, ARK_NO_MALLOC, __LINE__, __func__, __FILE__,
@@ -611,9 +613,9 @@ int ARKodeResStolerance(void* arkode_mem, sunrealtype rabstol)
   /* Guard against use for time steppers that do not support mass matrices */
   if (!ark_mem->step_supports_massmatrix)
   {
-    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__,
+    arkProcessError(ark_mem, ARK_STEPPER_UNSUPPORTED, __LINE__, __func__,
                     __FILE__, "time-stepping module does not support non-identity mass matrices");
-    return (ARK_ILL_INPUT);
+    return (ARK_STEPPER_UNSUPPORTED);
   }
 
   /* Check inputs */
@@ -676,9 +678,9 @@ int ARKodeResVtolerance(void* arkode_mem, N_Vector rabstol)
   /* Guard against use for time steppers that do not support mass matrices */
   if (!ark_mem->step_supports_massmatrix)
   {
-    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__,
+    arkProcessError(ark_mem, ARK_STEPPER_UNSUPPORTED, __LINE__, __func__,
                     __FILE__, "time-stepping module does not support non-identity mass matrices");
-    return (ARK_ILL_INPUT);
+    return (ARK_STEPPER_UNSUPPORTED);
   }
 
   /* Check inputs */
@@ -761,9 +763,9 @@ int ARKodeResFtolerance(void* arkode_mem, ARKRwtFn rfun)
   /* Guard against use for time steppers that do not support mass matrices */
   if (!ark_mem->step_supports_massmatrix)
   {
-    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__,
+    arkProcessError(ark_mem, ARK_STEPPER_UNSUPPORTED, __LINE__, __func__,
                     __FILE__, "time-stepping module does not support non-identity mass matrices");
-    return (ARK_ILL_INPUT);
+    return (ARK_STEPPER_UNSUPPORTED);
   }
 
   if (ark_mem->MallocDone == SUNFALSE)

src/arkode/arkode_arkstep.c

@@ -132,12 +132,13 @@ void* ARKStepCreate(ARKRhsFn fe, ARKRhsFn fi, sunrealtype t0, N_Vector y0,
   ark_mem->step_setstagepredictfn         = arkStep_SetStagePredictFn;
   ark_mem->step_getnumlinsolvsetups       = arkStep_GetNumLinSolvSetups;
   ark_mem->step_getcurrentgamma           = arkStep_GetCurrentGamma;
+  ark_mem->step_getestlocalerrors         = arkStep_GetEstLocalErrors;
   ark_mem->step_getnonlinearsystemdata    = arkStep_GetNonlinearSystemData;
   ark_mem->step_getnumnonlinsolviters     = arkStep_GetNumNonlinSolvIters;
   ark_mem->step_getnumnonlinsolvconvfails = arkStep_GetNumNonlinSolvConvFails;
   ark_mem->step_getnonlinsolvstats        = arkStep_GetNonlinSolvStats;
   ark_mem->step_supports_adaptive         = SUNTRUE;
-  ark_mem->step_supports_algebraic        = SUNTRUE;
+  ark_mem->step_supports_implicit         = SUNTRUE;
   ark_mem->step_supports_massmatrix       = SUNTRUE;
   ark_mem->step_supports_relaxation       = SUNTRUE;
   ark_mem->step_mem                       = (void*)step_mem;

src/arkode/arkode_arkstep_impl.h

@@ -202,6 +202,7 @@ int arkStep_SetMaxNonlinIters(ARKodeMem ark_mem, int maxcor);
 int arkStep_SetNonlinConvCoef(ARKodeMem ark_mem, sunrealtype nlscoef);
 int arkStep_SetStagePredictFn(ARKodeMem ark_mem, ARKStagePredictFn PredictStage);
 int arkStep_SetDeduceImplicitRhs(ARKodeMem ark_mem, sunbooleantype deduce);
+int arkStep_GetEstLocalErrors(ARKodeMem ark_mem, N_Vector ele);
 int arkStep_GetCurrentGamma(ARKodeMem ark_mem, sunrealtype* gamma);
 int arkStep_GetNonlinearSystemData(ARKodeMem ark_mem, sunrealtype* tcur,
                                    N_Vector* zpred, N_Vector* z, N_Vector* Fi,

src/arkode/arkode_arkstep_io.c

@@ -2024,6 +2024,25 @@ int arkStep_GetCurrentGamma(ARKodeMem ark_mem, sunrealtype* gamma)
   return (retval);
 }
 
+/*---------------------------------------------------------------
+  arkStep_GetEstLocalErrors: Returns the current local truncation
+  error estimate vector
+  ---------------------------------------------------------------*/
+int arkStep_GetEstLocalErrors(ARKodeMem ark_mem, N_Vector ele)
+{
+  int retval;
+  ARKodeARKStepMem step_mem;
+  retval = arkStep_AccessStepMem(ark_mem, __func__, &step_mem);
+  if (retval != ARK_SUCCESS) { return (retval); }
+
+  /* return an error if local truncation error is not computed */
+  if (ark_mem->fixedstep) { return (ARK_STEPPER_UNSUPPORTED); }
+
+  /* otherwise, copy local truncation error vector to output */
+  N_VScale(ONE, ark_mem->tempv1, ele);
+  return (ARK_SUCCESS);
+}
+
 /*---------------------------------------------------------------
   ARKStepGetNumRhsEvals:
 

src/arkode/arkode_erkstep.c

@@ -102,6 +102,7 @@ void* ERKStepCreate(ARKRhsFn f, sunrealtype t0, N_Vector y0, SUNContext sunctx)
   ark_mem->step_setdefaults         = erkStep_SetDefaults;
   ark_mem->step_setrelaxfn          = erkStep_SetRelaxFn;
   ark_mem->step_setorder            = erkStep_SetOrder;
+  ark_mem->step_getestlocalerrors   = erkStep_GetEstLocalErrors;
   ark_mem->step_supports_adaptive   = SUNTRUE;
   ark_mem->step_supports_relaxation = SUNTRUE;
   ark_mem->step_mem                 = (void*)step_mem;

src/arkode/arkode_erkstep_impl.h

@@ -82,6 +82,7 @@ int erkStep_Resize(ARKodeMem ark_mem, N_Vector y0, sunrealtype hscale,
                    sunrealtype t0, ARKVecResizeFn resize, void* resize_data);
 void erkStep_Free(ARKodeMem ark_mem);
 void erkStep_PrintMem(ARKodeMem ark_mem, FILE* outfile);
+int erkStep_GetEstLocalErrors(ARKodeMem ark_mem, N_Vector ele);
 
 /* Internal utility routines */
 int erkStep_AccessARKODEStepMem(void* arkode_mem, const char* fname,