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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.2.2
+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
@@ -29,12 +29,13 @@ Dynamic: license-file
 # solver-support
 
 A generic, domain-agnostic pipeline for running constraint-modelling and
-planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
-Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
-mechanics that every such run needs — building solver command lines from a model
-registry, spawning subprocesses with timeouts and clean teardown, naming the
-per-run files, parsing solver output into a uniform timing / cost-layer model,
-and driving the horizon (increasing-difficulty) loop.
+planning solvers: **Conjure** / **Savile Row** (driving a SAT solver, **Minion**,
+**OR-Tools CP-SAT**, **Gecode** or **Chuffed**), **Fast Downward**, **SymK**,
+**ENHSP**, and **UPF**-constructed models. It handles the mechanics that every
+such run needs — building solver command lines from a model registry, spawning
+subprocesses with timeouts and clean teardown, naming the per-run files, parsing
+solver output into a uniform timing / cost-layer model, and driving the horizon
+(increasing-difficulty) loop.
 
 It carries **no** notion of any particular problem domain or objective. A
 consumer supplies:
@@ -47,14 +48,17 @@ consumer supplies:
 
 ## Status
 
-**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
-its own test suite, but this is the first public release and the API may still
-shift between 0.x versions.
+**Alpha.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite, but the API may still shift between 0.x releases. Each
+release's changes are listed on the
+[releases page](https://github.com/ott2/solver-support/releases).
 
-The package ships **unwired**: a bare `import solver_support` gives a pipeline
-that resolves no model registry and interprets no objective, because it has no
-way to guess either. A consumer registers its scoring, registry paths, warning
-logger and UPF CLI once, before first use.
+The package ships **unwired**, by design and on every release: a bare
+`import solver_support` gives a pipeline that resolves no model registry and
+interprets no objective, because it has no way to guess either. Constructing a
+`ModelRegistry` *raises* rather than falling back on a guess. A consumer
+registers its scoring, registry paths, warning logger and UPF CLI once, before
+first use — see [Usage](#usage).
 
 ## Installation
 
@@ -63,7 +67,8 @@ pip install solver-support
 ```
 
 Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
-supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+supported deliberately — each release is built and tested against it). The only
+runtime dependencies are `psutil` and `PyYAML`.
 
 ## Usage
 
@@ -83,15 +88,18 @@ extraction, warning logger, UPF CLI — with a worked example.
 
 ## Development
 
-Clone and install editable. A consumer under development alongside it is
-normally installed into the same virtualenv, so both are importable and edits to
-either take effect immediately:
+To work on this package, clone and install it editable:
 
 ```bash
 git clone https://github.com/ott2/solver-support
 pip install -e solver-support
 ```
 
+Consumers pin a **released** version from PyPI rather than the working tree, so a
+change here reaches them only when it is released. To try an unreleased change
+against a consumer, install this editable into that consumer's environment
+deliberately — it is not the default arrangement.
+
 ## Tests
 
 `pytest tests/` — the core's own suite, and the home for solver-level

{solver_support-0.2.2 → solver_support-0.3.2}/README.md

@@ -1,12 +1,13 @@
 # solver-support
 
 A generic, domain-agnostic pipeline for running constraint-modelling and
-planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
-Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
-mechanics that every such run needs — building solver command lines from a model
-registry, spawning subprocesses with timeouts and clean teardown, naming the
-per-run files, parsing solver output into a uniform timing / cost-layer model,
-and driving the horizon (increasing-difficulty) loop.
+planning solvers: **Conjure** / **Savile Row** (driving a SAT solver, **Minion**,
+**OR-Tools CP-SAT**, **Gecode** or **Chuffed**), **Fast Downward**, **SymK**,
+**ENHSP**, and **UPF**-constructed models. It handles the mechanics that every
+such run needs — building solver command lines from a model registry, spawning
+subprocesses with timeouts and clean teardown, naming the per-run files, parsing
+solver output into a uniform timing / cost-layer model, and driving the horizon
+(increasing-difficulty) loop.
 
 It carries **no** notion of any particular problem domain or objective. A
 consumer supplies:
@@ -19,14 +20,17 @@ consumer supplies:
 
 ## Status
 
-**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
-its own test suite, but this is the first public release and the API may still
-shift between 0.x versions.
+**Alpha.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite, but the API may still shift between 0.x releases. Each
+release's changes are listed on the
+[releases page](https://github.com/ott2/solver-support/releases).
 
-The package ships **unwired**: a bare `import solver_support` gives a pipeline
-that resolves no model registry and interprets no objective, because it has no
-way to guess either. A consumer registers its scoring, registry paths, warning
-logger and UPF CLI once, before first use.
+The package ships **unwired**, by design and on every release: a bare
+`import solver_support` gives a pipeline that resolves no model registry and
+interprets no objective, because it has no way to guess either. Constructing a
+`ModelRegistry` *raises* rather than falling back on a guess. A consumer
+registers its scoring, registry paths, warning logger and UPF CLI once, before
+first use — see [Usage](#usage).
 
 ## Installation
 
@@ -35,7 +39,8 @@ pip install solver-support
 ```
 
 Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
-supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+supported deliberately — each release is built and tested against it). The only
+runtime dependencies are `psutil` and `PyYAML`.
 
 ## Usage
 
@@ -55,15 +60,18 @@ extraction, warning logger, UPF CLI — with a worked example.
 
 ## Development
 
-Clone and install editable. A consumer under development alongside it is
-normally installed into the same virtualenv, so both are importable and edits to
-either take effect immediately:
+To work on this package, clone and install it editable:
 
 ```bash
 git clone https://github.com/ott2/solver-support
 pip install -e solver-support
 ```
 
+Consumers pin a **released** version from PyPI rather than the working tree, so a
+change here reaches them only when it is released. To try an unreleased change
+against a consumer, install this editable into that consumer's environment
+deliberately — it is not the default arrangement.
+
 ## Tests
 
 `pytest tests/` — the core's own suite, and the home for solver-level

{solver_support-0.2.2 → solver_support-0.3.2}/docs/solver-runner.md

@@ -37,13 +37,13 @@ SolverResult(command, returncode, stdout, stderr, duration,
 
 Three easily-confused numbers:
 
-- `default_timeout` (a `SolverRunner` parameter) — the *limit*;
+- `timeout` (a `SolverRunner` parameter) — the *limit*;
 - `duration` (a `SolverResult` field) — the *actual* time it ran, whether it
   finished or was killed;
 - `timed_out` (a `SolverResult` field) — whether that limit was hit.
 
 ```python
-runner = SolverRunner(default_timeout=10.0)
+runner = SolverRunner(timeout=10.0)
 
 runner.run(['sleep', '3'])    # duration ~3.0,  timed_out False, returncode 0
 runner.run(['sleep', '15'])   # duration ~10.0, timed_out True,  returncode -1
@@ -87,7 +87,7 @@ SolverResult(ls /nonexistent) -> FAILED (rc=1, t=0.01s)
 ```python
 from solver_support import SolverRunner
 
-runner = SolverRunner(default_timeout=30.0)
+runner = SolverRunner(timeout=30.0)
 result = runner.run(['savilerow', 'model.eprime', 'problem.param'])
 
 if result.timed_out:

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

@@ -146,6 +146,85 @@ wires only the objective-file route will find continue-scan stops at the first
 solving horizon on those backends instead of improving — wire
 `set_raw_objective_from_solution` to use them for optimisation models.
 
+#### The three time limits, and how they relate
+
+A Savile Row run is bounded three times over, and the three are **not**
+interchangeable. Getting the relationship wrong is silent, so it is worth
+stating once:
+
+| limit | set by | what it actually bounds |
+|---|---|---|
+| `-timelimit T` | `build_savilerow_command(timeout=T)` | tailoring. Nominally translation *plus* solving, but Savile Row stops binding it once a solver is running |
+| the solver's own (`--time=S`, …) | `build_savilerow_command(solver_timeout=S)` | search |
+| the external kill | `SolverRunner(timeout=…)` | the whole process tree |
+
+**The first two are consecutive, so they add.** Savile Row tailors, and only
+then launches the solver, so the wall clock the pair permits is `T + S` — not
+`max(T, S)`. Left unsplit (`S` defaulting to `T`) that is `2T`, which is why an
+external kill set at `T` can fire while the toolchain is still inside the limits
+it was given.
+
+**An early kill costs every statistic, not just the tail.** Savile Row
+accumulates `SATVars`, `SATClauses`, `SolverNodes` and the
+`SavileRowTotalTime` / `SolverTotalTime` split in memory and writes the `.info`
+once, after the solver returns. Kill the tree and the output directory holds an
+`.eprime` and perhaps an `.eprime-minion`, never an `.eprime-info`, so
+`extract_savilerow_info` has nothing to read and the run cannot say even whether
+it reached the solver.
+
+So size the external kill with `savilerow_backstop(T, S)` — `T + S` plus grace
+for the flush — and it comes to mean "the toolchain ignored its limits", a
+genuine fault rather than an ordinary and lossy way for a run to end.
+
+**To hold a run to a wall-clock budget, shrink the pair, not the backstop.**
+Give the solver `S = T - (what tailoring will cost)`. The core picks no reserve
+policy: a horizon scan can estimate from the previous horizon's
+`SavileRowTotalTime`, a single-shot run has nothing to estimate from, and only
+the caller knows which it is.
+
+#### Verdicts: refuted vs gave up
+
+`No solution found.` is what Savile Row prints **both** when the solver proved
+there is none and when it stopped at its own limit without deciding, and
+`solution_found` is False for both. The first is a result; the second
+establishes nothing. `SolverStatsExtractor.savilerow_verdict` separates them and
+`_record_savilerow_times` records the answer on the phase as `verdict`:
+
+| verdict | evidence | meaning |
+|---|---|---|
+| `sat` / `unsat` | `SolverSatisfiable` present | decided (`proven_optimal` too, on optimisation models) |
+| `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` |
+
+Decidedness keys on `SolverSatisfiable` being **present**, deliberately not on
+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
+(`get_proves_unsat`), which is why the run-level `outcome` is derived in
+`RunSummary.finalize` and never aggregated from these.
+
 ### Fast Downward / SymK (PDDL models)
 
 - **Shape**: not a horizon scan — one `solving` phase whose A\* (blind) / symbolic
@@ -210,15 +289,46 @@ solving horizon on those backends instead of improving — wire
 - **Split is Savile-Row-only and best-effort.** `savilerow_time` / `solver_time`
   are `None` for planners and for any Savile Row horizon whose `.info` was
   missing.
+- **In-band limits add; the external kill must sit above their sum.** See "the
+  three time limits" above. `savilerow_backstop` derives it from the same
+  numbers the builder gets.
+- **A clean exit is not an answer.** A solver given its own limit stops *itself*
+  and exits 0, so every phase of a fruitless run can succeed. Run success is
+  decided by `outcome`, never by exit codes.
+
+## outcomes
+
+`final_status` answers two questions at once — what was learned, and why the run
+stopped — so `RunSummary.finalize` records them separately. `final_status` keeps
+its meaning; these sit alongside it.
+
+| field | values |
+|---|---|
+| `outcome` | `solved` / `unsat` / `unknown` / `error` |
+| `stop_reason` | `complete` / `time` / `horizons` / `interrupt` / `error` |
+
+`success` is `outcome in {solved, unsat}`: **a run succeeded if it produced a
+definitive answer in the budget it was given.** A proof that no solution exists
+answers the question as surely as a solution does, even though the planner that
+produced it exits non-zero.
+
+`unsat` requires the caller to pass `finalize(..., proves_unsat=True)`, normally
+from the registry's `get_proves_unsat`. The core cannot tell from the output — a
+bounded CP model and a complete planner print the same thing — and left False no
+run is ever concluded unsat, which understates rather than overstates what was
+proved. A status that stopped early (`timeout`, `hlim`, `stopped`) is never
+`unsat` however complete the model.
 
 ## what the core owns
 
 | concern | location |
 |---------|----------|
 | per-solver stat parsers, cost-layer assembly, dispatch | `solver_stats.py` |
+| per-run Savile Row verdict (refuted vs gave up) | `solver_stats.py` (`savilerow_verdict`) |
 | Savile Row `.info` split recording (per horizon) | `solver_horizon.py` (`_record_savilerow_times`) |
 | stats attached to a phase after each solve | `solver_runner.py`, `solver_horizon.py` |
-| the phase model (`RunSummary` / `PhaseResult`) | `run_summary.py` |
+| the phase model (`RunSummary` / `PhaseResult`), outcome and success | `run_summary.py` |
+| relating the in-band limits to the external kill | `command_builders.py` (`savilerow_backstop`) |
 
 Turning these per-phase stats into a unified per-horizon curve for display, a
 single "preprocess" baseline, and plots is the **consumer's** job — it reads the

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

@@ -11,10 +11,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "solver-support"
-# Single-sourced from solver_support.__version__, so a release bump touches one
-# line and the installed metadata can never disagree with what the package
-# reports at runtime.
-dynamic = ["version"]
+# The single source of the version. `solver_support.__version__` reads it back
+# from the installed distribution metadata, so there is no literal in the
+# package to drift from this one.
+#
+# Static rather than `dynamic = ["version"]` with a `{attr = ...}` pointing into
+# the package: PEP 621 treats `version` as a static field, and `dynamic` is the
+# 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.2"
 description = "Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -72,9 +78,6 @@ dev = [
 [tool.setuptools]
 zip-safe = false
 
-[tool.setuptools.dynamic]
-version = {attr = "solver_support.__version__"}
-
 [tool.setuptools.packages.find]
 include = ["solver_support*"]
 

{solver_support-0.2.2 → solver_support-0.3.2}/solver_support/__init__.py

@@ -13,7 +13,28 @@ unconfigured pipeline. A consumer registers its scoring (see :mod:`objective`)
 and its packaging paths (see :mod:`model_registry`) once at its own import time.
 """
 
-__version__ = "0.2.2"
+# Read back from the installed distribution metadata; the version itself is
+# declared once, in pyproject.toml. There is deliberately no literal here to
+# drift from it - the failure being avoided is a release where the metadata says
+# one thing and `__version__` another, each individually plausible and nothing
+# catching the disagreement.
+#
+# Resolved eagerly rather than behind a PEP 562 `__getattr__`: the lookup scans
+# sys.path for a matching .dist-info, which costs a fraction of a millisecond,
+# and this module already imports psutil, PyYAML and every solver backend below.
+# Deferring it would save nothing measurable against that.
+#
+# The fallback fires only in a source tree that was never installed. Note an
+# *editable* install pins its .dist-info at install time, so a checkout whose
+# version has moved on still reports the older one here until it is reinstalled
+# - the price of single-sourcing from metadata rather than from a literal.
+try:
+    from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    __version__ = _version("solver-support")
+except _PackageNotFoundError:  # a source tree, never installed
+    __version__ = "0+unknown"
 
 # --- model registry (loader + command builders + packaging injection) ---
 from .model_registry import (
@@ -25,6 +46,7 @@ from .model_registry import (
     set_resource_root,
     set_user_config_finder,
 )
+from .command_builders import savilerow_backstop, SAVILEROW_FLUSH_GRACE
 
 # --- run configuration singleton ---
 from .global_state import global_state, GlobalState
@@ -85,6 +107,8 @@ __all__ = [
     "set_default_config_path",
     "set_resource_root",
     "set_user_config_finder",
+    "savilerow_backstop",
+    "SAVILEROW_FLUSH_GRACE",
     # run config
     "global_state",
     "GlobalState",

{solver_support-0.2.2 → solver_support-0.3.2}/solver_support/command_builders.py

@@ -21,6 +21,41 @@ from typing import List, Optional
 from .model_registry import ModelRegistryError
 
 
+#: Seconds of slack between the in-band limits and the external kill. Savile Row
+#: needs a moment *after* its own limit fires to write the ``.info`` file (it
+#: accumulates every statistic in memory and flushes once), and Conjure to
+#: translate a solution back. A kill set exactly at the in-band limit races that
+#: flush and generally wins, so the run that was about to report its statistics
+#: reports nothing at all - the failure is worst precisely for the instances
+#: where all the work was tailoring, which are the ones the limit bounded.
+SAVILEROW_FLUSH_GRACE = 30
+
+
+def savilerow_backstop(timeout: int, solver_timeout: Optional[int] = None,
+                       grace: int = SAVILEROW_FLUSH_GRACE) -> int:
+    """The external timeout that cannot preempt Savile Row's own limits.
+
+    Savile Row's ``-timelimit`` and the backend solver's own limit are budgets
+    spent *one after the other* - it tailors, then runs the solver - so the wall
+    clock they jointly permit is their SUM, not the larger of the two. An
+    external kill below that sum will sometimes fire while the toolchain is
+    still inside the limits it was given, and because Savile Row writes its
+    ``.info`` only at the very end, firing early discards every statistic the
+    run had gathered.
+
+    Sized from the same numbers that reach :meth:`build_savilerow_command`, so
+    the two cannot drift apart. Passing this to the runner makes an external
+    kill mean "the toolchain ignored its limits", which is a genuine fault,
+    rather than an ordinary and silently lossy way for a run to end.
+
+    This is a *backstop*, not a wall-clock budget. To hold a run to ``T``
+    seconds of wall clock, do not shrink this - shrink the in-band pair so that
+    their sum is ``T`` (give the solver ``T`` minus what tailoring will cost)
+    and let the backstop sit above it, unreached.
+    """
+    return timeout + (timeout if solver_timeout is None else solver_timeout) + grace
+
+
 class CommandBuilderMixin:
     """The ``build_*_command`` methods mixed into :class:`ModelRegistry`."""
 
@@ -108,7 +143,8 @@ class CommandBuilderMixin:
                                objective_file_path: Optional[str] = None,
                                extra_options: Optional[List[str]] = None,
                                solver_name: str = 'kissat',
-                               tune: Optional[str] = None) -> List[str]:
+                               tune: Optional[str] = None,
+                               solver_timeout: Optional[int] = None) -> List[str]:
         """
         Build a Savile Row command with proper flags for horizon scanning.
 
@@ -120,7 +156,28 @@ class CommandBuilderMixin:
             model_path: path to the model file
             param_path: path to the parameter file
             use_srjava: use Java savilerow instead of savilerow-native
-            timeout: override timeout in seconds (uses default_timeout if None)
+            timeout: Savile Row's own ``-timelimit``, in seconds (uses
+                ``default_timeout`` if None). Covers tailoring *plus* solving,
+                but stops binding once a solver is running - so in practice it
+                bounds tailoring.
+            solver_timeout: the backend solver's own limit, if it should differ
+                from ``timeout``. Defaults to ``timeout``, which is what every
+                caller got before this existed.
+
+                These are two budgets spent one after the other, not one budget
+                named twice: Savile Row tailors, and only then runs the solver.
+                Passing the same number to both grants up to ``2 x timeout`` of
+                wall clock, which is why an external kill set at ``timeout``
+                fires mid-search and takes the statistics with it - Savile Row
+                accumulates them in memory and writes the ``.info`` once, after
+                the solver it launched returns.
+
+                The split is what lets a caller keep a real wall-clock budget:
+                reserve what tailoring will cost and give the solver the rest.
+                The core picks no reserve policy - a horizon scan can measure
+                the previous horizon's ``SavileRowTotalTime``, a single-shot run
+                cannot - so the number is the caller's. See
+                :func:`savilerow_backstop` for sizing the external kill.
             objective_file_path: path for intermediate objective values file (default: obj.txt)
             extra_options: additional command line options to pass to Savile Row
             solver_name: name of the solver configuration to use (default: 'kissat').
@@ -226,12 +283,18 @@ class CommandBuilderMixin:
             # The solver's own limit, in whatever flag and unit that solver
             # speaks. A config may override the dialect (or set it to null to
             # suppress it) without the core having to learn a new backend.
+            #
+            # Defaults to `timeout`, so a caller that says nothing gets exactly
+            # the argv it always got. Note the two limits are consecutive
+            # budgets - Savile Row tailors, then runs the solver - so leaving
+            # them equal permits roughly twice `timeout` of wall clock.
             option = solver_config.get('solver_timeout_option', spec['timeout_option'])
             if option:
                 scale = spec['timeout_scale']
+                budget = timeout if solver_timeout is None else solver_timeout
                 # Left untouched when the solver already speaks seconds, so those
                 # argvs keep their exact previous form (--time=45, never 45.0).
-                value = timeout if scale == 1 else int(timeout * scale)
+                value = budget if scale == 1 else int(budget * scale)
                 args.extend(["-solver-options", option.format(value=value)])
             # Savile Row's own limit covers translation plus solving and is always
             # in seconds. Always added, so a backend with no limit of its own is