Debian Codegraph @

include/deal.II/base/quadrature.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_quadrature_h
16 #define dealii_quadrature_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/array_view.h>
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/point.h>
25
26 #include <array>
27 #include <memory>
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * @addtogroup Quadrature
34 * @{
35 */
36
37 /**
38 * Base class for quadrature formulae in arbitrary dimensions.
39 * [Quadrature](https://en.wikipedia.org/wiki/Numerical_integration)
40 * is a means to approximate an integral by evaluating the integrand
41 * at specific points $\mathbf x_q$ and summing the point values with
42 * specific weights $w_q$; that is, quadrature computes
43 * @f{align*}{
44 * \int_K f(\mathbf x) \; dx
45 * \approx
46 * \sum_{q=0,\ldots,Q-1} f(\mathbf x_q) w_q.
47 * @f}
48 *
49 * This class stores quadrature points $\mathbf x_q$ and weights $w_q$
50 * for concrete "quadrature formulas" when $K$ (the domain we integrate
51 * over) is a reference cell. That is, points and weights are expressed
52 * in the coordinate system of
53 * a reference cell (see the ReferenceCell class) and as such serves to
54 * represent quadrature points and weights on the unit line segment
55 * $[0,1]$ in 1d, on the unit square or unit triangle in 2d, as well as
56 * the unit tetrahedron, cube, pyramid, and wedge reference cells in 3d.
57 * Integration over concrete cells is done by coordinate transformation
58 * to the reference cell represented by the current class.
59 *
60 * There are a number of derived classes, denoting concrete integration
61 * formulae. Their names are prefixed by <tt>Q</tt>. Refer to the list of
62 * derived classes for more details.
63 *
64 * At least for quadrilaterals and hexahedra (or, more precisely, since we work
65 * on reference cells: for the unit square and the unit cube), quadrature
66 * formulas are typically tensor products of one-dimensional formulas (see also
67 * the section on implementation detail below).
68 *
69 * In order to allow for dimension independent programming, a quadrature
70 * formula of dimension zero exists. Since an integral over zero dimensions is
71 * the evaluation at a single point, any constructor of such a formula
72 * initializes to a single quadrature point with weight one. Access to the
73 * weight is possible, while access to the quadrature point is not permitted,
74 * since a Point of dimension zero contains no information. The main purpose
75 * of these formulae is their use in QProjector, which will create a useful
76 * formula of dimension one out of them.
77 *
78 *
79 * <h3>Mathematical background</h3>
80 *
81 * For each quadrature formula we denote by <tt>m</tt>, the maximal degree of
82 * polynomials integrated exactly on the reference cell the quadrature
83 * formula corresponds to. This number is given in the documentation
84 * of each formula. The *order* of the integration error is <tt>m+1</tt>, that
85 * is, the error is the size of the cell to the <tt>m+1</tt> by the
86 * Bramble-Hilbert Lemma. The number <tt>m</tt> is to be found in the
87 * documentation of each concrete formula. For the optimal formulae QGauss we
88 * have $m = 2N-1$, where $N$ is the constructor parameter to QGauss. The tensor
89 * product formulae are exact on tensor product polynomials of degree <tt>m</tt>
90 * in each space direction, but they are still only of <tt>(m+1)</tt>st order.
91 *
92 *
93 * <h3>Tensor product quadrature</h3>
94 *
95 * At least for hypercube reference cells (i.e., squares and cubes),
96 * most integration formulae in more than one space dimension are tensor
97 * products of quadrature formulae in one space dimension, or more generally
98 * the tensor product of a formula in <tt>(dim-1)</tt> dimensions and one in
99 * one dimension. There is a special constructor to generate a quadrature
100 * formula from two others. For example, the QGauss@<dim@> formulae include
101 * <i>N<sup>dim</sup></i> quadrature points in <tt>dim</tt> dimensions, where
102 * $N$ is the constructor parameter of QGauss.
103 *
104 *
105 * <h3>Other uses of this class</h3>
106 *
107 * Quadrature objects are used in a number of places within deal.II where
108 * integration is performed, most notably via the FEValues and related classes.
109 * Some of these classes are also used in contexts where no integrals
110 * are involved, but where functions need to be evaluated at specific
111 * points, for example to evaluate the solution at individual points
112 * or to create graphical output. Examples are the implementation of
113 * VectorTools::point_value() and the DataOut and related classes (in
114 * particular in connection with the DataPostprocessor class). In
115 * such contexts, one often creates specific "Quadrature" objects in
116 * which the "quadrature points" are simply the points (in the coordinate
117 * system of the reference cell) at which one wants to evaluate the
118 * solution. In these kinds of cases, the weights stored by the current
119 * class are not used and the name "quadrature object" is interpreted
120 * as "list of evaluation points".
121 */
122 template <int dim>
123 class Quadrature : public EnableObserverPointer
124 {
125 public:
126 /**
127 * Define an alias for a quadrature that acts on an object of one dimension
128 * less. For cells, this would then be a face quadrature. A sub quadrature of
129 * a 0-dimensional quadrature is defined as still being 0-dimensional.
130 */
131 using SubQuadrature = Quadrature<dim == 0 ? 0 : dim - 1>;
132
133 /**
134 * Default constructor.
135 */
136 Quadrature();
137
138 /**
139 * Build this quadrature formula as the tensor product of a formula in a
140 * dimension one less than the present and a formula in one dimension.
141 * This constructor assumes (and tests) that constant functions are integrated
142 * exactly, i.e. the sum of the quadrature weights is one.
143 *
144 * <tt>SubQuadrature<dim>::type</tt> expands to <tt>Quadrature<dim-1></tt>.
145 */
146 Quadrature(const SubQuadrature &, const Quadrature<1> &);
147
148 /**
149 * Build this quadrature formula as the <tt>dim</tt>-fold tensor product of
150 * a formula in one dimension.
151 *
152 * Assuming that the points in the one-dimensional rule are in ascending
153 * order, the points of the resulting rule are ordered lexicographically
154 * with <i>x</i> running fastest.
155 *
156 * In order to avoid a conflict with the copy constructor in 1d, we let the
157 * argument be a 0d quadrature formula for dim==1, and a 1d quadrature
158 * formula for all other space dimensions.
159 *
160 * This constructor does not require that constant functions are integrated
161 * exactly. Therefore, it is appropriate if the one-dimensional formula
162 * is defined with respect to a weighting function.
163 *
164 * If dim == 0, the resulting quadrature formula will be a single Point<0>
165 * having unit weight.
166 */
167 explicit Quadrature(const Quadrature<dim != 1 ? 1 : 0> &quadrature_1d);
168
169 /**
170 * Copy constructor.
171 */
172 Quadrature(const Quadrature<dim> &q);
173
174 /**
175 * Move constructor. Construct a new quadrature object by transferring the
176 * internal data of another quadrature object.
177 */
178 Quadrature(Quadrature<dim> &&) noexcept = default;
179
180 /**
181 * Construct a quadrature formula from given vectors of quadrature points
182 * (which should really be in the unit cell) and the corresponding weights.
183 * You will want to have the weights sum up to one, but this is not checked.
184 */
185 Quadrature(const std::vector<Point<dim>> &points,
186 const std::vector<double> &weights);
187
188 /**
189 * Construct a quadrature formula from given vectors of quadrature points
190 * (which should really be in the unit cell) and the corresponding weights,
191 * moving the points and weights into the present object.
192 */
193 Quadrature(std::vector<Point<dim>> &&points, std::vector<double> &&weights);
194
195 /**
196 * Construct a dummy quadrature formula from a list of points, with weights
197 * set to infinity. The resulting object is therefore not meant to actually
198 * perform integrations, but rather to be used with FEValues objects in
199 * order to find the position of some points (the quadrature points in this
200 * object) on the transformed cell in real space.
201 */
202 Quadrature(const std::vector<Point<dim>> &points);
203
204 /**
205 * Constructor for a one-point quadrature. Sets the weight of this point to
206 * one.
207 */
208 Quadrature(const Point<dim> &point);
209
210 /**
211 * Virtual destructor.
212 */
213 virtual ~Quadrature() override = default;
214
215 /**
216 * Assignment operator. Copies contents of #weights and #quadrature_points
217 * as well as size.
218 */
219 Quadrature &
220 operator=(const Quadrature<dim> &);
221
222 /**
223 * Move assignment operator. Moves all data from another quadrature object
224 * to this object.
225 */
226 Quadrature &
227 operator=(Quadrature<dim> &&) = default; // NOLINT
228
229 /**
230 * Test for equality of two quadratures.
231 */
232 bool
233 operator==(const Quadrature<dim> &p) const;
234
235 /**
236 * Set the quadrature points and weights to the values provided in the
237 * arguments. The weights array is allowed to be empty, in which case the
238 * weights are set to infinity. The resulting object is therefore not meant
239 * to actually perform integrations, but rather to be used with FEValues
240 * objects in order to find the position of some points (the quadrature
241 * points in this object) on the transformed cell in real space.
242 */
243 void
244 initialize(const ArrayView<const Point<dim>> &points,
245 const ArrayView<const double> &weights = {});
246
247 /**
248 * Number of quadrature points.
249 */
250 unsigned int
251 size() const;
252
253 /**
254 * Return if quadrature is empty.
255 */
256 bool
257 empty() const;
258
259 /**
260 * Return the <tt>i</tt>th quadrature point.
261 */
262 const Point<dim> &
263 point(const unsigned int i) const;
264
265 /**
266 * Return a reference to the whole array of quadrature points.
267 */
268 const std::vector<Point<dim>> &
269 get_points() const;
270
271 /**
272 * Return the weight of the <tt>i</tt>th quadrature point.
273 */
274 double
275 weight(const unsigned int i) const;
276
277 /**
278 * Return a reference to the whole array of weights.
279 */
280 const std::vector<double> &
281 get_weights() const;
282
283 /**
284 * Determine an estimate for the memory consumption (in bytes) of this
285 * object.
286 */
287 std::size_t
288 memory_consumption() const;
289
290 /**
291 * Write or read the data of this object to or from a stream for the purpose
292 * of serialization using the [BOOST serialization
293 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
294 */
295 template <class Archive>
296 void
297 serialize(Archive &ar, const unsigned int version);
298
299 /**
300 * This function returns true if the quadrature object is a tensor product
301 * of one-dimensional formulas and the quadrature points are sorted
302 * lexicographically.
303 */
304 bool
305 is_tensor_product() const;
306
307 /**
308 * In case the quadrature formula is a tensor product, this function
309 * returns the @p dim one-dimensional basis objects.
310 * Otherwise, calling this function is not allowed.
311 *
312 * For @p dim equal to one, we can not return the std::array as a const
313 * reference and have to return it by value. In this case, the array
314 * will always contain a single element (@p this).
315 *
316 * @note The actual return type of this function is
317 * @code
318 * std::conditional_t<dim == 1,
319 * std::array<Quadrature<1>, dim>,
320 * const std::array<Quadrature<1>, dim> &>
321 * @endcode
322 * The type is abbreviated in the online documentation to improve
323 * readability of this page.
324 */
325 #ifndef DOXYGEN
326 std::conditional_t<dim == 1,
327 std::array<Quadrature<1>, dim>,
328 const std::array<Quadrature<1>, dim> &>
329 #else
330 const std::array<Quadrature<1>, dim> &
331 #endif
332 get_tensor_basis() const;
333
334 protected:
335 /**
336 * Constructor.
337 *
338 * This constructor is marked as explicit to avoid involuntary accidents
339 * like in <code>hp::QCollection@<dim@> q_collection(3)</code> where
340 * <code>hp::QCollection@<dim@> q_collection(QGauss@<dim@>(3))</code> was
341 * meant. Nonetheless, it is easy to accidentally write
342 * @code
343 * Quadrature<dim> quadrature(3);
344 * @endcode
345 * where QGauss was meant. As a consequence, this constructor is `protected`
346 * and so only available to derived classes initializing their base class.
347 */
348 explicit Quadrature(const unsigned int n_quadrature_points);
349
350 /**
351 * List of quadrature points. To be filled by the constructors of derived
352 * classes.
353 */
354 std::vector<Point<dim>> quadrature_points;
355
356 /**
357 * List of weights of the quadrature points. To be filled by the
358 * constructors of derived classes.
359 */
360 std::vector<double> weights;
361
362 /**
363 * Indicates if this object represents quadrature formula that is a tensor
364 * product of one-dimensional formulas.
365 * This flag is set if dim==1 or the constructors taking a Quadrature<1>
366 * (and possibly a Quadrature<dim-1> object) is called. This implies
367 * that the quadrature points are sorted lexicographically.
368 */
369 bool is_tensor_product_flag;
370
371 /**
372 * Stores the one-dimensional tensor basis objects in case this object
373 * can be represented by a tensor product.
374 */
375 std::unique_ptr<std::array<Quadrature<1>, dim>> tensor_basis;
376 };
377
378
379 /**
380 * Quadrature formula implementing anisotropic distributions of quadrature
381 * points on the reference cell. To this end, the tensor product of
382 * <tt>dim</tt> one-dimensional quadrature formulas is generated.
383 *
384 * @note Each constructor can only be used in the dimension matching the
385 * number of arguments.
386 */
387 template <int dim>
388 class QAnisotropic : public Quadrature<dim>
389 {
390 public:
391 /**
392 * Constructor for a one-dimensional formula. This one just copies the given
393 * quadrature rule.
394 */
395 QAnisotropic(const Quadrature<1> &qx);
396
397 /**
398 * Constructor for a two-dimensional formula.
399 */
400 QAnisotropic(const Quadrature<1> &qx, const Quadrature<1> &qy);
401
402 /**
403 * Constructor for a three-dimensional formula.
404 */
405 QAnisotropic(const Quadrature<1> &qx,
406 const Quadrature<1> &qy,
407 const Quadrature<1> &qz);
408 };
409
410
411 /**
412 * Quadrature formula constructed by iteration of another quadrature formula
413 * in each direction. In more than one space dimension, the resulting
414 * quadrature formula is constructed in the usual way by building the tensor
415 * product of the respective iterated quadrature formula in one space
416 * dimension.
417 *
418 * In one space dimension, the given base formula is copied and scaled onto a
419 * given number of subintervals of length <tt>1/n_copies</tt>. If the
420 * quadrature formula uses both end points of the unit interval, then in the
421 * interior of the iterated quadrature formula there would be quadrature
422 * points which are used twice; we merge them into one with a weight which is
423 * the sum of the weights of the left- and the rightmost quadrature point.
424 *
425 * Since all dimensions higher than one are built up by tensor products of one
426 * dimensional and <tt>dim-1</tt> dimensional quadrature formulae, the
427 * argument given to the constructor needs to be a quadrature formula in one
428 * space dimension, rather than in <tt>dim</tt> dimensions.
429 *
430 * The aim of this class is to provide a low order formula, where the error
431 * constant can be tuned by increasing the number of quadrature points. This
432 * is useful in integrating non-differentiable functions on cells.
433 */
434 template <int dim>
435 class QIterated : public Quadrature<dim>
436 {
437 public:
438 /**
439 * Constructor. Iterate the given quadrature formula <tt>n_copies</tt> times
440 * in each direction. The result is a tensor product quadrature formula
441 * defined on the unit hypercube (i.e., the line segment, unit square, or
442 * unit cube in 1d, 2d, and 3d respectively).
443 */
444 QIterated(const Quadrature<1> &base_quadrature, const unsigned int n_copies);
445
446 /**
447 * Constructor. Iterate the given quadrature formula on the given subintervals
448 * defined by adjacent points in @p intervals in each direction. The resulting
449 * quadrature rule will have `base_quadrature.size() * (intervals.size() - 1)`
450 * quadrature points if no quadrature point of `base_quadrature` is positioned
451 * on the boundaries. The result is a tensor product quadrature formula
452 * defined on the unit hypercube (i.e., the line segment, unit square, or
453 * unit cube in 1d, 2d, and 3d respectively).
454 *
455 * @note We require that `intervals.front() == 0` and `interval.back() == 1`.
456 */
457 QIterated(const Quadrature<1> &base_quadrature,
458 const std::vector<Point<1>> &intervals);
459
460 /**
461 * Exception
462 */
463 DeclExceptionMsg(ExcInvalidQuadratureFormula,
464 "The quadrature formula you provided cannot be used "
465 "as the basis for iteration.");
466 };
467
468
469
470 /** @} */
471
472 #ifndef DOXYGEN
473
474 // ------------------- inline and template functions ----------------
475
476
477 template <int dim>
478 inline unsigned int
479 Quadrature<dim>::size() const
480 {
481 return weights.size();
482 }
483
484
485
486 template <int dim>
487 inline bool
488 Quadrature<dim>::empty() const
489 {
490 return weights.empty();
491 }
492
493
494
495 template <int dim>
496 inline const Point<dim> &
497 Quadrature<dim>::point(const unsigned int i) const
498 {
499 AssertIndexRange(i, size());
500 return quadrature_points[i];
501 }
502
503
504
505 template <int dim>
506 double
507 Quadrature<dim>::weight(const unsigned int i) const
508 {
509 AssertIndexRange(i, size());
510 return weights[i];
511 }
512
513
514
515 template <int dim>
516 inline const std::vector<Point<dim>> &
517 Quadrature<dim>::get_points() const
518 {
519 return quadrature_points;
520 }
521
522
523
524 template <int dim>
525 inline const std::vector<double> &
526 Quadrature<dim>::get_weights() const
527 {
528 return weights;
529 }
530
531
532
533 template <int dim>
534 inline bool
535 Quadrature<dim>::is_tensor_product() const
536 {
537 return is_tensor_product_flag;
538 }
539
540
541
542 template <int dim>
543 template <class Archive>
544 inline void
545 Quadrature<dim>::serialize(Archive &ar, const unsigned int)
546 {
547 // forward to serialization
548 // function in the base class.
549 ar &static_cast<EnableObserverPointer &>(*this);
550
551 ar &quadrature_points &weights;
552 }
553
554
555
556 /* -------------- declaration of explicit specializations ------------- */
557
558 template <>
559 Quadrature<0>::Quadrature(const unsigned int);
560 template <>
561 Quadrature<0>::Quadrature(const Quadrature<0>::SubQuadrature &,
562 const Quadrature<1> &);
563 template <>
564 Quadrature<0>::Quadrature(const Quadrature<1> &);
565 template <>
566 Quadrature<0>::Quadrature(const Point<0> &);
567
568 template <>
569 Quadrature<1>::Quadrature(const Quadrature<0> &, const Quadrature<1> &);
570
571 template <>
572 Quadrature<1>::Quadrature(const Quadrature<0> &);
573
574 template <>
575 QIterated<1>::QIterated(const Quadrature<1> &base_quadrature,
576 const unsigned int n_copies);
577
578 #endif // DOXYGEN
579 DEAL_II_NAMESPACE_CLOSE
580
581 #endif