cdclkit 0.1.6__tar.gz → 0.2.0__tar.gz

{cdclkit-0.1.6 → cdclkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdclkit
-Version: 0.1.6
+Version: 0.2.0
 Summary: A CDCL SAT solver, preprocessor, encoding library and modelling layer, written from scratch in readable Python. Every answer comes with a certificate.
 Author: Carlo Perassi
 License-Expression: Apache-2.0
@@ -23,9 +23,9 @@ Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dratify>=0.1.7
+Requires-Dist: dratify>=0.1.11
 Provides-Extra: native
-Requires-Dist: cdclkit-native==0.1.6; extra == "native"
+Requires-Dist: cdclkit-native==0.2.0; extra == "native"
 Dynamic: license-file
 
 # cdclkit
@@ -140,8 +140,8 @@ checking a refactored Python function against the original.
 | `pyeq` | **experimental** — bounded equivalence of two Python integer functions |
 
 An optional Rust engine ([`cdclkit-native`](https://pypi.org/project/cdclkit-native/))
-is **bit-exact** with the Python one — identical conflicts, decisions and
-propagations on every instance — and about **20x faster**: the geometric mean
+runs a search **bit-exact** with the Python one — identical conflicts, decisions
+and propagations on every instance — and about **20x faster**: the geometric mean
 of per-instance ratios over the 17 benchmark instances is 20.1x, ranging from
 11x to 51x. That comes from two checkpoints recorded 34 seconds apart at the
 same commit, one sample per instance — good enough for the mean, not for any
@@ -199,6 +199,15 @@ otherwise.
   (0 of 105). See `experiments/pyeq-llm-refactor/report.md` for the full
   negative result.
 - Every performance figure comes from one machine.
+- Bit-exactness stops at the search. The two preprocessors differ: native has no
+  blocked clause elimination and visits clauses in another order. So once
+  preprocessing runs, on `--adaptive` past its probe for example, an engine can
+  give a different model, conflict count and proof. No verdict has differed, and
+  every model satisfied its formula. Proof streams differ on search-only routes
+  too, and each one replays.
+- Preprocessed proofs delete a unit clause and then rely on it. They check under
+  the rule dratify documents, which ignores such deletions, and which drat-trim
+  applies by default. A checker honouring every deletion to the letter rejects them.
 
 ## Documentation
 

{cdclkit-0.1.6 → cdclkit-0.2.0}/README.md

@@ -110,8 +110,8 @@ checking a refactored Python function against the original.
 | `pyeq` | **experimental** — bounded equivalence of two Python integer functions |
 
 An optional Rust engine ([`cdclkit-native`](https://pypi.org/project/cdclkit-native/))
-is **bit-exact** with the Python one — identical conflicts, decisions and
-propagations on every instance — and about **20x faster**: the geometric mean
+runs a search **bit-exact** with the Python one — identical conflicts, decisions
+and propagations on every instance — and about **20x faster**: the geometric mean
 of per-instance ratios over the 17 benchmark instances is 20.1x, ranging from
 11x to 51x. That comes from two checkpoints recorded 34 seconds apart at the
 same commit, one sample per instance — good enough for the mean, not for any
@@ -169,6 +169,15 @@ otherwise.
   (0 of 105). See `experiments/pyeq-llm-refactor/report.md` for the full
   negative result.
 - Every performance figure comes from one machine.
+- Bit-exactness stops at the search. The two preprocessors differ: native has no
+  blocked clause elimination and visits clauses in another order. So once
+  preprocessing runs, on `--adaptive` past its probe for example, an engine can
+  give a different model, conflict count and proof. No verdict has differed, and
+  every model satisfied its formula. Proof streams differ on search-only routes
+  too, and each one replays.
+- Preprocessed proofs delete a unit clause and then rely on it. They check under
+  the rule dratify documents, which ignores such deletions, and which drat-trim
+  applies by default. A checker honouring every deletion to the letter rejects them.
 
 ## Documentation
 

{cdclkit-0.1.6 → cdclkit-0.2.0}/cdclkit/__init__.py

@@ -52,7 +52,7 @@ from .preprocess import Preprocessor, preprocess
 from dratify.proof import DRATChecker, MemoryProof, ProofWriter, check_proof
 from .solver import Config, SAT, Solver, Stats, UNKNOWN, UNSAT
 
-__version__ = "0.1.6"
+__version__ = "0.2.0"
 
 __all__ = [
     "CNF",

{cdclkit-0.1.6 → cdclkit-0.2.0}/cdclkit/cli.py

@@ -90,6 +90,8 @@ def _emit_model(model: Sequence[bool], out=None, per_line: int = 20) -> None:
 
 
 def cmd_solve(args) -> int:
+    if args.conflicts is not None and args.conflicts < 0:
+        raise ValueError(f"--conflicts must not be negative, got {args.conflicts}")
     f = parse_dimacs_file(args.file)
     print(f"c cdclkit :: {args.file}")
     print(f"c formula: {f.nvars} vars, {f.nclauses} clauses")
@@ -144,20 +146,15 @@ def cmd_solve(args) -> int:
             config=cfg,
             jobs=jobs,
             proof=proof_sink,
+            max_conflicts=args.conflicts,
         )
         print(pr.report())
         print(f"c {pr.conflicts} conflicts in {pr.seconds:.3f}s")
+        if pr.sat is None:
+            print("s UNKNOWN")
+            return EXIT_UNKNOWN
         if pr.sat:
-            if args.check_model:
-                base = original if original is not None else f
-                if base.falsified_clauses(pr.model):
-                    print("c MODEL CHECK FAILED")
-                    return EXIT_ERROR
-                print("c model verified against the input formula")
-            print("s SATISFIABLE")
-            if not args.no_model:
-                _emit_model(pr.model)
-            return EXIT_SAT
+            return _finish_sat(args, pr.model, pre, original)
         print("s UNSATISFIABLE")
         # The proof covers preprocessing *and* the search, so it is checked
         # against the original formula, not the reduced one.
@@ -173,7 +170,8 @@ def cmd_solve(args) -> int:
         if engine is None:
             return EXIT_ERROR
         pr = solve_portfolio(f, jobs=jobs, engine=engine,
-                             want_proof=proof_sink is not None)
+                             want_proof=proof_sink is not None,
+                             max_conflicts=args.conflicts)
         if not pr.finished:
             print("s UNKNOWN")
             return EXIT_UNKNOWN
@@ -197,25 +195,39 @@ def cmd_solve(args) -> int:
         print("s UNKNOWN")
         return EXIT_UNKNOWN
     if result:
-        model = s.model
-        if pre is not None:
-            model = pre.reconstruct(model)
-        if args.check_model:
-            base = original if original is not None else f
-            bad = base.falsified_clauses(model)
-            if bad:
-                print(f"c MODEL CHECK FAILED: {len(bad)} clauses unsatisfied")
-                return EXIT_ERROR
-            print("c model verified against the input formula")
-        print("s SATISFIABLE")
-        if not args.no_model:
-            _emit_model(model)
-        return EXIT_SAT
+        return _finish_sat(args, s.model, pre, original)
 
     print("s UNSATISFIABLE")
     return _finish_unsat(args, original, mem_proof, proof_sink)
 
 
+def _finish_sat(args, model, pre, original) -> int:
+    """Reconstruct, check if asked, then print the model.
+
+    Shared by every route, for the reason `_finish_unsat` is. The adaptive
+    branch had its own copy that returned before the only `pre.reconstruct`, so
+    `--preprocess --adaptive` printed a model of the reduced formula as the
+    answer: `v -1` for `(x1)`, exit 10.
+
+    `--self-check` checks a model as well as a proof. Evaluating the clauses
+    costs one pass over the input, far less than the replay an UNSAT answer
+    gets, and a self-check that only looks at one of the two verdicts leaves
+    the other on trust.
+    """
+    if pre is not None:
+        model = pre.reconstruct(model)
+    if original is not None:  # kept for exactly --check-model and --self-check
+        bad = original.falsified_clauses(model)
+        if bad:
+            print(f"c MODEL CHECK FAILED: {len(bad)} clauses unsatisfied")
+            return EXIT_ERROR
+        print("c model verified against the input formula")
+    print("s SATISFIABLE")
+    if not args.no_model:
+        _emit_model(model)
+    return EXIT_SAT
+
+
 def _finish_unsat(args, formula, mem_proof, proof_sink) -> int:
     """Self-check or write out the proof, then report.
 
@@ -456,7 +468,9 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("file")
     s.add_argument("--proof", help="write a DRAT proof here (UNSAT only)")
     s.add_argument("--self-check", action="store_true",
-                   help="keep the proof in memory and verify it before reporting UNSAT")
+                   help="keep the proof in memory and verify it before reporting "
+                        "UNSAT; verify the model against the input before "
+                        "reporting SAT")
     s.add_argument("--check-model", action="store_true",
                    help="verify the model against the input before reporting SAT")
     s.add_argument("--preprocess", action="store_true")
@@ -464,7 +478,9 @@ def build_parser() -> argparse.ArgumentParser:
                    help="probe briefly, then preprocess only if the instance "
                         "turns out to be hard enough to repay it")
     s.add_argument("--prep-rounds", type=int, default=3)
-    s.add_argument("--conflicts", type=int, default=None, help="conflict budget")
+    s.add_argument("--conflicts", type=int, default=None,
+                   help="conflict budget; under -j, per worker. Out of budget is "
+                        "s UNKNOWN, exit 0")
     # Every search default comes from Config() rather than a literal. They were
     # literals, and --restart drifted to "glucose" while the library moved to
     # "luby" -- so the CLI quietly ran the policy the CHANGELOG says was
@@ -521,7 +537,8 @@ def build_parser() -> argparse.ArgumentParser:
     mu.add_argument("--method", default="deletion",
                     choices=["deletion", "quickxplain", "core"])
     mu.add_argument("--verify", action="store_true",
-                    help="check that the result is unsatisfiable and minimal")
+                    help="check that the result is unsatisfiable and minimal; a "
+                         "core need not be, so --method core can exit 1 here")
     mu.set_defaults(func=cmd_mus)
 
     st = sub.add_parser("stats", help="formula statistics")

{cdclkit-0.1.6 → cdclkit-0.2.0}/cdclkit/encodings.py

@@ -101,6 +101,12 @@ class Encoder:
     halves the clause count, and :meth:`tseitin` does apply it when you tell it
     the polarity; the individual ``*_gate`` helpers stay complete because they
     are also used to *define* variables the caller may reference either way.
+
+    A constraint may name variables the sink has not seen, as ``from_dimacs``
+    makes easy: anything that needs an auxiliary variable first grows the sink to
+    cover its own inputs. It cannot know about inputs of a *later* constraint, so
+    a program that numbers its own variables should declare them before the first
+    constraint rather than leave them to be taken.
     """
 
     #: Cap on direct XOR expansion, which emits 2^(k-1) clauses.  16 inputs is
@@ -143,6 +149,23 @@ class Encoder:
         for c in clauses:
             self.add(c)
 
+    def _declare(self, lits: Iterable[int]) -> None:
+        """Grow the sink to cover `lits`, before asking it for a fresh variable.
+
+        Its next variable is otherwise whatever it has not seen, which may be one
+        of these: the binary encoding of two undeclared inputs read `x1 -> ~x1`.
+        """
+        top = max(lits, default=-1) >> 1
+        while self.sink.nvars <= top:
+            self.sink.new_var()
+
+    def _declare_expr(self, expr) -> None:
+        if isinstance(expr, tuple):
+            for e in expr[1:]:
+                self._declare_expr(e)
+        elif not isinstance(expr, bool):
+            self._declare((expr,))
+
     @property
     def true_lit(self) -> int:
         """A literal that is forced true, created on first use."""
@@ -160,6 +183,7 @@ class Encoder:
 
     def and_gate(self, lits: Sequence[int], out: int | None = None) -> int:
         """``out <-> AND(lits)``.  Returns ``out``."""
+        self._declare(lits if out is None else [*lits, out])
         lits = self._simplify_and(lits)
         if lits is None:
             return self.false_lit
@@ -185,6 +209,7 @@ class Encoder:
 
     def xor_gate(self, a: int, b: int, out: int | None = None) -> int:
         """``out <-> a XOR b``."""
+        self._declare((a, b) if out is None else (a, b, out))
         key = ("xor", min(a, b), max(a, b))
         if out is None and key in self._cache:
             return self._cache[key]
@@ -205,6 +230,7 @@ class Encoder:
         on the chain is as strong as on the direct form as long as literals are
         fixed from the ends inwards.
         """
+        self._declare(lits)
         if not lits:
             if value:
                 self.add([])  # empty XOR is false; asserting true is a contradiction
@@ -225,6 +251,7 @@ class Encoder:
 
     def ite(self, c: int, t: int, e: int, out: int | None = None) -> int:
         """``out <-> (c ? t : e)``, the primitive every BDD encoding needs."""
+        self._declare((c, t, e) if out is None else (c, t, e, out))
         if t == e:
             return t
         key = ("ite", c, t, e)
@@ -275,7 +302,7 @@ class Encoder:
 
             ("and", e1, e2, ...)   ("or", ...)   ("xor", e1, e2)
             ("not", e)             ("ite", c, t, e)      ("imp", a, b)
-            ("iff", a, b)          <int literal>
+            ("iff", a, b)          <int literal>      True      False
 
         ``polarity`` is +1 when the expression only ever needs to be *forced
         true* (so only the ``inputs -> out`` direction is required), -1 for the
@@ -284,33 +311,40 @@ class Encoder:
         occurs with one polarity can always be set to the value its definition
         prescribes.
         """
+        self._declare_expr(expr)
+        return self._tseitin(expr, polarity)
+
+    def _tseitin(self, expr, polarity: int) -> int:
+        # before the int test, because True is the int 1 and 1 is a literal
+        if isinstance(expr, bool):
+            return self.true_lit if expr else self.false_lit
         if isinstance(expr, int):
             return expr
         op = expr[0]
         if op == "not":
-            return neg(self.tseitin(expr[1], -polarity))
+            return neg(self._tseitin(expr[1], -polarity))
         if op == "and":
-            kids = [self.tseitin(e, polarity) for e in expr[1:]]
+            kids = [self._tseitin(e, polarity) for e in expr[1:]]
             return self._and_pol(kids, polarity)
         if op == "or":
-            kids = [self.tseitin(e, polarity) for e in expr[1:]]
+            kids = [self._tseitin(e, polarity) for e in expr[1:]]
             return neg(self._and_pol([neg(k) for k in kids], -polarity))
         if op == "imp":
-            a = self.tseitin(expr[1], -polarity)
-            b = self.tseitin(expr[2], polarity)
+            a = self._tseitin(expr[1], -polarity)
+            b = self._tseitin(expr[2], polarity)
             return neg(self._and_pol([a, neg(b)], -polarity))
         if op == "iff":
-            a = self.tseitin(expr[1], 0)
-            b = self.tseitin(expr[2], 0)
+            a = self._tseitin(expr[1], 0)
+            b = self._tseitin(expr[2], 0)
             return neg(self.xor_gate(a, b))
         if op == "xor":
-            a = self.tseitin(expr[1], 0)
-            b = self.tseitin(expr[2], 0)
+            a = self._tseitin(expr[1], 0)
+            b = self._tseitin(expr[2], 0)
             return self.xor_gate(a, b)
         if op == "ite":
-            c = self.tseitin(expr[1], 0)
-            t = self.tseitin(expr[2], polarity)
-            e = self.tseitin(expr[3], polarity)
+            c = self._tseitin(expr[1], 0)
+            t = self._tseitin(expr[2], polarity)
+            e = self._tseitin(expr[3], polarity)
             return self.ite(c, t, e)
         raise ValueError(f"unknown operator {op!r}")
 
@@ -334,14 +368,15 @@ class Encoder:
 
     def assert_expr(self, expr) -> None:
         """Force an expression tree to be true, with polarity optimisation."""
+        self._declare_expr(expr)
         if isinstance(expr, tuple) and expr[0] == "and":
             for e in expr[1:]:
                 self.assert_expr(e)
             return
         if isinstance(expr, tuple) and expr[0] == "or":
-            self.add([self.tseitin(e, +1) for e in expr[1:]])
+            self.add([self._tseitin(e, +1) for e in expr[1:]])
             return
-        self.add([self.tseitin(expr, +1)])
+        self.add([self._tseitin(expr, +1)])
 
     # ------------------------------------------------------------ at-most-one
 
@@ -367,6 +402,7 @@ class Encoder:
         n = len(lits)
         if n <= 1:
             return
+        self._declare(lits)
         bits = max(1, (n - 1).bit_length())
         code = [self.new_lit() for _ in range(bits)]
         for i, x in enumerate(lits):
@@ -387,6 +423,7 @@ class Encoder:
         if len(lits) <= group:
             self.amo_pairwise(lits)
             return
+        self._declare(lits)
         commanders: list[int] = []
         for i in range(0, len(lits), group):
             g = lits[i : i + group]
@@ -444,6 +481,7 @@ class Encoder:
             for x in lits:
                 self.add([neg(x)])
             return
+        self._declare(lits)
         s = [[self.new_lit() for _ in range(k)] for _ in range(n - 1)]
         self.add([neg(lits[0]), s[0][0]])
         for j in range(1, k):
@@ -465,9 +503,12 @@ class Encoder:
 
     def at_most_k(self, lits: Sequence[int], k: int, method: str = "auto") -> None:
         n = len(lits)
+        if k < 0:  # before `k >= n`, which would call -1 of nothing vacuous
+            self.add([])
+            return
         if k >= n:
             return
-        if k <= 0:
+        if k == 0:
             for x in lits:
                 self.add([neg(x)])
             return
@@ -517,6 +558,7 @@ class Encoder:
         """
         if len(weights) != len(lits):
             raise ValueError("weights and literals must have equal length")
+        self._declare(lits)
         ws: list[int] = []
         ls: list[int] = []
         b = bound
@@ -595,20 +637,24 @@ class Totalizer:
 
     ``max_count`` truncates the counter: outputs above the cut are never
     created, since a bound of k never needs to distinguish k+2 from k+3.  The
-    truncated version is still arc consistent for the bound it was built for.
+    truncated version is still arc consistent for the bound it was built for,
+    and it cannot express anything beyond: ``sum <= k`` for k >= max_count and
+    ``sum >= k`` for k > max_count raise ``ValueError``, unless the inputs alone
+    decide them.
     """
 
     def __init__(self, enc: Encoder, lits: Sequence[int], max_count: int | None = None):
         self.enc = enc
         self.inputs = list(lits)
+        enc._declare(self.inputs)
         self.max_count = len(self.inputs) if max_count is None else min(
             max_count, len(self.inputs)
         )
         self.outputs = self._build(self.inputs)
 
     def _build(self, lits: Sequence[int]) -> list[int]:
-        if len(lits) == 1:
-            return [lits[0]]
+        if len(lits) <= 1:
+            return list(lits)
         mid = len(lits) // 2
         a = self._build(lits[:mid])
         b = self._build(lits[mid:])
@@ -653,17 +699,26 @@ class Totalizer:
             return None
         if k < 0:
             return self.enc.false_lit
-        if k >= len(self.outputs):
-            return None
+        self._require_output(k)
         return neg(self.outputs[k])
 
     def at_least_lit(self, k: int) -> int | None:
         if k <= 0:
             return None
-        if k > len(self.inputs) or k > len(self.outputs):
+        if k > len(self.inputs):
             return self.enc.false_lit
+        self._require_output(k - 1)
         return self.outputs[k - 1]
 
+    def _require_output(self, i: int) -> None:
+        # Missing here means this counter stopped short, and says nothing about
+        # the bound. Reading it as "vacuous" dropped a constraint, and as
+        # "impossible" made a feasible problem unsatisfiable, with a valid proof.
+        if i >= len(self.outputs):
+            raise ValueError(
+                f"this counter was truncated with max_count={self.max_count}, so "
+                f"it cannot count to {i + 1} of its {len(self.inputs)} inputs")
+
     def assert_at_most(self, k: int) -> None:
         l = self.at_most_lit(k)
         if l is not None:
@@ -754,6 +809,8 @@ class Optimiser:
     def solve_with_bound(self, bound: int | None, permanent: bool = False):
         """Solve demanding ``count <= bound``.  Returns a model or None."""
         assumptions: list[int] = []
+        if bound is not None and bound < 0 and self.totalizer is None:
+            return None  # nothing to count, so a count of 0, which is not <= -1
         if bound is not None and self.totalizer is not None:
             lit = self.totalizer.at_most_lit(bound)
             if lit is not None:
@@ -772,21 +829,29 @@ class Optimiser:
 
         Every iteration produces a real model, so stopping early still leaves
         :attr:`best` holding the best solution found -- the property that
-        matters when there is a time budget.
+        matters when there is a time budget. It only ever improves, whatever a
+        later call asks for. `max_iterations` applies to this call, so a loop
+        can resume with the same budget each time; :attr:`iterations` is the
+        total so far.
         """
         bound = target
+        if bound is None and self.best is not None:
+            bound = self.best[0] - 1
+        done = 0
         while True:
             model = self.solve_with_bound(bound)
             if model is None:
                 break
             self.iterations += 1
+            done += 1
             n = self.count(model)
-            self.best = (n, model)
-            if on_improve is not None:
-                on_improve(n, model)
+            if self.best is None or n < self.best[0]:
+                self.best = (n, model)
+                if on_improve is not None:
+                    on_improve(n, model)
             if n == 0:
                 break
-            if max_iterations and self.iterations >= max_iterations:
+            if max_iterations and done >= max_iterations:
                 break
             bound = n - 1
         return self.result()