ErrorFields - FEATURE - Add the correction requirement against the NTV-limited current allowance

[logan-nc]

Stacked on #487 (base feature/errorfields-linearity-check), itself on #486 and #485; the last of the three feature PRs planned after the ErrorFields stack merged. Closes #475.

The question it answers. The NTV limits (#455, #462) say how much correction current an array may carry before its own torque lowers the threshold. Nothing said how much it needs, or on which rational surfaces a correction falls short. For one array and the dominant mode the answer is the ratio −δ_source/δ_array and is not worth a PR. The question worth one is the joint one: given an error-field instance and a set of arrays, what complex currents on all of them minimize the resonant field on every rational surface, what is left on each surface after that, and how often does the sampled machine's overlap exceed what the NTV-limited array can correct at all?

What it adds (src/ErrorFields/Correction.jl, two plots in Analysis.ErrorFields)

• correction_requirement(ctx, source::CoilOverlap, arrays) and its file form, returning a CorrectionRequirement: per array the dominant-mode factor −δ_source/δ_array for the array alone and, for several arrays, the member of the dominant-mode family (one complex equation in narray unknowns, so any two arrays can cancel each other) with the least total ampere-turns squared; the joint least-squares factors argmin ‖C·(b̃_source + Σ_k f_k b̃_k)‖ over every rational surface (\ on the nsurface × narray complex system, with its rank reported, unique when the rank is narray); the resonant field on each surface before, after each array's dominant-mode correction alone, and after the joint correction; and each array's cosine similarity to the source's spectrum. Every current comes twice: as a complex factor on the array's current as given, and in kilo-ampere-turns through a new CoilOverlap.ampere_turns_kat (|winding multiplier| × max|I| / 1000, the normalization the EFC couplings use), because factors on arrays whose patterns were given at different currents are not comparable (the example's C-coil pattern is 0.08 kAt, its I-coil patterns 1 kAt) while kilo-ampere-turns are, and sit on the same axis as the NTV-limited current. Any CoilOverlap can be a source or an array, so an as-built assembly from combine_overlaps can be corrected with arrays that were never part of the run.
• needed_current_distribution(mc, array): the Monte Carlo's |δ| histogram as the current on the array that cancels each sampled overlap's dominant mode, as a factor on its current as given and in kilo-ampere-turns.
• uncorrectable_probability(mc, c::EFCCoupling; delta_threshold, torque_budget, model, …): the fraction of the Monte Carlo's overlap beyond max_correctable_overlap's with_ntv limit for that array, naming the model it used. This is the explicit-correction counterpart of the corrected locking probability's efc_factor model: not "does the field divided by a factor still lock" but "can the array, spending its own torque, reach the field at all".
• plot_correction_requirement (resonant field per surface before and after, as stems on a log axis; then one polar panel per array with its needed currents as phasors in kilo-ampere-turns, radius the magnitude and angle the toroidal phase) and plot_needed_current (the distribution in kilo-ampere-turns with the as-designed current and the NTV-limited allowance marked on the same axis).

Verification

• Tests (278 pass in the error-fields file, 98 in the NTV-limits file), Solovev two-hoop fixture: an array identical to the source needs exactly −1 of its current and the joint least squares leaves nothing (10⁻¹⁰ of the source); a second, differently tilted hoop alone cancels the dominant mode and leaves no more on any surface than the least squares does; with both arrays the least squares finds the exact cancellation (−1, 0) at rank 2, and the least-ampere-turn member of the dominant-mode family cancels the mode exactly with less current than (−1, 0); the overlap's ampere-turns normalize exactly as the coupling's per-kAt overlap, so the needed current and the allowance share one axis; the file form equals the memory form; the needed-current distribution integrates to one in both units and is the histogram rescaled; the exceedance equals the histogram's mass beyond the limit and is zero for a limit beyond the grid; unknown names, empty array lists and a coupling without its threshold throw.
• A caveat on uncorrectable_probability: it integrates the binned |δ| histogram beyond the limit, and the Monte Carlo folds every sample past delta_max into the last bin, so a limit that lands in or beyond that bin with a nonzero clamped_fraction understates the probability; the remedy is a wider delta_max on the Monte Carlo, and the result should be read together with clamped_fraction.
• Docs: a "Designing the correction" subsection; build clean.
• CI: the test.yaml workflow triggers only for pull requests into develop or main, so this stacked PR gets the conventions and documentation checks but not the Julia test suites; the test files above were run locally on the pushed head.
• Regression harness against the base branch: every quantity unchanged (below); the PR adds results and plots and changes no existing computation.
• On the displaced-F-coil variant of the DIII-D-like example (review package), at the deck's new 4 mm tolerances: the as-built F-coil field (|δ| 5.5×10⁻⁵) corrected by the C-coil alone needs 3.1 kAt and removes 93 % of the resonant field's norm over the five rational surfaces at the dominant-mode setting and 94 % at the least-squares setting; the I-coil pair (about 0.5 and 1.1 kAt) removes 96 %, all three arrays 96 %, with the C-coil's joint current falling from 3.1 to 0.7 kAt when the I-coils share the job (the dominant-mode family's least-ampere-turn member puts 0.2 kAt on it); the sampled machine needs 5.0 kAt on the C-coil on average, and the NTV-limited correctable current is 32 kAt at a 0.5 N·m budget and 100 kAt at 8 N·m, three to eight times beyond the samples, so the uncorrectable probability is zero for every budget under both models.

Review package (DIII-D-like example variant only): https://claude.ai/artifact/M95zYnDC7HtPJTNdsZJc1t (private until shared).

cc @matt-pharr

Release note

• Audience: users
• Numerical impact: none (harness @ 44a3b05) (head 0ebab04a5 adds a docs-only note, no source change) — diiid_n1 53 unchanged and diiid_error_field 8 unchanged against the base
• Migration: none

correction_requirement gives the joint least-squares currents a set of correction arrays needs to cancel an error field on every rational surface and what each correction leaves per surface; uncorrectable_probability is the fraction of the tolerance Monte Carlo beyond what an NTV-limited array can correct; two plots draw them.

Regression report

Regression Report: diiid_n1
================================================================================================================================================
Ref 1: feature/errorfields-linearity-check  @ 2add90cfc (2026-10-02)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 06e27666 (pinned), 16 threads/16 BLAS
Ref 2: feature/errorfields-correction-requirement  @ 44a3b05a2 (2026-10-02)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 06e27666 (pinned), 16 threads/16 BLAS
------------------------------------------------------------------------------------------------------------------------------------------------
Quantity                                      feature/errorfields-linearity-check  feature/errorfields-correction-requirement  Diff       Status
------------------------------------------------------------------------------------------------------------------------------------------------
total energy Re(et[1])                        8.012318e-01                         8.012318e-01                                0.0e+00    OK    
total energy Im(et[1])                        4.142529e-05                         4.142529e-05                                0.0e+00    OK    
plasma energy Re(ep[1])                       -1.348486e+00                        -1.348486e+00                               0.0e+00    OK    
vacuum energy Re(ev[1])                       2.149718e+00                         2.149718e+00                                0.0e+00    OK    
vacuum matrix min eigenvalue                  1.873976e-01                         1.873976e-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)                             2576                                 2576                                        0.0e+00    OK    
ODE steps (total)                             4572                                 4572                                        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.842392e-01                         8.842392e-01                                0.0e+00    OK    
internal inductance li2                       7.080847e-01                         7.080847e-01                                0.0e+00    OK    
internal inductance li3                       7.304433e-01                         7.304433e-01                                0.0e+00    OK    
poloidal beta betap1                          6.680744e-01                         6.680744e-01                                0.0e+00    OK    
poloidal beta betap2                          5.349834e-01                         5.349834e-01                                0.0e+00    OK    
poloidal beta betap3                          5.518761e-01                         5.518761e-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.236478e-01                         4.236478e-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.708350e+00                         1.708350e+00                                0.0e+00    OK    
q profile (checksum)                          0cd285cea88d...                      0cd285cea88d...                             identical  OK    
pressure profile (checksum)                   a1c48b266622...                      a1c48b266622...                             identical  OK    
Mercier D_I profile (checksum)                eeb06744e795...                      eeb06744e795...                             identical  OK    
resistive interchange D_R profile (checksum)  fa37296851f6...                      fa37296851f6...                             identical  OK    
ballooning Delta' profile (checksum)          6eb0ea075ccf...                      6eb0ea075ccf...                             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.189179e-04                         5.189179e-04                                0.0e+00    OK    
dominant-coupling singular values             [3 elem]                             [3 elem]                                    0.0e+00    OK    
|forcing overlap with dominant mode|          1.415683e-04                         1.415683e-04                                0.0e+00    OK    
|delta_nominal| of coil set 1                 7.055228e-05                         7.055228e-05                                0.0e+00    OK    
||ddelta/d(shift)|| over coil sets            1.246233e-04                         1.246233e-04                                0.0e+00    OK    
||ddelta/d(tilt)|| over coil sets             4.180643e-07                         4.180643e-07                                0.0e+00    OK    
PE plasma energy                              3.422677e+00                         3.422677e+00                                0.0e+00    OK    
PE vacuum energy                              3.174510e+00                         3.174510e+00                                0.0e+00    OK    
PE surface energy                             5.826684e+00                         5.826684e+00                                0.0e+00    OK    
PE toroidal torque                            5.087465e-02                         5.087465e-02                                0.0e+00    OK    
NTV torque FGAR [N·m]                         5.296762e-01                         5.296762e-01                                0.0e+00    OK    
NTV kinetic energy dW FGAR [J]                7.924971e-02                         7.924971e-02                                0.0e+00    OK    
Runtime (s)                                   296.9s                               289.7s                                                 --    
||forcing b~|| (root-area-weighted)           4.683328e-04                         4.683328e-04                                0.0e+00    OK    
resonant area-weighted field b^r              [5 elem]                             [5 elem]                                    0.0e+00    OK    
================================================================================================================================================
Summary: 53 unchanged

