# fast_sudoku_solver
## Description
This is a Python-project for solving 9x9 Sudoku puzzles using constraint propagation techniques combined with brute force search when necessary. The solver leverages the power of NumPy for numerical computations, making it highly performant for a Python based solver.
It includes functionality to validate solutions, solve puzzles, and compute the number of possible value combinations for an unsolved Sudoku puzzle.
## Installation
To run the Sudoku Solver, you will need Python 3.9 or higher. You can install it in one of two ways:
### Option 1: Install from PyPI using pip
```bash
pip install fast_sudoku_solver
```
### Option 2: Clone the repository
Clone the repository to your local machine:
```bash
git clone https://github.com/CassiusCle/fast_sudoku_solver
```
Install the required dependencies:
```bash
pip install -r requirements.txt
```
When running Sudoku Solver from the cloned repository, it is advised to install it as a package in "editable" mode using:
```bash
pip install -e .
```
## Usage
There are two main ways of using the Sudoku Solver, through the command-line or within Python.
N.B.: The solver was designed to take in Sudoku puzzles in the form of strings. Here the characters in the string represent the flattened Sudoku grid and empty cells are denoted by either "0" or ".".
### Command line
To run the Sudoku Solver from the command-line, simply run a command like below with your unsolved Sudoku:
```bash
python -m fast_sudoku_solver ..7........5.4..7..695...31...4.58.2.5..2..4.6.23.1...29...358..3..1.2........3..
```
```bash
> Solved Sudoku:
> ┌─────────┬─────────┬─────────┐
> │ 4 1 (7)│ 9 3 8 │ 6 2 5 │
> │ 3 2 (5)│ 1 (4) 6 │ 9 (7) 8 │
> │ 8 (6)(9)│(5) 7 2 │ 4 (3)(1)│
> ├─────────┼─────────┼─────────┤
> │ 1 7 3 │(4) 9 (5)│(8) 6 (2)│
> │ 9 (5) 8 │ 6 (2) 7 │ 1 (4) 3 │
> │(6) 4 (2)│(3) 8 (1)│ 7 5 9 │
> ├─────────┼─────────┼─────────┤
> │(2)(9) 1 │ 7 6 (3)│(5)(8) 4 │
> │ 5 (3) 6 │ 8 (1) 4 │(2) 9 7 │
> │ 7 8 4 │ 2 5 9 │(3) 1 6 │
> └─────────┴─────────┴─────────┘
> Flattened solution: 417938625325146978869572431173495862958627143642381759291763584536814297784259316
```
### Python
The code examples below show a few of the functionalities of the package. Please also see the `examples/example_usage.py` script and the various Sudoku examples that are included in the repository.
#### Solving a Sudoku
```python
from fast_sudoku_solver.sudoku_solver import SudokuSolver
unsolved_puzzle = "..7........5.4..7..695...31...4.58.2.5..2..4.6.23.1...29...358..3..1.2........3.."
solution: str = SudokuSolver.solve(unsolved_puzzle)
# Print solution as string
print("Solved Puzzle:", solution)
```
#### Validating a solution:
```python
is_valid: bool = SudokuSolver.validate(solution)
print("Is the solution valid?", is_valid)
```
#### Printing a Sudoku in a formatted grid
```python
from fast_sudoku_solver.services import SudokuFormatter
# Pretty print orignal (unsolved) puzzle
SudokuFormatter.print(puzzle=unsolved_puzzle)
# Pretty print solution only
SudokuFormatter.print(solution=solution)
# Pretty print original puzzle overlaid with solution
SudokuFormatter.print(puzzle=unsolved_puzzle, solution=solution)
```
## Testing
To run the tests for the Sudoku Solver, navigate to the project root and execute:
```python
python pytest
```
N.B.: Testing is yet to be implemented in a later version.
## Contributing
If you'd like to contribute to the Sudoku Solver project, please feel free to make a pull request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/CassiusCle/fast_sudoku_solver",
"name": "fast_sudoku_solver",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "sudoku, solver, fast, constraint, propagation, brute, force",
"author": "CassiusCle",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/28/03/fec5c5f6d58ee8482ebd729e989262757e8306096821b2c565ee001808e5/fast_sudoku_solver-1.0.1.tar.gz",
"platform": null,
"description": "# fast_sudoku_solver\n \n## Description \n \nThis is a Python-project for solving 9x9 Sudoku puzzles using constraint propagation techniques combined with brute force search when necessary. The solver leverages the power of NumPy for numerical computations, making it highly performant for a Python based solver. \nIt includes functionality to validate solutions, solve puzzles, and compute the number of possible value combinations for an unsolved Sudoku puzzle.\n \n## Installation \nTo run the Sudoku Solver, you will need Python 3.9 or higher. You can install it in one of two ways:\n\n### Option 1: Install from PyPI using pip\n```bash \npip install fast_sudoku_solver\n```\n\n### Option 2: Clone the repository\nClone the repository to your local machine:\n\n```bash\ngit clone https://github.com/CassiusCle/fast_sudoku_solver\n```\n\nInstall the required dependencies:\n```bash\npip install -r requirements.txt\n```\n\nWhen running Sudoku Solver from the cloned repository, it is advised to install it as a package in \"editable\" mode using:\n```bash\npip install -e .\n```\n \n## Usage\nThere are two main ways of using the Sudoku Solver, through the command-line or within Python.\n\nN.B.: The solver was designed to take in Sudoku puzzles in the form of strings. Here the characters in the string represent the flattened Sudoku grid and empty cells are denoted by either \"0\" or \".\".\n\n### Command line\nTo run the Sudoku Solver from the command-line, simply run a command like below with your unsolved Sudoku:\n```bash\npython -m fast_sudoku_solver ..7........5.4..7..695...31...4.58.2.5..2..4.6.23.1...29...358..3..1.2........3..\n```\n\n```bash\n> Solved Sudoku:\n> \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n> \u2502 4 1 (7)\u2502 9 3 8 \u2502 6 2 5 \u2502\n> \u2502 3 2 (5)\u2502 1 (4) 6 \u2502 9 (7) 8 \u2502\n> \u2502 8 (6)(9)\u2502(5) 7 2 \u2502 4 (3)(1)\u2502\n> \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n> \u2502 1 7 3 \u2502(4) 9 (5)\u2502(8) 6 (2)\u2502\n> \u2502 9 (5) 8 \u2502 6 (2) 7 \u2502 1 (4) 3 \u2502\n> \u2502(6) 4 (2)\u2502(3) 8 (1)\u2502 7 5 9 \u2502\n> \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n> \u2502(2)(9) 1 \u2502 7 6 (3)\u2502(5)(8) 4 \u2502\n> \u2502 5 (3) 6 \u2502 8 (1) 4 \u2502(2) 9 7 \u2502\n> \u2502 7 8 4 \u2502 2 5 9 \u2502(3) 1 6 \u2502\n> \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n> Flattened solution: 417938625325146978869572431173495862958627143642381759291763584536814297784259316\n```\n\n### Python\nThe code examples below show a few of the functionalities of the package. Please also see the `examples/example_usage.py` script and the various Sudoku examples that are included in the repository.\n\n#### Solving a Sudoku\n```python \nfrom fast_sudoku_solver.sudoku_solver import SudokuSolver \n \nunsolved_puzzle = \"..7........5.4..7..695...31...4.58.2.5..2..4.6.23.1...29...358..3..1.2........3..\"\nsolution: str = SudokuSolver.solve(unsolved_puzzle) \n\n# Print solution as string\nprint(\"Solved Puzzle:\", solution) \n```\n \n#### Validating a solution:\n```python \nis_valid: bool = SudokuSolver.validate(solution)\n\nprint(\"Is the solution valid?\", is_valid) \n```\n\n#### Printing a Sudoku in a formatted grid\n```python \nfrom fast_sudoku_solver.services import SudokuFormatter\n\n# Pretty print orignal (unsolved) puzzle\nSudokuFormatter.print(puzzle=unsolved_puzzle)\n\n# Pretty print solution only\nSudokuFormatter.print(solution=solution)\n\n# Pretty print original puzzle overlaid with solution\nSudokuFormatter.print(puzzle=unsolved_puzzle, solution=solution) \n```\n\n## Testing\n\nTo run the tests for the Sudoku Solver, navigate to the project root and execute:\n\n```python\npython pytest \n```\n\nN.B.: Testing is yet to be implemented in a later version.\n\n## Contributing\n\nIf you'd like to contribute to the Sudoku Solver project, please feel free to make a pull request.\n\n## License\n \nThis project is licensed under the MIT License - see the LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fast Python Sudoku Solver for 9x9 puzzles using constraint propagation and brute force, powered by NumPy and with a command-line interface.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/CassiusCle/fast_sudoku_solver",
"Repository": "https://github.com/CassiusCle/fast_sudoku_solver"
},
"split_keywords": [
"sudoku",
" solver",
" fast",
" constraint",
" propagation",
" brute",
" force"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0a94a5a5af688f0a5e31aea5e845bfd20c55734d2cd8b65fb06b535634313353",
"md5": "ab9cace7543554d680ffa42c659748c7",
"sha256": "f1a962dcbbf55af355f9e589076905c92e3d3ff7f5aef384d3f0ffbcd86aefc6"
},
"downloads": -1,
"filename": "fast_sudoku_solver-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab9cace7543554d680ffa42c659748c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 14004,
"upload_time": "2024-08-20T16:10:35",
"upload_time_iso_8601": "2024-08-20T16:10:35.701438Z",
"url": "https://files.pythonhosted.org/packages/0a/94/a5a5af688f0a5e31aea5e845bfd20c55734d2cd8b65fb06b535634313353/fast_sudoku_solver-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2803fec5c5f6d58ee8482ebd729e989262757e8306096821b2c565ee001808e5",
"md5": "d550af6f740e14cb743cc23428645b9d",
"sha256": "ee26c308dbb72a5ea6244e281d482b909290bdebc7d6b344d6ab085e3e008904"
},
"downloads": -1,
"filename": "fast_sudoku_solver-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d550af6f740e14cb743cc23428645b9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12752,
"upload_time": "2024-08-20T16:10:37",
"upload_time_iso_8601": "2024-08-20T16:10:37.214788Z",
"url": "https://files.pythonhosted.org/packages/28/03/fec5c5f6d58ee8482ebd729e989262757e8306096821b2c565ee001808e5/fast_sudoku_solver-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 16:10:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CassiusCle",
"github_project": "fast_sudoku_solver",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "fast_sudoku_solver"
}
JSON
