fix: updating for ortools 9.15 which changed some behavior. Also more reliable replacement for checking hints.

Author: d-krupke

chapters/04_modelling.md

@@ -826,10 +826,12 @@ model.add_abs_equality(target=abs_xz, expr=x + z)
 
 # Create variables to capture the maximum and minimum of x, (y-1), and z
 max_xyz = model.new_int_var(0, 100, "max(x, y-1, z)")
-model.add_max_equality(target=max_xyz, exprs=[x, y - 1, z])
+# Changed in ortools 9.15: was add_max_equality(target=max_xyz, exprs=[x, y - 1, z])
+model.add_max_equality(max_xyz, x, y - 1, z)
 
 min_xyz = model.new_int_var(-100, 100, "min(x, y-1, z)")
-model.add_min_equality(target=min_xyz, exprs=[x, y - 1, z])
+# Changed in ortools 9.15: was add_min_equality(target=min_xyz, exprs=[x, y - 1, z])
+model.add_min_equality(min_xyz, x, y - 1, z)
 ```
 
 While some practitioners report that these methods are more efficient than those

chapters/05_parameters.md

@@ -498,6 +498,7 @@ load the model on a different machine and run the solver.
 
 ```python
 from ortools.sat.python import cp_model
+from ortools.sat import cp_model_pb2
 from google.protobuf import text_format
 from pathlib import Path
 
@@ -508,20 +509,39 @@ def _detect_binary_mode(filename: str) -> bool:
         return True
     raise ValueError(f"Unknown extension for file: {filename}")
 
+# Changed in ortools 9.15: was model.Proto().SerializeToString() / text_format.MessageToString()
+# Now use model.export_to_file() which auto-detects format by extension
 def export_model(model: cp_model.CpModel, filename: str, binary: bool | None = None):
     binary = _detect_binary_mode(filename) if binary is None else binary
-    if binary:
-        Path(filename).write_bytes(model.Proto().SerializeToString())
+    # export_to_file uses .txt extension for text format, otherwise binary
+    # So we need to handle the mismatch for some extensions
+    if binary and filename.endswith(".txt"):
+        # Force binary even with .txt extension - use temp file
+        temp_file = filename + ".pb"
+        model.export_to_file(temp_file)
+        Path(filename).write_bytes(Path(temp_file).read_bytes())
+        Path(temp_file).unlink()
+    elif not binary and not filename.endswith(".txt"):
+        # Force text even without .txt extension
+        temp_file = filename + ".txt"
+        model.export_to_file(temp_file)
+        Path(filename).write_text(Path(temp_file).read_text())
+        Path(temp_file).unlink()
     else:
-        Path(filename).write_text(text_format.MessageToString(model.Proto()))
+        model.export_to_file(filename)
 
+# Changed in ortools 9.15: was model.Proto().ParseFromString() / text_format.Parse()
+# Now use model.Proto().parse_text_format() for text, or cp_model_pb2 for binary
 def import_model(filename: str, binary: bool | None = None) -> cp_model.CpModel:
     binary = _detect_binary_mode(filename) if binary is None else binary
     model = cp_model.CpModel()
     if binary:
-        model.Proto().ParseFromString(Path(filename).read_bytes())
+        # Parse binary via standard protobuf, then convert to text for import
+        proto = cp_model_pb2.CpModelProto()
+        proto.ParseFromString(Path(filename).read_bytes())
+        model.Proto().parse_text_format(text_format.MessageToString(proto))
     else:
-        text_format.Parse(Path(filename).read_text(), model.Proto())
+        model.Proto().parse_text_format(Path(filename).read_text())
     return model
 ```
 
@@ -560,17 +580,26 @@ We will also see how to utilize hints for multi-objective optimization in the
 > complete the solution from the hint, it may have wasted a lot of time in
 > branches it could otherwise have pruned.
 
-To ensure your hints are correct, you can enable the following parameter, which
-will make CP-SAT throw an error if the hints are incorrect:
+To verify that your hints are feasible, you can temporarily fix variables to
+their hinted values and check if the model becomes infeasible:
 
 ```python
