Utilities Module

The utils module provides utility functions for formula parsing, unit conversions, and mathematical operations.

Device Detection

GPU detection and diagnostics (System CUDA).

xraylabtool.device.get_system_cuda_version()[source]

Detect system CUDA version from nvcc.

Returns (full_version, major_version) or (None, None). Example: (“13.1”, 13)

Return type:

tuple[str | None, int | None]

xraylabtool.device.get_gpu_info()[source]

Detect GPU name and SM version.

Returns (gpu_name, sm_version) or (None, None). Example: (“NVIDIA GeForce RTX 4090”, 8.9)

Return type:

tuple[str | None, float | None]

xraylabtool.device.check_plugin_conflicts()[source]

Check for known JAX CUDA plugin conflicts.

Returns list of issue descriptions (empty = no issues).

Return type:

list[str]

xraylabtool.device.check_gpu_availability(warn=True)[source]

Check if GPU is available and being used by JAX.

If GPU hardware is detected but JAX is in CPU mode, prints a diagnostic warning with installation instructions.

Returns True if GPU is being used by JAX, False otherwise.

Return type:

bool

Parameters:

warn (bool)

Get recommended JAX package based on system CUDA and GPU.

Returns “jax[cuda12-local]”, “jax[cuda13-local]”, or None.

Return type:

str | None

xraylabtool.device.get_device_info()[source]

Get comprehensive device information as a dictionary.

Return type:

dict

Logging Utilities

Centralized logging utilities for XRayLabTool.

This module provides a single entry point to configure logging across the library, CLI, and GUI. It keeps setup lightweight (stdlib-only) while still offering:

  • Rotating file logs (default location: ~/.cache/xraylabtool/logs/xraylabtool.log)

  • Optional console output (stderr) with readable timestamps

  • Environment-variable overrides for level, file path, and rotation

  • Quieting of noisy third-party libraries (matplotlib, asyncio)

Environment variables

  • XRAYLABTOOL_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO.

  • XRAYLABTOOL_LOG_FILE: Path to log file. If empty, file logging is disabled.

  • XRAYLABTOOL_LOG_DIR: Directory for default log file (overrides cache path).

  • XRAYLABTOOL_LOG_MAX_BYTES: Max size per log file before rotation (bytes). Default: 5_000_000.

  • XRAYLABTOOL_LOG_BACKUPS: Number of rotated backups to keep. Default: 3.

  • XRAYLABTOOL_LOG_CONSOLE: 1/0 toggle for console logging. Default: on.

Library consumers can opt in by calling configure_logging() early. The CLI and GUI call it automatically.

xraylabtool.logging_utils.configure_logging(*, level=None, log_file=None, console=None, force=False)[source]

Configure package-wide logging once and return the base logger.

Parameters:

  • level (str | int | None) – Logging level (DEBUG/INFO/…). Defaults to XRAYLABTOOL_LOG_LEVEL or INFO.

  • log_file (str | PathLike[str] | None) – Path to log file. If "" or None after env resolution, file logging is disabled. Defaults to XRAYLABTOOL_LOG_FILE or ~/.cache/xraylabtool/logs/xraylabtool.log.

  • console (bool | None) – Whether to emit logs to stderr. Defaults to XRAYLABTOOL_LOG_CONSOLE (on).

  • force (bool) – If True, reconfigure even if logging was already set up (useful in tests).

Return type:

Logger

xraylabtool.logging_utils.get_logger(name=None)[source]

Return a child logger under the xraylabtool namespace.

Calling this function ensures logging is configured once.

Return type:

Logger

Parameters:

name (str | None)

xraylabtool.logging_utils.get_log_file_path()[source]

Return the configured log file path if file logging is enabled.

Return type:

str | None

xraylabtool.logging_utils.log_environment(logger, *, component, extra_keys=None)[source]

Emit a single structured line capturing runtime context.

Return type:

None

Parameters:
xraylabtool.logging_utils.reset_logging()[source]

Reset logging configuration (intended for tests).

Return type:

None

Typing Extensions

Enhanced type definitions for XRayLabTool.

This module provides performance-optimized type aliases and definitions specifically designed for scientific computing applications. It includes specialized NumPy array types, protocol definitions, and type helpers that enable both type safety and high-performance vectorized operations.

