User Guide

This guide is structured so you can read it end-to-end or jump directly to the section relevant to your experience level and goal.

Fundamentals

• Fundamentals
  • What is X-ray Photon Correlation Spectroscopy?
  • Analysis Modes
  • Homodyne Package Overview
  • Parameter Interpretation Guide

Data and Fitting

• Data and Fitting
  • Loading XPCS Data
  • NLSQ Fitting Guide
  • Choosing Your Model
  • Interpreting Results

Advanced Topics

• Advanced Topics
  • Bayesian Inference with CMC
  • Per-Angle Scaling Modes
  • Laminar Flow Analysis Guide
  • CMA-ES for Multi-Scale Problems
  • Large Dataset Handling and Streaming
  • Convergence Diagnostics

Practical Guides

• Practical Guides
  • YAML Configuration Reference
  • Batch Processing Multiple Datasets
  • Plotting Results
  • Performance Tuning: CPU/NUMA Optimization

Appendices

• Appendices
  • Troubleshooting Guide
  • Frequently Asked Questions
  • Glossary

---

Learning Pathways

Choose the pathway that matches your background and goal.

Path A — New to XPCS

For scientists with experimental data but no prior Homodyne experience.

1. What is X-ray Photon Correlation Spectroscopy? — what C2 matrices are and why they matter

2. installation — get Homodyne installed

3. quickstart — run your first analysis in 5 minutes

4. Loading XPCS Data — load your own HDF5 files

5. NLSQ Fitting Guide — fit static diffusion

6. Interpreting Results — understand the output

Path B — Laminar Flow / Shear Dynamics

For users analyzing systems with velocity gradients (He et al. PNAS 2025).

1. What is X-ray Photon Correlation Spectroscopy? — XPCS background

2. Analysis Modes — static vs. laminar flow

3. Laminar Flow Analysis Guide — 7-parameter fit

4. Per-Angle Scaling Modes — per-angle scaling

5. Bayesian Inference with CMC — uncertainty quantification

6. Troubleshooting Guide — diagnose convergence issues

Path C — Bayesian Uncertainty Quantification

For users who want posterior distributions, not just point estimates.

1. quickstart — run NLSQ first (warm-start)

2. NLSQ Fitting Guide — understand NLSQ output

3. Bayesian Inference with CMC — Consensus Monte Carlo

4. Convergence Diagnostics — shard size, chain method, R-hat, ESS

5. Interpreting Results — read posterior summaries

Path D — Advanced Configuration and Performance

For power users running large datasets on multi-core servers.

1. YAML Configuration Reference — full YAML reference

2. Performance Tuning: CPU/NUMA Optimization — XLA flags, NUMA, threading

3. Large Dataset Handling and Streaming — streaming vs. batch

4. CMA-ES for Multi-Scale Problems — CMA-ES for multi-scale problems

5. Parameter Interpretation Guide — all parameters, bounds, units

---

Sections Overview

Section	Contents
Fundamentals	XPCS primer, core equation, analysis modes, the homodyne model
Data and Fitting	Data loading, static mode, laminar flow, NLSQ, configuration
Advanced Topics	CMC/Bayesian, CPU optimisation, CMA-ES, diagnostics
Practical Guides	Interpreting results, troubleshooting, FAQ
Appendices	Parameter reference, CLI reference, changelog