symfem.finite_element

Abstract finite element classes and functions.

Attributes

TabulatedBasis

Exceptions

NoTensorProduct

Error for element without a tensor representation.

Classes

FiniteElement	Abstract finite element.
CiarletElement	Finite element defined using the Ciarlet definition.
DirectElement	Finite element defined directly.
EnrichedElement	Finite element defined directly.
ElementBasisFunction	A basis function of a finite element.

Module Contents

symfem.finite_element.TabulatedBasis

exception symfem.finite_element.NoTensorProduct

Bases: Exception

Error for element without a tensor representation.

class symfem.finite_element.FiniteElement(reference: symfem.references.Reference, order: int, space_dim: int, domain_dim: int, range_dim: int, range_shape: tuple[int, Ellipsis] | None = None)

Bases: abc.ABC

Abstract finite element.

_float_basis_functions: list[symfem.functions.Function] | None

_value_scale: sympy.core.expr.Expr | None

reference

order

space_dim

domain_dim

range_dim

property lagrange_subdegree: int

Abstractmethod:

Get the Lagrange subdegree of the element.

This is the degree of the highest degree Lagrange space whose polynomial space is a subspace of this element’s polynomial space.

property lagrange_superdegree: int | None

Abstractmethod:

Get the Lagrange superdegree of the element.

This is the degree of the highest degree Lagrange space whose polynomial space is a superspace of this element’s polynomial space.

property polynomial_subdegree: int

Abstractmethod:

Get the polynomial subdegree of the element.

This is the degree of the highest degree complete polynomial space that is a subspace of this element’s polynomial space.

property polynomial_superdegree: int | None

Abstractmethod:

Get the polynomial superdegree of the element.

This is the degree of the highest degree complete polynomial space that is a superspace of this element’s polynomial space.

abstractmethod dof_plot_positions() → list[symfem.geometry.PointType]

Get the points to plot each DOF at on a DOF diagram.

Returns:

The DOF positions

abstractmethod dof_directions() → list[symfem.geometry.PointType | None]

Get the direction associated with each DOF.

Returns:

The DOF directions

abstractmethod dof_entities() → list[tuple[int, int]]

Get the entities that each DOF is associated with.

Returns:

The entities

plot_dof_diagram(filename: str | list[str], plot_options: dict[str, Any] = {}, **kwargs: Any)

Plot a diagram showing the DOFs of the element.

Parameters:

• filename – The file name

• plot_options – Options for the plot

• kwargs – Keyword arguments

abstractmethod entity_dofs(entity_dim: int, entity_number: int) → list[int]

Get the numbers of the DOFs associated with the given entity.

Parameters:

• entity_dim – The dimension of the entity

• entity_number – The number of the entity

Returns:

The numbers of the DOFs associated with the entity

abstractmethod get_basis_functions(use_tensor_factorisation: bool = False) → list[symfem.functions.Function]

Get the basis functions of the element.

Parameters:

use_tensor_factorisation – Should a tensor factorisation be used?

Returns:

The basis functions

get_basis_function(n: int) → symfem.basis_functions.BasisFunction

Get a single basis function of the element.

Parameters:

n – The number of the basis function

Returns:

The basis function

tabulate_basis(points_in: symfem.geometry.SetOfPointsInput, order: str = 'xyzxyz') → TabulatedBasis

Evaluate the basis functions of the element at the given points.

Parameters:

• points_in – The points

• order – The order to return the values

Returns:

The tabulated basis functions

tabulate_basis_float(points_in: symfem.geometry.SetOfPointsInput) → TabulatedBasis

Evaluate the basis functions of the element at the given points in xyz,xyz order.

Parameters:

points_in – The points

Returns:

The tabulated basis functions

plot_basis_function(n: int, filename: str | list[str], cell: symfem.references.Reference | None = None, **kwargs: Any)

Plot a diagram showing a basis function.

Parameters:

• n – The basis function number

• filename – The file name

• cell – The cell to push the basis function to and plot on

• kwargs – Keyword arguments

abstractmethod map_to_cell(vertices_in: symfem.geometry.SetOfPointsInput, basis: list[symfem.functions.Function] | None = None, forward_map: symfem.geometry.PointType | None = None, inverse_map: symfem.geometry.PointType | None = None) → list[symfem.functions.Function]

