svmp::FE::basis::SerendipityBasis Class Reference

Reduced-degree-of-freedom serendipity basis on supported reference elements. More...

#include <SerendipityBasis.h>

Inheritance diagram for svmp::FE::basis::SerendipityBasis:

Public Member Functions
	SerendipityBasis (BasisTopology topology, int order)
	Construct an arbitrary-order quadrilateral or hexahedral serendipity basis.
	SerendipityBasis (ElementType type, int order)
	Construct a serendipity basis from a named element layout.
	SerendipityBasis (ElementType type)
	Construct a serendipity basis from a named layout at its fixed order.
BasisType	basis_type () const noexcept final
	Return the concrete basis family.
BasisTopology	topology () const noexcept final
	Return the reference topology of this basis.
int	dimension () const noexcept final
	Return the reference-space dimension of the basis.
int	order () const noexcept final
	Return the polynomial order represented by this basis.
std::size_t	size () const noexcept final
	Return the number of basis functions and reference nodes.
const std::vector< math::Vector< double, 3 > > &	nodes () const noexcept final
	Return the reference interpolation nodes in basis ordering.
void	evaluate_values_to (const math::Vector< double, 3 > &xi, std::span< double > values_out) const final
	Evaluate serendipity basis values into caller-provided storage.
void	evaluate_gradients_to (const math::Vector< double, 3 > &xi, std::span< Gradient > gradients_out) const final
	Evaluate serendipity basis gradients into caller-provided storage.
void	evaluate_hessians_to (const math::Vector< double, 3 > &xi, std::span< Hessian > hessians_out) const final
	Evaluate serendipity basis Hessians into caller-provided storage.
Public Member Functions inherited from svmp::FE::basis::BasisFunction
virtual	~BasisFunction ()=default
	Destroy a basis function through the abstract interface.
void	evaluate_values (const math::Vector< double, 3 > &xi, std::vector< double > &values) const
	Evaluate basis function values at a reference coordinate.
void	evaluate_gradients (const math::Vector< double, 3 > &xi, std::vector< Gradient > &gradients) const
	Evaluate basis gradients at a reference coordinate.
void	evaluate_hessians (const math::Vector< double, 3 > &xi, std::vector< Hessian > &hessians) const
	Evaluate basis Hessians at a reference coordinate.
void	evaluate_all (const math::Vector< double, 3 > &xi, std::vector< double > &values, std::vector< Gradient > &gradients, std::vector< Hessian > &hessians) const
	Evaluate values, gradients, and Hessians together.

Additional Inherited Members
Protected Member Functions inherited from svmp::FE::basis::BasisFunction
void	numerical_gradient (const math::Vector< double, 3 > &xi, std::vector< Gradient > &gradients, double eps=double(1e-6)) const
	Approximate gradients by centered finite differences of values.
void	numerical_hessian (const math::Vector< double, 3 > &xi, std::vector< Hessian > &hessians, double eps=double(1e-5)) const
	Approximate Hessians by centered finite differences of gradients.

Detailed Description

Reduced-degree-of-freedom serendipity basis on supported reference elements.

SerendipityBasis implements nodal bases for the quadrilateral and hexahedral serendipity families at arbitrary order, plus the Wedge15 prism layout. Compared with a complete tensor-product Lagrange basis of the same nominal order, a serendipity basis removes selected interior modes while retaining nodal interpolation on the supported node layout. The named layouts Quad8, Hex8, and Hex20 are the fixed-order instances of these families (quadrilateral order 2, hexahedron orders 1 and 2).

The quadrilateral serendipity polynomial space is described by monomials \(x^{a_x}y^{a_y}\) whose superlinear degree is at most the requested order. The implementation evaluates this space through tensor Legendre modes, which span the same polynomial space but give a better-conditioned Vandermonde. The superlinear degree is

\[ sldeg(x^{a_x}y^{a_y}) = \begin{cases} a_x, & a_x > 1 \\ 0, & a_x \le 1 \end{cases} + \begin{cases} a_y, & a_y > 1 \\ 0, & a_y \le 1 \end{cases}. \]

