Configuration

This section documents Homodyne’s comprehensive YAML configuration system, which controls all aspects of XPCS analysis including data input, analysis mode, optimization methods, and output generation.

Overview

Homodyne uses YAML configuration files to specify:

  • Analysis mode: Static diffusion or laminar flow

  • Data input: HDF5 file paths and phi angle filtering

  • Initial parameters: Starting values and bounds for optimization

  • Optimization method: NLSQ (fast) or CMC (uncertainty quantification)

  • Output options: Formats, visualization, and logging

Configuration Sections

A complete Homodyne configuration includes:

  1. Metadata: Version and description

  2. Analysis Mode: Static or laminar_flow

  3. Analyzer Parameters: Experimental settings (dt, frame range, q-vector)

  4. Experimental Data: HDF5 file paths and caching

  5. Phi Angle Filtering: Angle selection and quality control

  6. Initial Parameters: Starting values and bounds

  7. Optimization: Method selection and settings (NLSQ/CMC)

  8. Performance: JAX compilation and memory management

  9. Output: File formats and directory structure

  10. Logging: Console and file logging levels

Configuration Resources

Working with Configurations

Interactive Configuration Builder

Use the interactive configuration builder for guided setup:

homodyne-config --interactive

This prompts you through required fields and generates a configuration file.

Validating Configurations

Check if a configuration file is valid before running:

homodyne-config --validate my_config.yaml

This validates: - YAML syntax - Required fields present - Parameter bounds physically reasonable - Data files exist - Compatibility with selected analysis mode

Running Analysis with Configuration

Run NLSQ optimization:

homodyne --config my_config.yaml --method nlsq

Run CMC inference:

homodyne --config my_config.yaml --method cmc

Both methods use the same configuration file.

Analysis Modes

Two analysis modes are supported:

Static Mode (3 physical parameters)

For equilibrium systems with pure diffusion:

analysis_mode: "static"

initial_parameters:
  parameter_names:
    - D0           # Diffusion coefficient prefactor
    - alpha        # Anomalous diffusion exponent
    - D_offset     # Baseline diffusion

Laminar Flow Mode (7 physical parameters)

For non-equilibrium systems under shear:

analysis_mode: "laminar_flow"

initial_parameters:
  parameter_names:
    - D0               # Diffusion coefficient prefactor
    - alpha            # Anomalous diffusion exponent
    - D_offset         # Baseline diffusion
    - gamma_dot_t0     # Shear rate prefactor
    - beta             # Shear rate exponent
    - gamma_dot_t_offset  # Baseline shear rate
    - phi0             # Flow angle

Per-Angle Scaling

Mandatory: Each scattering angle has unique optical and detector properties, requiring per-angle scaling parameters.

Total parameters = physical parameters + 2 × number of scattering angles

Example with 3 filtered angles: - Physical: 3 parameters (static) or 7 parameters (laminar_flow) - Per-angle: 2 × 3 = 6 parameters (3 contrast + 3 offset) - Total: 9 parameters (static) or 13 parameters (laminar_flow)

See Configuration Templates for complete examples.

Configuration Features

Data Filtering and Caching

Homodyne supports: - Phi angle filtering: Select specific scattering angles (e.g., 0°, 90°, 180°) - Data caching: Save processed C2 data for reuse - Stratification: Automatic angle-aware chunking for large datasets - Sequential optimization: Per-angle NLSQ with result combination

See Configuration Options Reference for detailed parameter descriptions.

Optimization Configuration

NLSQ Configuration: - Trust region scaling - Convergence tolerance - Maximum iterations - Automatic strategy selection (STANDARD/LARGE/CHUNKED/STREAMING)

CMC Configuration: - Consensus Monte Carlo - Per-shard NUTS sampling - Subposterior combination method - Convergence diagnostics - Checkpoint and resume capability

Performance Tuning

Memory management: - Chunk size for processing - Maximum memory limits - Caching strategies

JAX optimization: - JIT compilation control - CPU thread count - Vectorization level

See Configuration Options Reference for all performance parameters.

Output Configuration

Control output generation: - Output directory and subdirectory structure - File formats (HDF5, JSON, CSV) - Compression settings - Visualization settings (plots, format, DPI)

Validation and Quality Control

Built-in validation checks: - Parameter bounds enforcement - Mode compatibility verification - File existence checks - Angle coverage validation

Configuration Examples

Complete configuration examples are provided in Configuration Templates:

  • Static mode: Minimal and comprehensive examples

  • Laminar flow: Minimal and comprehensive examples

  • Feature demonstrations: Per-angle scaling, filtering, stratification

Each template includes: - Detailed parameter descriptions and units - Physical meaning and typical ranges - Usage notes and workflow guidance - Production-ready defaults

Version Information

  • Required Python: 3.12+

  • JAX: ≥0.8.2 (CPU-only)

  • Analysis Modes: static, laminar_flow

Environment Validation

Before running analysis, validate your system:

python -m homodyne.runtime.utils.system_validator --quick

This checks: - Python version (3.12+) - JAX installation and version (≥0.8.2) - CPU device availability - Required dependencies

For Questions