Setup Guide

This document explains how to obtain, install, and use Puzzle Solvers.

Getting the Package

PyPI

Puzzle Solvers is available on pypi, so the recommended way to install it is

pip install puzzle-solvers

matplotlib is an optional dependency, which can be installed using the mpl extra:

pip install puzzle-solvers[mpl]

Source

You can obtain a copy of the Puzzle Solvers source code from GitLab at https://gitlab.com/madphysicist/puzzle-solvers. The simplest way to keep up with changes is to clone the repo:

git clone git@gitlab.com:madphysicist/puzzle-solvers.git

Puzzle Solvers uses setuptools, so you can install it from source as well. Once you have a copy of the source distribution, run

python setup.py install

from the project root directory, with the appropriate privileges.

You can do the same thing with pip if you prefer. Any of the following should work, depending on how you obtained your distribution

pip install git+<URL>/puzzle-solvers.git@master[mpl]  # For a remote git repository
pip install puzzle-solvers.zip[mpl]                   # For an archived file
pip install puzzle-solvers[mpl]                       # For an unpacked folder or repo

Usage

Puzzle Solvers is intended primarily as a library. Once it is properly installed, it can be imported as any normal python library:

import puzzle_solvers

The individual modules provide tools for specific puzzle types.

Demos

Each module in puzzle_solvers comes with a corresponding demo in puzzle_solvers.demos. Each demo is a standalone script that is intended to be run as a packaged module. For example:

python -m puzzle_solvers.demos.elimination

Tests

Puzzle Solvers does not currently have any formal unit tests available. However, running through all of the demos and tutorials serves as a non-automated set of tests, since they exercise nearly every aspect of the solvers. Eventually, pytest-compatible tests will be added in the tests package.

Documentation

Online

The documentation is available online at https://puzzle-solvers/readthedocs.io.

Building

If you intend to build the documentation, you must have Sphinx installed, and optionally the ReadTheDocs Theme extension for optimal viewing.

The documentation can be built from the complete source distribution by using the specially defined command:

python setup.py build_sphinx

Alternatively (perhaps preferably), it can be built using the provided Makefile/Batch script:

cd doc
make html

Both options work on Windows and Unix-like systems that have make installed. The Windows version does not require make. On Linux you can also do

make -C doc html

The documentation is not present in the PyPI source distributions, only directly from GitLab.