sudoku-smt-solvers 0.1.0__py3-none-any.whl

sudoku_smt_solvers/__init__.py

@@ -0,0 +1,4 @@
+from .benchmarks import BenchmarkRunner, SudokuGenerator
+from .solvers import CVC5Solver, DPLLSolver, Z3Solver
+
+__version__ = "0.1.0"

sudoku_smt_solvers/benchmarks/__init__.py

@@ -0,0 +1,5 @@
+from .benchmark_runner import BenchmarkRunner
+from .sudoku_generator.dfs_solver import DFSSolver
+from .sudoku_generator.sudoku_generator import SudokuGenerator
+from .sudoku_generator.las_vegas import LasVegasGenerator
+from .sudoku_generator.hole_digger import HoleDigger

sudoku_smt_solvers/benchmarks/benchmark_runner.py

@@ -0,0 +1,211 @@
+import json
+import os
+import time
+import multiprocessing
+from typing import Dict, List, Optional
+
+from ..solvers import CVC5Solver, DPLLSolver, DPLLTSolver, Z3Solver
+
+
+class BenchmarkRunner:
+    """A benchmark runner for comparing different Sudoku solver implementations.
+
+    This class manages running performance benchmarks across multiple Sudoku solvers,
+    collecting metrics like solve time and propagation counts, and saving results
+    to CSV files.
+
+    Attributes:
+        puzzles_dir (str): Directory containing puzzle JSON files
+        results_dir (str): Directory where benchmark results are saved
+        timeout (int): Maximum time in seconds allowed for each solver attempt
+        solvers (dict): Dictionary mapping solver names to solver classes
+    """
+
+    def __init__(
+        self,
+        puzzles_dir: str = "benchmarks/puzzles",
+        results_dir: str = "benchmarks/results",
+        timeout: int = 120,
+    ):
+        """Initialize the benchmark runner.
+
+        Args:
+            puzzles_dir: Directory containing puzzle JSON files
+            results_dir: Directory where benchmark results will be saved
+            timeout: Maximum time in seconds allowed for each solver attempt
+        """
+        self.puzzles_dir = puzzles_dir
+        self.results_dir = results_dir
+        self.timeout = timeout
+        self.solvers = {
+            "CVC5": CVC5Solver,
+            "DPLL": DPLLSolver,
+            "DPLL(T)": DPLLTSolver,
+            "Z3": Z3Solver,
+        }
+        os.makedirs(results_dir, exist_ok=True)
+
+    def load_puzzle(self, puzzle_id: str) -> Optional[List[List[int]]]:
+        puzzle_path = os.path.join(self.puzzles_dir, f"{puzzle_id}.json")
+        try:
+            with open(puzzle_path, "r") as f:
+                data = json.load(f)
+                for key in ["grid", "puzzle", "gridc"]:
+                    if key in data:
+                        return data[key]
+            print(
+                f"No valid grid found in {puzzle_id}. Available keys: {list(data.keys())}"
+            )
+            return None
+        except Exception as e:
+            print(f"Error loading puzzle {puzzle_id}: {e}")
+            return None
+
+    def _solve_with_timeout(self, solver_class, puzzle, queue):
+        solver = solver_class(puzzle)
+        result = solver.solve()
+        # Pack both the result and propagation count
+        queue.put((result, getattr(solver, "propagated_clauses", 0)))
+
+    def run_solver(self, solver_name: str, puzzle: List[List[int]]) -> Dict:
+        """Run a single solver on a puzzle and collect results with timeout.
+
+        Args:
+            solver_name: Name of the solver to use
+            puzzle: 2D list representing the Sudoku puzzle
+
+        Returns:
+            Dict containing:
+                status: 'sat', 'unsat', 'timeout', or 'error'
+                solve_time: Time taken in seconds
+                propagations: Number of clause propagations (if available)
+        """
+        solver_class = self.solvers[solver_name]
+
+        # Create queue for getting results
+        ctx = multiprocessing.get_context("spawn")
+        queue = ctx.Queue()
+
+        # Create process for solving
+        process = ctx.Process(
+            target=self._solve_with_timeout, args=(solver_class, puzzle, queue)
+        )
+
+        start_time = time.time()
+        process.start()
+        process.join(timeout=self.timeout)
+
+        solve_time = time.time() - start_time
+
+        if process.is_alive():
+            process.terminate()
+            process.join()
+            return {"status": "timeout", "solve_time": self.timeout, "propagations": 0}
+
+        # Get result and propagation count from queue
+        try:
+            result, propagations = queue.get_nowait()
+            return {
+                "status": "sat" if result else "unsat",
+                "solve_time": solve_time,
+                "propagations": propagations,
+            }
+        except:
+            return {"status": "error", "solve_time": solve_time, "propagations": 0}
+
+    def run_benchmarks(self) -> None:
+        """Run all solvers on all puzzles and save results.
+
+        Executes benchmarks for each solver on each puzzle, collecting performance
+        metrics and saving results to a timestamped CSV file.
+
+        The CSV output includes:
+        - Solver name
+        - Puzzle unique ID
+        - Solution status
+        - Solve time
+        - Propagation count
+
+        Also calculates and stores aggregate statistics per solver:
+        - Total puzzles attempted
+        - Number of puzzles solved
+        - Total and average solving times
+        - Total and average propagation counts
+        """
+        results = {
+            solver_name: {
+                "puzzles": {},
+                "stats": {
+                    "total_puzzles": 0,
+                    "solved_count": 0,
+                    "total_time": 0,
+                    "total_propagations": 0,
+                    "avg_time": 0,
+                    "avg_propagations": 0,
+                },
+            }
+            for solver_name in self.solvers
+        }
+
+        puzzle_files = [f for f in os.listdir(self.puzzles_dir) if f.endswith(".json")]
+        print(f"Found {len(puzzle_files)} puzzle files")  # Debug
+
+        for puzzle_file in puzzle_files:
+            puzzle_id = puzzle_file[:-5]
+            puzzle = self.load_puzzle(puzzle_id)
+
+            if not puzzle:
+                print(f"Failed to load puzzle: {puzzle_id}")  # Debug
+                continue
+
+            for solver_name in self.solvers:
+                print(f"Running {solver_name} on puzzle {puzzle_id}")
+                result = self.run_solver(solver_name, puzzle)
+                print(f"Result: {result}")  # Debug
+
+                results[solver_name]["puzzles"][puzzle_id] = result
+
+                stats = results[solver_name]["stats"]
+                stats["total_puzzles"] += 1
+                if result["status"] == "sat":
+                    stats["solved_count"] += 1
+                stats["total_time"] += result["solve_time"]
+                stats["total_propagations"] += result["propagations"]
+
+        # Calculate averages
+        for solver_name, solver_stats in results.items():
+            stats = solver_stats["stats"]
+            total_puzzles = stats["total_puzzles"]
+            if total_puzzles > 0:
+                stats["avg_time"] = stats["total_time"] / total_puzzles
+                stats["avg_propagations"] = stats["total_propagations"] / total_puzzles
+            print(f"Stats for {solver_name}: {stats}")  # Debug
+
+        # Save results
+        timestamp = time.strftime("%Y%m%d_%H%M%S")
+
+        # Debug CSV data
+        csv_data = []
+        for solver_name, solver_results in results.items():
+            for puzzle_id, puzzle_result in solver_results["puzzles"].items():
+                row = {
+                    "solver": solver_name,
+                    "puzzle_id": puzzle_id,
+                    "status": puzzle_result["status"],
+                    "solve_time": puzzle_result["solve_time"],
+                    "propagations": puzzle_result["propagations"],
+                }
+                csv_data.append(row)
+                print(f"Adding CSV row: {row}")  # Debug
+
+        csv_path = os.path.join(self.results_dir, f"benchmark_{timestamp}.csv")
+        print(f"Writing {len(csv_data)} rows to CSV")  # Debug
+
+        with open(csv_path, "w") as f:
+            if csv_data:
+                headers = csv_data[0].keys()
+                f.write(",".join(headers) + "\n")
+                for row in csv_data:
+                    f.write(",".join(str(row[h]) for h in headers) + "\n")
+
+        print(f"Benchmark results saved to {csv_path}")

