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

# Basix 0.6.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  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
412
413 Returns:
414  A custom finite element
415 )";
416
417 const std::string create_element__family_cell_degree_discontinuous = R"(
418 Create an element
419
420 Args:
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.
425
426 Returns:
427  A finite element
428 )";
429
430 const std::string create_element__family_cell_degree_lvariant_discontinuous
431  = R"(
432 Create an element using a given Lagrange variant
433
434 Args:
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.
440
441 Returns:
442  A finite element
443 )";
444
445 const std::string create_element__family_cell_degree_lvariant = R"(
446 Create a continuous element using a given Lagrange variant
447
448 Args:
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
453
454 Returns:
455  A finite element
456 )";
457
458 const std::string create_element__family_cell_degree_dvariant_discontinuous
459  = R"(
460 Create an element using a given DPC variant
461
462 Args:
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.
468
469 Returns:
470  A finite element
471 )";
472
473 const std::string
474  create_element__family_cell_degree_lvariant_dvariant_discontinuous
475  = R"(
476 Create an element using a given Lagrange variant and a given DPC variant
477
478 Args:
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.
485
486 Returns:
487  A finite element
488 )";
489
490 const std::string create_element__family_cell_degree_dvariant = R"(
491 Create a continuous element using a given DPC variant
492
493 Args:
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
498
499 Returns:
500  A finite element
501 )";
502
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
505 variant
506
507 Args:
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
513
514 Returns:
515  A finite element
516 )";
517
518 const std::string create_element__family_cell_degree = R"(
519 Create a continuous element
520
521 Args:
522  family: The element family
523  cell: The reference cell type that the element is defined on
524  degree: The degree of the element
525
526 Returns:
527  A finite element
528 )";
529
530 const std::string compute_interpolation_operator = R"(
531 Computes a matrix that represents the interpolation between two
532 elements.
533
534 If the two elements have the same value size, this function returns
535 the interpolation between them.
536
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.
540
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.
544
545 NOTE: If the elements have different value sizes and both are
546 greater than 1, this function throws a runtime error
547
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
554 each other out.
555
556 Args:
557  element_from: The element to interpolate from
558  element_to: The element to interpolate to
559
560 Returns:
561  Matrix operator that maps the 'from' degrees-of-freedom to
562  the 'to' degrees-of-freedom. Shape is (ndofs(element_to),
563  ndofs(element_from))
564 )";
565
566 const std::string tabulate_polynomial_set = R"(
567 @brief Tabulate the orthonormal polynomial basis, and derivatives,
568 at points on the reference cell.
569
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).
575
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.
580
581 Args:
582  celltype: Cell type
583  d: Polynomial degree
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).
586
587 Returns:
588  Polynomial sets, for each derivative, tabulated at points.
589  The shape is (number of derivatives computed, number of points,
590  basis index).
591
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
599  index.
600
601  - The second index is the point, with index i correspondign to the
602  point in row i of @p x.
603
604  - The third index is the basis function index.
605  TODO: Does the order for the third index need to be documented?
606 )";
607
608 const std::string tabulate_polynomials = R"(
609 @brief Tabulate a set of polynomials.
610
611 Args:
612  polytype: Polynomial type
613  celltype: Cell type
614  d: Polynomial degree
615  x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
616
617 Returns:
618  Polynomial sets, for each derivative, tabulated at points.
619  The shape is (basis index, number of points).
620 )";
621
622 const std::string polynomials_dim = R"(
623 @brief Dimension of a polynomial space.
624
625 Args:
626  polytype: The polynomial type
627  cell: The cell type
628  d: The polynomial degree
629
630 Returns:
631  The number terms in the basis spanning a space of
632  polynomial degree @p d
633 )";
634
635 const std::string make_quadrature__rule_celltype_m = R"(
636 Make a quadrature rule on a reference cell
637
638 Args:
640  celltype: The cell type
641  m: Maximum degree of polynomial that this quadrature rule will integrate exactly
642
643 Returns:
644  List of points and list of weights. The number of points
645  arrays has shape (num points, gdim)
646 )";
647
648 const std::string make_quadrature__celltype_m = R"(
649 Make a default quadrature rule on reference cell
650
651 Args:
652  celltype: The cell type
653  m: Maximum degree of polynomial that this quadrature rule will integrate exactly
654
655 Returns:
656  List of points and list of weights. The number of points
657  arrays has shape (num points, gdim)
658 )";
659
660 const std::string index__p = R"(
661 Compute trivial indexing in a 1D array (for completeness)
662
663 Args:
664  p: Index in x
665
666 Returns:
667  1D Index
668 )";
669
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)];
675
676 Args:
677  p: Index in x
678  q: Index in y
679
680 Returns:
681  1D Index
682 )";
683
684 const std::string index__p_q_r = R"(
685 Compute indexing in a 3D tetrahedral array compressed into a 1D array
686
687 Args:
688  p: Index in x
689  q: Index in y
690  r: Index in z
691
692 Returns:
693  1D Index
694 )";
695
696 const std::string space_intersection = R"(
697 Get the intersection of two Sobolev spaces
698
699 Args:
700  space1: The first space
701  space2: The second space
702
703 Returns:
704  The intersection
705 )";
706
707 } // namespace basix::docstring
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