Debian Codegraph @

include/deal.II/fe/fe_face.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 2024 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_face_h
16 #define dealii_fe_face_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/polynomial_space.h>
21 #include <deal.II/base/tensor_product_polynomials.h>
22
23 #include <deal.II/fe/fe_poly_face.h>
24
25 DEAL_II_NAMESPACE_OPEN
26
27
28 /**
29 * A finite element that is a tensor product polynomial on each face and
30 * undefined in the interior of the cells. The basis functions on the faces
31 * are Lagrange polynomials based on the support points of the
32 * (dim-1)-dimensional Gauss--Lobatto quadrature rule. For element degree one
33 * and two, the polynomials hence correspond to the usual Lagrange polynomials
34 * on equidistant points.
35 *
36 * Although the name does not give it away, the element is discontinuous at
37 * locations where faces of cells meet. In particular, this finite element is
38 * the trace space of FE_RaviartThomas on the faces and serves in hybridized
39 * methods, e.g. in combination with the FE_DGQ element. Its use is
40 * demonstrated in the step-51 tutorial program.
41 *
42 * @note Since this element is defined only on faces, only FEFaceValues and
43 * FESubfaceValues will provide useful information. On the other hand, if you
44 * use this element with FEValues for cell integration, then the values
45 * and derivatives of shape functions will have invalid values and will not
46 * likely produce anything useful. In order to make the use of this element
47 * as part of an FESystem simpler, using a (cell) FEValues object will not fail
48 * outright, but those components of shape functions of the combined element
49 * that correspond to FE_FaceQ will have the invalid values mentioned above.
50 *
51 * @ingroup fe
52 */
53 template <int dim, int spacedim = dim>
54 class FE_FaceQ
55 : public FE_PolyFace<TensorProductPolynomials<dim - 1>, dim, spacedim>
56 {
57 public:
58 /**
59 * Constructor for tensor product polynomials of degree <tt>p</tt>. The
60 * shape functions created using this constructor correspond to Lagrange
61 * polynomials in each coordinate direction.
62 */
63 FE_FaceQ(const unsigned int p);
64
65 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
66 clone() const override;
67
68 /**
69 * Return a string that uniquely identifies a finite element. This class
70 * returns <tt>FE_FaceQ<dim>(degree)</tt>, with <tt>dim</tt> and
71 * <tt>degree</tt> replaced by appropriate values.
72 */
73 virtual std::string
74 get_name() const override;
75
76 /**
77 * Implementation of the corresponding function in the FiniteElement
78 * class. Since the current element is interpolatory, the nodal
79 * values are exactly the support point values. Furthermore, since
80 * the current element is scalar, the support point values need to
81 * be vectors of length 1.
82 */
83 virtual void
84 convert_generalized_support_point_values_to_dof_values(
85 const std::vector<Vector<double>> &support_point_values,
86 std::vector<double> &nodal_values) const override;
87
88 /**
89 * Return the matrix interpolating from a face of one element to the face
90 * of the neighboring element. The size of the matrix is then
91 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
92 * element only provides interpolation matrices for elements of the same
93 * type and FE_Nothing. For all other elements, an exception of type
94 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
95 */
96 virtual void
97 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
98 FullMatrix<double> &matrix,
99 const unsigned int face_no = 0) const override;
100
101 /**
102 * Return the matrix interpolating from a face of one element to the face
103 * of the neighboring element. The size of the matrix is then
104 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
105 * element only provides interpolation matrices for elements of the same
106 * type and FE_Nothing. For all other elements, an exception of type
107 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
108 */
109 virtual void
110 get_subface_interpolation_matrix(
111 const FiniteElement<dim, spacedim> &source,
112 const unsigned int subface,
113 FullMatrix<double> &matrix,
114 const unsigned int face_no = 0) const override;
115
116 /**
117 * This function returns @p true, if the shape function @p shape_index has
118 * non-zero function values somewhere on the face @p face_index.
119 */
120 virtual bool
121 has_support_on_face(const unsigned int shape_index,
122 const unsigned int face_index) const override;
123
124 /**
125 * @name Functions to support hp
126 * @{
127 */
128
129 /**
130 * If, on a vertex, several finite elements are active, the hp-code first
131 * assigns the degrees of freedom of each of these FEs different global
132 * indices. It then calls this function to find out which of them should get
133 * identical values, and consequently can receive the same global DoF index.
134 * This function therefore returns a list of identities between DoFs of the
135 * present finite element object with the DoFs of @p fe_other, which is a
136 * reference to a finite element object representing one of the other finite
137 * elements active on this particular vertex. The function computes which of
138 * the degrees of freedom of the two finite element objects are equivalent,
139 * both numbered between zero and the corresponding value of
140 * n_dofs_per_vertex() of the two finite elements. The first index of each
141 * pair denotes one of the vertex dofs of the present element, whereas the
142 * second is the corresponding index of the other finite element.
143 *
144 * The set of such constraints is non-empty only for dim==1.
145 */
146 virtual std::vector<std::pair<unsigned int, unsigned int>>
147 hp_vertex_dof_identities(
148 const FiniteElement<dim, spacedim> &fe_other) const override;
149
150 /**
151 * Same as hp_vertex_dof_indices(), except that the function treats degrees
152 * of freedom on lines.
153 *
154 * The set of such constraints is non-empty only for dim==2.
155 */
156 virtual std::vector<std::pair<unsigned int, unsigned int>>
157 hp_line_dof_identities(
158 const FiniteElement<dim, spacedim> &fe_other) const override;
159
160 /**
161 * Same as hp_vertex_dof_indices(), except that the function treats degrees
162 * of freedom on quads.
163 *
164 * The set of such constraints is non-empty only for dim==3.
165 */
166 virtual std::vector<std::pair<unsigned int, unsigned int>>
167 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
168 const unsigned int face_no = 0) const override;
169
170 /**
171 * Return whether this element implements its hanging node constraints in
172 * the new way, which has to be used to make elements "hp-compatible".
173 */
174 virtual bool
175 hp_constraints_are_implemented() const override;
176
177 /**
178 * @copydoc FiniteElement::compare_for_domination()
179 */
180 virtual FiniteElementDomination::Domination
181 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
182 const unsigned int codim = 0) const override final;
183
184 /**
185 * @}
186 */
187
188 /**
189 * Return a list of constant modes of the element. For this element, it
190 * simply returns one row with all entries set to true.
191 */
192 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
193 get_constant_modes() const override;
194
195 private:
196 /**
197 * Return vector with dofs per vertex, line, quad, hex.
198 */
199 static std::vector<unsigned int>
200 get_dpo_vector(const unsigned int deg);
201 };
202
203
204
205 /**
206 * Specialization of FE_FaceQ for 1d. In that case, the finite element only
207 * consists of one degree of freedom in each of the two faces (= vertices) of
208 * a cell, irrespective of the degree. However, this element still accepts a
209 * degree in its constructor and also returns that degree. This way,
210 * dimension-independent programming with trace elements is also possible in
211 * 1d (even though there is no computational benefit at all from it in 1d).
212 *
213 * @ingroup fe
214 */
215 template <int spacedim>
216 class FE_FaceQ<1, spacedim> : public FiniteElement<1, spacedim>
217 {
218 public:
219 /**
220 * Constructor.
221 */
222 FE_FaceQ(const unsigned int p);
223
224 virtual std::unique_ptr<FiniteElement<1, spacedim>>
225 clone() const override;
226
227 /**
228 * Return a string that uniquely identifies a finite element. This class
229 * returns <tt>FE_FaceQ<dim>(degree)</tt>, with <tt>dim</tt> and
230 * <tt>degree</tt> replaced by appropriate values.
231 */
232 virtual std::string
233 get_name() const override;
234
235 // for documentation, see the FiniteElement base class
236 virtual UpdateFlags
237 requires_update_flags(const UpdateFlags update_flags) const override;
238
239 /**
240 * Return the matrix interpolating from a face of one element to the face
241 * of the neighboring element. The size of the matrix is then
242 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
243 * element only provides interpolation matrices for elements of the same
244 * type and FE_Nothing. For all other elements, an exception of type
245 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
246 */
247 virtual void
248 get_face_interpolation_matrix(const FiniteElement<1, spacedim> &source,
249 FullMatrix<double> &matrix,
250 const unsigned int face_no = 0) const override;
251
252 /**
253 * Return the matrix interpolating from a face of one element to the face
254 * of the neighboring element. The size of the matrix is then
255 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
256 * element only provides interpolation matrices for elements of the same
257 * type and FE_Nothing. For all other elements, an exception of type
258 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
259 */
260 virtual void
261 get_subface_interpolation_matrix(
262 const FiniteElement<1, spacedim> &source,
263 const unsigned int subface,
264 FullMatrix<double> &matrix,
265 const unsigned int face_no = 0) const override;
266
267 /**
268 * This function returns @p true, if the shape function @p shape_index has
269 * non-zero function values somewhere on the face @p face_index.
270 */
271 virtual bool
272 has_support_on_face(const unsigned int shape_index,
273 const unsigned int face_index) const override;
274
275 /**
276 * Return whether this element implements its hanging node constraints in
277 * the new way, which has to be used to make elements "hp-compatible".
278 */
279 virtual bool
280 hp_constraints_are_implemented() const override;
281
282 /**
283 * If, on a vertex, several finite elements are active, the hp-code first
284 * assigns the degrees of freedom of each of these FEs different global
285 * indices. It then calls this function to find out which of them should get
286 * identical values, and consequently can receive the same global DoF index.
287 * This function therefore returns a list of identities between DoFs of the
288 * present finite element object with the DoFs of @p fe_other, which is a
289 * reference to a finite element object representing one of the other finite
290 * elements active on this particular vertex. The function computes which of
291 * the degrees of freedom of the two finite element objects are equivalent,
292 * both numbered between zero and the corresponding value of
293 * n_dofs_per_vertex() of the two finite elements. The first index of each
294 * pair denotes one of the vertex dofs of the present element, whereas the
295 * second is the corresponding index of the other finite element.
296 *
297 * The set of such constraints is non-empty only for dim==1.
298 */
299 virtual std::vector<std::pair<unsigned int, unsigned int>>
300 hp_vertex_dof_identities(
301 const FiniteElement<1, spacedim> &fe_other) const override;
302
303 /**
304 * Same as hp_vertex_dof_indices(), except that the function treats degrees
305 * of freedom on lines.
306 *
307 * The set of such constraints is non-empty only for dim==2.
308 */
309 virtual std::vector<std::pair<unsigned int, unsigned int>>
310 hp_line_dof_identities(
311 const FiniteElement<1, spacedim> &fe_other) const override;
312
313 /**
314 * Same as hp_vertex_dof_indices(), except that the function treats degrees
315 * of freedom on quads.
316 *
317 * The set of such constraints is non-empty only for dim==3.
318 */
319 virtual std::vector<std::pair<unsigned int, unsigned int>>
320 hp_quad_dof_identities(const FiniteElement<1, spacedim> &fe_other,
321 const unsigned int face_no = 0) const override;
322
323 /**
324 * Return a list of constant modes of the element. For this element, it
325 * simply returns one row with all entries set to true.
326 */
327 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
328 get_constant_modes() const override;
329
330 protected:
331 /*
332 * NOTE: The following functions have their definitions inlined into the class
333 * declaration because we otherwise run into a compiler error with MS Visual
334 * Studio.
335 */
336
337
338 virtual std::unique_ptr<typename FiniteElement<1, spacedim>::InternalDataBase>
339 get_data(
340 const UpdateFlags /*update_flags*/,
341 const Mapping<1, spacedim> & /*mapping*/,
342 const Quadrature<1> & /*quadrature*/,
343 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
344 spacedim>
345 & /*output_data*/) const override
346 {
347 return std::make_unique<
348 typename FiniteElement<1, spacedim>::InternalDataBase>();
349 }
350
351 using FiniteElement<1, spacedim>::get_face_data;
352
353 std::unique_ptr<typename FiniteElement<1, spacedim>::InternalDataBase>
354 get_face_data(
355 const UpdateFlags update_flags,
356 const Mapping<1, spacedim> & /*mapping*/,
357 const hp::QCollection<0> &quadrature,
358 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
359 spacedim>
360 & /*output_data*/) const override
361 {
362 AssertDimension(quadrature.size(), 1);
363
364 // generate a new data object and initialize some fields
365 auto data_ptr =
366 std::make_unique<typename FiniteElement<1, spacedim>::InternalDataBase>();
367 data_ptr->update_each = requires_update_flags(update_flags);
368
369 const unsigned int n_q_points = quadrature[0].size();
370 AssertDimension(n_q_points, 1);
371 (void)n_q_points;
372
373 // No derivatives of this element are implemented.
374 if (data_ptr->update_each & update_gradients ||
375 data_ptr->update_each & update_hessians)
376 {
377 DEAL_II_NOT_IMPLEMENTED();
378 }
379
380 return data_ptr;
381 }
382
383 std::unique_ptr<typename FiniteElement<1, spacedim>::InternalDataBase>
384 get_subface_data(
385 const UpdateFlags update_flags,
386 const Mapping<1, spacedim> &mapping,
387 const Quadrature<0> &quadrature,
388 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
389 spacedim>
390 &output_data) const override
391 {
392 return get_face_data(update_flags,
393 mapping,
394 hp::QCollection<0>(quadrature),
395 output_data);
396 }
397
398 virtual void
399 fill_fe_values(
400 const typename Triangulation<1, spacedim>::cell_iterator &cell,
401 const CellSimilarity::Similarity cell_similarity,
402 const Quadrature<1> &quadrature,
403 const Mapping<1, spacedim> &mapping,
404 const typename Mapping<1, spacedim>::InternalDataBase &mapping_internal,
405 const internal::FEValuesImplementation::MappingRelatedData<1, spacedim>
406 &mapping_data,
407 const typename FiniteElement<1, spacedim>::InternalDataBase &fe_internal,
408 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
409 spacedim>
410 &output_data) const override;
411
412 using FiniteElement<1, spacedim>::fill_fe_face_values;
413
414 virtual void
415 fill_fe_face_values(
416 const typename Triangulation<1, spacedim>::cell_iterator &cell,
417 const unsigned int face_no,
418 const hp::QCollection<0> &quadrature,
419 const Mapping<1, spacedim> &mapping,
420 const typename Mapping<1, spacedim>::InternalDataBase &mapping_internal,
421 const internal::FEValuesImplementation::MappingRelatedData<1, spacedim>
422 &mapping_data,
423 const typename FiniteElement<1, spacedim>::InternalDataBase &fe_internal,
424 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
425 spacedim>
426 &output_data) const override;
427
428 virtual void
429 fill_fe_subface_values(
430 const typename Triangulation<1, spacedim>::cell_iterator &cell,
431 const unsigned int face_no,
432 const unsigned int sub_no,
433 const Quadrature<0> &quadrature,
434 const Mapping<1, spacedim> &mapping,
435 const typename Mapping<1, spacedim>::InternalDataBase &mapping_internal,
436 const internal::FEValuesImplementation::MappingRelatedData<1, spacedim>
437 &mapping_data,
438 const typename FiniteElement<1, spacedim>::InternalDataBase &fe_internal,
439 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<1,
440 spacedim>
441 &output_data) const override;
442
443 private:
444 /**
445 * Return vector with dofs per vertex, line, quad, hex.
446 */
447 static std::vector<unsigned int>
448 get_dpo_vector(const unsigned int deg);
449 };
450
451
452
453 /**
454 * A finite element that is a Legendre element of complete polynomials on
455 * each face (i.e., it is the face equivalent of what FE_DGP is on cells) and
456 * undefined in the interior of the cells. The basis functions on the faces
457 * are from Polynomials::Legendre.
458 *
459 * Although the name does not give it away, the element is discontinuous at
460 * locations where faces of cells meet. The element serves in hybridized
461 * methods, e.g. in combination with the FE_DGP element. An example of
462 * hybridizes methods can be found in the step-51 tutorial program.
463 *
464 * @note Since this element is defined only on faces, only FEFaceValues and
465 * FESubfaceValues will provide useful information. On the other hand, if you
466 * use this element with FEValues for cell integration, then the values
467 * and derivatives of shape functions will have invalid values and will not
468 * likely produce anything useful. In order to make the use of this element
469 * as part of an FESystem simpler, using a (cell) FEValues object will not fail
470 * outright, but those components of shape functions of the combined element
471 * that correspond to FE_FaceP will have the invalid values mentioned above.
472 *
473 * @ingroup fe
474 */
475 template <int dim, int spacedim = dim>
476 class FE_FaceP : public FE_PolyFace<PolynomialSpace<dim - 1>, dim, spacedim>
477 {
478 public:
479 /**
480 * Constructor for complete basis of polynomials of degree <tt>p</tt>. The
481 * shape functions created using this constructor correspond to Legendre
482 * polynomials in each coordinate direction.
483 */
484 FE_FaceP(unsigned int p);
485
486 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
487 clone() const override;
488
489 /**
490 * Return a string that uniquely identifies a finite element. This class
491 * returns <tt>FE_FaceP<dim>(degree)</tt> , with <tt>dim</tt> and
492 * <tt>degree</tt> replaced by appropriate values.
493 */
494 virtual std::string
495 get_name() const override;
496
497 /**
498 * Return the matrix interpolating from a face of one element to the face
499 * of the neighboring element. The size of the matrix is then
500 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
501 * element only provides interpolation matrices for elements of the same
502 * type and FE_Nothing. For all other elements, an exception of type
503 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
504 */
505 virtual void
506 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
507 FullMatrix<double> &matrix,
508 const unsigned int face_no = 0) const override;
509
510 /**
511 * Return the matrix interpolating from a face of one element to the face
512 * of the neighboring element. The size of the matrix is then
513 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. This
514 * element only provides interpolation matrices for elements of the same
515 * type and FE_Nothing. For all other elements, an exception of type
516 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
517 */
518 virtual void
519 get_subface_interpolation_matrix(
520 const FiniteElement<dim, spacedim> &source,
521 const unsigned int subface,
522 FullMatrix<double> &matrix,
523 const unsigned int face_no = 0) const override;
524
525 /**
526 * This function returns @p true, if the shape function @p shape_index has
527 * non-zero function values somewhere on the face @p face_index.
528 */
529 virtual bool
530 has_support_on_face(const unsigned int shape_index,
531 const unsigned int face_index) const override;
532
533 /**
534 * Return whether this element implements its hanging node constraints in
535 * the new way, which has to be used to make elements "hp-compatible".
536 */
537 virtual bool
538 hp_constraints_are_implemented() const override;
539
540 /**
541 * @copydoc FiniteElement::compare_for_domination()
542 */
543 virtual FiniteElementDomination::Domination
544 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
545 const unsigned int codim = 0) const override final;
546
547 /**
548 * Return a list of constant modes of the element. For this element, the
549 * first entry on each face is true, all other are false (as the constant
550 * function is represented by the first base function of Legendre
551 * polynomials).
552 */
553 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
554 get_constant_modes() const override;
555
556 private:
557 /**
558 * Return vector with dofs per vertex, line, quad, hex.
559 */
560 static std::vector<unsigned int>
561 get_dpo_vector(const unsigned int deg);
562 };
563
564
565
566 /**
567 * FE_FaceP in 1d, i.e., with degrees of freedom on the element vertices.
568 * See the documentation of the general template for more information.
569 */
570 template <int spacedim>
571 class FE_FaceP<1, spacedim> : public FE_FaceQ<1, spacedim>
572 {
573 public:
574 /**
575 * Constructor.
576 */
577 FE_FaceP(const unsigned int p);
578
579 /**
580 * Return the name of the element
581 */
582 std::string
583 get_name() const override;
584 };
585
586
587 DEAL_II_NAMESPACE_CLOSE
588
589 #endif