cdclkit 0.1.0__py3-none-any.whl

cdclkit/mus.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Carlo Perassi. Licensed under the Apache License 2.0.
+"""Minimal unsatisfiable subsets: *why* is this formula unsatisfiable?
+
+An UNSAT answer says a formula has no model. A **MUS** says which clauses are
+to blame: an unsatisfiable subset of the clauses such that removing any one of
+them makes it satisfiable. For a specification with 10,000 constraints and a
+contradiction somewhere in it, that difference is the difference between "your
+model is broken" and "these six lines conflict".
+
+Formally, `M ⊆ F` is a MUS when `M` is unsatisfiable and every proper subset of
+`M` is satisfiable. Minimal, not minimum: a formula can have many MUSes of
+different sizes, and finding the smallest is a harder (Σ₂ᵖ-complete) problem.
+Every algorithm here returns *a* MUS.
+
+The machinery is selector variables. Clause `cᵢ` becomes `¬sᵢ ∨ cᵢ`, so
+assuming `sᵢ` switches the clause on and assuming nothing leaves it inert. Then
+"is this subset unsatisfiable?" is one incremental solve under assumptions, the
+solver keeps everything it learned across all of them, and the unsatisfiable
+core the solver already computes (`Solver.conflict`) gives a free head start:
+it is an unsatisfiable subset, just not necessarily a minimal one.
+
+Two algorithms:
+
+**Deletion-based.** Try each candidate clause in turn; if the rest are still
+unsatisfiable, drop it permanently. Exactly `|M|` solver calls after the
+initial core, each one UNSAT-or-SAT, and the result is minimal by construction.
+Simple and hard to get wrong.
+
+**QuickXplain** (Junker 2004). Divide and conquer: split the candidate set,
+recurse on halves, and only descend into a half that is actually needed. When
+the MUS is small relative to the formula it takes O(|M| log(|F|/|M|)) calls
+instead of O(|F|), which is a large win on the realistic case where a handful
+of constraints out of thousands are guilty.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from dratify.cnf import CNF
+from dratify.lits import mk_lit, neg
+from .solver import Solver
+
+__all__ = ["MUSExtractor", "mus", "shrink_core"]
+
+
+class MUSExtractor:
+    """Wraps a formula with selector variables for incremental subset testing."""
+
+    def __init__(self, formula: CNF) -> None:
+        self.formula = formula
+        self.solver = Solver(formula.nvars)
+        self.selectors: list[int] = []
+        for clause in formula.clauses:
+            s = mk_lit(self.solver.new_var())
+            self.selectors.append(s)
+            # (~s or clause): assuming s switches the clause on
+            self.solver.add_clause([neg(s)] + list(clause))
+        self.calls = 0
+
+    def is_unsat(self, subset: Sequence[int]) -> bool:
+        """True when the clauses indexed by ``subset`` are unsatisfiable."""
+        self.calls += 1
+        return not self.solver.solve([self.selectors[i] for i in subset])
+
+    def _all(self, subset: Sequence[int] | None) -> list[int]:
+        cands = list(range(len(self.selectors))) if subset is None else list(subset)
+        return cands if self.is_unsat(cands) else []
+
+    def core(self, subset: Sequence[int] | None = None) -> list[int]:
+        """An unsatisfiable core: the subset the solver actually used.
+
+        Not minimal, but usually far smaller than the input, and it costs
+        nothing extra -- the solver computes it during the failed solve.
+        """
+        candidates = list(range(len(self.selectors))) if subset is None else list(subset)
+        if not self.is_unsat(candidates):
+            return []
+        by_sel = {self.selectors[i]: i for i in candidates}
+        used = [by_sel[l] for l in self.solver.conflict if l in by_sel]
+        return sorted(used) if used else candidates
+
+    # -- algorithms ---------------------------------------------------------
+
+    def deletion(self, subset: Sequence[int] | None = None, use_core: bool = True) -> list[int]:
+        """Deletion-based MUS extraction.
+
+        ``use_core`` first shrinks the candidate set to the solver's own
+        unsatisfiable core, which is nearly always worth it: one solve replaces
+        many.  Set it to False to measure the algorithms on equal footing.
+        """
+        candidates = self.core(subset) if use_core else self._all(subset)
+        if not candidates:
+            return []
+        keep: list[int] = []
+        remaining = list(candidates)
+        while remaining:
+            c = remaining.pop()
+            if self.is_unsat(keep + remaining):
+                continue  # c is not needed
+            keep.append(c)
+        return sorted(keep)
+
+    def quickxplain(self, subset: Sequence[int] | None = None,
+                    use_core: bool = True) -> list[int]:
+        """Junker's QuickXplain: divide and conquer over the candidate set."""
+        candidates = self.core(subset) if use_core else self._all(subset)
+        if not candidates:
+            return []
+        if self.is_unsat([]):
+            return []
+        return sorted(self._qx([], [], candidates))
+
+    def _qx(self, background: list[int], delta: list[int], candidates: list[int]) -> list[int]:
+        if delta and self.is_unsat(background):
+            return []
+        if len(candidates) == 1:
+            return list(candidates)
+        mid = len(candidates) // 2
+        first, second = candidates[:mid], candidates[mid:]
+        d1 = self._qx(background + first, first, second)
+        d2 = self._qx(background + d1, d1, first)
+        return d1 + d2
+
+    # -- verification -------------------------------------------------------
+
+    def verify(self, subset: Sequence[int]) -> tuple[bool, str]:
+        """Check the defining property: unsatisfiable, and minimally so.
+
+        Costs ``|subset| + 1`` solver calls.  Cheap enough to run in anger, and
+        the test suite always does -- a "minimal" set nobody checked is just a
+        set.
+        """
+        if not self.is_unsat(subset):
+            return False, "the subset is satisfiable"
+        for i in subset:
+            rest = [j for j in subset if j != i]
+            if self.is_unsat(rest):
+                return False, f"clause {i} is redundant: the rest is still unsatisfiable"
+        return True, f"verified: unsatisfiable, and all {len(subset)} clauses are necessary"
+
+
+def mus(formula: CNF, method: str = "deletion") -> list[int]:
+    """Return the indices of a minimal unsatisfiable subset of ``formula``.
+
+    Returns an empty list when the formula is satisfiable.
+    """
+    ex = MUSExtractor(formula)
+    if method == "deletion":
+        return ex.deletion()
+    if method == "quickxplain":
+        return ex.quickxplain()
+    raise ValueError(f"unknown MUS method {method!r}")
+
+
+def shrink_core(formula: CNF) -> list[int]:
+    """The cheap option: the solver's own unsatisfiable core, unminimised."""
+    return MUSExtractor(formula).core()

