fix(evaluate): recover boundary-face query points dropped by DMLocatePoints on quad/hex meshes (#390)

[lmoresi]

What this fixes

Closes #390 (the test_1052 VEP stability failures) — but the root cause is not PETSc 3.25.

uw.function.evaluate was returning silent zeros for query points sitting exactly on the domain's closed upper boundary faces of quad/hex meshes (e.g. y = y_max on a StructuredQuadBox). PETSc's point location uses a half-open cell convention, so a point exactly on the top face belongs to the nonexistent cell "above" and gets dropped; the dropped point was then zero-filled by the evaluator.

Semi-Lagrangian stress-history trace-backs slide departure points along the top boundary of the VEP shear box, so every step read ψ* = 0 there instead of the true history. The BDF history update amplified that boundary corruption exponentially: max|err| = 240 against a threshold of 0.10. With this fix the same run gives max|err| = 0.063 — the value recorded in the test docstring when it was written.

Why this is a UW3 regression, not a PETSc one

• Before 17a5a8d (May 24) the kd-tree cell hint was always passed into DMInterpolationSetUp_UW, and it prefilled the dropped-point recovery map — points PETSc dropped were evaluated in the adjacent hinted cell (with reference-coordinate clamping). When the hint pointer became the DMLocatePoints-bypass switch (simplex/manifold only), quad/hex volume meshes lost the recovery.
• PETSc's plexgeometry.c (point location, grid hash) has only cosmetic changes between v3.24.2 and v3.25.0.
• The failure reproduces byte-identically with conda-forge PETSc 3.25.3 and the custom 3.25.0 build, on any source branch that postdates May 24.

The fix

DMInterpolationSetUp_UW gains an explicit hintAuthoritative flag, separating the hint's two roles:

• simplex / manifold meshes: hint is authoritative, DMLocatePoints is bypassed — unchanged behaviour;
• quad / hex volume meshes: DMLocatePoints remains authoritative (the kd-tree nearest hint can be wrong on deformed cells), but the hint again rescues points it drops — restored behaviour.

For located points nothing changes: DMLocatePoints results always overwrite the hint. The evaluator's wrapper (_dminterp_wrapper.pyx) now always passes the hint and only varies the flag.

Testing

• New level_1/tier_a regression test: linear-field evaluation at points on every closed face of quad and simplex boxes (would have caught this immediately — the top face returned zeros).
• tests/test_1052_VEP_stability_regression.py: 5/5 pass (was 3 failing).
• level_1 + tier_a gate: 437 passed.
• Parallel suite (mpirun -np 2): 92 passed; the single failure (test_0765 deformed-shell) is pre-existing and carries its own TODO(BUG) note about the PR fix: medium Track-0 misc — parallel BoxInternalBoundary, SL theta restore, viewer crash, projection double-count, units-boundary honesty (BF-10a/12/13/15/18, D9) #326 _deform_mesh guard.

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]

Design follow-up agreed with Louis: #391 stays scoped to restoring the hint recovery (exact for regular/near-regular quad geometry). The general resolution — NaN sentinel instead of zero-fill, plus an RBF fallback rung for deformed quad/hex meshes where the kd-tree hint is not trustworthy — is tracked as #392.