basix

Basix is a finite element definition and tabulation library.

The core of the library is written in C++, but the majority of Basix’s functionality can be used via this Python interface.

class basix.CellType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Cell type.

hexahedron = 5
interval = 1
point = 0
prism = 6
pyramid = 7
quadrilateral = 4
tetrahedron = 3
triangle = 2
class basix.DPCVariant(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

DPC variant.

diagonal_equispaced = 5
diagonal_gll = 6
horizontal_equispaced = 3
horizontal_gll = 4
legendre = 7
simplex_equispaced = 1
simplex_gll = 2
unset = 0
class basix.ElementFamily(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Finite element family.

BDM = 4
CR = 6
DPC = 8
HHJ = 11
Hermite = 12
N1E = 3
N2E = 5
P = 1
RT = 2
Regge = 7
bubble = 9
custom = 0
iso = 13
serendipity = 10
class basix.LagrangeVariant(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Lagrange element variant.

bernstein = 12
chebyshev_centroid = 7
chebyshev_isaac = 6
chebyshev_warped = 5
equispaced = 1
gl_centroid = 10
gl_isaac = 9
gl_warped = 8
gll_centroid = 4
gll_isaac = 3
gll_warped = 2
legendre = 11
unset = 0
class basix.LatticeSimplexMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Lattice simplex method.

centroid = 3
isaac = 2
none = 0
warp = 1
class basix.LatticeType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Lattice type.

chebyshev = 2
equispaced = 0
gl = 4
gll = 1
class basix.MapType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Element map type.

L2Piola = 1
contravariantPiola = 3
covariantPiola = 2
doubleContravariantPiola = 5
doubleCovariantPiola = 4
identity = 0
class basix.PolynomialType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Polynomial type.

bernstein = 1
legendre = 0
class basix.PolysetType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Polyset type.

macroedge = 1
standard = 0
class basix.QuadratureType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Quadrature type.

default = 0
gauss_jacobi = 1
gll = 2
xiao_gimbutas = 3
class basix.SobolevSpace(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Sobolev space.

H1 = 1
H2 = 2
H3 = 3
HCurl = 11
HDiv = 10
HDivDiv = 13
HEin = 12
HInf = 8
L2 = 0
basix.compute_interpolation_operator(e0: FiniteElement, e1: FiniteElement) ndarray[Any, dtype[_ScalarType_co]]

Compute a matrix that represents the interpolation between two elements.

If the two elements have the same value size, this function returns the interpolation between them.

If element_from has value size 1 and element_to has value size > 1, then this function returns a matrix to interpolate from a blocked element_from (ie multiple copies of element_from) into element_to.

If element_to has value size 1 and element_from has value size > 1, then this function returns a matrix that interpolates the components of element_from into copies of element_to.

Note

If the elements have different value sizes and both are greater than 1, this function throws a runtime error

In order to interpolate functions between finite element spaces on arbitrary cells, the functions must be pulled back to the reference element (this pull back includes applying DOF transformations). The matrix that this function returns can then be applied, then the result pushed forward to the cell. If element_from and element_to have the same map type, then only the DOF transformations need to be applied, as the pull back and push forward cancel each other out.

Parameters:
  • e0 – The element to interpolate from

  • e1 – The element to interpolate to

Returns:

Matrix operator that maps the ‘from’ degrees-of-freedom to the ‘to’ degrees-of-freedom. Shape is (ndofs(element_to), ndofs(element_from))

basix.create_custom_element(cell_type: ~basix._basixcpp.CellType, value_shape: tuple[int, ...], wcoeffs: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.floating]], x: list[list[~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.floating]]]], M: list[list[~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.floating]]]], interpolation_nderivs: int, map_type: ~basix._basixcpp.MapType, sobolev_space: ~basix._basixcpp.SobolevSpace, discontinuous: bool, embedded_subdegree: int, embedded_superdegree: int, poly_type: ~basix._basixcpp.PolysetType, dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.float64'>) FiniteElement

Create a custom finite element.

Parameters:
  • cell_type – Element cell type.

  • value_shape – Value shape of the element.

  • wcoeffs – Matrices for the k-th value index containing the expansion coefficients defining a polynomial basis spanning the polynomial space for this element. Shape is (dim(finite element polyset), dim(Legendre polynomials)).

  • x – Interpolation points. Indices are (tdim, entity index, point index, dim).

  • M – Interpolation matrices. Indices are (tdim, entity index, dof, vs, point_index, derivative).

  • interpolation_nderivs – Number of derivatives that need to be used during interpolation.

  • map_type – Type of map to be used to map values from the reference to a physical cell.

  • sobolev_space – Underlying Sobolev space for the element.

  • discontinuous – If True create the discontinuous version of the element.

  • embedded_subdegree – Highest degree n such that a Lagrange (or vector Lagrange) element of degree n is a subspace of this element.

  • embedded_superdegree – Degree of a polynomial in this element’s polyset.

  • poly_type – Type of polyset to use for this element.

  • dtype – Element scalar type.

