xpcsviewer-gui 0.1.5

XPCS Viewer: A python-based interactive tool to visualize and model XPCS dataset

Python-based XPCS data analysis and visualization tool.

Features:

• G2 correlation analysis across three tabs (g2 view, g2 Fit, g2 Map)

• SAXS 1D/2D visualization

• Two-time correlation analysis

• Diffusion coefficient extraction (tau-Q analysis)

• Sample stability monitoring

• Mask Editor with Q-map and Q-binning

• HDF5 data support (NeXus format)

GUI Features:

• Light/dark theme support with system detection

• Scalable SVG icons with theme-aware coloring

• Category tab bar grouping 12 analysis tabs

• Session persistence (resume where you left off)

• Command palette (Ctrl+Shift+P) for quick access

• Toast notifications for status updates

• Keyboard shortcut management

• Drag-and-drop file handling

• Theme-aware plots (PyQtGraph & Matplotlib)

UI notes

• Menu-driven header (no quick-access toolbar); all actions live under the menus/shortcuts.

• Starts maximized with a rectangular layout and a minimum-size floor to prevent cramped controls.

• PySide6 GUI interface with modern theming

• Performance optimizations

Installation

Requirements: Python 3.12+

# Install from PyPI
pip install xpcsviewer-gui

# Or install with uv (recommended)
uv pip install xpcsviewer-gui

JAX and all scientific dependencies (NumPyro, ArviZ, interpax, etc.) are included automatically — no extras needed.

GPU Acceleration (Optional)

Performance Impact: 20-100x speedup for large datasets (>1M points)

Prerequisites:

• NVIDIA GPU with SM >= 5.2 (Maxwell or newer)

• System CUDA 12.x or 13.x installed (nvcc in PATH)

Quick Install (Recommended):

# Auto-detect system CUDA version and install matching JAX
make install-jax-gpu

This detects your system CUDA version, validates GPU compatibility, removes any conflicting packages, installs the correct JAX GPU package, and verifies GPU detection.

Manual Install:

# 1. Check your CUDA version
nvcc --version    # Note: release 12.x or 13.x

# 2. Remove ALL existing JAX/CUDA packages (prevents plugin conflicts)
pip uninstall -y jax jaxlib \
    jax-cuda13-plugin jax-cuda13-pjrt \
    jax-cuda12-plugin jax-cuda12-pjrt

# 3. Install matching package
pip install "jax[cuda13-local]"   # For CUDA 13.x (SM >= 7.5)
pip install "jax[cuda12-local]"   # For CUDA 12.x (SM >= 5.2)

# 4. Verify
python -c "import jax; print(jax.default_backend(), jax.devices())"
# Expected: gpu [CudaDevice(id=0)]

Troubleshooting:

Symptom	Cause	Fix
plugin version X is not compatible with jaxlib Y	Plugin/jaxlib version mismatch	Uninstall all, reinstall: make install-jax-gpu
PJRT_Api already exists for device type cuda	Both cuda12 and cuda13 plugins installed	Uninstall all, reinstall only ONE
nvcc not found	CUDA toolkit missing or not in PATH	sudo apt install nvidia-cuda-toolkit or export PATH=/usr/local/cuda/bin:$PATH
Backend: cpu (GPU exists)	GPU JAX packages not installed	make install-jax-gpu
libcuda.so not found	CUDA libs not in LD_LIBRARY_PATH	export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

Platform Support:

Platform	GPU	Notes
Linux x86_64/aarch64	Full	System CUDA 12.x or 13.x
Windows WSL2	Experimental	Linux wheels
macOS	CPU-only	No NVIDIA support
Windows native	CPU-only	No pre-built wheels

Environment variables for control:

Variable	Description	Default
XPCS_USE_JAX	Enable JAX backend (true, false, auto)	auto
JAX_PLATFORMS	Force CPU/GPU (cpu, cuda)	(auto-detected)
XPCS_GPU_FALLBACK	Allow CPU fallback if GPU fails	true
XPCS_GPU_MEMORY_FRACTION	Maximum GPU memory usage (0.0-1.0)	0.9

Usage

GUI (Interactive):

# Launch GUI with data path
xpcsviewer-gui /path/to/hdf/data

# Launch from current directory
xpcsviewer-gui

# With debug logging
xpcsviewer-gui --log-level DEBUG

CLI (Batch Processing):

# Show available commands
xpcsviewer --help

# Generate twotime plots for all phi angles at q=0.05
xpcsviewer twotime --input /data --output /results --q 0.05

