Rodin›Variational

H1Element

Degree k H1-conforming Lagrange element.

Defined in Rodin/Variational/H1/H1Element.h

template <
  size_t K,
  class Scalar>
class H1Element;
Template parameters
K Polynomial degree

Continuous H1-conforming piecewise polynomial (degree k) scalar Lagrange element.

H1Element provides a high-order H1-conforming finite element implementation with arbitrary polynomial degree K. The element uses Lagrange nodal basis functions satisfying $ \phi_i(x_j) = \delta_{ij} $ .

SpecializationDescription
K, Math::SpatialMatrix<Scalar>
Full specialization
template <
  size_t K,
  class Scalar>
class H1Element<
  K,
  Math::SpatialMatrix< Scalar >> final;
Matrix-valued reference element built from scalar nodal functionals.
K, Math::SpatialVector<Scalar>
Full specialization
template <
  size_t K,
  class Scalar>
class H1Element<
  K,
  Math::SpatialVector< Scalar >> final;
Continuous H1-conforming piecewise polynomial (degree k) vector Lagrange element.

The H1Element provides a k-th order finite element with Lagrange basis functions. This is a high-order-stable H1-conforming element family.

Mathematical Properties

  • DOF count: Depends on geometry and polynomial degree K
    • Segment: K+1
    • Triangle: (K+1)(K+2)/2
    • Quadrilateral: (K+1)²
    • Tetrahedron: (K+1)(K+2)(K+3)/6
    • Wedge: (K+1)·(K+1)(K+2)/2
  • Basis functions: Lagrange polynomials of degree K satisfying the Lagrange property: $ \phi_i(x_j) = \delta_{ij} $ where $ x_j $ are the Lagrange nodes
  • Gradient: Polynomial of degree K-1
  • Partition of unity: $ \sum_{i=1}^{n} \phi_i(x) = 1 $ for all $ x $
  • Continuity: Global C⁰ continuity across element interfaces (H¹-conforming)

Convergence Rates

For smooth solutions, H1 elements of degree k provide k-th order convergence:

  • L² norm: $ \|u - u_h\|_{L^2} = O(h^{k+1}) $
  • H¹ norm (energy): $ \|u - u_h\|_{H^1} = O(h^k) $

Basis Function Construction

  • 1D (Segment): Classical Lagrange interpolation $ L_i^K(x) = \prod_{j \neq i} \frac{x - x_j}{x_i - x_j} $
  • 2D/3D Simplices: Barycentric Lagrange polynomials $ L_n^K(\lambda) = \prod_{m=0}^{n-1} \frac{K\lambda - m}{m+1} $
  • Tensor Products: For quadrilaterals and wedges, tensor product of lower-dimensional bases

Usage Example

// H1 element of degree 3 on triangle - 10 DOFs
RealH1Element<3> h1_tri(Polytope::Type::Triangle);
std::cout << h1_tri.getCount() << std::endl;  // Output: 10

// Evaluate basis function at a point
Math::SpatialVector<Real> pt{{0.25, 0.25}};
Real value = h1_tri.getBasis(0)(pt);

// Get gradient of basis function
auto grad = h1_tri.getBasis(0).getGradient()(pt);
Direct inheritance by class family
↓
H1Element

Inherits from

Base classResponsibility
LagrangeFiniteElementBase<…>public
Full type
LagrangeFiniteElementBase< H1Element< K, Scalar > >
Common reference-space properties of Lagrange element families.

Inherited interface

Declared inMembers
FiniteElementBase
4 members
LagrangeFiniteElementBase
1 members

Public types