Returns:

A custom finite element.

basix.create_element(family: ~basix._basixcpp.ElementFamily, celltype: ~basix._basixcpp.CellType, degree: int, lagrange_variant: ~basix._basixcpp.LagrangeVariant = LagrangeVariant.unset, dpc_variant: ~basix._basixcpp.DPCVariant = DPCVariant.unset, discontinuous: bool = False, dof_ordering: list[int] | None = None, dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.float64'>) FiniteElement

Create a finite element.

Parameters:
  • family – Finite element family.

  • celltype – Reference cell type that the element is defined on.

  • degree – Polynomial degree of the element.

  • lagrange_variant – Lagrange variant type.

  • dpc_variant – DPC variant type.

  • discontinuous – If True element is discontinuous. The discontinuous element will have the same DOFs as a continuous element, but the DOFs will all be associated with the interior of the cell.

  • dof_ordering – Ordering of dofs for ElementDofLayout.

  • dtype – Element scalar type.

Returns:

A finite element.

basix.create_lattice(celltype: CellType, n: int, ltype: LatticeType, exterior: bool, method: LatticeSimplexMethod = LatticeSimplexMethod.none) _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Create a lattice of points on a reference cell.

Parameters:
  • celltype – Cell type.

  • n – The size in each direction. There will be n+1 points along each edge of the cell.

  • ltype – Lattice type.

  • exterior – If True, the points on the edges will be included.

  • method – The simplex method used to generate points on simplices.

Returns:

Lattice points

basix.create_tp_element(family: ~basix._basixcpp.ElementFamily, celltype: ~basix._basixcpp.CellType, degree: int, lagrange_variant: ~basix._basixcpp.LagrangeVariant = LagrangeVariant.unset, dpc_variant: ~basix._basixcpp.DPCVariant = DPCVariant.unset, discontinuous: bool = False, dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.float64'>) FiniteElement

Create a finite element with tensor product ordering.

Parameters:
  • family – Finite element family.

  • celltype – Reference cell type that the element is defined on

  • degree – Polynomial degree of the element.

  • lagrange_variant – Lagrange variant type.

  • dpc_variant – DPC variant type.

  • discontinuous – If True element is discontinuous. The discontinuous element will have the same DOFs as a continuous element, but the DOFs will all be associated with the interior of the cell.

  • dtype – Element scalar type.

Returns:

A finite element.

basix.geometry(celltype: CellType) _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Cell geometry.

Parameters:

celltype – Cell type.

Returns:

Vertices of the cell.

basix.index(p: int, q: int | None = None, r: int | None = None) int

Compute the indexing in a 1D, 2D or 3D simplex.

Parameters:
  • p – Index in x.

  • q – Index in y.

  • r – Index in z.

Returns:

Index in a flattened 1D array.

basix.make_quadrature(cell: CellType, degree: int, rule: QuadratureType = QuadratureType.default, polyset_type: PolysetType = PolysetType.standard) tuple[_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]

Create a quadrature rule.

Parameters:
  • cell – Cell type.

  • degree – Maximum polynomial degree that will be integrated exactly.

  • rule – Quadrature rule.

  • polyset_type – Type of polynomial that will be integrated exactly.

Returns:

Quadrature points and weights.

basix.polyset_restriction(ptype: PolysetType, cell: CellType, restriction_cell: CellType) PolysetType

Get the polyset type that represents the restrictions of a type on a subentity.

Parameters:
  • ptype – The polynomial type

  • cell – The cell type

  • restriction_cell – The cell type if the subentity

Returns:

The restricted polyset type

basix.polyset_superset(cell: CellType, type1: PolysetType, type2: PolysetType) PolysetType

Get the polyset type that is a superset of two types on the given cell.

Parameters:
  • cell – The cell type

  • type1 – The first polyset type

  • type2 – The second polyset type

Returns:

The superset type

basix.tabulate_polynomials(ptype: PolynomialType, celltype: CellType, degree: int, pts: ndarray[Any, dtype[_ScalarType_co]]) _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Tabulate a set of polynomials on a reference cell.

Parameters:
  • ptype – The polynomial type

  • celltype – The cell type

  • degree – The polynomial degree

  • pts – The points

Returns:

Tabulated polynomials

basix.topology(celltype: CellType) list[list[list[int]]]

Cell topology.

Parameters:

celltype – Cell type.

Returns:

Vertex indices for each sub-entity of the cell.

Modules

cell

Functions to get cell geometry information and manipulate cell types.

finite_element

Functions for creating finite elements.

interpolation

Interpolation.

lattice

Functions to manipulate lattice types.

maps

Maps.

numba_helpers

Helper functions for writing DOLFINx custom kernels using Numba.

polynomials

Functions for working with polynomials.

quadrature

Functions to manipulate quadrature types.

sobolev_spaces

Functions for handling Sobolev spaces.

ufl

Functions to directly wrap Basix elements in UFL.

utils

Utility funcitons.