The nodal basis is recovered by inverting the generalized Vandermonde interpolation matrix at the selected reference nodes. Values, gradients, and Hessians are then evaluated by differentiating the modal vector and applying the inverse Vandermonde coefficients. For order \(p \ge 1\), this space has \(4p\) boundary modes for \(p \le 3\) and

\[ 4p + \frac{(p - 3)(p - 2)}{2} \]

modes for \(p \ge 4\).

The quadrilateral node set is unisolvent by construction. If \(s(x,y)\) in this space vanishes at the \(p + 1\) distinct nodes on every edge, each edge restriction is a degree- \(p\) one-variable polynomial with \(p + 1\) roots, so all edge restrictions vanish. Thus \(s\) is divisible by the boundary bubble \((1 - x^2)(1 - y^2)\), and the quotient lies in \(P_{p-4}\) (with no quotient for \(p < 4\)). For \(p \ge 4\), the interior nodes form triangular rows for \(P_{p-4}\): the first row has \(m + 1\) distinct \(x\) values, the next row has \(m\), and so on for \(m = p - 4\). A total-degree polynomial that vanishes on those rows is zero by induction over rows, because each vanished row factors out one linear term in \(y\). The interpolation Vandermonde is therefore nonsingular for the implemented quadrilateral serendipity space.

Hexahedral serendipity generalizes the same construction to the cube. The polynomial space is described by every monomial \(r^{a_r}s^{a_s}t^{a_t}\) whose superlinear degree (the three-axis form of the rule above) is at most \(p\), and the nodal basis is again the inverse Vandermonde at the reference nodes. Those nodes are distributed by boundary stratum: 8 corners, \(12(p-1)\) edge nodes, \(6\,q(p)\) face-interior nodes – each face carries the 2D quadrilateral serendipity interior, since the trace of the cube space on a face is the square space – and a volume interior that is empty until \(p \ge 6\). Unisolvence follows the same factorization: a function vanishing on every boundary node vanishes on each face by the quadrilateral result above, hence is divisible by the cube bubble \((1 - r^2)(1 - s^2)(1 - t^2)\) with quotient in \(P_{p-6}\); the volume-interior nodes form a tetrahedral staircase that is unisolvent for \(P_{p-6}\) by induction over \(t\)-layers, so the cube Vandermonde is nonsingular.

SerendipityBasis(BasisTopology::Quadrilateral, p) and SerendipityBasis(BasisTopology::Hexahedron, p) are the arbitrary-order entry points ( \(p \ge 1\); orders below one are rejected). Reference nodes for both the arbitrary-order and the named paths come from the single ReferenceNodeLayout serendipity generator, in a VTK-consistent stratified order; for \(p \ge 3\) the interior ordering is an implementation convention rather than a public layout. The named fixed layouts – ElementType::Quad8 (order 2), Hex8 (order 1), and Hex20 (order 2) – are the same construction at those orders; the named overload only pins the order, so the named and topology constructions produce identical objects and share the single public node ordering the solver permutes against (order 1 and order 2 reuse the VTK corner/edge ordering exactly). Wedge serendipity remains a single fixed layout (Wedge15), constructed only from its named ElementType. Solver-default basis selection is separate: basis_factory maps the complete Quad4 layout to the default linear Lagrange basis and maps Quad8/Hex20 to serendipity unless a caller explicitly requests a different supported basis.

Every supported family – quadrilateral, hexahedral, and Wedge15 – is built by inverting the generalized Vandermonde of its mode space at the public-order reference nodes. Quadrilateral and hexahedral bases use tensor Legendre modes; the fixed Wedge15 table uses monomial modes. Values, gradients, and Hessians are evaluated by differentiating the matching mode vector and applying the inverse-Vandermonde coefficients. Because the tables are generated in public node order, evaluation needs no output reordering, and there is no hand-written special case – the Hex8 basis is the order-1 instance of the generated hexahedral space, not a separate trilinear evaluator.

Conditioning and the well-conditioned order range

