Adaptivity round 3: the 3D mover+adapt combination, spherical domains, and boundary snapping

[lmoresi]

What this delivers

The final round of the 3D adaptivity capstone: the mover and the refiner now compose in 3D, both work on spherical domains, and refined curved boundaries follow the true geometry instead of staying frozen on the base mesh's chords. Three bug fixes and one ruled feature, each found or decided by running the actual target problems.

The combination works in 3D

redistribute_nodes() then adapt() on a tetrahedral mesh now runs end to end. On the dipping-fault box it does what the 2D experiment promised: pre-grading the base with the mover spends the refinement budget better — 33,570 cells against 36,040 for adapt alone, slightly finer on the fault, with the over-refinement halo reduced from 46 to 39 percent of cells. Geometric multigrid on the combined mesh converges in 3 iterations and reproduces the exact linear solution.

Getting there exposed a PETSc subtlety worth knowing about: DMLabelSetValue does not remove a point from its previous stratum. Re-seeding the refinement-state label on the moved mesh therefore left every cell in two strata, and readers got the old value back — the refiner was silently running the moved geometry with a stale seed, and its conforming closure deadlocked. (Before finding this, the C driver itself was cleared by exhaustive comparison against the Python reference implementation: all 72 single-cell states through three passes, and all 3,456 valid two-cell state pairs.) The seed writer now destroys and recreates the label; a regression test locks re-seeding against a fresh seed of the same geometry.

Spherical domains

• The node mover needed no changes for spherical shells: with the shells' registered analytic surfaces, a boundary-layer metric grades the mesh radially (ratio 1.32) with zero folded cells, and nodes slide on the spheres to machine precision.
• A real multigrid gap surfaced: a refinement pass whose new vertices all land on a Dirichlet boundary adds only constrained degrees of freedom, making the finest transfer square — and the automatic multigrid pickup was rejecting that as 'no coarsening'. Boundary-focused metrics (exactly what curved domains invite) hit this every time, so every annulus boundary-layer adapt was silently falling back to the default preconditioner. With the guard corrected to reject only genuine size mismatches, annulus children solve with geometric multigrid in 2 iterations, identical to the algebraic reference.

Boundary snapping (the chord-vs-snap ruling)

Bisection places new boundary vertices at chord midpoints, so a curved domain's boundary geometry stayed frozen at base resolution no matter how deep the refinement — a measured radius error of about h²/8R that refinement never reduced. Per the maintainer ruling, every refinement generation now snaps its new boundary vertices onto the mesh's registered analytic surfaces, so each intermediate level is a valid mesh in its own right (extractable for solvers) and the metric marks on true geometry. On flat domains the snap is exactly a no-op (a chord midpoint of a plane face already lies in the plane), so all existing flat-mesh results are bit-unchanged.

An independent adversarial review of the branch caught one genuine hole before merge: in 3D parallel, a rank can hold a new boundary vertex through interior cells only, see no labelled boundary face for it, and skip the snap its neighbour applies. The snap mask is now made collective over the parallel point-sharing graph before use. The proof it works: an adapted spherical shell is exactly confluent at 1, 2, and 4 ranks (12,784 cells) with both spheres at analytic radius to 2e-16 on every rank, ghost vertices included. The review also added a loud fold guard (a base mesh too coarse for its boundary curvature now errors instead of tangling silently) and documented the disjoint-surfaces assumption at the snap site.

Evidence

• Serial: mover/adapt family green (38 tests in the confluence-sensitive set plus the full family sweep); new gates for the re-seed, the annulus and shell snap (child and intermediate levels, <1e-12), all hardened against vacuous passes.
• Parallel (np = 1/2/4): snapped annulus exactly confluent (1,068 cells, 2e-16); spherical shell exactly confluent (12,784 cells, 2e-16, ghosts included); the 3D mover-adapt composition runs clean at every rank count; the flat-domain confluence gates (test_0839/test_0842) unchanged.
• Style gate clean, no allowlist additions.

Design note with the round-3 status and measurements: docs/developer/design/ADAPTIVITY_3D_SPHERICAL_2026-07.md. Renders of the 3D combination: ~/+Simulations/nvb_3d_adapt_evaluation/combo3d_*.png.

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]

Added in 2508596b, following the maintainer discussion on internal surfaces: embedded interfaces (the Internal circle/sphere of the *InternalBoundary meshes) now register as radial bounding surfaces flagged interior=True. Refinement was already preserving them topologically (conforming bisection splits interface faces with their edges, labels carry through both refinement paths) — but geometrically they stayed chord-frozen and the snap could not see them. Now:

• adapt() snaps refinement onto the true interface radius (gate: an adapted AnnulusInternalBoundary holds its internal circle to 1e-12);
• the movers keep interface nodes fully pinned — no normal or tangential motion, even with slip_surfaces=True — since interface motion is physics-owned (the slip machinery explicitly skips interior-flagged surfaces; the gate asserts interface nodes are bitwise unmoved while the rest of the mesh redistributes). Tangential slide along an interface would be a one-flag change if ever wanted.

AnnulusInternalBoundary gains the refinement knob the other constructors already expose; the SphericalShellInternalBoundary registration is in place for when the gmsh meshing blocker clears.

Underworld development team with AI support from Claude Code