[AdamCorrao]

re/06: native easydiffraction.rietveld schema, builder and run (easydiffraction 0.21.1)

Branch re/06-easydiff-schema → refactor/multi-engine (base 494a802, 20 commits, tip 799938f).
Not a gate branch. Decisions referenced as A-numbers are in the refactor's decision log (A116, A136, A157–A181; A174–A181 from the PR review).

Summary

• The easydiffraction package moves to powderline.gateways.easydiffraction (no shim).
• A native easydiffraction.rietveld recipe (engine schema 1.0.0, on core 1.0.0). It uses easydiffraction's own names and units: Caglioti U/V/W as FWHM² in deg², the Lorentzian X/Y terms, calib_twotheta_offset, …
• A native builder and run. The 0.26.0 easydiffraction path is unchanged until re/07.
• easydiffraction is pinned at 0.21.1: the maintainer's lock in 508f39f, plus the gateway spec in e2408f3.
• The gsasii gateway now reports whether a Rietveld refinement converged (A172).

What the native path does

• Calculator in the recipe (refinement_controls.calculator: cryspy | crysfml, A162). Validation depends on it:
  • which peak types the calculator computes (cwl-pseudo-voigt, Bérar–Baldinozzi asymmetry for CrysPy, Thompson-Cox-Hastings with FCJ asymmetry for CrysFML);
  • cutoff_fwhm, which only CrysPy uses;
  • which space-group settings it computes correctly. These were established by computation over all 531 settings easydiffraction has, for a general position and for every special Wyckoff site (A163, A170, A174): CrysPy 428, CrysFML 230. CrysPy computes special positions wrongly in nine origin-choice-1 settings, so they are refused for it. The error names a setting the calculator does compute, or the other calculator.
• Every correction easydiffraction models is a slot (A160): Kα2 doublet, polarization with a monochromator angle, zero, displacement, transparency, cylinder absorption. A left-out block is not modelled.
• Bounds (A157 B4):
  • a stated bound replaces easydiffraction's physical limit on that side;
  • null keeps the physical limit;
  • a value outside a physical limit is an error, even when fixed;
  • after the run, easydiffraction_parameter_at_limit reports parameters that ended at a limit.
• Data (A158, A159, EB-72, EB-89):
  • easydiffraction gets exactly the weighted points with min ≤ 2θ ≤ max (fit_limits_on_data);
  • they are handed over as a CIF loop at full precision, written without exponents, which easydiffraction's loop cannot read;
  • a weight above 1e8 on one of those points is an error, because easydiffraction would silently replace σ < 1e-4 by 1.0;
  • a negative intensity on one of those points is an error, because easydiffraction refuses it (A177).
• Atoms (A116):
  • x/y/z, occupancy, Uiso and Uij are refinable. Each symmetry tie group becomes one easydiffraction parameter. After the build, easydiffraction's multiplicities and coordinates are checked against core's.
  • With CrysPy, an atom on a special position with a free coordinate must be written in easydiffraction's Wyckoff template pattern. CrysPy computes some other equivalent writings wrongly (and the rule is conservative: it also refuses some writings CrysPy gets right); the run refuses them before calculating and names the position to write (A164).
  • easydiffraction stores some positions in its own writing of the same site, e.g. (0.137, 0.863, z) on (x, −x, z) as (0.137, −0.137, z). That is the same atom: it is accepted with the warning easydiffraction_position_translated, and bounds and reports stay in the recipe's writing (A176).
  • Uaniso is refused with CrysFML, which is handed only B = 8π²·Ueq (A169).
  • With CrysPy, anisotropic atoms are handed over first, because easydiffraction 0.21.1 ignores a refined Uij that follows an isotropic atom (A169).
