// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2001 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_fe_q_h #define dealii_fe_q_h #include #include #include DEAL_II_NAMESPACE_OPEN /** * @addtogroup fe * @{ */ /** * This class provides an implementation of the scalar Lagrange $Q_p$ finite * element on hypercube (line segments, quadrilaterals, or hexahedra) cells that * yields the * finite element space of continuous, piecewise polynomials of degree @p p in * each coordinate direction. This class is realized using tensor product * polynomials based on 1d Lagrange polynomials with equidistant (degree up to * 2), Gauss-Lobatto (starting from degree 3), or given support points. The * corresponding element on simplex (triangular or tetrahedral) cells is * FE_SimplexP, whereas on other cell kinds it is FE_WedgeP and FE_PyramidP. * * The standard constructor of this class takes the degree @p p of this finite * element. Alternatively, it can take a quadrature formula @p points defining * the support points of the Lagrange interpolation in one coordinate * direction. * * For more information about the spacedim template parameter check * the documentation of FiniteElement or the one of Triangulation. * *

Implementation

* * The constructor creates a TensorProductPolynomials object that includes the * tensor product of @p LagrangeEquidistant polynomials of degree @p p. This * @p TensorProductPolynomials object provides all values and derivatives of * the shape functions. In case a quadrature rule is given, the constructor * creates a TensorProductPolynomials object that includes the tensor product * of @p Lagrange polynomials with the support points from @p points. * * Furthermore the constructor fills the @p interface_constraints, the @p * prolongation (embedding) and the @p restriction matrices. These are * implemented only up to a certain degree and may not be available for very * high polynomial degree. * *

Unit support point distribution and conditioning of interpolation

* * When constructing an FE_Q element at polynomial degrees one or two, * equidistant support points at 0 and 1 (linear case) or 0, 0.5, and 1 * (quadratic case) are used. The unit support or nodal points * xi are those points where the jth Lagrange * polynomial satisfies the $\delta_{ij}$ property, i.e., where one polynomial * is one and all the others are zero. For higher polynomial degrees, the * support points are non-equidistant by default, and chosen to be the support * points of the (degree+1)-order Gauss-Lobatto quadrature rule. This * point distribution yields well-conditioned Lagrange interpolation at * arbitrary polynomial degrees. By contrast, polynomials based on equidistant * points get increasingly ill-conditioned as the polynomial degree * increases. In interpolation, this effect is known as the Runge * phenomenon. For Galerkin methods, the Runge phenomenon is typically not * visible in the solution quality but rather in the condition number of the * associated system matrices. For example, the elemental @ref GlossMassMatrix "mass matrix" of * equidistant points at degree 10 has condition number 2.6e6, whereas the * condition number for Gauss-Lobatto points is around 400. * * The Gauss-Lobatto points in 1d include the end points 0 and +1 of the unit * interval. The interior points are shifted towards the end points, which * gives a denser point distribution close to the element boundary. * * If combined with Gauss-Lobatto quadrature, FE_Q based on the default * support points gives diagonal mass matrices. This case is demonstrated in * step-48. However, this element can be combined with arbitrary quadrature * rules through the usual FEValues approach, including full Gauss * quadrature. In the general case, the mass matrix is non-diagonal. * *

Numbering of the degrees of freedom (DoFs)

* * The original ordering of the shape functions represented by the * TensorProductPolynomials is a tensor product numbering. However, the shape * functions on a cell are renumbered beginning with the shape functions whose * support points are at the vertices, then on the line, on the quads, and * finally (for 3d) on the hexes. To be explicit, these numberings are listed * in the following: * *

Q1 elements