# Generate high-resolution PDF plots
xpcsviewer twotime -i /data -o /results --phi 45 --dpi 300 --format pdf

Citation

Chu et al., “pyXPCSviewer: an open-source interactive tool for X-ray photon correlation spectroscopy visualization and analysis”, Journal of Synchrotron Radiation, (2022) 29, 1122–1129.

Development

# Clone and install (uv recommended)
git clone https://github.com/imewei/XPCSViewer.git
cd XPCSViewer

# With uv (recommended) — installs package + dev/test dependencies
uv sync
make install-hooks      # install pre-commit + commit-msg hooks

# Or with pip (editable install, no dev dependencies)
pip install -e .

# Run tests
make test               # parallel tests (excl. GUI)
make test-fast          # fast tests excluding slow markers

# Build docs
make docs

Data Formats

• NeXus HDF5 (APS-8IDI beamline)

• SAXS 2D/1D data

• G2 correlation functions

• Time series data

Testing

make test              # Run tests
make test-unit         # Unit tests
make test-integration  # Integration tests
make coverage          # Coverage report

Documentation

• Tutorials – Step-by-step learning guides

• How-To Guides – Task-oriented instructions

• API Reference – Auto-generated from docstrings

• Architecture – Design decisions and diagrams

make docs              # Build docs
make docs-autobuild    # Live reload docs

Configuration

Environment variables for customization:

Variable	Description	Default
XPCS_LOG_LEVEL	Logging verbosity (DEBUG, INFO, WARNING, ERROR)	INFO
XPCS_CACHE_SIZE_MB	Maximum cache size in MB	512
XPCS_THEME	UI theme (light, dark, system)	system

Project Structure

xpcsviewer/
├── module/            # Analysis modules (g2, saxs, twotime, ...)
├── fileIO/            # HDF5 I/O and Q-map utilities
├── simplemask/        # Mask editor & Q-map
├── gui/               # GUI modernization
│   ├── icons.py       # SVG icon loader with theme-aware colors
│   ├── theme/         # Light/dark theming
│   ├── state/         # Session & preferences
│   ├── shortcuts/     # Keyboard shortcuts
│   └── widgets/       # Modern UI widgets (incl. category tab bar)
├── fitting/           # Bayesian fitting (NLSQ 0.6.0)
├── plothandler/       # Theme-aware plotting
├── threading/         # Async workers
├── utils/             # Utilities, validation, exceptions
└── xpcs_file.py       # Core data class

Analysis Features

• Multi-tau G2 correlation with fitting

• Two-time correlation analysis

• SAXS 2D pattern visualization

• SAXS 1D radial averaging

• Sample stability monitoring

• File averaging tools

• Mask editing with drawing tools (Rectangle, Circle, Polygon, Line, Ellipse)

• Q-map generation from detector geometry

• Q-binning (partition) for XPCS analysis

Fitting Module (NLSQ 0.6.0)

Bayesian fitting with NumPyro NUTS sampler and JAX-accelerated NLSQ warm-start:

• Statistical metrics: R², adjusted R², RMSE, MAE, AIC, BIC

• Confidence intervals for parameter uncertainty

• Prediction intervals accounting for observation noise

• Models: single/double/stretched exponential, power law

• Automatic bounds inference and fallback strategies

• Model health diagnostics

from xpcsviewer.fitting import nlsq_fit
import jax.numpy as jnp

def model(x, tau, baseline, contrast):
    return baseline + contrast * jnp.exp(-2 * x / tau)

result = nlsq_fit(
    model, x_data, y_data, y_errors,
    p0={'tau': 1.0, 'baseline': 1.0, 'contrast': 0.3},
    bounds={'tau': (0.01, 100), 'baseline': (0.9, 1.1), 'contrast': (0.1, 0.5)},
)
print(f"R² = {result.r_squared:.4f}")
print(result.summary())

Gallery

Analysis Modules Showcase

1. SAXS 2D – Integrated Scattering Pattern

   

2. SAXS 1D – Radial Reduction and Analysis

   

3. Stability – Sample Assessment

   

4. I(t) – Intensity vs Time

   

5. g2 – Correlation Function Viewer

   

6. g2 Fit – Correlation Fitting

   

7. g2 Map – Correlation Map

   

8. Diffusion – tau(q) Characterization

   

9. Two-Time – Correlation Maps

   

10. Q-Map – Q-Space Mapping

    

11. Average – File Averaging Toolbox

    

12. Metadata – HDF5 Explorer

    

License

MIT License. See CONTRIBUTING.md for development guidelines.