Abstract interface for finite-element basis-function families. More...

#include <BasisFunction.h>

Inheritance diagram for svmp::FE::basis::BasisFunction:

Public Member Functions
virtual	~BasisFunction ()=default
	Destroy a basis function through the abstract interface.

virtual BasisType	basis_type () const noexcept=0
	Return the concrete basis family.

virtual BasisTopology	topology () const noexcept=0
	Return the reference topology of this basis.

virtual int	dimension () const noexcept=0
	Return the reference-space dimension of the basis.

virtual int	order () const noexcept=0
	Return the polynomial order represented by this basis.

virtual std::size_t	size () const noexcept=0
	Return the number of basis functions and reference nodes.

virtual const std::vector< math::Vector< double, 3 > > &	nodes () const noexcept
	Return the reference interpolation nodes in basis ordering.

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.

virtual void	evaluate_values_to (const math::Vector< double, 3 > &xi, std::span< double > values_out) const =0
	Evaluate basis values into caller-provided storage.

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

virtual void	evaluate_hessians_to (const math::Vector< double, 3 > &xi, std::span< Hessian > hessians_out) const
	Evaluate basis Hessians into caller-provided storage.

Protected Member Functions
virtual void	evaluate_all_to (const math::Vector< double, 3 > &xi, std::span< double > values_out, std::span< Gradient > gradients_out, std::span< Hessian > hessians_out) const
	Evaluate any non-empty subset of values, gradients, and Hessians into caller-provided storage in a single pass.

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

Abstract interface for finite-element basis-function families.

BasisFunction defines the common query and evaluation API used by solver code that does not need to know the concrete basis implementation. Concrete families implement the span output primitives – shape function values at minimum, and optionally analytical gradients and Hessians; the vector overloads and the combined evaluator are provided once by the base class. The interface is deliberately limited to reference-space quantities; callers own node ordering translation, physical mapping, and any field-level discretization policy.

Constructor & Destructor Documentation

◆ ~BasisFunction()

virtual svmp::FE::basis::BasisFunction::~BasisFunction ( )

virtualdefault

Destroy a basis function through the abstract interface.

Member Function Documentation

◆ basis_type()

virtual BasisType svmp::FE::basis::BasisFunction::basis_type ( ) const

pure virtualnoexcept

Return the concrete basis family.

Returns: Basis family identifier.

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ dimension()

virtual int svmp::FE::basis::BasisFunction::dimension ( ) const

pure virtualnoexcept

Return the reference-space dimension of the basis.

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

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ evaluate_all()

void svmp::FE::basis::BasisFunction::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.

Convenience overload over evaluate_all_to(): it sizes all three containers to size() and forwards them in a single pass.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
values	Receives one value per basis function.
gradients	Receives one three-component gradient per basis function.
hessians	Receives one 3-by-3 Hessian per basis function.

◆ evaluate_all_to()

void svmp::FE::basis::BasisFunction::evaluate_all_to	(	const math::Vector< double, 3 > &	xi,
		std::span< double >	values_out,
		std::span< Gradient >	gradients_out,
		std::span< Hessian >	hessians_out
	)		const

protectedvirtual

Evaluate any non-empty subset of values, gradients, and Hessians into caller-provided storage in a single pass.

An empty span selects "skip that quantity". The base implementation forwards each requested quantity to its single-quantity span primitive; families that can share per-point setup override this to compute the requested quantities together. It backs the public evaluate_all() overload.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
values_out	Values output span, or empty to skip.
gradients_out	Gradients output span, or empty to skip.
hessians_out	Hessians output span, or empty to skip.

◆ evaluate_gradients()

void svmp::FE::basis::BasisFunction::evaluate_gradients	(	const math::Vector< double, 3 > &	xi,
		std::vector< Gradient > &	gradients
	)		const

Evaluate basis gradients at a reference coordinate.

Convenience overload over evaluate_gradients_to(); see evaluate_values() for the sizing and forwarding contract.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
gradients	Receives one three-component gradient per basis function.

Exceptions

BasisEvaluationException If gradients are not available for the basis.

◆ evaluate_gradients_to()

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

virtual

Evaluate basis gradients into caller-provided storage.

Override to supply analytical gradients. The base implementation throws, so a family that provides no gradients reports it uniformly through every gradient entry point.

Parameters

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

Exceptions

BasisEvaluationException If gradients are not available for the basis.

Reimplemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ evaluate_hessians()

void svmp::FE::basis::BasisFunction::evaluate_hessians	(	const math::Vector< double, 3 > &	xi,
		std::vector< Hessian > &	hessians
	)		const

