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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.2.1
+Version: 0.2.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.2.1 → solver_support-0.2.2}/docs/timing-model.md

@@ -76,12 +76,34 @@ fields. All times are seconds unless noted.
   `solver_time`, attaching them to the matching phase. Recorded for *every*
   horizon, so intermediate UNSAT horizons carry the split too.
 - **The rest of the file**: those two are what the phase model needs, but the
-  same `.info` carries the encoding size and search counters (`SATVars`,
-  `SATClauses`, `SolverNodes`, `SolverSatisfiable`, ...).
-  `SolverStatsExtractor.extract_savilerow_info(path)` returns every `Key:Value`
-  pair with keys verbatim and values coerced to int/float, for a consumer
-  reporting those columns; `extract_savilerow_info_times` is the renaming subset
-  of it that the core itself uses.
+  same `.info` carries the encoding size, the search counters, and the outcome
+  flags. All of it is recorded verbatim on the phase under
+  `solver_stats['savilerow_info']`, so a consumer never has to go back to the
+  `.info` files — which matters because that would depend on the run's output
+  directory rather than its summary, and so stops working once those files are
+  cleaned up. `SolverStatsExtractor.extract_savilerow_info(path)` is the parser
+  (keys verbatim, values coerced to int/float, `{}` for a missing file);
+  `extract_savilerow_info_times` is the renaming subset that produces the two
+  fields above.
+- **Nested, not flattened, and deliberately not curated.** `solver_stats` is the
+  core's normalised cross-solver vocabulary; `savilerow_info` is one solver's own
+  keys in its own spelling, so nesting keeps CamelCase off the snake_case
+  namespace. It is verbatim because the backends do not agree on which keys
+  exist — measured on one model:
+
+  | key | minion | ortools | gecode | chuffed | kissat |
+  |---|:-:|:-:|:-:|:-:|:-:|
+  | `SavileRowTotalTime` `SolverTotalTime` `SolverSatisfiable` `SolverTimeOut` `SavileRowTimeOut` `SavileRowClauseOut` | ✓ | ✓ | ✓ | ✓ | ✓ |
+  | `SolverNodes` | ✓ | — | ✓ | ✓ | ✓ |
+  | `SolverFailures` `SolverTotalWallTime` | — | ✓ | ✓ | ✓ | — |
+  | `SolverSetupTime` `SolverSolveTime` `SolverSolutionsFound` | ✓ | — | — | — | — |
+  | `SATVars` `SATClauses` `SolverMemOut` | — | — | — | — | ✓ |
+
+  Any allow-list would already be wrong, and would need extending for every new
+  backend or Savile Row version. Note `SolverSatisfiable` is one of the six every
+  backend emits: it distinguishes a **refuted horizon** from one that gave up —
+  which is *not* problem-level unsat, since a bounded model cannot prove that
+  (see `hlim`, above).
 - **Best-effort**: a hard timeout can kill Savile Row before it writes `.info`,
   leaving the split absent (`None`).
 

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

