FT - BUG - TOML runs with file forcing never apply convert_forcing_normalization! (uniform amplitude scale error)

[matt-pharr]

Summary

TOML-driven runs with ascii/hdf5 forcing formats skip convert_forcing_normalization! entirely, so every amplitude-linear PerturbedEquilibrium output carries a uniform, case-dependent scale error. On the coarse Solovev fixture the factor is 16.85 on forcing_b and resonant_area_weighted_field versus a properly converted load. Amplitude-ratio outputs (e.g. permeability matrices) are unaffected.

Mechanism

• The driver's forcing snapshot (snapshot_forcing_modes) loads the modes early via load_forcing_data! — without conversion — so they can be written into Input/RawInputs/ForcingTerms/.
• The PE compute step's load-and-convert block is guarded by isempty(intr.forcing_modes), so whenever the snapshot preloaded the modes — which is always, for file forcing with a [PerturbedEquilibrium] section — the branch containing convert_forcing_normalization! never runs.
• A direct load through ForcingTerms (as the new scripting API in FFS - REFACTOR - Publish solves as ForceFreeStatesResult; staged main; solve API (refactor plan interface PR) #393 does) converts correctly, which is how the discrepancy surfaced.

git log -S forcing_modes_snapshot places the introduction at #171; the behavior is present on develop and predates the #393 refactor stack (verified against develop and reproduced through the refactored path, which faithfully preserves it — #393's TOML byte-identity gates required not fixing it there).

Why the fix needs a design decision

Simply converting after the preload check would double-convert on the gpec.h5-replay path, which injects modes that were snapshotted from a run. The conversion needs a single well-defined home (probably: snapshot stores raw, and materialization always converts exactly once, with replay-injected modes tagged by their normalization state).

Note the fix will move TOML PE outputs for every file-forcing deck (uniformly, per case) — regression cases tracking amplitude-linear PE quantities will re-baseline, and any past comparisons of these outputs against Fortran GPEC or experiment should be revisited.

Related

• Add capability to rerun GPEC from an HDF5 file #171 (introduced the snapshot path)
• Make surface input always at psi=1 or on a specifiable surface, then use method of equivalent surface currents to get the currents on the control surface #377 (forcing-surface redesign — whoever reworks forcing input should place the conversion correctly as part of that design)
• FFS - REFACTOR - Publish solves as ForceFreeStatesResult; staged main; solve API (refactor plan interface PR) #393 (refactor stack; its API-vs-TOML parity test documents the discrepancy neutrally and compares amplitude-linear outputs only through the like-for-like path)

🤖 Generated with Claude Code