Evaluate basis Hessians at a reference coordinate.

Convenience overload over evaluate_hessians_to(); see evaluate_values() for the sizing and forwarding contract.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
hessians	Receives one 3-by-3 Hessian per basis function.

Exceptions

BasisEvaluationException If Hessians are not available for the basis.

◆ evaluate_hessians_to()

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

virtual

Evaluate basis Hessians into caller-provided storage.

Override to supply analytical Hessians. The base implementation throws, so a family that provides no Hessians reports it uniformly through every Hessian entry point.

Parameters

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

Exceptions

BasisEvaluationException If Hessians are not available for the basis.

Reimplemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ evaluate_values()

void svmp::FE::basis::BasisFunction::evaluate_values	(	const math::Vector< double, 3 > &	xi,
		std::vector< double > &	values
	)		const

Evaluate basis function values at a reference coordinate.

Convenience overload: it sizes values to size() and forwards to evaluate_values_to(). It is implemented once on the base class, so concrete families override the span primitive rather than this overload. The result is delivered through the output argument rather than by return value so a caller can reuse one container across repeated evaluations (for example, across quadrature points) instead of allocating on every call.

Parameters

xi	Reference coordinate. Lower-dimensional elements use the active prefix components.
values	Receives one value per basis function.

◆ evaluate_values_to()

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

pure virtual

Evaluate basis values into caller-provided storage.

This span primitive is the single required override for a concrete basis: the vector overloads above and the combined evaluate_all_to() are all defined in terms of it, so a minimal basis implements only this method.

Parameters

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

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ nodes()

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

virtualnoexcept

Return the reference interpolation nodes in basis ordering.

Nodal families return one reference-element coordinate per basis function, in the same order as the evaluator outputs. Bases that do not define interpolation nodes (non-nodal families, or abstract base usage) return an empty vector. The returned reference is valid for the lifetime of the basis object.

Returns: Reference node coordinates: size() entries for nodal families, empty otherwise.

Reimplemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ numerical_gradient()

void svmp::FE::basis::BasisFunction::numerical_gradient	(	const math::Vector< double, 3 > &	xi,
		std::vector< Gradient > &	gradients,
		double	eps = `double(1e-6)`
	)		const

protected

Approximate gradients by centered finite differences of values.

This helper is primarily a verification utility for tests: it provides a basis-independent reference that checks a concrete basis's analytical evaluate_gradients() against centered finite differences of evaluate_values(). It lives on the base class so any BasisFunction can be checked uniformly, and having no production caller is by design — every shipped basis supplies analytical gradients. Centered differences add truncation/roundoff sensitivity and require multiple value evaluations per reference coordinate, so analytical gradients are always preferred outside this testing context.

◆ numerical_hessian()

void svmp::FE::basis::BasisFunction::numerical_hessian	(	const math::Vector< double, 3 > &	xi,
		std::vector< Hessian > &	hessians,
		double	eps = `double(1e-5)`
	)		const

protected

Approximate Hessians by centered finite differences of gradients.

Companion verification utility to numerical_gradient: it checks a basis's analytical evaluate_hessians() against centered finite differences of evaluate_gradients(). Because it differentiates gradients, it is only meaningful for bases that already provide them. Like numerical_gradient it is test-support rather than a production fallback — finite-difference Hessians amplify numerical error and require repeated gradient evaluations, so analytical Hessians are used everywhere outside tests.

◆ order()

virtual int svmp::FE::basis::BasisFunction::order ( ) const

pure virtualnoexcept

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.

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ size()

virtual std::size_t svmp::FE::basis::BasisFunction::size ( ) const

pure virtualnoexcept

Return the number of basis functions and reference nodes.

Returns: Basis function count.

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

◆ topology()

virtual BasisTopology svmp::FE::basis::BasisFunction::topology ( ) const

pure virtualnoexcept

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.

Implemented in svmp::FE::basis::LagrangeBasis, and svmp::FE::basis::SerendipityBasis.

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

solver/FE/Basis/BasisFunction.h
solver/FE/Basis/BasisFunction.cpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~BasisFunction()

Member Function Documentation

◆ basis_type()

◆ dimension()

◆ evaluate_all()

◆ evaluate_all_to()

◆ evaluate_gradients()

◆ evaluate_gradients_to()

◆ evaluate_hessians()

◆ evaluate_hessians_to()

◆ evaluate_values()

◆ evaluate_values_to()

◆ nodes()

◆ numerical_gradient()

◆ numerical_hessian()

◆ order()

◆ size()

◆ topology()