xpcsviewer package

Main Package

XPCS Viewer - X-ray Photon Correlation Spectroscopy data analysis tool.

This package provides both a graphical user interface (GUI) and command-line interface (CLI) for analyzing XPCS data stored in HDF5/NeXus format.

Main Components:

XpcsFile: Core data container for XPCS datasets with lazy loading XpcsViewer: PySide6-based GUI for interactive analysis ViewerKernel: Backend for data processing and plot management FileLocator: File discovery and management utilities

Entry Points:

xpcsviewer-gui: Launch the graphical interface xpcsviewer: CLI for batch processing (e.g., twotime analysis)

Example

>>> from xpcsviewer import XpcsFile
>>> xf = XpcsFile('data.h5')
>>> print(f"Analysis type: {xf.atype}")

class xpcsviewer.FileLocator

Bases: object

Placeholder FileLocator class for documentation builds.

class xpcsviewer.ViewerKernel

Bases: object

Placeholder ViewerKernel class for documentation builds.

class xpcsviewer.ViewerUI

Bases: object

Placeholder ViewerUI class for documentation builds.

class xpcsviewer.XpcsViewer

Bases: object

Placeholder XpcsViewer class for documentation builds.

Core Classes

XpcsFile

class xpcsviewer.XpcsFile

Bases: object

Placeholder XpcsFile class for documentation builds.

The main data container class for XPCS datasets. Provides lazy loading of large data arrays and built-in analysis capabilities.

Note

XpcsFile automatically detects the analysis type (Multitau, Twotime, etc.) and loads appropriate data fields.

XpcsFile Submodules

The xpcsviewer.xpcs_file package splits internal concerns into submodules:

Cache

LRU data cache with memory-pressure awareness.

Data caching utilities for XpcsFile.

This module provides LRU caching with memory management for XPCS data.

class xpcsviewer.xpcs_file.cache.CacheItem(data, size_mb)

Bases: object

Individual cache item with metadata.

Parameters:

• data (Any)

• size_mb (float)

__init__(data, size_mb)

Parameters:

• data (Any)

• size_mb (float)

touch()

Mark item as accessed.

class xpcsviewer.xpcs_file.cache.DataCache(max_memory_mb=500.0, memory_pressure_threshold=0.85)

Bases: object

LRU cache with memory limit and automatic cleanup for XPCS data.

Features: - LRU eviction policy - Memory limit enforcement (default 500MB) - Automatic cleanup on memory pressure - Memory usage tracking per item - Thread-safe operations

Parameters:

• max_memory_mb (float)

• memory_pressure_threshold (float)

__init__(max_memory_mb=500.0, memory_pressure_threshold=0.85)

Parameters:

• max_memory_mb (float)

• memory_pressure_threshold (float)

put(file_path, data_type, data)

Store data in cache.

Parameters:

• file_path (str) – File path identifier

• data_type (str) – Type of data (‘saxs_2d’, ‘saxs_2d_log’, etc.)

• data (Any) – Data to cache

Returns:

True if successfully cached

Return type:

bool

get(file_path, data_type)

Retrieve data from cache.

Parameters:

• file_path (str) – File path identifier

• data_type (str) – Type of data

Returns:

Cached data or None if not found

Return type:

Any or None

clear()

Clear all cached data.

clear_file(file_path)

Clear all cached data for a specific file.

Parameters:

file_path (str)

get_stats()

Get cache statistics.

Return type:

dict[str, Any]

force_cleanup(target_memory_mb=None)

Force cleanup to target memory usage.

Parameters:

target_memory_mb (float | None)

Fitting Helpers

File-level fitting convenience functions used internally by fit_g2().

Fitting functions for XPCS analysis.

This module provides fitting functions for G2 correlation analysis.

These functions are JIT-traced by nlsq (a JAX-based curve fitting library), so they must use jax.numpy operations instead of numpy to avoid TracerArrayConversionError when nlsq traces them with JAX tracers.

