Ensure strict minimal puzzles with symmetry support

Author: SaridakisStamatisChristos

README.md

@@ -70,10 +70,19 @@ sudoku-dlx stats-file --in puzzles.txt --json stats.json --csv diff_hist.csv
 # }
 
 # Advanced generator flags:
+# Minimal & symmetry (slower; strict guarantee)
 sudoku-dlx gen   --seed 123 --givens 28 --minimal
-sudoku-dlx gen   --seed 123 --givens 28 --symmetry rot180
+sudoku-dlx gen   --seed 123 --givens 28 --minimal --symmetry rot180
 ```
 
+What this gives you
+
+Strict minimality: after generation, removing any single clue breaks uniqueness.
+
+Symmetry enforcement: rot180 removals are paired; mix keeps pairs adjacent but allows singles too.
+
+CI-safe tests: fast settings, strong assertions.
+
 ## Library (typed API)
 
 ```python

src/sudoku_dlx/generate.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import random
-from typing import Optional
+from typing import Optional, Union
 
 from .api import Grid, count_solutions, is_valid, solve
 
@@ -45,19 +45,23 @@ def _rot180(r: int, c: int) -> tuple[int, int]:
     return 8 - r, 8 - c
 
 
-def _removal_schedule(
-    symmetry: Symmetry, rng: random.Random
-) -> list[tuple[int, int] | tuple[tuple[int, int], tuple[int, int]]]:
-    """Return a shuffled list of single cells or symmetric pairs to try removing."""
+PairOrCell = Union[tuple[int, int], tuple[tuple[int, int], tuple[int, int]]]
+
+
+def _removal_schedule(symmetry: Symmetry, rng: random.Random) -> list[PairOrCell]:
+    """
+    Return a shuffled list of single cells or symmetric pairs to try
+    removing, preserving adjacency for paired removals.
+    """
 
     cells = [(r, c) for r in range(9) for c in range(9)]
     rng.shuffle(cells)
     if symmetry == "none":
-        return cells  # type: ignore[return-value]
+        return cells  # singles only
 
     # rot180 or mix → group into pairs; center maps to itself
-    seen: set[tuple[int, int]] = set()
-    pairs: list[tuple[int, int] | tuple[tuple[int, int], tuple[int, int]]] = []
+    seen: set[tuple[int,int]] = set()
+    pairs: list[PairOrCell] = []
     for (r, c) in cells:
         if (r, c) in seen:
             continue
@@ -71,10 +75,10 @@ def _removal_schedule(
 
     rng.shuffle(pairs)
     if symmetry == "rot180":
-        return pairs  # type: ignore[return-value]
+        return pairs
 
     # mix → flatten but keep pairs adjacent; mix of singles/pairs
-    flat: list[tuple[int, int] | tuple[tuple[int, int], tuple[int, int]]] = []
+    flat: list[PairOrCell] = []
     for item in pairs:
         flat.append(item)
     return flat
@@ -100,21 +104,47 @@ def _try_remove(p: Grid, r: int, c: int) -> bool:
 def _make_minimal(p: Grid) -> Grid:
     """Enforce minimality: every clue is necessary for uniqueness."""
 
+    # Strict single-clue minimality:
+    # keep removing clues as long as uniqueness still holds.
+    # Order clues by a light heuristic: remove from denser rows/cols first.
+    def clue_list(grid: Grid) -> list[tuple[int, int]]:
+        clues: list[tuple[int,int]] = []
+        for r in range(9):
+            for c in range(9):
+                if grid[r][c] != 0:
+                    clues.append((r,c))
+        # heuristic: denser row/col first
+        row_count = [sum(1 for x in grid[r] if x != 0) for r in range(9)]
+        col_count = [sum(1 for r in range(9) if grid[r][c] != 0) for c in range(9)]
+        clues.sort(key=lambda rc: -(row_count[rc[0]] + col_count[rc[1]]))
+        return clues
+
     changed = True
     while changed:
         changed = False
-        for r in range(9):
-            for c in range(9):
-                if p[r][c] == 0:
-                    continue
-                keep = p[r][c]
+        for r, c in clue_list(p):
+            keep = p[r][c]
+            p[r][c] = 0
+            if _uniqueness(p):
+                # removal kept; continue loop to see if we can remove more
+                changed = True
+            else:
+                p[r][c] = keep
+    # Verify strict minimality: removing any single clue breaks uniqueness.
+    for r in range(9):
+        for c in range(9):
+            if p[r][c] == 0:
+                continue
+            keep = p[r][c]
+            p[r][c] = 0
+            still_unique = _uniqueness(p)
+            p[r][c] = keep
+            if still_unique:
+                # Extremely rare due to ordering/race; harden by removing it and re-running once.
                 p[r][c] = 0
-                if _uniqueness(p):
-                    changed = True
-                    # keep removed
-                else:
-                    p[r][c] = keep
-    return p
+                # Re-run a short pass to clean up any others unlocked by this removal.
+                return _make_minimal(p)
+    return p  # strict
 
 
 def generate(
@@ -144,11 +174,8 @@ def remaining_clues() -> int:
         if remaining_clues() <= target_givens:
             break
 
-        if (
-            isinstance(item, tuple)
-            and len(item) == 2
-            and isinstance(item[0], tuple)
-        ):
+        # If symmetry is rot180, paired removals must succeed together.
+        if isinstance(item, tuple) and len(item) == 2 and isinstance(item[0], tuple):
             # symmetric pair (rot180)
             (r1, c1), (r2, c2) = item  # type: ignore[misc]
             keep1, keep2 = puzzle[r1][c1], puzzle[r2][c2]

tests/test_generate_minimal_symmetry.py

@@ -1,13 +1,12 @@
-from sudoku_dlx import generate, is_valid, solve
+from sudoku_dlx import generate, is_valid, solve, count_solutions
 
 
 def _filled(grid) -> int:
     return sum(1 for r in range(9) for c in range(9) if grid[r][c] != 0)
 
 
-def _is_minimal(grid) -> bool:
-    from sudoku_dlx import count_solutions
-
+def _is_minimal_strict(grid) -> bool:
+    # removing any single clue must break uniqueness
     for r in range(9):
         for c in range(9):
             if grid[r][c] == 0:
@@ -36,6 +35,11 @@ def test_gen_rot180_symmetry_unique_and_valid():
 def test_gen_minimal_flag_enforces_minimality():
     puzzle = generate(seed=11, target_givens=36, minimal=True, symmetry="none")
     assert is_valid(puzzle)
-    assert _is_minimal(puzzle)
+    assert _is_minimal_strict(puzzle)
     result = solve(puzzle)
     assert result is not None
+
+
+def test_minimal_puzzles_are_unique():
+    puzzle = generate(seed=21, target_givens=35, minimal=True, symmetry="mix")
+    assert count_solutions(puzzle, limit=2) == 1