Bugfix: CVODE(S) Inequality Constraints (#787)

Fix a bug in the CVODE(S) inequality constraint handling where the
predicted state was used to compute the step size reduction factor
instead of the prior solution which could lead to an incorrect reduction
in the step size or, when the prediction violates the constraints, an
infinitely large step size in the next step attempt. (Fixes #702)

Add a unit test for inequality constraint handling with all the
integrators.

In CVODE(S) and IDA(S), separate inequality constraint check from the
nonlinear solve check.

Add functions to set the maximum number of inequality constraint
failures and get total number of failures (constraint failures are no
longer included in the number of step failures due to a solver failure).

Add a function to get the number of steps modified but not failed due to
constraint violations.

Synchronize some differences between CVODE/CVODES and IDA/IDAS source
and docs.

Add missing return flag names to `CVodeGetReturnFlagName` in CVODES and
`IDAGetReturnFlagName` in IDA.

Author: gardner48

CHANGELOG.md

@@ -10,11 +10,31 @@ interfaces to most features of SUNDIALS.
 
 ### 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`).
+The functions `CVodeGetNumConstraintCorrections` and
+`IDAGetNumConstraintCorrections` were also added to retrieve the number of steps
+where the corrector was modified to satisfy an inequality constraint without
+failing the step.
+
 The functions `CVodeGetUserDataB` and `IDAGetUserDataB` were added to CVODES
 and IDAS, respectively.
 
 ### Bug Fixes
 
+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.
+
+In CVODES and IDA, added missing return flag names to `CVodeGetReturnFlagName`
+and `IDAGetReturnFlagName`, respectively.
+
 Fixed a CMake bug which resulted in static targets depending on shared targets
 when building both types of libraries in the same build
 ([Issue #692](https://github.com/LLNL/sundials/issues/692)).
@@ -55,19 +75,21 @@ called even when informational logging was disabled.
 
 ### Deprecation Notices
 
-`SUNDIALSFileOpen` and `SUNDIALSFileClose` will be removed in the next major release. 
-Use `SUNFileOpen` and `SUNFileClose` instead.
+`SUNDIALSFileOpen` and `SUNDIALSFileClose` will be removed in the next major
+release.  Use `SUNFileOpen` and `SUNFileClose` instead.
 
-The `Convert` methods on the `sundials::kokkos:Vector`, `sundials::kokkos::DenseMatrix`,
-`sundials::ginkgo::Matrix`, `sundials::ginkgo::BatchMatrix`, `sundials::kokkos::DenseLinearSolver`,
-`sundials::ginkgo::LinearSolver`, and `sundials::ginkgo::BatchLinearSolver` classes have
-been deprecated and will be removed in the next major release. The method `get`, should
-be used instead.
+The `Convert` methods on the `sundials::kokkos:Vector`,
+`sundials::kokkos::DenseMatrix`, `sundials::ginkgo::Matrix`,
+`sundials::ginkgo::BatchMatrix`, `sundials::kokkos::DenseLinearSolver`,
+`sundials::ginkgo::LinearSolver`, and `sundials::ginkgo::BatchLinearSolver`
+classes have been deprecated and will be removed in the next major release. The
+method `get`, should be used instead.
 
-The `CSC_MAT` and `CSR_MAT` macros defined in `sunmatrix_sparse.h` will be removed in
-the next major release. Use `SUN_CSC_MAT` and `SUN_CSR_MAT` instead.
+The `CSC_MAT` and `CSR_MAT` macros defined in `sunmatrix_sparse.h` will be
+removed in the next major release. Use `SUN_CSC_MAT` and `SUN_CSR_MAT` instead.
 
-The `N_Vector_S` typedef to `N_Vector*` is deprecated and will be removed in the next major release.
+The `N_Vector_S` typedef to `N_Vector*` is deprecated and will be removed in the
+next major release.
 
 ## Changes to SUNDIALS in release 7.5.0
 

bindings/sundials4py/cvodes/cvodes_generated.hpp

@@ -114,6 +114,9 @@ m.def("CVodeSVtolerances", CVodeSVtolerances, nb::arg("cvode_mem"),
 m.def("CVodeSetConstraints", CVodeSetConstraints, nb::arg("cvode_mem"),
       nb::arg("constraints"));
 
+m.def("CVodeSetMaxNumConstraintFails", CVodeSetMaxNumConstraintFails,
+      nb::arg("cvode_mem"), nb::arg("max_fails"));
+
 m.def("CVodeSetDeltaGammaMaxLSetup", CVodeSetDeltaGammaMaxLSetup,
       nb::arg("cvode_mem"), nb::arg("dgmax_lsetup"));
 
@@ -681,6 +684,45 @@ m.def(
   },
   nb::arg("cvode_mem"));
 
+m.def(
+  "CVodeGetNumConstraintFails",
+  [](void* cvode_mem) -> std::tuple<int, long>
+  {
+    auto CVodeGetNumConstraintFails_adapt_modifiable_immutable_to_return =
+      [](void* cvode_mem) -> std::tuple<int, long>
+    {
+      long num_fails_out_adapt_modifiable;
+
+      int r = CVodeGetNumConstraintFails(cvode_mem,
+                                         &num_fails_out_adapt_modifiable);
+      return std::make_tuple(r, num_fails_out_adapt_modifiable);
+    };
+
+    return CVodeGetNumConstraintFails_adapt_modifiable_immutable_to_return(
+      cvode_mem);
+  },
+  nb::arg("cvode_mem"));
+
+m.def(
+  "CVodeGetNumConstraintCorrections",
+  [](void* cvode_mem) -> std::tuple<int, long>
+  {
+    auto CVodeGetNumConstraintCorrections_adapt_modifiable_immutable_to_return =
+      [](void* cvode_mem) -> std::tuple<int, long>
+    {
+      long num_corrections_out_adapt_modifiable;
+
+      int r =
+        CVodeGetNumConstraintCorrections(cvode_mem,
+                                         &num_corrections_out_adapt_modifiable);
+      return std::make_tuple(r, num_corrections_out_adapt_modifiable);
+    };
+
+    return CVodeGetNumConstraintCorrections_adapt_modifiable_immutable_to_return(
+      cvode_mem);
+  },
+  nb::arg("cvode_mem"));
+
 m.def("CVodePrintAllStats", CVodePrintAllStats, nb::arg("cvode_mem"),
       nb::arg("outfile"), nb::arg("fmt"));
 

bindings/sundials4py/idas/idas_generated.hpp

@@ -128,6 +128,9 @@ m.def("IDASetId", IDASetId, nb::arg("ida_mem"), nb::arg("id"));
 m.def("IDASetConstraints", IDASetConstraints, nb::arg("ida_mem"),
       nb::arg("constraints"));
 
+m.def("IDASetMaxNumConstraintFails", IDASetMaxNumConstraintFails,
+      nb::arg("ida_mem"), nb::arg("max_fails"));
+
 m.def("IDASetEtaFixedStepBounds", IDASetEtaFixedStepBounds, nb::arg("ida_mem"),
       nb::arg("eta_min_fx"), nb::arg("eta_max_fx"));
 
@@ -508,6 +511,43 @@ m.def("IDAGetErrWeights", IDAGetErrWeights, nb::arg("ida_mem"),
 m.def("IDAGetEstLocalErrors", IDAGetEstLocalErrors, nb::arg("ida_mem"),
       nb::arg("ele"));
 
+m.def(
+  "IDAGetNumConstraintFails",
+  [](void* ida_mem) -> std::tuple<int, long>
+  {
+    auto IDAGetNumConstraintFails_adapt_modifiable_immutable_to_return =
+      [](void* ida_mem) -> std::tuple<int, long>
+    {
+      long num_fails_out_adapt_modifiable;
+
+      int r = IDAGetNumConstraintFails(ida_mem, &num_fails_out_adapt_modifiable);
+      return std::make_tuple(r, num_fails_out_adapt_modifiable);
+    };
+
+    return IDAGetNumConstraintFails_adapt_modifiable_immutable_to_return(ida_mem);
+  },
+  nb::arg("ida_mem"));
+
+m.def(
+  "IDAGetNumConstraintCorrections",
+  [](void* ida_mem) -> std::tuple<int, long>
+  {
+    auto IDAGetNumConstraintCorrections_adapt_modifiable_immutable_to_return =
+      [](void* ida_mem) -> std::tuple<int, long>
+    {
+      long num_corrections_out_adapt_modifiable;
+
+      int r =
+        IDAGetNumConstraintCorrections(ida_mem,
+                                       &num_corrections_out_adapt_modifiable);
+      return std::make_tuple(r, num_corrections_out_adapt_modifiable);
+    };
+
+    return IDAGetNumConstraintCorrections_adapt_modifiable_immutable_to_return(
+      ida_mem);
+  },
+  nb::arg("ida_mem"));
+
 m.def(
   "IDAGetNumGEvals",
   [](void* ida_mem) -> std::tuple<int, long>