Result fields#

This page says what each field of a RefinementResult, a StageResult, a SeriesResult and a SeriesEntry holds, and what it means when it is empty.

A number in a field costs nothing until you read it, so a statistic that does not tell one fit from another is kept in a field and explained here, rather than raised as a diagnostic on every run. The entries are generated from rietx.help.RESULT_FIELD_HELP, the one place each is written. The refinement result and Sequential refinement show the same types in use.

Looking one up in code#

rietx.help.explain takes a result field, named Type.field, or a diagnostic code, and returns its entry. The two kinds of name cannot collide, because a code has no dot in it. A name this version does not describe, such as a code read from an older file, returns None.

from rietx.help import explain

entry = explain("RefinementResult.status")
print(entry.title)
print(explain("BOUND_HIT") is not None)
print(explain("NO_SUCH_CODE"))

Solver exit
True
None

RefinementResult#

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

RefinementResult.status

Solver exit. How the solver stopped: converged, max_iter or diverged. It makes no claim that the fit is good, since a model that matches nothing can converge. Quality is in diagnostics, and usable reads both.

RefinementResult.mode

Intensity mode. How the fit treated the peak intensities. rietveld computes them from the structure; lebail and pawley extract them from the pattern and refine no structure.

RefinementResult.parameters

Refined parameters. Every parameter the fit determined: the free ones and the tied or derived ones that follow them, each with its value, its esd and whether it sits on a bound. A parameter no stage freed, or one the fit held because the data could not see it, is absent.

RefinementResult.statistics

Agreement indices. The agreement indices of the answer as Toby (2006) defines them: Rwp, Rp, Rexp, χ² and the goodness of fit, beside the point and parameter counts they rest on and the largest shift over esd in the last accepted step.

RefinementResult.stages

Stage records. One record per stage the fit ran, in order, ending with the closing stage where the plan has one. Each says what the stage freed, what it held and why, and what it cost.

RefinementResult.diagnostics

Findings. Every finding the fit raised, each with a code, a level, a message, the paths it is about and a suggested action. A warning is to be answered before quoting what it names; an error means the values are not a refinement of this model. rietx.help.explain says what a code means.

RefinementResult.provenance

Provenance. What produced the result: the package and schema versions, the backend and its precision, the solver, the version of the report thresholds and when it was made.

RefinementResult.node_id

History node. The history node this fit committed, which Refinement.checkout can restore. None when the refinement ran with history disabled.

RefinementResult.tree_id

History tree. The history tree that node belongs to. A tree is pinned to one pattern by its data fingerprint. None when the refinement ran with history disabled.

RefinementResult.two_theta

Fitted channels. The 2θ of every channel the fit used, in order. A channel outside the fit range or inside an excluded region is absent, so this can be shorter than the pattern file.

Unit deg 2θ

RefinementResult.y_obs

Observed intensity. The observed intensity at each channel of two_theta, in the pattern’s own intensity units. It is what the residual was computed against.

RefinementResult.y_calc

Calculated intensity. The calculated intensity at each channel at the refined values, background included. The weighted difference between y_obs and this is what the fit minimised.

RefinementResult.y_background

Background curve. The background part of y_calc at each channel: the whole declared background, any background humps included.

RefinementResult.sigma

Channel weights. The σ each channel was weighted by: the file’s esd column where it has one, else the Poisson estimate, widened only where a measured background adds its own counting statistics. Read it through RefinementResult.sig, which every weighted residual in the package divides by.

RefinementResult.ticks

Reflection positions. Where the model puts each reflection, keyed by phase name: the Bragg angle plus the zero shift and the geometry’s own shift. Every emission line’s image is listed, so a Kα2 reflection has a tick of its own.

Unit deg 2θ

RefinementResult.tick_hkl

Reflection indices. Which reflection each tick in ticks is, as Miller indices h k l, paired with the positions by index. A satellite carries a fourth number, its order. A key is absent rather than empty where the ticks have no index, as for peaks declared by their centre.

RefinementResult.qpa

Weight fractions. The weight fraction of each modelled phase from the refined scales (Hill and Howard, 1987), with esds from the correlated scale block. The fractions are of the crystalline phases in the model, so they sum to one whatever else the specimen holds. None in Le Bail and Pawley fits, and where the fractions could not be formed, which QPA_UNAVAILABLE reports.

