Glossary¶

Every refinable parameter, peak flag, stage setting, reader option and instrument preset field this package uses, with its unit, default and a range to sanity-check a refined number against.

The entries are generated from rietx.help, which is the single place any of this is written down. The GUI puts the same sentence beside the same control, so a description here and a tooltip there cannot disagree.

Every parameter is held (vary=False) until a stage or a set_vary call frees it, so no entry repeats that. Where an entry says a parameter is locked or tied, that is structural and set_vary will refuse it: see Constraining parameters to each other.

Looking one up in code¶

help_for takes a parameter dot-path and returns the entry whose family claims it, matching with fnmatch exactly as a stage’s turn_on globs do.

import rietx as rx

entry = rx.help_for("phases.0.atoms.2.biso")
print(entry.title)
print(entry.unit, entry.default)

Isotropic displacement parameter
Å² 0.5

A path outside the parameter vocabulary returns None rather than a guess.

help_key_for returns the family glob itself rather than the entry, and Refinement.parameters() puts that glob on every row as ParameterRow.help_key. A row carries the key and not the entry because an entry describes a family, so inlining one repeats the same paragraph once per atom.

import rietx as rx

print(rx.help_key_for("phases.0.atoms.3.biso"))
print(rx.help_key_for("phases.0.atoms.3.nonsense"))

phases.*.atoms.*.biso
None

help_registry returns the whole corpus as JSON-able data, and the GUI’s GET /api/help serves it. Its keys are parameters, peak_flags, peak_diagnostics, peak_origins, stage_fields, reader_options, instrument_fields, search_fields and plans. Each object in parameters lists every glob that reaches it, so a help_key looks up there.

import rietx as rx

registry = rx.help_registry()
print(sorted(registry))
print(registry["peak_flags"]["axial_tail"]["title"])

['instrument_fields', 'parameters', 'peak_diagnostics', 'peak_flags', 'peak_origins', 'plans', 'reader_options', 'search_fields', 'stage_fields']
Possibly a stronger line's axial tail

Entry fields¶

Each entry is a HelpEntry with seven fields.

HelpEntry.title: The name in words.
HelpEntry.description: What the quantity is, and what moves it.
HelpEntry.unit: The unit, or None where the quantity is dimensionless. Pinned against the schema’s own Parameter.unit by tests/test_help.py.
HelpEntry.default: The value the schema starts from, as a string, or None where there is none. A cell edge has no default because it arrives with the structure. Also pinned against the schema.
HelpEntry.typical: A range to check a refined number against. It is guidance, not a bound, and nothing in the package reads it.
HelpEntry.anchor: The manual heading that carries the equation, checked against the built HTML.
HelpEntry.label: The short form a chip carries where the name would not read: at bound for position_at_bound. Only the peak_flags and peak_origins arms carry one, and every entry there must. It is None elsewhere, where no chip is drawn.

Limitations¶

typical and label are the two authored fields, and no computation in the package reads either (the GUI reads label to letter a chip). The ranges come from McCusker et al. (1999) [McCusker et al., 1999] and from this repository’s own reference datasets, and a specimen outside one is not thereby wrong.

The corpus describes parameters rather than strategy. Which parameter to free next is Running a refinement, and what a diagnostic code means for a whole refinement is the agent skill.

Parameters¶

Dot-paths as a stage’s turn_on globs spell them. Several globs share one entry where they share a meaning.

