num_of_retries

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

@@ -276,6 +276,24 @@ Optional output functions
       * *ARK_MEM_NULL* if the LSRKStep memory was ``NULL``
 
 
+.. c:function:: LSRKStepGetNumRetiredSteps(void* arkode_mem, long int* num_of_retries);
+
+  Returns the number of retired steps (so far).
+
+  Step retries occur when stepper returns with an ARK_RETRY_STEP flag. This is relevant in situations where 
+  stable results cannot be achieved with the current step size and stage_max_limit. In such cases, the stepper 
+  returns with a recoverable flag before any costly operations, allowing ARKODE to reassign a new contracted 
+  step size to ensure that the required stages remain below the stage_max_limit.
+
+   **Arguments:**
+      * *arkode_mem* -- pointer to the LSRKStep memory block.
+      * *num_of_retries* -- number of retried steps.
+
+   **Return value:**
+      * *ARK_SUCCESS* if successful
+      * *ARK_MEM_NULL* if the LSRKStep memory was ``NULL``
+
+
 .. c:function:: int LSRKStepGetMaxNumStages(void* arkode_mem, int* stage_max);
 
    Returns the max number of stages used in any single step (so far).

examples/arkode/C_serial/ark_analytic_lsrk_varjac.c

@@ -211,11 +211,6 @@ int main(void)
   flag = ARKodePrintAllStats(arkode_mem, FID, SUN_OUTPUTFORMAT_CSV);
   fclose(FID);
 
-  long int* f_evals;
-  LSRKStepGetNumRhsEvals(arkode_mem, 1, &f_evals);
-  printf("f_evals = ", f_evals);
-
-
   /* check the solution error */
   flag = check_ans(y, t, reltol, abstol);
   flag = compute_error(y, t);

src/arkode/arkode_lsrkstep.c

@@ -229,6 +229,8 @@ void lsrkStep_PrintMem(ARKodeMem ark_mem, FILE* outfile)
     fprintf(outfile, "LSRKStep: nfe                   = %li\n", step_mem->nfe);
     fprintf(outfile, "LSRKStep: dom_eig_num_evals     = %li\n",
             step_mem->dom_eig_num_evals);
+    fprintf(outfile, "LSRKStep: num_of_retries        = %li\n",
+            step_mem->num_of_retries);
 
     /* output sunrealtype quantities */
     fprintf(outfile, "LSRKStep: dom_eig               = %f + i%f\n",
@@ -510,6 +512,7 @@ int lsrkStep_TakeStepRKC(ARKodeMem ark_mem, sunrealtype* dsmPtr, int* nflagPtr)
              (onep54 * step_mem->spectral_radius);
       ark_mem->eta = hmax / ark_mem->h;
       *nflagPtr    = ARK_RETRY_STEP;
+      step_mem->num_of_retries++;
       return (ARK_RETRY_STEP);
     }
     else
@@ -784,6 +787,7 @@ int lsrkStep_TakeStepRKL(ARKodeMem ark_mem, sunrealtype* dsmPtr, int* nflagPtr)
              (TWO * step_mem->spectral_radius);
       ark_mem->eta = hmax / ark_mem->h;
       *nflagPtr    = ARK_RETRY_STEP;
+      step_mem->num_of_retries++;
       return (ARK_RETRY_STEP);
     }
     else