RefinementResult.phase_agreement

Per-phase R-factors. Each phase’s Bragg R-factor and structure-factor R-factor, with the number of reflections behind them (optimize.statistics.structure_r_factors). The observed intensities are partitioned by the model’s own prediction, so a low value is not evidence that a phase is present. Empty outside Rietveld mode.

RefinementResult.texture

Texture evidence. For each phase with a spherical-harmonics texture, the texture index and the smallest pole-density multiplier over its reflections and over the whole sphere. A negative minimum is an unphysical texture, which TEXTURE_NOT_POSITIVE reports. Empty when no phase declares one, outside Rietveld mode and in a joint fit.

RefinementResult.data_support

Observations against parameters. How many independent observations the pattern holds: the reflections measured, the count corrected for overlap, and each per structural parameter (optimize.statistics). It gates nothing. None for a joint fit, and for a result recorded before the field.

RefinementResult.absorption

Absorption correction. The specimen absorption correction the fit applied, for a capillary or a flat plate, with the change in Biso it is equivalent to. That change, not Rwp, is what the correction buys. None when no correction applied, and outside Rietveld mode.

RefinementResult.restraints

Restraint deviations. Each soft restraint’s deviation from its target in units of its σ, and the pooled restraint χ². A large deviation is a restraint fighting the data, however good Rwp looks. None when no phase declared restraints.

RefinementResult.geometry

Bond geometry. Bond distances and angles of the refined structure, each with an esd propagated through the whole covariance beside the diagonal-only one. An esd that cannot be measured is absent rather than zero. None outside Rietveld mode and when the result did not come from a fit.

RefinementResult.cell_volumes

Cell volumes. Each phase’s unit-cell volume with its esd through the covariance of the cell parameters, in every mode, since a Le Bail cell is a measurement too. None when the result did not come from a fit.

Unit Å³

RefinementResult.microstructure

Size and strain. Each phase’s coherent domain size and microstrain as physical numbers, with the Gaussian and Lorentzian readings given separately, the Scherrer constant used, and whether size and strain could be told apart. Empty when the fit had no compiled model to read a wavelength from.

RefinementResult.identifiability

Degeneracy evidence. What the final Jacobian says about parameters the data cannot separate: how much of each structural column the background or an extra peak could imitate, the strongest correlations, the soft modes and the exchangeable pairs. A stored result keeps what the fit measured and cannot recompute it. None when the result did not come from a fit that ran the guards.

RefinementResult.parametric

Parametric coefficients. The coefficients of every parametric equation a joint fit refined, in the caller’s units at the equation’s reference, each with its esd from the joint covariance or None where that gives none. None when no parametric equation was declared.

RefinementResult.parametric_form

Parametric form tests. For each parametric equation, in declaration order, whether its form survives the data. None exactly when parametric is.

RefinementResult.parametric_form_joint

Joint parametric form test. The form test of every tested parametric equation at once: the χ² that freeing each equation’s target in every pattern would remove. It catches two wrong equations that each pass while the other is freed. None unless two or more equations were tested.

RefinementResult.parametric_equations

Resolved parametric equations. Each parametric equation as the fit resolved it, with its coefficients’ covariance in the caller’s units, in declaration order. RefinementResult.parametric_value evaluates one at any coordinate. None exactly when parametric is, and on a result written before the field.

RefinementResult.n_extra_components

Declared extra components. How many additive non-Bragg components the instrument declared, background humps and sharp peaks together, whether or not any was freed. 0 means none was declared; None means nothing counted, as in a joint fit or a result recorded before the field.

RefinementResult.n_background_components

Declared background components. How many of the declared extra components land in the background. This is the background flexibility the caller granted, which a reader comparing two Rwp values needs to see. 0 means none; None means nothing counted.

RefinementResult.histograms

Per-histogram results. One slice per pattern of a multi-histogram joint fit, each with its own curves, statistics and diagnostics, while statistics is then the pooled figure. Empty for an ordinary fit. RefinementResult.for_histogram gives one slice in a single fit’s shape.

StageResult#

One stage’s record in RefinementResult.stages: what it freed, what it held and why, and what it cost.

