[AdamCorrao]

re/05: native topas.* schemas, writer and runner (TOPAS 6)

Merges re/05-topas-schema into refactor/multi-engine (base 139e72d, re/04
merged; tip 240147e, 16 commits: 11 for the branch, 5 from its review).

Native TOPAS recipes (topas.rietveld, topas.spf) can now be validated,
written to an INP, run on TOPAS, and turned into the same standard result dict
and report files as the GSAS-II gateway. The branch declares TOPAS 6 only
(A143): the only TOPAS available is TOPAS-64 Version 6. Everything that needs
TOPAS was checked on it through five probe packs (devkit
probes/re05_topas/pack{1..5}).

The 0.26.0 GSASII_* → TOPAS path is unchanged; it keeps its >=7,<8 gate
and its v7.25 references until re/07 (A146).

What changes

Package move (A136).

• powderline.topas is now powderline.gateways.topas, with no shim.
• The topas-kicker entry point and pixi task follow.
• An existing checkout needs pixi reinstall powderline.

Native schemas (gateways/topas/schema.py; draft rev 3 signed as a set,
A147). The recipe uses TOPAS's own keywords, macro parameters and units (A142),
and PowderLine fills in no defaults: a block left out is not modelled.

• engine_version is a required field; only "6" is supported (A144). A run
  needs the installed version declared (topas_version or config) and equal
  to it (A145).
• Bounds: a stated min/max replaces TOPAS's default limit on that side
  (A138). A refined start value outside a default limit on an open side is a
  validation error, because TOPAS would move it silently.
• Instrument:
  • radiation: lam with lh required; lg only together with lh.
  • geometry: Rp/Rs.
  • corrections, keyed by macro: Zero_Error, LP_Factor /
    LP_Factor_Synchrotron, Simple/Full axial, capillary (parallel or
    divergent beam).
  • broadening: TCHZ / PV / PVII peak types.
• Background: Chebyshev, One_on_X, and pv/spv/spvii background peaks.
• TopasPhase:
  • scale;
  • CS_L/CS_G and Strain_L/Strain_G, reported with TOPAS's LVol-IB
    and e0;
  • Uiso written as beq, Uaniso as u_ij.
• Space groups: 541 accepted and 23 refused, checked against TOPAS 6's own
  operator output.
• SPF: each peak is the instrument peak type convolved with its own
  Gaussian/Lorentzian width.

Writer and runner (native_writer.py, native_run.py, gateway routing).

• One TOPAS parameter per symmetry tie group, with exact tie equations.
• Index-based names, and macro limits written explicitly.
• TOPAS 6's exit code says nothing, so success is judged from the output
  files the INP asks for. They are removed before the run, so an earlier
  run's files can never pass; timestamps are not used.
