How ggattoni/polyamonds-puzzle-solver works
Project Type and Purpose
• This project is a puzzle solver specifically designed to automatically solve polyamonds puzzles. These puzzles involve filling a grid of equilateral triangular cells with puzzle pieces that are also built from equilateral triangles.
• Key functionalities include reading puzzle definitions (found in the puzzles folder), managing the grid and pieces (via modules such as grid.py, piece.py, point.py, and triangle.py), and providing two solver algorithms: a brute-force approach and a CP-SAT (constraint programming) solver.
• The CLI is built so that the user can run commands like “pps solve <puzzle_name>” and select the solver algorithm if desired.
Analyzing the File Structure
• Top-level directories and files such as .gitignore, pre-commit configuration, requirements files, and a pyproject.toml indicate a structured Python project with quality controls and dependency management.
• The main code is under the “src” directory in the “polyamonds_puzzle_solver” module. This module is further broken into:
• Core functionality: grid.py, piece.py, point.py, triangle.py, and plot.py (for visual representation).
• Puzzle definitions contained in “puzzles” (with multiple implementations like daniel.py, luciano.py, nicola.py, and xtechai.py).
• Solver implementations under “solvers” (brute_force.py and cpsat.py).
• This organization suggests a modular design where each responsibility – puzzle definitions, puzzle-solving algorithms, grid representation, and plotting – is separated.
Key Points From the README
• The README clearly explains the goal: to solve a physical puzzle quickly via two available solving algorithms, emphasizing the performance difference between the CP-SAT solver and the brute-force method.
• It lists dependencies (Python, Ruff, and uv) and gives CLI usage instructions, which indicates the system design needs to show a command-line interface component.
• It also provides a bit of background and roadmap, highlighting planned improvements (like external configuration in JSON and enhanced user interfaces).
a. Main Components:
• CLI Interface: The entry point handling “pps solve” commands.
• Puzzle Loader: A component that uses the puzzle definitions found under the puzzles folder.
• Grid & Piece Manager: Core modules such as grid.py, piece.py, point.py, and triangle.py that manage game state and structure.
• Solver Module: Contains two sub-components – brute force solver and CP-SAT solver – which determine how the puzzle is solved.
• Plot/Visualizer: The plot.py module is responsible for rendering the solution (and possibly intermediate states) graphically.
• Configuration/Utilities: Including dependency management (pyproject.toml, uv.lock) and any pre-commit or linting tools.
b. Relationships and Interactions:
• The CLI component accepts user commands and parameters (such as the puzzle name and selected solving method).
• It then invokes the Puzzle Loader to retrieve the specific puzzle’s configuration from the puzzles directory.
• The Grid & Piece Manager sets up the grid and pieces based on this configuration.
• The Solver Module is selected (either CP-SAT or brute force) and interacts with the grid/piece classes to compute a solution.
• Once a solution is produced, it is passed to the Plot/Visualizer to render the solved puzzle.
• Additional configuration and logging might occur via the provided utilities and dependency scripts.
c. Architectural Patterns and Design Principles:
• Modularity: Clear separation of concerns with distinct modules for puzzles, solving algorithms, grid management, and plotting.
• Extensibility: The “puzzles” and “solvers” directories allow for plugging in additional puzzles or new solving strategies.
• Command-Line Driven: The CLI makes use of user commands to toggle between solver implementations, suggesting a design for flexibility and ease-of-use.
d. Relevant Technologies, Frameworks, or Libraries:
• Python is the language, and the project utilizes package management (pyproject.toml, requirements.txt) indicating a well-managed dependency structure.
• CP-SAT (likely powered by an external CP-SAT library for constraint programming) is a key technology.
• The plotting module might use Python’s plotting libraries (even if custom), and uv is mentioned for installation synchronization.
• Ruff is used for linting, suggesting an emphasis on code quality.