@@ -13,7 +13,7 @@ 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.1"
+__version__ = "0.2.2"
 
 # --- model registry (loader + command builders + packaging injection) ---
 from .model_registry import (

{solver_support-0.2.1 → solver_support-0.2.2}/solver_support/model_registry.py

@@ -9,6 +9,7 @@ from the original bash run script.
 
 from pathlib import Path
 from typing import Dict, Any, Optional, List, Tuple, Callable
+import copy
 import shutil
 import yaml
 
@@ -95,8 +96,14 @@ class ModelRegistry(CommandBuilderMixin):
         
         self.config = {'models': {}, 'solvers': {}}
         self._savilerow_native_warning_shown = False  # Track if we've shown the warning
+        # Every file merged in, in the order merged, so a caller can report what
+        # actually contributed. Without this the answer is only reconstructible
+        # by re-running the same two searches by hand - and the user-override one
+        # depends on the cwd at construction time, so it is not reproducible
+        # later. See `dump_config`.
+        self.config_sources: List[Path] = []
         self._load_yaml_config(default_yaml)
-        
+
         # Then, load user configuration to override defaults
         user_yaml = config_path or self._find_user_yaml_config()
         if user_yaml:
@@ -145,10 +152,11 @@ class ModelRegistry(CommandBuilderMixin):
         try:
             with open(config_path, 'r') as f:
                 user_config = yaml.safe_load(f)
-            
+
             # Deep merge user config with existing config
             self._deep_merge(self.config, user_config)
-            
+            self.config_sources.append(Path(str(config_path)))
+
         except Exception as e:
             raise ModelRegistryError(f"Failed to load config file {config_path}: {e}")
     
@@ -165,7 +173,76 @@ class ModelRegistry(CommandBuilderMixin):
                 self._deep_merge(base[key], value)
             else:
                 base[key] = value
-    
+
+    def effective_config(self, resolved: bool = False) -> Dict[str, Any]:
+        """The configuration actually in force, as a plain dict.
+
+        A deep copy of the merge of every file in ``config_sources``: the
+        consumer's bundled config first, then any user override merged over it.
+        Answering "what is in force?" otherwise means reading both files and
+        performing the merge by eye - and the override's location depends on the
+        working directory at construction time, so it cannot reliably be
+        reconstructed afterwards.
+
+        With ``resolved``, values a *builder* supplies when a key is absent are
+        written out explicitly - currently a savilerow solver's implicit
+        ``backend: sat``, the one default whose absence changes which arg-set,
+        timeout dialect and binary flag are used. Only real config keys are ever
+        added, so a resolved dump still loads; see :meth:`dump_config` for why
+        loading one back is not what it is for.
+
+        The copy is deep, so a caller may edit the result without disturbing the
+        live registry.
+        """
+        config = copy.deepcopy(self.config)
+        if resolved:
+            for solver_config in config.get('solvers', {}).values():
+                if (isinstance(solver_config, dict)
+                        and solver_config.get('solver_type') == 'savilerow'):
+                    solver_config.setdefault('backend', 'sat')
+        return config
+
+    def dump_config(self, resolved: bool = False, header: bool = True) -> str:
+        """The effective configuration as YAML text, for inspection.
+
+        Intended for a consumer's ``--show-registry``-style flag: it answers what
+        the registry resolved to and which files contributed. It is deliberately
+        *not* a config generator. Two reasons, both stated in the emitted header:
+
+        - Comments are not preserved. A config's comments carry the reasoning for
+          its arg-sets and timeouts, and a YAML round-trip drops all of them, so
+          the dump is a view of the configuration rather than a replacement.
+        - Overrides are deep-merged, so adopting a full dump as a user config
+          pins every key at today's value and silently shadows later changes to
+          the bundled config. A partial override is the supported shape: copy
+          only the keys being changed.
+        """
+        text = yaml.safe_dump(self.effective_config(resolved=resolved),
+                              sort_keys=False, default_flow_style=False,
+                              allow_unicode=True)
+        if not header:
+            return text
+
+        lines = ["# Effective solver-support registry, merged in this order:"]
+        lines.extend(f"#   {i}. {source}"
+                     for i, source in enumerate(self.config_sources, start=1))
+        if not self.config_sources:
+            lines.append("#   (none)")
+        if resolved:
+            lines.append("#")
+            lines.append("# Defaults a builder would supply are written out "
+                         "explicitly here.")
+        lines.extend([
+            "#",
+            "# For reading, not for adopting wholesale. Comments in the source",
+            "# files are not preserved, and overrides are deep-merged - so using",
+            "# this whole file as an override would pin every key at today's",
+            "# value and silently shadow later changes. Copy only what you mean",
+            "# to change.",
+            "",
+        ])
+        return "\n".join(lines) + "\n" + text
+
     def get_model_path(self, model_type: str) -> Path:
         """
         Get the file path for a model type.

{solver_support-0.2.1 → solver_support-0.2.2}/solver_support/solver_horizon.py

@@ -227,11 +227,31 @@ class HorizonBasedSolver(Solver):
                 self.runner.summary.phases[-1].solver_stats['objbound'] = self._best_objective
 
     def _record_savilerow_times(self, param_file: Path, n: int) -> None:
-        """Attach Savile Row's tailoring/solver time split to horizon n's phase.
+        """Attach Savile Row's ``.info`` stats to horizon n's phase.
 
         Reads the ``<param_file>.info`` stats file Savile Row writes for this
         horizon and records ``savilerow_time`` (tailoring) and ``solver_time``
         on the phase, alongside the wall-clock ``duration`` already stored.
+
+        The whole file is also kept verbatim under ``savilerow_info``. The two
+        renamed times are what the phase model needs, but the same file carries
+        the encoding-size and search-effort numbers (``SATVars``, ``SolverNodes``,
+        ``SolverFailures``, ...) and the outcome flags (``SolverSatisfiable``
+        distinguishes a refuted horizon from one that gave up; ``SolverTimeOut``
+        / ``SavileRowTimeOut`` attribute a timeout to the solver or to
+        tailoring). Without this a consumer wanting any of them has to re-parse
+        the ``.info`` files itself, which duplicates the parser and needs the
+        run's output directory rather than just its summary - so it stops working
+        once those files are cleaned up.
+
+        Kept **nested and verbatim** rather than flattened in. ``solver_stats``
+        is the core's normalised, cross-solver vocabulary; these are one solver's
+        own keys in its own spelling, and the backends do not even agree on which
+        of them exist - Minion alone emits ``SolverSetupTime`` /
+        ``SolverSolveTime`` / ``SolverSolutionsFound``, the FlatZinc backends
+        alone ``SolverTotalWallTime``, kissat alone ``SATVars`` / ``SATClauses``.
+        A curated allow-list would therefore be wrong already, and nesting also
+        keeps CamelCase keys from colliding with the snake_case ones beside them.
         ``param_file`` is whatever parameter file Savile Row was run on - the
         Essence Prime ``.param`` for the direct Savile Row path, or the
         Conjure-translated ``.eprime-param`` for the Essence path - since Savile
@@ -242,12 +262,15 @@ class HorizonBasedSolver(Solver):
         the matching ``solving-horizon-{n}`` phase so it cannot scribble on an
         unrelated phase.
         """
+        info = SolverStatsExtractor.extract_savilerow_info(f"{param_file}.info")
         times = SolverStatsExtractor.extract_savilerow_info_times(f"{param_file}.info")
-        if not times:
+        if not times and not info:
             return
         phases = self.runner.summary.phases
         if phases and phases[-1].name == f"solving-horizon-{n}":
             phases[-1].solver_stats.update(times)
+            if info:
+                phases[-1].solver_stats['savilerow_info'] = info
 
     def _build_savilerow_command(self, model_path: str, param_path: str, timeout: Optional[int], obj_file: Optional[Path] = None) -> List[str]:
         """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.2.1
+Version: 0.2.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.2.1 → solver_support-0.2.2}/solver_support.egg-info/SOURCES.txt

@@ -32,8 +32,10 @@ tests/test_command_builders.py
 tests/test_helpers.py
 tests/test_horizon_utils.py
 tests/test_import.py
+tests/test_registry_dump.py
 tests/test_run_summary.py
 tests/test_run_summary_success.py
+tests/test_savilerow_info_recording.py
 tests/test_solution_naming.py
 tests/test_solver_runner.py
 tests/test_solver_stats.py

solver_support-0.2.2/tests/test_registry_dump.py

@@ -0,0 +1,93 @@
+"""Reporting what the registry actually resolved to.
+
+``effective_config`` / ``dump_config`` exist to answer "what is in force?", which
+is otherwise only answerable by reading the bundled config and any user override
+and merging them by eye -- and the override's location depends on the working
+directory at construction time, so after the fact it may not be reconstructible
+at all.
+
+The dump is deliberately a *view*, not a config generator, and the tests below
+pin the two properties that keep it honest: it reports its sources, and its
+header warns against adopting it wholesale. Both matter because overrides are
+deep-merged, so a full dump adopted as an override pins every key at today's
+value and silently shadows later changes to the bundled config.
+"""
+
+import yaml
+
+import pytest
+
+from solver_support.model_registry import ModelRegistry
+
+
+@pytest.fixture
+def registry(fixture_registry):
+    return ModelRegistry()
+
+
+class TestEffectiveConfig:
+
+    def test_returns_the_merged_config(self, registry):
+        config = registry.effective_config()
+        assert set(config) >= {"models", "solvers"}
+        assert "srortools" in config["solvers"]
+
+    def test_copy_is_deep(self, registry):
+        config = registry.effective_config()
+        config["solvers"]["srortools"]["backend"] = "mutated"
+        # The live registry must be untouched, or a caller inspecting the config
+        # could silently reconfigure the run it is inspecting.
+        assert registry.get_solver_config("srortools")["backend"] == "ortools"
+
+    def test_unresolved_leaves_implicit_backend_absent(self, registry):
+        # srsat has no `backend:` key; unresolved output mirrors the source.
+        assert "backend" not in registry.effective_config()["solvers"]["srsat"]
+
+    def test_resolved_writes_out_the_implicit_backend(self, registry):
+        config = registry.effective_config(resolved=True)
+        assert config["solvers"]["srsat"]["backend"] == "sat"
+        # An explicit one is left alone.
+        assert config["solvers"]["srortools"]["backend"] == "ortools"
+
+    def test_resolved_leaves_non_savilerow_solvers_alone(self, registry):
+        # `backend` means nothing to a upfplan solver, so inventing one would be
+        # a lie that also happens to load.
+        assert "backend" not in registry.effective_config(resolved=True)["solvers"]["upffd"]
+
+
+class TestConfigSources:
+
+    def test_records_the_files_merged(self, registry):
+        assert len(registry.config_sources) == 1
+        assert registry.config_sources[0].name == "models.yaml"
+
+
+class TestDumpConfig:
+
+    def test_dump_round_trips_as_yaml(self, registry):
+        loaded = yaml.safe_load(registry.dump_config())
+        assert loaded == registry.effective_config()
+
+    def test_resolved_dump_also_round_trips(self, registry):
+        # Only real config keys are ever added, so a resolved dump still loads.
+        loaded = yaml.safe_load(registry.dump_config(resolved=True))
+        assert loaded["solvers"]["srsat"]["backend"] == "sat"
+
+    def test_header_names_the_sources(self, registry):
+        assert "models.yaml" in registry.dump_config().splitlines()[1]
+
+    def test_header_warns_against_adopting_it(self, registry):
+        header = registry.dump_config().split("\n\n")[0]
+        assert "not for adopting wholesale" in header
+        assert "deep-merged" in header
+
+    def test_header_can_be_suppressed(self, registry):
+        text = registry.dump_config(header=False)
+        assert not text.startswith("#")
+        assert yaml.safe_load(text) == registry.effective_config()
+
+    def test_key_order_follows_the_source(self, registry):
+        # sort_keys=False: alphabetising a registry makes it unreadable, and the
+        # source order is how a maintainer arranged it.
+        text = registry.dump_config(header=False)
+        assert text.index("models:") < text.index("solvers:")

solver_support-0.2.2/tests/test_savilerow_info_recording.py

@@ -0,0 +1,127 @@
+"""What ``_record_savilerow_times`` keeps from each horizon's ``.info`` file.
+
+Savile Row writes a ``<param>.info`` per horizon. Two of its fields are renamed
+into the core's normalised vocabulary (``savilerow_time`` / ``solver_time``); the
+rest used to be parsed and dropped, so a consumer wanting the encoding size or
+the search-effort counters had to re-parse the files itself -- duplicating the
+parser, and depending on the run's output directory rather than its summary, so
+it stopped working once those files were cleaned up.
+
+The whole file is now kept verbatim under ``savilerow_info``, nested rather than
+flattened. Nesting is the point of several tests below: ``solver_stats`` is the
+core's cross-solver vocabulary, while these are one solver's own keys in its own
+spelling, and the backends do not agree on which of them exist.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from solver_support.run_summary import PhaseResult
+from solver_support.solver_horizon import SavileRowSolver
+
+# A real Minion .info, which carries three keys no other backend emits.
+MINION_INFO = """SavileRowClauseOut:0
+SavileRowTotalTime:0.484
+SolverNodes:1
+SolverSatisfiable:1
+SolverSetupTime:0.001
+SolverSolutionsFound:1
+SolverSolveTime:0.000123
+SolverTimeOut:0
+SolverTotalTime:0.000123
+"""
+
+# A real OR-Tools .info: no SolverNodes, but SolverFailures and a wall time.
+ORTOOLS_INFO = """SavileRowClauseOut:0
+SavileRowTotalTime:0.51
+SolverFailures:0
+SolverSatisfiable:1
+SolverTimeOut:0
+SolverTotalTime:0.002
+SolverTotalWallTime:0.003
+"""
+
+
+@pytest.fixture
+def solver(tmp_path, monkeypatch):
+    """A SavileRowSolver whose summary already holds a horizon-3 phase."""
+    monkeypatch.chdir(tmp_path)
+    phase = PhaseResult(name="solving-horizon-3", duration=1.0)
+    runner = SimpleNamespace(
+        summary=SimpleNamespace(phases=[phase]),
+        logger=None,
+    )
+    return SavileRowSolver(runner), phase
+
+
+def write_info(tmp_path, text, stem="inst.param"):
+    (tmp_path / f"{stem}.info").write_text(text)
+    return tmp_path / stem
+
+
+class TestVerbatimInfo:
+
+    def test_whole_file_is_kept(self, solver, tmp_path):
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, MINION_INFO), 3)
+        info = phase.solver_stats["savilerow_info"]
+        assert info["SolverNodes"] == 1
+        assert info["SolverSatisfiable"] == 1
+        assert info["SolverSolutionsFound"] == 1
+
+    def test_renamed_times_still_recorded(self, solver, tmp_path):
+        # The existing contract must not move: these two are what the phase model
+        # reads, and they stay top-level and snake_case.
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, MINION_INFO), 3)
+        assert phase.solver_stats["savilerow_time"] == 0.484
+        assert phase.solver_stats["solver_time"] == 0.000123
+
+    def test_verbatim_keys_are_nested_not_flattened(self, solver, tmp_path):
+        # Savile Row's CamelCase must not land beside the core's snake_case.
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, MINION_INFO), 3)
+        assert "SolverNodes" not in phase.solver_stats
+        assert set(phase.solver_stats) == {"savilerow_time", "solver_time",
+                                           "savilerow_info"}
+
+    def test_keys_are_verbatim_and_coerced(self, solver, tmp_path):
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, ORTOOLS_INFO), 3)
+        info = phase.solver_stats["savilerow_info"]
+        assert info["SolverTotalWallTime"] == 0.003   # float
+        assert info["SolverTimeOut"] == 0             # int, not "0"
+
+    def test_backends_may_disagree_on_which_keys_exist(self, solver, tmp_path):
+        # Which is why this is verbatim rather than an allow-list: Minion emits
+        # SolverNodes and no wall time, OR-Tools the reverse.
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, ORTOOLS_INFO), 3)
+        info = phase.solver_stats["savilerow_info"]
+        assert "SolverNodes" not in info
+        assert "SolverFailures" in info and "SolverTotalWallTime" in info
+
+
+class TestBestEffort:
+
+    def test_missing_info_file_records_nothing(self, solver, tmp_path):
+        # A hard timeout can kill Savile Row before it writes the file.
+        sr, phase = solver
+        sr._record_savilerow_times(tmp_path / "absent.param", 3)
+        assert phase.solver_stats == {}
+
+    def test_only_the_matching_horizon_phase_is_touched(self, solver, tmp_path):
+        # Guarded so a mismatched horizon cannot scribble on an unrelated phase.
+        sr, phase = solver
+        sr._record_savilerow_times(write_info(tmp_path, MINION_INFO), 7)
+        assert phase.solver_stats == {}
+
+    def test_info_without_the_two_times_is_still_kept(self, solver, tmp_path):
+        # The times are absent if Savile Row was interrupted mid-write; whatever
+        # did land is still worth keeping.
+        sr, phase = solver
+        sr._record_savilerow_times(
+            write_info(tmp_path, "SolverSatisfiable:0\nSolverTimeOut:1\n"), 3)
+        assert phase.solver_stats["savilerow_info"] == {"SolverSatisfiable": 0,
+                                                        "SolverTimeOut": 1}