Performance Note: - All type definitions use TYPE_CHECKING to avoid runtime overhead - NumPy array types specify dtypes for optimal memory layout - Protocol definitions enable duck typing without inheritance overhead

class xraylabtool.typing_extensions.AtomicDataProvider(*args, **kwargs)[source]

Bases: Protocol

Protocol for atomic data sources with performance guarantees.

get_scattering_factors(element, energies)[source]

Get atomic scattering factors for element at given energies.

Parameters:
Returns:

Complex scattering factors (f1 + if2)

Return type:

ndarray[tuple[Any, ...], dtype[cdouble]]

is_element_cached(element)[source]

Check if element data is cached for fast access.

Return type:

bool

Parameters:

element (str)

__init__(*args, **kwargs)
class xraylabtool.typing_extensions.InterpolatorProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for high-performance interpolation functions.

__call__(x)[source]

Interpolate values at given x coordinates.

Return type:

ndarray[tuple[Any, ...], dtype[floating[Any]]]

Parameters:

x (ndarray[tuple[Any, ...], dtype[float64]])

property extrapolation_mode: str

Get extrapolation behavior (‘linear’, ‘constant’, ‘error’).

__init__(*args, **kwargs)
class xraylabtool.typing_extensions.CalculationEngine(*args, **kwargs)[source]

Bases: Protocol

Protocol for X-ray calculation engines.

calculate_optical_constants(formula, energies, density)[source]

Calculate dispersion and absorption coefficients.

Returns:

Dispersion (δ) and absorption (β) coefficients

Return type:

tuple[ndarray[tuple[Any, ...], dtype[double]], ndarray[tuple[Any, ...], dtype[double]]]

Parameters:
calculate_derived_quantities(dispersion, absorption, energies)[source]

Calculate derived quantities from optical constants.

Return type:

dict[str, ndarray[tuple[Any, ...], dtype[floating[Any]]]]

Parameters:
__init__(*args, **kwargs)
class xraylabtool.typing_extensions.PerformanceMetrics(*args, **kwargs)[source]

Bases: Protocol

Protocol for performance measurement and validation.

property calculations_per_second: float

Get current calculation rate in calculations/second.

property memory_usage_mb: float

Get current memory usage in MB.

validate_performance_target(target_cps=150000.0)[source]

Validate that performance meets target calculations/second.

Return type:

bool

Parameters:

target_cps (float)

__init__(*args, **kwargs)
xraylabtool.typing_extensions.validate_energy_array(energies)[source]

Validate that input is a proper energy array.

Parameters:

energies (Any) – Input to validate

Returns:

True if valid energy array

Return type:

bool

xraylabtool.typing_extensions.validate_complex_array(array)[source]

Validate that input is a proper complex scattering factor array.

Parameters:

array (Any) – Input to validate

Returns:

True if valid complex array

Return type:

bool

xraylabtool.typing_extensions.ensure_float64_array(array)[source]

Ensure input is converted to float64 array for performance.

Parameters:

array (Sequence[float] | ndarray[tuple[Any, ...], dtype[Any]]) – Input array or sequence

Returns:

Converted float64 array

Return type:

ndarray[tuple[Any, ...], dtype[double]]

xraylabtool.typing_extensions.ensure_complex128_array(array)[source]

Ensure input is converted to complex128 array for performance.

Parameters:

array (Sequence[float] | ndarray[tuple[Any, ...], dtype[Any]]) – Input array or sequence

Returns:

Converted complex128 array

Return type:

ndarray[tuple[Any, ...], dtype[cdouble]]

xraylabtool.typing_extensions.is_energy_array(obj)[source]

Type guard for energy arrays.

Return type:

bool

Parameters:

obj (Any)

xraylabtool.typing_extensions.is_complex_array(obj)[source]

Type guard for complex arrays.

Return type:

bool

Parameters:

obj (Any)

xraylabtool.typing_extensions.is_real_array(obj)[source]

Type guard for real arrays.

Return type:

bool

Parameters:

obj (Any)

xraylabtool.typing_extensions.optimize_array_memory_layout(array)[source]

Optimize array memory layout for performance.

Parameters:

