Model of a finite element. More...

#include <FiniteElement.h>

Public Types
using	geometry_type = T
	Geometry type of the Mesh that the FunctionSpace is defined on.

Public Member Functions
	FiniteElement (const basix::FiniteElement< geometry_type > &element, std::size_t gdim, const std::optional< std::vector< std::size_t > > &value_shape=std::nullopt, bool symmetric=false)
	Create a finite element from a Basix finite element.
	FiniteElement (std::vector< BasixElementData< geometry_type > > elements, std::size_t gdim)
	Create a mixed finite element from Basix finite elements.
	FiniteElement (const std::vector< std::shared_ptr< const FiniteElement< geometry_type > > > &elements)
	Create a mixed finite element from a list of finite elements.
	FiniteElement (mesh::CellType cell_type, std::span< const geometry_type > points, std::array< std::size_t, 2 > pshape, std::vector< std::size_t > value_shape={}, bool symmetric=false)
	Create a quadrature element.
	FiniteElement (const FiniteElement &element)=delete
	Copy constructor.
	FiniteElement (FiniteElement &&element)=default
	Move constructor.
	~FiniteElement ()=default
	Destructor.
FiniteElement &	operator= (const FiniteElement &element)=delete
	Copy assignment.
FiniteElement &	operator= (FiniteElement &&element)=default
	Move assignment.
bool	operator== (const FiniteElement &e) const
	Check if two elements are equivalent.
bool	operator!= (const FiniteElement &e) const
	Check if two elements are not equivalent.
mesh::CellType	cell_type () const noexcept
	Cell shape that the element is defined on.
const std::string &	signature () const noexcept
	String identifying the finite element.
int	space_dimension () const noexcept
	Dimension of the finite element function space (the number of degrees-of-freedom for the element).
int	block_size () const noexcept
	Block size of the finite element function space.
int	value_size () const
	Value size of the finite element field in physical space.
std::span< const std::size_t >	value_shape () const
	Value shape of the finite element field in physical space.
int	physical_base_value_size () const
	Number of physical components in one block of the finite element field.
int	reference_value_size () const
	Value size of the base (non-blocked) finite element field on the reference cell.
std::span< const std::size_t >	reference_value_shape () const
	Value shape of the base (non-blocked) finite element field on the reference cell.
const std::vector< std::vector< std::vector< int > > > &	entity_dofs () const noexcept
	Local DOFs associated with each sub-entity of the cell.
const std::vector< std::vector< std::vector< int > > > &	entity_closure_dofs () const noexcept
	Local DOFs associated with the closure of each sub-entity of the cell.
bool	symmetric () const
	Does the element represent a symmetric 2-tensor?
void	tabulate (std::span< geometry_type > values, std::span< const geometry_type > X, std::array< std::size_t, 2 > shape, int order) const
	Evaluate derivatives of the basis functions up to given order at points in the reference cell.
std::pair< std::vector< geometry_type >, std::array< std::size_t, 4 > >	tabulate (std::span< const geometry_type > X, std::array< std::size_t, 2 > shape, int order) const
	Evaluate all derivatives of the basis functions up to given order at given points in reference cell.
int	num_sub_elements () const noexcept
	Number of sub elements (for a mixed or blocked element).
bool	is_mixed () const noexcept
	Check if element is a mixed element.
const std::vector< std::shared_ptr< const FiniteElement< geometry_type > > > &	sub_elements () const noexcept
	Get subelements (if any).
std::shared_ptr< const FiniteElement< geometry_type > >	extract_sub_element (const std::vector< int > &component) const
	Extract sub finite element for component.
const basix::FiniteElement< geometry_type > &	basix_element () const
	Return underlying Basix element (if it exists).
basix::maps::type	map_type () const
	Get the map type used by the element.
bool	interpolation_ident () const noexcept
bool	map_ident () const noexcept
std::pair< std::vector< geometry_type >, std::array< std::size_t, 2 > >	interpolation_points () const
	Points on the reference cell at which an expression needs to be evaluated in order to interpolate the expression in the finite element space.
std::pair< std::vector< geometry_type >, std::array< std::size_t, 2 > >	interpolation_operator () const
std::pair< std::vector< geometry_type >, std::array< std::size_t, 2 > >	create_interpolation_operator (const FiniteElement &from) const
	Create a matrix that maps degrees of freedom from one element to this element (interpolation).
