Free surface in 3D: spherical shell support, dimension-general surface machinery, and the 2D compatibility-floor fix

[lmoresi]

What this is

Workstream C first pass (Louis + Claude; @gthyagi for review): uw.systems.FreeSurface runs end to end on a 3D spherical shell, built by making the surface machinery dimension-general rather than porting it piecewise. On the way, the 2D strong-datum compatibility floor was fully resolved (three stacked causes, each measured before fixed).

The 2D fix (rides first, benefits everything)

Strong-datum consistent solves on a deforming ring stalled honestly at rel ~2e-3, residual 100% in the pressure rows (block-split evidence). Three causes, closed in order, each verified by rerunning the power-law acceptance:

1. Trace-mass gauge — the demean weights become the P1 lumped boundary mass accumulated per owned DMPlex facet (necessary; measured not dominant).
2. Directed flux strip (maintainer ruling) — the datum's mean volume flux through the deformed facet normals is stripped with the same FE surface integral the residual uses (Φ = ∮ũ_n(n̂·Γ)ds, S = ∮(n̂·Γ)ds, mesh.Gamma), so the constrained field carries exactly zero discrete net flux.
3. Pressure-gauge quotient convergence — the constant-pressure mode is projected out of every increment by the inner KSP (it is the gauge of an enclosed domain) and is not exactly a left-nullvector on a deformed faceted boundary; the outer loop now measures the quotient-space residual, mirroring PETSc's projected residual for singular systems.

Result: every step of the power-law annulus acceptance converges (3, 3, then 1 warm-started increment per step; previously honest stalls).

The 3D machinery

• Surface mean/demean: reduction over owned-facet partial trace-mass weights — each facet counted exactly once globally, two scalar allreduces, no gather, no ordering. Same code is the 2D line gauge and the 3D area gauge.
• σ_nn on the 3D P2 trace: new boundary_flux mass="p1" — P1-projected recovery (edge-midpoint loads folded exactly onto vertices via the P1⊂P2 interpolation transpose; sound P1 lumped triangle mass; midpoints read back as the P1 interpolant). Chosen over mass="consistent" because the P2 vertex-integral checkerboard (Fix 3D boundary reaction flux recovery #404 hold) sits exactly at the vertices the P1 h∞ field consumes. The manager translates its lumped default to p1 on 3D meshes.
• 2D-only features refused per piece (ring Taubin filter, tangential transport) instead of the blanket dim != 2 guard; the ring's gather generalises via lexicographic coordinate keys for its remaining diagnostic uses.
• Interior carrier reads the deform displacement by direct nodal row map (no on-node point evaluation — the uw.function.evaluate returns wrong values for P1 fields at points exactly on cell edges (3D) #432 3D exposure class — and no per-step global location).

Evidence (~/+Simulations/FreeSurface/spherical_fs/)

Spherical Y20 topographic relaxation (constant-density shell, background_buoyancy="analytic", resolved timestep): clean exponential decay at rate 6.1–8.2 vs the half-space Cathles reference 12.5 — an O(1) shell/fixed-base correction in the physically correct direction — with the equilibrium modal bias falling 16.3% → 2.2% of A0 over one resolution step (matching the 2D production-resolution figure of ~2.4%; the #431-class discrete recovery defect, resolution-convergent, not structural).

Tests: new test_1072 (3D capability, 17s); full 2D battery green throughout (test_1018 18/18, 1070, 1071 serial; 1070 + 1066 at np2 and np4 for the quadrature/datum tests).

Deliberately delegated to the review/benchmarking pass (maintainer decision)

This PR ships the capability with first-evidence physics; the detailed benchmarking is left open, and this is the note recording that decision:

• exact analytic shell-rate comparison (degree-l relaxation, radius ratio 0.547, no-slip base) and a rate/floor convergence study;
• low-Ra spherical convection with bounded T;
• 3D parallel validation — a spherical-cap datum finally exercises true empty-boundary ranks (np2/np4 annulus partitions never do);
• the CBF sigma_nn recovery on deformed/faceted boundaries: ~2.4% amplitude deficit (chord-vs-arc boundary mass suspected) #431 chord-vs-arc boundary-mass question, which this work's floor evidence feeds directly.

Related: #457 (TI consistent tangent, found during workstream B) still limits Newton-rate claims for anisotropic rheology in any dimension.

An adversarial review follows as the first comment.

🤖 Generated with Claude Code

Underworld development team with AI support from Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[lmoresi]

Adversarial review (pre-review, per house practice)

Ordered by how much each should worry the reviewer.

1. The quotient-space convergence measure is doing load-bearing work. The 2D floor fix's third leg declares convergence while a physically-real (small) incompatibility remains in the pressure-gauge component. This is standard for projected singular systems, and the component is minimized by the directed flux strip — but nothing REPORTS its size per solve. A user whose deformed geometry develops a large gauge-mode residual would see "converged" with no hint. Worth a follow-up: log the projected component's magnitude when it exceeds, say, rtol·reference.

2. The P1-projected σ_nn recovery is validated by physics, not by an exact oracle. The fold-down is exact as a load transfer (interpolation transpose), but its recovery ACCURACY on curved 3D traces is only evidenced by the Y20 benchmark's behaviour (right direction, resolution-convergent bias matching the 2D figure). No manufactured-traction test exists for the 3D path the way the SolCx topography test pins 2D. The delegated benchmarking should include one.

3. 3D parallel is untested. All 3D evidence is serial. The surface-mean reduction and the lex-key gather are collective-by-construction, but the empty-boundary-rank path (a rank owning no piece of the surface) has never actually executed — annulus partitions at np2/np4 always give every rank boundary. A spherical shell at np4+ is the first genuine test, and it is explicitly in the delegated list.

4. The benchmark's fitted rate is not resolution-converged (8.2 at res 0.2, 6.1 at res 0.15, half-space reference 12.5): the O(1) shell correction claim is qualitative. The floor's clean 16%→2.2% convergence is the strong quantitative result; the rate needs the delegated study before any analytic comparison is asserted.

5. Smaller items. The 3D lex-key gather assumes the surface deforms only along the normal (ordering built once — same assumption as the 2D ring, inherited, documented). The mass="p1" mode returns midpoint values as P1 interpolants — correct for the P1 h∞ consumer, but a caller wanting genuine P2 pointwise recovery must use "consistent" and inherit the checkerboard risk; the error message says so. estimate_dt is CFL-based and can hop the entire relaxation in one L-stable step (correct but surprising — the benchmark README documents it; a rate-based dt suggestion is a possible ergonomic follow-up). The refused-in-3D features raise at construction, not import, so a 2D script switched to a 3D mesh fails at the right moment with a named alternative.

What is well-covered: the 2D regression surface (every prior test green throughout, serial and np2, including the re-derived quadrature invariant); the three-cause floor fix each verified by measurement rather than assertion; capability pinned by test_1072 at 17s.

Underworld development team with AI support from Claude Code