Skip to content

feat(evaluate): measured point-location capability + NaN/RBF fallback ladder#394

Closed
lmoresi wants to merge 3 commits into
bugfix/dminterp-hint-fallbackfrom
feature/point-location-capability
Closed

feat(evaluate): measured point-location capability + NaN/RBF fallback ladder#394
lmoresi wants to merge 3 commits into
bugfix/dminterp-hint-fallbackfrom
feature/point-location-capability

Conversation

@lmoresi

@lmoresi lmoresi commented Jul 22, 2026

Copy link
Copy Markdown
Member

Implements #392 (stacked on #391 — retarget to development once that merges; the diff shown here is the capability-ladder work only).

What this does

Makes the cell locator's authority (i.e. is it authoritative or an estimator) a measured mesh property instead of an isSimplex() type flag, and completes the fallback ladder agreed on #392 so quad/hex meshes keep working with a fallback that simplex meshes don't need.

Mesh._location_capability() audits face planarity (sagitta) and cell convexity, cached against (_mesh_version, _topology_version) so deform() and adaptation refresh it automatically:

  • exact — simplex, manifold, and any quad/hex mesh whose faces are planar and cells convex at machine level. This graduates all valid 2-D quad meshes, deformed included (straight edges are always planar; convexity is equivalent to an untangled mesh — verified 4000/4000 against exact polygon containment on a deformed box) and rectilinear/affine hex boxes to simplex-grade location: the hint bypasses DMLocatePoints.
  • continuous — warped hexes within a 5% sagitta tolerance (cubed-sphere class: 64% of faces exactly planar, spherical faces ≤ 1e-2). Authoritative for continuous fields only — a misclassified point lands in the face-adjacent neighbour where continuous FE interpolants agree to O(sagitta × gradient); a face-aligned jump (layered viscosity on a spherical shell) would see O(jump) errors.
  • none — badly warped / non-convex cells: no authority.