array (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Input array

Returns:

Memory-optimized array

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

xraylabtool.typing_extensions.get_optimal_chunk_size(array_length, memory_limit_mb=100.0)[source]

Calculate optimal chunk size for batch processing.

Parameters:

  • array_length (int) – Total array length

  • memory_limit_mb (float) – Memory limit in MB

Returns:

Optimal chunk size

Return type:

int

Utility functions for XRayLabTool.

This module contains helper functions for data processing, unit conversions, mathematical operations, and other common tasks in X-ray analysis.

xraylabtool.utils.angle_from_q(q, wavelength)[source]

Calculate scattering angle from momentum transfer q.

Parameters:
Return type:

float

Returns:

Scattering angle (2θ) in degrees

xraylabtool.utils.background_subtraction(x, y, method='linear')[source]

Perform background subtraction on diffraction data.

Parameters:
Return type:

ndarray

Returns:

Background-subtracted y data

xraylabtool.utils.bragg_angle(d_spacing, wavelength, order=1)[source]

Calculate Bragg angle for given d-spacing and wavelength.

Parameters:
Return type:

float

Returns:

Bragg angle in degrees

xraylabtool.utils.d_spacing_cubic(h, k, miller_l, a)[source]

Calculate d-spacing for cubic crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

xraylabtool.utils.d_spacing_orthorhombic(h, k, miller_l, a, b, c)[source]

Calculate d-spacing for orthorhombic crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

xraylabtool.utils.d_spacing_tetragonal(h, k, miller_l, a, c)[source]

Calculate d-spacing for tetragonal crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

xraylabtool.utils.energy_to_wavelength(energy, units='angstrom')[source]

Convert X-ray energy to wavelength.

Parameters:
Return type:

float

Returns:

Wavelength in specified units

xraylabtool.utils.find_peaks(x, y, prominence=0.1, distance=10)[source]

Find peaks in diffraction data.

Parameters:
Return type:

tuple[ndarray, dict[str, Any]]

Returns:

Tuple of (peak_indices, peak_properties)

xraylabtool.utils.get_atomic_data(element_symbol)[source]

Get comprehensive atomic data for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Returns:

  • symbol: Element symbol

  • atomic_number: Atomic number

  • atomic_weight: Atomic weight in u

  • name: Element name

  • density: Density in g/cm³ (if available)

Return type:

dict[str, Any]

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_data
>>> data = get_atomic_data('Si')
>>> data['atomic_number']
14
>>> data['symbol']
'Si'
xraylabtool.utils.get_atomic_number(element_symbol)[source]

Get atomic number for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Return type:

int

Returns:

Atomic number as integer

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_number
>>> get_atomic_number('H')
1
>>> get_atomic_number('C')
6
>>> get_atomic_number('Si')
14
xraylabtool.utils.get_atomic_weight(element_symbol)[source]

Get atomic weight for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Return type:

float

Returns:

Atomic weight in u (atomic mass units)

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_weight
>>> round(get_atomic_weight('H'), 3)
1.008
>>> round(get_atomic_weight('C'), 3)
12.011
>>> round(get_atomic_weight('O'), 3)
15.999
xraylabtool.utils.load_atomic_data(element_symbol)

Get comprehensive atomic data for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Returns:

  • symbol: Element symbol

  • atomic_number: Atomic number

  • atomic_weight: Atomic weight in u

  • name: Element name

  • density: Density in g/cm³ (if available)

Return type:

dict[str, Any]

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_data
>>> data = get_atomic_data('Si')
>>> data['atomic_number']
14
>>> data['symbol']
'Si'
xraylabtool.utils.normalize_intensity(y, method='max')[source]

Normalize intensity data.

Parameters:
Return type:

ndarray

Returns:

Normalized intensity data

xraylabtool.utils.parse_formula(formula_str)[source]

Parse a chemical formula string into element symbols and their counts.

Canonical formula parser for the entire codebase. Supports: - Element symbols with integer or decimal stoichiometry (SiO2, H0.5He0.5) - Parentheses, including nested (Ca5(PO4)3OH, Ca10(PO4)6(OH)2)

Parameters:

formula_str (str) – Chemical formula string (e.g., “SiO2”, “Al2O3”, “Ca5(PO4)3OH”)

Returns:

  • element_symbols: List of element symbols as strings

  • element_counts: List of corresponding stoichiometric counts as floats

Return type:

tuple[list[str], list[float]]

Raises:

FormulaError – If formula string is empty, contains unmatched parentheses, or no elements are found.

Examples

>>> from xraylabtool.utils import parse_formula
>>> parse_formula("SiO2")
(['Si', 'O'], [1.0, 2.0])
>>> parse_formula("Ca5(PO4)3OH")
(['Ca', 'P', 'O', 'H'], [5.0, 3.0, 12.0, 1.0])
xraylabtool.utils.progress_bar(iterable, desc='Processing')[source]

Create a progress bar for iterations.

Parameters:

  • iterable (Any) – Iterable to wrap

  • desc (str) – Description for progress bar

Return type:

Any | Iterator[Any]

Returns:

tqdm progress bar

xraylabtool.utils.q_from_angle(two_theta, wavelength)[source]

Calculate momentum transfer q from scattering angle.

Parameters:
Return type:

float

Returns:

Momentum transfer q in Ų⁻¹

xraylabtool.utils.save_processed_data(x, y, filename, header='# X-ray diffraction data')[source]

Save processed data to file.

Parameters:
Return type:

None

xraylabtool.utils.smooth_data(x, y, window_size=5)[source]

Apply moving average smoothing to data using optimized NumPy convolution.

This optimized version uses numpy convolution instead of pandas rolling, providing 3-5x speedup for typical use cases.

Parameters:
Return type:

ndarray

Returns:

Smoothed y data

xraylabtool.utils.wavelength_to_energy(wavelength, units='angstrom')[source]

Convert X-ray wavelength to energy.

Parameters:
Return type:

float

Returns:

Energy in keV

Chemical Formula Parsing

xraylabtool.utils.parse_formula(formula_str)[source]

Parse a chemical formula string into element symbols and their counts.

Canonical formula parser for the entire codebase. Supports: - Element symbols with integer or decimal stoichiometry (SiO2, H0.5He0.5) - Parentheses, including nested (Ca5(PO4)3OH, Ca10(PO4)6(OH)2)

Parameters:

formula_str (str) – Chemical formula string (e.g., “SiO2”, “Al2O3”, “Ca5(PO4)3OH”)

Returns:

  • element_symbols: List of element symbols as strings

  • element_counts: List of corresponding stoichiometric counts as floats

Return type:

tuple[list[str], list[float]]

Raises:

FormulaError – If formula string is empty, contains unmatched parentheses, or no elements are found.

Examples

>>> from xraylabtool.utils import parse_formula
>>> parse_formula("SiO2")
(['Si', 'O'], [1.0, 2.0])
>>> parse_formula("Ca5(PO4)3OH")
(['Ca', 'P', 'O', 'H'], [5.0, 3.0, 12.0, 1.0])

Parse a chemical formula string into element symbols and their counts.

Parameters: - formula_str (str): Chemical formula string (e.g., “SiO2”, “Al2O3”, “H0.5He0.5”)

Returns: - tuple: (element_symbols, element_counts) where element_symbols is a list of element symbols and element_counts is a list of corresponding stoichiometric counts

Examples:

from xraylabtool.utils import parse_formula

# Simple compounds
symbols, counts = parse_formula("SiO2")
print(symbols, counts)  # ['Si', 'O'] [1.0, 2.0]

# Complex compounds
symbols, counts = parse_formula("Al2O3")
print(symbols, counts)  # ['Al', 'O'] [2.0, 3.0]

# Fractional compositions
symbols, counts = parse_formula("H0.5He0.5")
print(symbols, counts)  # ['H', 'He'] [0.5, 0.5]

Atomic Data Functions

xraylabtool.utils.get_atomic_number(element_symbol)[source]

Get atomic number for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Return type:

int

Returns:

Atomic number as integer

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_number
>>> get_atomic_number('H')
1
>>> get_atomic_number('C')
6
>>> get_atomic_number('Si')
14

Get atomic number for given element symbol with LRU caching.

Example:

from xraylabtool.utils import get_atomic_number

atomic_num = get_atomic_number('Si')
print(atomic_num)  # 14
xraylabtool.utils.get_atomic_weight(element_symbol)[source]

Get atomic weight for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Return type:

float

Returns:

Atomic weight in u (atomic mass units)

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_weight
>>> round(get_atomic_weight('H'), 3)
1.008
>>> round(get_atomic_weight('C'), 3)
12.011
>>> round(get_atomic_weight('O'), 3)
15.999

Get atomic weight for given element symbol with LRU caching.

Example:

from xraylabtool.utils import get_atomic_weight

atomic_weight = get_atomic_weight('Si')
print(f"Silicon atomic weight: {atomic_weight:.3f} u")
xraylabtool.utils.get_atomic_data(element_symbol)[source]

Get comprehensive atomic data for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Returns:

  • symbol: Element symbol

  • atomic_number: Atomic number

  • atomic_weight: Atomic weight in u

  • name: Element name

  • density: Density in g/cm³ (if available)

Return type:

dict[str, Any]

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_data
>>> data = get_atomic_data('Si')
>>> data['atomic_number']
14
>>> data['symbol']
'Si'

Get atomic data for given element symbol with LRU caching.

Example:

from xraylabtool.utils import get_atomic_data

data = get_atomic_data('Si')
print(f"Symbol: {data['symbol']}")
print(f"Atomic number: {data['atomic_number']}")
print(f"Atomic weight: {data['atomic_weight']}")
xraylabtool.utils.load_atomic_data(element_symbol)

Get comprehensive atomic data for given element symbol with LRU caching.

Parameters:

element_symbol (str) – Element symbol (e.g., ‘H’, ‘C’, ‘N’, ‘O’, ‘Si’, ‘Al’)

Returns:

  • symbol: Element symbol

  • atomic_number: Atomic number

  • atomic_weight: Atomic weight in u

  • name: Element name

  • density: Density in g/cm³ (if available)

Return type:

dict[str, Any]

Raises:

  • UnknownElementError – If element symbol is not recognized

  • AtomicDataError – If there’s an issue loading atomic data

Examples

>>> from xraylabtool.utils import get_atomic_data
>>> data = get_atomic_data('Si')
>>> data['atomic_number']
14
>>> data['symbol']
'Si'

Backward compatibility alias for get_atomic_data.

Unit Conversions

xraylabtool.utils.energy_to_wavelength(energy, units='angstrom')[source]

Convert X-ray energy to wavelength.

Parameters:
Return type:

float

Returns:

Wavelength in specified units

Convert X-ray energy to wavelength.

Parameters: - energy (float): Energy in keV - units (str): Desired units of wavelength (‘angstrom’, ‘nm’, ‘m’)

Returns: - float: Wavelength in specified units

Example:

from xraylabtool.utils import energy_to_wavelength

# Convert 8 keV to wavelength in Angstroms
wavelength = energy_to_wavelength(8.0)  # 8 keV
print(f"8 keV = {wavelength:.3f} Å")
xraylabtool.utils.wavelength_to_energy(wavelength, units='angstrom')[source]

Convert X-ray wavelength to energy.

Parameters:
Return type:

float

Returns:

Energy in keV

Convert X-ray wavelength to energy.

Parameters: - wavelength (float): Wavelength value - units (str): Units of wavelength (‘angstrom’, ‘nm’, ‘m’)

Returns: - float: Energy in keV

Example:

from xraylabtool.utils import wavelength_to_energy

# Convert 1.55 Å to energy
energy = wavelength_to_energy(1.55)  # Copper K-alpha
print(f"1.55 Å = {energy:.1f} keV")

Crystallographic and Diffraction Functions

xraylabtool.utils.bragg_angle(d_spacing, wavelength, order=1)[source]

Calculate Bragg angle for given d-spacing and wavelength.

Parameters:
Return type:

float

Returns:

Bragg angle in degrees

Calculate Bragg angle for given d-spacing and wavelength.

Example:

from xraylabtool.utils import bragg_angle

# Calculate Bragg angle for Si(111) reflection at 8 keV
d_spacing = 3.14  # Angstroms for Si(111)
wavelength = 1.55  # Angstroms (8 keV)
angle = bragg_angle(d_spacing, wavelength)
print(f"Bragg angle: {angle:.2f} degrees")
xraylabtool.utils.d_spacing_cubic(h, k, miller_l, a)[source]

Calculate d-spacing for cubic crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

Calculate d-spacing for cubic crystal system.

Example:

from xraylabtool.utils import d_spacing_cubic

# Si(111) d-spacing
d = d_spacing_cubic(1, 1, 1, 5.43)  # Si lattice parameter
print(f"Si(111) d-spacing: {d:.3f} Å")
xraylabtool.utils.d_spacing_tetragonal(h, k, miller_l, a, c)[source]

Calculate d-spacing for tetragonal crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

Calculate d-spacing for tetragonal crystal system.

xraylabtool.utils.d_spacing_orthorhombic(h, k, miller_l, a, b, c)[source]

Calculate d-spacing for orthorhombic crystal system.

Parameters:
Return type:

float

Returns:

d-spacing in Angstroms

Calculate d-spacing for orthorhombic crystal system.

xraylabtool.utils.q_from_angle(two_theta, wavelength)[source]

Calculate momentum transfer q from scattering angle.

Parameters:
Return type:

float

Returns:

Momentum transfer q in Ų⁻¹

Calculate momentum transfer q from scattering angle.

Example:

from xraylabtool.utils import q_from_angle

q = q_from_angle(28.4, 1.55)  # 2theta, wavelength
print(f"Momentum transfer: {q:.3f} Å⁻¹")
xraylabtool.utils.angle_from_q(q, wavelength)[source]

Calculate scattering angle from momentum transfer q.

Parameters:
Return type:

float

Returns:

Scattering angle (2θ) in degrees

Calculate scattering angle from momentum transfer q.

Data Processing and Analysis

xraylabtool.utils.smooth_data(x, y, window_size=5)[source]

Apply moving average smoothing to data using optimized NumPy convolution.

This optimized version uses numpy convolution instead of pandas rolling, providing 3-5x speedup for typical use cases.

Parameters:
Return type:

ndarray

Returns:

Smoothed y data

Apply moving average smoothing to data using optimized NumPy convolution.

Example:

from xraylabtool.utils import smooth_data
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x) + 0.1 * np.random.randn(100)  # Noisy data
smoothed = smooth_data(x, y, window_size=5)
xraylabtool.utils.find_peaks(x, y, prominence=0.1, distance=10)[source]

