Basix
Namespaces | Classes | Functions
basix Namespace Reference

Placeholder. More...

Namespaces

 cell
 
 dofperms
 
 doftransforms
 
 mapping
 Information about mappings.
 
 moments
 
 polyset
 
 quadrature
 basix
 

Classes

class  FiniteElement
 
struct  has_shape
 
struct  has_shape< T, decltype(T::shape)>
 
class  ndspan
 This class provides a view into an n-dimensional row-wise array of data. More...
 
class  ndarray
 

Functions

int register_element (const char *family_name, const char *cell_type, int degree)
 
void release_element (int handle)
 
void tabulate (int handle, double *basis_values, int nd, const double *x, int npoints)
 
void map_push_forward_real (int handle, double *physical_data, const double *reference_data, const double *J, const double *detJ, const double *K, const int physical_dim, const int physical_value_size, const int nresults, const int npoints)
 
void map_pull_back_real (int handle, double *reference_data, const double *physical_data, const double *J, const double *detJ, const double *K, const int physical_dim, const int physical_value_size, const int nresults, const int npoints)
 
void map_push_forward_complex (int handle, std::complex< double > *physical_data, const std::complex< double > *reference_data, const double *J, const double *detJ, const double *K, const int physical_dim, const int physical_value_size, const int nresults, const int npoints)
 
void map_pull_back_complex (int handle, std::complex< double > *reference_data, const std::complex< double > *physical_data, const double *J, const double *detJ, const double *K, const int physical_dim, const int physical_value_size, const int nresults, const int npoints)
 
const char * cell_type (int handle)
 
int degree (int handle)
 Degree.
 
int value_rank (int handle)
 
void value_shape (int handle, int *dimensions)
 
int dim (int handle)
 
const char * family_name (int handle)
 
const char * mapping_name (int handle)
 
void entity_dofs (int handle, int dim, int *num_dofs)
 
int interpolation_num_points (int handle)
 
void interpolation_points (int handle, double *points)
 
void interpolation_matrix (int handle, double *matrix)
 
int cell_geometry_num_points (const char *cell_type)
 
int cell_geometry_dimension (const char *cell_type)
 
void cell_geometry (const char *cell_type, double *points)
 
std::vector< std::vector< std::vector< int > > > topology (const char *cell_type)
 Cell topology.
 
Eigen::MatrixXd compute_expansion_coefficients (cell::type cell_type, const Eigen::MatrixXd &B, const Eigen::MatrixXd &M, const Eigen::ArrayXXd &x, int degree, double kappa_tol=0.0)
 
std::pair< Eigen::ArrayXXd, Eigen::MatrixXd > combine_interpolation_data (const Eigen::ArrayXXd &points_1d, const Eigen::ArrayXXd &points_2d, const Eigen::ArrayXXd &points_3d, const Eigen::MatrixXd &matrix_1d, const Eigen::MatrixXd &matrix_2d, const Eigen::MatrixXd &matrix_3d, const int tdim, const int value_size)
 
FiniteElement create_element (std::string family, std::string cell, int degree)
 Create an element by name.
 
FiniteElement create_element (element::family family, cell::type cell, int degree)
 Create an element by name.
 
std::string version ()
 
constexpr int idx (int p)
 
constexpr int idx (int p, int q)
 
constexpr int idx (int p, int q, int r)
 
template<typename Array >
std::ostream & print_array (std::ostream &out, const Array &array)
 Convenience function for outputting arrays.
 
template<typename T , std::size_t N>
std::ostream & operator<< (std::ostream &out, const ndarray< T, N > &array)
 Pretty printing, useful for debuging.
 
template<typename T , std::size_t N>
std::ostream & operator<< (std::ostream &out, const ndspan< T, N > &span)
 Pretty printing, useful for debuging.
 
FiniteElement create_bdm (cell::type celltype, int degree)
 
FiniteElement create_bubble (cell::type celltype, int degree)
 
FiniteElement create_cr (cell::type celltype, int degree)
 
