Metadata-Version: 2.5
Name: rietx
Version: 1.10.0
Summary: Python-API-first analysis and Rietveld refinement of powder diffraction data
Project-URL: Homepage, https://github.com/yue-here/rietx
Project-URL: Documentation, https://rietx.org/docs/
Author: Yue Wu, Michael W. Gaultois
License-Expression: MIT
License-File: LICENSE
License-File: LICENSE-3RD-PARTY.md
Keywords: crystallography,neutron-diffraction,powder-diffraction,refinement,rietveld,xrd
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: gemmi>=0.6.5
Requires-Dist: matplotlib>=3.10.5; python_version >= '3.14'
Requires-Dist: matplotlib>=3.10; python_version < '3.14'
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Requires-Dist: rietx-kernels<2,>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: spglib>=2.8
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: ipykernel>=6.29; extra == 'dev'
Requires-Dist: myst-nb>=1.1; extra == 'dev'
Requires-Dist: myst-parser>=3; extra == 'dev'
Requires-Dist: nbclient>=0.10; extra == 'dev'
Requires-Dist: nbformat>=5.10; extra == 'dev'
Requires-Dist: pydata-sphinx-theme>=0.23; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: spgrep>=0.7; extra == 'dev'
Requires-Dist: sphinx-design>=0.6; extra == 'dev'
Requires-Dist: sphinx-markdown-builder<0.7,>=0.6.11; extra == 'dev'
Requires-Dist: sphinx>=7.4; extra == 'dev'
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == 'dev'
Requires-Dist: sphinxcontrib-mermaid>=2.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb>=1.1; extra == 'docs'
Requires-Dist: myst-parser>=3; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.23; extra == 'docs'
Requires-Dist: sphinx-design>=0.6; extra == 'docs'
Requires-Dist: sphinx-markdown-builder<0.7,>=0.6.11; extra == 'docs'
Requires-Dist: sphinx>=7.4; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid>=2.1; extra == 'docs'
Provides-Extra: gui
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == 'jax'
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29; extra == 'notebooks'
Requires-Dist: nbclient>=0.10; extra == 'notebooks'
Requires-Dist: nbformat>=5.10; extra == 'notebooks'
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == 'torch'
Provides-Extra: viz
Description-Content-Type: text/markdown

# rietx

