# 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](result.html.md) and [Sequential refinement](series.html.md) 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`. ```python from rietx.help import explain entry = explain("RefinementResult.status") print(entry.title) print(explain("BOUND_HIT") is not None) print(explain("NO_SUCH_CODE")) ``` ```text 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.