Debian Codegraph @

include/deal.II/fe/fe_tools.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2000 - 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_tools_H
16 #define dealii_fe_tools_H
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/geometry_info.h>
25 #include <deal.II/base/symmetric_tensor.h>
26 #include <deal.II/base/tensor.h>
27
28 #include <deal.II/distributed/tria.h>
29
30 #include <deal.II/fe/component_mask.h>
31
32 #include <deal.II/lac/la_parallel_vector.h>
33
34 #include <memory>
35 #include <string>
36 #include <vector>
37
38
39 DEAL_II_NAMESPACE_OPEN
40
41 // Forward declarations
42 #ifndef DOXYGEN
43 template <typename number>
44 class FullMatrix;
45 template <int dim>
46 class Quadrature;
47 template <int dim, int spacedim>
48 class FiniteElement;
49 template <int dim, int spacedim>
50 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
51 class DoFHandler;
52 template <int dim>
53 class FiniteElementData;
54 template <typename number>
55 class AffineConstraints;
56 #endif
57
58
59 /**
60 * @addtogroup feall
61 * @{
62 */
63
64
65 /**
66 * This namespace offers interpolations and extrapolations of discrete
67 * functions of one @p FiniteElement @p fe1 to another @p FiniteElement @p
68 * fe2.
69 *
70 * It also provides the local interpolation matrices that interpolate on each
71 * cell. Furthermore it provides the difference matrix $id-I_h$ that is needed
72 * for evaluating $(id-I_h)z$ for e.g. the dual solution $z$.
73 *
74 * For more information about the <tt>spacedim</tt> template parameter check
75 * the documentation of FiniteElement or the one of Triangulation.
76 */
77 namespace FETools
78 {
79 /**
80 * A base class for factory objects creating finite elements of a given
81 * degree. Derived classes are called whenever one wants to have a
82 * transparent way to create a finite element object.
83 *
84 * This class is used in the FETools::get_fe_by_name() and
85 * FETools::add_fe_name() functions.
86 */
87 template <int dim, int spacedim = dim>
88 class FEFactoryBase : public EnableObserverPointer
89 {
90 public:
91 /**
92 * Create a FiniteElement and return a pointer to it.
93 */
94 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
95 get(const unsigned int degree) const = 0;
96
97 /**
98 * Create a FiniteElement from a quadrature formula (currently only
99 * implemented for FE_Q) and return a pointer to it.
100 */
101
102 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
103 get(const Quadrature<1> &quad) const = 0;
104
105 /**
106 * Virtual destructor doing nothing but making the compiler happy.
107 */
108 virtual ~FEFactoryBase() override = default;
109 };
110
111 /**
112 * A concrete class for factory objects creating finite elements of a given
113 * degree.
114 *
115 * The class's get() function generates a finite element object of the type
116 * given as template argument, and with the degree (however the finite
117 * element class wishes to interpret this number) given as argument to
118 * get().
119 */
120 template <class FE>
121 class FEFactory : public FEFactoryBase<FE::dimension, FE::space_dimension>
122 {
123 public:
124 /**
125 * Create a FiniteElement and return a pointer to it.
126 */
127 virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
128 get(const unsigned int degree) const override;
129
130 /**
131 * Create a FiniteElement from a quadrature formula (currently only
132 * implemented for FE_Q) and return a pointer to it.
133 */
134 virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
135 get(const Quadrature<1> &quad) const override;
136 };
137
138 /**
139 * @warning In most cases, you will probably want to use
140 * compute_base_renumbering().
141 *
142 * Compute the vector required to renumber the dofs of a cell by component.
143 * Furthermore, compute the vector storing the start indices of each
144 * component in the local block vector.
145 *
146 * The second vector is organized such that there is a vector for each base
147 * element containing the start index for each component served by this base
148 * element.
149 *
150 * While the first vector is checked to have the correct size, the second
151 * one is reinitialized for convenience.
152 */
153 template <int dim, int spacedim>
154 void
155 compute_component_wise(const FiniteElement<dim, spacedim> &fe,
156 std::vector<unsigned int> &renumbering,
157 std::vector<std::vector<unsigned int>> &start_indices);
158
159 /**
160 * Compute the vector required to renumber the dofs of a cell by block.
161 * Furthermore, compute the vector storing either the start indices or the
162 * size of each local block vector.
163 *
164 * If the @p bool parameter is true, @p block_data is filled with the start
165 * indices of each local block. If it is false, then the block sizes are
166 * returned.
167 *
168 * The vector <tt>renumbering</tt> will be indexed by the standard numbering
169 * of local degrees of freedom, namely the first vertex, then the second
170 * vertex, after vertices lines, quads, and hexes. For each index, the entry
171 * indicates the index which this degree of freedom receives in a numbering
172 * scheme, where the first block is numbered completely before the second.
173 */
174 template <int dim, int spacedim>
175 void
176 compute_block_renumbering(const FiniteElement<dim, spacedim> &fe,
177 std::vector<types::global_dof_index> &renumbering,
178 std::vector<types::global_dof_index> &block_data,
179 bool return_start_indices = true);
180
181 /**
182 * @name Generation of local matrices
183 * @{
184 */
185 /**
186 * Compute the interpolation matrix that interpolates a @p fe1-function to a
187 * @p fe2-function on each cell. The interpolation_matrix needs to be of
188 * size <tt>(fe2.n_dofs_per_cell(), fe1.n_dofs_per_cell())</tt>.
189 *
190 * Note, that if the finite element space @p fe1 is a subset of the finite
191 * element space @p fe2 then the @p interpolation_matrix is an embedding
192 * matrix.
193 */
194 template <int dim, typename number, int spacedim>
195 void
196 get_interpolation_matrix(const FiniteElement<dim, spacedim> &fe1,
197 const FiniteElement<dim, spacedim> &fe2,
198 FullMatrix<number> &interpolation_matrix);
199
200 /**
201 * Compute the interpolation matrix that interpolates a @p fe1-function to a
202 * @p fe2-function, and interpolates this to a second @p fe1-function on
203 * each cell. The interpolation_matrix needs to be of size
204 * <tt>(fe1.n_dofs_per_cell(), fe1.n_dofs_per_cell())</tt>.
205 *
206 * Note, that this function only makes sense if the finite element space due
207 * to @p fe1 is not a subset of the finite element space due to @p fe2, as
208 * if it were a subset then the @p interpolation_matrix would be only the
209 * unit matrix.
210 */
211 template <int dim, typename number, int spacedim>
212 void
213 get_back_interpolation_matrix(const FiniteElement<dim, spacedim> &fe1,
214 const FiniteElement<dim, spacedim> &fe2,
215 FullMatrix<number> &interpolation_matrix);
216
217 /**
218 * Compute the identity matrix minus the back interpolation matrix.
219 * The @p difference_matrix will be of size <tt>(fe1.n_dofs_per_cell(),
220 * fe1.n_dofs_per_cell())</tt> after this function. Previous content
221 * of the argument will be overwritten.
222 *
223 * This function computes the matrix that transforms a @p fe1 function $z$ to
224 * $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1
225 * space to the @p fe2 space. This matrix hence is useful to evaluate
226 * error-representations where $z$ denotes the dual solution.
227 */
228 template <int dim, typename number, int spacedim>
229 void
230 get_interpolation_difference_matrix(const FiniteElement<dim, spacedim> &fe1,
231 const FiniteElement<dim, spacedim> &fe2,
232 FullMatrix<number> &difference_matrix);
233
234 /**
235 * Compute the local $L^2$-projection matrix from fe1 to fe2.
236 */
237 template <int dim, typename number, int spacedim>
238 void
239 get_projection_matrix(const FiniteElement<dim, spacedim> &fe1,
240 const FiniteElement<dim, spacedim> &fe2,
241 FullMatrix<number> &matrix);
242
243 /**
244 * This is a rather specialized function used during the construction of
245 * finite element objects. It is used to build the basis of shape functions
246 * for an element, given a set of polynomials and interpolation points. The
247 * function is only implemented for finite elements with exactly @p dim
248 * vector components. In particular, this applies to classes derived from
249 * the FE_PolyTensor class.
250 *
251 * Specifically, the purpose of this function is as follows: FE_PolyTensor
252 * receives, from its derived classes, an argument that describes a polynomial
253 * space. This space may be parameterized in terms of monomials, or in some
254 * other way, but is in general not in the form that we use for finite
255 * elements where we typically want to use a basis that is derived from
256 * some kind of node functional (e.g., the interpolation at specific points).
257 * Concretely, assume that the basis used by the polynomial space is
258 * $\{\tilde\varphi_j(\mathbf x)\}_{j=1}^N$, and that the node functionals
259 * of the finite element are $\{\Psi_i\}_{i=1}^N$. We then want to compute a
260 * basis $\{\varphi_j(\mathbf x)\}_{j=1}^N$ for the finite element space so
261 * that $\Psi_i[\varphi_j] = \delta_{ij}$. To do this, we can set
262 * $\varphi_j(\mathbf x) = \sum_{k=1}^N c_{jk} \tilde\varphi_k(\mathbf x)$
263 * where we need to determine the expansion coefficients $c_{jk}$. We do this
264 * by applying $\Psi_i$ to both sides of the equation, to obtain
265 * @f{align*}{
266 * \Psi_i [\varphi_j] = \sum_{k=1}^N c_{jk} \Psi_i[\tilde\varphi_k],
267 * @f}
268 * and we know that the left hand side equals $\delta_{ij}$.
269 * If you think of this as a system of $N\times N$ equations for the
270 * elements of a matrix on the left and on the right, then this can be
271 * written as
272 * @f{align*}{
273 * I = C X^T
274 * @f}
275 * where $C$ is the matrix of coefficients $c_{jk}$ and
276 * $X_{ik} = \Psi_i[\tilde\varphi_k]$. Consequently, in order to compute
277 * the expansion coefficients $C=X^{-T}$, we need to apply the node
278 * functionals to all functions of the "raw" basis of the polynomial space.
279 *
280 * Until the finite element receives this matrix $X$ back, it describes its
281 * shape functions (e.g., in FiniteElement::shape_value()) in the form
282 * $\tilde\varphi_j$. After it calls this function, it has the expansion
283 * coefficients and can describe its shape functions as $\varphi_j$.
284 *
285 * This function therefore computes this matrix $X$, for the following
286 * specific circumstances:
287 * - That the node functionals $\Psi_i$ are point evaluations at points
288 * $\mathbf x_i$ that the finite element in question describes via its
289 * "generalized" support points (through
290 * FiniteElement::get_generalized_support_points(), see also
291 * @ref GlossGeneralizedSupport "this glossary entry"). These point
292 * evaluations need to necessarily evaluate the <i>value</i> of a shape
293 * function at that point (the shape function may be vector-valued, and
294 * so the functional may be a linear combination of the individual
295 * components of the values); but, in particular, the nodal functions may
296 * not be <i>integrals</i> over entire edges or faces,
297 * or other non-local functionals. In other words, we assume that
298 * $\Psi_i[\tilde\varphi_j] = f_j(\tilde\varphi_j(\mathbf x_i))$
299 * where $f_j$ is a function of the (possibly vector-valued) argument
300 * that returns a scalar.
301 * - That the finite element has exactly @p dim vector components.
302 * - That the function $f_j$ is given by whatever the element implements
303 * through the
304 * FiniteElement::convert_generalized_support_point_values_to_dof_values()
305 * function.
306 *
307 * @param fe The finite element for which the operations above are to be
308 * performed.
309 * @return The matrix $X$ as discussed above.
310 */
311 template <int dim, int spacedim>
312 FullMatrix<double>
313 compute_node_matrix(const FiniteElement<dim, spacedim> &fe);
314
315 /**
316 * For all possible (isotropic and anisotropic) refinement cases compute the
317 * embedding matrices from a coarse cell to the child cells. Each column of
318 * the resulting matrices contains the representation of a coarse grid basis
319 * function by the fine grid basis; the matrices are split such that there
320 * is one matrix for every child.
321 *
322 * This function computes the coarse grid function in a sufficiently large
323 * number of quadrature points and fits the fine grid functions using least
324 * squares approximation. Therefore, the use of this function is restricted
325 * to the case that the finite element spaces are actually nested.
326 *
327 * Note, that <code>matrices[refinement_case-1][child]</code> includes the
328 * embedding (or prolongation) matrix of child <code>child</code> for the
329 * RefinementCase <code>refinement_case</code>. Here, we use
330 * <code>refinement_case-1</code> instead of <code>refinement_case</code> as
331 * for RefinementCase::no_refinement(=0) there are no prolongation matrices
332 * available.
333 *
334 * Typically this function is called by the various implementations of
335 * FiniteElement classes in order to fill the respective
336 * FiniteElement::prolongation matrices.
337 *
338 * @param fe The finite element class for which we compute the embedding
339 * matrices.
340 *
341 * @param matrices A reference to RefinementCase<dim>::isotropic_refinement
342 * vectors of FullMatrix objects. Each vector corresponds to one
343 * RefinementCase @p refinement_case and is of the vector size
344 * GeometryInfo<dim>::n_children(refinement_case). This is the format used
345 * in FiniteElement, where we want to use this function mostly.
346 *
347 * @param isotropic_only Set to <code>true</code> if you only want to
348 * compute matrices for isotropic refinement.
349 *
350 * @param threshold is the gap allowed in the least squares algorithm
351 * computing the embedding.
352 */
353 template <int dim, typename number, int spacedim>
354 void
355 compute_embedding_matrices(
356 const FiniteElement<dim, spacedim> &fe,
357 std::vector<std::vector<FullMatrix<number>>> &matrices,
358 const bool isotropic_only = false,
359 const double threshold = 1.e-12);
360
361 /**
362 * Compute the embedding matrices on faces needed for constraint matrices.
363 *
364 * @param fe The finite element for which to compute these matrices.
365 *
366 * @param matrices An array of <i>GeometryInfo<dim>::subfaces_per_face =
367 * 2<sup>dim-1</sup></i> FullMatrix objects, holding the embedding matrix for
368 * each subface.
369 *
370 * @param face_coarse The number of the face on the coarse side of the face
371 * for which this is computed.
372 *
373 * @param face_fine The number of the face on the refined side of the face
374 * for which this is computed.
375 *
376 * @param threshold is the gap allowed in the least squares algorithm
377 * computing the embedding.
378 *
379 * @warning This function will be used in computing constraint matrices. It
380 * is not sufficiently tested yet.
381 */
382 template <int dim, typename number, int spacedim>
383 void
384 compute_face_embedding_matrices(const FiniteElement<dim, spacedim> &fe,
385 const ArrayView<FullMatrix<number>> &matrices,
386 const unsigned int face_coarse,
387 const unsigned int face_fine,
388 const double threshold = 1.e-12);
389
390 /**
391 * For all possible (isotropic and anisotropic) refinement cases compute the
392 * <i>L<sup>2</sup></i>-projection matrices from the children to a coarse
393 * cell.
394 *
395 * Note, that <code>matrices[refinement_case-1][child]</code> includes the
396 * projection (or restriction) matrix of child <code>child</code> for the
397 * RefinementCase <code>refinement_case</code>. Here, we use
398 * <code>refinement_case-1</code> instead of <code>refinement_case</code> as
399 * for RefinementCase::no_refinement(=0) there are no projection matrices
400 * available.
401 *
402 * Typically this function is called by the various implementations of
403 * FiniteElement classes in order to fill the respective
404 * FiniteElement::restriction matrices.
405 *
406 * @arg[in] fe The finite element class for which we compute the projection
407 * matrices.
408 *
409 * @arg[out] matrices A reference to a set of
410 * <tt>RefinementCase<dim>::isotropic_refinement</tt> vectors of FullMatrix
411 * objects. Each vector corresponds to one RefinementCase @p refinement_case
412 * and is of the vector size
413 * <tt>GeometryInfo<dim>::n_children(refinement_case)</tt>. This is the
414 * format used in FiniteElement, where we want to use this function mostly.
415 *
416 * @arg[in] isotropic_only If set to <code>true</code>, then this
417 * function only computes data for the isotropic refinement case. The
418 * other elements of the output vector are left untouched (but still
419 * exist).
420 */
421 template <int dim, typename number, int spacedim>
422 void
423 compute_projection_matrices(
424 const FiniteElement<dim, spacedim> &fe,
425 std::vector<std::vector<FullMatrix<number>>> &matrices,
426 const bool isotropic_only = false);
427
428 /**
429 * Project scalar data defined in quadrature points to a finite element
430 * space on a single cell.
431 *
432 * What this function does is the following: assume that there is scalar
433 * data <tt>u<sub>q</sub>, 0 <= q < Q:=quadrature.size()</tt> defined at the
434 * quadrature points of a cell, with the points defined by the given
435 * <tt>rhs_quadrature</tt> object. We may then want to ask for that finite
436 * element function (on a single cell) <tt>v<sub>h</sub></tt> in the
437 * finite-dimensional space defined by the given FE object that is the
438 * projection of <tt>u</tt> in the following sense:
439 *
440 * Usually, the projection <tt>v<sub>h</sub></tt> is that function that
441 * satisfies <tt>(v<sub>h</sub>,w)=(u,w)</tt> for all discrete test
442 * functions <tt>w</tt>. In the present case, we can't evaluate the right
443 * hand side, since <tt>u</tt> is only defined in the quadrature points
444 * given by <tt>rhs_quadrature</tt>, so we replace it by a quadrature
445 * approximation. Likewise, the left hand side is approximated using the
446 * <tt>lhs_quadrature</tt> object; if this quadrature object is chosen
447 * appropriately, then the integration of the left hand side can be done
448 * exactly, without any approximation. The use of different quadrature
449 * objects is necessary if the quadrature object for the right hand side has
450 * too few quadrature points -- for example, if data <tt>q</tt> is only
451 * defined at the cell center, then the corresponding one-point quadrature
452 * formula is obviously insufficient to approximate the scalar product on
453 * the left hand side by a definite form.
454 *
455 * After these quadrature approximations, we end up with a nodal
456 * representation <tt>V<sub>h</sub></tt> of <tt>v<sub>h</sub></tt> that
457 * satisfies the following system of linear equations: <tt>M V<sub>h</sub> =
458 * Q U</tt>, where <tt>M<sub>ij</sub>=(phi_i,phi_j)</tt> is the @ref GlossMassMatrix "mass matrix"
459 * approximated by <tt>lhs_quadrature</tt>, and <tt>Q</tt> is the matrix
460 * <tt>Q<sub>iq</sub>=phi<sub>i</sub>(x<sub>q</sub>) w<sub>q</sub></tt>
461 * where <tt>w<sub>q</sub></tt> are quadrature weights; <tt>U</tt> is the
462 * vector of quadrature point data <tt>u<sub>q</sub></tt>.
463 *
464 * In order to then get the nodal representation <tt>V<sub>h</sub></tt> of
465 * the projection of <tt>U</tt>, one computes <tt>V<sub>h</sub> = X U,
466 * X=M<sup>-1</sup> Q</tt>. The purpose of this function is to compute the
467 * matrix <tt>X</tt> and return it through the last argument of this
468 * function.
469 *
470 * Note that this function presently only supports scalar data. An extension
471 * of the mass matrix is of course trivial, but one has to define the order
472 * of data in the vector <tt>U</tt> if it contains vector valued data in all
473 * quadrature points.
474 *
475 * A use for this function is described in the introduction to the step-18
476 * example program.
477 *
478 * The opposite of this function, interpolation of a finite element function
479 * onto quadrature points is essentially what the
480 * <tt>FEValues::get_function_values</tt> functions do; to make things a
481 * little simpler, the
482 * <tt>FETools::compute_interpolation_to_quadrature_points_matrix</tt>
483 * provides the matrix form of this.
484 *
485 * Note that this function works on a single cell, rather than an entire
486 * triangulation. In effect, it therefore doesn't matter if you use a
487 * continuous or discontinuous version of the finite element.
488 *
489 * It is worth noting that there are a few confusing cases of this function.
490 * The first one is that it really only makes sense to project onto a finite
491 * element that has at most as many degrees of freedom per cell as there are
492 * quadrature points; the projection of N quadrature point data into a space
493 * with M>N unknowns is well-defined, but often yields funny and
494 * non-intuitive results. Secondly, one would think that if the quadrature
495 * point data is defined in the support points of the finite element, i.e. the
496 * quadrature points of <tt>rhs_quadrature</tt> equal
497 * <tt>fe.get_unit_support_points()</tt>, then the projection should be the
498 * identity, i.e. each degree of freedom of the finite element equals the
499 * value of the given data in the support point of the corresponding shape
500 * function. However, this is not generally the case: while the matrix
501 * <tt>Q</tt> in that case is the identity matrix, the mass matrix
502 * <tt>M</tt> is not equal to the identity matrix, except for the special
503 * case that the quadrature formula <tt>lhs_quadrature</tt> also has its
504 * quadrature points in the support points of the finite element.
505 *
506 * Finally, this function only defines a cell wise projection, while one
507 * frequently wants to apply it to all cells in a triangulation. However, if
508 * it is applied to one cell after the other, the results from later cells
509 * may overwrite nodal values computed already from previous cells if
510 * degrees of freedom live on the interfaces between cells. The function is
511 * therefore most useful for discontinuous elements.
512 */
513 template <int dim, int spacedim>
514 void
515 compute_projection_from_quadrature_points_matrix(
516 const FiniteElement<dim, spacedim> &fe,
517 const Quadrature<dim> &lhs_quadrature,
518 const Quadrature<dim> &rhs_quadrature,
519 FullMatrix<double> &X);
520
521 /**
522 * Given a (scalar) local finite element function, compute the matrix that
523 * maps the vector of nodal values onto the vector of values of this
524 * function at quadrature points as given by the second argument. In a
525 * sense, this function does the opposite of the
526 * FETools::compute_projection_from_quadrature_points_matrix function.
527 */
528 template <int dim, int spacedim>
529 void
530 compute_interpolation_to_quadrature_points_matrix(
531 const FiniteElement<dim, spacedim> &fe,
532 const Quadrature<dim> &quadrature,
533 FullMatrix<double> &I_q);
534
535 /**
536 * Compute the projection of tensorial (first-order tensor) data stored at
537 * the quadrature points @p vector_of_tensors_at_qp to data @p
538 * vector_of_tensors_at_nodes at the support points of the cell. The data
539 * in @p vector_of_tensors_at_qp is ordered sequentially following the
540 * quadrature point numbering. The size of @p vector_of_tensors_at_qp must
541 * correspond to the number of columns of @p projection_matrix. The size of
542 * @p vector_of_tensors_at_nodes must correspond to the number of rows of @p
543 * vector_of_tensors_at_nodes . The projection matrix @p projection_matrix
544 * describes the projection of scalar data from the quadrature points and
545 * can be obtained from the
546 * FETools::compute_projection_from_quadrature_points_matrix function.
547 */
548 template <int dim>
549 void
550 compute_projection_from_quadrature_points(
551 const FullMatrix<double> &projection_matrix,
552 const std::vector<Tensor<1, dim>> &vector_of_tensors_at_qp,
553 std::vector<Tensor<1, dim>> &vector_of_tensors_at_nodes);
554
555
556
557 /**
558 * same as last function but for a @p SymmetricTensor .
559 */
560 template <int dim>
561 void
562 compute_projection_from_quadrature_points(
563 const FullMatrix<double> &projection_matrix,
564 const std::vector<SymmetricTensor<2, dim>> &vector_of_tensors_at_qp,
565 std::vector<SymmetricTensor<2, dim>> &vector_of_tensors_at_nodes);
566
567
568
569 /**
570 * This method implements the
571 * FETools::compute_projection_from_quadrature_points_matrix method for
572 * faces of a mesh. The matrix that it returns, X, is face specific and its
573 * size is fe.n_dofs_per_cell() by rhs_quadrature.size(). The dimension, dim
574 * must be larger than 1 for this class, since Quadrature<dim-1> objects are
575 * required. See the documentation on the Quadrature class for more
576 * information.
577 */
578 template <int dim, int spacedim>
579 void
580 compute_projection_from_face_quadrature_points_matrix(
581 const FiniteElement<dim, spacedim> &fe,
582 const Quadrature<dim - 1> &lhs_quadrature,
583 const Quadrature<dim - 1> &rhs_quadrature,
584 const typename DoFHandler<dim, spacedim>::active_cell_iterator &cell,
585 const unsigned int face,
586 FullMatrix<double> &X);
587
588 /**
589 * @brief Compute the nodal quadrature rule associated with an element.
590 *
591 * Many common finite elements (e.g., FE_Q) are interpolatory - i.e., they are
592 * multidimensional generalizations of Lagrange interpolating polynomials and
593 * are collectively referred to as @ref GlossLagrange "Lagrange elements".
594 *
595 * Since these elements define a polynomial interpolation, they implicitly
596 * also define a Quadrature rule. For example, the weights of QTrapezoid are
597 * the integrals of multilinear shape functions and the quadrature points are
598 * the vertices of the reference hypercube - i.e., QTrapezoid is the nodal
599 * rule corresponding to FE_Q(1). Some elements, such as FE_SimplexP(2), do
600 * not correspond to useful nodal quadrature rules since the integrals of some
601 * shape functions (in this case, the ones with support points at vertices)
602 * are zero. Other elements, like FE_RaviartThomas, are noninterpolatory and
603 * therefore also do not correspond to nodal quadrature rules.
604 *
605 * Given a FiniteElement with support points, this function determines the
606 * associated quadrature rule by setting the weights equal to the integrals of
607 * its shape functions (even if they are zero or negative) and points equal to
608 * the support points of the FiniteElement.
609 *
610 * @note If @p fe is an FE_Q or FE_DGQ with the default support points (i.e.,
611 * it was constructed with a polynomial order argument and not with a custom
612 * list of support points) then the corresponding nodal quadrature rule has
613 * the same points and weights as QGaussLobatto (but they will generally be in
614 * a different order).
615 *
616 * @note This function is only implemented for scalar (i.e., one block and one
617 * component) elements which have
618 * @ref GlossSupport "support points".
619 */
620 template <int dim, int spacedim = dim>
621 Quadrature<dim>
622 compute_nodal_quadrature(const FiniteElement<dim, spacedim> &fe);
623
624 /**
625 * Wrapper around
626 * FiniteElement::convert_generalized_support_point_values_to_dof_values()
627 * that works with arbitrary number types.
628 *
629 * @param[in] finite_element The FiniteElement to compute dof values for.
630 * @param[in] support_point_values An array of size @p dofs_per_cell
631 * (which equals the number of points the get_generalized_support_points()
632 * function will return) where each element is a vector with as many entries
633 * as the element has vector components. This array should contain
634 * the values of a function at the generalized support points of the
635 * finite element.
636 * @param[out] dof_values An array of size @p dofs_per_cell that contains
637 * the node functionals of the element applied to the given function.
638 */
639 template <int dim, int spacedim, typename number>
640 void
641 convert_generalized_support_point_values_to_dof_values(
642 const FiniteElement<dim, spacedim> &finite_element,
643 const std::vector<Vector<number>> &support_point_values,
644 std::vector<number> &dof_values);
645
646
647
648 /** @} */
649 /**
650 * @name Functions which should be in DoFTools or VectorTools
651 */
652 /** @{ */
653 /**
654 * Compute the interpolation of a the @p dof1-function @p u1 to a @p
655 * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on
656 * the same triangulation.
657 *
658 * If the elements @p fe1 and @p fe2 are either both continuous or both
659 * discontinuous then this interpolation is the usual point interpolation.
660 * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
661 * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
662 * a continuous finite element there is no point interpolation defined at
663 * the discontinuities. Therefore the mean value is taken at the DoF values
664 * on the discontinuities.
665 *
666 * Note that for continuous elements on grids with hanging nodes (i.e.
667 * locally refined grids) this function does not give the expected output.
668 * Indeed, the resulting output vector does not necessarily respect
669 * continuity requirements at hanging nodes: if, for example, you are
670 * interpolating a Q2 field to a Q1 field, then at hanging nodes the output
671 * field will have the function value of the input field, which however is
672 * not usually the mean value of the two adjacent nodes. It is thus not part
673 * of the Q1 function space on the whole triangulation, although it is of
674 * course Q1 on each cell.
675 *
676 * For this case (continuous elements on grids with hanging nodes), please
677 * use the @p interpolate() function with an additional AffineConstraints
678 * object as argument, see below, or make the field conforming yourself
679 * by calling the @p distribute function of your hanging node constraints
680 * object.
681 *
682 * @note There are also various interpolation-related functions in
683 * namespace VectorTools.
684 */
685 template <int dim, int spacedim, class InVector, class OutVector>
686 void
687 interpolate(const DoFHandler<dim, spacedim> &dof1,
688 const InVector &u1,
689 const DoFHandler<dim, spacedim> &dof2,
690 OutVector &u2);
691
692 /**
693 * Compute the interpolation of a the @p dof1-function @p u1 to a @p
694 * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on
695 * the same triangulation. @p constraints is a hanging node constraints object
696 * corresponding to @p dof2. This object is particular important when
697 * interpolating onto continuous elements on grids with hanging nodes (locally
698 * refined grids).
699 *
700 * If the elements @p fe1 and @p fe2 are either both continuous or both
701 * discontinuous then this interpolation is the usual point interpolation.
702 * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
703 * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
704 * a continuous finite element there is no point interpolation defined at
705 * the discontinuities. Therefore the mean value is taken at the DoF values
706 * at the discontinuities.
707 *
708 * @note There are also various interpolation-related functions in
709 * namespace VectorTools.
710 */
711 template <int dim, int spacedim, class InVector, class OutVector>
712 void
713 interpolate(
714 const DoFHandler<dim, spacedim> &dof1,
715 const InVector &u1,
716 const DoFHandler<dim, spacedim> &dof2,
717 const AffineConstraints<typename OutVector::value_type> &constraints,
718 OutVector &u2);
719
720 /**
721 * Compute the interpolation of the @p fe1-function @p u1 to a @p
722 * fe2-function, and interpolate this to a second @p fe1-function named @p
723 * u1_interpolated.
724 *
725 * Note, that this function does not work on continuous elements at hanging
726 * nodes. For that case use the @p back_interpolate function, below, that
727 * takes an additional @p AffineConstraints object.
728 *
729 * Furthermore note, that for the specific case when the finite element
730 * space corresponding to @p fe1 is a subset of the finite element space
731 * corresponding to @p fe2, this function is simply an identity mapping.
732 */
733 template <int dim, class InVector, class OutVector, int spacedim>
734 void
735 back_interpolate(const DoFHandler<dim, spacedim> &dof1,
736 const InVector &u1,
737 const FiniteElement<dim, spacedim> &fe2,
738 OutVector &u1_interpolated);
739
740 /**
741 * Compute the interpolation of the @p dof1-function @p u1 to a @p
742 * dof2-function, and interpolate this to a second @p dof1-function named
743 * @p u1_interpolated. @p constraints1 and @p constraints2 are the hanging
744 * node constraints corresponding to @p dof1 and @p dof2, respectively.
745 * These objects are particular important when continuous elements on grids
746 * with hanging nodes (locally refined grids) are involved.
747 *
748 * Furthermore note, that for the specific case when the finite element
749 * space corresponding to @p dof1 is a subset of the finite element space
750 * corresponding to @p dof2, this function is simply an identity mapping.
751 */
752 template <int dim, class InVector, class OutVector, int spacedim>
753 void
754 back_interpolate(
755 const DoFHandler<dim, spacedim> &dof1,
756 const AffineConstraints<typename OutVector::value_type> &constraints1,
757 const InVector &u1,
758 const DoFHandler<dim, spacedim> &dof2,
759 const AffineConstraints<typename OutVector::value_type> &constraints2,
760 OutVector &u1_interpolated);
761
762 /**
763 * Compute $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is
764 * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is
765 * written into @p z1_difference.
766 *
767 * Note, that this function does not work for continuous elements at hanging
768 * nodes. For that case use the @p interpolation_difference function, below,
769 * that takes an additional @p AffineConstraints object.
770 */
771 template <int dim, class InVector, class OutVector, int spacedim>
772 void
773 interpolation_difference(const DoFHandler<dim, spacedim> &dof1,
774 const InVector &z1,
775 const FiniteElement<dim, spacedim> &fe2,
776 OutVector &z1_difference);
777
778 /**
779 * Compute $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is
780 * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is
781 * written into @p z1_difference. @p constraints1 and @p constraints2 are
782 * the hanging node constraints corresponding to @p dof1 and @p dof2,
783 * respectively. These objects are particular important when continuous
784 * elements on grids with hanging nodes (locally refined grids) are
785 * involved.
786 *
787 * For parallel computations, supply @p z1 with ghost elements and @p
788 * z1_difference without ghost elements.
789 */
790 template <int dim, class InVector, class OutVector, int spacedim>
791 void
792 interpolation_difference(
793 const DoFHandler<dim, spacedim> &dof1,
794 const AffineConstraints<typename OutVector::value_type> &constraints1,
795 const InVector &z1,
796 const DoFHandler<dim, spacedim> &dof2,
797 const AffineConstraints<typename OutVector::value_type> &constraints2,
798 OutVector &z1_difference);
799
800
801
802 /**
803 * $L^2$ projection for discontinuous elements. Operates the same direction
804 * as interpolate.
805 *
806 * The global projection can be computed by local matrices if the finite
807 * element spaces are discontinuous. With continuous elements, this is
808 * impossible, since a global @ref GlossMassMatrix "mass matrix" must be inverted.
809 */
810 template <int dim, class InVector, class OutVector, int spacedim>
811 void
812 project_dg(const DoFHandler<dim, spacedim> &dof1,
813 const InVector &u1,
814 const DoFHandler<dim, spacedim> &dof2,
815 OutVector &u2);
816
817 /**
818 * Compute the patchwise extrapolation of a @p dof1 function @p z1 to a @p
819 * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects
820 * based on the same triangulation. This function is used, for example, for
821 * extrapolating patchwise a piecewise linear solution to a piecewise
822 * quadratic solution.
823 *
824 * The function's name is historical and probably not particularly well
825 * chosen. The function performs the following operations, one after the
826 * other:
827 *
828 * - It interpolates directly from every cell of @p dof1 to the
829 * corresponding cell of `dof2` using the interpolation matrix of the finite
830 * element spaces used on these cells and provided by the finite element
831 * objects involved. This step is done using the FETools::interpolate()
832 * function.
833 * - It then performs a loop over all non-active cells of `dof2`.
834 * If such a non-active cell has at least one active child, then we call the
835 * children of this cell a "patch". We then interpolate from the children of
836 * this patch to the patch, using the finite element space associated with
837 * `dof2` and immediately interpolate back to the children. In essence, this
838 * information throws away all information in the solution vector that lives
839 * on a scale smaller than the patch cell.
840 * - Since we traverse non-active cells from the coarsest to the finest
841 * levels, we may find patches that correspond to child cells of previously
842 * treated patches if the mesh had been refined adaptively (this cannot
843 * happen if the mesh has been refined globally because there the children
844 * of a patch are all active). We also perform the operation described above
845 * on these patches, which means that the final DoF values will always
846 * originate from the most refined patches.
847 *
848 * The name of the function originates from the fact that it can be used to
849 * construct a representation of a function of higher polynomial degree on a
850 * once coarser mesh. For example, if you imagine that you start with a
851 * $Q_1$ function on a globally refined mesh, and that @p dof2 is associated
852 * with a $Q_2$ element, then this function computes the equivalent of the
853 * operator $I_{2h}^{(2)}$ interpolating the original piecewise linear
854 * function onto a quadratic function on a once coarser mesh with mesh size
855 * $2h$ (but representing this function on the original mesh with size $h$).
856 * If the exact solution is sufficiently smooth, then
857 * $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to the exact
858 * solution $u$ of the PDE than $u_h$ is. In other words, this function
859 * provides a postprocessing step that improves the solution in a similar
860 * way one often obtains by extrapolating a sequence of solutions,
861 * explaining the origin of the function's name.
862 *
863 * @note The resulting field does not satisfy continuity requirements of the
864 * given finite elements if the algorithm outlined above is used. When you
865 * use continuous elements on grids with hanging nodes, please use the @p
866 * extrapolate function with an additional AffineConstraints argument, see
867 * below.
868 *
869 * @note Since this function operates on patches of cells, it requires that
870 * the underlying grid is refined at least once for every coarse grid cell.
871 * If this is not the case, an exception will be raised.
872 */
873 template <int dim, class InVector, class OutVector, int spacedim>
874 void
875 extrapolate(const DoFHandler<dim, spacedim> &dof1,
876 const InVector &z1,
877 const DoFHandler<dim, spacedim> &dof2,
878 OutVector &z2);
879
880 /**
881 * Compute the patchwise extrapolation of a @p dof1 function @p z1 to a @p
882 * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects
883 * based on the same triangulation. @p constraints is a hanging node
884 * constraints object corresponding to @p dof2. This object is necessary
885 * when interpolating onto continuous elements on grids with hanging nodes
886 * (locally refined grids).
887 *
888 * Otherwise, the function does the same as the other @p extrapolate
889 * function above (for which the documentation provides an extensive
890 * description of its operation).
891 */
892 template <int dim, class InVector, class OutVector, int spacedim>
893 void
894 extrapolate(
895 const DoFHandler<dim, spacedim> &dof1,
896 const InVector &z1,
897 const DoFHandler<dim, spacedim> &dof2,
898 const AffineConstraints<typename OutVector::value_type> &constraints,
899 OutVector &z2);
900
901 /** @} */
902 /**
903 * The numbering of the degrees of freedom in continuous finite elements is
904 * hierarchic, i.e. in such a way that we first number the vertex dofs, in
905 * the order of the vertices as defined by the triangulation, then the line
906 * dofs in the order and respecting the direction of the lines, then the
907 * dofs on quads, etc. However, we could have, as well, numbered them in a
908 * lexicographic way, i.e. with indices first running in x-direction, then
909 * in y-direction and finally in z-direction. Discontinuous elements of
910 * class FE_DGQ() are numbered in this way, for example.
911 *
912 * This function returns a vector containing information about the
913 * lexicographic index each degree of freedom in the hierarchic numbering
914 * would have to a given degree of a continuous finite element.
915 */
916 template <int dim>
917 std::vector<unsigned int>
918 hierarchic_to_lexicographic_numbering(unsigned int degree);
919
920 /**
921 * This is the reverse function to the above one, generating the map from
922 * the lexicographic to the hierarchical numbering for a given polynomial
923 * degree of a continuous finite element. All the remarks made about the
924 * above function are also valid here.
925 */
926 template <int dim>
927 std::vector<unsigned int>
928 lexicographic_to_hierarchic_numbering(unsigned int degree);
929
930 /**
931 * Given the polynomial degree, direction, and numbering options, this
932 * function returns a pair of vectors mapping cell DoFs to face patch DoFs
933 * in lexicographic order.
934 *
935 * This function works for scalar finite elements, specifically those derived
936 * from FE_Q and FE_DGQ. It computes the mapping from the DoFs of
937 * two adjacent cells sharing a face perpendicular to @p direction in
938 * reference space, to the DoFs on the face patch. The result is a pair of
939 * vectors: the first for the DoFs on the first cell, the second for the
940 * DoFs on the second cell. The @p cell_hierarchical_numbering flag
941 * determines whether hierarchical or lexicographic numbering is assumed for
942 * the cell DoFs. The @p is_continuous flag indicates whether the finite
943 * element space is continuous (i.e., FE_Q).
944 *
945 * @param degree Polynomial degree of the finite element.
946 * @param direction Axis perpendicular to the considered face.
947 * @param cell_hierarchical_numbering If true, use hierarchical numbering for cell DoFs.
948 * @param is_continuous If true, assumes the finite element space is continuous (FE_Q).
949 * @return A pair of vectors mapping cell DoFs to face patch DoFs in lexicographic order.
950 */
951 template <int dim>
952 std::pair<std::vector<unsigned int>, std::vector<unsigned int>>
953 cell_to_face_patch(const unsigned int &degree,
954 const unsigned int &direction,
955 const bool &cell_hierarchical_numbering,
956 const bool &is_continuous);
957
958 /**
959 * A namespace that contains functions that help setting up internal
960 * data structures when implementing FiniteElement which are build
961 * from simpler ("base") elements, for example FESystem. The things
962 * computed by these functions typically serve as constructor
963 * arguments to the FiniteElement base class of the derived finite
964 * element object being constructed.
965 *
966 * There are generally two ways in which one can build more complex
967 * elements, and this is reflected by several of the functions in
968 * this namespace having arguments called
969 * <code>do_tensor_product</code>:
970 *
971 * <ol>
972 * <li> Tensor product construction (<code>do_tensor_product=true</code>):
973 * The tensor product construction, in the simplest case, builds a
974 * vector-valued element from scalar elements (see
975 * @ref vector_valued "this documentation topic"
976 * and
977 * @ref GlossComponent "this glossary entry"
978 * for more information).
979 * To give an example, consider creating a vector-valued element with
980 * two vector components, where the first should have linear shape
981 * functions and the second quadratic shape functions. In 1d, the
982 * shape functions (on the reference cell) of the base elements are then
983 * @f{align*}{
984 * Q_1 &= \{ 1-x, x \},
985 * \\ Q_2 &= \{ 2(\frac 12 - x)(1-x), 2(x - \frac 12)x, 4x(1-x) \},
986 * @f}
987 * where shape functions are ordered in the usual way (first on the
988 * first vertex, then on the second vertex, then in the interior of
989 * the cell). The tensor product construction will create an element with
990 * the following shape functions:
991 * @f{align*}{
992 * Q_1 \times Q_2 &=
993 * \left\{
994 * \begin{pmatrix} 1-x \\ 0 \end{pmatrix},
995 * \begin{pmatrix} 0 \\ 2(\frac 12 - x)(1-x) \end{pmatrix},
996 * \begin{pmatrix} x \\ 0 \end{pmatrix},
997 * \begin{pmatrix} 0 \\ 2(x - \frac 12)x \end{pmatrix},
998 * \begin{pmatrix} 0 \\ 4x(1-x) \end{pmatrix}
999 * \right\}.
1000 * @f}
1001 * The list here is again in standard order.
1002 *
1003 * Of course, the procedure also works if the base elements are
1004 * already vector valued themselves: in that case, the composed
1005 * element simply has as many vector components as the base elements
1006 * taken together.
1007 *
1008 * <li> Combining shape functions
1009 * (<code>do_tensor_product=false</code>): In contrast to the
1010 * previous strategy, combining shape functions simply takes
1011 * <i>all</i> of the shape functions together. In the case above,
1012 * this would yield the following element:
1013 * @f{align*}{
1014 * Q_1 + Q_2 &= \{ 1-x, 2(\frac 12 - x)(1-x),
1015 * x, 2(x - \frac 12)x, 4x(1-x) \}.
1016 * @f}
1017 * In other words, if the base elements are scalar, the resulting
1018 * element will also be. In general, the base elements all will
1019 * have to have the same number of vector components.
1020 *
1021 * The element constructed above of course no longer has a linearly
1022 * independent set of shape functions. As a consequence, any matrix
1023 * one creates by treating all shape functions of the composed
1024 * element in the same way will be singular. In practice, this
1025 * strategy is therefore typically used in situations where one
1026 * explicitly makes sure that certain shape functions are treated
1027 * differently (e.g., by multiplying them with weight functions), or
1028 * in cases where the shape functions one combines are not linearly
1029 * dependent.
1030 *
1031 * </ol>
1032 */
1033 namespace Compositing
1034 {
1035 /**
1036 * Take vectors of finite elements and multiplicities and multiply out
1037 * how many degrees of freedom the composed element has per vertex,
1038 * line, etc.
1039 *
1040 * If @p do_tensor_product is true, the number of components
1041 * returned in the FiniteElementData object is the sum over the
1042 * product of the number of components in each of the finite
1043 * elements times the corresponding multiplicity. Otherwise the
1044 * number of components is taken from the first finite element with
1045 * non-zero multiplicity, and all other elements with non-zero
1046 * multiplicities need to have the same number of vector components.
1047 *
1048 * See the documentation of namespace FETools::Compositing for more
1049 * information about the @p do_tensor_product argument.
1050 */
1051 template <int dim, int spacedim>
1052 FiniteElementData<dim>
1053 multiply_dof_numbers(
1054 const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1055 const std::vector<unsigned int> &multiplicities,
1056 const bool do_tensor_product = true);
1057
1058 /**
1059 * Same as above for an arbitrary number of parameters of type
1060 * <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned
1061 * int></code> and <code>do_tensor_product = true</code>.
1062 */
1063 template <int dim, int spacedim>
1064 FiniteElementData<dim>
1065 multiply_dof_numbers(
1066 const std::initializer_list<
1067 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1068 &fe_systems);
1069
1070 /**
1071 * Same as above but for a specific number of sub-elements.
1072 *
1073 * @deprecated Use the versions of this function that take a
1074 * vector of elements or an initializer list as arguments.
1075 */
1076 template <int dim, int spacedim>
1077 DEAL_II_DEPRECATED FiniteElementData<dim>
1078 multiply_dof_numbers(const FiniteElement<dim, spacedim> *fe1,
1079 const unsigned int N1,
1080 const FiniteElement<dim, spacedim> *fe2 = nullptr,
1081 const unsigned int N2 = 0,
1082 const FiniteElement<dim, spacedim> *fe3 = nullptr,
1083 const unsigned int N3 = 0,
1084 const FiniteElement<dim, spacedim> *fe4 = nullptr,
1085 const unsigned int N4 = 0,
1086 const FiniteElement<dim, spacedim> *fe5 = nullptr,
1087 const unsigned int N5 = 0);
1088
1089 /**
1090 * Compute the "restriction is additive" flags (see the
1091 * documentation of the FiniteElement class) for a list of finite
1092 * elements with multiplicities given in the second argument.
1093 *
1094 * The "restriction is additive" flags are properties of
1095 * individual shape functions that do not depend on whether the
1096 * composed element uses the tensor product or combination
1097 * strategy outlined in the documentation of the
1098 * FETools::Composition namespace. Consequently, this function
1099 * does not have a @p do_tensor_product argument.
1100 */
1101 template <int dim, int spacedim>
1102 std::vector<bool>
1103 compute_restriction_is_additive_flags(
1104 const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1105 const std::vector<unsigned int> &multiplicities);
1106
1107 /**
1108 * Same as above for an arbitrary number of parameters of type
1109 * <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned
1110 * int></code>.
1111 */
1112 template <int dim, int spacedim>
1113 std::vector<bool>
1114 compute_restriction_is_additive_flags(
1115 const std::initializer_list<
1116 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1117 &fe_systems);
1118
1119 /**
1120 * Take a @p FiniteElement object and return a boolean vector
1121 * describing the @p restriction_is_additive_flags (see the
1122 * documentation of the FiniteElement class) for each shape function
1123 * of the mixed element consisting of @p N1, @p N2, ... copies of
1124 * the sub-elements @p fe1, @p fe2, ...
1125 *
1126 * The "restriction is additive" flags are properties of
1127 * individual shape functions that do not depend on whether the
1128 * composed element uses the tensor product or combination
1129 * strategy outlined in the documentation of the
1130 * FETools::Composition namespace. Consequently, this function
1131 * does not have a @p do_tensor_product argument.
1132 *
1133 * @deprecated Use the versions of this function that take a
1134 * vector of elements or an initializer list as arguments.
1135 */
1136 template <int dim, int spacedim>
1137 DEAL_II_DEPRECATED std::vector<bool>
1138 compute_restriction_is_additive_flags(
1139 const FiniteElement<dim, spacedim> *fe1,
1140 const unsigned int N1,
1141 const FiniteElement<dim, spacedim> *fe2 = nullptr,
1142 const unsigned int N2 = 0,
1143 const FiniteElement<dim, spacedim> *fe3 = nullptr,
1144 const unsigned int N3 = 0,
1145 const FiniteElement<dim, spacedim> *fe4 = nullptr,
1146 const unsigned int N4 = 0,
1147 const FiniteElement<dim, spacedim> *fe5 = nullptr,
1148 const unsigned int N5 = 0);
1149
1150
1151 /**
1152 * Compute the nonzero components for each shape function of a
1153 * composed finite element described by a list of finite elements
1154 * with multiplicities given in the second argument.
1155 *
1156 * If @p do_tensor_product is true, the number of components (and
1157 * thus the size of the ComponentMask objects) is the sum over the
1158 * product of the number of components in each of the finite
1159 * elements times the corresponding multiplicity. Otherwise the
1160 * number of components is taken from the first finite element with
1161 * non-zero multiplicity, and all other elements with non-zero
1162 * multiplicities need to have the same number of vector components.
1163 *
1164 * See the documentation of namespace FETools::Compositing for more
1165 * information about the @p do_tensor_product argument.
1166 */
1167 template <int dim, int spacedim>
1168 std::vector<ComponentMask>
1169 compute_nonzero_components(
1170 const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1171 const std::vector<unsigned int> &multiplicities,
1172 const bool do_tensor_product = true);
1173
1174 /**
1175 * Same as above for an arbitrary number of parameters of type
1176 * <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned
1177 * int></code> and <code>do_tensor_product = true</code>.
1178 */
1179 template <int dim, int spacedim>
1180 std::vector<ComponentMask>
1181 compute_nonzero_components(
1182 const std::initializer_list<
1183 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1184 &fe_systems);
1185
1186 /**
1187 * Compute the non-zero vector components of a composed finite
1188 * element. This function is similar to the previous one, except
1189 * that the pointers indicate the elements to be composed, and the
1190 * arguments @p N1, @p N2, ... the multiplicities. Null pointers
1191 * indicate that an argument is to be skipped.
1192 *
1193 * If @p do_tensor_product is true, the number of components (and
1194 * thus the size of the ComponentMask objects) is the sum over the
1195 * product of the number of components in each of the finite
1196 * elements times the corresponding multiplicity. Otherwise the
1197 * number of components is taken from the first finite element with
1198 * non-zero multiplicity, and all other elements with non-zero
1199 * multiplicities need to have the same number of vector components.
1200 *
1201 * See the documentation of namespace FETools::Compositing for more
1202 * information about the @p do_tensor_product argument.
1203 *
1204 * @deprecated Use the versions of this function that take a
1205 * vector of elements or an initializer list as arguments.
1206 */
1207 template <int dim, int spacedim>
1208 DEAL_II_DEPRECATED std::vector<ComponentMask>
1209 compute_nonzero_components(
1210 const FiniteElement<dim, spacedim> *fe1,
1211 const unsigned int N1,
1212 const FiniteElement<dim, spacedim> *fe2 = nullptr,
1213 const unsigned int N2 = 0,
1214 const FiniteElement<dim, spacedim> *fe3 = nullptr,
1215 const unsigned int N3 = 0,
1216 const FiniteElement<dim, spacedim> *fe4 = nullptr,
1217 const unsigned int N4 = 0,
1218 const FiniteElement<dim, spacedim> *fe5 = nullptr,
1219 const unsigned int N5 = 0,
1220 const bool do_tensor_product = true);
1221
1222 /**
1223 * For a given (composite) @p finite_element build @p
1224 * system_to_component_table, @p system_to_base_table and @p
1225 * component_to_base_table.
1226 *
1227 * If @p do_tensor_product is true, the number of components
1228 * used for the composite element is the sum over the
1229 * product of the number of components in each of the finite
1230 * elements times the corresponding multiplicity. Otherwise the
1231 * number of components is taken from the first finite element with
1232 * non-zero multiplicity, and all other elements with non-zero
1233 * multiplicities need to have the same number of vector components.
1234 *
1235 * See the documentation of namespace FETools::Compositing for more
1236 * information about the @p do_tensor_product argument.
1237 */
1238 template <int dim, int spacedim>
1239 void
1240 build_cell_tables(
1241 std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1242 unsigned int>> &system_to_base_table,
1243 std::vector<std::pair<unsigned int, unsigned int>>
1244 &system_to_component_table,
1245 std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1246 unsigned int>> &component_to_base_table,
1247 const FiniteElement<dim, spacedim> &finite_element,
1248 const bool do_tensor_product = true);
1249
1250 /**
1251 * For a given (composite) @p finite_element build @p face_system_to_base_table,
1252 * and @p face_system_to_component_table.
1253 *
1254 * If @p do_tensor_product is true, the number of components
1255 * used for the composite element is the sum over the
1256 * product of the number of components in each of the finite
1257 * elements times the corresponding multiplicity. Otherwise the
1258 * number of components is taken from the first finite element with
1259 * non-zero multiplicity, and all other elements with non-zero
1260 * multiplicities need to have the same number of vector components.
1261 *
1262 * See the documentation of namespace FETools::Compositing for more
1263 * information about the @p do_tensor_product argument.
1264 */
1265 template <int dim, int spacedim>
1266 void
1267 build_face_tables(
1268 std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1269 unsigned int>> &face_system_to_base_table,
1270 std::vector<std::pair<unsigned int, unsigned int>>
1271 &face_system_to_component_table,
1272 const FiniteElement<dim, spacedim> &finite_element,
1273 const bool do_tensor_product = true,
1274 const unsigned int face_no = 0 /*TODO*/);
1275
1276 } // namespace Compositing
1277
1278
1279 /**
1280 * Parse the name of a finite element and generate a finite element object
1281 * accordingly. The parser ignores space characters between words (things
1282 * matching the regular expression [A-Za-z0-9_]).
1283 *
1284 * The name must be in the form which is returned by the
1285 * FiniteElement::get_name function, where dimension template parameters
1286 * &lt;2&gt; etc. can be omitted. Alternatively, the explicit number can be
1287 * replaced by <tt>dim</tt> or <tt>d</tt>. If a number is given, it
1288 * <b>must</b> match the template parameter of this function.
1289 *
1290 * The names of FESystem elements follow the pattern
1291 * <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code> The powers <code>p1</code>
1292 * etc. may either be numbers or can be replaced by <tt>dim</tt> or
1293 * <tt>d</tt>.
1294 *
1295 *
1296 * If no finite element can be reconstructed from this string, an exception
1297 * of type @p FETools::ExcInvalidFEName is thrown.
1298 *
1299 * The function returns a std::unique_ptr to a newly created finite element
1300 * meaning the caller obtains ownership over the returned object.
1301 *
1302 * Since the value of the template argument can't be deduced from the
1303 * (string) argument given to this function, you have to explicitly specify
1304 * it when you call this function.
1305 *
1306 * This function knows about all the standard elements defined in the
1307 * library. However, it doesn't by default know about elements that you may
1308 * have defined in your program. To make your own elements known to this
1309 * function, use the add_fe_name() function. This function does not work if
1310 * one wants to get a codimension 1 finite element.
1311 */
1312 template <int dim, int spacedim = dim>
1313 std::unique_ptr<FiniteElement<dim, spacedim>>
1314 get_fe_by_name(const std::string &name);
1315
1316 /**
1317 * Extend the list of finite elements that can be generated by
1318 * get_fe_by_name() by the one given as @p name. If get_fe_by_name() is
1319 * later called with this name, it will use the object given as second
1320 * argument to create a finite element object.
1321 *
1322 * The format of the @p name parameter should include the name of a finite
1323 * element. However, it is safe to use either the class name alone or to use
1324 * the result of FiniteElement::get_name (which includes the space dimension
1325 * as well as the polynomial degree), since everything after the first
1326 * non-name character will be ignored.
1327 *
1328 * The FEFactory object should be an object newly created with <tt>new</tt>.
1329 * FETools will take ownership of this object and delete it once it is not
1330 * used anymore.
1331 *
1332 * In most cases, if you want objects of type <code>MyFE</code> be created
1333 * whenever the name <code>my_fe</code> is given to get_fe_by_name, you
1334 * will want the second argument to this function be of type
1335 * FEFactory@<MyFE@>, but you can of course create your custom finite
1336 * element factory class.
1337 *
1338 * This function takes over ownership of the object given as second
1339 * argument, i.e. you should never attempt to destroy it later on. The
1340 * object will be deleted at the end of the program's lifetime.
1341 *
1342 * If the name of the element is already in use, an exception is thrown.
1343 * Thus, functionality of get_fe_by_name() can only be added, not changed.
1344 *
1345 * @note This function manipulates a global table (one table for each space
1346 * dimension). It is thread safe in the sense that every access to this
1347 * table is secured by a lock. Nevertheless, since each name can be added
1348 * only once, user code has to make sure that only one thread adds a new
1349 * element.
1350 *
1351 * Note also that this table exists once for each space dimension. If you
1352 * have a program that works with finite elements in different space
1353 * dimensions (for example,
1354 * @ref step_4 "step-4"
1355 * does something like this), then you should call this function for each
1356 * space dimension for which you want your finite element added to the map.
1357 */
1358 template <int dim, int spacedim>
1359 void
1360 add_fe_name(const std::string &name,
1361 const FEFactoryBase<dim, spacedim> *factory);
1362
1363 /**
1364 * The string used for get_fe_by_name() cannot be translated to a finite
1365 * element.
1366 *
1367 * Either the string is badly formatted or you are using a custom element
1368 * that must be added using add_fe_name() first.
1369 *
1370 * @ingroup Exceptions
1371 */
1372 DeclException1(ExcInvalidFEName,
1373 std::string,
1374 << "Can't re-generate a finite element from the string '"
1375 << arg1 << "'.");
1376
1377 /**
1378 * The string used for get_fe_by_name() cannot be translated to a finite
1379 * element.
1380 *
1381 * Dimension arguments in finite element names should be avoided. If they
1382 * are there, the dimension should be <tt>dim</tt> or <tt>d</tt>. Here, you
1383 * gave a numeric dimension argument, which does not match the template
1384 * dimension of the finite element class.
1385 *
1386 * @ingroup Exceptions
1387 */
1388 DeclException2(ExcInvalidFEDimension,
1389 char,
1390 int,
1391 << "The dimension " << arg1
1392 << " in the finite element string must match "
1393 << "the space dimension " << arg2 << '.');
1394
1395 /**
1396 * Exception
1397 *
1398 * @ingroup Exceptions
1399 */
1400 DeclException0(ExcInvalidFE);
1401
1402 /**
1403 * The finite element must be
1404 * @ref GlossPrimitive "primitive".
1405 *
1406 * @ingroup Exceptions
1407 */
1408 DeclException0(ExcFENotPrimitive);
1409 /**
1410 * Exception
1411 *
1412 * @ingroup Exceptions
1413 */
1414 DeclException0(ExcTriangulationMismatch);
1415
1416 /**
1417 * A continuous element is used on a mesh with hanging nodes, but the
1418 * constraint matrices are missing.
1419 *
1420 * @ingroup Exceptions
1421 */
1422 DeclExceptionMsg(ExcHangingNodesNotAllowed,
1423 "You are using continuous elements on a grid with "
1424 "hanging nodes but without providing hanging node "
1425 "constraints. Use the respective function with "
1426 "additional AffineConstraints argument(s), instead.");
1427 /**
1428 * You need at least two grid levels.
1429 *
1430 * @ingroup Exceptions
1431 */
1432 DeclException0(ExcGridNotRefinedAtLeastOnce);
1433 /**
1434 * The dimensions of the matrix used did not match the expected dimensions.
1435 *
1436 * @ingroup Exceptions
1437 */
1438 DeclException4(ExcMatrixDimensionMismatch,
1439 int,
1440 int,
1441 int,
1442 int,
1443 << "This is a " << arg1 << 'x' << arg2 << " matrix, "
1444 << "but should be a " << arg3 << 'x' << arg4 << " matrix.");
1445
1446 /**
1447 * Exception thrown if an embedding matrix was computed inaccurately.
1448 *
1449 * @ingroup Exceptions
1450 */
1451 DeclException1(ExcLeastSquaresError,
1452 double,
1453 << "Least squares fit leaves a gap of " << arg1);
1454
1455 /**
1456 * Exception thrown if one variable may not be greater than another.
1457 *
1458 * @ingroup Exceptions
1459 */
1460 DeclException2(ExcNotGreaterThan,
1461 int,
1462 int,
1463 << arg1 << " must be greater than " << arg2);
1464 } // namespace FETools
1465
1466
1467 #ifndef DOXYGEN
1468
1469 namespace FETools
1470 {
1471 template <class FE>
1472 std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
1473 FEFactory<FE>::get(const unsigned int degree) const
1474 {
1475 return std::make_unique<FE>(degree);
1476 }
1477
1478 namespace Compositing
1479 {
1480 template <int dim, int spacedim>
1481 std::vector<bool>
1482 compute_restriction_is_additive_flags(
1483 const std::initializer_list<
1484 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1485 &fe_systems)
1486 {
1487 std::vector<const FiniteElement<dim, spacedim> *> fes;
1488 std::vector<unsigned int> multiplicities;
1489
1490 const auto extract =
1491 [&fes, &multiplicities](
1492 const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1493 unsigned int> &fe_system) {
1494 fes.push_back(fe_system.first.get());
1495 multiplicities.push_back(fe_system.second);
1496 };
1497
1498 for (const auto &p : fe_systems)
1499 extract(p);
1500
1501 return compute_restriction_is_additive_flags(fes, multiplicities);
1502 }
1503
1504
1505
1506 template <int dim, int spacedim>
1507 FiniteElementData<dim>
1508 multiply_dof_numbers(
1509 const std::initializer_list<
1510 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1511 &fe_systems)
1512 {
1513 std::vector<const FiniteElement<dim, spacedim> *> fes;
1514 std::vector<unsigned int> multiplicities;
1515
1516 const auto extract =
1517 [&fes, &multiplicities](
1518 const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1519 unsigned int> &fe_system) {
1520 fes.push_back(fe_system.first.get());
1521 multiplicities.push_back(fe_system.second);
1522 };
1523
1524 for (const auto &p : fe_systems)
1525 extract(p);
1526
1527 return multiply_dof_numbers(fes, multiplicities, true);
1528 }
1529
1530
1531
1532 template <int dim, int spacedim>
1533 std::vector<ComponentMask>
1534 compute_nonzero_components(
1535 const std::initializer_list<
1536 std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1537 &fe_systems)
1538 {
1539 std::vector<const FiniteElement<dim, spacedim> *> fes;
1540 std::vector<unsigned int> multiplicities;
1541
1542 const auto extract =
1543 [&fes, &multiplicities](
1544 const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1545 unsigned int> &fe_system) {
1546 fes.push_back(fe_system.first.get());
1547 multiplicities.push_back(fe_system.second);
1548 };
1549
1550 for (const auto &p : fe_systems)
1551 extract(p);
1552
1553 return compute_nonzero_components(fes, multiplicities, true);
1554 }
1555 } // namespace Compositing
1556 } // namespace FETools
1557
1558 #endif
1559
1560 /** @} */
1561
1562 DEAL_II_NAMESPACE_CLOSE
1563
1564 #endif /* dealii_fe_tools_H */