LifeGrid

A feature-rich cellular automata simulator with a modern Tkinter GUI, headless CLI, REST/WebSocket API, GPU acceleration, and plugin support.

Features

Automata Modes

GUI

• Drawing tools — pencil, eraser, stamp, and selection with configurable brush size and shape (square / circle / diamond)
• Simulation controls — start, stop, step, reset, speed slider, undo/redo (up to 100 states)
• Pattern library — built-in patterns per mode with a pattern browser and RLE import/export
• Themes — light and dark themes plus a visual theme editor with custom presets
• Generation timeline — scrub backward and forward through simulation history
• Population graph — real-time population-over-time chart in the sidebar
• Breakpoint system — pause the simulation when population, generation, or density conditions are met
• Rule explorer — browse 10 named rulesets (Seeds, Day & Night, Diamoeba, etc.) and apply them instantly
• Command palette — Ctrl+Shift+P quick-access to every action
• Pattern shape search — draw a shape and find matching patterns by similarity
• Grid overlays — symmetry guides, cell age heatmaps, activity heatmaps
• Export — PNG snapshots, animated GIF, MP4/WebM video, JSON state, CSV statistics

CLI

Run simulations headlessly for scripting and batch processing:

python src/cli.py --mode conway --steps 500 --export output/result.gif --fps 15

Supports --mode, --rule (custom B/S), --width, --height, --cell-size, --export (png/gif/mp4/webm/csv/json), --fps, --snapshot-every, and --quiet.

REST & WebSocket API

Start the API server:

uvicorn src.api.app:app --reload

GPU Acceleration

Optional CUDA-based acceleration via CuPy. Falls back to NumPy automatically when no GPU is available.

pip install cupy-cuda12x   # match your CUDA version

Plugin System

Drop a .py file into the plugins/ directory to add a new automaton mode. See docs/plugin_development.md for details.

Included plugin: Day & Night (B3678/S34678).

Installation

Requirements

• Python 3.11 or later
• Tcl/Tk (included with most Python distributions)

Quick Start

git clone https://github.com/James-HoneyBadger/LifeGrid.git
cd LifeGrid
pip install -r requirements.txt
python src/main.py

Development Install

make install-dev

This installs LifeGrid in editable mode with all optional dependencies (docs, export, dev tools).

Build a Standalone Executable

make executable

Uses PyInstaller with the included lifegrid.spec.

Usage

GUI

python src/main.py
# or
make run

Keyboard Shortcuts

CLI

# Run Conway for 1000 steps, export animated GIF
python src/cli.py --mode conway --steps 1000 --export sim.gif

# Run HighLife with a 200x200 grid, export MP4 at 30 fps
python src/cli.py --mode highlife -W 200 -H 200 --steps 500 --export video.mp4 --fps 30

# Custom B/S rule, export CSV statistics
python src/cli.py --rule B36/S23 --steps 2000 --export stats.csv

# Run WireWorld for 1000 steps, capturing every 100th frame as an animated GIF
python src/cli.py --mode wireworld --steps 1000 --snapshot-every 100 --export sim.gif

API

# Start the server
uvicorn src.api.app:app --host 0.0.0.0 --port 8000

# Create a session
curl -X POST http://localhost:8000/session \
  -H "Content-Type: application/json" \
  -d '{"width": 64, "height": 64, "mode": "conway"}'

# Step the simulation
curl -X POST http://localhost:8000/session/<id>/step \
  -H "Content-Type: application/json" \
  -d '{"steps": 10}'

Project Structure

LifeGrid/
├── src/
│   ├── main.py              # GUI entry point
│   ├── cli.py               # Headless CLI
│   ├── patterns.py           # Pattern definitions
│   ├── plugin_system.py      # Plugin loader
│   ├── export_manager.py     # PNG/GIF/MP4/WebM/JSON export
│   ├── config_manager.py     # Persistent app settings
│   ├── ui_enhancements.py    # Theme manager
│   ├── automata/             # All automaton implementations
│   ├── core/                 # Simulator, config, undo, boundary modes
│   ├── gui/                  # GUI app, rendering, tools, new features
│   ├── api/                  # FastAPI REST + WebSocket + collaboration
│   ├── advanced/             # Statistics, pattern analysis, RLE, heatmaps
│   └── performance/          # GPU acceleration, benchmarking
├── plugins/                  # User-installable automaton plugins
├── tests/                    # Test suite (71 tests)
├── examples/                 # Example scripts
├── output/                   # Default export directory
└── docs/                     # Documentation

Testing

# Run the full test suite
make test

# Run with coverage report
make coverage

71 tests covering the simulator, all automata modes, boundary conditions, GPU module, CLI, REST API, collaborative sessions, breakpoints, pattern system, statistics, and more.

Documentation

Full documentation is in the docs/ directory:

• Installation
• User Guide
• CLI Reference
• API Reference
• Architecture
• Plugin Development

License

MIT — see LICENSE for details.

Author

Honey Badger Universe