Stage settings, flags and options

This page lists the names rietx uses besides its parameters, plans, diagnostic codes and result fields: stage settings, peak flags, peak origins, reader options, instrument preset fields and indexing search settings.

The entries are generated from rietx.help, the one place each is written. The GUI puts the same sentence beside the same control, so this page and a tooltip cannot disagree. Parameters are on the parameter map, plans on Plan presets, diagnostic codes on Diagnostic codes and result fields on Result fields.

Looking one up in code

help_for takes a parameter name and returns the entry whose family claims it. It matches with fnmatch, as a stage’s turn_on patterns 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 name outside the parameter vocabulary returns None rather than a guess.

help_key_for returns the family’s pattern itself rather than the entry. Refinement.parameters() puts that pattern on every row as ParameterRow.help_key. A row carries the key and not the entry because an entry describes a family, so a copy on each row would repeat 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 data that converts to JSON, and the GUI’s GET /api/help serves it. Each object in its parameters list names every pattern that reaches it, so a help_key is looked up there.

import rietx as rx

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

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

rietx.help.explain looks up a diagnostic code or a result field, as Result fields shows.

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 has no unit. tests/test_help.py pins it against the schema’s own Parameter.unit.

HelpEntry.default

The value the schema starts from, as a string, or None where there is none. A lattice parameter has no default because it arrives with the structure. The test pins this against the schema too.

HelpEntry.typical

A range to check a refined number against. It is guidance and not a bound, and nothing in the package reads it. 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.

HelpEntry.anchor

The page and heading of this manual that carry the explanation, as page.html#heading-id, such as theory/corrections.html#surface-roughness. It is relative to the manual of the running version, rietx._about.docs_base, which is what the GUI joins it to. tests/test_help.py checks each one against this manual’s 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 entries carry one, and every entry there must. It is None elsewhere, where no chip is drawn.

Stage settings

One stage of a plan, as StageSpec serialises 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 that the stage commits and in any diagnostic that says where a finding came from.

turn_on

Parameters freed this stage. Wildcard patterns for the parameter paths that the stage frees when it starts. For example, phases.*.cell.* frees every lattice parameter of every phase. Staging is cumulative, so a parameter freed here keeps refining in every later stage. Paths contain no square brackets, because the matching reads brackets as a character class.

Default [] · Typical one or two patterns per stage

max_iter

Iteration budget. The approximate number of solver iterations for this stage. Both solvers cap function evaluations, so the number is scaled by a measured worst-case rejection rate (NFEV_PER_ITERATION) before it reaches the solver.

Default 100 · Typical 20-100

ftol

Stage stopping tolerance. This stage’s own relative tolerance on the decrease in cost. It overrides the plan’s schedule. Empty takes the value from the plan: every stage but the last stops at the plan’s intermediate_ftol, and the last stops at the solver’s 1e-9. The history records the tolerance a stage ran at and not the one it declared, so a cherry-pick replays what happened.

Default null · Typical leave empty unless reproducing a specific run

lebail_cycles

Le Bail cycles. How many cycles of intensity partitioning run before each solve in lebail mode. The setting is ignored in rietveld and pawley modes, where the intensities come from the structure or from the fitted Pawley intensities.

Default 3 · Typical 3

seed

Starting value for parameters at zero. Sets the starting value of every parameter that the stage frees and that sits exactly on a lower bound of 0 or above. A parameter that can go negative is never seeded. The Suortti roughness correction is the identity at b = 0, so the roughness stage uses this to start b near where the data can see it. That is the only shipped stage that seeds. For a Stephens strain block use strain_seed, which has the opposite problem.

Default 0.0 · Typical 0.3 where a stage frees surface roughness; 0 elsewhere

strain_seed

Stephens strain seed. Microstrain in ppm that starts an all-zero Stephens block on the isotropic limit. At S = 0 the square root in the width law has unbounded slope, so the block needs a starting value of its own. seed cannot do this, because it reaches only parameters bounded below at 0 and these coefficients can go negative.

Unit ppm · Default 0.0 · Typical 100-1000 ppm where a stage frees an anisotropic strain block

restraint_weight_scale

Restraint weight. The weight c_w in S = S_y + c_w·S_G (McCusker et al. 1999, equation 7). It sets how strongly the geometric restraints count against the diffraction data in this stage. Hold it high early and reduce it as the model improves. A value of 1.0 leaves the restraints unscaled. A value of 0.0 silences them without removing them, so the restraint count behind the statistics cannot change mid-plan.

