Debian Codegraph @

include/deal.II/fe/fe_dgq.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 2023 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_dgq_h
16 #define dealii_fe_dgq_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/mutex.h>
21 #include <deal.II/base/tensor_product_polynomials.h>
22
23 #include <deal.II/fe/fe_poly.h>
24
25 DEAL_II_NAMESPACE_OPEN
26
27 // Forward declarations
28 #ifndef DOXYGEN
29 template <int dim, int spacedim>
30 class MappingQ;
31 template <int dim>
32 class Quadrature;
33 #endif
34
35 /**
36 * @addtogroup fe
37 * @{
38 */
39
40 /**
41 * Implementation of scalar, discontinuous tensor product elements based on
42 * equidistant support points.
43 *
44 * This is a discontinuous finite element based on tensor products of
45 * Lagrangian polynomials. The shape functions are Lagrangian interpolants of
46 * an equidistant grid of points on the unit cell. The points are numbered in
47 * lexicographical order, with <i>x</i> running fastest, then <i>y</i>, then
48 * <i>z</i> (if these coordinates are present for a given space dimension at
49 * all). For example, these are the node orderings for <tt>FE_DGQ(1)</tt> in
50 * 3d:
51 * @verbatim
52 * 6-------7 6-------7
53 * /| | / /|
54 * / | | / / |
55 * / | | / / |
56 * 4 | | 4-------5 |
57 * | 2-------3 | | 3
58 * | / / | | /
59 * | / / | | /
60 * |/ / | |/
61 * 0-------1 0-------1
62 * @endverbatim
63 * and <tt>FE_DGQ(2)</tt>:
64 * @verbatim
65 * 24--25--26 24--25--26
66 * /| | / /|
67 * 21 | | 21 22 23 |
68 * / 15 16 17 / / 17
69 * 18 | | 18--19--20 |
70 * |12 6---7---8 | |14 8
71 * 9 / / 9 10 11 /
72 * | 3 4 5 | | 5
73 * |/ / | |/
74 * 0---1---2 0---1---2
75 * @endverbatim
76 * with node 13 being placed in the interior of the hex.
77 *
78 * Note, however, that these are just the Lagrange interpolation points of the
79 * shape functions. Even though they may physically be on the boundary of the
80 * cell, they are logically in the interior since there are no continuity
81 * requirements for these shape functions across cell boundaries. While
82 * discontinuous, when restricted to a single cell the shape functions of this
83 * element are exactly the same as those of the FE_Q element where they are
84 * shown visually.
85 *
86 * <h3>Unit support point distribution and conditioning of interpolation</h3>
87 *
88 * When constructing an FE_DGQ element at polynomial degrees one or two,
89 * equidistant support points at 0 and 1 (linear case) or 0, 0.5, and 1
90 * (quadratic case) are used. The unit support or nodal points
91 * <i>x<sub>i</sub></i> are those points where the <i>j</i>th Lagrange
92 * polynomial satisfies the $\delta_{ij}$ property, i.e., where one polynomial
93 * is one and all the others are zero. For higher polynomial degrees, the
94 * support points are non-equidistant by default, and chosen to be the support
95 * points of the <tt>(degree+1)</tt>-order Gauss-Lobatto quadrature rule. This
96 * point distribution yields well-conditioned Lagrange interpolation at
97 * arbitrary polynomial degrees. By contrast, polynomials based on equidistant
98 * points get increasingly ill-conditioned as the polynomial degree
99 * increases. In interpolation, this effect is known as the Runge
100 * phenomenon. For Galerkin methods, the Runge phenomenon is typically not
101 * visible in the solution quality but rather in the condition number of the
102 * associated system matrices. For example, the elemental @ref GlossMassMatrix "mass matrix" of
103 * equidistant points at degree 10 has condition number 2.6e6, whereas the
104 * condition number for Gauss-Lobatto points is around 400.
105 *
106 * The Gauss-Lobatto points in 1d include the end points 0 and +1 of the unit
107 * interval. The interior points are shifted towards the end points, which
108 * gives a denser point distribution close to the element boundary.
109 */
110 template <int dim, int spacedim = dim>
111 class FE_DGQ : public FE_Poly<dim, spacedim>
112 {
113 public:
114 /**
115 * Constructor for tensor product polynomials of degree <tt>p</tt>. The
116 * shape functions created using this constructor correspond to Lagrange
117 * interpolation polynomials for Gauss-Lobatto support (node) points in each
118 * coordinate direction.
119 */
120 FE_DGQ(const unsigned int p);
121
122 /**
123 * Return a string that uniquely identifies a finite element. This class
124 * returns <tt>FE_DGQ<dim>(degree)</tt>, with <tt>dim</tt> and
125 * <tt>degree</tt> replaced by appropriate values.
126 */
127 virtual std::string
128 get_name() const override;
129
130 /**
131 * Return the matrix interpolating from the given finite element to the
132 * present one. The size of the matrix is then @p dofs_per_cell times
133 * <tt>source.n_dofs_per_cell()</tt>.
134 *
135 * These matrices are only available if the source element is also a @p
136 * FE_DGQ element. Otherwise, an exception of type
137 * FiniteElement<dim>::ExcInterpolationNotImplemented is thrown.
138 */
139 virtual void
140 get_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
141 FullMatrix<double> &matrix) const override;
142
143 /**
144 * Return the matrix interpolating from a face of one element to the face
145 * of the neighboring element. The size of the matrix is then
146 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
147 *
148 * Derived elements will have to implement this function. They may only
149 * provide interpolation matrices for certain source finite elements, for
150 * example those from the same family. If they don't implement interpolation
151 * from a given element, then they must throw an exception of type
152 * FiniteElement<dim>::ExcInterpolationNotImplemented.
153 */
154 virtual void
155 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
156 FullMatrix<double> &matrix,
157 const unsigned int face_no = 0) const override;
158
159 /**
160 * Return the matrix interpolating from a face of one element to the face
161 * of the neighboring element. The size of the matrix is then
162 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
163 *
164 * Derived elements will have to implement this function. They may only
165 * provide interpolation matrices for certain source finite elements, for
166 * example those from the same family. If they don't implement interpolation
167 * from a given element, then they must throw an exception of type
168 * FiniteElement<dim>::ExcInterpolationNotImplemented.
169 */
170 virtual void
171 get_subface_interpolation_matrix(
172 const FiniteElement<dim, spacedim> &source,
173 const unsigned int subface,
174 FullMatrix<double> &matrix,
175 const unsigned int face_no = 0) const override;
176
177 /**
178 * Projection from a fine grid space onto a coarse grid space. Overrides the
179 * respective method in FiniteElement, implementing lazy evaluation
180 * (initialize when requested).
181 *
182 * If this projection operator is associated with a matrix @p P, then the
183 * restriction of this matrix @p P_i to a single child cell is returned
184 * here.
185 *
186 * The matrix @p P is the concatenation or the sum of the cell matrices @p
187 * P_i, depending on the #restriction_is_additive_flags. This distinguishes
188 * interpolation (concatenation) and projection with respect to scalar
189 * products (summation).
190 *
191 * Row and column indices are related to coarse grid and fine grid spaces,
192 * respectively, consistent with the definition of the associated operator.
193 */
194 virtual const FullMatrix<double> &
195 get_restriction_matrix(
196 const unsigned int child,
197 const RefinementCase<dim> &refinement_case =
198 RefinementCase<dim>::isotropic_refinement) const override;
199
200 /**
201 * Embedding matrix between grids. Overrides the respective method in
202 * FiniteElement, implementing lazy evaluation (initialize when queried).
203 *
204 * The identity operator from a coarse grid space into a fine grid space is
205 * associated with a matrix @p P. The restriction of this matrix @p P_i to a
206 * single child cell is returned here.
207 *
208 * The matrix @p P is the concatenation, not the sum of the cell matrices @p
209 * P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in two
210 * different child matrices @p P_i, the value should be the same in both
211 * matrices and it is copied into the matrix @p P only once.
212 *
213 * Row and column indices are related to fine grid and coarse grid spaces,
214 * respectively, consistent with the definition of the associated operator.
215 *
216 * These matrices are used by routines assembling the prolongation matrix
217 * for multi-level methods. Upon assembling the transfer matrix between
218 * cells using this matrix array, zero elements in the prolongation matrix
219 * are discarded and will not fill up the transfer matrix.
220 */
221 virtual const FullMatrix<double> &
222 get_prolongation_matrix(
223 const unsigned int child,
224 const RefinementCase<dim> &refinement_case =
225 RefinementCase<dim>::isotropic_refinement) const override;
226
227 /**
228 * @name Functions to support hp
229 * @{
230 */
231
232 /**
233 * If, on a vertex, several finite elements are active, the hp-code first
234 * assigns the degrees of freedom of each of these FEs different global
235 * indices. It then calls this function to find out which of them should get
236 * identical values, and consequently can receive the same global DoF index.
237 * This function therefore returns a list of identities between DoFs of the
238 * present finite element object with the DoFs of @p fe_other, which is a
239 * reference to a finite element object representing one of the other finite
240 * elements active on this particular vertex. The function computes which of
241 * the degrees of freedom of the two finite element objects are equivalent,
242 * both numbered between zero and the corresponding value of
243 * n_dofs_per_vertex() of the two finite elements. The first index of each
244 * pair denotes one of the vertex dofs of the present element, whereas the
245 * second is the corresponding index of the other finite element.
246 *
247 * This being a discontinuous element, the set of such constraints is of
248 * course empty.
249 */
250 virtual std::vector<std::pair<unsigned int, unsigned int>>
251 hp_vertex_dof_identities(
252 const FiniteElement<dim, spacedim> &fe_other) const override;
253
254 /**
255 * Same as hp_vertex_dof_indices(), except that the function treats degrees
256 * of freedom on lines.
257 *
258 * This being a discontinuous element, the set of such constraints is of
259 * course empty.
260 */
261 virtual std::vector<std::pair<unsigned int, unsigned int>>
262 hp_line_dof_identities(
263 const FiniteElement<dim, spacedim> &fe_other) const override;
264
265 /**
266 * Same as hp_vertex_dof_indices(), except that the function treats degrees
267 * of freedom on quads.
268 *
269 * This being a discontinuous element, the set of such constraints is of
270 * course empty.
271 */
272 virtual std::vector<std::pair<unsigned int, unsigned int>>
273 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
274 const unsigned int face_no = 0) const override;
275
276 /**
277 * Return whether this element implements its hanging node constraints in
278 * the new way, which has to be used to make elements "hp-compatible".
279 *
280 * For the FE_DGQ class the result is always true (independent of the degree
281 * of the element), as it has no hanging nodes (being a discontinuous
282 * element).
283 */
284 virtual bool
285 hp_constraints_are_implemented() const override;
286
287 /**
288 * @copydoc FiniteElement::compare_for_domination()
289 */
290 virtual FiniteElementDomination::Domination
291 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
292 const unsigned int codim = 0) const override final;
293
294 /**
295 * @}
296 */
297
298 /**
299 * This function returns @p true, if the shape function @p shape_index has
300 * non-zero function values somewhere on the face @p face_index.
301 */
302 virtual bool
303 has_support_on_face(const unsigned int shape_index,
304 const unsigned int face_index) const override;
305
306 /**
307 * Return a list of constant modes of the element. For this element, it
308 * simply returns one row with all entries set to true.
309 */
310 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
311 get_constant_modes() const override;
312
313 /**
314 * Implementation of the corresponding function in the FiniteElement
315 * class. Since the current element is interpolatory, the nodal
316 * values are exactly the support point values. Furthermore, since
317 * the current element is scalar, the support point values need to
318 * be vectors of length 1.
319 */
320 virtual void
321 convert_generalized_support_point_values_to_dof_values(
322 const std::vector<Vector<double>> &support_point_values,
323 std::vector<double> &nodal_values) const override;
324
325 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
326 clone() const override;
327
328 protected:
329 /**
330 * Constructor for tensor product polynomials based on an arbitrary vector
331 * of polynomials. This constructor is used in derived classes to construct
332 * e.g. elements with arbitrary nodes or elements based on Legendre
333 * polynomials.
334 *
335 * The degree of these polynomials is <tt>polynomials.size()-1</tt>.
336 */
337 FE_DGQ(const std::vector<Polynomials::Polynomial<double>> &polynomials);
338
339 private:
340 /**
341 * Only for internal use. Its full name is @p get_dofs_per_object_vector
342 * function and it creates the @p dofs_per_object vector that is needed
343 * within the constructor to be passed to the constructor of @p
344 * FiniteElementData.
345 */
346 static std::vector<unsigned int>
347 get_dpo_vector(const unsigned int degree);
348
349 /**
350 * Compute renumbering for rotation of degrees of freedom.
351 *
352 * This function rotates a tensor product numbering of degrees of
353 * freedom by 90 degrees. It is used to compute the transfer
354 * matrices of the children by using only the matrix for the first
355 * child.
356 *
357 * The direction parameter determines the type of rotation. It is one
358 * character of @p xXyYzZ. The character determines the axis of rotation,
359 * case determines the direction. Lower case is counter-clockwise seen in
360 * direction of the axis.
361 *
362 * Since rotation around the y-axis is not used, it is not implemented
363 * either.
364 */
365 void
366 rotate_indices(std::vector<unsigned int> &indices,
367 const char direction) const;
368
369 /**
370 * Mutex variables used for protecting the initialization of restriction
371 * and embedding matrices.
372 */
373 mutable Threads::Mutex restriction_matrix_mutex;
374 mutable Threads::Mutex prolongation_matrix_mutex;
375
376 // Allow access from other dimensions.
377 template <int dim1, int spacedim1>
378 friend class FE_DGQ;
379
380 // Allow @p MappingQ class to access to build_renumbering function.
381 template <int dim1, int spacedim1>
382 friend class MappingQ;
383 };
384
385
386
387 /**
388 * Implementation of scalar, discontinuous tensor product elements based on
389 * Lagrange polynomials with arbitrary nodes. The primary purpose of this
390 * class is to provide an element for which the @ref GlossMassMatrix "mass matrix" can be made
391 * diagonal by choosing basis functions that are not either zero or one at the
392 * vertices of the cell, but instead are zero or one at a given set of
393 * quadrature points. If this set of quadrature points is then also used in
394 * integrating the mass matrix, then it will be diagonal. The number of
395 * quadrature points automatically determines the polynomial degree chosen for
396 * this element. The typical applications are the Gauss quadrature or the
397 * Gauss-Lobatto quadrature (provided through the base class).
398 *
399 * See the base class documentation in FE_DGQ for details.
400 */
401 template <int dim, int spacedim = dim>
402 class FE_DGQArbitraryNodes : public FE_DGQ<dim, spacedim>
403 {
404 public:
405 /**
406 * Constructor for tensor product polynomials based on Polynomials::Lagrange
407 * interpolation of the support points in the quadrature rule
408 * <tt>points</tt>. The degree of these polynomials is
409 * <tt>points.size()-1</tt>.
410 */
411 FE_DGQArbitraryNodes(const Quadrature<1> &points);
412
413 /**
414 * Return a string that uniquely identifies a finite element. This class
415 * returns <tt>FE_DGQArbitraryNodes<dim>(degree)</tt>, with <tt>dim</tt> and
416 * <tt>degree</tt> replaced by appropriate values.
417 */
418 virtual std::string
419 get_name() const override;
420
421 /**
422 * Implementation of the corresponding function in the FiniteElement
423 * class. Since the current element is interpolatory, the nodal
424 * values are exactly the support point values. Furthermore, since
425 * the current element is scalar, the support point values need to
426 * be vectors of length 1.
427 */
428 virtual void
429 convert_generalized_support_point_values_to_dof_values(
430 const std::vector<Vector<double>> &support_point_values,
431 std::vector<double> &nodal_values) const override;
432 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
433 clone() const override;
434 };
435
436
437
438 /**
439 * Implementation of scalar, discontinuous tensor product elements based on
440 * Legendre polynomials, described by the tensor product of the polynomial
441 * space Polynomials::Legendre. The tensor product is achieved using
442 * TensorProductPolynomials and the ordering of shape functions, like in
443 * TensorProductPolynomials, is lexicographic. For instance, the ordering in 2d
444 * is $P_0(x)P_0(y),\ P_1(x)P_0(y),\ \ldots,\ P_n(x)P_0(y),\ P_0(x)P_1(y),
445 * \ \ldots,\ P_n(x)P_1(y),\ \ldots,\ P_0(x)P_n(y),\ \ldots,\ P_n(x)P_n(y)$
446 * when <tt>degree=n</tt> where $\{P_i\}_{i=0}^{n}$ are the one-dimensional
447 * Legendre polynomials defined on $[0,1]$. As opposed to the basic FE_DGQ
448 * element, these elements are not interpolatory and no support points are
449 * defined.
450 *
451 * See the base class documentation in FE_DGQ for details.
452 */
453 template <int dim, int spacedim = dim>
454 class FE_DGQLegendre : public FE_DGQ<dim, spacedim>
455 {
456 public:
457 /**
458 * Constructor for tensor product polynomials based on Polynomials::Legendre
459 * interpolation.
460 */
461 FE_DGQLegendre(const unsigned int degree);
462
463 /**
464 * Return a list of constant modes of the element. For the Legendre basis,
465 * it returns one row where the first element (corresponding to the constant
466 * mode) is set to true and all other elements are set to false.
467 */
468 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
469 get_constant_modes() const override;
470
471 /**
472 * Return a string that uniquely identifies a finite element. This class
473 * returns <tt>FE_DGQLegendre<dim>(degree)</tt> with <tt>dim</tt> and
474 * <tt>degree</tt> replaced by the values given by the template parameter
475 * and the argument passed to the constructor, respectively.
476 */
477 virtual std::string
478 get_name() const override;
479
480 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
481 clone() const override;
482 };
483
484
485
486 /**
487 * Implementation of scalar, discontinuous tensor product elements based on
488 * Hermite-like polynomials, described by the polynomial space
489 * Polynomials::HermiteLikeInterpolation. As opposed to the basic FE_DGQ
490 * element, these elements are not interpolatory and no support points are
491 * defined.
492 *
493 * Note that Hermite polynomials are only available for degrees larger or
494 * equal to three, and thus the beneficial properties of
495 * Polynomials::HermiteLikeInterpolation with only two basis functions having
496 * a non-trivial value or derivative on a face per dimension is only present
497 * for higher degrees. To facilitate usage also for degrees zero to two, a
498 * usual Lagrange basis is constructed by this class.
499 *
500 * See the base class documentation in FE_DGQ for details.
501 */
502 template <int dim, int spacedim = dim>
503 class FE_DGQHermite : public FE_DGQ<dim, spacedim>
504 {
505 public:
506 /**
507 * Constructor for tensor product polynomials based on
508 * Polynomials::HermiteLikeInterpolation.
509 */
510 FE_DGQHermite(const unsigned int degree);
511
512 /**
513 * Return a string that uniquely identifies a finite element. This class
514 * returns <tt>FE_DGQHermite<dim>(degree)</tt>, with <tt>dim</tt> and
515 * <tt>degree</tt> replaced by the values given by the template parameter
516 * and the argument passed to the constructor, respectively.
517 */
518 virtual std::string
519 get_name() const override;
520
521 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
522 clone() const override;
523 };
524
525
526 /** @} */
527
528 DEAL_II_NAMESPACE_CLOSE
529
530 #endif