Developer Guide

This guide covers everything needed to contribute to the Heterodyne package: environment setup, testing, code standards, and architecture.

Quick Reference

make dev           # Install in development mode (uv sync)
make test          # Run unit tests
make test-all      # Run the full test suite (unit + integration + slow)
make quality        # Lint (Ruff) + type-check (MyPy)
make docs          # Build Sphinx documentation

Tool Chain

Tool	Command	Purpose
uv	uv sync	Package manager and lockfile management.
Ruff	uv run ruff check .	Linting and import sorting.
MyPy	uv run mypy .	Static type checking with strict hints at API boundaries.
pytest	uv run pytest	Test runner with marker-based selection.
Sphinx	make docs	Documentation build (Furo theme, MyST for Markdown).

Sections

• Contributing Guide
  • Development Setup
  • Branch Naming
  • Commit Conventions
  • Code Style
  • Pull Request Checklist
  • Code Review
• Testing Guide
  • Test Structure
  • Test Markers
  • Running Tests
  • Coverage
  • JAX-Specific Testing Considerations
  • Writing New Tests
• Architecture Overview
  • Package Layout
  • Two-Path Integral Architecture
  • Design Patterns
  • Data Flow
• Parameter Bounds Verification
  • Invariants
  • Key Parameter Defaults
  • Dual Prior System
  • Common Pitfalls
• Architecture Decision Records
  • ADR-001: JAX CPU-Only Backend
  • ADR-002: NLSQ / CMC Architectural Split
  • ADR-003: Anti-Degeneracy Layer for Velocity-Phase Model
  • ADR-004: Consensus Monte Carlo for Bayesian Inference
  • ADR-005: Per-Angle Scaling Modes
  • ADR-006: No GPU Acceleration on Consumer Hardware