Getting Started¶

This guide shows XRayLabTool installation and basic usage.

Interactive Notebook¶

Open the Getting Started notebook directly (no embedded render in the docs):

Installation¶

System Requirements¶

XRayLabTool requires:

Python 3.12 or higher
Operating System: Windows, macOS, or Linux
Memory: Minimum 512 MB RAM (recommended 2 GB for large calculations)
Storage: 50 MB for basic installation

Install from PyPI¶

Install XRayLabTool using pip:

# Core package (NumPy backend)
pip install xraylabtool

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

# With matplotlib for publication-quality plots
pip install xraylabtool[plots]

Development Installation¶

For development or to get the latest features (uses uv):

git clone https://github.com/imewei/pyXRayLabTool.git
cd pyXRayLabTool
uv sync
uv run pytest  # verify installation

Verify Installation¶

Verify installation:

# Test CLI
xraylabtool --version
xraylabtool --help

# Test Python API
python -c "import xraylabtool; print('Installation successful!')"

Shell Completion (Virtual Environment-Centric)¶

Install completion in your current virtual environment:

# Install completion in current environment
xraylabtool completion install

# Verify installation
xraylabtool completion status

# List all environments with completion status
xraylabtool completion list

The new completion system provides:

Environment Isolation: Completion only available when environment is active
Multi-Shell Support: Native completion for bash, zsh, fish, PowerShell
No System Changes: No sudo required, installs per environment
Auto-Activation: Completion activates/deactivates with environment

For legacy compatibility, the old commands still work:

xraylabtool install-completion    # Uses new system backend

First Steps¶

Simple Calculation¶

Let’s calculate X-ray properties for silicon at 8 keV:

Using the CLI:

xraylabtool calc Si --density 2.33 --energy 8000

Using Python:

import xraylabtool as xrt

result = xrt.calculate_single_material_properties(
    formula="Si",
    density=2.33,  # g/cm³
    energy=8000    # eV
)

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

Expected output:

Formula: Si
Critical angle: 0.158°
Attenuation length: 9.84 cm

Understanding the Results¶

The main properties calculated are:

Critical angle: Angle for total external reflection
Attenuation length: Distance for 1/e intensity reduction
Delta (δ): Real part of refractive index decrement
Beta (β): Imaginary part related to absorption

Multiple Energies¶

Calculate properties across an energy range:

CLI:

xraylabtool calc Si --density 2.33 --energy 5000,8000,10000

Python:

import numpy as np

energies = [5000, 8000, 10000]  # eV
results = []

for energy in energies:
    result = xrt.calculate_single_material_properties("Si", 2.33, energy)
    results.append(result)

for result in results:
    print(f"{result.energy_ev} eV: θc = {result.critical_angle_degrees:.3f}°")

Different Materials¶

Try other materials:

# Silicon dioxide (quartz)
sio2 = xrt.calculate_single_material_properties("SiO2", 2.20, 8000)

# Aluminum
al = xrt.calculate_single_material_properties("Al", 2.70, 8000)

# Copper
cu = xrt.calculate_single_material_properties("Cu", 8.96, 8000)

materials = [("Si", sio2), ("SiO2", sio2), ("Al", al), ("Cu", cu)]
for name, result in materials:
    print(f"{name}: Critical angle = {result.critical_angle_degrees:.3f}°")

Batch Processing¶

For multiple materials, use batch processing:

Create a CSV file materials.csv:

Formula,Density,Energy
Si,2.33,8000
SiO2,2.20,8000
Al,2.70,8000
Cu,8.96,8000

Process the batch:

xraylabtool batch materials.csv --output results.csv

Or in Python:

# Define materials
materials = [
    {"formula": "Si", "density": 2.33},
    {"formula": "SiO2", "density": 2.20},
    {"formula": "Al", "density": 2.70},
    {"formula": "Cu", "density": 8.96}
]

# Calculate for all materials at 8 keV
results = xrt.calculate_xray_properties(materials, energy=8000)

# Display results
   print(f"{result.formula}: "
          f"θc = {result.critical_angle_degrees:.3f}°, "
          f"μ⁻¹ = {result.attenuation_length_cm:.2f} cm")

Graphical User Interface (GUI)¶

XRayLabTool includes a modern desktop application for interactive analysis.

Launch via:

python -m xraylabtool.gui

Key Features:

Interactive Analysis: Single and multiple material comparisons.
Modern Interface: Clean design with Light and Dark data-optimized themes.
Theme Toggle: Switch between Light and Dark modes via the status bar toggle.
Persisted Settings: Your theme preference is saved automatically.

