Debian Codegraph @

include/deal.II/fe/mapping_fe.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 2024 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_mapping_fe_h
16 #define dealii_mapping_fe_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/derivative_form.h>
22 #include <deal.II/base/quadrature_lib.h>
23 #include <deal.II/base/table.h>
24 #include <deal.II/base/vectorization.h>
25
26 #include <deal.II/fe/mapping.h>
27
28 #include <deal.II/grid/tria_iterator.h>
29
30 #include <array>
31 #include <cmath>
32
33 DEAL_II_NAMESPACE_OPEN
34
35
36 /**
37 * @addtogroup mapping
38 * @{
39 */
40
41 /**
42 * This class consistently uses a user-provided finite element on all cells of a
43 * triangulation to implement a polynomial mapping.
44 *
45 * If one initializes this class with the same FiniteElement as the
46 * discretization, one obtains an iso-parametric mapping.
47 *
48 * If one initializes this class with an FE_Q(degree) object, then this class is
49 * equivalent to MappingQ(degree). Please note that no optimizations
50 * exploiting tensor-product structures of finite elements have been added here.
51 *
52 * @note Currently, only implemented for elements with tensor_degree==1 and
53 * n_components==1.
54 *
55 * Also see
56 * @ref simplex "Simplex support".
57 */
58 template <int dim, int spacedim = dim>
59 class MappingFE : public Mapping<dim, spacedim>
60 {
61 public:
62 /**
63 * Constructor.
64 */
65 explicit MappingFE(const FiniteElement<dim, spacedim> &fe);
66
67 /**
68 * Copy constructor.
69 */
70 MappingFE(const MappingFE<dim, spacedim> &mapping);
71
72 // for documentation, see the Mapping base class
73 virtual std::unique_ptr<Mapping<dim, spacedim>>
74 clone() const override;
75
76 /**
77 * Return the degree of the mapping, i.e., the degree of the finite element
78 * which was passed to the constructor.
79 */
80 unsigned int
81 get_degree() const;
82
83 // for documentation, see the Mapping base class
84 virtual BoundingBox<spacedim>
85 get_bounding_box(const typename Triangulation<dim, spacedim>::cell_iterator
86 &cell) const override;
87
88
89 virtual bool
90 is_compatible_with(const ReferenceCell &reference_cell) const override;
91
92 /**
93 * Always returns @p true because the default implementation of functions in
94 * this class preserves vertex locations.
95 */
96 virtual bool
97 preserves_vertex_locations() const override;
98
99 /**
100 * @name Mapping points between reference and real cells
101 * @{
102 */
103
104 // for documentation, see the Mapping base class
105 virtual Point<spacedim>
106 transform_unit_to_real_cell(
107 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
108 const Point<dim> &p) const override;
109
110 // for documentation, see the Mapping base class
111 virtual Point<dim>
112 transform_real_to_unit_cell(
113 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
114 const Point<spacedim> &p) const override;
115
116 /**
117 * @}
118 */
119
120 /**
121 * @name Functions to transform tensors from reference to real coordinates
122 * @{
123 */
124
125 // for documentation, see the Mapping base class
126 virtual void
127 transform(const ArrayView<const Tensor<1, dim>> &input,
128 const MappingKind kind,
129 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
130 const ArrayView<Tensor<1, spacedim>> &output) const override;
131
132 // for documentation, see the Mapping base class
133 virtual void
134 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
135 const MappingKind kind,
136 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
137 const ArrayView<Tensor<2, spacedim>> &output) const override;
138
139 // for documentation, see the Mapping base class
140 virtual void
141 transform(const ArrayView<const Tensor<2, dim>> &input,
142 const MappingKind kind,
143 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
144 const ArrayView<Tensor<2, spacedim>> &output) const override;
145
146 // for documentation, see the Mapping base class
147 virtual void
148 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
149 const MappingKind kind,
150 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
151 const ArrayView<Tensor<3, spacedim>> &output) const override;
152
153 // for documentation, see the Mapping base class
154 virtual void
155 transform(const ArrayView<const Tensor<3, dim>> &input,
156 const MappingKind kind,
157 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
158 const ArrayView<Tensor<3, spacedim>> &output) const override;
159
160 /**
161 * @}
162 */
163
164 /**
165 * @name Interface with FEValues
166 * @{
167 */
168
169 /**
170 * Storage for internal data of polynomial mappings. See
171 * Mapping::InternalDataBase for an extensive description.
172 *
173 * For the current class, the InternalData class stores data that is
174 * computed once when the object is created (in get_data()) as well as data
175 * the class wants to store from between the call to fill_fe_values(),
176 * fill_fe_face_values(), or fill_fe_subface_values() until possible later
177 * calls from the finite element to functions such as transform(). The
178 * latter class of member variables are marked as 'mutable'.
179 */
180 class InternalData : public Mapping<dim, spacedim>::InternalDataBase
181 {
182 public:
183 /**
184 * Constructor.
185 */
186 InternalData(const FiniteElement<dim, spacedim> &fe);
187
188 // Documentation see Mapping::InternalDataBase.
189 virtual void
190 reinit(const UpdateFlags update_flags,
191 const Quadrature<dim> &quadrature) override;
192
193 /**
194 * Initialize the object's member variables related to cell and face data
195 * based on the given arguments. In order to initialize cell data, this
196 * function calls reinit().
197 */
198 void
199 initialize_face(const UpdateFlags update_flags,
200 const Quadrature<dim> &quadrature,
201 const unsigned int n_original_q_points);
202
203 /**
204 * Compute the values and/or derivatives of the shape functions used for
205 * the mapping.
206 */
207 void
208 compute_shape_function_values(const std::vector<Point<dim>> &unit_points);
209
210
211 /**
212 * Shape function at quadrature point. Shape functions are in tensor
213 * product order, so vertices must be reordered to obtain transformation.
214 */
215 const double &
216 shape(const unsigned int qpoint, const unsigned int shape_nr) const;
217
218 /**
219 * Shape function at quadrature point. See above.
220 */
221 double &
222 shape(const unsigned int qpoint, const unsigned int shape_nr);
223
224 /**
225 * Gradient of shape function in quadrature point. See above.
226 */
227 const Tensor<1, dim> &
228 derivative(const unsigned int qpoint, const unsigned int shape_nr) const;
229
230 /**
231 * Gradient of shape function in quadrature point. See above.
232 */
233 Tensor<1, dim> &
234 derivative(const unsigned int qpoint, const unsigned int shape_nr);
235
236 /**
237 * Second derivative of shape function in quadrature point. See above.
238 */
239 const Tensor<2, dim> &
240 second_derivative(const unsigned int qpoint,
241 const unsigned int shape_nr) const;
242
243 /**
244 * Second derivative of shape function in quadrature point. See above.
245 */
246 Tensor<2, dim> &
247 second_derivative(const unsigned int qpoint, const unsigned int shape_nr);
248
249 /**
250 * third derivative of shape function in quadrature point. See above.
251 */
252 const Tensor<3, dim> &
253 third_derivative(const unsigned int qpoint,
254 const unsigned int shape_nr) const;
255
256 /**
257 * third derivative of shape function in quadrature point. See above.
258 */
259 Tensor<3, dim> &
260 third_derivative(const unsigned int qpoint, const unsigned int shape_nr);
261
262 /**
263 * fourth derivative of shape function in quadrature point. See above.
264 */
265 const Tensor<4, dim> &
266 fourth_derivative(const unsigned int qpoint,
267 const unsigned int shape_nr) const;
268
269 /**
270 * fourth derivative of shape function in quadrature point. See above.
271 */
272 Tensor<4, dim> &
273 fourth_derivative(const unsigned int qpoint, const unsigned int shape_nr);
274
275 /**
276 * Return an estimate (in bytes) for the memory consumption of this object.
277 */
278 virtual std::size_t
279 memory_consumption() const override;
280
281 /**
282 * Values of shape functions. Access by function @p shape.
283 *
284 * Computed once.
285 */
286 std::vector<double> shape_values;
287
288 /**
289 * Values of shape function derivatives. Access by function @p derivative.
290 *
291 * Computed once.
292 */
293 std::vector<Tensor<1, dim>> shape_derivatives;
294
295 /**
296 * Values of shape function second derivatives. Access by function @p
297 * second_derivative.
298 *
299 * Computed once.
300 */
301 std::vector<Tensor<2, dim>> shape_second_derivatives;
302
303 /**
304 * Values of shape function third derivatives. Access by function @p
305 * second_derivative.
306 *
307 * Computed once.
308 */
309 std::vector<Tensor<3, dim>> shape_third_derivatives;
310
311 /**
312 * Values of shape function fourth derivatives. Access by function @p
313 * second_derivative.
314 *
315 * Computed once.
316 */
317 std::vector<Tensor<4, dim>> shape_fourth_derivatives;
318
319 /**
320 * Unit tangential vectors. Used for the computation of boundary forms and
321 * normal vectors.
322 *
323 * Filled once.
324 */
325 std::array<std::vector<Tensor<1, dim>>,
326 ReferenceCells::max_n_faces<dim>() * 2>
327 unit_tangentials;
328
329 /**
330 * Underlying finite element.
331 */
332 const FiniteElement<dim, spacedim> &fe;
333
334 /**
335 * The polynomial degree of the mapping.
336 */
337 const unsigned int polynomial_degree;
338
339 /**
340 * Number of shape functions.
341 */
342 const unsigned int n_shape_functions;
343
344 /**
345 * Tensors of covariant transformation at each of the quadrature points.
346 * The matrix stored is the Jacobian * G^{-1}, where G = Jacobian^{t} *
347 * Jacobian, is the first fundamental form of the map; if dim=spacedim
348 * then it reduces to the transpose of the inverse of the Jacobian matrix,
349 * which itself is stored in the @p contravariant field of this structure.
350 *
351 * Computed on each cell.
352 */
353 mutable std::vector<DerivativeForm<1, dim, spacedim>> covariant;
354
355 /**
356 * Tensors of contravariant transformation at each of the quadrature
357 * points. The contravariant matrix is the Jacobian of the transformation,
358 * i.e. $J_{ij}=dx_i/d\hat x_j$.
359 *
360 * Computed on each cell.
361 */
362 mutable std::vector<DerivativeForm<1, dim, spacedim>> contravariant;
363
364 /**
365 * Auxiliary vectors for internal use.
366 */
367 mutable std::vector<std::vector<Tensor<1, spacedim>>> aux;
368
369 /**
370 * Stores the support points of the mapping shape functions on the @p
371 * cell_of_current_support_points.
372 */
373 mutable std::vector<Point<spacedim>> mapping_support_points;
374
375 /**
376 * Stores the cell of which the @p mapping_support_points are stored.
377 */
378 mutable typename Triangulation<dim, spacedim>::cell_iterator
379 cell_of_current_support_points;
380
381 /**
382 * The determinant of the Jacobian in each quadrature point. Filled if
383 * #update_volume_elements.
384 */
385 mutable std::vector<double> volume_elements;
386
387 /**
388 * Projected quadrature weights.
389 */
390 mutable std::vector<double> quadrature_weights;
391 };
392
393
394 // documentation can be found in Mapping::requires_update_flags()
395 virtual UpdateFlags
396 requires_update_flags(const UpdateFlags update_flags) const override;
397
398 // documentation can be found in Mapping::get_data()
399 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
400 get_data(const UpdateFlags, const Quadrature<dim> &quadrature) const override;
401
402 using Mapping<dim, spacedim>::get_face_data;
403
404 // documentation can be found in Mapping::get_face_data()
405 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
406 get_face_data(const UpdateFlags flags,
407 const hp::QCollection<dim - 1> &quadrature) const override;
408
409 // documentation can be found in Mapping::get_subface_data()
410 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
411 get_subface_data(const UpdateFlags flags,
412 const Quadrature<dim - 1> &quadrature) const override;
413
414 // documentation can be found in Mapping::fill_fe_values()
415 virtual CellSimilarity::Similarity
416 fill_fe_values(
417 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
418 const CellSimilarity::Similarity cell_similarity,
419 const Quadrature<dim> &quadrature,
420 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
421 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
422 &output_data) const override;
423
424 using Mapping<dim, spacedim>::fill_fe_face_values;
425
426 // documentation can be found in Mapping::fill_fe_face_values()
427 virtual void
428 fill_fe_face_values(
429 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
430 const unsigned int face_no,
431 const hp::QCollection<dim - 1> &quadrature,
432 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
433 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
434 &output_data) const override;
435
436 // documentation can be found in Mapping::fill_fe_subface_values()
437 virtual void
438 fill_fe_subface_values(
439 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
440 const unsigned int face_no,
441 const unsigned int subface_no,
442 const Quadrature<dim - 1> &quadrature,
443 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
444 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
445 &output_data) const override;
446
447 /**
448 * @}
449 */
450
451 protected:
452 const std::unique_ptr<FiniteElement<dim, spacedim>> fe;
453
454 /**
455 * The degree of the polynomials used as shape functions for the mapping of
456 * cells.
457 */
458 const unsigned int polynomial_degree;
459
460 /**
461 * Return the locations of support points for the mapping.
462 */
463 virtual std::vector<Point<spacedim>>
464 compute_mapping_support_points(
465 const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
466
467 private:
468 Table<2, double> mapping_support_point_weights;
469 };
470
471
472
473 /** @} */
474
475 /*----------------------------------------------------------------------*/
476
477 #ifndef DOXYGEN
478
479 template <int dim, int spacedim>
480 inline const double &
481 MappingFE<dim, spacedim>::InternalData::shape(const unsigned int qpoint,
482 const unsigned int shape_nr) const
483 {
484 AssertIndexRange(qpoint * n_shape_functions + shape_nr, shape_values.size());
485 return shape_values[qpoint * n_shape_functions + shape_nr];
486 }
487
488
489
490 template <int dim, int spacedim>
491 inline double &
492 MappingFE<dim, spacedim>::InternalData::shape(const unsigned int qpoint,
493 const unsigned int shape_nr)
494 {
495 AssertIndexRange(qpoint * n_shape_functions + shape_nr, shape_values.size());
496 return shape_values[qpoint * n_shape_functions + shape_nr];
497 }
498
499
500 template <int dim, int spacedim>
501 inline const Tensor<1, dim> &
502 MappingFE<dim, spacedim>::InternalData::derivative(
503 const unsigned int qpoint,
504 const unsigned int shape_nr) const
505 {
506 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
507 shape_derivatives.size());
508 return shape_derivatives[qpoint * n_shape_functions + shape_nr];
509 }
510
511
512
513 template <int dim, int spacedim>
514 inline Tensor<1, dim> &
515 MappingFE<dim, spacedim>::InternalData::derivative(const unsigned int qpoint,
516 const unsigned int shape_nr)
517 {
518 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
519 shape_derivatives.size());
520 return shape_derivatives[qpoint * n_shape_functions + shape_nr];
521 }
522
523
524 template <int dim, int spacedim>
525 inline const Tensor<2, dim> &
526 MappingFE<dim, spacedim>::InternalData::second_derivative(
527 const unsigned int qpoint,
528 const unsigned int shape_nr) const
529 {
530 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
531 shape_second_derivatives.size());
532 return shape_second_derivatives[qpoint * n_shape_functions + shape_nr];
533 }
534
535
536 template <int dim, int spacedim>
537 inline Tensor<2, dim> &
538 MappingFE<dim, spacedim>::InternalData::second_derivative(
539 const unsigned int qpoint,
540 const unsigned int shape_nr)
541 {
542 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
543 shape_second_derivatives.size());
544 return shape_second_derivatives[qpoint * n_shape_functions + shape_nr];
545 }
546
547 template <int dim, int spacedim>
548 inline const Tensor<3, dim> &
549 MappingFE<dim, spacedim>::InternalData::third_derivative(
550 const unsigned int qpoint,
551 const unsigned int shape_nr) const
552 {
553 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
554 shape_third_derivatives.size());
555 return shape_third_derivatives[qpoint * n_shape_functions + shape_nr];
556 }
557
558
559 template <int dim, int spacedim>
560 inline Tensor<3, dim> &
561 MappingFE<dim, spacedim>::InternalData::third_derivative(
562 const unsigned int qpoint,
563 const unsigned int shape_nr)
564 {
565 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
566 shape_third_derivatives.size());
567 return shape_third_derivatives[qpoint * n_shape_functions + shape_nr];
568 }
569
570
571 template <int dim, int spacedim>
572 inline const Tensor<4, dim> &
573 MappingFE<dim, spacedim>::InternalData::fourth_derivative(
574 const unsigned int qpoint,
575 const unsigned int shape_nr) const
576 {
577 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
578 shape_fourth_derivatives.size());
579 return shape_fourth_derivatives[qpoint * n_shape_functions + shape_nr];
580 }
581
582
583 template <int dim, int spacedim>
584 inline Tensor<4, dim> &
585 MappingFE<dim, spacedim>::InternalData::fourth_derivative(
586 const unsigned int qpoint,
587 const unsigned int shape_nr)
588 {
589 AssertIndexRange(qpoint * n_shape_functions + shape_nr,
590 shape_fourth_derivatives.size());
591 return shape_fourth_derivatives[qpoint * n_shape_functions + shape_nr];
592 }
593
594
595
596 template <int dim, int spacedim>
597 inline bool
598 MappingFE<dim, spacedim>::preserves_vertex_locations() const
599 {
600 return true;
601 }
602
603
604
605 #endif // DOXYGEN
606
607 /* -------------- declaration of explicit specializations ------------- */
608
609
610 DEAL_II_NAMESPACE_CLOSE
611
612 #endif