instrument.zero_shift: Zero-point shift. A constant offset added to every calculated 2θ, absorbing the goniometer’s zero-point misalignment. It is a property of the diffractometer, not of the specimen, so calibrate it on a standard with a certified cell and hold it afterwards. Freed alongside a free cell and a free sample displacement it is close to degenerate with both, which is what makes calibration on a held cell the step that separates the three.
Unit deg 2θ · Default 0.0 · Typical |Δ| < 0.05 deg on an aligned diffractometer
instrument.polarization: Polarization factor. The K of the Lorentz-polarisation correction, (1 + K·cos²2θ)/(1 + K). Fixed by the beam optics, so it is declared and not refined: 0.5 for an unpolarised laboratory source, cos²2θ_M for a monochromated one, and 0.99 in the APS 11-BM instrument-parameter files.
Default 0.5 · Typical 0.5 unmonochromated lab; 0.9-1.0 synchrotron
instrument.source.lines.*.wavelength: Emission wavelength. One emission line’s wavelength. Bragg’s law fixes only the product of λ and the cell scale, so a free wavelength and a free cell are an exactly flat direction: the row reports needs_held_cell and set_vary refuses it while any cell is free. Refine it against a standard whose cell is certified, or leave it at the tabulated value.
Unit Å · Typical 1.540598 Å Cu Kα1, 0.7093 Å Mo Kα1, 0.3-1.0 Å synchrotron
instrument.source.lines.*.weight: Emission line weight. One emission line’s intensity relative to line 0. Line 0 is structurally locked at 1 because it is degenerate with the phase scales, so only a second or later line carries a refinable weight. For a Kα doublet the value is the 2j+1 degeneracy ratio and needs refining only when a monochromator or a filter has changed it.
Default 1.0 · Typical 0.5 for Kα2 against Kα1
instrument.geometry.sample_displacement: Specimen displacement. How far the specimen surface sits off the goniometer axis, positive toward the source and detector side of the focusing circle. On a Bragg-Brentano mount it shifts every line by −2s·cosθ/R (McCusker eq 3), which is the largest systematic position error a laboratory pattern usually carries. The cosθ shape is close to the constant shape of zero_shift, so freeing both on one pattern usually reports a correlation.
Unit mm · Default 0.0 · Typical |s| < 0.05 mm on a carefully packed flat plate
instrument.geometry.sample_transparency: Specimen transparency. The coefficient of the sin 2θ position shift a beam penetrating into the specimen produces (McCusker eq 4). On a flat plate it is the transparency aberration; on a capillary the same sin 2θ shape is the along-beam offset instead, so this parameter belongs to a flat-plate geometry and the report suggests it only there.
Default 0.0 · Typical 0-0.01 for a dense oxide; larger for a low-absorbing organic
instrument.geometry.axial_sl: Axial divergence: specimen length. The Finger-Cox-Jephcoat S/L, the illuminated specimen length divided by the goniometer radius. It sets how strongly low-angle peaks lean towards low 2θ. Fit it on a standard together with axial_hl; the two are strongly correlated and are usually reported as a pair.
Default 0.0 · Typical 0.01-0.05
instrument.geometry.axial_hl: Axial divergence: detector slit. The Finger-Cox-Jephcoat H/L, the receiving slit height divided by the goniometer radius. It is the second half of the axial asymmetry and is correlated with axial_sl closely enough that refining one while holding the other is a common protocol.
Default 0.0 · Typical 0.01-0.05
instrument.geometry.capillary_offset_along_beam: Capillary offset along the beam. How far the capillary axis sits from the rotation centre in the beam direction. It shifts positions as sin 2θ, the same shape flat-plate transparency has, and this is the parameter the report suggests for a Debye-Scherrer geometry.
Unit mm · Default 0.0 · Typical |d| < 0.05 mm on an aligned spinner
instrument.geometry.capillary_offset_across_beam: Capillary offset across the beam. How far the capillary axis sits from the rotation centre perpendicular to the beam. It shifts positions as cos 2θ, so it is separable from the along-beam offset by shape, unlike the flat-plate pair.
Unit mm · Default 0.0 · Typical |d| < 0.05 mm on an aligned spinner
instrument.geometry.surface_roughness.a: Suortti roughness: surviving fraction. The a of the Suortti (1972) surface-roughness correction, R = [a + (1 − a)·exp(−b/sinθ)] / [a + (1 − a)·exp(−b)]. It is the intensity fraction that survives even at grazing incidence, so 1 − a bounds how deep the low-angle depression can go. Refine it with b and never alone: b = 0 is exactly the identity whatever a is.
Default 0.5 · Typical 0.5-1; the default is interior because at a = 1 the gradient of b vanishes identically and it could never lift off
instrument.geometry.surface_roughness.b: Suortti roughness: layer depth. The dimensionless optical depth of the depleted surface layer in the Suortti (1972) correction. It sets where in angle the depression falls, not how deep it goes. Both limits return the identity, so any one depression is reproducible by two values of b, and ROUGHNESS_UNCONSTRAINED measures the modelled depression rather than b itself. b = 0 is a dead gradient, so a stage that frees it seeds it.
Default 0.0 · Typical 0.1-0.5; past about 3 the correction is dead and its gradient flat
instrument.geometry.surface_roughness.c: Pitschke roughness: strength. The strength of the Pitschke et al. (1993) surface-roughness correction, R = 1 − c·u·(1 − u) with u = τ/sinθ. c = 0 is exactly no correction. The paper’s angle-independent porosity term is deliberately absent here, because a constant prefactor is exactly degenerate with the phase scale.
Default 0.0 · Typical 0-4; beyond 4 R can go negative inside the valid range
instrument.geometry.surface_roughness.tau: Pitschke roughness: τ. The dimensionless surface-roughness parameter τ = t₀/β of the Pitschke et al. (1993) correction, refined directly rather than through a particle size the diffraction data cannot constrain. The correction is monotone only while sinθ ≥ 2τ and would amplify beyond sinθ = τ, which ROUGHNESS_OUTSIDE_REGIME reports: a box bound cannot express a fence that depends on the fitted range.
Default 0.05 · Typical 0.005-0.12, the span of the paper’s own four specimens
instrument.profile.u: Caglioti U. The tan²θ term of the Gaussian variance, Γ_G² = U·tan²θ + V·tanθ + W. It is where instrumental strain-like broadening lives, and a phase’s gauss_strain adds to it: variances add under convolution, so instrument and specimen stack here rather than replacing each other. Refining U on a specimen whose gauss_strain is also free fits one quantity twice.
Unit deg² 2θ · Default 0.0 · Typical 0-0.05 on a laboratory diffractometer
instrument.profile.v: Caglioti V. The tanθ term of the Gaussian variance. It is the only Caglioti term allowed to be negative, and the minimum of the width curve sits where it cancels against U. Nothing in the specimen contributes to it, so it is purely instrumental.
Unit deg² 2θ · Default 0.0 · Typical −0.05 to 0
instrument.profile.w: Caglioti W. The constant term of the Gaussian variance, so it sets the width the pattern would have at zero angle. It is bounded positive: a negative W is a negative variance. Freeing W together with a free gauss_size fits the same constant twice at low angle.
Unit deg² 2θ · Default 0.001 · Typical 0.001-0.02 on a laboratory diffractometer
instrument.profile.x: Lorentzian X. The 1/cosθ term of the Lorentzian FWHM, Γ_L = X/cosθ + Y·tanθ. The 1/cosθ shape is Scherrer size broadening, and a phase’s lor_size adds to it, since Lorentzian FWHMs add under convolution. Document the physics rather than the letter: GSAS and FullProf swap the X and Y assignment.
Unit deg 2θ · Default 0.001 · Typical 0.001-0.05 on a laboratory diffractometer
instrument.profile.y: Lorentzian Y. The tanθ term of the Lorentzian FWHM. The tanθ shape is microstrain broadening, and a phase’s lor_strain adds to it. An anisotropic strain block replaces the specimen half of this term with an hkl-dependent width and locks lor_strain, but leaves the instrumental Y alone.
Unit deg 2θ · Default 0.0 · Typical 0-0.05 on a laboratory diffractometer
instrument.background.c*: Background coefficient. One coefficient of the shifted-Chebyshev background, y_bkg = Σ c_n T_n(x) over the fitted 2θ range normalised to [−1, 1]. The model is linear in these, so their Jacobian columns are the basis functions themselves and they can be freed from the first stage. Adding terms until Rwp stops falling is the wrong test: a background flexible enough to imitate the peaks biases displacement parameters up and scales down while Rwp improves. Read FitReport.background instead.
Default 0.0 · Typical 4-8 terms for a flat laboratory background; c0 is of the order of the observed background counts
instrument.background.air: Air-scatter term. Scales an additive 1/(2θ) term for the low-angle air-scatter rise, carried by the P-spline background beside its spline coefficients. 0 is exactly no term, and that is where it belongs unless rietx.background.diagnose reports the rise: the shape is broad, so freeing it without cause gives the background one more way to imitate a peak.
Default 0.0 · Typical 0 unless the pattern diagnostics report a low-angle rise
instrument.extra_components.*.position: Background-peak position. The centre, in °2θ, of an explicit Gaussian background term — a diffuse or amorphous hump, a cryostat or sample-container contribution. Unbounded by default: it is not a Bragg position, so nothing constrains it but the data, and a caller who knows the fitted range may set min/max. A declared peak is inert (vary=False, height 0) until a stage frees it — nothing in the package adds one on its own. Freeing position, height and width together is a reflection with no cell behind it, which is why the fitted width is held to the resolution (HUMP_TOO_NARROW).
Unit deg 2θ · Default 0.0 · Typical wherever the diffuse feature sits, e.g. 14.4 on NIST BT-1
instrument.extra_components.*.height: Background-peak height. The peak intensity of an explicit Gaussian background term, in the pattern’s own count units. Softplus with min 0 because zero is the off state: h = 0 makes the whole term identically zero, so a declared-but-never-freed peak is bit-identical to no peak at all.
Unit counts · Default 0.0 · Typical of the order of the hump’s rise above the smooth background
instrument.extra_components.*.fwhm: Extra-component width. The full width at half maximum, in °2θ, of a declared extra component — and the two kinds want opposite things from it. For a hump the width is what makes the term a background term: it comes from disorder rather than the goniometer, so it is many times the instrumental resolution, and a fitted width approaching that resolution is a reflection being eaten, reported as HUMP_TOO_NARROW. For a peak sharp is the whole point — it is a real reflection from something that is not one of your phases — so no width guard fires and the floor is only there because the profile divides by Γ. Softplus in both cases, floored at a small positive value; the floor differs by kind (0.1 for a hump, 0.005 for a peak) because the two are derived from the coarsest and the finest scan step anything can be refined from.
Unit deg 2θ · Default 5.0 for a hump, 0.1 for a peak · Typical a hump: several times the instrumental FWHM at that angle, ~6 on the BT-1 case it was measured on. A peak: the instrumental FWHM itself, since it is a reflection
instrument.extra_components.*.center: Extra-peak centre. The apparent centre, in °2θ, of a declared sharp peak your phases cannot account for — a sample holder diffracting at its own specimen distance, a mount, an unidentified impurity line. It is the position of the primary emission line and it is not corrected: no zero shift, no displacement or transparency shift, no axial asymmetry. A holder sits at its own distance and its aberrations are its own, so all of them are absorbed here, which is also why you cannot read a d-spacing off this number. Unlike a hump’s position it must carry finite min/max: the evaluation window is frozen at stage compile and sized from those bounds, which is what lets the centre refine without leaving its window. A declared peak is inert (vary=False, area 0) until a stage frees it; of the presets only mccusker_structural does, in its extra_components stage, and nothing ever adds a peak you did not declare.
Unit deg 2θ · Typical where you can see the intruding line, bounded a few tenths either side
instrument.extra_components.*.area: Extra-peak area. The integrated intensity of a declared sharp peak, in the pattern’s count units times °2θ. An area and not a height because that is what a reflection intensity is, and it is not called scale on purpose: every *.scale path is force-fixed under Le Bail and Pawley, where a declared peak still has to refine. Softplus with min 0 because zero is the off state — area 0 makes the term identically zero, so a declared-but-never-freed peak is bit-identical to no peak at all. An area that refines to its zero bound means the data does not see the peak, and its centre then reports no esd at all rather than a small one: that absent esd is the evidence the peak was not needed.
Unit counts·deg 2θ · Default 0.0 · Typical the intruding line’s integrated counts above the background
instrument.extra_components.*.eta: Extra-peak mixing. The Lorentzian fraction of a declared sharp peak’s pseudo-Voigt: 0 is a pure Gaussian, 1 a pure Lorentzian, and both ends are legitimate rather than poles, which is why this is logit- rather than softplus-transformed. Its upper bound also sizes the frozen evaluation window, because the half-width at which the profile’s discarded area stays within tolerance is a steep function of η (about 1 FWHM at η = 0, about 16 at η = 1). A caller who knows the intruder is near-Gaussian can say so with eta.max and buy a much smaller window.
Default 0.5 · Typical 0.3-0.9 for a lab peak; leave it fixed unless the peak is strong enough to carry a fourth parameter
phases.*.cell.a, phases.*.cell.b, phases.*.cell.c: Cell edge. A unit-cell edge length. Sets every reflection position through the lattice metric, so it is the parameter a powder pattern determines best and the one a systematic position error corrupts first. Edges the space-group setting ties to another (b to a in a tetragonal cell) are held and follow their source.
Unit Å · Typical 3-40 Å for an inorganic phase; refined shifts are 10-1000 ppm
phases.*.cell.alpha, phases.*.cell.beta, phases.*.cell.gamma: Cell angle. A unit-cell angle. An angle the space-group setting fixes at 90° or 120° is locked and cannot be freed; a monoclinic cell frees only its unique-axis angle.
Unit deg · Typical 90° or 120° when symmetry fixes it; 80-100° for a monoclinic β
phases.*.scale: Phase scale. The multiplier on this phase’s calculated intensity, and the only route by which the phase reaches the pattern at all. Quantitative phase analysis is computed from it through the Hill-Howard ZMV relation, so it carries the weight fractions. A scale that refines onto its lower bound means the data does not see the phase: the fit still reports convergence while the phase’s cell drifts unconstrained, which is what PHASE_UNCONSTRAINED names.
Default 1.0 · Typical positive, spanning several orders of magnitude between phases
phases.*.extinction: Secondary extinction. The Sabine secondary-extinction coefficient, attenuating the strong low-angle reflections of a well-crystallised specimen. 0 is exactly no correction, so a phase that does not free it is unaffected. The gradient at 0 is dead, which is why the staged plans seed it off zero with Stage.seed when they free it.
Default 0.0 · Typical 0 for a ground powder; up to 1e-4 for large crystallites
phases.*.lor_size: Lorentzian size broadening. The specimen’s 1/cosθ contribution to the Lorentzian FWHM, which is Scherrer broadening from finite crystallite size. It adds to the instrumental X. Calibrate the instrument on a standard, hold U V W X Y, then refine this and its three companions. It carries a default upper bound — a floor on the crystallite at 2 nm, deliberately permissive so genuinely nanocrystalline specimens refine freely — which reports BOUND_HIT if reached. Setting max to any finite value is your own claim and switches that default off. A refined size below 5 nm raises SIZE_UNUSUALLY_SMALL, which flags rather than bounds.
Unit deg 2θ · Default 0.0 · Typical 0-0.3 deg; 0.1 deg is roughly a 100 nm domain at Cu Kα
phases.*.lor_strain: Lorentzian strain broadening. The specimen’s tanθ contribution to the Lorentzian FWHM, which is isotropic microstrain. It adds to the instrumental Y. Declaring a Stephens anisotropic strain block locks this parameter, because the isotropic direction of that block is identically this column. It carries a default upper bound derived from the fitted 2θ range — a line cannot be wider than the interval it was measured over — which sits two orders of magnitude above any specimen and reports BOUND_HIT if reached. Setting max to any finite value, however large, is your own claim and switches that default off. A width past 1.5 deg raises STRAIN_UNUSUALLY_LARGE, which flags rather than bounds.
Unit deg 2θ · Default 0.0 · Typical 0-0.3 deg
phases.*.gauss_size: Gaussian size broadening. The specimen’s 1/cos²θ contribution to the Gaussian variance. Gaussian variances add, so it stacks on the instrumental W and U rather than replacing them. Most specimens are better described by the Lorentzian pair; free this one when the peak shape is measurably more Gaussian than the standard’s. It carries the same default 2 nm floor as lor_size, squared: this is a variance, so the cap on the width it contributes applies to its square root.
Unit deg² 2θ · Default 0.0 · Typical 0-0.05 deg²
phases.*.gauss_strain: Gaussian strain broadening. The specimen’s tan²θ contribution to the Gaussian variance, stacking on the instrumental U. Freeing it while U is also free fits one quantity twice, and the guard reports the correlation. It carries the same default upper bound as lor_strain, squared: this is a variance, so the cap on the width it contributes applies to its square root.
Unit deg² 2θ · Default 0.0 · Typical 0-0.05 deg²
phases.*.preferred_orientation.r: March coefficient. The March-Dollase coefficient for preferred orientation along the declared hkl axis. r = 1 is exactly no correction. Which side of 1 means platy and which means needle-like flips between reflection and transmission geometry, so read it against the mount rather than from the number alone. The bound is 0.15 rather than 0 because the March factor divides by r.
Default 1.0 · Typical 0.6-1.4; a value outside 0.5-2 describes a texture few powder mounts produce
phases.*.atoms.*.x, phases.*.atoms.*.y, phases.*.atoms.*.z: Fractional coordinate. An atom’s position along a cell axis, in fractions of the edge. It is not refined directly: ParameterTable ties x, y and z to the site’s symmetry degrees of freedom, so editing it means editing the dof.k entries it follows. An atom on a fully fixed special position has no free direction and its coordinates are locked.
Typical 0 to 1
phases.*.atoms.*.dof.*: Site-symmetry coordinate degree of freedom. One allowed direction of motion for an atom on its Wyckoff site. This is the quantity that refines: x, y and z are affine-tied to the site’s degrees of freedom, so the site symmetry holds exactly rather than approximately. A site with no allowed direction produces no dof entry and its coordinates are locked. Free them with the phases.*.atoms.*.dof.* glob.
Typical 0 to 1, in the same units as the coordinate it drives
phases.*.atoms.*.occ: Site occupancy. The fraction of the site occupied by this species. It is close to degenerate with the site’s displacement parameter, since both reduce scattered intensity, and X-rays separate the two poorly. Refine one or the other unless the data reaches high Q, and constrain occupancies that must sum to 1 with a user tie.
Default 1.0 · Typical 0 to 1; the bound allows 1.5 so a shared site can be modelled
phases.*.atoms.*.biso: Isotropic displacement parameter. The atom’s isotropic B, related to the mean-square displacement by B = 8π²·Uiso. It damps intensity as exp(−B·sin²θ/λ²), so it is determined by the high-angle data and is the parameter a too-flexible background biases first. A negative B is unphysical and the bound is at 0; a refined B above about 5 Å² for a heavy atom usually means an absorption or background error rather than a real displacement.
Unit Å² · Default 0.5 · Typical 0.2-2 Å² for an inorganic framework at room temperature
phases.*.atoms.*.u11, phases.*.atoms.*.u22, phases.*.atoms.*.u33, phases.*.atoms.*.u12, phases.*.atoms.*.u13, phases.*.atoms.*.u23: Anisotropic displacement component. One component of the stored CIF U^ij displacement tensor, in Å². Like the coordinates it is tied rather than free: the refined quantities are the adp.k entries of the site-symmetry-allowed subspace, and a tensor outside that subspace is refused rather than symmetrised.
Unit Å² · Typical 0.005-0.05 Å² on the diagonal; off-diagonal components are smaller
phases.*.atoms.*.adp.*: Site-symmetry ADP degree of freedom. One allowed component of the anisotropic displacement tensor on this Wyckoff site. Unlike a coordinate degree of freedom these are absolute rather than incremental: U is the sum of θ_k times the basis tensors, which enforces the site symmetry exactly. Positive-definiteness couples all six components and so is not a bound; a tensor that loses it raises ADP_NOT_POSITIVE_DEFINITE, because the Debye-Waller factor then diverges at high Q. Free them with the phases.*.atoms.*.adp.* glob, alongside the biso glob every displacement stage carries.
Unit Å² · Typical 0.005-0.05 Å²
phases.*.microstrain.s*: Stephens strain coefficient. One S_HKL coefficient of the Stephens (1999) anisotropic strain model, multiplying the literal monomial h^H k^K l^L. Coefficients are in 10⁻¹² Å⁻⁴ because the physical Å⁻⁴ values near 10⁻⁸ would be finite-differenced with a step 100 times their own size. Like the ADP components these are tied: the refined quantities are the microstrain.dof.k entries of the Laue-allowed subspace.
Unit 10⁻¹² Å⁻⁴ · Default 0.0 · Typical 0-500 for a sample with measurable anisotropic strain
phases.*.microstrain.dof.*: Stephens strain degree of freedom. One allowed direction of the Laue-permitted S_HKL subspace, derived from the space-group operators rather than tabulated. These are what refine; the fifteen s coefficients are tied to them. Seed an all-zero block onto the isotropic ray with Stage.strain_seed: at S = 0 the square root in the width has unbounded slope. Positivity of σ²(M) is a cone coupling all fifteen coefficients, so under the default solver it is reported by STEPHENS_STRAIN_NOT_POSITIVE rather than bounded. Read that flag as ‘these coefficients are not quotable’, not as evidence of anisotropy.
Typical the isotropic seed is ε²·[M²] for a strain ε of 1e-4 to 1e-3

