NAME
SudokuTrainer
This program helps to train the detection of successful Sudoku solution strategies. It may also be used to get over an obstacle in a partially solved Sudoku puzzle.
VERSION
This documentation refers to SudokuTrainer version 0.01.5.
PURPOSE
SudokuTrainer helps the user in solving classical 9x9 Sudoku puzzles. It does this in two areas:
1. Help to train a Sudoku strategy
2. Help to overcome an obstacle while solving a Sudoku puzzle
SudokuTrainer is not a Sudoku teacher. The user must know the strategy that he wants to train. People who don't know about Sudoku strategies may still use SudokuTrainer for the second purpose, just to get a new value for continuation.
USAGE
sudokutrainer [Sudoku_file] [--prio=priority-list]
OPTIONS
Sudoku_file
The path of a Sudoku file to be used for training.
If this option is omitted, SudokuTrainer will ask for it. You will get the following choices:
Read from file Insert manually Read example fileA doubleclick on a choice will select it and close the selection window. When you select the choice Insert manually the utility program enter_presets.pl gets started. To see the documentation of it, use "perldoc enter_presets.pl". After you entered the initial puzzle manually, you should better save it. Chances are good that you will need it several times. Corrections to the initial puzzle can also be made with enter_presets.pl.
--prio=priority-list
The path to a file where a priority list has been stored.
TERMINOLOGY
cell
A cell is one of the 81 squares in a Sudoku board that will each finally show a digit from 1 to 9.
row
A row is a horizontal line of 9 cells. Rows are numbered from 1 to 9, top to bottom.
column
A column is a vertical line of 9 cells. Columns are numbered from 1 to 9, left to right.
block
A block is one of the 9 3x3 subsquares of a Sudoku board. Blocks are numbered according to the following scheme:
1 2 3 4 5 6 7 8 9line
A line is either a row or a column.
unit
A unit is either a line or a block.
candidate
A digit is a candidate of a cell if it is currently not yet forbidden to use it as the value of the cell.
For more difficult Sudoku puzzles it may be helpful to inspect a list of all still possible (or already excluded) candidates. You may view the internal candidate list of SudokuTrainer for this purpose (see section "View" in Games::Sudoku::Trainer::Training).
strategy
A strategy is a systematic collection of patterns which the player of a Sudoku puzzle tries to detect in the current state of the puzzle. The strategy is named successful if its detection allows for the exclusion of one or more candidates from some cells.
priority
Each strategy has a priority assigned. The priorities give the sequence in which SudokuTrainer tries the stragegies. Stragegies that are considered as easy by the user are usually assigned a high priority.
A priority list is a list of all strategies (exept Full house), ordered by their priorities. The user may rearrange the strategies, thus changing their priorities (see section "Priorities" in Games::Sudoku::Trainer::Training). He may also save the priority list for later reuse.
NAMES OF CELLS AND UNITS
These names are used in communications with the user.
units
Units are named by a character that gives the unit type (r for row, c for column, b for block), followed by the unit number. E. g. c1 is the leftmost column of the Sudoku board.
cells
Cells are named by concatenating the names of the row and column that cross at the cell. E. g. r1c9 is the upper right cell of the Sudoku board.
GUIDE TO DOCUMENTATION
The documentation for SudokuTrainer is broken up into sections:
General information
This is the document you are currently reading. It describes basic usage and the terminology that is needed for the communication with SudokuTrainer.
Train a strategy
The document Games::Sudoku::Trainer::Training describes the operation of SudokuTrainer from a user point of view.
SudokuTrainer has a list of all strategies that it knows about. Easy strategies are near the top, the most difficult ones near the end of this list. SudokuTrainer starts the solution of a given puzzle with the easiest strategy and proceeds until it finds the strategy that the user wants to train. Here it pauses without showing the find. It's time to train.
Overcome an obstacle
The document Games::Sudoku::Trainer::Obstacle describes how the user lets SudokuTrainer find the next value step by step. He can comprehend each step with minimum help by SudokuTrainer.
Get a further value
The document Games::Sudoku::Trainer::Nextvalue describes how the user lets SudokuTrainer find value by value, until the find hasn't been found by the user before. So it's above all well suited for users that aren't familiar with Sudoku strategies.
FILE FORMAT OF SUDOKU PUZZLES
The Sudoku files of the trainer are ASCII text files.
The input format for Sudoku puzzles is rather flexible. At the top of the file, lines starting with "#" are ignored (comment lines). In the puzzle itself, there need not be 9 lines with 9 characters each: newlines are ignored. The digits 1 - 9 represent known values. Exept for the blank, any other printable ASCII character is taken as a placeholder for an unknown value. Blanks are taken as placeholders only when there are no other placeholders, otherwise they are ignored. The sum of known values and placeholders must amount to 81. When the "#" is used as a placeholder, it is recommended that the comment lines are followed by an empty line.
On output, "-" is used as the placeholder. The puzzle is stored as a 9x9 grid, with blanks and empty lines added to separate the 3x3 subsquares for better human readability.
DIAGNOSTICS
Error messages are displayed in a message window. The window title shows the error type:
User error
The user made an error when running the trainer (e. g. entered an invalid cell name). In most cases he may correct his error.
Data error
An error has been detected in the puzzle (e. g. a cell without a value and without candidates).
Code error
A contradiction has been found in the internal state of the puzzle.
Problem
These errors come from other sources, e. g. Perl/Tk or the Perl interpreter.
Perl/Tk shows some of its error messages in its own message window.
The Run button gets disabled when it's of no use to continue. The user may still save files or investigate the history.
DEPENDENCIES
In addition to modules that are distributed with perl, the trainer needs the following modules (available from CPAN):
TO DO
Add more strategies
Add a restart feature
BUGS
Please report any bugs or feature requests to bug-SudokuTrainer [at] rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=SudokuTrainer.
Please include the following material in the bug report:
the error message
the puzzle (preferedly in its initial state)
the priority list, if different from the default
any output in the shell window (normally there is none, exept for code errors)
AUTHOR
Klaus Wittrock (<Wittrock [at] cpan.org>)
ACKNOWLEDGEMENT
Alex Becker pointed out to me several passages in the code that urgently needed improvement. He also encourages me repeatedly to use more OO techniques.
LICENCE AND COPYRIGHT
Copyright 2014 Klaus Wittrock. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.