API Reference

This section provides the complete API reference for the Homodyne package. All documentation is auto-generated from docstrings in the source code using Sphinx autodoc. Module and class signatures reflect the installed package version.

Note

The recommended entry points for most users are homodyne.optimization.nlsq.core.fit_nlsq_jax() for non-linear least squares fitting and homodyne.optimization.cmc.core.fit_mcmc_jax() for Bayesian uncertainty quantification. Start with the homodyne.optimization.nlsq — Adapter page for the high-level adapter interface.

---

Module Overview

Module	Description
homodyne.core	Physical constants, parameter bounds, validation, and shared utilities
homodyne.core.homodyne_model	HomodyneModel — unified model facade for NLSQ and CMC
homodyne.core.jax_backend	JIT-compiled g₁/g₂ physics, autodiff, meshgrid cache
homodyne.core.models	DiffusionModel, ShearModel, CombinedModel — OO model interface
homodyne.core.theory	TheoryEngine — high-level g1/g2 computation interface
homodyne.optimization	Optimization overview: NLSQ vs CMC, common workflow patterns
homodyne.optimization.nlsq — Adapter	NLSQAdapter — recommended adapter for standard optimizations
homodyne.optimization.nlsq — Wrapper	NLSQWrapper — full-featured wrapper for advanced use cases
homodyne.optimization.cmc	CMC overview, fit_mcmc_jax(), CMCConfig, shard size guide
homodyne.optimization.cmc.sampler	SamplingPlan, NUTS execution, adaptive sampling
homodyne.optimization.cmc.reparameterization	Parameter reparameterization for MCMC sampling efficiency
homodyne.optimization.cmc.backends	Multiprocessing backend, worker configuration, chain execution methods
homodyne.data	XPCSDataLoader — HDF5 data ingestion and validation
homodyne.config	ConfigManager, ParameterSpace, ParameterRegistry, YAML schema
homodyne CLI	All CLI entry points and shell completion system
Device Module	CPU device management, NUMA configuration, and status utilities
I/O Module	Result saving (JSON, NPZ) and serialization utilities
Visualization Module	Plotting, visualization, and diagnostic figure generation
Utilities	Logging utilities, CPU/NUMA detection

---

Quick Navigation

Core Physics

• homodyne.core — Physics constants, validation, safe_exp(), safe_sinc(), scaling utilities

• homodyne.core.homodyne_model — HomodyneModel unified model facade

• homodyne.core.jax_backend — JIT-compiled g₁/g₂ functions, autodiff, cache management

Models

• PhysicsModelBase — PhysicsModelBase abstract interface

• DiffusionModel — Static-mode diffusion model

• ShearModel — Shear-flow contribution

• CombinedModel — Full laminar-flow model

Optimization

• fit_nlsq_jax — fit_nlsq_jax() primary entry point

• homodyne.optimization.nlsq — Adapter — NLSQAdapter (JIT caching, multi-start)

• homodyne.optimization.nlsq — Wrapper — NLSQWrapper (streaming, anti-degeneracy)

• fit_mcmc_jax — fit_mcmc_jax() Bayesian pipeline

• CMCConfig — CMCConfig dataclass

• SamplingPlan — SamplingPlan adaptive scheduling

• ReparamConfig — ReparamConfig and parameter transforms

Infrastructure

• XPCSDataLoader — XPCSDataLoader

• ConfigManager — ConfigManager

• homodyne CLI — homodyne main command, all CLI entry points

• Utilities — get_logger(), log_phase(), path validation

---

API Reference

• homodyne.core
  • homodyne.core.physics
  • homodyne.core.physics_utils
  • homodyne.core.scaling_utils
• homodyne.core.homodyne_model
  • HomodyneModel
  • Architecture
  • Key Attributes
  • Usage Examples
• homodyne.core.jax_backend
  • Backend Availability
  • g₁ Correlation Functions
  • g₂ Correlation Functions
  • Chi-Squared
  • Batched Computations
  • Automatic Differentiation
  • Meshgrid Cache
  • Diagnostics
  • Usage Examples
• homodyne.core.models
  • Physical Model Summary
  • PhysicsModelBase
  • DiffusionModel
  • ShearModel
  • CombinedModel
  • Module-level factory
• homodyne.core.theory
  • TheoryEngine
  • Usage Examples
• homodyne.optimization
  • Choosing Between NLSQ and CMC
  • Common Workflow Patterns
  • Package Structure
• Optimization Module
  • Overview
  • Module Contents
  • NLSQ: Non-Linear Least Squares
  • CMC: Consensus Monte Carlo
  • Anti-Degeneracy Defense System
  • Supporting Modules
  • Usage Examples
  • See Also
• homodyne.optimization.nlsq — Adapter
  • When to Use NLSQAdapter vs NLSQWrapper
  • fit_nlsq_jax
  • NLSQAdapter
  • AdapterConfig
  • Usage Examples
  • Return Type
• homodyne.optimization.nlsq — Wrapper
  • Key Differences from NLSQAdapter
  • Out-of-Core Routing
  • NLSQWrapper
  • NLSQConfig
  • Usage Examples
  • Extracted Strategy Modules
• homodyne.optimization.cmc
  • fit_mcmc_jax
  • Shard Size Selection
  • CMCConfig
  • CMCResult
  • Per-Angle Mode
  • YAML Configuration Reference
  • Quality Filtering
  • Usage Examples
• homodyne.optimization.cmc.sampler
  • Divergence Rate Constants
  • SamplingPlan
  • Adaptive Sampling Behaviour
  • run_nuts_sampling
  • MCMCSamples
  • NUTS Configuration
  • JAX Profiling
  • Usage Examples
• homodyne.optimization.cmc.reparameterization
  • ReparamConfig
  • Parameter Transformations
  • compute_t_ref
  • transform_nlsq_to_reparam_space
  • transform_to_sampling_space
  • transform_to_physics_space
  • Usage Examples
• homodyne.optimization.cmc.backends
  • Multiprocessing Backend
  • Chain Execution Methods
  • XLA Device Setup
  • Heterogeneity Detection
  • Worker Pool
  • Base Backend and Combination Utilities
  • Usage Examples
• homodyne.data
  • XPCSDataLoader
  • HDF5 Format Requirements
  • NPZ Caching
  • Data Validation
  • Output Data Structure
  • Usage Examples
  • Supplementary Modules
• homodyne.config
  • ConfigManager
  • ParameterSpace
  • YAML Configuration Schema
  • Default Parameter Values
  • ParameterRegistry
• homodyne CLI
  • homodyne
  • homodyne-config
  • homodyne-config-xla
  • homodyne-post-install
  • homodyne-cleanup
  • Shell Completion System
  • Internal CLI Modules
• Device Module
  • Overview
  • Module Contents
  • Device Configuration
  • Device Status
  • Performance Benchmarking
  • CPU Module
  • Configuration Module
  • Environment Variables
  • HPC Best Practices
  • Troubleshooting
  • See Also
• I/O Module
  • Overview
  • Module Contents
  • NLSQ Writers
  • MCMC Writers
  • JSON Utilities
  • Usage Examples
  • See Also
• Visualization Module
  • Overview
  • Module Contents
  • Experimental Data Plots
  • NLSQ Optimization Plots
  • MCMC Diagnostic Plots
  • Datashader Backend (Optional)
  • Visualization Diagnostics
  • Publication-Quality Figures
  • Best Practices
  • See Also
• Utilities
  • homodyne.utils.logging
  • homodyne.device
  • homodyne.utils.path_validation
  • homodyne.utils.async_io