3 namespace basix::docstring
6 const std::string topology = R
"(
13 List of topology (vertex indices) for each dimension (0..tdim)
16 const std::string geometry = R
"(
23 (0) Vertex point data of the cell and (1) the shape of the
24 data array. The points are stored in row-major format and the shape
28 const std::string sub_entity_connectivity = R
"(
29 Get the numbers of entities connected to each subentity of the cell.
31 Returns a vector of the form: output[dim][entity_n][connected_dim] =
32 [connected_entity_n0, connected_entity_n1, ...] This indicates that
33 the entity of dimension `dim` and number `entity_n` is connected to
34 the entities of dimension `connected_dim` and numbers
35 `connected_entity_n0`, `connected_entity_n1`, ...
41 List of topology (vertex indices) for each dimension (0..tdim)
44 const std::string sub_entity_geometry = R
"(
45 Sub-entity of a cell, given by topological dimension and index
48 celltype: The cell::type
49 dim: Dimension of sub-entity
50 index: Local index of sub-entity
53 Set of vertex points of the sub-entity. Shape is (npoints, gdim)
56 const std::string create_lattice__celltype_n_type_exterior = R
"(
57 @brief Create a lattice of points on a reference cell optionally
58 including the outer surface points.
60 For a given `celltype`, this creates a set of points on a regular
61 grid which covers the cell, eg for a quadrilateral, with n=2, the
62 points are: `[0,0], [0.5,0], [1,0], [0,0.5], [0.5,0.5], [1,0.5],
63 [0,1], [0.5,1], [1,1]`. If the parameter exterior is set to false,
64 the points lying on the external boundary are omitted, in this case
65 for a quadrilateral with `n == 2`, the points are: `[0.5, 0.5]`. The
66 lattice type can be chosen as type::equispaced or type::gll. The
67 type::gll lattice has points spaced along each edge at the
68 Gauss-Lobatto-Legendre quadrature points. These are the same as
69 type::equispaced when `n < 3`.
72 celltype: The cell type
73 n: Size in each direction. There are `n + 1` points along each edge of the cell
75 exterior: If set, includes outer boundaries
78 Set of points. Shape is `(npoints, tdim)` and storage is
82 const std::string create_lattice__celltype_n_type_exterior_method = R
"(
83 @brief Create a lattice of points on a reference cell optionally
84 including the outer surface points.
86 For a given `celltype`, this creates a set of points on a regular
87 grid which covers the cell, eg for a quadrilateral, with n=2, the
88 points are: `[0,0], [0.5,0], [1,0], [0,0.5], [0.5,0.5], [1,0.5],
89 [0,1], [0.5,1], [1,1]`. If the parameter exterior is set to false,
90 the points lying on the external boundary are omitted, in this case
91 for a quadrilateral with `n == 2`, the points are: `[0.5, 0.5]`. The
92 lattice type can be chosen as type::equispaced or type::gll. The
93 type::gll lattice has points spaced along each edge at the
94 Gauss-Lobatto-Legendre quadrature points. These are the same as
95 type::equispaced when `n < 3`.
98 celltype: The cell type
99 n: Size in each direction. There are `n + 1` points along each edge of the cell
101 exterior: If set, includes outer boundaries
102 simplex_method: The method used to generate points on simplices
105 Set of points. Shape is `(npoints, tdim)` and storage is
109 const std::string cell_volume = R
"(
110 Get the volume of a reference cell
113 cell_type: Type of cell
116 The volume of the cell
119 const std::string cell_facet_normals = R
"(
120 Get the normals to the facets of a reference cell oriented using the
121 low-to-high ordering of the facet
124 cell_type: Type of cell
127 The normals. Shape is (nfacets, gdim)
130 const std::string cell_facet_reference_volumes = R
"(
131 Get the reference volumes of the facets of a reference cell
134 cell_type: Type of cell
137 The volumes of the references associated with each facet
140 const std::string cell_facet_outward_normals = R
"(
141 Get the (outward) normals to the facets of a reference cell
144 cell_type: Type of cell
147 The outward normals. Shape is (nfacets, gdim)
150 const std::string cell_facet_orientations = R
"(
151 Get an array of bools indicating whether or not the facet normals are
155 cell_type: Type of cell
161 const std::string cell_facet_jacobians = R
"(
162 Get the jacobians of the facets of a reference cell
165 cell_type: Type of cell
168 The jacobians of the facets. Shape is (nfacets, gdim, gdim - 1)
171 const std::string FiniteElement__tabulate = R
"(
172 @brief Compute basis values and derivatives at set of points.
174 NOTE: The version of `FiniteElement::tabulate` with the basis data
175 as an out argument should be preferred for repeated call where
176 performance is critical
179 nd: The order of derivatives, up to and including, to compute. Use 0 for the basis functions only.
180 x: The points at which to compute the basis functions. The shape of x is (number of points, geometric dimension).
183 The basis functions (and derivatives). The shape is
184 (derivative, point, basis fn index, value index).
185 - The first index is the derivative, with higher derivatives are
186 stored in triangular (2D) or tetrahedral (3D) ordering, ie for
187 the (x,y) derivatives in 2D: (0,0), (1,0), (0,1), (2,0), (1,1),
188 (0,2), (3,0)... The function basix::indexing::idx can be used to find the
189 appropriate derivative.
190 - The second index is the point index
191 - The third index is the basis function index
192 - The fourth index is the basis function component. Its has size
193 one for scalar basis functions.
196 const std::string FiniteElement__push_forward = R
"(
197 Map function values from the reference to a physical cell. This
198 function can perform the mapping for multiple points, grouped by
199 points that share a common Jacobian.
202 U: The function values on the reference. The indices are [Jacobian index, point index, components].
203 J: The Jacobian of the mapping. The indices are [Jacobian index, J_i, J_j].
204 detJ: The determinant of the Jacobian of the mapping. It has length `J.shape(0)`
205 K: The inverse of the Jacobian of the mapping. The indices are [Jacobian index, K_i, K_j].
208 The function values on the cell. The indices are [Jacobian
209 index, point index, components].
212 const std::string FiniteElement__pull_back = R
"(
213 Map function values from a physical cell to the reference
216 u: The function values on the cell
217 J: The Jacobian of the mapping
218 detJ: The determinant of the Jacobian of the mapping
219 K: The inverse of the Jacobian of the mapping
222 The function values on the reference. The indices are
223 [Jacobian index, point index, components].
226 const std::string FiniteElement__apply_dof_transformation = R
"(
227 Apply DOF transformations to some data
229 NOTE: This function is designed to be called at runtime, so its
230 performance is critical.
234 block_size: The number of data points per DOF
235 cell_info: The permutation info for the cell
241 const std::string FiniteElement__apply_dof_transformation_to_transpose = R
"(
242 Apply DOF transformations to some transposed data
244 NOTE: This function is designed to be called at runtime, so its
245 performance is critical.
249 block_size: The number of data points per DOF
250 cell_info: The permutation info for the cell
256 const std::string FiniteElement__apply_inverse_transpose_dof_transformation
258 Apply inverse transpose DOF transformations to some data
260 NOTE: This function is designed to be called at runtime, so its
261 performance is critical.
265 block_size: The number of data points per DOF
266 cell_info: The permutation info for the cell
272 const std::string FiniteElement__base_transformations = R
"(
273 @brief Get the base transformations.
275 The base transformations represent the effect of rotating or reflecting
276 a subentity of the cell on the numbering and orientation of the DOFs.
277 This returns a list of matrices with one matrix for each subentity
278 permutation in the following order:
279 Reversing edge 0, reversing edge 1, ...
280 Rotate face 0, reflect face 0, rotate face 1, reflect face 1, ...
282 *Example: Order 3 Lagrange on a triangle*
284 This space has 10 dofs arranged like:
297 For this element, the base transformations are:
298 [Matrix swapping 3 and 4,
299 Matrix swapping 5 and 6,
300 Matrix swapping 7 and 8]
301 The first row shows the effect of reversing the diagonal edge. The
302 second row shows the effect of reversing the vertical edge. The third
303 row shows the effect of reversing the horizontal edge.
305 *Example: Order 1 Raviart-Thomas on a triangle*
307 This space has 3 dofs arranged like:
321 These DOFs are integrals of normal components over the edges: DOFs 0 and 2
322 are oriented inward, DOF 1 is oriented outwards.
323 For this element, the base transformation matrices are:
338 The first matrix reverses DOF 0 (as this is on the first edge). The second
339 matrix reverses DOF 1 (as this is on the second edge). The third matrix
340 reverses DOF 2 (as this is on the third edge).
342 *Example: DOFs on the face of Order 2 Nedelec first kind on a tetrahedron*
344 On a face of this tetrahedron, this space has two face tangent DOFs:
357 For these DOFs, the subblocks of the base transformation matrices are:
369 The base transformations for this element. The shape is
370 (ntranformations, ndofs, ndofs)
373 const std::string FiniteElement__entity_transformations = R
"(
374 Return the entity dof transformation matrices
377 The base transformations for this element. The shape is
378 (ntranformations, ndofs, ndofs)
381 const std::string FiniteElement__get_tensor_product_representation = R
"(
382 Get the tensor product representation of this element, or throw an
383 error if no such factorisation exists.
385 The tensor product representation will be a vector of tuples. Each
386 tuple contains a vector of finite elements, and a vector of
387 integers. The vector of finite elements gives the elements on an
388 interval that appear in the tensor product representation. The
389 vector of integers gives the permutation between the numbering of
390 the tensor product DOFs and the number of the DOFs of this Basix
394 The tensor product representation
398 Create a custom finite element
401 cell_type: The cell type
402 value_shape: The value shape of the element
403 wcoeffs: Matrices for the kth 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))
404 x: Interpolation points. Indices are (tdim, entity index, point index, dim)
405 M: The interpolation matrices. Indices are (tdim, entity index, dof, vs, point_index, derivative)
406 interpolation_nderivs: The number of derivatives that need to be used during interpolation
407 map_type: The type of map to be used to map values from the reference to a cell
408 sobolev_space: The underlying Sobolev space for the element
409 discontinuous: Indicates whether or not this is the discontinuous version of the element
410 highest_complete_degree: The highest degree n such that a Lagrange (or vector Lagrange) element of degree n is a subspace of this element
411 highest_degree: The degree of a polynomial in this element's polyset
414 A custom finite element
417 const std::string create_element__family_cell_degree_discontinuous = R
"(
421 family: The element family
422 cell: The reference cell type that the element is defined on
423 degree: The degree of the element
424 discontinuous: Indicates whether the element is discontinuous between cells points of the element. The discontinuous element will have the same DOFs, but they will all be associated with the interior of the cell.
430 const std::string create_element__family_cell_degree_lvariant_discontinuous
432 Create an element using a given Lagrange variant
435 family: The element family
436 cell: The reference cell type that the element is defined on
437 degree: The degree of the element
438 lvariant: The variant of Lagrange to use
439 discontinuous: Indicates whether the element is discontinuous between cells points of the element. The discontinuous element will have the same DOFs, but they will all be associated with the interior of the cell.
445 const std::string create_element__family_cell_degree_lvariant = R
"(
446 Create a continuous element using a given Lagrange variant
449 family: The element family
450 cell: The reference cell type that the element is defined on
451 degree: The degree of the element
452 lvariant: The variant of Lagrange to use
458 const std::string create_element__family_cell_degree_dvariant_discontinuous
460 Create an element using a given DPC variant
463 family: The element family
464 cell: The reference cell type that the element is defined on
465 degree: The degree of the element
466 dvariant: The variant of DPC to use
467 discontinuous: Indicates whether the element is discontinuous between cells points of the element. The discontinuous element will have the same DOFs, but they will all be associated with the interior of the cell.
474 create_element__family_cell_degree_lvariant_dvariant_discontinuous
476 Create an element using a given Lagrange variant and a given DPC variant
479 family: The element family
480 cell: The reference cell type that the element is defined on
481 degree: The degree of the element
482 lvariant: The variant of Lagrange to use
483 dvariant: The variant of DPC to use
484 discontinuous: Indicates whether the element is discontinuous between cells points of the element. The discontinuous element will have the same DOFs, but they will all be associated with the interior of the cell.
490 const std::string create_element__family_cell_degree_dvariant = R
"(
491 Create a continuous element using a given DPC variant
494 family: The element family
495 cell: The reference cell type that the element is defined on
496 degree: The degree of the element
497 dvariant: The variant of DPC to use
503 const std::string create_element__family_cell_degree_lvariant_dvariant = R
"(
504 Create a continuous element using a given Lagrange variant and a given DPC
508 family: The element family
509 cell: The reference cell type that the element is defined on
510 degree: The degree of the element
511 lvariant: The variant of Lagrange to use
512 dvariant: The variant of DPC to use
518 const std::string create_element__family_cell_degree = R
"(
519 Create a continuous element
522 family: The element family
523 cell: The reference cell type that the element is defined on
524 degree: The degree of the element
531 Computes a matrix that represents the interpolation between two
534 If the two elements have the same value size, this function returns
535 the interpolation between them.
537 If element_from has value size 1 and element_to has value size > 1, then
538 this function returns a matrix to interpolate from a blocked element_from
539 (ie multiple copies of element_from) into element_to.
541 If element_to has value size 1 and element_from has value size > 1, then
542 this function returns a matrix that interpolates the components of
543 element_from into copies of element_to.
545 NOTE: If the elements have different value sizes and both are
546 greater than 1, this function throws a runtime error
548 In order to interpolate functions between finite element spaces on arbitrary
549 cells, the functions must be pulled back to the reference element (this pull
550 back includes applying DOF transformations). The matrix that this function
551 returns can then be applied, then the result pushed forward to the cell. If
552 element_from and element_to have the same map type, then only the DOF
553 transformations need to be applied, as the pull back and push forward cancel
557 element_from: The element to interpolate from
558 element_to: The element to interpolate to
561 Matrix operator that maps the 'from' degrees-of-freedom to
562 the 'to' degrees-of-freedom. Shape is (ndofs(element_to),
566 const std::string tabulate_polynomial_set = R
"(
567 @brief Tabulate the orthonormal polynomial basis, and derivatives,
568 at points on the reference cell.
570 All derivatives up to the given order are computed. If derivatives
571 are not required, use `n = 0`. For example, order `n = 2` for a 2D
572 cell, will compute the basis \f$\psi, d\psi/dx, d\psi/dy, d^2
573 \psi/dx^2, d^2\psi/dxdy, d^2\psi/dy^2\f$ in that order (0, 0), (1,
574 0), (0, 1), (2, 0), (1, 1), (0 ,2).
576 For an interval cell there are `nderiv + 1` derivatives, for a 2D
577 cell, there are `(nderiv + 1)(nderiv + 2)/2` derivatives, and in 3D,
578 there are `(nderiv + 1)(nderiv + 2)(nderiv + 3)/6`. The ordering is
579 'triangular' with the lower derivatives appearing first.
584 n: Maximum derivative order. Use n = 0 for the basis only.
585 x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
588 Polynomial sets, for each derivative, tabulated at points.
589 The shape is `(number of derivatives computed, number of points,
592 - The first index is the derivative. The first entry is the basis
593 itself. Derivatives are stored in triangular (2D) or tetrahedral
594 (3D) ordering, eg if `(p, q)` denotes `p` order dervative with
595 repsect to `x` and `q` order derivative with respect to `y`, [0] ->
596 (0, 0), [1] -> (1, 0), [2] -> (0, 1), [3] -> (2, 0), [4] -> (1, 1),
597 [5] -> (0, 2), [6] -> (3, 0),...
598 The function basix::indexing::idx maps tuples `(p, q, r)` to the array
601 - The second index is the point, with index `i` correspondign to the
602 point in row `i` of @p x.
604 - The third index is the basis function index.
605 TODO: Does the order for the third index need to be documented?
608 const std::string tabulate_polynomials = R
"(
609 @brief Tabulate a set of polynomials.
612 polytype: Polynomial type
615 x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
618 Polynomial sets, for each derivative, tabulated at points.
619 The shape is `(basis index, number of points)`.
622 const std::string polynomials_dim = R
"(
623 @brief Dimension of a polynomial space.
626 polytype: The polynomial type
628 d: The polynomial degree
631 The number terms in the basis spanning a space of
632 polynomial degree @p d
635 const std::string make_quadrature__rule_celltype_m = R
"(
636 Make a quadrature rule on a reference cell
639 rule: Type of quadrature rule (or use quadrature::Default)
640 celltype: The cell type
641 m: Maximum degree of polynomial that this quadrature rule will integrate exactly
644 List of points and list of weights. The number of points
645 arrays has shape (num points, gdim)
648 const std::string make_quadrature__celltype_m = R
"(
649 Make a default quadrature rule on reference cell
652 celltype: The cell type
653 m: Maximum degree of polynomial that this quadrature rule will integrate exactly
656 List of points and list of weights. The number of points
657 arrays has shape (num points, gdim)
660 const std::string index__p = R
"(
661 Compute trivial indexing in a 1D array (for completeness)
670 const std::string index__p_q = R
"(
671 Compute indexing in a 2D triangular array compressed into a 1D array.
672 This can be used to find the index of a derivative returned by
673 `FiniteElement::tabulate`. For instance to find d2N/dx2, use
674 `FiniteElement::tabulate(2, points)[idx(2, 0)];`
684 const std::string index__p_q_r = R
"(
685 Compute indexing in a 3D tetrahedral array compressed into a 1D array
696 const std::string space_intersection = R
"(
697 Get the intersection of two Sobolev spaces
700 space1: The first space
701 space2: The second space
std::pair< std::vector< double >, std::array< std::size_t, 2 > > compute_interpolation_operator(const FiniteElement &element_from, const FiniteElement &element_to)
Definition: interpolation.cpp:18
FiniteElement create_custom_element(cell::type cell_type, const std::vector< std::size_t > &value_shape, const impl::cmdspan2_t &wcoeffs, const std::array< std::vector< impl::cmdspan2_t >, 4 > &x, const std::array< std::vector< impl::cmdspan4_t >, 4 > &M, int interpolation_nderivs, maps::type map_type, sobolev::space sobolev_space, bool discontinuous, int highest_complete_degree, int highest_degree)
Definition: finite-element.cpp:464