Vacuum - FEATURE! - Add the 3D surface-current matrix and halve the solve with stellarator symmetry

[jhalpern30]

Release note

• Audience: users
• Numerical impact: 3D vacuum results shift ~2.2e-3 relative (interpolation-stencil change; 2D untouched) (harness @ a61d7dd)
• Migration: 3D vacuum results are no longer comparable to those from before this change; regenerate any saved 3D gpec.h5 baselines or reference values. 2D is unaffected.

The 3D vacuum solve now produces the surface-current matrix I_v, the same inductance diagnostic the 2D path already provided. It is also substantially cheaper: folding the mode-family phase into the kernel and exploiting stellarator symmetry cut the solve 2.5-7.6x and halved (or quartered) the operator memory, which is what makes production 3D grids fit in memory at all.

Regression report

regress --cases diiid_n1,solovev_n1 --refs feature/vacuum-3d-conformal-wall,feature/vacuum-3d-inductance @ a61d7dde

case	quantities tracked	changed
diiid_n1	47	none
solovev_n1	22	none

Both cases are 2D (nzeta == 1) and exercise none of the 3D code paths this branch touches. Zero movement confirms the 2D path is untouched; it does not cover the 3D result shift described below, which no harness case reaches.

Notes for reviewers

Stacked on #436 — this targets feature/vacuum-3d-conformal-wall, not develop, so the 3D conformal wall work is excluded from this diff. Merge #436 first. #438 stacks on top of this one in turn.

Review package (diagrams, derivations, benchmarks): https://claude.ai/code/artifact/17fac702-393d-4993-9b49-e290234d3ecc
It covers this branch and #438 as one story.

Two commits

commit	what
ef9f2036	3D surface-current matrix I_v; RHS projected onto the Fourier basis before the solve; mode-family phase folded into the kernel so only the reduced [nb·M x nb·M] operator is stored, one residue class at a time
a61d7dde	stellarator symmetry: the class operator becomes real, and splits into two half-size real blocks for a self-conjugate class

The one thing that moves results

Kernel3D.jl:124 changed the 5x5 Lagrange stencil selection from trunc(Int, u - 2) to round before the offset. This is not an accuracy fix — against a 72x36 reference the two agree to 0.06% and the winner flips with resolution (round better at 24x12 and 32x16, trunc better at 48x24), and both are exact through degree 4. It is a symmetry fix: trunc is not equivariant under the interpolation patch's pi-rotation, so 790 of 800 polar nodes got a stencil that was not the mirror of its partner's, and the operator could not inherit the boundary's symmetry (asymmetry 1.9e-3 nowall / 1.0e-2 with a close wall, versus 5.2e-13 after).

It is a prerequisite for stellarator symmetry and buys nothing on its own, so it ships here. Cost: 3D results move once. On examples/Solovev_ideal_example_3D, et[1] goes 7.942458514881e-01 -> 7.959714927451e-01 (2.2e-3 relative), comparable to that example's own discretization error.

Worth pushing on

• The 3D Solovev example gains nothing from the symmetry work. Its equilibrium-extracted boundary is stellarator-symmetric only to 1.9e-3, so detection (1e-10 relative) correctly rejects it and it falls through to the untransformed solve. Loosening the tolerance would trade an uncontrolled ~1e-3 error for the speedup; I did not. Making flux-surface extraction symmetry-preserving is separate work in the Equilibrium module.
• There is still no nfp > 1 example or regression case, and nfp is not plumbed through PerturbedEquilibrium.jl:72 or set by the VacuumInput(equil, ...) constructor at DataTypes.jl:64. Every nfp > 1 claim rests on unit tests.
• use_symmetry=false is bit-identical to the pre-symmetry code on all seven A/B cases; symmetry-on agrees to <=1.4e-12; an asymmetric boundary falls through bitwise.
• Measured, conformal wall, 6 threads: 2.5x at nfp=1 64x64, 3.8x at 96x96, 7.6x for nfp=5, k=0. Operator memory 2x, or 4x for a self-conjugate class with nfp > 1.

Commit messages

Both commit subjects on this branch are informal and one says the work is unreviewed. Worth squashing or rewording before merge.

[github-actions]

This pull request is missing a reviewer.

If you are not ready to name them, mark this pull request as a draft.
docs/development/contributors.md suggests lead developers to ask.
Merging is not blocked here, but no pull request may be merged without human review.

[jhalpern30]

Stacked on top of this: #438 (Vacuum - PERF - Serve conjugate toroidal residue classes from one factorization), which targets this branch rather than develop and should merge into it first.