Improve errors raised by calculate_variable_from_constraint

pyomo/common/errors.py

@@ -124,6 +124,16 @@ class InvalidValueError(PyomoException, ValueError):
     pass
 
 
+class IterationLimitError(PyomoException, RuntimeError):
+    """A subclass of :py:class:`RuntimeError`, raised by an iterative method
+    when the iteration limit is reached.
+
+    TODO: currently solvers currently do not raise this exception, but
+    probably should (at least when non-normal termination conditions are
+    mapped to exceptions)
+
+    """
+
 class IntervalException(PyomoException, ValueError):
     """
     Exception class used for errors in interval arithmetic.

pyomo/util/calc_var_value.py

@@ -9,6 +9,7 @@
 #  This software is distributed under the 3-clause BSD License.
 #  ___________________________________________________________________________
 
+from pyomo.common.errors import IterationLimitError
 from pyomo.core.expr.numvalue import native_numeric_types, value, is_fixed
 from pyomo.core.expr.calculus.derivatives import differentiate
 from pyomo.core.base.constraint import Constraint, _ConstraintData
@@ -212,7 +213,7 @@ def calculate_variable_from_constraint(
         fp0 = value(expr_deriv)
 
     if abs(value(fp0)) < 1e-12:
-        raise RuntimeError(
+        raise ValueError(
             f"Initial value for variable '{variable}' results in a derivative "
             f"value for constraint '{constraint}' that is very close to zero.\n"
             "\tPlease provide a different initial guess."
@@ -223,7 +224,7 @@ def calculate_variable_from_constraint(
     while abs(fk) > eps and iter_left:
         iter_left -= 1
         if not iter_left:
-            raise RuntimeError(
+            raise IterationLimitError(
                 f"Iteration limit (%s) reached solving for variable '{variable}' "
                 f"using constraint '{constraint}'; remaining residual = %s"
                 % (iterlim, value(expr))
@@ -251,6 +252,8 @@ def calculate_variable_from_constraint(
             fpk = value(expr_deriv)
 
         if abs(fpk) < 1e-12:
+            # TODO: should this raise a ValueError or a new
+            # DerivativeError (subclassing ArithmeticError)?
             raise RuntimeError(
                 "Newton's method encountered a derivative of constraint "
                 f"'{constraint}' with respect to variable '{variable}' that was too "
@@ -288,7 +291,7 @@ def calculate_variable_from_constraint(
                 residual = value(expr, exception=False)
                 if residual is None or type(residual) is complex:
                     residual = "{function evaluation error}"
-                raise RuntimeError(
+                raise IterationLimitError(
                     f"Linesearch iteration limit reached solving for "
                     f"variable '{variable}' using constraint '{constraint}'; "
                     f"remaining residual = {residual}."

pyomo/util/tests/test_calc_var_value.py

@@ -14,6 +14,7 @@
 
 import pyomo.common.unittest as unittest
 
+from pyomo.common.errors import IterationLimitError
 from pyomo.common.log import LoggingIntercept
 from pyomo.environ import (
     ConcreteModel,
@@ -152,7 +153,7 @@ def test_nonlinear(self):
         for mode in all_diff_modes:
             m.x.set_value(1.25)  # set the initial value
             with self.assertRaisesRegex(
-                RuntimeError, r'Iteration limit \(10\) reached'
+                IterationLimitError, r'Iteration limit \(10\) reached'
             ):
                 calculate_variable_from_constraint(
                     m.x, m.d, iterlim=10, linesearch=False, diff_mode=mode
@@ -162,7 +163,7 @@ def test_nonlinear(self):
         for mode in all_diff_modes:
             m.x.set_value(1.25)  # set the initial value
             with self.assertRaisesRegex(
-                RuntimeError, "Linesearch iteration limit reached"
+                    IterationLimitError, "Linesearch iteration limit reached"
             ):
                 calculate_variable_from_constraint(
                     m.x, m.d, iterlim=10, linesearch=True, diff_mode=mode
@@ -172,7 +173,7 @@ def test_nonlinear(self):
         for mode in all_diff_modes:
             m.x = 0
             with self.assertRaisesRegex(
-                RuntimeError,
+                ValueError,
                 "Initial value for variable 'x' results in a "
                 "derivative value for constraint 'c' that is very close to zero.",
             ):
@@ -185,7 +186,7 @@ def test_nonlinear(self):
                 # numeric differentiation should not be used to check if a
                 # derivative is always zero
                 with self.assertRaisesRegex(
-                    RuntimeError,
+                    ValueError,
                     "Initial value for variable 'y' results in a "
                     "derivative value for constraint 'c' that is very close to zero.",
                 ):
@@ -314,7 +315,7 @@ def f(m):
         m.c = Constraint(expr=m.x**0.5 == -1e-8)
         m.x = 1e-8  # 197.932807183
         with self.assertRaisesRegex(
-            RuntimeError,
+            IterationLimitError,
             "Linesearch iteration limit reached solving for variable 'x' using "
             "constraint 'c'; remaining residual = {function evaluation error}",
         ):