Skip to main content

XRayLabTool

Python 3.12+ PyPI version License: MIT Documentation Status CI

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

# 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.

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.

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=1 opts out; library users opt in with XRAYLABTOOL_JAX_CACHE=1).
  • set_backend("jax") is kept as a no-op; set_backend("numpy") raises ValueError.
  • xraylabtool.calculators.optics.optical_properties is a pure device function that works under jax.jit, jax.vmap and jax.grad.
  • import xraylabtool, --help and --version do 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

  • CXRO — Atomic scattering factor databases
  • NIST — Reference data and validation
  • kkcalc (Benjamin Watts, Daniel J. Lauk) — Kramers-Kronig transform and tabulated f2 data, ported in xraylabtool.kk; method: B. Watts, Opt. Express 22(19), 23628–23639 (2014), doi:10.1364/OE.22.023628

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)

Source distribution for xraylabtool 0.5.0
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)

Table of built distributions (wheels) for xraylabtool 0.5.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page