sudoku_smt_solvers/solvers/__init__.py

@@ -0,0 +1,4 @@
+from .cvc5_solver import CVC5Solver
+from .dpll_solver import DPLLSolver
+from .dpllt_solver import DPLLTSolver
+from .z3_solver import Z3Solver

sudoku_smt_solvers/solvers/cvc5_solver.py

@@ -0,0 +1,207 @@
+from typing import List, Optional
+import atexit
+from cvc5 import Kind, Solver
+from .sudoku_error import SudokuError
+
+
+class CVC5Solver:
+    """CVC5-based Sudoku solver using SMT encoding.
+
+    Solves 25x25 Sudoku puzzles by encoding the problem as an SMT formula and using
+    CVC5 to find a satisfying assignment.
+
+    Attributes:
+        sudoku (List[List[int]]): Input puzzle as 25x25 grid
+        size (int): Grid size (always 25)
+        solver (Solver): CVC5 solver instance
+        variables (List[List[Term]]): SMT variables for each cell
+        propagated_clauses (int): Counter for clause assertions
+
+    Example:
+        >>> puzzle = [[0 for _ in range(25)] for _ in range(25)]  # Empty puzzle
+        >>> solver = CVC5Solver(puzzle)
+        >>> solution = solver.solve()
+    """
+
+    def __init__(self, sudoku):
+        """Initialize CVC5 Sudoku solver.
+
+        Args:
+            sudoku: 25x25 grid with values 0-25 (0 for empty cells)
+
+        Raises:
+            SudokuError: If puzzle format is invalid
+        """
+        if not sudoku or not isinstance(sudoku, list) or len(sudoku) != 25:
+            raise SudokuError("Invalid Sudoku puzzle: must be a 25x25 grid")
+
+        self._validate_input(sudoku)
+        self.sudoku = sudoku
+        self.size = len(sudoku)
+        self.solver = None
+        self.variables = None
+        self.propagated_clauses = 0
+
+    def _validate_input(self, sudoku):
+        for i, row in enumerate(sudoku):
+            if not isinstance(row, list) or len(row) != 25:
+                raise SudokuError(f"Invalid Sudoku puzzle: row {i} must have 25 cells")
+            for j, val in enumerate(row):
+                if not isinstance(val, int) or not (0 <= val <= 25):
+                    raise SudokuError(
+                        f"Invalid value at position ({i},{j}): must be between 0 and 25"
+                    )
+
+    def _count_assertion(self):
+        self.propagated_clauses += 1
+
+    def create_variables(self):
+        self.solver = Solver()
+
+        # Configure CVC5 solver options
+        self.solver.setOption("produce-models", "true")
+        self.solver.setOption("incremental", "true")
+        self.solver.setLogic("QF_LIA")  # Quantifier-Free Linear Integer Arithmetic
+
+        integer_sort = self.solver.getIntegerSort()
+        self.variables = [
+            [self.solver.mkConst(integer_sort, f"x_{i}_{j}") for j in range(25)]
+            for i in range(25)
+        ]
+        atexit.register(self.cleanup)
+
+    def encode_rules(self):
+        # Domain constraints
+        for i in range(25):
+            for j in range(25):
+                self.solver.assertFormula(
+                    self.solver.mkTerm(
+                        Kind.AND,
+                        self.solver.mkTerm(
+                            Kind.LEQ, self.solver.mkInteger(1), self.variables[i][j]
+                        ),
+                        self.solver.mkTerm(
+                            Kind.LEQ, self.variables[i][j], self.solver.mkInteger(25)
+                        ),
+                    )
+                )
+                self._count_assertion()
+
+        # Row constraints
+        for i in range(25):
+            self.solver.assertFormula(
+                self.solver.mkTerm(
+                    Kind.DISTINCT, *[self.variables[i][j] for j in range(25)]
+                )
+            )
+            self._count_assertion()
+
+        # Column constraints
+        for j in range(25):
+            self.solver.assertFormula(
+                self.solver.mkTerm(
+                    Kind.DISTINCT, *[self.variables[i][j] for i in range(25)]
+                )
+            )
+            self._count_assertion()
+
+        # 5x5 subgrid constraints
+        for block_row in range(0, 25, 5):
+            for block_col in range(0, 25, 5):
+                block_vars = [
+                    self.variables[i][j]
+                    for i in range(block_row, block_row + 5)
+                    for j in range(block_col, block_col + 5)
+                ]
+                self.solver.assertFormula(
+                    self.solver.mkTerm(Kind.DISTINCT, *block_vars)
+                )
+                self._count_assertion()
+
+    def encode_puzzle(self):
+        for i in range(25):
+            for j in range(25):
+                if self.sudoku[i][j] != 0:  # Pre-filled cell
+                    self.solver.assertFormula(
+                        self.solver.mkTerm(
+                            Kind.EQUAL,
+                            self.variables[i][j],
+                            self.solver.mkInteger(self.sudoku[i][j]),
+                        )
+                    )
+                    self._count_assertion()
+
+    def extract_solution(self):
+        solution = [[0 for _ in range(25)] for _ in range(25)]
+        for i in range(25):
+            for j in range(25):
+                solution[i][j] = self.solver.getValue(
+                    self.variables[i][j]
+                ).getIntegerValue()
+        return solution
+
+    def cleanup(self):
+        if self.solver:
+            self.solver = None
+
+    def validate_solution(self, solution):
+        if not solution:
+            return False
+
+        # Check dimensions
+        if len(solution) != self.size or any(len(row) != self.size for row in solution):
+            return False
+
+        valid_nums = set(range(1, self.size + 1))
+
+        # Check rows
+        if any(set(row) != valid_nums for row in solution):
+            return False
+
+        # Check columns
+        for col in range(self.size):
+            if set(solution[row][col] for row in range(self.size)) != valid_nums:
+                return False
+
+        # Check 5x5 subgrids
+        subgrid_size = 5
+        for box_row in range(0, self.size, subgrid_size):
+            for box_col in range(0, self.size, subgrid_size):
+                numbers = set()
+                for i in range(subgrid_size):
+                    for j in range(subgrid_size):
+                        numbers.add(solution[box_row + i][box_col + j])
+                if numbers != valid_nums:
+                    return False
+
+        return True
+
+    def solve(self):
+        """Solve the Sudoku puzzle using CVC5.
+
+        Returns:
+            Solved 25x25 grid if satisfiable, None if unsatisfiable
+
+        Raises:
+            Exception: If solver encounters an error
+
+        Note:
+            Always cleans up solver resources, even on failure
+        """
+        try:
+            self.create_variables()
+            self.encode_rules()
+            self.encode_puzzle()
+
+            result = self.solver.checkSat()
+
+            if result.isSat():
+                solution = self.extract_solution()
+                if self.validate_solution(solution):
+                    return solution
+            return None
+
+        except Exception as e:
+            raise
+        finally:
+            self.cleanup()