• TOPAS's files are read strictly. Any non-finite number in the results, the
  profile or a reflection list is a divergence error, in Python or MSVC
  spelling (nan, 1.#QNAN, -nan(ind)). An undetermined ESD is left
  empty.
• Structured warnings:
  • topas_adp_converted;
  • topas_parameter_at_limit, which names the stated bound or TOPAS's default;
  • topas_parameters_not_varied;
  • topas_phase_contributes_nothing (informative only: a phase absent from
    the sample legitimately contributes nothing);
  • topas_background_not_calculated.

Fit window on data points, every engine (A149, A150).

• Core fit_limits_on_data hands each engine the first and last weighted data
  points inside fit_range as its limits. An open end, or no fit_range,
  becomes the data's first or last weighted point, so zero-weight edge points
  never widen an engine's window. The data themselves are not cut.

• The two engines round a limit that falls between data points differently:

  • GSAS-II fits one point past such a maximum (EB-54);
  • TOPAS takes the data point nearest each limit (EB-59).

  With limits on data points, both fit exactly min ≤ 2θ ≤ max, the same points
  core scores.

• TOPAS's own r_wp now equals core Rwp in all six fixtures. GSAS-II's Rwp
  equals core Rwp on LaB6, for gsasii.rietveld and gsasii.spf. With the
  open ends on weighted points, every engine's Chebyshev basis spans the same
  first and last points.

• The GSAS-II side is frozen-code ledger row R17 (signed, and annotated
  for the open ends). It changes only the fit-range read in
  executors.run_refinement; the 0.26.0 path is untouched.

• A fit_range with no positively weighted point is now a validation error.

Background column from a second TOPAS run (A152).

• TOPAS 6 cannot output the background: Get(bkg) is 0, and phase_out_X is
  TOPAS 7 only.
• After the fit, PowderLine runs a background-only INP: refined values fixed,
  no phases, iters 0. Its Ycalc becomes y_bkg, with every convolution
  TOPAS applies.

Goldens.

• tests/data/topas/native/golden/ holds the TOPAS 6 outputs for the six
  hand-written fixtures (A137).
• tests/test_topas_native_golden.py checks that the writer still emits
  exactly the INPs TOPAS ran, and that the result built from TOPAS's files is
  right.

Docs: docs/SCHEMA_HISTORY.md gains the topas 1.0.0 entry and fit-window
notes for core and gsasii.

Commits

• 5cde3e7 — move the TOPAS package into gateways/topas (A136).
• e448e16 — parameters_requested moves into schema_core, re-exported
  from the gsasii fit_report (D12).
• a357bda — the native schemas.
• 68f7926 — native writer, runner and gateway routing; six fixtures.
• 5062d3c — two bugs found by the pack 2 runs:
  • TOPAS's printed 2θ rounded above the recipe value missed its own point;
  • the cell volume was not exported.
• 720d883 — A149: core rule plus the TOPAS writer.
• 4347ae0 — A149 for GSAS-II (ledger R17, signed; code hash refreshed).
• c677b0d — the background-run INP (A152).
• 8cd5c86 — runner integration of the background run; the analytic
  background code is removed.
• 450c803 — TOPAS 6 goldens and roundtrip tests.
• ff17579 — SCHEMA_HISTORY.

From the PR review (record: devkit tasks/re05-pr-review-record.md; decisions
A154–A157):

• 1a35898 — TOPAS's files read strictly: any non-finite number is a
  divergence (S1).
• e8b2bf2 — outputs removed before the run; no timestamps (S3).
• 06cb9a4 — nits: limit messages in recipe units and with a limit that
  validates; CS's 10000 nm ceiling known for limit-hit warnings; SPF window
  test.
• b5342c8 — open fit-range ends on the first/last weighted point (S2;
  ledger R17 annotation).
• 240147e — SCHEMA_HISTORY and docstrings.

Most of the +128k lines are test data: six fixtures carrying the full 4096-point
patterns, the space-group list, and the goldens. src/ changes are +2262/−123
lines.

Verification

• Default suite 2954 passed, 9 skipped. Five of the skips are the DRX_33-only
  golden test on the other fixtures.

• Every 139e72d baseline ID passes, except the six whose IDs the package move
  renamed; every ff17579 ID passes (one test is now parametrized in two)
  (devkit tasks/re05-prreview-240147e.ids).

• easydiff suite 55 passed, with IDs identical to the baseline.

• Undefined-name probe 0; no CRLF; examples/ untouched; code hash current.

• TOPAS 6 evidence (maintainer's machine):

  • all six fixtures run;
  • TOPAS r_wp = core Rwp over 3767 points;
  • the background run reproduces core's Chebyshev to ≤ 3e-7 where only a
    Chebyshev is modelled;
  • TOPAS's Ycalc is never below the background.

• DRX_33 cubic a, all fits over the same 3767 points:

  Run	cubic a (Å)
  TOPAS 6	4.18244(39)
  TOPAS 7.25, 0.26.0 path	4.18266(39)
  GSAS-II	4.17153(330)

  The two TOPAS versions agree. The GSAS-II difference comes from the engines'
  different profile models; the 0.26.0 paths show the same difference.

Behaviour changes (devkit tasks/deliberate-changes.md rows 22–24)

• Imports: powderline.topas.* imports break, since the package moved
  without a shim.
• Native gsasii fits exactly min ≤ 2θ ≤ max. With a maximum that falls
  between data points, Nobs drops by one and refined values move slightly
  (LaB6: scale 5e-6 relative, U 7e-4). Without a fit_range, zero-weight
  points at the data's edges are no longer inside GSAS-II's window.
• Validation: a fit range with no positively weighted point is an error.

Known, documented, not blocking

• EB-66: without an axial convolution, TOPAS 6 calculates a wrong value at
  the last fitted point of a background or SPF peak (TOPAS xo_Is peaks).
  • No workaround exists: an exclude also drops the in-window neighbour.
  • y_bkg shows the same value, so it stays consistent with Ycalc.
  • TOPAS 7 is unverified.
• EB-69: a fixed peak-type term that makes a width negative (e.g. TCHZ
  X < 0 with Y = 0) validates; TOPAS 6 stops on a negative convolution width,
  but whether it does for the peak types is unverified. Documented for now; if
  it does, any negative value becomes a validation error.
• TOPAS 7 support needs a TOPAS 7 machine; the version set is widened
  explicitly (A143).
• The native runner end to end on Windows (powderline.run(..., engine="topas"), not only the INPs it writes) is checked by the G4 smoke.
• Until re/07 removes engine=, a topas.* recipe needs
  engine="topas".
• For re/10, the user docs:
  • the fit-window rule;
  • the background run;
  • that TOPAS's size/strain terms are not interpretable sizes or strains;
  • that TOPAS's TCHZ letters are not GSAS-II's U..Z.

Decision log: master plan §3, A134–A157. TOPAS 6 findings: devkit
tasks/re05-topas6-compat.md (C1–C36). Engine behaviour: EB-55..69. PR review:
devkit tasks/re05-pr-review-record.md. Execution log entries of 2026-10-09.

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