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, matplotlib figures

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.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 data
• Magnetic refinement (in progress)
• Joint refinement of several patterns
• Preset staged plans
• Extensively documented forward model
• Corrections: axial divergence, displacement and transparency, absorption, preferred orientation, anisotropic displacement and strain, anomalous dispersion
• Constraints and restraints
• Quantitative phase analysis
• 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, PANalytical .xrdml/.udf and Philips .rd/.sd
• Another program's refinement, read in: read_project_model opens a TOPAS .inp or a FullProf .pcr by content, refine flags included
• Writers for TOPAS, FullProf, GSAS and GSAS-II files
• The FitReport, an output bundle designed for agentic consumption.
• A git-style branchable refinement history
• Sequential refinements
• Indexing, and peaks fitted on their own at positions you name, with no structure at all
• Declared extra peaks and humps: 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
• PowderLine recipe interchange: read a pipeline's recipe, write its four tables back
• GUI mode rietx gui
• Live run viewer rietx watch
• Settings comparison rietx compare
• Structure figures rx.viz.render_structure
• Jupyter display and tutorial notebooks

Validation

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

Documentation

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

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.