Stage settings¶

One stage of a plan, as StageSpec serializes it. Staging is cumulative: a parameter freed in one stage keeps refining in every later one.

name: Stage name. A label for the stage. It appears in the stage table, in the history node this stage commits, and in any diagnostic that has to say where a finding came from.
turn_on: Parameters freed this stage. Dot-path globs freed when the stage starts, matched with fnmatch: phases.*.cell.* frees every cell parameter of every phase. Staging is cumulative, so a parameter freed here keeps refining in every later stage. Paths never contain brackets, because fnmatch reads them as a character class.
Default [] · Typical one or two globs per stage
max_iter: Iteration budget. Approximate solver iterations for this stage. The trust-region solver caps function evaluations rather than iterations, so the number is scaled by a measured worst-case rejection rate before it reaches the solver.
Default 100 · Typical 20-100
ftol: Stage termination tolerance. This stage’s own relative cost-decrease tolerance, overriding the plan’s schedule. Null takes it from the plan, which runs every stage but the last at intermediate_ftol and the last at the solver’s 1e-9. The record says what a stage ran at, never what it declared, so a cherry-pick replays what happened.
Default null · Typical leave null unless reproducing a specific run
lebail_cycles: Le Bail cycles per evaluation. How many intensity-partitioning cycles run before each solve in lebail mode. Ignored in rietveld and pawley modes, where intensities come from the structure or from the parameter vector.
Default 3 · Typical 3
seed: Softplus seed value. Lifts any softplus-floored parameter this stage frees to this value. A parameter sitting exactly at its floor has no gradient, so a stage that frees extinction without seeding it refines nothing. Use strain_seed for a Stephens block: that one has the opposite problem.
Default 0.0 · Typical 1e-4 to 1e-3 where a stage frees extinction
strain_seed: Stephens strain seed. Microstrain in ppm used to seed an all-zero Stephens block onto the isotropic ray. At S = 0 the square root in the width law has unbounded slope, which is the opposite pathology to a dead gradient and needs its own setting: seed reaches softplus entries only, and these coefficients are not softplus.
Unit ppm · Default 0.0 · Typical 100-1000 ppm where a stage frees an anisotropic strain block
restraint_weight_scale: Restraint weight. The c_w of S = S_y + c_w·S_G (McCusker eq 7), weighting the geometric restraints against the diffraction data for this stage. Hold it high early and reduce it as the model improves. 1.0 is the identity and is bit-identical to no scaling; 0.0 silences the rows without removing them, so the restraint count the statistics rest on cannot move mid-plan.
Default 1.0 · Typical 1-100 early, falling to 1 in the last stage
window_slack_deg: Window capture slack. Extra 2θ on each side of a reflection’s integration window, replacing the default. Declared by fits whose starting model may sit far from the data, such as the Le Bail validation an indexing candidate goes through. Null takes the default.
Unit deg 2θ · Default null · Typical leave null outside indexing validation

