API: everyday calls#

This page lists the calls a refinement session makes, with each signature, its fields and the first line of its docstring.

Everything is reached as rx. after import rietx as rx. help(obj) prints a call’s full docstring. Calls for one technique, such as magnetic refinement or another program’s files, are on API: techniques, and every other exported name is on API: everything else.

Reading data#

rx.read_pattern(

path: str | Path,

*,

diagnostics: list[Diagnostic] | None = None,

**options: Any,

) → PatternData#: Read any supported pattern file, dispatching on content first.

rx.read_pdcif( path: str | Path, *, block: str | None = None, diagnostics: list[Diagnostic] | None = None, ) → PatternData#: Read a powder pattern from a pdCIF file.

classmethod Structure.from_cif( path: str | os.PathLike[str], *, phase_name: str | None = None, aniso: bool = False, moment_ions: dict[str, str] | None = None, moment_g: dict[str, float] | None = None, nuclear_group: 'auto' | 'parent' | 'file' = 'auto', diagnostics: list | None = None, ) → Structure#: Read a CIF, or a magCIF, into a Structure.

classmethod Instrument.bragg_brentano( *, radiation: str = 'CuKa', goniometer_radius_mm: float = 217.5, monochromator_two_theta: float | None = None, ka2_ratio: float = 0.5, mu_t: float | None = None, thickness_mm: float | None = None, ) → Instrument#: Lab flat-plate diffractometer preset with a Kα1/Kα2 doublet.

classmethod Instrument.debye_scherrer( wavelength: float, *, polarization: float = 0.99, goniometer_radius_mm: float | None = None, capillary_radius_mm: float | None = None, packing_fraction: float = 0.6, mu_r: float | None = None, ) → Instrument#: Synchrotron/capillary preset with a single wavelength.

rx.estimate_mu_r( structure: Structure, instrument: Instrument, ) → float | None#: Starting µR for a packed capillary, from composition and geometry.

rx.auto_background( data: PatternData, *, kind: str = 'pspline', diagnostics: PatternDiagnostics | None = None, wavelength: float | None = None, two_theta_limits: tuple[float, float] | None = None, source: object | None = None, seed: bool = False, ) → BackgroundChoice#: Background sized to the data, with the scores it was sized on.

rx.diagnose( data: PatternData, *, wavelength: float | None = None, baseline_lambda: float | None = None, source: object | None = None, ) → PatternDiagnostics#: PatternDiagnostics of a raw pattern.

