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
| Property | Field | Unit |
|---|---|---|
| Dispersion coefficient | dispersion_delta |
dimensionless |
| Absorption coefficient | absorption_beta |
dimensionless |
| Scattering factors | scattering_factor_f1, f2 |
electrons |
| Critical angle | critical_angle_degrees |
degrees |
| Attenuation length | attenuation_length_cm |
cm |
| Scattering length density | real_sld_per_ang2, imaginary_sld_per_ang2 |
Å⁻² |
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
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.6},
year = {2024--2026}
}
License
MIT License. See LICENSE for details.
Acknowledgments
1 maintainer
Metadata
1 maintainer
Release files for xraylabtool 0.4.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| xraylabtool-0.4.6.tar.gz | 560.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| xraylabtool-0.4.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.2 MB
Release files / xraylabtool-0.4.6.tar.gz
| Download URL | xraylabtool-0.4.6.tar.gz |
|---|---|
| Size | 560.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1a02e0a626a6b922947552ebcf91088d394d7012c0a2ebde95de9f74cc9d6b6
|
|
BLAKE2b-256 checksum How to use checksums |
7d4b5cc9216a05560c620fa5c89a4622d5b4ff32de6ff08530dab029f484bc12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / xraylabtool-0.4.6-py3-none-any.whl
| Download URL | xraylabtool-0.4.6-py3-none-any.whl |
|---|---|
| Size | 654.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8dff1cb897214a4e4e62b201323231fd744629f4b3d40cef06a17ead7f6b3715
|
|
BLAKE2b-256 checksum How to use checksums |
b5fc8515551dc35d757d139b3a57d09919d15f29d8d7eeeda510a65ed15e0d72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
