Heterodyne

CPU-optimized JAX-based heterodyne scattering analysis for XPCS under nonequilibrium conditions.

Heterodyne provides a complete pipeline for fitting two-component heterodyne correlation functions from X-ray Photon Correlation Spectroscopy (XPCS) experiments. It combines JIT-compiled physics kernels with dual inference engines (NLSQ and MCMC/NUTS) to extract transport coefficients, velocity fields, and sample fractions from nonequilibrium soft matter systems.

At a Glance

Python	3.12+
JAX	>= 0.8.2 (CPU-only)
NLSQ	>= 0.6.10 (trust-region Levenberg–Marquardt)
Bayesian	NumPyro / NUTS / CMC
Analysis mode	Two-component heterodyne (14 physics + 2 scaling parameters)
Input	HDF5 via XPCSDataLoader
Output	JSON + NPZ
License	MIT

Key Features

• JIT-compiled heterodyne physics – all correlation kernels run through JAX’s XLA compiler for maximum throughput on multi-core CPUs.

• Two-component velocity phase model – simultaneously resolves reference and sample dynamics with distinct transport exponents.

• 14-parameter transport + fraction + velocity model – diffusion prefactors, transport exponents, velocity amplitude and offset, flow angle, and time-dependent sample fractions.

• NLSQ + CMC/NUTS dual inference – fast deterministic warm-start via trust-region Levenberg–Marquardt, followed by fully Bayesian posterior sampling.

• Element-wise ShardGrid CMC – O(n_pairs) cumsum lookup prevents N x N matrix allocation, eliminating out-of-memory failures on long time series.

• Fourier reparameterization for multi-angle fits – joint optimization across azimuthal angles with configurable Fourier order.

• CPU/NUMA-aware HPC backend – automatic thread pinning and XLA flag tuning for 36–128-core cluster nodes.

• Strict data integrity – runtime validation of shapes, dtypes, NaN guards, and monotonicity checks at every I/O boundary.

Quick Start

1. Install

uv add heterodyne

2. Generate a configuration file

heterodyne-config --output my_config.yaml

3. Run an analysis

heterodyne --config my_config.yaml --method nlsq

Python API

from heterodyne.data.xpcs_loader import XPCSDataLoader
from heterodyne.optimization.nlsq.core import fit_nlsq_jax

loader = XPCSDataLoader("experiment.hdf5")
data = loader.load()

result = fit_nlsq_jax(
    data=data,
    method="trf",
)

Documentation

User Guide

• User Guide
  • Learning Pathways
  • Path A – New to XPCS
  • Path B – Two-Component Dynamics
  • Path C – Bayesian Uncertainty Quantification
  • Path D – Advanced / Performance
  • Guide Contents

Theory & Physics

• Theory & Physics
  • Transport Coefficient J(t)
  • Correlation Functions
  • Heterodyne Scattering Model
  • Classical Stochastic Processes
  • Computational Methods
  • Analysis Modes
  • Anti-Degeneracy Defense System
  • References

Configuration

• Configuration
  • Generating a Default Config
  • Running with a Config
  • Section Reference

API Reference

• API Reference
  • Quick Navigation

Examples

• Examples
  • End-to-End NLSQ Workflow
  • Bayesian CMC Analysis
  • Multi-Angle Joint Fitting
  • Further Reading

Developer Guide

• Developer Guide
  • Quick Reference
  • Tool Chain
  • Sections

Architecture Deep Dives

• Architecture Deep Dives
  • Subsystem Summaries

Additional Resources

• Installation
• Quick Start
• Contributing

Citation

If you use Heterodyne in your research, please cite both papers:

He et al., PNAS 2024 – Transport coefficient approach for characterizing nonequilibrium dynamics in soft matter:

@article{He2024transport,
  title   = {Transport coefficient approach for characterizing
             nonequilibrium dynamics in soft matter},
  author  = {He, Hongrui and Chen, Wei and others},
  journal = {Proceedings of the National Academy of Sciences},
  year    = {2024},
  doi     = {10.1073/pnas.2401162121},
}

He et al., PNAS 2025 – Bridging microscopic dynamics and rheology in the yielding of charged colloidal suspensions:

@article{He2025bridging,
  title   = {Bridging microscopic dynamics and rheology in the
             yielding of charged colloidal suspensions},
  author  = {He, Hongrui and Chen, Wei and others},
  journal = {Proceedings of the National Academy of Sciences},
  year    = {2025},
  doi     = {10.1073/pnas.2514216122},
}

Community & Support

• Source code: https://github.com/imewei/heterodyne

• Issue tracker: https://github.com/imewei/heterodyne/issues

• Documentation: https://heterodyne.readthedocs.io

Indices and Tables

• Index

• Module Index

• Search Page