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
uv pip install xraylabtool

# With JAX backend for GPU acceleration
uv pip install "xraylabtool[jax]"

# With matplotlib for publication plots
uv pip install "xraylabtool[plots]"

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.

GUI overview

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

import xraylabtool as xlt

# Switch to JAX for JIT-compiled GPU acceleration
xlt.set_backend("jax")

# Switch back to NumPy (default)
xlt.set_backend("numpy")

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.5},
  year = {2024--2026}
}

License

MIT License. See LICENSE for details.

Acknowledgments

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

xray x-ray xrd xrr saxs crystallography diffraction scattering synchrotron beamline optics reflectometry absorption spectroscopy materials-science condensed-matter physics chemistry nanotechnology thin-films multilayers nanostructures characterization cxro nist atomic-scattering-factors optical-constants refractive-index critical-angle attenuation-length form-factors dispersion absorption-coefficient high-performance vectorized batch-processing parallel-processing scientific-computing numerical-analysis laboratory analysis cli command-line python-package api cross-platform shell-completion bash-completion zsh-completion fish-completion powershell-completion tab-completion virtual-environment environment-isolation materials-characterization structure-analysis quality-control medical-imaging industrial-radiography non-destructive-testing

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xraylabtool-0.4.5.tar.gz (555.6 kB view details)

Uploaded Aug 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

xraylabtool-0.4.5-py3-none-any.whl (639.1 kB view details)

Uploaded Aug 12, 2026 Python 3

File details

Details for the file xraylabtool-0.4.5.tar.gz.

File metadata

Download URL: xraylabtool-0.4.5.tar.gz
Upload date: Aug 12, 2026
Size: 555.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for xraylabtool-0.4.5.tar.gz
Algorithm	Hash digest
SHA256	`0a1f53eed22a9d222430b57aacb4dad1c888afd7a81cad8ec4b21a1082c07fd7`
MD5	`d39c5f18345f205b1eb4fa67394f3b87`
BLAKE2b-256	`64182cbf574a806cb7194b74da84f8ceb6d0987347f3a92f08cdf99c0cbf213d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xraylabtool-0.4.5.tar.gz:

Publisher: publish.yml on imewei/pyXRayLabTool

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xraylabtool-0.4.5.tar.gz
- Subject digest: 0a1f53eed22a9d222430b57aacb4dad1c888afd7a81cad8ec4b21a1082c07fd7
- Sigstore transparency entry: 2439193478
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: imewei/pyXRayLabTool@f273f5096d79278a7a3cfba8d34ba93b5420f840
- Branch / Tag: refs/heads/main
- Owner: https://github.com/imewei
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@f273f5096d79278a7a3cfba8d34ba93b5420f840
- Trigger Event: workflow_dispatch