Debian Codegraph @

include/deal.II/fe/mapping_fe_field.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 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_mapping_fe_field_h
16 #define dealii_mapping_fe_field_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/mg_level_object.h>
22 #include <deal.II/base/mutex.h>
23
24 #include <deal.II/dofs/dof_handler.h>
25
26 #include <deal.II/fe/fe.h>
27 #include <deal.II/fe/fe_values.h>
28 #include <deal.II/fe/mapping.h>
29
30 #include <deal.II/lac/vector.h>
31
32 #include <boost/container/small_vector.hpp>
33
34 #include <array>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39
40 /**
41 * @addtogroup mapping
42 * @{
43 */
44
45 /**
46 * The MappingFEField is a generalization of the MappingQEulerian class, for
47 * arbitrary vector finite elements. The two main differences are that this
48 * class uses a vector of absolute positions instead of a vector of
49 * displacements, and it allows for arbitrary FiniteElement types, instead of
50 * only FE_Q.
51 *
52 * This class effectively decouples the topology from the geometry, by
53 * relegating all geometrical information to some components of a
54 * FiniteElement vector field. The components that are used for the geometry
55 * can be arbitrarily selected at construction time.
56 *
57 * The idea is to consider the Triangulation as a parameter configuration
58 * space, on which we construct an arbitrary geometrical mapping, using the
59 * instruments of the deal.II library: a vector of degrees of freedom, a
60 * DoFHandler associated to the geometry of the problem and a ComponentMask
61 * that tells us which components of the FiniteElement to use for the mapping.
62 *
63 * Typically, the DoFHandler operates on a finite element that is constructed
64 * as a system element (FESystem()) from continuous FE_Q() (for iso-parametric
65 * discretizations) or FE_Bernstein() (for iso-geometric discretizations)
66 * objects. An example is shown below:
67 *
68 * @code
69 * const FE_Q<dim,spacedim> feq(1);
70 * const FESystem<dim,spacedim> fesystem(feq, spacedim);
71 * DoFHandler<dim,spacedim> dhq(triangulation);
72 * dhq.distribute_dofs(fesystem);
73 * const ComponentMask mask(spacedim, true);
74 * Vector<double> eulerq(dhq.n_dofs());
75 * // Fills the euler vector with information from the Triangulation
76 * VectorTools::get_position_vector(dhq, eulerq, mask);
77 * MappingFEField<dim,spacedim> map(dhq, eulerq, mask);
78 * @endcode
79 */
80 template <int dim, int spacedim = dim, typename VectorType = Vector<double>>
81 class MappingFEField : public Mapping<dim, spacedim>
82 {
83 public:
84 /**
85 * Constructor. The first argument is a VectorType that specifies the
86 * transformation of the domain from the reference to the current
87 * configuration.
88 *
89 * In general this class decouples geometry from topology, allowing users to
90 * define geometries which are only topologically equivalent to the
91 * underlying Triangulation, but which may otherwise be arbitrary.
92 * Differently from what happens in MappingQEulerian, the FiniteElement
93 * field which is passed to the constructor is interpreted as an absolute
94 * geometrical configuration, therefore one has to make sure that the
95 * euler_vector actually represents a valid geometry (i.e., one with no
96 * inverted cells, or with no zero-volume cells).
97 *
98 * If the underlying FiniteElement is a system of FE_Q(), and euler_vector
99 * is initialized using VectorTools::get_position_vector(), then this class
100 * is in all respects identical to MappingQ().
101 *
102 * The optional ComponentMask argument can be used to specify what
103 * components of the FiniteElement to use for the geometrical
104 * transformation. If no mask is specified at construction time, then a
105 * default one is used, which makes this class works in the same way of
106 * MappingQEulerian(), i.e., the first spacedim components of the
107 * FiniteElement are assumed to represent the geometry of the problem.
108 *
109 * Notice that if a mask is specified, it has to match in size the
110 * underlying FiniteElement, and it has to have exactly spacedim non-zero
111 * elements, indicating the components (in order) of the FiniteElement which
112 * will be used for the geometry.
113 *
114 * If an incompatible mask is passed, an exception is thrown.
115 */
116 MappingFEField(const DoFHandler<dim, spacedim> &euler_dof_handler,
117 const VectorType &euler_vector,
118 const ComponentMask &mask = {});
119
120 /**
121 * Constructor taking vectors on the multigrid levels rather than the active
122 * cells only. The vector of vectors is expected to have as many entries as
123 * there are global levels in the triangulation and provide valid data on
124 * each level, i.e., be of compatible length DoFHandler::n_dofs(level). A
125 * prerequisite of this constructor is that DoFHandler::distribute_mg_dofs()
126 * has been called. Apart from the level vectors, the same arguments as in
127 * the other constructor need to be provided.
128 */
129 MappingFEField(const DoFHandler<dim, spacedim> &euler_dof_handler,
130 const std::vector<VectorType> &euler_vector,
131 const ComponentMask &mask = {});
132
133 /**
134 * Constructor with MGLevelObject instead of std::vector, otherwise the same
135 * as above. It is required that `euler_vector.max_level()+1` equals the
136 * global number of levels in the triangulation. The minimum level may be
137 * zero or more &mdash; it only needs to be consistent between what is set
138 * here and later used for evaluation of the mapping.
139 */
140 MappingFEField(const DoFHandler<dim, spacedim> &euler_dof_handler,
141 const MGLevelObject<VectorType> &euler_vector,
142 const ComponentMask &mask = {});
143
144 /**
145 * Copy constructor.
146 */
147 MappingFEField(const MappingFEField<dim, spacedim, VectorType> &mapping);
148
149 /**
150 * Return a pointer to a copy of the present object. The caller of this copy
151 * then assumes ownership of it.
152 */
153 virtual std::unique_ptr<Mapping<dim, spacedim>>
154 clone() const override;
155
156 /**
157 * See the documentation of Mapping::preserves_vertex_locations()
158 * for the purpose of this function. The implementation in this
159 * class always returns @p false.
160 */
161 virtual bool
162 preserves_vertex_locations() const override;
163
164 virtual bool
165 is_compatible_with(const ReferenceCell &reference_cell) const override;
166
167 /**
168 * Return the mapped vertices of a cell.
169 *
170 * This mapping ignores the vertices of the Triangulation it is associated to,
171 * and constructs the position of the vertices according to the @p euler_vector
172 * that was passed at construction time.
173 */
174 virtual boost::container::small_vector<Point<spacedim>,
175 #ifndef _MSC_VER
176 ReferenceCells::max_n_vertices<dim>()
177 #else
178 GeometryInfo<dim>::vertices_per_cell
179 #endif
180 >
181 get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell)
182 const override;
183
184 /**
185 * @name Mapping points between reference and real cells
186 * @{
187 */
188
189 // for documentation, see the Mapping base class
190 virtual Point<spacedim>
191 transform_unit_to_real_cell(
192 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
193 const Point<dim> &p) const override;
194
195 // for documentation, see the Mapping base class
196 virtual Point<dim>
197 transform_real_to_unit_cell(
198 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
199 const Point<spacedim> &p) const override;
200
201 /**
202 * @}
203 */
204
205 /**
206 * @name Functions to transform tensors from reference to real coordinates
207 * @{
208 */
209
210 // for documentation, see the Mapping base class
211 virtual void
212 transform(const ArrayView<const Tensor<1, dim>> &input,
213 const MappingKind kind,
214 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
215 const ArrayView<Tensor<1, spacedim>> &output) const override;
216
217 // for documentation, see the Mapping base class
218 virtual void
219 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
220 const MappingKind kind,
221 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
222 const ArrayView<Tensor<2, spacedim>> &output) const override;
223
224 // for documentation, see the Mapping base class
225 virtual void
226 transform(const ArrayView<const Tensor<2, dim>> &input,
227 const MappingKind kind,
228 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
229 const ArrayView<Tensor<2, spacedim>> &output) const override;
230
231 // for documentation, see the Mapping base class
232 virtual void
233 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
234 const MappingKind kind,
235 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
236 const ArrayView<Tensor<3, spacedim>> &output) const override;
237
238 // for documentation, see the Mapping base class
239 virtual void
240 transform(const ArrayView<const Tensor<3, dim>> &input,
241 const MappingKind kind,
242 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
243 const ArrayView<Tensor<3, spacedim>> &output) const override;
244
245 /**
246 * @}
247 */
248
249 /**
250 * Return the degree of the mapping, i.e. the value which was passed to the
251 * constructor.
252 */
253 unsigned int
254 get_degree() const;
255
256 /**
257 * Return the ComponentMask of the mapping, i.e. which components to use for
258 * the mapping.
259 */
260 ComponentMask
261 get_component_mask() const;
262
263 /**
264 * Exception
265 */
266 DeclException0(ExcInactiveCell);
267
268 private:
269 /**
270 * @name Interface with FEValues
271 * @{
272 */
273
274 // documentation can be found in Mapping::requires_update_flags()
275 virtual UpdateFlags
276 requires_update_flags(const UpdateFlags update_flags) const override;
277
278 public:
279 /**
280 * Storage for internal data of this mapping. See Mapping::InternalDataBase
281 * for an extensive description.
282 *
283 * This includes data that is computed once when the object is created (in
284 * get_data()) as well as data the class wants to store from between the
285 * call to fill_fe_values(), fill_fe_face_values(), or
286 * fill_fe_subface_values() until possible later calls from the finite
287 * element to functions such as transform(). The latter class of member
288 * variables are marked as 'mutable', along with scratch arrays.
289 */
290 class InternalData : public Mapping<dim, spacedim>::InternalDataBase
291 {
292 public:
293 /**
294 * Constructor.
295 */
296 InternalData(const FiniteElement<dim, spacedim> &fe,
297 const ComponentMask &mask);
298
299 // Documentation see Mapping::InternalDataBase.
300 virtual void
301 reinit(const UpdateFlags update_flags,
302 const Quadrature<dim> &quadrature) override;
303
304 /**
305 * Shape function at quadrature point. Shape functions are in tensor
306 * product order, so vertices must be reordered to obtain transformation.
307 */
308 const double &
309 shape(const unsigned int qpoint, const unsigned int shape_nr) const;
310
311 /**
312 * Shape function at quadrature point. See above.
313 */
314 double &
315 shape(const unsigned int qpoint, const unsigned int shape_nr);
316
317 /**
318 * Gradient of shape function in quadrature point. See above.
319 */
320 const Tensor<1, dim> &
321 derivative(const unsigned int qpoint, const unsigned int shape_nr) const;
322
323 /**
324 * Gradient of shape function in quadrature point. See above.
325 */
326 Tensor<1, dim> &
327 derivative(const unsigned int qpoint, const unsigned int shape_nr);
328
329 /**
330 * Second derivative of shape function in quadrature point. See above.
331 */
332 const Tensor<2, dim> &
333 second_derivative(const unsigned int qpoint,
334 const unsigned int shape_nr) const;
335
336 /**
337 * Second derivative of shape function in quadrature point. See above.
338 */
339 Tensor<2, dim> &
340 second_derivative(const unsigned int qpoint, const unsigned int shape_nr);
341
342 /**
343 * Third derivative of shape function in quadrature point. See above.
344 */
345 const Tensor<3, dim> &
346 third_derivative(const unsigned int qpoint,
347 const unsigned int shape_nr) const;
348
349 /**
350 * Fourth derivative of shape function in quadrature point. See above.
351 */
352 Tensor<3, dim> &
353 third_derivative(const unsigned int qpoint, const unsigned int shape_nr);
354
355 /**
356 * Fourth derivative of shape function in quadrature point. See above.
357 */
358 const Tensor<4, dim> &
359 fourth_derivative(const unsigned int qpoint,
360 const unsigned int shape_nr) const;
361
362 /**
363 * Third derivative of shape function in quadrature point. See above.
364 */
365 Tensor<4, dim> &
366 fourth_derivative(const unsigned int qpoint, const unsigned int shape_nr);
367
368 /**
369 * Return an estimate (in bytes) for the memory consumption of this object.
370 */
371 virtual std::size_t
372 memory_consumption() const override;
373
374 /**
375 * A pointer to the underlying finite element.
376 */
377 ObserverPointer<const FiniteElement<dim, spacedim>> fe;
378
379 /**
380 * Values of shape functions. Access by function @p shape.
381 *
382 * Computed once.
383 */
384 std::vector<double> shape_values;
385
386 /**
387 * Values of shape function derivatives. Access by function @p derivative.
388 *
389 * Computed once.
390 */
391 std::vector<Tensor<1, dim>> shape_derivatives;
392
393 /**
394 * Values of shape function second derivatives. Access by function @p
395 * second_derivative.
396 *
397 * Computed once.
398 */
399 std::vector<Tensor<2, dim>> shape_second_derivatives;
400
401 /**
402 * Values of shape function third derivatives. Access by function @p
403 * third_derivative.
404 *
405 * Computed once.
406 */
407 std::vector<Tensor<3, dim>> shape_third_derivatives;
408
409 /**
410 * Values of shape function fourth derivatives. Access by function @p
411 * fourth_derivative.
412 *
413 * Computed once.
414 */
415 std::vector<Tensor<4, dim>> shape_fourth_derivatives;
416
417 /**
418 * Unit tangential vectors. Used for the computation of boundary forms and
419 * normal vectors.
420 *
421 * This array has `(dim-1)*GeometryInfo<dim>::%faces_per_cell` entries. The
422 * first GeometryInfo::faces_per_cell contain the vectors in the first
423 * tangential direction for each face; the second set of
424 * GeometryInfo::faces_per_cell entries contain the vectors in the second
425 * tangential direction (only in 3d, since there we have 2 tangential
426 * directions per face), etc.
427 *
428 * Filled once.
429 */
430 std::array<std::vector<Tensor<1, dim>>,
431 GeometryInfo<dim>::faces_per_cell *(dim - 1)>
432 unit_tangentials;
433
434 /**
435 * Number of shape functions. If this is a Q1 mapping, then it is simply
436 * the number of vertices per cell. However, since also derived classes
437 * use this class (e.g. the Mapping_Q() class), the number of shape
438 * functions may also be different.
439 */
440 unsigned int n_shape_functions;
441
442 /**
443 * Stores the mask given at construction time. If no mask was specified at
444 * construction time, then a default one is used, which makes this class
445 * works in the same way of MappingQEulerian(), i.e., the first spacedim
446 * components of the FiniteElement are used for the euler_vector and the
447 * euler_dh.
448 *
449 * If a mask is specified, then it has to match the underlying
450 * FiniteElement, and it has to have exactly spacedim non-zero elements,
451 * indicating the components (in order) of the FiniteElement which will be
452 * used for the euler vector and the euler dof handler.
453 */
454 ComponentMask mask;
455
456 /**
457 * Tensors of covariant transformation at each of the quadrature points.
458 * The matrix stored is the Jacobian * G^{-1}, where G = Jacobian^{t} *
459 * Jacobian, is the first fundamental form of the map; if dim=spacedim
460 * then it reduces to the transpose of the inverse of the Jacobian matrix,
461 * which itself is stored in the @p contravariant field of this structure.
462 *
463 * Computed on each cell.
464 */
465 mutable std::vector<DerivativeForm<1, dim, spacedim>> covariant;
466
467 /**
468 * Tensors of contravariant transformation at each of the quadrature
469 * points. The contravariant matrix is the Jacobian of the transformation,
470 * i.e. $J_{ij}=dx_i/d\hat x_j$.
471 *
472 * Computed on each cell.
473 */
474 mutable std::vector<DerivativeForm<1, dim, spacedim>> contravariant;
475
476 /**
477 * The determinant of the Jacobian in each quadrature point. Filled if
478 * #update_volume_elements.
479 */
480 mutable std::vector<double> volume_elements;
481
482 /**
483 * Projected quadrature weights.
484 */
485 mutable std::vector<double> quadrature_weights;
486
487 /**
488 * Auxiliary vectors for internal use.
489 */
490 mutable std::vector<std::vector<Tensor<1, spacedim>>> aux;
491
492 /**
493 * Storage for the indices of the local degrees of freedom.
494 */
495 mutable std::vector<types::global_dof_index> local_dof_indices;
496
497 /**
498 * Storage for local degrees of freedom.
499 */
500 mutable std::vector<double> local_dof_values;
501 };
502
503 protected:
504 // documentation can be found in Mapping::get_data()
505 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
506 get_data(const UpdateFlags, const Quadrature<dim> &quadrature) const override;
507
508 using Mapping<dim, spacedim>::get_face_data;
509
510 // documentation can be found in Mapping::get_face_data()
511 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
512 get_face_data(const UpdateFlags flags,
513 const hp::QCollection<dim - 1> &quadrature) const override;
514
515 // documentation can be found in Mapping::get_subface_data()
516 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
517 get_subface_data(const UpdateFlags flags,
518 const Quadrature<dim - 1> &quadrature) const override;
519
520 // documentation can be found in Mapping::fill_fe_values()
521 virtual CellSimilarity::Similarity
522 fill_fe_values(
523 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
524 const CellSimilarity::Similarity cell_similarity,
525 const Quadrature<dim> &quadrature,
526 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
527 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
528 &output_data) const override;
529
530 using Mapping<dim, spacedim>::fill_fe_face_values;
531
532 // documentation can be found in Mapping::fill_fe_face_values()
533 virtual void
534 fill_fe_face_values(
535 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
536 const unsigned int face_no,
537 const hp::QCollection<dim - 1> &quadrature,
538 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
539 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
540 &output_data) const override;
541
542 // documentation can be found in Mapping::fill_fe_subface_values()
543 virtual void
544 fill_fe_subface_values(
545 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
546 const unsigned int face_no,
547 const unsigned int subface_no,
548 const Quadrature<dim - 1> &quadrature,
549 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
550 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
551 &output_data) const override;
552
553 virtual void
554 fill_fe_immersed_surface_values(
555 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
556 const NonMatching::ImmersedSurfaceQuadrature<dim> &quadrature,
557 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
558 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
559 &output_data) const override;
560
561 /**
562 * @}
563 */
564
565 /**
566 * Reference cell over which the mapping is defined. This class does not yet
567 * support mixed meshes.
568 */
569 ReferenceCell reference_cell;
570
571 /**
572 * Specifies whether we access unknowns on the active dofs (with a single
573 * Euler vector) or on the level dofs (via a vector of Euler vectors).
574 */
575 const bool uses_level_dofs;
576
577 /**
578 * Reference to the vector of shifts.
579 */
580 std::vector<ObserverPointer<const VectorType,
581 MappingFEField<dim, spacedim, VectorType>>>
582 euler_vector;
583
584 /**
585 * Pointer to the DoFHandler to which the mapping vector is associated.
586 */
587 ObserverPointer<const DoFHandler<dim, spacedim>,
588 MappingFEField<dim, spacedim, VectorType>>
589 euler_dof_handler;
590
591 private:
592 /**
593 * Transform a point @p p on the unit cell to the point @p p_real on the
594 * real cell @p cell and returns @p p_real.
595 *
596 * This function is called by @p transform_unit_to_real_cell and multiple
597 * times (through the Newton iteration) by @p
598 * transform_real_to_unit_cell_internal.
599 *
600 * Takes a reference to an @p InternalData that must already include the
601 * shape values at point @p p and the mapping support points of the cell.
602 *
603 * This @p InternalData argument avoids multiple computations of the shape
604 * values at point @p p and especially multiple computations of the mapping
605 * support points.
606 */
607 Point<spacedim>
608 do_transform_unit_to_real_cell(const InternalData &mdata) const;
609
610 /**
611 * Transform the point @p p on the real cell to the corresponding point on
612 * the unit cell @p cell by a Newton iteration. @p starting_guess is
613 * a guess for the position on the unit cell at which this function will
614 * start its Newton iteration.
615 *
616 * Takes a reference to an @p InternalData that is assumed to be previously
617 * created by the @p get_data function with @p UpdateFlags including @p
618 * update_transformation_values and @p update_transformation_gradients and a
619 * one point Quadrature that includes the given initial guess specified
620 * through the given @p starting_guess.
621 *
622 * @p mdata will be changed by this function.
623 */
624 Point<dim>
625 do_transform_real_to_unit_cell(
626 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
627 const Point<spacedim> &p,
628 const Point<dim> &starting_guess,
629 InternalData &mdata) const;
630
631 /**
632 * Update internal degrees of freedom.
633 */
634 void
635 update_internal_dofs(
636 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
637 const typename MappingFEField<dim, spacedim, VectorType>::InternalData
638 &data) const;
639
640 /*
641 * Which components to use for the mapping.
642 */
643 const ComponentMask fe_mask;
644
645 /**
646 * Mapping between indices in the FE space and the real space. This vector
647 * contains one index for each component of the finite element space. If the
648 * index is one for which the ComponentMask which is used to construct this
649 * element is false, then numbers::invalid_unsigned_int is returned,
650 * otherwise the component in real space is returned. For example, if we
651 * construct the mapping using ComponentMask(spacedim, true), then this
652 * vector contains {0,1,2} in spacedim = 3.
653 */
654 std::vector<unsigned int> fe_to_real;
655
656 /**
657 * FEValues object used to query the given finite element field at the
658 * support points in the reference configuration.
659 */
660 mutable FEValues<dim, spacedim> fe_values;
661
662 /**
663 * A variable to guard access to the fe_values variable.
664 */
665 mutable Threads::Mutex fe_values_mutex;
666
667 void
668 compute_face_data(const unsigned int n_original_q_points,
669 InternalData &data) const;
670
671 // Declare other MappingFEField classes friends.
672 template <int, int, class>
673 friend class MappingFEField;
674 };
675
676 /** @} */
677
678 /* -------------- declaration of explicit specializations ------------- */
679
680 #ifndef DOXYGEN
681
682 #endif // DOXYGEN
683
684 DEAL_II_NAMESPACE_CLOSE
685
686 #endif