[![CI](https://github.com/yue-here/rietx/actions/workflows/ci.yml/badge.svg)](https://github.com/yue-here/rietx/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/rietx)](https://pypi.org/project/rietx/)

**`rietx`** is an open-source Rietveld refinement and pattern analysis Python module with a streamlined API designed for those who want to drive refinements from code.

## Installation

```sh
pip install rietx            # Python >= 3.11; numpy/scipy core, compiled kernels, matplotlib figures
```

## Example refinement

Condensed from [`examples/nac_11bm.py`](https://github.com/yue-here/rietx/blob/main/examples/nac_11bm.py),
which fits APS 11-BM synchrotron data on Na₂Ca₃Al₂F₁₄ with a CaF₂ impurity.

```python
import rietx as rx

data = rx.read_pattern("11BM_NAC.fxye")              # esd column read from file
structure = rx.Structure.from_cif("cod_1000236.cif")
instrument = rx.Instrument.debye_scherrer(wavelength=0.4139090)

ref = rx.Refinement(structure, instrument)

# structure-free Le Bail first: cell + profile + background
lebail = ref.fit(data, mode="lebail", two_theta_limits=(2, 24))

# then Rietveld under the staged turn-on order of McCusker et al. (1999)
result = ref.fit(data, plan="mccusker_default", two_theta_limits=(2, 24))

report = rx.build_report(result)                     # numbers, not pixels
result.plot(path="fit.png")                          # obs/calc/diff/ticks
```

Output of the full script (trimmed at the `…`):

```text
Le Bail:  status=converged  Rwp=0.1436  GoF=5.44  a=10.251213 A
Rietveld: status=converged  Rwp=0.0930  GoF=3.53
          a = 10.251216 +/- 0.000039 A (COD reference 10.257(1); high-accuracy powder ~10.2497-10.2506)
          warning[FLOOR_HIT]: phases.1.atoms.0.biso refined to its floor (ρ=+0.188).
          info[CAPILLARY_OFFSET_UNAVAILABLE]: This capillary geometry declares no goniometer radius, …

FitReport: 53 misfit regions. The top 15 carry 74% of χ² and the other 38 carry 15%.
  region  14.22- 14.54 deg  localRwp=0.154  chi2share=13.7%  max|d/sig|=49.6
  …

Refinement history (every stage is a restorable checkpoint):
t5544a638  15 nodes  data=11BM_NAC.fxye
 n0000  root                   —
 n0001  stage:bkg              Rwp 3.1772
 …
*n0014  stage:closing          Rwp 0.0930
```

## Current features

- Multi-phase Rietveld, Le Bail and Pawley
- X-ray and constant-wavelength [neutron](https://rietx.org/using/data.html) data
- [Magnetic refinement](https://rietx.org/using/refining.html) (in progress)
- [Joint refinement](https://rietx.org/using/series.html) of several patterns
- Preset [staged plans](https://rietx.org/using/concepts.html)
- Extensively documented [forward model](https://rietx.org/forward-model.html)
- [Corrections](https://rietx.org/corrections.html): axial divergence, displacement and
  transparency, absorption, preferred orientation, anisotropic displacement and strain,
  anomalous dispersion
- [Constraints and restraints](https://rietx.org/using/constraints.html)
- [Quantitative phase analysis](https://rietx.org/using/qpa.html)
- [Multiple solvers](https://rietx.org/estimation.html)
- Optional [JAX & torch differentiable backends](https://rietx.org/using/install.html) 
- [Readers](https://rietx.org/using/files.html) for many standard formats including
  `.xy`/`.xye`, GSAS raw, pdCIF, `.chi`, Rigaku `.ras`/`.rasx`, Bruker
  `.uxd`/`.brml`/`.raw`, PANalytical `.xrdml`/`.udf` and Philips `.rd`/`.sd`
- [Another program's refinement, read in](https://rietx.org/using/files.html):
  `read_project_model` opens a TOPAS `.inp` or a FullProf `.pcr` by content,
  refine flags included
- [Writers](https://rietx.org/using/files.html) for TOPAS, FullProf, GSAS and GSAS-II files
- The [`FitReport`](https://rietx.org/using/report.html), an output bundle designed for agentic consumption. 
- A git-style branchable [refinement history](https://rietx.org/using/history.html)
- [Sequential refinements](https://rietx.org/using/series.html)
- [Indexing](https://rietx.org/using/indexing.html), and
  [peaks fitted on their own](https://rietx.org/using/indexing.html)
  at positions you name, with no structure at all
- [Declared extra peaks and humps](https://rietx.org/using/model.html):
  a sample holder or an unidentified line stays in the fit instead of being
  excluded along with the sample peaks underneath it
- [Extensive agentic surface](https://rietx.org/using/agents.html)
- [PowderLine recipe interchange](https://rietx.org/using/recipe.html): read a
  pipeline's recipe, write its four tables back
- [GUI mode](https://rietx.org/using/gui-quickstart.html) `rietx gui`
- [Live run viewer](https://rietx.org/using/refining.html) `rietx watch`
- [Settings comparison](https://rietx.org/using/cli.html) `rietx compare`
- [Structure figures](https://rietx.org/using/exports.html) `rx.viz.render_structure`
- [Jupyter display](https://rietx.org/using/results.html)
  and [tutorial notebooks](https://github.com/yue-here/rietx/tree/main/examples/tutorials)

## Validation

Validation suites are run in CI against real data. Details here: [docs/VALIDATION.md](https://github.com/yue-here/rietx/blob/main/docs/VALIDATION.md)

## Documentation

- HTML manual: https://rietx.org/docs/ (https://rietx.org/ is the project page)
- Driving instructions for agents: the [agent skill](https://rietx.org/skill/rietx/SKILL.md)
  (`rietx skill --install` puts it where your harness looks)

## Development

```sh
git clone https://github.com/yue-here/rietx && cd rietx
uv venv --python 3.12 && uv pip install -e ".[dev]"
.venv/bin/python -m pytest -n auto --dist loadgroup -m "not slow"   # ~1-3 min
.venv/bin/python -m pytest -n auto --dist loadgroup                 # + real-data acceptance, ~15-30 min
.venv/bin/python -m ruff check src tests examples
```

`--dist loadgroup` is required to keep shared expensive fixtures on one
worker. For the test ladder and style see
[CONTRIBUTING.md](https://github.com/yue-here/rietx/blob/main/CONTRIBUTING.md), and [AGENTS.md](https://github.com/yue-here/rietx/blob/main/AGENTS.md) if your
contributor is an agent.

## License and credits

MIT. Algorithms are independently implemented from the published literature, with sources cited in the manual. A full list of sources is also provided in
[ATTRIBUTION.md](https://github.com/yue-here/rietx/blob/main/ATTRIBUTION.md),
and test-data provenance is listed in
[tests/data/README.md](https://github.com/yue-here/rietx/blob/main/tests/data/README.md).
CIF and symmetry handling uses
[gemmi](https://github.com/project-gemmi/gemmi). To cite the package, use
[CITATION.cff](https://github.com/yue-here/rietx/blob/main/CITATION.cff).
