Metadata-Version: 2.4
Name: xraylabtool
Version: 0.4.1
Summary: Ultra-fast Python package for X-ray optical properties calculation with CXRO/NIST data, CLI tools, and synchrotron applications
Author-email: Wei Chen <wchen@anl.gov>
Maintainer-email: Wei Chen <wchen@anl.gov>
License-Expression: MIT
Project-URL: Homepage, https://github.com/imewei/pyXRayLabTool
Project-URL: Documentation, https://pyxraylabtool.readthedocs.io
Project-URL: Repository, https://github.com/imewei/pyXRayLabTool
Project-URL: Source Code, https://github.com/imewei/pyXRayLabTool
Project-URL: Bug Tracker, https://github.com/imewei/pyXRayLabTool/issues
Project-URL: Changelog, https://github.com/imewei/pyXRayLabTool/blob/main/CHANGELOG.md
Project-URL: CLI Reference, https://pyxraylabtool.readthedocs.io/en/latest/cli_guide.html
Project-URL: Shell Completion Guide, https://pyxraylabtool.readthedocs.io/en/latest/completion_guide.html
Project-URL: Discussions, https://github.com/imewei/pyXRayLabTool/discussions
Project-URL: Release Notes, https://github.com/imewei/pyXRayLabTool/releases
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,virtual-environment,environment-isolation,materials-characterization,structure-analysis,quality-control,medical-imaging,industrial-radiography,non-destructive-testing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.3.5
Requires-Dist: pandas>=2.3.3
Requires-Dist: scipy>=1.16.3
Requires-Dist: mendeleev>=1.1.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: jax>=0.8.0
Requires-Dist: jaxlib>=0.8.0
Requires-Dist: interpax>=0.3.0
Requires-Dist: psutil>=7.1.3
Requires-Dist: pytest>=9.0.2
Requires-Dist: pytest-cov>=7.0.0
Requires-Dist: pytest-benchmark>=5.2.3
Requires-Dist: pytest-xdist>=3.8.0
Requires-Dist: pytest-timeout>=2.4.0
Requires-Dist: mypy>=1.19.0
Requires-Dist: ruff>=0.14.9
Requires-Dist: safety>=2.3.4
Requires-Dist: pandas-stubs>=2.3.3.251201
Requires-Dist: types-tqdm>=4.67.0.20250809
Requires-Dist: types-psutil>=7.1.3.20251202
Requires-Dist: pbr>=7.0.3
Requires-Dist: pre-commit>=4.5.0
Requires-Dist: codecov>=2.1.13
Requires-Dist: build>=1.0.0
Requires-Dist: twine>=4.0.0
Requires-Dist: sphinx>=8.2.3
Requires-Dist: furo>=2025.9.25
Requires-Dist: sphinx-autodoc-typehints>=3.5.2
Requires-Dist: sphinx-copybutton>=0.5.2
Requires-Dist: sphinx-design>=0.6.1
Requires-Dist: sphinx-tabs>=3.4.7
Requires-Dist: sphinx-togglebutton>=0.3.2
Requires-Dist: myst-parser>=4.0.1
Requires-Dist: sphinxcontrib-napoleon>=0.7
Requires-Dist: doc8>=2.0.0
Requires-Dist: rstcheck>=6.2.5
Requires-Dist: Pygments>=2.19.2
Requires-Dist: docutils>=0.21.2
Requires-Dist: nbsphinx>=0.9.8
Requires-Dist: ipykernel>=7.1.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: jinja2>=3.1.6
Requires-Dist: fastapi>=0.124.0
Requires-Dist: uvicorn[standard]>=0.38.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: PyJWT[crypto]>=2.10.0
Requires-Dist: bcrypt>=4.2.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: statsmodels>=0.14.6
Requires-Dist: memory-profiler>=0.61.0
Requires-Dist: line-profiler>=5.0.0
Requires-Dist: py-spy>=0.4.1
Requires-Dist: PySide6>=6.10.1
Requires-Dist: pyqtgraph>=0.13.7
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: seaborn>=0.13.2
Requires-Dist: plotly>=6.5.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: jupyterlab>=4.5.0
Requires-Dist: ipywidgets>=8.1.8
Provides-Extra: gpu-cuda13
Requires-Dist: jax-cuda13-plugin>=0.8.0; extra == "gpu-cuda13"
Requires-Dist: jax-cuda13-pjrt>=0.8.0; extra == "gpu-cuda13"
Provides-Extra: gpu-cuda12
Requires-Dist: jax-cuda12-plugin>=0.8.0; extra == "gpu-cuda12"
Requires-Dist: jax-cuda12-pjrt>=0.8.0; extra == "gpu-cuda12"
Dynamic: license-file