sudoku_smt_solvers/solvers/dpll_solver.py

@@ -0,0 +1,175 @@
+from typing import List, Optional
+from pysat.solvers import Solver
+from pysat.formula import CNF
+from .sudoku_error import SudokuError
+
+
+class DPLLSolver:
+    """DPLL-based Sudoku solver using SAT encoding.
+
+    Solves 25x25 Sudoku puzzles by converting them to CNF (Conjunctive Normal Form)
+    and using DPLL to find a satisfying assignment.
+
+    Attributes:
+        sudoku (List[List[int]]): Input puzzle as 25x25 grid
+        size (int): Grid size (25)
+        cnf (CNF): PySAT CNF formula object
+        solver (Solver): PySAT Glucose3 solver instance
+        propagated_clauses (int): Counter for clause additions
+
+    Example:
+        >>> puzzle = [[0 for _ in range(25)] for _ in range(25)]
+        >>> solver = DPLLSolver(puzzle)
+        >>> solution = solver.solve()
+    """
+
+    def __init__(self, sudoku: List[List[int]]) -> None:
+        """Initialize DPLL Sudoku solver.
+
+        Args:
+            sudoku: 25x25 grid with values 0-25 (0 for empty cells)
+
+        Raises:
+            SudokuError: If puzzle format is invalid
+        """
+        if not sudoku or not isinstance(sudoku, list) or len(sudoku) != 25:
+            raise SudokuError("Invalid Sudoku puzzle: must be a 25x25 grid")
+
+        self.sudoku = sudoku
+        self.size = 25
+        self.cnf = CNF()  # CNF object to store Boolean clauses
+        self.solver = Solver(name="glucose3")  # Low-level SAT solver
+        self.propagated_clauses = 0  # Add clause counter
+
+    def _count_clause(self) -> None:
+        self.propagated_clauses += 1
+
+    def add_sudoku_clauses(self) -> None:
+        size = self.size
+        block_size = int(size**0.5)
+
+        def get_var(row, col, num):
+            return row * size * size + col * size + num
+
+        # At least one number in each cell
+        for row in range(size):
+            for col in range(size):
+                self.cnf.append([get_var(row, col, num) for num in range(1, size + 1)])
+                self._count_clause()
+
+                # At most one number in each cell
+                for num1 in range(1, size + 1):
+                    for num2 in range(num1 + 1, size + 1):
+                        self.cnf.append(
+                            [-get_var(row, col, num1), -get_var(row, col, num2)]
+                        )
+                        self._count_clause()
+
+        # Add row constraints
+        for row in range(size):
+            for num in range(1, size + 1):
+                self.cnf.append([get_var(row, col, num) for col in range(size)])
+                self._count_clause()
+
+        # Add column constraints
+        for col in range(size):
+            for num in range(1, size + 1):
+                self.cnf.append([get_var(row, col, num) for row in range(size)])
+                self._count_clause()
+
+        # Add block constraints
+        for block_row in range(block_size):
+            for block_col in range(block_size):
+                for num in range(1, size + 1):
+                    self.cnf.append(
+                        [
+                            get_var(
+                                block_row * block_size + i,
+                                block_col * block_size + j,
+                                num,
+                            )
+                            for i in range(block_size)
+                            for j in range(block_size)
+                        ]
+                    )
+                    self._count_clause()
+
+        # Add initial assignments from the puzzle
+        for row in range(size):
+            for col in range(size):
+                if self.sudoku[row][col] != 0:
+                    num = self.sudoku[row][col]
+                    self.cnf.append([get_var(row, col, num)])
+                    self._count_clause()
+
+    def extract_solution(self, model: List[int]) -> List[List[int]]:
+        solution = [[0 for _ in range(self.size)] for _ in range(self.size)]
+        for var in model:
+            if var > 0:  # Only consider positive assignments
+                var -= 1
+                num = var % self.size + 1
+                col = (var // self.size) % self.size
+                row = var // (self.size * self.size)
+                solution[row][col] = num
+        return solution
+
+    def validate_solution(self, solution: List[List[int]]) -> bool:
+        size = self.size
+        block_size = int(size**0.5)
+
+        # Validate rows
+        for row in solution:
+            if len(set(row)) != size or not all(1 <= num <= size for num in row):
+                return False
+
+        # Validate columns
+        for col in range(size):
+            column = [solution[row][col] for row in range(size)]
+            if len(set(column)) != size:
+                return False
+
+        # Validate blocks
+        for block_row in range(block_size):
+            for block_col in range(block_size):
+                block = [
+                    solution[block_row * block_size + i][block_col * block_size + j]
+                    for i in range(block_size)
+                    for j in range(block_size)
+                ]
+                if len(set(block)) != size:
+                    return False
+
+        return True
+
+    def solve(self) -> Optional[List[List[int]]]:
+        """Solve Sudoku puzzle using DPLL SAT solver.
+
+        Returns:
+            Solved 25x25 grid if satisfiable, None if unsatisfiable
+
+        Raises:
+            SudokuError: If solver produces invalid solution
+            Exception: For other solver errors
+
+        Note:
+            Uses Glucose3 SAT solver from PySAT
+        """
+        self.add_sudoku_clauses()
+        self.solver.append_formula(self.cnf.clauses)
+
+        try:
+            if self.solver.solve():
+                # Extract and validate the solution
+                model = self.solver.get_model()
+                solution = self.extract_solution(model)
+
+                if self.validate_solution(solution):
+                    return solution
+                else:
+                    raise SudokuError("Invalid solution generated.")
+            else:
+                # If unsat, return None
+                return None
+
+        except Exception as e:
+            raise

sudoku_smt_solvers/solvers/dpllt_solver.py

@@ -0,0 +1,211 @@
+from typing import List, Optional
+from pysat.solvers import Solver
+from pysat.formula import CNF
+from .sudoku_error import SudokuError
+
+
+class DPLLTSolver:
+    """DPLL(T) solver combining SAT solving with theory propagation.
+
+    Extends basic DPLL SAT solving with theory propagation for Sudoku rules,
+    enabling more efficient pruning of the search space.
+
+    Attributes:
+        sudoku (List[List[int]]): Input puzzle as 25x25 grid
+        size (int): Grid size (25)
+        cnf (CNF): PySAT CNF formula object
+        solver (Solver): PySAT Glucose3 solver
+        theory_state (dict): Dynamic tracking of theory constraints
+        decision_level (int): Current depth in decision tree
+        propagated_clauses (int): Counter for clause additions
+
+    Example:
+        >>> puzzle = [[0 for _ in range(25)] for _ in range(25)]
+        >>> solver = DPLLTSolver(puzzle)
+        >>> solution = solver.solve()
+    """
+
+    def __init__(self, sudoku: List[List[int]]) -> None:
+        """Initialize DPLL(T) solver with theory support.
+
+        Args:
+            sudoku: 25x25 grid with values 0-25 (0 for empty cells)
+
+        Raises:
+            SudokuError: If puzzle format is invalid
+        """
+        if not sudoku or not isinstance(sudoku, list) or len(sudoku) != 25:
+            raise SudokuError("Invalid Sudoku puzzle: must be a 25x25 grid")
+
+        self.sudoku = sudoku
+        self.size = 25
+        self.cnf = CNF()  # CNF object to store Boolean clauses
+        self.solver = Solver(name="glucose3")  # Low-level SAT solver
+        self.theory_state = {}  # Store theory constraints dynamically
+        self.decision_level = 0
+        self.propagated_clauses = 0
+
+    def _count_clause(self) -> None:
+        self.propagated_clauses += 1
+
+    def add_sudoku_clauses(self) -> None:
+        size = self.size
+        block_size = int(size**0.5)
+
+        def get_var(row, col, num):
+            return row * size * size + col * size + num
+
+        # At least one number in each cell
+        for row in range(size):
+            for col in range(size):
+                self.cnf.append([get_var(row, col, num) for num in range(1, size + 1)])
+                self._count_clause()
+
+                # At most one number in each cell
+                for num1 in range(1, size + 1):
+                    for num2 in range(num1 + 1, size + 1):
+                        self.cnf.append(
+                            [-get_var(row, col, num1), -get_var(row, col, num2)]
+                        )
+                        self._count_clause()
+
+        # Add row constraints
+        for row in range(size):
+            for num in range(1, size + 1):
+                self.cnf.append([get_var(row, col, num) for col in range(size)])
+                self._count_clause()
+
+        # Add column constraints
+        for col in range(size):
+            for num in range(1, size + 1):
+                self.cnf.append([get_var(row, col, num) for row in range(size)])
+                self._count_clause()
+
+        # Add block constraints
+        for block_row in range(block_size):
+            for block_col in range(block_size):
+                for num in range(1, size + 1):
+                    self.cnf.append(
+                        [
+                            get_var(
+                                block_row * block_size + i,
+                                block_col * block_size + j,
+                                num,
+                            )
+                            for i in range(block_size)
+                            for j in range(block_size)
+                        ]
+                    )
+                    self._count_clause()
+
+        # Add initial assignments from the puzzle
+        for row in range(size):
+            for col in range(size):
+                if self.sudoku[row][col] != 0:
+                    num = self.sudoku[row][col]
+                    self.cnf.append([get_var(row, col, num)])
+                    self._count_clause()
+
+    def theory_propagation(self) -> Optional[List[int]]:
+        block_size = int(self.size**0.5)
+
+        def block_index(row, col):
+            return (row // block_size) * block_size + (col // block_size)
+
+        # Track constraints dynamically
+        for row in range(self.size):
+            for col in range(self.size):
+                if self.sudoku[row][col] != 0:
+                    num = self.sudoku[row][col]
+                    # Check row, column, and block constraints
+                    if num in self.theory_state.get((row, "row"), set()):
+                        return [-self.get_var(row, col, num)]
+                    if num in self.theory_state.get((col, "col"), set()):
+                        return [-self.get_var(row, col, num)]
+                    if num in self.theory_state.get(
+                        (block_index(row, col), "block"), set()
+                    ):
+                        return [-self.get_var(row, col, num)]
+
+                    # Add constraints to theory state
+                    self.theory_state.setdefault((row, "row"), set()).add(num)
+                    self.theory_state.setdefault((col, "col"), set()).add(num)
+                    self.theory_state.setdefault(
+                        (block_index(row, col), "block"), set()
+                    ).add(num)
+        return None
+
+    def extract_solution(self, model: List[int]) -> List[List[int]]:
+        """Convert SAT model to Sudoku grid."""
+        solution = [[0 for _ in range(self.size)] for _ in range(self.size)]
+        for var in model:
+            if var > 0:  # Only consider positive assignments
+                var -= 1
+                num = var % self.size + 1
+                col = (var // self.size) % self.size
+                row = var // (self.size * self.size)
+                solution[row][col] = num
+        return solution
+
+    def validate_solution(self, solution: List[List[int]]) -> bool:
+        size = self.size
+        block_size = int(size**0.5)
+
+        # Validate rows
+        for row in solution:
+            if len(set(row)) != size or not all(1 <= num <= size for num in row):
+                return False
+
+        # Validate columns
+        for col in range(size):
+            column = [solution[row][col] for row in range(size)]
+            if len(set(column)) != size:
+                return False
+
+        # Validate blocks
+        for block_row in range(block_size):
+            for block_col in range(block_size):
+                block = [
+                    solution[block_row * block_size + i][block_col * block_size + j]
+                    for i in range(block_size)
+                    for j in range(block_size)
+                ]
+                if len(set(block)) != size:
+                    return False
+
+        return True
+
+    def solve(self) -> Optional[List[List[int]]]:
+        """Solve Sudoku using DPLL(T) algorithm.
+
+        Returns:
+            Solved 25x25 grid if satisfiable, None if unsatisfiable
+
+        Raises:
+            SudokuError: If solver produces invalid solution
+
+        Note:
+            Combines SAT solving with theory propagation in DPLL(T) style
+        """
+        """Solve the Sudoku puzzle using DPLL(T)."""
+        self.add_sudoku_clauses()
+        self.solver.append_formula(self.cnf.clauses)
+
+        while self.solver.solve():
+            # Perform theory propagation
+            conflict_clause = self.theory_propagation()
+            if conflict_clause:
+                # Add conflict clause and continue solving
+                self.solver.add_clause(conflict_clause)
+                self._count_clause()
+            else:
+                # Extract and validate the solution
+                model = self.solver.get_model()
+                solution = self.extract_solution(model)
+                if self.validate_solution(solution):
+                    return solution
+                else:
+                    raise SudokuError("Invalid solution generated.")
+
+        # If UNSAT, return None
+        return None

sudoku_smt_solvers/solvers/sudoku_error.py

@@ -0,0 +1,8 @@
+class SudokuError(Exception):
+    """An exception class for errors in the sudoku solver"""
+
+    def __init__(self, message):
+        self.message = message
+
+    def __str__(self):
+        return self.message

sudoku_smt_solvers/solvers/z3_solver.py

@@ -0,0 +1,160 @@
+from z3 import Solver, Int, Distinct, sat
+from sudoku_smt_solvers.solvers.sudoku_error import SudokuError
+
+
+class Z3Solver:
+    """Z3-based SMT solver for Sudoku puzzles.
+
+    Uses integer variables and distinct constraints to encode Sudoku rules.
+    Tracks constraint propagation for performance analysis.
+
+    Attributes:
+        sudoku (List[List[int]]): Input puzzle as 25x25 grid
+        size (int): Grid size (25)
+        solver (z3.Solver): Z3 solver instance
+        variables (List[List[z3.Int]]): SMT variables for grid
+        propagated_clauses (int): Counter for constraint additions
+
+    Example:
+        >>> puzzle = [[0 for _ in range(25)] for _ in range(25)]
+        >>> solver = Z3Solver(puzzle)
+        >>> solution = solver.solve()
+    """
+
+    def __init__(self, sudoku):
+        """Initialize Z3 Sudoku solver.
+
+        Args:
+            sudoku: 25x25 grid with values 0-25 (0 for empty cells)
+
+        Raises:
+            SudokuError: If puzzle format is invalid
+        """
+        if not sudoku or not isinstance(sudoku, list) or len(sudoku) != 25:
+            raise SudokuError("Invalid Sudoku puzzle: must be a 25x25 grid")
+
+        self.sudoku = sudoku
+        self.size = len(sudoku)
+        self.solver = None
+        self.variables = None
+        self.propagated_clauses = 0
+
+    def create_variables(self):
+        self.variables = [
+            [Int(f"x_{i}_{j}") for j in range(self.size)] for i in range(self.size)
+        ]
+
+    def _count_clause(self):
+        self.propagated_clauses += 1
+
+    def encode_rules(self):
+        # Cell range constraints
+        cell_constraints = []
+        for i in range(self.size):
+            for j in range(self.size):
+                cell_constraints.append(1 <= self.variables[i][j])
+                cell_constraints.append(self.variables[i][j] <= 25)
+                self._count_clause()
+                self._count_clause()
+        self.solver.add(cell_constraints)
+
+        # Row constraints
+        row_constraints = [Distinct(self.variables[i]) for i in range(self.size)]
+        self.solver.add(row_constraints)
+        for _ in range(self.size):
+            self._count_clause()
+
+        # Column constraints
+        col_constraints = [
+            Distinct([self.variables[i][j] for i in range(self.size)])
+            for j in range(self.size)
+        ]
+        self.solver.add(col_constraints)
+        for _ in range(self.size):
+            self._count_clause()
+
+        # Box constraints
+        box_constraints = [
+            Distinct(
+                [
+                    self.variables[5 * box_i + i][5 * box_j + j]
+                    for i in range(5)
+                    for j in range(5)
+                ]
+            )
+            for box_i in range(5)
+            for box_j in range(5)
+        ]
+        self.solver.add(box_constraints)
+        for _ in range(25):
+            self._count_clause()
+
+    def encode_puzzle(self):
+        initial_values = []
+        for i in range(self.size):
+            for j in range(self.size):
+                if self.sudoku[i][j] != 0:
+                    initial_values.append(self.variables[i][j] == self.sudoku[i][j])
+                    self._count_clause()
+        self.solver.add(initial_values)
+
+    def extract_solution(self, model):
+        return [
+            [model.evaluate(self.variables[i][j]).as_long() for j in range(self.size)]
+            for i in range(self.size)
+        ]
+
+    def validate_solution(self, solution):
+        # Check range
+        for row in solution:
+            if not all(1 <= num <= 25 for num in row):
+                return False
+
+        # Check rows
+        for row in solution:
+            if len(set(row)) != self.size:
+                return False
+
+        # Check columns
+        for j in range(self.size):
+            col = [solution[i][j] for i in range(self.size)]
+            if len(set(col)) != self.size:
+                return False
+
+        # Check boxes
+        for box_i in range(5):
+            for box_j in range(5):
+                box = [
+                    solution[5 * box_i + i][5 * box_j + j]
+                    for i in range(5)
+                    for j in range(5)
+                ]
+                if len(set(box)) != self.size:
+                    return False
+
+        return True
+
+    def solve(self):
+        """Solve Sudoku using Z3 SMT solver.
+
+        Returns:
+            Solved 25x25 grid if satisfiable, None if unsatisfiable
+
+        Note:
+            Validates solution before returning to ensure correctness
+        """
+        self.solver = Solver()
+        self.create_variables()
+        self.encode_rules()
+        self.encode_puzzle()
+
+        result = self.solver.check()
+
+        if result == sat:
+            model = self.solver.model()
+            solution = self.extract_solution(model)
+
+            if self.validate_solution(solution):
+                return solution
+
+        return None

sudoku_smt_solvers-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 liamjdavis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sudoku_smt_solvers-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.1
+Name: sudoku_smt_solvers
+Version: 0.1.0
+Summary: A collection of SAT and SMT solvers for solving Sudoku puzzles
+Home-page: https://liamjdavis.github.io/sudoku-smt-solvers
+Author: Liam Davis
+Author-email: ljdavis27@amherst.edu
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cvc5
+Requires-Dist: pysat
+Requires-Dist: z3-solver
+
+# Sudoku-SMT-Solvers
+
+[![Pytest + CI/CD](https://github.com/liamjdavis/Sudoku-SMT-Solvers/actions/workflows/test.yml/badge.svg)](ttps://github.com/liamjdavis/Sudoku-SMT-Solvers/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/liamjdavis/Sudoku-SMT-Solvers/badge.svg)](https://coveralls.io/github/liamjdavis/Sudoku-SMT-Solvers)
+[![Docs Build Deployment](https://github.com/liamjdavis/Sudoku-SMT-Solvers/actions/workflows/docs.yml/badge.svg)](https://github.com/liamjdavis/Sudoku-SMT-Solvers/actions/workflows/docs.yml)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://liamjdavis.github.io/sudoku-smt-solvers)
+
+
+## About
+This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Ryan Ji (@TairanJ) as their for COSC-241 Artificial Intelligence at Amherst College, it evaluates the efficacy of SMT-Based Solvers by benchmarking three modern SMT solvers (DPLL(T), Z3, and CVC5) against the DPLL algorithm on a collection of 100 25x25 Sudoku puzzles of varying difficulty.
+
+Along with the study, we also published `sudoku-smt-solvers`, a Python package that provides the various SMT-based Sudoku solvers and benchmarking tools we built for this study. The package features DPLL(T), Z3, and CVC5 solvers optimized for 25x25 Sudoku puzzles, a puzzle generator for creating test cases, and a comprehensive benchmarking suite. Available through pip, it offers a simple API for solving Sudoku puzzles using state-of-the-art SMT solvers while facilitating performance comparisons between different solving approaches.
+
+The study aims to answer three research questions: 
+1. How have logical solvers evolved over time in terms of performance and capability?
+2. How do different encodings of Sudoku affect the efficiency and scalability of these solvers?
+3. Are there specific features or optimizations in SMT solvers that provide a significant advantage over traditional SAT solvers for this class of problem?
+
+## Getting started
+### Installation
+To run the code locally, you can install with `pip`
+
+```bash
+pip install sudoku-smt-solvers
+```
+
+### Solvers
+This package includes the DPLL solver and three modern SMT solvers:
+* DPLL(T)
+* CVC5
+* Z3
+
+To run any of the solvers on a 25x25 Sudoku puzzle, you can create an instance of the solver class and call the solve method in a file at the root (Sudoku-smt-solvers). Here is an example using Z3:
+
+```python
+from sudoku_smt_solvers.solvers.z3_solver import Z3Solver
+
+# Example grid (25x25)
+grid = [[0] * 25 for _ in range(25)]
+solver = Z3Solver(grid)
+solution = solver.solve()
+
+if solution:
+    print(f"Solution:\n\n{solution}")
+else:
+    print("No solution exists.")
+```
+
+### Sudoku Generator
+This package also includes a generator for creating Sudoku puzzles to be used as benchmarks. To generate a puzzle, create an instance of the `SudokuGenerator` class and call the `generate` method. Here is an example:
+
+```python
+from sudoku_smt_solvers.benchmarks.sudoku_generator.sudoku_generator import SudokuGenerator
+
+generator = SudokuGenerator(size = 25, givens = 80, timeout = 5, difficulty = "Medium", puzzles_dir = "benchmarks/puzzles", solutions_dir = "benchmarks/solutions")
+
+generator.generate()
+```
+
+Due to the computational complexity of generating large sudoku puzzles, it is recommended that you run multiple generator instances in parallel to create benchmarks.
+
+### Benchmark Runner
+To run the benchmarks you created on all four solvers, create an instance of the `BenchmarkRunner` class and call the `run_benchmarks` method. Here is an example:
+
+```python
+from sudoku_smt_solvers.benchmarks.benchmark_runner import BenchmarkRunner
+
+runner = BenchmarkRunner(
+    puzzles_dir='resources/benchmarks/puzzles/',
+    solutions_dir='resources/benchmarks/solutions/',
+    results_dir='results/'
+)
+runner.run_benchmarks()
+```
+
+## Contributing
+
+We welcome contributions in the form of new solvers, additions to our benchmark suite, or anything that improves the tool! Here's how to get started:
+
+### Development Setup
+
+1. **Fork and Clone**:  
+   Begin by forking the repository and cloning your fork locally:
+   ```bash
+   git clone https://github.com/yourusername/Sudoku-SMT-Solvers.git
+   cd Sudoku-SMT-Solvers
+   ```
+
+2. **Create and Activate a Virtual Environment**:  
+   Set up a Python virtual environment to isolate your dependencies:
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
+   ```
+
+3. **Install Dependencies**:  
+   Install the required dependencies from the `requirements.txt` file:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Set Up Pre-Commit Hooks**:  
+   Install and configure pre-commit hooks to maintain code quality:
+   ```bash
+   pip install pre-commit
+   pre-commit install
+   ```
+
+   To manually run the hooks and verify code compliance, use:
+   ```bash
+   pre-commit run
+   ```
+
+5. **Testing and Coverage Requirements**:  
+   - Write tests for any new code or modifications.
+   - Use `pytest` for running tests:
+     ```bash
+     pytest
+     ```
+   - Ensure the test coverage is at least 90%:
+
+6. **Add and Commit Your Changes**:  
+   - Follow the existing code style and structure.
+   - Verify that all pre-commit hooks pass and the test coverage meets the minimum requirement.
+   ```bash
+   git add .
+   git commit -m "Description of your changes"
+   ```
+
+7. **Push Your Branch**:
+   Push your changes to your forked repository:
+   ```bash
+   git push origin your-branch-name
+   ```
+
+8. **Open a PR for us to review**
+---
+
+Thank you for your interest in contributing to Sudoku-SMT-Solvers! Your efforts help make this project better for everyone.
+
+
+## Contact Us
+For any questions or support, please reach out to Liam at ljdavis27 at amherst.edu and Ryan at tji26 at amherst.edu

sudoku_smt_solvers-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sudoku_smt_solvers/__init__.py,sha256=vTwJLa8Yp7q-OdzA44zhFIK-LhK2o8aDt-4qOJJ1M7M,134
+sudoku_smt_solvers/benchmarks/__init__.py,sha256=lMrK_yj_otywN4dMvvVFtTzyTdamS_4nUgjm-k07obU,271
+sudoku_smt_solvers/benchmarks/benchmark_runner.py,sha256=Mc87ul-6VkWMomtlmOMc9GXmC4AwfQUwIWKDjeFvSVA,7712
+sudoku_smt_solvers/solvers/__init__.py,sha256=5qFfWzKN2WPDoFLN5ye6Ly5BqEaUdk2ks_jPP3c53l8,142
+sudoku_smt_solvers/solvers/cvc5_solver.py,sha256=DfLlgzhhgSaI3tV_4mzy3vdpxY5tISSFhs0xhRWcMYk,6849
+sudoku_smt_solvers/solvers/dpll_solver.py,sha256=ThLT1v87oNnzDMpYmoPcmTeeXijVIgk6A6qULWVID28,6138
+sudoku_smt_solvers/solvers/dpllt_solver.py,sha256=4UXcod7EnJGlD7OlakmPHOuIyWga5yN9rMtKMvuEAc8,7986
+sudoku_smt_solvers/solvers/sudoku_error.py,sha256=iUcv1QCgQ7anov0b-AtIB1fbfZ3yWfci4eTp_8RuUJg,208
+sudoku_smt_solvers/solvers/z3_solver.py,sha256=awQ3tzEMIy2woFmATMiwQsC2YtktxfJlx55MudB1SN0,4922
+sudoku_smt_solvers-0.1.0.dist-info/LICENSE,sha256=PbuZlvluV1l4HMMfPAVe5yjVvFGBK9DFp20JNhoJ8bI,1067
+sudoku_smt_solvers-0.1.0.dist-info/METADATA,sha256=lbOf7Pgg4nsMlchZ54WHWcJoGa98BvgCMHCMieULSrw,6414
+sudoku_smt_solvers-0.1.0.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
+sudoku_smt_solvers-0.1.0.dist-info/top_level.txt,sha256=Ww9vs8KC4aujzfGfddMl_X8Qzh-Cywn9aBTLQgemi5A,19
+sudoku_smt_solvers-0.1.0.dist-info/RECORD,,

sudoku_smt_solvers-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.7.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sudoku_smt_solvers-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sudoku_smt_solvers