Default 1.0 · Typical 1-100 early, falling to 1 in the last stage

window_slack_deg

Peak window margin. Extra 2θ on each side of a reflection’s integration window, replacing the default (WINDOW_MIN_DEG). A fit whose starting model may sit far from the data declares it, such as the Le Bail validation that an indexing candidate goes through. Empty takes the default.

Unit deg 2θ · Default null · Typical leave empty outside indexing validation

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 neither the GUI nor a script works it out again.

position_unmeasured

Position never determined. The fit gave this line’s position an uncertainty of 180° or more, the whole span of a 2θ axis. That is no position at all, and any window built from it matches whatever it is compared with. The line stays in the list so a report can say why it went. It is excluded from everything that matches positions.

Chip no position

ghost_kbeta

Kβ line of a stronger reflection. The line sits where the Kβ partner of a stronger reflection would be, and several other strong reflections carry a partner at the same intensity ratio. That agreement is the evidence. A single line at a predicted position is a coincidence and is not flagged. The line is excluded and Rachinger stripping is not applied, because 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 L line from the tube. The line sits at a tungsten L emission position, which an aged tube with a contaminated anode produces. Such lines are flagged jointly, as Kβ lines are, and excluded for the same reasons. The line is unusable.

Chip W ghost

excluded

Removed by hand. Someone removed this line by hand. It stays in the list so a report can say the line was seen and dropped. It is not offered as evidence.

fit_failed

Group fit did not converge. The fit over this line’s group of peaks did not converge. The position and σ on the row are the starting values from peak detection, so they measure nothing. The line is unusable.

Chip fit failed

sigma_assumed

Position uncertainty assumed. The position uncertainty was supplied and not measured. This happens to a list read from a publication or from another program. The line is still evidence, and its σ says how good it is, so it stays usable. Treat the precision as unknown and do not quote 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 weaker evidence than a resolved line but still evidence, so it stays usable.

Chip shoulder

position_at_bound

Position refined to its limit. The fitted position reached the limit on how far it could move from its starting value. That means peak detection put the starting value in the wrong place. The reported position is the limit itself, and the fit did not find a minimum there.

Chip at bound

asymmetry_unmodelled

Asymmetry the peak shape cannot fit. The residual over this line is asymmetric beyond what the fitted peak 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 fit as a shape only. The component improves the fit of its group, but the fit without it cannot be ruled out, so there is no evidence of a distinct reflection. It stays in the model because removing it would bias the position of the line it sits on. 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 and not observed. The intensity is real but may not belong to a line. The line stays usable, so you can weigh the evidence yourself.

Chip bkg extrapolated

axial_tail

Possibly a stronger line’s axial tail. A weak component lies within 3.5 fitted FWHM (PEAK_AXIAL_TAIL_MAX_FWHM) of a stronger component in its group, on the side that axial divergence points to. That side is low 2θ below 90° and high 2θ above it. The screen looks on one side only, because nothing else in a powder pattern flips sign at 90°. The line stays usable, 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 component in its group. The position is predicted from the declared doublet splitting as δ(2θ) = 2·(λ₂/λ₁ − 1)·tanθ and is not found by a distance threshold. It is the residual of a doublet that the model already carries. The line stays usable, 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 peak detection found another that you did not name. Its intensity went into the components you fitted, so their positions are biased towards it. Reduced χ² is the only other sign. The line stays usable, because naming a subset is a legitimate request and the esd inflation by the square root of reduced χ² 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, or its fitted intensity is smaller than its own esd. It contributes nothing measurable to the window, and its position cannot be identified, because a peak reaches the data only through intensity times profile. The line is unusable. Unlike the flags that leave a line usable, there is no judgement left to make.

Chip no intensity

duplicate_line

Line another group already fitted. This component sits on a line that a neighbouring group fitted with a better-measured component, so it is one physical peak fitted twice. The copy stays in the list because it let its own group’s window fit. It is unusable, because a list that offers one line twice gives a second line that no candidate cell explains.

Chip duplicate

weak_line

Below the false-discovery bar. The component’s fitted intensity over its esd is below the bar set by the pattern’s own false-discovery rate (Benjamini-Hochberg at q = 0.01, PEAK_FDR_Q, over the pattern’s resolution elements). The list cannot tell such a line from noise at the rate it promises for every other line. It stays usable, because on real laboratory data many such lines are weak reflections that the true cell indexes. The flag is evidence to weigh and is no verdict. A search is never driven by it, though: the line is scored like any usable one, but an accepted cell need not index it. A line you placed by hand is never tested.

