XRayLabTool

Ultra-fast Python package and CLI for calculating X-ray optical properties of materials using CXRO/NIST atomic scattering factor data. Supports NumPy and JAX backends for CPU/GPU acceleration.

Installation

Using uv (Recommended)

# Core package (NumPy + JAX CPU backends, CLI, GUI)
uv pip install xraylabtool

# NVIDIA GPU acceleration (pick the CUDA major matching your driver)
uv pip install "xraylabtool[gpu_cuda13]"
uv pip install "xraylabtool[gpu_cuda12]"

Using pip

pip install xraylabtool

Development

git clone https://github.com/imewei/pyXRayLabTool.git
cd pyXRayLabTool
uv sync

Quick Start

Python API

import xraylabtool as xlt

# Single material at 10 keV
result = xlt.calculate_single_material_properties("SiO2", 10.0, 2.2)
print(f"Critical angle: {result.critical_angle_degrees[0]:.3f}°")
print(f"Attenuation length: {result.attenuation_length_cm[0]:.2f} cm")

# Multiple materials comparison
materials = {"SiO2": 2.2, "Si": 2.33, "Al2O3": 3.95, "C": 3.52}
results = xlt.calculate_xray_properties(
    list(materials.keys()), 10.0, list(materials.values())
)
for formula, r in results.items():
    print(f"{formula:6}: θc = {r.critical_angle_degrees[0]:.3f}°")

Command-Line Interface

xraylabtool calc SiO2 -e 10.0 -d 2.2           # Single material
xraylabtool calc Si -e 5-15:11 -d 2.33 -o out.csv  # Energy sweep
xraylabtool convert energy 8.048,10.0 --to wavelength
xraylabtool formula Al2O3                         # Formula analysis
xraylabtool bragg -d 3.14,2.45 -e 8.048          # Bragg angles
xraylabtool batch materials.csv -o results.csv    # Batch processing
xraylabtool completion install                    # Shell tab-completion

xtool is a short alias for xraylabtool (e.g. xtool calc SiO2 -e 10.0 -d 2.2). Shell tab-completion installed via xraylabtool completion install works for both names.

GUI

xraylabtool-gui        # or the short alias: xtool-gui
python -m xraylabtool.gui   # equivalent module form

Single-material analysis and multi-material comparison with interactive plots and CSV/PNG export.

Calculated Properties

All properties are returned as NumPy arrays in the XRayResult dataclass, supporting single energies or energy sweeps.

Backend Selection

JAX is selected automatically when JAX and an NVIDIA GPU are available; otherwise NumPy. Override at runtime:

from xraylabtool.backend import set_backend

set_backend("jax")  # JIT-compiled kernels; GPU needs the gpu_cuda12/13 extra
set_backend("numpy")  # default on CPU-only machines

Scientific Background

Calculations use Henke, Gullikson, and Davis atomic scattering factor tabulations (0.03–30 keV):

• Refractive index: n = 1 - δ - iβ
• Critical angle: θc = √(2δ)
• Attenuation: Beer-Lambert law with μ = 4πβ/λ

Documentation

Full documentation: pyxraylabtool.readthedocs.io

• API Reference
• CLI Guide
• Migration Guide (v0.3 → v0.4)
• Architecture Decisions
• Changelog

Development

uv sync                          # Install dependencies
uv run pytest                    # Run tests
uv run ruff check .              # Lint
uv run ruff format .             # Format
uv run sphinx-build docs docs/_build/html  # Build docs
make test                        # Or use Makefile shortcuts

Citation

@software{xraylabtool,
  title = {XRayLabTool: High-Performance X-ray Optical Properties Calculator},
  author = {Wei Chen},
  url = {https://github.com/imewei/pyXRayLabTool},
  version = {0.4.7},
  year = {2024--2026}
}

License

MIT License. See LICENSE for details.

Acknowledgments

• CXRO — Atomic scattering factor databases
• NIST — Reference data and validation