Feature/fes tstop adaptivity

CHANGELOG.md

@@ -8,6 +8,13 @@
 
 Updated `examples/cvode/petsc/cv_petsc_ex7.c` to support PETSc 3.25.0.
 
+Added the function `ARKodeSkipAdaptStopTime` to specify that
+stop-time-limited steps should be disregarded when selecting step sizes
+for time step adaptivity.  Added the functions `CVodeSkipAdaptStopTime`
+and `IDASkipAdaptStopTime` to specify that stop-time-limited steps should
+be disregarded when adapting the step size and method order for CVODE(S)
+and IDA(S), respectively.
+
 ### Bug Fixes
 
 Fixed memory leaks in CVODES, IDAS, and KINSOL in the unlikely event of a failed
@@ -108,6 +115,37 @@ Fixed a bug where passing an empty string to
 corresponding logging stream ([Issue
 #844](https://github.com/llnl/sundials/issues/844)).
 
+Fixed a bug in logging output from ARKODE, where for some time stepping modules,
+the current "time" output in the logger was incorrect.
+
+Fixed a bug in the ARKODE discrete adjoint checkpointing where an incorrect
+state would be stored on the first step if the output vector passed to
+`ARKodeEvolve` did not contain the initial condition on the first call.
+
+Fixed a bug in MRIStep when using a custom inner integrator that relies on the
+input state being the initial condition for the fast integration rather than
+retaining the result from the last inner integration or most recent reset call
+and the output vector passed to `ARKodeEvolve` does not contain the initial
+condition on the first call or the last returned solution on subsequent calls.
+
+Removed an extraneous copy of the output vector in each step with SplittingStep.
+
+Added a missing call to `SUNNonlinSolSetup` in MRIStep when using an
+IMEX-MRI-SR method.
+
+Fixed a potential bug in LSRKStep's `ARKODE_LSRK_SSP_S_3` method, where a real
+number was used instead of an integer, potentially resulting in a rounding error.
+
+Fixed a bug in LSRKStep where an incorrect state vector could be passed to a
+user-supplied dominant eigenvalue function on the first step unless the output
+vector passed to `ARKodeEvolve` contained the initial condition and when an
+eigenvalue estimate is requested on the first step in a subsequent call to
+`ARKodeEvolve` unless the output vector passed contained the most recently returned
+solution.
+
+Fixed a bug in MRIStep for estimating the first "slow" time step in an adaptive
+multirate calculation.
+
 ### Deprecation Notices
 
 The `CVodeSetMonitorFn` and `CVodeSetMonitorFrequency` functions have been
@@ -117,7 +155,7 @@ Several CMake options have been deprecated in favor of namespaced versions
 prefixed with `SUNDIALS_` to avoid naming collisions in applications that
 include SUNDIALS directly within their CMake builds. Additionally, a consistent
 naming convention (`SUNDIALS_ENABLE`) is now used for all boolean options. The
-table below lists the old CMake option names and the new replacements.
+Removed an extraneous copy of the output vector in each step with SplittingStep.
 
 | Old Option                              | New Option                                     |
 |-----------------------------------------|------------------------------------------------|

bindings/sundials4py/arkode/arkode_generated.hpp

@@ -203,6 +203,9 @@ m.def("ARKodeSetStopTime", ARKodeSetStopTime, nb::arg("arkode_mem"),
 
 m.def("ARKodeClearStopTime", ARKodeClearStopTime, nb::arg("arkode_mem"));
 
+m.def("ARKodeSkipAdaptStopTime", ARKodeSkipAdaptStopTime, nb::arg("arkode_mem"),
+      nb::arg("skipadapttstop"));
+
 m.def("ARKodeSetFixedStep", ARKodeSetFixedStep, nb::arg("arkode_mem"),
       nb::arg("hfixed"));
 

bindings/sundials4py/cvodes/cvodes_generated.hpp

@@ -166,6 +166,9 @@ m.def("CVodeSetInterpolateStopTime", CVodeSetInterpolateStopTime,
 
 m.def("CVodeClearStopTime", CVodeClearStopTime, nb::arg("cvode_mem"));
 
+m.def("CVodeSkipAdaptStopTime", CVodeSkipAdaptStopTime, nb::arg("cvode_mem"),
+      nb::arg("skipadapttstop"));
+
 m.def("CVodeSetEtaFixedStepBounds", CVodeSetEtaFixedStepBounds,
       nb::arg("cvode_mem"), nb::arg("eta_min_fx"), nb::arg("eta_max_fx"));
 

bindings/sundials4py/idas/idas_generated.hpp

@@ -117,6 +117,9 @@ m.def("IDASetStopTime", IDASetStopTime, nb::arg("ida_mem"), nb::arg("tstop"));
 
 m.def("IDAClearStopTime", IDAClearStopTime, nb::arg("ida_mem"));
 
+m.def("IDASkipAdaptStopTime", IDASkipAdaptStopTime, nb::arg("ida_mem"),
+      nb::arg("skipadapttstop"));
+
 m.def("IDASetMaxErrTestFails", IDASetMaxErrTestFails, nb::arg("ida_mem"),
       nb::arg("maxnef"));
 

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

@@ -905,6 +905,7 @@ Minimum absolute step size                         :c:func:`ARKodeSetMinStep`
 Set a value for :math:`t_{stop}`                   :c:func:`ARKodeSetStopTime`                 undefined
 Interpolate at :math:`t_{stop}`                    :c:func:`ARKodeSetInterpolateStopTime`      ``SUNFALSE``
 Disable the stop time                              :c:func:`ARKodeClearStopTime`               N/A
+Disregard stop time limited steps in adaptivity    :c:func:`ARKodeSkipAdaptStopTime`           ``SUNFALSE``
 Supply a pointer for user data                     :c:func:`ARKodeSetUserData`                 ``NULL``
 Maximum no. of ARKODE error test failures          :c:func:`ARKodeSetMaxErrTestFails`          7
 Set inequality constraints on solution             :c:func:`ARKodeSetConstraints`              ``NULL``
@@ -1466,6 +1467,30 @@ Use compensated summation for accumulating time    :c:func:`ARKodeSetUseCompensa
    .. versionadded:: 6.1.0
 
 
+.. c:function:: int ARKodeSkipAdaptStopTime(void* arkode_mem, sunbooleantype skip)
+
+   Specifies whether stop-time-limited steps should be disregarded
+   when selecting step sizes for time step adaptivity.
+
+   :param arkode_mem: pointer to the ARKODE memory block.
+   :param skip: flag indicating to disregard (1) or retain (0) stop time
+                limited steps from the temporal adaptivity algorithm.
+
+   :retval ARK_SUCCESS: the function exited successfully.
+   :retval ARK_MEM_NULL: ``arkode_mem`` was ``NULL``.
+
+   .. note::
+
+      The default behavior is to use all successful time steps
+      (including stop-time-limited steps) when determining an
+      adapted time step size.
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.skip_adapt_stop_time".
+
+   .. versionadded:: x.y.z
+
+
 .. c:function:: int ARKodeSetUserData(void* arkode_mem, void* user_data)
 
    Specifies the user data block *user_data* and

doc/cvode/guide/source/Usage/index.rst

@@ -864,6 +864,9 @@ Main solver optional input functions
    +-------------------------------+---------------------------------------------+----------------+
    | Disable the stop time         | :c:func:`CVodeClearStopTime`                | N/A            |
    +-------------------------------+---------------------------------------------+----------------+
+   | Disregard stop time limited   | :c:func:`CVodeSkipAdaptStopTime`            | ``SUNFALSE``   |
+   | steps in adaptivity           |                                             |                |
+   +-------------------------------+---------------------------------------------+----------------+
    | Maximum no. of error test     | :c:func:`CVodeSetMaxErrTestFails`           | 7              |
    | failures                      |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
@@ -1207,6 +1210,28 @@ Main solver optional input functions
 
    .. versionadded:: 6.5.1
 
+.. c:function:: int CVodeSkipAdaptStopTime(void* cvode_mem, sunbooleantype skip)
+
+   Specifies whether stop-time-limited steps should be disregarded
+   when adapting step sizes and method order.
+
+   **Arguments:**
+      * ``cvode_mem`` -- pointer to the CVODE memory block.
+      * ``skip`` -- flag indicating to disregard (1) or retain (0) stop time limited steps from the temporal adaptivity algorithm.
+
+   **Return value:**
+      * ``CV_SUCCESS`` if successful
+      * ``CV_MEM_NULL`` if the CVODE memory is ``NULL``
+
+   **Notes:**
+      The default behavior is to use all successful time steps
+      (including stop-time-limited steps) when performing adaptivity.
+
+      This routine will be called by :c:func:`CVodeSetOptions`
+      when using the key "cvid.skip_adapt_stop_time".
+
+   .. versionadded:: x.y.z
+
 .. c:function:: int CVodeSetMaxErrTestFails(void* cvode_mem, int maxnef)
 
    The function ``CVodeSetMaxErrTestFails`` specifies the  maximum number of error test failures permitted in attempting one step.

doc/cvodes/guide/source/Usage/SIM.rst

@@ -873,6 +873,9 @@ Main solver optional input functions
    +-------------------------------+---------------------------------------------+----------------+
    | Disable the stop time         | :c:func:`CVodeClearStopTime`                | N/A            |
    +-------------------------------+---------------------------------------------+----------------+
+   | Disregard stop time limited   | :c:func:`CVodeSkipAdaptStopTime`            | ``SUNFALSE``   |
+   | steps in adaptivity           |                                             |                |
+   +-------------------------------+---------------------------------------------+----------------+
    | Maximum no. of error test     | :c:func:`CVodeSetMaxErrTestFails`           | 7              |
    | failures                      |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
@@ -1213,6 +1216,28 @@ Main solver optional input functions
 
    .. versionadded:: 6.5.1
 
+.. c:function:: int CVodeSkipAdaptStopTime(void* cvode_mem, sunbooleantype skip)
+
+   Specifies whether stop-time-limited steps should be disregarded
+   when adapting step sizes and method order.
+
+   **Arguments:**
+      * ``cvode_mem`` -- pointer to the CVODE memory block.
+      * ``skip`` -- flag indicating to disregard (1) or retain (0) stop time limited steps from the temporal adaptivity algorithm.
+
+   **Return value:**
+      * ``CV_SUCCESS`` if successful
+      * ``CV_MEM_NULL`` if the CVODE memory is ``NULL``
+
+   **Notes:**
+      The default behavior is to use all successful time steps
+      (including stop-time-limited steps) when performing adaptivity.
+
+      This routine will be called by :c:func:`CVodeSetOptions`
+      when using the key "cvid.skip_adapt_stop_time".
+
+   .. versionadded:: x.y.z
+
 .. c:function:: int CVodeSetMaxErrTestFails(void* cvode_mem, int maxnef)
 
    The function ``CVodeSetMaxErrTestFails`` specifies the  maximum number of error test failures permitted in attempting one step.

doc/ida/guide/source/Usage/index.rst

@@ -931,6 +931,8 @@ Main solver optional input functions
    +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Disable the stop time                                              | :c:func:`IDAClearStopTime`            | N/A            |
    +--------------------------------------------------------------------+---------------------------------------+----------------+
+   | Disregard stop time limited steps in adaptivity                    | :c:func:`IDASkipAdaptStopTime`        | ``SUNFALSE``   |
+   +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Maximum no. of error test failures                                 | :c:func:`IDASetMaxErrTestFails`       | 10             |
    +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Suppress alg. vars. from error test                                | :c:func:`IDASetSuppressAlg`           | ``SUNFALSE``   |
@@ -1189,6 +1191,28 @@ Main solver optional input functions
 
    .. versionadded:: 6.5.1
 
+.. c:function:: int IDASkipAdaptStopTime(void* ida_mem, sunbooleantype skip)
+
+   Specifies whether stop-time-limited steps should be disregarded
+   when adapting step sizes and method order.
+
+   **Arguments:**
+      * ``ida_mem`` -- pointer to the IDA memory block.
+      * ``skip`` -- flag indicating to disregard (1) or retain (0) stop time limited steps from the temporal adaptivity algorithm.
+
+   **Return value:**
+      * ``IDA_SUCCESS`` if successful
+      * ``IDA_MEM_NULL`` if the IDA memory is ``NULL``
+
+   **Notes:**
+      The default behavior is to use all successful time steps
+      (including stop-time-limited steps) when performing adaptivity.
+
+      This routine will be called by :c:func:`IDASetOptions`
+      when using the key "idaid.skip_adapt_stop_time".
+
+   .. versionadded:: x.y.z
+
 .. c:function:: int IDASetMaxErrTestFails(void * ida_mem, int maxnef)
 
    The function ``IDASetMaxErrTestFails`` specifies the maximum number of error

doc/idas/guide/source/Usage/SIM.rst

@@ -936,6 +936,8 @@ Main solver optional input functions
    +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Disable the stop time                                              | :c:func:`IDAClearStopTime`            | N/A            |
    +--------------------------------------------------------------------+---------------------------------------+----------------+
+   | Disregard stop time limited steps in adaptivity                    | :c:func:`IDASkipAdaptStopTime`        | ``SUNFALSE``   |
+   +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Maximum no. of error test failures                                 | :c:func:`IDASetMaxErrTestFails`       | 10             |
    +--------------------------------------------------------------------+---------------------------------------+----------------+
    | Suppress alg. vars. from error test                                | :c:func:`IDASetSuppressAlg`           | ``SUNFALSE``   |
@@ -1194,6 +1196,28 @@ Main solver optional input functions
 
    .. versionadded:: 6.5.1
 
+.. c:function:: int IDASkipAdaptStopTime(void* ida_mem, sunbooleantype skip)
+
+   Specifies whether stop-time-limited steps should be disregarded
+   when adapting step sizes and method order.
+
+   **Arguments:**
+      * ``ida_mem`` -- pointer to the IDA memory block.
+      * ``skip`` -- flag indicating to disregard (1) or retain (0) stop time limited steps from the temporal adaptivity algorithm.
+
+   **Return value:**
+      * ``IDA_SUCCESS`` if successful
+      * ``IDA_MEM_NULL`` if the IDA memory is ``NULL``
+
+   **Notes:**
+      The default behavior is to use all successful time steps
+      (including stop-time-limited steps) when performing adaptivity.
+
+      This routine will be called by :c:func:`IDASetOptions`
+      when using the key "idaid.skip_adapt_stop_time".
+
+   .. versionadded:: x.y.z
+
 .. c:function:: int IDASetMaxErrTestFails(void * ida_mem, int maxnef)
 
    The function :c:func:`IDASetMaxErrTestFails` specifies the maximum number of error

doc/shared/RecentChanges.rst

@@ -7,6 +7,13 @@
 
 Updated ``examples/cvode/petsc/cv_petsc_ex7.c`` to support PETSc 3.25.0.
 
+Added the function :c:func:`ARKodeSkipAdaptStopTime` to specify that
+stop-time-limited steps should be disregarded when selecting step sizes
+for time step adaptivity.  Added the functions
+:c:func:`CVodeSkipAdaptStopTime` and :c:func:`IDASkipAdaptStopTime`
+to specify that stop-time-limited steps should be disregarded when
+adapting the step size and method order for CVODE(S) and IDA(S), respectively.
+
 **Bug Fixes**
 
 Fixed memory leaks in CVODES, IDAS, and KINSOL in the unlikely event of a failed

examples/arkode/CXX_serial/CMakeLists.txt

@@ -39,6 +39,7 @@ set(ARKODE_examples
     "ark_kpr_Mt.cpp\;0 4 0 -10 1 10 1\;develop"
     "ark_kpr_Mt.cpp\;0 4 0 -10 0 10 1\;develop"
     "ark_kpr_nestedmri.cpp\;\;exclude-single"
+    "ark_kpr_nestedmri.cpp\;arkfast.skip_adapt_stop_time 1 arkmod.skip_adapt_stop_time 1\;exclude-single"
     "ark_pendulum.cpp\;\;develop")
 
 # Header files to install

examples/arkode/CXX_serial/ark_kpr_nestedmri.cpp

@@ -451,6 +451,8 @@ int main(int argc, char* argv[])
   if (check_flag(retval, "ARKodeSetMaxNumSteps")) return 1;
   retval = ARKodeSetUserData(inner_arkode_mem, (void*)&opts);
   if (check_flag(retval, "ARKodeSetUserData")) return 1;
+  retval = ARKodeSetOptions(inner_arkode_mem, "arkfast", nullptr, argc, argv);
+  if (check_flag(retval, "ARKodeSetOptions")) return 1;
 
   // Create inner stepper
   MRIStepInnerStepper inner_stepper = nullptr;
@@ -873,6 +875,8 @@ int main(int argc, char* argv[])
     retval = ARKodeSetFixedStep(mid_arkode_mem, opts.hm);
     if (check_flag(retval, "ARKodeSetFixedStep")) return 1;
   }
+  retval = ARKodeSetOptions(mid_arkode_mem, "arkmid", nullptr, argc, argv);
+  if (check_flag(retval, "ARKodeSetOptions")) return 1;
 
   // Create intermediate stepper
   MRIStepInnerStepper intermediate_stepper = nullptr;
@@ -931,6 +935,8 @@ int main(int argc, char* argv[])
     retval = ARKodeSetFixedStep(arkode_mem, opts.hs);
     if (check_flag(retval, "ARKodeSetFixedStep")) return 1;
   }
+  retval = ARKodeSetOptions(arkode_mem, "arkslow", nullptr, argc, argv);
+  if (check_flag(retval, "ARKodeSetOptions")) return 1;
 
   //
   // Integrate ODE

examples/arkode/C_serial/ark_analytic.out

@@ -29,6 +29,7 @@ Soderlind SUNAdaptController module:
   previous-previous step = 1
   firststeps = 0
   historysize = 0
+  Skip tstop-limited steps from affecting temporal adaptivity = 0
   Maximum number of error test failures = 7
   Maximum number of convergence test failures = 10
 ARKStep time step module parameters:

examples/arkode/C_serial/ark_analytic_arkode.scalar_tolerances_1e-6_1e-8_arkode.table_names_ARKODE_ESDIRK547L2SA_7_4_5_ARKODE_ERK_NONE.out

@@ -29,6 +29,7 @@ Soderlind SUNAdaptController module:
   previous-previous step = 1
   firststeps = 0
   historysize = 0
+  Skip tstop-limited steps from affecting temporal adaptivity = 0
   Maximum number of error test failures = 7
   Maximum number of convergence test failures = 10
 ARKStep time step module parameters:

examples/cvode/CXX_serial/cv_kpr.cpp

@@ -140,6 +140,12 @@ int main(int argc, char* argv[])
   // Advance in time
   for (int i = 0; i < opts.nout; i++)
   {
+    if (opts.use_tstop)
+    {
+      flag = CVodeSetStopTime(cvode_mem, tout);
+      if (check_flag(flag, "CVodeSetStopTime")) { return 1; }
+    }
+
     flag = CVode(cvode_mem, tout, y, &tret, CV_NORMAL);
     if (check_flag(flag, "CVode")) { return 1; }
 

examples/cvode/CXX_serial/cv_kpr.hpp

@@ -54,6 +54,9 @@ struct Options
   // Finite difference Jacobian
   bool fd_jac = false;
 
+  // Enforce stop time exactly (instead of interpolating)
+  bool use_tstop = false;
+
   // Output options
   sunrealtype dtout = ONE; // output interval
   int nout          = 10;  // number of outputs
@@ -99,6 +102,7 @@ static void InputHelp()
   std::cout << "  --fdjac        : finite-difference Jacobian\n";
   std::cout << "  --dtout        : output interval\n";
   std::cout << "  --nout         : number of outputs\n";
+  std::cout << "  --tstop        : enforce stop time exactly\n";
 }
 
 static int ReadInputs(std::vector<std::string>& args, Options& opts,
@@ -116,6 +120,7 @@ static int ReadInputs(std::vector<std::string>& args, Options& opts,
   find_arg(args, "--fdjac", opts.fd_jac);
   find_arg(args, "--dtout", opts.dtout);
   find_arg(args, "--nout", opts.nout);
+  find_arg(args, "--tstop", opts.use_tstop);
 
   return 0;
 }

include/arkode/arkode.h

@@ -289,6 +289,8 @@ SUNDIALS_EXPORT int ARKodeSetInterpolateStopTime(void* arkode_mem,
                                                  sunbooleantype interp);
 SUNDIALS_EXPORT int ARKodeSetStopTime(void* arkode_mem, sunrealtype tstop);
 SUNDIALS_EXPORT int ARKodeClearStopTime(void* arkode_mem);
+SUNDIALS_EXPORT int ARKodeSkipAdaptStopTime(void* arkode_mem,
+                                            sunbooleantype skipadapttstop);
 SUNDIALS_EXPORT int ARKodeSetFixedStep(void* arkode_mem, sunrealtype hfixed);
 SUNDIALS_EXPORT int ARKodeSetStepDirection(void* arkode_mem, sunrealtype stepdir);
 SUNDIALS_EXPORT int ARKodeSetUserData(void* arkode_mem, void* user_data);