XRayLabTool
Python package and CLI for calculating X-ray optical properties of materials using CXRO/NIST atomic scattering factor data. The calculations are JAX-first (float64) and run on the CPU or an NVIDIA GPU.
Installation
Using uv (Recommended)
# Core package (JAX on CPU, 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
Using conda
# Core package (CPU only) from the imewei channel; dependencies come from conda-forge
conda install -c imewei -c conda-forge xraylabtool
The conda package does not include the CUDA GPU extras; use pip or uv for GPU support.
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 kk Si --energies 8,10,12 # Kramers-Kronig f1 from f2 (keV)
xraylabtool completion install # Shell tab-completion
xtool and xlt are short aliases 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 aliases: xtool-gui, xlt-gui
python -m xraylabtool.gui # equivalent module form
Single-material analysis, multi-material comparison and Kramers-Kronig f1 reconstruction with interactive plots and CSV/PNG export. The window opens maximized.
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.
JAX Backend
All calculations run in JAX with float64 on JAX's default device: the CPU, or the
GPU of a CUDA install (gpu_cuda12/gpu_cuda13 extra). There is no NumPy backend and
no switch to select one; set JAX_PLATFORMS=cpu to force the CPU.
- The first compute call compiles a small program (a fraction of a second on CPU); later
calls with the same shape buckets compile nothing.
xraylabtool.warm_up()precompiles explicitly (energy_counts=also warms the energy buckets you will use), and the CLI and GUI keep a persistent compile cache (XRAYLABTOOL_NO_JAX_CACHE=1opts out; library users opt in withXRAYLABTOOL_JAX_CACHE=1). set_backend("jax")is kept as a no-op;set_backend("numpy")raisesValueError.xraylabtool.calculators.optics.optical_propertiesis a pure device function that works underjax.jit,jax.vmapandjax.grad.import xraylabtool,--helpand--versiondo not import JAX.
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.5.0},
year = {2024--2026}
}
License
MIT, with bundled kkcalc material under Zlib (see NOTICE). See LICENSE for details.
Acknowledgments
Metadata
Release files for xraylabtool 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xraylabtool-0.5.0.tar.gz | 2.5 MB | With provenance | Details for xraylabtool-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xraylabtool-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for xraylabtool-0.5.0-py3-none-any.whl |
Total release size: 5.1 MB
Release files / xraylabtool-0.5.0.tar.gz
| Download URL | xraylabtool-0.5.0.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6d463de4fb0e2d686b4b3c41c4492c64b743f329efa0b548d560509db4c7c45
|
|
BLAKE2b-256 checksum How to use checksums |
51440617ff8657c424fed2ced0011f8298cfb90b8cf32dce6522ece9dc425513
|
| 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 Oct 29, 2026.
Transparency logRelease files / xraylabtool-0.5.0-py3-none-any.whl
| Download URL | xraylabtool-0.5.0-py3-none-any.whl |
|---|---|
| Size | 2.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
df3c258e09342bdc95eb8223159fe79b325c012a7e8448205c5ec4764fd71e77
|
|
BLAKE2b-256 checksum How to use checksums |
1430dca3463c8507a3b6fb5bd61c7b6abfe612314db15527deacb1082ce6f509
|
| 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 Oct 29, 2026.
Transparency logSecurity for xraylabtool 0.5.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xraylabtool-0.5.0.tar.gz
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 Oct 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.