Nodal Lagrange basis on supported reference finite elements. More...

#include <LagrangeBasis.h>

Inheritance diagram for svmp::FE::basis::LagrangeBasis:

Public Types
using	TensorNodeIndex = std::array< std::size_t, 3 >
	Axis-index tuple for tensor-product reference nodes.

using	SimplexExponent = std::array< int, 4 >
	Barycentric exponent tuple for simplex reference nodes.

using	WedgeNodeIndex = std::array< std::size_t, 2 >
	Triangle-node and axis-node tuple for wedge reference nodes.

Public Member Functions
	LagrangeBasis (BasisTopology topology, int order)
	Construct a Lagrange basis on a reference topology at a polynomial order.

	LagrangeBasis (ElementType type, int order)
	Construct a Lagrange basis from a named element layout.

	LagrangeBasis (ElementType type)
	Construct a Lagrange basis from a named element layout at its baked-in 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 Lagrange basis values into caller-provided storage.

void	evaluate_gradients_to (const math::Vector< double, 3 > &xi, std::span< Gradient > gradients_out) const final
	Evaluate Lagrange basis gradients into caller-provided storage.

void	evaluate_hessians_to (const math::Vector< double, 3 > &xi, std::span< Hessian > hessians_out) const final
	Evaluate Lagrange 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

Nodal Lagrange basis on supported reference finite elements.

LagrangeBasis represents the complete (full-degree) nodal interpolation basis on a reference topology. It supports point, line, quadrilateral, hexahedron, triangle, tetrahedron, and wedge reference topologies. The primary constructor takes a BasisTopology and an explicit polynomial order, so an arbitrary order carries no node-count assumption (an order-2 hexahedron is BasisTopology::Hexahedron with order 2). A named ElementType such as Line3, Quad9, Tetra10, or Hex27 is a fixed-order shorthand: it maps to the same (topology, order) pair and the requested order must equal the order baked into that layout (1 for the linear elements, 2 for the complete-quadratic aliases, 0 for Point1).

Reference-node distribution

The interpolation nodes are not a single distribution across topologies; each family uses the node set its evaluator is built for:

Tensor-product (line, quadrilateral, hexahedron): the shared Gauss-Lobatto-Legendre (GLL) tensor-axis nodes – see line_coord_pm_one for the distribution and its conditioning – not an equispaced layout.
Simplex (triangle, tetrahedron): the equispaced barycentric lattice (each barycentric coordinate at \(i/p\)). The closed-form evaluator below is specific to this equispaced lattice.
Wedge: the tensor product of an equispaced triangle cross-section with a GLL through-axis.

Because GLL coincides with the equispaced layout at orders 1 and 2 (line_coord_pm_one), the linear and quadratic tensor elements – Line2/Line3, Quad4/Quad9, Hex8/Hex27, and the wedge through-axis – are built on equispaced nodes, and the GLL/equispaced distinction appears only for order >= 3.

Evaluation

Tensor-product elements use the one-dimensional nodal polynomials

\[ l_i(x) = \prod_{j \ne i} \frac{x - x_j}{x_i - x_j} \]

on the per-axis GLL coordinates \(x_j \in [-1, 1]\) (the barycentric-weight form, valid for any distinct node set). Multi-dimensional basis functions are products of the active axis polynomials, for example \(N_{ijk}(r,s,t) = l_i(r)l_j(s)l_k(t)\) on a hexahedron.

Simplex elements use barycentric coordinates and integer lattice exponents on the equispaced lattice. For a node with exponent tuple \(\alpha\), where \(\sum_a \alpha_a = p\), the basis is assembled from scaled falling-factorial factors,

\[ N_\alpha(\lambda) = \prod_a \prod_{m=0}^{\alpha_a-1} \frac{p\lambda_a - m}{m + 1}. \]

Gradients and Hessians are evaluated analytically by differentiating these factors and applying the barycentric-coordinate chain rule.

Wedge elements are treated as a tensor product between a triangle simplex basis and a one-dimensional through-axis basis: \(N_{a k}(r,s,t) = T_a(r,s)l_k(t)\).

Conditioning and the supported order range

Interpolation conditioning is governed by the node distribution and so differs by topology:

Tensor-product topologies stay well-conditioned at high order. GLL nodes have a logarithmic Lebesgue constant, so line/quadrilateral/hexahedron bases remain trustworthy well beyond the production orders.
Simplex topologies degrade at high order. The equispaced barycentric lattice has a Lebesgue constant that grows roughly exponentially with order (the Runge phenomenon), so triangle and tetrahedron bases are reliable through low orders but become increasingly ill-conditioned beyond them. The wedge inherits this through its equispaced triangle cross-section.

The vector-returning evaluators are convenient API wrappers. The *_to methods write to caller-provided spans and are intended for assembly paths that avoid temporary allocations.

Member Typedef Documentation

◆ SimplexExponent

using svmp::FE::basis::LagrangeBasis::SimplexExponent = std::array<int, 4>

Barycentric exponent tuple for simplex reference nodes.

◆ TensorNodeIndex

