The finite-width 3-D fault network: one band, both realisations

[lmoresi]

build(width=...) in 3-D is the 2-D contract one dimension up. The margin-expanded patches are thickened into one fused band (junctions free) and each un-expanded patch is embedded in the band as a conforming mid-surface, so the same mesh is cut and split (realisation="split") or left whole for the volumetric weak plane ("ti"). Honoured footprints are exact for planar patches, with nearest-plane ownership so a cell near a junction carries one director; the weak-plane director is the patch normal; slips() gains the plane gauge (the in-plane velocity jump across the layer), validated exactly on a prescribed shear.

The junction gap is physics and the tip margin convenience, and the two must not meet: a margin within half a cell of the ligament welds the expanded bands at the junction line and the split degenerates into self-paired nodes. We measured the failure as a bit-frozen residual floor (rel 8.8e-3, identical under direct LU, machine-zero leak — the degenerate constraint row is identically zero, so Newton cannot move it). build() refuses that configuration, and a collective post-split check raises on any surviving self-pair as a defect.

Parallel follows the placement's gather-first design: the placed band lives on the surgery rank, so the mid-surface labelling judges its refusal on the global face count and raises collectively — the rank-local raise it replaces was a hang for the peer ranks, not an error. The np=2 ptest builds, splits and solves the crossing network to the serial answer on a distributed mesh.

Refused loudly outside scope: outcropping bands (the embedded mid-surface cannot yet be clipped against the boundary), base= on the 3-D width path, non-network meshers with width, embed= outside mesher="network", and junction_cells in 3-D (the junction glue there is damage_yield's tubes).

Tests: test_0863 (one mesh two realisations, footprint and director oracles, gauge arithmetic, refusals, end-to-end split and TI solves) and ptest_0863 (np=2). The 3-D section of docs/advanced/fault-networks.md is rewritten for the width contract. Neighbouring suites (test_0851, test_0858, test_0859) pass unchanged.

Underworld development team with AI support from Claude Code

[lmoresi]

Adversarial review (posted by the authors' session).

What we tried to break, and what held:

• The degeneracy guard. The measured failure (margin welds the junction gap) produces self-paired nodes: residual bit-frozen at 1.711234e-02 across iterations, identical under direct LU, leak <= 2e-17 — the degenerate constraint row is identically zero, so no solver can move it. The guard refuses margin_rings > ligament - 0.5 before meshing, and a collective post-split check catches any node on both sides of a pairing (self-pairs and chains). What neither can catch is a wrong but bijective pairing — the end-to-end slip and leak oracles in test_0863/ptest_0863 are the guard there.
• Parallel refusals. The mid-surface labelling reduces its face count before branching; the rank-local raise it replaced was a np=2 hang (peer spins), reproduced and fixed. The all-rim erosion remains rank-local, which is correct only under gather-first placement (the band lives on the surgery rank). If placement ever rebalances the band, the erosion would see phantom rims at partition seams — documented assumption, not enforced.
• The margin/ligament rule. Measured at the endpoints: margin == ligament degenerates, margin == ligament - 0.5 (one-cell gap) converges in 1 iteration with np=2 equal to serial within 2%. Intermediate margins are asserted safe by construction, not swept.

Known limitations we chose to note rather than fix here:

• The 3-D weak-plane gauge samples 9 points per patch (corners, edge midpoints, centroid): a slip maximum localized between samples under-reads. It is the layer-throughput gauge, not a field maximizer.
• The gauge's probes reach ±(width/2 + h) off the patch; a patch close to a domain wall could probe outside the domain, where evaluate() extrapolates silently (evaluate() returns large negative values for a non-negative expression (sqrt invariant) at in-domain points near a boundary singularity #641). The band build refuses outcropping networks, which bounds but does not eliminate this.
• The outcrop pre-check is a bounding-box test against the built-in unit base box; it is exact while the width path owns its base (base= is refused) and must be revisited when an adaptable base lands.
• The honoured-footprint rule carries the 2-D edge slack (0.35 h) into 3-D; "exact for planar patches" is exact modulo that slack.

Underworld development team with AI support from Claude Code

[Copilot]

🟡 Changes recommended

_expand_convex_polygon() can divide by zero for convex polygons with collinear consecutive edges, which can propagate NaNs into the 3‑D band geometry build.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements the finite-width 3‑D fault-network “one band, both realisations” contract: a single fused volumetric band mesh is built once, then either split into contact faults (realisation="split") or used as an unsplit weak plane ("ti"), with updated geometry/footprint/director and slip-gauge behavior. This extends the 2‑D width behavior to 3‑D networks and adds serial/parallel tests plus documentation.

Changes:

• Add 3‑D width-band build path for FaultNetwork.build(width=..., realisation=...), including embedded conforming mid-surfaces and post-split self-pair defect checks.
• Extend band placement (place_thin_volume) with embedded mid-surface support and make mid-surface labelling collective-safe in parallel.
• Add serial and np=2 parallel tests for shared-mesh realisations, director/footprint/gauge oracles, and refusal cases; update the advanced docs.

File summaries

File	Description
tests/test_0863_fault_network_3d_width.py	New serial regression covering shared-mesh split/TI realisations, analytic oracles, refusals, and end-to-end solves.
tests/parallel/ptest_0863_fault_network_3d_width_parallel.py	New np=2 parallel validation that split + solve matches serial slip peaks.
src/underworld3/utilities/place_surface.py	Add embedded mid-surfaces to the 3‑D OCC band assembly and make mid-surface labelling refusal collective-safe.
src/underworld3/meshing/fault_network.py	Implement 3‑D finite-width band build and update TI director/slip-gauge logic for 3‑D planar patches.
docs/advanced/fault-networks.md	Document the 3‑D width contract, parallel split support, and current limitations.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[lmoresi]

Confirmed — and the fragility went deeper than the corner intersection: the plane normal itself came from the leading vertex triple (cross(P[1]-P[0], P[2]-P[0])) at five sites, so a collinear leading triple produced NaNs before the corner code was even reached. Fixed in 894effe: one Newell-method _patch_normal now serves every site, and the corner intersection guards the parallel-edge case (on a straight rim the offset corner is the edge's own offset point). Regression test added: a rim with a collinear midpoint expands finitely, in-plane, to the exact offset.

[lmoresi]

Confirmed dead: realisation='ti' with width=None is refused earlier by the ti-needs-width check, so with width=None only 'split' can reach this branch. Removed in 894effe, with a comment recording why width=None implies the split.