Merge pull request #18 from SaridakisStamatisChristos/codex/add-batch-tools-and-benchmarking-features

Add batch puzzle tools and benchmark script

Author: SaridakisStamatisChristos

README.md

@@ -46,6 +46,11 @@ sudoku-dlx rate  --grid "<81chars>"
 sudoku-dlx canon --grid "<81chars>"  # D4 × bands/stacks × inner row/col × digit relabel
 # Produces a stable 81-char string for deduping datasets.
 
+# Batch tools
+sudoku-dlx gen-batch --out puzzles.txt --count 1000 --givens 30 --symmetry rot180 --minimal
+sudoku-dlx rate-file --in puzzles.txt --csv ratings.csv
+python bench/bench_file.py --in puzzles.txt
+
 # Dedupe a file of puzzles (fast)
 sudoku-dlx dedupe --in puzzles.txt --out unique.txt
 

bench/bench_file.py

@@ -0,0 +1,40 @@
+import argparse
+import statistics as st
+import sys
+import time
+
+from sudoku_dlx import from_string, solve
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Benchmark solve() on a file of puzzles (81-chars per line)."
+    )
+    parser.add_argument("--in", dest="in_path", required=True)
+    ns = parser.parse_args()
+
+    times: list[float] = []
+    solved = 0
+    with open(ns.in_path, "r", encoding="utf-8") as handle:
+        for line in handle:
+            s = "".join(ch for ch in line.strip() if not ch.isspace())
+            if not s:
+                continue
+            grid = from_string(s)
+            t0 = time.perf_counter()
+            result = solve(grid)
+            if result is None:
+                continue
+            times.append((time.perf_counter() - t0) * 1000)
+            solved += 1
+    if not times:
+        print("no puzzles measured", file=sys.stderr)
+        return 2
+    mean = st.mean(times)
+    p95 = st.quantiles(times, n=20)[-1]
+    print(f"# puzzles: {solved} · mean {mean:.2f} ms · p95 {p95:.2f} ms")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/sudoku_dlx/cli.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
 import argparse
+import csv
 import pathlib
+import random
 import sys
 from typing import Optional
 
@@ -70,6 +74,52 @@ def cmd_canon(ns: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_gen_batch(ns: argparse.Namespace) -> int:
+    """Generate many canonicalized, unique puzzles quickly."""
+
+    out_path = pathlib.Path(ns.out)
+    seen: set[str] = set()
+    rng = random.Random(ns.seed)
+    unique: list[str] = []
+    while len(unique) < ns.count:
+        grid = generate(
+            seed=rng.randrange(2**31 - 1),
+            target_givens=ns.givens,
+            minimal=ns.minimal,
+            symmetry=ns.symmetry,
+        )
+        canon = canonical_form(grid)
+        if canon in seen:
+            continue
+        seen.add(canon)
+        unique.append(canon)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with out_path.open("w", encoding="utf-8") as handle:
+        for value in unique:
+            handle.write(value + "\n")
+    print(f"# generated: {len(unique)}", file=sys.stderr)
+    return 0
+
+
+def cmd_rate_file(ns: argparse.Namespace) -> int:
+    inp = pathlib.Path(ns.in_path)
+    rows: list[tuple[str, float]] = []
+    with inp.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            s = "".join(ch for ch in line.strip() if not ch.isspace())
+            if not s:
+                continue
+            score = rate(from_string(s))
+            rows.append((s, score))
+            print(f"{score:.1f}")
+    if ns.csv_path:
+        with open(ns.csv_path, "w", newline="", encoding="utf-8") as csv_handle:
+            writer = csv.writer(csv_handle)
+            writer.writerow(["grid", "score"])
+            writer.writerows(rows)
+    return 0
+
+
 def cmd_dedupe(ns: argparse.Namespace) -> int:
     inp = pathlib.Path(ns.in_path)
     outp = pathlib.Path(ns.out_path)
@@ -126,20 +176,32 @@ def main(argv: Optional[list[str]] = None) -> int:
     canon_parser.set_defaults(func=cmd_canon)
 
     dedupe_parser = sub.add_parser(
-        "dedupe",
-        help="dedupe puzzles by canonical form (one 81-char grid per line)",
+        "dedupe", help="dedupe puzzles by canonical form (one 81-char grid per line)"
     )
+    dedupe_parser.add_argument("--in", dest="in_path", required=True, help="input text file")
     dedupe_parser.add_argument(
-        "--in", dest="in_path", required=True, help="input text file with one grid per line"
-    )
-    dedupe_parser.add_argument(
-        "--out",
-        dest="out_path",
-        required=True,
-        help="output file path for unique canonical grids",
+        "--out", dest="out_path", required=True, help="output file for unique canonical grids"
     )
     dedupe_parser.set_defaults(func=cmd_dedupe)
 
+    genb_parser = sub.add_parser("gen-batch", help="generate N unique puzzles to a file")
+    genb_parser.add_argument("--out", required=True, help="output file (81-char per line)")
+    genb_parser.add_argument("--count", type=int, default=100, help="number of puzzles")
+    genb_parser.add_argument("--givens", type=int, default=30)
+    genb_parser.add_argument(
+        "--symmetry", choices=["none", "rot180", "mix"], default="mix"
+    )
+    genb_parser.add_argument("--minimal", action="store_true")
+    genb_parser.add_argument("--seed", type=int, default=None)
+    genb_parser.set_defaults(func=cmd_gen_batch)
+
+    ratef_parser = sub.add_parser("rate-file", help="rate each puzzle in a file")
+    ratef_parser.add_argument("--in", dest="in_path", required=True)
+    ratef_parser.add_argument(
+        "--csv", dest="csv_path", help="optional CSV output path"
+    )
+    ratef_parser.set_defaults(func=cmd_rate_file)
+
     gen_parser = sub.add_parser("gen", help="generate a puzzle")
     gen_parser.add_argument("--seed", type=int, default=None)
     gen_parser.add_argument("--givens", type=int, default=28, help="target number of clues (approx)")

tests/test_batch_tools.py

@@ -0,0 +1,24 @@
+from sudoku_dlx import cli
+
+
+def test_gen_batch_and_rate_file(tmp_path):
+    out = tmp_path / "puzzles.txt"
+    rc = cli.main(
+        [
+            "gen-batch",
+            "--out",
+            str(out),
+            "--count",
+            "5",
+            "--givens",
+            "35",
+            "--symmetry",
+            "none",
+        ]
+    )
+    assert rc == 0
+    assert out.exists()
+    lines = [ln.strip() for ln in out.read_text(encoding="utf-8").splitlines() if ln.strip()]
+    assert len(lines) == 5
+    rc = cli.main(["rate-file", "--in", str(out)])
+    assert rc == 0