Note: this is documentation for an old release. View the latest documentation at docs.fenicsproject.org/v0.5.0/v0.8.0/cpp

# Basix 0.5.0

## HomeInstallationDemosC++ docsPython docs

docs.h
1 #include <string>
2
3 namespace basix::docstring
4 {
5
6 const std::string topology = R"(
7 Cell topology
8
9 Args:
10  celltype: Cell Type
11
12 Returns::
13  List of topology (vertex indices) for each dimension (0..tdim)
14 )";
15
16 const std::string geometry = R"(
17 Cell geometry
18
19 Args:
20  celltype: Cell Type
21
22 Returns::
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
25  is is (npoints, gdim)
26 )";
27
28 const std::string sub_entity_connectivity = R"(
29 Get the numbers of entities connected to each subentity of the cell.
30
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, ...
36
37 Args:
38  celltype: Cell Type
39
40 Returns:
41  List of topology (vertex indices) for each dimension (0..tdim)
42 )";
43
44 const std::string sub_entity_geometry = R"(
45 Sub-entity of a cell, given by topological dimension and index
46
47 Args:
48  celltype: The cell::type
49  dim: Dimension of sub-entity
50  index: Local index of sub-entity
51
52 Returns:
53  Set of vertex points of the sub-entity. Shape is (npoints, gdim)
54 )";
55
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.
59
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.
70
71 Args:
72  celltype: The cell type
73  n: Size in each direction. There are n + 1 points along each edge of the cell
74  type: A lattice type
75  exterior: If set, includes outer boundaries
76
77 Returns:
78  Set of points. Shape is (npoints, tdim) and storage is
79  row-major
80 )";
81
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.
85
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.
96
97 Args:
98  celltype: The cell type
99  n: Size in each direction. There are n + 1 points along each edge of the cell
100  type: A lattice type
101  exterior: If set, includes outer boundaries
102  simplex_method: The method used to generate points on simplices
103
104 Returns:
105  Set of points. Shape is (npoints, tdim) and storage is
106  row-major
107 )";
108
109 const std::string cell_volume = R"(
110 Get the volume of a reference cell
111
112 Args:
113  cell_type: Type of cell
114
115 Returns:
116  The volume of the cell
117 )";
118
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
122
123 Args:
124  cell_type: Type of cell
125
126 Returns:
127  The normals. Shape is (nfacets, gdim)
128 )";
129
130 const std::string cell_facet_reference_volumes = R"(
131 Get the reference volumes of the facets of a reference cell
132
133 Args:
134  cell_type: Type of cell
135
136 Returns:
137  The volumes of the references associated with each facet
138 )";
139
140 const std::string cell_facet_outward_normals = R"(
141 Get the (outward) normals to the facets of a reference cell
142
143 Args:
144  cell_type: Type of cell
145
146 Returns:
147  The outward normals. Shape is (nfacets, gdim)
148 )";
149
150 const std::string cell_facet_orientations = R"(
151 Get an array of bools indicating whether or not the facet normals are
152 outward pointing
153
154 Args:
155  cell_type: Type of cell
156
157 Returns:
158  The orientations
159 )";
160
161 const std::string cell_facet_jacobians = R"(
162 Get the jacobians of the facets of a reference cell
163
164 Args:
165  cell_type: Type of cell
166
167 Returns:
168  The jacobians of the facets. Shape is (nfacets, gdim, gdim - 1)
169 )";
170
171 const std::string FiniteElement__tabulate = R"(
172 @brief Compute basis values and derivatives at set of points.
173
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
177
178 Args:
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).
181
182 Returns:
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.
194 )";
195
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.
200
201 Args:
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].
206
207 Returns:
208  The function values on the cell. The indices are [Jacobian
209  index, point index, components].
210 )";
211
212 const std::string FiniteElement__pull_back = R"(
213 Map function values from a physical cell to the reference
214
215 Args:
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
220
221 Returns:
222  The function values on the reference. The indices are
223  [Jacobian index, point index, components].
224 )";
225
226 const std::string FiniteElement__apply_dof_transformation = R"(
227 Apply DOF transformations to some data
228
229 NOTE: This function is designed to be called at runtime, so its
230 performance is critical.
231
232 Args:
233  data: The data
234  block_size: The number of data points per DOF
235  cell_info: The permutation info for the cell
236
237 Returns:
238  data: The data
239 )";
240
241 const std::string FiniteElement__apply_dof_transformation_to_transpose = R"(
242 Apply DOF transformations to some transposed data
243
244 NOTE: This function is designed to be called at runtime, so its
245 performance is critical.
246
247 Args:
248  data: The data
249  block_size: The number of data points per DOF
250  cell_info: The permutation info for the cell
251
252 Returns:
253  data: The data
254 )";
255
256 const std::string FiniteElement__apply_inverse_transpose_dof_transformation
257  = R"(
258 Apply inverse transpose DOF transformations to some data
259
260 NOTE: This function is designed to be called at runtime, so its
261 performance is critical.
262
263 Args:
264  data: The data
265  block_size: The number of data points per DOF
266  cell_info: The permutation info for the cell
267
268 Returns:
269  data: The data
270 )";
271
272 const std::string FiniteElement__base_transformations = R"(
273 @brief Get the base transformations.
274
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, ...
281
282 *Example: Order 3 Lagrange on a triangle*
283
284 This space has 10 dofs arranged like:
285
286 .. code-block::
287
288  2
289  |\
290  6 4
291  | \
292  5 9 3
293  | \
294  0-7-8-1
295
296
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.
304
305 *Example: Order 1 Raviart-Thomas on a triangle*
306
307 This space has 3 dofs arranged like:
308
309 .. code-block::
310
311  |\
312  | \
313  | \
314  <-1 0
315  | / \
316  | L ^ \
317  | | \
318  ---2---
319
320
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:
324
325 .. code-block::
326
327  0: [[-1, 0, 0],
328  [ 0, 1, 0],
329  [ 0, 0, 1]]
330  1: [[1, 0, 0],
331  [0, -1, 0],
332  [0, 0, 1]]
333  2: [[1, 0, 0],
334  [0, 1, 0],
335  [0, 0, -1]]
336
337
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).
341
342 *Example: DOFs on the face of Order 2 Nedelec first kind on a tetrahedron*
343
344 On a face of this tetrahedron, this space has two face tangent DOFs:
345
346 .. code-block::
347
348  |\ |\
349  | \ | \
350  | \ | ^\
351  | \ | | \
352  | 0->\ | 1 \
353  | \ | \
354  ------ ------
355
356
357 For these DOFs, the subblocks of the base transformation matrices are:
358
359 .. code-block::
360
361  rotation: [[-1, 1],
362  [ 1, 0]]
363  reflection: [[0, 1],
364  [1, 0]]
365
366
367
368 Returns:
369  The base transformations for this element. The shape is
370  (ntranformations, ndofs, ndofs)
371 )";
372
373 const std::string FiniteElement__entity_transformations = R"(
374 Return the entity dof transformation matrices
375
376 Returns:
377  The base transformations for this element. The shape is
378  (ntranformations, ndofs, ndofs)
379 )";
380
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.
384
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
391 element.
392
393 Returns:
394  The tensor product representation
395 )";
396
397 const std::string create_custom_element = R"(
398 Create a custom finite element
399
400 Args:
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  discontinuous: Indicates whether or not this is the discontinuous version of the element
409  highest_complete_degree: The highest degree n such that a Lagrange (or vector Lagrange) element of degree n is a subspace of this element
410  highest_degree: The degree of a polynomial in this element's polyset
411
412 Returns:
413  A custom finite element
414 )";
415
416 const std::string create_element__family_cell_degree_discontinuous = R"(
417 Create an element
418
419 Args:
420  family: The element family
421  cell: The reference cell type that the element is defined on
422  degree: The degree of the element
423  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.
424
425 Returns:
426  A finite element
427 )";
428
429 const std::string create_element__family_cell_degree_lvariant_discontinuous
430  = R"(
431 Create an element using a given Lagrange variant
432
433 Args:
434  family: The element family
435  cell: The reference cell type that the element is defined on
436  degree: The degree of the element
437  lvariant: The variant of Lagrange to use
438  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.
439
440 Returns:
441  A finite element
442 )";
443
444 const std::string create_element__family_cell_degree_lvariant = R"(
445 Create a continuous element using a given Lagrange variant
446
447 Args:
448  family: The element family
449  cell: The reference cell type that the element is defined on
450  degree: The degree of the element
451  lvariant: The variant of Lagrange to use
452
453 Returns:
454  A finite element
455 )";
456
457 const std::string create_element__family_cell_degree_dvariant_discontinuous
458  = R"(
459 Create an element using a given DPC variant
460
461 Args:
462  family: The element family
463  cell: The reference cell type that the element is defined on
464  degree: The degree of the element
465  dvariant: The variant of DPC to use
466  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.
467
468 Returns:
469  A finite element
470 )";
471
472 const std::string
473  create_element__family_cell_degree_lvariant_dvariant_discontinuous
474  = R"(
475 Create an element using a given Lagrange variant and a given DPC variant
476
477 Args:
478  family: The element family
479  cell: The reference cell type that the element is defined on
480  degree: The degree of the element
481  lvariant: The variant of Lagrange to use
482  dvariant: The variant of DPC to use
483  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.
484
485 Returns:
486  A finite element
487 )";
488
489 const std::string create_element__family_cell_degree_dvariant = R"(
490 Create a continuous element using a given DPC variant
491
492 Args:
493  family: The element family
494  cell: The reference cell type that the element is defined on
495  degree: The degree of the element
496  dvariant: The variant of DPC to use
497
498 Returns:
499  A finite element
500 )";
501
502 const std::string create_element__family_cell_degree_lvariant_dvariant = R"(
503 Create a continuous element using a given Lagrange variant and a given DPC
504 variant
505
506 Args:
507  family: The element family
508  cell: The reference cell type that the element is defined on
509  degree: The degree of the element
510  lvariant: The variant of Lagrange to use
511  dvariant: The variant of DPC to use
512
513 Returns:
514  A finite element
515 )";
516
517 const std::string create_element__family_cell_degree = R"(
518 Create a continuous element
519
520 Args:
521  family: The element family
522  cell: The reference cell type that the element is defined on
523  degree: The degree of the element
524
525 Returns:
526  A finite element
527 )";
528
529 const std::string compute_interpolation_operator = R"(
530 Computes a matrix that represents the interpolation between two
531 elements.
532
533 If the two elements have the same value size, this function returns
534 the interpolation between them.
535
536 If element_from has value size 1 and element_to has value size > 1, then
537 this function returns a matrix to interpolate from a blocked element_from
538 (ie multiple copies of element_from) into element_to.
539
540 If element_to has value size 1 and element_from has value size > 1, then
541 this function returns a matrix that interpolates the components of
542 element_from into copies of element_to.
543
544 NOTE: If the elements have different value sizes and both are
545 greater than 1, this function throws a runtime error
546
547 In order to interpolate functions between finite element spaces on arbitrary
548 cells, the functions must be pulled back to the reference element (this pull
549 back includes applying DOF transformations). The matrix that this function
550 returns can then be applied, then the result pushed forward to the cell. If
551 element_from and element_to have the same map type, then only the DOF
552 transformations need to be applied, as the pull back and push forward cancel
553 each other out.
554
555 Args:
556  element_from: The element to interpolate from
557  element_to: The element to interpolate to
558
559 Returns:
560  Matrix operator that maps the 'from' degrees-of-freedom to
561  the 'to' degrees-of-freedom. Shape is (ndofs(element_to),
562  ndofs(element_from))
563 )";
564
565 const std::string tabulate_polynomial_set = R"(
566 @brief Tabulate the orthonormal polynomial basis, and derivatives,
567 at points on the reference cell.
568
569 All derivatives up to the given order are computed. If derivatives
570 are not required, use n = 0. For example, order n = 2 for a 2D
571 cell, will compute the basis \f$\psi, d\psi/dx, d\psi/dy, d^2 572 \psi/dx^2, d^2\psi/dxdy, d^2\psi/dy^2\f$ in that order (0, 0), (1,
573 0), (0, 1), (2, 0), (1, 1), (0 ,2).
574
575 For an interval cell there are nderiv + 1 derivatives, for a 2D
576 cell, there are (nderiv + 1)(nderiv + 2)/2 derivatives, and in 3D,
577 there are (nderiv + 1)(nderiv + 2)(nderiv + 3)/6. The ordering is
578 'triangular' with the lower derivatives appearing first.
579
580 Args:
581  celltype: Cell type
582  d: Polynomial degree
583  n: Maximum derivative order. Use n = 0 for the basis only.
584  x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
585
586 Returns:
587  Polynomial sets, for each derivative, tabulated at points.
588  The shape is (number of derivatives computed, number of points,
589  basis index).
590
591  - The first index is the derivative. The first entry is the basis
592  itself. Derivatives are stored in triangular (2D) or tetrahedral
593  (3D) ordering, eg if (p, q) denotes p order dervative with
594  repsect to x and q order derivative with respect to y, [0] ->
595  (0, 0), [1] -> (1, 0), [2] -> (0, 1), [3] -> (2, 0), [4] -> (1, 1),
596  [5] -> (0, 2), [6] -> (3, 0),...
597  The function basix::indexing::idx maps tuples (p, q, r) to the array
598  index.
599
600  - The second index is the point, with index i correspondign to the
601  point in row i of @p x.
602
603  - The third index is the basis function index.
604  TODO: Does the order for the third index need to be documented?
605 )";
606
607 const std::string tabulate_polynomials = R"(
608 @brief Tabulate a set of polynomials.
609
610 Args:
611  polytype: Polynomial type
612  celltype: Cell type
613  d: Polynomial degree
614  x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
615
616 Returns:
617  Polynomial sets, for each derivative, tabulated at points.
618  The shape is (basis index, number of points).
619 )";
620
621 const std::string polynomials_dim = R"(
622 @brief Dimension of a polynomial space.
623
624 Args:
625  polytype: The polynomial type
626  cell: The cell type
627  d: The polynomial degree
628
629 Returns:
630  The number terms in the basis spanning a space of
631  polynomial degree @p d
632 )";
633
634 const std::string make_quadrature__rule_celltype_m = R"(
635 Make a quadrature rule on a reference cell
636
637 Args:
638  rule: Type of quadrature rule (or use quadrature::Default)
639  celltype: The cell type
640  m: Maximum degree of polynomial that this quadrature rule will integrate exactly
641
642 Returns:
643  List of points and list of weights. The number of points
644  arrays has shape (num points, gdim)
645 )";
646
647 const std::string make_quadrature__celltype_m = R"(
648 Make a default quadrature rule on reference cell
649
650 Args:
651  celltype: The cell type
652  m: Maximum degree of polynomial that this quadrature rule will integrate exactly
653
654 Returns:
655  List of points and list of weights. The number of points
656  arrays has shape (num points, gdim)
657 )";
658
659 const std::string index__p = R"(
660 Compute trivial indexing in a 1D array (for completeness)
661
662 Args:
663  p: Index in x
664
665 Returns:
666  1D Index
667 )";
668
669 const std::string index__p_q = R"(
670 Compute indexing in a 2D triangular array compressed into a 1D array.
671 This can be used to find the index of a derivative returned by
672 FiniteElement::tabulate. For instance to find d2N/dx2, use
673 FiniteElement::tabulate(2, points)[idx(2, 0)];
674
675 Args:
676  p: Index in x
677  q: Index in y
678
679 Returns:
680  1D Index
681 )";
682
683 const std::string index__p_q_r = R"(
684 Compute indexing in a 3D tetrahedral array compressed into a 1D array
685
686 Args:
687  p: Index in x
688  q: Index in y
689  r: Index in z
690
691 Returns:
692  1D Index
693 )";
694
695
696
697 } // namespace basix::docstring
basix::create_custom_element
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, bool discontinuous, int highest_complete_degree, int highest_degree)
Definition: finite-element.cpp:464
basix::compute_interpolation_operator
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