Logic Lab

Python translations of creative coding examples using py5. Each simulation is organized by domain, demonstrating core computational creativity concepts: physics, steering behaviors, genetic algorithms, neural networks, fractals, cellular automata, tiling patterns, and mathematical systems.

Setup

Install dependencies:

uv sync

Related MCP server: Processing MCP Server

MCP Server

Logic Lab includes a local read-only MCP server for AI agents. Clone this repository locally, install dependencies with uv sync, then register the server for use across your workspace.

With the MCP server, agents can search the Logic Lab manifest, find algorithms by visual intent or category, read short summaries, and fetch bounded source snippets for selected examples.

Manual installation

Requires uv.

git clone https://github.com/asamiile/logic-lab.git
cd logic-lab
uv sync

Registration

After installation, register the server with your AI tool using the logic-lab-mcp command:

Claude Code:

claude mcp add logic-lab -- logic-lab-mcp

Codex:

codex mcp add logic-lab -- logic-lab-mcp

GitHub Copilot in VS Code (.vscode/mcp.json or user MCP settings):

{
  "servers": {
    "logic-lab": {
      "type": "stdio",
      "command": "logic-lab-mcp"
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "logic-lab": {
      "type": "stdio",
      "command": "logic-lab-mcp"
    }
  }
}

See src/logic_lab/mcp/README.md for tools, security notes, and usage details.

Repository Structure

logic-lab/
├── src/logic_lab/                 # Package root
│   ├── __init__.py
│   ├── mcp/                       # MCP server for AI agent access
│   ├── physics/                   # Motion, forces, particles, simulations
│   ├── steering_behaviors/        # Autonomous agents, flow fields, flocking
│   ├── genetic_algorithms/        # Selection, mutation, evolutionary search
│   ├── neuro_evolution/           # Neural networks evolved via genetics
│   ├── fractals/                  # Recursion, trees, Koch curves, L-systems
│   ├── cellular_automata/         # Rule-based grids, lattice systems
│   ├── mathematical/              # Noise, curves, geometry, harmony
│   ├── tiling_patterns/           # Symmetry, tessellation, ornaments
│   ├── research/                  # Experimental and hybrid systems
│   ├── simulation/                # Prototypes and reference implementations
│   ├── shared/                    # Reusable utilities and helpers
│   └── shader/                    # GLSL shader experiments
├── tests/                         # Pytest test suite
├── CONTRIBUTING.md                # Contributor guidelines and conventions
├── CHANGELOG.md                   # Version history and release notes
├── pyproject.toml                 # Package configuration and dependencies
└── .github/workflows/
    ├── test.yml                   # CI: lint and test automation
    └── release.yml                # CD: automated releases with release-please

Algorithm Domains

mathematical/ - Generative geometry, color harmony, noise functions, fractals
physics/ - Particle systems, forces, spring physics, fluid dynamics, collision
steering_behaviors/ - Autonomous agents, flocking, pathfinding, flow fields
genetic_algorithms/ - Evolution, selection, crossover, mutation
neuro_evolution/ - Neural networks evolved via genetic algorithms
fractals/ - Recursive structures, space-filling curves, Mandelbrot sets
cellular_automata/ - Rule-based systems, Game of Life, emergence
tiling_patterns/ - Symmetry, tessellations, ornamental patterns
research/ - Experimental systems combining multiple domains
simulation/ - Prototype implementations and archived experiments
shader/ - GLSL fragment shaders for TouchDesigner and UE5

Development

To contribute new algorithms or fixes, see CONTRIBUTING.md for detailed guidelines on:

Development setup with uv
Algorithm addition workflow
py5 code patterns and templates
Testing requirements
Conventional Commits specification
Automated release process

Running Tests

# Install dev dependencies
uv sync --group dev

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=src/logic_lab

Code Quality

# Lint with ruff
uv run ruff check src/ tests/

# Format with black
uv run black src/ tests/

# Lint and fix
uv run ruff check --fix src/ tests/

Reference

License

License: MIT

Author

Asami.K

If you find this helpful, consider supporting the work:

logic-lab