Debian Codegraph @

include/deal.II/fe/fe_q_bubbles.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 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
16 #ifndef dealii_fe_q_bubbles_h
17 #define dealii_fe_q_bubbles_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/tensor_product_polynomials_bubbles.h>
22
23 #include <deal.II/fe/fe_q_base.h>
24
25 DEAL_II_NAMESPACE_OPEN
26
27
28 /**
29 * @addtogroup fe
30 * @{
31 */
32
33 /**
34 * Implementation of a scalar Lagrange finite element $Q_p^+$ that yields the
35 * finite element space of continuous, piecewise polynomials of degree @p p in
36 * each coordinate direction plus some (non-normalized) bubble enrichment space
37 * spanned by the additional shape function
38 * $\varphi_j(\mathbf x)
39 * = 2^{p-1}\left(x_j-\frac 12\right)^{p-1}
40 * \left[\prod_{i=0}^{dim-1}(x_i(1-x_i))\right]$.
41 * for $j=0,\ldots,dim-1$. If $p$ is one, then the first factor
42 * disappears and one receives the usual bubble function centered
43 * at the mid-point of the cell.
44 * Because these last shape functions have polynomial degree is $p+1$, the
45 * overall polynomial degree of the shape functions in the space described
46 * by this class is $p+1$.
47 *
48 * This class is realized using tensor product
49 * polynomials based on equidistant or given support points, in the same way as
50 * one can provide support points to the FE_Q class's constructors.
51 *
52 * For more information about the <tt>spacedim</tt> template parameter check
53 * the documentation of the FiniteElement class, or the one of Triangulation.
54 *
55 * Due to the fact that the enrichments are small almost everywhere for large
56 * $p$, the condition number for the mass and @ref GlossStiffnessMatrix "stiffness matrix" quickly
57 * increaseses with increasing $p$. Below you see a comparison with
58 * FE_Q(QGaussLobatto(p+1)) for dim=1.
59 *
60 * <p ALIGN="center">
61 * @image html fe_q_bubbles_conditioning.png
62 * </p>
63 *
64 * Therefore, this element should be used with care for $p>3$.
65 *
66 *
67 * <h3>Implementation</h3>
68 *
69 * The constructor creates a TensorProductPolynomials object that includes the
70 * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus
71 * the bubble enrichments. This @p TensorProductPolynomialsBubbles object
72 * provides all values and derivatives of the shape functions. In case a
73 * quadrature rule is given, the constructor creates a
74 * TensorProductPolynomialsBubbles object that includes the tensor product of
75 * @p Lagrange polynomials with the support points from @p points and the
76 * bubble enrichments as defined above.
77 *
78 * Furthermore the constructor fills the @p interface_constrains, the @p
79 * prolongation (embedding) and the @p restriction matrices.
80 *
81 *
82 * <h3>Numbering of the degrees of freedom (DoFs)</h3>
83 *
84 * The original ordering of the shape functions represented by the
85 * TensorProductPolynomialsBubbles is a tensor product numbering. However, the
86 * shape functions on a cell are renumbered beginning with the shape functions
87 * whose support points are at the vertices, then on the line, on the quads,
88 * and finally (for 3d) on the hexes. Finally, there are support points for
89 * the bubble enrichments in the middle of the cell.
90 */
91 template <int dim, int spacedim = dim>
92 class FE_Q_Bubbles : public FE_Q_Base<dim, spacedim>
93 {
94 public:
95 /**
96 * Constructor for tensor product polynomials of degree @p p plus bubble
97 * enrichments
98 */
99 FE_Q_Bubbles(const unsigned int p);
100
101 /**
102 * Constructor for tensor product polynomials with support points
103 * @p points plus bubble enrichments based on a one-dimensional
104 * quadrature formula. The degree of the finite element is then
105 * <tt>points.size()</tt>, the plus one compared to the
106 * corresponding case for the FE_Q class coming from the additional
107 * bubble function. See the documentation of the FE_Q constructors
108 * for more information.
109 *
110 * Note that the first point has to be 0
111 * and the last one 1.
112 */
113 FE_Q_Bubbles(const Quadrature<1> &points);
114
115 /**
116 * Return a string that uniquely identifies a finite element. This class
117 * returns <tt>FE_Q_Bubbles<dim>(degree)</tt>, with @p dim and @p degree
118 * replaced by appropriate values.
119 */
120 virtual std::string
121 get_name() const override;
122
123 // documentation inherited from the base class
124 virtual void
125 convert_generalized_support_point_values_to_dof_values(
126 const std::vector<Vector<double>> &support_point_values,
127 std::vector<double> &nodal_values) const override;
128
129 /**
130 * Return the matrix interpolating from the given finite element to the
131 * present one. The size of the matrix is then @p dofs_per_cell times
132 * <tt>source.n_dofs_per_cell()</tt>.
133 *
134 * These matrices are only available if the source element is also a @p
135 * FE_Q_Bubbles element. Otherwise, an exception of type
136 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
137 */
138 virtual void
139 get_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
140 FullMatrix<double> &matrix) const override;
141
142 virtual const FullMatrix<double> &
143 get_prolongation_matrix(
144 const unsigned int child,
145 const RefinementCase<dim> &refinement_case) const override;
146
147 virtual const FullMatrix<double> &
148 get_restriction_matrix(
149 const unsigned int child,
150 const RefinementCase<dim> &refinement_case) const override;
151
152 /**
153 * Check for non-zero values on a face.
154 *
155 * This function returns @p true, if the shape function @p shape_index has
156 * non-zero values on the face @p face_index.
157 *
158 * Implementation of the interface in FiniteElement
159 */
160 virtual bool
161 has_support_on_face(const unsigned int shape_index,
162 const unsigned int face_index) const override;
163
164 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
165 clone() const override;
166
167 /**
168 * @copydoc FiniteElement::compare_for_domination()
169 */
170 virtual FiniteElementDomination::Domination
171 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
172 const unsigned int codim = 0) const override final;
173
174 private:
175 /**
176 * Return the restriction_is_additive flags. Only the last components for
177 * the bubble enrichments are true.
178 */
179 static std::vector<bool>
180 get_riaf_vector(const unsigned int degree);
181
182 /**
183 * Only for internal use. Its full name is @p get_dofs_per_object_vector
184 * function and it creates the @p dofs_per_object vector that is needed
185 * within the constructor to be passed to the constructor of @p
186 * FiniteElementData.
187 */
188 static std::vector<unsigned int>
189 get_dpo_vector(const unsigned int degree);
190
191 /**
192 * Number of additional bubble functions
193 */
194 const unsigned int n_bubbles;
195 };
196
197
198
199 /** @} */
200
201
202 DEAL_II_NAMESPACE_CLOSE
203
204 #endif