Installation¶

Requirements¶

Python 3.12+
8 GB RAM minimum

Install¶

# Install from PyPI
pip install xpcsviewer-gui

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

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

# CLI batch processing
xpcsviewer twotime --input /data --output /results --q 0.05

All scientific dependencies (JAX, 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)]

Or install via project extras (ensures matching versions):

pip install "xpcsviewer-gui[gpu_cuda13]"   # CUDA 13
pip install "xpcsviewer-gui[gpu_cuda12]"   # CUDA 12

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`
`Backend: cpu` (GPU exists)	GPU JAX packages not installed	`make install-jax-gpu`

Diagnostics:

make gpu-check      # Verify backend, devices, SVD
make gpu-diagnose   # Check plugins, versions, conflicts

Development Install¶

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 .

Verify¶

import xpcsviewer
print(xpcsviewer.__version__)