Installation

pip install rietx

Requirements

Python 3.11 or newer, and five packages: numpy, scipy, pydantic, gemmi and spglib.

That core install is a complete refinement package. It reads patterns and CIFs, applies every correction, runs the whole staged refinement machinery, builds the report, indexes an unknown cell, and keeps projects and history. Nothing in that list is optional or lazily imported.

Optional extras

No extra makes a refinement more accurate. Each one adds a rendering (plots, HTML, the GUI), a second opinion on the Jacobian (the differentiable backends), or the development toolchain.

Install an extra by naming it in brackets. Quote the argument, because zsh reads bare brackets as a glob:

pip install "rietx[viz]"           # one extra
pip install "rietx[viz,jax]"       # several, comma-separated, no spaces
uv pip install -e ".[dev]"         # from a source checkout

Extra	Installs	What it buys
viz	matplotlib, plotly	Plots. RefinementResult.plot and the report figures need matplotlib; viz.html.write_html writes the interactive plotly page.
gui	plotly	The refinement GUI, rietx gui. Plotly only: the built frontend is committed inside the package, so this extra never needs node.
jax	jax	The backend="jax" Jacobian (jacfwd, chunked).
torch	torch	Experimental. backend="torch" (CPU fp64) and backend="torch-mps" (Apple GPU, necessarily fp32). About 500 MB, and slower than numpy on this hardware. It buys an independent opinion in the Jacobian-agreement matrix, and the forward model as a differentiable layer. It does not buy speed.
docs	sphinx, myst-parser, sphinxcontrib-bibtex, furo	Builds this manual.
dev	the docs extra, pytest, pytest-xdist, hypothesis, matplotlib, plotly, ruff	The test suite.

That is the whole list. Background estimation needs nothing installed: arPLS, SNIP and the penalised spline are implemented in the core, the spline as penalty rows inside the least squares rather than as a pre-subtraction. See auto_background.

Use the numpy backend. backend="numpy" is the default and the only backend a refinement needs. The others exist to hold the analytic Jacobian to an independent account. An Apple-GPU refinement runs 46 to 182 times slower than numpy, because the work is launch-latency-bound.

Precision is not the trade. A GPU backend may compute Jacobian columns in fp32, but the residual used for the cost and the statistics, and the solve itself, stay fp64 on the host.

Checking an install

Ask the package rather than a table that goes stale. capabilities() reports the versions, the backends, the plans, the modes, the anodes, the pattern formats it can open, and the feature flags. For each backend it reports whether the optional dependency imports here:

from rietx import capabilities

caps = capabilities()
caps.package_version
[backend.name for backend in caps.backends if backend.available]
[fmt.name for fmt in caps.reader_formats]

Capabilities.backends is the field that answers “did my jax extra take?”. Each BackendCapability carries BackendCapability.available (does it import here), BackendCapability.requires (the distribution to install) and BackendCapability.experimental. Calling rietx from a program covers the rest of the object.

Installing from source

git clone https://github.com/yue-here/rietx
cd rietx
uv venv --python 3.12 && uv pip install -e ".[dev]"

Then run the suite. The fast selection is the unit and property tests. The full selection adds the real-data acceptance suites, which refine certified standards and take tens of minutes:

.venv/bin/python -m pytest -n auto --dist loadgroup -m "not slow"   # fast
.venv/bin/python -m pytest -n auto --dist loadgroup                 # everything

--dist loadgroup is not optional. It honours the marks that keep a shared refinement fixture on one worker; plain --dist load silently refits. The suite prints its own counts, and those counts depend on the extras installed: jax and torch turn skips into passes.

Validation and accuracy claims

docs/VALIDATION.md tabulates every real-data assertion in the repository and says what each tolerance is referenced to. It is generated from the suite, so it is the accuracy claim, and nothing in this manual restates it.

Read it with its own opening rule in mind: judge a correction by what it changed, never by ΔRwp. Of the eight corrections in v0.5, two provably cannot move Rwp, one moves it the wrong way when it is right, and the two largest accuracy wins are invisible in it.