Map the basis onto a cell using the appropriate mapping for the element.

Parameters:

• vertices_in – The vertices of the cell

• basis – The basis functions

• forward_map – The map from the reference to the cell

• inverse_map – The map to the reference from the cell

Returns:

The basis functions mapped to the cell

abstractmethod get_polynomial_basis() → list[symfem.functions.Function]

Get the symbolic polynomial basis for the element.

Returns:

The polynomial basis

test()

Run tests for this element.

test_continuity()

Test that this element has the correct continuity.

get_tensor_factorisation() → list[tuple[str, list[FiniteElement], list[int]]]

Get the representation of the element as a tensor product.

Returns:

The tensor factorisation

_get_basis_functions_tensor() → list[symfem.functions.Function]

Compute the basis functions using the space’s tensor product factorisation.

Returns:

The basis functions

init_kwargs() → dict[str, Any]

Return the keyword arguments used to create this element.

Returns:

Keyword arguments dictionary

property name: str

Get the name of the element.

Returns:

The name of the element’s family

names: list[str] = []

references: list[str] = []

last_updated = '2025.12.0'

cache = True

value_type = 'unknown'

continuity: str | None = None

_max_continuity_test_order = 4

class symfem.finite_element.CiarletElement(reference: symfem.references.Reference, order: int, basis: list[symfem.functions.FunctionInput], dofs: symfem.functionals.ListOfFunctionals, domain_dim: int, range_dim: int, range_shape: tuple[int, Ellipsis] | None = None)

Bases: FiniteElement

Finite element defined using the Ciarlet definition.

_basis

dofs

_basis_functions: list[symfem.functions.Function] | None = None

entity_dofs(entity_dim: int, entity_number: int) → list[int]

Get the numbers of the DOFs associated with the given entity.

Parameters:

• entity_dim – The dimension of the entity

• entity_number – The number of the entity

Returns:

The numbers of the DOFs associated with the entity

dof_plot_positions() → list[symfem.geometry.PointType]

Get the points to plot each DOF at on a DOF diagram.

Returns:

The DOF positions

dof_directions() → list[symfem.geometry.PointType | None]

Get the direction associated with each DOF.

Returns:

The DOF directions

dof_entities() → list[tuple[int, int]]

Get the entities that each DOF is associated with.

Returns:

The entities

get_polynomial_basis() → list[symfem.functions.Function]

Get the symbolic polynomial basis for the element.

Returns:

The polynomial basis

get_dual_matrix(inverse=False, caching=True) → sympy.matrices.dense.MutableDenseMatrix

Get the dual matrix.

Parameters:

• inverse – Should the dual matrix be inverted?

• caching – Should the result be cached

Returns:

The dual matrix

get_basis_functions(use_tensor_factorisation: bool = False) → list[symfem.functions.Function]

Get the basis functions of the element.

Parameters:

use_tensor_factorisation – Should a tensor factorisation be used?

Returns:

The basis functions

plot_basis_function(n: int, filename: str | list[str], cell: symfem.references.Reference | None = None, **kwargs: Any)

Plot a diagram showing a basis function.

Parameters:

• n – The basis function number

• filename – The file name

• cell – The cell to push the basis function to and plot on

• kwargs – Keyword arguments

map_to_cell(vertices_in: symfem.geometry.SetOfPointsInput, basis: list[symfem.functions.Function] | None = None, forward_map: symfem.geometry.PointType | None = None, inverse_map: symfem.geometry.PointType | None = None) → list[symfem.functions.Function]

Map the basis onto a cell using the appropriate mapping for the element.

Parameters:

• vertices_in – The vertices of the cell

• basis – The basis functions

• forward_map – The map from the reference to the cell

• inverse_map – The map to the reference from the cell

Returns:

The basis functions mapped to the cell

test()

Run tests for this element.

test_dof_points()

Test that DOF points are valid.

test_functional_entities()

Test that the dof entities are valid and match the references of integrals.

test_functionals()

Test that the functionals are satisfied by the basis functions.