Plan presets¶

The named strategies refine(plan=...) accepts. Each lists the intensity modes it is meaningful in.

mccusker_default: Standard (profile only). The IUCr-guideline turn-on order (McCusker et al., 1999): scale + background, zero shift, cell, then the profile widths. Leaves every structural parameter fixed.
Modes rietveld · Typical The default first fit of a known structure, and the plan to reach for whenever a structural refinement has gone wrong — it converges the parameters everything else depends on.
mccusker_structural: Standard + structure. The standard order continued into the structure: coordinates as site-symmetry DOFs, then displacement parameters (biso or the anisotropic patterns, whichever each site declares), then preferred orientation, extinction and surface roughness where declared.
Modes rietveld · Typical A structure worth refining against data good enough to carry it. Run the profile-only plan first if the fit is not already close.
lab_bragg_brentano: Lab diffractometer (one pass). Bragg-Brentano flat-plate order: the sample displacement and transparency corrections join the zero shift, and the axial (Finger-Cox-Jephcoat) apertures refine with the widths.
Modes rietveld · Typical A single lab pattern with no instrument calibration to hand — it refines specimen and instrument effects together, so read the correlation guards before quoting a width.
lab_calibrate: Lab: calibrate on a standard. Step 1 of the two-step lab workflow. Refines the instrument profile and the position corrections on a line-position standard with its certified cell held fixed — which is what decorrelates zero shift, displacement and cell.
Modes rietveld · Typical On a standard (LaB6, Si, corundum), once per instrument configuration. Follow it with save_instrument_profile.
lab_sample_refine: Lab: refine a specimen. Step 2 of the two-step lab workflow. The instrument profile is held at its calibrated values and only the sample’s own broadening (size and strain, isotropic or Stephens-anisotropic) refines, instrument ⊕ sample.
Modes rietveld · Typical Any specimen measured on a calibrated instrument, and the only plan whose size/strain numbers mean what they say — an uncalibrated fit absorbs the instrument into them.
profile_only: Cell + profile, no structure. Background, zero shift, cell and widths only. In Le Bail mode the per-hkl intensities are extracted by iterated partitioning instead of being computed from a structure.
Modes lebail, rietveld · Typical A known cell with an unknown or untrusted structure — indexing checks, extracted intensities for structure solution, or a cell/width measurement you want independent of any structural model.
pawley_default: Pawley whole-pattern. The same order as the Le Bail plan, but the per-hkl intensities are refined inside the least squares, so they carry esds. Overlapped groups are conditioned by an equal-split restraint and come back flagged rather than confidently split.
Modes pawley · Typical Extracted intensities that need uncertainties — feeding structure solution or a peak-shape study. Read PAWLEY_OVERLAP_UNRESOLVED before using an intensity from an overlapped group.

