Validation Module¶

The validation module provides input validation, error handling, and custom exception classes.

Exception Hierarchy¶

Custom exceptions for XRayLabTool.

This module defines domain-specific exception classes that provide better error handling and more informative error messages for X-ray analysis operations.

exception xraylabtool.exceptions.AtomicDataError(message, element=None)[source]

Bases: XRayLabToolError

Exception raised when atomic data cannot be retrieved or processed.

Parameters:

message (str)
element (str | None)

__init__(message, element=None)[source]

Initialize AtomicDataError with message and optional element context.

Parameters:

message (str)
element (str | None)

exception xraylabtool.exceptions.BatchProcessingError(message, failed_items=None, total_items=None)[source]

Bases: XRayLabToolError

Exception raised during batch processing operations.

Parameters:

message (str)
failed_items (list[Any] | None)
total_items (int | None)

__init__(message, failed_items=None, total_items=None)[source]

Initialize BatchProcessingError with message and optional failure context.

Parameters:

message (str)
failed_items (list[Any] | None)
total_items (int | None)

exception xraylabtool.exceptions.CalculationError(message, formula=None, energy=None)[source]

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)[source]

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

exception xraylabtool.exceptions.ConfigurationError(message, config_key=None)[source]

Bases: XRayLabToolError

Exception raised for configuration-related errors.

Parameters:

message (str)
config_key (str | None)

__init__(message, config_key=None)[source]

Initialize ConfigurationError with message and optional config key context.

Parameters:

message (str) – The error message
config_key (str | None) – Optional configuration key that caused the error

exception xraylabtool.exceptions.DataFileError(message, filename=None)[source]

Bases: XRayLabToolError

Exception raised when data files cannot be loaded or processed.

Parameters:

message (str)
filename (str | None)

__init__(message, filename=None)[source]

Initialize DataFileError with message and optional filename context.

Parameters:

message (str)
filename (str | None)

exception xraylabtool.exceptions.EnergyError(message, energy=None, valid_range=None)[source]

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)[source]

Initialize EnergyError with message and optional energy context.

Parameters:

message (str)
energy (float | None)
valid_range (str | None)

exception xraylabtool.exceptions.FormulaError(message, formula=None)[source]

Bases: XRayLabToolError

Exception raised for invalid chemical formulas.

Parameters:

message (str)
formula (str | None)

__init__(message, formula=None)[source]

Initialize FormulaError with message and optional formula context.

Parameters:

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

exception xraylabtool.exceptions.UnknownElementError(element)[source]

Bases: AtomicDataError

Exception raised when an unknown element symbol is provided.

Parameters:: element (str)

__init__(element)[source]

Initialize UnknownElementError with element symbol.

Parameters:: element (str)

exception xraylabtool.exceptions.ValidationError(message, parameter=None, value=None)[source]

Bases: XRayLabToolError

Exception raised when input validation fails.

Parameters:

message (str)
parameter (str | None)
value (Any | None)

__init__(message, parameter=None, value=None)[source]

Initialize ValidationError with message and optional parameter context.

Parameters:

message (str)
parameter (str | None)
value (Any | None)

exception xraylabtool.exceptions.XRayLabToolError[source]

Bases: Exception

Base exception for all XRayLabTool-related errors.

Base Exception¶

class xraylabtool.exceptions.XRayLabToolError[source]

Bases: Exception

Base exception for all XRayLabTool-related errors.

The base exception class for all XRayLabTool-specific errors. All custom exceptions inherit from this class, making it easy to catch any XRayLabTool-related error.

Example:

try:
    result = calculate_single_material_properties("InvalidFormula", 1.0, 8000)
except XRayLabToolError as e:
    print(f"XRayLabTool error: {e}")

Specific Exceptions¶

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

Bases: XRayLabToolError

Exception raised when input validation fails.

Raised when input validation fails.

Parameters:

message (str)
parameter (str | None)
value (Any | None)

__init__(message, parameter=None, value=None)[source]

Initialize ValidationError with message and optional parameter context.

Parameters:

message (str)
parameter (str | None)
value (Any | None)

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

Bases: XRayLabToolError

Exception raised for invalid chemical formulas.

Raised when chemical formula parsing or validation fails.

Common causes: - Unknown chemical elements - Invalid formula syntax - Unsupported element combinations

Example:

try:
    from xraylabtool.utils import parse_formula
    composition = parse_formula("XYZ123")  # Invalid element
except FormulaError as e:
    print(f"Formula error: {e}")

Parameters:

message (str)
formula (str | None)

