[krystophny]

Restore the processed equilibrium saved by GPEC instead of retracing its input equilibrium when equilibrium_from_h5 is used for post-processing. Retracing can change the saved q profile, its derivative and the surface associated with stored response matrices.

The reader now builds the native profile and periodic geometry splines from the stored arrays, restores saved equilibrium parameters and reuses the existing geometry-to-field kernel. The full rerun entry point is unchanged. A temporary synthetic HDF5 regression checks the saved arrays, root and derivative, mode and rational-surface data, and an independent nonzero coil-forcing contraction. No private fixture is included.

Verified

• Native Julia 1.13.2 qualification job 3361292: the unchanged old reader fails at the missing-ingest contract, while the candidate passes all 25 synthetic checks. The RED fixture uses existing constructors and reaches the old reader.

• A read-only local consumer also checks stored profiles, geometry, modes, rational surfaces and root/q/derivative consistency at 1e-12. Private input and output files remain outside Git.

• The extracted 63-line numerical kernel is byte-identical to the original arithmetic and loop body. The committed source matches qualified candidate archive 87adf2d72527c47f872acebb0cc7cb849970024a02f3ee23afb12f6093a4ff6f, apart from one formatter-only docstring line wrap. All normal hygiene and formatting hooks passed.

• The full native suite also passes on Julia 1.11.9 in CI job 120552763819. Its actual checkout is PR merge b467a4e, and all four files changed here are byte-identical to b4773f7. Affected positive counts include equilibrium 320, error fields 297, analytic/coil/direct/inverse reruns 12/8/20/20, and the new frozen-state regression 25.

Notes for reviewers

This remains a draft pending human review. The current numerical regression report is below. Qualification was on the pinned baseline 9a51446, and does not claim coverage of later develop changes. The saved schema does not retain every derived field, so derived field and metric splines are rebuilt with the existing native kernel rather than claimed to be serialized bitwise snapshots for every equilibrium kind. The synthetic oracle and actual read-only consumer cover the stated reconstruction contract, not all equilibrium variants.

Open PR 548 touches the old reader documentation and retracing call, while PR 569 changes the deprecated-key helper; neither implements this saved-state restoration. This PR does not depend on either branch.

Release note

• Audience: users
• Numerical impact: existing regression cases unchanged; post-processing restores saved profiles and geometry without retracing. (harness @ ac5095f)
• Migration: Use complete HDF5 outputs containing the processed profile and geometry arrays for post-processing; regenerate incomplete outputs before calling equilibrium_from_h5. Current complete outputs require no changes.

Post-processing a saved response now keeps its original equilibrium profiles and geometry consistent with the stored control surface and response data. Full reruns continue to reconstruct their inputs and execute their requested stages.

Regression report

Compared develop @ 6d655c74c against this branch @ ac5095f5a on ITER SDCC through Slurm (Julia 1.12.6, CI-pinned manifest, 2 Julia threads / 1 BLAS thread): solovev_n1 22 unchanged, solovev_multi_n 15 unchanged, and diiid_n1 53 unchanged. All 90 tracked quantities are unchanged, with zero numerical differences and identical checksums.

Focused equilibrium, frozen-state, rerun, and solve-API tests passed, including 28 frozen-snapshot checks covering saved profiles, geometry, forcing contraction and analytic-source retention. Local and CI documentation builds passed. The full CI test matrix is still running.

Full regression report

================================================================
Case: solovev_n1 — Solovev analytical equilibrium, n=1, ideal stability
================================================================

