Metadata-Version: 2.4
Name: homodyne
Version: 2.22.7
Summary: CPU-optimized JAX-based homodyne scattering analysis for XPCS under nonequilibrium conditions
Author-email: Wei Chen <weichen@anl.gov>, Hongrui He <hhe@anl.gov>
Maintainer-email: Wei Chen <weichen@anl.gov>
License: MIT
Project-URL: Homepage, https://github.com/imewei/homodyne
Project-URL: Documentation, https://homodyne.readthedocs.io
Project-URL: Repository, https://github.com/imewei/homodyne.git
Project-URL: Issues, https://github.com/imewei/homodyne/issues
Project-URL: Changelog, https://github.com/imewei/homodyne/blob/main/CHANGELOG.md
Keywords: xpcs,scattering,dynamics,jax,optimization,bayesian,physics,materials-science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.3
Requires-Dist: scipy>=1.17
Requires-Dist: jax>=0.8.2
Requires-Dist: jaxlib>=0.8.2
Requires-Dist: jaxopt>=0.8.3
Requires-Dist: interpax>=0.3.12
Requires-Dist: nlsq>=0.6.10
Requires-Dist: evosax>=0.2.0
Requires-Dist: numpyro>=0.19.0
Requires-Dist: blackjax>=1.3
Requires-Dist: arviz>=0.23
Requires-Dist: h5py<4.0,>=3.15
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: psutil>=7.2
Requires-Dist: cloudpickle>=3.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: matplotlib>=3.10
Requires-Dist: datashader>=0.18
Requires-Dist: xarray>=2025.12
Requires-Dist: scikit-learn>=1.6
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: pytest-cov>=7.0
Requires-Dist: pytest-xdist>=3.8
Requires-Dist: ruff>=0.15.2
Requires-Dist: mypy>=1.19.1
Requires-Dist: pre-commit>=4.5.1
Requires-Dist: types-pyyaml>=6.0.12.20250915
Requires-Dist: sphinx>=9.1.0
Requires-Dist: furo>=2025.12.19
Requires-Dist: myst-parser>=5.0.0
Requires-Dist: sphinx-autodoc-typehints>=3.6.3
Requires-Dist: sphinx-copybutton>=0.5.2
Dynamic: license-file