Chip weak

unresolved_split

Split the data cannot resolve. This component sits closer to a comparable neighbour in its group than two lines of the fitted shape can and still show a dip between them. The data tell the pair apart only through the peak shape, so the pair is reported as one line. That line is the stronger component, with its position uncertainty widened to reach this one. This component stays in the list and is unusable.

Chip split

width_capped

Width ran into its bound. The fit tried to make this group broader than the limit of five times the pattern’s own width law at that angle (PEAK_WIDTH_BOUND_FACTORS). It is a hump, such as background that the envelope did not follow, and is not a line of the phase that set the width law. It stays in the list and is unusable.

Chip too wide

Peak origins

Where one line came from: detection, or a person. It records provenance and makes no judgement, and no gate in the package branches on it.

fitted

Found by peak detection. Peak detection found a maximum or a shoulder here and the group fit kept it. Nobody has touched the line. Its position, width and area come from the fit, and so do its flags.

manual

Placed by a person. Someone added this line from the plot or by typing a 2θ. Its position was still fitted, within the group it landed in. A person decided that a line exists here, so the peak picker’s own screens never remove it.

edited

Moved by a person. Peak detection proposed this line, and a person dragged it or typed a new 2θ. The group was refitted from the new starting position. The position shown comes from the refit and can differ from where you put the line.

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.

bank

Detector bank. Which detector bank of a GSAS file to read, given as the number in the file’s own BANK record. The instrument-parameter file uses the same number for its per-bank records. A bank is a detector and not a scan. It has its own scattering angle, its own DIFC, DIFA and zero calibration, and its own resolution. A time-of-flight diffractometer is several banks (ISIS GEM writes six). A file with more than one bank is refused until you name one, because answering with the first would choose for you.

Typical unset for a single-bank file; the bank’s own number otherwise

block

Data block. Which block of a multi-block file to read, matched against part of the block name. A pdCIF with both a _meas block and a _calc block gives a different pattern for each. The project therefore records this option beside the file name.

Typical _meas for measured data in a pdCIF

scan

Scan index. Which measurement to read from a file that holds several, counting from 0. A vendor file often stores a whole session. The scans of a multi-range file are separate measurements, so rietx reads one of them and never joins them. Joining would mix 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. They are not parameter names, and none of them is refined.

radiation

Anode. The tube anode that the pattern was measured with. It selects the Kα1 and Kα2 wavelengths from the package’s NIST-scale table, and the weight of the doublet. An error of about 100 ppm in the cell can hide behind this setting. Read it off the instrument, because the peak positions cannot tell you.

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. The Debye-Scherrer preset asks for it because that geometry has 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

Polarisation factor. The factor K of the Lorentz-polarisation correction (lorentz_polarization). Only the Debye-Scherrer preset takes it. Left empty there, it is 0.99, the APS 11-BM instrument-parameter value, and 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 with 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 et al. 1999, equation 3). Declaring it turns a refined displacement into millimetres. Without it the displacement is an arbitrary coefficient.

Unit mm · Typical 217.5 mm is a common laboratory value and the default

monochromator_two_theta

Monochromator 2θ. The take-off angle of a diffracted-beam monochromator crystal. It fixes the polarisation factor K at 1/(1 + cos²2θm), which is 0.556 for graphite (002) at Cu Kα. Instrument.bragg_brentano does that conversion. Leave it empty if there is no monochromator, which gives the unpolarised K = 0.5. The angle 26.6° belongs to Cu Kα. Graphite (002) diffracts other anodes at other angles, so compute it for your anode.

Unit deg · Typical 26.6° for graphite (002) at Cu Kα; 9.6-39.9° for the same crystal from Ag Kα to Cr 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 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 radius of the capillary bore, measured inside the glass. It is an input for estimating µR and is never refined.

Unit mm · Typical 0.1-0.5 mm

packing_fraction

Packing fraction. The fraction of the bore, or of the specimen slab, that solid occupies. It is an input for estimating µR and µt and is never refined. A tapped powder falls at 0.3-0.6, and random close packing of spheres is 0.64.

Default 0.6 · Typical 0.3-0.6

mu_r

