Debian Codegraph @

include/deal.II/base/quadrature_lib.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_quadrature_lib_h
16 #define dealii_quadrature_lib_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/quadrature.h>
22
23 DEAL_II_NAMESPACE_OPEN
24
25 /**
26 * @addtogroup Quadrature
27 * @{
28 */
29
30 /**
31 * The Gauss-Legendre family of quadrature rules for numerical integration.
32 *
33 * The coefficients of these quadrature rules are computed by the function
34 * described in <a
35 * href="http://en.wikipedia.org/wiki/Numerical_Recipes">Numerical
36 * Recipes</a>.
37 */
38 template <int dim>
39 class QGauss : public Quadrature<dim>
40 {
41 public:
42 /**
43 * Generate a formula with <tt>n</tt> quadrature points (in each space
44 * direction), exact for polynomials of degree <tt>2n-1</tt>.
45 */
46 QGauss(const unsigned int n);
47 };
48
49 /**
50 * The Gauss-Radau family of quadrature rules for numerical integration.
51 *
52 * This modification of the Gauss quadrature uses one of the two interval end
53 * points as well. Being exact for polynomials of degree $2n-2$, this
54 * formula is suboptimal by one degree.
55 *
56 * This formula is often used in the context of discontinuous Galerkin
57 * discretizations of ODEs and the temporal part of PDEs.
58 *
59 * The quadrature points are the left interval end point plus the $n-1$
60 * roots of the polynomial
61 * \f[
62 * \frac{P_{n-1}(x)+P_n(x)}{1+x}
63 * \f]
64 * where $P_{n-1}$ and $P_n$ are Legendre polynomials.
65 * The quadrature weights are
66 * \f[
67 * w_0=\frac{2}{n^2}\quad\text{and}
68 * \quad w_i=\frac{1-x_i}{n^2(P_{n-1}(x_i))^2}\text{ for }i>0
69 * \f]
70 *
71 * For the right Gauss-Radau formula the quadrature points are
72 * $\tilde{x}_i=1-x_{n-i-1}$ and the weights are $\tilde{w}_i=w_{n-i-1}$,
73 * with $(x_i,w_i)$ as quadrature points
74 * and weights of the left Gauss-Radau formula.
75 *
76 * @see https://mathworld.wolfram.com/RadauQuadrature.html
77 */
78 template <int dim>
79 class QGaussRadau : public Quadrature<dim>
80 {
81 public:
82 /**
83 * EndPoint is used to specify which of the two endpoints of the unit interval
84 * is used also as quadrature point.
85 */
86 enum EndPoint
87 {
88 /**
89 * Left end point.
90 */
91 left,
92 /**
93 * Right end point.
94 */
95 right
96 };
97 /**
98 * Generate a formula with <tt>n</tt> quadrature points (in each space
99 * direction).
100 * <tt>ep</tt> defines whether the left/lower/front endpoint(s) (default)
101 * or the right/upper/back endpoint(s) are part of the quadrature points.
102 */
103 QGaussRadau(const unsigned int n,
104 const EndPoint end_point = QGaussRadau::EndPoint::left);
105
106 /**
107 * Move constructor.
108 */
109 QGaussRadau(QGaussRadau<dim> &&) noexcept = default;
110
111 private:
112 const EndPoint end_point;
113 };
114
115
116 /**
117 * The Gauss-Lobatto family of quadrature rules for numerical integration.
118 *
119 * This modification of the Gauss quadrature uses the two interval end points
120 * as well. Being exact for polynomials of degree <i>2n-3</i>, this formula is
121 * suboptimal by two degrees.
122 *
123 * The quadrature points are interval end points plus the roots of the
124 * derivative of the Legendre polynomial <i>P<sub>n-1</sub></i> of degree
125 * <i>n-1</i>. The quadrature weights are
126 * <i>2/(n(n-1)(P<sub>n-1</sub>(x<sub>i</sub>)<sup>2</sup>)</i>.
127 *
128 * @note This implementation has not been optimized concerning numerical
129 * stability and efficiency. It can be easily adapted to the general case of
130 * Gauss-Lobatto-Jacobi-Bouzitat quadrature with arbitrary parameters
131 * $\alpha$, $\beta$, of which the Gauss-Lobatto-Legendre quadrature ($\alpha
132 * = \beta = 0$) is a special case.
133 *
134 * @sa http://en.wikipedia.org/wiki/Handbook_of_Mathematical_Functions @sa
135 * Karniadakis, G.E. and Sherwin, S.J.: Spectral/hp element methods for
136 * computational fluid dynamics. Oxford: Oxford University Press, 2005
137 */
138 template <int dim>
139 class QGaussLobatto : public Quadrature<dim>
140 {
141 public:
142 /**
143 * Generate a formula with <tt>n</tt> quadrature points (in each space
144 * direction).
145 */
146 QGaussLobatto(const unsigned int n);
147 };
148
149
150
151 /**
152 * The midpoint rule for numerical quadrature. This one-point formula is exact
153 * for linear integrands.
154 *
155 * @note This class only works for cells that are tensor product (hypercube) cells,
156 * that is, are either ReferenceCells::Line, ReferenceCells::Quadrilateral,
157 * or ReferenceCells::Hexahedron. For other cell shapes, this class is not
158 * appropriate. Use ReferenceCell::get_midpoint_quadrature() instead.
159 */
160 template <int dim>
161 class QMidpoint : public Quadrature<dim>
162 {
163 public:
164 QMidpoint();
165 };
166
167
168 /**
169 * The Simpson rule for numerical quadrature. This formula with 3 quadrature
170 * points is exact for polynomials of degree 3.
171 */
172 template <int dim>
173 class QSimpson : public Quadrature<dim>
174 {
175 public:
176 QSimpson();
177 };
178
179
180
181 /**
182 * The trapezoidal rule for numerical quadrature. This formula with two
183 * quadrature points is exact for linear polynomials and uses the
184 * end points of an interval for function evaluation in 1d, see
185 * https://en.wikipedia.org/wiki/Trapezoidal_rule . In higher dimensions,
186 * the class is constructed via a tensor product and then uses the
187 * vertices of a quadrilateral or hexahedron for function evaluation.
188 */
189 template <int dim>
190 class QTrapezoid : public Quadrature<dim>
191 {
192 public:
193 QTrapezoid();
194 };
195
196
197 /**
198 * The Milne rule for numerical quadrature formula. The Milne rule is a closed
199 * Newton-Cotes formula and is exact for polynomials of degree 5.
200 *
201 * @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
202 */
203 template <int dim>
204 class QMilne : public Quadrature<dim>
205 {
206 public:
207 QMilne();
208 };
209
210
211 /**
212 * The Weddle rule for numerical quadrature. The Weddle rule is a closed
213 * Newton-Cotes formula and is exact for polynomials of degree 7.
214 *
215 * @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
216 */
217 template <int dim>
218 class QWeddle : public Quadrature<dim>
219 {
220 public:
221 QWeddle();
222 };
223
224
225
226 /**
227 * A class for Gauss quadrature with logarithmic weighting function. This
228 * formula is used to integrate $\ln|x|\;f(x)$ on the interval $[0,1]$, where
229 * $f$ is a smooth function without singularities. The collection of
230 * quadrature points and weights has been obtained using <tt>Numerical
231 * Recipes</tt>.
232 *
233 * Notice that only the function $f(x)$ should be provided, i.e., $\int_0^1
234 * f(x) \ln|x| dx = \sum_{i=0}^N w_i f(q_i)$. Setting the @p revert flag to
235 * true at construction time switches the weight from $\ln|x|$ to $\ln|1-x|$.
236 *
237 * The weights and functions have been tabulated up to order 12.
238 */
239 template <int dim>
240 class QGaussLog : public Quadrature<dim>
241 {
242 public:
243 /**
244 * Generate a formula with <tt>n</tt> quadrature points
245 */
246 QGaussLog(const unsigned int n, const bool revert = false);
247
248 private:
249 /**
250 * Compute the points of the quadrature formula.
251 */
252 static std::vector<double>
253 get_quadrature_points(const unsigned int n);
254
255 /**
256 * Compute the weights of the quadrature formula.
257 */
258 static std::vector<double>
259 get_quadrature_weights(const unsigned int n);
260 };
261
262
263
264 /**
265 * A class for Gauss quadrature with arbitrary logarithmic weighting function.
266 * This formula is used to integrate $\ln(|x-x_0|/\alpha)\;f(x)$ on the
267 * interval $[0,1]$, where $f$ is a smooth function without singularities, and
268 * $x_0$ and $\alpha$ are given at construction time, and are the location of
269 * the singularity $x_0$ and an arbitrary scaling factor in the singularity.
270 *
271 * You have to make sure that the point $x_0$ is not one of the Gauss
272 * quadrature points of order $N$, otherwise an exception is thrown, since the
273 * quadrature weights cannot be computed correctly.
274 *
275 * This quadrature formula is rather expensive, since it uses internally two
276 * Gauss quadrature formulas of order n to integrate the nonsingular part of
277 * the factor, and two GaussLog quadrature formulas to integrate on the
278 * separate segments $[0,x_0]$ and $[x_0,1]$. If the singularity is one of the
279 * extremes and the factor alpha is 1, then this quadrature is the same as
280 * QGaussLog.
281 *
282 * The last argument from the constructor allows you to use this quadrature
283 * rule in one of two possible ways: \f[ \int_0^1 g(x) dx = \int_0^1 f(x)
284 * \ln\left(\frac{|x-x_0|}{\alpha}\right) dx = \sum_{i=0}^N w_i g(q_i) =
285 * \sum_{i=0}^N \bar{w}_i f(q_i) \f]
286 *
287 * Which one of the two sets of weights is provided, can be selected by the @p
288 * factor_out_singular_weight parameter. If it is false (the default), then
289 * the $\bar{w}_i$ weights are computed, and you should provide only the
290 * smooth function $f(x)$, since the singularity is included inside the
291 * quadrature. If the parameter is set to true, then the singularity is
292 * factored out of the quadrature formula, and you should provide a function
293 * $g(x)$, which should at least be similar to $\ln(|x-x_0|/\alpha)$.
294 *
295 * Notice that this quadrature rule is worthless if you try to use it for
296 * regular functions once you factored out the singularity.
297 *
298 * The weights and functions have been tabulated up to order 12.
299 */
300 template <int dim>
301 class QGaussLogR : public Quadrature<dim>
302 {
303 public:
304 /**
305 * The constructor takes four arguments: the order of the Gauss formula on
306 * each of the segments $[0,x_0]$ and $[x_0,1]$, the actual location of the
307 * singularity, the scale factor inside the logarithmic function and a flag
308 * that decides whether the singularity is left inside the quadrature
309 * formula or it is factored out, to be included in the integrand.
310 */
311 QGaussLogR(const unsigned int n,
312 const Point<dim> &x0 = Point<dim>(),
313 const double alpha = 1,
314 const bool factor_out_singular_weight = false);
315
316 /**
317 * Move constructor. We cannot rely on the move constructor for `Quadrature`,
318 * since it does not know about the additional member `fraction` of this
319 * class.
320 */
321 QGaussLogR(QGaussLogR<dim> &&) noexcept = default;
322
323 protected:
324 /**
325 * This is the length of interval $(0,origin)$, or 1 if either of the two
326 * extremes have been selected.
327 */
328 const double fraction;
329 };
330
331
332 /**
333 * A class for Gauss quadrature with $1/R$ weighting function. This formula
334 * can be used to integrate $1/R \ f(x)$ on the reference element $[0,1]^2$,
335 * where $f$ is a smooth function without singularities, and $R$ is the
336 * distance from the point $x$ to the vertex $\xi$, given at construction time
337 * by specifying its index. Notice that this distance is evaluated in the
338 * reference element.
339 *
340 * This quadrature formula is obtained from two QGauss quadrature formulas,
341 * upon transforming them into polar coordinate system centered at the
342 * singularity, and then again into another reference element. This allows for
343 * the singularity to be cancelled by part of the Jacobian of the
344 * transformation, which contains $R$. In practice the reference element is
345 * transformed into a triangle by collapsing one of the sides adjacent to the
346 * singularity. The Jacobian of this transformation contains $R$, which is
347 * removed before scaling the original quadrature, and this process is
348 * repeated for the next half element.
349 *
350 * Upon construction it is possible to specify whether we want the singularity
351 * removed, or not. In other words, this quadrature can be used to integrate
352 * $g(x) = 1/R\ f(x)$, or simply $f(x)$, with the $1/R$ factor already
353 * included in the quadrature weights.
354 */
355 template <int dim>
356 class QGaussOneOverR : public Quadrature<dim>
357 {
358 public:
359 /**
360 * This constructor takes three arguments: the order of the Gauss formula,
361 * the point of the reference element in which the singularity is located,
362 * and whether we include the weighting singular function inside the
363 * quadrature, or we leave it in the user function to be integrated.
364 *
365 * Traditionally, quadrature formulas include their weighting function, and
366 * the last argument is set to false by default. There are cases, however,
367 * where this is undesirable (for example when you only know that your
368 * singularity has the same order of 1/R, but cannot be written exactly in
369 * this way).
370 *
371 * In other words, you can use this function in either of the following way,
372 * obtaining the same result:
373 *
374 * @code
375 * QGaussOneOverR singular_quad(order, q_point, false);
376 * // This will produce the integral of f(x)/R
377 * for(unsigned int i=0; i<singular_quad.size(); ++i)
378 * integral += f(singular_quad.point(i))*singular_quad.weight(i);
379 *
380 * // And the same here
381 * QGaussOneOverR singular_quad_noR(order, q_point, true);
382 *
383 * // This also will produce the integral of f(x)/R, but 1/R has to
384 * // be specified.
385 * for(unsigned int i=0; i<singular_quad.size(); ++i) {
386 * double R = (singular_quad_noR.point(i)-cell->vertex(vertex_id)).norm();
387 * integral += f(singular_quad_noR.point(i))*singular_quad_noR.weight(i)/R;
388 * }
389 * @endcode
390 */
391 QGaussOneOverR(const unsigned int n,
392 const Point<dim> &singularity,
393 const bool factor_out_singular_weight = false);
394 /**
395 * The constructor takes three arguments: the order of the Gauss formula,
396 * the index of the vertex where the singularity is located, and whether we
397 * include the weighting singular function inside the quadrature, or we
398 * leave it in the user function to be integrated. Notice that this is a
399 * specialized version of the previous constructor which works only for the
400 * vertices of the quadrilateral.
401 *
402 * Traditionally, quadrature formulas include their weighting function, and
403 * the last argument is set to false by default. There are cases, however,
404 * where this is undesirable (for example when you only know that your
405 * singularity has the same order of 1/R, but cannot be written exactly in
406 * this way).
407 *
408 * In other words, you can use this function in either of the following way,
409 * obtaining the same result:
410 *
411 * @code
412 * QGaussOneOverR singular_quad(order, vertex_id, false);
413 * // This will produce the integral of f(x)/R
414 * for(unsigned int i=0; i<singular_quad.size(); ++i)
415 * integral += f(singular_quad.point(i))*singular_quad.weight(i);
416 *
417 * // And the same here
418 * QGaussOneOverR singular_quad_noR(order, vertex_id, true);
419 *
420 * // This also will produce the integral of f(x)/R, but 1/R has to
421 * // be specified.
422 * for(unsigned int i=0; i<singular_quad.size(); ++i) {
423 * double R = (singular_quad_noR.point(i)-cell->vertex(vertex_id)).norm();
424 * integral += f(singular_quad_noR.point(i))*singular_quad_noR.weight(i)/R;
425 * }
426 * @endcode
427 */
428 QGaussOneOverR(const unsigned int n,
429 const unsigned int vertex_index,
430 const bool factor_out_singular_weight = false);
431
432 private:
433 /**
434 * Given a quadrature point and a degree n, this function returns the size
435 * of the singular quadrature rule, considering whether the point is inside
436 * the cell, on an edge of the cell, or on a corner of the cell.
437 */
438 static unsigned int
439 quad_size(const Point<dim> &singularity, const unsigned int n);
440 };
441
442
443
444 /**
445 * Sorted Quadrature. Given an arbitrary quadrature formula, this class
446 * generates a quadrature formula where the quadrature points are ordered
447 * according the weights, from those with smaller corresponding weight, to
448 * those with higher corresponding weights. This might be necessary, for
449 * example, when integrating high order polynomials, since in these cases you
450 * might sum very big numbers with very small numbers, and summation is not
451 * stable if the numbers to sum are not close to each other.
452 */
453 template <int dim>
454 class QSorted : public Quadrature<dim>
455 {
456 public:
457 /**
458 * The constructor takes an arbitrary quadrature formula @p quad and sorts
459 * its points and weights according to ascending weights.
460 */
461 QSorted(const Quadrature<dim> &quad);
462
463 private:
464 /**
465 * A rule for std::sort to reorder pairs of points and weights.
466 * @p a and @p b are indices into the weights array and the result will
467 * be determined by comparing the weights.
468 */
469 bool
470 compare_weights(const unsigned int a, const unsigned int b) const;
471 };
472
473 /**
474 * Telles quadrature of arbitrary order.
475 *
476 * The coefficients of these quadrature rules are computed using a non linear
477 * change of variables starting from a Gauss-Legendre quadrature formula. This
478 * is done using a cubic polynomial, $n = a x^3 + b x^2 + c x + d$ in order to
479 * integrate a singular integral, with singularity at a given point x_0.
480 *
481 * We start from a Gauss Quadrature Formula with arbitrary function. Then we
482 * apply the cubic variable change. In the paper, J.C.F.Telles:A Self-Adaptive
483 * Co-ordinate Transformation For Efficient Numerical Evaluation of General
484 * Boundary Element Integrals. International Journal for Numerical Methods in
485 * Engineering, vol 24, pages 959–973. year 1987, the author applies the
486 * transformation on the reference cell $[-1, 1]$ getting
487 * @f{align*}{
488 * n(1) &= 1, \\ n(-1) &= -1, \\ \frac{dn}{dx} &= 0 \text{ at }
489 * x = x_0, \\ \frac{d^2n}{dx^2} &= 0 \text{ at } x = x_0
490 * @f}
491 * We get
492 * @f{align*}{
493 * a &= \frac{1}{q}, \\
494 * b &= -3 \frac{\bar{\Gamma}}{q}, \\
495 * c &= 3 \frac{\bar{\Gamma}}{q}, \\
496 * d &= -b,
497 * @f}
498 * with
499 * @f{align*}{
500 * \eta^{*} &= \bar{\eta}^2 - 1, \\
501 * \bar{\Gamma} &= \sqrt[3]{\bar{\eta} \eta^{*} + |\eta^{*} | }
502 * + \sqrt[3]{ \bar{\eta} \eta^{*} - |\eta^{*} | }
503 * + \bar{\eta}, \\
504 * q &= (\Gamma-\bar{\Gamma})^3 + \bar{\Gamma}
505 * \frac{\bar{\Gamma}^2+3}{1+3\bar{\Gamma}^2}
506 * @f}
507 * Since the library assumes $[0,1]$ as reference interval, we will map these
508 * values on the proper reference interval in the implementation.
509 *
510 * This variable change can be used to integrate singular integrals. One
511 * example is $f(x)/|x-x_0|$ on the reference interval $[0,1]$, where $x_0$ is
512 * given at construction time, and is the location of the singularity $x_0$,
513 * and $f(x)$ is a smooth non singular function.
514 *
515 * Singular quadrature formula are rather expensive, nevertheless Telles'
516 * quadrature formula are much easier to compute with respect to other
517 * singular integration techniques as Lachat-Watson.
518 *
519 * We have implemented the case for $dim = 1$. When we deal the case $dim >1$
520 * we have computed the quadrature formula has a tensorial product of one
521 * dimensional Telles' quadrature formulas considering the different
522 * components of the singularity.
523 *
524 * The weights and functions for Gauss Legendre formula have been tabulated up
525 * to order 12.
526 */
527 template <int dim>
528 class QTelles : public Quadrature<dim>
529 {
530 public:
531 /**
532 * A constructor that takes a quadrature formula and a singular point as
533 * argument. The quadrature formula will be mapped using Telles' rule. Make
534 * sure that the order of the quadrature rule is appropriate for the
535 * singularity in question.
536 */
537 QTelles(const Quadrature<1> &base_quad, const Point<dim> &singularity);
538 /**
539 * A variant of above constructor that takes as parameters the order @p n
540 * and location of a singularity. A Gauss Legendre quadrature of order n
541 * will be used
542 */
543 QTelles(const unsigned int n, const Point<dim> &singularity);
544 };
545
546 /**
547 * Gauss-Chebyshev quadrature rules integrate the weighted product
548 * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$.
549 * The nodes and weights are known analytically, and are exact for monomials
550 * up to the order $2n-1$, where $n$ is the number of quadrature points. Here
551 * we rescale the quadrature formula so that it is defined on the interval
552 * $[0,1]$ instead of $[-1,1]$. So the quadrature formulas integrate exactly
553 * the integral $\int_0^1 f(x) w(x) dx$ with the weight: $w(x) =
554 * 1/\sqrt{x(1-x)}$. For details see: M. Abramowitz & I.A. Stegun: Handbook of
555 * Mathematical Functions, par. 25.4.38
556 */
557 template <int dim>
558 class QGaussChebyshev : public Quadrature<dim>
559 {
560 public:
561 /// Generate a formula with <tt>n</tt> quadrature points
562 QGaussChebyshev(const unsigned int n);
563 };
564
565
566 /**
567 * Gauss-Radau-Chebyshev quadrature rules integrate the weighted product
568 * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$
569 * with the additional constraint that a quadrature point lies at one of the
570 * two extrema of the interval. The nodes and weights are known analytically,
571 * and are exact for monomials up to the order $2n-2$, where $n$ is the number
572 * of quadrature points. Here we rescale the quadrature formula so that it is
573 * defined on the interval $[0,1]$ instead of $[-1,1]$. So the quadrature
574 * formulas integrate exactly the integral $\int_0^1 f(x) w(x) dx$ with the
575 * weight: $w(x) = 1/\sqrt{x(1-x)}$. By default the quadrature is constructed
576 * with the left endpoint as quadrature node, but the quadrature node can be
577 * imposed at the right endpoint through the variable ep that can assume the
578 * values left or right.
579 */
580 template <int dim>
581 class QGaussRadauChebyshev : public Quadrature<dim>
582 {
583 public:
584 /**
585 * EndPoint is used to specify which of the two endpoints of the unit interval
586 * is used also as quadrature point.
587 */
588 enum EndPoint
589 {
590 /**
591 * Left end point.
592 */
593 left,
594 /**
595 * Right end point.
596 */
597 right
598 };
599 /// Generate a formula with <tt>n</tt> quadrature points
600 QGaussRadauChebyshev(
601 const unsigned int n,
602 const EndPoint end_point = QGaussRadauChebyshev::EndPoint::left);
603
604 /**
605 * Move constructor.
606 */
607 QGaussRadauChebyshev(QGaussRadauChebyshev<dim> &&) noexcept = default;
608
609 private:
610 const EndPoint end_point;
611 };
612
613 /**
614 * Gauss-Lobatto-Chebyshev quadrature rules integrate the weighted product
615 * $\int_{-1}^1 f(x) w(x) dx$ with weight given by: $w(x) = 1/\sqrt{1-x^2}$,
616 * with the additional constraint that two of the quadrature points are
617 * located at the endpoints of the quadrature interval. The nodes and weights
618 * are known analytically, and are exact for monomials up to the order $2n-3$,
619 * where $n$ is the number of quadrature points. Here we rescale the
620 * quadrature formula so that it is defined on the interval $[0,1]$ instead of
621 * $[-1,1]$. So the quadrature formulas integrate exactly the integral
622 * $\int_0^1 f(x) w(x) dx$ with the weight: $w(x) = 1/\sqrt{x(1-x)}$. For
623 * details see: M. Abramowitz & I.A. Stegun: Handbook of Mathematical
624 * Functions, par. 25.4.40
625 */
626 template <int dim>
627 class QGaussLobattoChebyshev : public Quadrature<dim>
628 {
629 public:
630 /// Generate a formula with <tt>n</tt> quadrature points
631 QGaussLobattoChebyshev(const unsigned int n);
632 };
633
634 /**
635 * Given an arbitrary quadrature formula, return one that chops the quadrature
636 * points above the hyper-plane defined by $\sum_i x_i = 1$. In other words,
637 * it extracts those quadrature points from the base formula that satisfy
638 * $\sum_i (\mathbf x_q)_i \le 1+10^{-12}$."
639 *
640 * In general the resulting quadrature is not very useful, unless the
641 * quadrature you started from has been constructed specifically to integrate
642 * over triangles or tetrahedra. This class only ensures that the resulting
643 * quadrature formula only has quadrature points in the reference simplex or on
644 * its boundary.
645 *
646 * No transformation is applied to the weights, and the weights referring to
647 * points that live outside the reference simplex are simply discarded.
648 * Because this leads to (or *may* lead to) a sum of quadrature weights that
649 * do not equal the area of the simplex, the resulting quadrature formula
650 * is not useful for actually computing integrals.
651 *
652 * The main use of this quadrature formula is not to chop tensor product
653 * quadratures. Ideally you should pass to this class a quadrature formula
654 * constructed directly using points and weights in the reference simplex,
655 * capable of integrating on triangles or tetrahedra.
656 *
657 * For finite elements based on quadrilaterals and hexahedra, a QSimplex
658 * quadrature formula is not very useful on its own. This class is typically
659 * used in conjunction with other classes, like QSplit, to patch the reference
660 * element using several QSimplex quadrature formulas.
661 *
662 * Such quadrature formulas are useful to integrate functions with
663 * singularities at certain points, or functions that present jumps along a
664 * co-dimension one surface inside the reference element, like in the extended
665 * finite element method (XFEM).
666 */
667 template <int dim>
668 class QSimplex : public Quadrature<dim>
669 {
670 public:
671 /**
672 * Construct a quadrature that only contains the points that are in the lower
673 * left reference simplex.
674 *
675 * @param[in] quad The input quadrature.
676 */
677 QSimplex(const Quadrature<dim> &quad);
678
679 /**
680 *
681 * Return an affine transformation of this quadrature, that can be used to
682 * integrate on the simplex identified by `vertices`.
683 *
684 * Both the quadrature point locations and the weights are transformed, so
685 * that you can effectively use the resulting quadrature to integrate on the
686 * simplex.
687 *
688 * The transformation is defined as
689 * \f[
690 * x = v_0 + B \hat x
691 * \f]
692 * where the matrix $B$ is given by $B_{ij} = v[j][i]-v[0][i]$.
693 *
694 * The weights are scaled with the absolute value of the determinant of $B$,
695 * that is $J \dealcoloneq |\text{det}(B)|$. If $J$ is zero, an empty
696 * quadrature is returned. This may happen, in two dimensions, if the three
697 * vertices are aligned, or in three dimensions if the four vertices are on
698 * the same plane. The present function works also in the codimension one and
699 * codimension two case. For instance, when `dim=2` and `spacedim=3`, we can
700 * map the quadrature points so that they live on the physical triangle
701 * embedded in the three dimensional space. In such a case, the matrix $B$ is
702 * not square anymore.
703 *
704 * @param[in] vertices The vertices of the simplex you wish to integrate on
705 * @return A quadrature object that can be used to integrate on the simplex
706 */
707 template <int spacedim = dim>
708 Quadrature<spacedim>
709 compute_affine_transformation(
710 const std::array<Point<spacedim>, dim + 1> &vertices) const;
711
712 /**
713 * Given a collection of simplices, this function creates a global
714 * quadrature rule on the area covered by the simplices, by mapping the
715 * current quadrature on each simplex. A simplex is identified by its
716 * vertices, which are stored into an array of Points. Hence, this function
717 * can provide quadrature rules on polygons (or polyhedra), as they can be
718 * split into simplices.
719 *
720 *
721 * @param simplices A std::vector where each entry is an array of `dim+1` points, which identifies the vertices of a simplex.
722 * @return A Quadrature object on the cell.
723 */
724 template <int spacedim = dim>
725 Quadrature<spacedim>
726 mapped_quadrature(
727 const std::vector<std::array<Point<spacedim>, dim + 1>> &simplices) const;
728 };
729
730 /**
731 * A quadrature that implements a polar transformation from a square to a
732 * triangle to integrate singularities in the origin of the reference simplex.
733 * The quadrature is obtained through the following polar transformation:
734 *
735 * \f[
736 * \begin{pmatrix}
737 * x \\
738 * y
739 * \end{pmatrix}
740 * =
741 * \begin{pmatrix}
742 * \frac{\hat x}{\sin(\theta)+\cos(\theta)} cos(\theta) \\
743 * \frac{\hat x}{\sin(\theta)+\cos(\theta)} sin(\theta)
744 * \end{pmatrix}
745 * \qquad \theta \dealcoloneq \frac\pi 2 \hat y
746 * \f]
747 */
748 class QTrianglePolar : public QSimplex<2>
749 {
750 public:
751 /**
752 * Construct a QTrianglePolar quadrature, with different formulas in the
753 * radial and angular directions.
754 *
755 * @param radial_quadrature Radial quadrature
756 * @param angular_quadrature Angular quadrature
757 */
758 QTrianglePolar(const Quadrature<1> &radial_quadrature,
759 const Quadrature<1> &angular_quadrature);
760
761 /**
762 * Call the other constructor, with QGauss<1>(n) for both radial and
763 * angular quadrature.
764 *
765 * @param n Order of QGauss quadrature
766 */
767 QTrianglePolar(const unsigned int n);
768 };
769
770 /**
771 * A quadrature that implements the Duffy transformation from a square to a
772 * triangle to integrate singularities in the origin of the reference
773 * simplex.
774 *
775 * The Duffy transformation is defined as
776 * \f[
777 * \begin{pmatrix}
778 * x\\
779 * y
780 * \end{pmatrix}
781 * =
782 * \begin{pmatrix}
783 * \hat x^\beta (1-\hat y)\\
784 * \hat x^\beta \hat y
785 * \end{pmatrix}
786 * \f]
787 *
788 * with determinant of the Jacobian equal to $J= \beta \hat x^{2\beta-1}$.
789 * Such transformation maps the reference square $[0,1]\times[0,1]$ to the
790 * reference simplex, by collapsing the left side of the square and squeezing
791 * quadrature points towards the origin, and then shearing the resulting
792 * triangle to the reference one. This transformation shows good convergence
793 * properties when $\beta = 1$ with singularities of order $1/R$ in the origin,
794 * but different $\beta$ values can be selected to increase convergence and/or
795 * accuracy when higher order Gauss rules are used (see "Generalized Duffy
796 * transformation for integrating vertex singularities", S. E. Mousavi, N.
797 * Sukumar, Computational Mechanics 2009).
798 *
799 * When $\beta = 1$, this transformation is also known as the Lachat-Watson
800 * transformation.
801 */
802 class QDuffy : public QSimplex<2>
803 {
804 public:
805 /**
806 * Constructor that allows the specification of different quadrature rules
807 * along the "radial" and "angular" directions.
808 *
809 * Since this quadrature is not based on a Polar change of coordinates, it
810 * is not fully proper to talk about radial and angular directions. However,
811 * the effect of the Duffy transformation is similar to a polar change
812 * of coordinates, since the resulting quadrature points are aligned radially
813 * with respect to the singularity.
814 *
815 * @param radial_quadrature Base quadrature to use in the radial direction
816 * @param angular_quadrature Base quadrature to use in the angular direction
817 * @param beta Exponent used in the transformation
818 */
819 QDuffy(const Quadrature<1> &radial_quadrature,
820 const Quadrature<1> &angular_quadrature,
821 const double beta = 1.0);
822
823 /**
824 * Call the above constructor with QGauss<1>(n) quadrature formulas for
825 * both the radial and angular quadratures.
826 *
827 * @param n Order of QGauss quadrature
828 * @param beta Exponent used in the transformation
829 */
830 QDuffy(const unsigned int n, const double beta);
831 };
832
833 /**
834 * A quadrature to use when the cell should be split into subregions to
835 * integrate using one or more base quadratures.
836 */
837 template <int dim>
838 class QSplit : public Quadrature<dim>
839 {
840 public:
841 /**
842 * Construct a quadrature formula by splitting the reference hyper cube into
843 * the minimum number of simplices that have vertex zero coinciding with
844 * @p split_point, and patch together affine transformations of the @p base
845 * quadrature. The point @p split_point should be in the reference element,
846 * and an exception is thrown if this is not the case.
847 *
848 * In two dimensions, the resulting quadrature formula will be composed of
849 * two, three, or four triangular quadrature formulas if @p split_point
850 * coincides with one of the vertices, if it lies on one of the edges, or if
851 * it is internal to the reference element respectively.
852 *
853 * The same is true for the three dimensional case, with six, eight, ten, or
854 * twelve tetrahedral quadrature formulas if @p split_point coincides with one
855 * of the vertices, if it lies on one of the edges, on one of the faces, or
856 * if it is internal to the reference element respectively.
857 *
858 * The resulting quadrature can be used, for example, to integrate functions
859 * with integrable singularities at the split point, provided that you select
860 * as base quadrature one that can integrate singular points on vertex zero
861 * of the reference simplex.
862 *
863 * An example usage in dimension two is given by:
864 * @code
865 * const unsigned int order = 5;
866 * QSplit<2> quad(QTrianglePolar(order), Point<2>(.3,.4));
867 * @endcode
868 *
869 * The resulting quadrature will look like the following:
870 * @image html split_quadrature.png ""
871 *
872 * @param base Base QSimplex quadrature to use
873 * @param split_point Where to split the hyper cube
874 */
875 QSplit(const QSimplex<dim> &base, const Point<dim> &split_point);
876 };
877
878 /**
879 * Integration rule for simplex entities.
880 *
881 * Users specify a number `n_points_1d` as an indication of what polynomial
882 * degree to be integrated exactly, similarly to the number of points in a
883 * QGauss quadrature object, even though the present quadrature formula is not
884 * a tensor product. The given value is translated for n_points_1d=1,2,3,4 to
885 * following number of quadrature points for 2d and 3d:
886 * - 2d: 1, 4, 7, 15
887 * - 3d: 1, 6, 14, 35
888 *
889 * For 1d, the quadrature rule degenerates to a
890 * `dealii::QGauss<1>(n_points_1d)`.
891 *
892 * @note The quadrature rules implemented by this class come from a variety of
893 * sources, but all of them have positive quadrature weights.
894 *
895 * @note Several of the schemes implemented by this class are not symmetric with
896 * respect to the vertices - i.e., the locations of the mapped quadrature points
897 * depends on the numbering of the cell vertices. If you need rules that are
898 * independent of the vertex numbering then use QWitherdenVincentSimplex.
899 *
900 * Also see
901 * @ref simplex "Simplex support".
902 */
903 template <int dim>
904 class QGaussSimplex : public QSimplex<dim>
905 {
906 public:
907 /**
908 * Constructor taking the number of quadrature points in 1d direction
909 * @p n_points_1d.
910 */
911 explicit QGaussSimplex(const unsigned int n_points_1D);
912 };
913
914 /**
915 * Witherden-Vincent rules for simplex entities.
916 *
917 * Like QGauss, users should specify a number `n_points_1d` as an indication
918 * of what polynomial degree to be integrated exactly (e.g., for $n$ points,
919 * the rule can integrate polynomials of degree $2 n - 1$ exactly).
920 * Additionally, since these rules were derived for simplices, there are
921 * also even-ordered rules (i.e., they integrate polynomials of degree $2 n$)
922 * available which do not have analogous 1d rules.
923 *
924 * The given value for n_points_1d = 1, 2, 3, 4, 5, 6, 7 (where the last two are
925 * only implemented in 2d) results in the following number of quadrature points
926 * in 2d and 3d:
927 * - 2d: odd (default): 1, 6, 7, 15, 19, 28, 37
928 * - 2d: even: 3, 6, 12, 16, 25, 33, 42
929 * - 3d: odd (default): 1, 8, 14, 35, 59
930 * - 3d: even: 4, 14, 24, 46, 81
931 *
932 * For 1d, the quadrature rule degenerates to a
933 * `dealii::QGauss<1>(n_points_1d)` and @p use_odd_order is ignored.
934 *
935 * These rules match the ones listed for Witherden-Vincent in the quadpy
936 * @cite quadpy library and were first described in
937 * @cite witherden2015identification.
938 *
939 * @note Some rules (2d 2 odd and 3d 2 even) do not yet exist and instead a
940 * higher-order rule is used in their place.
941 *
942 * Also see
943 * @ref simplex "Simplex support".
944 */
945 template <int dim>
946 class QWitherdenVincentSimplex : public QSimplex<dim>
947 {
948 public:
949 /**
950 * Constructor taking the equivalent number of quadrature points in 1d
951 * @p n_points_1d and boolean indicating whether the rule should be order
952 * $2 n - 1$ or $2 n$: see the general documentation of this class for more
953 * information.
954 */
955 explicit QWitherdenVincentSimplex(const unsigned int n_points_1D,
956 const bool use_odd_order = true);
957 };
958
959 /**
960 * Iterated quadrature for simplices. Since simplex cannot be described as
961 * tensor products the base quadrature has equal dimension.
962 *
963 * At the moment @p n_copies must be a power of 2 due to the complexity of
964 * subdividing a simplex.
965 */
966 template <int dim>
967 class QIteratedSimplex : public Quadrature<dim>
968 {
969 public:
970 QIteratedSimplex(const Quadrature<dim> &base_quadrature,
971 const unsigned int n_copies);
972 };
973
974 /**
975 * Integration rule for wedge entities.
976 */
977 template <int dim>
978 class QGaussWedge : public Quadrature<dim>
979 {
980 public:
981 /**
982 * Users specify a number `n_points_1d` as an indication of what polynomial
983 * degree to be integrated exactly. For details, see the comments of
984 * QGaussSimplex.
985 */
986 explicit QGaussWedge(const unsigned int n_points_1D);
987 };
988
989 /**
990 * Integration rule for pyramid entities.
991 */
992 template <int dim>
993 class QGaussPyramid : public Quadrature<dim>
994 {
995 public:
996 /**
997 * Users specify a number `n_points_1d` as an indication of what polynomial
998 * degree to be integrated exactly. For details, see the comments of
999 * QGaussSimplex.
1000 */
1001 explicit QGaussPyramid(const unsigned int n_points_1D);
1002 };
1003
1004 /** @} */
1005
1006 /* -------------- declaration of explicit specializations ------------- */
1007
1008 #ifndef DOXYGEN
1009 template <>
1010 QGauss<1>::QGauss(const unsigned int n);
1011 template <>
1012 QGaussRadau<1>::QGaussRadau(const unsigned int n,
1013 const QGaussRadau<1>::EndPoint end_point);
1014 template <>
1015 QGaussLobatto<1>::QGaussLobatto(const unsigned int n);
1016
1017 template <>
1018 std::vector<double>
1019 QGaussLog<1>::get_quadrature_points(const unsigned int);
1020 template <>
1021 std::vector<double>
1022 QGaussLog<1>::get_quadrature_weights(const unsigned int);
1023
1024 template <>
1025 QMidpoint<1>::QMidpoint();
1026 template <>
1027 QTrapezoid<1>::QTrapezoid();
1028 template <>
1029 QSimpson<1>::QSimpson();
1030 template <>
1031 QMilne<1>::QMilne();
1032 template <>
1033 QWeddle<1>::QWeddle();
1034 template <>
1035 QGaussLog<1>::QGaussLog(const unsigned int n, const bool revert);
1036 template <>
1037 QGaussLogR<1>::QGaussLogR(const unsigned int n,
1038 const Point<1> &x0,
1039 const double alpha,
1040 const bool flag);
1041 template <>
1042 QGaussOneOverR<2>::QGaussOneOverR(const unsigned int n,
1043 const unsigned int index,
1044 const bool flag);
1045 template <>
1046 QTelles<1>::QTelles(const Quadrature<1> &base_quad,
1047 const Point<1> &singularity);
1048 #endif // DOXYGEN
1049
1050
1051
1052 DEAL_II_NAMESPACE_CLOSE
1053 #endif