Peak flags¶

What is known about one fitted line. Whether a flag also makes the line unusable as evidence of a lattice is served beside the vocabulary as unusable_flags, so no client re-derives it.

ghost_kbeta: Kβ contamination line. The line sits where the Kβ partner of a stronger reflection would be. It is excluded rather than stripped: Rachinger stripping redistributes the counting noise and biases what is left. The line is unusable as evidence of a lattice.
Chip Kβ ghost
ghost_tungsten: Tungsten contamination line. The line sits at a tungsten L emission position, which an aged tube with a contaminated anode produces. Excluded for the same reason as a Kβ ghost, and unusable.
Chip W ghost
excluded: Excluded by the caller. Someone removed this line by hand. It stays in the list so a report can say the line was seen and dropped, and it is not offered as evidence.
fit_failed: Group fit did not converge. The solve over this line’s group did not converge, so the position and σ on the row are the detection seed rather than a measurement. Unusable.
Chip fit failed
sigma_assumed: σ assumed, not fitted. The position uncertainty was supplied rather than measured, which is what happens to a list read from a publication or another program. The line is still evidence, and its σ already says how good it is, so it stays usable. Treat the precision as unknown rather than quoting it.
Chip σ assumed
unresolved_shoulder: Never separated from its neighbour. The component was kept in a group where it never moved half a FWHM away from its neighbour. It is less precise evidence rather than none, so it stays usable.
Chip shoulder
position_at_bound: Position refined to its bound. The fitted position reached the limit it was allowed to move from its seed, which means detection put the seed in the wrong place. The position is a bound, not a minimum.
Chip at bound
asymmetry_unmodelled: Asymmetry the shape does not carry. The residual over this line is asymmetric beyond what the fitted shape allows, so the position is biased towards the tail. Axial divergence at low 2θ is the usual cause.
Chip asymmetric
not_separable: Improves the group as a shape, not as a line. The component makes the group fit measurably better, but a nested fit without it is not refuted, so it is not evidence of a distinct reflection. It stays in the model, because removing it would bias the position of the line it sits on, and it is never offered to an indexing engine.
Chip not separable
background_extrapolated: Standing on extrapolated background. The line’s prominence is measured against a background level that was extrapolated rather than observed. That is real intensity which may not be a line. It is reported and not refused, because a consumer that can weigh the evidence should be given the chance.
Chip bkg extrapolated
axial_tail: Possibly a stronger line’s axial tail. A weak component within 3.5 fitted FWHM of a stronger group-mate, on the side axial divergence points: towards low 2θ below 90° and towards high 2θ above it. The screen is one-sided, because nothing else in a powder pattern flips sign at 90°. Reported and not refused, since a real line can coincide with a tail.
Chip axial tail
kalpha2_residual: Sitting on a modelled Kα2 maximum. The component sits at the Kα2 position of a stronger group-mate, predicted from the declared doublet splitting as δ(2θ) = 2·(λ₂/λ₁ − 1)·tanθ rather than found by a distance threshold. It is the residual of a doublet the model already carries. Reported and not refused, since a real line can coincide with it.
Chip Kα2 residual
unnamed_neighbour: An unnamed component shares this window. You named the components in this window, and detection found another one you did not name. Its intensity had nowhere to go but into the components that were fitted, so their positions are biased towards it and χ²_red is the only other sign. Reported and not refused: naming a subset is a legitimate request, and the esd inflation by the square root of χ²_red already carries the cost. Name the neighbour too, or narrow the range, if the position matters.
Chip unnamed neighbour
no_intensity: Refined to zero intensity. The component reached its zero-intensity bound, so it contributes nothing to the window and its own position is no longer identifiable: a peak reaches the data only through intensity times profile. Unusable, and unlike the reported flags there is no judgement left to make.
Chip no intensity

