finat package

Subpackages

Submodules

finat.argyris module

class finat.argyris.Argyris(cell, degree=5, variant=None, avg=False)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

finat.aw module

Implementation of the Arnold-Winther finite elements.

class finat.aw.ArnoldWinther(cell, degree)[source]

Bases: PhysicallyMappedElement, FiatElement

basis_transformation(coordinate_mapping)[source]

The extra 6 dofs removed here correspond to the constraints.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

space_dimension()[source]

Return the dimension of the finite element space.

class finat.aw.ArnoldWintherNC(cell, degree)[source]

Bases: PhysicallyMappedElement, FiatElement

basis_transformation(coordinate_mapping)[source]

Note, the extra 3 dofs which are removed here correspond to the constraints.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

space_dimension()[source]

Return the dimension of the finite element space.

finat.bell module

class finat.bell.Bell(cell, degree=5)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

space_dimension()[source]

Return the dimension of the finite element space.

finat.cell_tools module

Find the maximal complex in a list of cell complexes. This is a pass-through from FIAT so that FInAT clients (e.g. tsfc) don’t have to directly import FIAT.

finat.cube module

class finat.cube.FlattenedDimensions(element)[source]

Bases: FiniteElementBase

Class for elements on quadrilaterals and hexahedra. Wraps a tensor product element on a tensor product cell, and flattens its entity dimensions.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

cell[source]
property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

entity_permutations[source]
fiat_equivalent[source]
property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, point, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.direct_serendipity module

class finat.direct_serendipity.DirectSerendipity(cell, degree)[source]

Bases: DirectlyDefinedElement, FiniteElementBase

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set.

  • entity – the cell entity on which to tabulate.

property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

mapping()[source]

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.direct_serendipity.diff(expr, xx, alpha)[source]

Differentiate expr with respect to xx.

Parameters:

  • expr – symengine/symengine Expression to differentiate.

  • xx – iterable of coordinates to differentiate with respect to.

  • alpha – derivative multiindex, one entry for each entry of xx indicating how many derivatives in that direction.

Returns:

New symengine/symengine expression.

finat.direct_serendipity.ds1_sym(ct, *, vs=None, sp=<module 'symengine' from '/opt/hostedtoolcache/Python/3.8.18/x64/lib/python3.8/site-packages/symengine/__init__.py'>)[source]

Constructs lowest-order case of Arbogast’s directly defined C^0 serendipity elements, which are a special case. :param ct: The cell topology of the reference quadrilateral. :param vs: (Optional) coordinates of cell on which to construct the basis.

If it is None, this function constructs symbols for the vertices.

Returns:

a 3-tuple containing symbols for the physical cell coordinates and the physical cell independent variables (e.g. “x” and “y”) and a list of the four basis functions.

finat.direct_serendipity.ds_sym(ct, r, *, vs=None, sp=<module 'symengine' from '/opt/hostedtoolcache/Python/3.8.18/x64/lib/python3.8/site-packages/symengine/__init__.py'>)[source]

Symbolically Constructs Arbogast’s directly defined C^0 serendipity elements, which include all polynomials of degree r plus a couple of rational functions. :param ct: The cell topology of the reference quadrilateral. :param vs: (Optional) coordinates of cell on which to construct the basis.

If it is None, this function constructs symbols for the vertices.

Returns:

a 3-tuple containing symbols for the physical cell coordinates and the physical cell independent variables (e.g. “x” and “y”) and a list of the four basis functions.

finat.direct_serendipity.dsr_sym(ct, r, *, vs=None, sp=<module 'symengine' from '/opt/hostedtoolcache/Python/3.8.18/x64/lib/python3.8/site-packages/symengine/__init__.py'>)[source]

Constructs higher-order (>= 2) case of Arbogast’s directly defined C^0 serendipity elements, which include all polynomials of degree r plus a couple of rational functions. :param ct: The cell topology of the reference quadrilateral. :param vs: (Optional) coordinates of cell on which to construct the basis.

If it is None, this function constructs symbols for the vertices.

Returns:

a 3-tuple containing symbols for the physical cell coordinates and the physical cell independent variables (e.g. “x” and “y”) and a list of the four basis functions.

finat.direct_serendipity.newton_dd(nds, fs)[source]

Constructs Newton’s divided differences for the input arrays, which may include symbolic values.

finat.direct_serendipity.newton_poly(nds, fs, xsym)[source]

Constructs Lagrange interpolating polynomial passing through x values nds and y values fs. Returns a a symbolic object in terms of independent variable xsym.

finat.direct_serendipity.xysub(x, y)[source]

finat.discontinuous module

class finat.discontinuous.DiscontinuousElement(element)[source]

Bases: FiniteElementBase

Element wrapper that makes a FInAT element discontinuous.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

  • coordinate_mapping – a PhysicalGeometry object that provides physical geometry callbacks (may be None).

property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

entity_permutations[source]
fiat_equivalent[source]
formdegree[source]
property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.enriched module

class finat.enriched.EnrichedElement(elements)[source]

Bases: FiniteElementBase

A finite element whose basis functions are the union of the basis functions of several other finite elements.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

