Rietveld refinement for humans and machines

rietx is an open-source Python package for analysing powder diffraction data. It is designed with a streamlined API that can be easily used by most common AI coding agents out of the box.

$pip install rietx Read the manual GitHub

Agentic refinement with standard models

The dataset is 275 in situ XRD patterns from supported Cu/CuO redox collected on a lab diffractometer with sub-minute acquisition times. The measurements were made at up to 300 °C under changing chemical environments using a bespoke gas cell. A coding agent (Claude Sonnet 5 running in Claude Code) was given the patterns and the reference structures and asked to refine the series.

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

Contributed by Michael W. Gaultois. Work performed with Jamie Capel, Martin C. Chan, Stuart Scott, Felix Donat, and Prof. Clare Grey at the Department of Chemistry, University of Cambridge.

An example refinement

Fluorapatite from the GSAS-II tutorial data: a lab Cu Kα pattern with seven atomic sites.

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 — Figure generated by `result.plot()`. GSAS's own converged refinement of this file gives Rwp 0.1005 and a = 9.371724(36) Å; the 60 ppm difference arises from 1.5405 Å used in the tutorial's instrument file against the 1.5405929 Å used in the `rietx` `CuKa` preset (Hölzer et al. 1997).

Figure generated by `result.plot()`. GSAS's own converged refinement of this file gives Rwp 0.1005 and a = 9.371724(36) Å; the 60 ppm difference arises from 1.5405 Å used in the tutorial's instrument file against the 1.5405929 Å used in the `rietx` `CuKa` preset (Hölzer et al. 1997).

The GUI

rietx gui runs the rietx GUI in the browser. The history panel is shown here: a git-like 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 — The screenshot is of version 1.3.0. GUI quickstart · the refinement history

The screenshot is of version 1.3.0. GUI quickstart · the refinement history

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 a TOPAS .inp or a FullProf .pcr by content, refine flags included, and writes a PowderLine recipe back. (In progress) Model files · Recipe
Phase quantificationWeight fractions with esds propagated through the full covariance, and a flag when a phase is not determined by the data. QPA
SeriesSequential refinement with warm start, run in both directions to catch a trajectory that depends on the order. Series
A report, not just RwpWhere the misfit is, which parameters the fit cannot separate, and what to try next. FitReport
A branchable historyEvery stage is a restorable checkpoint; fork, compare, merge. History
IndexingThree engines, a ranked list with its caveats, never one confident cell. Indexing
Peaks on their ownFit exactly the peaks you name with no structure at all, or declare an intruder — a holder line, an unidentified impurity — and keep the channels under it in the fit. Peaks · Components
CorrectionsAxial divergence, displacement and transparency, absorption, preferred orientation, anisotropic displacement and strain, anomalous dispersion on by default. Model
Solvers and backendsVery fast compiled kernel; trust-region and Levenberg–Marquardt on an analytic Jacobian; optional JAX and torch backends. Estimation
For agentsShips with an agent skill summarising refinement heuristics and rietx features. Works with most coding agents. rietx skill --install. Agents

Validation

These tests run in CI 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 matrix, with every tolerance and its reason, is docs/VALIDATION.md.

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.