# Homodyne

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)
[![Documentation](https://img.shields.io/badge/docs-sphinx-blue.svg)](https://homodyne.readthedocs.io)
[![ReadTheDocs](https://readthedocs.org/projects/homodyne/badge/?version=latest)](https://homodyne.readthedocs.io/en/latest/)
[![DOI](https://zenodo.org/badge/DOI/10.1073/pnas.2401162121.svg)](https://doi.org/10.1073/pnas.2401162121)

CPU-optimized JAX package for X-ray Photon Correlation Spectroscopy (XPCS) analysis,
implementing the theoretical framework from
[He et al. PNAS 2024](https://doi.org/10.1073/pnas.2401162121) and
[He et al. PNAS 2025](https://doi.org/10.1073/pnas.2514216122) for characterizing
transport properties in flowing soft matter systems.

## Homodyne Model

$$c_2(\phi, t_1, t_2) = \text{offset} + \text{contrast} \times \exp\left(-q^2 \int_{t_1}^{t_2} J(t')\ dt'\right) \times \mathrm{sinc}^2\left(\frac{qL\cos(\phi_0 - \phi)}{2\pi} \int_{t_1}^{t_2} \dot{\gamma}(t')\ dt'\right)$$

$$J(t) = D_0 \cdot t^{\alpha} + D_{\text{offset}} \qquad \dot{\gamma}(t) = \dot{\gamma}_0 \cdot t^{\beta} + \dot{\gamma}_{\text{offset}}$$

All time integrals are evaluated numerically via cumulative trapezoid on the discrete time grid.

| Mode | Parameters | Count |
|------|------------|-------|
| **static** | D0, alpha, D_offset | 3 |
| **laminar_flow** | D0, alpha, D_offset, gamma_dot_0, beta, gamma_dot_offset, phi0 | 7 |

Per-angle contrast and offset are added automatically based on the number of azimuthal angles.

## Installation

```bash
pip install homodyne
```

For development:

```bash
git clone https://github.com/imewei/homodyne.git
cd homodyne
make dev    # or: uv sync
```

**Requirements:** Python 3.12+, CPU-only (no GPU). Runs on Linux, macOS, and Windows.

## Quick Start

### CLI

```bash
# Generate a config template
homodyne-config --mode static --output config.yaml

# Run NLSQ optimization
homodyne --method nlsq --config config.yaml

# Run Consensus Monte Carlo for uncertainty quantification
homodyne --method cmc --config config.yaml
```

### Python API

```python
from homodyne.optimization import fit_nlsq_jax, fit_mcmc_jax
from homodyne.data import load_xpcs_data
from homodyne.config import ConfigManager

data = load_xpcs_data("config.yaml")
config = ConfigManager("config.yaml")

# NLSQ trust-region optimization
nlsq_result = fit_nlsq_jax(data, config)

# CMC with NLSQ warm-start for Bayesian uncertainty
cmc_result = fit_mcmc_jax(data, config, nlsq_result=nlsq_result)
```

### Data Flow

```
YAML config --> XPCSDataLoader(HDF5) --> HomodyneModel --> NLSQ or CMC --> Results (JSON + NPZ)
```

## Optimization Methods

**NLSQ** (primary) -- JAX-native trust-region Levenberg-Marquardt with automatic
anti-degeneracy defense, CMA-ES global search for multi-scale problems, and memory-aware
routing for large datasets.

**CMC** (secondary) -- Consensus Monte Carlo using NumPyro NUTS sampling with automatic
sharding, NLSQ warm-start priors, and multiprocessing across CPU cores. Produces
publication-quality posterior distributions with ArviZ diagnostics.

## Configuration

Homodyne uses YAML configuration files. Generate a template:

```bash
homodyne-config --mode laminar_flow --output config.yaml
```

Key sections:

```yaml
analysis_mode: "laminar_flow"
experimental_data:
  file_path: "data.h5"
optimization:
  method: "nlsq"
  nlsq:
    anti_degeneracy:
      per_angle_mode: "auto"   # auto, constant, individual, fourier
  cmc:
    sharding:
      max_points_per_shard: "auto"
```

See the [User Guide](https://homodyne.readthedocs.io/en/latest/user-guide/index.html)
for full configuration reference.

## CLI Commands

| Command | Purpose |
|---------|---------|
| `homodyne` | Run XPCS analysis (NLSQ/CMC) |
| `homodyne-config` | Generate and validate config files |
| `homodyne-config-xla` | Configure XLA device settings |
| `homodyne-post-install` | Install shell completion (bash/zsh/fish) |
| `homodyne-cleanup` | Remove shell completion files |

Shell completion and aliases are available after running `homodyne-post-install --interactive`.

## Development

```bash
make test       # Unit tests
make test-all   # Full suite + coverage
make quality    # Format + lint + type-check
```

## Documentation

- [User Guide](https://homodyne.readthedocs.io/en/latest/user-guide/index.html)
- [API Reference](https://homodyne.readthedocs.io/en/latest/api-reference/index.html)
- [Changelog](CHANGELOG.md)

## Citation

If you use Homodyne in your research, please cite:

```bibtex
@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},
  volume  = {121},
  number  = {31},
  year    = {2024},
  doi     = {10.1073/pnas.2401162121}
}
```

```bibtex
@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},
  volume  = {122},
  number  = {42},
  year    = {2025},
  doi     = {10.1073/pnas.2514216122}
}
```

## License

MIT License -- see [LICENSE](LICENSE) for details.

## Authors

- Wei Chen (weichen@anl.gov) -- Argonne National Laboratory
- Hongrui He (hhe@anl.gov) -- Argonne National Laboratory
