API Reference

This section contains the API reference for XRayLabTool’s modular architecture.

XRayLabTool is organized into focused sub-packages:

• calculators: Core X-ray physics calculations

• data_handling: Atomic data caching and batch processing

• interfaces: CLI and completion systems

• validation: Input validation and error handling

• io_operations: File operations and export functionality

• analysis: Material comparison and absorption edge detection

• export: CSV/JSON export for downstream analysis

• gui: PySide6 desktop application

• backend: NumPy/JAX array backend abstraction

• utils: Utility functions and constants

Core API

• Calculators Module
  • Core Calculations
  • Derived Quantities
  • XRay Result
  • Calculation Cache
  • Scattering Data
  • Kernels
  • Physics Background
  • Usage Examples
• Data Handling Module
  • Atomic Data Cache
  • Batch Processing
  • Performance Benchmarks
  • Cache Management
  • Data Sources
• Interfaces Module
  • Command Line Interface
  • Shell Completion (Legacy Bridge)
  • Shell Completion v2
  • Error Handling
  • Integration Examples
• Validation Module
  • Exception Hierarchy
  • Input Validators
  • Error Context and Suggestions
  • Internal Validation Utilities
  • Best Practices
• I/O Operations Module
  • File Operations
  • Data Export and Formatting
  • Available Functions
  • Supported File Formats
  • Usage Examples
  • Error Handling
  • Performance Considerations
• Utilities Module
  • Device Detection
  • Logging Utilities
  • Typing Extensions
  • Chemical Formula Parsing
  • Atomic Data Functions
  • Unit Conversions
  • Crystallographic and Diffraction Functions
  • Data Processing and Analysis
  • Utility Functions
• Constants Module
  • ANGSTROM_TO_METER
  • AVOGADRO
  • CM_TO_METER
  • DEGREES_TO_RADIANS
  • ELEMENT_CHARGE
  • ENERGY_TO_WAVELENGTH_FACTOR
  • EV_TO_KEV
  • KEV_TO_EV
  • METER_TO_ANGSTROM
  • METER_TO_CM
  • PI
  • PLANCK
  • RADIANS_TO_DEGREES
  • SCATTERING_FACTOR
  • SPEED_OF_LIGHT
  • SQRT_2
  • THOMPSON
  • TWO_PI
  • attenuation_length_cm()
  • critical_angle_degrees()
  • energy_to_wavelength_angstrom()
  • validate_constants()
  • wavelength_angstrom_to_energy()
  • Usage Examples
  • Constants Reference Table
  • CODATA Standards

Extended API

• Analysis
  • MaterialComparator
  • compare_materials()
  • find_absorption_edges()
  • Material Comparator
• Export
  • export_to_csv()
  • export_to_json()
• GUI
  • Main Window
  • Services
  • Theme Manager
  • Workers
  • Protocols
  • Logging Filters
  • Widgets
• Backend
  • InterpolationFactory
  • get_backend()
  • set_backend()
  • Array Operations
  • Interpolation

High-Level Interface

The primary entry points for most users:

Main Calculation Functions

xraylabtool.calculate_single_material_properties(formula, energy_keV=None, density=None, *, energy=None)

Calculate X-ray optical properties for a single material composition.

This is a pure function that calculates comprehensive X-ray optical properties for a single chemical formula at given energies and density. It returns an XRayResult dataclass containing all computed properties.

Parameters:

• formula (str) – Chemical formula string (e.g., “SiO2”, “Al2O3”, “CaCO3”)

• energy_keV (float | floating | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | list | None) – X-ray energies in keV. Valid range: 0.03-30.0 keV

• density (float | floating | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None) – Material mass density in g/cm³ (must be positive)

• energy (float | floating | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | list | None) – Optional backward-compatible alias (eV). If provided, interpreted as electron-volts and converted to keV.

Returns:

Dataclass containing all calculated X-ray properties.

Return type:

XRayResult

Raises:

• FormulaError – If chemical formula cannot be parsed or contains invalid elements

• EnergyError – If energy values are outside valid range (0.03-30.0 keV)

• ValidationError – If density is not positive or other validation failures

Examples

>>> import xraylabtool as xlt
>>> result = xlt.calculate_single_material_properties("SiO2", 8.0, 2.2)
>>> print(f"Formula: {result.formula}")
Formula: SiO2

See also

calculate_xray_properties : Calculate properties for multiple materials XRayResult : Complete documentation of returned dataclass

xraylabtool.calculate_xray_properties(formulas, energies, densities)

Calculate X-ray optical properties for multiple material compositions.

Parameters:

• formulas (list[str]) – List of chemical formula strings

• energies (float | floating | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | list) – X-ray energies in keV applied to all materials

• densities (list[float]) – List of material mass densities in g/cm³

Returns:

Dictionary mapping formula strings to XRayResult objects.

Return type:

dict[str, XRayResult]

Raises:

• ValidationError – If inputs don’t match

• RuntimeError – If no formulas were processed successfully

See also

calculate_single_material_properties : Single material calculations XRayResult : Documentation of returned data structure

Quick Reference

Single Material Calculation:

import xraylabtool as xrt

result = xrt.calculate_single_material_properties(
    formula="Si",
    density=2.33,
    energy=8000
)

Batch Calculation:

materials = [
    {"formula": "Si", "density": 2.33},
    {"formula": "Al", "density": 2.70}
]
energies = [5000, 8000, 10000]

results = xrt.calculate_xray_properties(materials, energies)

Formula Parsing:

from xraylabtool.utils import parse_formula

composition = parse_formula("SiO2")
# Returns: {"Si": 1, "O": 2}

Unit Conversions:

from xraylabtool.utils import energy_to_wavelength, wavelength_to_energy

wavelength = energy_to_wavelength(8000)  # eV to Angstrom
energy = wavelength_to_energy(1.55)      # Angstrom to eV

Exception Hierarchy

class xraylabtool.exceptions.XRayLabToolError

Bases: Exception

Base exception for all XRayLabTool-related errors.

class xraylabtool.exceptions.ValidationError(message, parameter=None, value=None)

Bases: XRayLabToolError

Exception raised when input validation fails.

Parameters:

• message (str)

• parameter (str | None)

• value (Any | None)

__init__(message, parameter=None, value=None)

Initialize ValidationError with message and optional parameter context.

Parameters:

• message (str)

• parameter (str | None)

• value (Any | None)

class xraylabtool.exceptions.FormulaError(message, formula=None)

Bases: XRayLabToolError

Exception raised for invalid chemical formulas.

Parameters:

• message (str)

• formula (str | None)

__init__(message, formula=None)

Initialize FormulaError with message and optional formula context.

Parameters:

• message (str) – The error message

• formula (str | None) – Optional chemical formula that caused the error

class xraylabtool.exceptions.EnergyError(message, energy=None, valid_range=None)

Bases: XRayLabToolError

Exception raised for invalid energy values or ranges.

Parameters:

• message (str)

• energy (float | None)

• valid_range (str | None)

__init__(message, energy=None, valid_range=None)

Initialize EnergyError with message and optional energy context.

Parameters:

• message (str)

• energy (float | None)

• valid_range (str | None)

class xraylabtool.exceptions.CalculationError(message, formula=None, energy=None)

Bases: XRayLabToolError

Exception raised when X-ray property calculations fail.

Parameters:

• message (str)

• formula (str | None)

• energy (float | None)

__init__(message, formula=None, energy=None)

Initialize CalculationError with message and optional context.

Parameters:

• message (str) – The error message

• formula (str | None) – Optional chemical formula context

• energy (float | None) – Optional energy value context in keV