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.

$pip install rietx Read the manual GitHub

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.

CuO reduction and reoxidation, in situ · Refined with Claude Code (model to confirm)

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.

fap_lab.py

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}")

report = rx.build_report(result)
print(report.summary)
result.plot(path="fap_fit.png")

output

converged  Rwp=0.0893  GoF=1.60
  a = 9.37228 +/- 0.00010 A
  c = 6.88626 +/- 0.00009 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] PATTERN_UNDERSAMPLED: 4.7 steps across the FWHM
    (median over 175 fitted peaks) — below the 5 the
    guidelines ask for
Rwp=0.0893 GoF=1.60; 63 regions, top 15 shown (47% of χ²);
  4 unmatched observed peak(s); remaining 48 regions carry
  30% of χ²; fitted instrument.zero_shift = -0.0365505
  stands 67σ from 0 but is exchangeable with the held
  instrument.geometry.sample_displacement …

Observed, calculated and difference curves for the fluorapatite refinement, 15 to 130 degrees two-theta, with the reflection tick row — Data is fluorapatite from the GSAS-II tutorial: a lab Cu Kα pattern with seven atomic sites. Figure generated by `result.plot()`.

Data is fluorapatite from the GSAS-II tutorial: a lab Cu Kα pattern with seven atomic sites. Figure generated by `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.

The rietx GUI with the fluorapatite fit on the left and the history panel on the right, reading 24 nodes in 3 lanes

Features

Rietveld, Le Bail and PawleyMulti-phase, X-ray and constant-wavelength neutron. Concepts
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 languagesOpens TOPAS, FullProf and PowderLine formats. (GSAS, 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
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
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
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 rietx features. Works with most coding agents. rietx skill --install. 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.156895(25) Å +28 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.39 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.0973 vs 0.1005 cell +116 / +113 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.84 ± 0.34 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 +122, c +28 ppm	The certificate cell; 51 of 55 lines indexed, graded low on its own caveats rather than accepted

Test-data provenance and licences: tests/data/README.md.