| Name | homodyne-analysis JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | https://github.com/imewei/homodyne |
| Summary | Comprehensive Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions |
| upload_time | 2025-08-21 05:51:15 |
| maintainer | None |
| docs_url | None |
| author | Hongrui He |
| requires_python | >=3.12 |
| license | MIT License
Copyright (c) 2025 Wei Chen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
xpcs
homodyne
scattering
correlation spectroscopy
soft matter
nonequilibrium dynamics
transport coefficients
bayesian analysis
mcmc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
numpy
scipy
matplotlib
numba
psutil
xpcs-viewer
pymc
arviz
pytensor
corner
pytest
pytest-cov
pytest-xdist
pytest-benchmark
pytest-mock
hypothesis
black
flake8
mypy
types-psutil
types-Pillow
types-six
sphinx
sphinx-rtd-theme
myst-parser
sphinx-autodoc-typehints
numpydoc
linkify-it-py
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Homodyne Scattering Analysis Package
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://numba.pydata.org/)
[](PERFORMANCE_OPTIMIZATIONS.md)
A high-performance Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions. Implements the theoretical framework from [He et al. PNAS 2024](https://doi.org/10.1073/pnas.2401162121) for characterizing transport properties in flowing soft matter systems.
## Overview
Analyzes time-dependent intensity correlation functions $c_2(\phi,t_1,t_2)$ in complex fluids under nonequilibrium conditions, capturing the interplay between Brownian diffusion and advective shear flow.
**Key Features:**
- **Three analysis modes**: Static Isotropic (3 params), Static Anisotropic (3 params), Laminar Flow (7 params)
- **Dual optimization**: Fast classical (Nelder-Mead) and robust Bayesian MCMC (NUTS)
- **High performance**: Numba JIT compilation with 3-5x speedup, vectorized operations, and optimized memory usage
- **Performance monitoring**: Comprehensive regression testing and automated benchmarking
- **Scientific accuracy**: Automatic $g_2 = \text{offset} + \text{contrast} \times g_1$ fitting for proper $\chi^2$ calculations
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Analysis Modes](#analysis-modes)
- [Usage Examples](#usage-examples)
- [Configuration](#configuration)
- [Performance & Testing](#performance--testing)
- [Theoretical Background](#theoretical-background)
- [Citation](#citation)
- [Documentation](#documentation)
## Installation
### PyPI Installation (Recommended)
```bash
pip install homodyne-analysis[all]
```
### Development Installation
```bash
git clone https://github.com/imewei/homodyne.git
cd homodyne
pip install -e .[all]
```
### Dependencies
- **Core**: `numpy`, `scipy`, `matplotlib`
- **Performance**: `numba` (3-5x speedup via JIT compilation)
- **Bayesian Analysis**: `pymc`, `arviz`, `pytensor` (for MCMC sampling)
- **Optional**: `pytest`, `sphinx` (testing and documentation)
## Quick Start
```bash
# Install
pip install homodyne-analysis[all]
# Create configuration
homodyne-config --mode laminar_flow --sample my_sample
# Run analysis
homodyne --config my_config.json --method all
```
**Python API:**
```python
from homodyne import HomodyneAnalysisCore, ConfigManager
config = ConfigManager("config.json")
analysis = HomodyneAnalysisCore(config)
results = analysis.optimize_classical() # Fast
results = analysis.optimize_all() # Classical + MCMC
```
## Analysis Modes
The homodyne analysis package supports three distinct analysis modes, each optimized for different experimental scenarios:
| Mode | Parameters | Angle Handling | Use Case | Speed | Command |
|------|------------|----------------|----------|-------|---------|
| **Static Isotropic** | 3 | Single dummy | Fastest, isotropic systems | ⭐⭐⭐ | `--static-isotropic` |
| **Static Anisotropic** | 3 | Filtering enabled | Static with angular deps | ⭐⭐ | `--static-anisotropic` |
| **Laminar Flow** | 7 | Full coverage | Flow & shear analysis | ⭐ | `--laminar-flow` |
### Static Isotropic Mode (3 parameters)
- **Physical Context**: Analysis of systems at equilibrium with isotropic scattering where results don't depend on scattering angle
- **Parameters**:
- $D_0$: Effective diffusion coefficient
- $\alpha$: Time exponent characterizing dynamic scaling
- $D_{\text{offset}}$: Baseline diffusion component
- **Key Features**:
- No angle filtering (automatically disabled)
- No phi_angles_file loading (uses single dummy angle)
- Fastest analysis mode
- **When to Use**: Isotropic samples, quick validation runs, preliminary analysis
- **Model**: $g_1(t_1,t_2) = \exp(-q^2 \int_{t_1}^{t_2} D(t)dt)$ with no angular dependence
### Static Anisotropic Mode (3 parameters)
- **Physical Context**: Analysis of systems at equilibrium with angular dependence but no flow effects
- **Parameters**: $D_0$, $\alpha$, $D_{\text{offset}}$ (same as isotropic mode)
- **Key Features**:
- Angle filtering enabled for optimization efficiency
- phi_angles_file loaded for angle information
- Per-angle scaling optimization
- **When to Use**: Static samples with measurable angular variations, moderate computational resources
- **Model**: Same as isotropic mode but with angle filtering to focus optimization on specific angular ranges
### Laminar Flow Mode (7 parameters)
- **Physical Context**: Analysis of systems under controlled shear flow conditions with full physics model
- **Parameters**:
- $D_0$, $\alpha$, $D_{\text{offset}}$: Same as static modes
- $\dot{\gamma}_0$: Characteristic shear rate
- $\beta$: Shear rate exponent for flow scaling
- $\dot{\gamma}_{\text{offset}}$: Baseline shear component
- $\phi_0$: Angular offset parameter for flow geometry
- **Key Features**:
- All flow and diffusion effects included
- phi_angles_file required for angle-dependent flow effects
- Complex parameter space with potential correlations
- **When to Use**: Systems under shear, nonequilibrium conditions, transport coefficient analysis
- **Model**: $g_1(t_1,t_2) = g_{1,\text{diff}}(t_1,t_2) \times g_{1,\text{shear}}(t_1,t_2)$ where shear effects are $\text{sinc}^2(\Phi)$
## Usage Examples
### Command Line Interface
```bash
# Basic analysis
homodyne --static-isotropic --method classical
homodyne --static-anisotropic --method mcmc
homodyne --laminar-flow --method all
# Data validation only
homodyne --plot-experimental-data --config my_config.json
# Custom configuration and output
homodyne --config my_experiment.json --output-dir ./results
# Generate C2 heatmaps
homodyne --method classical --plot-c2-heatmaps
```
### Data Validation
Generate validation plots without fitting:
```bash
homodyne --plot-experimental-data --config my_config.json --verbose
```
**Output**: Creates plots in `./homodyne_results/exp_data/`:
- 2D correlation function heatmaps $g_2(t_1,t_2)$
- Diagonal slices $g_2(t,t)$ showing decay
- Statistical summaries and quality metrics
## Configuration
### Creating Configurations
```bash
# Generate configuration templates
homodyne-config --mode static_isotropic --sample protein_01
homodyne-config --mode laminar_flow --sample microgel
```
### Mode Selection
Configuration files specify analysis mode:
```json
{
"analysis_settings": {
"static_mode": true/false,
"static_submode": "isotropic" | "anisotropic" | null
}
}
```
**Rules**:
- `static_mode: false` → Laminar Flow Mode (7 params)
- `static_mode: true, static_submode: "isotropic"` → Static Isotropic (3 params)
- `static_mode: true, static_submode: "anisotropic"` → Static Anisotropic (3 params)
### Quality Control
Check data quality before fitting:
```bash
homodyne --plot-experimental-data --verbose
```
**Look for**:
- Mean values around 1.0 ($g_2$ correlation functions)
- Enhanced diagonal values
- Sufficient contrast (> 0.001)
## Performance & Testing
### Optimization Methods
**Classical (Fast)**
- Algorithm: Nelder-Mead simplex with vectorized operations
- Speed: ~minutes (optimized with lazy imports and memory-efficient operations)
- Use: Exploratory analysis, parameter screening
- Command: `--method classical`
**Bayesian MCMC (Comprehensive)**
- Algorithm: NUTS sampler via PyMC (lazy-loaded for fast startup)
- Speed: ~hours (with Numba JIT acceleration and optional thinning)
- Features: Uncertainty quantification, thinning support, convergence diagnostics
- Use: Uncertainty quantification, publication results
- Command: `--method mcmc`
**Combined**
- Workflow: Classical → MCMC refinement
- Command: `--method all`
### Performance Optimizations
The package includes comprehensive performance optimizations:
**🚀 Computational Optimizations:**
- **Numba JIT compilation**: 3-5x speedup for core kernels with comprehensive warmup
- **Vectorized operations**: NumPy-optimized angle filtering and array operations
- **Memory-efficient processing**: Lazy allocation and memory-mapped file loading
- **Enhanced caching**: Fast cache key generation for NumPy arrays
- **Stable benchmarking**: Outlier filtering and variance reduction for reliable performance testing
**⚡ Import Optimizations:**
- **Lazy loading**: Heavy dependencies loaded only when needed
- **Fast startup**: >99% reduction in import time for optional components
- **Modular imports**: Core functionality available without heavy dependencies
**🎯 MCMC Optimizations:**
- **Thinning support**: Configurable sample thinning to reduce autocorrelation and memory usage
- **Smart defaults**: Mode-aware thinning settings (thin=1 for laminar flow, thin=2 for static modes)
- **Convergence diagnostics**: R-hat, ESS, and mixing assessment with thinning recommendations
**📊 Memory Optimizations:**
- **Memory-mapped I/O**: Efficient loading of large experimental datasets
- **Lazy array allocation**: Reduced peak memory usage
- **Garbage collection optimization**: Automatic cleanup of temporary objects
**🔧 Recent Performance Enhancements (v2024.2):**
- **Enhanced JIT warmup**: Comprehensive function-level warmup reduces timing variance by 60%
- **Stable benchmarking**: Statistical outlier filtering for reliable performance measurement
- **Consolidated performance utilities**: Unified performance testing infrastructure
- **Improved type safety**: Enhanced type annotations and consistency checks
## Physical Constraints and Parameter Ranges
### Parameter Distributions and Constraints
The homodyne package implements comprehensive physical constraints to ensure scientifically meaningful results:
#### **Core Model Parameters**
| Parameter | Range | Distribution | Physical Constraint |
|-----------|-------|--------------|-------------------|
| `D0` | [1.0, 1000000.0] Ų/s | TruncatedNormal(μ=10000.0, σ=1000.0) | positive |
| `alpha` | [-2.0, 2.0] dimensionless | Normal(μ=-1.5, σ=0.1) | none |
| `D_offset` | [-100, 100] Ų/s | Normal(μ=0.0, σ=10.0) | none |
| `gamma_dot_t0` | [1e-06, 1.0] s⁻¹ | TruncatedNormal(μ=0.001, σ=0.01) | positive |
| `beta` | [-2.0, 2.0] dimensionless | Normal(μ=0.0, σ=0.1) | none |
| `gamma_dot_t_offset` | [-0.01, 0.01] s⁻¹ | Normal(μ=0.0, σ=0.001) | none |
| `phi0` | [-10, 10] degrees | Normal(μ=0.0, σ=5.0) | angular |
#### **Physical Function Constraints**
The package **automatically enforces positivity** for time-dependent functions:
- **D(t) = D₀(t)^α + D_offset** → **max(D(t), 1×10⁻¹⁰)**
- Prevents negative diffusion coefficients
- Maintains numerical stability with minimal threshold
- **γ̇(t) = γ̇₀(t)^β + γ̇_offset** → **max(γ̇(t), 1×10⁻¹⁰)**
- Prevents negative shear rates
- Ensures physical validity in all optimization scenarios
#### **Scaling Parameters for Correlation Functions**
The relationship **c2_fitted = c2_theory × contrast + offset** uses bounded parameters:
| Parameter | Range | Distribution | Physical Meaning |
|-----------|-------|--------------|------------------|
| `contrast` | (0.05, 0.5] | TruncatedNormal(μ=0.3, σ=0.1) | Correlation strength scaling |
| `offset` | (0.05, 1.95] | TruncatedNormal(μ=1.0, σ=0.2) | Baseline correlation level |
| `c2_fitted` | [1.0, 2.0] | *derived* | Final correlation function range |
| `c2_theory` | [0.0, 1.0] | *derived* | Theoretical correlation bounds |
### MCMC Configuration
**Optimized MCMC Settings:**
- **target_accept = 0.95**: High acceptance rate for constrained sampling
- **Distribution-aware priors**: TruncatedNormal for positive parameters, Normal otherwise
- **Configuration-driven**: All parameters read from JSON files for consistency
#### Static Isotropic (3 parameters)
{
"draws": 8000,
"thin": 2, # Effective samples: 4000
"chains": 4
}
#### Static Anisotropic (3 parameters)
{
"draws": 8000,
"thin": 2, # Good convergence expected
"chains": 4
}
#### Laminar Flow (7 parameters)
{
"draws": 10000,
"thin": 1, # All samples needed for complex posterior
"chains": 6
}
#### Memory-Constrained Systems
{
"draws": 5000,
"thin": 5, # Effective samples: 1000
"chains": 2
}
```
**Thinning Benefits:**
- ✅ Reduces autocorrelation between samples
- ✅ Lower memory usage (fewer stored samples)
- ✅ Faster post-processing and plotting
- ✅ Better effective sample size per stored sample
- ⚠️ Trades total samples for independence
### Performance Monitoring
**Automated Performance Testing:**
```bash
# Quick performance validation
python run_performance_tests.py --quick
# Full performance test suite
python run_performance_tests.py --full
# Memory usage tests
python run_performance_tests.py --memory
# Update performance baselines after optimizations
python run_performance_tests.py --update --quick
```
**Pytest Integration:**
```bash
# Performance tests with pytest
pytest -m performance # All performance tests
pytest -m "performance and not slow" # Quick tests (CI-friendly)
pytest -m benchmark --benchmark-only # Benchmarking tests
pytest -m memory # Memory usage tests
```
**Performance Benchmarking:**
```bash
# Comprehensive benchmark
python performance_benchmark_optimized.py --detailed
# Quick benchmark validation
python performance_benchmark_optimized.py
```
### Scaling Optimization
Always enabled for scientific accuracy:
$$g_2 = \text{offset} + \text{contrast} \times g_1$$
Accounts for instrumental effects, background, and normalization differences.
### Environment Optimization
```bash
# Threading optimization for reproducible performance
export OMP_NUM_THREADS=8
export OPENBLAS_NUM_THREADS=8
export MKL_NUM_THREADS=8
export NUMBA_DISABLE_INTEL_SVML=1
# Memory optimization
export NUMBA_CACHE_DIR=/tmp/numba_cache
# Performance monitoring mode
export HOMODYNE_PERFORMANCE_MODE=1
```
### Testing Framework
**Standard Testing:**
```bash
python homodyne/run_tests.py # Standard tests
python homodyne/run_tests.py --fast # Quick tests
python homodyne/run_tests.py --coverage # With coverage
pytest # Pytest runner
```
**Performance Testing:**
```bash
# Performance validation
python run_performance_tests.py --quick
# Performance test suite
pytest -m performance
# Regression detection
pytest -m regression
# Stable benchmarking with statistical analysis
pytest -m benchmark --benchmark-only
```
**CI/CD Integration:**
- **Automated testing**: Performance tests run on every PR
- **Regression detection**: Automatic alerts for performance degradation
- **Multi-platform**: Tests across Python 3.12, 3.13
- **Baseline tracking**: Performance history and trend monitoring
### Performance Documentation
📊 **Detailed Performance Guides:**
- [`docs/performance_optimization.md`](docs/performance_optimization.md) - Complete optimization details and testing framework guide
### Output Organization
```
./homodyne_results/
├── classical/ # Classical method outputs
│ ├── experimental_data.npz
│ ├── fitted_data.npz
│ └── residuals_data.npz
├── mcmc/ # MCMC method outputs
│ ├── mcmc_summary.json
│ ├── mcmc_trace.nc
│ ├── trace_plot.png
│ └── corner_plot.png
└── exp_data/ # Data validation plots
```
## Theoretical Background
The package implements three key equations describing correlation functions in nonequilibrium laminar flow systems:
**Equation 13 - Full Nonequilibrium Laminar Flow:**
$$c_2(\vec{q}, t_1, t_2) = 1 + \beta\left[e^{-q^2\int J(t)dt}\right] \times \text{sinc}^2\left[\frac{1}{2\pi} qh \int\dot{\gamma}(t)\cos(\phi(t))dt\right]$$
**Equation S-75 - Equilibrium Under Constant Shear:**
$$c_2(\vec{q}, t_1, t_2) = 1 + \beta\left[e^{-6q^2D(t_2-t_1)}\right] \text{sinc}^2\left[\frac{1}{2\pi} qh \cos(\phi)\dot{\gamma}(t_2-t_1)\right]$$
**Equation S-76 - One-time Correlation (Siegert Relation):**
$$g_2(\vec{q}, \tau) = 1 + \beta\left[e^{-6q^2D\tau}\right] \text{sinc}^2\left[\frac{1}{2\pi} qh \cos(\phi)\dot{\gamma}\tau\right]$$
**Key Parameters:**
- $\vec{q}$: scattering wavevector [Å⁻¹]
- $h$: gap between stator and rotor [Å]
- $\phi(t)$: angle between shear/flow direction and $\vec{q}$ [degrees]
- $\dot{\gamma}(t)$: time-dependent shear rate [s⁻¹]
- $D(t)$: time-dependent diffusion coefficient [Ų/s]
- $\beta$: contrast parameter [dimensionless]
## Citation
If you use this package in your research, please cite:
```bibtex
@article{he2024transport,
title={Transport coefficient approach for characterizing nonequilibrium dynamics in soft matter},
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},
journal={Proceedings of the National Academy of Sciences},
volume={121},
number={31},
pages={e2401162121},
year={2024},
publisher={National Academy of Sciences},
doi={10.1073/pnas.2401162121}
}
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Documentation
📚 **Complete Documentation**: https://homodyne.readthedocs.io/
Includes user guides, API reference, and developer documentation.
## Contributing
We welcome contributions! Please submit issues and pull requests.
**Development setup:**
```bash
git clone https://github.com/imewei/homodyne.git
cd homodyne
pip install -e .[all]
python homodyne/run_tests.py
```
**Authors:** Wei Chen, Hongrui He (Argonne National Laboratory)
**License:** MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/imewei/homodyne",
"name": "homodyne-analysis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Wei Chen <wchen@anl.gov>",
"keywords": "xpcs, homodyne, scattering, correlation spectroscopy, soft matter, nonequilibrium dynamics, transport coefficients, Bayesian analysis, MCMC",
"author": "Hongrui He",
"author_email": "Wei Chen <wchen@anl.gov>",
"download_url": "https://files.pythonhosted.org/packages/f7/dd/b0a3d89f2bdc228ec2a09b1a0968e19841d5b8f316c4563d5da359ec449d/homodyne_analysis-0.6.1.tar.gz",
"platform": null,
"description": "# Homodyne Scattering Analysis Package\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/)\n[](https://numba.pydata.org/)\n[](PERFORMANCE_OPTIMIZATIONS.md)\n\nA high-performance Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions. Implements the theoretical framework from [He et al. PNAS 2024](https://doi.org/10.1073/pnas.2401162121) for characterizing transport properties in flowing soft matter systems.\n\n## Overview\n\nAnalyzes time-dependent intensity correlation functions $c_2(\\phi,t_1,t_2)$ in complex fluids under nonequilibrium conditions, capturing the interplay between Brownian diffusion and advective shear flow.\n\n**Key Features:**\n- **Three analysis modes**: Static Isotropic (3 params), Static Anisotropic (3 params), Laminar Flow (7 params)\n- **Dual optimization**: Fast classical (Nelder-Mead) and robust Bayesian MCMC (NUTS)\n- **High performance**: Numba JIT compilation with 3-5x speedup, vectorized operations, and optimized memory usage\n- **Performance monitoring**: Comprehensive regression testing and automated benchmarking\n- **Scientific accuracy**: Automatic $g_2 = \\text{offset} + \\text{contrast} \\times g_1$ fitting for proper $\\chi^2$ calculations\n\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Analysis Modes](#analysis-modes)\n- [Usage Examples](#usage-examples)\n- [Configuration](#configuration)\n- [Performance & Testing](#performance--testing)\n- [Theoretical Background](#theoretical-background)\n- [Citation](#citation)\n- [Documentation](#documentation)\n\n## Installation\n\n### PyPI Installation (Recommended)\n\n```bash\npip install homodyne-analysis[all]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/imewei/homodyne.git\ncd homodyne\npip install -e .[all]\n```\n\n### Dependencies\n\n- **Core**: `numpy`, `scipy`, `matplotlib`\n- **Performance**: `numba` (3-5x speedup via JIT compilation)\n- **Bayesian Analysis**: `pymc`, `arviz`, `pytensor` (for MCMC sampling)\n- **Optional**: `pytest`, `sphinx` (testing and documentation)\n\n## Quick Start\n\n```bash\n# Install\npip install homodyne-analysis[all]\n\n# Create configuration\nhomodyne-config --mode laminar_flow --sample my_sample\n\n# Run analysis\nhomodyne --config my_config.json --method all\n```\n\n**Python API:**\n\n```python\nfrom homodyne import HomodyneAnalysisCore, ConfigManager\n\nconfig = ConfigManager(\"config.json\")\nanalysis = HomodyneAnalysisCore(config)\nresults = analysis.optimize_classical() # Fast\nresults = analysis.optimize_all() # Classical + MCMC\n```\n\n## Analysis Modes\n\nThe homodyne analysis package supports three distinct analysis modes, each optimized for different experimental scenarios:\n\n| Mode | Parameters | Angle Handling | Use Case | Speed | Command |\n|------|------------|----------------|----------|-------|---------|\n| **Static Isotropic** | 3 | Single dummy | Fastest, isotropic systems | \u2b50\u2b50\u2b50 | `--static-isotropic` |\n| **Static Anisotropic** | 3 | Filtering enabled | Static with angular deps | \u2b50\u2b50 | `--static-anisotropic` |\n| **Laminar Flow** | 7 | Full coverage | Flow & shear analysis | \u2b50 | `--laminar-flow` |\n\n### Static Isotropic Mode (3 parameters)\n- **Physical Context**: Analysis of systems at equilibrium with isotropic scattering where results don't depend on scattering angle\n- **Parameters**: \n - $D_0$: Effective diffusion coefficient\n - $\\alpha$: Time exponent characterizing dynamic scaling\n - $D_{\\text{offset}}$: Baseline diffusion component\n- **Key Features**:\n - No angle filtering (automatically disabled)\n - No phi_angles_file loading (uses single dummy angle)\n - Fastest analysis mode\n- **When to Use**: Isotropic samples, quick validation runs, preliminary analysis\n- **Model**: $g_1(t_1,t_2) = \\exp(-q^2 \\int_{t_1}^{t_2} D(t)dt)$ with no angular dependence\n\n### Static Anisotropic Mode (3 parameters)\n- **Physical Context**: Analysis of systems at equilibrium with angular dependence but no flow effects\n- **Parameters**: $D_0$, $\\alpha$, $D_{\\text{offset}}$ (same as isotropic mode)\n- **Key Features**:\n - Angle filtering enabled for optimization efficiency\n - phi_angles_file loaded for angle information\n - Per-angle scaling optimization\n- **When to Use**: Static samples with measurable angular variations, moderate computational resources\n- **Model**: Same as isotropic mode but with angle filtering to focus optimization on specific angular ranges\n\n### Laminar Flow Mode (7 parameters) \n- **Physical Context**: Analysis of systems under controlled shear flow conditions with full physics model\n- **Parameters**: \n - $D_0$, $\\alpha$, $D_{\\text{offset}}$: Same as static modes\n - $\\dot{\\gamma}_0$: Characteristic shear rate\n - $\\beta$: Shear rate exponent for flow scaling\n - $\\dot{\\gamma}_{\\text{offset}}$: Baseline shear component\n - $\\phi_0$: Angular offset parameter for flow geometry\n- **Key Features**:\n - All flow and diffusion effects included\n - phi_angles_file required for angle-dependent flow effects\n - Complex parameter space with potential correlations\n- **When to Use**: Systems under shear, nonequilibrium conditions, transport coefficient analysis\n- **Model**: $g_1(t_1,t_2) = g_{1,\\text{diff}}(t_1,t_2) \\times g_{1,\\text{shear}}(t_1,t_2)$ where shear effects are $\\text{sinc}^2(\\Phi)$\n\n## Usage Examples\n\n### Command Line Interface\n\n```bash\n# Basic analysis\nhomodyne --static-isotropic --method classical\nhomodyne --static-anisotropic --method mcmc\nhomodyne --laminar-flow --method all\n\n# Data validation only\nhomodyne --plot-experimental-data --config my_config.json\n\n# Custom configuration and output\nhomodyne --config my_experiment.json --output-dir ./results\n\n# Generate C2 heatmaps\nhomodyne --method classical --plot-c2-heatmaps\n```\n\n### Data Validation\n\nGenerate validation plots without fitting:\n\n```bash\nhomodyne --plot-experimental-data --config my_config.json --verbose\n```\n\n**Output**: Creates plots in `./homodyne_results/exp_data/`:\n- 2D correlation function heatmaps $g_2(t_1,t_2)$\n- Diagonal slices $g_2(t,t)$ showing decay\n- Statistical summaries and quality metrics\n\n## Configuration\n\n### Creating Configurations\n\n```bash\n# Generate configuration templates\nhomodyne-config --mode static_isotropic --sample protein_01\nhomodyne-config --mode laminar_flow --sample microgel\n```\n\n### Mode Selection\n\nConfiguration files specify analysis mode:\n\n```json\n{\n \"analysis_settings\": {\n \"static_mode\": true/false,\n \"static_submode\": \"isotropic\" | \"anisotropic\" | null\n }\n}\n```\n\n**Rules**:\n- `static_mode: false` \u2192 Laminar Flow Mode (7 params)\n- `static_mode: true, static_submode: \"isotropic\"` \u2192 Static Isotropic (3 params)\n- `static_mode: true, static_submode: \"anisotropic\"` \u2192 Static Anisotropic (3 params)\n\n### Quality Control\n\nCheck data quality before fitting:\n\n```bash\nhomodyne --plot-experimental-data --verbose\n```\n\n**Look for**:\n- Mean values around 1.0 ($g_2$ correlation functions)\n- Enhanced diagonal values\n- Sufficient contrast (> 0.001)\n\n## Performance & Testing\n\n### Optimization Methods\n\n**Classical (Fast)**\n- Algorithm: Nelder-Mead simplex with vectorized operations\n- Speed: ~minutes (optimized with lazy imports and memory-efficient operations)\n- Use: Exploratory analysis, parameter screening\n- Command: `--method classical`\n\n**Bayesian MCMC (Comprehensive)**\n- Algorithm: NUTS sampler via PyMC (lazy-loaded for fast startup)\n- Speed: ~hours (with Numba JIT acceleration and optional thinning)\n- Features: Uncertainty quantification, thinning support, convergence diagnostics\n- Use: Uncertainty quantification, publication results\n- Command: `--method mcmc`\n\n**Combined**\n- Workflow: Classical \u2192 MCMC refinement\n- Command: `--method all`\n\n### Performance Optimizations\n\nThe package includes comprehensive performance optimizations:\n\n**\ud83d\ude80 Computational Optimizations:**\n- **Numba JIT compilation**: 3-5x speedup for core kernels with comprehensive warmup\n- **Vectorized operations**: NumPy-optimized angle filtering and array operations\n- **Memory-efficient processing**: Lazy allocation and memory-mapped file loading\n- **Enhanced caching**: Fast cache key generation for NumPy arrays\n- **Stable benchmarking**: Outlier filtering and variance reduction for reliable performance testing\n\n**\u26a1 Import Optimizations:**\n- **Lazy loading**: Heavy dependencies loaded only when needed\n- **Fast startup**: >99% reduction in import time for optional components\n- **Modular imports**: Core functionality available without heavy dependencies\n\n**\ud83c\udfaf MCMC Optimizations:**\n- **Thinning support**: Configurable sample thinning to reduce autocorrelation and memory usage\n- **Smart defaults**: Mode-aware thinning settings (thin=1 for laminar flow, thin=2 for static modes)\n- **Convergence diagnostics**: R-hat, ESS, and mixing assessment with thinning recommendations\n\n**\ud83d\udcca Memory Optimizations:**\n- **Memory-mapped I/O**: Efficient loading of large experimental datasets\n- **Lazy array allocation**: Reduced peak memory usage\n- **Garbage collection optimization**: Automatic cleanup of temporary objects\n\n**\ud83d\udd27 Recent Performance Enhancements (v2024.2):**\n- **Enhanced JIT warmup**: Comprehensive function-level warmup reduces timing variance by 60%\n- **Stable benchmarking**: Statistical outlier filtering for reliable performance measurement\n- **Consolidated performance utilities**: Unified performance testing infrastructure\n- **Improved type safety**: Enhanced type annotations and consistency checks\n\n## Physical Constraints and Parameter Ranges\n\n### Parameter Distributions and Constraints\n\nThe homodyne package implements comprehensive physical constraints to ensure scientifically meaningful results:\n\n#### **Core Model Parameters**\n\n| Parameter | Range | Distribution | Physical Constraint |\n|-----------|-------|--------------|-------------------|\n| `D0` | [1.0, 1000000.0] \u00c5\u00b2/s | TruncatedNormal(\u03bc=10000.0, \u03c3=1000.0) | positive |\n| `alpha` | [-2.0, 2.0] dimensionless | Normal(\u03bc=-1.5, \u03c3=0.1) | none |\n| `D_offset` | [-100, 100] \u00c5\u00b2/s | Normal(\u03bc=0.0, \u03c3=10.0) | none |\n| `gamma_dot_t0` | [1e-06, 1.0] s\u207b\u00b9 | TruncatedNormal(\u03bc=0.001, \u03c3=0.01) | positive |\n| `beta` | [-2.0, 2.0] dimensionless | Normal(\u03bc=0.0, \u03c3=0.1) | none |\n| `gamma_dot_t_offset` | [-0.01, 0.01] s\u207b\u00b9 | Normal(\u03bc=0.0, \u03c3=0.001) | none |\n| `phi0` | [-10, 10] degrees | Normal(\u03bc=0.0, \u03c3=5.0) | angular |\n\n#### **Physical Function Constraints**\n\nThe package **automatically enforces positivity** for time-dependent functions:\n\n- **D(t) = D\u2080(t)^\u03b1 + D_offset** \u2192 **max(D(t), 1\u00d710\u207b\u00b9\u2070)**\n - Prevents negative diffusion coefficients\n - Maintains numerical stability with minimal threshold\n\n- **\u03b3\u0307(t) = \u03b3\u0307\u2080(t)^\u03b2 + \u03b3\u0307_offset** \u2192 **max(\u03b3\u0307(t), 1\u00d710\u207b\u00b9\u2070)**\n - Prevents negative shear rates\n - Ensures physical validity in all optimization scenarios\n\n#### **Scaling Parameters for Correlation Functions**\n\nThe relationship **c2_fitted = c2_theory \u00d7 contrast + offset** uses bounded parameters:\n\n| Parameter | Range | Distribution | Physical Meaning |\n|-----------|-------|--------------|------------------|\n| `contrast` | (0.05, 0.5] | TruncatedNormal(\u03bc=0.3, \u03c3=0.1) | Correlation strength scaling |\n| `offset` | (0.05, 1.95] | TruncatedNormal(\u03bc=1.0, \u03c3=0.2) | Baseline correlation level |\n| `c2_fitted` | [1.0, 2.0] | *derived* | Final correlation function range |\n| `c2_theory` | [0.0, 1.0] | *derived* | Theoretical correlation bounds |\n\n\n### MCMC Configuration\n\n**Optimized MCMC Settings:**\n- **target_accept = 0.95**: High acceptance rate for constrained sampling\n- **Distribution-aware priors**: TruncatedNormal for positive parameters, Normal otherwise \n- **Configuration-driven**: All parameters read from JSON files for consistency\n#### Static Isotropic (3 parameters)\n{\n \"draws\": 8000,\n \"thin\": 2, # Effective samples: 4000\n \"chains\": 4\n}\n\n#### Static Anisotropic (3 parameters) \n{\n \"draws\": 8000,\n \"thin\": 2, # Good convergence expected\n \"chains\": 4\n}\n\n#### Laminar Flow (7 parameters)\n{\n \"draws\": 10000,\n \"thin\": 1, # All samples needed for complex posterior\n \"chains\": 6\n}\n\n#### Memory-Constrained Systems\n{\n \"draws\": 5000,\n \"thin\": 5, # Effective samples: 1000\n \"chains\": 2\n}\n```\n\n**Thinning Benefits:**\n- \u2705 Reduces autocorrelation between samples\n- \u2705 Lower memory usage (fewer stored samples)\n- \u2705 Faster post-processing and plotting\n- \u2705 Better effective sample size per stored sample\n- \u26a0\ufe0f Trades total samples for independence\n\n### Performance Monitoring\n\n**Automated Performance Testing:**\n```bash\n# Quick performance validation\npython run_performance_tests.py --quick\n\n# Full performance test suite\npython run_performance_tests.py --full\n\n# Memory usage tests\npython run_performance_tests.py --memory\n\n# Update performance baselines after optimizations\npython run_performance_tests.py --update --quick\n```\n\n**Pytest Integration:**\n```bash\n# Performance tests with pytest\npytest -m performance # All performance tests\npytest -m \"performance and not slow\" # Quick tests (CI-friendly)\npytest -m benchmark --benchmark-only # Benchmarking tests\npytest -m memory # Memory usage tests\n```\n\n**Performance Benchmarking:**\n```bash\n# Comprehensive benchmark\npython performance_benchmark_optimized.py --detailed\n\n# Quick benchmark validation\npython performance_benchmark_optimized.py\n```\n\n### Scaling Optimization\n\nAlways enabled for scientific accuracy:\n\n$$g_2 = \\text{offset} + \\text{contrast} \\times g_1$$\n\nAccounts for instrumental effects, background, and normalization differences.\n\n### Environment Optimization\n\n```bash\n# Threading optimization for reproducible performance\nexport OMP_NUM_THREADS=8\nexport OPENBLAS_NUM_THREADS=8\nexport MKL_NUM_THREADS=8\nexport NUMBA_DISABLE_INTEL_SVML=1\n\n# Memory optimization\nexport NUMBA_CACHE_DIR=/tmp/numba_cache\n\n# Performance monitoring mode\nexport HOMODYNE_PERFORMANCE_MODE=1\n```\n\n### Testing Framework\n\n**Standard Testing:**\n```bash\npython homodyne/run_tests.py # Standard tests\npython homodyne/run_tests.py --fast # Quick tests \npython homodyne/run_tests.py --coverage # With coverage\npytest # Pytest runner\n```\n\n**Performance Testing:**\n```bash\n# Performance validation\npython run_performance_tests.py --quick \n\n# Performance test suite\npytest -m performance \n\n# Regression detection\npytest -m regression \n\n# Stable benchmarking with statistical analysis\npytest -m benchmark --benchmark-only\n```\n\n**CI/CD Integration:**\n- **Automated testing**: Performance tests run on every PR\n- **Regression detection**: Automatic alerts for performance degradation\n- **Multi-platform**: Tests across Python 3.12, 3.13\n- **Baseline tracking**: Performance history and trend monitoring\n\n### Performance Documentation\n\n\ud83d\udcca **Detailed Performance Guides:**\n- [`docs/performance_optimization.md`](docs/performance_optimization.md) - Complete optimization details and testing framework guide\n\n### Output Organization\n\n```\n./homodyne_results/\n\u251c\u2500\u2500 classical/ # Classical method outputs\n\u2502 \u251c\u2500\u2500 experimental_data.npz\n\u2502 \u251c\u2500\u2500 fitted_data.npz\n\u2502 \u2514\u2500\u2500 residuals_data.npz\n\u251c\u2500\u2500 mcmc/ # MCMC method outputs \n\u2502 \u251c\u2500\u2500 mcmc_summary.json\n\u2502 \u251c\u2500\u2500 mcmc_trace.nc\n\u2502 \u251c\u2500\u2500 trace_plot.png\n\u2502 \u2514\u2500\u2500 corner_plot.png\n\u2514\u2500\u2500 exp_data/ # Data validation plots\n```\n\n## Theoretical Background\n\nThe package implements three key equations describing correlation functions in nonequilibrium laminar flow systems:\n\n**Equation 13 - Full Nonequilibrium Laminar Flow:**\n\n$$c_2(\\vec{q}, t_1, t_2) = 1 + \\beta\\left[e^{-q^2\\int J(t)dt}\\right] \\times \\text{sinc}^2\\left[\\frac{1}{2\\pi} qh \\int\\dot{\\gamma}(t)\\cos(\\phi(t))dt\\right]$$\n\n**Equation S-75 - Equilibrium Under Constant Shear:**\n\n$$c_2(\\vec{q}, t_1, t_2) = 1 + \\beta\\left[e^{-6q^2D(t_2-t_1)}\\right] \\text{sinc}^2\\left[\\frac{1}{2\\pi} qh \\cos(\\phi)\\dot{\\gamma}(t_2-t_1)\\right]$$\n\n**Equation S-76 - One-time Correlation (Siegert Relation):**\n\n$$g_2(\\vec{q}, \\tau) = 1 + \\beta\\left[e^{-6q^2D\\tau}\\right] \\text{sinc}^2\\left[\\frac{1}{2\\pi} qh \\cos(\\phi)\\dot{\\gamma}\\tau\\right]$$\n\n**Key Parameters:**\n- $\\vec{q}$: scattering wavevector [\u00c5\u207b\u00b9] \n- $h$: gap between stator and rotor [\u00c5]\n- $\\phi(t)$: angle between shear/flow direction and $\\vec{q}$ [degrees]\n- $\\dot{\\gamma}(t)$: time-dependent shear rate [s\u207b\u00b9]\n- $D(t)$: time-dependent diffusion coefficient [\u00c5\u00b2/s]\n- $\\beta$: contrast parameter [dimensionless]\n\n## Citation\n\nIf you use this package in your research, please cite:\n\n```bibtex\n@article{he2024transport,\n title={Transport coefficient approach for characterizing nonequilibrium dynamics in soft matter},\n 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},\n journal={Proceedings of the National Academy of Sciences},\n volume={121},\n number={31},\n pages={e2401162121},\n year={2024},\n publisher={National Academy of Sciences},\n doi={10.1073/pnas.2401162121}\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation\n\n\ud83d\udcda **Complete Documentation**: https://homodyne.readthedocs.io/\n\nIncludes user guides, API reference, and developer documentation.\n\n## Contributing\n\nWe welcome contributions! Please submit issues and pull requests.\n\n**Development setup:**\n```bash\ngit clone https://github.com/imewei/homodyne.git\ncd homodyne\npip install -e .[all]\npython homodyne/run_tests.py\n```\n\n**Authors:** Wei Chen, Hongrui He (Argonne National Laboratory)\n\n**License:** MIT\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Wei Chen\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Comprehensive Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions",
"version": "0.6.1",
"project_urls": {
"Documentation": "https://homodyne.readthedocs.io/",
"Homepage": "https://github.com/imewei/homodyne",
"Issues": "https://github.com/imewei/homodyne/issues",
"Repository": "https://github.com/imewei/homodyne"
},
"split_keywords": [
"xpcs",
" homodyne",
" scattering",
" correlation spectroscopy",
" soft matter",
" nonequilibrium dynamics",
" transport coefficients",
" bayesian analysis",
" mcmc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc83f94652c285d29dfaba870d6ed1a733f9190c96b0dc6ffe105bbb04f39422",
"md5": "30f04eec9d07d0ee1323e4bf3d831626",
"sha256": "e3012afed40a18a38158a6eb95022497f2292ed867b6564263d01a2b2c47a369"
},
"downloads": -1,
"filename": "homodyne_analysis-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30f04eec9d07d0ee1323e4bf3d831626",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 163236,
"upload_time": "2025-08-21T05:51:14",
"upload_time_iso_8601": "2025-08-21T05:51:14.153339Z",
"url": "https://files.pythonhosted.org/packages/fc/83/f94652c285d29dfaba870d6ed1a733f9190c96b0dc6ffe105bbb04f39422/homodyne_analysis-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f7ddb0a3d89f2bdc228ec2a09b1a0968e19841d5b8f316c4563d5da359ec449d",
"md5": "47f2531cd4c998f0c100326423b817e7",
"sha256": "0039f5535589c70ff2ad3df45853f48bddf3d5e635d464a5cc729c5fec4f03b4"
},
"downloads": -1,
"filename": "homodyne_analysis-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "47f2531cd4c998f0c100326423b817e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 192257,
"upload_time": "2025-08-21T05:51:15",
"upload_time_iso_8601": "2025-08-21T05:51:15.598735Z",
"url": "https://files.pythonhosted.org/packages/f7/dd/b0a3d89f2bdc228ec2a09b1a0968e19841d5b8f316c4563d5da359ec449d/homodyne_analysis-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 05:51:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imewei",
"github_project": "homodyne",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"<",
"2.3.0"
],
[
">=",
"1.24.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.3.0"
]
]
},
{
"name": "numba",
"specs": [
[
"<",
"0.62.0"
],
[
">=",
"0.61.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.8.0"
]
]
},
{
"name": "xpcs-viewer",
"specs": [
[
">=",
"1.0.4"
]
]
},
{
"name": "pymc",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "arviz",
"specs": [
[
">=",
"0.12.0"
]
]
},
{
"name": "pytensor",
"specs": [
[
">=",
"2.8.0"
]
]
},
{
"name": "corner",
"specs": [
[
">=",
"2.2.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.2.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.12.0"
]
]
},
{
"name": "pytest-xdist",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "pytest-benchmark",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
">=",
"3.6.0"
]
]
},
{
"name": "hypothesis",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"21.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"3.9.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"0.910"
]
]
},
{
"name": "types-psutil",
"specs": [
[
">=",
"5.9.0"
]
]
},
{
"name": "types-Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "types-six",
"specs": [
[
">=",
"1.16.0"
]
]
},
{
"name": "sphinx",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "sphinx-rtd-theme",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "myst-parser",
"specs": [
[
">=",
"0.17.0"
]
]
},
{
"name": "sphinx-autodoc-typehints",
"specs": [
[
">=",
"1.12.0"
]
]
},
{
"name": "numpydoc",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "linkify-it-py",
"specs": [
[
">=",
"2.0.0"
]
]
}
],
"lcname": "homodyne-analysis"
}
