Debian Codegraph @

include/deal.II/fe/fe_dgp.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2002 - 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_dgp_h
16 #define dealii_fe_dgp_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/polynomial_space.h>
21
22 #include <deal.II/fe/fe_poly.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 /**
27 * @addtogroup fe
28 * @{
29 */
30
31 /**
32 * Discontinuous finite elements based on Legendre polynomials.
33 *
34 * This finite element implements complete polynomial spaces, that is,
35 * dim-dimensional polynomials of degree p. For example, in 2d the element
36 * FE_DGP(1) would represent the span of the functions $\{1,\hat x,\hat y\}$,
37 * which is in contrast to the element FE_DGQ(1) that is formed by the span of
38 * $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the DGP space has only three
39 * unknowns for each quadrilateral, it is immediately clear that this element
40 * can not be continuous.
41 *
42 * The basis functions used in this element for the space described above are
43 * chosen to form a Legendre basis on the unit square, i.e., in particular
44 * they are $L_2$-orthogonal and normalized on the reference cell (but not
45 * necessarily on the real cell). As a consequence, the first basis function
46 * of this element is always the function that is constant and equal to one,
47 * regardless of the polynomial degree of the element. In addition, as a
48 * result of the orthogonality of the basis functions, the @ref GlossMassMatrix "mass matrix" is
49 * diagonal if the grid cells are parallelograms. Note that this is in
50 * contrast to the FE_DGPMonomial class that actually uses the monomial basis
51 * listed above as basis functions, without transformation from reference to
52 * real cell.
53 *
54 * The shape functions are defined in the class PolynomialSpace. The
55 * polynomials used inside PolynomialSpace are Polynomials::Legendre up to
56 * degree <tt>p</tt> given in FE_DGP. For the ordering of the basis functions,
57 * refer to PolynomialSpace, remembering that the Legendre polynomials are
58 * ordered by ascending degree.
59 *
60 * @note This element is not defined by finding shape functions within the
61 * given function space that interpolate a particular set of points.
62 * Consequently, there are no support points to which a given function could
63 * be interpolated; finding a finite element function that approximates a
64 * given function is therefore only possible through projection, rather than
65 * interpolation. Secondly, the shape functions of this element do not jointly
66 * add up to one. As a consequence of this, adding or subtracting a constant
67 * value -- such as one would do to make a function have mean value zero --
68 * can not be done by simply subtracting the constant value from each degree
69 * of freedom. Rather, one needs to use the fact that the first basis function
70 * is constant equal to one and simply subtract the constant from the value of
71 * the degree of freedom corresponding to this first shape function on each
72 * cell.
73 *
74 *
75 * @note This class is only partially implemented for the codimension one case
76 * (<tt>spacedim != dim </tt>), since no passage of information between meshes
77 * of different refinement level is possible because the embedding and
78 * projection matrices are not computed in the class constructor.
79 *
80 * <h3>Transformation properties</h3>
81 *
82 * It is worth noting that under a (bi-, tri-)linear mapping, the space
83 * described by this element does not contain $P(k)$, even if we use a basis
84 * of polynomials of degree $k$. Consequently, for example, on meshes with
85 * non-affine cells, a linear function can not be exactly represented by
86 * elements of type FE_DGP(1) or FE_DGPMonomial(1).
87 *
88 * This can be understood by the following 2-d example: consider the cell with
89 * vertices at $(0,0),(1,0),(0,1),(s,s)$:
90 * @image html dgp_doesnt_contain_p.png
91 *
92 * For this cell, a bilinear transformation $F$ produces the relations $x=\hat
93 * x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate reference
94 * coordinates $\hat x,\hat y$ and coordinates in real space $x,y$. Under this
95 * mapping, the constant function is clearly mapped onto itself, but the two
96 * other shape functions of the $P_1$ space, namely $\phi_1(\hat x,\hat
97 * y)=\hat x$ and $\phi_2(\hat x,\hat y)=\hat y$ are mapped onto
98 * $\phi_1(x,y)=\frac{x-t}{t(s-1)},\phi_2(x,y)=t$ where
99 * $t=\frac{y}{s-x+sx+y-sy}$.
100 *
101 * For the simple case that $s=1$, i.e. if the real cell is the unit square,
102 * the expressions can be simplified to $t=y$ and
103 * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the functions
104 * $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and neither is any
105 * linear combination of them. Consequently, the linear functions are not
106 * within the range of the mapped $P_1$ polynomials.
107 *
108 * <h3>Visualization of shape functions</h3> In 2d, the shape functions of
109 * this element look as follows.
110 *
111 * <h4>$P_0$ element</h4>
112 *
113 * <table> <tr> <td align="center">
114 * @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0000.png
115 * </td>
116 *
117 * <td align="center"> </td> </tr> <tr> <td align="center"> $P_0$ element,
118 * shape function 0 </td>
119 *
120 * <td align="center"></tr> </table>
121 *
122 * <h4>$P_1$ element</h4>
123 *
124 * <table> <tr> <td align="center">
125 * @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0000.png
126 * </td>
127 *
128 * <td align="center">
129 * @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0001.png
130 * </td> </tr> <tr> <td align="center"> $P_1$ element, shape function 0 </td>
131 *
132 * <td align="center"> $P_1$ element, shape function 1 </td> </tr>
133 *
134 * <tr> <td align="center">
135 * @image html http://www.dealii.org/images/shape-functions/DGP/P1/P1_DGP_shape0002.png
136 * </td>
137 *
138 * <td align="center"> </td> </tr> <tr> <td align="center"> $P_1$ element,
139 * shape function 2 </td>
140 *
141 * <td align="center"></td> </tr> </table>
142 *
143 *
144 * <h4>$P_2$ element</h4>
145 *
146 * <table> <tr> <td align="center">
147 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0000.png
148 * </td>
149 *
150 * <td align="center">
151 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0001.png
152 * </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 0 </td>
153 *
154 * <td align="center"> $P_2$ element, shape function 1 </td> </tr>
155 *
156 * <tr> <td align="center">
157 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0002.png
158 * </td>
159 *
160 * <td align="center">
161 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0003.png
162 * </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 2 </td>
163 *
164 * <td align="center"> $P_2$ element, shape function 3 </td> </tr>
165 *
166 * <tr> <td align="center">
167 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0004.png
168 * </td>
169 *
170 * <td align="center">
171 * @image html http://www.dealii.org/images/shape-functions/DGP/P2/P2_DGP_shape0005.png
172 * </td> </tr> <tr> <td align="center"> $P_2$ element, shape function 4 </td>
173 *
174 * <td align="center"> $P_2$ element, shape function 5 </td> </tr> </table>
175 *
176 *
177 * <h4>$P_3$ element</h4>
178 *
179 * <table> <tr> <td align="center">
180 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0000.png
181 * </td>
182 *
183 * <td align="center">
184 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0001.png
185 * </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 0 </td>
186 *
187 * <td align="center"> $P_3$ element, shape function 1 </td> </tr>
188 *
189 * <tr> <td align="center">
190 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0002.png
191 * </td>
192 *
193 * <td align="center">
194 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0003.png
195 * </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 2 </td>
196 *
197 * <td align="center"> $P_3$ element, shape function 3 </td> </tr>
198 *
199 * <tr> <td align="center">
200 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0004.png
201 * </td>
202 *
203 * <td align="center">
204 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0005.png
205 * </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 4 </td>
206 *
207 * <td align="center"> $P_3$ element, shape function 5 </td> </tr>
208 *
209 * <tr> <td align="center">
210 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0006.png
211 * </td>
212 *
213 * <td align="center">
214 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0007.png
215 * </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 6 </td>
216 *
217 * <td align="center"> $P_3$ element, shape function 7 </td> </tr>
218 *
219 * <tr> <td align="center">
220 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0008.png
221 * </td>
222 *
223 * <td align="center">
224 * @image html http://www.dealii.org/images/shape-functions/DGP/P3/P3_DGP_shape0009.png
225 * </td> </tr> <tr> <td align="center"> $P_3$ element, shape function 8 </td>
226 *
227 * <td align="center"> $P_3$ element, shape function 9 </td> </tr> </table>
228 *
229 *
230 * <h4>$P_4$ element</h4> <table> <tr> <td align="center">
231 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0000.png
232 * </td>
233 *
234 * <td align="center">
235 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0001.png
236 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 0 </td>
237 *
238 * <td align="center"> $P_4$ element, shape function 1 </td> </tr>
239 *
240 * <tr> <td align="center">
241 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0002.png
242 * </td>
243 *
244 * <td align="center">
245 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0003.png
246 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 2 </td>
247 *
248 * <td align="center"> $P_4$ element, shape function 3 </td> </tr>
249 *
250 * <tr> <td align="center">
251 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0004.png
252 * </td>
253 *
254 * <td align="center">
255 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0005.png
256 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 4 </td>
257 *
258 * <td align="center"> $P_4$ element, shape function 5 </td> </tr>
259 *
260 * <tr> <td align="center">
261 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0006.png
262 * </td>
263 *
264 * <td align="center">
265 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0007.png
266 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 6 </td>
267 *
268 * <td align="center"> $P_4$ element, shape function 7 </td> </tr>
269 *
270 * <tr> <td align="center">
271 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0008.png
272 * </td>
273 *
274 * <td align="center">
275 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0009.png
276 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 8 </td>
277 *
278 * <td align="center"> $P_4$ element, shape function 9 </td> </tr>
279 *
280 * <tr> <td align="center">
281 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0010.png
282 * </td>
283 *
284 * <td align="center">
285 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0011.png
286 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 10 </td>
287 *
288 * <td align="center"> $P_4$ element, shape function 11 </td> </tr>
289 *
290 * <tr> <td align="center">
291 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0012.png
292 * </td>
293 *
294 * <td align="center">
295 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0013.png
296 * </td> </tr> <tr> <td align="center"> $P_4$ element, shape function 12 </td>
297 *
298 * <td align="center"> $P_4$ element, shape function 13 </td> </tr>
299 *
300 * <tr> <td align="center">
301 * @image html http://www.dealii.org/images/shape-functions/DGP/P4/P4_DGP_shape0014.png
302 * </td>
303 *
304 * <td align="center"> </td> </tr> <tr> <td align="center"> $P_4$ element,
305 * shape function 14 </td>
306 *
307 * <td align="center"></td> </tr> </table>
308 */
309 template <int dim, int spacedim = dim>
310 class FE_DGP : public FE_Poly<dim, spacedim>
311 {
312 public:
313 /**
314 * Constructor for tensor product polynomials of degree @p p.
315 */
316 FE_DGP(const unsigned int p);
317
318 /**
319 * Return a string that uniquely identifies a finite element. This class
320 * returns <tt>FE_DGP<dim>(degree)</tt>, with @p dim and @p degree replaced
321 * by appropriate values.
322 */
323 virtual std::string
324 get_name() const override;
325
326 /**
327 * @name Functions to support hp
328 * @{
329 */
330
331 /**
332 * If, on a vertex, several finite elements are active, the hp-code first
333 * assigns the degrees of freedom of each of these FEs different global
334 * indices. It then calls this function to find out which of them should get
335 * identical values, and consequently can receive the same global DoF index.
336 * This function therefore returns a list of identities between DoFs of the
337 * present finite element object with the DoFs of @p fe_other, which is a
338 * reference to a finite element object representing one of the other finite
339 * elements active on this particular vertex. The function computes which of
340 * the degrees of freedom of the two finite element objects are equivalent,
341 * both numbered between zero and the corresponding value of
342 * n_dofs_per_vertex() of the two finite elements. The first index of each
343 * pair denotes one of the vertex dofs of the present element, whereas the
344 * second is the corresponding index of the other finite element.
345 *
346 * This being a discontinuous element, the set of such constraints is of
347 * course empty.
348 */
349 virtual std::vector<std::pair<unsigned int, unsigned int>>
350 hp_vertex_dof_identities(
351 const FiniteElement<dim, spacedim> &fe_other) const override;
352
353 /**
354 * Same as hp_vertex_dof_indices(), except that the function treats degrees
355 * of freedom on lines.
356 *
357 * This being a discontinuous element, the set of such constraints is of
358 * course empty.
359 */
360 virtual std::vector<std::pair<unsigned int, unsigned int>>
361 hp_line_dof_identities(
362 const FiniteElement<dim, spacedim> &fe_other) const override;
363
364 /**
365 * Same as hp_vertex_dof_indices(), except that the function treats degrees
366 * of freedom on quads.
367 *
368 * This being a discontinuous element, the set of such constraints is of
369 * course empty.
370 */
371 virtual std::vector<std::pair<unsigned int, unsigned int>>
372 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
373 const unsigned int face_no = 0) const override;
374
375 /**
376 * Return whether this element implements its hanging node constraints in
377 * the new way, which has to be used to make elements "hp-compatible".
378 *
379 * For the FE_DGP class the result is always true (independent of the degree
380 * of the element), as it has no hanging nodes (being a discontinuous
381 * element).
382 */
383 virtual bool
384 hp_constraints_are_implemented() const override;
385
386 /**
387 * @copydoc FiniteElement::compare_for_domination()
388 */
389 virtual FiniteElementDomination::Domination
390 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
391 const unsigned int codim = 0) const override final;
392
393 /**
394 * @}
395 */
396
397 /**
398 * Return the matrix interpolating from a face of one element to the face
399 * of the neighboring element. The size of the matrix is then
400 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
401 *
402 * Derived elements will have to implement this function. They may only
403 * provide interpolation matrices for certain source finite elements, for
404 * example those from the same family. If they don't implement interpolation
405 * from a given element, then they must throw an exception of type
406 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
407 */
408 virtual void
409 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
410 FullMatrix<double> &matrix,
411 const unsigned int face_no = 0) const override;
412
413 /**
414 * Return the matrix interpolating from a face of one element to the face
415 * of the neighboring element. The size of the matrix is then
416 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
417 *
418 * Derived elements will have to implement this function. They may only
419 * provide interpolation matrices for certain source finite elements, for
420 * example those from the same family. If they don't implement interpolation
421 * from a given element, then they must throw an exception of type
422 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
423 */
424 virtual void
425 get_subface_interpolation_matrix(
426 const FiniteElement<dim, spacedim> &source,
427 const unsigned int subface,
428 FullMatrix<double> &matrix,
429 const unsigned int face_no = 0) const override;
430
431 /**
432 * This function returns @p true, if the shape function @p shape_index has
433 * non-zero function values somewhere on the face @p face_index.
434 */
435 virtual bool
436 has_support_on_face(const unsigned int shape_index,
437 const unsigned int face_index) const override;
438
439 /**
440 * Determine an estimate for the memory consumption (in bytes) of this
441 * object.
442 *
443 * This function is made virtual, since finite element objects are usually
444 * accessed through pointers to their base class, rather than the class
445 * itself.
446 */
447 virtual std::size_t
448 memory_consumption() const override;
449
450
451 /**
452 * Return a list of constant modes of the element. For this element, the
453 * first entry is true, all other are false.
454 */
455 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
456 get_constant_modes() const override;
457
458 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
459 clone() const override;
460
461 private:
462 /**
463 * Only for internal use. Its full name is @p get_dofs_per_object_vector
464 * function and it creates the @p dofs_per_object vector that is needed
465 * within the constructor to be passed to the constructor of @p
466 * FiniteElementData.
467 */
468 static std::vector<unsigned int>
469 get_dpo_vector(const unsigned int degree);
470 };
471
472 /** @} */
473
474 DEAL_II_NAMESPACE_CLOSE
475
476 #endif