# 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(*values)

  Bases: `IntEnum`

  Cell type.

  hexahedron = 5
  interval = 1
  point = 0
  prism = 6
  pyramid = 7
  quadrilateral = 4
  tetrahedron = 3
  triangle = 2

class basix.DPCVariant(*values)

  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(*values)

  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(*values)

  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(*values)

  Bases: `IntEnum`

  Lattice simplex method.

  centroid = 3
  isaac = 2
  none = 0
  warp = 1

class basix.LatticeType(*values)

  Bases: `IntEnum`

  Lattice type.

  chebyshev = 2
  equispaced = 0
  gl = 4
  gll = 1

class basix.MapType(*values)

  Bases: `IntEnum`

  Element map type.

  L2Piola = 1
  contravariantPiola = 3
  covariantPiola = 2
  doubleContravariantPiola = 5
  doubleCovariantPiola = 4
  identity = 0

class basix.PolynomialType(*values)

  Bases: `IntEnum`

  Polynomial type.

  bernstein = 2
  lagrange = 1
  legendre = 0

class basix.PolysetType(*values)

  Bases: `IntEnum`

  Polyset type.

  macroedge = 1
  standard = 0

class basix.QuadratureType(*values)

  Bases: `IntEnum`

  Quadrature type.

  default = 0
  gauss_jacobi = 1
  gll = 2
  xiao_gimbutas = 3

class basix.SobolevSpace(*values)

  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[tuple[Any, ...], dtype[_ScalarT]]

  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[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], x: list[list[~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]]]], M: list[list[~numpy.ndarray[tuple[~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._typing.DTypeLike = <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: ElementFamily, celltype: CellType, degree: int, lagrange_variant: LagrangeVariant = LagrangeVariant.unset, dpc_variant: DPCVariant = DPCVariant.unset, discontinuous: bool = False, dof_ordering: list[int] | None = None, dtype: DTypeLike = <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) → ArrayLike

  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: ElementFamily, celltype: CellType, degree: int, lagrange_variant: LagrangeVariant = LagrangeVariant.unset, dpc_variant: DPCVariant = DPCVariant.unset, discontinuous: bool = False, dtype: DTypeLike = <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) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

  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[ArrayLike, ArrayLike]

  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[tuple[Any, ...], dtype[_ScalarT]]) → ArrayLike

  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.