Debian Codegraph @

include/deal.II/hp/fe_collection.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2005 - 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_collection_h
16 #define dealii_fe_collection_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/fe/component_mask.h>
21 #include <deal.II/fe/fe.h>
22 #include <deal.II/fe/fe_values_extractors.h>
23
24 #include <deal.II/hp/collection.h>
25
26 #include <memory>
27 #include <set>
28
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declarations
33 namespace hp
34 {
35 template <int dim, int spacedim>
36 class MappingCollection;
37 }
38
39
40 namespace hp
41 {
42 /**
43 * This class acts as a collection of finite element objects used in the
44 * DoFHandler.
45 *
46 * It implements the concepts stated in the
47 * @ref hpcollection
48 * topic described in the doxygen documentation.
49 *
50 * In addition to offering access to the elements of the collection, this
51 * class provides access to the maximal number of degrees of freedom per
52 * vertex, line, etc, to allow allocation of as much memory as is necessary
53 * in the worst case when using the finite elements associated with the
54 * cells of a triangulation.
55 *
56 * This class has not yet been implemented for the use in the codimension
57 * one case (<tt>spacedim != dim</tt>).
58 *
59 * @ingroup hp hpcollection
60 */
61 template <int dim, int spacedim = dim>
62 class FECollection : public Collection<FiniteElement<dim, spacedim>>
63 {
64 public:
65 /**
66 * Whenever p-adaptivity is considered in an hp-finite element program,
67 * a hierarchy of finite elements needs to be established to determine
68 * succeeding finite elements for refinement and preceding ones for
69 * coarsening.
70 *
71 * In this struct, we supply a hierarchy that is imposed on all FECollection
72 * objects by default.
73 */
74 struct DefaultHierarchy
75 {
76 /**
77 * Return the index succeeding @p fe_index in the @p fe_collection.
78 *
79 * Once the last element of the @p fe_collection is reached, there is no element on a higher level in
80 * the hierarchy and thus we return the last value.
81 */
82 static unsigned int
83 next_index(const typename hp::FECollection<dim, spacedim> &fe_collection,
84 const unsigned int fe_index)
85 {
86 return ((fe_index + 1) < fe_collection.size()) ? fe_index + 1 :
87 fe_index;
88 }
89
90 /**
91 * Return the index preceding @p fe_index in the @p fe_collection.
92 *
93 * Once the first element of the @p fe_collection is reached, there is no element on a lower level in
94 * the hierarchy and thus we return the first value.
95 */
96 static unsigned int
97 previous_index(
98 const typename hp::FECollection<dim, spacedim> &fe_collection,
99 const unsigned int fe_index)
100 {
101 (void)fe_collection;
102 return (fe_index > 0) ? fe_index - 1 : fe_index;
103 }
104 };
105
106 /**
107 * Default constructor. Leads to an empty collection that can later be
108 * filled using push_back(). Establishes a hierarchy of finite elements
109 * corresponding to their index in the collection.
110 */
111 FECollection();
112
113 /**
114 * Conversion constructor. This constructor creates a FECollection from a
115 * single finite element. More finite element objects can be added with
116 * push_back(), if desired, though it would probably be clearer to add all
117 * mappings the same way.
118 */
119 explicit FECollection(const FiniteElement<dim, spacedim> &fe);
120
121 /**
122 * Constructor. This constructor creates a FECollection from one or
123 * more finite element objects passed to the constructor. For this
124 * call to be valid, all arguments need to be of types derived
125 * from class FiniteElement<dim,spacedim>.
126 */
127 template <class... FETypes>
128 explicit FECollection(const FETypes &...fes);
129
130 /**
131 * Constructor. Same as above but for any number of elements. Pointers to
132 * the elements are passed in a vector to this constructor. As above, the
133 * finite element objects pointed to by the argument are not actually used
134 * other than to create copies internally. Consequently, you can delete
135 * these pointers immediately again after calling this constructor.
136 */
137 FECollection(const std::vector<const FiniteElement<dim, spacedim> *> &fes);
138
139 /**
140 * Copy constructor.
141 */
142 FECollection(const FECollection<dim, spacedim> &) = default;
143
144 /**
145 * Move constructor.
146 *
147 * @note The implementation of standard datatypes may change with different
148 * libraries, so their move members may or may not be flagged non-throwing.
149 * We need to explicitly set the noexcept specifier according to its
150 * member variables to still get the performance benefits (and to satisfy
151 * clang-tidy).
152 */
153 FECollection(FECollection<dim, spacedim> &&) noexcept(
154 std::is_nothrow_move_constructible_v<
155 std::vector<std::shared_ptr<const FiniteElement<dim, spacedim>>>>
156 &&std::is_nothrow_move_constructible_v<std::function<
157 unsigned int(const typename hp::FECollection<dim, spacedim> &,
158 const unsigned int)>>) = default;
159
160 /**
161 * Move assignment operator.
162 */
163 FECollection<dim, spacedim> &
164 operator=(FECollection<dim, spacedim> &&) = default; // NOLINT
165
166 /**
167 * Equality comparison operator. All stored FiniteElement objects are
168 * compared in order.
169 */
170 bool
171 operator==(const FECollection<dim, spacedim> &fe_collection) const;
172
173 /**
174 * Non-equality comparison operator. All stored FiniteElement objects are
175 * compared in order.
176 */
177 bool
178 operator!=(const FECollection<dim, spacedim> &fe_collection) const;
179
180 /**
181 * Add a finite element. This function generates a copy of the given
182 * element, i.e. you can do things like <tt>push_back(FE_Q<dim>(1));</tt>.
183 * The internal copy is later destroyed by this object upon destruction of
184 * the entire collection.
185 *
186 * When a new element is added, it needs to have the same number of vector
187 * components as all other elements already in the collection.
188 */
189 void
190 push_back(const FiniteElement<dim, spacedim> &new_fe);
191
192 /**
193 * @name Querying information about the elements in the collection
194 */
195
196 /**
197 * @{
198 */
199
200 /**
201 * Return the number of vector components of the finite elements in this
202 * collection. This number must be the same for all elements in the
203 * collection.
204 *
205 * This function calls FiniteElement::n_components. See
206 * @ref GlossComponent "the glossary"
207 * for more information.
208 */
209 unsigned int
210 n_components() const;
211
212 /**
213 * Return the number of vector blocks of the finite elements in this
214 * collection. While this class ensures that all elements stored in it
215 * have the same number of vector components, there is no such guarantees
216 * for the number of blocks each element is made up of (an element may
217 * have fewer blocks than vector components; see
218 * @ref GlossBlock "the glossary"
219 * for more information). For example, you may have an FECollection object
220 * that stores one copy of an FESystem with <code>dim</code> FE_Q objects
221 * and one copy of an FE_RaviartThomas element. Both have <code>dim</code>
222 * vector components but while the former has <code>dim</code> blocks the
223 * latter has only one. Consequently, this function will throw an
224 * assertion if the number of blocks is not the same for all elements. If
225 * they are the same, this function returns the result of
226 * FiniteElement::n_blocks().
227 */
228 unsigned int
229 n_blocks() const;
230
231 /**
232 * Return the maximum of values returned by FiniteElement::get_degree()
233 * over all elements of this collection.
234 */
235 unsigned int
236 max_degree() const;
237
238 /**
239 * Return the maximal number of degrees of freedom per vertex over all
240 * elements of this collection.
241 */
242 unsigned int
243 max_dofs_per_vertex() const;
244
245 /**
246 * Return the maximal number of degrees of freedom per line over all
247 * elements of this collection.
248 */
249 unsigned int
250 max_dofs_per_line() const;
251
252 /**
253 * Return the maximal number of degrees of freedom per quad over all
254 * elements of this collection.
255 */
256 unsigned int
257 max_dofs_per_quad() const;
258
259 /**
260 * Return the maximal number of degrees of freedom per hex over all
261 * elements of this collection.
262 */
263 unsigned int
264 max_dofs_per_hex() const;
265
266 /**
267 * Return the maximal number of degrees of freedom per face over all
268 * elements of this collection.
269 */
270 unsigned int
271 max_dofs_per_face() const;
272
273 /**
274 * Return the maximal number of degrees of freedom per cell over all
275 * elements of this collection.
276 */
277 unsigned int
278 max_dofs_per_cell() const;
279
280 /**
281 * Return a mapping collection that consists of the default linear mappings
282 * matching the reference cells for each hp index. More details may be found
283 * in the documentation for ReferenceCell::get_default_linear_mapping().
284 *
285 * @note This FECollection object must remain in scope for as long as the
286 * reference cell default linear mapping is in use.
287 */
288 const MappingCollection<dim, spacedim> &
289 get_reference_cell_default_linear_mapping() const;
290
291 /**
292 * @}
293 */
294
295 /**
296 * @name Functions to support hp-adaptivity
297 */
298
299 /**
300 * @{
301 */
302
303 /**
304 * Return whether all elements in this collection implement the hanging
305 * node constraints in the new way, which has to be used to make elements
306 * "hp-compatible". If this is not the case, the function returns false,
307 * which implies, that at least one element in the FECollection does not
308 * support the new face interface constraints. On the other hand, if this
309 * method does return true, this does not imply that the hp-method will
310 * work!
311 *
312 * This behavior is related to the fact, that FiniteElement classes,
313 * which provide the new style hanging node constraints might still not
314 * provide them for all possible cases. If FE_Q and FE_RaviartThomas
315 * elements are included in the FECollection and both properly implement
316 * the get_face_interpolation_matrix method, this method will return true.
317 * But the get_face_interpolation_matrix might still fail to find an
318 * interpolation matrix between these two elements.
319 */
320 bool
321 hp_constraints_are_implemented() const;
322
323 /**
324 * This function combines the functionality of the
325 * FiniteElement::hp_vertex_dof_identities() into multi-way comparisons.
326 * Given a set of elements (whose indices are provided as argument), this
327 * function determines identities between degrees of freedom of these
328 * elements at a vertex.
329 *
330 * The function returns a vector of such identities, where each element of
331 * the vector is a set of pairs `(fe_index,dof_index)` that identifies
332 * the `fe_index` (an element of the `fes` argument to this function) of
333 * an element and the `dof_index` indicates the how-manyth degree of freedom
334 * of that element on a vertex participates in this identity. Now,
335 * every `fe_index` can appear only once in these sets (for each identity,
336 * only one degree of freedom of a finite element can be involved --
337 * otherwise we would have identities between different DoFs of the same
338 * element, which would make the element not unisolvent), and as a
339 * consequence the function does not actually return a set of
340 * `(fe_index,dof_index)` pairs for each identity, but instead a `std::map`
341 * from `fe_index` to `dof_index`, which is conceptually of course
342 * equivalent to a `std::set` of pairs, but in practice is easier to query.
343 */
344 std::vector<std::map<unsigned int, unsigned int>>
345 hp_vertex_dof_identities(const std::set<unsigned int> &fes) const;
346
347 /**
348 * Same as hp_vertex_dof_indices(), except that the function treats degrees
349 * of freedom on lines.
350 */
351 std::vector<std::map<unsigned int, unsigned int>>
352 hp_line_dof_identities(const std::set<unsigned int> &fes) const;
353
354 /**
355 * Same as hp_vertex_dof_indices(), except that the function treats degrees
356 * of freedom on quads.
357 */
358 std::vector<std::map<unsigned int, unsigned int>>
359 hp_quad_dof_identities(const std::set<unsigned int> &fes,
360 const unsigned int face_no = 0) const;
361
362
363 /**
364 * Return the indices of finite elements in this FECollection that dominate
365 * all elements associated with the provided set of indices @p fes.
366 *
367 * You may find information about the domination behavior of finite elements
368 * in their respective class documentation or in the implementation of their
369 * inherited member function FiniteElement::compare_for_domination().
370 * Consider that a finite element may or may not dominate itself (e.g.
371 * FE_Nothing elements).
372 *
373 * For example, if a FECollection consists of
374 * `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements and we are looking for the
375 * finite elements that dominate the middle elements of this
376 * collection (i.e., @p fes is `{1,2}`), then the answer is `{FE_Q(1),FE_Q(2)`
377 * and therefore this function will return their indices in the
378 * FECollection, namely `{0,1}`.
379 *
380 * The @p codim parameter describes the codimension of the investigated
381 * subspace and specifies that it is subject to this comparison. See
382 * FiniteElement::compare_for_domination() for more information.
383 */
384 std::set<unsigned int>
385 find_common_fes(const std::set<unsigned int> &fes,
386 const unsigned int codim = 0) const;
387
388 /**
389 * Return the indices of finite elements in this FECollection that are
390 * dominated by all elements associated with the provided set of indices @p fes.
391 *
392 * You may find information about the domination behavior of finite elements
393 * in their respective class documentation or in the implementation of their
394 * inherited member function FiniteElement::compare_for_domination().
395 * Consider that a finite element may or may not dominate itself (e.g.
396 * FE_Nothing elements).
397 *
398 * For example, if a FECollection consists of
399 * `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements and we are looking for the
400 * finite elements that are dominated by the middle elements of this
401 * collection (i.e., @p fes is `{1,2}`), then the answer is `{FE_Q(3),FE_Q(4)`
402 * and therefore this function will return their indices in the
403 * FECollection, namely `{2,3}`.
404 *
405 * The @p codim parameter describes the codimension of the investigated
406 * subspace and specifies that it is subject to this comparison. See
407 * FiniteElement::compare_for_domination() for more information.
408 */
409 std::set<unsigned int>
410 find_enclosing_fes(const std::set<unsigned int> &fes,
411 const unsigned int codim = 0) const;
412
413 /**
414 * Return the index of a finite element from the provided set of indices @p fes
415 * that dominates all other elements of this very set.
416 *
417 * You may find information about the domination behavior of finite elements
418 * in their respective class documentation or in the implementation of their
419 * inherited member function FiniteElement::compare_for_domination().
420 * Consider that a finite element may or may not dominate itself (e.g.
421 * FE_Nothing elements).
422 *
423 * If this set consists of exactly one element, we consider it to be
424 * the dominating one and return its corresponding index. Further, if the
425 * function is not able to find a finite element at all, it returns
426 * numbers::invalid_fe_index.
427 *
428 * For example, if a FECollection consists of
429 * `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements and we are looking for the
430 * dominating finite element among the middle elements of this
431 * collection (i.e., @p fes is `{1,2}`), then the answer is FE_Q(2)
432 * and therefore this function will return its index in the
433 * FECollection, namely `1`.
434 *
435 * It is of course possible that there is more than one element that
436 * dominates all selected elements. For example, if the collection consists
437 * of `{FE_Q(1),FE_Q(1),FE_Q(2),FE_Q(2)}` and `fes` covers all indices,
438 * then one could return zero or one. In that case, the function returns
439 * either `0` or `1` since there is no tie-breaker between the two.
440 *
441 * The @p codim parameter describes the codimension of the investigated
442 * subspace and specifies that it is subject to this comparison. See
443 * FiniteElement::compare_for_domination() for more information.
444 */
445 unsigned int
446 find_dominating_fe(const std::set<unsigned int> &fes,
447 const unsigned int codim = 0) const;
448
449 /**
450 * Return the index of a finite element from the provided set of indices @p fes
451 * that is dominated by all other elements of this very set.
452 *
453 * You may find information about the domination behavior of finite elements
454 * in their respective class documentation or in the implementation of their
455 * inherited member function FiniteElement::compare_for_domination().
456 * Consider that a finite element may or may not dominate itself (e.g.
457 * FE_Nothing elements).
458 *
459 * If this set consists of exactly one element, we consider it to be
460 * the dominated one and return its corresponding index. Further, if the
461 * function is not able to find a finite element at all, it returns
462 * numbers::invalid_fe_index.
463 *
464 * For example, if a FECollection consists of
465 * `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements and we are looking for the
466 * dominated finite element among the middle elements of this
467 * collection (i.e., @p fes is `{1,2}`), then the answer is FE_Q(3)
468 * and therefore this function will return its index in the
469 * FECollection, namely `2`.
470 *
471 * It is of course possible that there is more than one element that is
472 * dominated by all selected elements. For example, if the collection
473 * consists of `{FE_Q(1),FE_Q(1),FE_Q(2),FE_Q(2)}` and `fes` covers all
474 * indices, then one could return two or three. In that case, the function
475 * returns either `2` or `3` since there is no tie-breaker between the two.
476 *
477 * The @p codim parameter describes the codimension of the investigated
478 * subspace and specifies that it is subject to this comparison. See
479 * FiniteElement::compare_for_domination() for more information.
480 */
481 unsigned int
482 find_dominated_fe(const std::set<unsigned int> &fes,
483 const unsigned int codim = 0) const;
484
485 /**
486 * Return the index of a finite element from the provided set of indices @p fes
487 * that dominates all other elements of this very set. If we do not succeed,
488 * we extend our search on the whole collection by picking the least
489 * dominating one, which is the element that describes the largest finite
490 * element space of which all of the finite elements of the
491 * provided set @p fes are part of.
492 *
493 * You may find information about the domination behavior of finite elements
494 * in their respective class documentation or in the implementation of their
495 * inherited member function FiniteElement::compare_for_domination().
496 * Consider that a finite element may or may not dominate itself (e.g.
497 * FE_Nothing elements).
498 *
499 * If this set consists of exactly one element, we consider it to be
500 * the dominated one and return its corresponding index. Further, if the
501 * function is not able to find a finite element at all, it returns
502 * numbers::invalid_fe_index.
503 *
504 * The @p codim parameter describes the codimension of the investigated
505 * subspace and specifies that it is subject to this comparison. See
506 * FiniteElement::compare_for_domination() for more information.
507 */
508 unsigned int
509 find_dominating_fe_extended(const std::set<unsigned int> &fes,
510 const unsigned int codim = 0) const;
511
512 /**
513 * Return the index of a finite element from the provided set of indices @p fes
514 * that is dominated by all other elements of this very set. If we do not
515 * succeed, we extend our search on the whole collection by picking the most
516 * dominated one, which is the element that describes the smallest finite
517 * element space which includes all finite elements of the provided set @p fes.
518 *
519 * You may find information about the domination behavior of finite elements
520 * in their respective class documentation or in the implementation of their
521 * inherited member function FiniteElement::compare_for_domination().
522 * Consider that a finite element may or may not dominate itself (e.g.
523 * FE_Nothing elements).
524 *
525 * If this set consists of exactly one element, we consider it to be
526 * the dominating one and return its corresponding index. Further, if the
527 * function is not able to find a finite element at all, it returns
528 * numbers::invalid_fe_index.
529 *
530 * The @p codim parameter describes the codimension of the investigated
531 * subspace and specifies that it is subject to this comparison. See
532 * FiniteElement::compare_for_domination() for more information.
533 */
534 unsigned int
535 find_dominated_fe_extended(const std::set<unsigned int> &fes,
536 const unsigned int codim = 0) const;
537
538 /**
539 * @}
540 */
541
542 /**
543 * @name Describing hierarchical relationships between elements
544 */
545
546 /**
547 * @{
548 */
549
550 /**
551 * Set functions determining the hierarchy of finite elements, i.e. a
552 * function @p next that returns the index of the finite element following
553 * the given one, and a function @p prev returning the preceding one.
554 *
555 * Both functions expect an hp::FECollection to be passed along with a
556 * finite element index, on whose basis the new index will be found and
557 * returned.
558 *
559 * @note Both passed and returned indices have to be valid within the index
560 * range of this collection, i.e. within [0, size()).
561 */
562 void
563 set_hierarchy(const std::function<unsigned int(
564 const typename hp::FECollection<dim, spacedim> &,
565 const unsigned int)> &next,
566 const std::function<unsigned int(
567 const typename hp::FECollection<dim, spacedim> &,
568 const unsigned int)> &prev);
569
570 /**
571 * Set the default hierarchy corresponding to the index of each finite
572 * element in the collection.
573 *
574 * This default hierarchy is established with functions
575 * DefaultHierarchy::next_index() and DefaultHierarchy::previous_index().
576 */
577 void
578 set_default_hierarchy();
579
580 /**
581 * Returns a sequence of FE indices that corresponds to the registered
582 * hierarchy in ascending order, i.e., FE indices are sorted from lowest to
583 * highest level.
584 *
585 * Multiple sequences of FE indices are possible with a single custom
586 * hierarchy that can be registered with set_hierarchy(). This function
587 * will return the sequence that contains the user-provided index
588 * @p fe_index which could be located anywhere inside the sequence. The
589 * default hierarchy set via set_default_hierarchy(), which corresponds to
590 * FE indices in ascending order, consists of only one sequence.
591 *
592 * This function can be used, for example, to verify that your provided
593 * hierarchy covers all elements in the desired order.
594 *
595 * Only one sequence of FE indices exists if the size of the returned
596 * container equals the number of elements of this object, i.e.,
597 * FECollection::size().
598 */
599 std::vector<unsigned int>
600 get_hierarchy_sequence(const unsigned int fe_index = 0) const;
601
602 /**
603 * %Function returning the index of the finite element following the given
604 * @p fe_index in hierarchy.
605 *
606 * By default, the index succeeding @p fe_index will be returned. If @p fe_index
607 * already corresponds to the last index, the last index will be returned.
608 * A custom hierarchy can be supplied via the member function
609 * set_hierarchy().
610 */
611 unsigned int
612 next_in_hierarchy(const unsigned int fe_index) const;
613
614 /**
615 * %Function returning the index of the finite element preceding the given
616 * @p fe_index in hierarchy.
617 *
618 * By default, the index preceding @p fe_index will be returned. If @p fe_index
619 * already corresponds to the first index, the first index will be returned.
620 * A custom hierarchy can be supplied via the member function
621 * set_hierarchy().
622 */
623 unsigned int
624 previous_in_hierarchy(const unsigned int fe_index) const;
625
626 /**
627 * @}
628 */
629
630 /**
631 * @name Components and blocks of elements
632 */
633
634 /**
635 * @{
636 */
637
638 /**
639 * Return a component mask with as many elements as this object has vector
640 * components and of which exactly the one component is true that
641 * corresponds to the given argument.
642 *
643 * @note This function is the equivalent of
644 * FiniteElement::component_mask() with the same arguments. It verifies
645 * that it gets the same result from every one of the elements that are
646 * stored in this FECollection. If this is not the case, it throws an
647 * exception.
648 *
649 * @param scalar An object that represents a single scalar vector
650 * component of this finite element.
651 * @return A component mask that is false in all components except for the
652 * one that corresponds to the argument.
653 */
654 ComponentMask
655 component_mask(const FEValuesExtractors::Scalar &scalar) const;
656
657 /**
658 * Return a component mask with as many elements as this object has vector
659 * components and of which exactly the <code>dim</code> components are
660 * true that correspond to the given argument.
661 *
662 * @note This function is the equivalent of
663 * FiniteElement::component_mask() with the same arguments. It verifies
664 * that it gets the same result from every one of the elements that are
665 * stored in this FECollection. If this is not the case, it throws an
666 * exception.
667 *
668 * @param vector An object that represents dim vector components of this
669 * finite element.
670 * @return A component mask that is false in all components except for the
671 * ones that corresponds to the argument.
672 */
673 ComponentMask
674 component_mask(const FEValuesExtractors::Vector &vector) const;
675
676 /**
677 * Return a component mask with as many elements as this object has vector
678 * components and of which exactly the <code>dim*(dim+1)/2</code>
679 * components are true that correspond to the given argument.
680 *
681 * @note This function is the equivalent of
682 * FiniteElement::component_mask() with the same arguments. It verifies
683 * that it gets the same result from every one of the elements that are
684 * stored in this FECollection. If this is not the case, it throws an
685 * exception.
686 *
687 * @param sym_tensor An object that represents dim*(dim+1)/2 components of
688 * this finite element that are jointly to be interpreted as forming a
689 * symmetric tensor.
690 * @return A component mask that is false in all components except for the
691 * ones that corresponds to the argument.
692 */
693 ComponentMask
694 component_mask(
695 const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
696
697 /**
698 * Given a block mask (see
699 * @ref GlossBlockMask "this glossary entry"
700 * ), produce a component mask (see
701 * @ref GlossComponentMask "this glossary entry"
702 * ) that represents the components that correspond to the blocks selected
703 * in the input argument. This is essentially a conversion operator from
704 * BlockMask to ComponentMask.
705 *
706 * @note This function is the equivalent of
707 * FiniteElement::component_mask() with the same arguments. It verifies
708 * that it gets the same result from every one of the elements that are
709 * stored in this FECollection. If this is not the case, it throws an
710 * exception.
711 *
712 * @param block_mask The mask that selects individual blocks of the finite
713 * element
714 * @return A mask that selects those components corresponding to the
715 * selected blocks of the input argument.
716 */
717 ComponentMask
718 component_mask(const BlockMask &block_mask) const;
719
720 /**
721 * Return a block mask with as many elements as this object has blocks and
722 * of which exactly the one component is true that corresponds to the
723 * given argument. See
724 * @ref GlossBlockMask "the glossary"
725 * for more information.
726 *
727 * @note This function will only succeed if the scalar referenced by the
728 * argument encompasses a complete block. In other words, if, for example,
729 * you pass an extractor for the single $x$ velocity and this object
730 * represents an FE_RaviartThomas object, then the single scalar object
731 * you selected is part of a larger block and consequently there is no
732 * block mask that would represent it. The function will then produce an
733 * exception.
734 *
735 * @note This function is the equivalent of
736 * FiniteElement::component_mask() with the same arguments. It verifies
737 * that it gets the same result from every one of the elements that are
738 * stored in this FECollection. If this is not the case, it throws an
739 * exception.
740 *
741 * @param scalar An object that represents a single scalar vector
742 * component of this finite element.
743 * @return A component mask that is false in all components except for the
744 * one that corresponds to the argument.
745 */
746 BlockMask
747 block_mask(const FEValuesExtractors::Scalar &scalar) const;
748
749 /**
750 * Return a component mask with as many elements as this object has vector
751 * components and of which exactly the <code>dim</code> components are
752 * true that correspond to the given argument. See
753 * @ref GlossBlockMask "the glossary"
754 * for more information.
755 *
756 * @note This function is the equivalent of
757 * FiniteElement::component_mask() with the same arguments. It verifies
758 * that it gets the same result from every one of the elements that are
759 * stored in this FECollection. If this is not the case, it throws an
760 * exception.
761 *
762 * @note The same caveat applies as to the version of the function above:
763 * The extractor object passed as argument must be so that it corresponds
764 * to full blocks and does not split blocks of this element.
765 *
766 * @param vector An object that represents dim vector components of this
767 * finite element.
768 * @return A component mask that is false in all components except for the
769 * ones that corresponds to the argument.
770 */
771 BlockMask
772 block_mask(const FEValuesExtractors::Vector &vector) const;
773
774 /**
775 * Return a component mask with as many elements as this object has vector
776 * components and of which exactly the <code>dim*(dim+1)/2</code>
777 * components are true that correspond to the given argument. See
778 * @ref GlossBlockMask "the glossary"
779 * for more information.
780 *
781 * @note The same caveat applies as to the version of the function above:
782 * The extractor object passed as argument must be so that it corresponds
783 * to full blocks and does not split blocks of this element.
784 *
785 * @note This function is the equivalent of
786 * FiniteElement::component_mask() with the same arguments. It verifies
787 * that it gets the same result from every one of the elements that are
788 * stored in this FECollection. If this is not the case, it throws an
789 * exception.
790 *
791 * @param sym_tensor An object that represents dim*(dim+1)/2 components of
792 * this finite element that are jointly to be interpreted as forming a
793 * symmetric tensor.
794 * @return A component mask that is false in all components except for the
795 * ones that corresponds to the argument.
796 */
797 BlockMask
798 block_mask(const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
799
800 /**
801 * Given a component mask (see
802 * @ref GlossComponentMask "this glossary entry"
803 * ), produce a block mask (see
804 * @ref GlossBlockMask "this glossary entry"
805 * ) that represents the blocks that correspond to the components selected
806 * in the input argument. This is essentially a conversion operator from
807 * ComponentMask to BlockMask.
808 *
809 * @note This function will only succeed if the components referenced by
810 * the argument encompasses complete blocks. In other words, if, for
811 * example, you pass an component mask for the single $x$ velocity and
812 * this object represents an FE_RaviartThomas object, then the single
813 * component you selected is part of a larger block and consequently there
814 * is no block mask that would represent it. The function will then
815 * produce an exception.
816 *
817 * @note This function is the equivalent of
818 * FiniteElement::component_mask() with the same arguments. It verifies
819 * that it gets the same result from every one of the elements that are
820 * stored in this FECollection. If this is not the case, it throws an
821 * exception.
822 *
823 * @param component_mask The mask that selects individual components of
824 * the finite element
825 * @return A mask that selects those blocks corresponding to the selected
826 * blocks of the input argument.
827 */
828 BlockMask
829 block_mask(const ComponentMask &component_mask) const;
830
831 /**
832 * @}
833 */
834
835 /**
836 * @name Exceptions
837 * @{
838 */
839
840 /**
841 * Exception
842 *
843 * @ingroup Exceptions
844 */
845 DeclException0(ExcNoFiniteElements);
846
847 /**
848 * @}
849 */
850
851 private:
852 /**
853 * A linear mapping collection for all reference cell types of each index
854 * of this object.
855 */
856 std::shared_ptr<MappingCollection<dim, spacedim>>
857 reference_cell_default_linear_mapping;
858
859 /**
860 * %Function returning the index of the finite element following the given
861 * one in hierarchy.
862 */
863 std::function<unsigned int(const typename hp::FECollection<dim, spacedim> &,
864 const unsigned int)>
865 hierarchy_next;
866
867 /**
868 * %Function returning the index of the finite element preceding the given
869 * one in hierarchy.
870 */
871 std::function<unsigned int(const typename hp::FECollection<dim, spacedim> &,
872 const unsigned int)>
873 hierarchy_prev;
874 };
875
876
877
878 /* --------------- inline functions ------------------- */
879
880 template <int dim, int spacedim>
881 template <class... FETypes>
882 FECollection<dim, spacedim>::FECollection(const FETypes &...fes)
883 {
884 static_assert(
885 is_base_of_all<FiniteElement<dim, spacedim>, FETypes...>::value,
886 "Not all of the input arguments of this function "
887 "are derived from FiniteElement<dim, spacedim>!");
888
889 // loop over all of the given arguments and add the finite elements to
890 // this collection. Inlining the definition of fe_pointers causes internal
891 // compiler errors on GCC 7.1.1 so we define it separately:
892 const auto fe_pointers = {
893 (static_cast<const FiniteElement<dim, spacedim> *>(&fes))...};
894 for (const auto p : fe_pointers)
895 push_back(*p);
896 }
897
898
899
900 template <int dim, int spacedim>
901 inline unsigned int
902 FECollection<dim, spacedim>::n_components() const
903 {
904 Assert(this->size() > 0, ExcNoFiniteElements());
905
906 // note that there is no need
907 // here to enforce that indeed
908 // all elements have the same
909 // number of components since we
910 // have already done this when
911 // adding a new element to the
912 // collection.
913
914 return this->operator[](0).n_components();
915 }
916
917
918
919 template <int dim, int spacedim>
920 inline bool
921 FECollection<dim, spacedim>::operator==(
922 const FECollection<dim, spacedim> &fe_collection) const
923 {
924 const unsigned int n_elements = this->size();
925 if (n_elements != fe_collection.size())
926 return false;
927
928 for (unsigned int i = 0; i < n_elements; ++i)
929 if (!(this->operator[](i) == fe_collection[i]))
930 return false;
931
932 return true;
933 }
934
935
936
937 template <int dim, int spacedim>
938 inline bool
939 FECollection<dim, spacedim>::operator!=(
940 const FECollection<dim, spacedim> &fe_collection) const
941 {
942 return !(*this == fe_collection);
943 }
944
945
946
947 template <int dim, int spacedim>
948 unsigned int
949 FECollection<dim, spacedim>::max_degree() const
950 {
951 Assert(this->size() > 0, ExcNoFiniteElements());
952
953 unsigned int max = 0;
954 for (unsigned int i = 0; i < this->size(); ++i)
955 max = std::max(max, this->operator[](i).degree);
956
957 return max;
958 }
959
960
961
962 template <int dim, int spacedim>
963 unsigned int
964 FECollection<dim, spacedim>::max_dofs_per_vertex() const
965 {
966 Assert(this->size() > 0, ExcNoFiniteElements());
967
968 unsigned int max = 0;
969 for (unsigned int i = 0; i < this->size(); ++i)
970 max = std::max(max, this->operator[](i).n_dofs_per_vertex());
971
972 return max;
973 }
974
975
976
977 template <int dim, int spacedim>
978 unsigned int
979 FECollection<dim, spacedim>::max_dofs_per_line() const
980 {
981 Assert(this->size() > 0, ExcNoFiniteElements());
982
983 unsigned int max = 0;
984 for (unsigned int i = 0; i < this->size(); ++i)
985 max = std::max(max, this->operator[](i).n_dofs_per_line());
986
987 return max;
988 }
989
990
991
992 template <int dim, int spacedim>
993 unsigned int
994 FECollection<dim, spacedim>::max_dofs_per_quad() const
995 {
996 Assert(this->size() > 0, ExcNoFiniteElements());
997
998 unsigned int max = 0;
999 for (unsigned int i = 0; i < this->size(); ++i)
1000 max = std::max(max, this->operator[](i).max_dofs_per_quad());
1001
1002 return max;
1003 }
1004
1005
1006
1007 template <int dim, int spacedim>
1008 unsigned int
1009 FECollection<dim, spacedim>::max_dofs_per_hex() const
1010 {
1011 Assert(this->size() > 0, ExcNoFiniteElements());
1012
1013 unsigned int max = 0;
1014 for (unsigned int i = 0; i < this->size(); ++i)
1015 max = std::max(max, this->operator[](i).n_dofs_per_hex());
1016
1017 return max;
1018 }
1019
1020
1021
1022 template <int dim, int spacedim>
1023 unsigned int
1024 FECollection<dim, spacedim>::max_dofs_per_face() const
1025 {
1026 Assert(this->size() > 0, ExcNoFiniteElements());
1027
1028 unsigned int max = 0;
1029 for (unsigned int i = 0; i < this->size(); ++i)
1030 max = std::max(max, this->operator[](i).max_dofs_per_face());
1031
1032 return max;
1033 }
1034
1035
1036
1037 template <int dim, int spacedim>
1038 unsigned int
1039 FECollection<dim, spacedim>::max_dofs_per_cell() const
1040 {
1041 Assert(this->size() > 0, ExcNoFiniteElements());
1042
1043 unsigned int max = 0;
1044 for (unsigned int i = 0; i < this->size(); ++i)
1045 max = std::max(max, this->operator[](i).n_dofs_per_cell());
1046
1047 return max;
1048 }
1049
1050
1051 template <int dim, int spacedim>
1052 bool
1053 FECollection<dim, spacedim>::hp_constraints_are_implemented() const
1054 {
1055 Assert(this->size() > 0, ExcNoFiniteElements());
1056
1057 for (unsigned int i = 0; i < this->size(); ++i)
1058 if (this->operator[](i).hp_constraints_are_implemented() == false)
1059 return false;
1060
1061 return true;
1062 }
1063
1064
1065 } // namespace hp
1066
1067 DEAL_II_NAMESPACE_CLOSE
1068
1069 #endif