pip install rietx
Rietveld refinement for humans and machines
rietx is an open-source Python package for analysing powder diffraction data. It's easy to install and the streamlined API can be used by most common AI coding agents.
Open Claude Code, Codex or another coding agent in the folder that holds your data, then paste in this prompt.
I want to refine powder diffraction data with rietx (https://rietx.org). My data and any structure files (CIFs) are in this folder.
- Create a Python virtual environment here with Python 3.11 or newer. Install rietx into it:
pip install rietxInstall the latest development version of rietx into it:pip install git+https://github.com/yue-here/rietx - Install the rietx agent skill with
rietx skill --install. Then read.agents/skills/rietx/SKILL.md. - Look at the files in this folder and tell me what they are. Propose a refinement plan before you run it.
Hands-on rietx tutorials. Run them live in your browser with JupyterLite, or on Colab.
- Quickstart: look at a pattern, then fit it with Le BailReadJupyterLiteColabDownload
- A simple Rietveld refinementReadJupyterLiteColabDownload
- Peaks, indexing and a Le Bail checkReadJupyterLiteColabDownload
- Peak shape and microstructureReadJupyterLiteColabDownload
- Sequential fitsReadJupyterLiteColabDownload
- A Rietveld refinement on your own dataReadJupyterLiteColabDownload
Out-of-the-box agentic refinement
We gave a coding agent (Sonnet 5 in Claude Code) a low-signal, multi-phase dataset and some reference structures, then asked it to perform a sequential refinement with quantitative phase analysis. No further setup required. Get started here.
The dataset is 275 in situ XRD patterns from a supported Cu/CuO redox experiment collected on a lab diffractometer with ~30 s acquisitions. The measurements were made at up to 300 °C under changing chemical environments using a bespoke gas cell. Contributed by Michael W. Gaultois. Work performed with Jamie Capel, Martin C. Chan, Stuart Scott, Felix Donat, and Prof. Dame Clare Grey at the Department of Chemistry, University of Cambridge. Visualisation constructed by Claude.
Simple and flexible Python API
A straightforward Python interface for scripting or Jupyter notebooks. Get started here.
import rietx as rx data = rx.read_pattern("FAP.XRA") # GSAS raw format structure = rx.Structure.from_cif("fluorapatite.cif") instrument = rx.Instrument.bragg_brentano(radiation="CuKa") instrument.geometry.axial_sl.value = 0.02 # axial divergence instrument.geometry.axial_hl.value = 0.02 instrument.background = rx.BackgroundChebyshev.with_terms(6) ref = rx.Refinement(structure, instrument) result = ref.fit(data, plan="mccusker_structural", two_theta_limits=(15, 130)) print(f"{result.status} Rwp={result.statistics.rwp:.4f} " f"GoF={result.statistics.gof:.2f}") for name in ("a", "c"): p = result.parameter(f"phases.0.cell.{name}") print(f" {name} = {p.value:.5f} +/- {p.stderr:.5f} A") for d in result.diagnostics: print(f" [{d.level}] {d.code}: {d.message}")
converged Rwp=0.0893 GoF=1.60 a = 9.37228 +/- 0.00008 A c = 6.88626 +/- 0.00008 A [warning] SITE_SNAPPED_TO_SPECIAL_POSITION: 1 site(s) in phase 'fluorapatite' sit within 0.0001 of a special position of 'P 63/m' without being on it, and were expanded at it: Ca1 (3.3e-11 → multiplicity 4) … [warning] RESOLUTION_UNCONSTRAINED: U, V, W refined on a predominantly Lorentzian pattern (Γ_L exceeds Γ_G at 4786 of 5751 fitted points; the Gaussian carries 41% of the width) … [warning] PATTERN_UNDERSAMPLED: 4.6 steps across the FWHM (median over 76 fitted peaks) — below the 5 the guidelines ask for
result.plot().The GUI
rietx ships with a comprehensive GUI for interactive refinement. There are several quality-of-life features not found in other Rietveld interfaces, including pre-rolled automatic refinement plans that sequentially release parameters, and the refinement history panel shown below: a git-style tree of refinement checkpoints can be easily loaded and compared.
Features
- Rietveld, Le Bail and PawleyMulti-phase, X-ray and constant-wavelength neutron. Concepts
- Magnetic structuresMoments refined on constant-wavelength neutron data, read and written as magCIF. In progress. Magnetic
- Reads common file formats.xy/.xye, GSAS, pdCIF, .chi, Rigaku .ras/.rasx, Bruker .uxd/.brml/.raw, PANalytical .xrdml/.udf, Philips .rd/.sd. Files
- Speaks other languagesReads and writes TOPAS, FullProf, GSAS and PowderLine formats. (Rietica, XND, etc. in progress) Formats · PowderLine
- Phase quantificationWeight fractions with esds propagated through the full covariance, and a flag when a phase is not determined by the data. QPA
- SeriesDesigned from the ground up for robust sequential refinement. Series
- Joint refinementSeveral patterns in one fit with shared parameters, including X-ray and neutron together. Joint fits
- Reporting beyond RwpCommon refinement heuristics reported in words alongside numbers. This helps both humans and agents interpret refinement results. FitReport
- History treeEvery refinement stage is a restorable checkpoint. You can fork, compare, merge. History
- Live run viewerEvery fit records itself.
rietx watchshows a running fit in the browser and can stop it. Watching a run - Structure figuresDraw a structure to a PNG from Python, with polyhedra and any view direction. Figures
- IndexingRobust automatic peak picking and three available indexing engines. Indexing
- CorrectionsAxial divergence, displacement and transparency, absorption, preferred orientation, anisotropic displacement and strain, anomalous dispersion. Model
- Constraints and restraintsTies, holds, named variables, and restraints on bond lengths and angles. Constraints
- Solvers and backendsVery fast compiled kernel; trust-region and Levenberg–Marquardt on an analytic Jacobian; optional JAX and PyTorch backends for fully differentiable refinements. Estimation
- For agentsShips with an agent skill summarising refinement heuristics and
rietxfeatures. Works with most coding agents.rietx skill --install. Quickstart · Agents
Validation
rietx is continuously tested on real data, referenced to something outside the package: a certificate, a weighed mixture, or another code's converged fit under the same protocol. The full, automatically updated test matrix is here.
| Data | What is checked | Result | Referenced to |
|---|---|---|---|
| NIST SRM 660c LaB₆, lab Cu Kα (the certification measurement) | Lattice parameter | a = 4.156882(21) Å +25 ppm | NIST certificate, cell recomputed for the measurement's 20.85 °C: 4.156780 Å |
| NIST SRM 676a corundum, lab Cu Kα | Axial ratio c/a | +30 ppm | NIST certificate: a = 4.759355(80), c = 12.99231(15) Å (k = 2) |
| IUCr CPD QPA round robin, sample 1: eight corundum, zincite and fluorite mixtures | Weight fractions | worst error 1.20 wt % | The weighed compositions. The participants' spread was 6 wt % on major phases (Madsen et al. 2001) |
| Fluorapatite, GSAS-II tutorial data, lab Cu Kα | Cross-code, same protocol | Rwp 0.0925 vs 0.1005 cell +83 / +82 ppm | GSAS's converged fit of the same file (FAP.EXP); the uniform cell offset is a d-scale convention |
| APS 11-BM, SRM 660b LaB₆ with cubic BN | Two-phase QPA | LaB₆ 17.791 ± 0.319 wt % | TOPAS: 17.907 and 17.950 wt % from its two models of the pattern (no weighed composition exists) |
| NIST SRM 676a corundum, peak list only | Indexing | correct cell first a +110, c +57 ppm | The certificate cell; 45 of 47 lines indexed, graded low on its own caveats rather than accepted |
Test-data provenance and licences: tests/data/README.md.