XRayLabTool Documentation

PyPI version Python versions

XRayLabTool is a Python package and command-line tool for calculating X-ray optical properties of materials. It provides both a Python API and CLI for synchrotron scientists, materials researchers, and X-ray optics developers.

Key Features

Performance

  • 150,000+ calculations per second

  • Preloaded atomic data cache for 10-50x speed improvement

  • Vectorized calculations and smart memory management

  • JAX JIT compilation for 5-100x additional speedup (optional)

X-ray Physics

  • Complex refractive index calculations

  • Attenuation coefficients and penetration depths

  • Critical angles for total external reflection

  • Transmission and reflection coefficients

Architecture (v0.4.0)

  • Backend abstraction: Runtime switching between NumPy and JAX via set_backend()

  • Modular design with focused sub-packages:

    • calculators: Core X-ray physics calculations

    • data_handling: Atomic data caching and batch processing

    • interfaces: CLI and completion systems

    • io: File operations and export functionality

    • validation: Input validation and error handling

    • analysis: Material comparison and absorption edge detection

    • export: CSV/JSON export for downstream analysis

    • backend: NumPy/JAX array backend abstraction

    • gui: PySide6 desktop application with PyQtGraph interactive plots

  • Type-safe with complete type hints

  • 202 characterization tests with golden-value assertions

  • Cross-platform compatibility (Linux, macOS, Windows)

CLI Interface

  • 10+ commands for common tasks and completion management

  • Multiple output formats (table, CSV, JSON)

  • Virtual environment-centric shell completion (bash, zsh, fish, PowerShell)

  • Batch processing from CSV files

  • Environment isolation for completion

Scientific Data Handling

  • Built on CXRO/NIST atomic scattering databases

  • Support for energy ranges and arrays

  • Chemical formula parsing and validation

  • Export capabilities for downstream analysis

Quick Start

Interactive Notebooks

Open the notebook gallery (Colab / nbviewer links) on the Examples page.

Installation

pip install xraylabtool          # Core (NumPy backend)
pip install xraylabtool[jax]     # With JAX backend
pip install xraylabtool[plots]   # With matplotlib

Basic Usage

Python API:

import xraylabtool as xrt

# Calculate X-ray properties for silicon at 8 keV
result = xrt.calculate_single_material_properties(
    formula="Si",
    density=2.33,
    energy=8000
)

print(f"Critical angle: {result.critical_angle_degrees:.3f}°")
print(f"Attenuation length: {result.attenuation_length_cm:.2f} cm")

Command Line:

# Single material calculation
xraylabtool calc Si --density 2.33 --energy 8000

# Batch processing
xraylabtool batch materials.csv --output results.csv

Performance Highlights

Operation

Speed

Use Case

Single calculation

< 0.1 ms

Interactive analysis

Batch processing (1000 materials)

< 10 ms

High-throughput screening

Energy array (100 points)

< 1 ms

Spectroscopy analysis

Target Audience

  • Synchrotron Scientists: Beamline optimization and experimental planning

  • Materials Researchers: X-ray characterization and property prediction

  • X-ray Optics Developers: Mirror and multilayer design

  • Students & Educators: Learning X-ray physics and optics

Citation

If you use XRayLabTool in your research, please cite:

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

Indices and Tables