@@ -2139,6 +2143,7 @@ void* lsrkStep_Create_Commons(ARKRhsFn rhs, sunrealtype t0, N_Vector y0, SUNCont
   step_mem->nfe               = 0;
   step_mem->stage_max         = 0;
   step_mem->dom_eig_num_evals = 0;
+  step_mem->num_of_retries    = 0;
   step_mem->stage_max_limit = STAGE_MAX_LIMIT;
   step_mem->dom_eig_nst = 0;
   step_mem->is_SSP = SUNFALSE;

src/arkode/arkode_lsrkstep_impl.h

@@ -55,6 +55,7 @@ typedef struct ARKodeLSRKStepMemRec
   /* Counters and stats*/
   long int nfe;               /* num fe calls       */
   long int dom_eig_num_evals; /* num of dom_eig computations   */
+  long int num_of_retries;    /* num retried steps       */
   int stage_max;              /* num of max stages used      */
   int stage_max_limit;        /* max allowed num of stages     */
   int dom_eig_nst; /* num of steps that successfully used dom_eig; indicates dom_eig update when 0;  */

src/arkode/arkode_lsrkstep_io.c

@@ -248,6 +248,12 @@ int LSRKStepSetDomEigSafetyFactor(void* arkode_mem, sunrealtype dom_eig_safety)
 
 /*---------------------------------------------------------------
   LSRKStepSetReTryContractionFactor sets the retry contraction factor for the step size.
+
+  retry_contraction_fac specifies a contraction factor for the next step size after an ARK_RETRY_STEP return. 
+  This is relevant in situations where stable results cannot be achieved with the current step size and stage_max_limit. 
+  In such cases, the stepper returns with a recoverable flag before any costly operations, allowing ARKODE 
+  to reassign a new contracted step size to ensure that the required stages remain below the stage_max_limit.
+
   ---------------------------------------------------------------*/
 int LSRKStepSetReTryContractionFactor(void* arkode_mem, sunrealtype retry_contraction_fac)
 {
@@ -404,6 +410,40 @@ int LSRKStepGetNumDomEigUpdates(void* arkode_mem, long int* dom_eig_num_evals)
   return (ARK_SUCCESS);
 }
 
+/*---------------------------------------------------------------
+  LSRKStepGetNumRetiredSteps:
+
+  Returns the number of retired steps
+
+  Step retries occur when stepper retruns with an ARK_RETRY_STEP flag. This is relevant in situations where 
+  stable results cannot be achieved with the current step size and stage_max_limit. In such cases, the stepper 
+  returns with a recoverable flag before any costly operations, allowing ARKODE to reassign a new contracted 
+  step size to ensure that the required stages remain below the stage_max_limit.
+  ---------------------------------------------------------------*/
+int LSRKStepGetNumRetiredSteps(void* arkode_mem, long int* num_of_retries)
+{
+  ARKodeMem ark_mem;
+  ARKodeLSRKStepMem step_mem;
+  int retval;
+
+  if (num_of_retries == NULL)
+  {
+    arkProcessError(ark_mem, ARK_ILL_INPUT, __LINE__, __func__, __FILE__,
+                    "num_of_retries cannot be NULL");
+    return (ARK_ILL_INPUT);
+  }
+
+  /* access ARKodeMem and ARKodeLSRKStepMem structures */
+  retval = lsrkStep_AccessARKODEStepMem(arkode_mem, __func__, &ark_mem,
+                                        &step_mem);
+  if (retval != ARK_SUCCESS) { return (retval); }
+
+  /* get values from step_mem */
+  *num_of_retries = step_mem->num_of_retries;
+
+  return (ARK_SUCCESS);
+}
+
 /*---------------------------------------------------------------
   LSRKStepGetMaxNumStages:
 
@@ -584,6 +624,8 @@ int lsrkStep_PrintAllStats(ARKodeMem ark_mem, FILE* outfile, SUNOutputFormat fmt
       fprintf(outfile, "RHS fn evals                 = %ld\n", step_mem->nfe);
       fprintf(outfile, "Number of dom_eig updates    = %ld\n",
               step_mem->dom_eig_num_evals);
+      fprintf(outfile, "Number of retried steps      = %ld\n",
+              step_mem->num_of_retries);
       fprintf(outfile, "Avr. num. of stages used     = %.2f\n", avg_stage);
       fprintf(outfile, "Max. num. of stages used     = %d\n", step_mem->stage_max);
       fprintf(outfile, "Max. num. of stages allowed  = %d\n",
@@ -598,6 +640,8 @@ int lsrkStep_PrintAllStats(ARKodeMem ark_mem, FILE* outfile, SUNOutputFormat fmt
       fprintf(outfile, ",RHS fn evals,%ld", step_mem->nfe);
       fprintf(outfile, ",Number of dom_eig update calls,%ld",
               step_mem->dom_eig_num_evals);
+      fprintf(outfile, ",Number of retried steps,%ld",
+              step_mem->num_of_retries);
       fprintf(outfile, ",Avr. num. of stages used,%.2f", avg_stage);
       fprintf(outfile, ",Max. num. of stages used,%d", step_mem->stage_max);
       fprintf(outfile, ",Max. num. of stages allowed,%d",