class LinearForm
Evaluates linear form at a given function/vector field.
class BasisFunction
Represents a Lagrange basis function of degree K.
template<Geometry::Polytope::Type ReferenceGeometry>
class Evaluation
Owned modal derivatives for nodal gradient evaluation at one point.
using Tabulation = ReferenceTabulation<Scalar>
Basis values and derivatives tabulated on the reference element.
using Parent = LagrangeFiniteElementBase<H1Element<K, Scalar>>
Parent class.
using ScalarType = Scalar
Scalar value type.
using RangeType = ScalarType
Type of range.
using Values = typename Tabulation::Values
Caller-owned scalar reference values at one point.
using Gradients = typename Tabulation::Gradients
Caller-owned scalar reference gradients at one point.

Public static functions

static auto getNodes(Geometry::Polytope::Type g) -> const std::vector<Math::SpatialPoint>&
Builds the high-order stable nodes for the element geometry.

Constructors, destructors, conversion operators

H1Element()
Default constructor. Creates an H1 element on a Point geometry.
H1Element(Geometry::Polytope::Type geometry)
Constructs an H1 element for the specified geometry.
H1Element(const H1Element& other) constexpr
Copy constructor.
H1Element(H1Element&& other) constexpr
Move constructor.

Public functions

auto getTabulation(const QF::QuadratureFormula& qf) const -> const Tabulation&
Tabulates the basis on a quadrature formula.
evaluate
Contracts current coefficients with tabulated reference basis values.
See declaration
template<class Coefficient>
void evaluate(RangeType& out, Coefficient&& coefficient, const QF::QuadratureFormula& formula, size_t quadratureIndex) const
auto findTabulation(const QF::QuadratureFormula& formula) const -> Optional<std::reference_wrapper<const Tabulation>>
Borrows an existing reference table for a persistent formula.
auto operator=(const H1Element& other) -> H1Element& constexpr
Copy assignment operator.
auto operator=(H1Element&& other) -> H1Element& constexpr
Move assignment operator.
auto getCount() const -> size_t constexpr
Gets the number of degrees of freedom in the finite element.
auto getNode(size_t i) const -> const Math::SpatialPoint& constexpr
Gets the spatial coordinates of the i-th Lagrange node.
auto getNodeIndex(const Math::SpatialPoint& point) const -> Optional<size_t>
Finds a reference point among the interpolation nodes.
auto getLinearForm(size_t i) const -> const LinearForm&
Gets the linear form (evaluation functional) for the i-th DOF.
auto getBasis(size_t i) const -> const BasisFunction&
Gets the i-th basis function.
auto getDegree() const -> Optional<size_t> constexpr
Returns a total polynomial degree bound for the reference basis.
auto getDegree(std::initializer_list<size_t> directions) const -> Optional<size_t>
Returns a degree bound in selected reference coordinates.
auto getOrder() const -> size_t constexpr
Returns the finite-element family index.
template<class Archive>
void serialize(Archive& ar, const unsigned int version)
Serializes the element (for boost::serialization).
template<G ReferenceGeometry>
auto tabulate(const Math::SpatialPoint& point) const -> Evaluation<ReferenceGeometry>
Prepares shared modal work for immediate per-basis gradient consumption.
void tabulate(Values values, const Math::SpatialPoint& point) const
Tabulates nodal values at one reference point.
void tabulate(Gradients gradients, const Math::SpatialPoint& point) const
Tabulates nodal reference gradients at one point.
void tabulate(Values values, Gradients gradients, const Math::SpatialPoint& point) const
Tabulates values and gradients with shared point-local modal work.
void tabulate(Tabulation& table, const QF::QuadratureFormulaBase& formula) const
Sizes and fills caller-owned values and gradients at reference samples.
tabulate
Prepares shared modal derivatives for nodal gradient evaluation.
See declaration
template<Geometry::Polytope::Type ReferenceGeometry>
auto tabulate(const Math::SpatialPoint& point) const -> Evaluation<ReferenceGeometry>

Function documentation

static const std::vector<Math::SpatialPoint>& getNodes(Geometry::Polytope::Type g)

Builds the high-order stable nodes for the element geometry.

Parameters
g Mesh entity used by this operation.
Returns The nodes.