bool	needs_dof_transformations () const noexcept
	Check if DOF transformations are needed for this element.
bool	needs_dof_permutations () const noexcept
	Check if DOF permutations are needed for this element.
template<typename U>
std::function< void(std::span< U >, std::span< const std::uint32_t >, std::int32_t, int)>	dof_transformation_fn (doftransform ttype, bool scalar_element=false) const
	Return a function that applies a DOF transformation operator to some data (see T_apply()).
template<typename U>
std::function< void(std::span< U >, std::span< const std::uint32_t >, std::int32_t, int)>	dof_transformation_right_fn (doftransform ttype, bool scalar_element=false) const
	Return a function that applies DOF transformation to some transposed data (see T_apply_right()).
template<typename U>
void	T_apply (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Transform basis functions from the reference element ordering and orientation to the globally consistent physical element ordering and orientation.
template<typename U>
void	Tt_inv_apply (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Apply the inverse transpose of the operator applied by T_apply().
template<typename U>
void	Tt_apply (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Apply the transpose of the operator applied by T_apply().
template<typename U>
void	Tinv_apply (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Apply the inverse of the operator applied by T_apply().
template<typename U>
void	T_apply_right (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Right(post)-apply the operator applied by T_apply().
template<typename U>
void	Tinv_apply_right (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Right(post)-apply the inverse of the operator applied by T_apply().
template<typename U>
void	Tt_apply_right (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Right(post)-apply the transpose of the operator applied by T_apply().
template<typename U>
void	Tt_inv_apply_right (std::span< U > data, std::uint32_t cell_permutation, int n) const
	Right(post)-apply the transpose inverse of the operator applied by T_apply().
void	permute (std::span< std::int32_t > doflist, std::uint32_t cell_permutation) const
	Permute indices associated with degree-of-freedoms on the reference element ordering to the globally consistent physical element degree-of-freedom ordering.
void	permute_inv (std::span< std::int32_t > doflist, std::uint32_t cell_permutation) const
	Perform the inverse of the operation applied by permute.
std::function< void(std::span< std::int32_t >, std::uint32_t)>	dof_permutation_fn (bool inverse=false, bool scalar_element=false) const
	Return a function that applies a degree-of-freedom permutation to some data.

Detailed Description

template<std::floating_point T>
class dolfinx::fem::FiniteElement< T >

Model of a finite element.

Provides the dof layout on a reference element, and various methods for evaluating and transforming the basis.

Value shapes

An element has two value shapes, and they are not interchangeable.

A basis is tabulated on the reference cell and pushed forward to a physical cell. FiniteElement::reference_value_shape is the shape Basix tabulates in, and is the shape of the data returned by FiniteElement::tabulate. FiniteElement::value_shape is the shape of the field after the push-forward. It is the shape a user of the space sees, and the one UFL reports for a Coefficient or Argument on the space, so it is the one to use for anything user-facing, for checking that two spaces are compatible, and for sizing buffers that hold physical values.

The two differ for three independent reasons:

Blocking. A blocked element repeats a scalar base element at each dof point, e.g. a vector Lagrange space. Its value shape is whatever the caller asked for, while its reference value shape is that of the scalar base element, {}.
Quadrature elements, whose reference value shape is {}.
The map. A Piola-mapped basis is pushed forward with the Jacobian J, which has shape (gdim, tdim). The value axes that J contracts therefore have extent gdim in physical space and tdim on the reference cell. These are equal unless gdim != tdim, i.e. on a manifold. See ::compute_value_shape.

Blocking

FiniteElement::block_size is the number of dofs collocated at a dof point. For a blocked element it equals FiniteElement::value_size, except for a symmetric rank-2 tensor, which stores only its independent components: a {3, 3} symmetric element has value size 9 but block size 6.

Code that needs the number of physical components in one block must therefore call FiniteElement::physical_base_value_size rather than compute value_size() / block_size(), which is wrong for symmetric elements.

Examples

All on a mesh of triangles, so tdim == 2. RT is Raviart-Thomas and sym marks a symmetric element. The columns are FiniteElement::value_shape, FiniteElement::block_size, FiniteElement::reference_value_shape and FiniteElement::physical_base_value_size. FiniteElement::value_size and FiniteElement::reference_value_size are the products of the respective shapes and are not tabulated.

element	gdim	vshape	bs	rvshape	bvsize
P1	2	{}	1	{}	1
P1	3	{}	1	{}	1
P1, shape {2}	2	{2}	2	{}	1
P1, shape {2}	3	{2}	2	{}	1
P1, shape {5}	2	{5}	5	{}	1
P1, sym {3, 3}	2	{3, 3}	6	{}	1
RT 1	2	{2}	1	{2}	2
RT 1	3	{3}	1	{2}	3
Regge 0	2	{2, 2}	1	{2, 2}	4
Regge 0	3	{3, 3}	1	{2, 2}	9
mixed	any	throws	1	throws	throws

Note first that gdim changes nothing for P1 or P1, shape {2}: both are identity mapped, so their physical and reference value shapes agree on a manifold exactly as they do on a 2D mesh, and the blocked shape {2} stays {2} on a gdim == 3 mesh. Contrast the RT 1 and Regge 0 pairs, where the Piola push-forward does introduce gdim.

Some rows deserve further comment:

P1, shape {5}. A blocked element's value shape is chosen by the caller and has nothing to do with gdim. A 5-vector, or a {3, 3} tensor field, on a mesh of any geometric dimension is legal, and gdim must never be substituted into such a shape.
P1, sym {3, 3}. The only case in which the block size is not the value size: the value size is 9, but only the six independent components are stored, one dof each, and the other three are recovered by symmetry.
RT 1 with gdim == 3, i.e. a triangle embedded in 3D. The contravariant Piola push-forward multiplies by a (3, 2) Jacobian, so the field has three components in physical space while Basix still tabulates two. This is the case that separates the two value shapes for a non-blocked element.
mixed. A mixed element has no value shape of its own, so every shape and size accessor throws; only FiniteElement::block_size is defined, and is 1. Extract a sub-element with ::extract_sub_element to get at its shapes. FiniteElement::is_mixed reports this case, and is implemented as "has no reference value shape".

Constructor & Destructor Documentation

◆ FiniteElement() [1/4]

template<std::floating_point T>

FiniteElement	(	const basix::FiniteElement< geometry_type > &	element,
		std::size_t	gdim,
		const std::optional< std::vector< std::size_t > > &	value_shape = std::nullopt,
		bool	symmetric = false )

Create a finite element from a Basix finite element.

Parameters

[in]	element	Basix finite element.
[in]	gdim	Geometric dimension of the mesh the element will be used on.
[in]	value_shape	Value shape for blocked element, e.g. {3} for a vector in 3D or {2, 2} for a rank-2 tensor in 2D. Can only be set for blocked scalar element. For other elements and scalar elements it should be std::nullopt.
[in]	symmetric	Is the element a symmetric tensor? Should only set for 2nd-order tensor blocked elements.

◆ FiniteElement() [2/4]

template<std::floating_point T>

FiniteElement	(	std::vector< BasixElementData< geometry_type > >	elements,
		std::size_t	gdim )

Create a mixed finite element from Basix finite elements.

See FiniteElement(const std::vector<std::shared_ptr<const FiniteElement<geometry_type>>>&) for a discussion of mixed elements.

Parameters

[in]	elements	List of (Basix finite element, block size, symmetric) tuples, one for each element in the mixed element.
[in]	gdim	Geometric dimension of the mesh the element will be used on, applied to every sub-element.

◆ FiniteElement() [3/4]

template<std::floating_point T>

FiniteElement ( const std::vector< std::shared_ptr< const FiniteElement< geometry_type > > > & elements )

Create a mixed finite element from a list of finite elements.

This constructs a mixed element \(E_0 \times E_1 \times \ldots \times E_{n-1}\). The *i*th sub-element \(E_i\) can be accessed by ::extract_sub_element. Functions defined on mixed element spaces cannot be interpolated into directly. It is necessary to first extract a sub-Function (view), which can then be interpolated into.

A mixed element can be constructed from one element. In this case the FiniteElement behaves like a mixed element and cannot be interpolated into. The underlying element can be accessed using ::extract_sub_element.

Parameters

[in] elements Finite elements to compose the mixed element from.

◆ FiniteElement() [4/4]

template<std::floating_point T>

FiniteElement	(	mesh::CellType	cell_type,
		std::span< const geometry_type >	points,
		std::array< std::size_t, 2 >	pshape,
		std::vector< std::size_t >	value_shape = {},
		bool	symmetric = false )

Create a quadrature element.

Note: A quadrature element is identity mapped, so value_shape is both its reference and its physical value shape and no geometric dimension is required.

Parameters

[in]	cell_type	Cell type.
[in]	points	Quadrature points.
[in]	pshape	Shape of points array.
[in]	value_shape	Value shape for the element.
[in]	symmetric	Is the element a symmetric tensor?

Member Function Documentation

◆ basix_element()

template<std::floating_point T>

const basix::FiniteElement< T > & basix_element ( ) const

Return underlying Basix element (if it exists).

Exceptions

Throws a std::runtime_error is there no Basix element.

◆ block_size()

template<std::floating_point T>

int block_size ( ) const

noexcept

Block size of the finite element function space.

For non-blocked elements, this is always 1. For blocked elements, this is the number of DOFs collocated at each DOF point, which equals FiniteElement::value_size except for a symmetric rank-2 tensor. A symmetric rank-2 tensor stores only its independent components, so a {2, 2} symmetric element has value size 4 and block size 3, and a {3, 3} one has value size 9 and block size 6.

Returns: Block size of the finite element space.

◆ create_interpolation_operator()

template<std::floating_point T>

std::pair< std::vector< T >, std::array< std::size_t, 2 > > create_interpolation_operator ( const FiniteElement< T > & from ) const

Create a matrix that maps degrees of freedom from one element to this element (interpolation).

Parameters

[in] from The element to interpolate from.

Returns: Matrix operator that maps the from degrees-of-freedom to the degrees-of-freedom of this element. The (0) matrix data (row-major storage) and (1) the shape (num_dofs of this element, num_dofs of from) are returned.

Precondition: The two elements must use the same mapping between the reference and physical cells.

Note: Does not support mixed elements.

◆ dof_permutation_fn()

template<std::floating_point T>

std::function< void(std::span< std::int32_t >, std::uint32_t)> dof_permutation_fn	(	bool	inverse = false,
		bool	scalar_element = false ) const

Return a function that applies a degree-of-freedom permutation to some data.

The returned function can apply permute to mixed-elements.

The signature of the returned function has three arguments:

[in,out] doflist The numbers of the DOFs, a span of length num_dofs
[in] cell_permutation Permutation data for the cell
[in] block_size The block_size of the input data

Parameters

[in]	inverse	Indicates if the inverse transformation should be returned.
[in]	scalar_element	Indicates is the scalar transformations should be returned for a vector element.

◆ dof_transformation_fn()

template<std::floating_point T>

template<typename U>

std::function< void(std::span< U >, std::span< const std::uint32_t >, std::int32_t, int)> dof_transformation_fn	(	doftransform	ttype,
		bool	scalar_element = false ) const

inline

Return a function that applies a DOF transformation operator to some data (see T_apply()).

The transformation is applied from the left-hand side, i.e.

\[ u \leftarrow T u. \]

If the transformation for the (sub)element is a permutation only, the returned function will do change the ordering for the (sub)element as it is assumed that permutations are incorporated into the degree-of-freedom map.

See the documentation for T_apply() for a description of the transformation for a single element type. This function generates a function that can apply the transformation to a mixed element.

The signature of the returned function has four arguments:

[in,out] data The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size)
[in] cell_info Permutation data for the cell. The size of this is num_cells. For elements where no transformations are required, an empty span can be passed in.
[in] cell The cell number.
[in] n The block_size of the input data.

Parameters

[in]	ttype	The transformation type. Typical usage is: doftransform::standard Transforms basis function data from the reference element to the conforming 'physical' element, e.g. \(\phi = T \tilde{\phi}\). doftransform::transpose Transforms degree-of-freedom data from the conforming (physical) ordering to the reference ordering, e.g. \(\tilde{u} = T^{T} u\). doftransform::inverse: Transforms basis function data from the the conforming (physical) ordering to the reference ordering, e.g. \(\tilde{\phi} = T^{-1} \phi\). doftransform::inverse_transpose: Transforms degree-of-freedom data from the reference element to the conforming (physical) ordering, e.g. \(u = T^{-t} \tilde{u}\).
[in]	scalar_element	Indicates whether the scalar transformations should be returned for a vector element.

◆ dof_transformation_right_fn()

template<std::floating_point T>

template<typename U>

std::function< void(std::span< U >, std::span< const std::uint32_t >, std::int32_t, int)> dof_transformation_right_fn	(	doftransform	ttype,
		bool	scalar_element = false ) const

inline

Return a function that applies DOF transformation to some transposed data (see T_apply_right()).

The transformation is applied from the right-hand side, i.e.

\[ u^{t} \leftarrow u^{t} T. \]

If the transformation for the (sub)element is a permutation only, the returned function will do change the ordering for the (sub)element as it is assumed that permutations are incorporated into the degree-of-freedom map.

The signature of the returned function has four arguments:

[in,out] data The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size)
[in] cell_info Permutation data for the cell. The size of this is num_cells. For elements where no transformations are required, an empty span can be passed in.
[in] cell The cell number
[in] block_size The block_size of the input data

Parameters

[in]	ttype	Transformation type. See dof_transformation_fn().
[in]	scalar_element	Indicate if the scalar transformations should be returned for a vector element.

◆ interpolation_ident()

template<std::floating_point T>

bool interpolation_ident ( ) const

noexcept

Check if interpolation into the finite element space is an identity operation given the evaluation on an expression at specific points, i.e. the degree-of-freedom are equal to point evaluations. The function will return true for Lagrange elements.

Returns: True if interpolation is an identity operation

◆ interpolation_operator()

template<std::floating_point T>

std::pair< std::vector< T >, std::array< std::size_t, 2 > > interpolation_operator ( ) const

Interpolation operator (matrix) Pi that maps a function evaluated at the points provided by FiniteElement::interpolation_points to the element degrees of freedom, i.e. dofs = Pi f_x. See the Basix documentation for basix::FiniteElement::interpolation_matrix for how the data in f_x should be ordered.

Returns: The interpolation operator Pi, returning the data for Pi (row-major storage) and the shape (num_dofs, num_points * value_size)

◆ interpolation_points()

template<std::floating_point T>

std::pair< std::vector< T >, std::array< std::size_t, 2 > > interpolation_points ( ) const

Points on the reference cell at which an expression needs to be evaluated in order to interpolate the expression in the finite element space.

For Lagrange elements the points will just be the nodal positions. For other elements the points will typically be the quadrature points used to evaluate moment degrees of freedom.

Returns: Interpolation point coordinates on the reference cell, returning the (0) coordinates data (row-major) storage and (1) the shape (num_points, tdim).

◆ is_mixed()

template<std::floating_point T>

bool is_mixed ( ) const

noexcept

Check if element is a mixed element.

A mixed element is composed of two or more elements of different types. A blocked element, e.g. a Lagrange element with block size >= 1 is not considered mixed.

Returns: True if element is mixed.

◆ map_ident()

template<std::floating_point T>

bool map_ident ( ) const

noexcept

Check if the push forward/pull back map from the values on reference to the values on a physical cell for this element is the identity map.

Returns: True if the map is the identity

◆ needs_dof_permutations()

template<std::floating_point T>

bool needs_dof_permutations ( ) const

noexcept

Check if DOF permutations are needed for this element.

DOF permutations will be needed for elements which might not be continuous when two neighbouring cells disagree on the orientation of a shared subentity, and when this can be corrected for by permuting the DOF numbering in the dofmap.

For example, higher order Lagrange elements will need DOF permutations, as the arrangement of DOFs on a shared sub-entity may be different from the point of view of neighbouring cells, and this can be corrected for by permuting the DOF numbers on each cell.

Returns: True if DOF transformations are required.

◆ needs_dof_transformations()

template<std::floating_point T>

bool needs_dof_transformations ( ) const

noexcept

Check if DOF transformations are needed for this element.

DOF transformations will be needed for elements which might not be continuous when two neighbouring cells disagree on the orientation of a shared sub-entity, and when this cannot be corrected for by permuting the DOF numbering in the dofmap.

For example, Raviart-Thomas elements will need DOF transformations, as the neighbouring cells may disagree on the orientation of a basis function, and this orientation cannot be corrected for by permuting the DOF numbers on each cell.

Returns: True if DOF transformations are required.

◆ num_sub_elements()

template<std::floating_point T>

int num_sub_elements ( ) const

noexcept

Number of sub elements (for a mixed or blocked element).

Returns: Number of sub elements.

◆ operator!=()

template<std::floating_point T>

bool operator!= ( const FiniteElement< T > & e ) const

Check if two elements are not equivalent.

Returns: True is the two elements are not the same.

Note: Equality can be checked only for non-mixed elements. For a mixed element, this function will raise an exception.

◆ operator==()

template<std::floating_point T>

bool operator== ( const FiniteElement< T > & e ) const

Check if two elements are equivalent.

Returns: True is the two elements are the same.

Note: Equality can be checked only for non-mixed elements. For a mixed element, this function will throw an exception.

◆ permute()

template<std::floating_point T>

void permute	(	std::span< std::int32_t >	doflist,
		std::uint32_t	cell_permutation ) const

Permute indices associated with degree-of-freedoms on the reference element ordering to the globally consistent physical element degree-of-freedom ordering.

Given an array \(\tilde{d}\) that holds an integer associated with each degree-of-freedom and following the reference element degree-of-freedom ordering, this function computes

\[ d = P \tilde{d},\]

where \(P\) is a permutation matrix and \(d\) holds the integers in \(\tilde{d}\) but permuted to follow the globally consistent physical element degree-of-freedom ordering. The permutation is computed in-place.

Parameters

[in,out]	doflist	Indices associated with the degrees-of-freedom. Size=num_dofs.
[in]	cell_permutation	Permutation data for the cell.

◆ permute_inv()

template<std::floating_point T>

void permute_inv	(	std::span< std::int32_t >	doflist,
		std::uint32_t	cell_permutation ) const

Perform the inverse of the operation applied by permute.

Given an array \(d\) that holds an integer associated with each degree-of-freedom and following the globally consistent physical element degree-of-freedom ordering, this function computes

\[ \tilde{d} = P^{T} d, \]

where \(P^{T}\) is a permutation matrix and \(\tilde{d}\) holds the integers in \(d\) but permuted to follow the reference element degree-of-freedom ordering. The permutation is computed in-place.

Parameters

[in,out]	doflist	Indices associated with the degrees-of-freedom. Size=num_dofs.
[in]	cell_permutation	Permutation data for the cell.

◆ physical_base_value_size()

template<std::floating_point T>

int physical_base_value_size ( ) const

Number of physical components in one block of the finite element field.

A blocked element repeats a scalar base element FiniteElement::block_size times, so one block of its field is a single scalar and this is 1. A non-blocked element has a single block, so this is FiniteElement::value_size.

This is the size of the push-forward of one (non-blocked) basis function, and hence the extent a buffer needs when it holds physical values one block at a time. It is the physical counterpart of FiniteElement::reference_value_size, and equals it unless the element is Piola mapped on a manifold, where it is gdim rather than tdim.

Note: This is not value_size() / block_size(): for a symmetric rank-2 tensor element that expression gives 4/3 or 9/6 rather than the correct value of 1.

Exceptions

Exception is thrown for a mixed element as mixed elements do not have a value shape.

Returns: Number of physical components per block.

◆ reference_value_shape()

template<std::floating_point T>

std::span< const std::size_t > reference_value_shape ( ) const

Value shape of the base (non-blocked) finite element field on the reference cell.

This is the shape Basix tabulates in. For blocked and quadrature elements the returned shape will be {}. For other elements it is the same as FiniteElement::value_shape except on a manifold, where a Piola-mapped element has tdim reference components and gdim physical ones.

Mixed elements do not have a reference value shape.

Exceptions

Exception is thrown for a mixed element as mixed elements do not have a value shape.

Returns: The value shape.

◆ reference_value_size()

template<std::floating_point T>

int reference_value_size ( ) const

Value size of the base (non-blocked) finite element field on the reference cell.

The reference value size is the product of the reference value shape, e.g. it is 1 for a scalar element, 2 for a 2D (non-blocked) vector, 9 for a (non-blocked) second-order tensor in 3D, etc. It is the number of components produced by FiniteElement::tabulate.

For blocked elements, this function returns the value size for the 'base' element from which the blocked element is composed.

Exceptions

Exception is thrown for a mixed element as mixed elements do not have a value shape.

Returns: The value size.

◆ signature()

template<std::floating_point T>

const std::string & signature ( ) const

noexcept

String identifying the finite element.

Returns: Element signature

Warning: The function is provided for convenience, but it should not be relied upon for determining the element type. Use other functions, commonly returning enums, to determine element properties.

◆ space_dimension()

template<std::floating_point T>

int space_dimension ( ) const

noexcept

Dimension of the finite element function space (the number of degrees-of-freedom for the element).

For 'blocked' elements, this function returns the dimension of the full element rather than the dimension of the base element.

Returns: Dimension of the finite element space.

◆ symmetric()

template<std::floating_point T>

bool symmetric ( ) const

Does the element represent a symmetric 2-tensor?

A symmetric element has a square rank-2 FiniteElement::value_shape, but stores only the independent components, so its FiniteElement::block_size is d * (d + 1) / 2 rather than d * d. See the examples in the class documentation.

◆ T_apply()

template<std::floating_point T>

template<typename U>

void T_apply	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Transform basis functions from the reference element ordering and orientation to the globally consistent physical element ordering and orientation.

Consider that the value of a finite element function \(f_{h}\) at a point is given by

\[ f_{h} = \phi^{T} c, \]

where \(f_{h}\) has shape \(r \times 1\), \(\phi\) has shape \(d \times r\) and holds the finite element basis functions, and \(c\) has shape \(d \times 1\) and holds the degrees-of-freedom. The basis functions and degree-of-freedom are with respect to the physical element orientation. If the degrees-of-freedom on the physical element orientation are given by

\[\phi = T \tilde{\phi}, \]

where \(T\) is a \(d \times d\) matrix, it follows from \(f_{h} = \phi^{T} c = \tilde{\phi}^{T} T^{T} c\) that

\[ \tilde{c} = T^{T} c. \]

This function applies \(T\) to data. The transformation is performed in-place. The operator \(T\) is orthogonal for many elements, but not all.

This function calls the corresponding Basix function.

Parameters

[in,out]	data	Data to transform. The shape is (m, n), where m is the number of dgerees-of-freedom and the storage is row-major.
[in]	cell_permutation	Permutation data for the cell
[in]	n	Number of columns in data.

◆ T_apply_right()

template<std::floating_point T>

template<typename U>

void T_apply_right	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Right(post)-apply the operator applied by T_apply().

Computes

\[ v^{T} = u^{T} T \]

in-place.

Parameters

[in,out]	data	The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell
[in]	n	Block size of the input data

◆ tabulate() [1/2]

template<std::floating_point T>

std::pair< std::vector< T >, std::array< std::size_t, 4 > > tabulate	(	std::span< const geometry_type >	X,
		std::array< std::size_t, 2 >	shape,
		int	order ) const

Evaluate all derivatives of the basis functions up to given order at given points in reference cell.

Parameters

[in]	X	The reference coordinates at which to evaluate the basis functions. Shape is (num_points, topological dimension) (row-major storage).
[in]	shape	Shape of X.
[in]	order	Number of derivatives (up to and including this order) to tabulate for.

Returns: Basis function values and array shape (row-major storage).

◆ tabulate() [2/2]

template<std::floating_point T>

void tabulate	(	std::span< geometry_type >	values,
		std::span< const geometry_type >	X,
		std::array< std::size_t, 2 >	shape,
		int	order ) const

Evaluate derivatives of the basis functions up to given order at points in the reference cell.

Parameters

[in,out]	values	Array that will be filled with the tabulated basis values. Must have shape (num_derivatives, num_points, num_dofs, reference_value_size) (row-major storage)
[in]	X	The reference coordinates at which to evaluate the basis functions. Shape is (num_points, topological dimension) (row-major storage).
[in]	shape	Shape of X.
[in]	order	Number of derivatives (up to and including this order) to tabulate for.

◆ Tinv_apply()

template<std::floating_point T>

template<typename U>

void Tinv_apply	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Apply the inverse of the operator applied by T_apply().

The transformation

\[ v = T^{-1} u \]

is performed in-place.

Parameters

[in,out]	data	The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell.
[in]	n	Block size of the input data.

◆ Tinv_apply_right()

template<std::floating_point T>

template<typename U>

void Tinv_apply_right	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Right(post)-apply the inverse of the operator applied by T_apply().

Computes

\[ v^{T} = u^{T} T^{-1} \]

in-place.

Parameters

[in,out]	data	Data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell
[in]	n	Block size of the input data

◆ Tt_apply()

template<std::floating_point T>

template<typename U>

void Tt_apply	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Apply the transpose of the operator applied by T_apply().

The transformation

\[ u \leftarrow T^{T} u \]

is performed in-place.

Parameters

[in,out]	data	The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell.
[in]	n	The block size of the input data.

◆ Tt_apply_right()

template<std::floating_point T>

template<typename U>

void Tt_apply_right	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Right(post)-apply the transpose of the operator applied by T_apply().

Computes

\[ v^{T} = u^{T} T^{T} \]

in-place.

Parameters

[in,out]	data	Data to be transformed. The data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell
[in]	n	Block size of the input data.

◆ Tt_inv_apply()

template<std::floating_point T>

template<typename U>

void Tt_inv_apply	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Apply the inverse transpose of the operator applied by T_apply().

The transformation

\[ v = T^{-T} u \]

is performed in-place.

Parameters

[in,out]	data	The data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell.
[in]	n	Block_size of the input data.

◆ Tt_inv_apply_right()

template<std::floating_point T>

template<typename U>

void Tt_inv_apply_right	(	std::span< U >	data,
		std::uint32_t	cell_permutation,
		int	n ) const

inline

Right(post)-apply the transpose inverse of the operator applied by T_apply().

Computes

\[ v^{T} = u^{T} T^{-T} \]

in-place.

Parameters

[in,out]	data	Data to be transformed. This data is flattened with row-major layout, shape=(num_dofs, block_size).
[in]	cell_permutation	Permutation data for the cell.
[in]	n	Block size of the input data.

◆ value_shape()

template<std::floating_point T>

std::span< const std::size_t > value_shape ( ) const

Value shape of the finite element field in physical space.

The value shape describes the shape of the finite element field once the basis has been pushed forward to a physical cell, e.g. {} for a scalar, {2} for a vector in 2D, {3, 3} for a rank-2 tensor in 3D, etc.

It differs from FiniteElement::reference_value_shape for blocked and quadrature elements, and for a Piola-mapped element on a manifold: Raviart-Thomas on a triangle embedded in 3D has reference value shape {2} and value shape {3}, because the push-forward contracts the reference value axis with a Jacobian of shape (gdim, tdim). See ::compute_value_shape.

Exceptions

Exception is thrown for a mixed element as mixed elements do not have a value shape.

Returns: The value shape.

◆ value_size()

template<std::floating_point T>

int value_size ( ) const

Value size of the finite element field in physical space.

The value size is the number of components of the finite element field once the basis has been pushed forward to a physical cell. It is the product of FiniteElement::value_shape, e.g. 1 for a scalar function, 2 for a 2D vector, 9 for a second-order tensor in 3D, etc. For blocked elements this is the value size of the full 'blocked' element.

Exceptions

Exception is thrown for a mixed element as mixed elements do not have a value shape.

Returns: The value size.

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

/__w/dolfinx/dolfinx/cpp/dolfinx/fem/FiniteElement.h
/__w/dolfinx/dolfinx/cpp/dolfinx/fem/FiniteElement.cpp

Public Types

Public Member Functions

Detailed Description

Value shapes

Blocking

Examples

Constructor & Destructor Documentation

◆ FiniteElement() [1/4]

◆ FiniteElement() [2/4]

◆ FiniteElement() [3/4]

◆ FiniteElement() [4/4]

Member Function Documentation

◆ basix_element()

◆ block_size()

◆ create_interpolation_operator()

◆ dof_permutation_fn()

◆ dof_transformation_fn()

◆ dof_transformation_right_fn()

◆ interpolation_ident()

◆ interpolation_operator()

◆ interpolation_points()

◆ is_mixed()

◆ map_ident()

◆ needs_dof_permutations()

◆ needs_dof_transformations()

◆ num_sub_elements()

◆ operator!=()

◆ operator==()

◆ permute()

◆ permute_inv()

◆ physical_base_value_size()

◆ reference_value_shape()

◆ reference_value_size()

◆ signature()

◆ space_dimension()

◆ symmetric()

◆ T_apply()

◆ T_apply_right()

◆ tabulate() [1/2]

◆ tabulate() [2/2]

◆ Tinv_apply()

◆ Tinv_apply_right()

◆ Tt_apply()

◆ Tt_apply_right()

◆ Tt_inv_apply()

◆ Tt_inv_apply_right()

◆ value_shape()

◆ value_size()