cdclkit/native.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Carlo Perassi. Licensed under the Apache License 2.0.
+"""Optional native engine: loader and capability probe.
+
+cdclkit's Python core has no dependencies and never will. The native engine is a
+strictly optional accelerator, and this module is the only place that knows
+whether it exists.
+
+The contract, in both directions:
+
+* **If the compiled module is absent, nothing breaks.** `available()` returns
+  False, every caller falls back to Python, and the test suite still passes in
+  full under a plain `python3` with no Rust toolchain anywhere. That property
+  is tested, not assumed -- it is what lets the port proceed in small commits
+  without the repo ever being in a broken state.
+* **If it is present, it is opt-in.** Nothing selects the native path on its
+  own. A caller asks for it explicitly (`--engine native`, or
+  `CDCLKIT_ENGINE=native`), because a silent switch between two implementations
+  is how differential bugs hide.
+
+Building it::
+
+    python3 -m venv .venv
+    .venv/bin/pip install maturin
+    make native                 # or: cd native && ../.venv/bin/maturin develop --release
+
+The build installs into `.venv`, so `.venv/bin/python` sees the native engine
+and the system interpreter does not. That separation is deliberate: it keeps a
+dependency-free path available at all times.
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = [
+    "available",
+    "require",
+    "module",
+    "version",
+    "build_hint",
+    "engine_requested",
+]
+
+try:  # pragma: no cover - the import result is the thing being reported
+    import cdclkit_native as _native
+except ImportError:  # pragma: no cover
+    _native = None
+else:  # pragma: no cover - depends on whether the module was built
+    # The Rust checker lives in the `dratify` crate, which this crate embeds,
+    # but `dratify` ships no Python bindings of its own yet. Hand ours over so
+    # that check_proof(engine="auto") uses it instead of falling back to the
+    # pure-Python checker, which is ~18x slower on large proofs.
+    #
+    # This is not the silent engine switch the rest of this module warns about.
+    # Two checkers must agree by construction -- if they ever disagree that is
+    # a bug worth surfacing, not a difference worth preserving. The solver is
+    # the thing that stays explicitly opt-in.
+    try:
+        import dratify as _dratify
+        _dratify.register_native(_native)
+    except (ImportError, AttributeError):  # dratify < 0.1.1 has no seam
+        pass
+
+
+BUILD_HINT = (
+    "the native engine is not built for this interpreter. Build it with:\n"
+    "    python3 -m venv .venv && .venv/bin/pip install maturin\n"
+    "    make native\n"
+    "then run with .venv/bin/python. The pure-Python engine needs none of this."
+)
+
+
+def available() -> bool:
+    """True when the compiled native module can be imported."""
+    return _native is not None
+
+
+def module():
+    """The native module, or None.  Prefer `require()` when you need it."""
+    return _native
+
+
+def require():
+    """Return the native module, raising a useful error when it is missing."""
+    if _native is None:
+        raise RuntimeError(BUILD_HINT)
+    return _native
+
+
+def version() -> str | None:
+    return getattr(_native, "__version__", None) if _native else None
+
+
+def build_hint() -> str:
+    return BUILD_HINT
+
+
+def engine_requested(default: str = "python") -> str:
+    """Which engine the environment asks for.
+
+    Reads `CDCLKIT_ENGINE`; an explicit request for an unavailable engine is an
+    error rather than a silent downgrade, because "I asked for native and got
+    Python timings" is a bad way to spend an afternoon.
+    """
+    want = os.environ.get("CDCLKIT_ENGINE", default).strip().lower()
+    if want not in ("python", "native"):
+        raise ValueError(f"unknown CDCLKIT_ENGINE {want!r} (expected python or native)")
+    if want == "native" and not available():
+        raise RuntimeError("CDCLKIT_ENGINE=native but " + BUILD_HINT)
+    return want

cdclkit/pipeline.py

@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Carlo Perassi. Licensed under the Apache License 2.0.
+"""Choosing when to preprocess, instead of always or never.
+
+Preprocessing is worth 1.3-1.5x on structured instances and a dead loss on
+instances that solve in milliseconds -- `bench/compare.py` measures both. The
+crafted families in the benchmark set finish in under a millisecond, so any
+preprocessing at all is a hundredfold overhead; the factoring and colouring
+instances take seconds, and preprocessing pays for itself several times over.
+
+Deciding by looking at the formula does not work well. Clause count is a poor
+predictor: `queens(40)` has 18 611 clauses and solves in zero conflicts, while
+`factor(16b)` has 8 051 and needs sixteen thousand. Size tells you how big the
+formula is, not how hard it is.
+
+So this asks the solver instead. Run with a small conflict budget; if the
+instance falls over quickly, nothing was spent. If the budget is exhausted, the
+instance is hard enough that preprocessing will repay its cost, so preprocess
+and solve properly. The wasted work is bounded by the budget and the learnt
+clauses from the probe are discarded -- a real cost, but a fixed and small one
+against an unbounded win.
+
+The policy is deliberately simple and its parameter is exposed, because the
+right budget depends on the ratio between preprocessing cost and solve cost on
+the machine in front of you.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Sequence
+
+from dratify.cnf import CNF
+from .solver import Config, Solver
+
+__all__ = ["solve_adaptive", "PipelineResult"]
+
+#: Conflicts to spend probing before deciding to preprocess.  At ~100k
+#: conflicts/second on the native engine this is a ~10 ms probe, which is
+#: cheaper than the fastest preprocessing run measured (~1 ms native, ~3 ms
+#: Python) on anything but the smallest instances, and negligible against the
+#: seconds-long solves where preprocessing matters.
+DEFAULT_PROBE = 1000
+
+
+class PipelineResult:
+    __slots__ = ("sat", "model", "conflicts", "seconds", "preprocessed",
+                 "probe_conflicts", "prep_seconds", "clauses_before",
+                 "clauses_after")
+
+    def __init__(self) -> None:
+        self.sat: bool | None = None
+        self.model: list[bool] | None = None
+        self.conflicts = 0
+        self.seconds = 0.0
+        self.preprocessed = False
+        self.probe_conflicts = 0
+        self.prep_seconds = 0.0
+        self.clauses_before = 0
+        self.clauses_after = 0
+
+    def report(self) -> str:
+        if not self.preprocessed:
+            return (f"c solved during the {self.probe_conflicts}-conflict probe; "
+                    f"preprocessing skipped")
+        return (f"c probe exhausted at {self.probe_conflicts} conflicts -> "
+                f"preprocessed {self.clauses_before} -> {self.clauses_after} "
+                f"clauses in {self.prep_seconds*1000:.0f} ms")
+
+
+def _native_available() -> bool:
+    from . import native
+
+    return native.available()
+
+
+def _solve(f: CNF, cfg: Config, budget: int | None, engine: str,
+           seconds: float | None = None):
+    """Returns (status, model, conflicts).  status None means budget exhausted."""
+    if engine == "native":
+        from . import native
+
+        n = native.require()
+        s = n.Solver(
+            f.nvars, restart=cfg.restart, ccmin=cfg.ccmin,
+            phase_saving=cfg.phase_saving, init_phase=cfg.init_phase,
+            target_phase=cfg.target_phase, target_reset=cfg.target_reset,
+            walk_flips=cfg.walk_flips, walk_interval=cfg.walk_interval,
+            walk_patience=cfg.walk_patience,
+            walk_min_conflicts=cfg.walk_min_conflicts,
+            var_decay=cfg.var_decay, var_decay_max=cfg.var_decay_max,
+            cla_decay=cfg.cla_decay, luby_base=float(cfg.luby_base),
+            first_reduce=cfg.first_reduce, reduce_inc=cfg.reduce_inc,
+            glue_keep=cfg.glue_keep, block_restart=cfg.block_restart,
+        )
+        for c in f.clauses:
+            if not s.add_clause(list(c)):
+                return False, None, s.conflicts
+        res = s.solve(budget, seconds)
+        if res is None:
+            return None, None, s.conflicts
+        return res, (list(s.model) if res else None), s.conflicts
+
+    s = Solver(f.nvars, config=cfg)
+    if not s.add_cnf(f):
+        return False, None, s.stats.conflicts
+    res = s.solve(max_conflicts=budget, deadline=(
+        None if seconds is None else time.perf_counter() + seconds))
+    if res is None:
+        return None, None, s.stats.conflicts
+    return res, (list(s.model) if res else None), s.stats.conflicts
+
+
+def _preprocess(f: CNF, engine: str):
+    """Returns (reduced_formula, unsat, reconstruct_fn, seconds)."""
+    t0 = time.perf_counter()
+    if engine == "native" and _native_available():
+        from . import native
+
+        n = native.require()
+        p = n.Preprocessor(f.nvars)
+        for c in f.clauses:
+            p.add_clause(list(c))
+        p.run(3)
+        red = CNF(f.nvars)
+        for c in p.reduced():
+            red.add(c)
+        red.nvars = f.nvars
+        return red, p.unsat, p.reconstruct, time.perf_counter() - t0
+
+    from .preprocess import Preprocessor
+
+    p = Preprocessor(f)
+    red = p.run()
+    return red, p.unsat, p.reconstruct, time.perf_counter() - t0
+
+
+def solve_adaptive(
+    f: CNF,
+    engine: str = "native",
+    probe: int = DEFAULT_PROBE,
+    config: Config | None = None,
+    always_preprocess: bool = False,
+    never_preprocess: bool = False,
+    jobs: int = 1,
+    seconds: float | None = None,
+) -> PipelineResult:
+    """Solve `f`, preprocessing only when a short probe says it is worth it.
+
+    `engine` selects "native" (falling back to Python when the module is
+    absent) or "python". `always_preprocess` / `never_preprocess` force the
+    decision, which is what the benchmark harness uses to measure the policy
+    against its own extremes.
+
+    `jobs > 1` runs the *post-probe* solve as a parallel portfolio. The probe
+    itself stays sequential and in-process on purpose: spawning five workers
+    costs ~60 ms, which is more than an easy instance takes to solve outright,
+    so paying it before knowing the instance is hard would throw away exactly
+    what the probe is for.
+    """
+    cfg = config or Config()
+    if engine == "native" and not _native_available():
+        engine = "python"
+
+    r = PipelineResult()
+    r.clauses_before = f.nclauses
+    t_start = time.perf_counter()
+
+    if not never_preprocess and not always_preprocess:
+        status, model, conflicts = _solve(f, cfg, probe, engine)
+        r.probe_conflicts = conflicts
+        if status is not None:
+            r.sat, r.model, r.conflicts = status, model, conflicts
+            r.seconds = time.perf_counter() - t_start
+            r.clauses_after = f.nclauses
+            return r
+
+    if never_preprocess:
+        status, model, conflicts = _solve(f, cfg, None, engine, seconds)
+        r.sat, r.model, r.conflicts = status, model, conflicts
+        r.seconds = time.perf_counter() - t_start
+        r.clauses_after = f.nclauses
+        return r
+
+    red, unsat, reconstruct, prep_s = _preprocess(f, engine)
+    r.preprocessed = True
+    r.prep_seconds = prep_s
+    r.clauses_after = red.nclauses
+
+    if unsat:
+        r.sat = False
+        r.seconds = time.perf_counter() - t_start
+        return r
+
+    if jobs > 1:
+        from .portfolio import solve_portfolio
+
+        # preprocess_workers=0 because this formula is *already* preprocessed;
+        # asking for preprocessing workers here would both redo the work and
+        # force the process-based path, paying ~60 ms of startup for nothing
+        pr = solve_portfolio(red, jobs=jobs, engine=engine, preprocess_workers=0)
+        status = pr.sat
+        model = pr.model
+        conflicts = pr.stats.get("conflicts", 0)
+    else:
+        status, model, conflicts = _solve(red, cfg, None, engine, seconds)
+    r.conflicts = conflicts + r.probe_conflicts
+    r.sat = status
+    if status:
+        r.model = list(reconstruct(model))
+    r.seconds = time.perf_counter() - t_start
+    return r