Constructs the positions of DOF nodes based on the geometry type and polynomial degree. Uses:

  • Segment: Gauss-Lobatto-Legendre (GLL) nodes on [0,1]
  • Quadrilateral: Tensor product of 1D GLL nodes
  • Triangle: Fekete nodes on reference triangle
  • Tetrahedron: Fekete nodes on reference tetrahedron
  • Wedge: Tensor product of triangle Fekete nodes with 1D GLL nodes

H1Element(Geometry::Polytope::Type geometry)

Constructs an H1 element for the specified geometry.

Parameters
geometry Type of element geometry (Segment, Triangle, Quadrilateral, etc.)

Initializes the element and builds the Lagrange nodes for the specified geometry. The number and positions of nodes depend on both the geometry and polynomial degree K.

H1Element(const H1Element& other) constexpr

Copy constructor.

Parameters
other Element to copy from

H1Element(H1Element&& other) constexpr

Move constructor.

Parameters
other Element to move from

const Tabulation& getTabulation(const QF::QuadratureFormula& qf) const

Tabulates the basis on a quadrature formula.

Parameters
qf Quadrature formula defining the evaluation points.
Returns The tabulation for the current formula contents.

Thread-local entries are identified by the reference geometry and the persistent quadrature formula's address. Its immutable samples remain valid until process termination.

template<size_t K, class Scalar> template<class Coefficient>
void evaluate(RangeType& out, Coefficient&& coefficient, const QF::QuadratureFormula& formula, size_t quadratureIndex) const

Contracts current coefficients with tabulated reference basis values.

Parameters
out Reference expansion value.
coefficient Local coefficient accessor in element basis order.
formula Immutable formula defining the reference samples.
quadratureIndex Index of the reference sample.

Optional<std::reference_wrapper<const Tabulation>> findTabulation(const QF::QuadratureFormula& formula) const

Borrows an existing reference table for a persistent formula.

Parameters
formula Persistent formula defining the samples.
Returns The matching table in this thread, or no value.

This lookup neither creates a table nor dereferences a formula. An absent or evicted table, including on another thread, returns no value. The borrowed result must not escape the immediate evaluation call.

H1Element& operator=(const H1Element& other) constexpr

Copy assignment operator.

Parameters
other Element to copy from
Returns Reference to this element

H1Element& operator=(H1Element&& other) constexpr

Move assignment operator.

Parameters
other Element to move from
Returns Reference to this element

size_t getCount() const constexpr

Gets the number of degrees of freedom in the finite element.

Returns Number of degrees of freedom

The DOF count depends on geometry and polynomial degree K:

  • Segment: K+1
  • Triangle: (K+1)(K+2)/2
  • Quadrilateral: (K+1)²
  • Tetrahedron: (K+1)(K+2)(K+3)/6
  • Wedge: (K+1)·(K+1)(K+2)/2

const Math::SpatialPoint& getNode(size_t i) const constexpr

Gets the spatial coordinates of the i-th Lagrange node.

Parameters
i Node index (0 to getCount()-1)
Returns Reference coordinates of the node (typically in [0,1]^d)

Lagrange nodes are the interpolation points where the basis functions satisfy φ_i(x_j) = δ_ij. Their positions are determined by the polynomial degree and geometry type.

Optional<size_t> getNodeIndex(const Math::SpatialPoint& point) const

Finds a reference point among the interpolation nodes.

Parameters
point Reference coordinates; trailing padding is ignored.
Returns Node index, or an empty optional for a nonnodal or undersized point.

Matching uses exact reference coordinates, without a distance tolerance. This permits pointwise nodal evaluation to retain the exact cardinal identity without discarding small values at nearby nonnodal points.

const LinearForm& getLinearForm(size_t i) const

Gets the linear form (evaluation functional) for the i-th DOF.

Parameters
i DOF index (0 to getCount()-1)
Returns Linear form object that evaluates functions at the i-th node

