SurfaceCollection nearest-fault director is non-functional in 2-D (three separate faults)

[lmoresi]

Summary

SurfaceCollection advertises "transfer surface normals to mesh variables via nearest-neighbor" — the nearest-available-fault director, which is exactly what a multi-fault TI zone needs. It works in 3-D (triangulated surfaces have genuine cell normals) but is non-functional in 2-D, in three independent places.

The three failures

1. transfer_normals hard-codes 3 components

   normal_var = uw.discretisation.MeshVariable(variable_name, mesh, 3, degree=mesh.degree)
   

   On a 2-D mesh this raises ValueError: Unable to infer variable type from num_components. Should be mesh.dim, with the normals sliced to match.

2. Surface.face_normals raises KeyError: 'Normals' for a polyline. pyvista defines cell normals for surface cells, not lines, so in 2-D there are no face normals to transfer even if (1) is fixed. A polyline's normals are trivially available from the segment tangents (n = (-t_y, t_x)); they just are not computed.

3. compute_distance_field passes (N,2) coordinates to pyvista, which requires (N,3):

   ValueError: points has shape (2058, 2) which is not allowed. Shape must be one of [3, (-1, 3)].
   

   So the alternative route — the collection distance field, whose gradient is the nearest surface's normal — is unavailable too.

The single-Surface path is fine in 2-D: Surface.distance uses the dedicated polyline routine and Surface.director is built from it. Only the collection API is affected.

Why it matters

Without it, every multi-fault TI model hand-rolls a nearest-trace director loop. That is not merely duplication — getting it wrong is quiet and severe. Applying one fault's analytic normal to a second fault's cells (two identical listric curves offset horizontally, slopes differing by exp(dx/lambda) ~ 16 at the same x) locked the second fault: peak slip 0.08 against 0.53 for its partner, from a converged, entirely plausible-looking solve. Reproduced in ~/+Simulations/listric_extension/listric2.py.

This is also the natural home for automating junction glue: the director should follow the fault that is interrupted, and a working nearest-fault lookup supplies that without the modeller nominating a hierarchy.

Suggested fixes

• transfer_normals: mesh.dim components; slice combined_normals[:, :mesh.dim].
• Surface.face_normals: compute polyline normals from segment tangents in 2-D instead of deferring to pyvista.
• compute_distance_field: pad query coordinates to 3-D.
• A 2-D regression test with an analytic oracle: two traces whose normals differ materially at the same x, asserting each probe gets its own trace's normal.

Underworld development team with AI support from Claude Code