Find peaks in diffraction data.

Parameters:
Return type:

tuple[ndarray, dict[str, Any]]

Returns:

Tuple of (peak_indices, peak_properties)

Find peaks in diffraction data.

Example:

from xraylabtool.utils import find_peaks
import numpy as np

x = np.linspace(0, 50, 1000)
y = np.exp(-((x-20)**2)/10) + np.exp(-((x-30)**2)/5)  # Two peaks
peaks, properties = find_peaks(x, y, prominence=0.1)
print(f"Found {len(peaks)} peaks at x = {properties['x_values']}")
xraylabtool.utils.background_subtraction(x, y, method='linear')[source]

Perform background subtraction on diffraction data.

Parameters:
Return type:

ndarray

Returns:

Background-subtracted y data

Perform background subtraction on diffraction data.

xraylabtool.utils.normalize_intensity(y, method='max')[source]

Normalize intensity data.

Parameters:
Return type:

ndarray

Returns:

Normalized intensity data

Normalize intensity data.

Example:

from xraylabtool.utils import normalize_intensity
import numpy as np

intensity = np.array([100, 200, 150, 300, 250])
normalized = normalize_intensity(intensity, method="max")
print(normalized)  # [0.33, 0.67, 0.5, 1.0, 0.83]

Utility Functions

xraylabtool.utils.progress_bar(iterable, desc='Processing')[source]

Create a progress bar for iterations.

Parameters:

  • iterable (Any) – Iterable to wrap

  • desc (str) – Description for progress bar

Return type:

Any | Iterator[Any]

Returns:

tqdm progress bar

Create a progress bar for iterations.

Example:

from xraylabtool.utils import progress_bar

for i in progress_bar(range(100), desc="Processing"):
    # Your processing code here
    pass
xraylabtool.utils.save_processed_data(x, y, filename, header='# X-ray diffraction data')[source]

Save processed data to file.

Parameters:
Return type:

None

Save processed data to file.

Example:

from xraylabtool.utils import save_processed_data
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
save_processed_data(x, y, "sine_data.txt", header="# x, sin(x) data")