FiniteElement create_lagrange (cell::type celltype, int degree)
 
FiniteElement create_dlagrange (cell::type celltype, int degree)
 
FiniteElement create_dpc (cell::type celltype, int degree)
 
FiniteElement create_rtc (cell::type celltype, int degree)
 
FiniteElement create_nce (cell::type celltype, int degree)
 
FiniteElement create_nedelec (cell::type celltype, int degree)
 
FiniteElement create_nedelec2 (cell::type celltype, int degree)
 
FiniteElement create_rt (cell::type celltype, int degree)
 
FiniteElement create_regge (cell::type celltype, int degree)
 
FiniteElement create_serendipity (cell::type celltype, int degree)
 

Detailed Description

Placeholder.

Function Documentation

◆ cell_geometry()

void basix::cell_geometry ( const char *  cell_type,
double *  points 
)

Cell points The memory for "x" must be allocated by the user, and is a two dimensional (row-major) ndarray with dimensions [gdim, npoints] where "npoints" is the number of vertices of the cell, and "gdim" is the geometric dimension of the cell.

Parameters
[in]cell_type
[out]pointsArray of size [npoints x gdim]

◆ cell_geometry_dimension()

int basix::cell_geometry_dimension ( const char *  cell_type)

Cell geometric dimension (gdim)

Parameters
[in]cell_type
Returns
gdim

◆ cell_geometry_num_points()

int basix::cell_geometry_num_points ( const char *  cell_type)

Cell geometry number of points (npoints)

Parameters
[in]cell_type
Returns
npoints

◆ cell_type()

const char * basix::cell_type ( int  handle)

String representation of the cell type of the finite element

Parameters
handle
Returns
cell type string

◆ combine_interpolation_data()

std::pair< Eigen::ArrayXXd, Eigen::MatrixXd > basix::combine_interpolation_data ( const Eigen::ArrayXXd &  points_1d,
const Eigen::ArrayXXd &  points_2d,
const Eigen::ArrayXXd &  points_3d,
const Eigen::MatrixXd &  matrix_1d,
const Eigen::MatrixXd &  matrix_2d,
const Eigen::MatrixXd &  matrix_3d,
const int  tdim,
const int  value_size 
)

Combines interpolation data

When the value size is not 1, the matrices are split up into value_size parts, then recombined so that the columns of the matrix that is output is ordered correctly.

Parameters
[in]points_1dThe interpolation points for a 1d entity
[in]points_2dThe interpolation points for a 2d entity
[in]points_3dThe interpolation points for a 3d entity
[in]matrix_1dThe interpolation matrix for a 1d entity
[in]matrix_2dThe interpolation matrix for a 2d entity
[in]matrix_3dThe interpolation matrix for a 3d entity
[in]tdimThe toplogical dimension
[in]value_sizeValue size
Returns
The interpolation points and matrix

◆ compute_expansion_coefficients()

Eigen::MatrixXd basix::compute_expansion_coefficients ( cell::type  cell_type,
const Eigen::MatrixXd &  B,
const Eigen::MatrixXd &  M,
const Eigen::ArrayXXd &  x,
int  degree,
double  kappa_tol = 0.0 
)

Calculates the basis functions of the finite element, in terms of the polynomial basis.

The basis functions \((\phi_i)\) of a finite element can be represented as a linear combination of polynomials \((p_j)\) in an underlying polynomial basis that span the space of all d-dimensional polynomials up to order \(k (P_k^d)\):

\[ \phi_i = \sum_j c_{ij} p_j \]

This function computed the matrix \(C = (c_{ij})\).

In some cases, the basis functions \((\phi_i)\) do not span the full space \(P_k\). In these cases, we represent the space spanned by the basis functions as the span of some polynomials \((q_k)\). These can be represented in terms of the underlying polynomial basis:

\[ q_k = \sum_j b_{kj} p_j \]

If the basis functions span the full space, then \(B = (b_{kj})\) is simply the identity.

