Developer Guide

This section is for contributors and developers who want to understand Homodyne’s internal design, run the test suite, or submit improvements.

Getting Started

• Contributing to Homodyne
  • Development Setup with uv
  • Code Quality Standards
  • Testing with Pytest
  • Pull Request Guidelines
  • Reference Material
• Testing Guide
  • Test Organization
  • Running Tests
  • Code Coverage
  • JAX Debugging
  • Continuous Integration
  • Troubleshooting Tests
  • Reference Commands

Design & Architecture

• System Architecture
  • Component Overview
  • Data Flow
  • Core Module Map
  • NLSQ Module Map
  • CMC Module Map
  • CLI Module Map
  • Visualization Module Map
  • Key Design Decisions
  • Module Dependency Map
• Architecture Decision Records
  • ADR-001: JAX CPU-Only Backend
  • ADR-002: NLSQ / CMC Architectural Split
  • ADR-003: Anti-Degeneracy Layer for Laminar Flow
  • ADR-004: Consensus Monte Carlo for Bayesian Inference
  • ADR-005: Per-Angle Scaling Modes
  • ADR-006: No GPU Acceleration on Consumer Hardware
• Parameter Bounds Codebase Verification
  • Verified Source Files
  • Verified Bounds (All Sources Consistent)
  • Registry Defaults and Priors
  • YAML Template Prior Overrides
  • NLSQ Bounds Flow
  • CMC Prior Construction
  • Physics Validators (Soft Constraints)
  • Mode Selection Logic
  • Documentation Corrections Applied (2026-03-03)

---

Quick Reference

Task	Command
Install with dev extras	make dev
Run unit tests	make test
Run full suite with coverage	make test-all
Format + lint + type-check	make quality
Build documentation	make docs

Code quality stack:

• Formatting: Black

• Linting: Ruff

• Type checking: MyPy (strict mode at API boundaries)

• Package manager: uv (uv.lock is the single source of truth)

---

Architecture Overview

homodyne/
├── core/           # Physics kernel — JIT-compiled JAX
│   ├── jax_backend.py       # Meshgrid-mode residuals (NLSQ)
│   ├── physics_cmc.py       # Element-wise residuals (CMC)
│   ├── physics_utils.py     # Shared: safe_exp, safe_sinc, etc.
│   ├── models.py            # OO model interface
│   ├── theory.py            # g1/g2 calculations
│   └── homodyne_model.py    # Unified model facade
├── optimization/
│   ├── nlsq/                # Trust-region LM (primary)
│   └── cmc/                 # Consensus Monte Carlo (secondary)
├── data/                    # HDF5 loading, validation
├── config/                  # YAML config management
├── cli/                     # Entry points, shell completion
└── device/                  # CPU/NUMA detection

Key design decisions:

• NLSQ uses jax_backend.py (meshgrid mode — all (t1, t2) pairs batched).

• CMC uses physics_cmc.py (element-wise mode — per-shard vectors).

• No shared mutable state across the two paths.

• physics_utils.py provides shared utilities (safe_exp, safe_sinc, calculate_diffusion_coefficient).

See System Architecture for module-level design decisions, Architecture Decision Records for Architecture Decision Records (ADRs), and Architecture Deep Dives for detailed subsystem architecture documentation.

---

Version information:

• Homodyne: 2.23.3.dev3

• Python: 3.12+

• JAX: 0.8.2+ (CPU-only)

• Package manager: uv