class symfem.finite_element.DirectElement(reference: symfem.references.Reference, order: int, basis_functions: list[symfem.functions.FunctionInput], basis_entities: list[tuple[int, int]], domain_dim: int, range_dim: int, range_shape: tuple[int, Ellipsis] | None = None)

Bases: FiniteElement

Finite element defined directly.

_basis_functions: list[symfem.functions.Function]

_basis_entities

entity_dofs(entity_dim: int, entity_number: int) → list[int]

Get the numbers of the DOFs associated with the given entity.

Parameters:

• entity_dim – The dimension of the entity

• entity_number – The number of the entity

Returns:

The numbers of the DOFs associated with the entity

dof_plot_positions() → list[symfem.geometry.PointType]

Get the points to plot each DOF at on a DOF diagram.

Returns:

The DOF positions

dof_directions() → list[symfem.geometry.PointType | None]

Get the direction associated with each DOF.

Returns:

The DOF directions

dof_entities() → list[tuple[int, int]]

Get the entities that each DOF is associated with.

Returns:

The entities

get_basis_functions(use_tensor_factorisation: bool = False) → list[symfem.functions.Function]

Get the basis functions of the element.

Parameters:

use_tensor_factorisation – Should a tensor factorisation be used?

Returns:

The basis functions

map_to_cell(vertices_in: symfem.geometry.SetOfPointsInput, basis: list[symfem.functions.Function] | None = None, forward_map: symfem.geometry.PointType | None = None, inverse_map: symfem.geometry.PointType | None = None) → list[symfem.functions.Function]

Map the basis onto a cell using the appropriate mapping for the element.

Parameters:

• vertices_in – The vertices of the cell

• basis – The basis functions

• forward_map – The map from the reference to the cell

• inverse_map – The map to the reference from the cell

Returns:

The basis functions mapped to the cell

abstractmethod get_polynomial_basis() → list[symfem.functions.Function]

Get the symbolic polynomial basis for the element.

Returns:

The polynomial basis

test()

Run tests for this element.

test_independence()

Test that the basis functions of this element are linearly independent.

class symfem.finite_element.EnrichedElement(subelements: list[FiniteElement])

Bases: FiniteElement

Finite element defined directly.

_basis_functions: list[symfem.functions.Function] | None

_subelements

entity_dofs(entity_dim: int, entity_number: int) → list[int]

Get the numbers of the DOFs associated with the given entity.

Parameters:

• entity_dim – The dimension of the entity

• entity_number – The number of the entity

Returns:

The numbers of the DOFs associated with the entity

dof_plot_positions() → list[symfem.geometry.PointType]

Get the points to plot each DOF at on a DOF diagram.

Returns:

The DOF positions

dof_directions() → list[symfem.geometry.PointType | None]

Get the direction associated with each DOF.

Returns:

The DOF directions

dof_entities() → list[tuple[int, int]]

Get the entities that each DOF is associated with.

Returns:

The entities

get_basis_functions(use_tensor_factorisation: bool = False) → list[symfem.functions.Function]

Get the basis functions of the element.

Parameters:

use_tensor_factorisation – Should a tensor factorisation be used?

Returns:

The basis functions

map_to_cell(vertices_in: symfem.geometry.SetOfPointsInput, basis: list[symfem.functions.Function] | None = None, forward_map: symfem.geometry.PointType | None = None, inverse_map: symfem.geometry.PointType | None = None) → list[symfem.functions.Function]

Map the basis onto a cell using the appropriate mapping for the element.

Parameters:

• vertices_in – The vertices of the cell

• basis – The basis functions

• forward_map – The map from the reference to the cell

• inverse_map – The map to the reference from the cell

Returns:

The basis functions mapped to the cell

abstractmethod get_polynomial_basis() → list[symfem.functions.Function]

Get the symbolic polynomial basis for the element.

Returns:

The polynomial basis

test()

Run tests for this element.

class symfem.finite_element.ElementBasisFunction(element: FiniteElement, n: int)

Bases: symfem.basis_functions.BasisFunction

A basis function of a finite element.

element

n

get_function() → symfem.functions.Function

Get the actual basis function.

Returns:

The basis function