Basix
Loading...
Searching...
No Matches
docs.h
1#include <string>
2
3namespace basix::docstring
4{
5
6const std::string topology = R"(
7Cell topology
8
9Args:
10 celltype: Cell Type
11
12Returns::
13 List of topology (vertex indices) for each dimension (0..tdim)
14)";
15
16const std::string geometry = R"(
17Cell geometry
18
19Args:
20 celltype: Cell Type
21
22Returns::
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
28const std::string sub_entity_connectivity = R"(
29Get the numbers of entities connected to each subentity of the cell.
30
31Returns a vector of the form: output[dim][entity_n][connected_dim] =
32[connected_entity_n0, connected_entity_n1, ...] This indicates that
33the entity of dimension `dim` and number `entity_n` is connected to
34the entities of dimension `connected_dim` and numbers
35`connected_entity_n0`, `connected_entity_n1`, ...
36
37Args:
38 celltype: Cell Type
39
40Returns:
41 List of topology (vertex indices) for each dimension (0..tdim)
42)";
43
44const std::string sub_entity_geometry = R"(
45Sub-entity of a cell, given by topological dimension and index
46
47Args:
48 celltype: The cell::type
49 dim: Dimension of sub-entity
50 index: Local index of sub-entity
51
52Returns:
53 Set of vertex points of the sub-entity. Shape is (npoints, gdim)
54)";
55
56const std::string create_lattice__celltype_n_type_exterior = R"(
57Create a lattice of points on a reference cell optionally
58including the outer surface points.
59
60For a given `celltype`, this creates a set of points on a regular
61grid which covers the cell, eg for a quadrilateral, with n=2, the
62points 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,
64the points lying on the external boundary are omitted, in this case
65for a quadrilateral with `n == 2`, the points are: `[0.5, 0.5]`. The
66lattice type can be chosen as type::equispaced or type::gll. The
67type::gll lattice has points spaced along each edge at the
68Gauss-Lobatto-Legendre quadrature points. These are the same as
69type::equispaced when `n < 3`.
70
71Args:
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
77Returns:
78 Set of points. Shape is `(npoints, tdim)` and storage is
79 row-major
80)";
81
82const std::string create_lattice__celltype_n_type_exterior_method = R"(
83Create a lattice of points on a reference cell optionally
84including the outer surface points.
85
86For a given `celltype`, this creates a set of points on a regular
87grid which covers the cell, eg for a quadrilateral, with n=2, the
88points 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,
90the points lying on the external boundary are omitted, in this case
91for a quadrilateral with `n == 2`, the points are: `[0.5, 0.5]`. The
92lattice type can be chosen as type::equispaced or type::gll. The
93type::gll lattice has points spaced along each edge at the
94Gauss-Lobatto-Legendre quadrature points. These are the same as
95type::equispaced when `n < 3`.
96
97Args:
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
104Returns:
105 Set of points. Shape is `(npoints, tdim)` and storage is
106 row-major
107)";
108
109const std::string cell_volume = R"(
110Get the volume of a reference cell
111
112Args:
113 cell_type: Type of cell
114
115Returns:
116 The volume of the cell
117)";
118
119const std::string cell_facet_normals = R"(
120Get the normals to the facets of a reference cell oriented using the
121low-to-high ordering of the facet
122
123Args:
124 cell_type: Type of cell
125
126Returns:
127 The normals. Shape is (nfacets, gdim)
128)";
129
130const std::string cell_facet_reference_volumes = R"(
131Get the reference volumes of the facets of a reference cell
132
133Args:
134 cell_type: Type of cell
135
136Returns:
137 The volumes of the references associated with each facet
138)";
139
140const std::string cell_facet_outward_normals = R"(
141Get the (outward) normals to the facets of a reference cell
142
143Args:
144 cell_type: Type of cell
145
146Returns:
147 The outward normals. Shape is (nfacets, gdim)
148)";
149
150const std::string cell_facet_orientations = R"(
151Get an array of bools indicating whether or not the facet normals are
152outward pointing
153
154Args:
155 cell_type: Type of cell
156
157Returns:
158 The orientations
159)";
160
161const std::string cell_facet_jacobians = R"(
162Get the jacobians of the facets of a reference cell
163
164Args:
165 cell_type: Type of cell
166
167Returns:
168 The jacobians of the facets. Shape is (nfacets, gdim, gdim - 1)
169)";
170
171const std::string FiniteElement__tabulate = R"(
172Compute basis values and derivatives at set of points.
173
174NOTE: The version of `FiniteElement::tabulate` with the basis data
175as an out argument should be preferred for repeated call where
176performance is critical
177
178Args:
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
182Returns:
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
196const std::string FiniteElement__push_forward = R"(
197Map function values from the reference to a physical cell. This
198function can perform the mapping for multiple points, grouped by
199points that share a common Jacobian.
200
201Args:
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
207Returns:
208 The function values on the cell. The indices are [Jacobian
209 index, point index, components].
210)";
211
212const std::string FiniteElement__pull_back = R"(
213Map function values from a physical cell to the reference
214
215Args:
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
221Returns:
222 The function values on the reference. The indices are
223 [Jacobian index, point index, components].
224)";
225
226const std::string FiniteElement__apply_dof_transformation = R"(
227Apply DOF transformations to some data
228
229NOTE: This function is designed to be called at runtime, so its
230performance is critical.
231
232Args:
233 data: The data
234 block_size: The number of data points per DOF
235 cell_info: The permutation info for the cell
236
237Returns:
238 data: The data
239)";
240
241const std::string FiniteElement__apply_dof_transformation_to_transpose = R"(
242Apply DOF transformations to some transposed data
243
244NOTE: This function is designed to be called at runtime, so its
245performance is critical.
246
247Args:
248 data: The data
249 block_size: The number of data points per DOF
250 cell_info: The permutation info for the cell
251
252Returns:
253 data: The data
254)";
255
256const std::string FiniteElement__apply_inverse_transpose_dof_transformation
257 = R"(
258Apply inverse transpose DOF transformations to some data
259
260NOTE: This function is designed to be called at runtime, so its
261performance is critical.
262
263Args:
264 data: The data
265 block_size: The number of data points per DOF
266 cell_info: The permutation info for the cell
267
268Returns:
269 data: The data
270)";
271
272const std::string FiniteElement__base_transformations = R"(
273Get the base transformations.
274
275The base transformations represent the effect of rotating or reflecting
276a subentity of the cell on the numbering and orientation of the DOFs.
277This returns a list of matrices with one matrix for each subentity
278permutation in the following order:
279Reversing edge 0, reversing edge 1, ...
280Rotate face 0, reflect face 0, rotate face 1, reflect face 1, ...
281
282*Example: Order 3 Lagrange on a triangle*
283
284This 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
297For this element, the base transformations are:
298[Matrix swapping 3 and 4,
299Matrix swapping 5 and 6,
300Matrix swapping 7 and 8]
301The first row shows the effect of reversing the diagonal edge. The
302second row shows the effect of reversing the vertical edge. The third
303row shows the effect of reversing the horizontal edge.
304
305*Example: Order 1 Raviart-Thomas on a triangle*
306
307This 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
321These DOFs are integrals of normal components over the edges: DOFs 0 and 2
322are oriented inward, DOF 1 is oriented outwards.
323For 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
338The first matrix reverses DOF 0 (as this is on the first edge). The second
339matrix reverses DOF 1 (as this is on the second edge). The third matrix
340reverses 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
344On 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
357For 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
368Returns:
369 The base transformations for this element. The shape is
370 (ntranformations, ndofs, ndofs)
371)";
372
373const std::string FiniteElement__entity_transformations = R"(
374Return the entity dof transformation matrices
375
376Returns:
377 The base transformations for this element. The shape is
378 (ntranformations, ndofs, ndofs)
379)";
380
381const std::string FiniteElement__get_tensor_product_representation = R"(
382Get the tensor product representation of this element, or throw an
383error if no such factorisation exists.
384
385The tensor product representation will be a vector of tuples. Each
386tuple contains a vector of finite elements, and a vector of
387integers. The vector of finite elements gives the elements on an
388interval that appear in the tensor product representation. The
389vector of integers gives the permutation between the numbering of
390the tensor product DOFs and the number of the DOFs of this Basix
391element.
392
393Returns:
394 The tensor product representation
395)";
396
397const std::string create_custom_element = R"(
398Create a custom finite element
399
400Args:
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
414Returns:
415 A custom finite element
416)";
417
418const std::string
419 create_element__family_cell_degree_lvariant_dvariant_discontinuous_dof_ordering
420 = R"(
421Create an element using a given Lagrange variant and a given DPC variant
422
423Args:
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
432Returns:
433 A finite element
434)";
435
436const std::string compute_interpolation_operator = R"(
437Compute a matrix that represents the interpolation between
438two elements.
439
440If the two elements have the same value size, this function returns
441the interpolation between them.
442
443If element_from has value size 1 and element_to has value size > 1,
444then this function returns a matrix to interpolate from a blocked
445element_from (ie multiple copies of element_from) into element_to.
446
447If element_to has value size 1 and element_from has value size > 1,
448then this function returns a matrix that interpolates the components
449of element_from into copies of element_to.
450
451NOTE: If the elements have different value sizes and both are
452greater than 1, this function throws a runtime error
453
454In order to interpolate functions between finite element spaces on
455arbitrary cells, the functions must be pulled back to the reference
456element (this pull back includes applying DOF transformations). The
457matrix that this function returns can then be applied, then the
458result pushed forward to the cell. If element_from and element_to
459have the same map type, then only the DOF transformations need to be
460applied, as the pull back and push forward cancel each other out.
461
462Args:
463 element_from: The element to interpolate from
464 element_to: The element to interpolate to
465
466Returns:
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
472const std::string tabulate_polynomial_set = R"(
473Tabulate the orthonormal polynomial basis, and derivatives,
474at points on the reference cell.
475
476All derivatives up to the given order are computed. If derivatives
477are not required, use `n = 0`. For example, order `n = 2` for a 2D
478cell, 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,
4800), (0, 1), (2, 0), (1, 1), (0 ,2).
481
482For an interval cell there are `nderiv + 1` derivatives, for a 2D
483cell, there are `(nderiv + 1)(nderiv + 2)/2` derivatives, and in 3D,
484there are `(nderiv + 1)(nderiv + 2)(nderiv + 3)/6`. The ordering is
485'triangular' with the lower derivatives appearing first.
486
487Args:
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
494Returns:
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
515const std::string tabulate_polynomials = R"(
516Tabulate a set of polynomials.
517
518Args:
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
524Returns:
525 Polynomial sets, for each derivative, tabulated at points.
526 The shape is `(basis index, number of points)`.
527)";
528
529const std::string polynomials_dim = R"(
530Dimension of a polynomial space.
531
532Args:
533 polytype: The polynomial type
534 cell: The cell type
535 d: The polynomial degree
536
537Returns:
538 The number terms in the basis spanning a space of
539 polynomial degree @p d
540)";
541
542const std::string make_quadrature__rule_celltype_polytype_m = R"(
543Make a quadrature rule on a reference cell
544
545Args:
546 rule: Type of quadrature rule (or use quadrature::Default)
547 celltype: The cell type
548 polytype: The polyset type
549 m: Maximum degree of polynomial that this quadrature rule will integrate exactly
550
551Returns:
552 List of points and list of weights. The number of points
553 arrays has shape (num points, gdim)
554)";
555
556const std::string index__p = R"(
557Compute trivial indexing in a 1D array (for completeness)
558
559Args:
560 p: Index in x
561
562Returns:
563 1D Index
564)";
565
566const std::string index__p_q = R"(
567Compute indexing in a 2D triangular array compressed into a 1D
568array. This can be used to find the index of a derivative returned
569by `FiniteElement::tabulate`. For instance to find d2N/dx2, use
570`FiniteElement::tabulate(2, points)[idx(2, 0)];`
571
572Args:
573 p: Index in x
574 q: Index in y
575
576Returns:
577 1D Index
578)";
579
580const std::string index__p_q_r = R"(
581Compute indexing in a 3D tetrahedral array compressed into a 1D
582array
583
584Args:
585 p: Index in x
586 q: Index in y
587 r: Index in z
588
589Returns:
590 1D Index
591)";
592
593const std::string space_intersection = R"(
594Get the intersection of two Sobolev spaces.
595
596Args:
597 space1: First space
598 space2: Second space
599
600Returns:
601 Intersection of the spaces
602)";
603
604const std::string superset = R"(
605Get the polyset types that is a superset of two types on the given
606cell
607
608Args:
609 cell: The cell type
610 type1: The first polyset type
611 type2: The second polyset type
612
613Returns::
614 The superset type
615)";
616
617const std::string restriction = R"(
618Get the polyset type that represents the restrictions of a type on a
619subentity
620
621Args:
622 ptype: The polyset type
623 cell: The cell type
624 restriction_cell: The cell type of the subentity
625
626Returns::
627 The restricted polyset type
628)";
629
630} // namespace basix::docstring