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

pip install rietx            # Python >= 3.11; numpy/scipy core, compiled kernels on
pip install "rietx[viz]"     # + matplotlib and plotly rendering

Example refinement

Condensed from examples/nac_11bm.py, which fits APS 11-BM synchrotron data on Na₂Ca₃Al₂F₁₄ with a CaF₂ impurity.

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 …):

Le Bail:  status=converged  Rwp=0.1457  GoF=5.52  a=10.251214 A
Rietveld: status=converged  Rwp=0.0932  GoF=3.53
          a = 10.251216 +/- 0.000046 A (COD reference 10.257(1); high-accuracy powder ~10.2497-10.2506)
          [warning] BOUND_HIT: phases.1.atoms.0.biso refined to its bound

FitReport: Rwp=0.0932 GoF=3.53; 52 regions, top 15 shown (74% of χ²); 54 unmatched observed peak(s); …
  region  14.22- 14.54 deg  localRwp=0.154  chi2share=13.6%  max|d/sig|=49.5
  …

Refinement history (every stage is a restorable checkpoint):
t5544a638  13 nodes  data=11BM_NAC.fxye
 n0000  root                   —
└─  n0001  stage:bkg              Rwp 3.1725
   …
                                 └─ *n0012  stage:biso             Rwp 0.0932

Current features

• Multi-phase Rietveld, Le Bail and Pawley
• Preset staged plans
• Extensively documented forward model
• Multiple solvers
• Optional JAX & torch differentiable backends
• Readers for many standard formats including .xy/.xye, GSAS raw, pdCIF, .chi, Rigaku .ras/.rasx, Bruker .uxd/.brml/.raw and PANalytical .xrdml
• The FitReport, an output bundle designed for agentic consumption.
• A git-style branchable refinement history
• Sequential refinements
• Indexing
• Extensive agentic surface
• GUI mode rietx gui (currently in beta)

Validation

Validation suites are run in CI against real data. Details here: docs/VALIDATION.md

Documentation

• HTML manual: https://rietx.org/
• Driving instructions for agents: AGENT_PROTOCOL.md

Development

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, and 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. and test-data provenance is listed in tests/data/README.md. CIF and symmetry handling uses gemmi. To cite the package, use CITATION.cff.