pond-planner

Pond Planner 🐟

Build and Publish Docker Image

A comprehensive pond planning application that helps you calculate optimal pond dimensions, fish stocking levels, and equipment requirements for your backyard pond project.

Features

Supported Pond Shapes

Geometric Shapes

Organic Shapes

Complex Shapes

Installation

The easiest way to run Pond Planner is using Docker:

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/parttimelegend/pond-planner:latest

# Run the application interactively
docker run -it ghcr.io/parttimelegend/pond-planner:latest

# Or run with docker-compose
git clone https://github.com/parttimelegend/pond-planner.git
cd pond-planner
docker-compose up pond-planner

Option 2: Local Installation

  1. Clone the repository:

    git clone https://github.com/parttimelegend/pond-planner.git
cd pond-planner

  2. Create a virtual environment:

    python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies:

    pip install -r requirements.txt

  4. Verify installation:

    python verify_setup.py

    This script will check that all dependencies are installed and the application is working correctly.

Quick Start

Docker Usage

# Interactive mode
docker run -it ghcr.io/parttimelegend/pond-planner:latest

# With persistent storage for saved ponds
docker run -it -v $(pwd)/data:/app/data ghcr.io/parttimelegend/pond-planner:latest

# With docker-compose for development (includes persistent storage)
docker-compose up pond-planner-dev

# Build locally
docker build -t pond-planner .
docker run -it pond-planner

Note: The docker-compose configuration automatically handles persistent storage for saved pond configurations.

Command Line Interface

Run the interactive pond planner:

python main.py

The application provides a user-friendly menu interface with options to:

  1. Create new pond plan - Design a new pond with custom dimensions and fish selection
  2. Load saved pond plan - Restore a previously saved pond configuration
  3. List saved pond plans - View all saved pond designs with metadata
  4. Delete saved pond plan - Remove unwanted saved configurations
  5. Exit - Close the application

Interactive Features

The application will guide you through:

  1. Setting pond dimensions and shape
  2. Selecting fish types and quantities from 267 species
  3. Saving your pond configuration with a custom name and description
  4. Loading and modifying existing pond designs
  5. Generating comprehensive planning reports

Programmatic Usage

from PondPlanner import PondPlanner

# Create a pond planner instance
planner = PondPlanner()

# Set pond dimensions (length, width, depth in meters, shape)
planner.set_dimensions(5.0, 3.0, 1.5, "rectangular")

# Add fish to the pond
planner.add_fish("goldfish", 10)
planner.add_fish("koi", 3)

# Or add multiple fish types at once (atomic operation)
fish_batch = {"goldfish": 10, "koi": 3, "shubunkin": 5}
planner.add_fish_batch(fish_batch)

# Save pond configuration with description
filename = planner.save_pond("My Garden Pond", "Beautiful koi pond for the backyard")
print(f"Saved as: {filename}")

# List all saved ponds
saved_ponds = planner.list_saved_ponds()
for pond in saved_ponds:
    print(f"- {pond['name']}: {pond['shape']} pond with {pond['fish_count']} fish")

# Load a saved pond configuration
planner_2 = PondPlanner()
planner_2.load_pond("My Garden Pond")
print(f"Loaded pond volume: {planner_2.calculate_volume_liters():,.0f} liters")
print(f"Fish stock: {planner_2.get_fish_stock()}")

# Calculate pond volume
volume = planner.calculate_volume_liters()
print(f"Pond volume: {volume:,.0f} liters")

# Check if pond is adequately sized
required_volume = planner.calculate_required_volume()
bioload = planner.calculate_bioload()

# Get equipment recommendations
pump_lph, pump_category = planner.calculate_pump_size()
filter_specs = planner.calculate_filter_size()

# Get stocking recommendations
recommendations = planner.get_stocking_recommendations()

# Generate comprehensive report
report = planner.generate_report()
print(report)

Architecture

The application follows SOLID principles and clean architecture patterns:

Core Components

Services

Repositories

Key Features

Configuration

Data Persistence

Pond configurations are automatically saved to the data/saved_ponds/ directory as JSON files. Each saved pond includes:

The persistence system is designed to be:

Fish Database

The application includes a comprehensive database of 267 fish species covering:

Each fish species includes detailed information:

Adding New Fish Species

Edit fish_database.yaml:

fish_species:
  your_fish_key:
    name: "Your Fish Name"
    adult_length_cm: 25
    bioload_factor: 1.2
    min_liters_per_fish: 150

Adding New Pond Shapes

Edit pond_shapes.yaml:

pond_shapes:
  your_shape:
    name: "Your Shape"
    description: "Description of your shape"
    formula_type: "simple" # or circular, elliptical, etc.
    area_formula: "length * width"
    multiplier: 1.0
    uses_length: true
    uses_width: true

Sample Output

POND PLANNING REPORT
====================

Pond Specifications:
- Dimensions: 5.0m x 3.0m x 1.5m
- Shape: Rectangular
- Total Volume: 22,500 liters

Current Fish Stock:
- Goldfish: 10 fish
- Koi: 3 fish

Stocking Analysis:
- Required Volume: 3,600 liters
- Available Volume: 22,500 liters
- Status: ✓ Adequate
- Total Bioload: 17.5

Equipment Recommendations:
- Pump Size: 12,375 LPH (Medium bioload)
- 2,475 liters filter media
- UV Sterilizer: 79 watts
- Mechanical Filter: Pre-filter with 50-100 micron capability

Maximum Stocking Recommendations:
- Goldfish: up to 300 fish
- Koi: up to 23 fish
- Shubunkin: up to 118 fish
...

API Reference

Main Classes

PondPlanner

The main facade class for pond planning operations.

Methods:

Properties:

Validation

All input validation provides detailed error messages:

try:
    planner.set_dimensions(-1, 5, 2, "rectangular")
except ValueError as e:
    print(e)  # "Invalid dimensions: Length must be at least 0.1 meters"

Testing

Run the test suite:

python -m pytest tests/

For coverage report:

python -m pytest --cov=. tests/

Troubleshooting

Common Issues

ModuleNotFoundError: No module named ‘yaml’

This occurs when PyYAML is not installed. Make sure you’ve followed the installation steps:

# Activate your virtual environment first
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Or install PyYAML directly
pip install PyYAML>=6.0

File permissions issues with saved ponds

Ensure the application has write permissions to create the data/ directory:

# Create the directory if it doesn't exist
mkdir -p data/saved_ponds

# Check permissions
ls -la data/

Docker container doesn’t persist saved ponds

Use volume mounting to persist data:

# Mount local data directory
docker run -it -v $(pwd)/data:/app/data ghcr.io/parttimelegend/pond-planner:latest

# Or use docker-compose (recommended)
docker-compose up pond-planner

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

Requirements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Support

For questions, issues, or feature requests, please open an issue on GitHub.

Docker Images

The application is available as Docker images with multiple tags:

Image Variants

CI/CD

The project uses GitHub Actions for:

This site is open source. Improve this page.