-solver.parameters.debug_crash_on_bad_hint = True
+solver.parameters.fix_variables_to_their_hinted_value = True
+status = solver.solve(model)
+if status == cp_model.INFEASIBLE:
+    print("Hints are conflicting or infeasible!")
 ```
 
 If you suspect that your hints are not being utilized, it might indicate a
-logical error in your model or a bug in your code. This parameter can help
-diagnose such issues. However, this feature does not work reliably, so it should
-not be solely relied upon.
+logical error in your model or a bug in your code. This approach reliably
+detects infeasible hints by forcing the solver to use the exact hinted values.
+
+There is also `solver.parameters.debug_crash_on_bad_hint = True`, which crashes
+the solver if it cannot complete hints into a feasible solution. However, this
+feature is unreliable: it only triggers in multi-worker mode, depends on a race
+condition between workers, and is controlled by `hint_conflict_limit` (default:
+10). The `fix_variables_to_their_hinted_value` approach above is simpler and
+deterministic.
 
 > [!WARNING]
 >

tests/test_abs_minmax.py

@@ -12,7 +12,9 @@ def test_lin_constraints():
     model.add_abs_equality(target=abs_xz, expr=x + z)
     # max_xyz = max(x,y,z-1)
     max_xyz = model.new_int_var(0, 100, "max(x,y, z-1)")
-    model.add_max_equality(target=max_xyz, exprs=[x, y, z - 1])
+    # Changed in ortools 9.15: was add_max_equality(target=max_xyz, exprs=[x, y, z - 1])
+    model.add_max_equality(max_xyz, x, y, z - 1)
     # min_xyz = min(x,y,z)
     min_xyz = model.new_int_var(-100, 100, " min(x,y, z)")
-    model.add_min_equality(target=min_xyz, exprs=[x, y, z])
+    # Changed in ortools 9.15: was add_min_equality(target=min_xyz, exprs=[x, y, z])
+    model.add_min_equality(min_xyz, x, y, z)

tests/test_interval.py

@@ -38,8 +38,9 @@ def test_interval():
         name="optional_fixed_interval",
     )
 
+    # Changed in ortools 9.15: was interval_vars=
     model.add_no_overlap(
-        interval_vars=[
+        intervals=[
             flexible_interval,
             fixed_interval,
             optional_interval,

tests/test_parameters.py

@@ -127,21 +127,24 @@ def test_assumptions():
 
 
 def test_bad_hints():
+    """
+    Test that fix_variables_to_their_hinted_value detects infeasible hints.
+    This is more reliable than debug_crash_on_bad_hint which has race conditions.
+    """
     model = cp_model.CpModel()
-    vertices = range(30)
+    vertices = range(10)
     arcs = [(i, j) for i in vertices for j in vertices if i != j]
-    costs = {(i, j): random.randint(1, 100) for i, j in arcs}
     x = {(i, j): model.new_bool_var(f"x_{i}_{j}") for i, j in arcs}
     model.add_circuit([(v, w, x) for (v, w), x in x.items()])
-    model.minimize(sum(costs[i, j] * x[i, j] for i, j in arcs))
+    # add a bad hint of multiple outgoing arcs from the same node (violates circuit)
     model.add_hint(x[0, 1], 1)
     model.add_hint(x[0, 2], 1)
     model.add_hint(x[0, 3], 1)
     solver = cp_model.CpSolver()
-    # add a bad hint of two outgoing arcs from the same node
-    solver.parameters.max_time_in_seconds = 10
-    solver.parameters.debug_crash_on_bad_hint = True
-    status = solver.solve(model)  # noqa: F841
+    # Fix variables to hinted values to reliably detect infeasible hints
+    solver.parameters.fix_variables_to_their_hinted_value = True
+    status = solver.solve(model)
+    assert status == cp_model.INFEASIBLE, "Expected INFEASIBLE due to conflicting hints"
 
 
 def test_presolve_parameters_exist():

tests/test_serialization.py

@@ -3,6 +3,7 @@
 
 def test_serialization():
     from ortools.sat.python import cp_model
+    from ortools.sat import cp_model_pb2
     from google.protobuf import text_format
     from pathlib import Path
 
@@ -13,28 +14,55 @@ def _detect_binary_mode(filename: str) -> bool:
             return True
         raise ValueError(f"Unknown extension for file: {filename}")
 
+    # Changed in ortools 9.15: was model.Proto().SerializeToString() / text_format.MessageToString()
+    # Now use model.export_to_file() which auto-detects format by extension
     def export_model(
         model: cp_model.CpModel, filename: str, binary: bool | None = None
     ):
         binary = _detect_binary_mode(filename) if binary is None else binary
-        if binary:
-            Path(filename).write_bytes(model.Proto().SerializeToString())
+        # export_to_file uses .txt extension for text format, otherwise binary
+        # So we need to handle the mismatch for some extensions
+        if binary and filename.endswith(".txt"):
+            # Force binary even with .txt extension - use temp file
+            temp_file = filename + ".pb"
+            model.export_to_file(temp_file)
+            Path(filename).write_bytes(Path(temp_file).read_bytes())
+            Path(temp_file).unlink()
+        elif not binary and not filename.endswith(".txt"):
+            # Force text even without .txt extension
+            temp_file = filename + ".txt"
+            model.export_to_file(temp_file)
+            Path(filename).write_text(Path(temp_file).read_text())
+            Path(temp_file).unlink()
         else:
-            Path(filename).write_text(text_format.MessageToString(model.Proto()))
+            model.export_to_file(filename)
 
+    # Changed in ortools 9.15: was model.Proto().ParseFromString() / text_format.Parse()
+    # Now use model.Proto().parse_text_format() for text, or cp_model_pb2 for binary
     def import_model(filename: str, binary: bool | None = None) -> cp_model.CpModel:
         binary = _detect_binary_mode(filename) if binary is None else binary
         model = cp_model.CpModel()
         if binary:
-            model.Proto().ParseFromString(Path(filename).read_bytes())
+            # Parse binary via standard protobuf, then convert to text for import
+            proto = cp_model_pb2.CpModelProto()
+            proto.ParseFromString(Path(filename).read_bytes())
+            model.Proto().parse_text_format(text_format.MessageToString(proto))
         else:
-            text_format.Parse(Path(filename).read_text(), model.Proto())
+            model.Proto().parse_text_format(Path(filename).read_text())
         return model
 
     def rename_variable_names(model: cp_model.CpModel):
-        for i, var in enumerate(model.proto.variables):
+        for i, var in enumerate(model.Proto().variables):
             var.name = f"x{i}"
 
+    # Changed in ortools 9.15: Proto() objects no longer support == comparison
+    # Compare via text representation instead
+    def protos_equal(m1: cp_model.CpModel, m2: cp_model.CpModel) -> bool:
+        with tempfile.TemporaryDirectory() as td:
+            m1.export_to_file(f"{td}/m1.txt")
+            m2.export_to_file(f"{td}/m2.txt")
+            return Path(f"{td}/m1.txt").read_text() == Path(f"{td}/m2.txt").read_text()
+
     model = cp_model.CpModel()
     x = [model.NewIntVar(0, 10, f"x{i}") for i in range(10)]
     model.add(sum(x) <= 20)
@@ -43,16 +71,16 @@ def rename_variable_names(model: cp_model.CpModel):
     with tempfile.TemporaryDirectory() as tmpdir:
         export_model(model, f"{tmpdir}/model.pb")
         model2 = import_model(f"{tmpdir}/model.pb")
-        assert model.Proto() == model2.Proto()
+        assert protos_equal(model, model2)
         export_model(model, f"{tmpdir}/model.txt", binary=False)
         model3 = import_model(f"{tmpdir}/model.txt", binary=False)
-        assert model.Proto() == model3.Proto()
+        assert protos_equal(model, model3)
         export_model(model, f"{tmpdir}/model.pbtxt", binary=False)
         model4 = import_model(f"{tmpdir}/model.pbtxt", binary=False)
-        assert model.Proto() == model4.Proto()
+        assert protos_equal(model, model4)
         export_model(model, f"{tmpdir}/model.pb.txt", binary=True)
         model5 = import_model(f"{tmpdir}/model.pb.txt", binary=True)
-        assert model.Proto() == model5.Proto()
+        assert protos_equal(model, model5)
         rename_variable_names(model)
         export_model(model, f"{tmpdir}/model_renamed.pb.txt")
         model6 = import_model(f"{tmpdir}/model_renamed.pb.txt")