High-order nodal interpolation is governed by two conditioning factors, both addressed so that arbitrary orders produce trustworthy shape functions:

• Node distribution. The quadrilateral and hexahedral families place their nodes on the shared Gauss-Lobatto-Legendre (GLL) distribution – edges, faces, and the interior staircase all use the GLL 1D nodes (line_coord_pm_one), whose logarithmic Lebesgue constant keeps high-order interpolation well-conditioned. The named production layouts are unaffected, since GLL coincides with the equispaced layout at orders 1 and 2 (so Quad8/Hex8/Hex20 keep their exact public coordinates); the layout is this module's own convention only for order >= 3.
• Modal basis. The quadrilateral and hexahedral Vandermondes are assembled in a tensor Legendre basis rather than raw monomials. The serendipity exponent set is downward-closed, so the Legendre and monomial spans are identical (the change of basis is triangular) – the nodal shape functions are unchanged – but the Legendre Vandermonde is far better conditioned. (The fixed Wedge15 layout, order 2, keeps the monomial form; it is trivially well-conditioned.)

Constructor & Destructor Documentation

SerendipityBasis() [1/3]

svmp::FE::basis::SerendipityBasis::SerendipityBasis	(	BasisTopology	topology,
		int	order
	)

Construct an arbitrary-order quadrilateral or hexahedral serendipity basis.

This is the arbitrary-order entry point for the serendipity families with a free order: the quadrilateral and the hexahedron. The topology carries no node-count assumption; the serendipity polynomial space, reference nodes (generated here in VTK-consistent stratified order), and nodal coefficient table are built from the requested order (which must be \(p \ge 1\)). Wedge serendipity is a single fixed layout and is not constructed this way – use the named ElementType overload (Wedge15).

Parameters

topology	Must be BasisTopology::Quadrilateral or BasisTopology::Hexahedron.
order	Polynomial order \(p \ge 1\); orders below 1 are rejected.

Exceptions

BasisConfigurationException	If order is less than 1.
BasisElementCompatibilityException	If topology is not Quadrilateral or Hexahedron.

SerendipityBasis() [2/3]

svmp::FE::basis::SerendipityBasis::SerendipityBasis	(	ElementType	type,
		int	order
	)

Construct a serendipity basis from a named element layout.

Convenience overload for the named, fixed serendipity layouts. Each layout is the fixed-order instance of its family, built through the same generated construction as the arbitrary-order path and taking its nodes from ReferenceNodeLayout: Quad8 is the quadrilateral at order 2, Hex8 and Hex20 are the hexahedron at orders 1 and 2, and Wedge15 is the prism layout. Each layout carries an inferred fixed order (Hex8 to 1; Quad8, Hex20, and Wedge15 to 2); the requested order must equal that inferred order and is never adjusted to fit, so a mismatched request (including order 0 or negative) is rejected. Arbitrary-order quadrilateral and hexahedral serendipity is requested through the BasisTopology overload.

Parameters

type	Named serendipity element type (Quad8, Hex8, Hex20, or Wedge15).
order	Requested order; must equal the layout's inferred fixed order (1 for Hex8; 2 for Quad8, Hex20, and Wedge15).

Exceptions

BasisConfigurationException	If order does not match the layout's inferred order.
BasisElementCompatibilityException	If the element type is unsupported.

SerendipityBasis() [3/3]

svmp::FE::basis::SerendipityBasis::SerendipityBasis ( ElementType  type )

explicit

Construct a serendipity basis from a named layout at its fixed order.

Single-argument convenience overload for the named serendipity layouts: the order is the one fixed by the layout (1 for Hex8; 2 for Quad8, Hex20, and Wedge15), so the caller does not repeat it. Equivalent to SerendipityBasis(type, <fixed order>).

Parameters

type	Named serendipity element type (Quad8, Hex8, Hex20, or Wedge15).

Exceptions

BasisElementCompatibilityException

If the element type is unsupported.

Member Function Documentation

basis_type()

BasisType svmp::FE::basis::SerendipityBasis::basis_type ( ) const

inlinefinalvirtualnoexcept

