Debian Codegraph @

include/deal.II/fe/fe_system.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_system_h
16 #define dealii_fe_system_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/fe/fe.h>
21 #include <deal.II/fe/fe_tools.h>
22
23 #include <memory>
24 #include <type_traits>
25 #include <utility>
26 #include <vector>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 // Forward declaration
31 #ifndef DOXYGEN
32 template <int dim, int spacedim>
33 class FE_Enriched;
34 #endif
35
36 /**
37 * This class provides an interface to group several elements together into
38 * one, vector-valued element. As example, consider the Taylor-Hood element
39 * that is used for the solution of the Stokes and Navier-Stokes equations:
40 * There, the velocity (of which there are as many components as the dimension
41 * $d$ of the domain) is discretized with $Q_2$ elements and the pressure with
42 * $Q_1$ elements. Mathematically, the finite element space for the coupled
43 * problem is then often written as $V_h = Q_2^d \times Q_1$ where the
44 * exponentiation is understood to be the tensor product of spaces -- i.e.,
45 * in 2d, we have $V_h=Q_2\times Q_2\times Q_1$ -- and tensor products
46 * lead to vectors where each component of the vector-valued function
47 * space corresponds to a scalar function in one of the $Q_2$ or $Q_1$
48 * spaces. Using the FESystem class, this space is created using
49 * @code
50 * FESystem<dim> taylor_hood_fe (FE_Q<dim>(2)^dim, // velocity components
51 * FE_Q<dim>(1)); // pressure component
52 * @endcode
53 * The creation of this element here corresponds to taking tensor-product
54 * powers of the $Q_2$ element in the first line of the list of arguments
55 * to the FESystem constructor, and then concatenation via another tensor
56 * product with the element in the second line. This kind of construction
57 * is used, for example, in the step-22 tutorial program.
58 *
59 * Similarly, step-8 solves an elasticity equation where we need to solve
60 * for the displacement of a solid object. The displacement again has
61 * $d$ components if the domain is $d$-dimensional, and so the combined
62 * finite element is created using
63 * @code
64 * FESystem<dim> displacement_fe (FE_Q<dim>(1)^dim);
65 * @endcode
66 * where now each (vector) component of the combined element corresponds to
67 * a $Q_1$ space.
68 *
69 * To the outside world, FESystem objects look just like a usual
70 * finite element object, they just happen to be composed of several other
71 * finite elements that are possibly of different type. These "base elements"
72 * can themselves have multiple components and, in particular, could
73 * also be vector-valued -- for example, if one of the base elements
74 * is an FESystem itself (see also below). An example is given in the
75 * documentation of namespace FETools::Compositing, when using the
76 * "tensor product" strategy.
77 *
78 * %Vector valued elements are discussed in a number of
79 * tutorial programs, for example step-8, step-20, step-21, step-22, and in
80 * particular in the
81 * @ref vector_valued
82 * topic.
83 *
84 * @dealiiVideoLecture{19,20}
85 *
86 *
87 * <h3>FESystem, components and blocks</h3>
88 *
89 * An FESystem, except in the most trivial case, produces a vector-valued
90 * finite element with several components. The number of components
91 * n_components() corresponds to the dimension of the solution function in the
92 * PDE system, and correspondingly also to the number of equations your PDE
93 * system has. For example, the mixed Laplace system covered in step-20 has
94 * $d+1$ components in $d$ space dimensions: the scalar pressure and the $d$
95 * components of the velocity vector. Similarly, the elasticity equation
96 * covered in step-8 has $d$ components in $d$ space dimensions. In general,
97 * the number of components of a FESystem element is the accumulated number of
98 * components of all base elements times their multiplicities. A bit more on
99 * components is also given in the
100 * @ref GlossComponent "glossary entry on components".
101 *
102 * While the concept of components is important from the viewpoint of a
103 * partial differential equation, the finite element side looks a bit
104 * different Since not only FESystem, but also vector-valued elements like
105 * FE_RaviartThomas, have several components. The concept needed here is a
106 * @ref GlossBlock "block".
107 * Each block encompasses the set of degrees of freedom associated with a
108 * single base element of an FESystem, where base elements with multiplicities
109 * count multiple times. These blocks are usually addressed using the
110 * information in DoFHandler::block_info(). The number of blocks of a FESystem
111 * object is simply the sum of all multiplicities of base elements and is
112 * given by n_blocks().
113 *
114 * For example, the FESystem for the Taylor-Hood element for the
115 * three-dimensional Stokes problem can be built using the code
116 * @code
117 * const FE_Q<3> u(2);
118 * const FE_Q<3> p(1);
119 * FESystem<3> sys1(u,3, p,1);
120 * @endcode
121 * or more concisely via
122 * @code
123 * FESystem<3> sys1(FE_Q<3>(2),3,
124 * FE_Q<3>(1),1);
125 * @endcode
126 * or even shorter (mimicking the mathematical notation that we are dealing
127 * with a $Q_2^3 \times Q_1$ element):
128 * @code
129 * FESystem<3> sys1(FE_Q<3>(2)^3,
130 * FE_Q<3>(1));
131 * @endcode
132 *
133 * This example creates an FESystem @p sys1 with four components, three for
134 * the velocity components and one for the pressure, and also four blocks with
135 * the degrees of freedom of each of the velocity components and the pressure
136 * in a separate block each. The number of blocks is four since the first base
137 * element is repeated three times.
138 *
139 * On the other hand, a Taylor-Hood element can also be constructed using
140 *
141 * @code
142 * FESystem<3> U(u,3);
143 * FESystem<3> sys2(U, p);
144 * @endcode
145 *
146 * The FESystem @p sys2 created here has the same four components, but the
147 * degrees of freedom are distributed into only two blocks. The first block
148 * has all velocity degrees of freedom from @p U, while the second block
149 * contains the pressure degrees of freedom. Note that while @p U itself has 3
150 * blocks, the FESystem @p sys2 does not attempt to split @p U into its base
151 * elements but considers it a block of its own. By blocking all velocities
152 * into one system first as in @p sys2, we achieve the same block structure
153 * that would be generated if instead of using a $Q_2^3$ element for the
154 * velocities we had used vector-valued base elements, for instance like using
155 * a mixed discretization of Darcy's law using
156 *
157 * @code
158 * FE_RaviartThomas<3> u(1);
159 * FE_DGQ<3> p(1);
160 * FESystem<3> sys3(u, p);
161 * @endcode
162 *
163 * This example also produces a system with four components, but only two
164 * blocks.
165 *
166 * In most cases, the composed element behaves as if it were a usual element.
167 * It just has more degrees of freedom than most of the "common" elements.
168 * However the underlying structure is visible in the restriction,
169 * prolongation and interface constraint matrices, which do not couple the
170 * degrees of freedom of the base elements. E.g. the continuity requirement is
171 * imposed for the shape functions of the subobjects separately; no
172 * requirement exist between shape functions of different subobjects, i.e. in
173 * the above example: on a hanging node, the respective value of the @p u
174 * velocity is only coupled to @p u at the vertices and the line on the larger
175 * cell next to this vertex, but there is no interaction with @p v and @p w of
176 * this or the other cell.
177 *
178 *
179 * <h3>Internal information on numbering of degrees of freedom</h3>
180 *
181 * The overall numbering of degrees of freedom is as follows: for each 0d, 1d,
182 * 2d, or 3d subobject, the degrees of freedom are numbered such that we run
183 * over all subelements first, before turning for the next dof on this
184 * subobject or for the next subobject. For example, for an element of three
185 * components in one space dimension, the first two components being cubic
186 * lagrange elements and the third being a quadratic lagrange element, the
187 * ordering for the system <tt>s=(u,v,p)</tt> is:
188 *
189 * <ul>
190 * <li> First vertex: <tt>u0, v0, p0 = s0, s1, s2</tt>
191 * <li> Second vertex: <tt>u1, v1, p1 = s3, s4, s5</tt>
192 * <li> First component on the line: <tt>u2, u3 = s4, s5</tt>
193 * <li> Second component on the line: <tt>v2, v3 = s6, s7</tt>.
194 * <li> Third component on the line: <tt>p2 = s8</tt>.
195 * </ul>
196 * That said, you should not rely on this numbering in your application as
197 * these %internals might change in future. Rather use the functions
198 * system_to_component_index() and component_to_system_index().
199 *
200 * For more information on the template parameter <tt>spacedim</tt> see the
201 * documentation of Triangulation.
202 *
203 * @ingroup febase fe vector_valued
204 *
205 */
206 template <int dim, int spacedim = dim>
207 class FESystem : public FiniteElement<dim, spacedim>
208 {
209 public:
210 /**
211 * Delete default constructor so that `FESystem(FEPairs &&... fe_pairs)` is
212 * not accidentally picked if no FiniteElement is provided.
213 */
214 FESystem() = delete;
215
216 /**
217 * Constructor. Take a finite element and the number of elements you want to
218 * group together using this class.
219 *
220 * The object @p fe is not actually used for anything other than creating a
221 * copy that will then be owned by the current object. In other words, it is
222 * completely fine to call this constructor with a temporary object for the
223 * finite element, as in this code snippet:
224 * @code
225 * FESystem<dim> fe (FE_Q<dim>(2), 2);
226 * @endcode
227 * Here, <code>FE_Q@<dim@>(2)</code> constructs an unnamed, temporary object
228 * that is passed to the FESystem constructor to create a finite element
229 * that consists of two components, both of which are quadratic FE_Q
230 * elements. The temporary is destroyed again at the end of the code that
231 * corresponds to this line, but this does not matter because FESystem
232 * creates its own copy of the FE_Q object.
233 *
234 * This constructor (or its variants below) is used in essentially all
235 * tutorial programs that deal with vector valued problems. See step-8,
236 * step-20, step-22 and others for use cases. Also see the topic on
237 * @ref vector_valued "Handling vector valued problems".
238 *
239 * @dealiiVideoLecture{19,20}
240 *
241 * @param[in] fe The finite element that will be used to represent the
242 * components of this composed element.
243 * @param[in] n_elements An integer denoting how many copies of @p fe this
244 * element should consist of.
245 */
246 FESystem(const FiniteElement<dim, spacedim> &fe,
247 const unsigned int n_elements);
248
249 /**
250 * Constructor for mixed discretizations with two base elements.
251 *
252 * See the other constructor above for an explanation of the general idea of
253 * composing elements.
254 */
255 FESystem(const FiniteElement<dim, spacedim> &fe1,
256 const unsigned int n1,
257 const FiniteElement<dim, spacedim> &fe2,
258 const unsigned int n2);
259
260 /**
261 * Constructor for mixed discretizations with three base elements.
262 *
263 * See the other constructor above for an explanation of the general idea of
264 * composing elements.
265 */
266 FESystem(const FiniteElement<dim, spacedim> &fe1,
267 const unsigned int n1,
268 const FiniteElement<dim, spacedim> &fe2,
269 const unsigned int n2,
270 const FiniteElement<dim, spacedim> &fe3,
271 const unsigned int n3);
272
273 /**
274 * Constructor for mixed discretizations with four base elements.
275 *
276 * See the first of the other constructors above for an explanation of the
277 * general idea of composing elements.
278 */
279 FESystem(const FiniteElement<dim, spacedim> &fe1,
280 const unsigned int n1,
281 const FiniteElement<dim, spacedim> &fe2,
282 const unsigned int n2,
283 const FiniteElement<dim, spacedim> &fe3,
284 const unsigned int n3,
285 const FiniteElement<dim, spacedim> &fe4,
286 const unsigned int n4);
287
288 /**
289 * Constructor for mixed discretizations with five base elements.
290 *
291 * See the first of the other constructors above for an explanation of the
292 * general idea of composing elements.
293 */
294 FESystem(const FiniteElement<dim, spacedim> &fe1,
295 const unsigned int n1,
296 const FiniteElement<dim, spacedim> &fe2,
297 const unsigned int n2,
298 const FiniteElement<dim, spacedim> &fe3,
299 const unsigned int n3,
300 const FiniteElement<dim, spacedim> &fe4,
301 const unsigned int n4,
302 const FiniteElement<dim, spacedim> &fe5,
303 const unsigned int n5);
304
305 /**
306 * Same as above but for any number of base elements. Pointers to the base
307 * elements and their multiplicities are passed as vectors to this
308 * constructor. The lengths of these vectors are assumed to be equal.
309 *
310 * As above, the finite element objects pointed to by the first argument are
311 * not actually used other than to create copies internally. Consequently,
312 * you can delete these pointers immediately again after calling this
313 * constructor.
314 *
315 * <h4>How to use this constructor</h4>
316 *
317 * Using this constructor is a bit awkward at times because you need to pass
318 * two vectors in a place where it may not be straightforward to construct
319 * such a vector -- for example, in the member initializer list of a class
320 * with an FESystem member variable. For example, if your main class looks
321 * like this:
322 * @code
323 * template <int dim>
324 * class MySimulator {
325 * public:
326 * MySimulator (const unsigned int polynomial_degree);
327 * private:
328 * FESystem<dim> fe;
329 * };
330 *
331 * template <int dim>
332 * MySimulator<dim>::MySimulator (const unsigned int polynomial_degree)
333 * :
334 * fe (...) // what to pass here???
335 * {}
336 * @endcode
337 *
338 * Using the C++11 language standard (or later) you could do something like
339 * this to create an element with four base elements and multiplicities 1,
340 * 2, 3 and 4:
341 * @code
342 * template <int dim>
343 * MySimulator<dim>::MySimulator (const unsigned int polynomial_degree)
344 * :
345 * fe (std::vector<const FiniteElement<dim>*> { new FE_Q<dim>(1),
346 * new FE_Q<dim>(2),
347 * new FE_Q<dim>(3),
348 * new FE_Q<dim>(4) },
349 * std::vector<unsigned int> { 1, 2, 3, 4 })
350 * {}
351 * @endcode
352 * This creates two vectors in place and initializes them using the
353 * initializer list enclosed in braces <code>{ ... }</code>.
354 *
355 * This code has a problem: it creates four memory leaks because the first
356 * vector above is created with pointers to elements that are allocated with
357 * <code>new</code> but never destroyed.
358 *
359 * The solution to the second of these problems is to create two static
360 * member functions that can create vectors. Here is an example:
361 * @code
362 * template <int dim>
363 * class MySimulator {
364 * public:
365 * MySimulator (const unsigned int polynomial_degree);
366 *
367 * private:
368 * FESystem<dim> fe;
369 *
370 * static std::vector<const FiniteElement<dim>*>
371 * create_fe_list (const unsigned int polynomial_degree);
372 *
373 * static std::vector<unsigned int>
374 * create_fe_multiplicities ();
375 * };
376 *
377 * template <int dim>
378 * std::vector<const FiniteElement<dim>*>
379 * MySimulator<dim>::create_fe_list (const unsigned int polynomial_degree)
380 * {
381 * std::vector<const FiniteElement<dim>*> fe_list;
382 * fe_list.push_back (new FE_Q<dim>(1));
383 * fe_list.push_back (new FE_Q<dim>(2));
384 * fe_list.push_back (new FE_Q<dim>(3));
385 * fe_list.push_back (new FE_Q<dim>(4));
386 * return fe_list;
387 * }
388 *
389 * template <int dim>
390 * std::vector<unsigned int>
391 * MySimulator<dim>::create_fe_multiplicities ()
392 * {
393 * std::vector<unsigned int> multiplicities;
394 * multiplicities.push_back (1);
395 * multiplicities.push_back (2);
396 * multiplicities.push_back (3);
397 * multiplicities.push_back (4);
398 * return multiplicities;
399 * }
400 *
401 * template <int dim>
402 * MySimulator<dim>::MySimulator (const unsigned int polynomial_degree)
403 * :
404 * fe (create_fe_list (polynomial_degree),
405 * create_fe_multiplicities ())
406 * {}
407 * @endcode
408 *
409 * The way this works is that we have two static member functions that
410 * create the necessary vectors to pass to the constructor of the member
411 * variable <code>fe</code>. They need to be static because they are called
412 * during the constructor of <code>MySimulator</code> at a time when the
413 * <code>*this</code> object isn't fully constructed and, consequently,
414 * regular member functions cannot be called yet.
415 *
416 * The code above does not solve the problem with the memory leak yet,
417 * though: the <code>create_fe_list()</code> function creates a vector of
418 * pointers, but nothing destroys these. This is the solution:
419 * @code
420 * template <int dim>
421 * class MySimulator
422 * {
423 * public:
424 * MySimulator (const unsigned int polynomial_degree);
425 *
426 * private:
427 * FESystem<dim> fe;
428 *
429 * struct VectorElementDestroyer
430 * {
431 * const std::vector<const FiniteElement<dim>*> data;
432 *
433 * VectorElementDestroyer(
434 * const std::vector<const FiniteElement<dim>*> &pointers);
435 *
436 * // destructor to delete the pointers
437 * ~VectorElementDestroyer ();
438 *
439 * const std::vector<const FiniteElement<dim>*> & get_data () const;
440 * };
441 *
442 * static std::vector<const FiniteElement<dim>*>
443 * create_fe_list (const unsigned int polynomial_degree);
444 *
445 * static std::vector<unsigned int>
446 * create_fe_multiplicities ();
447 * };
448 *
449 * template <int dim>
450 * MySimulator<dim>::VectorElementDestroyer::
451 * VectorElementDestroyer(
452 * const std::vector<const FiniteElement<dim>*> &pointers)
453 * :
454 * data(pointers)
455 * {}
456 *
457 * template <int dim>
458 * MySimulator<dim>::VectorElementDestroyer::
459 * ~VectorElementDestroyer ()
460 * {
461 * for (unsigned int i=0; i<data.size(); ++i)
462 * delete data[i];
463 * }
464 *
465 * template <int dim>
466 * const std::vector<const FiniteElement<dim>*> &
467 * MySimulator<dim>::VectorElementDestroyer::
468 * get_data () const
469 * {
470 * return data;
471 * }
472 *
473 * template <int dim>
474 * MySimulator<dim>::MySimulator (const unsigned int polynomial_degree)
475 * :
476 * fe (VectorElementDestroyer(create_fe_list (polynomial_degree)).get_data(),
477 * create_fe_multiplicities ())
478 * {}
479 * @endcode
480 *
481 * In other words, the vector we receive from the
482 * <code>create_fe_list()</code> is packed into a temporary object of type
483 * <code>VectorElementDestroyer</code>; we then get the vector from this
484 * temporary object immediately to pass it to the constructor of
485 * <code>fe</code>; and finally, the <code>VectorElementDestroyer</code>
486 * destructor is called at the end of the entire expression (after the
487 * constructor of <code>fe</code> has finished) and destroys the elements of
488 * the temporary vector. Voila: not short nor elegant, but it works!
489 */
490 FESystem(const std::vector<const FiniteElement<dim, spacedim> *> &fes,
491 const std::vector<unsigned int> &multiplicities);
492
493 #if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
494 /**
495 * Constructor taking an arbitrary number of parameters of type
496 * <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned
497 * int></code>. In combination with FiniteElement::operator^, this allows to
498 * construct FESystem objects as follows:
499 * @code
500 * FiniteElementType1<dim,spacedim> fe_1;
501 * FiniteElementType1<dim,spacedim> fe_2;
502 * FESystem<dim,spacedim> fe_system ( fe_1^dim, fe_2 );
503 * @endcode
504 *
505 * The `fe_1` and `fe_2` objects are not actually used for anything other than
506 * creating a copy that will then be owned by the current object. In other
507 * words, it is completely fine to call this constructor with a temporary
508 * object for the finite element, as in this code snippet:
509 * @code
510 * FESystem<dim> fe (FE_Q<dim>(2)^2);
511 * @endcode
512 * Here, <code>FE_Q@<dim@>(2)</code> constructs an unnamed, temporary object
513 * that is passed to the FESystem constructor to create a finite element
514 * that consists of two components, both of which are quadratic FE_Q
515 * elements. The temporary is destroyed again at the end of the code that
516 * corresponds to this line, but this does not matter because FESystem
517 * creates its own copy of the FE_Q object.
518 *
519 * As a shortcut, this constructor also allows calling
520 * @code
521 * FESystem<dim> fe (FE_Q<dim>(2)^dim, FE_Q<dim>(1));
522 * @endcode
523 * instead of the more explicit
524 * @code
525 * FESystem<dim> fe (FE_Q<dim>(2)^dim, FE_Q<dim>(1)^1);
526 * @endcode
527 * In other words, if no multiplicity for an element is explicitly specified
528 * via the exponentiation operation, then it is assumed to be one (as one
529 * would have expected).
530 *
531 * @warning This feature is not available for Intel compilers
532 * prior to version 19.0. Defining this
533 * constructor leads to internal compiler errors for Intel compilers prior
534 * to 18.0.
535 */
536 template <
537 class... FEPairs,
538 typename = enable_if_all_t<
539 (std::is_same_v<std::decay_t<FEPairs>,
540 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
541 unsigned int>> ||
542 std::is_base_of_v<FiniteElement<dim, spacedim>,
543 std::decay_t<FEPairs>>)...>>
544 FESystem(FEPairs &&...fe_pairs);
545
546 /**
547 * Same as above allowing the following syntax:
548 * @code
549 * FiniteElementType1<dim,spacedim> fe_1;
550 * FiniteElementType1<dim,spacedim> fe_2;
551 * FESystem<dim,spacedim> fe_system = { fe_1^dim, fe_2^1 };
552 * @endcode
553 *
554 * @warning This feature is not available for Intel compilers
555 * prior to version 19.0. The constructor is just not selected for overload
556 * resolution.
557 */
558 FESystem(
559 const std::initializer_list<
560 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
561 &fe_systems);
562 #endif
563
564 /**
565 * Copy constructor. This constructor is deleted, i.e., copying
566 * FESystem objects is not allowed.
567 */
568 FESystem(const FESystem<dim, spacedim> &) = delete;
569
570 /**
571 * Move constructor.
572 */
573 FESystem(FESystem<dim, spacedim> &&other_fe_system) noexcept
574 : FiniteElement<dim, spacedim>(std::move(other_fe_system))
575 , base_elements(std::move(other_fe_system.base_elements))
576 , generalized_support_points_index_table(
577 std::move(other_fe_system.generalized_support_points_index_table))
578 {}
579
580 /**
581 * Destructor.
582 */
583 virtual ~FESystem() override = default;
584
585 /**
586 * Return a string that uniquely identifies a finite element. This element
587 * returns a string that is composed of the strings @p name1...@p nameN
588 * returned by the basis elements. From these, we create a sequence
589 * <tt>FESystem<dim>[name1^m1-name2^m2-...-nameN^mN]</tt>, where @p mi are
590 * the multiplicities of the basis elements. If a multiplicity is equal to
591 * one, then the superscript is omitted.
592 */
593 virtual std::string
594 get_name() const override;
595
596 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
597 clone() const override;
598
599 virtual UpdateFlags
600 requires_update_flags(const UpdateFlags update_flags) const override;
601
602 // make variant with ComponentMask also available:
603 using FiniteElement<dim, spacedim>::get_sub_fe;
604
605 /**
606 * @copydoc FiniteElement::get_sub_fe()
607 */
608 virtual const FiniteElement<dim, spacedim> &
609 get_sub_fe(const unsigned int first_component,
610 const unsigned int n_selected_components) const override;
611
612 /**
613 * Return the value of the @p ith shape function at the point @p p. @p p is
614 * a point on the reference element. Since this finite element is always
615 * vector-valued, we return the value of the only non-zero component of the
616 * vector value of this shape function. If the shape function has more than
617 * one non-zero component (which we refer to with the term non-primitive),
618 * then throw an exception of type @p ExcShapeFunctionNotPrimitive.
619 *
620 * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
621 * @p FiniteElement (corresponding to the @p ith shape function) depend on
622 * the shape of the cell in real space.
623 */
624 virtual double
625 shape_value(const unsigned int i, const Point<dim> &p) const override;
626
627 /**
628 * Return the value of the @p componentth vector component of the @p ith
629 * shape function at the point @p p. See the FiniteElement base class for
630 * more information about the semantics of this function.
631 *
632 * Since this element is vector valued in general, it relays the computation
633 * of these values to the base elements.
634 */
635 virtual double
636 shape_value_component(const unsigned int i,
637 const Point<dim> &p,
638 const unsigned int component) const override;
639
640 /**
641 * Return the gradient of the @p ith shape function at the point @p p. @p p
642 * is a point on the reference element, and likewise the gradient is the
643 * gradient on the unit cell with respect to unit cell coordinates. Since
644 * this finite element is always vector-valued, we return the value of the
645 * only non-zero component of the vector value of this shape function. If
646 * the shape function has more than one non-zero component (which we refer
647 * to with the term non-primitive), then throw an exception of type @p
648 * ExcShapeFunctionNotPrimitive.
649 *
650 * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
651 * @p FiniteElement (corresponding to the @p ith shape function) depend on
652 * the shape of the cell in real space.
653 */
654 virtual Tensor<1, dim>
655 shape_grad(const unsigned int i, const Point<dim> &p) const override;
656
657 /**
658 * Return the gradient of the @p componentth vector component of the @p ith
659 * shape function at the point @p p. See the FiniteElement base class for
660 * more information about the semantics of this function.
661 *
662 * Since this element is vector valued in general, it relays the computation
663 * of these values to the base elements.
664 */
665 virtual Tensor<1, dim>
666 shape_grad_component(const unsigned int i,
667 const Point<dim> &p,
668 const unsigned int component) const override;
669
670 /**
671 * Return the tensor of second derivatives of the @p ith shape
672 * function at point @p p on the unit cell. The derivatives are
673 * derivatives on the unit cell with respect to unit cell
674 * coordinates. Since this finite element is always vector-valued,
675 * we return the value of the only non-zero component of the vector
676 * value of this shape function. If the shape function has more than
677 * one non-zero component (which we refer to with the term
678 * non-primitive), then throw an exception of type
679 * @p ExcShapeFunctionNotPrimitive.
680 *
681 * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
682 * @p FiniteElement (corresponding to the @p ith shape function) depend on
683 * the shape of the cell in real space.
684 */
685 virtual Tensor<2, dim>
686 shape_grad_grad(const unsigned int i, const Point<dim> &p) const override;
687
688 /**
689 * Return the second derivatives of the @p componentth vector component of
690 * the @p ith shape function at the point @p p. See the FiniteElement base
691 * class for more information about the semantics of this function.
692 *
693 * Since this element is vector valued in general, it relays the computation
694 * of these values to the base elements.
695 */
696 virtual Tensor<2, dim>
697 shape_grad_grad_component(const unsigned int i,
698 const Point<dim> &p,
699 const unsigned int component) const override;
700
701 /**
702 * Return the tensor of third derivatives of the @p ith shape function at
703 * point @p p on the unit cell. The derivatives are derivatives on the unit
704 * cell with respect to unit cell coordinates. Since this finite element is
705 * always vector-valued, we return the value of the only non-zero component
706 * of the vector value of this shape function. If the shape function has
707 * more than one non-zero component (which we refer to with the term
708 * non-primitive), then throw an exception of type @p
709 * ExcShapeFunctionNotPrimitive.
710 *
711 * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
712 * @p FiniteElement (corresponding to the @p ith shape function) depend on
713 * the shape of the cell in real space.
714 */
715 virtual Tensor<3, dim>
716 shape_3rd_derivative(const unsigned int i,
717 const Point<dim> &p) const override;
718
719 /**
720 * Return the third derivatives of the @p componentth vector component of
721 * the @p ith shape function at the point @p p. See the FiniteElement base
722 * class for more information about the semantics of this function.
723 *
724 * Since this element is vector valued in general, it relays the computation
725 * of these values to the base elements.
726 */
727 virtual Tensor<3, dim>
728 shape_3rd_derivative_component(const unsigned int i,
729 const Point<dim> &p,
730 const unsigned int component) const override;
731
732 /**
733 * Return the tensor of fourth derivatives of the @p ith shape function at
734 * point @p p on the unit cell. The derivatives are derivatives on the unit
735 * cell with respect to unit cell coordinates. Since this finite element is
736 * always vector-valued, we return the value of the only non-zero component
737 * of the vector value of this shape function. If the shape function has
738 * more than one non-zero component (which we refer to with the term
739 * non-primitive), then throw an exception of type
740 * @p ExcShapeFunctionNotPrimitive.
741 *
742 * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
743 * @p FiniteElement (corresponding to the @p ith shape function) depend on
744 * the shape of the cell in real space.
745 */
746 virtual Tensor<4, dim>
747 shape_4th_derivative(const unsigned int i,
748 const Point<dim> &p) const override;
749
750 /**
751 * Return the fourth derivatives of the @p componentth vector component of
752 * the @p ith shape function at the point @p p. See the FiniteElement base
753 * class for more information about the semantics of this function.
754 *
755 * Since this element is vector valued in general, it relays the computation
756 * of these values to the base elements.
757 */
758 virtual Tensor<4, dim>
759 shape_4th_derivative_component(const unsigned int i,
760 const Point<dim> &p,
761 const unsigned int component) const override;
762
763 /**
764 * Return the matrix interpolating from the given finite element to the
765 * present one. The size of the matrix is then @p dofs_per_cell times
766 * <tt>source.n_dofs_per_cell()</tt>.
767 *
768 * These matrices are available if source and destination element are both
769 * @p FESystem elements, have the same number of base elements with same
770 * element multiplicity, and if these base elements also implement their @p
771 * get_interpolation_matrix functions. Otherwise, an exception of type
772 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
773 */
774 virtual void
775 get_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
776 FullMatrix<double> &matrix) const override;
777
778 /**
779 * Access to a composing element. The index needs to be smaller than the
780 * number of base elements. Note that the number of base elements may in
781 * turn be smaller than the number of components of the system element, if
782 * the multiplicities are greater than one.
783 */
784 virtual const FiniteElement<dim, spacedim> &
785 base_element(const unsigned int index) const override;
786
787 /**
788 * This function returns @p true, if the shape function @p shape_index has
789 * non-zero function values somewhere on the face @p face_index.
790 */
791 virtual bool
792 has_support_on_face(const unsigned int shape_index,
793 const unsigned int face_index) const override;
794
795 /**
796 * Projection from a fine grid space onto a coarse grid space. Overrides the
797 * respective method in FiniteElement, implementing lazy evaluation
798 * (initialize when requested).
799 *
800 * If this projection operator is associated with a matrix @p P, then the
801 * restriction of this matrix @p P_i to a single child cell is returned
802 * here.
803 *
804 * The matrix @p P is the concatenation or the sum of the cell matrices @p
805 * P_i, depending on the value of FiniteElement::restriction_is_additive().
806 * This distinguishes interpolation (concatenation) and projection with
807 * respect to scalar products (summation).
808 *
809 * Row and column indices are related to coarse grid and fine grid spaces,
810 * respectively, consistent with the definition of the associated operator.
811 *
812 * If projection matrices are not implemented in the derived finite element
813 * class, this function aborts with an exception of type
814 * FiniteElement::ExcProjectionVoid. You can check whether this would happen
815 * by first calling the restriction_is_implemented() or the
816 * isotropic_restriction_is_implemented() function.
817 */
818 virtual const FullMatrix<double> &
819 get_restriction_matrix(
820 const unsigned int child,
821 const RefinementCase<dim> &refinement_case =
822 RefinementCase<dim>::isotropic_refinement) const override;
823
824 /**
825 * Embedding matrix between grids. Overrides the respective method in
826 * FiniteElement, implementing lazy evaluation (initialize when queried).
827 *
828 * The identity operator from a coarse grid space into a fine grid space is
829 * associated with a matrix @p P. The restriction of this matrix @p P_i to a
830 * single child cell is returned here.
831 *
832 * The matrix @p P is the concatenation, not the sum of the cell matrices @p
833 * P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in two
834 * different child matrices @p P_i, the value should be the same in both
835 * matrices and it is copied into the matrix @p P only once.
836 *
837 * Row and column indices are related to fine grid and coarse grid spaces,
838 * respectively, consistent with the definition of the associated operator.
839 *
840 * These matrices are used by routines assembling the prolongation matrix
841 * for multi-level methods. Upon assembling the transfer matrix between
842 * cells using this matrix array, zero elements in the prolongation matrix
843 * are discarded and will not fill up the transfer matrix.
844 *
845 * If prolongation matrices are not implemented in one of the base finite
846 * element classes, this function aborts with an exception of type
847 * FiniteElement::ExcEmbeddingVoid. You can check whether this would happen
848 * by first calling the prolongation_is_implemented() or the
849 * isotropic_prolongation_is_implemented() function.
850 */
851 virtual const FullMatrix<double> &
852 get_prolongation_matrix(
853 const unsigned int child,
854 const RefinementCase<dim> &refinement_case =
855 RefinementCase<dim>::isotropic_refinement) const override;
856
857 /**
858 * Given an index in the natural ordering of indices on a face, return the
859 * index of the same degree of freedom on the cell.
860 *
861 * To explain the concept, consider the case where we would like to know
862 * whether a degree of freedom on a face, for example as part of an FESystem
863 * element, is primitive. Unfortunately, the is_primitive() function in the
864 * FiniteElement class takes a cell index, so we would need to find the cell
865 * index of the shape function that corresponds to the present face index.
866 * This function does that.
867 *
868 * Code implementing this would then look like this:
869 * @code
870 * for (i=0; i<dofs_per_face; ++i)
871 * if (fe.is_primitive(fe.face_to_cell_index(i, some_face_no)))
872 * ... do whatever
873 * @endcode
874 * The function takes additional arguments that account for the fact that
875 * actual faces can be in their standard ordering with respect to the cell
876 * under consideration, or can be flipped, oriented, etc.
877 *
878 * @param face_dof_index The index of the degree of freedom on a face. This
879 * index must be between zero and dofs_per_face.
880 * @param face The number of the face this degree of freedom lives on. This
881 * number must be between zero and GeometryInfo::faces_per_cell.
882 * @param combined_orientation The combined orientation flag containing the
883 * orientation, rotation, and flip of the face. See
884 * @ref GlossCombinedOrientation.
885 * @return The index of this degree of freedom within the set of degrees of
886 * freedom on the entire cell. The returned value will be between zero and
887 * dofs_per_cell.
888 */
889 virtual unsigned int
890 face_to_cell_index(const unsigned int face_dof_index,
891 const unsigned int face,
892 const types::geometric_orientation combined_orientation =
893 numbers::default_geometric_orientation) const override;
894
895 /**
896 * Implementation of the respective function in the base class.
897 */
898 virtual Point<dim>
899 unit_support_point(const unsigned int index) const override;
900
901 /**
902 * Implementation of the respective function in the base class.
903 */
904 virtual Point<dim - 1>
905 unit_face_support_point(const unsigned int index,
906 const unsigned int face_no = 0) const override;
907
908 /**
909 * Return a list of constant modes of the element. The returns table has as
910 * many rows as there are components in the element and dofs_per_cell
911 * columns. To each component of the finite element, the row in the returned
912 * table contains a basis representation of the constant function 1 on the
913 * element. Concatenates the constant modes of each base element.
914 */
915 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
916 get_constant_modes() const override;
917
918 /**
919 * @name Functions to support hp
920 * @{
921 */
922
923 /**
924 * Return whether this element implements its hanging node constraints in
925 * the new way, which has to be used to make elements "hp-compatible".
926 *
927 * This function returns @p true if and only if all its base elements return
928 * @p true for this function.
929 */
930 virtual bool
931 hp_constraints_are_implemented() const override;
932
933 /**
934 * Return the matrix interpolating from a face of one element to the face
935 * of the neighboring element. The size of the matrix is then
936 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
937 *
938 * Base elements of this element will have to implement this function. They
939 * may only provide interpolation matrices for certain source finite
940 * elements, for example those from the same family. If they don't implement
941 * interpolation from a given element, then they must throw an exception of
942 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented, which
943 * will get propagated out from this element.
944 */
945 virtual void
946 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
947 FullMatrix<double> &matrix,
948 const unsigned int face_no = 0) const override;
949
950
951 /**
952 * Return the matrix interpolating from a face of one element to the
953 * subface of the neighboring element. The size of the matrix is then
954 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
955 *
956 * Base elements of this element will have to implement this function. They
957 * may only provide interpolation matrices for certain source finite
958 * elements, for example those from the same family. If they don't implement
959 * interpolation from a given element, then they must throw an exception of
960 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented, which
961 * will get propagated out from this element.
962 */
963 virtual void
964 get_subface_interpolation_matrix(
965 const FiniteElement<dim, spacedim> &source,
966 const unsigned int subface,
967 FullMatrix<double> &matrix,
968 const unsigned int face_no = 0) const override;
969
970 /**
971 * If, on a vertex, several finite elements are active, the hp-code first
972 * assigns the degrees of freedom of each of these FEs different global
973 * indices. It then calls this function to find out which of them should get
974 * identical values, and consequently can receive the same global DoF index.
975 * This function therefore returns a list of identities between DoFs of the
976 * present finite element object with the DoFs of @p fe_other, which is a
977 * reference to a finite element object representing one of the other finite
978 * elements active on this particular vertex. The function computes which of
979 * the degrees of freedom of the two finite element objects are equivalent,
980 * both numbered between zero and the corresponding value of
981 * n_dofs_per_vertex() of the two finite elements. The first index of each
982 * pair denotes one of the vertex dofs of the present element, whereas the
983 * second is the corresponding index of the other finite element.
984 */
985 virtual std::vector<std::pair<unsigned int, unsigned int>>
986 hp_vertex_dof_identities(
987 const FiniteElement<dim, spacedim> &fe_other) const override;
988
989 /**
990 * Same as hp_vertex_dof_indices(), except that the function treats degrees
991 * of freedom on lines.
992 */
993 virtual std::vector<std::pair<unsigned int, unsigned int>>
994 hp_line_dof_identities(
995 const FiniteElement<dim, spacedim> &fe_other) const override;
996
997 /**
998 * Same as hp_vertex_dof_indices(), except that the function treats degrees
999 * of freedom on quads.
1000 */
1001 virtual std::vector<std::pair<unsigned int, unsigned int>>
1002 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
1003 const unsigned int face_no = 0) const override;
1004
1005 /**
1006 * @copydoc FiniteElement::compare_for_domination()
1007 */
1008 virtual FiniteElementDomination::Domination
1009 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
1010 const unsigned int codim = 0) const override final;
1011
1012 /** @} */
1013
1014 /**
1015 * Implementation of the
1016 * FiniteElement::convert_generalized_support_point_values_to_dof_values()
1017 * function.
1018 *
1019 * This function simply calls
1020 * FiniteElement::convert_generalized_support_point_values_to_dof_values
1021 * of the base elements and re-assembles everything into the output
1022 * argument. If a base element is non-interpolatory the corresponding dof
1023 * values are filled with "signaling" NaNs instead.
1024 *
1025 * The function fails if none of the base elements of the FESystem are
1026 * interpolatory.
1027 */
1028 virtual void
1029 convert_generalized_support_point_values_to_dof_values(
1030 const std::vector<Vector<double>> &support_point_values,
1031 std::vector<double> &dof_values) const override;
1032
1033 /**
1034 * Determine an estimate for the memory consumption (in bytes) of this
1035 * object.
1036 *
1037 * This function is made virtual, since finite element objects are usually
1038 * accessed through pointers to their base class, rather than the class
1039 * itself.
1040 */
1041 virtual std::size_t
1042 memory_consumption() const override;
1043
1044 /**
1045 * Computing values on a cell requires copying values between the
1046 * FEValuesImplementation::FiniteElementRelatedData objects owned by the
1047 * present object and its subelements. The indexing for this is fairly
1048 * complicated since each shape function in the nonprimitive base element may
1049 * have a different number of nonzero components (e.g., a Taylor-Hood pair
1050 * base element): we also need offsets into both the base element and present
1051 * element's arrays. To this end, we will create a table with all the
1052 * necessary information for each shape function in the nonprimitive base
1053 * element.
1054 */
1055 struct BaseOffsets
1056 {
1057 /**
1058 * Number of nonzero components for the current base element shape function.
1059 */
1060 unsigned int n_nonzero_components;
1061
1062 /**
1063 * Index into the base element's
1064 * FEValuesImplementation::FiniteElementRelatedData arrays for the current
1065 * base element shape function.
1066 */
1067 unsigned int in_index;
1068
1069 /**
1070 * Index into the present element's
1071 * FEValuesImplementation::FiniteElementRelatedData arrays for the current
1072 * base element shape function.
1073 */
1074 unsigned int out_index;
1075 };
1076
1077 protected:
1078 virtual std::unique_ptr<
1079 typename FiniteElement<dim, spacedim>::InternalDataBase>
1080 get_data(
1081 const UpdateFlags update_flags,
1082 const Mapping<dim, spacedim> &mapping,
1083 const Quadrature<dim> &quadrature,
1084 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1085 spacedim>
1086 &output_data) const override;
1087
1088 using FiniteElement<dim, spacedim>::get_face_data;
1089
1090 virtual std::unique_ptr<
1091 typename FiniteElement<dim, spacedim>::InternalDataBase>
1092 get_face_data(
1093 const UpdateFlags update_flags,
1094 const Mapping<dim, spacedim> &mapping,
1095 const hp::QCollection<dim - 1> &quadrature,
1096 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1097 spacedim>
1098 &output_data) const override;
1099
1100 virtual std::unique_ptr<
1101 typename FiniteElement<dim, spacedim>::InternalDataBase>
1102 get_subface_data(
1103 const UpdateFlags update_flags,
1104 const Mapping<dim, spacedim> &mapping,
1105 const Quadrature<dim - 1> &quadrature,
1106 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1107 spacedim>
1108 &output_data) const override;
1109
1110 virtual void
1111 fill_fe_values(
1112 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1113 const CellSimilarity::Similarity cell_similarity,
1114 const Quadrature<dim> &quadrature,
1115 const Mapping<dim, spacedim> &mapping,
1116 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
1117 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1118 &mapping_data,
1119 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
1120 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1121 spacedim>
1122 &output_data) const override;
1123
1124 using FiniteElement<dim, spacedim>::fill_fe_face_values;
1125
1126 virtual void
1127 fill_fe_face_values(
1128 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1129 const unsigned int face_no,
1130 const hp::QCollection<dim - 1> &quadrature,
1131 const Mapping<dim, spacedim> &mapping,
1132 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
1133 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1134 &mapping_data,
1135 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
1136 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1137 spacedim>
1138 &output_data) const override;
1139
1140 virtual void
1141 fill_fe_subface_values(
1142 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1143 const unsigned int face_no,
1144 const unsigned int sub_no,
1145 const Quadrature<dim - 1> &quadrature,
1146 const Mapping<dim, spacedim> &mapping,
1147 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
1148 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1149 &mapping_data,
1150 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
1151 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1152 spacedim>
1153 &output_data) const override;
1154
1155 /**
1156 * Do the work for the three <tt>fill_fe*_values</tt> functions.
1157 *
1158 * Calls (among other things) <tt>fill_fe_([sub]face)_values</tt> of the
1159 * base elements. Calls @p fill_fe_values if
1160 * <tt>face_no==invalid_face_no</tt> and <tt>sub_no==invalid_face_no</tt>;
1161 * calls @p fill_fe_face_values if <tt>face_no==invalid_face_no</tt> and
1162 * <tt>sub_no!=invalid_face_no</tt>; and calls @p fill_fe_subface_values if
1163 * <tt>face_no!=invalid_face_no</tt> and <tt>sub_no!=invalid_face_no</tt>.
1164 */
1165 template <class Q_or_QC>
1166 void
1167 compute_fill(
1168 const Mapping<dim, spacedim> &mapping,
1169 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1170 const unsigned int face_no,
1171 const unsigned int sub_no,
1172 const Q_or_QC &quadrature,
1173 const CellSimilarity::Similarity cell_similarity,
1174 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
1175 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_data,
1176 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1177 &mapping_data,
1178 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
1179 &output_data) const;
1180
1181 private:
1182 /**
1183 * Value to indicate that a given face or subface number is invalid.
1184 */
1185 static const unsigned int invalid_face_number = numbers::invalid_unsigned_int;
1186
1187 /**
1188 * Lookup tables for indexing primitive elements.
1189 *
1190 * These tables store, for each primitive base element, the array indices into
1191 * which we will write values. One can think of these indices as a combination
1192 * of the system index and the number of nonzero components per shape
1193 * function. This data is needed to copy values from base element value
1194 * reinitialization to the present element's value reinitialization.
1195 */
1196 std::vector<Table<2, unsigned int>> primitive_offset_tables;
1197
1198 /**
1199 * Lookup tables for indexing nonprimitive elements.
1200 */
1201 std::vector<std::vector<BaseOffsets>> nonprimitive_offset_tables;
1202
1203 /**
1204 * Pointers to underlying finite element objects.
1205 *
1206 * This object contains a pointer to each contributing element of a mixed
1207 * discretization and its multiplicity. It is created by the constructor and
1208 * constant afterwards.
1209 */
1210 std::vector<std::pair<std::unique_ptr<const FiniteElement<dim, spacedim>>,
1211 unsigned int>>
1212 base_elements;
1213
1214 /**
1215 * An index table that maps generalized support points of a base element
1216 * to the vector of generalized support points of the FE System.
1217 * It holds true that
1218 * @code
1219 * auto n = generalized_support_points_index_table[i][j];
1220 * generalized_support_points[n] ==
1221 * base_elements[i].generalized_support_points[j];
1222 * @endcode
1223 * for each base element (indexed by i) and each g. s. point of the base
1224 * element (index by j).
1225 */
1226 std::vector<std::vector<std::size_t>> generalized_support_points_index_table;
1227
1228 /**
1229 * This function is simply singled out of the constructors since there are
1230 * several of them. It sets up the index table for the system as well as @p
1231 * restriction and @p prolongation matrices.
1232 */
1233 void
1234 initialize(const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1235 const std::vector<unsigned int> &multiplicities);
1236
1237 /**
1238 * Used by @p initialize.
1239 */
1240 void
1241 build_interface_constraints();
1242
1243 /**
1244 * A function that computes the hp_vertex_dof_identities(),
1245 * hp_line_dof_identities(), or hp_quad_dof_identities(), depending on the
1246 * value of the template parameter.
1247 */
1248 template <int structdim>
1249 std::vector<std::pair<unsigned int, unsigned int>>
1250 hp_object_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
1251 const unsigned int face_no = 0) const;
1252
1253 /**
1254 * Usually: Fields of cell-independent data.
1255 *
1256 * However, here, this class does not itself store the data but only
1257 * pointers to @p InternalData objects for each of the base elements.
1258 */
1259 class InternalData : public FiniteElement<dim, spacedim>::InternalDataBase
1260 {
1261 public:
1262 /**
1263 * Constructor. Is called by the @p get_data function. Sets the size of
1264 * the @p base_fe_datas vector to @p n_base_elements.
1265 */
1266 InternalData(const unsigned int n_base_elements);
1267
1268 /**
1269 * Destructor. Deletes all @p InternalDatas whose pointers are stored by
1270 * the @p base_fe_datas vector.
1271 */
1272 ~InternalData() override;
1273
1274 /**
1275 * Give write-access to the pointer to a @p InternalData of the
1276 * `base_no`th base element.
1277 */
1278 void
1279 set_fe_data(
1280 const unsigned int base_no,
1281 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>);
1282
1283 /**
1284 * Give read-access to the pointer to a @p InternalData of the
1285 * `base_no`th base element.
1286 */
1287 typename FiniteElement<dim, spacedim>::InternalDataBase &
1288 get_fe_data(const unsigned int base_no) const;
1289
1290 /**
1291 * Give read-access to the pointer to an object to which into which the
1292 * <code>base_no</code>th base element will write its output when calling
1293 * FiniteElement::fill_fe_values() and similar functions.
1294 */
1295 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim> &
1296 get_fe_output_object(const unsigned int base_no) const;
1297
1298 private:
1299 /**
1300 * Pointers to @p InternalData objects for each of the base elements. They
1301 * are accessed to by the @p set_ and @p get_fe_data functions.
1302 *
1303 * The size of this vector is set to @p n_base_elements by the
1304 * InternalData constructor. It is filled by the @p get_data function.
1305 * Note that since the data for each instance of a base class is
1306 * necessarily the same, we only need as many of these objects as there
1307 * are base elements, irrespective of their multiplicity.
1308 */
1309 typename std::vector<
1310 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>>
1311 base_fe_datas;
1312
1313 /**
1314 * A collection of objects to which the base elements will write their
1315 * output when we call FiniteElement::fill_fe_values() and related
1316 * functions on them.
1317 *
1318 * The size of this vector is set to @p n_base_elements by the
1319 * InternalData constructor.
1320 */
1321 mutable std::vector<
1322 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>>
1323 base_fe_output_objects;
1324 };
1325
1326 /**
1327 * Mutex variables used for protecting the initialization of restriction
1328 * and embedding matrices.
1329 */
1330 mutable std::mutex restriction_matrix_mutex;
1331 mutable std::mutex prolongation_matrix_mutex;
1332
1333 friend class FE_Enriched<dim, spacedim>;
1334 };
1335
1336 //------------------------variadic template constructor------------------------
1337
1338 #ifndef DOXYGEN
1339 namespace internal
1340 {
1341 namespace FESystemImplementation
1342 {
1343 template <int dim, int spacedim>
1344 unsigned int
1345 count_nonzeros(
1346 const std::initializer_list<
1347 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1348 &fe_systems)
1349 {
1350 return std::count_if(
1351 fe_systems.begin(),
1352 fe_systems.end(),
1353 [](const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1354 unsigned int> &fe_system) {
1355 return fe_system.second > 0;
1356 });
1357 }
1358
1359
1360
1361 template <int dim, int spacedim>
1362 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>
1363 promote_to_fe_pair(const FiniteElement<dim, spacedim> &fe)
1364 {
1365 return std::make_pair(std::move(fe.clone()), 1u);
1366 }
1367
1368
1369
1370 template <int dim, int spacedim>
1371 auto
1372 promote_to_fe_pair(std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1373 unsigned int> &&p)
1374 -> decltype(std::forward<
1375 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1376 unsigned int>>(p))
1377 {
1378 return std::forward<
1379 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>(
1380 p);
1381 }
1382 } // namespace FESystemImplementation
1383 } // namespace internal
1384
1385
1386
1387 # if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
1388 // We are just forwarding/delegating to the constructor taking a
1389 // std::initializer_list. If we decide to remove the deprecated constructors, we
1390 // might just use the variadic constructor with a suitable static_assert instead
1391 // of the std::enable_if.
1392 template <int dim, int spacedim>
1393 template <class... FEPairs, typename>
1394 FESystem<dim, spacedim>::FESystem(FEPairs &&...fe_pairs)
1395 : FESystem<dim, spacedim>(
1396 {internal::FESystemImplementation::promote_to_fe_pair<dim, spacedim>(
1397 std::forward<FEPairs>(fe_pairs))...})
1398 {}
1399
1400
1401
1402 template <int dim, int spacedim>
1403 FESystem<dim, spacedim>::FESystem(
1404 const std::initializer_list<
1405 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1406 &fe_systems)
1407 : FiniteElement<dim, spacedim>(
1408 FETools::Compositing::multiply_dof_numbers<dim, spacedim>(fe_systems),
1409 FETools::Compositing::compute_restriction_is_additive_flags<dim,
1410 spacedim>(
1411 fe_systems),
1412 FETools::Compositing::compute_nonzero_components<dim, spacedim>(
1413 fe_systems))
1414 , base_elements(internal::FESystemImplementation::count_nonzeros(fe_systems))
1415 {
1416 std::vector<const FiniteElement<dim, spacedim> *> fes;
1417 std::vector<unsigned int> multiplicities;
1418
1419 const auto extract =
1420 [&fes, &multiplicities](
1421 const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1422 unsigned int> &fe_system) {
1423 fes.push_back(fe_system.first.get());
1424 multiplicities.push_back(fe_system.second);
1425 };
1426
1427 for (const auto &p : fe_systems)
1428 extract(p);
1429
1430 initialize(fes, multiplicities);
1431 }
1432 # endif
1433 #endif // DOXYGEN
1434
1435 DEAL_II_NAMESPACE_CLOSE
1436
1437 #endif