cdclkit 0.1.3__tar.gz → 0.1.5__tar.gz

{cdclkit-0.1.3 → cdclkit-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdclkit
-Version: 0.1.3
+Version: 0.1.5
 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
@@ -17,14 +17,15 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dratify>=0.1.4
+Requires-Dist: dratify>=0.1.7
 Provides-Extra: native
-Requires-Dist: cdclkit-native==0.1.3; extra == "native"
+Requires-Dist: cdclkit-native==0.1.5; extra == "native"
 Dynamic: license-file
 
 # cdclkit
@@ -142,9 +143,11 @@ An optional Rust engine ([`cdclkit-native`](https://pypi.org/project/cdclkit-nat
 is **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. Regenerate it with `make history` (the `python` and `native`
-checkpoints in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for
-the method. The pure-Python path has zero third-party
+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
+single row. Regenerate it with `make history` (the `python` and `native`
+entries in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for the
+method. The pure-Python path has zero third-party
 dependencies and is the one that must never break.
 
 ## Relationship to dratify

{cdclkit-0.1.3 → cdclkit-0.1.5}/README.md

@@ -113,9 +113,11 @@ An optional Rust engine ([`cdclkit-native`](https://pypi.org/project/cdclkit-nat
 is **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. Regenerate it with `make history` (the `python` and `native`
-checkpoints in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for
-the method. The pure-Python path has zero third-party
+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
+single row. Regenerate it with `make history` (the `python` and `native`
+entries in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for the
+method. The pure-Python path has zero third-party
 dependencies and is the one that must never break.
 
 ## Relationship to dratify

{cdclkit-0.1.3 → cdclkit-0.1.5}/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.3"
+__version__ = "0.1.5"
 
 __all__ = [
     "CNF",

{cdclkit-0.1.3 → cdclkit-0.1.5}/cdclkit/solver.py

@@ -392,6 +392,11 @@ class Solver:
         #: depth. Only meaningful when cfg.target_phase is on.
         self._target = bytearray()
         self._target_size = 0
+        #: how much of the current trail the target already records: for every
+        #: i < _target_synced, _target holds trail[i]'s value. The trail only
+        #: grows by appending and only shrinks in _cancel_until, so a prefix
+        #: that has been copied stays copied until a backtrack cuts into it.
+        self._target_synced = 0
         self._walk_best = 1 << 30
         self._walk_stale = 0
         self.frozen = bytearray()  # variables excluded from decisions
@@ -605,6 +610,8 @@ class Solver:
         del trail[bound:]
         del self.trail_lim[level:]
         self.qhead = len(trail)
+        if self._target_synced > bound:
+            self._target_synced = bound
 
     # ------------------------------------------------------------ propagation
 
@@ -1154,6 +1161,7 @@ class Solver:
         self._target[:] = best
         self.polarity[:] = best
         self._target_size = 0   # the target now describes the walk, not a trail
+        self._target_synced = 0
 
     # -------------------------------------------------------------- restarts
 
@@ -1229,13 +1237,21 @@ class Solver:
                     self._reduce_db()
             else:
                 # A new deepest conflict-free trail: remember the assignment
-                # that reached it. Copying costs O(|trail|), but only on a
-                # strict improvement, and improvements become rare quickly.
+                # that reached it -- copying only what the target does not
+                # already hold. This used to copy the whole trail on every
+                # improvement, on the theory that improvements become rare
+                # quickly. They do once conflicts start; a search that makes
+                # many decisions without one improves on every decision, and
+                # n of them cost O(n^2) (tests/test_target_scaling.py). The
+                # target ends up byte-for-byte what the full copy produced.
                 if self.cfg.target_phase and len(self.trail) > self._target_size:
-                    self._target_size = len(self.trail)
+                    trail = self.trail
+                    self._target_size = len(trail)
                     target = self._target
-                    for t in self.trail:
+                    for i in range(self._target_synced, len(trail)):
+                        t = trail[i]
                         target[t >> 1] = 0 if (t & 1) else 1
+                    self._target_synced = len(trail)
 
                 if max_conflicts is not None and conflicts >= max_conflicts:
                     self._cancel_until(len(self.assumptions_applied))

{cdclkit-0.1.3 → cdclkit-0.1.5}/cdclkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdclkit
-Version: 0.1.3
+Version: 0.1.5
 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
@@ -17,14 +17,15 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dratify>=0.1.4
+Requires-Dist: dratify>=0.1.7
 Provides-Extra: native
-Requires-Dist: cdclkit-native==0.1.3; extra == "native"
+Requires-Dist: cdclkit-native==0.1.5; extra == "native"
 Dynamic: license-file
 
 # cdclkit
@@ -142,9 +143,11 @@ An optional Rust engine ([`cdclkit-native`](https://pypi.org/project/cdclkit-nat
 is **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. Regenerate it with `make history` (the `python` and `native`
-checkpoints in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for
-the method. The pure-Python path has zero third-party
+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
+single row. Regenerate it with `make history` (the `python` and `native`
+entries in `bench/history.jsonl`); see [BENCHMARKS.md](BENCHMARKS.md) for the
+method. The pure-Python path has zero third-party
 dependencies and is the one that must never break.
 
 ## Relationship to dratify

{cdclkit-0.1.3 → cdclkit-0.1.5}/cdclkit.egg-info/SOURCES.txt

@@ -38,4 +38,6 @@ tests/test_portfolio.py
 tests/test_preprocess.py
 tests/test_proof.py
 tests/test_pyeq.py
-tests/test_solver.py
+tests/test_readme.py
+tests/test_solver.py
+tests/test_target_scaling.py

cdclkit-0.1.5/cdclkit.egg-info/requires.txt

@@ -0,0 +1,4 @@
+dratify>=0.1.7
+
+[native]
+cdclkit-native==0.1.5

{cdclkit-0.1.3 → cdclkit-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdclkit"
-version = "0.1.3"
+version = "0.1.5"
 description = "A CDCL SAT solver, preprocessor, encoding library and modelling layer, written from scratch in readable Python. Every answer comes with a certificate."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Programming Language :: Rust",
     "Topic :: Scientific/Engineering :: Mathematics",
 ]
@@ -29,13 +30,13 @@ classifiers = [
 # The only dependency is the proof checker, which itself has none. The solver
 # uses it to check its own refutations, so the checker is exercised by every
 # test run here as well as by its own suite.
-dependencies = ["dratify>=0.1.4"]
+dependencies = ["dratify>=0.1.7"]
 
 [project.optional-dependencies]
 # The Rust accelerator, as abi3 wheels for Linux and macOS. Pinned exactly:
 # the two are bit-exact by construction and a mismatched pair is a divergence
 # nobody would look for. tests/test_packaging.py enforces the pin.
-native = ["cdclkit-native==0.1.3"]
+native = ["cdclkit-native==0.1.5"]
 
 [project.scripts]
 cdclkit = "cdclkit.__main__:main"

{cdclkit-0.1.3 → cdclkit-0.1.5}/tests/test_packaging.py

@@ -103,6 +103,31 @@ class TestVersions(unittest.TestCase):
         self.assertRegex(cdclkit.__version__, r"^\d+\.\d+\.\d+([.-]\w+)?$")
 
 
+class TestSmokeTestIsCurrent(unittest.TestCase):
+    """The post-install smoke test must ask for the modules that exist.
+
+    Its list named `cnf`, `lits` and `proof` long after they moved to
+    `dratify`, so `make smoke` failed on every run and nobody saw, because
+    nothing ran it automatically. CI now runs it; this keeps its list honest.
+    """
+
+    def test_the_smoke_module_list_matches_the_package(self):
+        import importlib.util
+
+        spec = importlib.util.spec_from_file_location(
+            "smoke_installed", ROOT / "tests" / "smoke_installed.py")
+        smoke = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(smoke)
+
+        on_disk = {p.stem for p in (ROOT / "cdclkit").glob("*.py")
+                   if p.stem not in ("__init__", "__main__")}
+        self.assertEqual(
+            set(smoke.MODULES), on_disk,
+            "tests/smoke_installed.py MODULES does not match cdclkit/*.py. "
+            "A module added here and not there ships untested; one listed "
+            "there and not here makes the smoke test fail on every run.")
+
+
 class TestEntryPoints(unittest.TestCase):
     def test_console_script_target_exists_and_is_callable(self):
         """`cdclkit = "cdclkit.cli:main"` has to still resolve after a refactor."""

cdclkit-0.1.5/tests/test_readme.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Carlo Perassi. Licensed under the Apache License 2.0.
+"""Every Python example in the README has to run, and print what it says.
+
+The README is the first code a visitor copies, and until this test existed
+nothing executed it. The sibling project found its own example broken this
+way: fine on the input its author tried, and failing on the first line for
+the most common input there is.
+
+Each ```python block runs in a fresh namespace from a temporary directory. A
+`print(x)  # value` line is an assertion: the printed value must match the
+first word of the comment, so an example that runs but answers wrongly fails
+too. A block preceded by `<!-- readme-test: skip ... -->` is not executed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import os
+import pathlib
+import re
+import shutil
+import tempfile
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+SKIP = re.compile(r"<!--\s*readme-test:\s*skip")
+EXPECT = re.compile(r"^\s*print\(.*\)\s*#\s*(\S+)")
+
+
+def blocks(markdown: str) -> list[tuple[int, str, bool]]:
+    """(line number, source, skipped) for every ```python block."""
+    lines = markdown.splitlines()
+    out, i = [], 0
+    while i < len(lines):
+        if lines[i].strip() == "```python":
+            start = i + 1
+            skipped = i > 0 and bool(SKIP.search(lines[i - 1]))
+            j = start
+            while lines[j].strip() != "```":
+                j += 1
+            out.append((start + 1, "\n".join(lines[start:j]) + "\n", skipped))
+            i = j
+        i += 1
+    return out
+
+
+def expected_output(source: str) -> list[str]:
+    return [m.group(1) for ln in source.splitlines()
+            if (m := EXPECT.match(ln))]
+
+
+class TestReadmeExamples(unittest.TestCase):
+    def setUp(self):
+        self.dir = pathlib.Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir)
+        self.all = blocks((ROOT / "README.md").read_text(encoding="utf-8"))
+
+    def test_the_readme_has_examples_to_test(self):
+        """Guards the extractor: a regex that matches nothing passes everything."""
+        self.assertGreaterEqual(len(self.all), 1)
+
+    def test_every_example_runs_and_prints_what_it_promises(self):
+        ran = 0
+        for lineno, source, skipped in self.all:
+            if skipped:
+                continue
+            with self.subTest(line=lineno):
+                want = expected_output(source)
+                out = io.StringIO()
+                here = os.getcwd()
+                os.chdir(self.dir)
+                try:
+                    with contextlib.redirect_stdout(out):
+                        exec(compile(source, "README.md", "exec"),
+                             {"__name__": "__readme__"})
+                finally:
+                    os.chdir(here)
+                got = out.getvalue().split()
+                self.assertEqual(
+                    got, want,
+                    f"README.md:{lineno} printed {got}, but its comments "
+                    f"promise {want}")
+                ran += 1
+        self.assertGreater(ran, 0, "no README example was run")
+
+
+if __name__ == "__main__":
+    unittest.main()

cdclkit-0.1.5/tests/test_target_scaling.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Carlo Perassi. Licensed under the Apache License 2.0.
+"""Target phases must not make the search quadratic in the number of variables.
+
+With target phases on (the default), each time the trail reached a new depth
+the solver copied the whole trail into the target. The comment beside it said
+improvements "become rare quickly". That holds only once conflicts happen. A
+search that makes many decisions without a conflict improves on every one, so
+n decisions copied 1, 2, ..., n entries.
+
+Measured on the Python engine, solving one unit clause in a formula that
+declares n variables: 4,096 took 0.8 s, 16,384 took 10.6 s and 65,536 took
+144 s -- each 4x costing about 13x. Turning target phases off made 16,384
+take 0.11 s. Since dratify 0.1.7 a header may declare up to 2^20 variables
+from a file of any length, so a 22-byte file cost hours of CPU.
+
+The test compares scaling rather than absolute time, which shared CI runners
+cannot be trusted with: quadrupling the variables should cost about 4x when
+the search is linear and about 16x when it is quadratic. The threshold sits
+between them, and each size takes the best of three runs to damp noise.
+"""
+
+from __future__ import annotations
+
+import time
+import unittest
+
+from cdclkit import native
+from cdclkit.solver import Solver
+
+
+def _solve(nvars: int, engine: str) -> bool:
+    """One unit clause, `nvars` declared: every other variable is a decision."""
+    if engine == "native":
+        s = native.require().Solver(nvars)   # defaults match Config
+    else:
+        s = Solver(nvars)
+    s.add_clause([0])
+    return s.solve()
+
+
+def _seconds(nvars: int, engine: str) -> float:
+    best = float("inf")
+    for _ in range(3):
+        t0 = time.perf_counter()
+        sat = _solve(nvars, engine)
+        best = min(best, time.perf_counter() - t0)
+        assert sat
+    return best
+
+
+class TestUnusedVariablesCostLinearTime(unittest.TestCase):
+    #: quadrupling: ~4x if linear, ~16x if quadratic
+    LIMIT = 8.0
+
+    def _check(self, engine: str, small: int):
+        t_small = _seconds(small, engine)
+        t_large = _seconds(4 * small, engine)
+        ratio = t_large / max(t_small, 1e-4)
+        self.assertLess(
+            ratio, self.LIMIT,
+            f"{engine}: {small:,} vars took {t_small:.3f}s and "
+            f"{4 * small:,} took {t_large:.3f}s, a {ratio:.1f}x increase for "
+            f"4x the variables. Linear is ~4x; this is closer to quadratic.")
+
+    def test_python_engine(self):
+        self._check("python", 4096)
+
+    @unittest.skipUnless(native.available(),
+                         "native engine not built for this interpreter")
+    def test_native_engine(self):
+        # Rust is fast enough that the quadratic term only dominates at
+        # larger sizes.
+        self._check("native", 32768)
+
+
+if __name__ == "__main__":
+    unittest.main()

cdclkit-0.1.3/cdclkit.egg-info/requires.txt

@@ -1,4 +0,0 @@
-dratify>=0.1.4
-
-[native]
-cdclkit-native==0.1.3