Debian Codegraph @

include/deal.II/fe/fe.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_fe_h
16 #define dealii_fe_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/fe/block_mask.h>
21 #include <deal.II/fe/component_mask.h>
22 #include <deal.II/fe/fe_data.h>
23 #include <deal.II/fe/fe_update_flags.h>
24 #include <deal.II/fe/fe_values_extractors.h>
25 #include <deal.II/fe/mapping.h>
26 #include <deal.II/fe/mapping_related_data.h>
27
28 #include <deal.II/lac/full_matrix.h>
29 #include <deal.II/lac/vector.h>
30
31 #include <memory>
32
33
34 DEAL_II_NAMESPACE_OPEN
35
36 // Forward declarations:
37 #ifndef DOXYGEN
38 template <int dim, int spacedim>
39 class FEValuesBase;
40 template <int dim, int spacedim>
41 class FEValues;
42 template <int dim, int spacedim>
43 class FEFaceValues;
44 template <int dim, int spacedim>
45 class FESubfaceValues;
46 namespace NonMatching
47 {
48 template <int dim>
49 class FEImmersedSurfaceValues;
50 }
51 template <int dim, int spacedim>
52 class FESystem;
53 #endif
54
55 /**
56 * This is the base class for finite elements in arbitrary dimensions. It
57 * declares the interface both in terms of member variables and public member
58 * functions through which properties of a concrete implementation of a finite
59 * element can be accessed. This interface generally consists of a number of
60 * groups of variables and functions that can roughly be delineated as
61 * follows:
62 * - Basic information about the finite element, such as the number of
63 * degrees of freedom per vertex, edge, or cell. This kind of data is stored
64 * in the FiniteElementData base class. (Though the FiniteElement::get_name()
65 * member function also falls into this category.)
66 * - A description of the shape functions and their derivatives on the
67 * reference cell $[0,1]^d$, if an element is indeed defined by mapping shape
68 * functions from the reference cell to an actual cell.
69 * - Matrices (and functions that access them) that describe how an
70 * element's shape functions related to those on parent or child cells
71 * (restriction or prolongation) or neighboring cells (for hanging node
72 * constraints), as well as to other finite element spaces defined on the same
73 * cell (e.g., when doing $p$ refinement).
74 * - %Functions that describe the properties of individual shape functions,
75 * for example which
76 * @ref GlossComponent "vector components"
77 * of a
78 * @ref vector_valued "vector-valued finite element's"
79 * shape function is nonzero, or whether an element is
80 * @ref GlossPrimitive "primitive".
81 * - For elements that are interpolatory, such as the common $Q_p$
82 * Lagrange elements, data that describes where their
83 * @ref GlossSupport "support points"
84 * are located.
85 * - %Functions that define the interface to the FEValues class that is
86 * almost always used to access finite element shape functions from user code.
87 *
88 * The following sections discuss many of these concepts in more detail, and
89 * outline strategies by which concrete implementations of a finite element
90 * can provide the details necessary for a complete description of a finite
91 * element space.
92 *
93 * As a general rule, there are three ways by which derived classes provide
94 * this information:
95 * - A number of fields that are generally easy to compute and that
96 * are initialized by the constructor of this class (or the constructor of the
97 * FiniteElementData base class) and derived classes therefore have to compute
98 * in the process of calling this class's constructor. This is, specifically,
99 * the case for the basic information and parts of the descriptive information
100 * about shape functions mentioned above.
101 * - Some common matrices that are widely used in the library and for
102 * which this class provides protected member variables that the constructors
103 * of derived classes need to fill. The purpose of providing these matrices in
104 * this class is that (i) they are frequently used, and (ii) they are
105 * expensive to compute. Consequently, it makes sense to only compute them
106 * once, rather than every time they are used. In most cases, the constructor
107 * of the current class already sets them to their correct size, and derived
108 * classes therefore only have to fill them. Examples of this include the
109 * matrices that relate the shape functions on one cell to the shape functions
110 * on neighbors, children, and parents.
111 * - Uncommon information, or information that depends on specific input
112 * arguments, and that needs to be implemented by derived classes. For these,
113 * this base class only declares abstract virtual member functions and derived
114 * classes then have to implement them. Examples of this category would
115 * include the functions that compute values and derivatives of shape
116 * functions on the reference cell for which it is not possible to tabulate
117 * values because there are infinitely many points at which one may want to
118 * evaluate them. In some cases, derived classes may choose to simply not
119 * implement <i>all</i> possible interfaces (or may not <i>yet</i> have a
120 * complete implementation); for uncommon functions, there is then often a
121 * member function derived classes can overload that describes whether a
122 * particular feature is implemented. An example is whether an element
123 * implements the information necessary to use it in the $hp$ finite element
124 * context (see
125 * @ref hp "hp-finite element support").
126 *
127 *
128 * <h3>Nomenclature</h3>
129 *
130 * Finite element classes have to define a large number of different
131 * properties describing a finite element space. The following subsections
132 * describe some nomenclature that will be used in the documentation below.
133 *
134 * <h4>Components and blocks</h4>
135 *
136 * @ref vector_valued "Vector-valued finite element"
137 * are elements used for systems of partial differential equations.
138 * Oftentimes, they are composed via the FESystem class (which is itself
139 * derived from the current class), but there are also non-composed elements
140 * that have multiple components (for example the FE_Nedelec and
141 * FE_RaviartThomas classes, among others). For any of these vector valued
142 * elements, individual shape functions may be nonzero in one or several
143 * @ref GlossComponent "components"
144 * of the vector valued function. If the element is
145 * @ref GlossPrimitive "primitive",
146 * there is indeed a single component with a nonzero entry for each shape
147 * function. This component can be determined using the
148 * FiniteElement::system_to_component_index() function.
149 *
150 * On the other hand, if there is at least one shape function that is nonzero
151 * in more than one vector component, then we call the entire element
152 * "non-primitive". The FiniteElement::get_nonzero_components() can then be used
153 * to determine which vector components of a shape function are nonzero. The
154 * number of nonzero components of a shape function is returned by
155 * FiniteElement::n_components(). Whether a shape function is non-primitive
156 * can be queried by FiniteElement::is_primitive().
157 *
158 * Oftentimes, one may want to split linear system into blocks so that they
159 * reflect the structure of the underlying operator. This is typically not
160 * done based on vector components, but based on the use of
161 * @ref GlossBlock "blocks",
162 * and the result is then used to substructure objects of type BlockVector,
163 * BlockSparseMatrix, and so on. If you use non-primitive
164 * elements, you cannot determine the block number by
165 * FiniteElement::system_to_component_index(). Instead, you can use
166 * FiniteElement::system_to_block_index(). The number of blocks of a finite
167 * element can be determined by FiniteElement::n_blocks().
168 *
169 * To better illustrate these concepts, let's consider the following
170 * example of the multi-component system
171 * @code
172 * FESystem<dim> fe_basis(FE_Q<dim>(2), dim, FE_Q<dim>(1),1);
173 * @endcode
174 * with <code>dim=2</code>. The resulting finite element has 3 components:
175 * two that come from the quadratic element and one from the linear element.
176 * If, for example, this system were used to discretize a problem in fluid
177 * dynamics then one could think of the first two components representing a
178 * vector-valued velocity field whereas the last one corresponds to the scalar
179 * pressure field. Without degree-of-freedom (DoF) renumbering this finite
180 * element will produce the following distribution of local DoFs:
181 *
182 * @image html fe_system_example.png DoF indices
183 *
184 * Using the two functions FiniteElement::system_to_component_index() and
185 * FiniteElement::system_to_base_index() one can get the
186 * following information for each degree-of-freedom "i":
187 * @code
188 * const unsigned int component =
189 * fe_basis.system_to_component_index(i).first;
190 * const unsigned int within_base =
191 * fe_basis.system_to_component_index(i).second;
192 * const unsigned int base =
193 * fe_basis.system_to_base_index(i).first.first;
194 * const unsigned int multiplicity =
195 * fe_basis.system_to_base_index(i).first.second;
196 * const unsigned int within_base_ =
197 * fe_basis.system_to_base_index(i).second; // same as above
198 * @endcode
199 * which will result in:
200 *
201 * | DoF | Component | Base element | Shape function within base | Multiplicity |
202 * | :----: | :--------: | :----------: | :------------------------: | :----------: |
203 * | 0 | 0 | 0 | 0 | 0 |
204 * | 1 | 1 | 0 | 0 | 1 |
205 * | 2 | 2 | 1 | 0 | 0 |
206 * | 3 | 0 | 0 | 1 | 0 |
207 * | 4 | 1 | 0 | 1 | 1 |
208 * | 5 | 2 | 1 | 1 | 0 |
209 * | 6 | 0 | 0 | 2 | 0 |
210 * | 7 | 1 | 0 | 2 | 1 |
211 * | 8 | 2 | 1 | 2 | 0 |
212 * | 9 | 0 | 0 | 3 | 0 |
213 * | 10 | 1 | 0 | 3 | 1 |
214 * | 11 | 2 | 1 | 3 | 0 |
215 * | 12 | 0 | 0 | 4 | 0 |
216 * | 13 | 1 | 0 | 4 | 1 |
217 * | 14 | 0 | 0 | 5 | 0 |
218 * | 15 | 1 | 0 | 5 | 1 |
219 * | 16 | 0 | 0 | 6 | 0 |
220 * | 17 | 1 | 0 | 6 | 1 |
221 * | 18 | 0 | 0 | 7 | 0 |
222 * | 19 | 1 | 0 | 7 | 1 |
223 * | 20 | 0 | 0 | 8 | 0 |
224 * | 21 | 1 | 0 | 8 | 1 |
225 *
226 * What we see is the following: there are a total of 22 degrees-of-freedom on
227 * this element with components ranging from 0 to 2. Each DoF corresponds to one
228 * of the two base elements used to build FESystem : $\mathbb Q_2$ or $\mathbb
229 * Q_1$. Since FE_Q are primitive elements, we have a total of 9 distinct
230 * scalar-valued shape functions for the quadratic element and 4 for the linear
231 * element. Finally, for DoFs corresponding to the first base element
232 * multiplicity is either zero or one, meaning that we use the same scalar
233 * valued $\mathbb Q_2$ for both $x$ and $y$ components of the velocity field
234 * $\mathbb Q_2 \otimes \mathbb Q_2$. For DoFs corresponding to the second base
235 * element multiplicity is zero.
236 *
237 * <h4>Support points</h4>
238 *
239 * Finite elements are frequently defined by defining a polynomial space and a
240 * set of dual functionals. If these functionals involve point evaluations,
241 * then the element is "interpolatory" and it is possible to interpolate an
242 * arbitrary (but sufficiently smooth) function onto the finite element space
243 * by evaluating it at these points. We call these points "support points".
244 *
245 * Most finite elements are defined by mapping from the reference cell to a
246 * concrete cell. Consequently, the support points are then defined on the
247 * reference ("unit") cell, see
248 * @ref GlossSupport "this glossary entry".
249 * The support points on a concrete cell can then be computed by mapping the
250 * unit support points, using the Mapping class interface and derived classes,
251 * typically via the FEValues class.
252 *
253 * A typical code snippet to do so would look as follows:
254 * @code
255 * Quadrature<dim> dummy_quadrature (fe.get_unit_support_points());
256 * FEValues<dim> fe_values (mapping, fe, dummy_quadrature,
257 * update_quadrature_points);
258 * fe_values.reinit (cell);
259 * Point<dim> mapped_point = fe_values.quadrature_point (i);
260 * @endcode
261 *
262 * Alternatively, the points can be transformed one-by-one:
263 * @code
264 * const vector<Point<dim> > &unit_points =
265 * fe.get_unit_support_points();
266 *
267 * Point<dim> mapped_point =
268 * mapping.transform_unit_to_real_cell (cell, unit_points[i]);
269 * @endcode
270 *
271 * @note Finite elements' implementation of the get_unit_support_points()
272 * function returns these points in the same order as shape functions. As a
273 * consequence, the quadrature points accessed above are also ordered in this
274 * way. The order of shape functions is typically documented in the class
275 * documentation of the various finite element classes.
276 *
277 *
278 * <h3>Implementing finite element spaces in derived classes</h3>
279 *
280 * The following sections provide some more guidance for implementing concrete
281 * finite element spaces in derived classes. This includes information that
282 * depends on the dimension for which you want to provide something, followed
283 * by a list of tools helping to generate information in concrete cases.
284 *
285 * It is important to note that there is a number of intermediate classes that
286 * can do a lot of what is necessary for a complete description of finite
287 * element spaces. For example, the FE_Poly, FE_PolyTensor, and FE_PolyFace
288 * classes in essence build a complete finite element space if you only
289 * provide them with an abstract description of the polynomial space upon
290 * which you want to build an element. Using these intermediate classes
291 * typically makes implementing finite element descriptions vastly simpler.
292 *
293 * As a general rule, if you want to implement an element, you will likely
294 * want to look at the implementation of other, similar elements first. Since
295 * many of the more complicated pieces of a finite element interface have to
296 * do with how they interact with mappings, quadrature, and the FEValues
297 * class, you will also want to read through the
298 * @ref FE_vs_Mapping_vs_FEValues
299 * documentation topic.
300 *
301 *
302 * <h4>Interpolation matrices in one dimension</h4>
303 *
304 * In one space dimension (i.e., for <code>dim==1</code> and any value of
305 * <code>spacedim</code>), finite element classes implementing the interface
306 * of the current base class need only set the #restriction and #prolongation
307 * matrices that describe the interpolation of the finite element space on one
308 * cell to that of its parent cell, and to that on its children, respectively.
309 * The constructor of the current class in one dimension presets the
310 * #interface_constraints matrix (used to describe hanging node constraints at
311 * the interface between cells of different refinement levels) to have size
312 * zero because there are no hanging nodes in 1d.
313 *
314 * <h4>Interpolation matrices in two dimensions</h4>
315 *
316 * In addition to the fields discussed above for 1d, a constraint matrix
317 * is needed to describe hanging node constraints if the finite element has
318 * degrees of freedom located on edges or vertices. These constraints are
319 * represented by an $m\times n$-matrix #interface_constraints, where <i>m</i>
320 * is the number of degrees of freedom on the refined side without the corner
321 * vertices (those dofs on the middle vertex plus those on the two lines), and
322 * <i>n</i> is that of the unrefined side (those dofs on the two vertices plus
323 * those on the line). The matrix is thus a rectangular one. The $m\times n$
324 * size of the #interface_constraints matrix can also be accessed through the
325 * interface_constraints_size() function.
326 *
327 * The mapping of the dofs onto the indices of the matrix on the unrefined
328 * side is as follows: let $d_v$ be the number of dofs on a vertex, $d_l$ that
329 * on a line, then $n=0...d_v-1$ refers to the dofs on vertex zero of the
330 * unrefined line, $n=d_v...2d_v-1$ to those on vertex one,
331 * $n=2d_v...2d_v+d_l-1$ to those on the line.
332 *
333 * Similarly, $m=0...d_v-1$ refers to the dofs on the middle vertex of the
334 * refined side (vertex one of child line zero, vertex zero of child line
335 * one), $m=d_v...d_v+d_l-1$ refers to the dofs on child line zero,
336 * $m=d_v+d_l...d_v+2d_l-1$ refers to the dofs on child line one. Please note
337 * that we do not need to reserve space for the dofs on the end vertices of
338 * the refined lines, since these must be mapped one-to-one to the appropriate
339 * dofs of the vertices of the unrefined line.
340 *
341 * Through this construction, the degrees of freedom on the child faces are
342 * constrained to the degrees of freedom on the parent face. The information
343 * so provided is typically consumed by the
344 * DoFTools::make_hanging_node_constraints() function.
345 *
346 * @note The hanging node constraints described by these matrices are only
347 * relevant to the case where the same finite element space is used on
348 * neighboring (but differently refined) cells. The case that the finite
349 * element spaces on different sides of a face are different, i.e., the $hp$
350 * case (see
351 * @ref hp "hp-finite element support")
352 * is handled by separate functions. See the
353 * FiniteElement::get_face_interpolation_matrix() and
354 * FiniteElement::get_subface_interpolation_matrix() functions.
355 *
356 *
357 * <h4>Interpolation matrices in three dimensions</h4>
358 *
359 * For the interface constraints, the 3d case is similar to the 2d case. The
360 * numbering for the indices $n$ on the parent face is obvious and keeps to
361 * the usual numbering of degrees of freedom on quadrilaterals.
362 *
363 * The numbering of the degrees of freedom on the interior of the refined
364 * faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above, and
365 * $d_q$ be the number of degrees of freedom per quadrilateral (and therefore
366 * per face), then $m=0...d_v-1$ denote the dofs on the vertex at the center,
367 * $m=d_v...5d_v-1$ for the dofs on the vertices at the center of the bounding
368 * lines of the quadrilateral, $m=5d_v..5d_v+4*d_l-1$ are for the degrees of
369 * freedom on the four lines connecting the center vertex to the outer
370 * boundary of the parent face, $m=5d_v+4*d_l...5d_v+4*d_l+8*d_l-1$ for the
371 * degrees of freedom on the small lines surrounding the quad, and
372 * $m=5d_v+12*d_l...5d_v+12*d_l+4*d_q-1$ for the dofs on the four child faces.
373 * Note the direction of the lines at the boundary of the quads, as shown
374 * below.
375 *
376 * The order of the twelve lines and the four child faces can be extracted
377 * from the following sketch, where the overall order of the different dof
378 * groups is depicted:
379 * @verbatim
380 * *--15--4--16--*
381 * | | |
382 * 10 19 6 20 12
383 * | | |
384 * 1--7---0--8---2
385 * | | |
386 * 9 17 5 18 11
387 * | | |
388 * *--13--3--14--*
389 * @endverbatim
390 * The numbering of vertices and lines, as well as the numbering of children
391 * within a line is consistent with the one described in Triangulation.
392 * Therefore, this numbering is seen from the outside and inside,
393 * respectively, depending on the face.
394 *
395 * The three-dimensional case has a few pitfalls available for derived classes
396 * that want to implement constraint matrices. Consider the following case:
397 * @verbatim
398 * *-------*
399 * / /|
400 * / / |
401 * / / |
402 * *-------* |
403 * | | *-------*
404 * | | / /|
405 * | 1 | / / |
406 * | |/ / |
407 * *-------*-------* |
408 * | | | *
409 * | | | /
410 * | 2 | 3 | /
411 * | | |/
412 * *-------*-------*
413 * @endverbatim
414 * Now assume that we want to refine cell 2. We will end up with two faces
415 * with hanging nodes, namely the faces between cells 1 and 2, as well as
416 * between cells 2 and 3. Constraints have to be applied to the degrees of
417 * freedom on both these faces. The problem is that there is now an edge (the
418 * top right one of cell 2) which is part of both faces. The hanging node(s)
419 * on this edge are therefore constrained twice, once from both faces. To be
420 * meaningful, these constraints of course have to be consistent: both faces
421 * have to constrain the hanging nodes on the edge to the same nodes on the
422 * coarse edge (and only on the edge, as there can then be no constraints to
423 * nodes on the rest of the face), and they have to do so with the same
424 * weights. This is sometimes tricky since the nodes on the edge may have
425 * different local numbers.
426 *
427 * For the constraint matrix this means the following: if a degree of
428 * freedom on one edge of a face is constrained by some other nodes on the same
429 * edge with some weights, then the weights have to be exactly the same as those
430 * for constrained nodes on the three other edges with respect to the
431 * corresponding nodes on these edges. If this isn't the case, you will get
432 * into trouble with the AffineConstraints class that is the primary consumer
433 * of the constraint information: while that class is able to handle
434 * constraints that are entered more than once (as is necessary for the case
435 * above), it insists that the weights are exactly the same.
436 *
437 * Using this scheme, child face degrees of freedom are constrained against
438 * parent face degrees of freedom that contain those on the edges of the
439 * parent face; it is possible that some of them are in turn constrained
440 * themselves, leading to longer chains of constraints that the
441 * AffineConstraints class will eventually have to sort out. (The constraints
442 * described above are used by the DoFTools::make_hanging_node_constraints()
443 * function that constructs an AffineConstraints object.) However, this is of no
444 * concern for the FiniteElement and derived classes since they only act
445 * locally on one cell and its immediate neighbor, and do not see the bigger
446 * picture. The
447 * @ref hp_paper
448 * details how such chains are handled in practice.
449 *
450 *
451 * <h4>Helper functions</h4>
452 *
453 * Construction of a finite element and computation of the matrices described
454 * above is often a tedious task, in particular if it has to be performed for
455 * several dimensions. Most of this work can be avoided by using the
456 * intermediate classes already mentioned above (e.g., FE_Poly, FE_PolyTensor,
457 * etc). Other tasks can be automated by some of the functions in namespace
458 * FETools.
459 *
460 * <h5>Computing the correct basis from a set of linearly independent
461 * functions</h5>
462 *
463 * First, it may already be difficult to compute the basis of shape functions
464 * for arbitrary order and dimension. On the other hand, if the
465 * @ref GlossNodes "node values"
466 * are given, then the duality relation between node functionals and basis
467 * functions defines the basis. As a result, the shape function space may be
468 * defined from a set of linearly independent functions, such that the actual
469 * finite element basis is computed from linear combinations of them. The
470 * coefficients of these combinations are determined by the duality of node
471 * values and form a matrix.
472 *
473 * Using this matrix allows the construction of the basis of shape functions
474 * in two steps.
475 * <ol>
476 *
477 * <li>Define the space of shape functions using an arbitrary basis
478 * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node functionals
479 * <i>N<sub>i</sub></i> applied to these basis functions, such that its
480 * entries are <i>m<sub>ij</sub> = N<sub>i</sub>(w<sub>j</sub>)</i>.
481 *
482 * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element shape
483 * function space by applying <i>M<sup>-1</sup></i> to the basis
484 * <i>w<sub>j</sub></i>.
485 * </ol>
486 *
487 * The matrix <i>M</i> may be computed with FETools::compute_node_matrix().
488 * This function relies on the existence of #generalized_support_points and
489 * FiniteElement::convert_generalized_support_point_values_to_dof_values()
490 * (see the
491 * @ref GlossGeneralizedSupport "glossary entry on generalized support points"
492 * for more information). With this, one can then use the
493 * following piece of code in the constructor of a class derived from
494 * FiniteElement to compute the $M$ matrix:
495 * @code
496 * FullMatrix<double> M(this->n_dofs_per_cell(), this->n_dofs_per_cell());
497 * FETools::compute_node_matrix(M, *this);
498 * this->inverse_node_matrix.reinit(this->n_dofs_per_cell(),
499 * this->n_dofs_per_cell()); this->inverse_node_matrix.invert(M);
500 * @endcode
501 * Don't forget to make sure
502 * that #unit_support_points or #generalized_support_points are initialized
503 * before this!
504 *
505 * <h5>Computing prolongation matrices</h5>
506 *
507 * Once you have shape functions, you can define matrices that transfer data
508 * from one cell to its children or the other way around. This is a common
509 * operation in multigrid, of course, but is also used when interpolating the
510 * solution from one mesh to another after mesh refinement, as well as in the
511 * definition of some error estimators.
512 *
513 * To define the prolongation matrices, i.e., those matrices that describe the
514 * transfer of a finite element field from one cell to its children,
515 * implementations of finite elements can either fill the #prolongation array
516 * by hand, or can call FETools::compute_embedding_matrices().
517 *
518 * In the latter case, all that is required is the following piece of code:
519 * @code
520 * for (unsigned int c=0; c<GeometryInfo<dim>::max_children_per_cell; ++c)
521 * this->prolongation[c].reinit (this->n_dofs_per_cell(),
522 * this->n_dofs_per_cell());
523 * FETools::compute_embedding_matrices (*this, this->prolongation);
524 * @endcode
525 * As in this example, prolongation is almost always implemented via
526 * embedding, i.e., the nodal values of the function on the children may be
527 * different from the nodal values of the function on the parent cell, but as
528 * a function of $\mathbf x\in{\mathbb R}^\text{spacedim}$, the finite element
529 * field on the child is the same as on the parent.
530 *
531 *
532 * <h5>Computing restriction matrices</h5>
533 *
534 * The opposite operation, restricting a finite element function defined on
535 * the children to the parent cell is typically implemented by interpolating
536 * the finite element function on the children to the nodal values of the
537 * parent cell. In deal.II, the restriction operation is implemented as a loop
538 * over the children of a cell that each apply a matrix to the vector of
539 * unknowns on that child cell (these matrices are stored in #restriction and
540 * are accessed by get_restriction_matrix()). The operation that then needs to
541 * be implemented turns out to be surprisingly difficult to describe, but is
542 * instructive to describe because it also defines the meaning of the
543 * #restriction_is_additive_flags array (accessed via the
544 * restriction_is_additive() function).
545 *
546 * To give a concrete example, assume we use a $Q_1$ element in 1d, and that
547 * on each of the parent and child cells degrees of freedom are (locally and
548 * globally) numbered as follows:
549 * @code
550 * meshes: *-------* *---*---*
551 * local DoF numbers: 0 1 0 1|0 1
552 * global DoF numbers: 0 1 0 1 2
553 * @endcode
554 * Then we want the restriction operation to take the value of the zeroth DoF
555 * on child 0 as the value of the zeroth DoF on the parent, and take the value
556 * of the first DoF on child 1 as the value of the first DoF on the parent.
557 * Ideally, we would like to write this follows
558 * @f[
559 * U^\text{coarse}|_\text{parent}
560 * = \sum_{\text{child}=0}^1 R_\text{child} U^\text{fine}|_\text{child}
561 * @f]
562 * where $U^\text{fine}|_\text{child=0}=(U^\text{fine}_0,U^\text{fine}_1)^T$
563 * and $U^\text{fine}|_\text{child=1}=(U^\text{fine}_1,U^\text{fine}_2)^T$.
564 * Writing the requested operation like this would here be possible by
565 * choosing
566 * @f[
567 * R_0 = \left(\begin{matrix}1 & 0 \\ 0 & 0\end{matrix}\right),
568 * \qquad\qquad
569 * R_1 = \left(\begin{matrix}0 & 0 \\ 0 & 1\end{matrix}\right).
570 * @f]
571 * However, this approach already fails if we go to a $Q_2$ element with the
572 * following degrees of freedom:
573 * @code
574 * meshes: *-------* *----*----*
575 * local DoF numbers: 0 2 1 0 2 1|0 2 1
576 * global DoF numbers: 0 2 1 0 2 1 4 3
577 * @endcode
578 * Writing things as the sum over matrix operations as above would not easily
579 * work because we have to add nonzero values to $U^\text{coarse}_2$ twice,
580 * once for each child.
581 *
582 * Consequently, restriction is typically implemented as a
583 * <i>concatenation</i> operation. I.e., we first compute the individual
584 * restrictions from each child,
585 * @f[
586 * \tilde U^\text{coarse}_\text{child}
587 * = R_\text{child} U^\text{fine}|_\text{child},
588 * @f]
589 * and then compute the values of $U^\text{coarse}|_\text{parent}$ with the
590 * following code:
591 * @code
592 * for (unsigned int child=0; child<cell->n_children(); ++child)
593 * for (unsigned int i=0; i<dofs_per_cell; ++i)
594 * if (U_tilde_coarse[child][i] != 0)
595 * U_coarse_on_parent[i] = U_tilde_coarse[child][i];
596 * @endcode
597 * In other words, each nonzero element of $\tilde
598 * U^\text{coarse}_\text{child}$ <i>overwrites</i>, rather than adds to the
599 * corresponding element of $U^\text{coarse}|_\text{parent}$. This typically
600 * also implies that the restriction matrices from two different cells should
601 * agree on a value for coarse degrees of freedom that they both want to touch
602 * (otherwise the result would depend on the order in which we loop over
603 * children, which would be unreasonable because the order of children is an
604 * otherwise arbitrary convention). For example, in the example above, the
605 * restriction matrices will be
606 * @f[
607 * R_0 = \left(\begin{matrix}1 & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 1 & 0
608 * \end{matrix}\right), \qquad\qquad R_1 = \left(\begin{matrix}0 & 0 & 0 \\ 0 &
609 * 1 & 0 \\ 1 & 0 & 0 \end{matrix}\right),
610 * @f]
611 * and the compatibility condition is the $R_{0,21}=R_{1,20}$ because they
612 * both indicate that $U^\text{coarse}|_\text{parent,2}$ should be set to one
613 * times $U^\text{fine}|_\text{child=0,1}$ and
614 * $U^\text{fine}|_\text{child=1,0}$.
615 *
616 * Unfortunately, not all finite elements allow to write the restriction
617 * operation in this way. For example, for the piecewise constant FE_DGQ(0)
618 * element, the value of the finite element field on the parent cell can not
619 * be determined by interpolation from the children. Rather, the only
620 * reasonable choice is to take it as the <i>average</i> value between the
621 * children -- so we are back to the sum operation, rather than the
622 * concatenation. Further thought shows that whether restriction should be
623 * additive or not is a property of the individual shape function, not of the
624 * finite element as a whole. Consequently, the
625 * FiniteElement::restriction_is_additive() function returns whether a
626 * particular shape function should act via concatenation (a return value of
627 * @p false) or via addition (return value of @p true), and the correct code
628 * for the overall operation is then as follows (and as, in fact, implemented
629 * in DoFAccessor::get_interpolated_dof_values()):
630 * @code
631 * for (unsigned int child=0; child<cell->n_children(); ++child)
632 * for (unsigned int i=0; i<dofs_per_cell; ++i)
633 * if (fe.restriction_is_additive(i) == true)
634 * U_coarse_on_parent[i] += U_tilde_coarse[child][i];
635 * else
636 * if (U_tilde_coarse[child][i] != 0)
637 * U_coarse_on_parent[i] = U_tilde_coarse[child][i];
638 * @endcode
639 *
640 *
641 * <h5>Computing #interface_constraints</h5>
642 *
643 * Constraint matrices can be computed semi-automatically using
644 * FETools::compute_face_embedding_matrices(). This function computes the
645 * representation of the coarse mesh functions by fine mesh functions for each
646 * child of a face separately. These matrices must be convoluted into a single
647 * rectangular constraint matrix, eliminating degrees of freedom on common
648 * vertices and edges as well as on the coarse grid vertices. See the
649 * discussion above for details of this numbering.
650 *
651 * @ingroup febase fe
652 */
653 template <int dim, int spacedim = dim>
654 class FiniteElement : public EnableObserverPointer,
655 public FiniteElementData<dim>
656 {
657 public:
658 /**
659 * The dimension of the image space, corresponding to Triangulation.
660 */
661 static constexpr unsigned int space_dimension = spacedim;
662
663 /**
664 * A base class for internal data that derived finite element classes may
665 * wish to store.
666 *
667 * The class is used as follows: Whenever an FEValues (or FEFaceValues or
668 * FESubfaceValues) object is initialized, it requests that the finite
669 * element it is associated with creates an object of a class derived from
670 * the current one here. This is done via each derived class's
671 * FiniteElement::get_data() function. This object is then passed to the
672 * FiniteElement::fill_fe_values(), FiniteElement::fill_fe_face_values(),
673 * and FiniteElement::fill_fe_subface_values() functions as a constant
674 * object. The intent of these objects is so that finite element classes can
675 * pre-compute information once at the beginning (in the call to
676 * FiniteElement::get_data() call) that can then be used on each cell that
677 * is subsequently visited. An example for this is the values of shape
678 * functions at the quadrature point of the reference cell, which remain the
679 * same no matter the cell visited, and that can therefore be computed once
680 * at the beginning and reused later on.
681 *
682 * Because only derived classes can know what they can pre-compute, each
683 * derived class that wants to store information computed once at the
684 * beginning, needs to derive its own InternalData class from this class,
685 * and return an object of the derived type through its get_data() function.
686 */
687 class InternalDataBase
688 {
689 public:
690 /**
691 * Constructor. Sets update_flags to @p update_default and @p first_cell
692 * to @p true.
693 */
694 InternalDataBase();
695
696 /**
697 * Destructor. Made virtual to allow polymorphism.
698 */
699 virtual ~InternalDataBase() = default;
700
701 /**
702 * Copy construction is forbidden.
703 */
704 InternalDataBase(const InternalDataBase &) = delete;
705
706 /**
707 * A set of update flags specifying the kind of information that an
708 * implementation of the FiniteElement interface needs to compute on each
709 * cell or face, i.e., in FiniteElement::fill_fe_values() and friends.
710 *
711 * This set of flags is stored here by implementations of
712 * FiniteElement::get_data(), FiniteElement::get_face_data(), or
713 * FiniteElement::get_subface_data(), and is that subset of the update
714 * flags passed to those functions that require re-computation on every
715 * cell. (The subset of the flags corresponding to information that can be
716 * computed once and for all already at the time of the call to
717 * FiniteElement::get_data() -- or an implementation of that interface --
718 * need not be stored here because it has already been taken care of.)
719 */
720 UpdateFlags update_each;
721
722 /**
723 * Return an estimate (in bytes) for the memory consumption of this object.
724 */
725 virtual std::size_t
726 memory_consumption() const;
727 };
728
729 public:
730 /**
731 * Constructor: initialize the fields of this base class of all finite
732 * elements.
733 *
734 * @param[in] fe_data An object that stores identifying (typically integral)
735 * information about the element to be constructed. In particular, this
736 * object will contain data such as the number of degrees of freedom per
737 * cell (and per vertex, line, etc), the number of vector components, etc.
738 * This argument is used to initialize the base class of the current object
739 * under construction.
740 * @param[in] restriction_is_additive_flags A vector of size
741 * <code>dofs_per_cell</code> (or of size one, see below) that for each
742 * shape function states whether the shape function is additive or not. The
743 * meaning of these flags is described in the section on restriction
744 * matrices in the general documentation of this class.
745 * @param[in] nonzero_components A vector of size <code>dofs_per_cell</code>
746 * (or of size one, see below) that for each shape function provides a
747 * ComponentMask (of size <code>fe_data.n_components()</code>) that
748 * indicates in which vector components this shape function is nonzero
749 * (after mapping the shape function to the real cell). For "primitive"
750 * shape functions, this component mask will have a single entry (see
751 * @ref GlossPrimitive
752 * for more information about primitive elements). On the other hand, for
753 * elements such as the Raviart-Thomas or Nedelec elements, shape functions
754 * are nonzero in more than one vector component (after mapping to the real
755 * cell) and the given component mask will contain more than one entry. (For
756 * these two elements, all entries will in fact be set, but this would not
757 * be the case if you couple a FE_RaviartThomas and a FE_Nedelec together
758 * into a FESystem.)
759 *
760 * @pre <code>restriction_is_additive_flags.size() == dofs_per_cell</code>,
761 * or <code>restriction_is_additive_flags.size() == 1</code>. In the latter
762 * case, the array is simply interpreted as having size
763 * <code>dofs_per_cell</code> where each element has the same value as the
764 * single element given.
765 *
766 * @pre <code>nonzero_components.size() == dofs_per_cell</code>, or
767 * <code>nonzero_components.size() == 1</code>. In the latter case, the
768 * array is simply interpreted as having size <code>dofs_per_cell</code>
769 * where each element equals the component mask provided in the single
770 * element given.
771 */
772 FiniteElement(const FiniteElementData<dim> &fe_data,
773 const std::vector<bool> &restriction_is_additive_flags,
774 const std::vector<ComponentMask> &nonzero_components);
775
776 /**
777 * Move constructor.
778 */
779 FiniteElement(FiniteElement<dim, spacedim> &&) = default; // NOLINT
780
781 /**
782 * Copy constructor.
783 */
784 FiniteElement(const FiniteElement<dim, spacedim> &) = default;
785
786 /**
787 * Virtual destructor. Makes sure that pointers to this class are deleted
788 * properly.
789 */
790 virtual ~FiniteElement() override = default;
791
792 /**
793 * Creates information for creating a FESystem with this class as
794 * base element and with multiplicity @p multiplicity. In particular,
795 * the return type of this function can be used in the constructor
796 * for a FESystem object.
797 * This function calls clone() and hence creates a copy of the
798 * current object.
799 */
800 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>
801 operator^(const unsigned int multiplicity) const;
802
803 /**
804 * A sort of virtual copy constructor, this function returns a copy of
805 * the finite element object. Derived classes need to override the function
806 * here in this base class and return an object of the same type as the
807 * derived class.
808 *
809 * Some places in the library, for
810 * example the constructors of FESystem as well as the hp::FECollection
811 * class, need to make copies of finite elements without knowing their exact
812 * type. They do so through this function.
813 */
814 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
815 clone() const = 0;
816
817 /**
818 * Return a string that uniquely identifies a finite element. The general
819 * convention is that this is the class name, followed by the dimension in
820 * angle brackets, and the polynomial degree and whatever else is necessary
821 * in parentheses. For example, <tt>FE_Q<2>(3)</tt> is the value returned
822 * for a cubic element in 2d.
823 *
824 * Systems of elements have their own naming convention, see the FESystem
825 * class.
826 */
827 virtual std::string
828 get_name() const = 0;
829
830 /**
831 * @name Shape function access
832 * @{
833 */
834
835 /**
836 * Return the value of the @p ith shape function at the point @p p. @p p is
837 * a point on the reference element. If the finite element is vector-valued,
838 * then return the value of the only non-zero component of the vector value
839 * of this shape function. If the shape function has more than one non-zero
840 * component (which we refer to with the term non-primitive), then derived
841 * classes implementing this function should throw an exception of type
842 * ExcShapeFunctionNotPrimitive. In that case, use the
843 * shape_value_component() function.
844 *
845 * Implementations of this function should throw an exception of type
846 * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
847 * under consideration depend on the shape of the cell in real space, i.e.,
848 * if the shape functions are not defined by mapping from the reference
849 * cell. Some non-conforming elements are defined this way, as is the
850 * FE_DGPNonparametric class, to name just one example.
851 *
852 * The default implementation of this virtual function does exactly this,
853 * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
854 */
855 virtual double
856 shape_value(const unsigned int i, const Point<dim> &p) const;
857
858 /**
859 * Just like for shape_value(), but this function will be called when the
860 * shape function has more than one non-zero vector component. In that case,
861 * this function should return the value of the @p component-th vector
862 * component of the @p ith shape function at point @p p.
863 */
864 virtual double
865 shape_value_component(const unsigned int i,
866 const Point<dim> &p,
867 const unsigned int component) const;
868
869 /**
870 * Return the gradient of the @p ith shape function at the point @p p. @p p
871 * is a point on the reference element, and likewise the gradient is the
872 * gradient on the unit cell with respect to unit cell coordinates. If the
873 * finite element is vector-valued, then return the value of the only
874 * non-zero component of the vector value of this shape function. If the shape
875 * function has more than one non-zero component (which we refer to with the
876 * term non-primitive), then derived classes implementing this function
877 * should throw an exception of type ExcShapeFunctionNotPrimitive. In that
878 * case, use the shape_grad_component() function.
879 *
880 * Implementations of this function should throw an exception of type
881 * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
882 * under consideration depend on the shape of the cell in real space, i.e.,
883 * if the shape functions are not defined by mapping from the reference
884 * cell. Some non-conforming elements are defined this way, as is the
885 * FE_DGPNonparametric class, to name just one example.
886 *
887 * The default implementation of this virtual function does exactly this,
888 * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
889 */
890 virtual Tensor<1, dim>
891 shape_grad(const unsigned int i, const Point<dim> &p) const;
892
893 /**
894 * Just like for shape_grad(), but this function will be called when the
895 * shape function has more than one non-zero vector component. In that case,
896 * this function should return the gradient of the @p component-th vector
897 * component of the @p ith shape function at point @p p.
898 */
899 virtual Tensor<1, dim>
900 shape_grad_component(const unsigned int i,
901 const Point<dim> &p,
902 const unsigned int component) const;
903
904 /**
905 * Return the tensor of second derivatives of the @p ith shape function at
906 * point @p p on the unit cell. The derivatives are derivatives on the unit
907 * cell with respect to unit cell coordinates. If the finite element is
908 * vector-valued, then return the value of the only non-zero component of
909 * the vector value of this shape function. If the shape function has more
910 * than one non-zero component (which we refer to with the term
911 * non-primitive), then derived classes implementing this function should
912 * throw an exception of type ExcShapeFunctionNotPrimitive. In that case, use
913 * the shape_grad_grad_component() function.
914 *
915 * Implementations of this function should throw an exception of type
916 * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
917 * under consideration depend on the shape of the cell in real space, i.e.,
918 * if the shape functions are not defined by mapping from the reference
919 * cell. Some non-conforming elements are defined this way, as is the
920 * FE_DGPNonparametric class, to name just one example.
921 *
922 * The default implementation of this virtual function does exactly this,
923 * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
924 */
925 virtual Tensor<2, dim>
926 shape_grad_grad(const unsigned int i, const Point<dim> &p) const;
927
928 /**
929 * Just like for shape_grad_grad(), but this function will be called when
930 * the shape function has more than one non-zero vector component. In that
931 * case, this function should return the gradient of the @p component-th
932 * vector component of the @p ith shape function at point @p p.
933 */
934 virtual Tensor<2, dim>
935 shape_grad_grad_component(const unsigned int i,
936 const Point<dim> &p,
937 const unsigned int component) const;
938
939 /**
940 * Return the tensor of third derivatives of the @p ith shape function at
941 * point @p p on the unit cell. The derivatives are derivatives on the unit
942 * cell with respect to unit cell coordinates. If the finite element is
943 * vector-valued, then return the value of the only non-zero component of
944 * the vector value of this shape function. If the shape function has more
945 * than one non-zero component (which we refer to with the term
946 * non-primitive), then derived classes implementing this function should
947 * throw an exception of type ExcShapeFunctionNotPrimitive. In that case, use
948 * the shape_3rd_derivative_component() function.
949 *
950 * Implementations of this function should throw an exception of type
951 * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
952 * under consideration depend on the shape of the cell in real space, i.e.,
953 * if the shape functions are not defined by mapping from the reference
954 * cell. Some non-conforming elements are defined this way, as is the
955 * FE_DGPNonparametric class, to name just one example.
956 *
957 * The default implementation of this virtual function does exactly this,
958 * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
959 */
960 virtual Tensor<3, dim>
961 shape_3rd_derivative(const unsigned int i, const Point<dim> &p) const;
962
963 /**
964 * Just like for shape_3rd_derivative(), but this function will be
965 * called when the shape function has more than one non-zero vector
966 * component. In that case, this function should return the gradient
967 * of the @p component-th vector component of the @p ith shape
968 * function at point @p p.
969 */
970 virtual Tensor<3, dim>
971 shape_3rd_derivative_component(const unsigned int i,
972 const Point<dim> &p,
973 const unsigned int component) const;
974
975 /**
976 * Return the tensor of fourth derivatives of the @p ith shape function at
977 * point @p p on the unit cell. The derivatives are derivatives on the unit
978 * cell with respect to unit cell coordinates. If the finite element is
979 * vector-valued, then return the value of the only non-zero component of
980 * the vector value of this shape function. If the shape function has more
981 * than one non-zero component (which we refer to with the term
982 * non-primitive), then derived classes implementing this function should
983 * throw an exception of type ExcShapeFunctionNotPrimitive. In that case, use
984 * the shape_4th_derivative_component() function.
985 *
986 * Implementations of this function should throw an exception of type
987 * ExcUnitShapeValuesDoNotExist if the shape functions of the FiniteElement
988 * under consideration depend on the shape of the cell in real space, i.e.,
989 * if the shape functions are not defined by mapping from the reference
990 * cell. Some non-conforming elements are defined this way, as is the
991 * FE_DGPNonparametric class, to name just one example.
992 *
993 * The default implementation of this virtual function does exactly this,
994 * i.e., it simply throws an exception of type ExcUnitShapeValuesDoNotExist.
995 */
996 virtual Tensor<4, dim>
997 shape_4th_derivative(const unsigned int i, const Point<dim> &p) const;
998
999 /**
1000 * Just like for shape_4th_derivative(), but this function will be called
1001 * when the shape function has more than one non-zero vector component. In
1002 * that case, this function should return the gradient of the
1003 * @p component-th vector component of the @p ith shape function at point
1004 * @p p.
1005 */
1006 virtual Tensor<4, dim>
1007 shape_4th_derivative_component(const unsigned int i,
1008 const Point<dim> &p,
1009 const unsigned int component) const;
1010 /**
1011 * This function returns @p true, if the shape function @p shape_index has
1012 * non-zero function values somewhere on the face @p face_index. The
1013 * function is typically used to determine whether some matrix elements
1014 * resulting from face integrals can be assumed to be zero and may therefore
1015 * be omitted from integration.
1016 *
1017 * A default implementation is provided in this base class which always
1018 * returns @p true. This is the safe way to go.
1019 */
1020 virtual bool
1021 has_support_on_face(const unsigned int shape_index,
1022 const unsigned int face_index) const;
1023
1024 /** @} */
1025 /**
1026 * @name Transfer and constraint matrices
1027 * @{
1028 */
1029
1030 /**
1031 * Return the matrix that describes restricting a finite element field from
1032 * the given @p child (as obtained by the given @p refinement_case) to the
1033 * parent cell. The interpretation of the returned matrix depends on what
1034 * restriction_is_additive() returns for each shape function.
1035 *
1036 * Row and column indices are related to coarse grid and fine grid spaces,
1037 * respectively, consistent with the definition of the associated operator.
1038 *
1039 * If projection matrices are not implemented in the derived finite element
1040 * class, this function aborts with an exception of type
1041 * FiniteElement::ExcProjectionVoid. You can check whether this would happen
1042 * by first calling the restriction_is_implemented() or the
1043 * isotropic_restriction_is_implemented() function.
1044 *
1045 * @note The term "restriction" is also used in the definition of multigrid
1046 * methods, but in a different context. For the current function, we are
1047 * interested in the interpolation of a finite element function from
1048 * child cells to the parent cell, and this results in a situation where
1049 * you have a function that is constant on a fine mesh, the function
1050 * "restricted" to the coarse mesh will also be constant and have the same
1051 * value. In contrast, in the multigrid context, the restriction operation
1052 * is applied to residual (rather than solution) vectors, and is usually
1053 * chosen as the transpose of the prolongation operation. For the multigrid
1054 * restriction operation, one would consequently not typically expect
1055 * that it maps a constant function to a constant function. In other words,
1056 * the *meaning* of the term "restriction" in the current context and in
1057 * the multigrid context is quite different, and the two should not
1058 * be confused.
1059 */
1060 virtual const FullMatrix<double> &
1061 get_restriction_matrix(const unsigned int child,
1062 const RefinementCase<dim> &refinement_case =
1063 RefinementCase<dim>::isotropic_refinement) const;
1064
1065 /**
1066 * Prolongation/embedding matrix between grids.
1067 *
1068 * The identity operator from a coarse grid space into a fine grid space
1069 * (where both spaces are identified as functions defined on the parent and
1070 * child cells) is associated with a matrix @p P that maps the corresponding
1071 * representations of these functions in terms of their nodal values. The
1072 * restriction of this matrix @p P_i to a single child cell is returned
1073 * here.
1074 *
1075 * The matrix @p P is the concatenation, not the sum of the cell matrices @p
1076 * P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in two
1077 * different child matrices @p P_i, the value should be the same in both
1078 * matrices and it is copied into the matrix @p P only once.
1079 *
1080 * Row and column indices are related to fine grid and coarse grid spaces,
1081 * respectively, consistent with the definition of the associated operator.
1082 *
1083 * These matrices are used by routines assembling the prolongation matrix
1084 * for multi-level methods. Upon assembling the transfer matrix between
1085 * cells using this matrix array, zero elements in the prolongation matrix
1086 * are discarded and will not fill up the transfer matrix.
1087 *
1088 * If prolongation matrices are not implemented in the derived finite
1089 * element class, this function aborts with an exception of type
1090 * FiniteElement::ExcEmbeddingVoid. You can check whether this would happen
1091 * by first calling the prolongation_is_implemented() or the
1092 * isotropic_prolongation_is_implemented() function.
1093 */
1094 virtual const FullMatrix<double> &
1095 get_prolongation_matrix(const unsigned int child,
1096 const RefinementCase<dim> &refinement_case =
1097 RefinementCase<dim>::isotropic_refinement) const;
1098
1099 /**
1100 * Return whether this element implements its prolongation matrices. The
1101 * return value also indicates whether a call to the
1102 * get_prolongation_matrix() function will generate an error or not.
1103 *
1104 * Note, that this function returns <code>true</code> only if the
1105 * prolongation matrices of the isotropic and all anisotropic refinement
1106 * cases are implemented. If you are interested in the prolongation matrices
1107 * for isotropic refinement only, use the
1108 * isotropic_prolongation_is_implemented function instead.
1109 *
1110 * This function is mostly here in order to allow us to write more efficient
1111 * test programs which we run on all kinds of weird elements, and for which
1112 * we simply need to exclude certain tests in case something is not
1113 * implemented. It will in general probably not be a great help in
1114 * applications, since there is not much one can do if one needs these
1115 * features and they are not implemented. This function could be used to
1116 * check whether a call to <tt>get_prolongation_matrix()</tt> will succeed;
1117 * however, one then still needs to cope with the lack of information this
1118 * just expresses.
1119 */
1120 bool
1121 prolongation_is_implemented() const;
1122
1123 /**
1124 * Return whether this element implements its prolongation matrices for
1125 * isotropic children. The return value also indicates whether a call to the
1126 * @p get_prolongation_matrix function will generate an error or not.
1127 *
1128 * This function is mostly here in order to allow us to write more efficient
1129 * test programs which we run on all kinds of weird elements, and for which
1130 * we simply need to exclude certain tests in case something is not
1131 * implemented. It will in general probably not be a great help in
1132 * applications, since there is not much one can do if one needs these
1133 * features and they are not implemented. This function could be used to
1134 * check whether a call to <tt>get_prolongation_matrix()</tt> will succeed;
1135 * however, one then still needs to cope with the lack of information this
1136 * just expresses.
1137 */
1138 bool
1139 isotropic_prolongation_is_implemented() const;
1140
1141 /**
1142 * Return whether this element implements its restriction matrices. The
1143 * return value also indicates whether a call to the
1144 * get_restriction_matrix() function will generate an error or not.
1145 *
1146 * Note, that this function returns <code>true</code> only if the
1147 * restriction matrices of the isotropic and all anisotropic refinement
1148 * cases are implemented. If you are interested in the restriction matrices
1149 * for isotropic refinement only, use the
1150 * isotropic_restriction_is_implemented() function instead.
1151 *
1152 * This function is mostly here in order to allow us to write more efficient
1153 * test programs which we run on all kinds of weird elements, and for which
1154 * we simply need to exclude certain tests in case something is not
1155 * implemented. It will in general probably not be a great help in
1156 * applications, since there is not much one can do if one needs these
1157 * features and they are not implemented. This function could be used to
1158 * check whether a call to <tt>get_restriction_matrix()</tt> will succeed;
1159 * however, one then still needs to cope with the lack of information this
1160 * just expresses.
1161 */
1162 bool
1163 restriction_is_implemented() const;
1164
1165 /**
1166 * Return whether this element implements its restriction matrices for
1167 * isotropic children. The return value also indicates whether a call to the
1168 * get_restriction_matrix() function will generate an error or not.
1169 *
1170 * This function is mostly here in order to allow us to write more efficient
1171 * test programs which we run on all kinds of weird elements, and for which
1172 * we simply need to exclude certain tests in case something is not
1173 * implemented. It will in general probably not be a great help in
1174 * applications, since there is not much one can do if one needs these
1175 * features and they are not implemented. This function could be used to
1176 * check whether a call to <tt>get_restriction_matrix()</tt> will succeed;
1177 * however, one then still needs to cope with the lack of information this
1178 * just expresses.
1179 */
1180 bool
1181 isotropic_restriction_is_implemented() const;
1182
1183
1184 /**
1185 * Access the #restriction_is_additive_flags field. See the discussion about
1186 * restriction matrices in the general class documentation for more
1187 * information.
1188 *
1189 * The index must be between zero and the number of shape functions of this
1190 * element.
1191 */
1192 bool
1193 restriction_is_additive(const unsigned int index) const;
1194
1195 /**
1196 * Return a read only reference to the matrix that describes the constraints
1197 * at the interface between a refined and an unrefined cell.
1198 *
1199 * Some finite elements do not (yet) implement hanging node constraints. If
1200 * this is the case, then this function will generate an exception, since no
1201 * useful return value can be generated. If you should have a way to live
1202 * with this, then you might want to use the constraints_are_implemented()
1203 * function to check up front whether this function will succeed or generate
1204 * the exception.
1205 */
1206 const FullMatrix<double> &
1207 constraints(const dealii::internal::SubfaceCase<dim> &subface_case =
1208 dealii::internal::SubfaceCase<dim>::case_isotropic) const;
1209
1210 /**
1211 * Return whether this element implements its hanging node constraints. The
1212 * return value also indicates whether a call to the constraints() function
1213 * will generate an error or not.
1214 *
1215 * This function is mostly here in order to allow us to write more efficient
1216 * test programs which we run on all kinds of weird elements, and for which
1217 * we simply need to exclude certain tests in case hanging node constraints
1218 * are not implemented. It will in general probably not be a great help in
1219 * applications, since there is not much one can do if one needs hanging
1220 * node constraints and they are not implemented. This function could be
1221 * used to check whether a call to <tt>constraints()</tt> will succeed;
1222 * however, one then still needs to cope with the lack of information this
1223 * just expresses.
1224 */
1225 bool
1226 constraints_are_implemented(
1227 const dealii::internal::SubfaceCase<dim> &subface_case =
1228 dealii::internal::SubfaceCase<dim>::case_isotropic) const;
1229
1230
1231 /**
1232 * Return whether this element implements its hanging node constraints in
1233 * the new way, which has to be used to make elements "hp-compatible". That
1234 * means, the element properly implements the get_face_interpolation_matrix
1235 * and get_subface_interpolation_matrix methods. Therefore the return value
1236 * also indicates whether a call to the get_face_interpolation_matrix()
1237 * method and the get_subface_interpolation_matrix() method will generate an
1238 * error or not.
1239 *
1240 * Currently the main purpose of this function is to allow the
1241 * make_hanging_node_constraints method to decide whether the new
1242 * procedures, which are supposed to work in the hp-framework can be used,
1243 * or if the old well verified but not hp-capable functions should be used.
1244 * Once the transition to the new scheme for computing the interface
1245 * constraints is complete, this function will be superfluous and will
1246 * probably go away.
1247 *
1248 * Derived classes should implement this function accordingly. The default
1249 * assumption is that a finite element does not provide hp-capable face
1250 * interpolation, and the default implementation therefore returns @p false.
1251 */
1252 virtual bool
1253 hp_constraints_are_implemented() const;
1254
1255
1256 /**
1257 * Return the matrix interpolating from the given finite element to the
1258 * present one. The size of the matrix is then #dofs_per_cell times
1259 * <tt>source.#dofs_per_cell</tt>.
1260 *
1261 * Derived elements will have to implement this function. They may only
1262 * provide interpolation matrices for certain source finite elements, for
1263 * example those from the same family. If they don't implement interpolation
1264 * from a given element, then they must throw an exception of type
1265 * ExcInterpolationNotImplemented.
1266 */
1267 virtual void
1268 get_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
1269 FullMatrix<double> &matrix) const;
1270 /** @} */
1271
1272 /**
1273 * @name Functions to support hp-adaptivity
1274 * @{
1275 */
1276
1277
1278 /**
1279 * Return the matrix interpolating from a face of one element to the face
1280 * of the neighboring element. The size of the matrix is then
1281 * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
1282 *
1283 * Derived elements will have to implement this function. They may only
1284 * provide interpolation matrices for certain source finite elements, for
1285 * example those from the same family. If they don't implement interpolation
1286 * from a given element, then they must throw an exception of type
1287 * ExcInterpolationNotImplemented.
1288 */
1289 virtual void
1290 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
1291 FullMatrix<double> &matrix,
1292 const unsigned int face_no = 0) const;
1293
1294
1295 /**
1296 * Return the matrix interpolating from a face of one element to the
1297 * subface of the neighboring element. The size of the matrix is then
1298 * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
1299 *
1300 * Derived elements will have to implement this function. They may only
1301 * provide interpolation matrices for certain source finite elements, for
1302 * example those from the same family. If they don't implement interpolation
1303 * from a given element, then they must throw an exception of type
1304 * ExcInterpolationNotImplemented.
1305 */
1306 virtual void
1307 get_subface_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
1308 const unsigned int subface,
1309 FullMatrix<double> &matrix,
1310 const unsigned int face_no = 0) const;
1311 /** @} */
1312
1313
1314 /**
1315 * @name Functions to support hp-adaptivity
1316 * @{
1317 */
1318
1319 /**
1320 * If, on a vertex, several finite elements are active, the hp-code first
1321 * assigns the degrees of freedom of each of these FEs different global
1322 * indices. It then calls this function to find out which of them should get
1323 * identical values, and consequently can receive the same global DoF index.
1324 * This function therefore returns a list of identities between DoFs of the
1325 * present finite element object with the DoFs of @p fe_other, which is a
1326 * reference to a finite element object representing one of the other finite
1327 * elements active on this particular vertex. The function computes which of
1328 * the degrees of freedom of the two finite element objects are equivalent,
1329 * both numbered between zero and the corresponding value of
1330 * n_dofs_per_vertex() of the two finite elements. The first index of each
1331 * pair denotes one of the vertex dofs of the present element, whereas the
1332 * second is the corresponding index of the other finite element.
1333 */
1334 virtual std::vector<std::pair<unsigned int, unsigned int>>
1335 hp_vertex_dof_identities(const FiniteElement<dim, spacedim> &fe_other) const;
1336
1337 /**
1338 * Same as hp_vertex_dof_indices(), except that the function treats degrees
1339 * of freedom on lines.
1340 */
1341 virtual std::vector<std::pair<unsigned int, unsigned int>>
1342 hp_line_dof_identities(const FiniteElement<dim, spacedim> &fe_other) const;
1343
1344 /**
1345 * Same as hp_vertex_dof_indices(), except that the function treats degrees
1346 * of freedom on quads.
1347 */
1348 virtual std::vector<std::pair<unsigned int, unsigned int>>
1349 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
1350 const unsigned int face_no = 0) const;
1351
1352 /**
1353 * Return whether this element dominates another one given as argument
1354 * @p fe_other, whether it is the other way around, whether neither dominates,
1355 * or if either could dominate. The @p codim parameter describes the codimension
1356 * of the investigated subspace and specifies that it is subject to this
1357 * comparison. For example, if `codim==0` then this function compares which
1358 * element dominates at the cell level. If `codim==1`, then the elements are
1359 * compared at faces, i.e., the comparison happens between the function spaces
1360 * of the two finite elements as restricted to a face. Larger values of
1361 * `codim` work correspondingly.
1362 *
1363 * For a definition of domination, see FiniteElementDomination::Domination
1364 * and in particular the
1365 * @ref hp_paper "hp-paper".
1366 */
1367 virtual FiniteElementDomination::Domination
1368 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
1369 const unsigned int codim = 0) const;
1370
1371 /** @} */
1372
1373 /**
1374 * Comparison operator.
1375 *
1376 * The implementation in the current class checks for equality of the
1377 * following pieces of information between the current object and the one
1378 * given as argument, in this order:
1379 * - the dynamic type (i.e., the type of the most derived class) of the
1380 * current object and of the given object,
1381 * - the name returned by get_name(),
1382 * - as all of the fields in FiniteElementData,
1383 * - constraint matrices.
1384 *
1385 * This covers most cases where elements can differ, but there are
1386 * cases of derived elements that are different and for which the
1387 * current function still returns @p true. For these cases, derived
1388 * classes should overload this function.
1389 *
1390 * @note This operator specifically does not check the following
1391 * member variables of the current class:
1392 * - restriction matrices,
1393 * - prolongation matrices of this object and the argument.
1394 * This is because these member variables may be initialized only
1395 * on demand by derived classes, rather than being available immediately.
1396 * Consequently, comparing these members would not only be costly because
1397 * these are generally big arrays, but also because their computation may
1398 * be expensive. On the other hand, derived classes for which these
1399 * arrays may differ for two objects even though the above list compares
1400 * as equal, will probably want to implement their own operator==()
1401 * anyway.
1402 */
1403 virtual bool
1404 operator==(const FiniteElement<dim, spacedim> &fe) const;
1405
1406 /**
1407 * Non-equality comparison operator. Defined in terms of the equality
1408 * comparison operator.
1409 */
1410 bool
1411 operator!=(const FiniteElement<dim, spacedim> &) const;
1412
1413 /**
1414 * @name Index computations
1415 * @{
1416 */
1417 /**
1418 * Compute vector component and index of this shape function within the
1419 * shape functions corresponding to this component from the index of a shape
1420 * function within this finite element.
1421 *
1422 * If the element is scalar, then the component is always zero, and the
1423 * index within this component is equal to the overall index.
1424 *
1425 * If the shape function referenced has more than one non-zero component,
1426 * then it cannot be associated with one vector component, and an exception
1427 * of type ExcShapeFunctionNotPrimitive will be raised.
1428 *
1429 * Note that if the element is composed of other (base) elements, and a base
1430 * element has more than one component but all its shape functions are
1431 * primitive (i.e. are non-zero in only one component), then this mapping
1432 * contains valid information. However, the index of a shape function of
1433 * this element within one component (i.e. the second number of the
1434 * respective entry of this array) does not indicate the index of the
1435 * respective shape function within the base element (since that has more
1436 * than one vector-component). For this information, refer to the
1437 * #system_to_base_table field and the system_to_base_index() function.
1438 *
1439 * See the class description above for an example of how this function is
1440 * typically used.
1441 *
1442 * The use of this function is explained extensively in the step-8 and
1443 * @ref step_20 "step-20"
1444 * tutorial programs as well as in the
1445 * @ref vector_valued
1446 * topic.
1447 */
1448 std::pair<unsigned int, unsigned int>
1449 system_to_component_index(const unsigned int index) const;
1450
1451 /**
1452 * Compute the shape function for the given vector component and index.
1453 *
1454 * If the element is scalar, then the component must be zero, and the index
1455 * within this component is equal to the overall index.
1456 *
1457 * This is the opposite operation from the system_to_component_index()
1458 * function.
1459 */
1460 unsigned int
1461 component_to_system_index(const unsigned int component,
1462 const unsigned int index) const;
1463
1464 /**
1465 * Same as system_to_component_index(), but do it for shape functions and
1466 * their indices on a face. The range of allowed indices is therefore
1467 * 0..#dofs_per_face.
1468 *
1469 * You will rarely need this function in application programs, since almost
1470 * all application codes only need to deal with cell indices, not face
1471 * indices. The function is mainly there for use inside the library.
1472 */
1473 std::pair<unsigned int, unsigned int>
1474 face_system_to_component_index(const unsigned int index,
1475 const unsigned int face_no = 0) const;
1476
1477 /**
1478 * Given a local dof @p index on a quad, return the local index accounting for
1479 * the face orientation @p combined_orientation. This is only necessary in 3d:
1480 * consequently, if this function is called in 1d or 2d then an exception is
1481 * thrown.
1482 */
1483 unsigned int
1484 adjust_quad_dof_index_for_face_orientation(
1485 const unsigned int index,
1486 const unsigned int face_no,
1487 const types::geometric_orientation combined_orientation) const;
1488
1489 /**
1490 * Given an index in the natural ordering of indices on a face, return the
1491 * index of the same degree of freedom on the cell.
1492 *
1493 * To explain the concept, consider the case where we would like to know
1494 * whether a degree of freedom on a face, for example as part of an FESystem
1495 * element, is primitive. Unfortunately, the is_primitive() function in the
1496 * FiniteElement class takes a cell index, so we would need to find the cell
1497 * index of the shape function that corresponds to the present face index.
1498 * This function does that.
1499 *
1500 * Code implementing this would then look like this:
1501 * @code
1502 * for (i=0; i<dofs_per_face; ++i)
1503 * if (fe.is_primitive(fe.face_to_cell_index(i, some_face_no)))
1504 * ... do whatever
1505 * @endcode
1506 * The function takes additional arguments that account for the fact that
1507 * actual faces can be in their standard ordering with respect to the cell
1508 * under consideration, or can be flipped, oriented, etc.
1509 *
1510 * @param face_dof_index The index of the degree of freedom on a face. This
1511 * index must be between zero and dofs_per_face.
1512 * @param face The number of the face this degree of freedom lives on. This
1513 * number must be between zero and GeometryInfo::faces_per_cell.
1514 * @param combined_orientation The combined orientation flag containing the
1515 * orientation, rotation, and flip of the face. See
1516 * @ref GlossCombinedOrientation.
1517 * @return The index of this degree of freedom within the set of degrees of
1518 * freedom on the entire cell. The returned value will be between zero and
1519 * dofs_per_cell.
1520 *
1521 * @note This function exists in this class because that is where it was
1522 * first implemented. However, it can't really work in the most general case
1523 * without knowing what element we have. The reason is that when a face is
1524 * flipped or rotated, we also need to know whether we need to swap the
1525 * degrees of freedom on this face, or whether they are immune from this.
1526 * For this, consider the situation of a $Q_3$ element in 2d. If face_flip
1527 * is true, then we need to consider the two degrees of freedom on the edge
1528 * in reverse order. On the other hand, if the element were a $Q_1^2$, then
1529 * because the two degrees of freedom on this edge belong to different
1530 * vector components, they should not be considered in reverse order. What
1531 * all of this shows is that the function can't work if there are more than
1532 * one degree of freedom per line or quad, and that in these cases the
1533 * function will throw an exception pointing out that this functionality
1534 * will need to be provided by a derived class that knows what degrees of
1535 * freedom actually represent.
1536 */
1537 virtual unsigned int
1538 face_to_cell_index(const unsigned int face_dof_index,
1539 const unsigned int face,
1540 const types::geometric_orientation combined_orientation =
1541 numbers::default_geometric_orientation) const;
1542
1543 /**
1544 * Given a local dof @p index on a line and the orientation @p
1545 * combined_orientation of that line, return the local dof which accounts for
1546 * @p combined_orientation.
1547 *
1548 * @note In both 1d and 2d all-quadrilateral meshes all lines have the
1549 * standard orientation. However, since 2d meshes may contain both
1550 * quadrilaterals and triangles, this assumption cannot be made in this class.
1551 */
1552 unsigned int
1553 adjust_line_dof_index_for_line_orientation(
1554 const unsigned int index,
1555 const types::geometric_orientation combined_orientation) const;
1556
1557 /**
1558 * Return in which of the vector components of this finite element the @p
1559 * ith shape function is non-zero. The length of the returned array is equal
1560 * to the number of vector components of this element.
1561 *
1562 * For most finite element spaces, the result of this function will be a
1563 * vector with exactly one element being @p true, since for most spaces the
1564 * individual vector components are independent. In that case, the component
1565 * with the single zero is also the first element of what
1566 * system_to_component_index() returns.
1567 *
1568 * Only for those spaces that couple the components, for example to make a
1569 * shape function divergence free, will there be more than one @p true
1570 * entry. Elements for which this is true are called non-primitive (see
1571 * @ref GlossPrimitive).
1572 */
1573 const ComponentMask &
1574 get_nonzero_components(const unsigned int i) const;
1575
1576 /**
1577 * Return in how many vector components the @p ith shape function is
1578 * non-zero. This value equals the number of entries equal to @p true in the
1579 * result of the get_nonzero_components() function.
1580 *
1581 * For most finite element spaces, the result will be equal to one. It is
1582 * not equal to one only for those ansatz spaces for which vector-valued
1583 * shape functions couple the individual components, for example in order to
1584 * make them divergence-free.
1585 */
1586 unsigned int
1587 n_nonzero_components(const unsigned int i) const;
1588
1589 /**
1590 * Return whether the entire finite element is primitive, in the sense that
1591 * all its shape functions are primitive. If the finite element is scalar,
1592 * then this is always the case.
1593 *
1594 * Since this is an extremely common operation, the result is cached and
1595 * returned by this function.
1596 */
1597 bool
1598 is_primitive() const;
1599
1600 /**
1601 * Return whether the @p ith shape function is primitive in the
1602 * sense that the shape function is non-zero in only one vector
1603 * component. Non-primitive shape functions would then, for example,
1604 * be those of divergence free ansatz spaces, in which the
1605 * individual vector components are coupled.
1606 *
1607 * The result of the function is @p true if and only if the result of
1608 * <tt>n_nonzero_components(i)</tt> is equal to one.
1609 */
1610 bool
1611 is_primitive(const unsigned int i) const;
1612
1613 /**
1614 * Return a table (or sparsity pattern) with information which of the
1615 * local DoFs per cell couple with each other.
1616 *
1617 * If the FiniteElement returns an empty (0 by 0) table, which is the
1618 * default implementation for any class that does not override this
1619 * function, all DoFs are assumed to couple.
1620 *
1621 * Otherwise, this function returns a square table with n_dofs_per_cell
1622 * rows and columns. The entry (i,j) then denotes if the DoF i and j
1623 * are coupled. This should be true if the support of the shape functions
1624 * have a non-empty intersection.
1625 *
1626 * An example for an element that does make use of this feature is
1627 * FE_Q_iso_Q1.
1628 */
1629 virtual const Table<2, bool> &
1630 get_local_dof_sparsity_pattern() const;
1631
1632 /**
1633 * Number of base elements in a mixed discretization.
1634 *
1635 * Note that even for vector valued finite elements, the number of
1636 * components needs not coincide with the number of base elements, since
1637 * they may be reused. For example, if you create a FESystem with three
1638 * identical finite element classes by using the constructor that takes one
1639 * finite element and a multiplicity, then the number of base elements is
1640 * still one, although the number of components of the finite element is
1641 * equal to the multiplicity.
1642 */
1643 unsigned int
1644 n_base_elements() const;
1645
1646 /**
1647 * Access to base element objects. If the element is atomic, then
1648 * <code>base_element(0)</code> is @p this.
1649 */
1650 virtual const FiniteElement<dim, spacedim> &
1651 base_element(const unsigned int index) const;
1652
1653 /**
1654 * This index denotes how often the base element @p index is used in a
1655 * composed element. If the element is atomic, then the result is always
1656 * equal to one. See the documentation for the n_base_elements() function
1657 * for more details.
1658 */
1659 unsigned int
1660 element_multiplicity(const unsigned int index) const;
1661
1662 /**
1663 * Return a reference to a contained finite element that matches the
1664 * components
1665 * selected by the given ComponentMask @p mask.
1666 *
1667 * For an arbitrarily nested FESystem, this function returns the inner-most
1668 * FiniteElement that matches the given mask. The method fails if the @p mask
1669 * does not exactly match one of the contained finite elements. It is most
1670 * useful if the current object is an FESystem, as the return value can
1671 * only be @p this in all other cases.
1672 *
1673 * Note that the returned object can be an FESystem if the
1674 * mask matches it but not any of the contained objects.
1675 *
1676 * Let us illustrate the function with the an FESystem @p fe with 7 components:
1677 * @code
1678 * FESystem<2> fe_velocity(FE_Q<2>(2), 2);
1679 * FE_Q<2> fe_pressure(1);
1680 * FE_DGP<2> fe_dg(0);
1681 * FE_BDM<2> fe_nonprim(1);
1682 * FESystem<2> fe(fe_velocity, 1, fe_pressure, 1, fe_dg, 2, fe_nonprim, 1);
1683 * @endcode
1684 *
1685 * The following table lists all possible component masks you can use:
1686 * <table>
1687 * <tr>
1688 * <th>ComponentMask</th>
1689 * <th>Result</th>
1690 * <th>Description</th>
1691 * </tr>
1692 * <tr>
1693 * <td><code>[true,true,true,true,true,true,true]</code></td>
1694 * <td><code>FESystem<2>[FESystem<2>[FE_Q<2>(2)^2]-FE_Q<2>(1)-FE_DGP<2>(0)^2-FE_BDM<2>(1)]</code></td>
1695 * <td>@p fe itself, the whole @p FESystem</td>
1696 * </tr>
1697 * <tr>
1698 * <td><code>[true,true,false,false,false,false,false]</code></td>
1699 * <td><code>FESystem<2>[FE_Q<2>(2)^2]</code></td>
1700 * <td>just the @p fe_velocity</td>
1701 * </tr>
1702 * <tr>
1703 * <td><code>[true,false,false,false,false,false,false]</code></td>
1704 * <td><code>FE_Q<2>(2)</code></td>
1705 * <td>The first component in @p fe_velocity</td>
1706 * </tr>
1707 * <tr>
1708 * <td><code>[false,true,false,false,false,false,false]</code></td>
1709 * <td><code>FE_Q<2>(2)</code></td>
1710 * <td>The second component in @p fe_velocity</td>
1711 * </tr>
1712 * <tr>
1713 * <td><code>[false,false,true,false,false,false,false]</code></td>
1714 * <td><code>FE_Q<2>(1)</code></td>
1715 * <td>@p fe_pressure</td>
1716 * </tr>
1717 * <tr>
1718 * <td><code>[false,false,false,true,false,false,false]</code></td>
1719 * <td><code>FE_DGP<2>(0)</code></td>
1720 * <td>first copy of @p fe_dg</td>
1721 * </tr>
1722 * <tr>
1723 * <td><code>[false,false,false,false,true,false,false]</code></td>
1724 * <td><code>FE_DGP<2>(0)</code></td>
1725 * <td>second copy of @p fe_dg</td>
1726 * </tr>
1727 * <tr>
1728 * <td><code>[false,false,false,false,false,true,true]</code></td>
1729 * <td><code>FE_BDM<2>(1)</code></td>
1730 * <td>both components of @p fe_nonprim</td>
1731 * </tr>
1732 * </table>
1733 */
1734 const FiniteElement<dim, spacedim> &
1735 get_sub_fe(const ComponentMask &mask) const;
1736
1737 /**
1738 * Return a reference to a contained finite element that matches the
1739 * components
1740 * @p n_selected_components components starting at component with index
1741 * @p first_component.
1742 *
1743 * See the other get_sub_fe() function above for more details.
1744 */
1745 virtual const FiniteElement<dim, spacedim> &
1746 get_sub_fe(const unsigned int first_component,
1747 const unsigned int n_selected_components) const;
1748
1749 /**
1750 * Return for shape function @p index the base element it belongs to, the
1751 * number of the copy of this base element (which is between zero and the
1752 * multiplicity of this element), and the index of this shape function
1753 * within this base element.
1754 *
1755 * If the element is not composed of others, then base and instance are
1756 * always zero, and the index is equal to the number of the shape function.
1757 * If the element is composed of single instances of other elements (i.e.
1758 * all with multiplicity one) all of which are scalar, then base values and
1759 * dof indices within this element are equal to the
1760 * #system_to_component_table. It differs only in case the element is
1761 * composed of other elements and at least one of them is vector-valued
1762 * itself.
1763 *
1764 * See the class documentation above for an example of how this function is
1765 * typically used.
1766 *
1767 * This function returns valid values also in the case of vector-valued
1768 * (i.e. non-primitive) shape functions, in contrast to the
1769 * system_to_component_index() function.
1770 */
1771 std::pair<std::pair<unsigned int, unsigned int>, unsigned int>
1772 system_to_base_index(const unsigned int index) const;
1773
1774 /**
1775 * Same as system_to_base_index(), but for degrees of freedom located on a
1776 * face. The range of allowed indices is therefore 0..#dofs_per_face.
1777 *
1778 * You will rarely need this function in application programs, since almost
1779 * all application codes only need to deal with cell indices, not face
1780 * indices. The function is mainly there for use inside the library.
1781 */
1782 std::pair<std::pair<unsigned int, unsigned int>, unsigned int>
1783 face_system_to_base_index(const unsigned int index,
1784 const unsigned int face_no = 0) const;
1785
1786 /**
1787 * Given a base element number, return the first block of a BlockVector it
1788 * would generate.
1789 */
1790 types::global_dof_index
1791 first_block_of_base(const unsigned int b) const;
1792
1793 /**
1794 * For each vector component, return which base element implements this
1795 * component and which vector component in this base element this is. This
1796 * information is only of interest for vector-valued finite elements which
1797 * are composed of several sub-elements. In that case, one may want to
1798 * obtain information about the element implementing a certain vector
1799 * component, which can be done using this function and the
1800 * FESystem::base_element() function.
1801 *
1802 * If this is a scalar finite element, then the return value is always equal
1803 * to a pair of zeros.
1804 */
1805 std::pair<unsigned int, unsigned int>
1806 component_to_base_index(const unsigned int component) const;
1807
1808
1809 /**
1810 * Return the base element for this block and the number of the copy of the
1811 * base element.
1812 */
1813 std::pair<unsigned int, unsigned int>
1814 block_to_base_index(const unsigned int block) const;
1815
1816 /**
1817 * The vector block and the index inside the block for this shape function.
1818 */
1819 std::pair<unsigned int, types::global_dof_index>
1820 system_to_block_index(const unsigned int component) const;
1821
1822 /**
1823 * The vector block for this component.
1824 */
1825 unsigned int
1826 component_to_block_index(const unsigned int component) const;
1827
1828 /**
1829 * For vector-valued finite elements, return whether the shape
1830 * function indicated by the first argument is part of the scalar
1831 * vector component indicated by the second argument. In practice,
1832 * what this means is that the set of nonzero vector components of
1833 * the indicated shape function includes the one vector component
1834 * represented by the second argument; in other words, whether the
1835 * shape function is (potentially) nonzero in the given vector
1836 * component.
1837 *
1838 * A typical example would be in a program like step-22, where we
1839 * might want to know whether a shape function of the combined,
1840 * vector-valued element, corresponds to the pressure part of the
1841 * solution.
1842 */
1843 bool
1844 shape_function_belongs_to(const unsigned int shape_function,
1845 const FEValuesExtractors::Scalar &component) const;
1846
1847 /**
1848 * For vector-valued finite elements, return whether the shape
1849 * function indicated by the first argument is part of the `dim`
1850 * vector components indicated by the second argument. In practice,
1851 * what this means is that the set of nonzero vector components of
1852 * the indicated shape function overlaps the vector components
1853 * represented by the second argument; in other words, whether the
1854 * shape function is (potentially) nonzero any of the given vector
1855 * components.
1856 *
1857 * A typical example would be in a program like step-22, where we
1858 * might want to know whether a shape function of the combined,
1859 * vector-valued element, corresponds to the velocity part of the
1860 * solution.
1861 */
1862 bool
1863 shape_function_belongs_to(const unsigned int shape_function,
1864 const FEValuesExtractors::Vector &components) const;
1865
1866
1867 /**
1868 * For vector-valued finite elements, return whether the shape
1869 * function indicated by the first argument is part of the `dim*(dim+1)/2`
1870 * vector components indicated by the second argument. In practice,
1871 * what this means is that the set of nonzero vector components of
1872 * the indicated shape function overlaps the vector components
1873 * represented by the second argument; in other words, whether the
1874 * shape function is (potentially) nonzero any of the given
1875 * components that represent a symmetric tensor.
1876 *
1877 * An example would be in a program like step-71, where we
1878 * might want to know whether a shape function of the combined,
1879 * vector-valued element, corresponds to the $H$ or $C$ part of the
1880 * solution, where $H$ is a vector and $C$ is a symmetric tensor.
1881 */
1882 bool
1883 shape_function_belongs_to(
1884 const unsigned int shape_function,
1885 const FEValuesExtractors::SymmetricTensor<2> &components) const;
1886
1887
1888 /**
1889 * For vector-valued finite elements, return whether the shape
1890 * function indicated by the first argument is part of the `dim*dim`
1891 * vector components indicated by the second argument. In practice,
1892 * what this means is that the set of nonzero vector components of
1893 * the indicated shape function overlaps the vector components
1894 * represented by the second argument; in other words, whether the
1895 * shape function is (potentially) nonzero any of the given
1896 * components that represent a tensor.
1897 */
1898 bool
1899 shape_function_belongs_to(
1900 const unsigned int shape_function,
1901 const FEValuesExtractors::Tensor<2> &components) const;
1902 /** @} */
1903
1904 /**
1905 * @name Component and block masks
1906 * @{
1907 */
1908
1909 /**
1910 * Return a component mask with as many elements as this object has vector
1911 * components and of which exactly the one component is true that
1912 * corresponds to the given argument. See
1913 * @ref GlossComponentMask "the glossary"
1914 * for more information.
1915 *
1916 * @param scalar An object that represents a single scalar vector component
1917 * of this finite element.
1918 * @return A component mask that is false in all components except for the
1919 * one that corresponds to the argument.
1920 */
1921 ComponentMask
1922 component_mask(const FEValuesExtractors::Scalar &scalar) const;
1923
1924 /**
1925 * Return a component mask with as many elements as this object has vector
1926 * components and of which exactly the <code>dim</code> components are true
1927 * that correspond to the given argument. See
1928 * @ref GlossComponentMask "the glossary"
1929 * for more information.
1930 *
1931 * @param vector An object that represents dim vector components of this
1932 * finite element.
1933 * @return A component mask that is false in all components except for the
1934 * ones that corresponds to the argument.
1935 */
1936 ComponentMask
1937 component_mask(const FEValuesExtractors::Vector &vector) const;
1938
1939 /**
1940 * Return a component mask with as many elements as this object has vector
1941 * components and of which exactly the <code>dim*(dim+1)/2</code> components
1942 * are true that correspond to the given argument. See
1943 * @ref GlossComponentMask "the glossary"
1944 * for more information.
1945 *
1946 * @param sym_tensor An object that represents dim*(dim+1)/2 components of
1947 * this finite element that are jointly to be interpreted as forming a
1948 * symmetric tensor.
1949 * @return A component mask that is false in all components except for the
1950 * ones that corresponds to the argument.
1951 */
1952 ComponentMask
1953 component_mask(
1954 const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
1955
1956 /**
1957 * Given a block mask (see
1958 * @ref GlossBlockMask "this glossary entry"),
1959 * produce a component mask (see
1960 * @ref GlossComponentMask "this glossary entry")
1961 * that represents the components that correspond to the blocks selected in
1962 * the input argument. This is essentially a conversion operator from
1963 * BlockMask to ComponentMask.
1964 *
1965 * @param block_mask The mask that selects individual blocks of the finite
1966 * element
1967 * @return A mask that selects those components corresponding to the
1968 * selected blocks of the input argument.
1969 */
1970 ComponentMask
1971 component_mask(const BlockMask &block_mask) const;
1972
1973 /**
1974 * Return a block mask with as many elements as this object has blocks and
1975 * of which exactly the one component is true that corresponds to the given
1976 * argument. See
1977 * @ref GlossBlockMask "the glossary"
1978 * for more information.
1979 *
1980 * @note This function will only succeed if the scalar referenced by the
1981 * argument encompasses a complete block. In other words, if, for example,
1982 * you pass an extractor for the single $x$ velocity and this object
1983 * represents an FE_RaviartThomas object, then the single scalar object you
1984 * selected is part of a larger block and consequently there is no block
1985 * mask that would represent it. The function will then produce an
1986 * exception.
1987 *
1988 * @param scalar An object that represents a single scalar vector component
1989 * of this finite element.
1990 * @return A component mask that is false in all components except for the
1991 * one that corresponds to the argument.
1992 */
1993 BlockMask
1994 block_mask(const FEValuesExtractors::Scalar &scalar) const;
1995
1996 /**
1997 * Return a component mask with as many elements as this object has vector
1998 * components and of which exactly the <code>dim</code> components are true
1999 * that correspond to the given argument. See
2000 * @ref GlossBlockMask "the glossary"
2001 * for more information.
2002 *
2003 * @note The same caveat applies as to the version of the function above:
2004 * The extractor object passed as argument must be so that it corresponds to
2005 * full blocks and does not split blocks of this element.
2006 *
2007 * @param vector An object that represents dim vector components of this
2008 * finite element.
2009 * @return A component mask that is false in all components except for the
2010 * ones that corresponds to the argument.
2011 */
2012 BlockMask
2013 block_mask(const FEValuesExtractors::Vector &vector) const;
2014
2015 /**
2016 * Return a component mask with as many elements as this object has vector
2017 * components and of which exactly the <code>dim*(dim+1)/2</code> components
2018 * are true that correspond to the given argument. See
2019 * @ref GlossBlockMask "the glossary"
2020 * for more information.
2021 *
2022 * @note The same caveat applies as to the version of the function above:
2023 * The extractor object passed as argument must be so that it corresponds to
2024 * full blocks and does not split blocks of this element.
2025 *
2026 * @param sym_tensor An object that represents dim*(dim+1)/2 components of
2027 * this finite element that are jointly to be interpreted as forming a
2028 * symmetric tensor.
2029 * @return A component mask that is false in all components except for the
2030 * ones that corresponds to the argument.
2031 */
2032 BlockMask
2033 block_mask(const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
2034
2035 /**
2036 * Given a component mask (see
2037 * @ref GlossComponentMask "this glossary entry"),
2038 * produce a block mask (see
2039 * @ref GlossBlockMask "this glossary entry")
2040 * that represents the blocks that correspond to the components selected in
2041 * the input argument. This is essentially a conversion operator from
2042 * ComponentMask to BlockMask.
2043 *
2044 * @note This function will only succeed if the components referenced by the
2045 * argument encompasses complete blocks. In other words, if, for example,
2046 * you pass an component mask for the single $x$ velocity and this object
2047 * represents an FE_RaviartThomas object, then the single component you
2048 * selected is part of a larger block and consequently there is no block
2049 * mask that would represent it. The function will then produce an
2050 * exception.
2051 *
2052 * @param component_mask The mask that selects individual components of the
2053 * finite element
2054 * @return A mask that selects those blocks corresponding to the selected
2055 * blocks of the input argument.
2056 */
2057 BlockMask
2058 block_mask(const ComponentMask &component_mask) const;
2059
2060 /**
2061 * Return a list of constant modes of the element. The number of rows in
2062 * the resulting table depends on the elements in use. For standard
2063 * elements, the table has as many rows as there are components in the
2064 * element and dofs_per_cell columns. To each component of the finite
2065 * element, the row in the returned table contains a basis representation of
2066 * the constant function 1 on the element. However, there are some scalar
2067 * elements where there is more than one constant mode, e.g. the element
2068 * FE_Q_DG0.
2069 *
2070 * In order to match the constant modes to the actual components in the
2071 * element, the returned data structure also returns a vector with as many
2072 * components as there are constant modes on the element that contains the
2073 * component number.
2074 */
2075 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
2076 get_constant_modes() const;
2077
2078 /** @} */
2079
2080 /**
2081 * @name Support points and interpolation
2082 * @{
2083 */
2084
2085 /**
2086 * Return the support points of the trial functions on the unit cell, if the
2087 * derived finite element defines them. Finite elements that allow some
2088 * kind of interpolation operation usually have support points. On the other
2089 * hand, elements that define their degrees of freedom by, for example,
2090 * moments on faces, or as derivatives, don't have support points. In that
2091 * case, the returned field is empty.
2092 *
2093 * If the finite element defines support points, then their number equals
2094 * the number of degrees of freedom of the element. The order of points in
2095 * the array matches that returned by the <tt>cell->get_dof_indices</tt>
2096 * function.
2097 *
2098 * See the class documentation for details on support points.
2099 *
2100 * @note Finite elements' implementation of this function returns these
2101 * points in the same order as shape functions. The order of shape functions
2102 * is typically documented in the class documentation of the various finite
2103 * element classes. In particular, shape functions (and consequently the
2104 * mapped quadrature points discussed in the class documentation of this
2105 * class) will then traverse first those shape functions located on
2106 * vertices, then on lines, then on quads, etc.
2107 *
2108 * @note If this element implements support points, then it will return one
2109 * such point per shape function. Since multiple shape functions may be
2110 * defined at the same location, the support points returned here may be
2111 * duplicated. An example would be an element of the kind
2112 * <code>FESystem(FE_Q(1),3)</code> for which each support point would
2113 * appear three times in the returned array.
2114 */
2115 const std::vector<Point<dim>> &
2116 get_unit_support_points() const;
2117
2118 /**
2119 * Return whether a finite element has defined support points. If the result
2120 * is true, then a call to the get_unit_support_points() yields an
2121 * array with `dofs_per_cell` entries. Note that the function's name is
2122 * poorly chosen: The function does not return *whether* an element has
2123 * support points, but whether its implementation is able to *provide*
2124 * a list of support points via get_unit_support_points().
2125 *
2126 * The result may be false if a finite element defines itself not by
2127 * interpolating shape functions, but by other means. A typical example are
2128 * discontinuous $P$-type elements on quadrilaterals (rather than the common
2129 * $Q$-type elements on quadrilaterals). Elements will generally only return
2130 * `true` if they construct their shape functions by the
2131 * requirement that they be nonzero at a certain point and zero at all the
2132 * points associated with the other shape functions. In other words,
2133 * if the "node functionals" that form the dual space of the finite
2134 * element space and are used to define the shape functions are point
2135 * evaluations.
2136 *
2137 * In composed elements (i.e. for the FESystem class), the result will be
2138 * true if all the base elements have defined support points. FE_Nothing
2139 * is a special case since it does not have support point (it has no
2140 * shape functions, after all), and so returns an empty array from its
2141 * get_unit_support_points() function. Nonetheless, because that array has
2142 * the right size, it reports `true` in the current function.
2143 */
2144 bool
2145 has_support_points() const;
2146
2147 /**
2148 * Return the position of the support point of the @p indexth shape
2149 * function. If it does not exist, raise an exception.
2150 *
2151 * The default implementation simply returns the respective element from the
2152 * array you get from get_unit_support_points(), but derived elements may
2153 * overload this function. In particular, note that the FESystem class
2154 * overloads it so that it can return the support points of individual base
2155 * elements, if not all the base elements define support points. In this
2156 * way, you can still ask for certain support points, even if
2157 * get_unit_support_points() only returns an empty array.
2158 */
2159 virtual Point<dim>
2160 unit_support_point(const unsigned int index) const;
2161
2162 /**
2163 * Return the support points of the trial functions on the unit face, if the
2164 * derived finite element defines some. Finite elements that allow some
2165 * kind of interpolation operation usually have support points. On the other
2166 * hand, elements that define their degrees of freedom by, for example,
2167 * moments on faces, or as derivatives, don't have support points. In that
2168 * case, the returned field is empty
2169 *
2170 * Note that elements that have support points need not necessarily have
2171 * some on the faces, even if the interpolation points are located
2172 * physically on a face. For example, the discontinuous elements have
2173 * interpolation points on the vertices, and for higher degree elements also
2174 * on the faces, but they are not defined to be on faces since in that case
2175 * degrees of freedom from both sides of a face (or from all adjacent
2176 * elements to a vertex) would be identified with each other, which is not
2177 * what we would like to have). Logically, these degrees of freedom are
2178 * therefore defined to belong to the cell, rather than the face or vertex.
2179 * In that case, the returned element would therefore have length zero.
2180 *
2181 * If the finite element defines support points, then their number equals
2182 * the number of degrees of freedom on the face (#dofs_per_face). The order
2183 * of points in the array matches that returned by the
2184 * <tt>cell->face(face)->get_dof_indices</tt> function.
2185 *
2186 * See the class documentation for details on support points.
2187 */
2188 const std::vector<Point<dim - 1>> &
2189 get_unit_face_support_points(const unsigned int face_no = 0) const;
2190
2191 /**
2192 * Return whether a finite element has defined support points on faces. If
2193 * the result is true, then a call to the get_unit_face_support_points()
2194 * yields an array with `dofs_per_face` entries. Note that the function's name
2195 * is poorly chosen: The function does not return *whether* an element has
2196 * support points, but whether its implementation is able to *provide*
2197 * a list of support points via get_unit_face_support_points().
2198 *
2199 * For more information, see the documentation for the has_support_points()
2200 * function.
2201 */
2202 bool
2203 has_face_support_points(const unsigned int face_no = 0) const;
2204
2205 /**
2206 * The function corresponding to the unit_support_point() function, but for
2207 * faces. See there for more information.
2208 */
2209 virtual Point<dim - 1>
2210 unit_face_support_point(const unsigned int index,
2211 const unsigned int face_no = 0) const;
2212
2213 /**
2214 * Return a vector of generalized support points.
2215 *
2216 * @note The vector returned by this function is always a minimal set of
2217 * *unique* support points. This is in contrast to the behavior of
2218 * get_unit_support_points() that returns a repeated list of unit support
2219 * points for an FESystem of numerous (Lagrangian) base elements. As a
2220 * consequence, it is possible to have fewer generalized support points
2221 * than degrees of freedom in the element. An example is the
2222 * element `FESystem<dim>(FE_Q<dim>(1), 2)`, which has two
2223 * copies of the $Q_1$ element. In 2d, each copy has 4 degrees of
2224 * freedom, and each copy has its support points in the
2225 * four vertices of the cell. While the get_support_points()
2226 * function would return a vector of size 8 in which each of the
2227 * vertices is listed twice, this function strips
2228 * out the duplicates and returns a vector of length 4 in which each
2229 * vertex is listed only once. This is possible because the purpose of this
2230 * function is to return a list of points so that it is possible to
2231 * interpolate an arbitrary function onto the finite element
2232 * space, and this is possible by knowing the two components of the
2233 * function in question at the four vertices of the cell -- it is not
2234 * necessary to ask for this information twice at each vertex.
2235 *
2236 * See the
2237 * @ref GlossGeneralizedSupport "glossary entry on generalized support points"
2238 * for more information.
2239 */
2240 const std::vector<Point<dim>> &
2241 get_generalized_support_points() const;
2242
2243 /**
2244 * Return whether a finite element has defined generalized support
2245 * points. If the result is true, then a call to the
2246 * get_generalized_support_points() yields an
2247 * array with minimal set of *unique* support points. Note that the function's
2248 * name is poorly chosen: The function does not return *whether* an element
2249 * has support points, but whether its implementation is able to *provide*
2250 * a list of support points via get_unit_support_points().
2251 *
2252 * See the
2253 * @ref GlossGeneralizedSupport "glossary entry on generalized support points"
2254 * or the documentation for the has_support_points() function for more
2255 * information.
2256 */
2257 bool
2258 has_generalized_support_points() const;
2259
2260 /**
2261 * For a given degree of freedom, return whether it is logically associated
2262 * with a vertex, line, quad or hex.
2263 *
2264 * For instance, for continuous finite elements this coincides with
2265 * the lowest dimensional object the support point of the degree of
2266 * freedom lies on. To give an example, for $Q_1$ elements in 3d,
2267 * every degree of freedom is defined by a shape function that we
2268 * get by interpolating using support points that lie on the
2269 * vertices of the cell. The support of these points of course
2270 * extends to all edges connected to this vertex, as well as the
2271 * adjacent faces and the cell interior, but we say that logically
2272 * the degree of freedom is associated with the vertex as this is
2273 * the lowest-dimensional object it is associated with. Likewise,
2274 * for $Q_2$ elements in 3d, the degrees of freedom with support
2275 * points at edge midpoints would yield a value of
2276 * GeometryPrimitive::line from this function, whereas those on the
2277 * centers of faces in 3d would return GeometryPrimitive::quad.
2278 *
2279 * To make this more formal, the kind of object returned by this function
2280 * represents the object so that the support of the shape function
2281 * corresponding to the degree of freedom, (i.e., that part of the domain
2282 * where the function "lives") is the union of all of the cells sharing this
2283 * object. To return to the example above, for $Q_2$ in 3d, the shape
2284 * function with support point at an edge midpoint has support on all cells
2285 * that share the edge and not only the cells that share the adjacent faces,
2286 * and consequently the function will return GeometryPrimitive::line.
2287 *
2288 * On the other hand, for discontinuous elements of type $DGQ_2$, a degree
2289 * of freedom associated with an interpolation polynomial that has its
2290 * support point physically located at a line bounding a cell, but is
2291 * nonzero only on one cell. Consequently, it is logically associated with
2292 * the interior of that cell (i.e., with a GeometryPrimitive::quad in 2d and
2293 * a GeometryPrimitive::hex in 3d).
2294 *
2295 * @param[in] cell_dof_index The index of a shape function or degree of
2296 * freedom. This index must be in the range <code>[0,dofs_per_cell)</code>.
2297 *
2298 * @note The integer value of the object returned by this function equals
2299 * the dimensionality of the object it describes, and can consequently be
2300 * used in generic programming paradigms. For example, if a degree of
2301 * freedom is associated with a vertex, then this function returns
2302 * GeometryPrimitive::vertex, which has a numeric value of zero (the
2303 * dimensionality of a vertex).
2304 */
2305 GeometryPrimitive
2306 get_associated_geometry_primitive(const unsigned int cell_dof_index) const;
2307
2308
2309 /**
2310 * Given the values of a function $f(\mathbf x)$ at the (generalized)
2311 * support points of the reference cell, this function then computes what
2312 * the nodal values of the element are, i.e., $\Psi_i[f]$, where $\Psi_i$
2313 * are the node functionals of the element
2314 * (see also
2315 * @ref GlossNodes "Node values or node functionals").
2316 * The values $\Psi_i[f]$ are then the expansion coefficients
2317 * for the shape functions of the finite element function that
2318 * <i>interpolates</i> the given function $f(x)$, i.e.,
2319 * $ f_h(\mathbf x) = \sum_i \Psi_i[f] \varphi_i(\mathbf x)
2320 * $ is the finite element interpolant of $f$ with the current element.
2321 * The operation described here is used, for example, in the
2322 * FETools::compute_node_matrix() function.
2323 *
2324 * In more detail, let us assume that the generalized support points
2325 * (see
2326 * @ref GlossGeneralizedSupport "this glossary entry"
2327 * ) of the current
2328 * element are $\hat{\mathbf x}_i$ and that the node functionals associated
2329 * with the current element are $\Psi_i[\cdot]$. Then, the fact that the
2330 * element is based on generalized support points, implies that if we
2331 * apply $\Psi_i$ to a (possibly vector-valued) finite element function
2332 * $\varphi$, the result must have the form
2333 * $\Psi_i[\varphi] = f_i(\varphi(\hat{\mathbf x}_i))$ -- in other words,
2334 * the value of the node functional $\Psi_i$ applied to $\varphi$ <i>only</i>
2335 * depends on the <i>values of $\varphi$ at $\hat{\mathbf x}_i$</i> and not
2336 * on values anywhere else, or integrals of $\varphi$, or any other kind
2337 * of information.
2338 *
2339 * The exact form of $f_i$ depends on the element. For example, for scalar
2340 * @ref GlossLagrange "Lagrange elements",
2341 * we have that in fact
2342 * $\Psi_i[\varphi] = \varphi(\hat{\mathbf x}_i)$. If you combine multiple
2343 * scalar Lagrange elements via an FESystem object, then
2344 * $\Psi_i[\varphi] = \varphi(\hat{\mathbf x}_i)_{c(i)}$ where $c(i)$
2345 * is the result of the FiniteElement::system_to_component_index()
2346 * function's return value's first component. In these two cases,
2347 * $f_i$ is therefore simply the identity (in the scalar case) or a
2348 * function that selects a particular vector component of its argument.
2349 * On the other hand, for Raviart-Thomas elements, one would have that
2350 * $f_i(\mathbf y) = \mathbf y \cdot \mathbf n_i$ where $\mathbf n_i$
2351 * is the normal vector of the face at which the shape function is
2352 * defined.
2353 *
2354 * Given all of this, what this function does is the following: If you
2355 * input a list of values of a function $\varphi$ at all generalized
2356 * support points (where each value is in fact a vector of values with
2357 * as many components as the element has), then this function returns
2358 * a vector of values obtained by applying the node functionals to
2359 * these values. In other words, if you pass in
2360 * $\{\varphi(\hat{\mathbf x}_i)\}_{i=0}^{N-1}$ then you
2361 * will get out a vector
2362 * $\{\Psi[\varphi]\}_{i=0}^{N-1}$ where $N$ equals @p dofs_per_cell.
2363 *
2364 * @param[in] support_point_values An array of size @p dofs_per_cell
2365 * (which equals the number of points the get_generalized_support_points()
2366 * function will return) where each element is a vector with as many entries
2367 * as the element has vector components. This array should contain
2368 * the values of a function at the generalized support points of the
2369 * current element.
2370 * @param[out] nodal_values An array of size @p dofs_per_cell that contains
2371 * the node functionals of the element applied to the given function.
2372 *
2373 * @note It is safe to call this function for (transformed) values on the
2374 * real cell only for elements with trivial MappingKind. For all other
2375 * elements (for example for H(curl), or H(div) conforming elements)
2376 * vector values have to be transformed to the reference cell first.
2377 *
2378 * @note Given what the function is supposed to do, the function clearly
2379 * can only work for elements that actually implement (generalized) support
2380 * points. Elements that do not have generalized support points -- e.g.,
2381 * elements whose nodal functionals evaluate integrals or moments of
2382 * functions (such as FE_Q_Hierarchical) -- can in general not make
2383 * sense of the operation that is required for this function. They
2384 * consequently may not implement it.
2385 */
2386 virtual void
2387 convert_generalized_support_point_values_to_dof_values(
2388 const std::vector<Vector<double>> &support_point_values,
2389 std::vector<double> &nodal_values) const;
2390
2391 /** @} */
2392
2393 /**
2394 * Determine an estimate for the memory consumption (in bytes) of this
2395 * object.
2396 *
2397 * This function is made virtual, since finite element objects are usually
2398 * accessed through pointers to their base class, rather than the class
2399 * itself.
2400 */
2401 virtual std::size_t
2402 memory_consumption() const;
2403
2404 /**
2405 * Exception
2406 *
2407 * @ingroup Exceptions
2408 */
2409 DeclException1(ExcShapeFunctionNotPrimitive,
2410 int,
2411 << "The shape function with index " << arg1
2412 << " is not primitive, i.e. it is vector-valued and "
2413 << "has more than one non-zero vector component. This "
2414 << "function cannot be called for these shape functions. "
2415 << "Maybe you want to use the same function with the "
2416 << "_component suffix?");
2417 /**
2418 * Exception
2419 *
2420 * @ingroup Exceptions
2421 */
2422 DeclException0(ExcFENotPrimitive);
2423 /**
2424 * Exception
2425 *
2426 * @ingroup Exceptions
2427 */
2428 DeclExceptionMsg(
2429 ExcUnitShapeValuesDoNotExist,
2430 "You are trying to access the values or derivatives of shape functions "
2431 "on the reference cell of an element that does not define its shape "
2432 "functions through mapping from the reference cell. Consequently, "
2433 "you cannot ask for shape function values or derivatives on the "
2434 "reference cell.");
2435
2436 /**
2437 * Attempt to access support points of a finite element that is not
2438 * Lagrangian.
2439 *
2440 * @ingroup Exceptions
2441 */
2442 DeclExceptionMsg(ExcFEHasNoSupportPoints,
2443 "You are trying to access the support points of a finite "
2444 "element that either has no support points at all, or for "
2445 "which the corresponding tables have not been implemented.");
2446
2447 /**
2448 * Attempt to access embedding matrices of a finite element that did not
2449 * implement these matrices.
2450 *
2451 * @ingroup Exceptions
2452 */
2453 DeclExceptionMsg(ExcEmbeddingVoid,
2454 "You are trying to access the matrices that describe how "
2455 "to embed a finite element function on one cell into the "
2456 "finite element space on one of its children (i.e., the "
2457 "'embedding' or 'prolongation' matrices). However, the "
2458 "current finite element can either not define this sort of "
2459 "operation, or it has not yet been implemented.");
2460
2461 /**
2462 * Attempt to access restriction matrices of a finite element that did not
2463 * implement these matrices.
2464 *
2465 * Exception
2466 * @ingroup Exceptions
2467 */
2468 DeclExceptionMsg(ExcProjectionVoid,
2469 "You are trying to access the matrices that describe how "
2470 "to restrict a finite element function from the children "
2471 "of one cell to the finite element space defined on their "
2472 "parent (i.e., the 'restriction' or 'projection' matrices). "
2473 "However, the current finite element can either not define "
2474 "this sort of operation, or it has not yet been "
2475 "implemented.");
2476
2477 /**
2478 * Exception
2479 * @ingroup Exceptions
2480 */
2481 DeclException2(ExcWrongInterfaceMatrixSize,
2482 int,
2483 int,
2484 << "The interface matrix has a size of " << arg1 << 'x' << arg2
2485 << ", which is not reasonable for the current element "
2486 "in the present dimension.");
2487 /**
2488 * Exception
2489 * @ingroup Exceptions
2490 */
2491 DeclException0(ExcInterpolationNotImplemented);
2492
2493 protected:
2494 /**
2495 * Reinit the vectors of restriction and prolongation matrices to the right
2496 * sizes: For every refinement case, except for
2497 * RefinementCase::no_refinement, and for every child of that refinement
2498 * case the space of one restriction and prolongation matrix is allocated,
2499 * see the documentation of the restriction and prolongation vectors for
2500 * more detail on the actual vector sizes.
2501 *
2502 * @param isotropic_restriction_only only the restriction matrices required
2503 * for isotropic refinement are reinited to the right size.
2504 * @param isotropic_prolongation_only only the prolongation matrices
2505 * required for isotropic refinement are reinited to the right size.
2506 */
2507 void
2508 reinit_restriction_and_prolongation_matrices(
2509 const bool isotropic_restriction_only = false,
2510 const bool isotropic_prolongation_only = false);
2511
2512 /**
2513 * Vector of projection matrices. See get_restriction_matrix() above. The
2514 * constructor initializes these matrices to zero dimensions, which can be
2515 * changed by derived classes implementing them.
2516 *
2517 * Note, that <code>restriction[refinement_case-1][child]</code> includes
2518 * the restriction matrix of child <code>child</code> for the RefinementCase
2519 * <code>refinement_case</code>. Here, we use <code>refinement_case-1</code>
2520 * instead of <code>refinement_case</code> as for
2521 * RefinementCase::no_refinement(=0) there are no restriction matrices
2522 * available.
2523 */
2524 std::vector<std::vector<FullMatrix<double>>> restriction;
2525
2526 /**
2527 * Vector of embedding matrices. See <tt>get_prolongation_matrix()</tt>
2528 * above. The constructor initializes these matrices to zero dimensions,
2529 * which can be changed by derived classes implementing them.
2530 *
2531 * Note, that <code>prolongation[refinement_case-1][child]</code> includes
2532 * the prolongation matrix of child <code>child</code> for the
2533 * RefinementCase <code>refinement_case</code>. Here, we use
2534 * <code>refinement_case-1</code> instead of <code>refinement_case</code> as
2535 * for RefinementCase::no_refinement(=0) there are no prolongation matrices
2536 * available.
2537 */
2538 std::vector<std::vector<FullMatrix<double>>> prolongation;
2539
2540 /**
2541 * Specify the constraints which the dofs on the two sides of a cell
2542 * interface underlie if the line connects two cells of which one is refined
2543 * once.
2544 *
2545 * For further details see the general description of the derived class.
2546 *
2547 * This field is obviously useless in one dimension and has there a zero
2548 * size.
2549 */
2550 FullMatrix<double> interface_constraints;
2551
2552 /**
2553 * List of support points on the unit cell, in case the finite element has
2554 * any. The constructor leaves this field empty, derived classes may write
2555 * in some contents.
2556 *
2557 * Finite elements that allow some kind of interpolation operation usually
2558 * have support points. On the other hand, elements that define their
2559 * degrees of freedom by, for example, moments on faces, or as derivatives,
2560 * don't have support points. In that case, this field remains empty.
2561 */
2562 std::vector<Point<dim>> unit_support_points;
2563
2564 /**
2565 * Same for the faces. See the description of the
2566 * get_unit_face_support_points() function for a discussion of what
2567 * contributes a face support point.
2568 */
2569 std::vector<std::vector<Point<dim - 1>>> unit_face_support_points;
2570
2571 /**
2572 * Support points used for interpolation functions of non-Lagrangian
2573 * elements.
2574 */
2575 std::vector<Point<dim>> generalized_support_points;
2576
2577 /**
2578 * Face support points used for interpolation functions of non-Lagrangian
2579 * elements.
2580 */
2581 std::vector<std::vector<Point<dim - 1>>> generalized_face_support_points;
2582
2583 /**
2584 * For faces with non-standard face_orientation in 3d, the dofs on faces
2585 * (quads) have to be permuted in order to be combined with the correct
2586 * shape functions. Given a local dof @p index on a quad, return the shift
2587 * in the local index, if the face has non-standard face_orientation, i.e.
2588 * <code>old_index + shift = new_index</code>. In 2d and 1d there is no need
2589 * for permutation so the vector is empty. In 3d it has the size of <code>
2590 * #dofs_per_quad * 8 </code>, where 8 is the number of orientations, a face
2591 * can be in (all combinations of the three bool flags face_orientation,
2592 * face_flip and face_rotation).
2593 *
2594 * The constructor of this class fills this table with zeros, i.e.,
2595 * no permutation at all. Derived finite element classes have to
2596 * fill this Table with the correct values.
2597 */
2598 std::vector<Table<2, int>> adjust_quad_dof_index_for_face_orientation_table;
2599
2600 /**
2601 * For lines with non-standard orientation in 2d or 3d, the dofs on lines
2602 * have to be permuted in order to be combined with the correct shape
2603 * functions. Given a local dof @p index on a line, return the shift in the
2604 * local index, if the line has non-standard line_orientation, i.e.
2605 * <code>old_index + shift = new_index</code>.
2606 *
2607 * The constructor of this class fills this table with zeros, i.e.,
2608 * no permutation at all. Derived finite element classes have to
2609 * fill this vector with the correct values.
2610 */
2611 std::vector<int> adjust_line_dof_index_for_line_orientation_table;
2612
2613 /**
2614 * Store what system_to_component_index() will return.
2615 */
2616 std::vector<std::pair<unsigned int, unsigned int>> system_to_component_table;
2617
2618 /**
2619 * Map between linear dofs and component dofs on face. This is filled with
2620 * default values in the constructor, but derived classes will have to
2621 * overwrite the information if necessary.
2622 *
2623 * By component, we mean the vector component, not the base element. The
2624 * information thus makes only sense if a shape function is non-zero in only
2625 * one component.
2626 */
2627 std::vector<std::vector<std::pair<unsigned int, unsigned int>>>
2628 face_system_to_component_table;
2629
2630 /**
2631 * For each shape function, store to which base element and which instance
2632 * of this base element (in case its multiplicity is greater than one) it
2633 * belongs, and its index within this base element. If the element is not
2634 * composed of others, then base and instance are always zero, and the index
2635 * is equal to the number of the shape function. If the element is composed
2636 * of single instances of other elements (i.e. all with multiplicity one)
2637 * all of which are scalar, then base values and dof indices within this
2638 * element are equal to the #system_to_component_table. It differs only in
2639 * case the element is composed of other elements and at least one of them
2640 * is vector-valued itself.
2641 *
2642 * This array has valid values also in the case of vector-valued (i.e.
2643 * non-primitive) shape functions, in contrast to the
2644 * #system_to_component_table.
2645 */
2646 std::vector<std::pair<std::pair<unsigned int, unsigned int>, unsigned int>>
2647 system_to_base_table;
2648
2649 /**
2650 * Likewise for the indices on faces.
2651 */
2652 std::vector<
2653 std::vector<std::pair<std::pair<unsigned int, unsigned int>, unsigned int>>>
2654 face_system_to_base_table;
2655
2656 /**
2657 * For each base element, store the number of blocks generated by the base
2658 * and the first block in a block vector it will generate.
2659 */
2660 BlockIndices base_to_block_indices;
2661
2662 /**
2663 * The base element establishing a component.
2664 *
2665 * For each component number <tt>c</tt>, the entries have the following
2666 * meaning: <dl> <dt><tt>table[c].first.first</tt></dt> <dd>Number of the
2667 * base element for <tt>c</tt>. This is the index you can pass to
2668 * base_element().</dd> <dt><tt>table[c].first.second</tt></dt>
2669 * <dd>Component within the base element for <tt>c</tt>. This value is
2670 * between 0 and the n_components() of this base element.</dd>
2671 * <dt><tt>table[c].second</tt></dt> <dd>Index of the multiple of the base
2672 * element that contains <tt>c</tt>. This value is between 0 and the
2673 * element_multiplicity() of this base element.</dd> </dl>
2674 *
2675 * This variable is set to the correct size by the constructor of this
2676 * class, but needs to be initialized by derived classes, unless its size is
2677 * one and the only entry is a zero, which is the case for scalar elements.
2678 * In that case, the initialization by the base class is sufficient.
2679 *
2680 * @note This table is filled by FETools::Compositing::build_cell_tables().
2681 */
2682 std::vector<std::pair<std::pair<unsigned int, unsigned int>, unsigned int>>
2683 component_to_base_table;
2684
2685 /**
2686 * A flag determining whether restriction matrices are to be concatenated or
2687 * summed up. See the discussion about restriction matrices in the general
2688 * class documentation for more information.
2689 */
2690 const std::vector<bool> restriction_is_additive_flags;
2691
2692 /**
2693 * For each shape function, give a vector of bools (with size equal to the
2694 * number of vector components which this finite element has) indicating in
2695 * which component each of these shape functions is non-zero.
2696 *
2697 * For primitive elements, there is only one non-zero component.
2698 */
2699 const std::vector<ComponentMask> nonzero_components;
2700
2701 /**
2702 * This array holds how many values in the respective entry of the
2703 * #nonzero_components element are non-zero. The array is thus a short-cut
2704 * to allow faster access to this information than if we had to count the
2705 * non-zero entries upon each request for this information. The field is
2706 * initialized in the constructor of this class.
2707 */
2708 const std::vector<unsigned int> n_nonzero_components_table;
2709
2710 /**
2711 * Store whether all shape functions are primitive. Since finding this out
2712 * is a very common operation, we cache the result, i.e. compute the value
2713 * in the constructor for simpler access.
2714 */
2715 const bool cached_primitivity;
2716
2717 /**
2718 * This table is returned by get_local_dof_sparsity_pattern(). Its meaning
2719 * is described there in detail. This variable has to be
2720 * filled by any class derived from FiniteElement that does not want to keep
2721 * the default empty table (meaning all DoFs couple within the cell).
2722 */
2723 Table<2, bool> local_dof_sparsity_pattern;
2724
2725 /**
2726 * Return the size of interface constraint matrices. Since this is
2727 * needed in every derived finite element class when initializing
2728 * their size, it is placed into this function, to avoid having to
2729 * recompute the dimension-dependent size of these matrices each
2730 * time.
2731 *
2732 * Note that some elements do not implement the interface constraints for
2733 * certain polynomial degrees. In this case, this function still returns the
2734 * size these matrices should have when implemented, but the actual matrices
2735 * are empty.
2736 */
2737 TableIndices<2>
2738 interface_constraints_size() const;
2739
2740 /**
2741 * Given the pattern of nonzero components for each shape function, compute
2742 * for each entry how many components are non-zero for each shape function.
2743 * This function is used in the constructor of this class.
2744 */
2745 static std::vector<unsigned int>
2746 compute_n_nonzero_components(
2747 const std::vector<ComponentMask> &nonzero_components);
2748
2749 /**
2750 * Given a set of update flags, compute which other quantities <i>also</i>
2751 * need to be computed in order to satisfy the request by the given flags.
2752 * Then return the combination of the original set of flags and those just
2753 * computed.
2754 *
2755 * As an example, if @p update_flags contains update_gradients a finite
2756 * element class will typically require the computation of the inverse of
2757 * the Jacobian matrix in order to rotate the gradient of shape functions on
2758 * the reference cell to the real cell. It would then return not just
2759 * update_gradients, but also update_covariant_transformation, the flag that
2760 * makes the mapping class produce the inverse of the Jacobian matrix.
2761 *
2762 * An extensive discussion of the interaction between this function and
2763 * FEValues can be found in the
2764 * @ref FE_vs_Mapping_vs_FEValues
2765 * documentation topic.
2766 *
2767 * @see UpdateFlags
2768 */
2769 virtual UpdateFlags
2770 requires_update_flags(const UpdateFlags update_flags) const = 0;
2771
2772 /**
2773 * Create an internal data object and return a pointer to it of which the
2774 * caller of this function then assumes ownership. This object will then be
2775 * passed to the FiniteElement::fill_fe_values() every time the finite
2776 * element shape functions and their derivatives are evaluated on a concrete
2777 * cell. The object created here is therefore used by derived classes as a
2778 * place for scratch objects that are used in evaluating shape functions, as
2779 * well as to store information that can be pre-computed once and re-used on
2780 * every cell (e.g., for evaluating the values and gradients of shape
2781 * functions on the reference cell, for later re-use when transforming these
2782 * values to a concrete cell).
2783 *
2784 * This function is the first one called in the process of initializing a
2785 * FEValues object for a given mapping and finite element object. The
2786 * returned object will later be passed to FiniteElement::fill_fe_values()
2787 * for a concrete cell, which will itself place its output into an object of
2788 * type internal::FEValuesImplementation::FiniteElementRelatedData. Since
2789 * there may be data that can already be computed in its <i>final</i> form on
2790 * the reference cell, this function also receives a reference to the
2791 * internal::FEValuesImplementation::FiniteElementRelatedData object as its
2792 * last argument. This output argument is guaranteed to always be the same one
2793 * when used with the InternalDataBase object returned by this function. In
2794 * other words, the subdivision of scratch data and final data in the returned
2795 * object and the @p output_data object is as follows: If data can be
2796 * pre-computed on the reference cell in the exact form in which it will later
2797 * be needed on a concrete cell, then this function should already emplace
2798 * it in the @p output_data object. An example are the values of shape
2799 * functions at quadrature points for the usual Lagrange elements which on a
2800 * concrete cell are identical to the ones on the reference cell. On the
2801 * other hand, if some data can be pre-computed to make computations on a
2802 * concrete cell <i>cheaper</i>, then it should be put into the returned
2803 * object for later re-use in a derive class's implementation of
2804 * FiniteElement::fill_fe_values(). An example are the gradients of shape
2805 * functions on the reference cell for Lagrange elements: to compute the
2806 * gradients of the shape functions on a concrete cell, one has to multiply
2807 * the gradients on the reference cell by the inverse of the Jacobian of the
2808 * mapping; consequently, we cannot already compute the gradients on a
2809 * concrete cell at the time the current function is called, but we can at
2810 * least pre-compute the gradients on the reference cell, and store it in
2811 * the object returned.
2812 *
2813 * An extensive discussion of the interaction between this function and
2814 * FEValues can be found in the
2815 * @ref FE_vs_Mapping_vs_FEValues
2816 * documentation topic. See also the documentation of the InternalDataBase
2817 * class.
2818 *
2819 * @param[in] update_flags A set of UpdateFlags values that describe what
2820 * kind of information the FEValues object requests the finite element to
2821 * compute. This set of flags may also include information that the finite
2822 * element can not compute, e.g., flags that pertain to data produced by the
2823 * mapping. An implementation of this function needs to set up all data
2824 * fields in the returned object that are necessary to produce the
2825 * finite-element related data specified by these flags, and may already
2826 * pre-compute part of this information as discussed above. Elements may
2827 * want to
2828 * store these update flags (or a subset of these flags) in
2829 * InternalDataBase::update_each so they know at the time when
2830 * FiniteElement::fill_fe_values() is called what they are supposed to
2831 * compute
2832 * @param[in] mapping A reference to the mapping used for computing values
2833 * and derivatives of shape functions.
2834 * @param[in] quadrature A reference to the object that describes where the
2835 * shape functions should be evaluated.
2836 * @param[out] output_data A reference to the object that FEValues will use
2837 * in conjunction with the object returned here and where an implementation
2838 * of FiniteElement::fill_fe_values() will place the requested information.
2839 * This allows the current function to already pre-compute pieces of
2840 * information that can be computed on the reference cell, as discussed
2841 * above. FEValues guarantees that this output object and the object
2842 * returned by the current function will always be used together.
2843 * @return A pointer to an object of a type derived from InternalDataBase
2844 * and that derived classes can use to store scratch data that can be
2845 * pre-computed, or for scratch arrays that then only need to be allocated
2846 * once. The calling site assumes ownership of this object and will delete it
2847 * when it is no longer necessary.
2848 */
2849 virtual std::unique_ptr<InternalDataBase>
2850 get_data(const UpdateFlags update_flags,
2851 const Mapping<dim, spacedim> &mapping,
2852 const Quadrature<dim> &quadrature,
2853 dealii::internal::FEValuesImplementation::
2854 FiniteElementRelatedData<dim, spacedim> &output_data) const = 0;
2855
2856 /**
2857 * Like get_data(), but return an object that will later be used for
2858 * evaluating shape function information at quadrature points on faces of
2859 * cells. The object will then be used in calls to implementations of
2860 * FiniteElement::fill_fe_face_values(). See the documentation of get_data()
2861 * for more information.
2862 *
2863 * The default implementation of this function converts the face quadrature
2864 * into a cell quadrature with appropriate quadrature point locations, and
2865 * with that calls the get_data() function above that has to be implemented
2866 * in derived classes.
2867 *
2868 * @param[in] update_flags A set of UpdateFlags values that describe what
2869 * kind of information the FEValues object requests the finite element to
2870 * compute. This set of flags may also include information that the finite
2871 * element can not compute, e.g., flags that pertain to data produced by the
2872 * mapping. An implementation of this function needs to set up all data
2873 * fields in the returned object that are necessary to produce the
2874 * finite-element related data specified by these flags, and may already
2875 * pre-compute part of this information as discussed above. Elements may
2876 * want to
2877 * store these update flags (or a subset of these flags) in
2878 * InternalDataBase::update_each so they know at the time when
2879 * FiniteElement::fill_fe_face_values() is called what they are supposed to
2880 * compute
2881 * @param[in] mapping A reference to the mapping used for computing values
2882 * and derivatives of shape functions.
2883 * @param[in] quadrature A reference to the object that describes where the
2884 * shape functions should be evaluated.
2885 * @param[out] output_data A reference to the object that FEValues will use
2886 * in conjunction with the object returned here and where an implementation
2887 * of FiniteElement::fill_fe_face_values() will place the requested
2888 * information. This allows the current function to already pre-compute
2889 * pieces of information that can be computed on the reference cell, as
2890 * discussed above. FEValues guarantees that this output object and the
2891 * object returned by the current function will always be used together.
2892 * @return A pointer to an object of a type derived from InternalDataBase
2893 * and that derived classes can use to store scratch data that can be
2894 * pre-computed, or for scratch arrays that then only need to be allocated
2895 * once. The calling site assumes ownership of this object and will
2896 * delete it when it is no longer necessary.
2897 */
2898 virtual std::unique_ptr<InternalDataBase>
2899 get_face_data(const UpdateFlags update_flags,
2900 const Mapping<dim, spacedim> &mapping,
2901 const hp::QCollection<dim - 1> &quadrature,
2902 dealii::internal::FEValuesImplementation::
2903 FiniteElementRelatedData<dim, spacedim> &output_data) const;
2904
2905 /**
2906 * @deprecated Use the version taking a hp::QCollection argument.
2907 */
2908 virtual std::unique_ptr<InternalDataBase>
2909 get_face_data(
2910 const UpdateFlags update_flags,
2911 const Mapping<dim, spacedim> &mapping,
2912 const Quadrature<dim - 1> &quadrature,
2913 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
2914 &output_data) const;
2915
2916 /**
2917 * Like get_data(), but return an object that will later be used for
2918 * evaluating shape function information at quadrature points on children of
2919 * faces of cells. The object will then be used in calls to implementations
2920 * of FiniteElement::fill_fe_subface_values(). See the documentation of
2921 * get_data() for more information.
2922 *
2923 * The default implementation of this function converts the face quadrature
2924 * into a cell quadrature with appropriate quadrature point locations, and
2925 * with that calls the get_data() function above that has to be implemented
2926 * in derived classes.
2927 *
2928 * @param[in] update_flags A set of UpdateFlags values that describe what
2929 * kind of information the FEValues object requests the finite element to
2930 * compute. This set of flags may also include information that the finite
2931 * element can not compute, e.g., flags that pertain to data produced by the
2932 * mapping. An implementation of this function needs to set up all data
2933 * fields in the returned object that are necessary to produce the
2934 * finite-element related data specified by these flags, and may already
2935 * pre-compute part of this information as discussed above. Elements may
2936 * want to
2937 * store these update flags (or a subset of these flags) in
2938 * InternalDataBase::update_each so they know at the time when
2939 * FiniteElement::fill_fe_subface_values() is called what they are supposed
2940 * to compute
2941 * @param[in] mapping A reference to the mapping used for computing values
2942 * and derivatives of shape functions.
2943 * @param[in] quadrature A reference to the object that describes where the
2944 * shape functions should be evaluated.
2945 * @param[out] output_data A reference to the object that FEValues will use
2946 * in conjunction with the object returned here and where an implementation
2947 * of FiniteElement::fill_fe_subface_values() will place the requested
2948 * information. This allows the current function to already pre-compute
2949 * pieces of information that can be computed on the reference cell, as
2950 * discussed above. FEValues guarantees that this output object and the
2951 * object returned by the current function will always be used together.
2952 * @return A pointer to an object of a type derived from InternalDataBase
2953 * and that derived classes can use to store scratch data that can be
2954 * pre-computed, or for scratch arrays that then only need to be allocated
2955 * once.
2956 * The calling site assumes ownership of this object and will delete it when
2957 * it is no longer necessary.
2958 */
2959 virtual std::unique_ptr<InternalDataBase>
2960 get_subface_data(
2961 const UpdateFlags update_flags,
2962 const Mapping<dim, spacedim> &mapping,
2963 const Quadrature<dim - 1> &quadrature,
2964 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
2965 spacedim>
2966 &output_data) const;
2967
2968 /**
2969 * Compute information about the shape functions on the cell denoted by the
2970 * first argument. Derived classes will have to implement this function
2971 * based on the kind of element they represent. It is called by
2972 * FEValues::reinit().
2973 *
2974 * Conceptually, this function evaluates shape functions and their
2975 * derivatives at the quadrature points represented by the mapped locations
2976 * of those described by the quadrature argument to this function. In many
2977 * cases, computing derivatives of shape functions (and in some cases also
2978 * computing values of shape functions) requires making use of the mapping
2979 * from the reference to the real cell; this information can either be taken
2980 * from the @p mapping_data object that has been filled for the current cell
2981 * before this function is called, or by calling the member functions of a
2982 * Mapping object with the @p mapping_internal object that also corresponds
2983 * to the current cell.
2984 *
2985 * The information computed by this function is used to fill the various
2986 * member variables of the output argument of this function. Which of the
2987 * member variables of that structure should be filled is determined by the
2988 * update flags stored in the FiniteElement::InternalDataBase::update_each
2989 * field of the object passed to this function. These flags are typically
2990 * set by FiniteElement::get_data(), FiniteElement::get_face_date() and
2991 * FiniteElement::get_subface_data() (or, more specifically, implementations
2992 * of these functions in derived classes).
2993 *
2994 * An extensive discussion of the interaction between this function and
2995 * FEValues can be found in the
2996 * @ref FE_vs_Mapping_vs_FEValues
2997 * documentation topic.
2998 *
2999 * @param[in] cell The cell of the triangulation for which this function is
3000 * to compute a mapping from the reference cell to.
3001 * @param[in] cell_similarity Whether or not the cell given as first
3002 * argument is simply a translation, rotation, etc of the cell for which
3003 * this function was called the most recent time. This information is
3004 * computed simply by matching the vertices (as stored by the Triangulation)
3005 * between the previous and the current cell. The value passed here may be
3006 * modified by implementations of this function and should then be returned
3007 * (see the discussion of the return value of this function).
3008 * @param[in] quadrature A reference to the quadrature formula in use for
3009 * the current evaluation. This quadrature object is the same as the one
3010 * used when creating the @p internal_data object. The current object is
3011 * then responsible for evaluating shape functions at the mapped locations
3012 * of the quadrature points represented by this object.
3013 * @param[in] mapping A reference to the mapping object used to map from the
3014 * reference cell to the current cell. This object was used to compute the
3015 * information in the @p mapping_data object before the current function was
3016 * called. It is also the mapping object that created the @p
3017 * mapping_internal object via Mapping::get_data(). You will need the
3018 * reference to this mapping object most often to call Mapping::transform()
3019 * to transform gradients and higher derivatives from the reference to the
3020 * current cell.
3021 * @param[in] mapping_internal An object specific to the mapping object.
3022 * What the mapping chooses to store in there is of no relevance to the
3023 * current function, but you may have to pass a reference to this object to
3024 * certain functions of the Mapping class (e.g., Mapping::transform()) if
3025 * you need to call them from the current function.
3026 * @param[in] mapping_data The output object into which the
3027 * Mapping::fill_fe_values() function wrote the mapping information
3028 * corresponding to the current cell. This includes, for example, Jacobians
3029 * of the mapping that may be of relevance to the current function, as well
3030 * as other information that FEValues::reinit() requested from the mapping.
3031 * @param[in] fe_internal A reference to an object previously created by
3032 * get_data() and that may be used to store information the mapping can
3033 * compute once on the reference cell. See the documentation of the
3034 * FiniteElement::InternalDataBase class for an extensive description of the
3035 * purpose of these objects.
3036 * @param[out] output_data A reference to an object whose member variables
3037 * should be computed. Not all of the members of this argument need to be
3038 * filled; which ones need to be filled is determined by the update flags
3039 * stored inside the @p fe_internal object.
3040 *
3041 * @note FEValues ensures that this function is always called with the same
3042 * pair of @p fe_internal and @p output_data objects. In other words, if an
3043 * implementation of this function knows that it has written a piece of data
3044 * into the output argument in a previous call, then there is no need to
3045 * copy it there again in a later call if the implementation knows that this
3046 * is the same value.
3047 */
3048 virtual void
3049 fill_fe_values(
3050 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
3051 const CellSimilarity::Similarity cell_similarity,
3052 const Quadrature<dim> &quadrature,
3053 const Mapping<dim, spacedim> &mapping,
3054 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
3055 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
3056 &mapping_data,
3057 const InternalDataBase &fe_internal,
3058 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
3059 spacedim>
3060 &output_data) const = 0;
3061
3062 /**
3063 * This function is the equivalent to FiniteElement::fill_fe_values(), but
3064 * for faces of cells. See there for an extensive discussion of its purpose.
3065 * It is called by FEFaceValues::reinit().
3066 *
3067 * @param[in] cell The cell of the triangulation for which this function is
3068 * to compute a mapping from the reference cell to.
3069 * @param[in] face_no The number of the face we are currently considering,
3070 * indexed among the faces of the cell specified by the previous argument.
3071 * @param[in] quadrature A reference to the quadrature formula in use for
3072 * the current evaluation. This quadrature object is the same as the one
3073 * used when creating the @p internal_data object. The current object is
3074 * then responsible for evaluating shape functions at the mapped locations
3075 * of the quadrature points represented by this object.
3076 * @param[in] mapping A reference to the mapping object used to map from the
3077 * reference cell to the current cell. This object was used to compute the
3078 * information in the @p mapping_data object before the current function was
3079 * called. It is also the mapping object that created the @p
3080 * mapping_internal object via Mapping::get_data(). You will need the
3081 * reference to this mapping object most often to call Mapping::transform()
3082 * to transform gradients and higher derivatives from the reference to the
3083 * current cell.
3084 * @param[in] mapping_internal An object specific to the mapping object.
3085 * What the mapping chooses to store in there is of no relevance to the
3086 * current function, but you may have to pass a reference to this object to
3087 * certain functions of the Mapping class (e.g., Mapping::transform()) if
3088 * you need to call them from the current function.
3089 * @param[in] mapping_data The output object into which the
3090 * Mapping::fill_fe_values() function wrote the mapping information
3091 * corresponding to the current cell. This includes, for example, Jacobians
3092 * of the mapping that may be of relevance to the current function, as well
3093 * as other information that FEValues::reinit() requested from the mapping.
3094 * @param[in] fe_internal A reference to an object previously created by
3095 * get_data() and that may be used to store information the mapping can
3096 * compute once on the reference cell. See the documentation of the
3097 * FiniteElement::InternalDataBase class for an extensive description of the
3098 * purpose of these objects.
3099 * @param[out] output_data A reference to an object whose member variables
3100 * should be computed. Not all of the members of this argument need to be
3101 * filled; which ones need to be filled is determined by the update flags
3102 * stored inside the @p fe_internal object.
3103 */
3104 virtual void
3105 fill_fe_face_values(
3106 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
3107 const unsigned int face_no,
3108 const hp::QCollection<dim - 1> &quadrature,
3109 const Mapping<dim, spacedim> &mapping,
3110 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
3111 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
3112 &mapping_data,
3113 const InternalDataBase &fe_internal,
3114 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
3115 spacedim>
3116 &output_data) const;
3117
3118 /**
3119 * @deprecated Use the version taking a hp::QCollection argument.
3120 */
3121 virtual void
3122 fill_fe_face_values(
3123 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
3124 const unsigned int face_no,
3125 const Quadrature<dim - 1> &quadrature,
3126 const Mapping<dim, spacedim> &mapping,
3127 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
3128 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
3129 &mapping_data,
3130 const InternalDataBase &fe_internal,
3131 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
3132 &output_data) const;
3133
3134 /**
3135 * This function is the equivalent to FiniteElement::fill_fe_values(), but
3136 * for the children of faces of cells. See there for an extensive discussion
3137 * of its purpose. It is called by FESubfaceValues::reinit().
3138 *
3139 * @param[in] cell The cell of the triangulation for which this function is
3140 * to compute a mapping from the reference cell to.
3141 * @param[in] face_no The number of the face we are currently considering,
3142 * indexed among the faces of the cell specified by the previous argument.
3143 * @param[in] sub_no The number of the subface, i.e., the number of the
3144 * child of a face, that we are currently considering, indexed among the
3145 * children of the face specified by the previous argument.
3146 * @param[in] quadrature A reference to the quadrature formula in use for
3147 * the current evaluation. This quadrature object is the same as the one
3148 * used when creating the @p internal_data object. The current object is
3149 * then responsible for evaluating shape functions at the mapped locations
3150 * of the quadrature points represented by this object.
3151 * @param[in] mapping A reference to the mapping object used to map from the
3152 * reference cell to the current cell. This object was used to compute the
3153 * information in the @p mapping_data object before the current function was
3154 * called. It is also the mapping object that created the @p
3155 * mapping_internal object via Mapping::get_data(). You will need the
3156 * reference to this mapping object most often to call Mapping::transform()
3157 * to transform gradients and higher derivatives from the reference to the
3158 * current cell.
3159 * @param[in] mapping_internal An object specific to the mapping object.
3160 * What the mapping chooses to store in there is of no relevance to the
3161 * current function, but you may have to pass a reference to this object to
3162 * certain functions of the Mapping class (e.g., Mapping::transform()) if
3163 * you need to call them from the current function.
3164 * @param[in] mapping_data The output object into which the
3165 * Mapping::fill_fe_values() function wrote the mapping information
3166 * corresponding to the current cell. This includes, for example, Jacobians
3167 * of the mapping that may be of relevance to the current function, as well
3168 * as other information that FEValues::reinit() requested from the mapping.
3169 * @param[in] fe_internal A reference to an object previously created by
3170 * get_data() and that may be used to store information the mapping can
3171 * compute once on the reference cell. See the documentation of the
3172 * FiniteElement::InternalDataBase class for an extensive description of the
3173 * purpose of these objects.
3174 * @param[out] output_data A reference to an object whose member variables
3175 * should be computed. Not all of the members of this argument need to be
3176 * filled; which ones need to be filled is determined by the update flags
3177 * stored inside the @p fe_internal object.
3178 */
3179 virtual void
3180 fill_fe_subface_values(
3181 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
3182 const unsigned int face_no,
3183 const unsigned int sub_no,
3184 const Quadrature<dim - 1> &quadrature,
3185 const Mapping<dim, spacedim> &mapping,
3186 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
3187 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
3188 &mapping_data,
3189 const InternalDataBase &fe_internal,
3190 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
3191 spacedim>
3192 &output_data) const = 0;
3193
3194 friend class InternalDataBase;
3195 friend class FEValuesBase<dim, spacedim>;
3196 friend class FEValues<dim, spacedim>;
3197 friend class FEFaceValues<dim, spacedim>;
3198 friend class FESubfaceValues<dim, spacedim>;
3199 friend class NonMatching::FEImmersedSurfaceValues<dim>;
3200 friend class FESystem<dim, spacedim>;
3201
3202 // explicitly check for sensible template arguments, but not on windows
3203 // because MSVC creates bogus warnings during normal compilation
3204 #ifndef DEAL_II_MSVC
3205 static_assert(dim <= spacedim,
3206 "The dimension <dim> of a FiniteElement must be less than or "
3207 "equal to the space dimension <spacedim> in which it lives.");
3208 #endif
3209 };
3210
3211
3212 //----------------------------------------------------------------------//
3213 #ifndef DOXYGEN
3214
3215 template <int dim, int spacedim>
3216 inline std::pair<unsigned int, unsigned int>
3217 FiniteElement<dim, spacedim>::system_to_component_index(
3218 const unsigned int index) const
3219 {
3220 AssertIndexRange(index, system_to_component_table.size());
3221 Assert(is_primitive(index),
3222 (typename FiniteElement<dim, spacedim>::ExcShapeFunctionNotPrimitive(
3223 index)));
3224 return system_to_component_table[index];
3225 }
3226
3227
3228
3229 template <int dim, int spacedim>
3230 inline unsigned int
3231 FiniteElement<dim, spacedim>::n_base_elements() const
3232 {
3233 return base_to_block_indices.size();
3234 }
3235
3236
3237
3238 template <int dim, int spacedim>
3239 inline unsigned int
3240 FiniteElement<dim, spacedim>::element_multiplicity(
3241 const unsigned int index) const
3242 {
3243 return static_cast<unsigned int>(base_to_block_indices.block_size(index));
3244 }
3245
3246
3247
3248 template <int dim, int spacedim>
3249 inline unsigned int
3250 FiniteElement<dim, spacedim>::component_to_system_index(
3251 const unsigned int component,
3252 const unsigned int index) const
3253 {
3254 AssertIndexRange(component, this->n_components());
3255 const std::vector<std::pair<unsigned int, unsigned int>>::const_iterator it =
3256 std::find(system_to_component_table.begin(),
3257 system_to_component_table.end(),
3258 std::pair<unsigned int, unsigned int>(component, index));
3259
3260 Assert(it != system_to_component_table.end(),
3261 ExcMessage("You are asking for the number of the shape function "
3262 "within a system element that corresponds to vector "
3263 "component " +
3264 Utilities::int_to_string(component) +
3265 " and within this to "
3266 "index " +
3267 Utilities::int_to_string(index) +
3268 ". But no such "
3269 "shape function exists."));
3270 return std::distance(system_to_component_table.begin(), it);
3271 }
3272
3273
3274
3275 template <int dim, int spacedim>
3276 inline std::pair<unsigned int, unsigned int>
3277 FiniteElement<dim, spacedim>::face_system_to_component_index(
3278 const unsigned int index,
3279 const unsigned int face_no) const
3280 {
3281 AssertIndexRange(
3282 index,
3283 face_system_to_component_table[this->n_unique_faces() == 1 ? 0 : face_no]
3284 .size());
3285
3286 // in debug mode, check whether the
3287 // function is primitive, since
3288 // otherwise the result may have no
3289 // meaning
3290 //
3291 // since the primitivity tables are
3292 // all geared towards cell dof
3293 // indices, rather than face dof
3294 // indices, we have to work a
3295 // little bit...
3296 //
3297 // in 1d, the face index is equal
3298 // to the cell index
3299 Assert(is_primitive(this->face_to_cell_index(index, face_no)),
3300 (typename FiniteElement<dim, spacedim>::ExcShapeFunctionNotPrimitive(
3301 index)));
3302
3303 return face_system_to_component_table[this->n_unique_faces() == 1 ?
3304 0 :
3305 face_no][index];
3306 }
3307
3308
3309
3310 template <int dim, int spacedim>
3311 inline std::pair<std::pair<unsigned int, unsigned int>, unsigned int>
3312 FiniteElement<dim, spacedim>::system_to_base_index(
3313 const unsigned int index) const
3314 {
3315 AssertIndexRange(index, system_to_base_table.size());
3316 return system_to_base_table[index];
3317 }
3318
3319
3320
3321 template <int dim, int spacedim>
3322 inline std::pair<std::pair<unsigned int, unsigned int>, unsigned int>
3323 FiniteElement<dim, spacedim>::face_system_to_base_index(
3324 const unsigned int index,
3325 const unsigned int face_no) const
3326 {
3327 AssertIndexRange(
3328 index,
3329 face_system_to_base_table[this->n_unique_faces() == 1 ? 0 : face_no]
3330 .size());
3331 return face_system_to_base_table[this->n_unique_faces() == 1 ? 0 : face_no]
3332 [index];
3333 }
3334
3335
3336
3337 template <int dim, int spacedim>
3338 inline types::global_dof_index
3339 FiniteElement<dim, spacedim>::first_block_of_base(
3340 const unsigned int index) const
3341 {
3342 return base_to_block_indices.block_start(index);
3343 }
3344
3345
3346
3347 template <int dim, int spacedim>
3348 inline std::pair<unsigned int, unsigned int>
3349 FiniteElement<dim, spacedim>::component_to_base_index(
3350 const unsigned int index) const
3351 {
3352 AssertIndexRange(index, component_to_base_table.size());
3353
3354 return component_to_base_table[index].first;
3355 }
3356
3357
3358
3359 template <int dim, int spacedim>
3360 inline std::pair<unsigned int, unsigned int>
3361 FiniteElement<dim, spacedim>::block_to_base_index(
3362 const unsigned int index) const
3363 {
3364 return base_to_block_indices.global_to_local(index);
3365 }
3366
3367
3368
3369 template <int dim, int spacedim>
3370 inline std::pair<unsigned int, types::global_dof_index>
3371 FiniteElement<dim, spacedim>::system_to_block_index(
3372 const unsigned int index) const
3373 {
3374 AssertIndexRange(index, this->n_dofs_per_cell());
3375 // The block is computed simply as
3376 // first block of this base plus
3377 // the index within the base blocks
3378 return std::pair<unsigned int, types::global_dof_index>(
3379 first_block_of_base(system_to_base_table[index].first.first) +
3380 system_to_base_table[index].first.second,
3381 system_to_base_table[index].second);
3382 }
3383
3384
3385
3386 template <int dim, int spacedim>
3387 inline bool
3388 FiniteElement<dim, spacedim>::shape_function_belongs_to(
3389 const unsigned int shape_function,
3390 const FEValuesExtractors::Scalar &component) const
3391 {
3392 AssertIndexRange(shape_function, this->n_dofs_per_cell());
3393 AssertIndexRange(component.component, this->n_components());
3394
3395 if (is_primitive(shape_function))
3396 return (system_to_component_table[shape_function].first ==
3397 component.component);
3398 else
3399 return nonzero_components[shape_function][component.component];
3400 }
3401
3402
3403
3404 template <int dim, int spacedim>
3405 inline bool
3406 FiniteElement<dim, spacedim>::shape_function_belongs_to(
3407 const unsigned int shape_function,
3408 const FEValuesExtractors::Vector &components) const
3409 {
3410 AssertIndexRange(shape_function, this->n_dofs_per_cell());
3411 AssertIndexRange(components.first_vector_component, this->n_components());
3412 AssertIndexRange(components.first_vector_component + dim,
3413 this->n_components() + 1);
3414
3415 if (is_primitive(shape_function))
3416 return ((system_to_component_table[shape_function].first >=
3417 components.first_vector_component) &&
3418 (system_to_component_table[shape_function].first <
3419 components.first_vector_component + dim));
3420 else
3421 // Return whether there is overlap between the nonzero components
3422 // of the current shape function and the selected components of
3423 // the extractor:
3424 {
3425 for (unsigned int i = components.first_vector_component;
3426 i < components.first_vector_component + dim;
3427 ++i)
3428 if (nonzero_components[shape_function][i])
3429 return true;
3430 return false;
3431 }
3432 }
3433
3434
3435
3436 template <int dim, int spacedim>
3437 inline bool
3438 FiniteElement<dim, spacedim>::shape_function_belongs_to(
3439 const unsigned int shape_function,
3440 const FEValuesExtractors::SymmetricTensor<2> &components) const
3441 {
3442 AssertIndexRange(shape_function, this->n_dofs_per_cell());
3443 AssertIndexRange(components.first_tensor_component, this->n_components());
3444 AssertIndexRange(components.first_tensor_component + dim,
3445 this->n_components() + 1);
3446
3447 if (is_primitive(shape_function))
3448 return ((system_to_component_table[shape_function].first >=
3449 components.first_tensor_component) &&
3450 (system_to_component_table[shape_function].first <
3451 components.first_tensor_component +
3452 SymmetricTensor<2, dim>::n_independent_components));
3453 else
3454 // Return whether there is overlap between the nonzero components
3455 // of the current shape function and the selected components of
3456 // the extractor:
3457 {
3458 for (unsigned int i = components.first_tensor_component;
3459 i < components.first_tensor_component +
3460 SymmetricTensor<2, dim>::n_independent_components;
3461 ++i)
3462 if (nonzero_components[shape_function][i])
3463 return true;
3464 return false;
3465 }
3466 }
3467
3468
3469
3470 template <int dim, int spacedim>
3471 inline bool
3472 FiniteElement<dim, spacedim>::shape_function_belongs_to(
3473 const unsigned int shape_function,
3474 const FEValuesExtractors::Tensor<2> &components) const
3475 {
3476 AssertIndexRange(shape_function, this->n_dofs_per_cell());
3477 AssertIndexRange(components.first_tensor_component, this->n_components());
3478 AssertIndexRange(components.first_tensor_component + dim,
3479 this->n_components() + 1);
3480
3481 if (is_primitive(shape_function))
3482 return ((system_to_component_table[shape_function].first >=
3483 components.first_tensor_component) &&
3484 (system_to_component_table[shape_function].first <
3485 components.first_tensor_component +
3486 Tensor<2, dim>::n_independent_components));
3487 else
3488 // Return whether there is overlap between the nonzero components
3489 // of the current shape function and the selected components of
3490 // the extractor:
3491 {
3492 for (unsigned int i = components.first_tensor_component;
3493 i < components.first_tensor_component +
3494 Tensor<2, dim>::n_independent_components;
3495 ++i)
3496 if (nonzero_components[shape_function][i])
3497 return true;
3498 return false;
3499 }
3500 }
3501
3502
3503
3504 template <int dim, int spacedim>
3505 inline bool
3506 FiniteElement<dim, spacedim>::restriction_is_additive(
3507 const unsigned int index) const
3508 {
3509 AssertIndexRange(index, this->n_dofs_per_cell());
3510 return restriction_is_additive_flags[index];
3511 }
3512
3513
3514
3515 template <int dim, int spacedim>
3516 inline const ComponentMask &
3517 FiniteElement<dim, spacedim>::get_nonzero_components(const unsigned int i) const
3518 {
3519 AssertIndexRange(i, this->n_dofs_per_cell());
3520 return nonzero_components[i];
3521 }
3522
3523
3524
3525 template <int dim, int spacedim>
3526 inline unsigned int
3527 FiniteElement<dim, spacedim>::n_nonzero_components(const unsigned int i) const
3528 {
3529 AssertIndexRange(i, this->n_dofs_per_cell());
3530 return n_nonzero_components_table[i];
3531 }
3532
3533
3534
3535 template <int dim, int spacedim>
3536 inline bool
3537 FiniteElement<dim, spacedim>::is_primitive() const
3538 {
3539 return cached_primitivity;
3540 }
3541
3542
3543
3544 template <int dim, int spacedim>
3545 inline bool
3546 FiniteElement<dim, spacedim>::is_primitive(const unsigned int i) const
3547 {
3548 AssertIndexRange(i, this->n_dofs_per_cell());
3549
3550 // return primitivity of a shape
3551 // function by checking whether it
3552 // has more than one non-zero
3553 // component or not. we could cache
3554 // this value in an array of bools,
3555 // but accessing a bit-vector (as
3556 // std::vector<bool> is) is
3557 // probably more expensive than
3558 // just comparing against 1
3559 //
3560 // for good measure, short circuit the test
3561 // if the entire FE is primitive
3562 return (is_primitive() || (n_nonzero_components_table[i] == 1));
3563 }
3564
3565
3566
3567 template <int dim, int spacedim>
3568 inline const Table<2, bool> &
3569 FiniteElement<dim, spacedim>::get_local_dof_sparsity_pattern() const
3570 {
3571 return local_dof_sparsity_pattern;
3572 }
3573
3574
3575
3576 template <int dim, int spacedim>
3577 inline GeometryPrimitive
3578 FiniteElement<dim, spacedim>::get_associated_geometry_primitive(
3579 const unsigned int cell_dof_index) const
3580 {
3581 AssertIndexRange(cell_dof_index, this->n_dofs_per_cell());
3582
3583 // just go through the usual cases, taking into account how DoFs
3584 // are enumerated on the reference cell
3585 if (cell_dof_index < this->get_first_line_index())
3586 return GeometryPrimitive::vertex;
3587 else if (cell_dof_index < this->get_first_quad_index(0))
3588 return GeometryPrimitive::line;
3589 else if (cell_dof_index < this->get_first_hex_index())
3590 return GeometryPrimitive::quad;
3591 else
3592 return GeometryPrimitive::hex;
3593 }
3594
3595 #endif
3596
3597 DEAL_II_NAMESPACE_CLOSE
3598
3599 #endif