Homodyne¶

JAX-first XPCS analysis for nonequilibrium soft matter systems.

Homodyne is a CPU-optimized X-ray Photon Correlation Spectroscopy (XPCS) analysis framework built on JAX. It implements the algorithms described in He et al. PNAS 2024 and He et al. PNAS 2025 for analyzing time-dependent dynamics in soft matter systems — from static isotropic scattering to complex laminar flow geometries.

At a Glance¶

Language	Python 3.12+
Compute backend	JAX \(\geq\) 0.8.2 (CPU-only, XLA-accelerated)
Optimizer	NLSQ \(\geq\) 0.6.4 (trust-region Levenberg-Marquardt)
Bayesian engine	NumPyro / NUTS / Consensus Monte Carlo
Analysis modes	`static` (3 params) \| `laminar_flow` (7 params)
Input format	HDF5 via `XPCSDataLoader`
Output format	JSON + NPZ result bundles
License	MIT

Key Features¶

JIT-compiled physics — full homodyne model in JAX with jit + vmap; no Python loops in the hot path.
Two inference methods — point-estimate NLSQ (seconds) and full Bayesian CMC/NUTS posteriors (minutes), both from the same model.
Anti-degeneracy system — quantile-based per-angle scaling prevents parameter absorption for laminar flow data.
Consensus Monte Carlo — embarrassingly parallel Bayesian inference across CPU shards with automatic shard-size selection.
Adaptive sampling — NUTS warmup/samples scale with dataset size to avoid wasted compute on small shards.
Strict data integrity — no silent subsampling; full-precision HDF5 I/O with shape/dtype/NaN validation at every boundary.
CLI-first workflow — homodyne, homodyne-config, and homodyne-config-xla entry points with shell completion.

Quick Start¶

Install and run a static-mode NLSQ analysis in three steps:

# 1. Install (recommended: uv)
uv add homodyne

# 2. Generate a configuration template
homodyne-config --mode static --output my_config.yaml

# 3. Run NLSQ analysis
homodyne --config my_config.yaml --method nlsq

Or from Python:

from homodyne.data import XPCSDataLoader
from homodyne.config import ConfigManager
from homodyne.optimization.nlsq import fit_nlsq_jax

# Load configuration and experimental data
config = ConfigManager("my_config.yaml")
data   = XPCSDataLoader(config_dict=config.config).load_experimental_data()

# Run NLSQ fit
result = fit_nlsq_jax(data, config)

print(f"Success:  {result.success}")
print(f"Chi2/n:   {result.reduced_chi_squared:.4f}")
print(f"Params:   {result.parameters}")

See Quick Start — 5 Minutes to First Analysis for the full five-minute guide.

Documentation¶

User Guide	Installation, CLI workflows, analysis modes, and result interpretation.
Theory & Physics	Homodyne scattering, correlation functions, transport coefficients, and anti-degeneracy.
Configuration	YAML configuration reference for NLSQ, CMC, and data loading.
API Reference	Python API reference (autodoc).
Examples	Example workflows for static and laminar flow analyses.
Developer Guide	Contributing, architecture, and testing guide.
Architecture Deep Dives	Internal architecture deep dives for each subsystem.

Citation¶

If you use Homodyne in published research, please cite both papers:

Primary algorithm paper:

@article{He2024,
  author  = {He, Hongrui and Liang, Hao and Chu, Miaoqi and Jiang, Zhang and
             de Pablo, Juan J and Tirrell, Matthew V and Narayanan, Suresh
             and Chen, Wei},
  title   = {Transport coefficient approach for characterizing nonequilibrium
             dynamics in soft matter},
  journal = {Proceedings of the National Academy of Sciences},
  year    = {2024},
  volume  = {121},
  number  = {31},
  pages   = {e2401162121},
  doi     = {10.1073/pnas.2401162121},
  url     = {https://doi.org/10.1073/pnas.2401162121}
}

Laminar flow / shear dynamics extension:

@article{He2025,
  author  = {He, Hongrui and Liang, Heyi and Chu, Miaoqi and Jiang, Zhang and
             de Pablo, Juan J and Tirrell, Matthew V and Narayanan, Suresh
             and Chen, Wei},
  title   = {Bridging microscopic dynamics and rheology in the yielding
             of charged colloidal suspensions},
  journal = {Proceedings of the National Academy of Sciences},
  year    = {2025},
  volume  = {122},
  number  = {42},
  pages   = {e2514216122},
  doi     = {10.1073/pnas.2514216122},
  url     = {https://doi.org/10.1073/pnas.2514216122}
}

Community and Support¶

Source code	github.com/imewei/homodyne
Bug reports	GitHub Issues
Discussions	GitHub Discussions
Institution	Argonne National Laboratory

Note

Homodyne is developed at Argonne National Laboratory. Contributions, bug reports, and feature requests are welcome via GitHub.