StageResult.name: Stage name. The stage’s name from the plan. The stage a plan appends to converge the answer is named by strategy.staged.CLOSING_STAGE_NAME.
StageResult.status: Stage solver exit. How the solver stopped in this stage: converged, max_iter or diverged. Earlier stages of a plan stop at a looser tolerance on purpose (ftol), so the last stage’s exit is the one about the answer.
StageResult.n_iterations: Residual evaluations. The residual evaluations the stage’s solve made, the starting one included, and both solves where the stage solved twice. The name says iterations but the count is evaluations, the unit a stage’s max_iter budget is converted to through NFEV_PER_ITERATION.
StageResult.cost_initial: Starting cost. The least-squares cost when the stage started: half the sum of squared weighted residuals over every row, the penalty and restraint rows included (model.rows).
StageResult.cost_final: Final cost. The least-squares cost where the stage stopped, on the same terms as cost_initial. The pair says how much the stage improved the fit.
StageResult.freed: Parameters refined. The parameter paths this stage’s turn_on patterns freed, less any the stage held. A locked, tied or held path is never here, and ParameterRow.held_because says why.
StageResult.ftol: Tolerance the stage ran at. The relative cost-decrease tolerance this stage stopped at. None means the solver’s own default, which the last stage of a plan takes; an earlier stage takes the plan’s intermediate_ftol unless it declares its own.
StageResult.window_area_tol: Profile window fraction. The fraction of each peak’s area this stage’s profile windows dropped. None means model.forward.WINDOW_AREA_TOL, which every declared stage takes, and the closing stage runs at the plan’s closing_window_tol. model.forward.recorded_window_tol turns this into what compile_model needs to reproduce the result’s curves.
StageResult.n_constraint_truncations: Steps held on a constraint. How many solver steps were held on a linear-inequality constraint, such as the Stephens strain cone, because the step for the bounds alone crossed it. Always zero under the TRF solver. Nonzero in the last stage means the answer sits on a constraint face, which CONSTRAINT_ACTIVE reports.
StageResult.n_degenerate_cell_probes: Degenerate cells refused. How many trial cells this stage’s residual refused as degenerate, with zero or negative volume, pushing the solver back rather than failing. The cell parameters carry no bounds of their own, so an underdetermined cell can reach one often. Zero means this stage never did.
StageResult.n_lapack_fallbacks: Decompositions repeated. How many matrix decompositions this stage repeated with LAPACK’s QR-iteration driver because the default driver stopped without converging (optimize.lapack). The answer is the one a converging build computes. Zero means none needed it.
StageResult.held: Held by the stage. Parameter columns this stage held fixed although its plan freed them, because the data could not determine them: the structural parameters of a phase too weak to see, for example. They are never in freed, and the stage’s other fields say which test held which.
StageResult.held_reach: Stopped with a held column. For each held column that drives other entries through a tie, the entries it stopped with it: holding a cubic a also stops b and c. A column that moved nothing else is absent, so held and these values together are every value the stage froze.
StageResult.scale_b_held: Displacements held against the scale. For each phase, by index, whose displacement parameters this stage held because the fitted range cannot separate them from the phase’s scale, the separation measured (refine._scale_b_separation, against refine.SCALE_B_SEPARATION_FLOOR). An empty mapping is a stage that looked and held nothing; None means nobody looked, as in a joint fit.
StageResult.width_twins_held: Instrument widths held. For each instrument width term this stage held because a free specimen width has the same angular dependence, the specimen columns it pairs with (refine._width_twin_flats). The data see only the total width, so the instrument side is held where the stage found it. An empty mapping held nothing; None means a result stored before the field.
StageResult.released: Released within the stage. Paths held at the start of the stage and freed again within it, because their phase rose above support while the stage solved, which then solved once more with them free. They refined, so they are not in held.
StageResult.moment_flat_axes: Flat moment axes. For each magnetic site, keyed phases.i.atoms.j, whose moment azimuth this stage held as part of a flat combination of its two angles, the flat rotation axis as a unit vector in crystal-axis components. Empty on every fit where no such site was held.
StageResult.moment_turned: Moments turned. The sites of moment_flat_axes whose moment the stage turned about the flat axis before holding it, a move the data cannot see that changes the direction the fit reports. A site held where it was is in moment_flat_axes alone.
StageResult.blocked_by_hold: Blocked by a hold. Paths this stage’s turn_on matched and did not free, because the caller declared a hold on them with Refinement.hold. A hold outranks a plan’s pattern and lasts until Refinement.unhold. It feeds HOLD_BLOCKED_PLAN.
StageResult.unknown_paths: Paths naming nothing. The literal paths in this stage’s turn_on, and any retired spellings, that name no parameter of the model: a typo or a renamed path, so what the stage meant to refine did not refine. An empty list is a stage that was checked; None means nobody looked. It feeds STAGE_PATH_UNKNOWN.
StageResult.unreached_histograms: Histograms a stage missed. Joint fits only: for each histogram, by index, the patterns of this stage that matched rows on another histogram and none on this one. A single-histogram fit writes an empty mapping; None means nobody looked. It feeds STAGE_FREED_NOTHING.
StageResult.seeded: Rows lifted before solving. Each row this stage moved before solving, with the value it started at. A freed row sitting on a floor starts at the stage’s seed, and an all-zero Stephens block is put on its isotropic ray by strain_seed. An empty mapping lifted nothing; None means a result stored before the field.
StageResult.moment_angle_tests: Stationary-angle tests. The stationary-angle test the stage’s covariance ran, one round per entry in order. An angle a round zeroed stayed free and kept its value but carries no esd. None means no test ran, for example because no moment angle was free beside its modulus. It feeds MOMENT_ANGLE_STATIONARY.
StageResult.cell_reset: Cells put back. The free cell parameters this stage put back at their starting values, because a cell parameter of their phase left the safety window while it solved (params.vector.CELL_SAFETY_FRACTION). CELL_RUNAWAY names them and says what followed. An empty list is every stage of an ordinary fit; None means a result stored before the field.
StageResult.collapsed: Restored and held. The free parameters this stage restored to their starting values and held, because its first solve found them flat: a phase whose scale fell under support, or a moment direction that stopped moving the pattern. Their first-solve values were a walk, not a measurement. A subset of held; None means a result stored before the field.

