Plan presets#
A plan preset is a named list of stages, and this page draws each one from the plan objects rietx runs.
A stage frees the parameters its globs match.
Staging is cumulative, so each stage refines with every earlier stage’s parameters still free.
Pass a preset by name, as fit(plan="lab_calibrate"), or build one with RefinementPlan and edit its stages list.
Preset |
Title |
Modes |
Stages |
|---|---|---|---|
Standard (profile only) |
|
5 |
|
Standard + structure |
|
11 |
|
Lab diffractometer (one pass) |
|
7 |
|
Lab: calibrate on a standard |
|
6 |
|
Lab: refine a specimen |
|
6 |
|
Cell + profile, no structure |
|
5 |
|
Pawley whole-pattern |
|
5 |
|
Magnetic broadening (three steps) |
|
3 |
Under lebail, mccusker_default runs as profile_only.
Under pawley, mccusker_default runs as pawley_default.
Every stage before the last stops at ftol = 1e-06. The last runs to the solver’s own tolerance.
mccusker_default#
The IUCr guideline’s turn-on order (McCusker et al., 1999). It frees the scale and background, then the zero shift, then the lattice parameters, then the profile widths. Every structural parameter stays fixed.
The first fit of a known structure. Return to it whenever a structural refinement has gone wrong, because it converges the parameters everything else depends on.
flowchart TB
s0["scale_bkg<br>phases.\*.scale<br>instrument.background.\*"]
s1["zero<br>instrument.zero_shift"]
s2["cell<br>phases.\*.cell.\*"]
s3["profile_w<br>instrument.profile.w"]
s4["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s0 --> s1 --> s2 --> s3 --> s4
mccusker_structural#
The standard order continued into the structure. It frees the atomic coordinates along the directions the site symmetry leaves free. Displacement parameters follow (Biso, or the anisotropic tensor each site declares). Then come preferred orientation (March-Dollase or spherical-harmonics texture), extinction and surface roughness, where the structure declares them.
A structure worth refining against data good enough to carry it. Run the profile-only plan first if the fit is not already close.
flowchart TB
s0["scale_bkg<br>phases.\*.scale<br>instrument.background.\*"]
s1["zero<br>instrument.zero_shift"]
s2["cell<br>phases.\*.cell.\*"]
s3["profile_w<br>instrument.profile.w"]
s4["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s5["extra_components<br>instrument.extra_components.\*"]
s6["coordinates<br>phases.\*.atoms.\*.dof.\*"]
s7["biso<br>phases.\*.atoms.\*.biso<br>phases.\*.atoms.\*.adp.\*"]
s8["preferred_orientation<br>phases.\*.preferred_orientation.r<br>phases.\*.texture.\*"]
s9["extinction<br>phases.\*.extinction"]
s10["roughness<br>instrument.geometry.surface_roughness.\*<br>seed = 0.3"]
s0 --> s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10
lab_bragg_brentano#
Bragg-Brentano flat-plate order. The specimen displacement and transparency corrections join the zero shift. The axial (Finger-Cox-Jephcoat) apertures refine with the widths.
A lab pattern where something outside the fit pins the zero shift or the specimen displacement, such as a calibrated goniometer or an internal standard. This plan frees both in one stage. Unpinned, they are collinear with the lattice parameters. On one uncalibrated pattern, use mccusker_default or mccusker_structural, which free the zero shift alone. This plan refines specimen and instrument effects together, so read the correlation guards before quoting a width.
flowchart TB
s0["scale_bkg<br>phases.\*.scale<br>instrument.background.\*"]
s1["zero_disp<br>instrument.zero_shift<br>instrument.geometry.sample_displacement"]
s2["cell<br>phases.\*.cell.\*"]
s3["profile_w<br>instrument.profile.w"]
s4["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s5["lines_axial<br>instrument.source.lines.\*.weight<br>instrument.geometry.axial_sl<br>instrument.geometry.axial_hl"]
s6["roughness<br>instrument.geometry.surface_roughness.\*<br>seed = 0.3"]
s0 --> s1 --> s2 --> s3 --> s4 --> s5 --> s6
lab_calibrate#
Step 1 of the two-step lab workflow. It refines the instrument profile and the position corrections on a line-position standard with its certified lattice parameters held fixed. Holding them fixed decorrelates the zero shift, the specimen displacement and the lattice parameters from one another.
A standard (LaB6, Si or corundum), once per instrument configuration. Follow it with save_instrument_profile.
flowchart TB
s0["scale_bkg<br>phases.\*.scale<br>instrument.background.\*"]
s1["zero_disp<br>instrument.zero_shift<br>instrument.geometry.sample_displacement"]
s2["profile_w<br>instrument.profile.w"]
s3["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s4["lines_axial<br>instrument.source.lines.\*.weight<br>instrument.geometry.axial_sl<br>instrument.geometry.axial_hl"]
s5["biso<br>phases.\*.atoms.\*.biso<br>phases.\*.atoms.\*.adp.\*"]
s0 --> s1 --> s2 --> s3 --> s4 --> s5
lab_sample_refine#
Step 2 of the two-step lab workflow. The instrument profile stays at its calibrated values. Only the specimen’s own broadening refines (size and strain, isotropic or Stephens-anisotropic). It combines with the instrument’s by adding Gaussian variances and Lorentzian widths.
Any specimen measured on a calibrated instrument. This is the only plan whose size and strain values mean what they say, because an uncalibrated fit absorbs the instrument into them.
flowchart TB
s0["scale_bkg<br>phases.\*.scale<br>instrument.background.\*"]
s1["disp<br>instrument.geometry.sample_displacement"]
s2["cell<br>phases.\*.cell.\*"]
s3["sample_profile<br>phases.\*.lor_size<br>phases.\*.lor_strain<br>phases.\*.gauss_size<br>phases.\*.gauss_strain<br>phases.\*.microstrain.dof.\*<br>strain_seed = 1000.0"]
s4["biso<br>phases.\*.atoms.\*.biso<br>phases.\*.atoms.\*.adp.\*"]
s5["roughness<br>instrument.geometry.surface_roughness.\*<br>seed = 0.3"]
s0 --> s1 --> s2 --> s3 --> s4 --> s5
profile_only#
Background, zero shift, lattice parameters and widths only. In Le Bail mode, the plan extracts the per-hkl intensities by iterated partitioning instead of computing them from a structure.
A known lattice with an unknown structure, or one you do not trust. Use it for indexing checks, for intensities to feed structure solution, or for a lattice parameter and width measurement that does not depend on any structural model.
flowchart TB
s0["bkg<br>instrument.background.\*"]
s1["zero<br>instrument.zero_shift"]
s2["cell<br>phases.\*.cell.\*"]
s3["profile_w<br>instrument.profile.w"]
s4["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s0 --> s1 --> s2 --> s3 --> s4
pawley_default#
The same order as the Le Bail plan. The per-hkl intensities refine inside the least squares, so they carry esds. An equal-split restraint conditions overlapped groups. The plan flags them instead of splitting them with false confidence.
Intensities that need uncertainties, for structure solution or a peak-shape study. Read PAWLEY_OVERLAP_UNRESOLVED before using an intensity from an overlapped group.
flowchart TB
s0["bkg<br>instrument.background.\*"]
s1["zero<br>instrument.zero_shift"]
s2["cell<br>phases.\*.cell.\*"]
s3["profile_w<br>instrument.profile.w"]
s4["profile<br>instrument.profile.u<br>instrument.profile.v<br>instrument.profile.x<br>instrument.profile.y"]
s0 --> s1 --> s2 --> s3 --> s4
magnetic_width#
The turn-on order for a phase whose magnetic peaks are broader than its nuclear peaks. The first stage refines the moment with the magnetic width held at zero. The second frees the width beside the converged moment, and the moment keeps refining because staging is cumulative. The third frees both together and runs to the final tolerance. The plan frees nothing else. The moment and the width confound each other, since both lower the calculated magnetic peak’s height. This order brings the moment into the width stage already converged.
After a magnetic structure has converged and MAGNETIC_WIDTH_UNMODELLED says its magnetic reflections fit too narrow. The plan frees both width terms, because the dataset decides which of the two carries the effect. Expect the other term back unmeasured. Expect the last stage to report max_iter in that case, since the solver keeps walking a direction the data cannot constrain. Read MAGNETIC_WIDTH_MOVED_MOMENT before dropping an unmeasured term, because the shift it names is the measurement.
flowchart TB
s0["moment<br>phases.\*.atoms.\*.moment.dof\*<br>phases.\*.scale<br>instrument.background.c\*"]
s1["magnetic_width<br>phases.\*.magnetic_lor_size<br>phases.\*.magnetic_lor_strain"]
s2["moment_and_width<br>phases.\*.atoms.\*.moment.dof\*<br>phases.\*.magnetic_lor_size<br>phases.\*.magnetic_lor_strain"]
s0 --> s1 --> s2