This is a Ulster University, BSc Computing Science final year project which solves 9x9 Sudoku puzzles.
The dissertation submitted with this code base is found in ./report/dissertation.pdf
This project was developed using:
python v2.7python modules versionas described in./py/requirements.txtq v3.6rlwrapES6HTML5CSS3
Software versions are subject to change with new releases, to ensure the project runs smoothly without alteration the above versions should be used. This software was last ran on 16/04/2019.
The application currently solves 94.5% of valid puzzles suppled to it.
This application allows users to play 9x9 Sudoku puzzles through its front-end website. However, its main feature is its ability to solve and check solutions through its back-end algorithm engine.
This application allows users to play and complete 9x9 Sudoku puzzles through its website; it can source puzzles with 3 varying difficulties: easy, medium and hard, or the user can manually enter puzzles.
The user can then enter numbers into the cells using mouse clicks or keyboard presses; the method of entry can be changed at will. It supports removing and overwriting values in cells except the starting clues which are immutable.
The website is hosted via a python Flask server.
The application attempts to solve the board in its current state (i.e. the starting clues plus user values added) and returns the first solution it finds (this is a prerequisite to a true Sudoku puzzle, i.e. a true Sudoku puzzle will only have 1 solution). It also displays the solved board in a new tab to allow it to be printed out.
Invalid boards (i.e. those with no solution) are returned to the user via a message stating so.
The back-end solving algorithm engine is developed in the functional programming language q and uses a brute-force backtracking algorithm.
Follow the instructions below to enable you to use the application to play and solve 9x9 Sudoku puzzles.
The following packages need to be installed before using this application:
- Complete this form to download q
- Follow the instructions when prompted during download
- Unzip the downloaded folder into home by running
unzip /path/to/download/file.zip -d /path/to/home/folder/ - Check the installation by running
/path/to/home/folder/q/l32/q
- Run this command
sudo apt-get install rlwrap - Check the installation by running
rlwrap -v
- Git clone the log4q repo by running
git clone <HTTPS URL>/log4q.git /path/to/log4q/repo/
To install this application on your local machine, follow these instructions:
- Create a project directory
mkdir proj/
- Clone this repo to your local machine
git clone <HTTPS URL>/onid.git /path/to/repo/proj/
2.5. Optional: Create a python virtual environment
python -m virtualenv .
then
. bin/activate
- Install the required python libraries
pip install -r ./onid/py/requirements.txt
To configure this application follow these steps:
- In
./q/bin/launch.shchange the placeholder paths to your specific files
home_path='/path/to/home/folder/'
src_path=$home_path'/path/to/repo/proj/onid/q/src/'
- In
~/.bashrcadd an environment variable for the entry point to the Flask application and source it
export FLASK_APP=/path/to/repo/proj/onid/py/src/src.py
then
. ~/.bashrc
In ./q/src/init.q and ./q/test/test.q change the placeholder path to your specific log4q file
\l /path/to/log4q/repo/log4q.q
To run this application both the front-end Flask server and the back-end q server must be running.
Note: the q server and Flask server run in the foreground so 2 terminal tabs are required.
- Change into the q folder
cd ./q
- Launch the server
sh ./bin/launch.sh
- Change into the py folder
cd ./py
- Launch the server
sh ./bin/launch.sh
This project is a proof of concept piece and all rights are reserved by the authors of the included software or otherwise - see the LICENSE.md file for details.