sudoku-smt-solvers 0.3.0__tar.gz → 1.0.0__tar.gz

{sudoku_smt_solvers-0.3.0/sudoku_smt_solvers.egg-info → sudoku_smt_solvers-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sudoku_smt_solvers
-Version: 0.3.0
+Version: 1.0.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, Tairan 'Ryan' Ji
@@ -35,7 +35,7 @@ Dynamic: summary
 
 
 ## About
-This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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.
+This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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. The corresponding paper can be found [here](https://arxiv.org/abs/2501.08569).
 
 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.
 
@@ -61,7 +61,7 @@ This package includes the DPLL solver and three modern SMT solvers:
 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
+from sudoku_smt_solvers import Z3Solver
 
 # Example grid (25x25)
 grid = [[0] * 25 for _ in range(25)]
@@ -78,7 +78,7 @@ else:
 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
+from sudoku_smt_solvers import SudokuGenerator
 
 generator = SudokuGenerator(size = 25, givens = 80, timeout = 5, difficulty = "Medium", puzzles_dir = "benchmarks/puzzles", solutions_dir = "benchmarks/solutions")
 
@@ -91,11 +91,10 @@ Due to the computational complexity of generating large sudoku puzzles, it is re
 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
+from sudoku_smt_solvers import BenchmarkRunner
 
 runner = BenchmarkRunner(
     puzzles_dir='resources/benchmarks/puzzles/',
-    solutions_dir='resources/benchmarks/solutions/',
     results_dir='results/'
 )
 runner.run_benchmarks()

{sudoku_smt_solvers-0.3.0 → sudoku_smt_solvers-1.0.0}/README.md

@@ -7,7 +7,7 @@
 
 
 ## About
-This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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.
+This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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. The corresponding paper can be found [here](https://arxiv.org/abs/2501.08569).
 
 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.
 
@@ -33,7 +33,7 @@ This package includes the DPLL solver and three modern SMT solvers:
 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
+from sudoku_smt_solvers import Z3Solver
 
 # Example grid (25x25)
 grid = [[0] * 25 for _ in range(25)]
@@ -50,7 +50,7 @@ else:
 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
+from sudoku_smt_solvers import SudokuGenerator
 
 generator = SudokuGenerator(size = 25, givens = 80, timeout = 5, difficulty = "Medium", puzzles_dir = "benchmarks/puzzles", solutions_dir = "benchmarks/solutions")
 
@@ -63,11 +63,10 @@ Due to the computational complexity of generating large sudoku puzzles, it is re
 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
+from sudoku_smt_solvers import BenchmarkRunner
 
 runner = BenchmarkRunner(
     puzzles_dir='resources/benchmarks/puzzles/',
-    solutions_dir='resources/benchmarks/solutions/',
     results_dir='results/'
 )
 runner.run_benchmarks()

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/__init__.py

@@ -0,0 +1,35 @@
+"""Sudoku SMT Solvers - A package for solving and benchmarking large-scale Sudoku puzzles.
+
+This package provides various SAT and SMT-based solvers optimized for 25x25 Sudoku puzzles,
+along with tools for puzzle generation and solver benchmarking.
+
+Key Components:
+- Multiple solver implementations (DPLL, DPLL(T), Z3, CVC5)
+- Sudoku puzzle generator with difficulty settings
+- Benchmarking suite for comparing solver performance
+"""
+
+from .solvers import CVC5Solver, DPLLSolver, DPLLTSolver, Z3Solver
+from .solvers.utils import SudokuError
+from .benchmarks import BenchmarkRunner
+from .benchmarks.sudoku_generator import (
+    SudokuGenerator,
+    LasVegasGenerator,
+    HoleDigger,
+    DFSSolver,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CVC5Solver",
+    "DPLLSolver",
+    "DPLLTSolver",
+    "Z3Solver",
+    "BenchmarkRunner",
+    "SudokuGenerator",
+    "LasVegasGenerator",
+    "HoleDigger",
+    "DFSSolver",
+    "SudokuError",
+]

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/__init__.py

@@ -0,0 +1,3 @@
+from .benchmark_runner import BenchmarkRunner
+
+__all__ = ["BenchmarkRunner"]

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/sudoku_generator/__init__.py

@@ -0,0 +1,6 @@
+from .sudoku_generator import SudokuGenerator
+from .las_vegas import LasVegasGenerator
+from .hole_digger import HoleDigger
+from .dfs_solver import DFSSolver
+
+__all__ = ["SudokuGenerator", "LasVegasGenerator", "HoleDigger", "DFSSolver"]

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/sudoku_generator/dfs_solver.py

@@ -0,0 +1,99 @@
+from math import sqrt
+
+
+class DFSSolver:
+    def __init__(self, size=25, solutions_limit=-1):
+        """Initialize solver with configurable grid size"""
+        self.size = size  # Total grid size (default 25x25)
+        self.box_size = int(sqrt(size))  # Size of each sub-box (default 5x5)
+        self.solutions_limit = solutions_limit  # Number of solutions to find (-1 for all solutions, n>0 for n solutions)
+        self.solutions_found = 0
+        self.rows = [set() for _ in range(self.size)]
+        self.cols = [set() for _ in range(self.size)]
+        self.boxes = [set() for _ in range(self.size)]
+        self.unfilled_positions = []  # Track positions of empty cells
+
+        self.box_lookup = [[0] * size for _ in range(size)]
+        for i in range(size):
+            for j in range(size):
+                self.box_lookup[i][j] = (i // self.box_size) * self.box_size + (
+                    j // self.box_size
+                )
+
+    def setup_board(self, grid):
+        """Set up initial board state"""
+        self.unfilled_positions.clear()
+        for i in range(self.size):
+            for j in range(self.size):
+                num = grid[i][j]
+                if num == 0:
+                    self.unfilled_positions.append((i, j))
+                else:
+                    self.rows[i].add(num)
+                    self.cols[j].add(num)
+                    self.boxes[self.box_lookup[i][j]].add(num)
+
+    def get_valid_numbers(self, row, col):
+        """Get valid numbers for a cell using set operations"""
+        used = self.rows[row] | self.cols[col] | self.boxes[self.box_lookup[row][col]]
+        return set(range(1, self.size + 1)) - used
+
+    def solve(self, grid):
+        """Main solving function using backtracking"""
+        self.setup_board(grid)
+        self.solutions_found = 0
+        solutions = []
+
+        def search():
+            """Depth-first search implementation"""
+            if not self.unfilled_positions:  # Found a solution
+                solutions.append([row[:] for row in grid])
+                self.solutions_found += 1
+                # Stop if we've found desired number of solutions
+                return (
+                    self.solutions_limit > 0
+                    and self.solutions_found >= self.solutions_limit
+                )
+
+            # Select cell with minimum valid numbers to reduce branching
+            min_candidates = float("inf")
+            min_pos = None
+            min_idx = None
+
+            for idx, (row, col) in enumerate(self.unfilled_positions):
+                valid_numbers = self.get_valid_numbers(row, col)
+                if len(valid_numbers) < min_candidates:
+                    min_candidates = len(valid_numbers)
+                    min_pos = (row, col)
+                    min_idx = idx
+                    if min_candidates == 0:  # No valid numbers available
+                        return False
+
+            row, col = min_pos
+            self.unfilled_positions.pop(min_idx)
+
+            for num in self.get_valid_numbers(row, col):
+                # Place number and update board state
+                grid[row][col] = num
+                self.rows[row].add(num)
+                self.cols[col].add(num)
+                self.boxes[self.box_lookup[row][col]].add(num)
+
+                if search():  # If search returns True, we should stop
+                    return True
+
+                # Backtrack: remove number and restore board state
+                grid[row][col] = 0
+                self.rows[row].remove(num)
+                self.cols[col].remove(num)
+                self.boxes[self.box_lookup[row][col]].remove(num)
+
+            self.unfilled_positions.insert(min_idx, (row, col))
+            return False
+
+        search()
+        return (
+            solutions
+            if self.solutions_limit != 1
+            else (solutions[0] if solutions else [])
+        )

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/sudoku_generator/hole_digger.py

@@ -0,0 +1,144 @@
+import random
+from typing import List, Tuple
+from .dfs_solver import DFSSolver
+
+from .las_vegas import LasVegasGenerator
+
+# A mapping from difficulty to the range of givens
+difficulty_givensRange_mapping = {
+    "Extremely Easy": [382, float("inf")],  # More than 386 given cells
+    "Easy": [274, 381],
+    "Medium": [243, 273],
+    "Difficult": [212, 242],
+    "Evil": [166, 211],
+}
+
+# A mapping from difficulty to the lower bound of givens in each row and column
+difficulty_lower_bound_mapping = {
+    "Extremely Easy": 14,
+    "Easy": 11,
+    "Medium": 7,
+    "Difficult": 4,
+    "Evil": 0,
+}
+
+digging_sequence_mapping = {
+    "Extremely Easy": "random",
+    "Easy": "random",
+    "Medium": "Jumping one cell",
+    "Difficult": "Wandering along 'S'",
+    "Evil": "Left to right, top to bottom",
+}
+
+
+class HoleDigger:
+    def __init__(self, puzzle: List[List[int]], difficulty: str):
+        self.puzzle = puzzle
+        self.size = len(puzzle)
+        self.difficulty = difficulty
+
+        self.target_range = difficulty_givensRange_mapping[difficulty]
+        self.num_givens = (
+            random.randint(*self.target_range)
+            if self.target_range[1] != float("inf")
+            else random.randint(self.target_range[0], self.size**2)
+        )
+
+        self.lower_bound = difficulty_lower_bound_mapping[difficulty]
+        self.pattern = digging_sequence_mapping[difficulty]
+
+        self.can_be_dug = {(i, j) for i in range(self.size) for j in range(self.size)}
+        self.remaining_cells = self.size * self.size
+
+    def get_digging_sequence(self) -> List[Tuple[int, int]]:
+        if self.pattern == "random":
+            return self._random_pattern()
+        elif self.pattern == "Jumping one cell":
+            return self._jumping_pattern()
+        elif self.pattern == "Wandering along 'S'":
+            return self._s_pattern()
+        else:  # "Left to right, top to bottom"
+            return self._linear_pattern()
+
+    def _random_pattern(self) -> List[Tuple[int, int]]:
+        cells = list(self.can_be_dug)
+        random.shuffle(cells)
+        return cells
+
+    def _jumping_pattern(self) -> List[Tuple[int, int]]:
+        sequence = []
+        # Forward pass - only on even rows (0, 2, 4...)
+        for i in range(0, self.size, 2):
+            for j in range(0, self.size, 2):
+                sequence.append((i, j))
+
+        # Backward pass - only on odd rows (1, 3, 5...)
+        for i in range(1, self.size, 2):
+            for j in range(self.size - 2, -1, -2):
+                sequence.append((i, j))
+
+        return sequence
+
+    def _s_pattern(self) -> List[Tuple[int, int]]:
+        sequence = []
+        for i in range(self.size):
+            row = range(self.size) if i % 2 == 0 else range(self.size - 1, -1, -1)
+            for j in row:
+                sequence.append((i, j))
+        return sequence
+
+    def _linear_pattern(self) -> List[Tuple[int, int]]:
+        return [(i, j) for i in range(self.size) for j in range(self.size)]
+
+    def pass_restrictions(self, row: int, col: int) -> bool:
+        # Skip if already dug
+        if self.puzzle[row][col] == 0:
+            return False
+
+        # Check if digging would violate minimum remaining cells
+        if self.remaining_cells - 1 < self.num_givens:
+            return False
+
+        # Check row constraint
+        row_remaining = sum(cell != 0 for cell in self.puzzle[row])
+        if row_remaining - 1 < self.lower_bound:
+            return False
+
+        # Check column constraint
+        col_remaining = sum(self.puzzle[i][col] != 0 for i in range(self.size))
+        if col_remaining - 1 < self.lower_bound:
+            return False
+
+        return True
+
+    def has_unique_solution(self) -> bool:
+        solver = DFSSolver(size=self.size, solutions_limit=2)
+        solutions = solver.solve(self.puzzle)
+        return len(solutions) == 1
+
+    def dig_holes(self) -> List[List[int]]:
+        digging_sequence = self.get_digging_sequence()
+        cells_to_check = set(digging_sequence)
+
+        while cells_to_check:
+            row, col = next(iter(cells_to_check))
+
+            if not self.pass_restrictions(row, col):
+                cells_to_check.remove((row, col))
+                continue
+
+            # Save current value in case we need to restore it
+            current_value = self.puzzle[row][col]
+            self.puzzle[row][col] = 0
+
+            if not self.has_unique_solution():
+                # Restore the value if digging creates multiple solutions
+                self.puzzle[row][col] = current_value
+                self.can_be_dug.remove((row, col))
+            else:
+                # Update remaining cells if digging is successful
+                self.remaining_cells -= 1
+
+            cells_to_check.remove((row, col))
+
+        return self.puzzle

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/sudoku_generator/las_vegas.py

@@ -0,0 +1,150 @@
+import random
+import time
+from .dfs_solver import DFSSolver
+from typing import List, Set, Tuple
+from multiprocessing import Process, Queue
+
+
+def solve_with_timeout(grid, solver, queue):
+    start_time = time.time()
+    solutions = solver.solve(grid)
+    solve_time = time.time() - start_time
+    queue.put((solutions, solve_time))
+
+
+class LasVegasGenerator:
+    def __init__(self, size: int = 25, givens: int = 80, timeout: int | None = 5):
+        self.size = size
+        self.givens = givens
+        self.timeout = timeout
+        self.all_positions = [
+            (i, j) for i in range(self.size) for j in range(self.size)
+        ]  # Create list of all possible positions
+        self.rows = [set() for _ in range(self.size)]
+        self.cols = [set() for _ in range(self.size)]
+        self.boxes = [set() for _ in range(self.size)]
+        self.solver = DFSSolver(size, solutions_limit=1)
+
+        box_size = int(self.size**0.5)
+        self.box_lookup = [[0] * size for _ in range(size)]
+        for i in range(size):
+            for j in range(size):
+                self.box_lookup[i][j] = (i // box_size) * box_size + (j // box_size)
+
+    def create_empty_grid(self) -> List[List[int]]:
+        return [[0 for _ in range(self.size)] for _ in range(self.size)]
+
+    def get_random_positions(self) -> Set[Tuple[int, int]]:
+        # Use random.sample to select givens number of positions without replacement
+        selected_positions = random.sample(self.all_positions, self.givens)
+
+        return set(selected_positions)
+
+    def is_valid_number(
+        self, grid: List[List[int]], row: int, col: int, num: int
+    ) -> bool:
+        # Check if number exists in row, column or box using sets
+        if (
+            num in self.rows[row]
+            or num in self.cols[col]
+            or num in self.boxes[self.box_lookup[row][col]]
+        ):
+            return False
+        return True
+
+    def fill_random_positions(
+        self, grid: List[List[int]], positions: Set[Tuple[int, int]]
+    ) -> bool:
+        # Clear existing sets
+        self.rows = [set() for _ in range(self.size)]
+        self.cols = [set() for _ in range(self.size)]
+        self.boxes = [set() for _ in range(self.size)]
+
+        positions_list = list(positions)
+        random.shuffle(positions_list)
+
+        def backtrack(pos_index: int) -> bool:
+            if pos_index == len(positions_list):
+                return True
+
+            row, col = positions_list[pos_index]
+            valid_numbers = [
+                num
+                for num in range(1, self.size + 1)
+                if self.is_valid_number(grid, row, col, num)
+            ]
+
+            random.shuffle(valid_numbers)
+
+            for num in valid_numbers:
+                grid[row][col] = num
+                self.rows[row].add(num)
+                self.cols[col].add(num)
+                self.boxes[self.box_lookup[row][col]].add(num)
+
+                if backtrack(pos_index + 1):
+                    return True
+
+                grid[row][col] = 0
+                self.rows[row].remove(num)
+                self.cols[col].remove(num)
+                self.boxes[self.box_lookup[row][col]].remove(num)
+
+            return False
+
+        return backtrack(0)
+
+    def generate(self) -> List[List[int]]:
+        attempts = 0
+
+        while True:
+            attempts += 1
+            print(f"Attempt {attempts}...")
+            attempt_start = time.time()
+
+            grid = self.create_empty_grid()
+            positions = self.get_random_positions()
+
+            if not self.fill_random_positions(grid, positions):
+                continue
+
+            queue = Queue()
+            process = Process(
+                target=solve_with_timeout, args=(grid, self.solver, queue)
+            )
+            process.start()
+
+            if self.timeout is not None:
+                process.join(timeout=self.timeout)
+                if process.is_alive():
+                    process.terminate()
+                    process.join()
+                    continue
+            else:
+                process.join()
+                attempt_duration = time.time() - attempt_start
+                print(f"Attempt duration: {attempt_duration:.2f} seconds")
+
+            try:
+                solution, solve_time = queue.get_nowait()
+                if solution:
+                    print(f"Found valid puzzle after {attempts} attempts")
+                    print(f"Solving time: {solve_time:.2f} seconds")
+                    return solution
+            except Exception:  # Changed from queue.Empty to catch any queue errors
+                continue
+
+
+def print_grid(grid: List[List[int]]):
+    size = len(grid)
+    box_size = int(size**0.5)
+
+    for i, row in enumerate(grid):
+        if i > 0 and i % box_size == 0:
+            print("-" * (size * 3 + box_size))
+
+        for j, num in enumerate(row):
+            if j > 0 and j % box_size == 0:
+                print("|", end=" ")
+            print(f"{num:2}", end=" ")
+        print()

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/benchmarks/sudoku_generator/sudoku_generator.py

@@ -0,0 +1,113 @@
+import os
+import json
+import copy
+from datetime import datetime
+from typing import List, Tuple
+
+from .las_vegas import LasVegasGenerator
+from .hole_digger import HoleDigger
+
+
+class SudokuGenerator:
+    """Generates Sudoku puzzles and their solutions using Las Vegas algorithm.
+
+    This class handles the complete puzzle generation process:
+    1. Generates a complete valid solution using Las Vegas algorithm
+    2. Creates holes in the solution to create the actual puzzle
+    3. Saves both puzzle and solution with metadata
+
+    Attributes:
+        size (int): Size of the Sudoku grid (e.g., 25 for 25x25)
+        givens (int): Number of initial filled positions for Las Vegas
+        timeout (int): Maximum generation attempt time in seconds
+        difficulty (str): Target difficulty level for hole creation
+        puzzles_dir (str): Directory for storing generated puzzles
+        solutions_dir (str): Directory for storing solutions
+
+    Example:
+        >>> generator = SudokuGenerator(size=9, difficulty="Hard")
+        >>> puzzle, solution, puzzle_id = generator.generate()
+    """
+
+    def __init__(
+        self,
+        size: int = 25,
+        givens: int = 80,
+        timeout: int = 5,
+        difficulty: str = "Medium",
+        puzzles_dir: str = "benchmarks/puzzles",
+        solutions_dir: str = "benchmarks/solutions",
+    ):
+        """Initialize the Sudoku puzzle generator.
+
+        Args:
+            size: Grid size (default 25 for 25x25 grid)
+            givens: Number of initial filled positions for Las Vegas
+            timeout: Maximum time in seconds for generation attempts
+            difficulty: Puzzle difficulty level for hole digger
+            puzzles_dir: Directory to store generated puzzles
+            solutions_dir: Directory to store solutions
+        """
+        self.size = size
+        self.givens = givens
+        self.timeout = timeout
+        self.difficulty = difficulty
+        self.puzzles_dir = puzzles_dir
+        self.solutions_dir = solutions_dir
+
+        # Create directories if they don't exist
+        os.makedirs(puzzles_dir, exist_ok=True)
+        os.makedirs(solutions_dir, exist_ok=True)
+
+    def generate(self) -> Tuple[List[List[int]], List[List[int]], str]:
+        """Generate a complete Sudoku puzzle and solution pair.
+
+        Uses a two-step process:
+        1. Las Vegas algorithm generates a complete valid solution
+        2. Hole digger creates the puzzle by removing certain cells
+
+        Returns:
+            tuple: Contains:
+                - List[List[int]]: The puzzle grid with holes
+                - List[List[int]]: The complete solution grid
+                - str: Unique identifier for the puzzle/solution pair
+
+        Note:
+            The generated puzzle is guaranteed to have a unique solution
+        """
+        # Step 1: Generate complete solution using Las Vegas
+        generator = LasVegasGenerator(self.size, self.givens, self.timeout)
+        solution = generator.generate()
+
+        # Step 2: Create holes using HoleDigger
+        digger = HoleDigger(copy.deepcopy(solution), self.difficulty)
+        puzzle = digger.dig_holes()
+
+        # Generate unique identifier for this puzzle
+        puzzle_id = self._generate_puzzle_id()
+
+        # Save both puzzle and solution
+        self._save_grid(puzzle, puzzle_id, is_puzzle=True)
+        self._save_grid(solution, puzzle_id, is_puzzle=False)
+
+        return puzzle, solution, puzzle_id
+
+    def _generate_puzzle_id(self) -> str:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        return f"sudoku_{self.size}x{self.size}_{self.difficulty}_{timestamp}"
+
+    def _save_grid(self, grid: List[List[int]], puzzle_id: str, is_puzzle: bool):
+        directory = self.puzzles_dir if is_puzzle else self.solutions_dir
+        filename = f"{puzzle_id}_{'puzzle' if is_puzzle else 'solution'}.json"
+        filepath = os.path.join(directory, filename)
+
+        metadata = {
+            "size": self.size,
+            "difficulty": self.difficulty,
+            "givens": sum(cell != 0 for row in grid for cell in row),
+            "type": "puzzle" if is_puzzle else "solution",
+            "grid": grid,
+        }
+
+        with open(filepath, "w") as f:
+            json.dump(metadata, f, indent=2)

{sudoku_smt_solvers-0.3.0 → sudoku_smt_solvers-1.0.0}/sudoku_smt_solvers/solvers/__init__.py

@@ -2,4 +2,5 @@ from .cvc5_solver import CVC5Solver
 from .dpll_solver import DPLLSolver
 from .dpllt_solver import DPLLTSolver
 from .z3_solver import Z3Solver
-from .utils.sudoku_error import SudokuError
+
+__all__ = ["CVC5Solver", "DPLLSolver", "DPLLTSolver", "Z3Solver"]

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/solvers/utils/__init__.py

@@ -0,0 +1,3 @@
+from .sudoku_error import SudokuError
+
+__all__ = ["SudokuError"]

sudoku_smt_solvers-1.0.0/sudoku_smt_solvers/solvers/utils/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-0.3.0 → sudoku_smt_solvers-1.0.0/sudoku_smt_solvers.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sudoku_smt_solvers
-Version: 0.3.0
+Version: 1.0.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, Tairan 'Ryan' Ji
@@ -35,7 +35,7 @@ Dynamic: summary
 
 
 ## About
-This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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.
+This repository contains the code for the study "Evaluating SMT-Based Solvers on Sudoku". Created by Liam Davis (@liamjdavis) and Tairan "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. The corresponding paper can be found [here](https://arxiv.org/abs/2501.08569).
 
 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.
 
@@ -61,7 +61,7 @@ This package includes the DPLL solver and three modern SMT solvers:
 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
+from sudoku_smt_solvers import Z3Solver
 
 # Example grid (25x25)
 grid = [[0] * 25 for _ in range(25)]
@@ -78,7 +78,7 @@ else:
 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
+from sudoku_smt_solvers import SudokuGenerator
 
 generator = SudokuGenerator(size = 25, givens = 80, timeout = 5, difficulty = "Medium", puzzles_dir = "benchmarks/puzzles", solutions_dir = "benchmarks/solutions")
 
@@ -91,11 +91,10 @@ Due to the computational complexity of generating large sudoku puzzles, it is re
 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
+from sudoku_smt_solvers import BenchmarkRunner
 
 runner = BenchmarkRunner(
     puzzles_dir='resources/benchmarks/puzzles/',
-    solutions_dir='resources/benchmarks/solutions/',
     results_dir='results/'
 )
 runner.run_benchmarks()

{sudoku_smt_solvers-0.3.0 → sudoku_smt_solvers-1.0.0}/sudoku_smt_solvers.egg-info/SOURCES.txt

@@ -10,11 +10,18 @@ sudoku_smt_solvers.egg-info/requires.txt
 sudoku_smt_solvers.egg-info/top_level.txt
 sudoku_smt_solvers/benchmarks/__init__.py
 sudoku_smt_solvers/benchmarks/benchmark_runner.py
+sudoku_smt_solvers/benchmarks/sudoku_generator/__init__.py
+sudoku_smt_solvers/benchmarks/sudoku_generator/dfs_solver.py
+sudoku_smt_solvers/benchmarks/sudoku_generator/hole_digger.py
+sudoku_smt_solvers/benchmarks/sudoku_generator/las_vegas.py
+sudoku_smt_solvers/benchmarks/sudoku_generator/sudoku_generator.py
 sudoku_smt_solvers/solvers/__init__.py
 sudoku_smt_solvers/solvers/cvc5_solver.py
 sudoku_smt_solvers/solvers/dpll_solver.py
 sudoku_smt_solvers/solvers/dpllt_solver.py
 sudoku_smt_solvers/solvers/z3_solver.py
+sudoku_smt_solvers/solvers/utils/__init__.py
+sudoku_smt_solvers/solvers/utils/sudoku_error.py
 tests/test_benchmark_runner.py
 tests/test_cvc5_solver.py
 tests/test_dfs_solver.py

sudoku_smt_solvers-0.3.0/sudoku_smt_solvers/__init__.py

@@ -1,19 +0,0 @@
-"""Sudoku SMT Solvers - A package for solving and benchmarking large-scale Sudoku puzzles.
-
-This package provides various SAT and SMT-based solvers optimized for 25x25 Sudoku puzzles,
-along with tools for puzzle generation and solver benchmarking.
-
-Key Components:
-- Multiple solver implementations (DPLL, DPLL(T), Z3, CVC5)
-- Sudoku puzzle generator with difficulty settings
-- Benchmarking suite for comparing solver performance
-"""
-
-from .solvers.dpll_solver import DPLLSolver
-from .solvers.dpllt_solver import DPLLTSolver
-from .solvers.z3_solver import Z3Solver
-from .solvers.cvc5_solver import CVC5Solver
-from .benchmarks.benchmark_runner import BenchmarkRunner
-from .benchmarks.sudoku_generator.sudoku_generator import SudokuGenerator
-
-__version__ = "0.3.0"

sudoku_smt_solvers-0.3.0/sudoku_smt_solvers/benchmarks/__init__.py

@@ -1,5 +0,0 @@
-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