# XRayLabTool

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/xraylabtool.svg)](https://badge.fury.io/py/xraylabtool)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/pyxraylabtool/badge/?version=latest)](https://pyxraylabtool.readthedocs.io/en/latest/?badge=latest)
[![CI](https://github.com/imewei/pyXRayLabTool/actions/workflows/ci.yml/badge.svg)](https://github.com/imewei/pyXRayLabTool/actions/workflows/ci.yml)

Ultra-fast Python package and CLI for calculating X-ray optical properties of materials using CXRO/NIST atomic scattering factor data. Supports NumPy and JAX backends for CPU/GPU acceleration.

## Installation

```bash
pip install xraylabtool

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

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

# Development (uses uv)
git clone https://github.com/imewei/pyXRayLabTool.git
cd pyXRayLabTool
uv sync
```

## Quick Start

### Python API

```python
import xraylabtool as xlt

# Single material at 10 keV
result = xlt.calculate_single_material_properties("SiO2", 10.0, 2.2)
print(f"Critical angle: {result.critical_angle_degrees[0]:.3f}°")
print(f"Attenuation length: {result.attenuation_length_cm[0]:.2f} cm")

# Multiple materials comparison
materials = {"SiO2": 2.2, "Si": 2.33, "Al2O3": 3.95, "C": 3.52}
results = xlt.calculate_xray_properties(
    list(materials.keys()), 10.0, list(materials.values())
)
for formula, r in results.items():
    print(f"{formula:6}: θc = {r.critical_angle_degrees[0]:.3f}°")
```

### Command-Line Interface

```bash
xraylabtool calc SiO2 -e 10.0 -d 2.2           # Single material
xraylabtool calc Si -e 5-15:11 -d 2.33 -o out.csv  # Energy sweep
xraylabtool convert energy 8.048,10.0 --to wavelength
xraylabtool formula Al2O3                         # Formula analysis
xraylabtool bragg -d 3.14,2.45 -e 8.048          # Bragg angles
xraylabtool batch materials.csv -o results.csv    # Batch processing
xraylabtool completion install                    # Shell tab-completion
```

### GUI

```bash
python -m xraylabtool.gui
```

Single-material analysis and multi-material comparison with interactive plots and CSV/PNG export.

![GUI overview](docs/_static/gui_main_offscreen.png)

## Calculated Properties

| Property | Field | Unit |
|----------|-------|------|
| Dispersion coefficient | `dispersion_delta` | dimensionless |
| Absorption coefficient | `absorption_beta` | dimensionless |
| Scattering factors | `scattering_factor_f1`, `f2` | electrons |
| Critical angle | `critical_angle_degrees` | degrees |
| Attenuation length | `attenuation_length_cm` | cm |
| Scattering length density | `real_sld_per_ang2`, `imaginary_sld_per_ang2` | Å⁻² |

All properties are returned as NumPy arrays in the `XRayResult` dataclass, supporting single energies or energy sweeps.

## Backend Selection

```python
import xraylabtool as xlt

# Switch to JAX for JIT-compiled GPU acceleration
xlt.set_backend("jax")

# Switch back to NumPy (default)
xlt.set_backend("numpy")
```

## Scientific Background

Calculations use Henke, Gullikson, and Davis atomic scattering factor tabulations (0.03–30 keV):

- **Refractive index**: n = 1 - δ - iβ
- **Critical angle**: θc = √(2δ)
- **Attenuation**: Beer-Lambert law with μ = 4πβ/λ

## Documentation

Full documentation: **[pyxraylabtool.readthedocs.io](https://pyxraylabtool.readthedocs.io)**

- [API Reference](https://pyxraylabtool.readthedocs.io/en/latest/api/)
- [CLI Guide](https://pyxraylabtool.readthedocs.io/en/latest/guides/cli_reference.html)
- [Migration Guide (v0.3 → v0.4)](https://pyxraylabtool.readthedocs.io/en/latest/guides/migration_guide_v0_4.html)
- [Architecture Decisions](https://pyxraylabtool.readthedocs.io/en/latest/architecture/)
- [Changelog](CHANGELOG.md)

## Development

```bash
uv sync                          # Install dependencies
uv run pytest                    # Run tests
uv run ruff check .              # Lint
uv run ruff format .             # Format
uv run sphinx-build docs docs/_build  # Build docs
make test                        # Or use Makefile shortcuts
```

## Citation

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

## License

MIT License. See [LICENSE](LICENSE) for details.

## Acknowledgments

- [CXRO](https://henke.lbl.gov/optical_constants/) — Atomic scattering factor databases
- [NIST](https://www.nist.gov/) — Reference data and validation