Regression Report: solovev_n1
========================================================================================================
Ref 1: develop  @ 6d655c74c (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
Ref 2: bugfix/hdf-frozen-equilibrium-20261023  @ ac5095f5a (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
--------------------------------------------------------------------------------------------------------
Quantity                      develop          bugfix/hdf-frozen-equilibrium-20261023  Diff       Status
--------------------------------------------------------------------------------------------------------
total energy Re(et[1])        1.090560e-02     1.090560e-02                            0.0e+00    OK    
total energy Im(et[1])        1.309258e-10     1.309258e-10                            0.0e+00    OK    
plasma energy Re(ep[1])       -1.041640e+01    -1.041640e+01                           0.0e+00    OK    
vacuum energy Re(ev[1])       1.042730e+01     1.042730e+01                            0.0e+00    OK    
vacuum matrix min eigenvalue  2.170703e+00     2.170703e+00                            0.0e+00    OK    
plasma energy (all)           [32 elem]        [32 elem]                               0.0e+00    OK    
vacuum energy (all)           [32 elem]        [32 elem]                               0.0e+00    OK    
total energy (all)            [32 elem]        [32 elem]                               0.0e+00    OK    
ODE steps (saved)             287              287                                     0.0e+00    OK    
ODE steps (total)             285              285                                     0.0e+00    OK    
q0                            1.900006e+00     1.900006e+00                            0.0e+00    OK    
q95                           3.147422e+00     3.147422e+00                            0.0e+00    OK    
beta_t                        4.621027e-02     4.621027e-02                            0.0e+00    OK    
beta_n                        3.217775e+00     3.217775e+00                            0.0e+00    OK    
# singular surfaces           2                2                                       0.0e+00    OK    
singular psi locations        [2 elem]         [2 elem]                                0.0e+00    OK    
singular q values             [2 elem]         [2 elem]                                0.0e+00    OK    
mpert                         32               32                                      0.0e+00    OK    
npert                         1                1                                       0.0e+00    OK    
q profile (checksum)          2340b888d410...  2340b888d410...                         identical  OK    
pressure profile (checksum)   108b947087e6...  108b947087e6...                         identical  OK    
ca_left (checksum)            21c2d085d11b...  21c2d085d11b...                         identical  OK    
Runtime (s)                   249.6s           250.9s                                             --    
========================================================================================================
Summary: 22 unchanged


================================================================
Case: solovev_multi_n — Solovev analytical equilibrium, multi-n, ideal stability
================================================================

Regression Report: solovev_multi_n
========================================================================================================
Ref 1: develop  @ 6d655c74c (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
Ref 2: bugfix/hdf-frozen-equilibrium-20261023  @ ac5095f5a (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
--------------------------------------------------------------------------------------------------------
Quantity                      develop          bugfix/hdf-frozen-equilibrium-20261023  Diff       Status
--------------------------------------------------------------------------------------------------------
total energy Re(et[1])        -2.134718e+00    -2.134718e+00                           0.0e+00    OK    
total energy Im(et[1])        1.943387e-10     1.943387e-10                            0.0e+00    OK    
vacuum matrix min eigenvalue  1.730832e+00     1.730832e+00                            0.0e+00    OK    
plasma energy (all)           [70 elem]        [70 elem]                               0.0e+00    OK    
vacuum energy (all)           [70 elem]        [70 elem]                               0.0e+00    OK    
total energy (all)            [70 elem]        [70 elem]                               0.0e+00    OK    
ODE steps (saved)             56               56                                      0.0e+00    OK    
ODE steps (total)             1044             1044                                    0.0e+00    OK    
q0                            1.900006e+00     1.900006e+00                            0.0e+00    OK    
q95                           3.147422e+00     3.147422e+00                            0.0e+00    OK    
# singular surfaces           3                3                                       0.0e+00    OK    
singular psi locations        [3 elem]         [3 elem]                                0.0e+00    OK    
mpert                         35               35                                      0.0e+00    OK    
npert                         2                2                                       0.0e+00    OK    
q profile (checksum)          2340b888d410...  2340b888d410...                         identical  OK    
Runtime (s)                   245.1s           246.1s                                             --    
========================================================================================================
Summary: 15 unchanged


================================================================
Case: diiid_n1 — DIII-D-like equilibrium, n=1, ideal + perturbed equilibrium
================================================================

Regression Report: diiid_n1
========================================================================================================================
Ref 1: develop  @ 6d655c74c (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
Ref 2: bugfix/hdf-frozen-equilibrium-20261023  @ ac5095f5a (2026-10-27)
       env: julia 1.12.6, x86_64-linux-gnu, manifest 4c9d54fa (pinned), 2 threads/1 BLAS, jit build
------------------------------------------------------------------------------------------------------------------------
Quantity                                      develop          bugfix/hdf-frozen-equilibrium-20261023  Diff       Status
------------------------------------------------------------------------------------------------------------------------
total energy Re(et[1])                        8.006122e-01     8.006122e-01                            0.0e+00    OK    
total energy Im(et[1])                        7.924888e-05     7.924888e-05                            0.0e+00    OK    
plasma energy Re(ep[1])                       -1.372261e+00    -1.372261e+00                           0.0e+00    OK    
vacuum energy Re(ev[1])                       2.172874e+00     2.172874e+00                            0.0e+00    OK    
vacuum matrix min eigenvalue                  1.873975e-01     1.873975e-01                            0.0e+00    OK    
plasma energy (all)                           [35 elem]        [35 elem]                               0.0e+00    OK    
vacuum energy (all)                           [35 elem]        [35 elem]                               0.0e+00    OK    
total energy (all)                            [35 elem]        [35 elem]                               0.0e+00    OK    
ODE steps (saved)                             792              792                                     0.0e+00    OK    
ODE steps (total)                             787              787                                     0.0e+00    OK    
q0                                            1.204212e+00     1.204212e+00                            0.0e+00    OK    
q95                                           4.781723e+00     4.781723e+00                            0.0e+00    OK    
beta_t                                        1.327024e-02     1.327024e-02                            0.0e+00    OK    
beta_n                                        1.372511e+00     1.372511e+00                            0.0e+00    OK    
internal inductance li1                       8.842268e-01     8.842268e-01                            0.0e+00    OK    
internal inductance li2                       7.080757e-01     7.080757e-01                            0.0e+00    OK    
internal inductance li3                       7.304340e-01     7.304340e-01                            0.0e+00    OK    
poloidal beta betap1                          6.680739e-01     6.680739e-01                            0.0e+00    OK    
poloidal beta betap2                          5.349836e-01     5.349836e-01                            0.0e+00    OK    
poloidal beta betap3                          5.518764e-01     5.518764e-01                            0.0e+00    OK    
# singular surfaces                           5                5                                       0.0e+00    OK    
singular psi locations                        [5 elem]         [5 elem]                                0.0e+00    OK    
singular q values                             [5 elem]         [5 elem]                                0.0e+00    OK    
current beta betaj                            4.236480e-01     4.236480e-01                            0.0e+00    OK    
plasma volume                                 1.829472e+01     1.829472e+01                            0.0e+00    OK    
plasma current                                1.152130e+00     1.152130e+00                            0.0e+00    OK    
mpert                                         35               35                                      0.0e+00    OK    
npert                                         1                1                                       0.0e+00    OK    
toroidal field bt0                            2.006573e+00     2.006573e+00                            0.0e+00    OK    
wall field bwall                              3.880145e-01     3.880145e-01                            0.0e+00    OK    
aspect ratio                                  2.845746e+00     2.845746e+00                            0.0e+00    OK    
elongation kappa                              1.708322e+00     1.708322e+00                            0.0e+00    OK    
q profile (checksum)                          6da947d0754e...  6da947d0754e...                         identical  OK    
pressure profile (checksum)                   c9c6ca4072ca...  c9c6ca4072ca...                         identical  OK    
Mercier D_I profile (checksum)                26babbe22505...  26babbe22505...                         identical  OK    
resistive interchange D_R profile (checksum)  c46830151a0b...  c46830151a0b...                         identical  OK    
ballooning Delta' profile (checksum)          c27c6779804a...  c27c6779804a...                         identical  OK    
island half-widths                            [5 elem]         [5 elem]                                0.0e+00    OK    
Chirikov parameter                            [5 elem]         [5 elem]                                0.0e+00    OK    
||resonant area-weighted field||              5.288461e-04     5.288461e-04                            0.0e+00    OK    
dominant-coupling singular values             [3 elem]         [3 elem]                                0.0e+00    OK    
|forcing overlap with dominant mode|          1.411548e-04     1.411548e-04                            0.0e+00    OK    
|delta_nominal| of coil set 1                 7.034622e-05     7.034622e-05                            0.0e+00    OK    
||ddelta/d(shift)|| over coil sets            1.245446e-04     1.245446e-04                            0.0e+00    OK    
||ddelta/d(tilt)|| over coil sets             4.177337e-07     4.177337e-07                            0.0e+00    OK    
PE plasma energy                              3.320466e+00     3.320466e+00                            0.0e+00    OK    
PE vacuum energy                              3.174319e+00     3.174319e+00                            0.0e+00    OK    
PE surface energy                             5.508585e+00     5.508585e+00                            0.0e+00    OK    
PE toroidal torque                            1.119355e-04     1.119355e-04                            0.0e+00    OK    
NTV torque FGAR [N·m]                         5.480580e-01     5.480580e-01                            0.0e+00    OK    
NTV kinetic energy dW FGAR [J]                8.163220e-02     8.163220e-02                            0.0e+00    OK    
Runtime (s)                                   298.9s           298.9s                                             --    
||forcing b~|| (root-area-weighted)           4.683171e-04     4.683171e-04                            0.0e+00    OK    
resonant area-weighted field b^r              [5 elem]         [5 elem]                                0.0e+00    OK    
========================================================================================================================
Summary: 53 unchanged

Chris&AI

[matt-pharr]

@krystophny is this ready for review? If so please put it to open instead of draft. Avoid requesting a review until something is no longer a draft, as that is a mixed signal about whether something is ready for eyes/merge yet. If you want eyes on a PR before you feel it is ready to be merged then better to make that an explicit @tag + request.

This also applies to several other PRs you have here.

[krystophny]

@krystophny is this ready for review? If so please put it to open instead of draft. Avoid requesting a review until something is no longer a draft, as that is a mixed signal about whether something is ready for eyes/merge yet. If you want eyes on a PR before you feel it is ready to be merged then better to make that an explicit @tag + request.

This also applies to several other PRs you have here.

Yes!

[matt-pharr]

Merged develop and retained the geometry-to-field kernel extraction in Axisymmetric/Direct.jl. Preserved frozen restoration, updated the deprecated-key check, and adapted construction to retain analytic configs. Added checks that analytic snapshots keep both their source config and saved profiles.

[matt-pharr]

This is useful and will save runtime and confusion, and will keep things closer to the actual outputs if anything about equilibrium treatment changes in the future. This is roughly how I would have implemented this. Approve.