Stop the mesh factories recommending a deprecated, broken API (#538)

[lmoresi]

Comments only, no behaviour change.

The problem

Ten comments across four meshing modules said:

# boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals

steering the reader from one deprecated API to another. Gamma_P1 is itself deprecated, and its own docstring explains why it cannot serve here:

off-kernel evaluation falls back to a coordinate-based direction [...] Retained unchanged for back-compat (mesh-smoothing internals)

Measured on a unit box (#538), it returns the edge tangent on Left and Bottom — (0, 1) where the outward normal is (-1, 0) — and drifts up to 40 degrees along Right and Top. mesh.boundary_normal(boundary) is exact on all four edges to 1.6e-11.

So the guidance pointed at the one thing that does not work.

Why this was looked for

Two bugs in a row turned out to be callers of documented-unsuitable APIs — #538 (_slip_normals on Gamma_P1) and #614 (boundary_flux at a constrained boundary). That suggested sweeping for in-tree callers of anything whose own docstring says deprecated or back-compat-only.

The rest of the sweep came back clean, recorded here so nobody repeats it:

API	in-tree callers
boundary_flux_to_field	none — only its own alias and warning
swarm.points	only the deprecation machinery; ckdtree hits are its own unrelated self.points
mesh.access() / swarm.access()	only inside commented-out code
use_legacy_array	none

What is deliberately not touched

The one real internal dependency on Gamma_P1 is the mesh-smoothing path: _slip_normals (meshing/smoothing/graph.py:547) evaluates it, with pre-touch plumbing in graph.py, api.py and mmpde.py. That is #538's actual defect — a node whose "normal" lies along its own edge has its tangential motion projected out, which is why node_redistribution(..., slip_surfaces=True) freezes Left and Bottom exactly. Fixing it means threading the per-boundary normal through _slip_normals, which takes arbitrary boundary coordinates and would need each mapped to its owning boundary. That is a code change with its own testing, not a comment change, so it stays with the issue.

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.