xpcsviewer.xpcs_file.fitting.single_exp_all(x, a, b, c, d)

Single exponential fitting for XPCS-multitau analysis.

Parameters:

• x (float or ndarray) – Delay in seconds.

• a (float) – Contrast.

• b (float) – Characteristic time (tau).

• c (float) – Restriction factor.

• d (float) – Baseline offset.

Returns:

Computed value of the single exponential model.

Return type:

float or ndarray

xpcsviewer.xpcs_file.fitting.double_exp_all(x, a, b1, c1, d, b2, c2, f)

Double exponential fitting for XPCS-multitau analysis.

Parameters:

• x (float or ndarray) – Delay in seconds.

• a (float) – Contrast.

• b1 (float) – Characteristic time (tau) of the first exponential component.

• c1 (float) – Restriction factor for the first component.

• d (float) – Baseline offset.

• b2 (float) – Characteristic time (tau) of the second exponential component.

• c2 (float) – Restriction factor for the second component.

• f (float) – Fractional contribution of the first exponential component (0 ≤ f ≤ 1).

Returns:

Computed value of the double exponential model.

Return type:

float or ndarray

xpcsviewer.xpcs_file.fitting.power_law(x, a, b)

Power-law fitting for diffusion behavior.

Parameters:

• x (float or ndarray) – Independent variable, typically time delay (tau).

• a (float) – Scaling factor.

• b (float) – Power exponent.

Returns:

Computed value based on the power-law model.

Return type:

float or ndarray

xpcsviewer.xpcs_file.fitting.create_id(fname, label_style=None, simplify_flag=True)

Generate a simplified or customized ID string from a filename.

Parameters:

• fname (str) – Input file name, possibly with path and extension.

• label_style (str or None, optional) – Optional custom regex pattern for extracting a label from the filename. If None, uses simplified default label extraction.

• simplify_flag (bool, optional) – If True (default), applies default simplification logic.

Returns:

A simplified or customized ID string derived from the input filename.

Return type:

str

Memory Monitor

Virtual-memory monitoring for adaptive cache eviction.

Memory monitoring utilities for XpcsFile.

This module provides memory monitoring and status tracking for XPCS data operations.

class xpcsviewer.xpcs_file.memory.MemoryStatus(percent_used)

Bases: object

Container for memory status information.

Parameters:

percent_used (float)

__init__(percent_used)

Parameters:

percent_used (float)

class xpcsviewer.xpcs_file.memory.MemoryMonitor

Bases: object

Simple memory monitoring utilities using psutil.

get_memory_info()

Get current memory usage information.

Returns:

(used_mb, available_mb, pressure_ratio)

Return type:

tuple[float, float, float]

get_memory_status()

Get memory status object.

Returns:

Object containing percent_used attribute

Return type:

MemoryStatus

static get_memory_usage()

Get current memory usage in MB (static method for backward compatibility).

Return type:

tuple[float, float]

static get_memory_pressure()

Calculate memory pressure as a percentage (0-1) (static method for backward compatibility).

Return type:

float

static is_memory_pressure_high(threshold=0.85)

Check if memory pressure is above threshold (static method for backward compatibility).

Parameters:

threshold (float)

Return type:

bool

static estimate_array_memory(shape, dtype)

Estimate memory usage of a numpy array in MB.

Parameters:

• shape (tuple) – Array shape

• dtype (np.dtype) – Array data type

Returns:

Estimated memory usage in MB

Return type:

float

xpcsviewer.xpcs_file.memory.get_cached_memory_monitor()

Get or create a cached memory monitor instance.

Returns:

Singleton memory monitor instance

Return type:

MemoryMonitor

Package Information

xpcsviewer.__version__ = version string

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

xpcsviewer.__author__ = "Miaoqi Chu & Wei Chen"

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

xpcsviewer.__credits__ = "Argonne National Laboratory"

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.