Skip to content

Add Elem::face_orientation() and fix 3D hierarchic shape functions across shared faces - #4579

Merged
lindsayad merged 6 commits into
libMesh:develfrom
lindsayad:elem-orientation
Oct 8, 2026
Merged

lindsayad merged 6 commits into
libMesh:develfrom
lindsayad:elem-orientation

Conversation

@lindsayad

@lindsayad lindsayad commented Sep 30, 2026 •

Copy link
Copy Markdown
Member

Fixes 3D HIERARCHIC and SIDE_HIERARCHIC shape functions that disagreed between two elements sharing a face at order >= 3. Seven cases in cube_indices(), cube_remap(), prism_indices() and fe_hierarchic_3D_shape() produced the shape function of the wrong face symmetry. For example, the HEX27 flip bit in cube_remap() was always true, so SIDE_HIERARCHIC was non-conforming from order 3 up, and the transposing cases of the prism quadrilateral faces swapped both the mode indices and the in-face coordinates, which cancels. The second commit's message itemizes each case.

Adds Elem::face_orientation(), which reports which of a face's 6 (triangle) or 8 (quadrilateral) symmetries relates the element's numbering of the face to an ordering every element computes alike: the least vertex, then its lesser neighbor. Elem::oriented_face_vertices() returns the face's vertices in that ordering, so callers do not decode the index themselves. positive_face_orientation() is now the low bit of face_orientation(). The 3D hierarchic shape code takes every face orientation from these, replacing the eight-case tree per quadrilateral face and four vertex-sorting helpers.

The new FEOrientationTest checks, on a skewed mesh over every element permutation, that the shape functions of each face and edge DOF depend only on the orientation index of the entity that owns it, and that neighbors agree on shared DOFs. FEHybridOrientationTest runs the same checks on a mesh where a prism shares quadrilateral faces with a hexahedron and with a prism extruded along a different axis, and its top triangle with a tetrahedron.

