Bugfix: CVODE(S) Inequality Constraints

CHANGELOG.md

@@ -6,13 +6,29 @@
 
 ### New Features and Enhancements
 
+Added functions to CVODE(S) and IDA(S) to set the maximum number of inequality
+constraint failures in a step attempt (`CVodeSetMaxNumConstraintFails` and
+`IDASetMaxNumConstraintFails`) and to retrieve the total number of failed step
+attempts due to an inequality constraint violation (`CVodeGetNumConstraintFails`
+and `IDAGetNumConstraintFails`). As a result, constraint failures are no longer
+included in the number of step failures due to a solver failure (i.e., the
+values returned by `CVodeGetNumStepSolveFails` and `IDAGetNumStepSolveFails`).
+
 ### Bug Fixes
 
-The SPRKStep module now accounts for zero coefficients in the SPRK tables, eliminating
-extraneous function evaluations.
+Fixed a bug in the CVODE(S) inequality constraint handling where the predicted
+state was used to compute the step size reduction factor which could lead to an
+insufficient reduction in the step size or, when the prediction violates the
+constraints, an infinitely large step size in the next step attempt.
+
+The SPRKStep module now accounts for zero coefficients in the SPRK tables,
+eliminating extraneous function evaluations.
+
+A bug preventing a user supplied `SUNStepper_ResetCheckpointIndex` function from
+being called was fixed.
 
-A bug preventing a user supplied `SUNStepper_ResetCheckpointIndex` function from being
-called was fixed. 
+In CVODES and IDA, added missing return flag names to `CVodeGetReturnFlagName`
+and `IDAGetReturnFlagName`, respectively.
 
 ### Deprecation Notices
 

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

@@ -832,8 +832,8 @@ Main solver optional input functions
    +-------------------------------+---------------------------------------------+----------------+
    |      **Optional input**       |              **Function name**              |  **Default**   |
    +===============================+=============================================+================+
-   | Set CVODE options from the    | :c:func:`CVodeSetOptions`.                  |                |
-   | command line or file          |                                             |                |
+   | Set CVODE options from the    | :c:func:`CVodeSetOptions`                   |                |
+   | command line or a file        |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
    | User data                     | :c:func:`CVodeSetUserData`                  | ``NULL``       |
    +-------------------------------+---------------------------------------------+----------------+
@@ -867,9 +867,12 @@ Main solver optional input functions
    | Maximum no. of error test     | :c:func:`CVodeSetMaxErrTestFails`           | 7              |
    | failures                      |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
-   | Inequality constraints on     | :c:func:`CVodeSetConstraints`               |                |
+   | Inequality constraints on     | :c:func:`CVodeSetConstraints`               | disabled       |
    | solution                      |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
+   | Maximum number of inequality  | :c:func:`CVodeSetMaxNumConstraintFails`     | 10             |
+   | constraint fails in a step    |                                             |                |
+   +-------------------------------+---------------------------------------------+----------------+
    | Flag to activate specialized  | :c:func:`CVodeSetUseIntegratorFusedKernels` | ``SUNFALSE``   |
    | fused kernels                 |                                             |                |
    +-------------------------------+---------------------------------------------+----------------+
@@ -1178,7 +1181,6 @@ Main solver optional input functions
       This routine will be called by :c:func:`CVodeSetOptions`
       when using the key "cvid.interpolate_stop_time".
 
-
    .. versionadded:: 6.6.0
 
 .. c:function:: int CVodeClearStopTime(void* cvode_mem)
@@ -1239,7 +1241,28 @@ Main solver optional input functions
      * ``CV_ILL_INPUT`` -- The constraints vector contains illegal values.
 
    **Notes:**
