Metadata-Version: 2.4
Name: xraylabtool
Version: 0.5.0
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 AND Zlib
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/guides/cli_reference.html
Project-URL: Shell Completion Guide, https://pyxraylabtool.readthedocs.io/en/latest/guides/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 :: 3.14
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: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
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: psutil>=7.1.3
Requires-Dist: jax>=0.12.0.1
Requires-Dist: jaxlib>=0.12.0.1
Requires-Dist: PySide6>=6.10.1
Requires-Dist: pyqtgraph>=0.13.7
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: pytest<9.2,>=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.20.0
Requires-Dist: ruff>=0.17.2
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: pre-commit>=4.5.0
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: nbsphinx>=0.9.8
Requires-Dist: doc8>=2.0.0
Requires-Dist: rstcheck>=6.2.5
Provides-Extra: gpu-cuda13
Requires-Dist: jax-cuda13-plugin>=0.12.0.1; extra == "gpu-cuda13"
Requires-Dist: jax-cuda13-pjrt>=0.12.0.1; extra == "gpu-cuda13"
Provides-Extra: gpu-cuda12
Requires-Dist: jax-cuda12-plugin>=0.12.0.1; extra == "gpu-cuda12"
Requires-Dist: jax-cuda12-pjrt>=0.12.0.1; 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)

Python package and CLI for calculating X-ray optical properties of materials using CXRO/NIST atomic scattering factor data. The calculations are JAX-first (float64) and run on the CPU or an NVIDIA GPU.

## Installation

### Using uv (Recommended)

```bash
# Core package (JAX on CPU, CLI, GUI)
uv pip install xraylabtool

# NVIDIA GPU acceleration (pick the CUDA major matching your driver)
uv pip install "xraylabtool[gpu_cuda13]"
uv pip install "xraylabtool[gpu_cuda12]"
```

### Using pip

```bash
pip install xraylabtool
```

### Using conda

```bash
# Core package (CPU only) from the imewei channel; dependencies come from conda-forge
conda install -c imewei -c conda-forge xraylabtool
```

The conda package does not include the CUDA GPU extras; use pip or uv for GPU support.

### Development

```bash
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 kk Si --energies 8,10,12             # Kramers-Kronig f1 from f2 (keV)
xraylabtool completion install                    # Shell tab-completion
```

`xtool` and `xlt` are short aliases for `xraylabtool` (e.g. `xtool calc SiO2 -e 10.0 -d 2.2`).
Shell tab-completion installed via `xraylabtool completion install` works for both names.

### GUI

```bash
xraylabtool-gui        # or the short aliases: xtool-gui, xlt-gui
python -m xraylabtool.gui   # equivalent module form
```

Single-material analysis, multi-material comparison and Kramers-Kronig f1 reconstruction with interactive plots and CSV/PNG export. The window opens maximized.

![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.

## JAX Backend

All calculations run in JAX with float64 on JAX's default device: the CPU, or the
GPU of a CUDA install (`gpu_cuda12`/`gpu_cuda13` extra). There is no NumPy backend and
no switch to select one; set `JAX_PLATFORMS=cpu` to force the CPU.

- The first compute call compiles a small program (a fraction of a second on CPU); later
  calls with the same shape buckets compile nothing. `xraylabtool.warm_up()` precompiles
  explicitly (`energy_counts=` also warms the energy buckets you will use), and the CLI and
  GUI keep a persistent compile cache (`XRAYLABTOOL_NO_JAX_CACHE=1` opts out; library users
  opt in with `XRAYLABTOOL_JAX_CACHE=1`).
- `set_backend("jax")` is kept as a no-op; `set_backend("numpy")` raises `ValueError`.
- `xraylabtool.calculators.optics.optical_properties` is a pure device function that works
  under `jax.jit`, `jax.vmap` and `jax.grad`.
- `import xraylabtool`, `--help` and `--version` do not import JAX.

## 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)
- [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/html  # 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.5.0},
  year = {2024--2026}
}
```

## License

MIT, with bundled kkcalc material under Zlib (see [NOTICE](NOTICE)). 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
- [kkcalc](https://github.com/benajamin/kkcalc) (Benjamin Watts, Daniel J. Lauk) — Kramers-Kronig transform and tabulated f2 data, ported in `xraylabtool.kk`; method: B. Watts, *Opt. Express* **22**(19), 23628–23639 (2014), doi:10.1364/OE.22.023628
