Developer Guide

This document covers setup and development workflows for contributing to happy-simulator.

Prerequisites

• Python 3.13 or higher
• Git

Installation

Using pip (standard)

# Clone the repository
git clone https://github.com/adamfilli/happy-simulator.git
cd happy-simulator

# Create and activate virtual environment
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# Windows Command Prompt
.\.venv\Scripts\activate.bat

# Linux/macOS
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Using uv (faster alternative)

uv is a fast Python package installer written in Rust.

# Install uv (if not already installed)
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/adamfilli/happy-simulator.git
cd happy-simulator

# Create venv and install (uv handles both)
uv venv --python 3.13
uv pip install -e ".[dev]"

Development Commands

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/unit/test_event.py

# Run a specific test directory
pytest tests/integration/

# Run with coverage
pytest --cov=happysimulator --cov-report=html

Code Quality

# Type checking
mypy happysimulator

# Linting and formatting check
ruff check .

# Auto-fix linting issues
ruff check --fix .

# Format code
ruff format .

Running Examples

Examples are organized into subdirectories by domain:

python -m examples.queuing.m_m_1_queue
python -m examples.distributed.chain_replication
python -m examples.industrial.bank_branch

Documentation

# Local preview at localhost:8000
python -m mkdocs serve

# Build docs to site/
python -m mkdocs build

Visual Debugger

Requires optional dependencies:

pip install -e ".[visual]"
python -m examples.visual.visual_debugger

Frontend Build Pipeline

The visual debugger has a two-directory architecture:

• visual-frontend/ — React + TypeScript source code (Vite project). This is where you edit components, write TSX, and install npm dependencies. Not shipped in the Python package.
• happysimulator/visual/ — Python server (FastAPI + WebSocket). The static/ subdirectory holds the built output from npm run build — the minified JS/CSS/HTML that the server serves to the browser.

visual-frontend/src/*.tsx  →  npm run build  →  happysimulator/visual/static/  →  served by FastAPI

After editing frontend code, rebuild and restart:

cd visual-frontend && npm run build    # compiles TSX → static/
python -m examples.visual.visual_debugger  # restart server

If the browser shows stale UI, do a clean rebuild:

rm -rf happysimulator/visual/static/*      # delete old build output
rm visual-frontend/tsconfig.tsbuildinfo    # delete TS incremental cache
cd visual-frontend && npm run build        # rebuild from scratch

Then hard-refresh the browser with Ctrl+Shift+R.

Debugging

Set the logging level via environment variable:

# Bash
HS_LOGGING=DEBUG python -m examples.queuing.m_m_1_queue

# PowerShell
$env:HS_LOGGING='DEBUG'
python -m examples.queuing.m_m_1_queue

Project Structure

happy-simulator/
├── happysimulator/              # Main package
│   ├── __init__.py              # Package exports and version
│   ├── core/                    # Simulation engine (event, entity, instant, sim_future)
│   │   └── control/             # Pause/step/breakpoints
│   ├── components/              # Reusable simulation building blocks
│   │   ├── behavior/            # Agent-based behavioral modeling
│   │   ├── client/              # Client entities
│   │   ├── consensus/           # Consensus protocols (Raft, Paxos)
│   │   ├── crdt/                # Conflict-free replicated data types
│   │   ├── datastore/           # Storage engine components
│   │   ├── deployment/          # Deployment strategies (canary, rolling)
│   │   ├── industrial/          # Manufacturing/service industry components
│   │   ├── infrastructure/      # CPU, disk, scheduling primitives
│   │   ├── load_balancer/       # Load balancing strategies
│   │   ├── messaging/           # Message queues and pub/sub
│   │   ├── microservice/        # Microservice patterns
│   │   ├── network/             # Network topology and partitions
│   │   ├── queue_policies/      # FIFO, priority, etc.
│   │   ├── rate_limiter/        # Rate limiting (token bucket, etc.)
│   │   ├── replication/         # Replication protocols
│   │   ├── resilience/          # Circuit breakers, retries, bulkheads
│   │   ├── scheduling/          # Job/task scheduling
│   │   ├── server/              # Server entities
│   │   ├── sketching/           # Probabilistic data structures
│   │   ├── storage/             # B-tree, LSM tree, WAL
│   │   ├── streaming/           # Stream processing
│   │   └── sync/                # Synchronization primitives
│   ├── analysis/                # Post-run analysis utilities
│   ├── distributions/           # Statistical distributions
│   ├── faults/                  # Fault injection
│   ├── instrumentation/         # Probes, trackers, data collection
│   ├── load/                    # Load generation (sources, profiles)
│   ├── numerics/                # Numerical utilities
│   ├── sketching/               # Core sketching algorithms
│   ├── visual/                  # Browser-based debugger (FastAPI + React)
│   └── utils/                   # Shared utilities
├── visual-frontend/             # React + TypeScript source for visual debugger
├── examples/                    # Example simulations (organized by domain)
│   ├── behavior/                # Agent-based modeling examples
│   ├── deployment/              # Deployment simulation examples
│   ├── distributed/             # Distributed systems examples
│   ├── industrial/              # Manufacturing/service examples
│   ├── infrastructure/          # Infrastructure simulation examples
│   ├── load-balancing/          # Load balancing examples
│   ├── performance/             # Performance analysis examples
│   ├── queuing/                 # Queuing theory examples
│   ├── storage/                 # Storage engine examples
│   └── visual/                  # Visual debugger example
├── tests/                       # Test suite
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   ├── regression/              # Regression tests
│   └── perf/                    # Performance tests
├── docs/                        # MkDocs Material documentation site
│   ├── guides/                  # User guides
│   ├── reference/               # Auto-generated API reference
│   ├── examples/                # Example gallery
│   └── design/                  # Design philosophy
├── .github/workflows/           # CI/CD
│   ├── tests.yml                # Daily test runs
│   ├── docs.yml                 # Docs deployment to GitHub Pages
│   └── publish-pypi.yml         # PyPI publish on GitHub release
├── pyproject.toml               # Package configuration
├── CLAUDE.md                    # AI assistant instructions
└── DEV.md                       # This file

CI/CD

Tests

Tests run daily via GitHub Actions and can be triggered manually. See .github/workflows/tests.yml.

Documentation

Docs are auto-deployed to GitHub Pages on push to main. See .github/workflows/docs.yml.

PyPI Publishing

Publishing is automated via GitHub Actions using trusted publishing (no API tokens needed):

1. Create a GitHub release (or use the /release workflow)
2. The publish-pypi.yml workflow builds and publishes to PyPI automatically

Manual publishing with twine is no longer needed for normal releases.

Version Management

The package version is defined in two places (keep them in sync):

• pyproject.toml: version = "..." (used by PyPI)
• happysimulator/__init__.py: __version__ = "..." (used at runtime)

Building Distribution Packages

# Install build tool
pip install build

# Build wheel and sdist
python -m build

# Output will be in dist/