-      The presence of a non-``NULL`` constraints vector that is not 0.0 in  all components will cause constraint checking to be performed.  However, a call with 0.0 in all components of ``constraints`` will  result in an illegal input return. A ``NULL`` constraints vector will disable  constraint checking.
+      The presence of a non-``NULL`` constraints vector that is not 0.0 in  all
+      components will cause constraint checking to be performed. However, a call
+      with 0.0 in all components of ``constraints`` will  result in an illegal
+      input return. A ``NULL`` constraints vector will disable  constraint
+      checking.
+
+.. c:function:: int CVodeSetMaxNumConstraintFails(void* cvode_mem, int max_fails)
+
+   Sets the maximum number of inequality constraint failures allowed in a step
+   attempt (default 10).
+
+   **Arguments:**
+      * ``cvode_mem`` -- pointer to the CVODE memory block.
+      * ``max_fail`` -- the maximum number of failures. Passing a value
+        :math:`\leq 0` will restore the default value.
+
+   **Return value:**
+     * ``CV_SUCCESS`` -- The optional value has been successfully set.
+     * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a
+       previous call to :c:func:`CVodeCreate`
+
+   .. versionadded:: x.y.z
 
 .. c:function:: int CVodeSetUseIntegratorFusedKernels(void* cvode_mem, sunbooleantype onoff)
 
@@ -2254,12 +2277,16 @@ the rootfinding algorithm.
      * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a previous call to :c:func:`CVodeCreate`.
 
    **Notes:**
-      CVODE will not report the initial conditions as a possible zero-crossing  (assuming that one or more components :math:`g_i` are zero at the initial time).  However, if it appears that some :math:`g_i` is identically zero at the initial  time (i.e., :math:`g_i` is zero at the initial time and after the first step),  CVODE will issue a warning which can be disabled with this optional input  function.
+      CVODES will not report the initial conditions as a possible zero-crossing
+      (assuming that one or more components :math:`g_i` are zero at the initial time).
+      However, if it appears that some :math:`g_i` is identically zero at the initial
+      time (i.e., :math:`g_i` is zero at the initial time and after the first step),
+      CVODES will issue a warning which can be disabled with this optional input
+      function.
 
       This routine will be called by :c:func:`CVodeSetOptions`
       when using the key "cvid.no_inactive_root_warn".
 
-
 .. _CVODE.Usage.CC.optional_input.optin_proj:
 
 Projection optional input functions
@@ -2469,6 +2496,9 @@ the preconditioner.
    | No. of failed steps due to a nonlinear solver   | :c:func:`CVodeGetNumStepSolveFails`      |
    | failure                                         |                                          |
    +-------------------------------------------------+------------------------------------------+
+   | No. of failed steps due to an inequality        | :c:func:`CVodeGetNumConstraintFails`     |
+   | constraint failure                              |                                          |
+   +-------------------------------------------------+------------------------------------------+
    | Order used during the last step                 | :c:func:`CVodeGetLastOrder`              |
    +-------------------------------------------------+------------------------------------------+
    | Order to be attempted on the next step          | :c:func:`CVodeGetCurrentOrder`           |
@@ -2615,7 +2645,6 @@ described next.
       Work space functions will be removed in version 8.0.0.
 
 
-
 .. c:function:: int CVodeGetNumSteps(void* cvode_mem, long int *nsteps)
 
    The function ``CVodeGetNumSteps`` returns the cumulative number of internal  steps taken by the solver (total so far).
@@ -2687,7 +2716,26 @@ described next.
       * ``CV_SUCCESS`` -- The optional output value has been successfully set.
       * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a previous call to :c:func:`CVodeCreate`.
 
+   .. versionchanged:: x.y.z
+
+      In prior versions, inequality constraint failures were included with the
+      number of step failures due to a nonlinear solver failure. These failures
+      are now counted separately, see :c:func:`CVodeGetNumConstraintFails`.
 
+.. c:function:: int CVodeGetNumConstraintFails(void* cvode_mem, long int* num_fails_out)
+
+   Returns the number of failed steps due to an inequality constraint failure.
+
+   **Arguments:**
+      * ``cvode_mem`` -- pointer to the CVODE memory block.
+      * ``num_fails_out`` -- number of step failures.
+
+   **Return value:**
+      * ``CV_SUCCESS`` -- The optional output value has been successfully set.
+      * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a
+        previous call to :c:func:`CVodeCreate`.
+
+   .. versionadded:: x.y.z
 
 .. c:function:: int CVodeGetLastOrder(void* cvode_mem, int *qlast)
 
@@ -2974,7 +3022,6 @@ described next.
       The user is responsible for freeing the returned string.
 
 
-
 .. _CVODE.Usage.CC.optional_output.optout_root:
 
 Rootfinding optional output functions