The basis functions \(\phi_i\) are defined by a dual set of functionals \((f_l)\). The basis functions are the functions in span{ \(q_k\)} such that:

\[ f_l(\phi_i) = 1 \mbox{ if } i=l \mbox{ else } 0 \]

We can define a matrix D given by applying the functionals to each polynomial p_j:

\[ D = (d_{lj}),\mbox{ where } d_{lj} = f_l(p_j) \]

This function takes the matrices B (span_coeffs) and D (dual) as inputs and returns the matrix C. It computed C using:

\[ C = (B D^T)^{-1} B \]

Example: Order 1 Lagrange elements on a triangle

On a triangle, the scalar expansion basis is:

\[ p_0 = \sqrt{2}/2 \qquad p_1 = \sqrt{3}(2x + y - 1) \qquad p_2 = 3y - 1 \]

These span the space \(P_1\).

Lagrange order 1 elements span the space P_1, so in this example, B (span_coeffs) is the identity matrix:

\[ B = \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix} \]

The functionals defining the Lagrange order 1 space are point evaluations at the three vertices of the triangle. The matrix D (dual) given by applying these to p_0 to p_2 is:

\[ \mbox{dual} = \begin{bmatrix} \sqrt{2}/2 & -\sqrt{3} & -1 \\ \sqrt{2}/2 & \sqrt{3} & -1 \\ \sqrt{2}/2 & 0 & 2 \end{bmatrix} \]

For this example, this function outputs the matrix:

\[ C = \begin{bmatrix} \sqrt{2}/3 & -\sqrt{3}/6 & -1/6 \\ \sqrt{2}/3 & \sqrt{3}/6 & -1/6 \\ \sqrt{2}/3 & 0 & 1/3 \end{bmatrix} \]

The basis functions of the finite element can be obtained by applying the matrix C to the vector \([p_0, p_1, p_2]\), giving:

\[ \begin{bmatrix} 1 - x - y \\ x \\ y \end{bmatrix} \]

Example: Order 1 Raviart-Thomas on a triangle

On a triangle, the 2D vector expansion basis is:

\[ \begin{matrix} p_0 & = & (\sqrt{2}/2, 0) \\ p_1 & = & (\sqrt{3}(2x + y - 1), 0) \\ p_2 & = & (3y - 1, 0) \\ p_3 & = & (0, \sqrt{2}/2) \\ p_4 & = & (0, \sqrt{3}(2x + y - 1)) \\ p_5 & = & (0, 3y - 1) \end{matrix} \]

These span the space \( P_1^2 \).

Raviart-Thomas order 1 elements span a space smaller than \( P_1^2 \), so B (span_coeffs) is not the identity. It is given by:

\[ B = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 1/12 & \sqrt{6}/48 & -\sqrt{2}/48 & 1/12 & 0 & \sqrt{2}/24 \end{bmatrix} \]

Applying the matrix B to the vector \([p_0, p_1, ..., p_5]\) gives the basis of the polynomial space for Raviart-Thomas:

\[ \begin{bmatrix} \sqrt{2}/2 & 0 \\ 0 & \sqrt{2}/2 \\ \sqrt{2}x/8 & \sqrt{2}y/8 \end{bmatrix} \]

The functionals defining the Raviart-Thomas order 1 space are integral of the normal components along each edge. The matrix D (dual) given by applying these to \(p_0\) to \(p_5\) is: dual =

\[ \begin{bmatrix} -\sqrt{2}/2 & -\sqrt{3}/2 & -1/2 & -\sqrt{2}/2 & -\sqrt{3}/2 & -1/2 \\ -\sqrt{2}/2 & \sqrt{3}/2 & -1/2 & 0 & 0 & 0 \\ 0 & 0 & 0 & \sqrt{2}/2 & 0 & -1 \end{bmatrix} \]

In this example, this function outputs the matrix:

\[ C = \begin{bmatrix} -\sqrt{2}/2 & -\sqrt{3}/2 & -1/2 & -\sqrt{2}/2 & -\sqrt{3}/2 & -1/2 \\ -\sqrt{2}/2 & \sqrt{3}/2 & -1/2 & 0 & 0 & 0 \\ 0 & 0 & 0 & \sqrt{2}/2 & 0 & -1 \end{bmatrix} \]

The basis functions of the finite element can be obtained by applying the matrix C to the vector \([p_0, p_1, ..., p_5]\), giving:

\[ \begin{bmatrix} -x & -y \\ x - 1 & y \\ -x & 1 - y \end{bmatrix} \]

Parameters
[in]cell_typeThe cells shape
[in]BThe matrix containing the expansion coefficients defining a polynomial basis spanning the polynomial space for this element
[in]MThe interpolation matrix, such that the dual matrix \(D\) is computed by \(D = MP\)
[in]xThe interpolation points
[in]degreeThe degree of the polynomial set
[in]kappa_tolIf positive, the condition number is computed and an error thrown if the condition number of \(B D^{T}\) is greater than kappa_tol. If kappa_tol is less than 1 the condition number is not checked.
Returns
The matrix C of expansion coefficients that define the basis functions of the finite element space.

◆ create_bdm()

FiniteElement basix::create_bdm ( cell::type  celltype,
int  degree 
)

Create BDM element

Parameters
celltype
degree

◆ create_bubble()

FiniteElement basix::create_bubble ( cell::type  celltype,
int  degree 
)

Create a bubble element on cell with given degree

Parameters
[in]celltypeinterval, triangle, tetrahedral, quadrilateral or hexahedral celltype
[in]degree
Returns
A FiniteElement

◆ create_cr()

FiniteElement basix::create_cr ( cell::type  celltype,
int  degree 
)

Crouzeix-Raviart element

Note
degree must be 1 for Crouzeix-Raviart
Parameters
celltype
degree

◆ create_dlagrange()

FiniteElement basix::create_dlagrange ( cell::type  celltype,
int  degree 
)

Create a Discontinuous Lagrange element on cell with given degree

Parameters
celltypeinterval, triangle, quadrilateral, tetrahedral, or hexahedral celltype
[in]degree
Returns
A FiniteElement

◆ create_dpc()

FiniteElement basix::create_dpc ( cell::type  celltype,
int  degree 
)

Create a DPC element on cell with given degree

Parameters
celltypeinterval, quadrilateral or hexahedral celltype
[in]degree
Returns
A FiniteElement

◆ create_lagrange()

FiniteElement basix::create_lagrange ( cell::type  celltype,
int  degree 
)

Create a Lagrange element on cell with given degree

Parameters
celltypeinterval, triangle, quadrilateral, tetrahedral, or hexahedral celltype
[in]degree
Returns
A FiniteElement

◆ create_nce()

FiniteElement basix::create_nce ( cell::type  celltype,
int  degree 
)

Create NC H(curl) element

Parameters
celltype
degree

◆ create_nedelec()

FiniteElement basix::create_nedelec ( cell::type  celltype,
int  degree 
)

Create Nedelec element (first kind)

Parameters
celltype
degree

◆ create_nedelec2()

FiniteElement basix::create_nedelec2 ( cell::type  celltype,
int  degree 
)

Create Nedelec element (second kind)

Parameters
celltype
degree

◆ create_regge()

FiniteElement basix::create_regge ( cell::type  celltype,
int  degree 
)

Create Regge element

Parameters
celltype
degree

◆ create_rt()

FiniteElement basix::create_rt ( cell::type  celltype,
int  degree 
)

Create Raviart-Thomas element

Parameters
celltype
degree

◆ create_rtc()

FiniteElement basix::create_rtc ( cell::type  celltype,
int  degree 
)

Create RTC H(div) element

Parameters
celltype
degree

◆ create_serendipity()

FiniteElement basix::create_serendipity ( cell::type  celltype,
int  degree 
)

Create a serendipity element on cell with given degree

Parameters
[in]celltypequadrilateral or hexahedral celltype
[in]degree
Returns
A FiniteElement

◆ dim()