Regression Report: diiid_error_field
=================================================================================================================================================
Ref 1: feature/errorfields-linearity-check  @ 2add90cfc (2026-10-02)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 06e27666 (pinned), 16 threads/16 BLAS
Ref 2: feature/errorfields-correction-requirement  @ 44a3b05a2 (2026-10-02)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 06e27666 (pinned), 16 threads/16 BLAS
-------------------------------------------------------------------------------------------------------------------------------------------------
Quantity                                         feature/errorfields-linearity-check  feature/errorfields-correction-requirement  Diff     Status
-------------------------------------------------------------------------------------------------------------------------------------------------
EFC overlap per kAt                              [1 elem]                             [1 elem]                                    0.0e+00  OK    
EFC whole-field NTV torque per kAt² [N·m]        [1 elem]                             [1 elem]                                    0.0e+00  OK    
EFC residual-field NTV torque per kAt² [N·m]     [1 elem]                             [1 elem]                                    0.0e+00  OK    
EFC reference rotation ω_ref [rad/s]             [1 elem]                             [1 elem]                                    0.0e+00  OK    
EFC rotation-scan shifts [rad/s]                 [9 elem]                             [9 elem]                                    0.0e+00  OK    
EFC residual torque against rotation [N·m/kAt²]  [9 elem]                             [9 elem]                                    0.0e+00  OK    
dominant-coupling singular values                [3 elem]                             [3 elem]                                    0.0e+00  OK    
|delta_nominal| of coil set 1                    1.411046e-06                         1.411046e-06                                0.0e+00  OK    
Runtime (s)                                      606.2s                               618.2s                                               --    
=================================================================================================================================================
Summary: 8 unchanged

🤖 Generated with Claude Code

https://claude.ai/code/session_01BzKDmtKYDotJWrcxWf1oJu