Debian Codegraph @

include/deal.II/fe/fe_q_base.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2013 - 2025 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_fe_q_base_h
16 #define dealii_fe_q_base_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/mutex.h>
21
22 #include <deal.II/fe/fe_poly.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26
27 /**
28 * @addtogroup fe
29 * @{
30 */
31
32 /**
33 * This class collects the basic methods used in FE_Q, FE_Q_DG0 and
34 * FE_Q_Bubbles. There is no public constructor for this class as it is not
35 * functional as a stand-alone. The completion of definitions is left to the
36 * derived classes.
37 */
38 template <int dim, int spacedim = dim>
39 class FE_Q_Base : public FE_Poly<dim, spacedim>
40 {
41 public:
42 /**
43 * Constructor.
44 */
45 FE_Q_Base(const ScalarPolynomialsBase<dim> &poly_space,
46 const FiniteElementData<dim> &fe_data,
47 const std::vector<bool> &restriction_is_additive_flags);
48
49 /**
50 * Return the matrix interpolating from the given finite element to the
51 * present one. The size of the matrix is then @p dofs_per_cell times
52 * <tt>source.n_dofs_per_cell()</tt>.
53 *
54 * These matrices are only available if the source element is also a @p FE_Q
55 * element. Otherwise, an exception of type
56 * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is thrown.
57 */
58 virtual void
59 get_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
60 FullMatrix<double> &matrix) const override;
61
62
63 /**
64 * Return the matrix interpolating from a face of one element to the face
65 * of the neighboring element. The size of the matrix is then
66 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. The
67 * FE_Q element family only provides interpolation matrices for elements of
68 * the same type and FE_Nothing. For all other elements, an exception of
69 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is
70 * thrown.
71 */
72 virtual void
73 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
74 FullMatrix<double> &matrix,
75 const unsigned int face_no = 0) const override;
76
77 /**
78 * Return the matrix interpolating from a face of one element to the face
79 * of the neighboring element. The size of the matrix is then
80 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>. The
81 * FE_Q element family only provides interpolation matrices for elements of
82 * the same type and FE_Nothing. For all other elements, an exception of
83 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented is
84 * thrown.
85 */
86 virtual void
87 get_subface_interpolation_matrix(
88 const FiniteElement<dim, spacedim> &source,
89 const unsigned int subface,
90 FullMatrix<double> &matrix,
91 const unsigned int face_no = 0) const override;
92
93 /**
94 * This function returns @p true, if the shape function @p shape_index has
95 * non-zero function values somewhere on the face @p face_index.
96 */
97 virtual bool
98 has_support_on_face(const unsigned int shape_index,
99 const unsigned int face_index) const override;
100
101 /**
102 * Projection from a fine grid space onto a coarse grid space. Overrides the
103 * respective method in FiniteElement, implementing lazy evaluation
104 * (initialize when requested).
105 *
106 * If this projection operator is associated with a matrix @p P, then the
107 * restriction of this matrix @p P_i to a single child cell is returned
108 * here.
109 *
110 * The matrix @p P is the concatenation or the sum of the cell matrices @p
111 * P_i, depending on the #restriction_is_additive_flags. This distinguishes
112 * interpolation (concatenation) and projection with respect to scalar
113 * products (summation).
114 *
115 * Row and column indices are related to coarse grid and fine grid spaces,
116 * respectively, consistent with the definition of the associated operator.
117 *
118 * If projection matrices are not implemented in the derived finite element
119 * class, this function aborts with ExcProjectionVoid. You can check whether
120 * this is the case by calling the restriction_is_implemented() or the
121 * isotropic_restriction_is_implemented() function.
122 */
123 virtual const FullMatrix<double> &
124 get_restriction_matrix(
125 const unsigned int child,
126 const RefinementCase<dim> &refinement_case =
127 RefinementCase<dim>::isotropic_refinement) const override;
128
129 /**
130 * Embedding matrix between grids. Overrides the respective method in
131 * FiniteElement, implementing lazy evaluation (initialize when queried).
132 *
133 * The identity operator from a coarse grid space into a fine grid space is
134 * associated with a matrix @p P. The restriction of this matrix @p P_i to a
135 * single child cell is returned here.
136 *
137 * The matrix @p P is the concatenation, not the sum of the cell matrices @p
138 * P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in two
139 * different child matrices @p P_i, the value should be the same in both
140 * matrices and it is copied into the matrix @p P only once.
141 *
142 * Row and column indices are related to fine grid and coarse grid spaces,
143 * respectively, consistent with the definition of the associated operator.
144 *
145 * These matrices are used by routines assembling the prolongation matrix
146 * for multi-level methods. Upon assembling the transfer matrix between
147 * cells using this matrix array, zero elements in the prolongation matrix
148 * are discarded and will not fill up the transfer matrix.
149 *
150 * If projection matrices are not implemented in the derived finite element
151 * class, this function aborts with ExcEmbeddingVoid. You can check whether
152 * this is the case by calling the prolongation_is_implemented() or the
153 * isotropic_prolongation_is_implemented() function.
154 */
155 virtual const FullMatrix<double> &
156 get_prolongation_matrix(
157 const unsigned int child,
158 const RefinementCase<dim> &refinement_case =
159 RefinementCase<dim>::isotropic_refinement) const override;
160
161 /**
162 * Given an index in the natural ordering of indices on a face, return the
163 * index of the same degree of freedom on the cell.
164 *
165 * To explain the concept, consider the case where we would like to know
166 * whether a degree of freedom on a face, for example as part of an FESystem
167 * element, is primitive. Unfortunately, the is_primitive() function in the
168 * FiniteElement class takes a cell index, so we would need to find the cell
169 * index of the shape function that corresponds to the present face index.
170 * This function does that.
171 *
172 * Code implementing this would then look like this:
173 * @code
174 * for (i=0; i<dofs_per_face; ++i)
175 * if (fe.is_primitive(fe.face_to_cell_index(i, some_face_no)))
176 * ... do whatever
177 * @endcode
178 * The function takes additional arguments that account for the fact that
179 * actual faces can be in their standard ordering with respect to the cell
180 * under consideration, or can be flipped, oriented, etc.
181 *
182 * @param face_dof_index The index of the degree of freedom on a face. This
183 * index must be between zero and dofs_per_face.
184 * @param face The number of the face this degree of freedom lives on. This
185 * number must be between zero and GeometryInfo::faces_per_cell.
186 * @param combined_orientation The combined orientation flag containing the
187 * orientation, rotation, and flip of the face. See
188 * @ref GlossCombinedOrientation.
189 * @return The index of this degree of freedom within the set of degrees of
190 * freedom on the entire cell. The returned value will be between zero and
191 * dofs_per_cell.
192 */
193 virtual unsigned int
194 face_to_cell_index(const unsigned int face_dof_index,
195 const unsigned int face,
196 const types::geometric_orientation combined_orientation =
197 numbers::default_geometric_orientation) const override;
198
199 /**
200 * Return a list of constant modes of the element. For this element, the
201 * list consists of true arguments for all components.
202 */
203 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
204 get_constant_modes() const override;
205
206 /**
207 * @name Functions to support hp
208 * @{
209 */
210
211 /**
212 * Return whether this element implements its hanging node constraints in
213 * the new way, which has to be used to make elements "hp-compatible".
214 *
215 * For the FE_Q class the result is always true (independent of the degree
216 * of the element), as it implements the complete set of functions necessary
217 * for hp-capability.
218 */
219 virtual bool
220 hp_constraints_are_implemented() const override;
221
222 /**
223 * If, on a vertex, several finite elements are active, the hp-code first
224 * assigns the degrees of freedom of each of these FEs different global
225 * indices. It then calls this function to find out which of them should get
226 * identical values, and consequently can receive the same global DoF index.
227 * This function therefore returns a list of identities between DoFs of the
228 * present finite element object with the DoFs of @p fe_other, which is a
229 * reference to a finite element object representing one of the other finite
230 * elements active on this particular vertex. The function computes which of
231 * the degrees of freedom of the two finite element objects are equivalent,
232 * both numbered between zero and the corresponding value of
233 * n_dofs_per_vertex() of the two finite elements. The first index of each
234 * pair denotes one of the vertex dofs of the present element, whereas the
235 * second is the corresponding index of the other finite element.
236 */
237 virtual std::vector<std::pair<unsigned int, unsigned int>>
238 hp_vertex_dof_identities(
239 const FiniteElement<dim, spacedim> &fe_other) const override;
240
241 /**
242 * Same as hp_vertex_dof_indices(), except that the function treats degrees
243 * of freedom on lines.
244 */
245 virtual std::vector<std::pair<unsigned int, unsigned int>>
246 hp_line_dof_identities(
247 const FiniteElement<dim, spacedim> &fe_other) const override;
248
249 /**
250 * Same as hp_vertex_dof_indices(), except that the function treats degrees
251 * of freedom on quads.
252 */
253 virtual std::vector<std::pair<unsigned int, unsigned int>>
254 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
255 const unsigned int face_no = 0) const override;
256
257 /** @} */
258
259 /**
260 * Attempt to construct an FE_Q object of degree 0
261 *
262 * @ingroup Exceptions
263 */
264 DeclExceptionMsg(ExcFEQCannotHaveDegree0,
265 "FE_Q can only be used for polynomial degrees "
266 "greater than zero. If you want an element of polynomial "
267 "degree zero, then it cannot be continuous and you "
268 "will want to use FE_DGQ<dim>(0).");
269
270 protected:
271 /**
272 * Only for internal use. Its full name is @p get_dofs_per_object_vector
273 * function and it creates the @p dofs_per_object vector that is needed
274 * within the constructor to be passed to the constructor of @p
275 * FiniteElementData.
276 */
277 static std::vector<unsigned int>
278 get_dpo_vector(const unsigned int degree);
279
280 /**
281 * Perform the initialization of the element based on 1d support points,
282 * i.e., sets renumbering, initializes unit support points, initializes
283 * constraints as well as restriction and prolongation matrices.
284 */
285 void
286 initialize(const std::vector<Point<1>> &support_points_1d);
287
288 /**
289 * Initialize the hanging node constraints matrices. Called from
290 * initialize().
291 */
292 void
293 initialize_constraints(const std::vector<Point<1>> &points);
294
295 /**
296 * Initialize the @p unit_support_points field of the FiniteElement class.
297 * Called from initialize().
298 */
299 void
300 initialize_unit_support_points(const std::vector<Point<1>> &points);
301
302 /**
303 * Initialize the @p unit_face_support_points field of the FiniteElement
304 * class. Called from initialize().
305 */
306 void
307 initialize_unit_face_support_points(const std::vector<Point<1>> &points);
308
309 /**
310 * Initialize the @p adjust_quad_dof_index_for_face_orientation_table and
311 * adjust_line_dof_index_for_line_orientation_table tables of the
312 * FiniteElement class. Called from initialize().
313 */
314 void
315 initialize_dof_index_permutations();
316
317 /**
318 * Forward declaration of a class into which we put significant parts of the
319 * implementation.
320 *
321 * See the .cc file for more information.
322 */
323 struct Implementation;
324
325 // Declare implementation friend.
326 friend struct FE_Q_Base<dim, spacedim>::Implementation;
327
328 private:
329 /**
330 * Mutex variables used for protecting the initialization of restriction
331 * and embedding matrices.
332 */
333 mutable Threads::Mutex restriction_matrix_mutex;
334 mutable Threads::Mutex prolongation_matrix_mutex;
335
336 /**
337 * The highest polynomial degree of the underlying tensor product space
338 * without any enrichment. For FE_Q*(p) this is p. Note that enrichments
339 * may lead to a difference to degree.
340 */
341 const unsigned int q_degree;
342 };
343
344
345 /** @} */
346
347 DEAL_II_NAMESPACE_CLOSE
348
349 #endif