int basix::dim ( int  handle)

Finite Element dimension

Parameters
[in]handleIdentifier

◆ entity_dofs()

void basix::entity_dofs ( int  handle,
int  dim,
int *  num_dofs 
)

Number of dofs per entity of given dimension

Parameters
handleIdentifier
dimEntity dimension
[in,out]num_dofsNumber of dofs on each entity

◆ family_name()

const char * basix::family_name ( int  handle)

Family name

Parameters
[in]handleIdentifier

◆ idx() [1/3]

constexpr int basix::idx ( int  p)
constexpr

Compute trivial indexing in a 1D array (for completeness)

Parameters
pIndex in x
Returns
1D Index

◆ idx() [2/3]

constexpr int basix::idx ( int  p,
int  q 
)
constexpr

Compute indexing in a 2D triangular array compressed into a 1D array. This can be used to find the index of a derivative returned by FiniteElement::tabulate. For instance to find d2N/dx2, use FiniteElement::tabulate(2, points)[idx(2, 0)];

Parameters
pIndex in x
qIndex in y
Returns
1D Index

◆ idx() [3/3]

constexpr int basix::idx ( int  p,
int  q,
int  r 
)
constexpr

Compute indexing in a 3D tetrahedral array compressed into a 1D array

Parameters
pIndex in x
qIndex in y
rIndex in z
Returns
1D Index

◆ interpolation_matrix()

void basix::interpolation_matrix ( int  handle,
double *  matrix 
)

Interpolation matrix

Parameters
[in]handleIdentifier
[in,out]matrixThe interpolation matrix

◆ interpolation_num_points()

int basix::interpolation_num_points ( int  handle)

Number of interpolation points

Parameters
[in]handleIdentifier

◆ interpolation_points()

void basix::interpolation_points ( int  handle,
double *  points 
)

Interpolation points

Parameters
[in]handleIdentifier
[in,out]pointsThe interpolation points

◆ map_pull_back_complex()

void basix::map_pull_back_complex ( int  handle,
std::complex< double > *  reference_data,
const std::complex< double > *  physical_data,
const double *  J,
const double *  detJ,
const double *  K,
const int  physical_dim,
const int  physical_value_size,
const int  nresults,
const int  npoints 
)

Map function values from a physical cell to the reference

See map_pull_back_real().

◆ map_pull_back_real()

void basix::map_pull_back_real ( int  handle,
double *  reference_data,
const double *  physical_data,
const double *  J,
const double *  detJ,
const double *  K,
const int  physical_dim,
const int  physical_value_size,
const int  nresults,
const int  npoints 
)

Map function values from a physical cell to the reference

The memory for "reference_data" must be allocated by the user, and is a three dimensional (row-major) ndarray with dimensions [value_size, nresults, npoints] where "npoints" and "nresults" are given as function inputs, and "value_size" is the value size of the finite element (the product of the values in value_shape()).

"reference_data" points to the memory for a three dimensional (row-major) ndarray with dimensions [value_size, nresults, npoints] where "physical_value_size", "nresults", and "npoints" are given as function inputs.

"J" points to the memory for a three dimensional (row-major) ndarray with dimensions [npoints, physical_dim, tdim], where "physical_dim" and "npoints" are given as function inputs, and "tdim" is the topological dimension of the cell for this element.

"K" points to the memory for a two dimensional (row-major) ndarray with dimensions [npoints, tdim, physical_dim].

Parameters
[in]handleThe handle of the basix element
[out]reference_dataThe data on the physical cell at the corresponding point
[in]physical_dataThe reference data at a single point
[in]JThe Jacobian of the map to the cell (evaluated at the point)
[in]detJThe determinant of the Jacobian of the map to the cell (evaluated at the point)
[in]KThe inverse of the Jacobian of the map to the cell (evaluated at the point)
[in]physical_dimThe geometric dimension of the physical domain
[in]physical_value_sizeThe value size of the physical element
[in]nresultsThe number of data values per point
[in]npointsThe number of points