• Results:
  • standard rwp/r_exp/gof/chi2_red from core fitstats over the window (Rwp equals easydiffraction's);
  • easydiffraction's own values, the calculator, the peak type, parameters_requested and parameters_varied under engine_details;
  • the background column is easydiffraction's own;
  • CrysFML reports no reflection list, so no peak-list reports are written with it (A165);
  • a non-finite calculated value, refined value or reflection-list value is a divergence error.
• Warnings:
  • easydiffraction_parameters_not_varied;
  • easydiffraction_parameter_at_limit (within 1e-6 relative of the limit; at a limit of 0, within 1e-6 of the starting value, A181);
  • easydiffraction_phase_contributes_nothing (informative);
  • easydiffraction_fit_not_converged (informative, values kept, A166);
  • easydiffraction_negative_width, when the refined profile makes a width negative within 1° of the window (widened by the position corrections; A171, A178). A stated profile that does so is a validation error, because easydiffraction then computes a wrong pattern without a message, also from a reflection just outside the window.
  • easydiffraction_reflections_not_available (CrysFML);
  • easydiffraction_crysfml_start_dependent on every CrysFML refinement (A175): CrysFML computes in single precision, below lmfit's finite-difference step, so the refined values, Rwp and ESDs can depend on the starting values (in the LaB6 test, Rwp 6.15–6.79 % for starts differing by 1e-6–1e-4; the cell barely moves);
  • easydiffraction_position_translated (A176).
• gsasii (A172): engine_details['converged'] comes from GSAS-II's Rvals['converged']. When it is False, the warning gsasii_fit_not_converged is given and the values are kept. Single peak fitting reports None: GSAS-II's DoPeakFit keeps no convergence flag.

Engine findings worth knowing (easydiffraction 0.21.1)

• CrysPy:

  • wrong intensities for some equivalent writings of a special position with a free coordinate (LaB6's B written as (½, ½, x));
  • a refined anisotropic ADP has no effect when an isotropic atom precedes it;
  • P 31 is computed with P 32's operators (same powder pattern, the other hand per reflection);
  • 53 settings crash.

• CrysPy also computes special positions wrongly in nine origin-choice-1 settings, even in the template writing.

• CrysFML:

  • is handed only the short space-group symbol, so non-default settings are read in the default one;
  • ignores anisotropic ADPs;
  • computes in single precision: its pattern does not change for parameter steps below about 1e-7 relative, so lmfit's fits stop at start-dependent points.

• Data: easydiffraction refuses negative measured intensities.

• Both calculators: a negative peak width gives a wrong pattern without a message.

• Cell constraints: they reset the unique angle of c- and a-unique monoclinic cells.

• Cross-engine LaB6 cell, refined in both (GSAS-II 4.157216(21) Å):

  easydiffraction profile	a (Å)	vs GSAS-II
  CrysFML TCH + FCJ	4.157175(18)	−1.5σ (the CrysFML fit is start-dependent: 4.15716–4.15718 Å)
  CrysPy pseudo-Voigt (no asymmetry)	4.157495(17)	+67 ppm
  CrysFML pseudo-Voigt (no asymmetry)	4.157593(20)	+91 ppm

  The offset is the missing axial asymmetry, whichever calculator runs the profile.

• DRX_33, two phases: agrees with TOPAS 6 native: cubic a 4.18201 vs 4.18244 Å, Rwp 7.25 vs 7.31 %.

• 0.20.1 → 0.21.1: the legacy LaB6 example's Rwp is unchanged (9.633 %); some ESDs change.

Tests

• Default env: 3037 passed, 19 skipped. The skips are 14 easydiffraction-only tests and 5 TOPAS DRX_33-only golden tests. Every base test ID still passes except four renamed by the package move and the new version spec.
• easydiff env (test_easydiff_* test_easydiffraction_* test_gateways test_phase_canary): 265 passed, 2 skipped (the "easydiffraction not installed" tests).
• New test modules:
  • tests/test_easydiffraction_schema.py;
  • tests/test_easydiffraction_native.py: the builder, the run, an A127 check that every free parameter changes the pattern on lmfit's own update path, divergence, warnings, and four fixtures (three LaB6, one two-phase DRX_33) with goldens;
  • tests/test_easydiffraction_space_groups.py: the space-group table is regenerated and compared, and a sample of settings is re-verified by computation.
• An independent review (tasks/re06-pr-review-record.md in the devkit) checked every decision by disabling its code (each caught by a test) and led to the fixes in the last six commits (A174–A181).
• Generators: scripts/generate_easydiffraction_space_groups.py and scripts/verify_easydiffraction_settings.py (about 1.5 h with --jobs 4; more workers need more than ~1.5 GB each).
• No GSAS-II frozen or hashed module is touched. examples/ is unchanged.

For reviewers

• After checkout, refresh the entry points (pixi reinstall powderline, or pip install --no-deps --no-build-isolation --no-index -e . per env), because the package moved.

• The fixtures' derivations from GSAS-II's instrument terms are in tests/data/easydiffraction/native/README.md. They cover:

  • polarization p = 1 − P;
  • the Lorentzian X/Y role swap;
  • FCJ S/L = H/L = SH/L / 2.

  The v0.1.1 path got these wrong; it stays as is until re/07.

• The CrysPy LaB6 fixture's fit refines X = −0.098, so its golden carries easydiffraction_negative_width. This is intentional: the start is valid and the warning describes the output.

Follow-ups (not in this PR)

• re/07: remove the legacy easydiffraction path, migrate the LaB6 example (write B as (0.2021, ½, ½) and state the calculator).
• TOPAS 7: a convergence signal, after the refactor.
• Upstream reports for easydiffraction, GSAS-II and TOPAS are drafted (with standalone reproductions for easydiffraction). Filing them is the maintainer's call.

Assisted-by: claude-code:claude-opus-5-5
Assisted-by: claude-code:claude-sonnet-5-5