From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 27 Oct 2020 17:21:32 +0000 (-0600)
Subject: Better document a constructor of FE_Q.
X-Git-Tag: v9.3.0-rc1~963^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9812ca491825b37bcaf490e6b9cb4c1f72bae247;p=dealii.git

Better document a constructor of FE_Q.
---

diff --git a/include/deal.II/fe/fe_q.h b/include/deal.II/fe/fe_q.h
index 34ebe53e6c..967c26a902 100644
--- a/include/deal.II/fe/fe_q.h
+++ b/include/deal.II/fe/fe_q.h
@@ -564,6 +564,34 @@ public:
    * constructor that specifies the polynomial degree only. For selecting
    * equidistant nodes at <tt>fe_degree > 2</tt>, construct
    * <tt>FE_Q<dim>(QIterated<1>(QTrapezoid<1>(),fe_degree))</tt>.
+   *
+   * The *space* created by this constructor is the
+   * same as if you had called `FE_Q<dim>(points.size()-1)`, but what *is*
+   * different are the basis functions of this space. This is useful in
+   * contexts where one wants to achieve certain properties of the matrices
+   * that result from integrating bilinear forms of these shape functions.
+   * For example, when computing the mass matrix on cell $K$,
+   * @f[
+   *   M_{ij}^K = \int_K \varphi_i(\mathbf x) \varphi_j(\mathbf x) \; dx
+   * @f]
+   * one generally applies a quadrature formula and approximates the real
+   * mass matrix by the following:
+   * @f[
+   *   M_{ij}^K = \sum_q \varphi_i(\mathbf x_q) \varphi_j(\mathbf x_q) w_q,
+   * @f]
+   * where the locations of the quadrature points $\mathbf x_q$ and the
+   * weights $w_q$ depend on the cell $K$. If the quadrature formula used
+   * to define these points $\mathbf x_q$ is the same as the one passed
+   * to this constructor (or, in higher dimensions, is generated by a
+   * tensor product of the one used to the constructor), then
+   * $\varphi_i(\mathbf x_q) = \delta_{iq}$, and the matrix reduces to
+   * @f[
+   *   M_{ij}^K = \sum_q \delta_{iq} \delta_{jq} w_q = \delta_{ij} w_i,
+   * @f]
+   * i.e., a diagonal matrix with the weights $w_i$ on the diagonal. Such
+   * constructions are quite useful when using explicit time stepping
+   * methods because, for example, one then only has to invert a diagonal
+   * mass matrix in each time step when solving the linear system.
    */
   FE_Q(const Quadrature<1> &points);