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

# Basix 0.7.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 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 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 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 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  poly_type: The type of polyset to use for this element
413
414 Returns:
415  A custom finite element
416 )";
417
418 const std::string
419  create_element__family_cell_degree_lvariant_dvariant_discontinuous_dof_ordering
420  = R"(
421 Create an element using a given Lagrange variant and a given DPC variant
422
423 Args:
424  family: The element family
425  cell: The reference cell type that the element is defined on
426  degree: The degree of the element
427  lvariant: The variant of Lagrange to use
428  dvariant: The variant of DPC to use
429  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  dof_ordering: Ordering of dofs for ElementDofLayout
431
432 Returns:
433  A finite element
434 )";
435
436 const std::string compute_interpolation_operator = R"(
437 Compute a matrix that represents the interpolation between
438 two elements.
439
440 If the two elements have the same value size, this function returns
441 the interpolation between them.
442
443 If element_from has value size 1 and element_to has value size > 1,
444 then this function returns a matrix to interpolate from a blocked
445 element_from (ie multiple copies of element_from) into element_to.
446
447 If element_to has value size 1 and element_from has value size > 1,
448 then this function returns a matrix that interpolates the components
449 of element_from into copies of element_to.
450
451 NOTE: If the elements have different value sizes and both are
452 greater than 1, this function throws a runtime error
453
454 In order to interpolate functions between finite element spaces on
455 arbitrary cells, the functions must be pulled back to the reference
456 element (this pull back includes applying DOF transformations). The
457 matrix that this function returns can then be applied, then the
458 result pushed forward to the cell. If element_from and element_to
459 have the same map type, then only the DOF transformations need to be
460 applied, as the pull back and push forward cancel each other out.
461
462 Args:
463  element_from: The element to interpolate from
464  element_to: The element to interpolate to
465
466 Returns:
467  Matrix operator that maps the 'from' degrees-of-freedom to
468  the 'to' degrees-of-freedom. Shape is (ndofs(element_to),
469  ndofs(element_from))
470 )";
471
472 const std::string tabulate_polynomial_set = R"(
473 Tabulate the orthonormal polynomial basis, and derivatives,
474 at points on the reference cell.
475
476 All derivatives up to the given order are computed. If derivatives
477 are not required, use n = 0. For example, order n = 2 for a 2D
478 cell, will compute the basis \f$\psi, d\psi/dx, d\psi/dy, d^2 479 \psi/dx^2, d^2\psi/dxdy, d^2\psi/dy^2\f$ in that order (0, 0), (1,
480 0), (0, 1), (2, 0), (1, 1), (0 ,2).
481
482 For an interval cell there are nderiv + 1 derivatives, for a 2D
483 cell, there are (nderiv + 1)(nderiv + 2)/2 derivatives, and in 3D,
484 there are (nderiv + 1)(nderiv + 2)(nderiv + 3)/6. The ordering is
485 'triangular' with the lower derivatives appearing first.
486
487 Args:
488  celltype: Cell type
489  ptype: The polynomial type
490  d: Polynomial degree
491  n: Maximum derivative order. Use n = 0 for the basis only.
492  x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
493
494 Returns:
495  Polynomial sets, for each derivative, tabulated at points.
496  The shape is (number of derivatives computed, number of points,
497  basis index).
498
499  - The first index is the derivative. The first entry is the basis
500  itself. Derivatives are stored in triangular (2D) or tetrahedral
501  (3D) ordering, eg if (p, q) denotes p order derivative with
502  respect to x and q order derivative with respect to y, [0] ->
503  (0, 0), [1] -> (1, 0), [2] -> (0, 1), [3] -> (2, 0), [4] -> (1, 1),
504  [5] -> (0, 2), [6] -> (3, 0),...
505  The function basix::indexing::idx maps tuples (p, q, r) to the
506  array index.
507
508  - The second index is the point, with index i corresponding to the
509  point in row i of @p x.
510
511  - The third index is the basis function index.
512  TODO: Does the order for the third index need to be documented?
513 )";
514
515 const std::string tabulate_polynomials = R"(
516 Tabulate a set of polynomials.
517
518 Args:
519  polytype: Polynomial type
520  celltype: Cell type
521  d: Polynomial degree
522  x: Points at which to evaluate the basis. The shape is (number of points, geometric dimension).
523
524 Returns:
525  Polynomial sets, for each derivative, tabulated at points.
526  The shape is (basis index, number of points).
527 )";
528
529 const std::string polynomials_dim = R"(
530 Dimension of a polynomial space.
531
532 Args:
533  polytype: The polynomial type
534  cell: The cell type
535  d: The polynomial degree
536
537 Returns:
538  The number terms in the basis spanning a space of
539  polynomial degree @p d
540 )";
541
542 const std::string make_quadrature__rule_celltype_polytype_m = R"(
543 Make a quadrature rule on a reference cell
544
545 Args:
547  celltype: The cell type
548  polytype: The polyset type
549  m: Maximum degree of polynomial that this quadrature rule will integrate exactly
550
551 Returns:
552  List of points and list of weights. The number of points
553  arrays has shape (num points, gdim)
554 )";
555
556 const std::string index__p = R"(
557 Compute trivial indexing in a 1D array (for completeness)
558
559 Args:
560  p: Index in x
561
562 Returns:
563  1D Index
564 )";
565
566 const std::string index__p_q = R"(
567 Compute indexing in a 2D triangular array compressed into a 1D
568 array. This can be used to find the index of a derivative returned
569 by FiniteElement::tabulate. For instance to find d2N/dx2, use
570 FiniteElement::tabulate(2, points)[idx(2, 0)];
571
572 Args:
573  p: Index in x
574  q: Index in y
575
576 Returns:
577  1D Index
578 )";
579
580 const std::string index__p_q_r = R"(
581 Compute indexing in a 3D tetrahedral array compressed into a 1D
582 array
583
584 Args:
585  p: Index in x
586  q: Index in y
587  r: Index in z
588
589 Returns:
590  1D Index
591 )";
592
593 const std::string space_intersection = R"(
594 Get the intersection of two Sobolev spaces.
595
596 Args:
597  space1: First space
598  space2: Second space
599
600 Returns:
601  Intersection of the spaces
602 )";
603
604 const std::string superset = R"(
605 Get the polyset types that is a superset of two types on the given
606 cell
607
608 Args:
609  cell: The cell type
610  type1: The first polyset type
611  type2: The second polyset type
612
613 Returns::
614  The superset type
615 )";
616
617 const std::string restriction = R"(
618 Get the polyset type that represents the restrictions of a type on a
619 subentity
620
621 Args:
622  ptype: The polyset type
623  cell: The cell type
624  restriction_cell: The cell type of the subentity
625
626 Returns::
627  The restricted polyset type
628 )";
629
630 } // namespace basix::docstring
FiniteElement< T > create_custom_element(cell::type cell_type, const std::vector< std::size_t > &value_shape, impl::mdspan_t< const T, 2 > wcoeffs, const std::array< std::vector< impl::mdspan_t< const T, 2 >>, 4 > &x, const std::array< std::vector< impl::mdspan_t< const T, 4 >>, 4 > &M, int interpolation_nderivs, maps::type map_type, sobolev::space sobolev_space, bool discontinuous, int highest_complete_degree, int highest_degree, polyset::type poly_type)
Definition: finite-element.cpp:418
std::pair< std::vector< T >, std::array< std::size_t, 2 > > compute_interpolation_operator(const FiniteElement< T > &element_from, const FiniteElement< T > &element_to)
Compute a matrix that represents the interpolation between two elements.
Definition: interpolation.cpp:21