Debian Codegraph @

include/deal.II/base/qprojector.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_qprojector_h
16 #define dealii_qprojector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/geometry_info.h>
22 #include <deal.II/base/quadrature.h>
23
24 #include <deal.II/hp/q_collection.h>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 #ifndef DOXYGEN
29 class ReferenceCell;
30 #endif
31
32 /**
33 * @addtogroup Quadrature
34 * @{
35 */
36
37 /**
38 * @brief Class which transforms `dim - 1`-dimensional quadrature rules to
39 * `dim`-dimensional face quadratures.
40 *
41 * The majority of the finite element infrastructure, such as FE_Q and
42 * FE_SimplexP, uses polynomials defined on a reference cell: for example,
43 * FE_Q<3> defines a polynomial space whose domain is the unit hexahedron (i.e.,
44 * ReferenceCells::Hexahedron). Hence, computing quadratures using shape
45 * functions on a face of a reference cell requires converting a
46 * lower-dimensional Quadrature into one defined on the boundary of the
47 * higher-dimensional object, e.g., converting a Quadrature defined on a
48 * quadrilateral into one defined on one face of a hexahedron.
49 *
50 * QProjector computes the locations of quadrature points on faces or subfaces
51 * of reference cells from a Quadrature of one dimension less than that of the
52 * cell, face (and possibly also subface) number, and orientation. For example,
53 * calling QProjector::project_to_face() with QSimpson<1>, face number 1, and
54 * numbers::default_geometric_orientation returns a Quadrature with points
55 * (1,0), (1,0.5), and (1,1) with weights equal to the 1d case. Similarly, if we
56 * instead use face 3 and numbers::reverse_line_orientation we obtain points
57 * (1,1), (0.5,1) and (0,1). Projection to subfaces works in the same way.
58 *
59 * In practice, computing face integrals (e.g., via FEFaceValues or
60 * FESubfaceValues) requires quadrature rules for all possible permutations of
61 * face number, subface number, and combined orientation. This class provides
62 * several functions for doing just that, such as
63 * QProjector::project_to_all_faces(). Furthermore, the DataSetDescriptor class
64 * implements indexing for converting between face number, subface number, and
65 * combined orientation to the index of the associated Quadrature rule.
66 */
67 template <int dim>
68 class QProjector
69 {
70 public:
71 /**
72 * Define an alias for a quadrature that acts on an object of one dimension
73 * less. For cells, this would then be a face quadrature.
74 */
75 using SubQuadrature = Quadrature<dim - 1>;
76
77 /**
78 * Compute the quadrature points on the cell if the given quadrature formula
79 * is used on face <tt>face_no</tt>. For further details, see the general
80 * doc for this class.
81 *
82 * @deprecated Use the version of this function which takes a
83 * combined_orientation argument instead.
84 */
85 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
86 "Use the version of this function which takes a combined_orientation "
87 "argument instead.")
88 static void
89 project_to_face(const ReferenceCell &reference_cell,
90 const SubQuadrature &quadrature,
91 const unsigned int face_no,
92 std::vector<Point<dim>> &q_points);
93
94 /**
95 * Compute the cell quadrature formula corresponding to using
96 * <tt>quadrature</tt> on face <tt>face_no</tt>. For further details, see
97 * the general doc for this class.
98 *
99 * @deprecated Use the version of this function which takes a
100 * combined_orientation argument instead.
101 */
102 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
103 "Use the version of this function which takes a combined_orientation "
104 "argument instead.")
105 static Quadrature<dim>
106 project_to_face(const ReferenceCell &reference_cell,
107 const SubQuadrature &quadrature,
108 const unsigned int face_no);
109
110 /**
111 * Compute the cell quadrature formula corresponding to using
112 * <tt>quadrature</tt> on face <tt>face_no</tt> taking into account the
113 * orientation of the face. For further details, see the general doc for this
114 * class.
115 *
116 * @deprecated Use the version of project_to_face() which takes a
117 * combined_orientation argument instead.
118 */
119 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
120 "Use the version of project_to_face() which takes a combined_orientation "
121 "argument instead.")
122 static Quadrature<dim>
123 project_to_oriented_face(const ReferenceCell &reference_cell,
124 const SubQuadrature &quadrature,
125 const unsigned int face_no,
126 const bool face_orientation,
127 const bool face_flip,
128 const bool face_rotation);
129
130 /**
131 * Compute the cell quadrature formula corresponding to using
132 * <tt>quadrature</tt> on face <tt>face_no</tt>. For further details, see
133 * the general doc for this class.
134 */
135 static Quadrature<dim>
136 project_to_face(const ReferenceCell &reference_cell,
137 const SubQuadrature &quadrature,
138 const unsigned int face_no,
139 const types::geometric_orientation combined_orientation);
140
141 /**
142 * Compute the quadrature points on the cell if the given quadrature formula
143 * is used on face <tt>face_no</tt>, subface number <tt>subface_no</tt>
144 * corresponding to RefineCase::Type <tt>ref_case</tt>. The last argument is
145 * only used in 3d.
146 *
147 * @note Only the points are transformed. The quadrature weights are the
148 * same as those of the original rule.
149 *
150 * @deprecated Use the version of project_to_subface() which takes a
151 * combined_orientation argument instead.
152 */
153 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
154 "Use the version of project_to_subface() which takes a "
155 "combined_orientation argument instead.")
156 static void
157 project_to_subface(const ReferenceCell &reference_cell,
158 const SubQuadrature &quadrature,
159 const unsigned int face_no,
160 const unsigned int subface_no,
161 std::vector<Point<dim>> &q_points,
162 const RefinementCase<dim - 1> &ref_case =
163 RefinementCase<dim - 1>::isotropic_refinement);
164
165 /**
166 * Compute the cell quadrature formula corresponding to using
167 * <tt>quadrature</tt> on subface <tt>subface_no</tt> of face
168 * <tt>face_no</tt> with RefinementCase<dim-1> <tt>ref_case</tt>. The last
169 * argument is only used in 3d.
170 *
171 * @note Only the points are transformed. The quadrature weights are the
172 * same as those of the original rule.
173 *
174 * @note This function is deprecated since it makes an implicit assumption
175 * that the cell is a line (1D), a quad (2d), or a hex (3d). Use the other
176 * version of this function that takes the reference cell type instead.
177 *
178 * @deprecated Use the version of project_to_subface() which takes a
179 * combined_orientation argument instead.
180 */
181 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
182 "Use the version of project_to_subface() which takes a "
183 "combined_orientation argument instead.")
184 static Quadrature<dim>
185 project_to_subface(const ReferenceCell &reference_cell,
186 const SubQuadrature &quadrature,
187 const unsigned int face_no,
188 const unsigned int subface_no,
189 const RefinementCase<dim - 1> &ref_case =
190 RefinementCase<dim - 1>::isotropic_refinement);
191
192 /**
193 * Compute the cell quadrature formula corresponding to using
194 * <tt>quadrature</tt> on subface <tt>subface_no</tt> of face
195 * <tt>face_no</tt> with SubfaceCase<dim> <tt>ref_case</tt>. The last
196 * argument is only used in 3d.
197 *
198 * @note Only the points are transformed. The quadrature weights are the
199 * same as those of the original rule.
200 *
201 * @deprecated Use the version of project_to_subface() which takes a
202 * combined_orientation argument instead.
203 */
204 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
205 "Use the version of project_to_subface() which takes a "
206 "combined_orientation argument instead.")
207 static Quadrature<dim>
208 project_to_oriented_subface(const ReferenceCell &reference_cell,
209 const SubQuadrature &quadrature,
210 const unsigned int face_no,
211 const unsigned int subface_no,
212 const bool face_orientation,
213 const bool face_flip,
214 const bool face_rotation,
215 const internal::SubfaceCase<dim> ref_case);
216
217 /**
218 * Compute the cell quadrature formula corresponding to using
219 * <tt>quadrature</tt> on subface <tt>subface_no</tt> of face
220 * <tt>face_no</tt> with RefinementCase<dim-1> <tt>ref_case</tt>. The last
221 * argument is only used in 3d.
222 *
223 * @note Only the points are transformed. The quadrature weights are the
224 * same as those of the original rule.
225 */
226 static Quadrature<dim>
227 project_to_subface(const ReferenceCell &reference_cell,
228 const SubQuadrature &quadrature,
229 const unsigned int face_no,
230 const unsigned int subface_no,
231 const types::geometric_orientation combined_orientation,
232 const RefinementCase<dim - 1> &ref_case);
233
234 /**
235 * Take a collection of face quadrature formulas and generate a cell
236 * quadrature formula from it where the quadrature points of the given
237 * argument are projected on all faces.
238 *
239 * The weights of the new rule are replications of the original weights.
240 * Thus, the sum of the weights is not one, but the number of faces, which
241 * is the surface of the reference cell.
242 *
243 * This in particular allows us to extract a subset of points corresponding
244 * to a single face and use it as a quadrature on this face, as is done in
245 * FEFaceValues.
246 *
247 * @note This function creates ReferenceCell::n_face_orientations() sets of
248 * quadrature points for each face which are indexed (by combined orientation
249 * and face number) by a DataSetDescriptor.
250 */
251 static Quadrature<dim>
252 project_to_all_faces(const ReferenceCell &reference_cell,
253 const hp::QCollection<dim - 1> &quadrature);
254
255 /**
256 * Like the above function, applying the same face quadrature
257 * formula on all faces.
258 */
259 static Quadrature<dim>
260 project_to_all_faces(const ReferenceCell &reference_cell,
261 const Quadrature<dim - 1> &quadrature);
262
263 /**
264 * Take a face quadrature formula and generate a cell quadrature formula
265 * from it where the quadrature points of the given argument are projected
266 * on all subfaces.
267 *
268 * Like in project_to_all_faces(), the weights of the new rule sum up to the
269 * number of faces (not subfaces), which is the surface of the reference
270 * cell.
271 *
272 * This in particular allows us to extract a subset of points corresponding
273 * to a single subface and use it as a quadrature on this face, as is done
274 * in FESubfaceValues.
275 */
276 static Quadrature<dim>
277 project_to_all_subfaces(const ReferenceCell &reference_cell,
278 const SubQuadrature &quadrature);
279
280 /**
281 * Project a given quadrature formula to a child of a cell. You may want to
282 * use this function in case you want to extend an integral only over the
283 * area which a potential child would occupy. The child numbering is the
284 * same as the children would be numbered upon refinement of the cell.
285 *
286 * As integration using this quadrature formula now only extends over a
287 * fraction of the cell, the weights of the resulting object are divided by
288 * GeometryInfo<dim>::children_per_cell.
289 *
290 * @warning This function is only implemented for hypercube elements.
291 */
292 static Quadrature<dim>
293 project_to_child(const ReferenceCell &reference_cell,
294 const Quadrature<dim> &quadrature,
295 const unsigned int child_no);
296
297 /**
298 * Project a quadrature rule to all children of a cell. Similarly to
299 * project_to_all_subfaces(), this function replicates the formula generated
300 * by project_to_child() for all children, such that the weights sum up to
301 * one, the volume of the total cell again.
302 *
303 * The child numbering is the same as the children would be numbered upon
304 * refinement of the cell.
305 *
306 * @warning This function is only implemented for hypercube elements.
307 */
308 static Quadrature<dim>
309 project_to_all_children(const ReferenceCell &reference_cell,
310 const Quadrature<dim> &quadrature);
311
312 /**
313 * Project the one dimensional rule <tt>quadrature</tt> to the straight line
314 * connecting the points <tt>p1</tt> and <tt>p2</tt>.
315 */
316 static Quadrature<dim>
317 project_to_line(const ReferenceCell &reference_cell,
318 const Quadrature<1> &quadrature,
319 const Point<dim> &p1,
320 const Point<dim> &p2);
321
322 /**
323 * @brief Class storing the offset index into a Quadrature rule created by
324 * project_to_all_faces() or project_to_all_subfaces().
325 *
326 * The functions QProjector::project_to_all_faces() and
327 * QProjector::project_to_all_subfaces() each combine all quadrature rules
328 * (i.e., all possible combinations of face, subface, and combined
329 * orientation) into a single Quadrature object. DataSetDescriptor implements
330 * the correct indexing for extracting from that Quadrature rule the correct
331 * index for those values.
332 */
333 class DataSetDescriptor
334 {
335 public:
336 /**
337 * Default constructor. This doesn't do much except generating an invalid
338 * index, since you didn't give a valid descriptor of the cell, face, or
339 * subface you wanted.
340 */
341 DataSetDescriptor();
342
343 /**
344 * Static function to generate the offset of a cell. Since we only have
345 * one cell per quadrature object, this offset is of course zero, but we
346 * carry this function around for consistency with the other static
347 * functions.
348 */
349 static DataSetDescriptor
350 cell();
351
352 /**
353 * Static function to generate an offset object for a given face of a cell
354 * with the given face orientation, flip and rotation. This function of
355 * course is only allowed if <tt>dim>=2</tt>, and the face orientation,
356 * flip and rotation are ignored if the space dimension equals 2.
357 *
358 * The last argument denotes the number of quadrature points the
359 * lower-dimensional face quadrature formula (the one that has been
360 * projected onto the faces) has.
361 *
362 * @deprecated Use the version of this function which takes a
363 * combined_orientation argument instead.
364 */
365 DEAL_II_DEPRECATED_WITH_COMMENT(
366 "Use the version of this function which takes a combined_orientation "
367 "argument instead.")
368 static DataSetDescriptor
369 face(const ReferenceCell &reference_cell,
370 const unsigned int face_no,
371 const bool face_orientation,
372 const bool face_flip,
373 const bool face_rotation,
374 const unsigned int n_quadrature_points);
375
376 /**
377 * Static function to generate an offset object for a given face of a cell
378 * with the given combined face orientation.
379 *
380 * @p n_quadrature_points is the number of quadrature points the
381 * lower-dimensional face quadrature formula (the one that has been
382 * projected onto the faces) has.
383 */
384 static DataSetDescriptor
385 face(const ReferenceCell &reference_cell,
386 const unsigned int face_no,
387 const types::geometric_orientation combined_orientation,
388 const unsigned int n_quadrature_points);
389
390 /**
391 * Compute an offset object for the given face number and orientation,
392 * taking into account the possibility of different quadrature rules being
393 * used on each face.
394 *
395 * @deprecated Use the version of this function which takes a
396 * combined_orientation argument instead.
397 */
398 DEAL_II_DEPRECATED_WITH_COMMENT(
399 "Use the version of this function which takes a combined_orientation "
400 "argument instead.")
401 static DataSetDescriptor
402 face(const ReferenceCell &reference_cell,
403 const unsigned int face_no,
404 const bool face_orientation,
405 const bool face_flip,
406 const bool face_rotation,
407 const hp::QCollection<dim - 1> &quadrature);
408
409 /**
410 * Compute an offset object for the given face number and orientation,
411 * taking into account the possibility of different quadrature rules being
412 * used on each face.
413 *
414 */
415 static DataSetDescriptor
416 face(const ReferenceCell &reference_cell,
417 const unsigned int face_no,
418 const types::geometric_orientation combined_orientation,
419 const hp::QCollection<dim - 1> &quadrature);
420
421 /**
422 * Static function to generate an offset object for a given subface of a
423 * cell with the given face orientation, flip and rotation. This function
424 * of course is only allowed if <tt>dim>=2</tt>, and the face orientation,
425 * flip and rotation are ignored if the space dimension equals 2.
426 *
427 * The last but one argument denotes the number of quadrature points the
428 * lower-dimensional face quadrature formula (the one that has been
429 * projected onto the faces) has.
430 *
431 * Through the last argument anisotropic refinement can be respected.
432 *
433 * @deprecated Use the version of this function which takes a
434 * combined_orientation argument instead.
435 */
436 DEAL_II_DEPRECATED_WITH_COMMENT(
437 "Use the version of this function which takes a combined_orientation "
438 "argument instead.")
439 static DataSetDescriptor
440 subface(const ReferenceCell &reference_cell,
441 const unsigned int face_no,
442 const unsigned int subface_no,
443 const bool face_orientation,
444 const bool face_flip,
445 const bool face_rotation,
446 const unsigned int n_quadrature_points,
447 const internal::SubfaceCase<dim> ref_case =
448 internal::SubfaceCase<dim>::case_isotropic);
449
450 /**
451 * Static function to generate an offset object for a given subface of a
452 * cell with the given combined face orientation. This function of course is
453 * only allowed if <tt>dim>=2</tt>, and the orientation is ignored if the
454 * space dimension equals 2.
455 *
456 * @p n_quadrature_points denotes the number of quadrature points the
457 * lower-dimensional face quadrature formula (the one that has been
458 * projected onto the faces) has.
459 *
460 * Through the last argument anisotropic refinement can be respected.
461 */
462 static DataSetDescriptor
463 subface(const ReferenceCell &reference_cell,
464 const unsigned int face_no,
465 const unsigned int subface_no,
466 const types::geometric_orientation combined_orientation,
467 const unsigned int n_quadrature_points,
468 const internal::SubfaceCase<dim> ref_case =
469 internal::SubfaceCase<dim>::case_isotropic);
470
471 /**
472 * Conversion operator to an integer denoting the offset of the first
473 * element of this dataset in the set of quadrature formulas all projected
474 * onto faces and subfaces. This conversion operator allows us to use
475 * offset descriptor objects in place of integer offsets.
476 */
477 operator unsigned int() const;
478
479 private:
480 /**
481 * Store the integer offset for a given cell, face, or subface.
482 */
483 const unsigned int dataset_offset;
484
485 /**
486 * This is the real constructor, but it is private and thus only available
487 * to the static member functions above.
488 */
489 DataSetDescriptor(const unsigned int dataset_offset);
490 };
491 };
492
493 /** @} */
494
495
496 // ------------------- inline and template functions ----------------
497
498
499
500 template <int dim>
501 inline QProjector<dim>::DataSetDescriptor::DataSetDescriptor(
502 const unsigned int dataset_offset)
503 : dataset_offset(dataset_offset)
504 {}
505
506
507 template <int dim>
508 inline QProjector<dim>::DataSetDescriptor::DataSetDescriptor()
509 : dataset_offset(numbers::invalid_unsigned_int)
510 {}
511
512
513
514 template <int dim>
515 typename QProjector<dim>::DataSetDescriptor
516 QProjector<dim>::DataSetDescriptor::cell()
517 {
518 return 0;
519 }
520
521
522
523 template <int dim>
524 inline QProjector<dim>::DataSetDescriptor::operator unsigned int() const
525 {
526 return dataset_offset;
527 }
528
529
530
531 template <int dim>
532 Quadrature<dim> inline QProjector<dim>::project_to_all_faces(
533 const ReferenceCell &reference_cell,
534 const Quadrature<dim - 1> &quadrature)
535 {
536 return project_to_all_faces(reference_cell,
537 hp::QCollection<dim - 1>(quadrature));
538 }
539
540
541 /* -------------- declaration of explicit specializations ------------- */
542
543 #ifndef DOXYGEN
544
545
546 template <>
547 void
548 QProjector<1>::project_to_face(const ReferenceCell &reference_cell,
549 const Quadrature<0> &,
550 const unsigned int,
551 std::vector<Point<1>> &);
552 template <>
553 void
554 QProjector<2>::project_to_face(const ReferenceCell &reference_cell,
555 const Quadrature<1> &quadrature,
556 const unsigned int face_no,
557 std::vector<Point<2>> &q_points);
558 template <>
559 void
560 QProjector<3>::project_to_face(const ReferenceCell &reference_cell,
561 const Quadrature<2> &quadrature,
562 const unsigned int face_no,
563 std::vector<Point<3>> &q_points);
564
565 template <>
566 void
567 QProjector<1>::project_to_subface(const ReferenceCell &reference_cell,
568 const Quadrature<0> &,
569 const unsigned int,
570 const unsigned int,
571 std::vector<Point<1>> &,
572 const RefinementCase<0> &);
573 template <>
574 void
575 QProjector<2>::project_to_subface(const ReferenceCell &reference_cell,
576 const Quadrature<1> &quadrature,
577 const unsigned int face_no,
578 const unsigned int subface_no,
579 std::vector<Point<2>> &q_points,
580 const RefinementCase<1> &);
581 template <>
582 void
583 QProjector<3>::project_to_subface(const ReferenceCell &reference_cell,
584 const Quadrature<2> &quadrature,
585 const unsigned int face_no,
586 const unsigned int subface_no,
587 std::vector<Point<3>> &q_points,
588 const RefinementCase<2> &face_ref_case);
589
590 template <>
591 Quadrature<1>
592 QProjector<1>::project_to_all_subfaces(const ReferenceCell &reference_cell,
593 const Quadrature<0> &quadrature);
594
595
596 #endif // DOXYGEN
597 DEAL_II_NAMESPACE_CLOSE
598
599 #endif