Peak-list diagnostics¶

Messages about the list rather than about one line. Several are the list-level summary of a flag and say how many lines carry it.

PEAK_LIST_TOO_SHORT: Too few usable lines to index. The list has fewer usable lines than an indexing search needs. The classical figures of merit are also undefined below that count, which caps confidence rather than refuting any cell. Widen the 2θ range, count for longer, or lower the detection threshold and check what arrives.
PEAK_SIGMA_ASSUMED: Position uncertainties were assumed. Some or all lines carry an assumed σ(2θ) rather than a fitted one, which is what a list of bare positions produces. Downstream gates treat the precision as unmeasured.
PEAK_UNRESOLVED_SHOULDER: Components that never separated. Lines were kept in groups where they stayed within half a FWHM of a neighbour. Their positions are correlated with their neighbours’ and are less precise than their σ alone suggests.
PEAK_NOT_SEPARABLE: Components refuted as distinct lines. Components improved their group’s fit but did not survive the nested comparison against a fit without them. They stay in the model and are withheld from indexing.
PEAK_ASYMMETRY_UNMODELLED: Asymmetry the peak shape does not carry. Lines show asymmetric residuals beyond the fitted shape, so their positions are pulled towards the tail. Declaring the axial divergence terms is the usual fix.
PEAK_AXIAL_TAIL: Weak lines that may be axial tails. Weak components lie within 3.5 FWHM of a stronger group-mate on the side axial divergence points. They may be real lines and are reported rather than removed.
PEAK_KALPHA2_RESIDUAL: Components on a modelled Kα2 maximum. Components sit where the Kα2 partner of a stronger line is already modelled, so they are that doublet’s residual rather than new lines. Reported rather than removed.
PEAK_KALPHA2_ALIAS: Kα2 candidates dropped before fitting. Detection found candidates at the Kα2 positions of stronger lines and dropped them before any fit. The drop is reported because a genuine weak line can alias onto one.
PEAK_CONTAMINATION_LINE: Contamination lines excluded. Lines were identified as Kβ or tungsten emission and excluded. They are excluded and never stripped, because stripping redistributes the counting noise.
PEAK_SHOULDER_SEEDED: Extra components seeded from the residual. The width census found groups wider than the instrument’s own law allows, so extra components were seeded into them from the residual. Check that the added lines are real before indexing on them.
PEAK_WIDTH_LAW_MISMATCH: Fitted widths disagree with the instrument. The fitted widths do not follow the declared instrumental width law. Either the specimen is broadened, which is a finding, or the declared instrument is wrong, which is a setup error. The message carries the ratio so the two can be told apart.
PEAK_POSITION_PRECISION: Position precision relative to the line spacing. States the measured position precision against what an indexing search needs. A cell search matches within an assumed systematic allowance rather than within σ, so this is context for reading a search result, not a refusal.