◆ map_push_forward_complex()

void basix::map_push_forward_complex ( int  handle,
std::complex< double > *  physical_data,
const std::complex< double > *  reference_data,
const double *  J,
const double *  detJ,
const double *  K,
const int  physical_dim,
const int  physical_value_size,
const int  nresults,
const int  npoints 
)

Map function values from the reference to a physical cell.

See map_push_forward_real().

◆ map_push_forward_real()

void basix::map_push_forward_real ( int  handle,
double *  physical_data,
const double *  reference_data,
const double *  J,
const double *  detJ,
const double *  K,
const int  physical_dim,
const int  physical_value_size,
const int  nresults,
const int  npoints 
)

Map function values from the reference to a physical cell.

The memory for "physical_data" must be allocated by the user, and is a three dimensional (row-major) ndarray with dimensions [npoints, nresults, physical_value_size] where "physical_value_size", "nresults", and "npoints" are given as function inputs.

"reference_data" points to the memory for a three dimensional (row-major) ndarray with dimensions [npoints, nresults, value_size] where "nresults" and "npoints" are given as function inputs, and "value_size" is the value size of the finite element (the product of the values in value_shape()).

"J" points to the memory for a three dimensional (row-major) ndarray with dimensions [npoints, physical_dim, tdim], where "npoints" and "physical_dim" are given as function inputs, and "tdim" is the topological dimension of the cell for this element.

"K" points to the memory for a three dimensional (row-major) ndarray with dimensions [npoints, tdim, physical_dim].

Parameters
[in]handleThe handle of the basix element
[out]physical_dataThe data on the physical cell at the corresponding point
[in]reference_dataThe reference data at a single point
[in]JThe Jacobian of the map to the cell (evaluated at the point)
[in]detJThe determinant of the Jacobian of the map to the cell (evaluated at the point)
[in]KThe inverse of the Jacobian of the map to the cell (evaluated at the point)
[in]physical_dimThe geometric dimension of the physical domain
[in]physical_value_sizeThe value size of the physical element
[in]nresultsThe number of data values per point
[in]npointsThe number of points

◆ mapping_name()

const char * basix::mapping_name ( int  handle)

Mapping name (identity, piola etc.)

Parameters
[in]handleIdentifier

◆ register_element()

int basix::register_element ( const char *  family_name,
const char *  cell_type,
int  degree 
)

Create element in global registry and return handle

Returns
handle

◆ release_element()

void basix::release_element ( int  handle)

Delete from global registry

Parameters
[in]handleIdentifier

◆ tabulate()

void basix::tabulate ( int  handle,
double *  basis_values,
int  nd,
const double *  x,
int  npoints 
)

Tabulate basis values into the memory at "basis_values" with nd derivatives for the points x.

The memory for "basis_values" must be allocated by the user, and is a four dimensional (row-major) ndarray with dimensions [(nd+tdim)!/nd!tdim!, value_size, dim, npoints] where "npoints" and "nd" are given as function inputs, "tdim" is the topological dimension of the cell for this element, "dim" is the dimension of the finite element (See dim()), and "value_size" is the value size of the finite element (the product of the values in value_shape()).

"x" points to the memory for a two dimensional (row-major) ndarray with dimensions [npoints, tdim] where "npoints" is given as a function input, and "tdim" is the topological dimension of the reference element.

Parameters
[in]handleThe handle for the basix element
[out]basis_valuesBlock of memory to be filled with basis data
[in]ndNumber of derivatives
[in]xPoints at which to evaluate (of size [npoints * tdim])
[in]npointsNumber of points

◆ value_rank()

int basix::value_rank ( int  handle)

Value rank

Parameters
handleIdentifier
Returns
The number of dimensions of the value shape

◆ value_shape()

void basix::value_shape ( int  handle,
int *  dimensions 
)

Value shape

Parameters
[in]handleIdentifier
[in,out]dimensionsArray of value_rank size

◆ version()

std::string basix::version ( )

Return the version number of basix across projects

Returns
version string