solver-support 0.3.1__tar.gz → 0.3.2__tar.gz

{solver_support-0.3.1/solver_support.egg-info → solver_support-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.3.1
+Version: 0.3.2
 Summary: Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline
 Author: András Salamon
 License-Expression: BSD-3-Clause

{solver_support-0.3.1 → solver_support-0.3.2}/docs/timing-model.md

@@ -193,7 +193,7 @@ establishes nothing. `SolverStatsExtractor.savilerow_verdict` separates them and
 | verdict | evidence | meaning |
 |---|---|---|
 | `sat` / `unsat` | `SolverSatisfiable` present | decided (`proven_optimal` too, on optimisation models) |
-| `unknown` | absent, with `verdict_reason` | `solver-limit`, `tailoring-limit`, `memory`, `encoding-limit`, or `unexplained` |
+| `unknown` | absent, with `verdict_reason` | `solver-limit`, `tailoring-limit`, `memory`, `tailoring-memory`, `encoding-limit`, or `unexplained` |
 | `error` | `SavileRowUncaughtException` | Savile Row itself failed |
 | `killed` | no `.info` at all | recorded by the caller, from the phase's `timed_out` / `launch_failed` |
 
@@ -202,6 +202,23 @@ the solver having run: Savile Row can settle an instance during tailoring and
 never invoke a solver, leaving `SolverTotalTime: 0` beside a perfectly good
 verdict. Testing "did the solver run?" reports every one of those as undecided.
 
+**Each limit names the process it bound.** `solver-limit` / `tailoring-limit`
+are the two time limits (see above), and `memory` / `tailoring-memory` are the
+same split for the heap: `SolverMemOut` is the backend, `SavileRowOutOfMemory`
+the JVM running Savile Row. The front-end memory-out is `unknown` and not
+`error` for the same reason its timeout is — a resource cap stopped the run
+before it decided; nothing malfunctioned. It is checked **before** the verdict,
+and before `SavileRowUncaughtException`: one heap exhaustion sets both flags,
+because the `OutOfMemoryError` reaches Savile Row's top-level handler, and the
+cause is a more useful report than the symptom. `error` is then what is left
+when Savile Row has no account of what went wrong.
+
+You will mostly see this flag if your limits are **in band**. A harness that
+caps memory externally (`runsolver` and friends) kills the JVM before it reaches
+its own `-Xmx`, so Savile Row never writes the flag and you get a killed process
+with no statistics instead — the same trade the time limits make. Bounding a run
+from the inside buys diagnostics that killing it from outside destroys.
+
 **A horizon's `unsat` is about the bound, not the problem.** It means "not at
 this horizon", never "not at all" — refuting horizons 1..N says nothing about
 N+1. Only the registry knows which models decide the problem itself

{solver_support-0.3.1 → solver_support-0.3.2}/pyproject.toml

@@ -20,7 +20,7 @@ name = "solver-support"
 # escape hatch for a version that genuinely cannot be known without building.
 # Ours can. Carrying a `.devN` suffix between releases keeps the working tree
 # from claiming a version that is already tagged and published.
-version = "0.3.1"
+version = "0.3.2"
 description = "Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline"
 readme = "README.md"
 requires-python = ">=3.9"

{solver_support-0.3.1 → solver_support-0.3.2}/solver_support/solver_stats.py

@@ -101,7 +101,8 @@ SAVILEROW_VERDICTS = ('sat', 'unsat', 'unknown', 'error', 'killed')
 # Why a run ended without deciding, keyed by the ``.info`` flag that explains it,
 # in the order they are checked. Savile Row sets at most one of these in practice;
 # the order records which explanation would win if it ever set two, most specific
-# (the solver's own limit) first.
+# (the solver's own limit) first. ``memory`` is the *backend* running out; the
+# front end running out is an abort flag below, not one of these.
 _SAVILEROW_STOP_FLAGS = (
     ('SolverTimeOut', 'solver-limit'),
     ('SavileRowTimeOut', 'tailoring-limit'),
@@ -109,6 +110,23 @@ _SAVILEROW_STOP_FLAGS = (
     ('SavileRowClauseOut', 'encoding-limit'),
 )
 
+# Savile Row itself did not finish. Checked BEFORE the verdict test - a run that
+# died mid-flight cannot be trusted to have written a sound one - and so, unlike
+# the stop flags above, these outrank a ``SolverSatisfiable`` that is present.
+#
+# Ordered cause before symptom: a JVM heap exhaustion reaches Savile Row's
+# top-level handler, so it sets BOTH ``SavileRowOutOfMemory`` and
+# ``SavileRowUncaughtException``, and "ran out of memory" is the more useful of
+# the two reports. Out-of-memory is ``unknown`` rather than ``error`` because
+# nothing malfunctioned: it is the front-end twin of ``SolverMemOut``, a resource
+# cap that stopped the run before it decided, exactly as the two time limits are
+# a matched ``solver-limit`` / ``tailoring-limit`` pair. ``error`` stays for the
+# case where Savile Row has no account of what went wrong.
+_SAVILEROW_ABORT_FLAGS = (
+    ('SavileRowOutOfMemory', 'unknown', 'tailoring-memory'),
+    ('SavileRowUncaughtException', 'error', 'uncaught-exception'),
+)
+
 
 class SolverStatsExtractor:
     """Extract structured statistics from solver output."""
@@ -492,11 +510,14 @@ class SolverStatsExtractor:
             except (TypeError, ValueError):
                 return False
 
-        # Checked before the verdict: a Savile Row that threw cannot be trusted
-        # to have written a sound one. The two have never been observed together,
-        # so this ordering only decides a case not yet seen in practice.
-        if _flagged('SavileRowUncaughtException'):
-            return {'verdict': 'error', 'verdict_reason': 'uncaught-exception'}
+        # Checked before the verdict: a Savile Row that died cannot be trusted to
+        # have written a sound one. An abort has never been observed together
+        # with a verdict, so that half of the ordering only decides a case not
+        # yet seen in practice; the cause-before-symptom half of it decides a
+        # real one, since an out-of-memory sets the exception flag as well.
+        for key, verdict, reason in _SAVILEROW_ABORT_FLAGS:
+            if _flagged(key):
+                return {'verdict': verdict, 'verdict_reason': reason}
 
         # `SolverSatisfiable` is written if and only if something DECIDED this
         # run, and is deliberately not keyed on the solver having run: Savile Row

{solver_support-0.3.1 → solver_support-0.3.2/solver_support.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.3.1
+Version: 0.3.2
 Summary: Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline
 Author: András Salamon
 License-Expression: BSD-3-Clause

{solver_support-0.3.1 → solver_support-0.3.2}/tests/test_solver_stats.py

@@ -281,6 +281,47 @@ class TestSavileRowVerdict:
         assert SolverStatsExtractor.savilerow_verdict(info) == {
             'verdict': 'error', 'verdict_reason': 'uncaught-exception'}
 
+    def test_out_of_memory_is_reported_by_cause_not_symptom(self, tmp_path):
+        """Both flags are set by one event, and the cause is the useful one.
+
+        A JVM heap exhaustion reaches Savile Row's top-level handler, so the
+        ``.info`` carries ``SavileRowUncaughtException: 1`` beside the memory
+        flag. Reporting the exception says *Savile Row has a bug*; reporting the
+        memory says *this model did not fit*, which is what decides whether a
+        consumer retries at a larger scale or files a fault. Keys verbatim from
+        a real run (Savile Row 1.11.1, ~183 s, exit 1, ``ERROR: Out of Memory``).
+        """
+        info = self._write_info(
+            tmp_path,
+            "SavileRowClauseOut:0\nSavileRowTotalTime:182.786\n"
+            "SavileRowOutOfMemory:1\nSavileRowUncaughtException:1\n"
+            "SavileRowTimeOut:0\n")
+        assert SolverStatsExtractor.savilerow_verdict(info) == {
+            'verdict': 'unknown', 'verdict_reason': 'tailoring-memory'}
+
+    def test_out_of_memory_alone_is_not_unexplained(self, tmp_path):
+        """An ``OutOfMemoryError`` caught and reported cleanly sets one flag.
+
+        Without its own branch this falls past the exception test, finds no stop
+        flag set, and lands on ``unexplained`` - which for a consumer that sets
+        the backend's limit itself reads as the routine solver timeout, turning
+        a fault into a cap.
+        """
+        info = self._write_info(
+            tmp_path,
+            "SavileRowTotalTime:120.5\nSavileRowOutOfMemory:1\n"
+            "SavileRowTimeOut:0\nSolverTimeOut:0\n")
+        assert SolverStatsExtractor.savilerow_verdict(info) == {
+            'verdict': 'unknown', 'verdict_reason': 'tailoring-memory'}
+
+    def test_backend_memout_stays_distinct_from_tailoring_memory(self, tmp_path):
+        """The two memory reasons name different processes' heaps."""
+        info = self._write_info(
+            tmp_path,
+            "SolverTotalTime:88.1\nSolverMemOut:1\nSolverTimeOut:0\n")
+        assert SolverStatsExtractor.savilerow_verdict(info) == {
+            'verdict': 'unknown', 'verdict_reason': 'memory'}
+
     def test_proven_optimum_marked_on_sat(self, tmp_path):
         info = self._write_info(
             tmp_path,