Common Use Cases¶

Mirror Design¶

For X-ray mirror applications:

# Compare substrate materials
substrates = ["Si", "SiO2", "Zerodur"]  # Zerodur is a glass-ceramic
densities = [2.33, 2.20, 2.53]
energy = 8000  # eV

print("Mirror substrate comparison at 8 keV:")
print("Material | Critical Angle | Attenuation Length")
print("---------|----------------|-------------------")

for formula, density in zip(substrates, densities):
    result = xrt.calculate_single_material_properties(formula, density, energy)
    print(f"{formula:8} | {result.critical_angle_degrees:13.3f}° | "
          f"{result.attenuation_length_cm:15.2f} cm")

Beamline Planning¶

For synchrotron beamline design:

# Energy scan for beamline components
energies = np.logspace(3, 4.5, 50)  # 1 keV to ~32 keV
material = "Si"
density = 2.33

critical_angles = []
attenuation_lengths = []

for energy in energies:
    result = xrt.calculate_single_material_properties(material, density, energy)
    critical_angles.append(result.critical_angle_mrad)
    attenuation_lengths.append(result.attenuation_length_cm)

# Plot or analyze the energy dependence
import matplotlib.pyplot as plt

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))

ax1.loglog(energies, critical_angles)
ax1.set_xlabel('Energy (eV)')
ax1.set_ylabel('Critical Angle (mrad)')
ax1.set_title('Critical Angle vs Energy')

ax2.loglog(energies, attenuation_lengths)
ax2.set_xlabel('Energy (eV)')
ax2.set_ylabel('Attenuation Length (cm)')
ax2.set_title('Attenuation Length vs Energy')

plt.tight_layout()
plt.show()

Understanding the Architecture¶

XRayLabTool uses a modular architecture:

backend/: NumPy/JAX array backend abstraction. Switch at runtime with set_backend("jax") for JIT-compiled GPU acceleration.
calculators/: Core X-ray physics calculations and algorithms. Contains the main calculation functions and XRayResult data structure.
data_handling/: Atomic data caching and batch processing. Provides high-performance data management with preloaded elements.
interfaces/: User interfaces including the complete CLI and shell completion systems.
io/: File operations and data export functionality. Handles CSV, JSON, and other format conversions.
validation/: Input validation and error handling. Ensures data quality and provides detailed error messages.
gui/: PySide6 desktop application with PyQtGraph interactive plots.

This modular design allows you to import only what you need:

# Import main calculation functions
from xraylabtool.calculators import calculate_single_material_properties

# Import specific utilities
from xraylabtool.utils import parse_formula, energy_to_wavelength

# Switch to JAX backend for GPU acceleration
from xraylabtool.backend import set_backend
set_backend("jax")

Next Steps¶

Next steps:

Explore the CLI: Try all 9 commands with xraylabtool --help
Read the Tutorials: Learn techniques and workflows
Study Examples: See applications
Check the API Reference: View available functions
Learn the Physics: Understand the X-ray optics background

Key Documentation Sections:

CLI Reference - Complete command-line interface documentation
Examples - Real-world usage examples
API Reference - Complete API reference
X-ray Physics - X-ray physics background

Getting Help¶

If you encounter issues:

Check the FAQ: Common questions and solutions
Read Error Messages: XRayLabTool provides detailed error descriptions
Use Help Commands: xraylabtool --help and xraylabtool <command> --help
Check Documentation: This documentation covers most use cases
Report Issues: Use the GitHub issue tracker for bugs

Command-line help:

xraylabtool --help                    # General help
xraylabtool calc --help               # Help for calc command
xraylabtool list examples             # Show example materials

Python help:

import xraylabtool as xrt
help(xrt.calculate_single_material_properties)

# Or in IPython/Jupyter for interactive help
In [1]: xrt.calculate_single_material_properties?

Performance Tips¶

For better performance:

Use preloaded elements: Si, O, Al, Fe, C, etc. are cached for speed
Batch processing: Process multiple materials together when possible
Energy arrays: Use NumPy arrays for energy ranges
Avoid repeated parsing: Cache formula parsing results

# Good - batch processing
results = xrt.calculate_xray_properties(materials, energies)

# Less efficient - individual calculations
for material in materials:
    for energy in energies:
        result = xrt.calculate_single_material_properties(
            material['formula'], material['density'], energy
        )