__init__(message, formula=None)[source]

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)[source]

Bases: XRayLabToolError

Exception raised for invalid energy values or ranges.

Raised when energy values are invalid or out of supported range.

Common causes: - Negative or zero energy values - Energy outside supported range (typically 10 eV - 100 keV) - Invalid energy array or range specification

Example:

try:
    result = calculate_single_material_properties("Si", 2.33, -1000)  # Negative energy
except EnergyError as e:
    print(f"Energy error: {e}")

Parameters:

message (str)
energy (float | None)
valid_range (str | None)

__init__(message, energy=None, valid_range=None)[source]

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)[source]

Bases: XRayLabToolError

Exception raised when X-ray property calculations fail.

Raised when X-ray property calculations fail due to numerical issues or invalid parameters.

Common causes: - Numerical instability in calculations - Invalid density values - Missing atomic data - Convergence failures

Parameters:

message (str)
formula (str | None)
energy (float | None)

__init__(message, formula=None, energy=None)[source]

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

Input Validators¶

Validation functions for XRayLabTool.

This module contains functions for validating input parameters, chemical formulas, energy ranges, and other data used in calculations.

xraylabtool.validation.validators.validate_energy_range(energies, min_energy=0.1, max_energy=100.0)[source]

Validate X-ray energy values.

Parameters:

energies (float | ndarray) – Energy value(s) in keV
min_energy (float) – Minimum allowed energy in keV
max_energy (float) – Maximum allowed energy in keV

Return type:

ndarray

Returns:

Validated energy array

Raises:

EnergyError – If energies are invalid

xraylabtool.validation.validators.validate_chemical_formula(formula)[source]

Validate and parse a chemical formula.

Parameters:: formula (str) – Chemical formula string (e.g., “SiO2”, “Ca0.5Sr0.5TiO3”)
Return type:: dict[str, float]
Returns:: Dictionary mapping element symbols to their quantities
Raises:: FormulaError – If formula is invalid

xraylabtool.validation.validators.validate_density(density, min_density=0.001, max_density=30.0)[source]

Validate material density value.

Parameters:

density (float) – Density in g/cm³
min_density (float) – Minimum allowed density
max_density (float) – Maximum allowed density

Return type:

float

Returns:

Validated density value

Raises:

ValidationError – If density is invalid

xraylabtool.validation.validators.validate_calculation_parameters(formula, energies, density)[source]

Validate all parameters for X-ray calculations.

Parameters:

formula (str) – Chemical formula
energies (float | ndarray) – Energy values in keV
density (float) – Material density in g/cm³

Return type:

tuple[str, ndarray, float]

Returns:

Tuple of validated (formula, energies, density)

Raises:

ValidationError – If any parameters are invalid

Validation Functions¶

xraylabtool.validation.validators.validate_energy_range(energies, min_energy=0.1, max_energy=100.0)[source]

Validate X-ray energy values.

Parameters:

energies (float | ndarray) – Energy value(s) in keV
min_energy (float) – Minimum allowed energy in keV
max_energy (float) – Maximum allowed energy in keV

Return type:

ndarray

Returns:

Validated energy array

Raises:

EnergyError – If energies are invalid

Validate X-ray energy values.

Parameters: - energies (float or np.ndarray): Energy value(s) in keV - min_energy (float): Minimum allowed energy in keV (default: 0.1) - max_energy (float): Maximum allowed energy in keV (default: 100.0)

Returns: - np.ndarray: Validated energy array

Raises: - EnergyError: If energies are invalid

Example:

from xraylabtool.validation.validators import validate_energy_range
import numpy as np

# Valid energies
energies = validate_energy_range(8.0)  # Single energy
energies = validate_energy_range([5.0, 8.0, 10.0])  # Multiple energies
energies = validate_energy_range(np.array([1.0, 2.0, 3.0]))  # Array

# Invalid energies will raise EnergyError
# validate_energy_range(-1.0)  # Negative energy
# validate_energy_range(200.0)  # Above max energy

xraylabtool.validation.validators.validate_chemical_formula(formula)[source]

Validate and parse a chemical formula.

Parameters:: formula (str) – Chemical formula string (e.g., “SiO2”, “Ca0.5Sr0.5TiO3”)
Return type:: dict[str, float]
Returns:: Dictionary mapping element symbols to their quantities
Raises:: FormulaError – If formula is invalid

Validate and parse a chemical formula.

Parameters: - formula (str): Chemical formula string (e.g., “SiO2”, “Ca0.5Sr0.5TiO3”)