Peak origins¶

Where one line came from: detection, or a person. Provenance and not a judgement; no gate in the package branches on it.

fitted: Proposed by detection. Detection found a maximum or a shoulder here and the group fit kept it. Nobody has touched the line: its position, width and area are the fitter’s, and so are its flags.
manual: Placed by a person. Someone added this line by clicking the plot or typing a 2θ. Its position was still fitted, within the group it landed in, but the decision that a line exists here is a person’s, so the picker’s own screens never remove it.
edited: Moved by a person. Detection proposed this line and a person dragged it or typed a new 2θ; the group was refitted from the new seed. The position shown is the refit’s, not the pointer’s.
Chip moved

Reader options¶

Keyword arguments read_pattern accepts. A project records which ones claimed its file, because the same file can hold more than one pattern.

block: Data block. Which block of a multi-block file to read, matched by substring on the block name. A pdCIF carrying both a _meas and a _calc block is a different pattern depending on this, which is why the project records the option beside the file rather than only the file name.
Typical _meas for measured data in a pdCIF
scan: Scan index. Which measurement to read from a file holding several, counting from 0. A vendor file commonly stores a whole session. Scans are selected and never concatenated: a multi-range file holds separate measurements, and joining them mixes two weighting regimes.
Default 0 · Typical 0 unless a preview reports more than one scan

Instrument preset fields¶

Constructor arguments for building an instrument from a geometry and an anode. These are not parameter paths and none of them is refined.

radiation: Anode. Which tube anode the pattern was measured with. It selects the Kα1 and Kα2 wavelengths from the package’s NIST-scale table and the doublet weight, so it is the one entry a cell error of about 100 ppm hides behind. Read it off the instrument rather than guessing from the peak positions.
Typical CuKa, MoKa, CoKa, CrKa, FeKa, AgKa, or the …Ka1 variant of any of them for a Kα1-only beam
wavelength: Wavelength. The incident wavelength, asked for by the Debye-Scherrer preset because it is the one geometry with no anode to read it from. A synchrotron or neutron beamline states it in the data file or the beamline record.
Unit Å · Typical 0.3-1.0 Å synchrotron, 1.0-2.5 Å constant-wavelength neutron
polarization: Polarization. The K of the Lorentz-polarisation correction. Only the Debye-Scherrer preset takes it, and leaving it empty there gives 0.99, the APS 11-BM instrument-parameter value, not the 0.5 of an unpolarised laboratory beam. Neither flat-plate preset has the field: Bragg-Brentano derives K from monochromator_two_theta and transmission is unpolarised, K = 0.5.
Typical 0.99 is the preset default; 0.5 is an unpolarised lab beam
goniometer_radius_mm: Goniometer radius. The radius of the 2θ circle. The specimen-displacement shift divides by it (McCusker eq 3), so declaring it is what turns a refined displacement into millimetres instead of an arbitrary coefficient.
Unit mm · Typical 217.5 mm is a common benchtop value and the default
monochromator_two_theta: Monochromator 2θ. The take-off angle of a diffracted-beam monochromator crystal, which fixes the polarisation factor as cos²2θ_M. Leave it empty if there is no monochromator.
Unit deg · Typical 26.6° for graphite (002) at Cu Kα
ka2_ratio: Kα2 to Kα1 ratio. The intensity of the Kα2 line relative to Kα1. 0.5 is the 2j+1 degeneracy ratio and is the right starting value for every anode. Change it only when a monochromator or a filter has altered the doublet.
Default 0.5 · Typical 0.5
capillary_radius_mm: Capillary radius. The internal radius of the capillary bore, not its outside diameter. It is an input to estimating µR and never a refined quantity.
Unit mm · Typical 0.1-0.5 mm
packing_fraction: Packing fraction. The fraction of the bore or the specimen slab occupied by solid. An input to estimating µR and µt, never refinable. 0.3-0.6 covers a tapped powder and 0.64 is random close packing of spheres.
Default 0.6 · Typical 0.3-0.6
mu_r: µR. The capillary absorption parameter, the linear attenuation coefficient times the bore radius. Leave it empty for no correction: µR = 0 is the off state. It is not refinable, because it is exactly a reparameterisation of the phase scale and the displacement parameters, so the fit statistic cannot move. Its entire content is a shift of every B by c(µR)·λ²/2.
Typical 0-1 for a typical capillary mount
mu_t: µt. The flat-plate absorption parameter, the linear attenuation coefficient times the specimen thickness. The off state belongs to the geometry. On a Bragg-Brentano mount leaving it empty is the thick specimen, and µt = 0 there is a specimen of no thickness and is refused. In transmission µt = 0 is legal and is what empty means: a non-absorbing plate, still carrying the sec θ footprint factor. Declaring a thickness wrongly on a genuinely thick specimen makes the fit worse and biases every B downwards.
Typical empty for a thick reflection specimen; 1-5 for a thin transmission mount
thickness_mm: Specimen thickness. For a reflection mount, the depth of the powder layer and not the depth of the holder. An input to estimating µt only. Leave it empty for a thick specimen.
Unit mm · Typical 0.1-2 mm for a transmission mount

