| Author: | David Goodger <goodger@python.org> |
|---|---|
| Date: | 2015-02-24 |
| Web site: | http://puzzler.sourceforge.net/ |
| Copyright: | © 1998-2015 by David J. Goodger |
| License: | GPL 2 |
Polyform Puzzler is a set of solvers for many polyform puzzles (like Pentominoes and Soma Cubes), and a software toolkit for exploring & solving polyform puzzles. It consists of a set of front-end applications for specific polyform puzzles and a Python library that does the heavy lifting. New polyforms and new puzzles can easily be defined and added. Python 2.4 or higher is required.
Polyform Puzzler also contains a Sudoku puzzle solver using the same (versatile!) engine.
Contents
This section is for those who understand computers well and who want to get up & running quickly. If you don't know what a "shell" is, or if you don't understand any of the following steps, go to "Installation" below. Full details are in the following sections.
Get and install the latest release of Python, available from
Python 2.5 or later; Python 2.7.2 or later is recommended.
Use the latest Polyform Puzzler code. Get the code from Subversion or from the snapshot:
See Snapshots below for details.
Unpack the snapshot tarball (archive file) in a temporary directory (not directly in Python's site-packages).
For example, on Unix, GNU/Linux, or Mac OS X, in a shell type:::
tar xzf puzzler-snapshot.tgz
On Windows, use the WinZip program (or equivalent) to unpack the archive file.
In a shell/terminal, move (cd) into the temporary directory:
cd puzzler
There are two ways to proceed from here: install it, or just run it:
This option installs the Polyform Puzzler library into Python's system-wide standard library.
Run install.py with admin rights. On Windows systems it may be sufficient to double-click install.py. On Unix, GNU/Linux, or Mac OS X, type:
su (enter admin password) ./install.py
See Installation below for details.
Use a front-end application from the "bin" subdirectory. For example:
cd bin ./pentominoes3x20.py (Unix/Mac) python pentominoes3x20.py (Windows)
See Usage below for details.
This option allows you to use the "puzzler" package without installing it permanently. Note that you will only be able to use the "puzzler" package from one location (where you unpacked it, not from arbitrary locations on your system), unless you install it, or you set your PYTHONPATH environment variable.
In the top-level directory (containing the "puzzler", "docs", and "bin" directories), you can run the various front-ends.
See Usage below for details.
Unix/Mac users:
Enter the following command:
PYTHONPATH= bin/pentominoes3x20.py
The PYTHONPATH= part tells Python to look in the current directory for modules and packages, so it can find the "puzzler" package (directory).
Windows users:
Enter the following commands:
set PYTHONPATH=; python bin\pentominoes3x20.py
The set PYTHONPATH=; command tells Python to look in the current directory for modules and packages, so it can find the "puzzler" package (directory).
If the Python executable is not on your PATH, you will have to specify its location, e.g.:
C:\Python24\python bin\pentominoes3x20.py
We recommend that you always use the current snapshot, which is usually updated within an hour of changes being committed to the repository:
http://puzzler.sourceforge.net/puzzler-snapshot.tgz
To keep up to date on the latest developments, either download fresh copies of the snapshots regularly, or use the Subversion repository:
svn co https://puzzler.svn.sourceforge.net/svnroot/puzzler/trunk/puzzler
OS-specific installation instructions follow. For non-standard installations (i.e. installing to non-standard places, like your home directory), please see Installing Python Modules.
Open a shell (terminal).
Expand the .tgz archive into a temporary directory (not directly into Python's site-packages):
tar xzf puzzler-snapshot.tgz
(The archive file name may not be exactly as shown above.)
Go to the directory created by expanding the archive:
cd <archive_directory_path>
It contains a distutils setup file "setup.py".
Install the package (you may need root permissions to complete this step):
python setup.py install
If the Python executable isn't on your PATH, you'll have to specify the complete path, such as /usr/local/bin/python.
You can also just run install.py; it does the same thing.
Double-click on the .tgz archive; this should open the archive in WinZip. (If you don't have WinZip or equivalent installed, please download and install it.) Extract the archive's contents into a temporary directory (not directly into Python's site-packages).
tar xzf puzzler-snapshot.tgz
(The archive file name may not be exactly as shown above.)
The extracted folder contains distutils setup files setup.py and install.py. Just double-click install.py and you're done.
If you have any trouble, try the following steps:
Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're calling it these days).
Go to the directory created by expanding the archive:
cd <archive_directory_path>
Install the package:
<path_to_python.exe>\python setup.py install
Note that Psyco does not seem to accelerate the X2 algorithm, only the DLX algorithm.
If your computer has an Intel/AMD 386-compatible processor (under any OS), you can use Psyco to accelerate processing by 1.5 to 3 times. Support is already built into Polyform Puzzler (a few trivial lines in puzzler/exact_cover_dlx.py), so just install Psyco to enjoy the speed boost!
After unpacking and installing the Polyform Puzzler package, the applications in the bin directory can be used to solve puzzles.
All of the puzzle applications support several command-line options. Use the "-h" or "--help" option to see a complete list.
For example, type the following commands (in a shell) to solve the 3x20 pentominoes puzzle:
cd <archive_directory_path> bin/pentominoes-3x20.py
For example, type the following commands (in a command prompt window) to solve the 3x20 pentominoes puzzle:
cd <archive_directory_path> python bin\pentominoes-3x20.py
If you just double-click on the puzzle application, it will run, but the output window will disappear as soon as the puzzle finishes.
You may want to redirect the output to a file, since the Windows command prompt limits the number of output lines it remembers. Do this:
python bin\pentominoes-3x20.py > output.txt
(Choose any name you like for your output file.)
Alternatively, right-click on the puzzle application file, choose "Edit with IDLE", then choose "Run script" from the "Edit" menu (or hit Ctrl+F5).
To solve a 9x9 Sudoku puzzle, use the bin/sudoku.py front end command as described the Usage section above. You must supply a Sudoku starting position, either by providing (on the command line) the name of the file containing the position, or by typing in the starting position at the prompt. Examples:
Supply the name of a file containing the starting position:
bin/sudoku.py start.txt
Supply the starting position at the prompt:
bin/sudoku.py Enter a 9x9 Sudoku starting position: either 9 lines of 9 columns or 1 big line, "." or "0" for empty squares, spaces optional. Ctrl-D (on Linux/Mac), Ctrl-Z + Enter (on Windows) to end: ... enter starting position here ...
Starting positions must use periods (".") or zeros ("0") to represent empty squares, and must be in one of the following formats:
9 lines of 9 columns, with or without spaces between digits:
4 . . . . . 8 . 5 . 3 . . . . . . . . . . 7 . . . . . . 2 . . . . . 6 . . . . . 8 . 4 . . . . . . 1 . . . . . . . 6 . 3 . 7 . 5 . . 2 . . . . . 1 . 4 . . . . . . 4.....8.5 .3....... ...7..... .2.....6. ....8.4.. ....1.... ...6.3.7. 5..2..... 1.4......
Blank lines and spaces may be used to separate blocks:
4.. ... 8.5 .3. ... ... ... 7.. ... .2. ... .6. ... .8. 4.. ... .1. ... ... 6.3 .7. 5.. 2.. ... 1.4 ... ...
Dividing-line characters may be used to clarify the diagram ("- | +" are simply ignored):
4 . . | . . . | 8 . 5 . 3 . | . . . | . . . . . . | 7 . . | . . . ------+-------+------ . 2 . | . . . | . 6 . . . . | . 8 . | 4 . . . . . | . 1 . | . . . ------+-------+------ . . . | 6 . 3 | . 7 . 5 . . | 2 . . | . . . 1 . 4 | . . . | . . .
All on one line, with or without spaces between digits:
4.....8.5.3..........7......2.....6.....8.4......1.......6.3.7.5..2.....1.4...... 4.....8.5 .3....... ...7..... .2.....6. ....8.4.. ....1.... ...6.3.7. 5..2..... 1.4......
If you have questions or need assistance with Polyform Puzzler, please post a message to the Puzzler-Users mailing list (puzzler-users@lists.sourceforge.net). Please subscribe if possible; messages from non-subscribers will be held for approval.
Bug reports, patches, and other contributions are welcome!