Debian Codegraph @

include/deal.II/fe/fe_raviart_thomas.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2003 - 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_raviart_thomas_h
16 #define dealii_fe_raviart_thomas_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/mutex.h>
21 #include <deal.II/base/table.h>
22
23 #include <deal.II/fe/fe.h>
24 #include <deal.II/fe/fe_poly_tensor.h>
25
26 #include <vector>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 /**
31 * @addtogroup fe
32 * @{
33 */
34
35 /**
36 * Implementation of Raviart-Thomas (RT) elements. The Raviart-Thomas space
37 * is designed to solve problems in which the solution only lives in the
38 * space
39 * $H^\text{div}=\{ {\mathbf u} \in L_2: \text{div}\, {\mathbf u} \in L_2\}$,
40 * rather than in the more commonly used space
41 * $H^1=\{ u \in L_2: \nabla u \in L_2\}$. In other words, the solution must
42 * be a vector field whose divergence is square integrable, but for which the
43 * gradient may not be square integrable. The typical application for this
44 * space (and these elements) is to the mixed formulation of the Laplace
45 * equation and related situations, see for example step-20. The defining
46 * characteristic of functions in $H^\text{div}$ is that they are in
47 * general discontinuous -- but that if you draw a line in 2d (or a
48 * surface in 3d), then the <i>normal</i> component of the vector
49 * field must be continuous across the line (or surface) even though
50 * the tangential component may not be. As a consequence, the
51 * Raviart-Thomas element is constructed in such a way that (i) it is
52 * @ref vector_valued "vector-valued",
53 * (ii) the shape functions are
54 * discontinuous, but (iii) the normal component of the vector field
55 * represented by each shape function is continuous across the faces
56 * of cells.
57 *
58 * Other properties of the Raviart-Thomas element are that (i) it is
59 * @ref GlossPrimitive "not a primitive element"
60 * ; (ii) the shape functions
61 * are defined so that certain integrals over the faces are either zero
62 * or one, rather than the common case of certain point values being
63 * either zero or one. (There is, however, the FE_RaviartThomasNodal
64 * element that uses point values.)
65 *
66 * We follow the commonly used -- though confusing -- definition of the "degree"
67 * of RT elements. Specifically, the "degree" of the element denotes
68 * the polynomial degree of the <i>largest complete polynomial subspace</i>
69 * contained in the finite element space, even if the space may contain shape
70 * functions of higher polynomial degree. The lowest order element is
71 * consequently FE_RaviartThomas(0), i.e., the Raviart-Thomas element "of
72 * degree zero", even though the functions of this space are in general
73 * polynomials of degree one in each variable. This choice of "degree"
74 * implies that the approximation order of the function itself is
75 * <i>degree+1</i>, as with usual polynomial spaces. The numbering so chosen
76 * implies the sequence
77 * @f[
78 * Q_{k+1}
79 * \stackrel{\text{grad}}{\rightarrow}
80 * \text{Nedelec}_k
81 * \stackrel{\text{curl}}{\rightarrow}
82 * \text{RaviartThomas}_k
83 * \stackrel{\text{div}}{\rightarrow}
84 * DGQ_{k}
85 * @f]
86 *
87 * This class is not implemented for the codimension one case (<tt>spacedim !=
88 * dim</tt>).
89 *
90 *
91 * <h3>Interpolation</h3>
92 *
93 * The
94 * @ref GlossInterpolation "interpolation"
95 * operators associated with the RT element are constructed such that
96 * interpolation and computing the divergence are commuting operations. We
97 * require this from interpolating arbitrary functions as well as the
98 * #restriction matrices. It can be achieved by two interpolation schemes,
99 * the simplified one in FE_RaviartThomasNodal and the original one here:
100 *
101 * <h4>Node values on edges/faces</h4>
102 *
103 * On edges or faces, the
104 * @ref GlossNodes "node values"
105 * are the moments of the normal component of the interpolated function with
106 * respect to the traces of the RT polynomials. Since the normal trace of the
107 * RT space of degree <i>k</i> on an edge/face is the space
108 * <i>Q<sub>k</sub></i>, the moments are taken with respect to this space.
109 *
110 * <h4>Interior node values</h4>
111 *
112 * Higher order RT spaces have interior nodes. These are moments taken with
113 * respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell
114 * (this space is the matching space for RT<sub>k</sub> in a mixed
115 * formulation).
116 *
117 * <h4>Generalized support points</h4>
118 *
119 * The node values above rely on integrals, which will be computed by
120 * quadrature rules themselves. The generalized support points are a set of
121 * points such that this quadrature can be performed with sufficient accuracy.
122 * The points needed are those of QGauss<sub>k+1</sub> on each face as well as
123 * QGauss<sub>k+1</sub> in the interior of the cell (or none for
124 * RT<sub>0</sub>).
125 */
126 template <int dim>
127 class FE_RaviartThomas : public FE_PolyTensor<dim>
128 {
129 public:
130 /**
131 * Constructor for the Raviart-Thomas element of degree @p p.
132 */
133 FE_RaviartThomas(const unsigned int p);
134
135 /**
136 * Return a string that uniquely identifies a finite element. This class
137 * returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree
138 * replaced by appropriate values.
139 */
140 virtual std::string
141 get_name() const override;
142
143 // documentation inherited from the base class
144 virtual std::unique_ptr<FiniteElement<dim, dim>>
145 clone() const override;
146
147 /**
148 * Compute the lexicographic to hierarchic numbering underlying this class,
149 * necessary for the creation of the respective vector polynomial space.
150 */
151 static std::vector<unsigned int>
152 get_lexicographic_numbering(const unsigned int degree);
153
154 /**
155 * This function returns @p true, if the shape function @p shape_index has
156 * non-zero function values somewhere on the face @p face_index.
157 *
158 * Right now, this is only implemented for RT0 in 1d. Otherwise, returns
159 * always @p true.
160 */
161 virtual bool
162 has_support_on_face(const unsigned int shape_index,
163 const unsigned int face_index) const override;
164
165 // documentation inherited from the base class
166 virtual void
167 convert_generalized_support_point_values_to_dof_values(
168 const std::vector<Vector<double>> &support_point_values,
169 std::vector<double> &nodal_values) const override;
170
171 /**
172 * Return a list of constant modes of the element. This method is currently
173 * not correctly implemented because it returns ones for all components.
174 */
175 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
176 get_constant_modes() const override;
177
178 virtual std::size_t
179 memory_consumption() const override;
180
181 private:
182 /**
183 * Only for internal use. Its full name is @p get_dofs_per_object_vector
184 * function and it creates the @p dofs_per_object vector that is needed
185 * within the constructor to be passed to the constructor of @p
186 * FiniteElementData.
187 */
188 static std::vector<unsigned int>
189 get_dpo_vector(const unsigned int degree);
190
191 /**
192 * Initialize the @p generalized_support_points field of the FiniteElement
193 * class and fill the tables with interpolation weights (#boundary_weights
194 * and #interior_weights). Called from the constructor.
195 */
196 void
197 initialize_support_points(const unsigned int rt_degree);
198
199 /**
200 * Initialize the interpolation from functions on refined mesh cells onto
201 * the parent cell. According to the philosophy of the Raviart-Thomas
202 * element, this restriction operator preserves the divergence of a function
203 * weakly.
204 */
205 void
206 initialize_restriction();
207
208 /**
209 * These are the factors multiplied to a function in the
210 * #generalized_face_support_points when computing the integration. They are
211 * organized such that there is one row for each generalized face support
212 * point and one column for each degree of freedom on the face.
213 *
214 * See the
215 * @ref GlossGeneralizedSupport "glossary entry on generalized support points"
216 * for more information.
217 */
218 Table<2, double> boundary_weights;
219
220 /**
221 * Precomputed factors for interpolation of interior degrees of freedom. The
222 * rationale for this Table is the same as for #boundary_weights. Only, this
223 * table has a third coordinate for the space direction of the component
224 * evaluated.
225 */
226 Table<3, double> interior_weights;
227
228 /**
229 * Fill the necessary tables defined in base classes such as
230 * <code>adjust_quad_dof_index_for_face_orientation_table</code> declared in
231 * fe.cc. We need to fill it with the correct values in case of non-standard,
232 * flipped (rotated by +180 degrees) or rotated (rotated by +90 degrees)
233 * faces. These are given in the form three flags (face_orientation,
234 * face_flip, face_rotation), see the documentation in GeometryInfo<dim> and
235 * this
236 * @ref GlossCombinedOrientation "glossary entry on face orientations".
237 *
238 * <h3>Example: Raviart-Thomas Elements of order 2 (tensor polynomial
239 * degree 3)</h3>
240 *
241 * The dofs on a face are connected to a $n\times n$
242 * matrix where here <code>n=3</code>. In our example we can imagine the
243 * following dofs on a quad (face):
244 *
245 * @verbatim
246 * ___________
247 * | |
248 * | 6 7 8 |
249 * | |
250 * | 3 4 5 |
251 * | |
252 * | 0 1 2 |
253 * |___________|
254 * @endverbatim
255 *
256 * We have for a local <code>face_dof_index=i+n*j</code> with index
257 * <code>i</code> in x-direction and index <code>j</code> in y-direction
258 * running from 0 to <code>n-1</code>. To extract <code>i</code> and
259 * <code>j</code> we can use <code>i = face_dof_index % n</code> and <code>j =
260 * dof_index / n</code> (integer division). The indices <code>i</code> and
261 * <code>j</code> can then be used to compute the offset.
262 *
263 * For our example of Raviart-Thomas elements this means if the
264 * switches are <code>(true | true | true)</code> that means we rotate the
265 * face first by + 90 degree(counterclockwise) then by another +180
266 * degrees but we do not flip it since the face has standard
267 * orientation. The flip axis is the diagonal from the lower left to the upper
268 * right corner of the face. With these flags the configuration above becomes:
269 *
270 * @verbatim
271 * ___________
272 * | |
273 * | 2 5 8 |
274 * | |
275 * | 1 4 7 |
276 * | |
277 * | 0 3 6 |
278 * |___________|
279 * @endverbatim
280 *
281 * Note that the necessity of a permutation depends on the combination of the
282 * three flags.
283 *
284 * There is also a pattern for the sign change of the permuted shape functions
285 * that depends on the combination of the switches. In the above example it
286 * would be
287 *
288 * @verbatim
289 * ___________
290 * | |
291 * | + - + |
292 * | |
293 * | + - + |
294 * | |
295 * | + - + |
296 * |___________|
297 * @endverbatim
298 *
299 * The relevant table for the sign changes is declared in FE_PolyTensor.
300 */
301 void
302 initialize_quad_dof_index_permutation_and_sign_change();
303
304 // Allow access from other dimensions.
305 template <int dim1>
306 friend class FE_RaviartThomas;
307 };
308
309
310
311 /**
312 * The Raviart-Thomas elements with node functionals defined as point values
313 * in Gauss-Lobatto points.
314 *
315 * <h3>Description of node values</h3>
316 *
317 * For this Raviart-Thomas element, the node values are not cell and face
318 * moments with respect to certain polynomials, but the values at quadrature
319 * points. Following the general scheme for numbering degrees of freedom, the
320 * node values on faces (edges in 2d, quads in 3d) are first, face by face,
321 * according to the natural ordering of the faces of a cell. The interior
322 * degrees of freedom are last.
323 *
324 * For an RT-element of degree <i>k</i>, we choose <i>(k+1)<sup>d-1</sup></i>
325 * Gauss-Lobatto points on each face, as defined by QGaussLobatto. For degree
326 * $k=0$, the midpoint is chosen. These points are ordered lexicographically
327 * with respect to the orientation of the face. This way, the normal component
328 * which is in <i>Q<sub>k</sub></i>, is uniquely determined.
329 *
330 * These face polynomials are extended into the interior by the means of a
331 * QGaussLobatto formula for the normal direction. In other words, the
332 * polynomials are the tensor product of Lagrange polynomials on the points of
333 * a QGaussLobatto formula with $(k+2)$ points in the normal direction with
334 * Lagrange polynomials on the points of a QGaussLobatto quadrature formula
335 * with $(k+1)$ points.
336 *
337 * @note The degree stored in the member variable
338 * FiniteElementData<dim>::degree is higher by one than the constructor
339 * argument!
340 */
341 template <int dim>
342 class FE_RaviartThomasNodal : public FE_PolyTensor<dim>
343 {
344 public:
345 /**
346 * Constructor for the Raviart-Thomas element of degree @p p.
347 */
348 FE_RaviartThomasNodal(const unsigned int p);
349
350 /**
351 * Return a string that uniquely identifies a finite element. This class
352 * returns <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with @p dim and @p
353 * degree replaced by appropriate values.
354 */
355 virtual std::string
356 get_name() const override;
357
358 // documentation inherited from the base class
359 virtual std::unique_ptr<FiniteElement<dim, dim>>
360 clone() const override;
361
362 virtual void
363 get_face_interpolation_matrix(const FiniteElement<dim> &source,
364 FullMatrix<double> &matrix,
365 const unsigned int face_no = 0) const override;
366
367 virtual void
368 get_subface_interpolation_matrix(
369 const FiniteElement<dim> &source,
370 const unsigned int subface,
371 FullMatrix<double> &matrix,
372 const unsigned int face_no = 0) const override;
373
374 virtual void
375 convert_generalized_support_point_values_to_dof_values(
376 const std::vector<Vector<double>> &support_point_values,
377 std::vector<double> &nodal_values) const override;
378
379 virtual bool
380 hp_constraints_are_implemented() const override;
381
382 virtual std::vector<std::pair<unsigned int, unsigned int>>
383 hp_vertex_dof_identities(const FiniteElement<dim> &fe_other) const override;
384
385 virtual std::vector<std::pair<unsigned int, unsigned int>>
386 hp_line_dof_identities(const FiniteElement<dim> &fe_other) const override;
387
388 virtual std::vector<std::pair<unsigned int, unsigned int>>
389 hp_quad_dof_identities(const FiniteElement<dim> &fe_other,
390 const unsigned int face_no = 0) const override;
391
392 /**
393 * @copydoc FiniteElement::compare_for_domination()
394 */
395 virtual FiniteElementDomination::Domination
396 compare_for_domination(const FiniteElement<dim> &fe_other,
397 const unsigned int codim = 0) const override final;
398
399 virtual const FullMatrix<double> &
400 get_restriction_matrix(
401 const unsigned int child,
402 const RefinementCase<dim> &refinement_case =
403 RefinementCase<dim>::isotropic_refinement) const override;
404
405 virtual const FullMatrix<double> &
406 get_prolongation_matrix(
407 const unsigned int child,
408 const RefinementCase<dim> &refinement_case =
409 RefinementCase<dim>::isotropic_refinement) const override;
410
411 private:
412 /**
413 * This function returns @p true, if the shape function @p shape_index has
414 * non-zero function values somewhere on the face @p face_index.
415 */
416 virtual bool
417 has_support_on_face(const unsigned int shape_index,
418 const unsigned int face_index) const override;
419
420 /**
421 * Initialize the permutation pattern and the pattern of sign change.
422 */
423 void
424 initialize_quad_dof_index_permutation_and_sign_change();
425
426 /**
427 * Mutex variables used for protecting the initialization of restriction
428 * and embedding matrices.
429 */
430 mutable Threads::Mutex restriction_matrix_mutex;
431 mutable Threads::Mutex prolongation_matrix_mutex;
432 };
433
434 /** @} */
435
436 /* -------------- declaration of explicit specializations ------------- */
437
438 #ifndef DOXYGEN
439
440 template <>
441 void
442 FE_RaviartThomas<1>::initialize_restriction();
443
444 #endif // DOXYGEN
445
446 DEAL_II_NAMESPACE_CLOSE
447
448 #endif