cell[source]
complex[source]
degree[source]
entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

entity_permutations[source]

Return the map of topological entities to the map of orientations to permutation lists for the finite element

fiat_equivalent[source]
formdegree[source]
index_shape[source]
is_mixed[source]
property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

value_shape[source]

A tuple indicating the shape of the element.

finat.enriched.concatenate_entity_dofs(ref_el, elements, method)[source]

Combine the entity DoFs from a list of elements into a combined dict containing the information for the concatenated DoFs of all the elements.

Parameters:

  • ref_el – the reference cell

  • elements – subelement whose DoFs are concatenated

  • method – method to obtain the entity DoFs dict

Returns:

concatenated entity DoFs dict

finat.enriched.concatenate_entity_permutations(elements)[source]

For each dimension, for each entity, and for each possible entity orientation, collect the DoF permutation lists from entity_permutations dicts of elements and concatenate them.

Parameters:

elements – subelements whose DoF permutation lists are concatenated

Returns:

entity_permutation dict of the EnrichedElement object composed of elements.

finat.enriched.tree_map(f, *args)[source]

Like the built-in map(), but applies to a tuple tree.

finat.fiat_elements module

class finat.fiat_elements.Bernstein(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.BrezziDouglasFortinMarini(cell, degree)[source]

Bases: VectorFiatElement

class finat.fiat_elements.BrezziDouglasMarini(cell, degree, variant=None)[source]

Bases: VectorFiatElement

class finat.fiat_elements.BrezziDouglasMariniCubeEdge(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.BrezziDouglasMariniCubeFace(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.Bubble(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.CrouzeixRaviart(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.DPC(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.DiscontinuousLagrange(cell, degree, variant=None)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.DiscontinuousTaylor(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.FacetBubble(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.FiatElement(fiat_element)[source]

Bases: FiniteElementBase

Base class for finite elements for which the tabulation is provided by FIAT.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set.

  • entity – the cell entity on which to tabulate.

property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

property fiat_equivalent

The FIAT element equivalent to this FInAT element.

property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

class finat.fiat_elements.HellanHerrmannJohnson(cell, degree)[source]

Bases: FiatElement

class finat.fiat_elements.KongMulderVeldhuizen(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.Lagrange(cell, degree, variant=None)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.Nedelec(cell, degree, variant=None)[source]

Bases: VectorFiatElement

class finat.fiat_elements.NedelecSecondKind(cell, degree, variant=None)[source]

Bases: VectorFiatElement

class finat.fiat_elements.RaviartThomas(cell, degree, variant=None)[source]

Bases: VectorFiatElement

class finat.fiat_elements.Real(cell, degree, variant=None)[source]

Bases: DiscontinuousLagrange

class finat.fiat_elements.Regge(cell, degree)[source]

Bases: FiatElement

class finat.fiat_elements.ScalarFiatElement(fiat_element)[source]

Bases: FiatElement

property value_shape

A tuple indicating the shape of the element.

class finat.fiat_elements.Serendipity(cell, degree)[source]

Bases: ScalarFiatElement

class finat.fiat_elements.TrimmedSerendipityCurl(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.TrimmedSerendipityDiv(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.TrimmedSerendipityEdge(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.TrimmedSerendipityFace(cell, degree)[source]

Bases: VectorFiatElement

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

class finat.fiat_elements.VectorFiatElement(fiat_element)[source]

Bases: FiatElement

property value_shape

A tuple indicating the shape of the element.

finat.fiat_elements.point_evaluation(fiat_element, order, refcoords, entity)[source]

finat.finiteelementbase module

class finat.finiteelementbase.FiniteElementBase[source]

Bases: object

abstract basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

  • coordinate_mapping – a PhysicalGeometry object that provides physical geometry callbacks (may be None).

abstract property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

abstract property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

dual_evaluation(fn)[source]

Get a GEM expression for performing the dual basis evaluation at the nodes of the reference element. Currently only works for flat elements: tensor elements are implemented in TensorFiniteElement.

Parameters:

fn – Callable representing the function to dual evaluate. Callable should take in an AbstractPointSet and return a GEM expression for evaluation of the function at those points.

Returns:

A tuple (dual_evaluation_gem_expression, basis_indices) where the given basis_indices are those needed to form a return expression for the code which is compiled from dual_evaluation_gem_expression (alongside any argument multiindices already encoded within fn)

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

abstract entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

entity_support_dofs()[source]

Return the map of topological entities to degrees of freedom that have non-zero support on those entities for the finite element.

property fiat_equivalent

The FIAT element equivalent to this FInAT element.

abstract property formdegree

Degree of the associated form (FEEC)

get_indices()[source]

A tuple of GEM Index of the correct extents to loop over the basis functions of this element.

get_value_indices()[source]

A tuple of GEM Index of the correct extents to loop over the value shape of this element.

abstract property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

abstract property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

abstract point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

abstract space_dimension()[source]

Return the dimension of the finite element space.

abstract property value_shape

A tuple indicating the shape of the element.

finat.finiteelementbase.entity_support_dofs(elem, entity_dim)[source]

Return the map of entity id to the degrees of freedom for which the corresponding basis functions take non-zero values.

Parameters:

  • elem – FInAT finite element

  • entity_dim – Dimension of the cell subentity.

finat.hct module

class finat.hct.HsiehCloughTocher(cell, degree=3, avg=False)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

class finat.hct.ReducedHsiehCloughTocher(cell, degree=3)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

space_dimension()[source]

Return the dimension of the finite element space.

finat.hdivcurl module

class finat.hdivcurl.HCurlElement(wrappee)[source]

Bases: WrapperElementBase

H(curl) wrapper element for tensor product elements.

fiat_equivalent[source]
property formdegree

Degree of the associated form (FEEC)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

class finat.hdivcurl.HDivElement(wrappee)[source]

Bases: WrapperElementBase

H(div) wrapper element for tensor product elements.

fiat_equivalent[source]
property formdegree

Degree of the associated form (FEEC)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

class finat.hdivcurl.WrapperElementBase(wrappee, transform)[source]

Bases: FiniteElementBase

Common base class for H(div) and H(curl) element wrappers.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

  • coordinate_mapping – a PhysicalGeometry object that provides physical geometry callbacks (may be None).

property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property entity_permutations

Returns a nested dictionary that gives, for each dimension, for each entity, and for each possible entity orientation, the DoF permutation array that maps the entity local DoF ordering to the canonical global DoF ordering.

The entity permutations dict for the degree 4 Lagrange finite element on the interval, for instance, is given by:

{0: {0: {0: [0]},
     1: {0: [0]}},
 1: {0: {0: [0, 1, 2],
         1: [2, 1, 0]}}}

Note that there are two entities on dimension 0 (vertices), each of which has only one possible orientation, while there is a single entity on dimension 1 (interval), which has two possible orientations representing non-reflected and reflected intervals.

entity_support_dofs()[source]

Return the map of topological entities to degrees of freedom that have non-zero support on those entities for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

transform

A transformation applied on the scalar/vector values of the wrapped element to produce an H(div) or H(curl) conforming element.

property value_shape

A tuple indicating the shape of the element.

wrappee

An appropriate tensor product FInAT element whose basis functions are mapped to produce an H(div) or H(curl) conforming element.

finat.hdivcurl.select_hcurl_transformer(element)[source]
finat.hdivcurl.select_hdiv_transformer(element)[source]

finat.hermite module

class finat.hermite.Hermite(cell, degree=3)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

finat.johnson_mercier module

class finat.johnson_mercier.JohnsonMercier(cell, degree, variant=None)[source]

Bases: PhysicallyMappedElement, FiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

finat.mixed module

finat.mixed.MixedElement(elements)[source]

Constructor function for FEniCS-style mixed elements.

Implements mixed element using EnrichedElement and value shape transformations with MixedSubElement.

class finat.mixed.MixedSubElement(element, size, offset)[source]

Bases: FiniteElementBase

Element wrapper that flattens value shape and places the flattened vector in a longer vector of zeros.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

  • coordinate_mapping – a PhysicalGeometry object that provides physical geometry callbacks (may be None).

property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

entity_support_dofs()[source]

Return the map of topological entities to degrees of freedom that have non-zero support on those entities for the finite element.

property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.morley module

class finat.morley.Morley(cell, degree=2)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

finat.mtw module

class finat.mtw.MardalTaiWinther(cell, degree)[source]

Bases: PhysicallyMappedElement, FiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

entity_closure_dofs()[source]

Return the map of topological entities to degrees of freedom on the closure of those entities for the finite element.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

space_dimension()[source]

Return the dimension of the finite element space.

finat.nodal_enriched module

class finat.nodal_enriched.NodalEnrichedElement(elements)[source]

Bases: FiatElement

An enriched element with a nodal basis.

finat.physically_mapped module

class finat.physically_mapped.DirectlyDefinedElement[source]

Bases: NeedsCoordinateMappingElement

Base class for directly defined elements such as direct serendipity that bypass a coordinate mapping.

class finat.physically_mapped.NeedsCoordinateMappingElement[source]

Bases: object

Abstract class for elements that require physical information either to map or construct their basis functions.

class finat.physically_mapped.PhysicalGeometry[source]

Bases: object

abstract cell_size()[source]

The cell size at each vertex.

Returns:

A GEM expression for the cell size, shape (nvertex, ).

abstract detJ_at(point)[source]

The determinant of the jacobian of the physical coordinates at a point.

Parameters:

point – The point in reference space to evaluate the Jacobian determinant.

Returns:

A GEM expression for the Jacobian determinant.

abstract jacobian_at(point)[source]

The jacobian of the physical coordinates at a point.

Parameters:

point – The point in reference space (on the cell) to evaluate the Jacobian.

Returns:

A GEM expression for the Jacobian, shape (gdim, tdim).

abstract physical_edge_lengths()[source]

The length of each edge of the physical cell.

Returns:

A GEM expression for the length of each edge (numbered according to FIAT conventions), shape (nfacet, ).

abstract physical_normals()[source]

The (unit) physical cell normals for each facet.

Returns:

A GEM expression for the normal to each facet (numbered according to FIAT conventions). These are all computed by a clockwise rotation of the physical tangents, shape (nfacet, gdim).

abstract physical_points(point_set, entity=None)[source]

Maps reference element points to GEM for the physical coordinates

Parameters:

  • point_set – A point_set on the reference cell to push forward to physical space.

  • entity – Reference cell entity on which the point set is defined (for example if it is a point set on a facet).

Returns:

a GEM expression for the physical locations of the points, shape (gdim, ) with free indices of the point_set.

abstract physical_tangents()[source]

The (unit) physical cell tangents on each facet.

Returns:

A GEM expression for the tangent to each facet (numbered according to FIAT conventions). These always point from low to high numbered local vertex, shape (nfacet, gdim).

abstract physical_vertices()[source]

Physical locations of the cell vertices.

Returns:

a GEM expression for the physical vertices, shape (gdim, ).

abstract reference_normals()[source]

The (unit) reference cell normals for each facet.

Returns:

A GEM expression for the normal to each facet (numbered according to FIAT conventions), shape (nfacet, tdim).

class finat.physically_mapped.PhysicallyMappedElement(*args, **kwargs)[source]

Bases: NeedsCoordinateMappingElement

A mixin that applies a “physical” transformation to tabulated basis functions.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]
abstract basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

point_evaluation(order, refcoords, entity=None)[source]

finat.point_set module

class finat.point_set.AbstractPointSet[source]

Bases: object

A way of specifying a known set of points, perhaps with some (tensor) structure.

Points, when stored, have shape point_set_shape + (point_dimension,) where point_set_shape is () for scalar, (N,) for N element vector, (N, M) for N x M matrix etc.

property dimension

Point dimension.

abstract property expression

GEM expression describing the points, with free indices self.indices and shape (point dimension,).

abstract property indices

GEM indices with matching shape and extent to the structure of the point set.

abstract property points

A flattened numpy array of points or UnknownPointsArray object with shape (# of points, point dimension).

class finat.point_set.GaussLegendrePointSet(points)[source]

Bases: PointSet

Gauss-Legendre quadrature points on the interval.

This facilitates implementing discontinuous spectral elements.

Build a PointSet from a vector of points

Parameters:

points – A vector of N points of shape (N, D) where D is the dimension of each point.

class finat.point_set.GaussLobattoLegendrePointSet(points)[source]

Bases: PointSet

Gauss-Lobatto-Legendre quadrature points on the interval.

This facilitates implementing continuous spectral elements.

Build a PointSet from a vector of points

Parameters:

points – A vector of N points of shape (N, D) where D is the dimension of each point.

class finat.point_set.PointSet(points)[source]

Bases: AbstractPointSet

A basic point set with no internal structure representing a vector of points.

Build a PointSet from a vector of points

Parameters:

points – A vector of N points of shape (N, D) where D is the dimension of each point.

almost_equal(other, tolerance=1e-12)[source]

Approximate numerical equality of point sets

expression[source]
indices[source]
points[source]
class finat.point_set.PointSingleton(point)[source]

Bases: AbstractPointSet

A point set representing a single point.

These have a gem.Literal expression and no indices.

Build a PointSingleton from a single point.

Parameters:

point – A single point of shape (D,) where D is the dimension of the point.

expression[source]
indices = ()
points[source]
class finat.point_set.TensorPointSet(factors)[source]

Bases: AbstractPointSet

almost_equal(other, tolerance=1e-12)[source]

Approximate numerical equality of point sets

expression[source]
indices[source]
points[source]
class finat.point_set.UnknownPointSet(points_expr)[source]

Bases: AbstractPointSet

A point set representing a vector of points with unknown locations but known gem.Variable expression.

The .points property is an UnknownPointsArray object with shape (N, D) where N is the number of points and D is their dimension.

The .expression property is a derived gem.partial_indexed with shape (D,) and free indices for the points N.

Build a PointSingleton from a gem expression for a single point.

Parameters:

points_expr – A gem.Variable expression representing a vector of N points in D dimensions. Should have shape (N, D) and no free indices. For runtime tabulation the variable name should begin with ‘rt_:’.

expression[source]
indices[source]
points[source]
class finat.point_set.UnknownPointsArray(shape)[source]

Bases: object

A placeholder for a set of unknown points with appropriate length and size but without indexable values. For use with :class:`AbstractPointSet`s whose points are not known at compile time.

Parameters:

shape – The shape of the unknown set of N points of shape (N, D) where D is the dimension of each point.

finat.powell_sabin module

class finat.powell_sabin.QuadraticPowellSabin12(cell, degree=2, avg=False)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

class finat.powell_sabin.QuadraticPowellSabin6(cell, degree=2)[source]

Bases: PhysicallyMappedElement, ScalarFiatElement

basis_transformation(coordinate_mapping)[source]

Transformation matrix for the basis functions.

Parameters:

coordinate_mapping – Object providing physical geometry.

finat.quadrature module

class finat.quadrature.AbstractQuadratureRule[source]

Bases: object

Abstract class representing a quadrature rule as point set and a corresponding set of weights.

abstract property point_set

Point set object representing the quadrature points.

abstract property weight_expression

GEM expression describing the weights, with the same free indices as the point set.

class finat.quadrature.QuadratureRule(point_set, weights)[source]

Bases: AbstractQuadratureRule

Generic quadrature rule with no internal structure.

point_set[source]
weight_expression[source]
class finat.quadrature.TensorProductQuadratureRule(factors)[source]

Bases: AbstractQuadratureRule

Quadrature rule which is a tensor product of other rules.

point_set[source]
weight_expression[source]
finat.quadrature.make_quadrature(ref_el, degree, scheme='default')[source]

Generate quadrature rule for given reference element that will integrate an polynomial of order ‘degree’ exactly.

For low-degree (<=6) polynomials on triangles and tetrahedra, this uses hard-coded rules, otherwise it falls back to a collapsed Gauss scheme on simplices. On tensor-product cells, it is a tensor-product quadrature rule of the subcells.

Parameters:

  • ref_el – The FIAT cell to create the quadrature for.

  • degree – The degree of polynomial that the rule should integrate exactly.

finat.quadrature_element module

class finat.quadrature_element.QuadratureElement(fiat_ref_cell, rule)[source]

Bases: FiniteElementBase

A set of quadrature points pretending to be a finite element.

Construct a QuadratureElement.

Parameters:

  • fiat_ref_cell – The FIAT reference cell to build the QuadratureElement on

  • rule – A AbstractQuadratureRule to use

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

cell[source]
property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

fiat_equivalent[source]
property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, refcoords, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.quadrature_element.make_quadrature_element(fiat_ref_cell, degree, scheme='default')[source]

Construct a QuadratureElement from a given a reference element, degree and scheme.

Parameters:

  • fiat_ref_cell – The FIAT reference cell to build the QuadratureElement on.

  • degree – The degree of polynomial that the rule should integrate exactly.

  • scheme – The quadrature scheme to use - e.g. “default”, “canonical” or “KMV”.

Returns:

The appropriate QuadratureElement

finat.restricted module

finat.restricted.RestrictedElement(element, restriction_domain, *, indices=None)[source]

Construct a restricted element.

Parameters:

  • element – The element to restrict.

  • restriction_domain – Which entities to restrict to.

  • indices – Indices of basis functions to select (not supported)

Returns:

A new element.

Note

A restriction domain of “interior” means to select the dofs on the cell, all other domains (e.g. “face”, “edge”) select dofs in the closure of the entity.

Warning

The returned element may not be interpolatory. That is, the dual basis (if implemented) might not be nodal to the primal basis. Assembly still works (basis_evaluation is fine), but interpolation may produce bad results.

Restrictions of FIAT-implemented CiarletElements are always nodal.

finat.restricted.codim_to_r(codim, dim)[source]
finat.restricted.r_to_codim(restriction, dim)[source]
finat.restricted.restrict(element, domain, take_closure)[source]
finat.restricted.restrict(element: FiatElement, domain, take_closure)
finat.restricted.restrict(element: PhysicallyMappedElement, domain, take_closure)
finat.restricted.restrict(element: FlattenedDimensions, domain, take_closure)
finat.restricted.restrict(element: Legendre, domain, take_closure)
finat.restricted.restrict(element: DiscontinuousLagrange, domain, take_closure)
finat.restricted.restrict(element: DiscontinuousElement, domain, take_closure)
finat.restricted.restrict(element: EnrichedElement, domain, take_closure)
finat.restricted.restrict(element: HCurlElement, domain, take_closure)
finat.restricted.restrict(element: HDivElement, domain, take_closure)
finat.restricted.restrict(element: MixedSubElement, domain, take_closure)
finat.restricted.restrict(element: TensorProductElement, domain, take_closure)
finat.restricted.restrict(element: TensorFiniteElement, domain, take_closure)
finat.restricted.restrict(element: HDivTrace, domain, take_closure)

Restrict an element to a given subentity.

Parameters:

  • element – The element to restrict.

  • domain – The subentity to restrict to.

  • take_closure – Gather dofs in closure of the subentities? Ignored for “interior” domain.

Raises:
Returns:

A new finat element.

finat.restricted.restrict_discontinuous(element, domain, take_closure)[source]
finat.restricted.restrict_enriched(element, domain, take_closure)[source]
finat.restricted.restrict_fiat(element, domain, take_closure)[source]
finat.restricted.restrict_flattened_dimensions(element, domain, take_closure)[source]
finat.restricted.restrict_hcurl(element, domain, take_closure)[source]
finat.restricted.restrict_hdiv(element, domain, take_closure)[source]
finat.restricted.restrict_hdivtrace(element, domain, take_closure)[source]
finat.restricted.restrict_mixed(element, domain, take_closure)[source]
finat.restricted.restrict_physically_mapped(element, domain, take_closure)[source]
finat.restricted.restrict_tfe(element, domain, take_closure)[source]
finat.restricted.restrict_tpe(element, domain, take_closure)[source]

finat.runtime_tabulated module

class finat.runtime_tabulated.RuntimeTabulated(cell, degree, variant=None, shift_axes=0, restriction=None, continuous=True)[source]

Bases: FiniteElementBase

Element placeholder for tabulations provided at run time through a kernel argument.

Used by Themis.

Construct a runtime tabulated element.

Parameters:

  • cell – reference cell

  • degree – polynomial degree (int)

  • variant – variant string of the UFL element

  • shift_axes – first dimension

  • restriction – None for single-cell integrals, ‘+’ or ‘-’ for interior facet integrals depending on which we need the tabulation on

  • continuous – continuous or discontinuous element?

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

cell[source]
degree[source]
entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

formdegree[source]
property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, point, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.spectral module

class finat.spectral.FDMBrokenH1(cell, degree)[source]

Bases: ScalarFiatElement

1D Broken CG element with FDM shape functions.

class finat.spectral.FDMBrokenL2(cell, degree)[source]

Bases: ScalarFiatElement

1D DG element with derivatives of FDM shape functions.

class finat.spectral.FDMDiscontinuousLagrange(cell, degree)[source]

Bases: ScalarFiatElement

1D DG element with derivatives of FDM shape functions with point evaluation Bcs.

class finat.spectral.FDMHermite(cell, degree)[source]

Bases: ScalarFiatElement

1D CG element with FDM shape functions, point evaluation BCs and derivative BCs.

class finat.spectral.FDMLagrange(cell, degree)[source]

Bases: ScalarFiatElement

1D CG element with FDM shape functions and point evaluation BCs.

class finat.spectral.FDMQuadrature(cell, degree)[source]

Bases: ScalarFiatElement

1D CG element with FDM shape functions and orthogonalized vertex modes.

class finat.spectral.GaussLegendre(cell, degree)[source]

Bases: DiscontinuousLagrange

1D discontinuous element with nodes at the Gauss-Legendre points.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set.

  • entity – the cell entity on which to tabulate.

class finat.spectral.GaussLobattoLegendre(cell, degree)[source]

Bases: Lagrange

1D continuous element with nodes at the Gauss-Lobatto points.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set.

  • entity – the cell entity on which to tabulate.

class finat.spectral.IntegratedLegendre(cell, degree, variant=None)[source]

Bases: ScalarFiatElement

CG element with integrated Legendre polynomials.

class finat.spectral.Legendre(cell, degree, variant=None)[source]

Bases: ScalarFiatElement

DG element with Legendre polynomials.

finat.sympy2gem module

finat.sympy2gem.sympy2gem(node, self)[source]
finat.sympy2gem.sympy2gem(node: Expr, self)
finat.sympy2gem.sympy2gem(node: Expr, self)
finat.sympy2gem.sympy2gem(node: Add, self)
finat.sympy2gem.sympy2gem(node: Add, self)
finat.sympy2gem.sympy2gem(node: Mul, self)
finat.sympy2gem.sympy2gem(node: Mul, self)
finat.sympy2gem.sympy2gem(node: Pow, self)
finat.sympy2gem.sympy2gem(node: Pow, self)
finat.sympy2gem.sympy2gem(node: bool, self)
finat.sympy2gem.sympy2gem(node: BooleanFalse, self)
finat.sympy2gem.sympy2gem(node: BooleanTrue, self)
finat.sympy2gem.sympy2gem(node: int, self)
finat.sympy2gem.sympy2gem(node: Integer, self)
finat.sympy2gem.sympy2gem(node: Integer, self)
finat.sympy2gem.sympy2gem(node: float, self)
finat.sympy2gem.sympy2gem(node: Float, self)
finat.sympy2gem.sympy2gem(node: Float, self)
finat.sympy2gem.sympy2gem(node: Symbol, self)
finat.sympy2gem.sympy2gem(node: Symbol, self)
finat.sympy2gem.sympy2gem(node: Rational, self)
finat.sympy2gem.sympy2gem(node: Rational, self)
finat.sympy2gem.sympy2gem(node: Abs, self)
finat.sympy2gem.sympy2gem(node: Abs, self)
finat.sympy2gem.sympy2gem(node: Not, self)
finat.sympy2gem.sympy2gem(node: Not, self)
finat.sympy2gem.sympy2gem(node: Or, self)
finat.sympy2gem.sympy2gem(node: Or, self)
finat.sympy2gem.sympy2gem(node: And, self)
finat.sympy2gem.sympy2gem(node: And, self)
finat.sympy2gem.sympy2gem(node: Equality, self)
finat.sympy2gem.sympy2gem(node: Equality, self)
finat.sympy2gem.sympy2gem(node: StrictGreaterThan, self)
finat.sympy2gem.sympy2gem(node: GreaterThan, self)
finat.sympy2gem.sympy2gem(node: StrictLessThan, self)
finat.sympy2gem.sympy2gem(node: StrictLessThan, self)
finat.sympy2gem.sympy2gem(node: LessThan, self)
finat.sympy2gem.sympy2gem(node: LessThan, self)
finat.sympy2gem.sympy2gem(node: Piecewise, self)
finat.sympy2gem.sympy2gem(node: Piecewise, self)
finat.sympy2gem.sympy2gem(node: ITE, self)
finat.sympy2gem.sympy2gem_abs(node, self)[source]
finat.sympy2gem.sympy2gem_add(node, self)[source]
finat.sympy2gem.sympy2gem_and(node, self)[source]
finat.sympy2gem.sympy2gem_boolean(node, self)[source]
finat.sympy2gem.sympy2gem_conditional(node, self)[source]
finat.sympy2gem.sympy2gem_eq(node, self)[source]
finat.sympy2gem.sympy2gem_expr(node, self)[source]
finat.sympy2gem.sympy2gem_float(node, self)[source]
finat.sympy2gem.sympy2gem_ge(node, self)[source]
finat.sympy2gem.sympy2gem_gt(node, self)[source]
finat.sympy2gem.sympy2gem_ifthenelse(node, self)[source]
finat.sympy2gem.sympy2gem_integer(node, self)[source]
finat.sympy2gem.sympy2gem_le(node, self)[source]
finat.sympy2gem.sympy2gem_lt(node, self)[source]
finat.sympy2gem.sympy2gem_mul(node, self)[source]
finat.sympy2gem.sympy2gem_not(node, self)[source]
finat.sympy2gem.sympy2gem_or(node, self)[source]
finat.sympy2gem.sympy2gem_pow(node, self)[source]
finat.sympy2gem.sympy2gem_rational(node, self)[source]
finat.sympy2gem.sympy2gem_symbol(node, self)[source]

finat.tensor_product module

class finat.tensor_product.TensorProductElement(factors)[source]

Bases: FiniteElementBase

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Return code for evaluating the element at known points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • ps – the point set object.

  • entity – the cell entity on which to tabulate.

  • coordinate_mapping – a PhysicalGeometry object that provides physical geometry callbacks (may be None).

cell[source]
complex[source]
property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

entity_permutations[source]
fiat_equivalent[source]
formdegree[source]
property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

mapping[source]
point_evaluation(order, point, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.tensor_product.compose_permutations(factors)[source]

For the TensorProductElement object composed of factors, construct, for each dimension tuple, for each entity, and for each possible entity orientation combination, the DoF permutation list.

Parameters:

factors – element factors.

Returns:

entity_permutation dict of the TensorProductElement object composed of factors.

For tensor-product elements, one needs to consider two kinds of orientations: extrinsic orientations and intrinsic (“material”) orientations.

Example:

UFCQuadrilateral := UFCInterval x UFCInterval

eo (extrinsic orientation): swap axes (X -> y, Y-> x) io (intrinsic orientation): reflect component intervals o (total orientation) : (2 ** dim) * eo + io

eoio 0 1 2 3

1—3 0—2 3—1 2—0

0 | | | | | | | |

0—2 1—3 2—0 3—1

2—3 3—2 0—1 1—0

1 | | | | | | | |

0—1 1—0 2—3 3—2

import FIAT
import finat

cell = FIAT.ufc_cell("interval")
elem = finat.DiscontinuousLagrange(cell, 1)
elem = finat.TensorProductElement([elem, elem])
print(elem.entity_permutations)

prints:

{(0, 0): {0: {(0, 0, 0): []},

1: {(0, 0, 0): []}, 2: {(0, 0, 0): []}, 3: {(0, 0, 0): []}},

(0, 1): {0: {(0, 0, 0): [],

(0, 0, 1): []},

1: {(0, 0, 0): [],

(0, 0, 1): []}},

(1, 0): {0: {(0, 0, 0): [],

(0, 1, 0): []},

1: {(0, 0, 0): [],

(0, 1, 0): []}},

(1, 1): {0: {(0, 0, 0): [0, 1, 2, 3],

(0, 0, 1): [1, 0, 3, 2], (0, 1, 0): [2, 3, 0, 1], (0, 1, 1): [3, 2, 1, 0], (1, 0, 0): [0, 2, 1, 3], (1, 0, 1): [2, 0, 3, 1], (1, 1, 0): [1, 3, 0, 2], (1, 1, 1): [3, 1, 2, 0]}}}

finat.tensor_product.factor_point_set(product_cell, product_dim, point_set)[source]

Factors a point set for the product element into a point sets for each subelement.

Parameters:

  • product_cell – a TensorProductCell

  • product_dim – entity dimension for the product cell

  • point_set – point set for the product element

finat.tensor_product.productise(factors, method)[source]

Tensor product the dict mapping topological entities to dofs across factors.

Parameters:

  • factors – element factors.

  • method – instance method to call on each factor to get dofs.

finat.tensorfiniteelement module

class finat.tensorfiniteelement.TensorFiniteElement(element, shape, transpose=False)[source]

Bases: FiniteElementBase

A Finite element whose basis functions have the form:

\[\boldsymbol\phi_{i \alpha \beta} = \mathbf{e}_{\alpha} \mathbf{e}_{\beta}^{\mathrm{T}}\phi_i\]

Where \(\{\mathbf{e}_\alpha,\, \alpha=0\ldots\mathrm{shape[0]}\}\) and \(\{\mathbf{e}_\beta,\, \beta=0\ldots\mathrm{shape[1]}\}\) are the bases for \(\mathbb{R}^{\mathrm{shape[0]}}\) and \(\mathbb{R}^{\mathrm{shape[1]}}\) respectively; and \(\{\phi_i\}\) is the basis for the corresponding scalar finite element space.

Parameters:

  • element – The scalar finite element.

  • shape – The geometric shape of the tensor element.

  • transpose – Changes the DoF ordering from the Firedrake-style XYZ XYZ XYZ XYZ to the FEniCS-style XXXX YYYY ZZZZ. That is, tensor shape indices come before the scalar basis function indices when transpose=True.

\(\boldsymbol\phi_{i\alpha\beta}\) is, of course, tensor-valued. If we subscript the vector-value with \(\gamma\epsilon\) then we can write:

\[\boldsymbol\phi_{\gamma\epsilon(i\alpha\beta)} = \delta_{\gamma\alpha}\delta_{\epsilon\beta}\phi_i\]

This form enables the simplification of the loop nests which will eventually be created, so it is the form we employ here.

property base_element

The base element of this tensor element.

basis_evaluation(order, ps, entity=None, coordinate_mapping=None)[source]

Produce the recipe for basis function evaluation at a set of points \(q\):

\[ \begin{align}\begin{aligned}\boldsymbol\phi_{(\gamma \epsilon) (i \alpha \beta) q} = \delta_{\alpha \gamma} \delta_{\beta \epsilon}\phi_{i q}\\\nabla\boldsymbol\phi_{(\epsilon \gamma \zeta) (i \alpha \beta) q} = \delta_{\alpha \epsilon} \delta_{\beta \gamma}\nabla\phi_{\zeta i q}\end{aligned}\end{align} \]
property cell

The reference cell on which the element is defined.

property complex

The reference cell complex over which bases are defined. Can be different than self.cell in the case of macro elements.

property degree

The degree of the embedding polynomial space.

In the tensor case this is a tuple.

property dual_basis

Return a dual evaluation gem weight tensor Q and point set x to dual evaluate a function fn at.

The general dual evaluation is then Q * fn(x) (the contraction of Q with fn(x) along the the indices of x and any shape introduced by fn).

If the dual weights are scalar then Q, for a general scalar FIAT element, is a matrix with dimensions

(num_nodes, num_points)

If the dual weights are tensor valued then Q, for a general tensor valued FIAT element, is a tensor with dimensions

(num_nodes, num_points, dual_weight_shape[0], ..., dual_weight_shape[n])

If the dual basis is of a tensor product or FlattenedDimensions element with N factors then Q in general is a tensor with dimensions

(num_nodes_factor1, ..., num_nodes_factorN,
 num_points_factor1, ..., num_points_factorN,
 dual_weight_shape[0], ..., dual_weight_shape[n])

where num_points_factorX are made free indices that match the free indices of x (which is now a TensorPointSet).

If the dual basis is of a tensor finite element with some shape (S1, S2, …, Sn) then the tensor element tQ is constructed from the base element’s Q by taking the outer product with appropriately sized identity matrices:

tQ = Q ⊗ 𝟙ₛ₁ ⊗ 𝟙ₛ₂ ⊗ ... ⊗ 𝟙ₛₙ

Note

When Q is returned, the contraction indices of the point set are already free indices rather than being left in its shape (as either num_points or num_points_factorX). This is to avoid index labelling confusion when performing the dual evaluation contraction.

Note

FIAT element dual bases are built from their Functional.pt_dict properties. Therefore any FIAT dual bases with derivative nodes represented via a Functional.deriv_dict property does not currently have a FInAT dual basis.

dual_evaluation(fn)[source]

Get a GEM expression for performing the dual basis evaluation at the nodes of the reference element. Currently only works for flat elements: tensor elements are implemented in TensorFiniteElement.

Parameters:

fn – Callable representing the function to dual evaluate. Callable should take in an AbstractPointSet and return a GEM expression for evaluation of the function at those points.

Returns:

A tuple (dual_evaluation_gem_expression, basis_indices) where the given basis_indices are those needed to form a return expression for the code which is compiled from dual_evaluation_gem_expression (alongside any argument multiindices already encoded within fn)

entity_dofs()[source]

Return the map of topological entities to degrees of freedom for the finite element.

property formdegree

Degree of the associated form (FEEC)

property index_shape

A tuple indicating the number of degrees of freedom in the element. For example a scalar quadratic Lagrange element on a triangle would return (6,) while a vector valued version of the same element would return (6, 2)

property mapping

Appropriate mapping from the reference cell to a physical cell for all basis functions of the finite element.

point_evaluation(order, point, entity=None)[source]

Return code for evaluating the element at an arbitrary points on the reference element.

Parameters:

  • order – return derivatives up to this order.

  • refcoords – GEM expression representing the coordinates on the reference entity. Its shape must be a vector with the correct dimension, its free indices are arbitrary.

  • entity – the cell entity on which to tabulate.

space_dimension()[source]

Return the dimension of the finite element space.

property value_shape

A tuple indicating the shape of the element.

finat.trace module

class finat.trace.HDivTrace(cell, degree)[source]

Bases: ScalarFiatElement

Module contents