Indexing search settings¶

The controls an indexing search takes, as ProjectDoc.indexing holds them. Several bound the search rather than describing the specimen, and each says what a negative result means once it has bitten.

systems: Crystal systems to search. Which crystal systems the search covers, run in decreasing symmetry so a cubic answer arrives in seconds and a triclinic one in minutes. Restricting them is not a verdict about the specimen: the result reports the systems it searched, and says nothing about the ones it did not.
Typical all seven; narrow only when a prior tells you the system
centrings: Bravais centrings. Which lattice centrings to try within each system. Unticking one narrows the search and is recorded in the result’s spec notes. At least one must stay in every system being searched.
Typical all of them; a wrongly excluded centring costs the true cell
preset: Search preset. The name of the whole-run ceiling. quick, the default, runs every engine and system under a measured ceiling and reports truncation loudly. full is unbounded. A typed whole-run budget overrides the preset and the result records custom.
Typical quick for a first look, full when the answer matters
total_budget_seconds: Whole-run budget. Wall-clock ceiling for the whole run: search, probe and validation together. Empty leaves it to the preset. Setting it overrides the preset’s ceiling and the result records the preset as custom.
Unit s · Typical empty; a few minutes if you are bounding an interactive click
budget_seconds: Budget per search slice. Wall clock for one engine on one crystal system, not for the run. An engine stopped by it reports that system as incomplete, and a negative result from an incomplete search is not evidence against a cell.
Unit s · Default 30.0 · Typical 30 s; raise it for a triclinic search you intend to trust
min_d_axis: Shortest principal d-spacing. The shortest principal d-spacing a candidate cell may have. It bounds d(100) rather than the axis a, which is slightly stronger for an oblique cell.
Unit Å · Default 2.0 · Typical 2 Å for an inorganic phase
max_d_axis: Longest principal d-spacing. The longest principal d-spacing a candidate cell may have. Raising it costs exponentially, because the size of the domain is what an exhaustive search pays for.
Unit Å · Default 25.0 · Typical 25 Å; raise it only for a genuinely large cell
min_volume: Smallest cell volume. The smallest cell volume a candidate may have. It removes the degenerate small cells that index a few lines by coincidence.
Unit Å³ · Default 15.0 · Typical 15 Å³
max_volume: Cell-volume ceiling. The largest cell volume a candidate may have, taken verbatim. Empty takes Smith’s per-system envelope from the data-quality report, with the calibration slack the engines apply to a mean line.
Unit Å³ · Typical empty; state it only when you know the volume
n_unindexed: Unindexed lines allowed. How many search lines a cell may leave unindexed and still be accepted. Raising it manufactures cells: every tolerated line is one more coincidence a wrong metric is allowed. Two is a default; four is a statement about the specimen.
Default 2 · Typical 2, or up to 4 on a pattern with a known impurity
n_search_lines: Lines the search is driven by. How many of the strongest observed lines drive the search. It is not free to raise: a cell must index all but the allowance of these, so every extra foreign line can refute the true cell. Measured on a 68-line list, the certified lattice is lost at 32.
Default 20 · Typical 20; the tail of a list is where foreign lines live
k_sigma: Matching window in σ. The matching window, in units of each line’s own σ. Three is a 99.7 % window and a calibrated figure rather than a knob. The systematic allowance below is the other half of the window, and it is the half a displaced pattern needs.
Default 3.0 · Typical 3
shift_allowance_deg: Systematic 2θ allowance. A systematic 2θ allowance you have measured: the amplitude a matching window has to span, never the residual scatter a template leaves after fitting. The two differ by 4.3× on a certified pattern, and declaring the scatter finds no cell at all. Zero lets the engines assume their own allowance and caps the confidence they may report.
Unit deg 2θ · Default 0.0 · Typical 0 unless an internal standard measured the shift
shift_template: Shift template. The physical cause of the 2θ shift, if you know it. A candidate that survives the search is re-fitted with this column, which is what stops a widened search reporting a biased cell.
Typical cos_theta for specimen displacement, constant for a zero error
max_candidates: Candidates reported. How many candidates the reported list holds once the engines are merged and ranked. It also prices validation, since every reported candidate costs a Le Bail fit. Each engine hands the merge five times this many, so the cap never decides a rank.
Default 12 · Typical 12
seed: Random seed. The stochastic engine’s RNG seed. It is recorded in every result, so a run is reproducible from what it reports.
Default 0 · Typical 0
prior_cells: Analogue cells. Cells from a structural analogue, each as a b c α β γ. The system jumps the queue, the metric seeds the stochastic engine, and the cell itself is checked against the lines. A prior steers and never gates: a wrong one costs time rather than truth, and the result records what it changed.
Typical empty; one analogue cell when the chemistry suggests one
prior_spacegroups: Analogue space groups. Space-group symbols from a structural analogue, such as R -3 c. Each contributes its crystal system to the queue jump and, beside a matching prior cell, its centring.
Typical empty
engines: Engines to run. Which searches run. All of them is the default to keep, because high confidence means every engine that ran found the same lattice: a subset narrows what the answer is able to say.
Typical all of them
validate_candidates: Le Bail validation. Whole-profile validation of the top candidates. Turning it off caps every candidate at medium confidence, because the figure-of-merit panel cannot see a reflection predicted where the pattern has no intensity. Do it only to save time on a first look.
Default true · Typical on
check_top: Candidates given the expensive checks. How many candidates get the per-candidate checks, which are the ambiguity search and the Le Bail fit. Empty takes the package default plus every candidate the confidence gate could promote.
Typical empty