Debian Codegraph @

include/deal.II/fe/fe_poly.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_fe_poly_h
16 #define dealii_fe_poly_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/quadrature.h>
22 #include <deal.II/base/scalar_polynomials_base.h>
23
24 #include <deal.II/fe/fe.h>
25
26 #include <memory>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 /**
31 * @addtogroup fe
32 * @{
33 */
34
35 /**
36 * This class gives a unified framework for the implementation of
37 * FiniteElement classes based on scalar polynomial spaces like the
38 * TensorProductPolynomials or PolynomialSpace classes. This
39 * class has a corresponding class for tensor-valued finite
40 * elements in the FE_PolyTensor class.
41 *
42 * Every class that has the following public member variables and
43 * functions can be used as template parameter @p PolynomialType.
44 *
45 * @code
46 * static constexpr unsigned int dimension;
47 *
48 * void evaluate (const Point<dim> &unit_point,
49 * std::vector<double> &values,
50 * std::vector<Tensor<1,dim> > &grads,
51 * std::vector<Tensor<2,dim> > &grad_grads,
52 * std::vector<Tensor<3,dim> > &third_derivatives,
53 * std::vector<Tensor<4,dim> > &fourth_derivatives) const;
54 *
55 * double compute_value (const unsigned int i,
56 * const Point<dim> &p) const;
57 *
58 * template <int order>
59 * Tensor<order,dim> compute_derivative (const unsigned int i,
60 * const Point<dim> &p) const;
61 * @endcode
62 * Example classes are TensorProductPolynomials, PolynomialSpace or
63 * PolynomialsP.
64 *
65 * This class is not a fully implemented FiniteElement class. Instead there
66 * are several pure virtual functions declared in the FiniteElement and
67 * FiniteElement classes which cannot be implemented by this class but are
68 * left for implementation in derived classes.
69 *
70 * @todo Since nearly all functions for spacedim != dim are specialized, this
71 * class needs cleaning up.
72 */
73
74 template <int dim, int spacedim = dim>
75 class FE_Poly : public FiniteElement<dim, spacedim>
76 {
77 public:
78 /**
79 * Constructor.
80 */
81 FE_Poly(const ScalarPolynomialsBase<dim> &poly_space,
82 const FiniteElementData<dim> &fe_data,
83 const std::vector<bool> &restriction_is_additive_flags,
84 const std::vector<ComponentMask> &nonzero_components);
85
86 /**
87 * Copy constructor.
88 */
89 FE_Poly(const FE_Poly &fe);
90
91 /**
92 * Return the polynomial degree of this finite element, i.e. the value
93 * passed to the constructor.
94 */
95 unsigned int
96 get_degree() const;
97
98 // for documentation, see the FiniteElement base class
99 virtual UpdateFlags
100 requires_update_flags(const UpdateFlags update_flags) const override;
101
102 /**
103 * Return the underlying polynomial space.
104 */
105 const ScalarPolynomialsBase<dim> &
106 get_poly_space() const;
107
108 /**
109 * Return the numbering of the underlying polynomial space compared to
110 * lexicographic ordering of the basis functions. Returns
111 * PolynomialType::get_numbering().
112 *
113 * @note Some implementations of this class do not support this function,
114 * since no lexicographic ordering of the basis functions is possible
115 * for them. Examples are: FE_SimplexP, FE_WedgeP, and FE_PyramidP.
116 */
117 std::vector<unsigned int>
118 get_poly_space_numbering() const;
119
120 /**
121 * Return the inverse numbering of the underlying polynomial space. Returns
122 * PolynomialType::get_numbering_inverse().
123 *
124 * @note See note of get_poly_space_numbering().
125 */
126 std::vector<unsigned int>
127 get_poly_space_numbering_inverse() const;
128
129 /**
130 * Return the value of the <tt>i</tt>th shape function at the point
131 * <tt>p</tt>. See the FiniteElement base class for more information about
132 * the semantics of this function.
133 */
134 virtual double
135 shape_value(const unsigned int i, const Point<dim> &p) const override;
136
137 /**
138 * Return the value of the <tt>component</tt>th vector component of the
139 * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
140 * FiniteElement base class for more information about the semantics of this
141 * function.
142 *
143 * Since this element is scalar, the returned value is the same as if the
144 * function without the <tt>_component</tt> suffix were called, provided
145 * that the specified component is zero.
146 */
147 virtual double
148 shape_value_component(const unsigned int i,
149 const Point<dim> &p,
150 const unsigned int component) const override;
151
152 /**
153 * Return the gradient of the <tt>i</tt>th shape function at the point
154 * <tt>p</tt>. See the FiniteElement base class for more information about
155 * the semantics of this function.
156 */
157 virtual Tensor<1, dim>
158 shape_grad(const unsigned int i, const Point<dim> &p) const override;
159
160 /**
161 * Return the gradient of the <tt>component</tt>th vector component of the
162 * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
163 * FiniteElement base class for more information about the semantics of this
164 * function.
165 *
166 * Since this element is scalar, the returned value is the same as if the
167 * function without the <tt>_component</tt> suffix were called, provided
168 * that the specified component is zero.
169 */
170 virtual Tensor<1, dim>
171 shape_grad_component(const unsigned int i,
172 const Point<dim> &p,
173 const unsigned int component) const override;
174
175 /**
176 * Return the tensor of second derivatives of the <tt>i</tt>th shape
177 * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
178 * class for more information about the semantics of this function.
179 */
180 virtual Tensor<2, dim>
181 shape_grad_grad(const unsigned int i, const Point<dim> &p) const override;
182
183 /**
184 * Return the second derivative of the <tt>component</tt>th vector component
185 * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
186 * FiniteElement base class for more information about the semantics of this
187 * function.
188 *
189 * Since this element is scalar, the returned value is the same as if the
190 * function without the <tt>_component</tt> suffix were called, provided
191 * that the specified component is zero.
192 */
193 virtual Tensor<2, dim>
194 shape_grad_grad_component(const unsigned int i,
195 const Point<dim> &p,
196 const unsigned int component) const override;
197
198 /**
199 * Return the tensor of third derivatives of the <tt>i</tt>th shape function
200 * at point <tt>p</tt> on the unit cell. See the FiniteElement base class
201 * for more information about the semantics of this function.
202 */
203 virtual Tensor<3, dim>
204 shape_3rd_derivative(const unsigned int i,
205 const Point<dim> &p) const override;
206
207 /**
208 * Return the third derivative of the <tt>component</tt>th vector component
209 * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
210 * FiniteElement base class for more information about the semantics of this
211 * function.
212 *
213 * Since this element is scalar, the returned value is the same as if the
214 * function without the <tt>_component</tt> suffix were called, provided
215 * that the specified component is zero.
216 */
217 virtual Tensor<3, dim>
218 shape_3rd_derivative_component(const unsigned int i,
219 const Point<dim> &p,
220 const unsigned int component) const override;
221
222 /**
223 * Return the tensor of fourth derivatives of the <tt>i</tt>th shape
224 * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
225 * class for more information about the semantics of this function.
226 */
227 virtual Tensor<4, dim>
228 shape_4th_derivative(const unsigned int i,
229 const Point<dim> &p) const override;
230
231 /**
232 * Return the fourth derivative of the <tt>component</tt>th vector component
233 * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
234 * FiniteElement base class for more information about the semantics of this
235 * function.
236 *
237 * Since this element is scalar, the returned value is the same as if the
238 * function without the <tt>_component</tt> suffix were called, provided
239 * that the specified component is zero.
240 */
241 virtual Tensor<4, dim>
242 shape_4th_derivative_component(const unsigned int i,
243 const Point<dim> &p,
244 const unsigned int component) const override;
245
246 /**
247 * Return an estimate (in bytes) for the memory consumption of this object.
248 */
249 virtual std::size_t
250 memory_consumption() const override;
251
252 protected:
253 /*
254 * NOTE: The following function has its definition inlined into the class
255 * declaration because we otherwise run into a compiler error with MS Visual
256 * Studio.
257 */
258
259
260 virtual std::unique_ptr<
261 typename FiniteElement<dim, spacedim>::InternalDataBase>
262 get_data(
263 const UpdateFlags update_flags,
264 const Mapping<dim, spacedim> &mapping,
265 const Quadrature<dim> &quadrature,
266 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
267 spacedim>
268 &output_data) const override
269 {
270 (void)mapping;
271
272 // generate a new data object and
273 // initialize some fields
274 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>
275 data_ptr = std::make_unique<InternalData>();
276 auto &data = dynamic_cast<InternalData &>(*data_ptr);
277 data.update_each = requires_update_flags(update_flags);
278
279 const unsigned int n_q_points = quadrature.size();
280
281 // initialize some scratch arrays. we need them for the underlying
282 // polynomial to put the values and derivatives of shape functions
283 // to put there, depending on what the user requested
284 std::vector<double> values(
285 update_flags & update_values ? this->n_dofs_per_cell() : 0);
286 std::vector<Tensor<1, dim>> grads(
287 update_flags & update_gradients ? this->n_dofs_per_cell() : 0);
288 std::vector<Tensor<2, dim>> grad_grads(
289 update_flags & update_hessians ? this->n_dofs_per_cell() : 0);
290 std::vector<Tensor<3, dim>> third_derivatives(
291 update_flags & update_3rd_derivatives ? this->n_dofs_per_cell() : 0);
292 std::vector<Tensor<4, dim>>
293 fourth_derivatives; // won't be needed, so leave empty
294
295 // now also initialize fields the fields of this class's own
296 // temporary storage, depending on what we need for the given
297 // update flags.
298 //
299 // there is one exception from the rule: if we are dealing with
300 // cells (i.e., if this function is not called via
301 // get_(sub)face_data()), then we can already store things in the
302 // final location where FEValues::reinit() later wants to see
303 // things. we then don't need the intermediate space. we determine
304 // whether we are on a cell by asking whether the number of
305 // elements in the output array equals the number of quadrature
306 // points (yes, it's a cell) or not (because in that case the
307 // number of quadrature points we use here equals the number of
308 // quadrature points summed over *all* faces or subfaces, whereas
309 // the number of output slots equals the number of quadrature
310 // points on only *one* face)
311 if ((update_flags & update_values) &&
312 !((output_data.shape_values.n_rows() > 0) &&
313 (output_data.shape_values.n_cols() == n_q_points)))
314 data.shape_values.reinit(this->n_dofs_per_cell(), n_q_points);
315
316 if (update_flags & update_gradients)
317 data.shape_gradients.reinit(this->n_dofs_per_cell(), n_q_points);
318
319 if (update_flags & update_hessians)
320 data.shape_hessians.reinit(this->n_dofs_per_cell(), n_q_points);
321
322 if (update_flags & update_3rd_derivatives)
323 data.shape_3rd_derivatives.reinit(this->n_dofs_per_cell(), n_q_points);
324
325 // next already fill those fields of which we have information by
326 // now. note that the shape gradients are only those on the unit
327 // cell, and need to be transformed when visiting an actual cell
328 if (update_flags & (update_values | update_gradients | update_hessians |
329 update_3rd_derivatives))
330 for (unsigned int i = 0; i < n_q_points; ++i)
331 {
332 poly_space->evaluate(quadrature.point(i),
333 values,
334 grads,
335 grad_grads,
336 third_derivatives,
337 fourth_derivatives);
338
339 // the values of shape functions at quadrature points don't change.
340 // consequently, write these values right into the output array if
341 // we can, i.e., if the output array has the correct size. this is
342 // the case on cells. on faces, we already precompute data on *all*
343 // faces and subfaces, but we later on copy only a portion of it
344 // into the output object; in that case, copy the data from all
345 // faces into the scratch object
346 if (update_flags & update_values)
347 if (output_data.shape_values.n_rows() > 0)
348 {
349 if (output_data.shape_values.n_cols() == n_q_points)
350 for (unsigned int k = 0; k < this->n_dofs_per_cell(); ++k)
351 output_data.shape_values[k][i] = values[k];
352 else
353 for (unsigned int k = 0; k < this->n_dofs_per_cell(); ++k)
354 data.shape_values[k][i] = values[k];
355 }
356
357 // for everything else, derivatives need to be transformed,
358 // so we write them into our scratch space and only later
359 // copy stuff into where FEValues wants it
360 if (update_flags & update_gradients)
361 for (unsigned int k = 0; k < this->n_dofs_per_cell(); ++k)
362 data.shape_gradients[k][i] = grads[k];
363
364 if (update_flags & update_hessians)
365 for (unsigned int k = 0; k < this->n_dofs_per_cell(); ++k)
366 data.shape_hessians[k][i] = grad_grads[k];
367
368 if (update_flags & update_3rd_derivatives)
369 for (unsigned int k = 0; k < this->n_dofs_per_cell(); ++k)
370 data.shape_3rd_derivatives[k][i] = third_derivatives[k];
371 }
372 return data_ptr;
373 }
374
375 virtual void
376 fill_fe_values(
377 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
378 const CellSimilarity::Similarity cell_similarity,
379 const Quadrature<dim> &quadrature,
380 const Mapping<dim, spacedim> &mapping,
381 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
382 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
383 &mapping_data,
384 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
385 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
386 spacedim>
387 &output_data) const override;
388
389 using FiniteElement<dim, spacedim>::fill_fe_face_values;
390
391 virtual void
392 fill_fe_face_values(
393 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
394 const unsigned int face_no,
395 const hp::QCollection<dim - 1> &quadrature,
396 const Mapping<dim, spacedim> &mapping,
397 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
398 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
399 &mapping_data,
400 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
401 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
402 spacedim>
403 &output_data) const override;
404
405 virtual void
406 fill_fe_subface_values(
407 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
408 const unsigned int face_no,
409 const unsigned int sub_no,
410 const Quadrature<dim - 1> &quadrature,
411 const Mapping<dim, spacedim> &mapping,
412 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
413 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
414 &mapping_data,
415 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
416 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
417 spacedim>
418 &output_data) const override;
419
420 /**
421 * Fields of cell-independent data.
422 *
423 * For information about the general purpose of this class, see the
424 * documentation of the base class.
425 */
426 class InternalData : public FiniteElement<dim, spacedim>::InternalDataBase
427 {
428 public:
429 /**
430 * Array with shape function values in quadrature points. There is one row
431 * for each shape function, containing values for each quadrature point.
432 *
433 * In this array, we store the values of the shape function in the
434 * quadrature points on the unit cell. Since these values do not change
435 * under transformation to the real cell, we only need to copy them over
436 * when visiting a concrete cell.
437 */
438 Table<2, double> shape_values;
439
440 /**
441 * Array with shape function gradients in quadrature points. There is one
442 * row for each shape function, containing values for each quadrature
443 * point.
444 *
445 * We store the gradients in the quadrature points on the unit cell. We
446 * then only have to apply the transformation (which is a matrix-vector
447 * multiplication) when visiting an actual cell.
448 */
449 Table<2, Tensor<1, dim>> shape_gradients;
450
451 /**
452 * Array with shape function hessians in quadrature points. There is one
453 * row for each shape function, containing values for each quadrature
454 * point.
455 *
456 * We store the hessians in the quadrature points on the unit cell. We
457 * then only have to apply the transformation when visiting an actual
458 * cell.
459 */
460 Table<2, Tensor<2, dim>> shape_hessians;
461
462 /**
463 * Array with shape function third derivatives in quadrature points. There
464 * is one row for each shape function, containing values for each
465 * quadrature point.
466 *
467 * We store the third derivatives in the quadrature points on the unit
468 * cell. We then only have to apply the transformation when visiting an
469 * actual cell.
470 */
471 Table<2, Tensor<3, dim>> shape_3rd_derivatives;
472 };
473
474 /**
475 * Correct the shape Hessians by subtracting the terms corresponding to the
476 * Jacobian pushed forward gradient.
477 *
478 * Before the correction, the Hessians would be given by
479 * @f[
480 * D_{ijk} = \frac{d^2\phi_i}{d \hat x_J d \hat x_K} (J_{jJ})^{-1}
481 * (J_{kK})^{-1},
482 * @f]
483 * where $J_{iI}=\frac{d x_i}{d \hat x_I}$. After the correction, the
484 * correct Hessians would be given by
485 * @f[
486 * \frac{d^2 \phi_i}{d x_j d x_k} = D_{ijk} - H_{mjk} \frac{d \phi_i}{d x_m},
487 * @f]
488 * where $H_{ijk}$ is the Jacobian pushed-forward derivative.
489 */
490 void
491 correct_hessians(
492 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
493 &output_data,
494 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
495 &mapping_data,
496 const unsigned int n_q_points) const;
497
498 /**
499 * Correct the shape third derivatives by subtracting the terms
500 * corresponding to the Jacobian pushed forward gradient and second
501 * derivative.
502 *
503 * Before the correction, the third derivatives would be given by
504 * @f[
505 * D_{ijkl} = \frac{d^3\phi_i}{d \hat x_J d \hat x_K d \hat x_L} (J_{jJ})^{-1}
506 * (J_{kK})^{-1} (J_{lL})^{-1},
507 * @f]
508 * where $J_{iI}=\frac{d x_i}{d \hat x_I}$. After the correction, the
509 * correct third derivative would be given by
510 * @f[
511 * \frac{d^3\phi_i}{d x_j d x_k d x_l} = D_{ijkl} - H_{mjl} \frac{d^2
512 * \phi_i}{d x_k d x_m}
513 * - H_{mkl} \frac{d^2 \phi_i}{d x_j d x_m} - H_{mjk} \frac{d^2 \phi_i}{d x_l
514 * d x_m}
515 * - K_{mjkl} \frac{d \phi_i}{d x_m},
516 * @f]
517 * where $H_{ijk}$ is the Jacobian pushed-forward derivative and $K_{ijkl}$
518 * is the Jacobian pushed-forward second derivative.
519 */
520 void
521 correct_third_derivatives(
522 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
523 &output_data,
524 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
525 &mapping_data,
526 const unsigned int n_q_points) const;
527
528
529 /**
530 * The polynomial space.
531 */
532 const std::unique_ptr<ScalarPolynomialsBase<dim>> poly_space;
533 };
534
535 /** @} */
536
537 DEAL_II_NAMESPACE_CLOSE
538
539 #endif