Basix
|
Placeholder. More...
Namespaces | |
cell | |
doftransforms | |
maps | |
Information about finite element maps. | |
moments | |
polyset | |
quadrature | |
basix | |
Classes | |
class | FiniteElement |
Functions | |
FiniteElement | create_bdm (cell::type celltype, int degree) |
FiniteElement | create_bubble (cell::type celltype, int degree) |
FiniteElement | create_cr (cell::type celltype, int degree) |
xt::xtensor< double, 3 > | compute_expansion_coefficients (cell::type cell_type, const xt::xtensor< double, 2 > &B, const std::vector< std::vector< xt::xtensor< double, 3 >>> &M, const std::vector< std::vector< xt::xtensor< double, 2 >>> &x, int degree, double kappa_tol=0.0) |
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) |
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) |
FiniteElement | create_serendipity_div (cell::type celltype, int degree) |
FiniteElement | create_serendipity_curl (cell::type celltype, int degree) |
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, int physical_dim, int physical_value_size, int nresults, 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, int physical_dim, int physical_value_size, int nresults, 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, int physical_dim, int physical_value_size, int nresults, 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, int physical_dim, int physical_value_size, int nresults, int npoints) |
void | permute_dofs (int handle, std::int32_t *dofs, std::uint32_t cell_info) |
void | unpermute_dofs (int handle, std::int32_t *dofs, std::uint32_t cell_info) |
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) |
bool | dof_transformations_are_identity (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. | |
Placeholder.
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.
[in] | cell_type | |
[out] | points | Array of size [npoints x gdim] |
int basix::cell_geometry_dimension | ( | const char * | cell_type | ) |
Cell geometric dimension (gdim)
[in] | cell_type |
int basix::cell_geometry_num_points | ( | const char * | cell_type | ) |
Cell geometry number of points (npoints)
[in] | cell_type |
const char * basix::cell_type | ( | int | handle | ) |
String representation of the cell type of the finite element
handle |
xt::xtensor< double, 3 > basix::compute_expansion_coefficients | ( | cell::type | cell_type, |
const xt::xtensor< double, 2 > & | B, | ||
const std::vector< std::vector< xt::xtensor< double, 3 >>> & | M, | ||
const std::vector< std::vector< xt::xtensor< double, 2 >>> & | x, | ||
int | degree, | ||
double | kappa_tol = 0.0 |
||
) |
Calculates the basis functions of the finite element, in terms of the polynomial basis.
The below explanation uses Einstein notation.
The basis functions \({\phi_i}\) of a finite element are 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 = c_{ij} p_j \]
In some cases, the basis functions \(\{\phi_i\}\) do not span the full space \(P_k\), in which case we denote space spanned by the basis functions by \(\{q_k\}\), which can be represented by:
\[ q_i = b_{ij} p_j. \]
This leads to
\[ \phi_i = c^{\prime}_{ij} q_j = c^{\prime}_{ij} b_{jk} p_k, \]
and in matrix form:
\[ \phi = C^{\prime} B p \]
If the basis functions span the full space, then \( B \) is simply the identity.
The basis functions \(\phi_i\) are defined by a dual set of functionals \(\{f_i\}\). The basis functions are the functions in span{ \(q_k\)} such that
\[ f_i(\phi_j) = \delta_{ij} \]
and inserting the expression for \(\phi_{j}\):
\[ f_i(c^{\prime}_{jk}b_{kl}p_{l}) = c^{\prime}_{jk} b_{kl} f_i \left( p_{l} \right) \]
Defining a matrix D given by applying the functionals to each polynomial \(p_j\):
\[ [D] = d_{ij},\mbox{ where } d_{ij} = f_i(p_j), \]
we have:
\[ C^{\prime} B D^{T} = I \]
and
\[ C^{\prime} = (B D^{T})^{-1}. \]
Recalling that \(C = C^{\prime} B\), where \(C\) is the matrix form of \(c_{ij}\),
\[ C = (B D^{T})^{-1} B \]
This function takes the matrices B (span_coeffs) and D (dual) as inputs and returns the matrix C.
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} \]
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:
\[ D = \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} \]
[in] | cell_type | The cells shape |
[in] | B | Matrices for the kth value index containing the expansion coefficients defining a polynomial basis spanning the polynomial space for this element |
[in] | M | The interpolation tensor, such that the dual matrix \(D\) is computed by \(D = MP\) |
[in] | x | The interpolation points. The vector index is for points on entities of the same dimension, ordered with the lowest topological dimension being first. Each 3D tensor hold the points on cell entities of a common dimension. The shape of the 3d tensors is (num_entities, num_points_per_entity, tdim). |
[in] | degree | The degree of the polynomial basis P used to create the element (before applying B) |
[in] | kappa_tol | If 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. |
Flatten D and take transpose
FiniteElement basix::create_bdm | ( | cell::type | celltype, |
int | degree | ||
) |
Create BDM element
celltype | |
degree |
FiniteElement basix::create_bubble | ( | cell::type | celltype, |
int | degree | ||
) |
Create a bubble element on cell with given degree
[in] | celltype | interval, triangle, tetrahedral, quadrilateral or hexahedral celltype |
[in] | degree |
FiniteElement basix::create_cr | ( | cell::type | celltype, |
int | degree | ||
) |
Crouzeix-Raviart element
celltype | |
degree |
FiniteElement basix::create_dlagrange | ( | cell::type | celltype, |
int | degree | ||
) |
Create a Discontinuous Lagrange element on cell with given degree
celltype | interval, triangle, quadrilateral, tetrahedral, or hexahedral celltype | |
[in] | degree |
FiniteElement basix::create_dpc | ( | cell::type | celltype, |
int | degree | ||
) |
Create a DPC element on cell with given degree
celltype | interval, quadrilateral or hexahedral celltype | |
[in] | degree |
FiniteElement basix::create_lagrange | ( | cell::type | celltype, |
int | degree | ||
) |
Create a Lagrange element on cell with given degree
celltype | interval, triangle, quadrilateral, tetrahedral, or hexahedral celltype | |
[in] | degree |
FiniteElement basix::create_nce | ( | cell::type | celltype, |
int | degree | ||
) |
Create NC H(curl) element
celltype | |
degree |
FiniteElement basix::create_nedelec | ( | cell::type | celltype, |
int | degree | ||
) |
Create Nedelec element (first kind)
celltype | |
degree |
FiniteElement basix::create_nedelec2 | ( | cell::type | celltype, |
int | degree | ||
) |
Create Nedelec element (second kind)
celltype | |
degree |
FiniteElement basix::create_regge | ( | cell::type | celltype, |
int | degree | ||
) |
Create Regge element
celltype | |
degree |
FiniteElement basix::create_rt | ( | cell::type | celltype, |
int | degree | ||
) |
Create Raviart-Thomas element
celltype | |
degree |
FiniteElement basix::create_rtc | ( | cell::type | celltype, |
int | degree | ||
) |
Create RTC H(div) element
celltype | |
degree |
FiniteElement basix::create_serendipity | ( | cell::type | celltype, |
int | degree | ||
) |
Create a serendipity element on cell with given degree
[in] | celltype | quadrilateral or hexahedral celltype |
[in] | degree |
FiniteElement basix::create_serendipity_curl | ( | cell::type | celltype, |
int | degree | ||
) |
Create a serendipity H(curl) element on cell with given degree
[in] | celltype | quadrilateral or hexahedral celltype |
[in] | degree |
FiniteElement basix::create_serendipity_div | ( | cell::type | celltype, |
int | degree | ||
) |
Create a serendipity H(div) element on cell with given degree
[in] | celltype | quadrilateral or hexahedral celltype |
[in] | degree |
int basix::dim | ( | int | handle | ) |
Finite Element dimension
[in] | handle | Identifier |
bool basix::dof_transformations_are_identity | ( | int | handle | ) |
Indicates whether all the DOF transformations are identity matrices
[in] | handle | Identifier |
void basix::entity_dofs | ( | int | handle, |
int | dim, | ||
int * | num_dofs | ||
) |
Number of dofs per entity of given dimension
handle | Identifier | |
dim | Entity dimension | |
[in,out] | num_dofs | Number of dofs on each entity |
const char * basix::family_name | ( | int | handle | ) |
Family name
[in] | handle | Identifier |
|
constexpr |
Compute trivial indexing in a 1D array (for completeness)
p | Index in x |
|
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)];
p | Index in x |
q | Index in y |
|
constexpr |
Compute indexing in a 3D tetrahedral array compressed into a 1D array
p | Index in x |
q | Index in y |
r | Index in z |
void basix::interpolation_matrix | ( | int | handle, |
double * | matrix | ||
) |
Interpolation matrix
[in] | handle | Identifier |
[in,out] | matrix | The interpolation matrix |
int basix::interpolation_num_points | ( | int | handle | ) |
Number of interpolation points
[in] | handle | Identifier |
void basix::interpolation_points | ( | int | handle, |
double * | points | ||
) |
Interpolation points
[in] | handle | Identifier |
[in,out] | points | The interpolation points |
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, | ||
int | physical_dim, | ||
int | physical_value_size, | ||
int | nresults, | ||
int | npoints | ||
) |
Map function values from a physical cell to the reference
See 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, | ||
int | physical_dim, | ||
int | physical_value_size, | ||
int | nresults, | ||
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].
[in] | handle | The handle of the basix element |
[out] | reference_data | The data on the physical cell at the corresponding point |
[in] | physical_data | The reference data at a single point |
[in] | J | The Jacobian of the map to the cell (evaluated at the point) |
[in] | detJ | The determinant of the Jacobian of the map to the cell (evaluated at the point) |
[in] | K | The inverse of the Jacobian of the map to the cell (evaluated at the point) |
[in] | physical_dim | The geometric dimension of the physical domain |
[in] | physical_value_size | The value size of the physical element |
[in] | nresults | The number of data values per point |
[in] | npoints | The number of points |
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, | ||
int | physical_dim, | ||
int | physical_value_size, | ||
int | nresults, | ||
int | npoints | ||
) |
Map function values from the reference to a physical cell.
void basix::map_push_forward_real | ( | int | handle, |
double * | physical_data, | ||
const double * | reference_data, | ||
const double * | J, | ||
const double * | detJ, | ||
const double * | K, | ||
int | physical_dim, | ||
int | physical_value_size, | ||
int | nresults, | ||
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].
[in] | handle | The handle of the basix element |
[out] | physical_data | The data on the physical cell at the corresponding point |
[in] | reference_data | The reference data at a single point |
[in] | J | The Jacobian of the map to the cell (evaluated at the point) |
[in] | detJ | The determinant of the Jacobian of the map to the cell (evaluated at the point) |
[in] | K | The inverse of the Jacobian of the map to the cell (evaluated at the point) |
[in] | physical_dim | The geometric dimension of the physical domain |
[in] | physical_value_size | The value size of the physical element |
[in] | nresults | The number of data values per point |
[in] | npoints | The number of points |
const char * basix::mapping_name | ( | int | handle | ) |
Mapping name (identity, piola etc.)
[in] | handle | Identifier |
void basix::permute_dofs | ( | int | handle, |
std::int32_t * | dofs, | ||
std::uint32_t | cell_info | ||
) |
Permute the DOF numbering of a cell
[in] | handle | The handle of the basix element |
[in,out] | dofs | The dof numbers |
[in] | cell_info | The permutation data of the cell |
int basix::register_element | ( | const char * | family_name, |
const char * | cell_type, | ||
int | degree | ||
) |
Create element in global registry and return handle
void basix::release_element | ( | int | handle | ) |
Delete from global registry
[in] | handle | Identifier |
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.
[in] | handle | The handle for the basix element |
[out] | basis_values | Block of memory to be filled with basis data |
[in] | nd | Number of derivatives |
[in] | x | Points at which to evaluate (of size [npoints * tdim]) |
[in] | npoints | Number of points |
void basix::unpermute_dofs | ( | int | handle, |
std::int32_t * | dofs, | ||
std::uint32_t | cell_info | ||
) |
Unpermute the DOF numbering of a cell
[in] | handle | The handle of the basix element |
[in,out] | dofs | The dof numbers |
[in] | cell_info | The permutation data of the cell |
int basix::value_rank | ( | int | handle | ) |
Value rank
handle | Identifier |
void basix::value_shape | ( | int | handle, |
int * | dimensions | ||
) |
Value shape
[in] | handle | Identifier |
[in,out] | dimensions | Array of value_rank size |
std::string basix::version | ( | ) |
Return the version number of basix across projects