Returns: - dict: Dictionary mapping element symbols to their quantities

Raises: - FormulaError: If formula is invalid

Example:

from xraylabtool.validation.validators import validate_chemical_formula

# Valid formulas
elements = validate_chemical_formula("SiO2")
print(elements)  # {'Si': 1.0, 'O': 2.0}

elements = validate_chemical_formula("Al2O3")
print(elements)  # {'Al': 2.0, 'O': 3.0}

# Fractional compositions
elements = validate_chemical_formula("Ca0.5Sr0.5TiO3")
print(elements)  # {'Ca': 0.5, 'Sr': 0.5, 'Ti': 1.0, 'O': 3.0}

xraylabtool.validation.validators.validate_density(density, min_density=0.001, max_density=30.0)[source]

Validate material density value.

Parameters:

density (float) – Density in g/cm³
min_density (float) – Minimum allowed density
max_density (float) – Maximum allowed density

Return type:

float

Returns:

Validated density value

Raises:

ValidationError – If density is invalid

Validate material density value.

Parameters: - density (float): Density in g/cm³ - min_density (float): Minimum allowed density (default: 0.001) - max_density (float): Maximum allowed density (default: 30.0)

Returns: - float: Validated density value

Raises: - ValidationError: If density is invalid

Example:

from xraylabtool.validation.validators import validate_density

# Valid densities
density = validate_density(2.33)    # Silicon
density = validate_density(8.96)    # Copper
density = validate_density(0.001)   # Gas-phase materials

# Invalid densities will raise ValidationError
# validate_density(-1.0)     # Negative density
# validate_density(0.0)      # Zero density

xraylabtool.validation.validators.validate_calculation_parameters(formula, energies, density)[source]

Validate all parameters for X-ray calculations.

Parameters:

formula (str) – Chemical formula
energies (float | ndarray) – Energy values in keV
density (float) – Material density in g/cm³

Return type:

tuple[str, ndarray, float]

Returns:

Tuple of validated (formula, energies, density)

Raises:

ValidationError – If any parameters are invalid

Validate all parameters for X-ray calculations.

Parameters: - formula (str): Chemical formula - energies (float or np.ndarray): Energy values in keV - density (float): Material density in g/cm³

Returns: - tuple: Validated (formula, energies, density)

Raises: - ValidationError: If any parameters are invalid

Example:

from xraylabtool.validation.validators import validate_calculation_parameters

# Validate all parameters at once
formula, energies, density = validate_calculation_parameters(
    "SiO2", 8.0, 2.20
)
print(f"Formula: {formula}, Energy: {energies}, Density: {density}")

Error Context and Suggestions¶

XRayLabTool exceptions provide detailed context and suggestions for resolution:

try:
    result = calculate_single_material_properties("Si123", 2.33, 8000)
except FormulaError as e:
    print(f"Error: {e}")
    print(f"Suggestion: {e.suggestion}")
    # Output:
    # Error: Invalid formula 'Si123': numbers should follow elements
    # Suggestion: Use format like 'SiO2' or 'Al2O3'

Internal Validation Utilities¶

The validation module also includes internal helper functions that are used by the main validation functions but are not part of the public API:

_parse_formula(): Internal formula parsing logic
_get_valid_element_symbols(): Returns a set of valid element symbols for validation

Best Practices¶

1. Always Validate Input:

from xraylabtool.validation.validators import validate_chemical_formula, validate_energy_range

def safe_calculation(formula, density, energy):
    validate_chemical_formula(formula)
    validate_energy_range(energy)
    # Proceed with calculation...

2. Handle Specific Exceptions:

from xraylabtool.exceptions import FormulaError, EnergyError

try:
    result = calculate_single_material_properties(formula, density, energy)
except FormulaError:
    print("Please check your chemical formula")
except EnergyError:
    print("Please provide a valid energy value")
except Exception as e:
    print(f"Unexpected error: {e}")

3. Use Complete Parameter Validation:

from xraylabtool.validation.validators import validate_calculation_parameters

materials = [
    {"formula": "Si", "density": 2.33},
    {"formula": "InvalidElement", "density": 1.0}
]

# Validate all materials first
valid_materials = []
for material in materials:
    try:
        formula, energies, density = validate_calculation_parameters(
            material["formula"], 8.0, material["density"]
        )
        valid_materials.append({
            "formula": formula,
            "density": density,
            "energies": energies
        })
    except (FormulaError, ValidationError) as e:
        print(f"Skipping invalid material: {e}")

# Process only valid materials
results = calculate_xray_properties(valid_materials, energy=8000)