const BasisFunction& getBasis(size_t i) const

Gets the i-th basis function.

Parameters
i Local basis-function index.
Returns Basis function object

The basis functions satisfy the Lagrange property and form a partition of unity.

Optional<size_t> getDegree() const constexpr

Returns a total polynomial degree bound for the reference basis.

Returns A total polynomial degree bound, or no value for rational pyramid bases.

Optional<size_t> getDegree(std::initializer_list<size_t> directions) const

Returns a degree bound in selected reference coordinates.

Parameters
directions Reference-coordinate indices; duplicates are ignored.
Returns The bound, or no value for invalid or unsupported selections.

size_t getOrder() const constexpr

Returns the finite-element family index.

Returns The family index, independently of the reference geometry.

template<size_t K, class Scalar> template<class Archive>
void serialize(Archive& ar, const unsigned int version)

Serializes the element (for boost::serialization).

Parameters
ar Archive to serialize to/from
version Serialization version

template<size_t K, class Scalar> template<G ReferenceGeometry>
Evaluation<ReferenceGeometry> tabulate(const Math::SpatialPoint& point) const

Prepares shared modal work for immediate per-basis gradient consumption.

Template parameters
ReferenceGeometry Tetrahedron or pyramid reference geometry.
Parameters
point Reference coordinates; optional trailing padding is ignored.
Returns An owned evaluation with a lifetime independent of the input point.
Exceptions
Alert::Exception If the geometry or coordinates are incompatible.

void tabulate(Values values, const Math::SpatialPoint& point) const

Tabulates nodal values at one reference point.

Parameters
values Output with one entry per basis function.
point Reference coordinates; padding beyond the dimension is ignored.
Exceptions
Alert::Exception If coordinates or output dimensions are invalid.

void tabulate(Gradients gradients, const Math::SpatialPoint& point) const

Tabulates nodal reference gradients at one point.

Parameters
gradients Basis-major output with the reference dimension.
point Reference coordinates; padding beyond the dimension is ignored.
Exceptions
Alert::Exception If coordinates or output dimensions are invalid.

void tabulate(Values values, Gradients gradients, const Math::SpatialPoint& point) const

Tabulates values and gradients with shared point-local modal work.

Parameters
values Output with one entry per basis function.
gradients Basis-major reference gradients.
point Reference coordinates.
Exceptions
Alert::Exception If coordinates or output dimensions are invalid.

The modal basis owns differentiation; this element owns its inverse Vandermonde contraction. Scratch belongs to this invocation, with no retained borrow or cache state. For modal values $\psi_m$ ,

\[ \phi_a = \sum_m (V^{-1})_{ma} \psi_m, \qquad \partial_i\phi_a = \sum_m (V^{-1})_{ma} \partial_i\psi_m. \]

Mode order, real derivative accumulation, scalar promotion and historical singular-vertex conventions are retained.

void tabulate(Tabulation& table, const QF::QuadratureFormulaBase& formula) const

Sizes and fills caller-owned values and gradients at reference samples.

Parameters
table Numerical output in sample-major order.
formula Reference sample collection.

This operation does not inspect formula identity or access a cache. Existing output capacity is reused. Modal formulas obtain the inverse and prepare their shared workspace once, outside the sample loop. Empty formulas do not evaluate a basis or initialize an inverse.

template<size_t K, class Scalar> template<Geometry::Polytope::Type ReferenceGeometry>
Evaluation<ReferenceGeometry> tabulate(const Math::SpatialPoint& point) const

Defined in Rodin/Variational/H1/H1Element.hpp

Prepares shared modal derivatives for nodal gradient evaluation.

Template parameters
ReferenceGeometry Tetrahedron or pyramid reference geometry.
Parameters
point Reference coordinates; optional trailing padding is ignored.
Returns Owned modal derivatives with shared inverse Vandermonde access.
Exceptions
Alert::Exception If the geometry or coordinates are incompatible.