SeriesEntry#

One pattern’s summary in SeriesResult.entries: what was fitted and how the chain reached it.

SeriesEntry.index: Position in the series. The pattern’s position in the series as given, counting from zero. It is the series axis when no coordinate was given.
SeriesEntry.label: Pattern label. The pattern’s name in the series: the label the run was given, else its source file’s name, made unique because it also names the pattern’s history file.
SeriesEntry.x: Series coordinate. The pattern’s series coordinate, such as a temperature, time or pressure, in the caller’s units. None when the caller gave none, and index is then the axis.
SeriesEntry.status: Pattern solver exit. The solver’s exit for the attempt kept on this pattern. diverged after the last rung of the ladder means the pattern is quarantined: it seeds no successor and joins no median, and SEQUENTIAL_UNRECOVERED says so.
SeriesEntry.statistics: Pattern agreement indices. The agreement indices of the kept attempt, the same table as RefinementResult.statistics. Every entry the chain builds carries one; None means none was recorded.
SeriesEntry.parameters: Pattern parameters. The refined parameters of the kept attempt, as RefinementResult.parameters holds them. SeriesResult.trajectory reads one path across every entry.
SeriesEntry.qpa: Pattern weight fractions. The weight fractions of the kept attempt, as RefinementResult.qpa holds them. None outside Rietveld mode and where the fractions could not be formed.
SeriesEntry.phase_agreement: Pattern R-factors. Each phase’s Bragg and structure-factor R-factors on this pattern, copied from its result. A low value on a weak phase is not evidence the phase is present, because the observed intensity is partitioned by the model’s own prediction. Empty outside Rietveld mode.
SeriesEntry.magnetic: Moment evidence. The evidence for each magnetic site’s moment on this pattern: whether the data support it, its esd and what the powder average cannot determine. A signed moment parameter alone draws an unsupported moment as a small one. Empty when no phase declares a moment or the pattern carries no magnetic term, and never because no moment was found.
SeriesEntry.diagnostics: Pattern findings. The findings of this pattern’s own fit. Findings about the series as a whole are on SeriesResult.diagnostics.
SeriesEntry.n_iterations: Pattern evaluations. The residual evaluations spent on this pattern over every attempt, each rung of the escalation ladder included. It is what a warm start actually buys, measured rather than assumed.
SeriesEntry.reseeded: Warm start rejected. Whether the warm start was rejected and the pattern refitted from the initial models, the cold rung. A reseeded point can be a good fit, but it is not evidence that the trajectory is continuous there. SEQUENTIAL_RESEED reports it.
SeriesEntry.rwp_warm: Warm attempt’s Rwp. The Rwp the first, warm attempt reached, recorded whenever the ladder escalated. With reseeded set too, a cold restart rescued the pattern; alone, the warm attempt stayed the best tried. None when the ladder did not escalate or the first attempt raised.
SeriesEntry.rung: Winning rung. Which attempt produced this entry’s values: warm, a one-stage refit from the neighbour; warm_staged, the full plan from the warm state; or cold, the full plan from the initial models. The first pattern is always cold, having no neighbour to start from.
SeriesEntry.rungs_tried: Rungs tried. Every rung attempted on this pattern, in ladder order. One entry means the pattern fitted first time; n_iterations is the cost of these less the ones in rungs_raised.
SeriesEntry.rungs_raised: Rungs that raised. The rungs whose fit raised an exception rather than returning, each with the exception’s type and message. The ladder escalates past a raised rung as past a diverged one. Empty wherever no rung raised.
SeriesEntry.rwp_fence: Rwp fence. The Rwp limit the chain set at this pattern, from reseed_factor and the Rwp of the patterns accepted before it (sequential._rwp_fence). An attempt above it climbs the ladder. None where no earlier pattern had been accepted, so no fence judged it.
SeriesEntry.node_id: Pattern history node. The history node of this pattern’s kept fit. Each pattern has a tree of its own, pinned to it by its data fingerprint. None when the series ran without history.
SeriesEntry.tree_id: Pattern history tree. The history tree this pattern’s fit is in, one tree per pattern. None when the series ran without history.

