Vacuum - FEATURE - Add 3D conformal conducting wall capabilities

[jhalpern30]

Release note

• Audience: users
• Numerical impact: none (harness @ 5f21e87)
• Migration: none

The 3D vacuum solver can now put a conducting wall around a non-axisymmetric boundary. With
nzeta_in > 1, shape = "conformal" builds the wall by displacing every plasma point a fixed
distance along its own normal. Previously any 3D-input case — stellarator or 3D tokamak alike —
could only be run with shape = "nowall".

Regression report

Run against the tip of this branch (5f21e873, develop merged in) vs current develop:

regress --cases solovev_n1,diiid_n1 --refs 987e63f3,5f21e873

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

Regression Report: solovev_n1
=================================================================================
Ref 1: 987e63f3  @ 987e63f3 (2026-08-28)
       env: julia 1.12.6, arm64-apple-darwin24.0.0, manifest ece8f5d1 (pinned), 6 threads/6 BLAS
Ref 2: 5f21e873  @ 5f21e873 (2026-08-31)
       env: julia 1.12.6, arm64-apple-darwin24.0.0, manifest ece8f5d1 (pinned), 6 threads/6 BLAS
=================================================================================
Summary: 22 unchanged


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

Regression Report: diiid_n1
=================================================================================================
Ref 1: 987e63f3  @ 987e63f3 (2026-08-28)
       env: julia 1.12.6, arm64-apple-darwin24.0.0, manifest ece8f5d1 (pinned), 6 threads/6 BLAS
Ref 2: 5f21e873  @ 5f21e873 (2026-08-31)
       env: julia 1.12.6, arm64-apple-darwin24.0.0, manifest ece8f5d1 (pinned), 6 threads/6 BLAS
=================================================================================================
Summary: 47 unchanged

Both cases: every tracked quantity identical (Diff 0.0e+00 / checksums identical). Full tables
in the CI harness log for this run.

NOTE: because I am not really tracking the 3D in the regression yet, the harness isn't super important here. Mainly going off of the diagnostic plots here. Specifically because a lot of the outputs here rely on the unpublished 3D DCON python code

Notes for reviewers

What to look at

• WallGeometry3D now takes plasma_surf and selects the shape with the same if/elseif
  chain WallGeometry uses in 2D: axisymmetric revolves the 2D contour, otherwise conformal,
  otherwise the same "shape not recognized" error the 2D reader gives. One sequential function,
  no helper indirection.
• The offset: r_wall = r_plasma − d·n̂_plasma with d = a·r_minor and
  r_minor = ½(max R − min R) — the same definition the 2D shapes use, which is what makes the
  two routes comparable on an axisymmetric boundary.
• The guards: fold (error), machine-axis crossing (error, reports the largest admissible a),
  near-fold (warn), gap under one grid cell (warn), equal_arc_wall ignored (warn). There is
  deliberately no centre-stack clamp — clamping a 3D surface would leave a cusp and corrupt
  the spline normals the near-field quadrature depends on, so it is rejected instead.

Verification

gate	what it tests	result
A	same Solovev plasma through both wall routes, vs a converged 2D solve	4th-order convergence on both routes; their difference converges away faster still
B	W7-X wall geometry	offset error ≤ 6.7e-16 m, nfp-periodicity ≤ 4.2e-14 m, index alignment exact
C	W7-X Wᵛ vs wall distance, two grids	smooth and monotone to ~0.08 m; 1–3 % self-convergence there
D	Solovev Wᵛ vs wall distance, against a gap-independent 2D reference	both routes fail identically — the quadrature, not the wall construction
E	precise-QA boundary, three-grid Richardson ladder	geometry exact; the threshold reproduces on geometry that had no part in deriving it

Unit tests 277 → 307. docs/make.jl builds clean.

Known limitation, now warned about

Accuracy is set by the plasma–wall gap measured in grid cells of the coarser direction
(toroidal, on every stellarator grid tested): at or above 1 cell the wall gap is no longer the
limiting error; between 0.3 and 1 cell the answer is one to two orders worse; below 0.3 cells it
is meaningless. The constructor warns below one cell and names the direction to refine. Note this
says when to stop blaming the wall, not that the answer is converged — what remains above one
cell is ordinary surface discretization and is geometry-dependent.

JMH - I am going to try to fix this in a future PR, but for now will just warn. This is not an inherently 3D issue. It also appears in 2D, but we can typically increase the resolution to be large enough that it isn't an issue.

[github-actions]

This pull request is missing an assignee.

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.