1. What is GNOME Sudoku?

Sudoku is a Japanese logic game popular that has recently become
popular in Great Britain and elsewhere (or so I've heard).

I (the author) am an American whose wife happened to get addicted to
sudoku. I played it once and decided I wanted to write a program to
solve Sudoku. It turned out, letting the computer solve the puzzle
took all the fun out of it.

So then I wrote GNOME Sudoku, a program for my favorite desktop
platform that generates new puzzles and helps you play them. Like all
the software I use, write and love, GNOME Sudoku is free software,
released under the GNU General Public License.

2. That's nice, but how do I play?

The rules of Sudoku are quite simple. You simply have to fill the
empty squares on the board with the numbers 1 through 9.

You must place the numbers such that every row, every column, and
every 3x3 box has the numbers 1 through 9 exactly once.

Another way of looking at this is to say that you must place all the
numbers on the grid such that no number repeats itself in any given
row, column or box.

These two different ways of looking at the puzzle are actually two of
the main ways you'll be thinking when you play. On the one hand, you
ask yourself "how can I fit all the numbers in this box, column or
row?" On the other hand, you ask yourself, "What number can go here
without causing a conflict with another number on the board?"

The squares that are bolded to start with are your givens -- the
placement of numbers in these squares is what makes a given puzzle
easy or hard.

If you don't understand yet, just start putting numbers in squares and
you'll get the hang of it -- if you make an illegal move, the numbers
that are in conflict will turn red.

By default, Sudoku will give you an easy game to start with (though
even the easy ones may not seem easy at first -- my first puzzle took
me over 3 hours to solve!). Each time you win a game, Sudoku will try
to find you a slightly harder game for the next one (Though you can
always customize your difficulty setting all you like).

Note that each sudoku generated by GNOME Sudoku has one and only one
solution. The hints are also distributed symmetrically, as is
traditional.

2.1. Trackers

Sometimes, it's useful to keep track of a series of moves all at once,
so that you can delete them all at once later if a guess turns out to
be wrong.  Trackers are designed for this. When you choose "Add
Tracker", new moves will show up in a different color to distinguish
them.  You can then delete all of these moves at once if you like, or
delete all other moves.

You can have as many trackers as you like.

2.2 Hints

When you play the game with pen and paper you do a lot of
note-taking. On the computer, that's not really possible. That means
that in general, on the computer, I find I play the game more "in my
head" than I do on paper, which is actually more fun.

Sometimes, though, you just want to keep track of what values are
possible in each square. If you click on "Hint" or type "Control-H"
(for Hint), you'll get a list of values that can go in each square.

2.3 Filling Squares Automatically

GNOME Sudoku has an "auto-fill" feature to automatically fill in
squares and save you some busy work. You press the "Fill" button in
the toolbar or the Hints menu to fill in the square the cursor is
currently on -- this is especially nice when you can see there is only
one square open in a column but you don't want to take the time to run
through the numbers and see which number is missing.

You can also choose to "Fill All Squares" automatically, which will
fill all squares currently fill-able using the two simple algorithms
gnome-sudoku's puzzle solver is based on. This should be used rarely
-- there are some puzzles which can be solved entirely by using this
command, which sort of takes the fun out of playing.

2.4 High Scores

When you finish, you get to put your name in high scores.

Sudoku isn't really a game you play for points, but I like high
scores, so GNOME Sudoku generates a score for you based on the
difficulty of the puzzle, the number of times you used hints (which
counts against you), and the time it takes you to solve the puzzle.

3. Saving and Opening Puzzles

3.1 Saving

I don't like the concept of "Saving", so GNOME Sudoku doesn't have a
Save command or button. But don't worry -- Sudoku *always* saves your
work. I got rid of "Save" not because saving doesn't matter, but
because saving your work is so important, it happens automatically.

3.1 Opening

Any time you open GNOME Sudoku, it will pick up where you left off
last time you closed.

Any time you open a new puzzle without finishing an old one, you can
get your old puzzle back in the state you left it. To get your puzzle
back, select "Resume game" from the toolbar or the File menu and
you'll get a list of puzzles you've played, along with information on
how long you've played each puzzle, when you started it, and when you
last worked on it.

3.2 New Puzzles

When you choose a new puzzle, you'll get a window asking you how
difficult a puzzle you want. The program will then look at its
available puzzles and choose the puzzle that best matches the
difficulty you requested.

If you click on the "Details" expander in the "New Puzzle" window, you
can get more detailed information about each puzzle GNOME Sudoku has
generated.

4. Where do the puzzles come from?

GNOME Sudoku makes the puzzles up on its own. Because this takes some
time and work from your computer, I distribute Sudoku with some
puzzles already in place. When you open GNOME Sudoku, it checks how
many puzzles it has. If it is running low, it will run its
puzzle-generator in the background while you play (the process will
stop any time the Sudoku Window is minimized so as not to interfere
with your other work).

You can stop GNOME Sudoku from generating new puzzles by un-checking
the "Generate new puzzles while you play" checkmark in the File menu.

5. How does the puzzle generator work?

Sudoku started as a simple puzzle solver. This solver is then used to
generate new puzzles (if you tell it to solve a blank puzzle, it will
come up with a new solution each time; then it's just a matter of
choosing which squares to give away as hints).

The solver tries three techniques. All three techniques factor into
the difficulty of a given puzzle.  1st, the solver has two ways to
fill in squares "deterministically".

5.1. By elimination

To fill in squares by elimination, the solver checks which values
could fit in any given square. If there is only one value that can go
in a square, it adds that value.

5.2. By filling

For this method, the solver looks at each row, column and box and sees
where any given digit could go. If there is only one square in a box,
row or column which can take a given number, the solver puts that
number in that place.

5.3 By guessing

When the solver can't fill any more squares by the above methods, it
will pick the square with the fewest possible candidates and guess. It
will then continue to work on the puzzle until it either solves it or
fails. If it fails to solve the puzzle, it simply tries another guess,
and so on until it wins.

6. Where do the difficulty ratings come from?

GNOME Sudoku rates puzzles based on how many guesses were necessary to
solve it (for many puzzles, no guesses are necessary) and how many
squares can be solved for in the puzzle's initial state.

A quick test says that my difficulty ratings line up well with those
of popular websites such as dailysudoku.com

You can get more details on the difficulty rating for the current
puzzle by selecting "Puzzle Statistics" from the "Hints" menu.

7. Where can I ask more questions?

You can report bugs, feature requests, or submit patches at GNOME
Sudoku's sourceforge page: http://sf.net/projects/gnome-sudoku/

You can also e-mail me directly at Thomas_Hinkle@alumni.brown.edu

8. How can I help out?

If you're a programmer, please feel free to hack on Sudoku's code,
either by sprucing up the UI (the trackers could be much nicer!) or by
working on the solver and generator code, which could use some
optimization!

If you're not a programmer, there's lots GNOME Sudoku could use, including:

Nicer icons

A nice web page

Better documentation than this file!

Any contributions will be gladly accepted as patches at sourceforge or
as e-mails directly to Thomas_Hinkle@alumni.brown.edu