Sudoku RL Solver

An intelligent Sudoku solver powered by Reinforcement Learning, specifically using a Deep Q-Network (DQN). This project combines a robust neural network backend with a modern PyQt6 graphical user interface to provide real-time visualization of the agent's learning and solving process.

Download & Run (Windows Executable)

You can download the standalone Windows executable from Releases.

• After downloading the .zip, extract it and run the application by double-clicking the SudokuRLSolver.exe file.

Features

• RL-Based Solver: Uses Deep Q-Learning to master Sudoku puzzles through trial and error.
• Modern UI: A responsive and interactive GUI built with PyQt6.
• Real-time Training: Watch the agent solve puzzles line by line, with visual feedback on its actions.
• Difficulty Selection: Support for multiple difficulty levels (Easy, Medium, Hard, Expert).
• Performance Analytics: Integrated charts and stats to track training progress, loss, and rewards.
• Model Persistence: Save and load trained models to resume progress or share results.

Project Structure

sudoku-rl/
├── agents/             # RL Agent implementations (DQN)
├── environment/        # Sudoku environment logic and state representation
├── models/             # Neural network architectures and replay buffers
├── ui/                 # PyQt6 graphical interface components
├── training/           # Training loops and logic
├── utils/              # Helper functions and Sudoku generation logic
├── saved_models/       # Directory for serialized models (ignored by git)
└── main.py             # Application entry point

Installation

1. Clone the repository:

   git clone https://github.com/Mostafa-Abbasi/Sudoku-Solver.git
   cd Sudoku-Solver

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

Usage

To start the application, simply run:

python main.py

From the control panel, you can:

• Select a difficulty level.
• Generate a new puzzle.
• Start/stop the training process.
• Save or load your trained models.

Building from Source (Windows Executable)

If you want to generate a standalone Windows executable yourself:

1. Install PyInstaller:

   pip install pyinstaller

2. Ensure CPU-only PyTorch (to keep size manageable):

   pip install torch --index-url https://download.pytorch.org/whl/cpu

3. Run the build:

   pyinstaller --noconfirm sudoku_rl.spec

The resulting executable will be found in dist/SudokuRLSolver/.

Deep Reinforcement Learning Details

The solver treats Sudoku as a Markov Decision Process (MDP):

• State: The current 9x9 board configuration.
• Action: Selecting a cell and assigning a number (1-9).
• Reward: Positive feedback for correct placements and negative feedback for collisions or invalid moves.
• Model: A Deep Q-Network (DQN) that approximates the Q-value function to predict the best action for any given board state.

Contributing

Feel free to fork the project and submit pull requests. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.