The FE tests now also compare each family against its exact solution at points just past every vertex along every edge direction, outside the element (the general test we deferred from #4585). These tests catch the edge orientation sign fixed in that PR, for HIERARCHIC and L2_HIERARCHIC triangles, tetrahedra and prisms, so they replace the simpler HierarchicSimplexEdgeTest. Against the prism face code before this PR the new general testing added here would fail at fourth order, where the old transposed face bases were rational functions that blew up outside the element.

🤖 Mostly generated with Claude Code

@moosebuild

moosebuild commented Sep 30, 2026 •

Copy link
Copy Markdown

Job Coverage, step Generate coverage on c64691f wanted to post the following:

Coverage

acab14 #4579 c64691
Total Total +/- New
Rate 66.05% 66.12% +0.06% 100.00%
Hits 79873 79745 -128 69
Misses 41051 40870 -181 0

Diff coverage report

Full coverage report

This comment will be updated on new commits.

@lindsayad lindsayad changed the title Fix 3D hierarchic shape functions across shared faces Add Elem::face_orientation() and fix 3D hierarchic shape functions across shared faces Oct 4, 2026
@lindsayad
lindsayad force-pushed the elem-orientation branch 2 times, most recently from ec7eb2b to f9bea66 Compare October 5, 2026 18:17
lindsayad and others added 3 commits October 5, 2026 13:49
positive_face_orientation() reports the direction in which a face's vertices
run, which is a single bit. A basis whose shape functions follow the order of a
face's vertices needs the whole ordering, including which vertex is the
lexicographically least, so that two elements sharing a face arrive at the same
shape function for a degree of freedom they share. That single bit leaves the
least vertex of a face with more than three vertices open.

face_orientation() carries the whole ordering, as twice the position that the
least vertex takes in the face's node map plus the direction bit, so it runs
over the six symmetries of a triangular face or the eight of a quadrilateral
face. positive_face_orientation() now reads its low bit.
oriented_face_vertices() decodes the index into the face's vertices in that
ordering, so that callers need not decode it themselves.

The new ElemTest cases hold face_orientation() to agreeing with
positive_face_orientation() and to naming the least vertex, and hold two
elements sharing a face to the same oriented_face_vertices(), which is the
property that lets the index select a conforming shape function.

Co-Authored-By: Claude <noreply@anthropic.com>
A hierarchic basis of order three or above places degrees of freedom on the
faces of a 3D element, and the two elements sharing a face have to arrive at the
same shape function for each of them. Seven places did not.

HEX27, in cube_indices(): face 1 case 7 and face 5 case 8 rewrote the reference
coordinates with the transformation of another case, so two of the eight
symmetries of those faces produced a shape function belonging to a different
symmetry.

PRISM*, in prism_indices(): a transposing case has to swap either the mode
indices or the in-plane coordinates. The transposing cases of all three
quadrilateral faces did both, which cancels, so two symmetries differing only in
the direction bit produced identical shape functions. Face 2 case 1 hard-coded
the offset from an edge to the second triangle's numbering, which holds only at
order three, and cases 5 through 8 of that face reflected a coordinate that
needs no reflection there.

PRISM*, in fe_hierarchic_3D_shape(): the parity of a triangle edge mode was
taken from the wrong index base, which agrees with the mode number only at order
three.

PRISM*, in prism_indices(): the interior basis of a triangle is not symmetric in
its barycentric coordinates, so the two triangular faces need those coordinates
ordered by the face's vertices, as the tetrahedral faces already are. The
comment saying the TRI code handled this was mistaken; it orders the edge modes
of a triangle, not the barycentric coordinates a face's interior modes read.

HEX27, in cube_remap(): the flip bit of a quadrilateral face compared the least
node of the face against a neighbor, which is true for any two distinct points,
so the four symmetries reached through a reflection were unreachable and
SIDE_HIERARCHIC was non-conforming from order three up. Rotating the least node
to the origin leaves the reflection about the diagonal through it, which is
settled by which of that node's two neighbors is the lesser. cube_remap() now
takes both from orient_quad().

The new FEOrientationTest holds each family to two properties on a skewed mesh:
that the shape functions of a degree of freedom follow the orientation index of
the one entity that owns it, and that two elements sharing a side agree on the
shape function of a degree of freedom they share. Each of the seven shape
function corrections above is needed for that agreement between neighbors.
Following the orientation index is what lets a cache of reference shape
functions carry one entry per entity and orientation. A side-only family has no
shape value at an interior point, so FEConformityTest checks only the
agreement between neighbors.

Co-Authored-By: Claude <noreply@anthropic.com>
The 3D hierarchic shape code worked out each face's orientation on its own.
cube_indices() and prism_indices() picked one of eight hand-written cases per
quadrilateral face from point comparisons, and four helpers sorted face
vertices for the triangular faces and for SIDE_HIERARCHIC. Each case is a
symmetry of the face that Elem::face_orientation() already identifies.

All of them now read one vertex ordering, Elem::oriented_face_vertices(): the
face's least vertex, then its lesser neighbor. The
in-face coordinates of a hex face are projections onto the two axes that
ordering defines, so the six faces share one block. The symmetry of a prism
quadrilateral face is a swap of its two modes, a reflection of zeta, and a
reflection of the triangle, each read from the same ordering. This removes the
per-face case trees, get_min_point(), orient_quad(), orient_triangle(),
oriented_prism_nodes() and oriented_tet_nodes().

Shape values are unchanged to within roundoff. Over every permutation of
skewed HEX27, PRISM21 and TET14 elements, HIERARCHIC, L2_HIERARCHIC and
SIDE_HIERARCHIC values at orders three through five agree with the previous
code to a relative 3e-17, and their finite-difference derivatives to 4e-11.

Co-Authored-By: Claude <noreply@anthropic.com>
lindsayad and others added 3 commits October 5, 2026 16:04
The FE tests compared each family against its exact solution only at points
inside the element. Shape functions are also evaluated just outside it: the
finite-difference derivatives of HIERARCHIC simplices and prisms place half
their stencil outside the element at any point on its boundary, and
inverse_map() of a point on or near a boundary can return a reference point
slightly outside. A basis is a polynomial (or rational function) there too, so
the projected solution has to keep matching the exact solution.

testUPastVertices and testGradUPastVertices evaluate at offsets from every
vertex along every edge direction. Offsets of a quarter edge reach the loci
where HIERARCHIC simplex edge functions switch to their limiting expression,
the line through a triangle vertex parallel to the opposite edge and the
plane through a tetrahedron edge parallel to the opposite edge, and a
power-of-two offset makes that switch happen in floating point as it does in
exact arithmetic. With the edge orientation sign of libMesh#4585 reverted, these
tests fail for HIERARCHIC and L2_HIERARCHIC triangles, tetrahedra and prisms
at third and fourth order, so they replace HierarchicSimplexEdgeTest.

The tolerances past the vertices grow with the order p by T_p(1.5), the
Chebyshev bound on how much a degree p polynomial within a tolerance on an
edge can grow a quarter edge beyond it. A fixed factor covers only low orders:
past some vertices the error of FIFTH MONOMIAL on TET14 reaches twelve times
the interior tolerance.

Co-Authored-By: Claude <noreply@anthropic.com>
…ypes

FEOrientationTest built every mesh from a single element type with
build_cube(), so no face it checked was shared by two element types, and
every pair of neighboring prisms was extruded in the same direction.
FEHybridOrientationTest runs the same checks on a mesh in which a prism
shares one quadrilateral face with a hexahedron, another with a prism
extruded along a different axis, and its top triangle with a tetrahedron.
With the 3D hierarchic shape functions as they were before this branch,
its conformity check fails at third and fourth order.

The number of permutation rounds now comes from the elements in the mesh,
which is the same as before for a single element type.

The checks move to FEOrientationTestBase, which leaves building the mesh to
its subclasses: FEOrientationTest for a cube of one element type and
FEHybridOrientationTest for the mixed mesh.

Co-Authored-By: Claude <noreply@anthropic.com>
Phrasing a comparison as a negated opposite, such as "grows no faster" for
"grows more slowly", reads as machine-drafted and states a weaker claim than
intended. Ask for the direct comparison, and reserve bound phrasing for claims
that are genuinely non-strict bounds.

Co-Authored-By: Claude <noreply@anthropic.com>
@lindsayad
lindsayad marked this pull request as ready for review October 6, 2026 03:39
@lindsayad
lindsayad merged commit 342ad76 into libMesh:devel Oct 8, 2026
23 checks passed
@lindsayad
lindsayad deleted the elem-orientation branch October 8, 2026 21:38
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.

3 participants