using svmp::FE::basis::LagrangeBasis::TensorNodeIndex = std::array<std::size_t, 3>

Axis-index tuple for tensor-product reference nodes.

◆ WedgeNodeIndex

using svmp::FE::basis::LagrangeBasis::WedgeNodeIndex = std::array<std::size_t, 2>

Triangle-node and axis-node tuple for wedge reference nodes.

Constructor & Destructor Documentation

◆ LagrangeBasis() [1/3]

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

Construct a Lagrange basis on a reference topology at a polynomial order.

This is the primary, arbitrary-order entry point: a BasisTopology carries no node-count assumption, so any supported order is requested explicitly (e.g. an order-5 hexahedron is BasisTopology::Hexahedron with order 5). The constructor builds the reference node coordinates and the topology-specific lookup data used by evaluation. Tensor-product bases store per-axis node indices, simplex bases store barycentric exponent tuples, and wedge bases store the triangle-node/axis-node decomposition.

Reference nodes follow the per-topology distribution described in the class documentation (Reference-node distribution). Unlike SerendipityBasis, this constructor does not reject ill-conditioned high-order simplex/wedge requests (where the equispaced barycentric lattice degrades); that choice is the caller's.

Parameters

topology	Reference topology; Point through the volume topologies.
order	Polynomial order; must be non-negative. Point is order 0.

Exceptions

BasisConfigurationException	If the order is negative, or if Point is requested with a nonzero order.
BasisElementCompatibilityException	If the topology is Unknown.

◆ LagrangeBasis() [2/3]

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

Construct a Lagrange basis from a named element layout.

Convenience overload for a named mesh element. The order is baked into the layout (0 for Point1, 1 for the linear elements, 2 for the complete-quadratic aliases such as Hex27/Tetra10) and the requested order must match it; arbitrary orders must be requested through the BasisTopology overload. Serendipity and pyramid layouts are rejected.

Parameters

type	Named element type used to determine topology and baked-in order.
order	Requested order; must equal the element's baked-in order.

Exceptions

BasisConfigurationException	If `order` does not match the element's baked-in order.
BasisElementCompatibilityException	If the element type is unsupported.

◆ LagrangeBasis() [3/3]

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

explicit

Construct a Lagrange basis from a named element layout at its baked-in order.

Single-argument convenience overload: the polynomial order is the one baked into the layout (0 for Point1, 1 for the linear elements, 2 for the complete-quadratic aliases such as Hex27/Tetra10), so the caller does not repeat it. Equivalent to LagrangeBasis(type, <baked-in order>). Serendipity and pyramid layouts are rejected, as for the two-argument overload.

Parameters

type	Named element type; determines both topology and order.

Exceptions

BasisElementCompatibilityException If the element type is unsupported.

Member Function Documentation

◆ basis_type()

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

inlinefinalvirtualnoexcept

Return the concrete basis family.

Returns: Basis family identifier.

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

◆ dimension()

int svmp::FE::basis::LagrangeBasis::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::LagrangeBasis::evaluate_gradients_to	(	const math::Vector< double, 3 > &	xi,
		std::span< Gradient >	gradients_out
	)		const

finalvirtual

Evaluate Lagrange basis gradients into caller-provided storage.

Gradients are written in basis-node order with one three-component gradient per node.

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::LagrangeBasis::evaluate_hessians_to	(	const math::Vector< double, 3 > &	xi,
		std::span< Hessian >	hessians_out
	)		const

finalvirtual

Evaluate Lagrange basis Hessians into caller-provided storage.

Hessians are written in basis-node order with one 3-by-3 Hessian per node.

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::LagrangeBasis::evaluate_values_to	(	const math::Vector< double, 3 > &	xi,
		std::span< double >	values_out
	)		const

finalvirtual

Evaluate Lagrange basis values into caller-provided storage.

This is the low-allocation API intended for element assembly loops. The span is filled in basis-node order and no vector resizing is performed.

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::LagrangeBasis::nodes ( ) const

inlinefinalvirtualnoexcept

Return the reference interpolation nodes in basis ordering.

The returned node order matches the basis-function order used by all evaluators; the coordinates follow the per-topology distribution described in the class documentation (Reference-node distribution).

Returns: Reference node coordinates, one per basis function.

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

◆ order()

int svmp::FE::basis::LagrangeBasis::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::LagrangeBasis::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::LagrangeBasis::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/LagrangeBasis.h
solver/FE/Basis/LagrangeBasis.cpp

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Reference-node distribution

Evaluation

Conditioning and the supported order range

Member Typedef Documentation

◆ SimplexExponent

◆ TensorNodeIndex

◆ WedgeNodeIndex

Constructor & Destructor Documentation

◆ LagrangeBasis() [1/3]

◆ LagrangeBasis() [2/3]

◆ LagrangeBasis() [3/3]

Member Function Documentation

◆ basis_type()

◆ dimension()

◆ evaluate_gradients_to()

◆ evaluate_hessians_to()

◆ evaluate_values_to()

◆ nodes()

◆ order()

◆ size()

◆ topology()