# XRayLabTool
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/xraylabtool)
[](https://opensource.org/licenses/MIT)
[](https://pyxraylabtool.readthedocs.io/en/latest/?badge=latest)
XRayLabTool is a Python package and command-line tool for calculating X-ray optical properties of materials based on their chemical formulas and densities.
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command-Line Interface (CLI)](#command-line-interface-cli)
- [Input Parameters](#input-parameters)
- [Output: XRayResult Dataclass](#output-xrayresult-dataclass)
- [Usage Examples](#usage-examples)
- [Migration Guide](#migration-guide)
- [Supported Calculations](#supported-calculations)
- [Performance Features](#performance-features)
- [Testing and Validation](#testing-and-validation)
- [API Reference](#api-reference)
- [Documentation & Support](#documentation--support)
- [Citation](#citation)
## Installation
### From PyPI (Recommended)
```bash
pip install xraylabtool
```
### From Source (Development)
```bash
git clone https://github.com/imewei/pyXRayLabTool.git
cd pyXRayLabTool
pip install -e .
```
### Shell Completion Setup
After installation, enable tab completion for enhanced CLI productivity:
```bash
# Install shell completion (auto-detects shell)
xraylabtool install-completion
# Alternative: using flag syntax
xraylabtool --install-completion
# Test if completion is working
xraylabtool install-completion --test
```
**Prerequisites by Shell:**
**Bash users:**
```bash
# macOS (Homebrew)
brew install bash-completion@2
# Add to ~/.bash_profile or ~/.bashrc:
[[ -r "/opt/homebrew/etc/profile.d/bash_completion.sh" ]] && . "/opt/homebrew/etc/profile.d/bash_completion.sh"
# Linux (Ubuntu/Debian)
sudo apt install bash-completion
# Linux (RHEL/CentOS)
sudo yum install bash-completion
```
**Zsh users:**
```bash
# macOS (Homebrew)
brew install zsh-completions
# Add to ~/.zshrc:
if type brew &>/dev/null; then
FPATH="$(brew --prefix)/share/zsh-completions:${FPATH}"
autoload -U compinit
compinit
fi
# Linux (Ubuntu/Debian)
sudo apt install zsh-autosuggestions zsh-syntax-highlighting
# Linux (RHEL/CentOS)
sudo yum install zsh-autosuggestions
```
**Fish and PowerShell users:**
- Fish: No additional prerequisites (built-in completion system)
- PowerShell: No additional prerequisites (built-in completion system)
**Uninstalling completion:**
```bash
# Remove shell completion
xraylabtool uninstall-completion
```
Restart your shell or source your config file after installation.
> **Note**: Shell completion is supported for **bash, zsh, fish, and PowerShell**. Use `xraylabtool install-completion <shell>` to install completion for your preferred shell, or `xraylabtool install-completion` for auto-detection.
### Requirements
- **Python** ≥ 3.12
- **NumPy** ≥ 1.20.0
- **SciPy** ≥ 1.7.0
- **Pandas** ≥ 1.3.0
- **Mendeleev** ≥ 0.10.0
- **tqdm** ≥ 4.60.0
- **matplotlib** ≥ 3.4.0 (optional, for plotting)
---
## Quick Start
```bash
# Install from PyPI
pip install xraylabtool
# Calculate X-ray properties for silicon at 10 keV
python -c "import xraylabtool as xlt; result = xlt.calculate_single_material_properties('Si', 10.0, 2.33); print(f'Critical angle: {result.critical_angle_degrees[0]:.3f}°')"
# Or use the command-line interface
xraylabtool calc Si -e 10.0 -d 2.33
```
## Usage Examples
### Single Material Analysis
```python
import xraylabtool as xlt
import numpy as np
# Calculate properties for quartz at 10 keV
result = xlt.calculate_single_material_properties("SiO2", 10.0, 2.2)
print(f"Formula: {result.formula}")
print(f"Molecular Weight: {result.molecular_weight_g_mol:.2f} g/mol")
print(f"Critical Angle: {result.critical_angle_degrees[0]:.3f}°")
print(f"Attenuation Length: {result.attenuation_length_cm[0]:.2f} cm")
```
### Multiple Materials Comparison
```python
# Compare common X-ray optics materials
materials = {
"SiO2": 2.2, # Fused silica
"Si": 2.33, # Silicon
"Al2O3": 3.95, # Sapphire
"C": 3.52, # Diamond
}
formulas = list(materials.keys())
densities = list(materials.values())
energy = 10.0 # keV (Cu Kα)
results = xlt.calculate_xray_properties(formulas, energy, densities)
# Display results (using new field names)
for formula, result in results.items():
print(f"{formula:6}: θc = {result.critical_angle_degrees[0]:.3f}°, "
f"δ = {result.dispersion_delta[0]:.2e}")
```
### Energy Range Analysis
```python
# Energy sweep for material characterization
energies = np.logspace(np.log10(1), np.log10(30), 100) # 1-30 keV
result = xlt.calculate_single_material_properties("Si", energies, 2.33)
print(f"Energy range: {result.energy_kev[0]:.1f} - {result.energy_kev[-1]:.1f} keV")
print(f"Data points: {len(result.energy_kev)}")
```
---
## Command-Line Interface (CLI)
### Installation & Verification
```bash
# Install with CLI support
pip install xraylabtool
# Verify CLI installation
xraylabtool --version
# Install shell completion (auto-detects shell)
xraylabtool install-completion
# Test completion is working
xraylabtool install-completion --test
```
### Quick CLI Examples
#### Single Material Calculation
```bash
# Calculate properties for quartz at 10 keV
xraylabtool calc SiO2 -e 10.0 -d 2.2
```
#### Energy Range Scan
```bash
# Energy sweep from 5-15 keV (11 points)
xraylabtool calc Si -e 5-15:11 -d 2.33 -o silicon_scan.csv
```
#### Batch Processing
```bash
# Create materials file
cat > materials.csv << EOF
formula,density,energy
SiO2,2.2,10.0
Si,2.33,"5.0,10.0,15.0"
Al2O3,3.95,10.0
EOF
# Process batch
xraylabtool batch materials.csv -o results.csv
```
#### Unit Conversions
```bash
# Convert energy to wavelength
xraylabtool convert energy 8.048,10.0,12.4 --to wavelength
```
#### Formula Analysis
```bash
# Parse chemical formulas
xraylabtool formula Ca10P6O26H2
xraylabtool atomic Si,Al,Fe
```
#### Bragg Diffraction Angles
```bash
# Calculate Bragg angles
xraylabtool bragg -d 3.14,2.45,1.92 -e 8.048
```
### Available CLI Commands
| Command | Purpose | Example |
|---------|---------|--------|
| `calc` | Single material calculations | `xraylabtool calc SiO2 -e 10.0 -d 2.2` |
| `batch` | Process multiple materials | `xraylabtool batch materials.csv -o results.csv` |
| `convert` | Energy/wavelength conversion | `xraylabtool convert energy 10.0 --to wavelength` |
| `formula` | Chemical formula analysis | `xraylabtool formula Al2O3` |
| `atomic` | Atomic data lookup | `xraylabtool atomic Si,Al,Fe` |
| `bragg` | Diffraction angle calculations | `xraylabtool bragg -d 3.14 -e 8.0` |
| `list` | Show constants/fields/examples | `xraylabtool list constants` |
| `install-completion` | Install shell completion | `xraylabtool install-completion` |
| `uninstall-completion` | Remove shell completion | `xraylabtool uninstall-completion` |
### Shell Completion Usage
Both command and flag syntaxes are supported:
```bash
# Subcommand syntax (recommended)
xraylabtool install-completion # Install shell completion (auto-detect)
xraylabtool install-completion --test # Test installation
xraylabtool uninstall-completion # Remove completion
# Flag syntax (alternative)
xraylabtool --install-completion # Install shell completion (auto-detect)
# Install for specific shells
xraylabtool install-completion bash # Bash completion
xraylabtool install-completion zsh # Zsh completion (requires zsh-completions)
xraylabtool install-completion fish # Fish completion
xraylabtool install-completion powershell # PowerShell completion
```
> **💡 Shell Requirements**: Make sure to install the shell-specific prerequisites above before installing completion. Zsh users especially need `zsh-completions` for proper functionality.
**Tab Completion Features:**
- **Command completion**: Auto-complete all 9 available commands
- **Option completion**: Complete command-line options and flags
- **File path completion**: Automatic file path completion for input/output files
- **Chemical formulas**: Suggestions for common chemical formulas
- **Energy values**: Common X-ray energy suggestions (8.048, 10.0, 12.4 keV)
### Output Formats
- **Table** (default): Human-readable console output
- **CSV**: Spreadsheet-compatible format
- **JSON**: Structured data for programming
### Advanced Features
- **Energy Input Formats**: Single values, ranges, logarithmic spacing
- **Parallel Processing**: Multi-core batch processing with `--workers`
- **Field Selection**: Choose specific output fields with `--fields`
- **Precision Control**: Set decimal places with `--precision`
- **File Output**: Save results to CSV or JSON files
- **Multi-Shell Tab Completion**: Intelligent completion for bash, zsh, fish, and PowerShell
- **Context-aware**: Suggests appropriate values based on current command
- **File completion**: Automatic file path completion for input/output files
- **Chemical formulas**: Common materials and element suggestions
- **Energy values**: Typical X-ray energy suggestions (Cu Kα, Mo Kα, etc.)
- **Cross-platform**: Works on macOS, Linux, and Windows (with WSL/Cygwin)
### 📖 CLI Help and Documentation
Get comprehensive help for any command:
```bash
# General help
xraylabtool --help
# Command-specific help
xraylabtool calc --help
xraylabtool batch --help
xraylabtool install-completion --help
# List available options and examples
xraylabtool list --help
```
**CLI Features:**
- 9 commands for X-ray analysis
- Energy input formats: Single values, ranges, lists, and logarithmic spacing
- Batch processing from CSV files
- Output formats: Table, CSV, and JSON
- Shell completion for bash, zsh, fish, and PowerShell
- Cross-platform support
---
## Input Parameters
| Parameter | Type | Description |
| ------------ | ------------------------------------- | -------------------------------------------------------------- |
| `formula(s)` | `str` or `List[str]` | Case-sensitive chemical formula(s), e.g., `"CO"` vs `"Co"` |
| `energy` | `float`, `List[float]`, or `np.array` | X-ray photon energies in keV (valid range: **0.03–30 keV**) |
| `density` | `float` or `List[float]` | Mass density in g/cm³ (one per formula) |
---
## Output: `XRayResult` Dataclass
The `XRayResult` dataclass contains all computed X-ray optical properties with clear, descriptive field names:
### Material Properties
- **`formula: str`** – Chemical formula
- **`molecular_weight_g_mol: float`** – Molecular weight (g/mol)
- **`total_electrons: float`** – Total electrons per molecule
- **`density_g_cm3: float`** – Mass density (g/cm³)
- **`electron_density_per_ang3: float`** – Electron density (electrons/ų)
### X-ray Properties (Arrays)
- **`energy_kev: np.ndarray`** – X-ray energies (keV)
- **`wavelength_angstrom: np.ndarray`** – X-ray wavelengths (Å)
- **`dispersion_delta: np.ndarray`** – Dispersion coefficient δ
- **`absorption_beta: np.ndarray`** – Absorption coefficient β
- **`scattering_factor_f1: np.ndarray`** – Real part of atomic scattering factor
- **`scattering_factor_f2: np.ndarray`** – Imaginary part of atomic scattering factor
### Derived Quantities (Arrays)
- **`critical_angle_degrees: np.ndarray`** – Critical angles (degrees)
- **`attenuation_length_cm: np.ndarray`** – Attenuation lengths (cm)
- **`real_sld_per_ang2: np.ndarray`** – Real scattering length density (Å⁻²)
- **`imaginary_sld_per_ang2: np.ndarray`** – Imaginary scattering length density (Å⁻²)
> **📝 Note**: Legacy field names (e.g., `Formula`, `MW`, `Critical_Angle`) are still supported for backward compatibility but will emit deprecation warnings. Use the new descriptive field names for clearer, more maintainable code.
---
## Usage Examples
### Recommended: Using New Field Names
```python
# Calculate properties for silicon dioxide at 10 keV
result = xlt.calculate_single_material_properties("SiO2", 10.0, 2.33)
# Use new descriptive field names (recommended)
print(f"Formula: {result.formula}") # "SiO2"
print(f"Molecular weight: {result.molecular_weight_g_mol:.2f} g/mol") # 60.08 g/mol
print(f"Dispersion: {result.dispersion_delta[0]:.2e}") # δ value
print(f"Critical angle: {result.critical_angle_degrees[0]:.3f}°") # θc
print(f"Attenuation: {result.attenuation_length_cm[0]:.1f} cm") # Attenuation length
```
### Legacy Field Names (Still Supported)
```python
# Legacy field names still work but emit deprecation warnings
print(f"Formula: {result.Formula}") # ⚠️ DeprecationWarning
print(f"Molecular weight: {result.MW:.2f} g/mol") # ⚠️ DeprecationWarning
print(f"Dispersion: {result.Dispersion[0]:.2e}") # ⚠️ DeprecationWarning
print(f"Critical angle: {result.Critical_Angle[0]:.3f}°") # ⚠️ DeprecationWarning
```
### Energy Range Analysis
```python
# Energy sweep for material characterization
energies = np.linspace(8.0, 12.0, 21) # 21 points from 8-12 keV
result = xlt.calculate_single_material_properties("SiO2", energies, 2.33)
# Using new field names
print(f"Energy range: {result.energy_kev[0]:.1f} - {result.energy_kev[-1]:.1f} keV")
print(f"Number of points: {len(result.energy_kev)}")
print(f"Dispersion range: {result.dispersion_delta.min():.2e} to {result.dispersion_delta.max():.2e}")
```
### Multiple Materials Comparison
```python
# Compare common X-ray optics materials
materials = {
"SiO2": 2.2, # Fused silica
"Si": 2.33, # Silicon
"Al2O3": 3.95, # Sapphire
"C": 3.52, # Diamond
}
formulas = list(materials.keys())
densities = list(materials.values())
energy = 10.0 # keV (Cu Kα)
results = xlt.calculate_xray_properties(formulas, energy, densities)
# Compare using new field names
for formula, result in results.items():
print(f"{formula:8}: θc = {result.critical_angle_degrees[0]:.3f}°, "
f"δ = {result.dispersion_delta[0]:.2e}, "
f"μ = {result.attenuation_length_cm[0]:.1f} cm")
```
### Enhanced Plotting Example
```python
import matplotlib.pyplot as plt
# Energy-dependent properties with new field names
energies = np.logspace(np.log10(1), np.log10(20), 100)
result = xlt.calculate_single_material_properties("Si", energies, 2.33)
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
# Plot using new descriptive field names
ax1.loglog(result.energy_kev, result.dispersion_delta, 'b-',
label='δ (dispersion)', linewidth=2)
ax1.loglog(result.energy_kev, result.absorption_beta, 'r-',
label='β (absorption)', linewidth=2)
ax1.set_xlabel('Energy (keV)')
ax1.set_ylabel('Optical constants')
ax1.set_title('Silicon: Dispersion & Absorption')
ax1.legend()
ax1.grid(True, alpha=0.3)
# Plot critical angle with new field name
ax2.semilogx(result.energy_kev, result.critical_angle_degrees, 'g-', linewidth=2)
ax2.set_xlabel('Energy (keV)')
ax2.set_ylabel('Critical angle (°)')
ax2.set_title('Silicon: Critical Angle')
ax2.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
```
---
## Migration Guide: Legacy to New Field Names
To help users transition from legacy CamelCase field names to the new descriptive snake_case names, here's a comprehensive mapping:
### Field Name Migration Table
| **Legacy Name** | **New Name** | **Description** |
| ---------------------------------- | ---------------------------------- | ------------------------------------------------- |
| `result.Formula` | `result.formula` | Chemical formula string |
| `result.MW` | `result.molecular_weight_g_mol` | Molecular weight (g/mol) |
| `result.Number_Of_Electrons` | `result.total_electrons` | Total electrons per molecule |
| `result.Density` | `result.density_g_cm3` | Mass density (g/cm³) |
| `result.Electron_Density` | `result.electron_density_per_ang3` | Electron density (electrons/ų) |
| `result.Energy` | `result.energy_kev` | X-ray energies (keV) |
| `result.Wavelength` | `result.wavelength_angstrom` | X-ray wavelengths (Å) |
| `result.Dispersion` | `result.dispersion_delta` | Dispersion coefficient δ |
| `result.Absorption` | `result.absorption_beta` | Absorption coefficient β |
| `result.f1` | `result.scattering_factor_f1` | Real part of atomic scattering factor |
| `result.f2` | `result.scattering_factor_f2` | Imaginary part of atomic scattering factor |
| `result.Critical_Angle` | `result.critical_angle_degrees` | Critical angles (degrees) |
| `result.Attenuation_Length` | `result.attenuation_length_cm` | Attenuation lengths (cm) |
| `result.reSLD` | `result.real_sld_per_ang2` | Real scattering length density (Å⁻²) |
| `result.imSLD` | `result.imaginary_sld_per_ang2` | Imaginary scattering length density (Å⁻²) |
### Quick Migration Examples
```python
# ❌ OLD (deprecated, but still works)
print(f"Critical angle: {result.Critical_Angle[0]:.3f}°") # Emits warning
print(f"Attenuation: {result.Attenuation_Length[0]:.1f} cm") # Emits warning
print(f"MW: {result.MW:.2f} g/mol") # Emits warning
# ✅ NEW (recommended)
print(f"Critical angle: {result.critical_angle_degrees[0]:.3f}°")
print(f"Attenuation: {result.attenuation_length_cm[0]:.1f} cm")
print(f"MW: {result.molecular_weight_g_mol:.2f} g/mol")
```
### Suppressing Deprecation Warnings (Temporary)
If you need to temporarily suppress deprecation warnings during migration:
```python
import warnings
# Suppress only XRayLabTool deprecation warnings
with warnings.catch_warnings():
warnings.filterwarnings("ignore", category=DeprecationWarning,
message=".*deprecated.*")
# Your legacy code here
print(f"Result: {result.Critical_Angle[0]}")
```
### Migration Strategy
1. **Identify Usage**: Search your codebase for the legacy field names
2. **Update Gradually**: Replace legacy names with new ones section by section
3. **Test**: Ensure your code works with new field names
4. **Clean Up**: Remove any deprecation warning suppressions
---
## Supported Calculations
### Optical Constants
- **Dispersion coefficient (δ)**: Real part of refractive index decrement
- **Absorption coefficient (β)**: Imaginary part of refractive index decrement
- **Complex refractive index**: n = 1 - δ - iβ
### Scattering Factors
- **f1, f2**: Atomic scattering factors from CXRO/NIST databases
- **Total scattering factors**: Sum over all atoms in the formula
### Derived Quantities
- **Critical angle**: Total external reflection angle
- **Attenuation length**: 1/e penetration depth
- **Scattering length density (SLD)**: Real and imaginary parts
---
## Scientific Background
XRayLabTool uses atomic scattering factor data from the [Center for X-ray Optics (CXRO)](https://henke.lbl.gov/optical_constants/) and NIST databases. The calculations are based on:
1. **Atomic Scattering Factors**: Henke, Gullikson, and Davis tabulations
2. **Optical Constants**: Classical dispersion relations
3. **Critical Angles**: Fresnel reflection theory
4. **Attenuation**: Beer-Lambert law
### Key Equations
- **Refractive Index**: n = 1 - δ - iβ
- **Dispersion**: δ = (r₀λ²/2π) × ρₑ × f₁
- **Absorption**: β = (r₀λ²/2π) × ρₑ × f₂
- **Critical Angle**: θc = √(2δ)
Where r₀ is the classical electron radius, λ is wavelength, and ρₑ is electron density.
---
## Performance Features
XRayLabTool has been extensively optimized for high-performance calculations. Here are the key performance improvements:
### Performance Cache System
#### Preloaded Atomic Data Cache
- 92 elements preloaded for instant access to atomic data
- Eliminates database queries to Mendeleev for common elements
- Fast access for Si, O, Al, Fe, and other common elements
- Fallback to Mendeleev for uncommon elements with runtime caching
```python
# Check cache statistics
from xraylabtool.atomic_data_cache import get_cache_stats
print(get_cache_stats())
# {'preloaded_elements': 92, 'runtime_cached_elements': 0, 'total_cached_elements': 92}
```
#### Advanced Caching Infrastructure
- Interpolator caching: Reuses PCHIP interpolators across calculations
- LRU caches: Memory management for frequently accessed data
- Bulk loading: Optimized atomic data loading for multiple elements
### Vectorized Mathematical Operations
#### Matrix Operations for Multi-Element Materials
- Vectorized computations: Matrix operations instead of loops for multi-element materials
- NumPy optimizations: Proper dtypes and memory-contiguous arrays
- Batch interpolation: Process multiple elements simultaneously
- Faster mathematical computations compared to previous versions
#### Smart Single vs Multi-Element Optimization
```python
# Single element materials use optimized direct computation
result_single = xlt.calculate_single_material_properties("Si", energies, 2.33)
# Multi-element materials use vectorized matrix operations
result_multi = xlt.calculate_single_material_properties("SiO2", energies, 2.2)
```
### Memory-Efficient Batch Processing
#### High-Performance Batch API
For large-scale calculations, use the optimized batch processor:
```python
from xraylabtool.batch_processor import calculate_batch_properties, BatchConfig
# Configure for optimal performance
config = BatchConfig(
chunk_size=100, # Process in chunks of 100
max_workers=8, # Use 8 parallel workers
memory_limit_gb=4.0, # Limit memory usage
enable_progress=True # Show progress bar
)
# Process large batches efficiently
formulas = ["SiO2", "Al2O3", "Fe2O3"] * 100 # 300 materials
energies = np.linspace(5, 15, 50) # 50 energy points
densities = [2.2, 3.95, 5.24] * 100
results = calculate_batch_properties(formulas, energies, densities, config)
```
#### Memory Management Features
- Chunked processing: Handles datasets larger than available RAM
- Automatic garbage collection: Prevents memory leaks during large calculations
- Memory monitoring: Real-time memory usage tracking
- Progress tracking: Visual feedback for long-running calculations
### Performance Benchmarks
#### Real-World Performance (Modern Hardware)
**Single Material Calculations:**
- Single energy point: ~0.03 ms
- 100 energy points: ~0.3 ms
- 1000 energy points: ~3 ms
**Batch Processing:**
- High throughput for multiple materials
- 50 materials × 50 energies = 2,500 calculations in ~17ms
- Average: 0.33 ms per material
**Memory Efficiency:**
- 150 materials × 100 energies = 15,000 calculations
- Memory usage: <1 MB additional RAM
- No memory leaks during extended calculations
#### Performance Comparison
| Operation | Before Optimization | After Optimization | Improvement |
|-----------|--------------------|--------------------|-------------|
| Atomic data access | ~200ms (DB query) | ~0.001ms (cache) | 200,000x |
| Single calculation | ~1.07s | ~0.003s | 350x |
| Mathematical ops | Baseline | Vectorized | 2-3x |
| Memory usage | High allocation | Chunked/optimized | 5-10x |
| Batch processing | Sequential | Parallel+chunked | 5-15x |
### Performance Best Practices
#### For Maximum Speed
```python
# 1. Use common elements (preloaded in cache)
common_materials = ["SiO2", "Al2O3", "Fe2O3", "Si", "C"] # ✅ Fast
uncommon_materials = ["Uuo", "Fl", "Mc"] # ⚠️ Slower (Mendeleev fallback)
# 2. Reuse energy arrays when possible
energies = np.linspace(5, 15, 100)
for formula in formulas:
result = xlt.calculate_single_material_properties(formula, energies, density)
# 3. Use batch processing for many materials
results = xlt.calculate_xray_properties(formulas, energies, densities) # ✅ Parallel
# Instead of:
# results = {f: xlt.calculate_single_material_properties(f, energies, d)
# for f, d in zip(formulas, densities)} # ❌ Sequential
```
#### For Large Datasets
```python
# Use the optimized batch processor for very large datasets
from xraylabtool.batch_processor import calculate_batch_properties, BatchConfig
# Configure for your system
config = BatchConfig(
chunk_size=min(100, len(formulas) // 4), # Adapt to dataset size
max_workers=os.cpu_count() // 2, # Use half of CPU cores
memory_limit_gb=8.0, # Set appropriate memory limit
enable_progress=True # Monitor progress
)
results = calculate_batch_properties(formulas, energies, densities, config)
```
### Performance Monitoring
```python
# Monitor cache performance
from xraylabtool.atomic_data_cache import get_cache_stats, is_element_preloaded
print(f"Cache stats: {get_cache_stats()}")
print(f"Silicon preloaded: {is_element_preloaded('Si')}") # True
print(f"Unobtainium preloaded: {is_element_preloaded('Uo')}") # False
# Monitor memory usage during batch processing
from xraylabtool.batch_processor import MemoryMonitor
monitor = MemoryMonitor(limit_gb=4.0)
print(f"Current memory usage: {monitor.get_memory_usage_mb():.1f} MB")
print(f"Within limits: {monitor.check_memory()}")
```
---
## Testing and Validation
XRayLabTool includes a comprehensive test suite with:
- **Unit Tests**: Individual function validation
- **Integration Tests**: End-to-end workflows
- **Physics Tests**: Consistency with known relationships
- **Performance Tests**: Regression monitoring
- **Robustness Tests**: Edge cases and error handling
Run tests with:
```bash
pytest tests/ -v
```
---
## API Reference
### Main Functions
#### `calculate_single_material_properties(formula, energy, density)`
Calculate X-ray properties for a single material.
**Parameters:**
- `formula` (str): Chemical formula
- `energy` (float/array): X-ray energies in keV
- `density` (float): Mass density in g/cm³
**Returns:** `XRayResult` object
#### `calculate_xray_properties(formulas, energies, densities)`
Calculate X-ray properties for multiple materials.
**Parameters:**
- `formulas` (List[str]): List of chemical formulas
- `energies` (float/array): X-ray energies in keV
- `densities` (List[float]): Mass densities in g/cm³
**Returns:** `Dict[str, XRayResult]`
### Utility Functions
- `energy_to_wavelength(energy)`: Convert energy (keV) to wavelength (Å)
- `wavelength_to_energy(wavelength)`: Convert wavelength (Å) to energy (keV)
- `parse_formula(formula)`: Parse chemical formula into elements and counts
- `get_atomic_number(symbol)`: Get atomic number for element symbol
- `get_atomic_weight(symbol)`: Get atomic weight for element symbol
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## Acknowledgments
- **CXRO**: Atomic scattering factor databases
- **NIST**: Reference data and validation
- **NumPy/SciPy**: Scientific computing foundation
---
## Documentation & Support
### 📖 Documentation
- **Main README**: Overview and Python API examples
- **CLI Reference**: [CLI_REFERENCE.md](CLI_REFERENCE.md) - Comprehensive command-line interface guide
- **Virtual Environment Setup**: [VIRTUAL_ENV.md](VIRTUAL_ENV.md) - Development environment setup
- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - Version history and updates
- **Online Docs**: [https://pyxraylabtool.readthedocs.io](https://pyxraylabtool.readthedocs.io)
### 🔍 Getting Help
- **Issues**: [GitHub Issues](https://github.com/imewei/pyXRayLabTool/issues) - Bug reports and feature requests
- **Discussions**: [GitHub Discussions](https://github.com/imewei/pyXRayLabTool/discussions) - Questions and community support
- **CLI Help**: `xraylabtool --help` or `xraylabtool <command> --help` for command-specific help
---
## Citation
If you use XRayLabTool in your research, please cite:
```bibtex
@software{xraylabtool,
title = {XRayLabTool: High-Performance X-ray Optical Properties Calculator},
author = {Wei Chen},
url = {https://github.com/imewei/pyXRayLabTool},
year = {2024},
version = {0.1.10}
}
```
---
<!-- SEO Meta Tags -->
<!--
Primary Keywords: X-ray optical properties, atomic scattering factors, synchrotron calculations, Python X-ray tools
Secondary Keywords: CXRO NIST database, X-ray reflectometry, materials characterization, critical angle calculator
Long-tail Keywords: high-performance X-ray property calculator, Python synchrotron beamline tools, X-ray diffraction analysis software
-->
<!-- GitHub Topics for Discovery -->
<!-- Topics: xray, synchrotron, crystallography, materials-science, optics, physics, scientific-computing, python-package, cli-tool -->
Raw data
{
"_id": null,
"home_page": null,
"name": "xraylabtool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Wei Chen <wchen@anl.gov>",
"keywords": "xray, x-ray, xrd, xrr, saxs, crystallography, diffraction, scattering, synchrotron, beamline, optics, reflectometry, absorption, spectroscopy, materials-science, condensed-matter, physics, chemistry, nanotechnology, thin-films, multilayers, nanostructures, characterization, cxro, nist, atomic-scattering-factors, optical-constants, refractive-index, critical-angle, attenuation-length, form-factors, dispersion, absorption-coefficient, high-performance, vectorized, batch-processing, parallel-processing, scientific-computing, numerical-analysis, laboratory, analysis, cli, command-line, python-package, api, cross-platform, shell-completion, bash-completion, zsh-completion, fish-completion, powershell-completion, tab-completion, windows-powershell, pwsh, materials-characterization, structure-analysis, quality-control, medical-imaging, industrial-radiography, non-destructive-testing",
"author": null,
"author_email": "Wei Chen <wchen@anl.gov>",
"download_url": "https://files.pythonhosted.org/packages/2c/72/8cac43ccb74fd91d637ec9edaf3231f436317188018617cc2ff3755a8b26/xraylabtool-0.2.2.tar.gz",
"platform": null,
"description": "# XRayLabTool\n\n[](https://www.python.org/downloads/)\n[](https://badge.fury.io/py/xraylabtool)\n[](https://opensource.org/licenses/MIT)\n[](https://pyxraylabtool.readthedocs.io/en/latest/?badge=latest)\n\nXRayLabTool is a Python package and command-line tool for calculating X-ray optical properties of materials based on their chemical formulas and densities.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Command-Line Interface (CLI)](#command-line-interface-cli)\n- [Input Parameters](#input-parameters)\n- [Output: XRayResult Dataclass](#output-xrayresult-dataclass)\n- [Usage Examples](#usage-examples)\n- [Migration Guide](#migration-guide)\n- [Supported Calculations](#supported-calculations)\n- [Performance Features](#performance-features)\n- [Testing and Validation](#testing-and-validation)\n- [API Reference](#api-reference)\n- [Documentation & Support](#documentation--support)\n- [Citation](#citation)\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install xraylabtool\n```\n\n### From Source (Development)\n\n```bash\ngit clone https://github.com/imewei/pyXRayLabTool.git\ncd pyXRayLabTool\npip install -e .\n```\n\n### Shell Completion Setup\n\nAfter installation, enable tab completion for enhanced CLI productivity:\n\n```bash\n# Install shell completion (auto-detects shell)\nxraylabtool install-completion\n\n# Alternative: using flag syntax\nxraylabtool --install-completion\n\n# Test if completion is working\nxraylabtool install-completion --test\n```\n\n**Prerequisites by Shell:**\n\n**Bash users:**\n```bash\n# macOS (Homebrew)\nbrew install bash-completion@2\n\n# Add to ~/.bash_profile or ~/.bashrc:\n[[ -r \"/opt/homebrew/etc/profile.d/bash_completion.sh\" ]] && . \"/opt/homebrew/etc/profile.d/bash_completion.sh\"\n\n# Linux (Ubuntu/Debian)\nsudo apt install bash-completion\n\n# Linux (RHEL/CentOS)\nsudo yum install bash-completion\n```\n\n**Zsh users:**\n```bash\n# macOS (Homebrew)\nbrew install zsh-completions\n\n# Add to ~/.zshrc:\nif type brew &>/dev/null; then\n FPATH=\"$(brew --prefix)/share/zsh-completions:${FPATH}\"\n autoload -U compinit\n compinit\nfi\n\n# Linux (Ubuntu/Debian)\nsudo apt install zsh-autosuggestions zsh-syntax-highlighting\n\n# Linux (RHEL/CentOS)\nsudo yum install zsh-autosuggestions\n```\n\n**Fish and PowerShell users:**\n- Fish: No additional prerequisites (built-in completion system)\n- PowerShell: No additional prerequisites (built-in completion system)\n\n**Uninstalling completion:**\n```bash\n# Remove shell completion\nxraylabtool uninstall-completion\n```\n\nRestart your shell or source your config file after installation.\n\n> **Note**: Shell completion is supported for **bash, zsh, fish, and PowerShell**. Use `xraylabtool install-completion <shell>` to install completion for your preferred shell, or `xraylabtool install-completion` for auto-detection.\n\n### Requirements\n\n- **Python** \u2265 3.12\n- **NumPy** \u2265 1.20.0\n- **SciPy** \u2265 1.7.0\n- **Pandas** \u2265 1.3.0\n- **Mendeleev** \u2265 0.10.0\n- **tqdm** \u2265 4.60.0\n- **matplotlib** \u2265 3.4.0 (optional, for plotting)\n\n---\n\n## Quick Start\n\n```bash\n# Install from PyPI\npip install xraylabtool\n\n# Calculate X-ray properties for silicon at 10 keV\npython -c \"import xraylabtool as xlt; result = xlt.calculate_single_material_properties('Si', 10.0, 2.33); print(f'Critical angle: {result.critical_angle_degrees[0]:.3f}\u00b0')\"\n\n# Or use the command-line interface\nxraylabtool calc Si -e 10.0 -d 2.33\n```\n\n## Usage Examples\n\n### Single Material Analysis\n\n```python\nimport xraylabtool as xlt\nimport numpy as np\n\n# Calculate properties for quartz at 10 keV\nresult = xlt.calculate_single_material_properties(\"SiO2\", 10.0, 2.2)\nprint(f\"Formula: {result.formula}\")\nprint(f\"Molecular Weight: {result.molecular_weight_g_mol:.2f} g/mol\")\nprint(f\"Critical Angle: {result.critical_angle_degrees[0]:.3f}\u00b0\")\nprint(f\"Attenuation Length: {result.attenuation_length_cm[0]:.2f} cm\")\n```\n\n### Multiple Materials Comparison\n\n```python\n# Compare common X-ray optics materials\nmaterials = {\n \"SiO2\": 2.2, # Fused silica\n \"Si\": 2.33, # Silicon\n \"Al2O3\": 3.95, # Sapphire\n \"C\": 3.52, # Diamond\n}\n\nformulas = list(materials.keys())\ndensities = list(materials.values())\nenergy = 10.0 # keV (Cu K\u03b1)\n\nresults = xlt.calculate_xray_properties(formulas, energy, densities)\n\n# Display results (using new field names)\nfor formula, result in results.items():\n print(f\"{formula:6}: \u03b8c = {result.critical_angle_degrees[0]:.3f}\u00b0, \"\n f\"\u03b4 = {result.dispersion_delta[0]:.2e}\")\n```\n\n### Energy Range Analysis\n\n```python\n# Energy sweep for material characterization\nenergies = np.logspace(np.log10(1), np.log10(30), 100) # 1-30 keV\nresult = xlt.calculate_single_material_properties(\"Si\", energies, 2.33)\n\nprint(f\"Energy range: {result.energy_kev[0]:.1f} - {result.energy_kev[-1]:.1f} keV\")\nprint(f\"Data points: {len(result.energy_kev)}\")\n```\n\n---\n\n## Command-Line Interface (CLI)\n\n### Installation & Verification\n\n```bash\n# Install with CLI support\npip install xraylabtool\n\n# Verify CLI installation\nxraylabtool --version\n\n# Install shell completion (auto-detects shell)\nxraylabtool install-completion\n\n# Test completion is working\nxraylabtool install-completion --test\n```\n\n### Quick CLI Examples\n\n#### Single Material Calculation\n```bash\n# Calculate properties for quartz at 10 keV\nxraylabtool calc SiO2 -e 10.0 -d 2.2\n```\n\n#### Energy Range Scan\n```bash\n# Energy sweep from 5-15 keV (11 points)\nxraylabtool calc Si -e 5-15:11 -d 2.33 -o silicon_scan.csv\n```\n\n#### Batch Processing\n```bash\n# Create materials file\ncat > materials.csv << EOF\nformula,density,energy\nSiO2,2.2,10.0\nSi,2.33,\"5.0,10.0,15.0\"\nAl2O3,3.95,10.0\nEOF\n\n# Process batch\nxraylabtool batch materials.csv -o results.csv\n```\n\n#### Unit Conversions\n```bash\n# Convert energy to wavelength\nxraylabtool convert energy 8.048,10.0,12.4 --to wavelength\n```\n\n#### Formula Analysis\n```bash\n# Parse chemical formulas\nxraylabtool formula Ca10P6O26H2\nxraylabtool atomic Si,Al,Fe\n```\n\n#### Bragg Diffraction Angles\n```bash\n# Calculate Bragg angles\nxraylabtool bragg -d 3.14,2.45,1.92 -e 8.048\n```\n\n### Available CLI Commands\n\n| Command | Purpose | Example |\n|---------|---------|--------|\n| `calc` | Single material calculations | `xraylabtool calc SiO2 -e 10.0 -d 2.2` |\n| `batch` | Process multiple materials | `xraylabtool batch materials.csv -o results.csv` |\n| `convert` | Energy/wavelength conversion | `xraylabtool convert energy 10.0 --to wavelength` |\n| `formula` | Chemical formula analysis | `xraylabtool formula Al2O3` |\n| `atomic` | Atomic data lookup | `xraylabtool atomic Si,Al,Fe` |\n| `bragg` | Diffraction angle calculations | `xraylabtool bragg -d 3.14 -e 8.0` |\n| `list` | Show constants/fields/examples | `xraylabtool list constants` |\n| `install-completion` | Install shell completion | `xraylabtool install-completion` |\n| `uninstall-completion` | Remove shell completion | `xraylabtool uninstall-completion` |\n\n### Shell Completion Usage\n\nBoth command and flag syntaxes are supported:\n\n```bash\n# Subcommand syntax (recommended)\nxraylabtool install-completion # Install shell completion (auto-detect)\nxraylabtool install-completion --test # Test installation\nxraylabtool uninstall-completion # Remove completion\n\n# Flag syntax (alternative)\nxraylabtool --install-completion # Install shell completion (auto-detect)\n\n# Install for specific shells\nxraylabtool install-completion bash # Bash completion\nxraylabtool install-completion zsh # Zsh completion (requires zsh-completions)\nxraylabtool install-completion fish # Fish completion\nxraylabtool install-completion powershell # PowerShell completion\n```\n\n> **\ud83d\udca1 Shell Requirements**: Make sure to install the shell-specific prerequisites above before installing completion. Zsh users especially need `zsh-completions` for proper functionality.\n\n**Tab Completion Features:**\n- **Command completion**: Auto-complete all 9 available commands\n- **Option completion**: Complete command-line options and flags\n- **File path completion**: Automatic file path completion for input/output files\n- **Chemical formulas**: Suggestions for common chemical formulas\n- **Energy values**: Common X-ray energy suggestions (8.048, 10.0, 12.4 keV)\n\n### Output Formats\n\n- **Table** (default): Human-readable console output\n- **CSV**: Spreadsheet-compatible format\n- **JSON**: Structured data for programming\n\n### Advanced Features\n\n- **Energy Input Formats**: Single values, ranges, logarithmic spacing\n- **Parallel Processing**: Multi-core batch processing with `--workers`\n- **Field Selection**: Choose specific output fields with `--fields`\n- **Precision Control**: Set decimal places with `--precision`\n- **File Output**: Save results to CSV or JSON files\n- **Multi-Shell Tab Completion**: Intelligent completion for bash, zsh, fish, and PowerShell\n - **Context-aware**: Suggests appropriate values based on current command\n - **File completion**: Automatic file path completion for input/output files\n - **Chemical formulas**: Common materials and element suggestions\n - **Energy values**: Typical X-ray energy suggestions (Cu K\u03b1, Mo K\u03b1, etc.)\n - **Cross-platform**: Works on macOS, Linux, and Windows (with WSL/Cygwin)\n\n### \ud83d\udcd6 CLI Help and Documentation\n\nGet comprehensive help for any command:\n\n```bash\n# General help\nxraylabtool --help\n\n# Command-specific help\nxraylabtool calc --help\nxraylabtool batch --help\nxraylabtool install-completion --help\n\n# List available options and examples\nxraylabtool list --help\n```\n\n**CLI Features:**\n- 9 commands for X-ray analysis\n- Energy input formats: Single values, ranges, lists, and logarithmic spacing\n- Batch processing from CSV files\n- Output formats: Table, CSV, and JSON\n- Shell completion for bash, zsh, fish, and PowerShell\n- Cross-platform support\n\n---\n\n## Input Parameters\n\n| Parameter | Type | Description |\n| ------------ | ------------------------------------- | -------------------------------------------------------------- |\n| `formula(s)` | `str` or `List[str]` | Case-sensitive chemical formula(s), e.g., `\"CO\"` vs `\"Co\"` |\n| `energy` | `float`, `List[float]`, or `np.array` | X-ray photon energies in keV (valid range: **0.03\u201330 keV**) |\n| `density` | `float` or `List[float]` | Mass density in g/cm\u00b3 (one per formula) |\n\n---\n\n## Output: `XRayResult` Dataclass\n\nThe `XRayResult` dataclass contains all computed X-ray optical properties with clear, descriptive field names:\n\n### Material Properties\n- **`formula: str`** \u2013 Chemical formula\n- **`molecular_weight_g_mol: float`** \u2013 Molecular weight (g/mol)\n- **`total_electrons: float`** \u2013 Total electrons per molecule\n- **`density_g_cm3: float`** \u2013 Mass density (g/cm\u00b3)\n- **`electron_density_per_ang3: float`** \u2013 Electron density (electrons/\u00c5\u00b3)\n\n### X-ray Properties (Arrays)\n- **`energy_kev: np.ndarray`** \u2013 X-ray energies (keV)\n- **`wavelength_angstrom: np.ndarray`** \u2013 X-ray wavelengths (\u00c5)\n- **`dispersion_delta: np.ndarray`** \u2013 Dispersion coefficient \u03b4\n- **`absorption_beta: np.ndarray`** \u2013 Absorption coefficient \u03b2\n- **`scattering_factor_f1: np.ndarray`** \u2013 Real part of atomic scattering factor\n- **`scattering_factor_f2: np.ndarray`** \u2013 Imaginary part of atomic scattering factor\n\n### Derived Quantities (Arrays)\n- **`critical_angle_degrees: np.ndarray`** \u2013 Critical angles (degrees)\n- **`attenuation_length_cm: np.ndarray`** \u2013 Attenuation lengths (cm)\n- **`real_sld_per_ang2: np.ndarray`** \u2013 Real scattering length density (\u00c5\u207b\u00b2)\n- **`imaginary_sld_per_ang2: np.ndarray`** \u2013 Imaginary scattering length density (\u00c5\u207b\u00b2)\n\n> **\ud83d\udcdd Note**: Legacy field names (e.g., `Formula`, `MW`, `Critical_Angle`) are still supported for backward compatibility but will emit deprecation warnings. Use the new descriptive field names for clearer, more maintainable code.\n\n---\n\n## Usage Examples\n\n### Recommended: Using New Field Names\n\n```python\n# Calculate properties for silicon dioxide at 10 keV\nresult = xlt.calculate_single_material_properties(\"SiO2\", 10.0, 2.33)\n\n# Use new descriptive field names (recommended)\nprint(f\"Formula: {result.formula}\") # \"SiO2\"\nprint(f\"Molecular weight: {result.molecular_weight_g_mol:.2f} g/mol\") # 60.08 g/mol\nprint(f\"Dispersion: {result.dispersion_delta[0]:.2e}\") # \u03b4 value\nprint(f\"Critical angle: {result.critical_angle_degrees[0]:.3f}\u00b0\") # \u03b8c\nprint(f\"Attenuation: {result.attenuation_length_cm[0]:.1f} cm\") # Attenuation length\n```\n\n### Legacy Field Names (Still Supported)\n\n```python\n# Legacy field names still work but emit deprecation warnings\nprint(f\"Formula: {result.Formula}\") # \u26a0\ufe0f DeprecationWarning\nprint(f\"Molecular weight: {result.MW:.2f} g/mol\") # \u26a0\ufe0f DeprecationWarning\nprint(f\"Dispersion: {result.Dispersion[0]:.2e}\") # \u26a0\ufe0f DeprecationWarning\nprint(f\"Critical angle: {result.Critical_Angle[0]:.3f}\u00b0\") # \u26a0\ufe0f DeprecationWarning\n```\n\n### Energy Range Analysis\n\n```python\n# Energy sweep for material characterization\nenergies = np.linspace(8.0, 12.0, 21) # 21 points from 8-12 keV\nresult = xlt.calculate_single_material_properties(\"SiO2\", energies, 2.33)\n\n# Using new field names\nprint(f\"Energy range: {result.energy_kev[0]:.1f} - {result.energy_kev[-1]:.1f} keV\")\nprint(f\"Number of points: {len(result.energy_kev)}\")\nprint(f\"Dispersion range: {result.dispersion_delta.min():.2e} to {result.dispersion_delta.max():.2e}\")\n```\n\n### Multiple Materials Comparison\n\n```python\n# Compare common X-ray optics materials\nmaterials = {\n \"SiO2\": 2.2, # Fused silica\n \"Si\": 2.33, # Silicon\n \"Al2O3\": 3.95, # Sapphire\n \"C\": 3.52, # Diamond\n}\n\nformulas = list(materials.keys())\ndensities = list(materials.values())\nenergy = 10.0 # keV (Cu K\u03b1)\n\nresults = xlt.calculate_xray_properties(formulas, energy, densities)\n\n# Compare using new field names\nfor formula, result in results.items():\n print(f\"{formula:8}: \u03b8c = {result.critical_angle_degrees[0]:.3f}\u00b0, \"\n f\"\u03b4 = {result.dispersion_delta[0]:.2e}, \"\n f\"\u03bc = {result.attenuation_length_cm[0]:.1f} cm\")\n```\n\n### Enhanced Plotting Example\n\n```python\nimport matplotlib.pyplot as plt\n\n# Energy-dependent properties with new field names\nenergies = np.logspace(np.log10(1), np.log10(20), 100)\nresult = xlt.calculate_single_material_properties(\"Si\", energies, 2.33)\n\nfig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))\n\n# Plot using new descriptive field names\nax1.loglog(result.energy_kev, result.dispersion_delta, 'b-',\n label='\u03b4 (dispersion)', linewidth=2)\nax1.loglog(result.energy_kev, result.absorption_beta, 'r-',\n label='\u03b2 (absorption)', linewidth=2)\nax1.set_xlabel('Energy (keV)')\nax1.set_ylabel('Optical constants')\nax1.set_title('Silicon: Dispersion & Absorption')\nax1.legend()\nax1.grid(True, alpha=0.3)\n\n# Plot critical angle with new field name\nax2.semilogx(result.energy_kev, result.critical_angle_degrees, 'g-', linewidth=2)\nax2.set_xlabel('Energy (keV)')\nax2.set_ylabel('Critical angle (\u00b0)')\nax2.set_title('Silicon: Critical Angle')\nax2.grid(True, alpha=0.3)\n\nplt.tight_layout()\nplt.show()\n```\n\n---\n\n## Migration Guide: Legacy to New Field Names\n\nTo help users transition from legacy CamelCase field names to the new descriptive snake_case names, here's a comprehensive mapping:\n\n### Field Name Migration Table\n\n| **Legacy Name** | **New Name** | **Description** |\n| ---------------------------------- | ---------------------------------- | ------------------------------------------------- |\n| `result.Formula` | `result.formula` | Chemical formula string |\n| `result.MW` | `result.molecular_weight_g_mol` | Molecular weight (g/mol) |\n| `result.Number_Of_Electrons` | `result.total_electrons` | Total electrons per molecule |\n| `result.Density` | `result.density_g_cm3` | Mass density (g/cm\u00b3) |\n| `result.Electron_Density` | `result.electron_density_per_ang3` | Electron density (electrons/\u00c5\u00b3) |\n| `result.Energy` | `result.energy_kev` | X-ray energies (keV) |\n| `result.Wavelength` | `result.wavelength_angstrom` | X-ray wavelengths (\u00c5) |\n| `result.Dispersion` | `result.dispersion_delta` | Dispersion coefficient \u03b4 |\n| `result.Absorption` | `result.absorption_beta` | Absorption coefficient \u03b2 |\n| `result.f1` | `result.scattering_factor_f1` | Real part of atomic scattering factor |\n| `result.f2` | `result.scattering_factor_f2` | Imaginary part of atomic scattering factor |\n| `result.Critical_Angle` | `result.critical_angle_degrees` | Critical angles (degrees) |\n| `result.Attenuation_Length` | `result.attenuation_length_cm` | Attenuation lengths (cm) |\n| `result.reSLD` | `result.real_sld_per_ang2` | Real scattering length density (\u00c5\u207b\u00b2) |\n| `result.imSLD` | `result.imaginary_sld_per_ang2` | Imaginary scattering length density (\u00c5\u207b\u00b2) |\n\n### Quick Migration Examples\n\n```python\n# \u274c OLD (deprecated, but still works)\nprint(f\"Critical angle: {result.Critical_Angle[0]:.3f}\u00b0\") # Emits warning\nprint(f\"Attenuation: {result.Attenuation_Length[0]:.1f} cm\") # Emits warning\nprint(f\"MW: {result.MW:.2f} g/mol\") # Emits warning\n\n# \u2705 NEW (recommended)\nprint(f\"Critical angle: {result.critical_angle_degrees[0]:.3f}\u00b0\")\nprint(f\"Attenuation: {result.attenuation_length_cm[0]:.1f} cm\")\nprint(f\"MW: {result.molecular_weight_g_mol:.2f} g/mol\")\n```\n\n### Suppressing Deprecation Warnings (Temporary)\n\nIf you need to temporarily suppress deprecation warnings during migration:\n\n```python\nimport warnings\n\n# Suppress only XRayLabTool deprecation warnings\nwith warnings.catch_warnings():\n warnings.filterwarnings(\"ignore\", category=DeprecationWarning,\n message=\".*deprecated.*\")\n # Your legacy code here\n print(f\"Result: {result.Critical_Angle[0]}\")\n```\n\n### Migration Strategy\n\n1. **Identify Usage**: Search your codebase for the legacy field names\n2. **Update Gradually**: Replace legacy names with new ones section by section\n3. **Test**: Ensure your code works with new field names\n4. **Clean Up**: Remove any deprecation warning suppressions\n\n---\n\n## Supported Calculations\n\n### Optical Constants\n- **Dispersion coefficient (\u03b4)**: Real part of refractive index decrement\n- **Absorption coefficient (\u03b2)**: Imaginary part of refractive index decrement\n- **Complex refractive index**: n = 1 - \u03b4 - i\u03b2\n\n### Scattering Factors\n- **f1, f2**: Atomic scattering factors from CXRO/NIST databases\n- **Total scattering factors**: Sum over all atoms in the formula\n\n### Derived Quantities\n- **Critical angle**: Total external reflection angle\n- **Attenuation length**: 1/e penetration depth\n- **Scattering length density (SLD)**: Real and imaginary parts\n\n---\n\n## Scientific Background\n\nXRayLabTool uses atomic scattering factor data from the [Center for X-ray Optics (CXRO)](https://henke.lbl.gov/optical_constants/) and NIST databases. The calculations are based on:\n\n1. **Atomic Scattering Factors**: Henke, Gullikson, and Davis tabulations\n2. **Optical Constants**: Classical dispersion relations\n3. **Critical Angles**: Fresnel reflection theory\n4. **Attenuation**: Beer-Lambert law\n\n### Key Equations\n\n- **Refractive Index**: n = 1 - \u03b4 - i\u03b2\n- **Dispersion**: \u03b4 = (r\u2080\u03bb\u00b2/2\u03c0) \u00d7 \u03c1\u2091 \u00d7 f\u2081\n- **Absorption**: \u03b2 = (r\u2080\u03bb\u00b2/2\u03c0) \u00d7 \u03c1\u2091 \u00d7 f\u2082\n- **Critical Angle**: \u03b8c = \u221a(2\u03b4)\n\nWhere r\u2080 is the classical electron radius, \u03bb is wavelength, and \u03c1\u2091 is electron density.\n\n---\n\n## Performance Features\n\nXRayLabTool has been extensively optimized for high-performance calculations. Here are the key performance improvements:\n\n### Performance Cache System\n\n#### Preloaded Atomic Data Cache\n- 92 elements preloaded for instant access to atomic data\n- Eliminates database queries to Mendeleev for common elements\n- Fast access for Si, O, Al, Fe, and other common elements\n- Fallback to Mendeleev for uncommon elements with runtime caching\n\n```python\n# Check cache statistics\nfrom xraylabtool.atomic_data_cache import get_cache_stats\nprint(get_cache_stats())\n# {'preloaded_elements': 92, 'runtime_cached_elements': 0, 'total_cached_elements': 92}\n```\n\n#### Advanced Caching Infrastructure\n- Interpolator caching: Reuses PCHIP interpolators across calculations\n- LRU caches: Memory management for frequently accessed data\n- Bulk loading: Optimized atomic data loading for multiple elements\n\n### Vectorized Mathematical Operations\n\n#### Matrix Operations for Multi-Element Materials\n- Vectorized computations: Matrix operations instead of loops for multi-element materials\n- NumPy optimizations: Proper dtypes and memory-contiguous arrays\n- Batch interpolation: Process multiple elements simultaneously\n- Faster mathematical computations compared to previous versions\n\n#### Smart Single vs Multi-Element Optimization\n```python\n# Single element materials use optimized direct computation\nresult_single = xlt.calculate_single_material_properties(\"Si\", energies, 2.33)\n\n# Multi-element materials use vectorized matrix operations\nresult_multi = xlt.calculate_single_material_properties(\"SiO2\", energies, 2.2)\n```\n\n### Memory-Efficient Batch Processing\n\n#### High-Performance Batch API\nFor large-scale calculations, use the optimized batch processor:\n\n```python\nfrom xraylabtool.batch_processor import calculate_batch_properties, BatchConfig\n\n# Configure for optimal performance\nconfig = BatchConfig(\n chunk_size=100, # Process in chunks of 100\n max_workers=8, # Use 8 parallel workers\n memory_limit_gb=4.0, # Limit memory usage\n enable_progress=True # Show progress bar\n)\n\n# Process large batches efficiently\nformulas = [\"SiO2\", \"Al2O3\", \"Fe2O3\"] * 100 # 300 materials\nenergies = np.linspace(5, 15, 50) # 50 energy points\ndensities = [2.2, 3.95, 5.24] * 100\n\nresults = calculate_batch_properties(formulas, energies, densities, config)\n```\n\n#### Memory Management Features\n- Chunked processing: Handles datasets larger than available RAM\n- Automatic garbage collection: Prevents memory leaks during large calculations\n- Memory monitoring: Real-time memory usage tracking\n- Progress tracking: Visual feedback for long-running calculations\n\n### Performance Benchmarks\n\n#### Real-World Performance (Modern Hardware)\n\n**Single Material Calculations:**\n- Single energy point: ~0.03 ms\n- 100 energy points: ~0.3 ms\n- 1000 energy points: ~3 ms\n\n**Batch Processing:**\n- High throughput for multiple materials\n- 50 materials \u00d7 50 energies = 2,500 calculations in ~17ms\n- Average: 0.33 ms per material\n\n**Memory Efficiency:**\n- 150 materials \u00d7 100 energies = 15,000 calculations\n- Memory usage: <1 MB additional RAM\n- No memory leaks during extended calculations\n\n#### Performance Comparison\n\n| Operation | Before Optimization | After Optimization | Improvement |\n|-----------|--------------------|--------------------|-------------|\n| Atomic data access | ~200ms (DB query) | ~0.001ms (cache) | 200,000x |\n| Single calculation | ~1.07s | ~0.003s | 350x |\n| Mathematical ops | Baseline | Vectorized | 2-3x |\n| Memory usage | High allocation | Chunked/optimized | 5-10x |\n| Batch processing | Sequential | Parallel+chunked | 5-15x |\n\n### Performance Best Practices\n\n#### For Maximum Speed\n```python\n# 1. Use common elements (preloaded in cache)\ncommon_materials = [\"SiO2\", \"Al2O3\", \"Fe2O3\", \"Si\", \"C\"] # \u2705 Fast\nuncommon_materials = [\"Uuo\", \"Fl\", \"Mc\"] # \u26a0\ufe0f Slower (Mendeleev fallback)\n\n# 2. Reuse energy arrays when possible\nenergies = np.linspace(5, 15, 100)\nfor formula in formulas:\n result = xlt.calculate_single_material_properties(formula, energies, density)\n\n# 3. Use batch processing for many materials\nresults = xlt.calculate_xray_properties(formulas, energies, densities) # \u2705 Parallel\n\n# Instead of:\n# results = {f: xlt.calculate_single_material_properties(f, energies, d)\n# for f, d in zip(formulas, densities)} # \u274c Sequential\n```\n\n#### For Large Datasets\n```python\n# Use the optimized batch processor for very large datasets\nfrom xraylabtool.batch_processor import calculate_batch_properties, BatchConfig\n\n# Configure for your system\nconfig = BatchConfig(\n chunk_size=min(100, len(formulas) // 4), # Adapt to dataset size\n max_workers=os.cpu_count() // 2, # Use half of CPU cores\n memory_limit_gb=8.0, # Set appropriate memory limit\n enable_progress=True # Monitor progress\n)\n\nresults = calculate_batch_properties(formulas, energies, densities, config)\n```\n\n### Performance Monitoring\n\n```python\n# Monitor cache performance\nfrom xraylabtool.atomic_data_cache import get_cache_stats, is_element_preloaded\n\nprint(f\"Cache stats: {get_cache_stats()}\")\nprint(f\"Silicon preloaded: {is_element_preloaded('Si')}\") # True\nprint(f\"Unobtainium preloaded: {is_element_preloaded('Uo')}\") # False\n\n# Monitor memory usage during batch processing\nfrom xraylabtool.batch_processor import MemoryMonitor\n\nmonitor = MemoryMonitor(limit_gb=4.0)\nprint(f\"Current memory usage: {monitor.get_memory_usage_mb():.1f} MB\")\nprint(f\"Within limits: {monitor.check_memory()}\")\n```\n\n---\n\n## Testing and Validation\n\nXRayLabTool includes a comprehensive test suite with:\n\n- **Unit Tests**: Individual function validation\n- **Integration Tests**: End-to-end workflows\n- **Physics Tests**: Consistency with known relationships\n- **Performance Tests**: Regression monitoring\n- **Robustness Tests**: Edge cases and error handling\n\nRun tests with:\n```bash\npytest tests/ -v\n```\n\n---\n\n## API Reference\n\n### Main Functions\n\n#### `calculate_single_material_properties(formula, energy, density)`\nCalculate X-ray properties for a single material.\n\n**Parameters:**\n- `formula` (str): Chemical formula\n- `energy` (float/array): X-ray energies in keV\n- `density` (float): Mass density in g/cm\u00b3\n\n**Returns:** `XRayResult` object\n\n#### `calculate_xray_properties(formulas, energies, densities)`\nCalculate X-ray properties for multiple materials.\n\n**Parameters:**\n- `formulas` (List[str]): List of chemical formulas\n- `energies` (float/array): X-ray energies in keV\n- `densities` (List[float]): Mass densities in g/cm\u00b3\n\n**Returns:** `Dict[str, XRayResult]`\n\n### Utility Functions\n\n- `energy_to_wavelength(energy)`: Convert energy (keV) to wavelength (\u00c5)\n- `wavelength_to_energy(wavelength)`: Convert wavelength (\u00c5) to energy (keV)\n- `parse_formula(formula)`: Parse chemical formula into elements and counts\n- `get_atomic_number(symbol)`: Get atomic number for element symbol\n- `get_atomic_weight(symbol)`: Get atomic weight for element symbol\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Acknowledgments\n\n- **CXRO**: Atomic scattering factor databases\n- **NIST**: Reference data and validation\n- **NumPy/SciPy**: Scientific computing foundation\n\n---\n\n## Documentation & Support\n\n### \ud83d\udcd6 Documentation\n- **Main README**: Overview and Python API examples\n- **CLI Reference**: [CLI_REFERENCE.md](CLI_REFERENCE.md) - Comprehensive command-line interface guide\n- **Virtual Environment Setup**: [VIRTUAL_ENV.md](VIRTUAL_ENV.md) - Development environment setup\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - Version history and updates\n- **Online Docs**: [https://pyxraylabtool.readthedocs.io](https://pyxraylabtool.readthedocs.io)\n\n### \ud83d\udd0d Getting Help\n- **Issues**: [GitHub Issues](https://github.com/imewei/pyXRayLabTool/issues) - Bug reports and feature requests\n- **Discussions**: [GitHub Discussions](https://github.com/imewei/pyXRayLabTool/discussions) - Questions and community support\n- **CLI Help**: `xraylabtool --help` or `xraylabtool <command> --help` for command-specific help\n\n---\n\n## Citation\n\nIf you use XRayLabTool in your research, please cite:\n\n```bibtex\n@software{xraylabtool,\n title = {XRayLabTool: High-Performance X-ray Optical Properties Calculator},\n author = {Wei Chen},\n url = {https://github.com/imewei/pyXRayLabTool},\n year = {2024},\n version = {0.1.10}\n}\n```\n\n---\n\n<!-- SEO Meta Tags -->\n<!--\nPrimary Keywords: X-ray optical properties, atomic scattering factors, synchrotron calculations, Python X-ray tools\nSecondary Keywords: CXRO NIST database, X-ray reflectometry, materials characterization, critical angle calculator\nLong-tail Keywords: high-performance X-ray property calculator, Python synchrotron beamline tools, X-ray diffraction analysis software\n-->\n\n<!-- GitHub Topics for Discovery -->\n<!-- Topics: xray, synchrotron, crystallography, materials-science, optics, physics, scientific-computing, python-package, cli-tool -->\n",
"bugtrack_url": null,
"license": null,
"summary": "Ultra-fast Python package for X-ray optical properties calculation with CXRO/NIST data, CLI tools, and synchrotron applications",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/imewei/pyXRayLabTool/issues",
"CLI Reference": "https://pyxraylabtool.readthedocs.io/en/latest/cli_guide.html",
"Changelog": "https://github.com/imewei/pyXRayLabTool/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/imewei/pyXRayLabTool/discussions",
"Documentation": "https://pyxraylabtool.readthedocs.io",
"Homepage": "https://github.com/imewei/pyXRayLabTool",
"Release Notes": "https://github.com/imewei/pyXRayLabTool/releases",
"Repository": "https://github.com/imewei/pyXRayLabTool",
"Shell Completion": "https://pyxraylabtool.readthedocs.io/en/latest/cli_guide.html#install-completion-shell-completion-setup",
"Source Code": "https://github.com/imewei/pyXRayLabTool"
},
"split_keywords": [
"xray",
" x-ray",
" xrd",
" xrr",
" saxs",
" crystallography",
" diffraction",
" scattering",
" synchrotron",
" beamline",
" optics",
" reflectometry",
" absorption",
" spectroscopy",
" materials-science",
" condensed-matter",
" physics",
" chemistry",
" nanotechnology",
" thin-films",
" multilayers",
" nanostructures",
" characterization",
" cxro",
" nist",
" atomic-scattering-factors",
" optical-constants",
" refractive-index",
" critical-angle",
" attenuation-length",
" form-factors",
" dispersion",
" absorption-coefficient",
" high-performance",
" vectorized",
" batch-processing",
" parallel-processing",
" scientific-computing",
" numerical-analysis",
" laboratory",
" analysis",
" cli",
" command-line",
" python-package",
" api",
" cross-platform",
" shell-completion",
" bash-completion",
" zsh-completion",
" fish-completion",
" powershell-completion",
" tab-completion",
" windows-powershell",
" pwsh",
" materials-characterization",
" structure-analysis",
" quality-control",
" medical-imaging",
" industrial-radiography",
" non-destructive-testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f132aeaba92a2bffcddfe4ea09e567047f7391d032b5bf0897c2f1bbbdb16ec8",
"md5": "cfa0d83bfcb2f3f725494b9c1397b9d4",
"sha256": "df8dbd8ae0c56c8114044a3d74bed76925f707c72779a99e2c0750392782edff"
},
"downloads": -1,
"filename": "xraylabtool-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cfa0d83bfcb2f3f725494b9c1397b9d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 595828,
"upload_time": "2025-09-12T14:47:56",
"upload_time_iso_8601": "2025-09-12T14:47:56.327627Z",
"url": "https://files.pythonhosted.org/packages/f1/32/aeaba92a2bffcddfe4ea09e567047f7391d032b5bf0897c2f1bbbdb16ec8/xraylabtool-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2c728cac43ccb74fd91d637ec9edaf3231f436317188018617cc2ff3755a8b26",
"md5": "4df6092575f0520cd3ad9d6fd4e41feb",
"sha256": "31a9ce8a64846e61eb3746dfdadf24f15542dbb1cc76efa080640b083a29ac70"
},
"downloads": -1,
"filename": "xraylabtool-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "4df6092575f0520cd3ad9d6fd4e41feb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 669927,
"upload_time": "2025-09-12T14:47:58",
"upload_time_iso_8601": "2025-09-12T14:47:58.392977Z",
"url": "https://files.pythonhosted.org/packages/2c/72/8cac43ccb74fd91d637ec9edaf3231f436317188018617cc2ff3755a8b26/xraylabtool-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 14:47:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imewei",
"github_project": "pyXRayLabTool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.9.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "mendeleev",
"specs": [
[
">=",
"0.15.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.64.0"
]
]
}
],
"lcname": "xraylabtool"
}