Return the concrete basis family.

Returns

Basis family identifier.

Implements svmp::FE::basis::BasisFunction.

dimension()

int svmp::FE::basis::SerendipityBasis::dimension ( ) const

inlinefinalvirtualnoexcept

Return the reference-space dimension of the basis.

Returns

Reference dimension, from zero for points through three for volume elements.

Implements svmp::FE::basis::BasisFunction.

evaluate_gradients_to()

void svmp::FE::basis::SerendipityBasis::evaluate_gradients_to ( const math::Vector< double, 3 > &  xi, std::span< Gradient >  gradients_out  ) const

finalvirtual

Evaluate serendipity basis gradients into caller-provided storage.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
gradients_out	Output span with at least size() entries.

Reimplemented from svmp::FE::basis::BasisFunction.

evaluate_hessians_to()

void svmp::FE::basis::SerendipityBasis::evaluate_hessians_to ( const math::Vector< double, 3 > &  xi, std::span< Hessian >  hessians_out  ) const

finalvirtual

Evaluate serendipity basis Hessians into caller-provided storage.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
hessians_out	Output span with at least size() entries.

Reimplemented from svmp::FE::basis::BasisFunction.

evaluate_values_to()

void svmp::FE::basis::SerendipityBasis::evaluate_values_to ( const math::Vector< double, 3 > &  xi, std::span< double >  values_out  ) const

finalvirtual

Evaluate serendipity basis values into caller-provided storage.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
values_out	Output span with at least size() entries.

Implements svmp::FE::basis::BasisFunction.

nodes()

const std::vector< math::Vector< double, 3 > > & svmp::FE::basis::SerendipityBasis::nodes ( ) const

inlinefinalvirtualnoexcept

Return the reference interpolation nodes in basis ordering.

Node coordinates are the points at which the serendipity basis satisfies the nodal interpolation property. All families take their nodes from ReferenceNodeLayout, the public node-ordering source the solver adapter permutes against: the fixed Wedge15 layout and the quadrilateral/hexahedral families (named or arbitrary-order) alike, in VTK-consistent stratified order – corners and edges first (matching the public Quad8/Hex8/Hex20 ordering at the named orders), then the face and volume interior points needed to make the reduced polynomial space unisolvent. For \(p \ge 3\) that interior ordering is an implementation convention; callers should pair it with basis values from the same object rather than assume an external mesh ordering contract beyond the supported named production layouts.

Returns

Reference node coordinates, one per basis function.

Reimplemented from svmp::FE::basis::BasisFunction.

order()

int svmp::FE::basis::SerendipityBasis::order ( ) const

inlinefinalvirtualnoexcept

Return the polynomial order represented by this basis.

Returns

Polynomial order of the basis. A named element layout reports the order implied by that layout (Quad8 and Hex20 report 2, Hex8 reports 1), not its node count.

Implements svmp::FE::basis::BasisFunction.

size()

std::size_t svmp::FE::basis::SerendipityBasis::size ( ) const

inlinefinalvirtualnoexcept

Return the number of basis functions and reference nodes.

Returns

Basis function count.

Implements svmp::FE::basis::BasisFunction.

topology()

BasisTopology svmp::FE::basis::SerendipityBasis::topology ( ) const

inlinefinalvirtualnoexcept

Return the reference topology of this basis.

Together with order() and basis_type(), this is the authoritative identity of a basis: a topology, a polynomial order, and a basis family, with no node-count assumption. The family is part of the identity because the same topology and order can denote different bases – a hexahedron at order 2 is the Hex20 serendipity space or the Hex27 Lagrange space depending on basis_type(). Arbitrary-order bases are constructed from a BasisTopology and an order; named ElementType layouts (Hex8, Hex27, ...) are a fixed-order shorthand that maps to the same (topology, order, family) triple.

Returns

Reference topology.

Implements svmp::FE::basis::BasisFunction.

---

The documentation for this class was generated from the following files:

• solver/FE/Basis/SerendipityBasis.h
• solver/FE/Basis/SerendipityBasis.cpp