Architecture Deep Dives

Detailed internal architecture documentation for each major subsystem. These documents describe the design, data flow, and implementation details at a level useful for contributors, maintainers, and advanced users.

For a concise module-level overview, see System Architecture. For formal design rationale, see Architecture Decision Records.

• Homodyne Architecture Overview
  • Table of Contents
  • System Overview
  • 1. Package Structure
  • 2. Initialization & Environment
  • 3. CLI Layer
  • 4. Configuration System
  • 5. Data Loading Pipeline
  • 6. Physical Model Layer
  • 7. NLSQ Optimization
  • 8. CMC Bayesian Inference
  • 9. IO & Result Serialization
  • 10. Visualization
  • 11. Device & HPC Configuration
  • 12. Utilities
  • 13. Runtime & Deployment
  • 14. Fault Tolerance & Recovery
  • 15. Cross-Cutting Concerns
  • Complete End-to-End Flow
  • Module Size & Dependency Matrix
  • Architecture Decision Records
  • Companion Documents
• Homodyne Physical Model Architecture
  • Table of Contents
  • High-Level Architecture
  • 1. Mathematical Foundation
  • 2. Physical Constants & Validation
  • 3. Model Hierarchy
  • 4. Physics Factors Pre-Computation
  • 5. JIT-Compiled Computation Kernels
  • 6. Shadow-Copy Architecture
  • 7. Per-Angle Scaling System
  • 8. Numerical Stability Techniques
  • 9. Automatic Differentiation & Fallback
  • 10. HomodyneModel Unified Interface
  • 11. TheoryEngine High-Level API
  • 12. Fitting Infrastructure
  • Complete Computation Flow
  • Quick Reference Tables
  • Key Files Reference
• Homodyne NLSQ Fitting Architecture
  • Table of Contents
  • High-Level Architecture
  • 1. Setup Phase
  • 2. Global Optimization Selection
  • 3. CMA-ES Global Optimization
  • 4. Adapter Selection
  • 5. Memory & Strategy Selection
  • 6. Stratification Decision
  • 7. Residual Function Setup
  • 8. Anti-Degeneracy Defense System
  • 9. Strategy Execution
  • 10. Error Recovery
  • 11. Result Building
  • Quick Reference Tables
  • Key Files Reference
  • NLSQ as CMC Warm-Start Provider (v2.20.0)
• Homodyne CMC (Consensus Monte Carlo) Fitting Architecture
  • Table of Contents
  • High-Level Architecture
  • 1. Entry Point & Orchestration
  • 2. Data Preparation & Sharding
  • 3. Auto Shard Size Selection
  • 4. Time Grid Construction
  • 5. Physics Model
  • 6. Gradient Balancing (Z-Space)
  • 7. NUTS Sampling
  • 8. Backend Execution
  • 9. Sample Combination
  • 10. Result Creation & Diagnostics
  • Complete Data Flow
  • Quick Reference Tables
  • Key Files Reference
  • Critical Features & Fixes
• Homodyne Data Handler Architecture
  • Table of Contents
  • High-Level Architecture
  • 1. Configuration System
  • 2. Data Loading
  • 3. HDF5 Format Detection & Loading
  • 4. Data Filtering
  • 5. Preprocessing Pipeline
  • 6. Quality Control
  • 7. Caching & Performance
  • 8. Memory Management
  • 9. Result Writing (NLSQ)
  • 10. Result Writing (CMC)
  • 11. CLI Orchestration
  • Complete Data Flow
  • Quick Reference Tables
  • Key Files Reference

Homodyne Architecture Overview	System-level architecture: package layout, data flow, module dependencies, and cross-cutting concerns.
Homodyne Physical Model Architecture	Physics kernel: g1/g2 theory, JIT-compiled backends, model variants, and gradient-safe numerics.
Homodyne NLSQ Fitting Architecture	NLSQ optimization: trust-region LM, anti-degeneracy layers, CMA-ES, memory routing, and streaming.
Homodyne CMC (Consensus Monte Carlo) Fitting Architecture	Consensus Monte Carlo: sharding, multiprocessing workers, NUTS execution, and posterior combination.
Homodyne Data Handler Architecture	Data pipeline: HDF5 loading, configuration management, validation, and result serialization.