From d86f52c08ee1e1a020135da278387193bb799a8a Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sun, 19 Mar 2023 16:52:03 -0600 Subject: [PATCH] Update documentation of Quadrature. --- include/deal.II/base/quadrature.h | 42 ++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/include/deal.II/base/quadrature.h b/include/deal.II/base/quadrature.h index d1013e76b9..7388d36863 100644 --- a/include/deal.II/base/quadrature.h +++ b/include/deal.II/base/quadrature.h @@ -34,12 +34,27 @@ DEAL_II_NAMESPACE_OPEN */ /** - * Base class for quadrature formulae in arbitrary dimensions. This class - * stores quadrature points and weights in the coordinate system of + * Base class for quadrature formulae in arbitrary dimensions. + * [Quadrature](https://en.wikipedia.org/wiki/Numerical_integration) + * is a means to approximate an integral by evaluating the integrand + * at specific points $\mathbf x_q$ and summing the point values with + * specific weights $w_q$; that is, quadrature computes + * @f{align*}{ + * \int_K f(\mathbf x) \; dx + * \approx + * \sum_{q=0,\ldots,Q-1} f(\mathbf x_q) w_q. + * @f} + * + * This class stores quadrature points $\mathbf x_q$ and weights $w_q$ + * for concrete "quadrature formulas" when $K$ (the domain we integrate + * over) is a reference cell. That is, points and weights are expressed + * in the coordinate system of * a reference cell (see the ReferenceCell class) and as such serves to * represent quadrature points and weights on the unit line segment * $[0,1]$ in 1d, on the unit square or unit triangle in 2d, as well as * the unit tetrahedron, cube, pyramid, and wedge reference cells in 3d. + * Integration over concrete cells is done by coordinate transformation + * to the reference cell represented by the current class. * * There are a number of derived classes, denoting concrete integration * formulae. Their names are prefixed by Q. Refer to the list of @@ -74,15 +89,34 @@ DEAL_II_NAMESPACE_OPEN * in each space direction, but they are still only of (m+1)st order. * * - *

Implementation details

+ *

Tensor product quadrature

* - * Most integration formulae in more than one space dimension are tensor + * At least for hypercube reference cells (i.e., squares and cubes), + * most integration formulae in more than one space dimension are tensor * products of quadrature formulae in one space dimension, or more generally * the tensor product of a formula in (dim-1) dimensions and one in * one dimension. There is a special constructor to generate a quadrature * formula from two others. For example, the QGauss@ formulae include * Ndim quadrature points in dim dimensions, where * $N$ is the constructor parameter of QGauss. + * + * + *

Other uses of this class

+ * + * Quadrature objects are used in a number of places within deal.II where + * integration is performed, most notably via the FEValues and related classes. + * Some of these classes are also used in contexts where no integrals + * are involved, but where functions need to be evaluated at specific + * points, for example to evaluate the solution at individual points + * or to create graphical output. Examples are the implementation of + * VectorTools::point_value() and the DataOut and related classes (in + * particular in connection with the DataPostprocessor class). In + * such contexts, one often creates specific "Quadrature" objects in + * which the "quadrature points" are simply the points (in the coordinate + * system of the reference cell) at which one wants to evaluate the + * solution. In these kinds of cases, the weights stored by the current + * class are not used and the name "quadrature object" is interpreted + * as "list of evaluation points". */ template class Quadrature : public Subscriptor -- 2.39.5