SeriesResult#

What a sequential refinement returns: one entry per pattern, and what the chain found about the series as a whole.

SeriesResult.mode: Series intensity mode. The intensity mode every pattern of the series was fitted in. One protocol over every pattern is what makes their trajectories comparable.
SeriesResult.entries: Pattern summaries. One summary per pattern that returned a fit, in series order: its refined values, agreement indices, findings and how the chain reached it. Curves are not kept; SequentialRefinement.results_ holds each full result.
SeriesResult.x_label: Series axis name. The name of the series coordinate, such as temperature or time, for plots and trajectories. When no coordinate was given the pattern index is the axis, and this says so.
SeriesResult.direction: Chain direction. Which way the chain ran: forward, backward, or both, which runs it each way and compares the two trajectories. Under both the entries are the forward chain’s and the comparison is SEQUENTIAL_PATH_DEPENDENT.
SeriesResult.backward: Reverse chain. The reverse chain’s own series result when direction is both, so the trajectory a path-dependence finding is about can be read. None for a one-way run.
SeriesResult.diagnostics: Series findings. Findings about the series as a whole, such as path dependence, discontinuities, reseeds and patterns that failed. Each pattern’s own findings stay on its entry.
SeriesResult.discontinuities: Flagged steps. Every SEQUENTIAL_DISCONTINUITY finding as fields, in the same order: the parameter, the two patterns it stepped between and the signed step. An empty list is a series that flagged nothing; None means a document written before the field.
SeriesResult.relative_paths: Paths that are steps. The paths whose values are steps from where each fit began rather than positions, such as coordinate DOFs and rigid-body rotations. A comparison across patterns must not read them as positions. None means a document written before the field.
SeriesResult.angle_paths: Moment angle paths. The moment angle DOFs, whose differences across patterns are taken modulo a full turn. Recorded as relative_paths is, and None means the same.
SeriesResult.failures: Patterns that failed. Every pattern on which every rung of the ladder raised an exception, so the chain has no entry for it: its index, its label and the last exception. An empty list means every pattern returned a fit.
SeriesResult.n_failed: Failure count. How many patterns failed outright, the length of failures, for a caller that wants a number rather than a list to count.
SeriesResult.provenance: Series provenance. What produced the series: the package version, backend, solver, version of the report thresholds and when it ran. None on the reverse chain in backward, which carries none of its own.