The ladder: non-authoritative evaluations (capability none, or continuous with a discontinuous variable in the mix) run DMLocatePoints; points it drops (the #390 class — queries exactly on the domain's closed upper faces) are NaN-filled — never zeros — reported via a new unlocated mask, and filled per-variable through rbf_interpolate: bounded, topology-free, honest. NaN survives only if the plumbing is bypassed, which is exactly when it should be visible.

The policy lives in one place (Mesh._hint_is_authoritative) and joins the DMInterpolation cache key (same coords with a different field-continuity mix legitimately need different structures).

Testing

  • Three new tier_a tests in test_0503: capability grading of regular/deformed quad and hex meshes; deformed-quad boundary evaluation exact to 1e-8; warped-hex RBF rung (no NaN escapes, no silent zeros, values bounded by data range).
  • test_1052 VEP stability: 5/5 (the shear box now takes the authoritative bypass).
  • level_1 + tier_a gate: 440 passed.
  • Parallel np2 suite: identical to baseline (92 passed; the single failure is the pre-existing test_0765 _deform_mesh-guard issue with its own TODO).

Design record: issue #392 and docs/developer/design/point-location-capability.md.

Underworld development team with AI support from Claude Code

… ladder (#392)

The cell-wall estimator's authority is now a MEASURED mesh property, not an
isSimplex() type flag. Mesh._location_capability() audits face planarity
(sagitta) and cell convexity per mesh, cached against the mesh/topology
version so deform() and adaptation refresh it:

- "exact"      — simplex, manifold, and any quad/hex mesh with planar faces
                 and convex cells at machine level. This graduates ALL valid
                 2-D quad meshes (deformed included — straight edges are
                 always planar, convexity is equivalent to an untangled
                 mesh) and rectilinear/affine hex boxes to simplex-grade
                 authoritative location: the hint bypasses DMLocatePoints.
- "continuous" — warped hexes within a 5% sagitta tolerance (cubed-sphere
                 class). Authoritative for continuous fields only: a
                 misclassified point lands in the face-adjacent neighbour,
                 where continuous FE interpolants agree to O(sagitta x
                 gradient); a face-aligned jump would see O(jump) errors.
- "none"       — badly warped or non-convex cells: no authority.

Evaluations that are NOT authoritative (capability "none", or "continuous"
with a discontinuous variable in the mix) run DMLocatePoints, and points it
drops — e.g. queries exactly on the domain's closed upper faces, the #390
class — are NaN-filled (never zeros), reported via a new unlocated mask,
and filled per-variable through the RBF interpolant: bounded, topology-free,
honest. NaN can only survive if that plumbing is bypassed, which is exactly
when it should be visible.

The policy lives in one place (Mesh._hint_is_authoritative) and joins the
DMInterpolation cache key, since the same coords with a different
field-continuity mix legitimately need different structures.

Design record: issue #392 and docs/developer/design/point-location-capability.md.

Validation: test_0503 11/11 (three new tests: capability grading, deformed-
quad exactness, warped-hex RBF rung), test_1052 5/5, level_1+tier_a gate
440 passed, np2 parallel suite unchanged from baseline.

Underworld development team with AI support from Claude Code
lmoresi added 2 commits July 23, 2026 10:41
… crash

The test job dies with zero pytest output ~2s into each batch — a hard
crash during import underworld3 on the linux runner, before pytest's
first stdout flush. Reproduce attempts on macOS (custom PETSc 3.25.0 and
conda PETSc 3.25.3 dev env) all pass, so surface the crash point in CI
with faulthandler. This commit will be reverted once the cause is fixed.

Underworld development team with AI support from Claude Code
The PR #394 'failure' turned out to be a runner-side flake: pytest died
during import underworld3 before its first stdout flush, so all eight
serial batches failed with zero output — undiagnosable from the log.
The identical code passed once re-run. Keep the 5-second faulthandler
import step so any future import-time crash is loud and localised
instead of silent.

Underworld development team with AI support from Claude Code
@lmoresi

lmoresi commented Jul 23, 2026

Copy link
Copy Markdown
Member Author

CI resolved — the failure was a runner-side flake, not the code. The failing run died during import underworld3 before pytest's first stdout flush (every batch ~2s, zero output, undiagnosable from the log). A faulthandler import smoke step was added to surface the crash point; on the very next run the identical code imported cleanly and the full test job passed (25 min, green). The smoke step is kept as a permanent 5-second guard so any future import-time crash is loud and localised. Local reproduction attempts on both custom PETSc 3.25.0 and conda-forge PETSc 3.25.3 (full CI batch selection via scripts/test.sh) were green throughout.

@lmoresi
lmoresi deleted the branch bugfix/dminterp-hint-fallback July 23, 2026 01:04
@lmoresi lmoresi closed this Jul 23, 2026
lmoresi added a commit that referenced this pull request Jul 23, 2026
… ladder (#392) (#395)

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

PETSc's point location uses a half-open cell convention: a query point
sitting exactly on the domain's closed upper face (e.g. y = y_max on a
StructuredQuadBox) belongs to the cell "above", which doesn't exist, so
DMLocatePoints silently drops it and the evaluator zero-fills the result.

Semi-Lagrangian stress-history trace-backs slide departure points along
the top boundary of the shear box, so every step read psi* = 0 there
instead of the true history. The BDF history update then amplified that
boundary corruption exponentially — the test_1052 VEP "blow-up"
(max|err| = 240 vs threshold 0.10). With this fix the run returns
max|err| = 0.063, matching the value recorded when the test was written.

This was a UW3 regression, not a PETSc 3.25 change: before 17a5a8d the
kd-tree cell hint was always passed to DMInterpolationSetUp_UW and
prefilled the dropped-point recovery map. When the hint pointer became
the bypass switch (simplex/manifold only), quad/hex meshes lost the
recovery. PETSc's plexgeometry.c is unchanged between 3.24.2 and 3.25.0.

The fix separates the two roles with an explicit hintAuthoritative flag:

- simplex / manifold meshes: hint is authoritative, DMLocatePoints is
  bypassed (unchanged behaviour);
- quad / hex volume meshes: DMLocatePoints remains authoritative, but
  the hint again rescues points it drops, evaluated in the adjacent
  cell with reference-coordinate clamping (restored behaviour).

Adds a level_1/tier_a regression test evaluating a linear field at
points on every closed face of quad and simplex boxes.

Underworld development team with AI support from Claude Code

* feat(evaluate): measured point-location capability + NaN/RBF fallback ladder (#392)

The cell-wall estimator's authority is now a MEASURED mesh property, not an
isSimplex() type flag. Mesh._location_capability() audits face planarity
(sagitta) and cell convexity per mesh, cached against the mesh/topology
version so deform() and adaptation refresh it:

- "exact"      — simplex, manifold, and any quad/hex mesh with planar faces
                 and convex cells at machine level. This graduates ALL valid
                 2-D quad meshes (deformed included — straight edges are
                 always planar, convexity is equivalent to an untangled
                 mesh) and rectilinear/affine hex boxes to simplex-grade
                 authoritative location: the hint bypasses DMLocatePoints.
- "continuous" — warped hexes within a 5% sagitta tolerance (cubed-sphere
                 class). Authoritative for continuous fields only: a
                 misclassified point lands in the face-adjacent neighbour,
                 where continuous FE interpolants agree to O(sagitta x
                 gradient); a face-aligned jump would see O(jump) errors.
- "none"       — badly warped or non-convex cells: no authority.

Evaluations that are NOT authoritative (capability "none", or "continuous"
with a discontinuous variable in the mix) run DMLocatePoints, and points it
drops — e.g. queries exactly on the domain's closed upper faces, the #390
class — are NaN-filled (never zeros), reported via a new unlocated mask,
and filled per-variable through the RBF interpolant: bounded, topology-free,
honest. NaN can only survive if that plumbing is bypassed, which is exactly
when it should be visible.

The policy lives in one place (Mesh._hint_is_authoritative) and joins the
DMInterpolation cache key, since the same coords with a different
field-continuity mix legitimately need different structures.

Design record: issue #392 and docs/developer/design/point-location-capability.md.

Validation: test_0503 11/11 (three new tests: capability grading, deformed-
quad exactness, warped-hex RBF rung), test_1052 5/5, level_1+tier_a gate
440 passed, np2 parallel suite unchanged from baseline.

Underworld development team with AI support from Claude Code

* ci: TEMPORARY faulthandler import smoke test to surface the silent CI crash

The test job dies with zero pytest output ~2s into each batch — a hard
crash during import underworld3 on the linux runner, before pytest's
first stdout flush. Reproduce attempts on macOS (custom PETSc 3.25.0 and
conda PETSc 3.25.3 dev env) all pass, so surface the crash point in CI
with faulthandler. This commit will be reverted once the cause is fixed.

Underworld development team with AI support from Claude Code

* ci: keep the import smoke test as a permanent guard

The PR #394 'failure' turned out to be a runner-side flake: pytest died
during import underworld3 before its first stdout flush, so all eight
serial batches failed with zero output — undiagnosable from the log.
The identical code passed once re-run. Keep the 5-second faulthandler
import step so any future import-time crash is loud and localised
instead of silent.

Underworld development team with AI support from Claude Code
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant