xraylabtool 0.4.0

Ultra-fast Python package for X-ray optical properties calculation with CXRO/NIST data, CLI tools, and synchrotron applications

XRayLabTool

Python package and CLI for calculating X-ray optical properties of materials using CXRO/NIST atomic scattering factor data.

Installation

pip install xraylabtool

# Or with uv (recommended for 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

GUI

python -m xraylabtool.gui

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.

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
• Shell Completion
• Changelog

Development

make test          # Run tests with coverage
make test-all      # Full suite (unit + integration + perf + CLI)
make format        # Format with ruff
make lint          # Lint with ruff
make docs          # Build Sphinx docs

Citation

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

License

MIT License. See LICENSE for details.

Acknowledgments

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