µR. The capillary absorption parameter. It is the linear attenuation coefficient times the bore radius. Leave it empty for no correction, because µR = 0 is the off state. It cannot be refined. It is exactly a reparameterisation of the phase scale and the displacement parameters, so the fit statistic cannot move. Its whole effect 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. It is the linear attenuation coefficient times the specimen thickness. What an empty value means depends on the geometry. On a Bragg-Brentano mount, empty is a thick specimen. There µt = 0 is a specimen of no thickness, and it is refused. In transmission, µt = 0 is legal and means a non-absorbing plate that still carries the sec θ footprint factor. Declaring a thickness for 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, excluding the holder. It is an input for 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. They run in decreasing symmetry, so a cubic answer arrives in seconds and a triclinic one in minutes. Restricting the systems says nothing about the specimen. The result lists the systems it searched and makes no claim about the others.

Typical all seven; narrow only when a prior tells you the system

centrings

Bravais centrings. Which lattice centrings to try within each system. Clearing one tick narrows the search, and the result records it. At least one must stay ticked in every system you search.

Typical all of them; a wrongly excluded centring costs the true cell

preset

Search preset. The named ceiling on the whole run. quick, the default, runs every engine and system under a measured ceiling and reports any truncation prominently. full has no ceiling. A whole-run budget that you type overrides the preset, and the result then records custom.

Typical quick for a first look, full when the answer matters

total_budget_seconds

Whole-run budget. Wall-clock ceiling on the whole run, covering search, probe and validation together. Empty leaves the ceiling to the preset. A value here overrides the preset’s ceiling, and the result records the preset as custom.

Unit s · Typical empty; a few minutes to bound an interactive run

budget_seconds

Time per engine and system. Wall-clock time for one engine on one crystal system. It does not bound the whole run. An engine that this limit stops reports that system as incomplete. A negative result from an incomplete search is no 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). For an oblique cell that is slightly stronger than a bound on the axis a.

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 domain grows and an exhaustive search covers all of it.

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 tiny cells that index a few lines by coincidence.

Unit ų · Default 15.0 · Typical 15 ų

max_volume

Largest cell volume. The largest cell volume a candidate may have, used exactly as you give it. Empty takes the per-system envelope of Smith (1977) from the data-quality report, with the calibration slack that 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. Empty (the default) is two. A run where no two engines agree on a lattice is searched again accepting a cell that indexes 60 % of the search lines and the five strongest; 'inliers' searches that way from the start. A number forbids the retry. Raising it manufactures cells, because every tolerated line is one more coincidence that a wrong metric is allowed. Four is a statement that you know something about the specimen, such as an impurity.

Typical empty; 'inliers' on a pattern with a known impurity

n_search_lines

Lines that drive the search. How many of the strongest observed lines drive the search. Raising it is not free. A cell must index all but the allowance of these lines, so every extra foreign line can refute the true cell. On a 68-line list the certified lattice is lost at 32.

Default 20 · Typical 20; foreign lines live in the tail of a list

k_sigma

Matching window in σ. The matching window in units of each line’s own σ. Three is a calibrated 99.7 % window and needs no tuning. The systematic 2θ allowance is the other half of the window, and a displaced pattern needs that half.

Default 3.0 · Typical 3

shift_allowance_deg

Systematic 2θ allowance. A systematic 2θ allowance that you have measured. It is the amplitude that the matching window has to span. The residual scatter left after fitting a template is a different quantity. 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 refitted with this correction. The refit stops a widened search from reporting a biased cell.

Typical cos_theta for specimen displacement, constant for a zero-point shift

max_candidates

Candidates reported. How many candidates the final list holds after the engines are merged and ranked. It also sets the validation cost, since every reported candidate needs a Le Bail fit. Each engine hands five times this number to the merge, so the cap never decides a rank.

Default 12 · Typical 12

seed

Random seed. The seed of the stochastic engine’s random number generator. Every result records it, so you can reproduce a run from what it reports.

Default 0 · Typical 0

prior_cells

Analogue cells. Cells from a structural analogue, each given as a b c α β γ. The cell’s crystal system moves to the front of the queue, its metric seeds the stochastic engine, and the cell itself is checked against the lines. A prior steers the search. A wrong one costs time and cannot rule out the true cell, 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 moves its crystal system to the front of the queue and, beside a matching prior cell, supplies its centring.

Typical empty

engines

Engines to run. Which searches run. Keep the default of all of them. High confidence means that every engine that ran found the same lattice, so a subset narrows what the answer can 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. Turn it off only to save time on a first look.

Default true · Typical on

check_top

Candidates checked in depth. How many candidates get the per-candidate checks: the ambiguity search and the Le Bail fit. Empty takes the package default plus every candidate that the confidence gate could promote.

Typical empty