rx.load_instrument_profile( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → Instrument#: Read a profile file back as a frozen instrument.

rx.save_instrument_profile(instrument: Instrument, path: str | Path)#: Write the instrument’s calibrated state to a JSON profile file.

rx.capabilities() → Capabilities#: Everything this build can do.

rx.help_for(path: str) → HelpEntry | None#: The entry for a parameter dot-path, or None if no family claims it.

Model objects#

class rx.Parameter#

A single refinable scalar.

value: float#
vary: bool = False#
min: float = -inf#
max: float = inf#
expr: str | None = None#
unit: str | None = None#
stderr: float | None = None#

class rx.Structure#

The phases refined against one pattern.

phases: list[Phase]#

class rx.Phase#

A crystalline phase: symmetry, cell, atoms, scale, sample broadening.

name: str#
space_group: str#
symmetry_operations: list[str] | None = None#
cell: Cell#
atoms: list[Atom]#
scale: Parameter = Parameter(1.0, min=0.0)#
extinction: Parameter = Parameter(0.0, min=0.0)#
preferred_orientation: PreferredOrientation | None = None#
texture: SphericalHarmonicTexture | None = None#
lor_size: Parameter = Parameter(0.0, min=0.0)#
lor_strain: Parameter = Parameter(0.0, min=0.0)#
magnetic_lor_size: Parameter = Parameter(0.0, min=0.0)#
magnetic_lor_strain: Parameter = Parameter(0.0, min=0.0)#
gauss_size: Parameter = Parameter(0.0, min=0.0)#
gauss_strain: Parameter = Parameter(0.0, min=0.0)#
microstrain: StephensStrain | None = None#
particle_radius_um: float | None = None#
propagation_vector: tuple[str, str, str] | None = None#
magnetic_symmetry: MagneticSymmetry | None = None#
restraints: list[BondRestraint | AngleRestraint | ValueRestraint] = []#
floating_origin: 'hold' | 'centroid' | None = None#

class rx.Atom#

One site in the asymmetric unit.

label: str#
species: str#
x: Parameter#
y: Parameter#
z: Parameter#
occ: Parameter = Parameter(1.0, min=0.0)#
biso: Parameter = Parameter(0.5)#
aniso: AnisoU | None = None#
moment: Moment | None = None#
disorder_assembly: str | None = None#
disorder_group: str | None = None#

class rx.Cell#

The lattice parameters: three lengths (Å) and three angles (degrees).

a: Parameter#
b: Parameter#
c: Parameter#
alpha: Parameter#
beta: Parameter#
gamma: Parameter#

class rx.AnisoU#

Anisotropic displacement tensor in the CIF U^ij convention (Å²).

u11: Parameter#
u22: Parameter#
u33: Parameter#
u12: Parameter = Parameter(0.0)#
u13: Parameter = Parameter(0.0)#
u23: Parameter = Parameter(0.0)#

class rx.PreferredOrientation#

Single-axis March-Dollase preferred-orientation correction (Dollase 1986).

axis: tuple[int, int, int]#
r: Parameter = Parameter(1.0, min=1e-06)#

class rx.StephensStrain#

Anisotropic strain broadening coefficients S_HKL (Stephens, 1999).

s400: Parameter = Parameter(0.0)#
s310: Parameter = Parameter(0.0)#
s301: Parameter = Parameter(0.0)#
s220: Parameter = Parameter(0.0)#
s211: Parameter = Parameter(0.0)#
s202: Parameter = Parameter(0.0)#
s130: Parameter = Parameter(0.0)#
s121: Parameter = Parameter(0.0)#
s112: Parameter = Parameter(0.0)#
s103: Parameter = Parameter(0.0)#
s040: Parameter = Parameter(0.0)#
s031: Parameter = Parameter(0.0)#
s022: Parameter = Parameter(0.0)#
s013: Parameter = Parameter(0.0)#
s004: Parameter = Parameter(0.0)#

class rx.Instrument#

Everything about the measurement except the sample.

source: Source | NeutronSource | TOFSource#
geometry: Geometry = Geometry(…)#
zero_shift: Parameter = Parameter(0.0)#
profile: ProfileTCHZ = ProfileTCHZ(…)#
background: BackgroundChebyshev | BackgroundFixedPlusChebyshev | BackgroundPSpline = BackgroundChebyshev(…)#
extra_components: list[HumpComponent | PeakComponent] = []#

class rx.Source#

Constant-wavelength X-ray source.

kind: 'xray_cw' = 'xray_cw'#
lines: list[EmissionLine]#
polarization: Parameter = Parameter(0.5, min=0.0, max=1.0)#
kbeta: 'filter' | 'monochromator' | 'mirror' | None = None#
dispersion: Dispersion | None = Dispersion(…)#
harmonics: list[Harmonic] = []#

class rx.NeutronSource#

Constant-wavelength neutron source: one wavelength, nuclear scattering.

kind: 'neutron_cw' = 'neutron_cw'#
wavelength: Parameter#
harmonics: list[Harmonic] = []#

class rx.Geometry#

Diffraction geometry.

kind: 'debye_scherrer' | 'bragg_brentano' | 'flat_plate_transmission' = 'debye_scherrer'#
goniometer_radius_mm: float | None = None#
surface_roughness: RoughnessSuortti | RoughnessPitschke | None = None#
sample_displacement: Parameter = Parameter(0.0)#
sample_transparency: Parameter = Parameter(0.0, min=0.0)#
capillary_offset_along_beam: Parameter = Parameter(0.0)#
capillary_offset_across_beam: Parameter = Parameter(0.0)#
axial_sl: Parameter = Parameter(0.0, min=0.0)#
axial_hl: Parameter = Parameter(0.0, min=0.0)#
mu_r: float | None = None#
capillary_radius_mm: float | None = None#
mu_t: float | None = None#
thickness_mm: float | None = None#
packing_fraction: float = 0.6#

class rx.ProfileTCHZ#

Thompson-Cox-Hastings pseudo-Voigt width parameters.

shape: 'tchz_pv' | 'voigt' = 'tchz_pv'#
u: Parameter = Parameter(0.0, min=-32400.0, max=32400.0)#
v: Parameter = Parameter(0.0, min=-32400.0, max=32400.0)#
w: Parameter = Parameter(0.001, min=1e-08, max=32400.0)#
x: Parameter = Parameter(0.001, min=0.0, max=180.0)#
y: Parameter = Parameter(0.0, min=-180.0, max=180.0)#

class rx.BackgroundChebyshev#

Shifted-Chebyshev background, linear in its coefficients.

kind: 'chebyshev' = 'chebyshev'#
coefficients: list[Parameter] = [Parameter(0.0) × 4]#

class rx.BackgroundPSpline#

Penalised cubic P-spline background, co-refined with the structure.

kind: 'pspline' = 'pspline'#
breakpoints: list[float]#
coefficients: list[Parameter]#
lambda_smooth: float = 1.0#
lambda_units: 'dimensionless' | 'intensity' = 'dimensionless'#
air_scatter: Parameter | None = None#

class rx.BackgroundFixedPlusChebyshev#

A fixed curve held in the model, a small refinable Chebyshev correction on top, and a scale on the curve itself.

kind: 'fixed_plus_chebyshev' = 'fixed_plus_chebyshev'#
fixed_two_theta: list[float]#
fixed_intensity: list[float]#
fixed_sigma: list[float] | None = None#
fixed_source: str | None = None#
scale: Parameter = Parameter(1.0, min=0.0)#
chebyshev: BackgroundChebyshev = BackgroundChebyshev(…)#

class rx.Dispersion#

Anomalous scattering corrections f′, f″ at the source wavelengths.

table: 'cromer_liberman' = 'cromer_liberman'#
overrides: dict[str, tuple[float, float]] = {}#

class rx.PatternData#

A powder pattern.

two_theta: list[float] | None = None#
tof: list[float] | None = None#
intensity: list[float]#
sigma: list[float] | None = None#
excluded_regions: list[tuple[float, float]] = []#
metadata: dict[str, str] = {}#

Refinement#

class rx.Refinement( structure: Structure, instrument: Instrument, *, backend: str = 'numpy', solver: str = 'lm', history: bool | str | Path | RefinementTree = True, )#: Refine structure + instrument against a powder pattern.

Refinement.fit( data: PatternData, *, mode: Mode = 'rietveld', plan: RefinementPlan | str = 'mccusker_default', two_theta_limits: tuple[float, float] | None = None, events=None, cancel=None, telemetry=None, label: str | None = None, stage_reports: bool = False, progress=None, ) → RefinementResult#: Run a staged refinement.

Refinement.report(*, plan: RefinementPlan | str | None = None, **kw)#: The full rietx.report.FitReport for the last fit.

Refinement.summary( *, deliverable: str | None = None, plot: str | None = None, plan: RefinementPlan | str | None = None, report: FitReport | None = None, levels: dict[str, str] | None = None, ) → str#: The termination view (WP-1302): “done, or not, and why” from one call.

Refinement.suggest( data: PatternData, *, top_n: int = 5, include: str | list[str] = '*', exclude: list[str] | tuple[str, ...] = (), mode: Mode | None = None, two_theta_limits: tuple[float, float] | None = None, report=None, ) → SuggestionResult#: Which held parameter should be freed next?

Refinement.predict(two_theta=None) → np.ndarray#: Evaluate y_calc at the current parameters, without a fit.

Refinement.run_stage( data: PatternData, stage: Stage, *, mode: Mode | None = None, two_theta_limits: tuple[float, float] | None = None, correlation_guard: float = 0.98, phase_support_sigma: float | None = 3.0, window_area_tol: float | None = None, events=None, cancel=None, telemetry=None, label: str | None = None, ) → RefinementResult#: Run a single stage from the current state, recording a child node.

Refinement.parameters(*, mode: Mode | None = None) → list[ParameterRow]#: Every parameter as data, with fixed, locked and tied rows included.

Refinement.set_vary( path_globs: list[str] | str, vary: bool = True, ) → list[str]#: Free (or hold) every parameter matching path_globs.

Refinement.set_values(values: dict[str, float])#: Set parameter values by dot-path, recording a set_value node.

Refinement.tie( path: str, source: str | dict[str, float] | Sequence[tuple[str, float]], *, scale: float = 1.0, offset: float = 0.0, ) → str#: Constrain path to scale·source + offset, recording a node.

Refinement.tie_equal( paths: list[str] | str, *, source: str | None = None, ) → list[str]#: Make every parameter matching paths one parameter.

Refinement.untie(paths: list[str] | str) → list[str]#: Release user ties, recording a set_tie node.

Refinement.add_variable( name: str, value: float, *, vary: bool = False, min: float = -inf, max: float = inf, unit: str | None = None, ) → str#: Declare a named variable other parameters can follow.

Refinement.remove_variable(name: str) → str#: Delete a named variable, refusing while anything follows it.

Refinement.hold(path_globs: list[str] | str) → list[str]#: Declare that these parameters do not move, whatever a plan asks.

Refinement.unhold(path_globs: list[str] | str) → list[str]#: Take back a hold.

Refinement.edit( *, structure: Structure | None = None, instrument: Instrument | None = None, label: str = '', ) → str | None#: Record a change to the model itself, such as adding an impurity phase, raising the background order or swapping the geometry.

rx.refine( data: PatternData, structure: Structure, instrument: Instrument, *, mode: Mode = 'rietveld', plan: RefinementPlan | str = 'mccusker_default', two_theta_limits: tuple[float, float] | None = None, backend: str = 'numpy', solver: str = 'lm', history: bool | str | Path | RefinementTree = False, events=None, cancel=None, telemetry=None, label: str | None = None, ) → RefinementResult#: One-shot functional API: refine(data, structure, instrument).

class rx.RefinementPlan#

stages: list[Stage]#
correlation_guard: float = 0.98#
intermediate_ftol: float | None = 1e-06#
lebail_passes: int = 1#
phase_support_sigma: float | None = 3.0#
closing_window_tol: float | None = 0.001#

class rx.Stage#

One turn-on group of a staged plan.

name: str#
turn_on: list[str]#
max_iter: int = 100#
ftol: float | None = None#
lebail_cycles: int = 3#
seed: float = 0.0#
strain_seed: float = 0.0#
restraint_weight_scale: float = 1.0#
window_slack_deg: float | None = None#

rx.PLAN_INFO#: A dict. Keys: mccusker_default, mccusker_structural, lab_bragg_brentano, lab_calibrate, lab_sample_refine, profile_only, pawley_default, magnetic_width.

class rx.ParameterRow#

One row of the parameter table, mirroring params.vector.Entry.

path: str#
value: float#
vary: bool = False#
lo: float = -inf#
hi: float = inf#
tie: TieSpec | None = None#
locked: bool = False#
held: bool = False#
esd: float | None = None#
mode_fixed: bool = False#
needs_held_cell: bool = False#
origin_axis: tuple[int, int, int] | None = None#
help_key: str | None = None#

Results#

class rx.RefinementResult#

What a fit returns: the answer, its statistics, and what the engine found wrong with it.

status: 'converged' | 'max_iter' | 'diverged'#
mode: 'rietveld' | 'lebail' | 'pawley'#
parameters: list[RefinedParameter]#
statistics: Statistics#
stages: list[StageResult] = []#
diagnostics: list[Diagnostic] = []#
provenance: Provenance#
node_id: str | None = None#
tree_id: str | None = None#
two_theta: list[float] = []#
y_obs: list[float] = []#
y_calc: list[float] = []#
y_background: list[float] = []#
sigma: list[float] = []#
ticks: dict[str, list[float]] = {}#
tick_hkl: dict[str, list[list[int]]] = {}#
qpa: QuantitativePhaseAnalysis | None = None#
phase_agreement: list[PhaseAgreement] = []#
texture: list[PhaseTexture] = []#
data_support: DataSupport | None = None#
absorption: AbsorptionCorrection | None = None#
restraints: RestraintReport | None = None#
geometry: GeometryTable | None = None#
cell_volumes: list[CellVolume] | None = None#
microstructure: list[PhaseMicrostructure] = []#
identifiability: Identifiability | None = None#
parametric: list[ParametricCoefficient] | None = None#
parametric_form: list[ParametricFormTest] | None = None#
parametric_form_joint: ParametricFormReading | None = None#
parametric_equations: list[RefinedParametricEquation] | None = None#
n_extra_components: int | None = None#
n_background_components: int | None = None#
histograms: list[HistogramResult] = []#

class rx.StageResult#

One stage’s outcome.

name: str#
status: 'converged' | 'max_iter' | 'diverged'#
n_iterations: int#
cost_initial: float#
cost_final: float#
freed: list[str] = []#
ftol: float | None = None#
window_area_tol: float | None = None#
n_constraint_truncations: int = 0#
n_degenerate_cell_probes: int = 0#
n_lapack_fallbacks: int = 0#
held: list[str] = []#
held_reach: dict[str, list[str]] = {}#
scale_b_held: dict[int, float] | None = None#
width_twins_held: dict[str, list[str]] | None = None#
released: list[str] = []#
moment_flat_axes: dict[str, list[float]] = {}#
moment_turned: list[str] = []#
blocked_by_hold: list[str] = []#
unknown_paths: list[str] | None = None#
unreached_histograms: dict[int, list[str]] | None = None#
seeded: dict[str, float] | None = None#
moment_angle_tests: list[MomentAngleTest] | None = None#
cell_reset: list[str] | None = None#
collapsed: list[str] | None = None#

class rx.Statistics#

Agreement indices, defined per Toby (2006), Powder Diffraction 21, 67.

rwp: float#
rp: float#
rexp: float#
chi2: float#
gof: float#
rwp_background_subtracted: float | None = None#
durbin_watson: float | None = None#
esd_inflation: float | None = None#
n_points: int#
n_free_parameters: int#
max_shift_over_esd: float | None = None#
identifiability_clause: str | None = None#

class rx.RefinedParameter#

One row of RefinementResult.parameters.

path: str#
value: float#
stderr: float | None = None#
stderr_uncorrected: float | None = None#
vary: bool = True#
at_bound: bool | None = None#
equations: list[str] | None = None#
interval: ParameterInterval | None = None#

class rx.Diagnostic#

A structured, actionable message produced by the engine.

level: 'info' | 'warning' | 'error'#
code: str#
message: str#
where: list[str] = []#
suggestion: str | None = None#
value: float | None = None#

class rx.SeriesResult#

The result of a sequential refinement over an ordered set of patterns.

mode: 'rietveld' | 'lebail' | 'pawley' = 'rietveld'#
entries: list[SeriesEntry] = []#
x_label: str = 'index'#
direction: 'forward' | 'backward' | 'both' = 'forward'#
backward: SeriesResult | None = None#
diagnostics: list[Diagnostic] = []#
discontinuities: list[SeriesStep] | None = None#
relative_paths: list[str] | None = None#
angle_paths: list[str] | None = None#
failures: list[SeriesFailure] = []#
n_failed: int = 0#
provenance: Provenance | None = None#

SeriesResult.trajectory(path: str) → Trajectory#: One parameter’s trajectory across the series.

SeriesResult.to_table( *, paths: list[str] | None = None, ) → tuple[list[str], list[list]]#: (header, rows): one row per pattern, a column per path (+ esd where that kind of path has one).

SeriesResult.write_csv( path, *, delimiter: str | None = None, paths: list[str] | None = None, )#: Write to_table to CSV/TSV (delimiter inferred from suffix).

SeriesResult.summary( *, max_entries: int = 5, deliverable: str | None = None, parametric: RefinementResult | None = None, levels: dict[str, str] | None = None, ) → str#: The series termination view (WP-1302): the trajectory table, the SEQUENTIAL_* rows, first and last max_entries with the count.

class rx.SeriesEntry#

One pattern’s place in the series: what was fitted and how it went.

index: int#
label: str = ''#
x: float | None = None#
status: 'converged' | 'max_iter' | 'diverged' = 'converged'#
statistics: Statistics | None = None#
parameters: list[RefinedParameter] = []#
qpa: QuantitativePhaseAnalysis | None = None#
phase_agreement: list[PhaseAgreement] = []#
magnetic: list[MomentEvidence] = []#
diagnostics: list[Diagnostic] = []#
n_iterations: int = 0#
reseeded: bool = False#
rwp_warm: float | None = None#
rung: 'warm' | 'warm_staged' | 'cold' = 'warm'#
rungs_tried: list[str] = []#
rungs_raised: dict[str, str] = {}#
rwp_fence: float | None = None#
node_id: str | None = None#
tree_id: str | None = None#

class rx.IndexingResult#

What rietx.index_pattern returns: a list of candidates, with no .cell or .best.

candidates: list[CellCandidate] = []#
engines_run: list[str] = []#
systems_searched: list[str] = []#
search_complete: dict[str, bool] = {}#
engine_stats: dict[str, float] = {}#
fom_panel_disagrees: bool = False#
quality: DataQualityReport | None = None#
validated: bool = False#
wavelength: float = 0.0#
n_usable_lines: int = 0#
provenance: Provenance#
preset: str | None = None#
thresholds_version: str = '1.11'#
diagnostics: list[Diagnostic] = []#

IndexingResult.best_or_none() → CellCandidate | None#: The single candidate, or None.

IndexingResult.evidence() → IndexingEvidence#: The machine-readable evidence view (WP-1043).

class rx.SuggestionResult#

Ranked, gated answer to “which parameter should be freed next?”.

groups: list[CandidateGroup] = []#
non_separable: list[ParameterCandidate] = []#
skipped: list[str] = []#
n_evaluated: int = 0#
chi2_red: float#
noise_floor: float#
summary: str#
n_effective: float | None = None#

class rx.CandidateGroup#

One candidate, or a tie of candidates the data cannot split.

members: list[ParameterCandidate]#
gain: float#
resolved: bool#
delta_bic: float#
delta_bic_raw_n: float | None = None#

Fit report#

rx.build_report( result: RefinementResult, *, model=None, values=None, plan=None, free_paths: list[str] | None = None, structure=None, instrument=None, held: list[str] | None = None, top_n: int = 15, match_tol_deg: float = 0.08, min_peak_sigma: float = 5.0, ) → FitReport#: Build the report, going as deep as the inputs allow.

class rx.FitReport#

All three layers.

thresholds_version: str = '1.13'#
rwp: float#
gof: float#
cumulative_chi2_breakpoints: list[float] = []#
regions: list[Region] = []#
n_regions_total: int = 0#
unmatched: list[UnmatchedPeak] = []#
satellites: list[SatelliteEvidence] = []#
magnetic: list[MomentEvidence] = []#
lebail_gap: LeBailGap | None = None#
background: BackgroundEvidence | None = None#
identifiability: IdentifiabilityEvidence | None = None#
summary: str = ''#
attribution: list[RegionAttribution] = []#
trends: list[TrendAnalysis] = []#
texture: list[TextureAnalysis] = []#
strain: list[StrainAnalysis] = []#
restraints: RestraintReport | None = None#
geometry: GeometryTable | None = None#
microstructure: list[PhaseMicrostructure] = []#
layer1_available: bool = False#
abstained_reason: str | None = None#
abstained_kind: 'immature' | 'resolution_limited' | 'unreadable' | None = None#
suggested_actions: list[SuggestedAction] = []#

report.compare_rivals( refinement, data, finding: ExchangeFinding | tuple[str, str], ) → RivalComparison#: Fit each member of an exchangeable pair alone, the other at its null.

report.predict_then_verify( refinement, data, action: SuggestedAction, *, min_improvement: float = 0.01, ) → VerificationOutcome#: Try an action on a branch, keep it only if χ² actually improves.

report.compare_freed(restricted, full) → FreedComparison#: ΔBIC of the parameters full frees beyond restricted, each one’s t beside it.

class report.FreedComparison#

The effect of freeing parameters, as ΔBIC with each one’s t-ratio beside it.

freed: list[FreedParameter]#
n_added: int#
n_points: int#
chi2_restricted: float#
chi2_full: float#
esd_inflation: float | None = None#
n_effective: float#
delta_bic: float#
delta_bic_raw_n: float#

class report.FreedParameter#

One parameter the fuller fit frees and the restricted fit held.

path: str#
held_at: float | None = None#
value: float#
esd: float | None = None#
t_ratio: float | None = None#

Series, history, projects#

rx.refine_sequential(

patterns: Sequence[PatternData],

structure: Structure,

instrument: Instrument,

*,

carry: Sequence[str] = '*',

carry_hkl_intensities: bool = True,

backend: str = 'numpy',

solver: str = 'lm',

history: bool | str | Path = False,

**kw,

) → SeriesResult#: One-shot functional API for a warm-started series.

class rx.SequentialRefinement( structure: Structure, instrument: Instrument, *, backend: str = 'numpy', solver: str = 'lm', carry: Sequence[str] = '*', carry_hkl_intensities: bool = True, history: bool | str | Path = False, )#: Refine an ordered series of patterns, each warm-started from the last.

rx.refine_multi( data: list[PatternData], structure: Structure | list[Structure], instruments: list[Instrument], *, plan: RefinementPlan | str = 'mccusker_default', sharing: SharingMap | None = None, coordinates: CoordinateTable | None = None, parametric: list[ParametricEquation] | None = None, two_theta_limits=None, weights: list[float] | None = None, backend: str = 'numpy', solver: str = 'lm', events=None, cancel=None, telemetry=None, label: str | None = None, progress=None, ) → RefinementResult#: One-shot joint refinement of structure against several data/ instruments pairs.

class rx.MultiHistogramRefinement( structure: Structure | list[Structure], instruments: list[Instrument], *, sharing: SharingMap | None = None, coordinates: CoordinateTable | None = None, parametric: list[ParametricEquation] | None = None, backend: str = 'numpy', solver: str = 'lm', )#: Joint Rietveld refinement of a shared structure against several patterns.

MultiHistogramRefinement.report(

histogram: int,

*,

plan: RefinementPlan | str | None = None,

**kw,

)#: The rietx.report.FitReport for one histogram of the last fit.

Refinement.checkout(node_id: str) → Refinement#: Restore the state recorded at node_id (a node id or a tag).

Refinement.branch(node_id: str | None = None) → Refinement#: A second working tree over the same history, for a rival strategy.

Refinement.merge( other: str, *, prefer: str = 'theirs', label: str = '', ) → str#: Three-way merge of another branch into the current state.

Refinement.cherry_pick( node_id: str, data: PatternData, ) → RefinementResult#: Re-run another node’s stage action on top of the current state.

rx.replay( tree: RefinementTree, node_id: str, data: PatternData, ) → RefinementResult#: Recompute the curves and statistics of a recorded node.

class rx.Project( path: str | Path, doc: ProjectDoc, data: PatternData, refinement: Refinement, data_diagnostics: list[Diagnostic] | None = None, history_diagnostics: list[Diagnostic] | None = None, )#: A refinement session stored on disk, which you can open and save.

classmethod Project.create( path: str | Path, *, pattern: str | Path, structure: Structure | None = None, instrument: Instrument, mode: Mode = 'rietveld', plan: Any = None, two_theta_limits: tuple[float, float] | None = None, excluded_regions: list[tuple[float, float]] | None = None, reader_options: dict[str, Any] | None = None, ui: dict[str, Any] | None = None, backend: str = 'numpy', solver: str = 'lm', ) → Project#: Create a project directory around a pattern file and a model.

classmethod Project.open( path: str | Path, *, backend: str = 'numpy', solver: str = 'lm', ) → Project#: Open an existing project, resuming at the history head.

Project.save()#: Rewrite project.json.

class rx.CancelToken#: A thread-safe “stop asking for evaluations” flag.

Peaks and indexing#

rx.pick_peaks( data: PatternData, instrument: Instrument, *, two_theta_range: tuple[float, float] | None = None, shoulders: bool = True, flag_contamination: bool = True, ) → PeakList#: Every resolvable line in data, with a fitted position and its esd.

rx.fit_peaks( data: PatternData, instrument: Instrument, positions: np.ndarray | list[float], *, two_theta_range: tuple[float, float] | None = None, ) → PeakList#: Profile-fit the peaks at positions and nothing else, with no structure, space group or refinement.

rx.index_pattern( peaks: PeakList | None = None, *, data: PatternData | None = None, instrument: Instrument | None = None, spec=None, preset: str | None = None, engines: Sequence[str] | None = None, quality=None, shift_from_pairs: bool = True, validate: bool = True, check_top: int | None = None, two_theta_limits: tuple[float, float] | None = None, formula: str | None = None, temperature: float = 298.0, events=None, cancel=None, )#: Find the unit cell, or say in the shape of the answer that it cannot be found.

rx.determine_extinction_symbol( data: PatternData, candidate: CellCandidate, instrument: Instrument, *, peaks: PeakList | None = None, two_theta_limits: tuple[float, float] | None = None, k_sigma: float = 3.0, max_classes: int | None = None, refine_cell: bool = False, restrict: ExtinctionPrior | dict | None = None, cancel=None, ) → ExtinctionScreen#: Rank the extinction classes of a lattice.

Export and plots#

rx.write_refinement_cif( result: RefinementResult, structure: Structure, instrument: Instrument, path: str | Path, *, pattern: PatternData | None = None, )#: Write a refinement CIF: structure, fit and pattern.

rx.write_qpa_table( qpa: QuantitativePhaseAnalysis, path: str | Path, *, delimiter: str | None = None, )#: Write the QPA table to CSV/TSV (delimiter inferred from suffix).

rx.write_reflection_table( rows: list[ReflectionRow], path: str | Path, *, delimiter: str | None = None, )#: Write reflection rows to CSV/TSV (delimiter inferred from suffix).

rx.reflection_table( model: CompiledModel, values: dict[str, float], structure: Structure, ) → list[ReflectionRow]#: Reflection rows for every (emission line, reflection) of every phase.

rx.format_su(value: float, esd: float | None, *, decimals: int = 6) → str#: A number with its standard uncertainty in value(su) notation.

viz.plot_result( result: RefinementResult, *, path: str | None = None, two_theta_range: tuple[float, float] | None = None, show_background: bool = True, weighted: bool = False, style: str = 'light', wavelength: float | None = None, x_axis: str = 'two_theta', y_scale: str = 'linear', label_align: str = 'bottom', figsize: tuple[float, float] | None = None, font_size: float = 11.0, dpi: int = 300, title: str | None = None, )#: Standard Rietveld panel: observed, calculated, difference, tick rows.

viz.plot_for_vlm( result: RefinementResult, report=None, *, path: str, n_regions: int = 4, dpi: int = 140, )#: Annotated multi-panel montage drawn for a vision-language model to read.

rietx.viz.html.write_html( result: RefinementResult, path: str, *, weighted: bool = False, max_points: int | None = None, )#: Render a RefinementResult to a self-contained HTML file.