=============================== README |---| Polyform Puzzler =============================== :Author: David Goodger :Date: $Date: 2009-01-19 07:46:29 -0500 (Mon, 19 Jan 2009) $ :Web site: http://puzzler.sourceforge.net/ :Copyright: |c| 1998-2009 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:: Quick-Start =========== This section is for those who want to get up & running quickly. Read on for complete details. 1. Get and install the latest release of Python, available from http://www.python.org/ Python 2.4 or later; Python 2.4.2 or later is recommended. 2. Use the latest Polyform Puzzler code. Get the code from Subversion or from the snapshot: http://puzzler.sourceforge.net/puzzler-snapshot.tgz See Snapshots_ below for details. 3. In a shell, unpack the snapshot tarball in a temporary directory (**not** directly in Python's ``site-packages``) and move into it. For example:: tar xzf puzzler-snapshot.tgz cd puzzler There are two ways to proceed from here: `install it`_, or `just run it`_: Install It ---------- This option installs the Polyform Puzzler library into Python's system-wide standard library. 4. 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. 5. 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. Just Run It ----------- This option allows you to use the "puzzler" package without installing it permanently. 4. In the top-level directory (containing the "puzzler", "docs", and "bin" directories), run the front-end:: bin/pentominoes6x10.py (Unix/Mac) python bin\pentominoes6x10.py (Windows) Because Python searches the current working directory for modules & packages, it will find the "puzzler" package directory. See Usage_ below for details. (For Windows users:) If the the Python executable is not on your ``PATH``, you will have to specify its location:: C:\Python24\python bin\pentominoes6x10.py Note that you will only be able to use the "puzzler" package from that one location (not from arbitrary locations on your system), unless you `install it`_, or you set your ``PYTHONPATH`` environment variable. Snapshots ========= 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 .. _Subversion repository: https://sourceforge.net/svn/?group_id=7049 Project Files & Directories =========================== * README.txt: You're reading it. * COPYING.txt: Copyright and license details. * GPL2.txt: The GNU General Public License, version 2. * setup.py: Installation script. See "Installation" below. * install.py: Quick & dirty installation script. Just run it. For any kind of customization or help though, setup.py must be used. * puzzler: The project source directory, installed as a Python package. * bin: Polyform puzzler front-end applications directory. * docs: The project documentation directory. All project documentation is in reStructuredText_ format, and can be converted to HTML and other formats using Docutils_. - FAQ.txt: Frequently Asked Questions (with answers!). - puzzles.txt: List of puzzles implemented and counts of solutions - extend.txt: How to extend Polyform Puzzler - history.txt: Detailed log of changes. - todo.txt: To do list. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net Installation ============ 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 `_. GNU/Linux, BSDs, Unix, Mac OS X, etc. ------------------------------------- 1. Open a shell (terminal). 2. 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.) 3. Go to the directory created by expanding the archive:: cd It contains a distutils setup file "setup.py". 4. 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. Windows ------- 1. 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.) 2. 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: 3. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're calling it these days). 4. Go to the directory created by expanding the archive:: cd 5. Install the package:: \python setup.py install Optional Acceleration With Psyco -------------------------------- 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.py``), so just install Psyco_ to enjoy the speed boost! Usage ===== 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. GNU/Linux, BSDs, Unix, Mac OS X, etc. ------------------------------------- For example, type the following commands (in a shell) to solve the 3x20 pentominoes puzzle:: cd bin/pentominoes-3x20.py Windows ------- For example, type the following commands (in a command prompt window) to solve the 3x20 pentominoes puzzle:: cd python bin\pentominoes-3x20.py Alternatively, right-click on the puzzle application file, choose "Edit with IDLE", then choose "Run script" from the "Edit" menu (or hit Ctrl+F5). (If you just double-click on the puzzle application, it will run, but the output window will disappear as soon as the puzzle finishes.) Sudoku ====== 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. Use periods (".") to represent empty squares in starting positions. 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 start.txt Enter a 9x9 Sudoku starting position: either 9 lines of 9 columns or 1 big line, "." for empty squares, spaces optional. Ctrl-D (on Linux/Mac), Ctrl-Z + Enter (on Windows) to end: ... enter starting position here ... Starting positions 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 may be used to separate blocks:: 4.. ... 8.5 .3. ... ... ... 7.. ... .2. ... .6. ... .8. 4.. ... .1. ... ... 6.3 .7. 5.. 2.. ... 1.4 ... ... The following format may also be used (the dividing-line characters "- | +" 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...... Getting Help ============ 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! .. _subscribe: https://lists.sourceforge.net/lists/listinfo/puzzler-users .. _Bug reports: http://sourceforge.net/tracker/?group_id=7049&atid=107049 .. _patches: http://sourceforge.net/tracker/?group_id=7049&atid=307049 .. |---| unicode:: U+2014 .. em dash :trim: .. |c| unicode:: U+00A9 .. copyright sign .. |x| unicode:: U+00D7 .. multiplication sign :trim: .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: