homodyne-analysis

Name	homodyne-analysis JSON
Version	0.7.1 JSON
	download
home_page	None
Summary	High-performance Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions with comprehensive optimization methods, pre-commit hooks, and cross-platform shell completion
upload_time	2025-08-28 16:39:20
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 optimization bayesian-analysis mcmc robust-optimization trust-region-optimization gurobi jax high-performance-computing jit-compilation performance-optimization code-quality pre-commit-hooks shell-completion cross-platform windows-compatibility security-scanning
VCS
bugtrack_url
requirements	numpy scipy matplotlib
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Homodyne Scattering Analysis Package

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)
[![PyPI version](https://badge.fury.io/py/homodyne-analysis.svg)](https://badge.fury.io/py/homodyne-analysis)

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)
- **Multiple optimization methods**: Classical (Nelder-Mead, Gurobi), Robust
  (Wasserstein DRO, Scenario-based, Ellipsoidal), Bayesian MCMC (NUTS)
- **Noise-resistant analysis**: Robust optimization methods for measurement uncertainty
  and outlier resistance
- **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)
- [Robust Optimization](#robust-optimization)
- [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 Dependencies (always installed)

```bash
# Core scientific computing stack
numpy>=1.24.0,<2.3.0              # Array operations and linear algebra
scipy>=1.9.0                       # Scientific computing functions
matplotlib>=3.5.0                  # Plotting and visualization
```

#### Optional Dependencies by Feature

**Data Handling:**

```bash
pip install homodyne-analysis[data]
# Includes:
# - xpcs-viewer>=1.0.4             # XPCS data loading and visualization
```

**Performance Optimization:**

```bash
pip install homodyne-analysis[performance]
# Includes:
# - numba>=0.61.0,<0.62.0          # JIT compilation (3-5x speedup)
# - jax>=0.7.0                     # High-performance numerical computing
# - jaxlib>=0.4.35                 # JAX backend library
# - psutil>=5.8.0                  # Memory profiling and monitoring
```

**JAX Acceleration (GPU/TPU support):**

```bash
pip install homodyne-analysis[jax]
# Includes:
# - jax>=0.7.0                     # High-performance computations
# - jaxlib>=0.4.35                 # JAX backend with CPU/GPU support
```

**Bayesian MCMC Analysis:**

```bash
pip install homodyne-analysis[mcmc]
# Includes:
# - pymc>=5.0.0                    # Probabilistic programming
# - arviz>=0.12.0                  # Bayesian data analysis
# - pytensor>=2.8.0                # Tensor operations for PyMC
# - corner>=2.2.0                  # Corner plots for MCMC results
```

**Robust Optimization:**

```bash
pip install homodyne-analysis[robust]
# Includes:
# - cvxpy>=1.4.0                   # Convex optimization framework
```

**Gurobi Solver (requires license):**

```bash
pip install homodyne-analysis[gurobi]
# Includes:
# - gurobipy>=11.0.0               # Commercial optimization solver
```

**Documentation:**

```bash
pip install homodyne-analysis[docs]
# Includes:
# - sphinx>=4.0.0                  # Documentation generator
# - sphinx-rtd-theme>=1.0.0        # Read the Docs theme
# - myst-parser>=0.17.0            # Markdown support
# - sphinx-autodoc-typehints>=1.12.0  # Type hints in docs
# - numpydoc>=1.2.0                # NumPy-style docstrings
# - linkify-it-py>=2.0.0           # Link detection
```

**Testing Framework:**

```bash
pip install homodyne-analysis[test]
# Includes:
# - pytest>=6.2.0                  # Testing framework
# - pytest-cov>=2.12.0             # Coverage reporting
# - pytest-xdist>=2.3.0            # Parallel testing
# - pytest-benchmark>=4.0.0        # Performance benchmarking
# - pytest-mock>=3.6.0             # Mocking utilities
# - pytest-html>=4.1.1             # HTML test reports
# - pytest-metadata>=3.1.1         # Test metadata
# - hypothesis>=6.0.0               # Property-based testing
# - coverage>=6.2.0                 # Coverage measurement
```

**Code Quality and Security Tools:**

```bash
pip install homodyne-analysis[quality]
# Includes:
# - black>=23.0.0                  # Code formatter
# - isort>=5.12.0                  # Import sorter
# - flake8>=6.0.0                  # Style guide enforcement
# - mypy>=1.5.0                    # Type checker
# - ruff>=0.1.0                    # Modern linter and formatter
# - bandit>=1.8.0                  # Security linter
# - pip-audit>=2.6.0               # Dependency vulnerability scanner
```

**Type Checking Stubs:**

```bash
pip install homodyne-analysis[typing]
# Includes:
# - types-psutil>=5.9.0            # Type stubs for psutil
# - types-Pillow>=10.0.0           # Type stubs for Pillow
# - types-six>=1.16.0              # Type stubs for six
# - types-requests>=2.28.0         # Type stubs for requests
```

**Development Environment:**

```bash
pip install homodyne-analysis[dev]
# Includes all test, docs, quality, and typing dependencies plus:
# - pre-commit>=3.0.0              # Pre-commit hooks
# - tox>=4.0.0                     # Testing across environments
# - build>=0.10.0                  # Build tools
# - twine>=4.0.0                   # Package uploading
```

**All Features:**

```bash
pip install homodyne-analysis[all]
# Includes: data, performance, jax, mcmc, robust, gurobi, dev
# Complete installation with all optional dependencies
```

#### Quick Installation Commands

**For most users:**

```bash
pip install homodyne-analysis[performance,mcmc,robust]  # Core analysis features
```

**For developers:**

```bash
pip install homodyne-analysis[all]  # Everything included
```

**For high-performance computing:**

```bash
pip install homodyne-analysis[performance,jax,gurobi]  # Maximum performance
```

## 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

# Run only robust optimization (noise-resistant)
homodyne --config my_config.json --method robust
```

## CLI Commands

The homodyne package provides two main command-line tools:

### 1. `homodyne` - Main Analysis Command

```bash
# Usage: homodyne [OPTIONS]

# Basic examples
homodyne                                    # Default classical method
homodyne --method robust                    # Robust optimization only  
homodyne --method mcmc                      # MCMC sampling only
homodyne --method all --verbose             # All methods with debug logging

# Analysis mode control
homodyne --static-isotropic                 # Force 3-parameter isotropic mode
homodyne --static-anisotropic               # Force 3-parameter anisotropic mode  
homodyne --laminar-flow                     # Force 7-parameter flow mode

# Data visualization  
homodyne --plot-experimental-data           # Validate experimental data
homodyne --plot-simulated-data              # Plot theoretical correlations
homodyne --plot-simulated-data --contrast 1.5 --offset 0.1 --phi-angles "0,45,90,135"

# Configuration and output
homodyne --config my_config.json --output-dir ./results --verbose
homodyne --quiet                            # File logging only, no console output
```

### 2. `homodyne-config` - Configuration Generator

```bash
# Usage: homodyne-config [OPTIONS]

# Basic examples
homodyne-config                             # Default laminar_flow config
homodyne-config --mode static_isotropic     # Fastest analysis mode
homodyne-config --mode static_anisotropic   # Static with angle filtering

# With metadata
homodyne-config --sample protein_sample --author "Your Name" --experiment "Protein dynamics"
homodyne-config --mode laminar_flow --output custom_config.json --sample microgel
```

**See [CLI_REFERENCE.md](CLI_REFERENCE.md) for complete command-line documentation.**

## Shell Completion & Shortcuts

The homodyne CLI includes robust completion and shortcut systems for enhanced
productivity with full cross-platform support:

### Quick Setup

```bash
# Install completion support
pip install homodyne-analysis[completion]

# Enable for your shell (one-time setup)
homodyne --install-completion bash     # Linux/macOS
homodyne --install-completion zsh      # macOS default
homodyne --install-completion fish     # Fish shell
homodyne --install-completion powershell  # Windows PowerShell

# Restart shell or reload config
source ~/.bashrc   # Linux
source ~/.zshrc    # macOS
# Windows PowerShell: restart terminal

# To remove completion later
homodyne --uninstall-completion bash   # or zsh, fish, powershell
```

### Available Features

**🔥 Command Shortcuts (Always Available):**

```bash
hc          # homodyne --method classical
hm          # homodyne --method mcmc
hr          # homodyne --method robust  
ha          # homodyne --method all
hconfig     # homodyne --config
hplot       # homodyne --plot-experimental-data
```

**⚡ Tab Completion (When Working):**

```bash
homodyne --method <TAB>     # Shows: classical, mcmc, robust, all
homodyne --config <TAB>     # Shows available .json files
homodyne --output-dir <TAB> # Shows available directories
```

**📋 Help System:**

```bash
homodyne_help              # Show all available options and current config files
```

### Usage Examples

```bash
# Using shortcuts for quick analysis
hc --verbose               # homodyne --method classical --verbose
hr --config my_data.json   # homodyne --method robust --config my_data.json
ha                         # homodyne --method all

# Check what's available
homodyne_help             # Shows methods, config files, flags
```

**Python API:**

```python
from homodyne import HomodyneAnalysisCore, ConfigManager

config = ConfigManager("config.json")
analysis = HomodyneAnalysisCore(config)
results = analysis.optimize_classical()  # Fast (includes robust methods)
results = analysis.optimize_robust()     # Robust methods only
results = analysis.optimize_all()        # Classical + Robust + 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 robust    # NEW: Robust optimization only
homodyne --laminar-flow --method all

# Robust optimization examples (noise-resistant)
homodyne --method robust                         # Run all robust methods
homodyne --method robust --static-isotropic      # Robust in static mode
homodyne --method robust --config noisy_data.json # Robust for noisy data

# Data validation only
homodyne --plot-experimental-data --config my_config.json

# Custom configuration and output
homodyne --config my_experiment.json --output-dir ./results

# Logging control options
homodyne --verbose                              # Debug logging to console and file
homodyne --quiet                               # File logging only, no console output
homodyne --config my_config.json --quiet       # Quiet mode with custom config

# Generate C2 heatmaps
homodyne --method classical --plot-c2-heatmaps
```

### Data Validation and Plotting

#### Experimental Data Visualization

Generate validation plots without fitting:

```bash
homodyne --plot-experimental-data --config my_config.json --verbose
homodyne --plot-experimental-data --config my_config.json --quiet  # Quiet mode
```

**Output**: Creates plots in `./homodyne_results/exp_data/`:

- 2D correlation function heatmaps $c_2(t_1,t_2)$ for each phi angle
- Statistical summaries and quality metrics
- Simplified 2-column layout (heatmap + statistics)

**Supported Data Formats:**

- **HDF5 files**: Uses PyXPCS viewer library with exchange key
- **NPZ files**: Pre-processed correlation data with structure `(n_phi, n_t1, n_t2)`
- **Multiple phi angles**: Each angle plotted individually for comprehensive analysis

#### Simulated Data Visualization

Visualize theoretical and fitted correlation functions with scaling transformations:

```bash
# Basic simulated data plotting
homodyne --plot-simulated-data --config my_config.json

# With custom scaling parameters
homodyne --plot-simulated-data --config my_config.json --contrast 0.3 --offset 1.2

# Override phi angles from command line
homodyne --plot-simulated-data --config my_config.json --phi-angles 0,45,90,135
```

**Key Features:**

- **Scaling transformation**: `c2_fitted = contrast × c2_theoretical + offset`
- **Default scaling**: `contrast=1.0`, `offset=0.0` (no scaling)
- **Phi angles override**: Command-line `--phi-angles` overrides config file angles
- **Individual angle scaling**: `vmin = min(c2_data)` calculated per angle
- **Clean visualization**: No grid lines on heatmaps

**Data File Structure:**

- **Theoretical data**: `theoretical_c2_data.npz`
- **Fitted data**: `fitted_c2_data.npz`
- **Array format**: `c2_data(n_phi, n_t1, n_t2)`, `t1`, `t2`, `phi_angles`

**Usage Examples:**

```bash
# Validate experimental data quality
homodyne --plot-experimental-data --config experiment.json

# Compare theoretical predictions with scaling
homodyne --plot-simulated-data --config theory.json --contrast 0.25 --offset 1.1

# Multi-angle analysis with custom angles
homodyne --plot-simulated-data --config multi_angle.json --phi-angles 0,30,60,90,120,150
```

## Robust Optimization

**NEW**: Dedicated robust optimization methods for noise-resistant parameter estimation.

### Overview

The `--method robust` flag runs only robust optimization methods, designed to handle:

- **Measurement noise** and experimental uncertainties
- **Outliers** in correlation function data
- **Model misspecification** and systematic errors

### Available Robust Methods

| Method | Description | Best For | |--------|-------------|----------| |
**Robust-Wasserstein** | Distributionally Robust Optimization with Wasserstein
uncertainty sets | Noisy experimental data with theoretical guarantees | |
**Robust-Scenario** | Bootstrap scenario-based robust optimization | Data with outliers
and non-Gaussian noise | | **Robust-Ellipsoidal** | Ellipsoidal uncertainty sets
optimization | Well-characterized noise levels |

### Usage

```bash
# Run only robust methods (recommended for noisy data)
homodyne --method robust

# Robust optimization in different modes
homodyne --method robust --static-isotropic     # 3-parameter static
homodyne --method robust --laminar-flow         # 7-parameter flow

# Custom configuration for robust analysis
homodyne --method robust --config robust_config.json
```

### Key Features

- **Dedicated output**: Results saved to `/robust/` directory
- **Method comparison**: All three robust methods run, best chi-squared selected
- **Noise resistance**: 3-8% uncertainty tolerance (configurable)
- **Performance**: ~2-5x slower than classical, but uncertainty-resistant

### When to Use Robust Optimization

✅ **Use `--method robust` when:**

- Data has significant measurement noise (>2%)
- Outliers are present in correlation functions
- Systematic errors suspected in experimental setup
- Need uncertainty-resistant parameter estimates

❌ **Use `--method classical` when:**

- Clean, low-noise data (\<1% uncertainty)
- Fast parameter estimation needed
- Comparing with previous classical results

## 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)

### Logging Control

The package provides flexible logging control for different use cases:

| Option | Console Output | File Output | Use Case |
|--------|---------------|-------------|----------| | **Default** | INFO level | INFO
level | Normal interactive analysis | | **`--verbose`** | DEBUG level | DEBUG level |
Detailed troubleshooting and debugging | | **`--quiet`** | None | INFO level | Batch
processing, scripting, clean output |

```bash
# Detailed debugging information
homodyne --verbose --method all

# Quiet execution (logs only to file)
homodyne --quiet --method classical --output-dir ./batch_results

# Cannot combine conflicting options
homodyne --verbose --quiet  # ERROR: conflicting options
```

**File Logging**: All modes save detailed logs to `output_dir/run.log` for analysis
tracking and debugging, regardless of console settings.

## Performance & Testing

### Optimization Methods

**Classical Optimization (Fast)**

- **Nelder-Mead**: Derivative-free simplex algorithm, robust for noisy functions
- **Gurobi**: Iterative quadratic programming with trust region optimization (requires
  license), excellent for smooth functions with parameter bounds
- 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`

**Note**: Gurobi is automatically detected if installed and licensed. Both classical
methods are attempted if available, with the best result selected based on chi-squared
value. All optimization methods (Nelder-Mead, Gurobi, MCMC) use the same parameter
bounds defined in the configuration for consistency.

### 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

## 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 |

### 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
```

### Output Organization

```
./homodyne_results/
├── homodyne_analysis_results.json    # Main results with config and metadata
├── run.log                          # Execution log file
├── classical/                      # Classical optimization results (if run)
│   ├── all_classical_methods_summary.json
│   ├── nelder_mead/                # Method-specific directory
│   │   ├── analysis_results_nelder_mead.json
│   │   ├── parameters.json
│   │   ├── fitted_data.npz         # Experimental, fitted, residuals data
│   │   ├── c2_heatmaps_nelder_mead_phi_*.png
│   │   └── nelder_mead_diagnostic_summary.png
│   ├── gurobi/                     # Gurobi method directory (if available)
│   │   ├── analysis_results_gurobi.json
│   │   ├── parameters.json
│   │   ├── fitted_data.npz
│   │   └── c2_heatmaps_gurobi_phi_*.png
│   └── ...                         # Other classical methods
├── robust/                         # Robust optimization results (if run)
│   ├── all_robust_methods_summary.json
│   ├── wasserstein/               # Robust method directories
│   │   ├── analysis_results_wasserstein.json
│   │   ├── parameters.json
│   │   ├── fitted_data.npz
│   │   └── c2_heatmaps_wasserstein_phi_*.png
│   ├── scenario/
│   ├── ellipsoidal/
│   └── ...
├── mcmc/                          # MCMC results (if run)
│   ├── mcmc_summary.json          # MCMC summary statistics
│   ├── mcmc_trace.nc              # NetCDF trace file
│   ├── experimental_data.npz      # Original experimental data
│   ├── fitted_data.npz            # MCMC fitted data
│   ├── residuals_data.npz         # Residuals
│   ├── c2_heatmaps_phi_*.png      # Heatmap plots per angle
│   ├── 3d_surface_phi_*.png       # 3D surface plots
│   ├── 3d_surface_residuals_phi_*.png
│   ├── trace_plot.png             # MCMC trace plots
│   └── corner_plot.png            # Parameter posterior distributions
├── exp_data/                      # Experimental data plots (if --plot-experimental-data)
│   ├── data_validation_phi_*.png  # Per-angle validation plots
│   └── summary_statistics.txt     # Data summary
└── simulated_data/               # Simulated data plots (if --plot-simulated-data)
    ├── simulated_c2_fitted_phi_*.png    # Simulated fitted data plots
    ├── theoretical_c2_phi_*.png         # Theoretical correlation plots
    ├── fitted_c2_data.npz              # Fitted data arrays
    └── theoretical_c2_data.npz         # Theoretical data arrays
```

**File Organization:**

- `homodyne_analysis_results.json`: Summary of all analysis methods (stays in root
  directory)
- `all_classical_methods_summary.json`: Summary of all classical methods in classical
  directory
- `all_robust_methods_summary.json`: Summary of all robust methods in robust directory
- **Method-specific directories**: Each optimization method has its own complete
  directory containing:
  - `analysis_results_[method_name].json`: Complete analysis results for the method
  - `parameters.json`: Fitted parameters with uncertainties, chi-squared values, and
    convergence information
  - `fitted_data.npz`: Complete numerical data (experimental, fitted, residuals,
    parameters, time arrays)
  - `c2_heatmaps_[method_name].png`: Method-specific correlation heatmaps
- **Standardized robust method names**: `wasserstein`, `scenario`, `ellipsoidal` for
  clean organization
- **No redundant files**: All data is organized within method-specific directories

## Common Output Structure for All Optimization Methods

### Classical Methods Directory Structure

```
./homodyne_results/classical/
├── nelder_mead/
└── gurobi/
```

### Robust Methods Directory Structure

```
./homodyne_results/robust/
├── wasserstein/      # Robust-Wasserstein method
├── scenario/         # Robust-Scenario method  
└── ellipsoidal/      # Robust-Ellipsoidal method
```

### Per-Method Files

Each method directory contains:

#### `parameters.json` - Human-readable parameter results

```json
{
  "method_name": "Nelder-Mead",
  "method_type": "Classical Optimization",
  "parameters": {
    "amplitude": {
      "value": 1.234,
      "uncertainty": 0.056,
      "unit": "arb"
    },
    "frequency": {
      "value": 2.678,
      "uncertainty": 0.123,
      "unit": "Hz"
    },
    "phase": {
      "value": 0.789,
      "uncertainty": 0.034,
      "unit": "rad"
    }
  },
  "goodness_of_fit": {
    "chi_squared": 0.523,
    "degrees_of_freedom": 397,
    "reduced_chi_squared": 0.00132
  },
  "convergence_info": {
    "success": true,
    "iterations": 150,
    "function_evaluations": 280,
    "message": "Optimization terminated successfully"
  },
  "data_info": {
    "n_data_points": 400,
    "n_angles": 4,
    "n_time_points": 100
  }
}
```

#### `fitted_data.npz` - Consolidated Numerical Data Archive

**Complete data structure for each method:**

```python
import numpy as np

# Load method-specific data
data = np.load("fitted_data.npz")

# Primary correlation function data
c2_fitted = data["c2_fitted"]           # Method-specific fitted data (n_angles, n_t2, n_t1)
c2_experimental = data["c2_experimental"] # Original experimental data (n_angles, n_t2, n_t1)
residuals = data["residuals"]           # Method-specific residuals (n_angles, n_t2, n_t1)

# Parameter and fit results
parameters = data["parameters"]         # Fitted parameter values (n_params,)
uncertainties = data["uncertainties"]   # Parameter uncertainties (n_params,)
chi_squared = data["chi_squared"]       # Chi-squared goodness-of-fit (scalar)

# Coordinate arrays
phi_angles = data["phi_angles"]         # Angular coordinates (n_angles,) [degrees]
t1 = data["t1"]                        # First correlation time array (n_t1,) [seconds]
t2 = data["t2"]                        # Second correlation time array (n_t2,) [seconds]
```

**Key Features:**

- **Consolidated structure**: All method-specific data in a single NPZ file per method
- **Complete data access**: Experimental, fitted, and residual data together
- **Coordinate information**: Full time and angular coordinate arrays included
- **Statistical metadata**: Parameter uncertainties and goodness-of-fit metrics
- **Consistent format**: Same structure across all optimization methods (classical,
  robust, MCMC)

**Array Dimensions:**

- **Correlation functions**: `(n_angles, n_t2, n_t1)` - typically `(4, 60-100, 60-100)`
- **Parameters**: `(n_params,)` - 3 for static modes, 7 for laminar flow
- **Time arrays**: `(n_t1,)`, `(n_t2,)` - discretized with `dt` spacing
- **Angles**: `(n_angles,)` - typically `[0°, 45°, 90°, 135°]`

**Usage Examples:**

```python
# Calculate residual statistics
residual_rms = np.sqrt(np.mean(residuals**2))
residual_max = np.max(np.abs(residuals))

# Extract parameter with uncertainty
D0_value = parameters[0]
D0_error = uncertainties[0]
print(f"D0 = {D0_value:.2e} ± {D0_error:.2e}")

# Access time-resolved data at specific angle
angle_idx = 0  # First angle (typically 0°)
c2_at_angle = c2_fitted[angle_idx, :, :]  # Shape: (n_t2, n_t1)
```

### Method-Specific Characteristics

#### **Nelder-Mead**

```json
{
  "method_name": "Nelder-Mead",
  "method_type": "Classical Optimization",
  "convergence_info": {
    "success": true,
    "iterations": 150,
    "function_evaluations": 280,
    "message": "Optimization terminated successfully",
    "termination_reason": "ftol achieved"
  }
}
```

#### **Gurobi**

```json
{
  "method_name": "Gurobi",
  "method_type": "Classical Optimization",
  "convergence_info": {
    "success": true,
    "iterations": 50,
    "function_evaluations": 100,
    "message": "Optimal solution found",
    "solve_time": 1.23,
    "solver_status": "OPTIMAL"
  }
}
```

#### **Robust-Wasserstein**

```json
{
  "method_name": "Robust-Wasserstein",
  "method_type": "Robust Optimization",
  "robust_specific": {
    "uncertainty_radius": 0.03,
    "regularization_alpha": 0.01,
    "wasserstein_distance": 0.025
  },
  "convergence_info": {
    "success": true,
    "solve_time": 2.5,
    "status": "optimal"
  }
}
```

#### **Robust-Scenario**

```json
{
  "method_name": "Robust-Scenario",
  "method_type": "Robust Optimization",
  "robust_specific": {
    "n_scenarios": 50,
    "worst_case_value": 0.65,
    "scenario_weights": "uniform"
  },
  "convergence_info": {
    "success": true,
    "solve_time": 3.2,
    "status": "optimal"
  }
}
```

#### **Robust-Ellipsoidal**

```json
{
  "method_name": "Robust-Ellipsoidal",
  "method_type": "Robust Optimization",
  "robust_specific": {
    "uncertainty_set": "ellipsoidal",
    "ellipsoid_radius": 0.04,
    "confidence_level": 0.95
  },
  "convergence_info": {
    "success": true,
    "solve_time": 1.8,
    "status": "optimal"
  }
}
```

### Summary Files

#### `all_methods_summary.json` - Cross-method comparison

```json
{
  "analysis_type": "Classical Optimization",
  "timestamp": "2025-01-15T10:30:45Z",
  "methods_analyzed": ["Nelder-Mead", "Gurobi", "Robust-Wasserstein", "Robust-Scenario", "Robust-Ellipsoidal"],
  "best_method": "Gurobi",
  "results": {
    "Nelder-Mead": {
      "chi_squared": 0.523,
      "parameters": [1.234, 2.678, 0.789],
      "success": true
    },
    "Gurobi": {
      "chi_squared": 0.501,
      "parameters": [1.245, 2.689, 0.785],
      "success": true
    },
    "Robust-Wasserstein": {
      "chi_squared": 0.534,
      "parameters": [1.228, 2.665, 0.792],
      "success": true
    }
  }
}
```

### Key Differences Between Methods

**Classical Methods (Nelder-Mead, Gurobi)**

- Point estimates only with deterministic convergence metrics
- Faster execution with iterations and function evaluations tracking
- No built-in uncertainty quantification from optimization method

**Robust Methods (Wasserstein, Scenario, Ellipsoidal)**

- Robust optimization against data uncertainty with worst-case guarantees
- Additional robust-specific parameters (uncertainty radius, scenarios, confidence
  levels)
- Convex optimization solver status codes and solve times
- Enhanced reliability under data perturbations

## Diagnostic Summary Images Structure

The diagnostic summary images are comprehensive visualizations that combine multiple
analysis components into a single figure. Here's what they typically contain:

### 1. Main Diagnostic Summary Plot (`diagnostic_summary.png`)

**Location**: `./homodyne_results/diagnostic_summary.png` (root directory)

**Generated for**: Only `--method all` (comparison across multiple methods)

A **2×3 grid layout** containing:

#### Subplot 1: Method Comparison (Top Left)

- **Bar chart** comparing chi-squared values across different optimization methods
- **Y-axis**: Chi-squared values (log scale)
- **X-axis**: Method names (Nelder-Mead, Gurobi, Robust-Wasserstein, etc.)
- **Value labels** showing exact chi-squared values in scientific notation
- **Color coding** for different methods (C0, C1, C2, C3)

#### Subplot 2: Parameter Uncertainties (Top Middle)

- **Horizontal bar chart** showing parameter uncertainties
- **Y-axis**: Parameter names (amplitude, frequency, phase, etc.)
- **X-axis**: Uncertainty values (σ)
- **Includes grid lines** for better readability
- Shows **"No uncertainty data available"** if uncertainties aren't computed

#### Subplot 3: MCMC Convergence Diagnostics (Top Right)

- **Horizontal bar chart** of R̂ (R-hat) values for convergence assessment
- **Y-axis**: Parameter names
- **X-axis**: R̂ values (convergence metric)
- **Color coding**: Green (R̂ < 1.1), Orange (1.1 ≤ R̂ < 1.2), Red (R̂ ≥ 1.2)
- **Red dashed line** at R̂ = 1.1 (convergence threshold)
- Shows **"No MCMC convergence diagnostics available"** for classical-only methods

#### Subplot 4: Residuals Distribution Analysis (Bottom, Full Width)

- **Histogram** of residuals (experimental - theoretical data)
- **Overlay** of fitted normal distribution curve
- **Statistics**: Mean (μ) and standard deviation (σ) displayed
- **X-axis**: Residual values
- **Y-axis**: Probability density
- Shows **"No residuals data available"** if data is missing

### 2. Method-Specific Diagnostic Summaries (Removed)

**Note:** Method-specific diagnostic summary plots have been removed to reduce redundant
output. Only the main `diagnostic_summary.png` is generated for `--method all` to
provide meaningful cross-method comparisons.

### Diagnostic Plot Generation Summary

| Command | Main `diagnostic_summary.png` | Method-Specific Diagnostic Plots |
|---------|-------------------------------|-----------------------------------| |
`--method classical` | ❌ Not generated (single method) | ❌ Not generated | |
`--method robust` | ❌ Not generated (single method) | ❌ Not generated | |
`--method mcmc` | ❌ Not generated (single method) | ❌ Not generated | | `--method all` |
✅ Root directory | ❌ Not generated |

### 3. Additional Diagnostic/Visualization Outputs

#### C2 Correlation Heatmaps (`c2_heatmaps_*.png`)

- **2D heatmaps** showing experimental vs theoretical correlation functions
- **Individual plots** for each scattering angle (φ = 0°, 45°, 90°, 135°)
- **Method-specific** versions for each optimization approach
- **Time axes**: t₁ and t₂ (correlation delay times)
- **Color mapping**: Viridis colormap showing correlation intensity

#### MCMC-Specific Plots (when applicable)

- **`trace_plot.png`**: MCMC chain traces for each parameter
- **`corner_plot.png`**: Parameter posterior distributions and correlations

#### Data Validation Plots (`data_validation_*.png`)

- **Experimental data validation** plots
- **Individual plots** for each scattering angle
- **Full 2D heatmaps** and **cross-sections** of experimental data
- **Statistical summaries** and **quality metrics**

### Key Features of Diagnostic Summaries:

1. **Adaptive Content**: Shows appropriate placeholders when data is unavailable
1. **Cross-Method Comparison**: Allows comparison of different optimization approaches
1. **Quality Assessment**: Provides convergence and fitting quality metrics
1. **Statistical Analysis**: Includes residuals analysis and uncertainty quantification
1. **Professional Formatting**: Consistent styling with grid lines, proper labels, and
   legends

These diagnostic summaries provide researchers with a comprehensive overview of their
analysis quality, method performance, and parameter uncertainties all in a single
visualization.

## 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 Portal

**Primary Site**: https://homodyne.readthedocs.io/

### 📖 Available Documentation Resources

#### **User Documentation**

- **[Installation Guide](docs/user-guide/installation.rst)**: Complete installation
  instructions with dependency options
- **[Quickstart Tutorial](docs/user-guide/quickstart.rst)**: Get started with analysis
  in 5 minutes
- **[Configuration Guide](docs/user-guide/configuration.rst)**: Detailed configuration
  options and templates
- **[Analysis Modes](docs/user-guide/analysis-modes.rst)**: Static vs. laminar flow
  analysis modes
- **[Plotting & Visualization](docs/user-guide/plotting.rst)**: Data visualization and
  validation tools
- **[Examples & Use Cases](docs/user-guide/examples.rst)**: Real-world analysis examples

#### **Command Line Interface**

- **[CLI_REFERENCE.md](CLI_REFERENCE.md)**: Complete command-line documentation
- **Shell completion support** for bash, zsh, fish, and PowerShell
- **Interactive help system** with `homodyne_help` command

#### **Developer Resources**

- **[Architecture Overview](docs/developer-guide/architecture.rst)**: Package structure
  and design
- **[Contributing Guide](docs/developer-guide/contributing.rst)**: Development workflow
  and standards
- **[Performance Guide](docs/developer-guide/performance.rst)**: Optimization techniques
  and benchmarking
- **[Testing Framework](docs/developer-guide/testing.rst)**: Test organization and best
  practices
- **[Troubleshooting](docs/developer-guide/troubleshooting.rst)**: Common issues and
  solutions

#### **API Reference**

- **[Core Analysis](docs/api-reference/core.rst)**: Main analysis classes and functions
- **[Optimization Methods](docs/api-reference/mcmc.rst)**: MCMC, classical, and robust
  optimization
- **[Robust Methods](docs/api-reference/robust.rst)**: Noise-resistant optimization
  techniques
- **[Utilities](docs/api-reference/utilities.rst)**: Helper functions and data handling

#### **Reference Documentation**

- **[API_REFERENCE.md](API_REFERENCE.md)**: Comprehensive API documentation
- **[CHANGELOG.md](CHANGELOG.md)**: Version history and release notes
- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Development guidelines and standards

### 🚀 Recent Improvements (v0.7.1)

- **Windows Compatibility**: Fixed path separator issues in shell completion system for
  full cross-platform support
- **Pre-commit Hooks**: Comprehensive code quality framework with automatic formatting,
  linting, and security scanning
- **Shell Completion**: Enhanced tab completion with Windows path separator support and
  robust fallback mechanisms
- **Code Quality**: 100% Black and isort compliance, integrated Bandit security scanning
- **Test Reliability**: All CI tests pass consistently across Windows, macOS, and Linux
- **Type Safety**: Enhanced type annotations and MyPy configuration for scientific code
  patterns
- **Performance**: Optimized completion system with fast caching and memory efficiency
- **Security**: Zero medium/high severity security issues with comprehensive
  vulnerability scanning

### 📋 Quick Access

| Topic | Link | Description | |-------|------|-------------| | **Getting Started** |
[Quickstart](docs/user-guide/quickstart.rst) | 5-minute tutorial | | **CLI Commands** |
[CLI_REFERENCE.md](CLI_REFERENCE.md) | Complete command reference | | **Configuration**
| [Configuration Guide](docs/user-guide/configuration.rst) | Setup and templates | |
**API Usage** | [API_REFERENCE.md](API_REFERENCE.md) | Python API documentation | |
**Troubleshooting** | [Troubleshooting](docs/developer-guide/troubleshooting.rst) |
Common issues & solutions | | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) |
Development workflow |

### 💡 Documentation Features

- **Comprehensive coverage**: User guides, API reference, and developer documentation
- **Cross-platform compatibility**: Windows, macOS, and Linux instructions
- **Multiple analysis modes**: Static isotropic, anisotropic, and laminar flow
- **Security-focused**: Bandit integration for continuous security scanning
- **Performance-oriented**: Detailed optimization guides and benchmarking tools

## Development Status & Code Quality

**Code Formatting & Quality:**

- ✅ **Black**: 100% compliant (all files formatted with 88-character line length)
- ✅ **isort**: 100% compliant (imports sorted and optimized)
- ✅ **Ruff**: Fast linting and formatting with auto-fixes enabled
- ✅ **Bandit**: 0 medium/high severity security issues (comprehensive security scanning)
- ✅ **Pre-commit Hooks**: Automated code quality checks on every commit
- ⚠️ **flake8**: ~350 remaining style issues (primarily line length E501 in data
  scripts)
- ⚠️ **mypy**: ~250 type annotation issues (mainly missing library stubs for scientific
  packages)

**Security & Best Practices:**

- ✅ **Security scanning**: Integrated Bandit for continuous vulnerability detection (0
  medium/high severity issues)
- ✅ **Dependency vulnerability checking**: pip-audit integration for automated
  dependency security scanning
- ✅ **Cross-platform compatibility**: Windows, macOS, and Linux support with proper path
  handling
- ✅ **Dependency management**: Clean dependency tree with optional feature groups
- ✅ **Safe coding practices**: No hardcoded paths, secure file operations, proper error
  handling
- ✅ **Security configuration**: Properly configured security tools with scientific code
  patterns
- ✅ **Pre-commit security**: Automatic security checks on every commit
- ✅ **Shell completion security**: Safe command completion without shell injection risks

**Python Version Support:**

- **Required**: Python 3.12+ (enforced at package and CLI level)
- **Tested**: Python 3.12, 3.13
- **CI/CD**: Multi-platform testing (Ubuntu, Windows, macOS)
- **Compatibility**: Full Python 3.13 support with typing improvements

**Performance:**

- **JIT Compilation**: Numba warmup eliminates compilation overhead
- **JAX Integration**: Optional GPU acceleration for MCMC
- **Memory Management**: Automatic cleanup and smart caching
- **Benchmarking**: Comprehensive performance regression testing
- **Shell Completion**: Multi-tier fallback system for enhanced UX

## 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]

# Run tests
python homodyne/run_tests.py

# Code quality and security checks
black homodyne/                    # Format code
isort homodyne/                    # Sort imports  
flake8 homodyne/                   # Linting
mypy homodyne/                     # Type checking
bandit -r homodyne/                # Security scanning
pip-audit                          # Dependency vulnerability scanning
```

**Pre-commit hooks available for automated code quality checks.**

```bash
# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run hooks manually
pre-commit run --all-files
```

**Authors:** Wei Chen, Hongrui He (Argonne National Laboratory)

**License:** MIT

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "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, optimization, bayesian-analysis, mcmc, robust-optimization, trust-region-optimization, gurobi, jax, high-performance-computing, jit-compilation, performance-optimization, code-quality, pre-commit-hooks, shell-completion, cross-platform, windows-compatibility, security-scanning",
    "author": "Hongrui He",
    "author_email": "Wei Chen <wchen@anl.gov>",
    "download_url": "https://files.pythonhosted.org/packages/1e/b4/377079bef3c73de08e80753eb8ced41b0ef4f70cc8161240056eaf55b037/homodyne_analysis-0.7.1.tar.gz",
    "platform": null,
    "description": "# Homodyne Scattering Analysis Package\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)\n[![PyPI version](https://badge.fury.io/py/homodyne-analysis.svg)](https://badge.fury.io/py/homodyne-analysis)\n\nA high-performance Python package for analyzing homodyne scattering in X-ray Photon\nCorrelation Spectroscopy (XPCS) under nonequilibrium conditions. Implements the\ntheoretical framework from\n[He et al. PNAS 2024](https://doi.org/10.1073/pnas.2401162121) for characterizing\ntransport 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\nfluids under nonequilibrium conditions, capturing the interplay between Brownian\ndiffusion and advective shear flow.\n\n**Key Features:**\n\n- **Three analysis modes**: Static Isotropic (3 params), Static Anisotropic (3 params),\n  Laminar Flow (7 params)\n- **Multiple optimization methods**: Classical (Nelder-Mead, Gurobi), Robust\n  (Wasserstein DRO, Scenario-based, Ellipsoidal), Bayesian MCMC (NUTS)\n- **Noise-resistant analysis**: Robust optimization methods for measurement uncertainty\n  and outlier resistance\n- **High performance**: Numba JIT compilation with 3-5x speedup, vectorized operations,\n  and optimized memory usage\n- **Performance monitoring**: Comprehensive regression testing and automated\n  benchmarking\n- **Scientific accuracy**: Automatic $g_2 = \\\\text{offset} + \\\\text{contrast} \\\\times\n  g_1$ fitting for proper $\\\\chi^2$ calculations\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- [Robust Optimization](#robust-optimization)\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 Dependencies (always installed)\n\n```bash\n# Core scientific computing stack\nnumpy>=1.24.0,<2.3.0              # Array operations and linear algebra\nscipy>=1.9.0                       # Scientific computing functions\nmatplotlib>=3.5.0                  # Plotting and visualization\n```\n\n#### Optional Dependencies by Feature\n\n**Data Handling:**\n\n```bash\npip install homodyne-analysis[data]\n# Includes:\n# - xpcs-viewer>=1.0.4             # XPCS data loading and visualization\n```\n\n**Performance Optimization:**\n\n```bash\npip install homodyne-analysis[performance]\n# Includes:\n# - numba>=0.61.0,<0.62.0          # JIT compilation (3-5x speedup)\n# - jax>=0.7.0                     # High-performance numerical computing\n# - jaxlib>=0.4.35                 # JAX backend library\n# - psutil>=5.8.0                  # Memory profiling and monitoring\n```\n\n**JAX Acceleration (GPU/TPU support):**\n\n```bash\npip install homodyne-analysis[jax]\n# Includes:\n# - jax>=0.7.0                     # High-performance computations\n# - jaxlib>=0.4.35                 # JAX backend with CPU/GPU support\n```\n\n**Bayesian MCMC Analysis:**\n\n```bash\npip install homodyne-analysis[mcmc]\n# Includes:\n# - pymc>=5.0.0                    # Probabilistic programming\n# - arviz>=0.12.0                  # Bayesian data analysis\n# - pytensor>=2.8.0                # Tensor operations for PyMC\n# - corner>=2.2.0                  # Corner plots for MCMC results\n```\n\n**Robust Optimization:**\n\n```bash\npip install homodyne-analysis[robust]\n# Includes:\n# - cvxpy>=1.4.0                   # Convex optimization framework\n```\n\n**Gurobi Solver (requires license):**\n\n```bash\npip install homodyne-analysis[gurobi]\n# Includes:\n# - gurobipy>=11.0.0               # Commercial optimization solver\n```\n\n**Documentation:**\n\n```bash\npip install homodyne-analysis[docs]\n# Includes:\n# - sphinx>=4.0.0                  # Documentation generator\n# - sphinx-rtd-theme>=1.0.0        # Read the Docs theme\n# - myst-parser>=0.17.0            # Markdown support\n# - sphinx-autodoc-typehints>=1.12.0  # Type hints in docs\n# - numpydoc>=1.2.0                # NumPy-style docstrings\n# - linkify-it-py>=2.0.0           # Link detection\n```\n\n**Testing Framework:**\n\n```bash\npip install homodyne-analysis[test]\n# Includes:\n# - pytest>=6.2.0                  # Testing framework\n# - pytest-cov>=2.12.0             # Coverage reporting\n# - pytest-xdist>=2.3.0            # Parallel testing\n# - pytest-benchmark>=4.0.0        # Performance benchmarking\n# - pytest-mock>=3.6.0             # Mocking utilities\n# - pytest-html>=4.1.1             # HTML test reports\n# - pytest-metadata>=3.1.1         # Test metadata\n# - hypothesis>=6.0.0               # Property-based testing\n# - coverage>=6.2.0                 # Coverage measurement\n```\n\n**Code Quality and Security Tools:**\n\n```bash\npip install homodyne-analysis[quality]\n# Includes:\n# - black>=23.0.0                  # Code formatter\n# - isort>=5.12.0                  # Import sorter\n# - flake8>=6.0.0                  # Style guide enforcement\n# - mypy>=1.5.0                    # Type checker\n# - ruff>=0.1.0                    # Modern linter and formatter\n# - bandit>=1.8.0                  # Security linter\n# - pip-audit>=2.6.0               # Dependency vulnerability scanner\n```\n\n**Type Checking Stubs:**\n\n```bash\npip install homodyne-analysis[typing]\n# Includes:\n# - types-psutil>=5.9.0            # Type stubs for psutil\n# - types-Pillow>=10.0.0           # Type stubs for Pillow\n# - types-six>=1.16.0              # Type stubs for six\n# - types-requests>=2.28.0         # Type stubs for requests\n```\n\n**Development Environment:**\n\n```bash\npip install homodyne-analysis[dev]\n# Includes all test, docs, quality, and typing dependencies plus:\n# - pre-commit>=3.0.0              # Pre-commit hooks\n# - tox>=4.0.0                     # Testing across environments\n# - build>=0.10.0                  # Build tools\n# - twine>=4.0.0                   # Package uploading\n```\n\n**All Features:**\n\n```bash\npip install homodyne-analysis[all]\n# Includes: data, performance, jax, mcmc, robust, gurobi, dev\n# Complete installation with all optional dependencies\n```\n\n#### Quick Installation Commands\n\n**For most users:**\n\n```bash\npip install homodyne-analysis[performance,mcmc,robust]  # Core analysis features\n```\n\n**For developers:**\n\n```bash\npip install homodyne-analysis[all]  # Everything included\n```\n\n**For high-performance computing:**\n\n```bash\npip install homodyne-analysis[performance,jax,gurobi]  # Maximum performance\n```\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# Run only robust optimization (noise-resistant)\nhomodyne --config my_config.json --method robust\n```\n\n## CLI Commands\n\nThe homodyne package provides two main command-line tools:\n\n### 1. `homodyne` - Main Analysis Command\n\n```bash\n# Usage: homodyne [OPTIONS]\n\n# Basic examples\nhomodyne                                    # Default classical method\nhomodyne --method robust                    # Robust optimization only  \nhomodyne --method mcmc                      # MCMC sampling only\nhomodyne --method all --verbose             # All methods with debug logging\n\n# Analysis mode control\nhomodyne --static-isotropic                 # Force 3-parameter isotropic mode\nhomodyne --static-anisotropic               # Force 3-parameter anisotropic mode  \nhomodyne --laminar-flow                     # Force 7-parameter flow mode\n\n# Data visualization  \nhomodyne --plot-experimental-data           # Validate experimental data\nhomodyne --plot-simulated-data              # Plot theoretical correlations\nhomodyne --plot-simulated-data --contrast 1.5 --offset 0.1 --phi-angles \"0,45,90,135\"\n\n# Configuration and output\nhomodyne --config my_config.json --output-dir ./results --verbose\nhomodyne --quiet                            # File logging only, no console output\n```\n\n### 2. `homodyne-config` - Configuration Generator\n\n```bash\n# Usage: homodyne-config [OPTIONS]\n\n# Basic examples\nhomodyne-config                             # Default laminar_flow config\nhomodyne-config --mode static_isotropic     # Fastest analysis mode\nhomodyne-config --mode static_anisotropic   # Static with angle filtering\n\n# With metadata\nhomodyne-config --sample protein_sample --author \"Your Name\" --experiment \"Protein dynamics\"\nhomodyne-config --mode laminar_flow --output custom_config.json --sample microgel\n```\n\n**See [CLI_REFERENCE.md](CLI_REFERENCE.md) for complete command-line documentation.**\n\n## Shell Completion & Shortcuts\n\nThe homodyne CLI includes robust completion and shortcut systems for enhanced\nproductivity with full cross-platform support:\n\n### Quick Setup\n\n```bash\n# Install completion support\npip install homodyne-analysis[completion]\n\n# Enable for your shell (one-time setup)\nhomodyne --install-completion bash     # Linux/macOS\nhomodyne --install-completion zsh      # macOS default\nhomodyne --install-completion fish     # Fish shell\nhomodyne --install-completion powershell  # Windows PowerShell\n\n# Restart shell or reload config\nsource ~/.bashrc   # Linux\nsource ~/.zshrc    # macOS\n# Windows PowerShell: restart terminal\n\n# To remove completion later\nhomodyne --uninstall-completion bash   # or zsh, fish, powershell\n```\n\n### Available Features\n\n**\ud83d\udd25 Command Shortcuts (Always Available):**\n\n```bash\nhc          # homodyne --method classical\nhm          # homodyne --method mcmc\nhr          # homodyne --method robust  \nha          # homodyne --method all\nhconfig     # homodyne --config\nhplot       # homodyne --plot-experimental-data\n```\n\n**\u26a1 Tab Completion (When Working):**\n\n```bash\nhomodyne --method <TAB>     # Shows: classical, mcmc, robust, all\nhomodyne --config <TAB>     # Shows available .json files\nhomodyne --output-dir <TAB> # Shows available directories\n```\n\n**\ud83d\udccb Help System:**\n\n```bash\nhomodyne_help              # Show all available options and current config files\n```\n\n### Usage Examples\n\n```bash\n# Using shortcuts for quick analysis\nhc --verbose               # homodyne --method classical --verbose\nhr --config my_data.json   # homodyne --method robust --config my_data.json\nha                         # homodyne --method all\n\n# Check what's available\nhomodyne_help             # Shows methods, config files, flags\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 (includes robust methods)\nresults = analysis.optimize_robust()     # Robust methods only\nresults = analysis.optimize_all()        # Classical + Robust + MCMC\n```\n\n## Analysis Modes\n\nThe homodyne analysis package supports three distinct analysis modes, each optimized for\ndifferent experimental scenarios:\n\n| Mode | Parameters | Angle Handling | Use Case | Speed | Command |\n|------|------------|----------------|----------|-------|---------| | **Static\nIsotropic** | 3 | Single dummy | Fastest, isotropic systems | \u2b50\u2b50\u2b50 | `--static-isotropic`\n| | **Static Anisotropic** | 3 | Filtering enabled | Static with angular deps | \u2b50\u2b50 |\n`--static-anisotropic` | | **Laminar Flow** | 7 | Full coverage | Flow & shear analysis\n| \u2b50 | `--laminar-flow` |\n\n### Static Isotropic Mode (3 parameters)\n\n- **Physical Context**: Analysis of systems at equilibrium with isotropic scattering\n  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\n  dependence\n\n### Static Anisotropic Mode (3 parameters)\n\n- **Physical Context**: Analysis of systems at equilibrium with angular dependence but\n  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\n  computational resources\n- **Model**: Same as isotropic mode but with angle filtering to focus optimization on\n  specific angular ranges\n\n### Laminar Flow Mode (7 parameters)\n\n- **Physical Context**: Analysis of systems under controlled shear flow conditions with\n  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\n  analysis\n- **Model**: $g_1(t_1,t_2) = g\\_{1,\\\\text{diff}}(t_1,t_2) \\\\times\n  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 robust    # NEW: Robust optimization only\nhomodyne --laminar-flow --method all\n\n# Robust optimization examples (noise-resistant)\nhomodyne --method robust                         # Run all robust methods\nhomodyne --method robust --static-isotropic      # Robust in static mode\nhomodyne --method robust --config noisy_data.json # Robust for noisy data\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# Logging control options\nhomodyne --verbose                              # Debug logging to console and file\nhomodyne --quiet                               # File logging only, no console output\nhomodyne --config my_config.json --quiet       # Quiet mode with custom config\n\n# Generate C2 heatmaps\nhomodyne --method classical --plot-c2-heatmaps\n```\n\n### Data Validation and Plotting\n\n#### Experimental Data Visualization\n\nGenerate validation plots without fitting:\n\n```bash\nhomodyne --plot-experimental-data --config my_config.json --verbose\nhomodyne --plot-experimental-data --config my_config.json --quiet  # Quiet mode\n```\n\n**Output**: Creates plots in `./homodyne_results/exp_data/`:\n\n- 2D correlation function heatmaps $c_2(t_1,t_2)$ for each phi angle\n- Statistical summaries and quality metrics\n- Simplified 2-column layout (heatmap + statistics)\n\n**Supported Data Formats:**\n\n- **HDF5 files**: Uses PyXPCS viewer library with exchange key\n- **NPZ files**: Pre-processed correlation data with structure `(n_phi, n_t1, n_t2)`\n- **Multiple phi angles**: Each angle plotted individually for comprehensive analysis\n\n#### Simulated Data Visualization\n\nVisualize theoretical and fitted correlation functions with scaling transformations:\n\n```bash\n# Basic simulated data plotting\nhomodyne --plot-simulated-data --config my_config.json\n\n# With custom scaling parameters\nhomodyne --plot-simulated-data --config my_config.json --contrast 0.3 --offset 1.2\n\n# Override phi angles from command line\nhomodyne --plot-simulated-data --config my_config.json --phi-angles 0,45,90,135\n```\n\n**Key Features:**\n\n- **Scaling transformation**: `c2_fitted = contrast \u00d7 c2_theoretical + offset`\n- **Default scaling**: `contrast=1.0`, `offset=0.0` (no scaling)\n- **Phi angles override**: Command-line `--phi-angles` overrides config file angles\n- **Individual angle scaling**: `vmin = min(c2_data)` calculated per angle\n- **Clean visualization**: No grid lines on heatmaps\n\n**Data File Structure:**\n\n- **Theoretical data**: `theoretical_c2_data.npz`\n- **Fitted data**: `fitted_c2_data.npz`\n- **Array format**: `c2_data(n_phi, n_t1, n_t2)`, `t1`, `t2`, `phi_angles`\n\n**Usage Examples:**\n\n```bash\n# Validate experimental data quality\nhomodyne --plot-experimental-data --config experiment.json\n\n# Compare theoretical predictions with scaling\nhomodyne --plot-simulated-data --config theory.json --contrast 0.25 --offset 1.1\n\n# Multi-angle analysis with custom angles\nhomodyne --plot-simulated-data --config multi_angle.json --phi-angles 0,30,60,90,120,150\n```\n\n## Robust Optimization\n\n**NEW**: Dedicated robust optimization methods for noise-resistant parameter estimation.\n\n### Overview\n\nThe `--method robust` flag runs only robust optimization methods, designed to handle:\n\n- **Measurement noise** and experimental uncertainties\n- **Outliers** in correlation function data\n- **Model misspecification** and systematic errors\n\n### Available Robust Methods\n\n| Method | Description | Best For | |--------|-------------|----------| |\n**Robust-Wasserstein** | Distributionally Robust Optimization with Wasserstein\nuncertainty sets | Noisy experimental data with theoretical guarantees | |\n**Robust-Scenario** | Bootstrap scenario-based robust optimization | Data with outliers\nand non-Gaussian noise | | **Robust-Ellipsoidal** | Ellipsoidal uncertainty sets\noptimization | Well-characterized noise levels |\n\n### Usage\n\n```bash\n# Run only robust methods (recommended for noisy data)\nhomodyne --method robust\n\n# Robust optimization in different modes\nhomodyne --method robust --static-isotropic     # 3-parameter static\nhomodyne --method robust --laminar-flow         # 7-parameter flow\n\n# Custom configuration for robust analysis\nhomodyne --method robust --config robust_config.json\n```\n\n### Key Features\n\n- **Dedicated output**: Results saved to `/robust/` directory\n- **Method comparison**: All three robust methods run, best chi-squared selected\n- **Noise resistance**: 3-8% uncertainty tolerance (configurable)\n- **Performance**: ~2-5x slower than classical, but uncertainty-resistant\n\n### When to Use Robust Optimization\n\n\u2705 **Use `--method robust` when:**\n\n- Data has significant measurement noise (>2%)\n- Outliers are present in correlation functions\n- Systematic errors suspected in experimental setup\n- Need uncertainty-resistant parameter estimates\n\n\u274c **Use `--method classical` when:**\n\n- Clean, low-noise data (\\<1% uncertainty)\n- Fast parameter estimation needed\n- Comparing with previous classical results\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\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\n- Mean values around 1.0 ($g_2$ correlation functions)\n- Enhanced diagonal values\n- Sufficient contrast (> 0.001)\n\n### Logging Control\n\nThe package provides flexible logging control for different use cases:\n\n| Option | Console Output | File Output | Use Case |\n|--------|---------------|-------------|----------| | **Default** | INFO level | INFO\nlevel | Normal interactive analysis | | **`--verbose`** | DEBUG level | DEBUG level |\nDetailed troubleshooting and debugging | | **`--quiet`** | None | INFO level | Batch\nprocessing, scripting, clean output |\n\n```bash\n# Detailed debugging information\nhomodyne --verbose --method all\n\n# Quiet execution (logs only to file)\nhomodyne --quiet --method classical --output-dir ./batch_results\n\n# Cannot combine conflicting options\nhomodyne --verbose --quiet  # ERROR: conflicting options\n```\n\n**File Logging**: All modes save detailed logs to `output_dir/run.log` for analysis\ntracking and debugging, regardless of console settings.\n\n## Performance & Testing\n\n### Optimization Methods\n\n**Classical Optimization (Fast)**\n\n- **Nelder-Mead**: Derivative-free simplex algorithm, robust for noisy functions\n- **Gurobi**: Iterative quadratic programming with trust region optimization (requires\n  license), excellent for smooth functions with parameter bounds\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\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\n- Workflow: Classical \u2192 MCMC refinement\n- Command: `--method all`\n\n**Note**: Gurobi is automatically detected if installed and licensed. Both classical\nmethods are attempted if available, with the best result selected based on chi-squared\nvalue. All optimization methods (Nelder-Mead, Gurobi, MCMC) use the same parameter\nbounds defined in the configuration for consistency.\n\n### Performance Optimizations\n\nThe package includes comprehensive performance optimizations:\n\n**\ud83d\ude80 Computational Optimizations:**\n\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\n  performance testing\n\n**\u26a1 Import Optimizations:**\n\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## Physical Constraints and Parameter Ranges\n\n### Parameter Distributions and Constraints\n\nThe homodyne package implements comprehensive physical constraints to ensure\nscientifically meaningful results:\n\n#### **Core Model Parameters**\n\n| Parameter | Range | Distribution | Physical Constraint |\n|-----------|-------|--------------|-------------------| | `D0` | [1.0, 1000000.0] \u00c5\u00b2/s\n| TruncatedNormal(\u03bc=10000.0, \u03c3=1000.0) | positive | | `alpha` | [-2.0, 2.0]\ndimensionless | Normal(\u03bc=-1.5, \u03c3=0.1) | none | | `D_offset` | [-100, 100] \u00c5\u00b2/s |\nNormal(\u03bc=0.0, \u03c3=10.0) | none | | `gamma_dot_t0` | [1e-06, 1.0] s\u207b\u00b9 |\nTruncatedNormal(\u03bc=0.001, \u03c3=0.01) | positive | | `beta` | [-2.0, 2.0] dimensionless |\nNormal(\u03bc=0.0, \u03c3=0.1) | none | | `gamma_dot_t_offset` | [-0.01, 0.01] s\u207b\u00b9 | Normal(\u03bc=0.0,\n\u03c3=0.001) | none | | `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\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\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|-----------|-------|--------------|------------------| | `contrast` | (0.05, 0.5\\] |\nTruncatedNormal(\u03bc=0.3, \u03c3=0.1) | Correlation strength scaling | | `offset` | (0.05,\n1.95\\] | TruncatedNormal(\u03bc=1.0, \u03c3=0.2) | Baseline correlation level | | `c2_fitted` |\n[1.0, 2.0] | *derived* | Final correlation function range | | `c2_theory` | [0.0, 1.0] |\n*derived* | Theoretical correlation bounds |\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### Output Organization\n\n```\n./homodyne_results/\n\u251c\u2500\u2500 homodyne_analysis_results.json    # Main results with config and metadata\n\u251c\u2500\u2500 run.log                          # Execution log file\n\u251c\u2500\u2500 classical/                      # Classical optimization results (if run)\n\u2502   \u251c\u2500\u2500 all_classical_methods_summary.json\n\u2502   \u251c\u2500\u2500 nelder_mead/                # Method-specific directory\n\u2502   \u2502   \u251c\u2500\u2500 analysis_results_nelder_mead.json\n\u2502   \u2502   \u251c\u2500\u2500 parameters.json\n\u2502   \u2502   \u251c\u2500\u2500 fitted_data.npz         # Experimental, fitted, residuals data\n\u2502   \u2502   \u251c\u2500\u2500 c2_heatmaps_nelder_mead_phi_*.png\n\u2502   \u2502   \u2514\u2500\u2500 nelder_mead_diagnostic_summary.png\n\u2502   \u251c\u2500\u2500 gurobi/                     # Gurobi method directory (if available)\n\u2502   \u2502   \u251c\u2500\u2500 analysis_results_gurobi.json\n\u2502   \u2502   \u251c\u2500\u2500 parameters.json\n\u2502   \u2502   \u251c\u2500\u2500 fitted_data.npz\n\u2502   \u2502   \u2514\u2500\u2500 c2_heatmaps_gurobi_phi_*.png\n\u2502   \u2514\u2500\u2500 ...                         # Other classical methods\n\u251c\u2500\u2500 robust/                         # Robust optimization results (if run)\n\u2502   \u251c\u2500\u2500 all_robust_methods_summary.json\n\u2502   \u251c\u2500\u2500 wasserstein/               # Robust method directories\n\u2502   \u2502   \u251c\u2500\u2500 analysis_results_wasserstein.json\n\u2502   \u2502   \u251c\u2500\u2500 parameters.json\n\u2502   \u2502   \u251c\u2500\u2500 fitted_data.npz\n\u2502   \u2502   \u2514\u2500\u2500 c2_heatmaps_wasserstein_phi_*.png\n\u2502   \u251c\u2500\u2500 scenario/\n\u2502   \u251c\u2500\u2500 ellipsoidal/\n\u2502   \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 mcmc/                          # MCMC results (if run)\n\u2502   \u251c\u2500\u2500 mcmc_summary.json          # MCMC summary statistics\n\u2502   \u251c\u2500\u2500 mcmc_trace.nc              # NetCDF trace file\n\u2502   \u251c\u2500\u2500 experimental_data.npz      # Original experimental data\n\u2502   \u251c\u2500\u2500 fitted_data.npz            # MCMC fitted data\n\u2502   \u251c\u2500\u2500 residuals_data.npz         # Residuals\n\u2502   \u251c\u2500\u2500 c2_heatmaps_phi_*.png      # Heatmap plots per angle\n\u2502   \u251c\u2500\u2500 3d_surface_phi_*.png       # 3D surface plots\n\u2502   \u251c\u2500\u2500 3d_surface_residuals_phi_*.png\n\u2502   \u251c\u2500\u2500 trace_plot.png             # MCMC trace plots\n\u2502   \u2514\u2500\u2500 corner_plot.png            # Parameter posterior distributions\n\u251c\u2500\u2500 exp_data/                      # Experimental data plots (if --plot-experimental-data)\n\u2502   \u251c\u2500\u2500 data_validation_phi_*.png  # Per-angle validation plots\n\u2502   \u2514\u2500\u2500 summary_statistics.txt     # Data summary\n\u2514\u2500\u2500 simulated_data/               # Simulated data plots (if --plot-simulated-data)\n    \u251c\u2500\u2500 simulated_c2_fitted_phi_*.png    # Simulated fitted data plots\n    \u251c\u2500\u2500 theoretical_c2_phi_*.png         # Theoretical correlation plots\n    \u251c\u2500\u2500 fitted_c2_data.npz              # Fitted data arrays\n    \u2514\u2500\u2500 theoretical_c2_data.npz         # Theoretical data arrays\n```\n\n**File Organization:**\n\n- `homodyne_analysis_results.json`: Summary of all analysis methods (stays in root\n  directory)\n- `all_classical_methods_summary.json`: Summary of all classical methods in classical\n  directory\n- `all_robust_methods_summary.json`: Summary of all robust methods in robust directory\n- **Method-specific directories**: Each optimization method has its own complete\n  directory containing:\n  - `analysis_results_[method_name].json`: Complete analysis results for the method\n  - `parameters.json`: Fitted parameters with uncertainties, chi-squared values, and\n    convergence information\n  - `fitted_data.npz`: Complete numerical data (experimental, fitted, residuals,\n    parameters, time arrays)\n  - `c2_heatmaps_[method_name].png`: Method-specific correlation heatmaps\n- **Standardized robust method names**: `wasserstein`, `scenario`, `ellipsoidal` for\n  clean organization\n- **No redundant files**: All data is organized within method-specific directories\n\n## Common Output Structure for All Optimization Methods\n\n### Classical Methods Directory Structure\n\n```\n./homodyne_results/classical/\n\u251c\u2500\u2500 nelder_mead/\n\u2514\u2500\u2500 gurobi/\n```\n\n### Robust Methods Directory Structure\n\n```\n./homodyne_results/robust/\n\u251c\u2500\u2500 wasserstein/      # Robust-Wasserstein method\n\u251c\u2500\u2500 scenario/         # Robust-Scenario method  \n\u2514\u2500\u2500 ellipsoidal/      # Robust-Ellipsoidal method\n```\n\n### Per-Method Files\n\nEach method directory contains:\n\n#### `parameters.json` - Human-readable parameter results\n\n```json\n{\n  \"method_name\": \"Nelder-Mead\",\n  \"method_type\": \"Classical Optimization\",\n  \"parameters\": {\n    \"amplitude\": {\n      \"value\": 1.234,\n      \"uncertainty\": 0.056,\n      \"unit\": \"arb\"\n    },\n    \"frequency\": {\n      \"value\": 2.678,\n      \"uncertainty\": 0.123,\n      \"unit\": \"Hz\"\n    },\n    \"phase\": {\n      \"value\": 0.789,\n      \"uncertainty\": 0.034,\n      \"unit\": \"rad\"\n    }\n  },\n  \"goodness_of_fit\": {\n    \"chi_squared\": 0.523,\n    \"degrees_of_freedom\": 397,\n    \"reduced_chi_squared\": 0.00132\n  },\n  \"convergence_info\": {\n    \"success\": true,\n    \"iterations\": 150,\n    \"function_evaluations\": 280,\n    \"message\": \"Optimization terminated successfully\"\n  },\n  \"data_info\": {\n    \"n_data_points\": 400,\n    \"n_angles\": 4,\n    \"n_time_points\": 100\n  }\n}\n```\n\n#### `fitted_data.npz` - Consolidated Numerical Data Archive\n\n**Complete data structure for each method:**\n\n```python\nimport numpy as np\n\n# Load method-specific data\ndata = np.load(\"fitted_data.npz\")\n\n# Primary correlation function data\nc2_fitted = data[\"c2_fitted\"]           # Method-specific fitted data (n_angles, n_t2, n_t1)\nc2_experimental = data[\"c2_experimental\"] # Original experimental data (n_angles, n_t2, n_t1)\nresiduals = data[\"residuals\"]           # Method-specific residuals (n_angles, n_t2, n_t1)\n\n# Parameter and fit results\nparameters = data[\"parameters\"]         # Fitted parameter values (n_params,)\nuncertainties = data[\"uncertainties\"]   # Parameter uncertainties (n_params,)\nchi_squared = data[\"chi_squared\"]       # Chi-squared goodness-of-fit (scalar)\n\n# Coordinate arrays\nphi_angles = data[\"phi_angles\"]         # Angular coordinates (n_angles,) [degrees]\nt1 = data[\"t1\"]                        # First correlation time array (n_t1,) [seconds]\nt2 = data[\"t2\"]                        # Second correlation time array (n_t2,) [seconds]\n```\n\n**Key Features:**\n\n- **Consolidated structure**: All method-specific data in a single NPZ file per method\n- **Complete data access**: Experimental, fitted, and residual data together\n- **Coordinate information**: Full time and angular coordinate arrays included\n- **Statistical metadata**: Parameter uncertainties and goodness-of-fit metrics\n- **Consistent format**: Same structure across all optimization methods (classical,\n  robust, MCMC)\n\n**Array Dimensions:**\n\n- **Correlation functions**: `(n_angles, n_t2, n_t1)` - typically `(4, 60-100, 60-100)`\n- **Parameters**: `(n_params,)` - 3 for static modes, 7 for laminar flow\n- **Time arrays**: `(n_t1,)`, `(n_t2,)` - discretized with `dt` spacing\n- **Angles**: `(n_angles,)` - typically `[0\u00b0, 45\u00b0, 90\u00b0, 135\u00b0]`\n\n**Usage Examples:**\n\n```python\n# Calculate residual statistics\nresidual_rms = np.sqrt(np.mean(residuals**2))\nresidual_max = np.max(np.abs(residuals))\n\n# Extract parameter with uncertainty\nD0_value = parameters[0]\nD0_error = uncertainties[0]\nprint(f\"D0 = {D0_value:.2e} \u00b1 {D0_error:.2e}\")\n\n# Access time-resolved data at specific angle\nangle_idx = 0  # First angle (typically 0\u00b0)\nc2_at_angle = c2_fitted[angle_idx, :, :]  # Shape: (n_t2, n_t1)\n```\n\n### Method-Specific Characteristics\n\n#### **Nelder-Mead**\n\n```json\n{\n  \"method_name\": \"Nelder-Mead\",\n  \"method_type\": \"Classical Optimization\",\n  \"convergence_info\": {\n    \"success\": true,\n    \"iterations\": 150,\n    \"function_evaluations\": 280,\n    \"message\": \"Optimization terminated successfully\",\n    \"termination_reason\": \"ftol achieved\"\n  }\n}\n```\n\n#### **Gurobi**\n\n```json\n{\n  \"method_name\": \"Gurobi\",\n  \"method_type\": \"Classical Optimization\",\n  \"convergence_info\": {\n    \"success\": true,\n    \"iterations\": 50,\n    \"function_evaluations\": 100,\n    \"message\": \"Optimal solution found\",\n    \"solve_time\": 1.23,\n    \"solver_status\": \"OPTIMAL\"\n  }\n}\n```\n\n#### **Robust-Wasserstein**\n\n```json\n{\n  \"method_name\": \"Robust-Wasserstein\",\n  \"method_type\": \"Robust Optimization\",\n  \"robust_specific\": {\n    \"uncertainty_radius\": 0.03,\n    \"regularization_alpha\": 0.01,\n    \"wasserstein_distance\": 0.025\n  },\n  \"convergence_info\": {\n    \"success\": true,\n    \"solve_time\": 2.5,\n    \"status\": \"optimal\"\n  }\n}\n```\n\n#### **Robust-Scenario**\n\n```json\n{\n  \"method_name\": \"Robust-Scenario\",\n  \"method_type\": \"Robust Optimization\",\n  \"robust_specific\": {\n    \"n_scenarios\": 50,\n    \"worst_case_value\": 0.65,\n    \"scenario_weights\": \"uniform\"\n  },\n  \"convergence_info\": {\n    \"success\": true,\n    \"solve_time\": 3.2,\n    \"status\": \"optimal\"\n  }\n}\n```\n\n#### **Robust-Ellipsoidal**\n\n```json\n{\n  \"method_name\": \"Robust-Ellipsoidal\",\n  \"method_type\": \"Robust Optimization\",\n  \"robust_specific\": {\n    \"uncertainty_set\": \"ellipsoidal\",\n    \"ellipsoid_radius\": 0.04,\n    \"confidence_level\": 0.95\n  },\n  \"convergence_info\": {\n    \"success\": true,\n    \"solve_time\": 1.8,\n    \"status\": \"optimal\"\n  }\n}\n```\n\n### Summary Files\n\n#### `all_methods_summary.json` - Cross-method comparison\n\n```json\n{\n  \"analysis_type\": \"Classical Optimization\",\n  \"timestamp\": \"2025-01-15T10:30:45Z\",\n  \"methods_analyzed\": [\"Nelder-Mead\", \"Gurobi\", \"Robust-Wasserstein\", \"Robust-Scenario\", \"Robust-Ellipsoidal\"],\n  \"best_method\": \"Gurobi\",\n  \"results\": {\n    \"Nelder-Mead\": {\n      \"chi_squared\": 0.523,\n      \"parameters\": [1.234, 2.678, 0.789],\n      \"success\": true\n    },\n    \"Gurobi\": {\n      \"chi_squared\": 0.501,\n      \"parameters\": [1.245, 2.689, 0.785],\n      \"success\": true\n    },\n    \"Robust-Wasserstein\": {\n      \"chi_squared\": 0.534,\n      \"parameters\": [1.228, 2.665, 0.792],\n      \"success\": true\n    }\n  }\n}\n```\n\n### Key Differences Between Methods\n\n**Classical Methods (Nelder-Mead, Gurobi)**\n\n- Point estimates only with deterministic convergence metrics\n- Faster execution with iterations and function evaluations tracking\n- No built-in uncertainty quantification from optimization method\n\n**Robust Methods (Wasserstein, Scenario, Ellipsoidal)**\n\n- Robust optimization against data uncertainty with worst-case guarantees\n- Additional robust-specific parameters (uncertainty radius, scenarios, confidence\n  levels)\n- Convex optimization solver status codes and solve times\n- Enhanced reliability under data perturbations\n\n## Diagnostic Summary Images Structure\n\nThe diagnostic summary images are comprehensive visualizations that combine multiple\nanalysis components into a single figure. Here's what they typically contain:\n\n### 1. Main Diagnostic Summary Plot (`diagnostic_summary.png`)\n\n**Location**: `./homodyne_results/diagnostic_summary.png` (root directory)\n\n**Generated for**: Only `--method all` (comparison across multiple methods)\n\nA **2\u00d73 grid layout** containing:\n\n#### Subplot 1: Method Comparison (Top Left)\n\n- **Bar chart** comparing chi-squared values across different optimization methods\n- **Y-axis**: Chi-squared values (log scale)\n- **X-axis**: Method names (Nelder-Mead, Gurobi, Robust-Wasserstein, etc.)\n- **Value labels** showing exact chi-squared values in scientific notation\n- **Color coding** for different methods (C0, C1, C2, C3)\n\n#### Subplot 2: Parameter Uncertainties (Top Middle)\n\n- **Horizontal bar chart** showing parameter uncertainties\n- **Y-axis**: Parameter names (amplitude, frequency, phase, etc.)\n- **X-axis**: Uncertainty values (\u03c3)\n- **Includes grid lines** for better readability\n- Shows **\"No uncertainty data available\"** if uncertainties aren't computed\n\n#### Subplot 3: MCMC Convergence Diagnostics (Top Right)\n\n- **Horizontal bar chart** of R\u0302 (R-hat) values for convergence assessment\n- **Y-axis**: Parameter names\n- **X-axis**: R\u0302 values (convergence metric)\n- **Color coding**: Green (R\u0302 < 1.1), Orange (1.1 \u2264 R\u0302 < 1.2), Red (R\u0302 \u2265 1.2)\n- **Red dashed line** at R\u0302 = 1.1 (convergence threshold)\n- Shows **\"No MCMC convergence diagnostics available\"** for classical-only methods\n\n#### Subplot 4: Residuals Distribution Analysis (Bottom, Full Width)\n\n- **Histogram** of residuals (experimental - theoretical data)\n- **Overlay** of fitted normal distribution curve\n- **Statistics**: Mean (\u03bc) and standard deviation (\u03c3) displayed\n- **X-axis**: Residual values\n- **Y-axis**: Probability density\n- Shows **\"No residuals data available\"** if data is missing\n\n### 2. Method-Specific Diagnostic Summaries (Removed)\n\n**Note:** Method-specific diagnostic summary plots have been removed to reduce redundant\noutput. Only the main `diagnostic_summary.png` is generated for `--method all` to\nprovide meaningful cross-method comparisons.\n\n### Diagnostic Plot Generation Summary\n\n| Command | Main `diagnostic_summary.png` | Method-Specific Diagnostic Plots |\n|---------|-------------------------------|-----------------------------------| |\n`--method classical` | \u274c Not generated (single method) | \u274c Not generated | |\n`--method robust` | \u274c Not generated (single method) | \u274c Not generated | |\n`--method mcmc` | \u274c Not generated (single method) | \u274c Not generated | | `--method all` |\n\u2705 Root directory | \u274c Not generated |\n\n### 3. Additional Diagnostic/Visualization Outputs\n\n#### C2 Correlation Heatmaps (`c2_heatmaps_*.png`)\n\n- **2D heatmaps** showing experimental vs theoretical correlation functions\n- **Individual plots** for each scattering angle (\u03c6 = 0\u00b0, 45\u00b0, 90\u00b0, 135\u00b0)\n- **Method-specific** versions for each optimization approach\n- **Time axes**: t\u2081 and t\u2082 (correlation delay times)\n- **Color mapping**: Viridis colormap showing correlation intensity\n\n#### MCMC-Specific Plots (when applicable)\n\n- **`trace_plot.png`**: MCMC chain traces for each parameter\n- **`corner_plot.png`**: Parameter posterior distributions and correlations\n\n#### Data Validation Plots (`data_validation_*.png`)\n\n- **Experimental data validation** plots\n- **Individual plots** for each scattering angle\n- **Full 2D heatmaps** and **cross-sections** of experimental data\n- **Statistical summaries** and **quality metrics**\n\n### Key Features of Diagnostic Summaries:\n\n1. **Adaptive Content**: Shows appropriate placeholders when data is unavailable\n1. **Cross-Method Comparison**: Allows comparison of different optimization approaches\n1. **Quality Assessment**: Provides convergence and fitting quality metrics\n1. **Statistical Analysis**: Includes residuals analysis and uncertainty quantification\n1. **Professional Formatting**: Consistent styling with grid lines, proper labels, and\n   legends\n\nThese diagnostic summaries provide researchers with a comprehensive overview of their\nanalysis quality, method performance, and parameter uncertainties all in a single\nvisualization.\n\n## Theoretical Background\n\nThe package implements three key equations describing correlation functions in\nnonequilibrium 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\n\\\\text{sinc}^2\\\\left\\[\\\\frac{1}{2\\\\pi} qh\n\\\\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]\n\\\\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]\n\\\\text{sinc}^2\\\\left[\\\\frac{1}{2\\\\pi} qh \\\\cos(\\\\phi)\\\\dot{\\\\gamma}\\\\tau\\\\right]$$\n\n**Key Parameters:**\n\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\ndetails.\n\n## Documentation\n\n### \ud83d\udcda Complete Documentation Portal\n\n**Primary Site**: https://homodyne.readthedocs.io/\n\n### \ud83d\udcd6 Available Documentation Resources\n\n#### **User Documentation**\n\n- **[Installation Guide](docs/user-guide/installation.rst)**: Complete installation\n  instructions with dependency options\n- **[Quickstart Tutorial](docs/user-guide/quickstart.rst)**: Get started with analysis\n  in 5 minutes\n- **[Configuration Guide](docs/user-guide/configuration.rst)**: Detailed configuration\n  options and templates\n- **[Analysis Modes](docs/user-guide/analysis-modes.rst)**: Static vs. laminar flow\n  analysis modes\n- **[Plotting & Visualization](docs/user-guide/plotting.rst)**: Data visualization and\n  validation tools\n- **[Examples & Use Cases](docs/user-guide/examples.rst)**: Real-world analysis examples\n\n#### **Command Line Interface**\n\n- **[CLI_REFERENCE.md](CLI_REFERENCE.md)**: Complete command-line documentation\n- **Shell completion support** for bash, zsh, fish, and PowerShell\n- **Interactive help system** with `homodyne_help` command\n\n#### **Developer Resources**\n\n- **[Architecture Overview](docs/developer-guide/architecture.rst)**: Package structure\n  and design\n- **[Contributing Guide](docs/developer-guide/contributing.rst)**: Development workflow\n  and standards\n- **[Performance Guide](docs/developer-guide/performance.rst)**: Optimization techniques\n  and benchmarking\n- **[Testing Framework](docs/developer-guide/testing.rst)**: Test organization and best\n  practices\n- **[Troubleshooting](docs/developer-guide/troubleshooting.rst)**: Common issues and\n  solutions\n\n#### **API Reference**\n\n- **[Core Analysis](docs/api-reference/core.rst)**: Main analysis classes and functions\n- **[Optimization Methods](docs/api-reference/mcmc.rst)**: MCMC, classical, and robust\n  optimization\n- **[Robust Methods](docs/api-reference/robust.rst)**: Noise-resistant optimization\n  techniques\n- **[Utilities](docs/api-reference/utilities.rst)**: Helper functions and data handling\n\n#### **Reference Documentation**\n\n- **[API_REFERENCE.md](API_REFERENCE.md)**: Comprehensive API documentation\n- **[CHANGELOG.md](CHANGELOG.md)**: Version history and release notes\n- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Development guidelines and standards\n\n### \ud83d\ude80 Recent Improvements (v0.7.1)\n\n- **Windows Compatibility**: Fixed path separator issues in shell completion system for\n  full cross-platform support\n- **Pre-commit Hooks**: Comprehensive code quality framework with automatic formatting,\n  linting, and security scanning\n- **Shell Completion**: Enhanced tab completion with Windows path separator support and\n  robust fallback mechanisms\n- **Code Quality**: 100% Black and isort compliance, integrated Bandit security scanning\n- **Test Reliability**: All CI tests pass consistently across Windows, macOS, and Linux\n- **Type Safety**: Enhanced type annotations and MyPy configuration for scientific code\n  patterns\n- **Performance**: Optimized completion system with fast caching and memory efficiency\n- **Security**: Zero medium/high severity security issues with comprehensive\n  vulnerability scanning\n\n### \ud83d\udccb Quick Access\n\n| Topic | Link | Description | |-------|------|-------------| | **Getting Started** |\n[Quickstart](docs/user-guide/quickstart.rst) | 5-minute tutorial | | **CLI Commands** |\n[CLI_REFERENCE.md](CLI_REFERENCE.md) | Complete command reference | | **Configuration**\n| [Configuration Guide](docs/user-guide/configuration.rst) | Setup and templates | |\n**API Usage** | [API_REFERENCE.md](API_REFERENCE.md) | Python API documentation | |\n**Troubleshooting** | [Troubleshooting](docs/developer-guide/troubleshooting.rst) |\nCommon issues & solutions | | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) |\nDevelopment workflow |\n\n### \ud83d\udca1 Documentation Features\n\n- **Comprehensive coverage**: User guides, API reference, and developer documentation\n- **Cross-platform compatibility**: Windows, macOS, and Linux instructions\n- **Multiple analysis modes**: Static isotropic, anisotropic, and laminar flow\n- **Security-focused**: Bandit integration for continuous security scanning\n- **Performance-oriented**: Detailed optimization guides and benchmarking tools\n\n## Development Status & Code Quality\n\n**Code Formatting & Quality:**\n\n- \u2705 **Black**: 100% compliant (all files formatted with 88-character line length)\n- \u2705 **isort**: 100% compliant (imports sorted and optimized)\n- \u2705 **Ruff**: Fast linting and formatting with auto-fixes enabled\n- \u2705 **Bandit**: 0 medium/high severity security issues (comprehensive security scanning)\n- \u2705 **Pre-commit Hooks**: Automated code quality checks on every commit\n- \u26a0\ufe0f **flake8**: ~350 remaining style issues (primarily line length E501 in data\n  scripts)\n- \u26a0\ufe0f **mypy**: ~250 type annotation issues (mainly missing library stubs for scientific\n  packages)\n\n**Security & Best Practices:**\n\n- \u2705 **Security scanning**: Integrated Bandit for continuous vulnerability detection (0\n  medium/high severity issues)\n- \u2705 **Dependency vulnerability checking**: pip-audit integration for automated\n  dependency security scanning\n- \u2705 **Cross-platform compatibility**: Windows, macOS, and Linux support with proper path\n  handling\n- \u2705 **Dependency management**: Clean dependency tree with optional feature groups\n- \u2705 **Safe coding practices**: No hardcoded paths, secure file operations, proper error\n  handling\n- \u2705 **Security configuration**: Properly configured security tools with scientific code\n  patterns\n- \u2705 **Pre-commit security**: Automatic security checks on every commit\n- \u2705 **Shell completion security**: Safe command completion without shell injection risks\n\n**Python Version Support:**\n\n- **Required**: Python 3.12+ (enforced at package and CLI level)\n- **Tested**: Python 3.12, 3.13\n- **CI/CD**: Multi-platform testing (Ubuntu, Windows, macOS)\n- **Compatibility**: Full Python 3.13 support with typing improvements\n\n**Performance:**\n\n- **JIT Compilation**: Numba warmup eliminates compilation overhead\n- **JAX Integration**: Optional GPU acceleration for MCMC\n- **Memory Management**: Automatic cleanup and smart caching\n- **Benchmarking**: Comprehensive performance regression testing\n- **Shell Completion**: Multi-tier fallback system for enhanced UX\n\n## Contributing\n\nWe welcome contributions! Please submit issues and pull requests.\n\n**Development setup:**\n\n```bash\ngit clone https://github.com/imewei/homodyne.git\ncd homodyne\npip install -e .[all]\n\n# Run tests\npython homodyne/run_tests.py\n\n# Code quality and security checks\nblack homodyne/                    # Format code\nisort homodyne/                    # Sort imports  \nflake8 homodyne/                   # Linting\nmypy homodyne/                     # Type checking\nbandit -r homodyne/                # Security scanning\npip-audit                          # Dependency vulnerability scanning\n```\n\n**Pre-commit hooks available for automated code quality checks.**\n\n```bash\n# Install pre-commit hooks\npip install pre-commit\npre-commit install\n\n# Run hooks manually\npre-commit run --all-files\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": "High-performance Python package for analyzing homodyne scattering in X-ray Photon Correlation Spectroscopy (XPCS) under nonequilibrium conditions with comprehensive optimization methods, pre-commit hooks, and cross-platform shell completion",
    "version": "0.7.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",
        " optimization",
        " bayesian-analysis",
        " mcmc",
        " robust-optimization",
        " trust-region-optimization",
        " gurobi",
        " jax",
        " high-performance-computing",
        " jit-compilation",
        " performance-optimization",
        " code-quality",
        " pre-commit-hooks",
        " shell-completion",
        " cross-platform",
        " windows-compatibility",
        " security-scanning"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "75b8c964827389e5c9dce3060e889ced9c18f5aad8e07c21dd9e44b707738926",
                "md5": "8c65e48b4199711eddee4fb98fd80d0e",
                "sha256": "47f9a056ab848d58a25f9d7062574bca56d6f70c3ea20c8f1d0311fbfe42a7d2"
            },
            "downloads": -1,
            "filename": "homodyne_analysis-0.7.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8c65e48b4199711eddee4fb98fd80d0e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 196603,
            "upload_time": "2025-08-28T16:39:19",
            "upload_time_iso_8601": "2025-08-28T16:39:19.209785Z",
            "url": "https://files.pythonhosted.org/packages/75/b8/c964827389e5c9dce3060e889ced9c18f5aad8e07c21dd9e44b707738926/homodyne_analysis-0.7.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1eb4377079bef3c73de08e80753eb8ced41b0ef4f70cc8161240056eaf55b037",
                "md5": "df7c1cfc15e7094638db47539966964b",
                "sha256": "6d6d98a8af3ba52c9136cd96356af663aa147df480a4f5598ab6d09c0a8e7e63"
            },
            "downloads": -1,
            "filename": "homodyne_analysis-0.7.1.tar.gz",
            "has_sig": false,
            "md5_digest": "df7c1cfc15e7094638db47539966964b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 294093,
            "upload_time": "2025-08-28T16:39:20",
            "upload_time_iso_8601": "2025-08-28T16:39:20.963563Z",
            "url": "https://files.pythonhosted.org/packages/1e/b4/377079bef3c73de08e80753eb8ced41b0ef4f70cc8161240056eaf55b037/homodyne_analysis-0.7.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-28 16:39:20",
    "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": [
                [
                    ">=",
                    "1.24.0"
                ],
                [
                    "<",
                    "2.3.0"
                ]
            ]
        },
        {
            "name": "scipy",
            "specs": [
                [
                    ">=",
                    "1.9.0"
                ]
            ]
        },
        {
            "name": "matplotlib",
            "specs": [
                [
                    ">=",
                    "3.5.0"
                ]
            ]
        }
    ],
    "lcname": "homodyne-analysis"
}