Debian Codegraph @

include/deal.II/fe/fe_poly_tensor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2005 - 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_poly_tensor_h
16 #define dealii_fe_poly_tensor_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/derivative_form.h>
22 #include <deal.II/base/mutex.h>
23 #include <deal.II/base/qprojector.h>
24 #include <deal.II/base/quadrature.h>
25 #include <deal.II/base/tensor_polynomials_base.h>
26
27 #include <deal.II/fe/fe.h>
28
29 #include <deal.II/lac/full_matrix.h>
30
31 #include <memory>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 /**
36 * This class provides a unified framework for the implementation of
37 * FiniteElement classes based on tensor-valued polynomial spaces like
38 * PolynomialsBDM and PolynomialsRaviartThomas. In this, it is the
39 * tensor-valued equivalent of the FE_Poly class.
40 *
41 * In essence, what this class requires is that a derived class describes
42 * to it a (vector-valued) polynomial space in which every polynomial
43 * has exactly @p dim vector components. The classes that provide such
44 * implementations are all derived from the TensorPolynomialsBase
45 * class, and an object of one of these derived types needs to be
46 * provided to the constructor of this class.
47 *
48 *
49 * <h3>Deriving classes</h3>
50 *
51 * This class is not a fully implemented FiniteElement class, but implements
52 * some common features of vector valued elements based on vector valued
53 * polynomial classes. What's missing here in particular is information on the
54 * topological location of the node values (i.e., whether a degree of freedom
55 * is logically at a vertex, edge, face, or the interior of a cell --
56 * information that determines the continuity properties of the associated
57 * shape functions across cell interfaces), and derived classes need to provide
58 * this information.
59 *
60 * Similarly, in many cases, node functionals depend on the shape of the mesh
61 * cell, since they evaluate normal or tangential components on the faces. In
62 * order to allow for a set of transformations, the variable #mapping_kind has
63 * been introduced. It needs be set in the constructor of a derived
64 * class.
65 *
66 * Any derived class must decide on the polynomial space to use. This
67 * polynomial space should be implemented simply as a set of vector valued
68 * polynomials like PolynomialsBDM and PolynomialsRaviartThomas. In order to
69 * facilitate this implementation, which basis the polynomial space chooses
70 * is not of importance to the current class -- as described next, this class
71 * handles the transformation from the basis chosen by the polynomial space
72 * template argument to the basis we want to use for finite element
73 * computations internally.
74 *
75 *
76 * <h4>Determining the correct basis</h4>
77 *
78 * In most cases, the basis used by the class that describes the polynomial
79 * space, $\{\tilde\varphi_j(\hat{\mathbf x})\}$, does not match the one we
80 * want to use for the finite element description,
81 * $\{\varphi_j(\hat{\mathbf x})\}$. Rather, we need to express the finite
82 * element shape functions as a linear combination of the basis provided
83 * by the polynomial space:
84 * @f{align*}{
85 * \varphi_j = \sum_k c_{jk} \tilde\varphi_j.
86 * @f}
87 * These expansion coefficients $c_{jk}$ are typically computed in the
88 * constructors of derived classes. To facilitate this, this class
89 * at first (unless told otherwise, see below), assumes that the shape
90 * functions should be exactly the ones provided by the polynomial
91 * space. In the constructor of the derived class, one then typically has
92 * code of the form
93 * @code
94 * // Now compute the inverse node matrix, generating the correct
95 * // basis functions from the raw ones. For a discussion of what
96 * // exactly happens here, see FETools::compute_node_matrix.
97 * const FullMatrix<double> M = FETools::compute_node_matrix(*this);
98 * this->inverse_node_matrix.reinit(n_dofs, n_dofs);
99 * this->inverse_node_matrix.invert(M);
100 * // From now on, the shape functions provided by FiniteElement::shape_value
101 * // and similar functions will be the correct ones, not
102 * // the raw shape functions from the polynomial space anymore.
103 * @endcode
104 * The FETools::compute_node_matrix() function explains in more
105 * detail what exactly it computes, and how; in any case, the result
106 * is that @p inverse_node_matrix now contains the expansion coefficients
107 * $c_{jk}$, and the fact that this block of code now sets the
108 * matrix to a non-zero size indicates to the functions of the current
109 * class that it should from then on use the expanded basis,
110 * $\{\varphi_j(\hat{\mathbf x})\}$, and no longer the original, "raw"
111 * basis $\{\tilde\varphi_j(\hat{\mathbf x})\}$ when asked for values
112 * or derivatives of shape functions.
113 *
114 * In order for this scheme to work, it is important to ensure that
115 * the size of the @p inverse_node_matrix be zero at the time when
116 * FETools::compute_node_matrix() is called; thus, the call to this
117 * function cannot be inlined into the last line -- the result of
118 * the call really does need to be stored in the temporary object
119 * @p M.
120 *
121 *
122 * <h4>Setting the transformation</h4>
123 *
124 * In most cases, vector valued basis functions must be transformed when
125 * mapped from the reference cell to the actual grid cell. These
126 * transformations can be selected from the set MappingKind and stored in
127 * #mapping_kind. Therefore, each constructor should contain a line like:
128 * @code
129 * this->mapping_kind = {mapping_none};
130 * @endcode
131 * (in case no mapping is required) or using whatever value among
132 * the ones defined in MappingKind is appropriate for the element you
133 * are implementing. If each shape function may be mapped by different
134 * mappings, then @p mapping_kind may be a vector with the same number
135 * of elements as there are shape functions.
136 *
137 * @see TensorPolynomialsBase
138 * @ingroup febase
139 */
140 template <int dim, int spacedim = dim>
141 class FE_PolyTensor : public FiniteElement<dim, spacedim>
142 {
143 public:
144 /**
145 * Constructor. This constructor does a deep copy of the polynomials
146 * object via the TensorPolynomialsBase::clone() function and stores
147 * a pointer to the copy. As a consequence, the calling site can
148 * simply pass a temporary object as the first argument.
149 */
150 FE_PolyTensor(const TensorPolynomialsBase<dim> &polynomials,
151 const FiniteElementData<dim> &fe_data,
152 const std::vector<bool> &restriction_is_additive_flags,
153 const std::vector<ComponentMask> &nonzero_components);
154
155
156 /**
157 * Copy constructor.
158 */
159 FE_PolyTensor(const FE_PolyTensor &fe);
160
161 // for documentation, see the FiniteElement base class
162 virtual UpdateFlags
163 requires_update_flags(const UpdateFlags update_flags) const override;
164
165 /**
166 * Compute the (scalar) value of shape function @p i at the given quadrature
167 * point @p p. Since the elements represented by this class are vector
168 * valued, there is no such scalar value and the function therefore throws
169 * an exception.
170 */
171 virtual double
172 shape_value(const unsigned int i, const Point<dim> &p) const override;
173
174 // documentation inherited from the base class
175 virtual double
176 shape_value_component(const unsigned int i,
177 const Point<dim> &p,
178 const unsigned int component) const override;
179
180 /**
181 * Compute the gradient of (scalar) shape function @p i at the given
182 * quadrature point @p p. Since the elements represented by this class are
183 * vector valued, there is no such scalar value and the function therefore
184 * throws an exception.
185 */
186 virtual Tensor<1, dim>
187 shape_grad(const unsigned int i, const Point<dim> &p) const override;
188
189 // documentation inherited from the base class
190 virtual Tensor<1, dim>
191 shape_grad_component(const unsigned int i,
192 const Point<dim> &p,
193 const unsigned int component) const override;
194
195 /**
196 * Compute the Hessian of (scalar) shape function @p i at the given
197 * quadrature point @p p. Since the elements represented by this class are
198 * vector valued, there is no such scalar value and the function therefore
199 * throws an exception.
200 */
201 virtual Tensor<2, dim>
202 shape_grad_grad(const unsigned int i, const Point<dim> &p) const override;
203
204 // documentation inherited from the base class
205 virtual Tensor<2, dim>
206 shape_grad_grad_component(const unsigned int i,
207 const Point<dim> &p,
208 const unsigned int component) const override;
209
210 protected:
211 #ifndef DOXYGEN
212 class InternalData;
213 #endif
214
215 /**
216 * Internal function called by fill_fe_values(), fill_fe_face_values(),
217 * and fill_fe_subface_values().
218 */
219 void
220 compute_fill(
221 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
222 const typename QProjector<dim>::DataSetDescriptor &offset,
223 const unsigned int n_q_points,
224 const Mapping<dim, spacedim> &mapping,
225 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
226 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
227 &mapping_data,
228 const typename FE_PolyTensor<dim, spacedim>::InternalData &fe_internal,
229 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
230 &output_data) const;
231
232 /**
233 * The mapping type to be used to map shape functions from the reference
234 * cell to the mesh cell. If this vector is length one, the same mapping
235 * will be applied to all shape functions. If the vector size is equal to
236 * the finite element dofs per cell, then each shape function will be mapped
237 * according to the corresponding entry in the vector.
238 */
239 std::vector<MappingKind> mapping_kind;
240
241 /**
242 * Returns a boolean that is true when the finite element uses a single
243 * mapping and false when the finite element uses multiple mappings.
244 */
245 bool
246 single_mapping_kind() const;
247
248 /**
249 * For faces with non-standard face_orientation in 3d, the dofs on faces
250 * (quads) have to be permuted in order to be combined with the correct shape
251 * functions and additionally can change the sign. Given a local dof @p index
252 * on a quad, return the sign of the permuted shape function.
253 *
254 * The permutation itself is returned by
255 * adjust_quad_dof_index_for_face_orientation implemented in the interface
256 * class FiniteElement<dim>.
257 */
258 bool
259 adjust_quad_dof_sign_for_face_orientation(
260 const unsigned int index,
261 const unsigned int face_no,
262 const types::geometric_orientation combined_orientation) const;
263
264 /**
265 * For faces with non-standard face_orientation in 3d, the dofs on faces
266 * (quads) need not only to be permuted in order to be combined with the
267 * correct shape functions. Additionally they may change their sign.
268 *
269 * The constructor of this class fills this table with 'false' values, i.e.,
270 * no sign change at all. Derived finite element classes have to
271 * fill this Table with the correct values, see the documentation in
272 * GeometryInfo<dim> and this
273 * @ref GlossCombinedOrientation "glossary entry on face orientations".
274 *
275 * The table must be filled in finite element classes derived
276 * from FE_PolyTensor in a meaningful way since the permutation
277 * pattern and the pattern of sign changes depends on how the finite element
278 * distributes the local dofs on the faces. An example is the function
279 * `initialize_quad_dof_index_permutation_and_sign_change()` in the
280 * FE_RaviartThomas class that fills this table.
281 */
282 std::vector<Table<2, bool>> adjust_quad_dof_sign_for_face_orientation_table;
283
284 /**
285 * Returns MappingKind @p i for the finite element.
286 */
287 MappingKind
288 get_mapping_kind(const unsigned int i) const;
289
290 /* NOTE: The following function has its definition inlined into the class
291 declaration because we otherwise run into a compiler error with MS Visual
292 Studio. */
293 virtual std::unique_ptr<
294 typename FiniteElement<dim, spacedim>::InternalDataBase>
295 get_data(
296 const UpdateFlags update_flags,
297 const Mapping<dim, spacedim> &mapping,
298 const Quadrature<dim> &quadrature,
299 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
300 spacedim>
301 &output_data) const override
302 {
303 (void)mapping;
304 (void)output_data;
305 // generate a new data object and
306 // initialize some fields
307 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>
308 data_ptr = std::make_unique<InternalData>();
309 auto &data = dynamic_cast<InternalData &>(*data_ptr);
310 data.update_each = requires_update_flags(update_flags);
311
312 const unsigned int n_q_points = quadrature.size();
313
314 // some scratch arrays
315 std::vector<Tensor<1, dim>> values(0);
316 std::vector<Tensor<2, dim>> grads(0);
317 std::vector<Tensor<3, dim>> grad_grads(0);
318 std::vector<Tensor<4, dim>> third_derivatives(0);
319 std::vector<Tensor<5, dim>> fourth_derivatives(0);
320
321 if (update_flags & (update_values | update_gradients | update_hessians))
322 data.dof_sign_change.resize(this->dofs_per_cell);
323
324 // initialize fields only if really
325 // necessary. otherwise, don't
326 // allocate memory
327
328 const bool update_transformed_shape_values =
329 std::any_of(this->mapping_kind.begin(),
330 this->mapping_kind.end(),
331 [](const MappingKind t) { return t != mapping_none; });
332
333 const bool update_transformed_shape_grads =
334 std::any_of(this->mapping_kind.begin(),
335 this->mapping_kind.end(),
336 [](const MappingKind t) {
337 return (t == mapping_raviart_thomas || t == mapping_piola ||
338 t == mapping_nedelec || t == mapping_contravariant);
339 });
340
341 const bool update_transformed_shape_hessian_tensors =
342 update_transformed_shape_values;
343
344 if (update_flags & update_values)
345 {
346 values.resize(this->n_dofs_per_cell());
347 data.shape_values.reinit(this->n_dofs_per_cell(), n_q_points);
348 if (update_transformed_shape_values)
349 data.transformed_shape_values.resize(n_q_points);
350 }
351
352 if (update_flags & update_gradients)
353 {
354 grads.resize(this->n_dofs_per_cell());
355 data.shape_grads.reinit(this->n_dofs_per_cell(), n_q_points);
356 data.transformed_shape_grads.resize(n_q_points);
357
358 if (update_transformed_shape_grads)
359 data.untransformed_shape_grads.resize(n_q_points);
360 }
361
362 if (update_flags & update_hessians)
363 {
364 grad_grads.resize(this->n_dofs_per_cell());
365 data.shape_grad_grads.reinit(this->n_dofs_per_cell(), n_q_points);
366 data.transformed_shape_hessians.resize(n_q_points);
367 if (update_transformed_shape_hessian_tensors)
368 data.untransformed_shape_hessian_tensors.resize(n_q_points);
369 }
370
371 // Compute shape function values
372 // and derivatives and hessians on
373 // the reference cell.
374 // Make sure, that for the
375 // node values N_i holds
376 // N_i(v_j)=\delta_ij for all basis
377 // functions v_j
378 if (update_flags & (update_values | update_gradients))
379 for (unsigned int k = 0; k < n_q_points; ++k)
380 {
381 poly_space->evaluate(quadrature.point(k),
382 values,
383 grads,
384 grad_grads,
385 third_derivatives,
386 fourth_derivatives);
387
388 if (update_flags & update_values)
389 {
390 if (inverse_node_matrix.n_cols() == 0)
391 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
392 data.shape_values[i][k] = values[i];
393 else
394 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
395 {
396 Tensor<1, dim> add_values;
397 for (unsigned int j = 0; j < this->n_dofs_per_cell(); ++j)
398 add_values += inverse_node_matrix(j, i) * values[j];
399 data.shape_values[i][k] = add_values;
400 }
401 }
402
403 if (update_flags & update_gradients)
404 {
405 if (inverse_node_matrix.n_cols() == 0)
406 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
407 data.shape_grads[i][k] = grads[i];
408 else
409 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
410 {
411 Tensor<2, dim> add_grads;
412 for (unsigned int j = 0; j < this->n_dofs_per_cell(); ++j)
413 add_grads += inverse_node_matrix(j, i) * grads[j];
414 data.shape_grads[i][k] = add_grads;
415 }
416 }
417
418 if (update_flags & update_hessians)
419 {
420 if (inverse_node_matrix.n_cols() == 0)
421 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
422 data.shape_grad_grads[i][k] = grad_grads[i];
423 else
424 for (unsigned int i = 0; i < this->n_dofs_per_cell(); ++i)
425 {
426 Tensor<3, dim> add_grad_grads;
427 for (unsigned int j = 0; j < this->n_dofs_per_cell(); ++j)
428 add_grad_grads +=
429 inverse_node_matrix(j, i) * grad_grads[j];
430 data.shape_grad_grads[i][k] = add_grad_grads;
431 }
432 }
433 }
434 return data_ptr;
435 }
436
437 virtual void
438 fill_fe_values(
439 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
440 const CellSimilarity::Similarity cell_similarity,
441 const Quadrature<dim> &quadrature,
442 const Mapping<dim, spacedim> &mapping,
443 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
444 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
445 &mapping_data,
446 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
447 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
448 spacedim>
449 &output_data) const override;
450
451 using FiniteElement<dim, spacedim>::fill_fe_face_values;
452
453 virtual void
454 fill_fe_face_values(
455 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
456 const unsigned int face_no,
457 const hp::QCollection<dim - 1> &quadrature,
458 const Mapping<dim, spacedim> &mapping,
459 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
460 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
461 &mapping_data,
462 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
463 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
464 spacedim>
465 &output_data) const override;
466
467 virtual void
468 fill_fe_subface_values(
469 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
470 const unsigned int face_no,
471 const unsigned int sub_no,
472 const Quadrature<dim - 1> &quadrature,
473 const Mapping<dim, spacedim> &mapping,
474 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
475 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
476 &mapping_data,
477 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
478 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
479 spacedim>
480 &output_data) const override;
481
482 /**
483 * Fields of cell-independent data for FE_PolyTensor. Stores the values of
484 * the shape functions and their derivatives on the reference cell for later
485 * use.
486 *
487 * All tables are organized in a way, that the value for shape function
488 * <i>i</i> at quadrature point <i>k</i> is accessed by indices
489 * <i>(i,k)</i>.
490 */
491 class InternalData : public FiniteElement<dim, spacedim>::InternalDataBase
492 {
493 public:
494 /**
495 * Array with shape function values in quadrature points. There is one row
496 * for each shape function, containing values for each quadrature point.
497 */
498 Table<2, Tensor<1, dim>> shape_values;
499
500 /**
501 * Array with shape function gradients in quadrature points. There is one
502 * row for each shape function, containing values for each quadrature
503 * point.
504 */
505 Table<2, DerivativeForm<1, dim, spacedim>> shape_grads;
506
507 /**
508 * Array with shape function hessians in quadrature points. There is one
509 * row for each shape function, containing values for each quadrature
510 * point.
511 */
512 Table<2, DerivativeForm<2, dim, spacedim>> shape_grad_grads;
513
514 /**
515 * Scratch arrays for intermediate computations
516 */
517 mutable std::vector<double> dof_sign_change;
518 mutable std::vector<Tensor<1, spacedim>> transformed_shape_values;
519 // for shape_gradient computations
520 mutable std::vector<Tensor<2, spacedim>> transformed_shape_grads;
521 mutable std::vector<Tensor<2, dim>> untransformed_shape_grads;
522 // for shape_hessian computations
523 mutable std::vector<Tensor<3, spacedim>> transformed_shape_hessians;
524 mutable std::vector<Tensor<3, dim>> untransformed_shape_hessian_tensors;
525 };
526
527
528
529 /**
530 * A copy of the object passed to the constructor that describes the
531 * polynomial space.
532 */
533 const std::unique_ptr<const TensorPolynomialsBase<dim>> poly_space;
534
535 /**
536 * The inverse of the matrix <i>a<sub>ij</sub></i> of node functionals
537 * <i>N<sub>i</sub></i> applied to polynomial <i>p<sub>j</sub></i>. This
538 * matrix is used to convert polynomials in the "raw" basis provided in
539 * #poly_space to the basis dual to the node functionals on the reference
540 * cell.
541 *
542 * This object is not filled by FE_PolyTensor, but is a chance for a derived
543 * class to allow for reorganization of the basis functions. If it is left
544 * empty, the basis in #poly_space is used, i.e., it is assumed that
545 * #poly_space already satisfies the Kronecker delta property with
546 * regard to the node functionals.
547 */
548 FullMatrix<double> inverse_node_matrix;
549
550 /**
551 * A mutex to be used to guard access to the variables below.
552 */
553 mutable Threads::Mutex cache_mutex;
554
555 /**
556 * If a shape function is computed at a single point, we must compute all of
557 * them to apply #inverse_node_matrix. In order to avoid too much overhead,
558 * we cache the point and the function values for the next evaluation.
559 */
560 mutable Point<dim> cached_point;
561
562 /**
563 * Cached shape function values after call to shape_value_component().
564 */
565 mutable std::vector<Tensor<1, dim>> cached_values;
566
567 /**
568 * Cached shape function gradients after call to shape_grad_component().
569 */
570 mutable std::vector<Tensor<2, dim>> cached_grads;
571
572 /**
573 * Cached second derivatives of shape functions after call to
574 * shape_grad_grad_component().
575 */
576 mutable std::vector<Tensor<3, dim>> cached_grad_grads;
577 };
578
579 DEAL_II_NAMESPACE_CLOSE
580
581 #endif