*
    *
  • 1d case: * @verbatim * 0-------1 * @endverbatim * *
  • 2d case: * @verbatim * 2-------3 * | | * | | * | | * 0-------1 * @endverbatim * *
  • 3d case: * @verbatim * 6-------7 6-------7 * /| | / /| * / | | / / | * / | | / / | * 4 | | 4-------5 | * | 2-------3 | | 3 * | / / | | / * | / / | | / * |/ / | |/ * 0-------1 0-------1 * @endverbatim * * The respective coordinate values of the support points of the shape * functions are as follows: *
      *
    • Shape function 0: [0, 0, 0]; *
    • Shape function 1: [1, 0, 0]; *
    • Shape function 2: [0, 1, 0]; *
    • Shape function 3: [1, 1, 0]; *
    • Shape function 4: [0, 0, 1]; *
    • Shape function 5: [1, 0, 1]; *
    • Shape function 6: [0, 1, 1]; *
    • Shape function 7: [1, 1, 1]; *
    *
* * In 2d, these shape functions look as follows: * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0001.png *
$Q_1$ element, shape function 0 $Q_1$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0003.png *
$Q_1$ element, shape function 2 $Q_1$ element, shape function 3
* * *

Q2 elements

*
    *
  • 1d case: * @verbatim * 0---2---1 * @endverbatim * *
  • 2d case: * @verbatim * 2---7---3 * | | * 4 8 5 * | | * 0---6---1 * @endverbatim * *
  • 3d case: * @verbatim * 6--15---7 6--15---7 * /| | / /| * 12 | 19 12 1319 * / 18 | / / | * 4 | | 4---14--5 | * | 2---11--3 | | 3 * | / / | 17 / * 16 8 9 16 | 9 * |/ / | |/ * 0---10--1 0---10--1 * * *-------* *-------* * /| | / /| * / | 23 | / 25 / | * / | | / / | * * | | *-------* | * |20 *-------* | |21 * * | / / | 22 | / * | / 24 / | | / * |/ / | |/ * *-------* *-------* * @endverbatim * The center node has number 26. * * The respective coordinate values of the support points of the shape * functions are as follows: *
      *
    • Shape function 0: [0, 0, 0]; *
    • Shape function 1: [1, 0, 0]; *
    • Shape function 2: [0, 1, 0]; *
    • Shape function 3: [1, 1, 0]; *
    • Shape function 4: [0, 0, 1]; *
    • Shape function 5: [1, 0, 1]; *
    • Shape function 6: [0, 1, 1]; *
    • Shape function 7: [1, 1, 1]; *
    • Shape function 8: [0, 1/2, 0]; *
    • Shape function 9: [1, 1/2, 0]; *
    • Shape function 10: [1/2, 0, 0]; *
    • Shape function 11: [1/2, 1, 0]; *
    • Shape function 12: [0, 1/2, 1]; *
    • Shape function 13: [1, 1/2, 1]; *
    • Shape function 14: [1/2, 0, 1]; *
    • Shape function 15: [1/2, 1, 1]; *
    • Shape function 16: [0, 0, 1/2]; *
    • Shape function 17: [1, 0, 1/2]; *
    • Shape function 18: [0, 1, 1/2]; *
    • Shape function 19: [1, 1, 1/2]; *
    • Shape function 20: [0, 1/2, 1/2]; *
    • Shape function 21: [1, 1/2, 1/2]; *
    • Shape function 22: [1/2, 0, 1/2]; *
    • Shape function 23: [1/2, 1, 1/2]; *
    • Shape function 24: [1/2, 1/2, 0]; *
    • Shape function 25: [1/2, 1/2, 1]; *
    • Shape function 26: [1/2, 1/2, 1/2]; *
    *
* * * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0001.png *
$Q_2$ element, shape function 0 $Q_2$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0003.png *
$Q_2$ element, shape function 2 $Q_2$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0005.png *
$Q_2$ element, shape function 4 $Q_2$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0007.png *
$Q_2$ element, shape function 6 $Q_2$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0008.png *
$Q_2$ element, * shape function 8
* * *

Q3 elements

*
    *
  • 1d case: * @verbatim * 0--2--3--1 * @endverbatim * *
  • 2d case: * @verbatim * 2--10-11-3 * | | * 5 14 15 7 * | | * 4 12 13 6 * | | * 0--8--9--1 * @endverbatim *
* * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0001.png *
$Q_3$ element, shape function 0 $Q_3$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0003.png *
$Q_3$ element, shape function 2 $Q_3$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0005.png *
$Q_3$ element, shape function 4 $Q_3$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0007.png *
$Q_3$ element, shape function 6 $Q_3$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0008.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0009.png *
$Q_3$ element, shape function 8 $Q_3$ element, shape function 9
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0010.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0011.png *
$Q_3$ element, shape function 10 $Q_3$ element, shape function 11
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0012.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0013.png *
$Q_3$ element, shape function 12 $Q_3$ element, shape function 13
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0014.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0015.png *
$Q_3$ element, shape function 14 $Q_3$ element, shape function 15
* * *

Q4 elements

*
    *
  • 1d case: * @verbatim * 0--2--3--4--1 * @endverbatim * *
  • 2d case: * @verbatim * 2--13-14-15-3 * | | * 6 22 23 24 9 * | | * 5 19 20 21 8 * | | * 4 16 17 18 7 * | | * 0--10-11-12-1 * @endverbatim *
* * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0001.png *
$Q_4$ element, shape function 0 $Q_4$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0003.png *
$Q_4$ element, shape function 2 $Q_4$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0005.png *
$Q_4$ element, shape function 4 $Q_4$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0007.png *
$Q_4$ element, shape function 6 $Q_4$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0008.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0009.png *
$Q_4$ element, shape function 8 $Q_4$ element, shape function 9
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0010.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0011.png *
$Q_4$ element, shape function 10 $Q_4$ element, shape function 11
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0012.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0013.png *
$Q_4$ element, shape function 12 $Q_4$ element, shape function 13
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0014.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0015.png *
$Q_4$ element, shape function 14 $Q_4$ element, shape function 15
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0016.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0017.png *
$Q_4$ element, shape function 16 $Q_4$ element, shape function 17
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0018.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0019.png *
$Q_4$ element, shape function 18 $Q_4$ element, shape function 19
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0020.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0021.png *
$Q_4$ element, shape function 20 $Q_4$ element, shape function 21
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0022.png * * @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0023.png *
$Q_4$ element, shape function 22 $Q_4$ element, shape function 23
* @image html http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0024.png *
$Q_4$ element, * shape function 24
*/ template class FE_Q : public FE_Q_Base { public: /** * Constructor for tensor product polynomials of degree @p p based on * Gauss-Lobatto support (node) points. For polynomial degrees of one and * two, these are the usual equidistant points. */ FE_Q(const unsigned int p); /** * Constructor for tensor product polynomials with support points @p points * based on a one-dimensional quadrature formula. The degree of the finite * element is points.size()-1. Note that the first point has to be * 0 and the last one 1, to ensure that the resulting element is continuous. * As a consequence, only *certain* quadrature formulas make sense as * argument to this constructor. Specifically, constructing * FE_Q(QGaussLobatto<1>(fe_degree+1)) is equivalent to the * constructor that specifies the polynomial degree only. For selecting * equidistant nodes at fe_degree > 2, use * FE_Q(QIterated<1>(QTrapezoid<1>(),fe_degree)), though the * use of equidistant node points is known to lead to poorly conditioned * linear systems with poor interpolation properties for high polynomial * degrees (which is why the default uses the QGaussLobatto points). * * The *space* created by this constructor is the * same as if you had called `FE_Q(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 @ref GlossMassMatrix "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); /** * Return a string that uniquely identifies a finite element. This class * returns FE_Q(degree), with @p dim and @p degree replaced by * appropriate values. */ virtual std::string get_name() const override; virtual std::unique_ptr> clone() const override; /** * Implementation of the corresponding function in the FiniteElement * class. Since the current element is interpolatory, the nodal * values are exactly the support point values. Furthermore, since * the current element is scalar, the support point values need to * be vectors of length 1. */ virtual void convert_generalized_support_point_values_to_dof_values( const std::vector> &support_point_values, std::vector &nodal_values) const override; /** * @copydoc FiniteElement::compare_for_domination() */ virtual FiniteElementDomination::Domination compare_for_domination(const FiniteElement &fe_other, const unsigned int codim = 0) const override final; }; /** @} */ DEAL_II_NAMESPACE_CLOSE #endif