Debian Codegraph @

include/deal.II/fe/mapping_manifold.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 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_manifold_h
16 #define dealii_mapping_manifold_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/array_view.h>
22 #include <deal.II/base/derivative_form.h>
23 #include <deal.II/base/quadrature.h>
24
25 #include <deal.II/fe/mapping.h>
26
27 #include <cmath>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 /**
32 * @addtogroup mapping
33 * @{
34 */
35
36 /**
37 * This class implements the functionality for Manifold conforming
38 * mappings. This Mapping computes the transformation between the
39 * reference and real cell by exploiting the geometrical information
40 * coming from the underlying Manifold object.
41 *
42 * Quadrature points computed using this mapping lie on the exact
43 * geometrical objects, and tangent and normal vectors computed using
44 * this class are tangent and normal to the underlying geometry. This
45 * is in contrast with the MappingQ class, which approximates the
46 * geometry using a polynomial of some order, and then computes the
47 * normals and tangents using the approximated surface.
48 *
49 * @warning It is not possible, for mathematical reasons, for one to use this
50 * class with a geometry described by a SphericalManifold: see the note in
51 * that class for more information.
52 */
53 template <int dim, int spacedim = dim>
54 class MappingManifold : public Mapping<dim, spacedim>
55 {
56 public:
57 /**
58 * Constructor.
59 */
60 MappingManifold() = default;
61
62 /**
63 * Copy constructor.
64 */
65 MappingManifold(const MappingManifold<dim, spacedim> &mapping);
66
67 // for documentation, see the Mapping base class
68 virtual std::unique_ptr<Mapping<dim, spacedim>>
69 clone() const override;
70
71 /**
72 * Always returns @p true because this class assumes that the
73 * vertices always lies on the underlying Manifold.
74 */
75 virtual bool
76 preserves_vertex_locations() const override;
77
78 virtual bool
79 is_compatible_with(const ReferenceCell &cell_type) const override;
80
81 /**
82 * @name Mapping points between reference and real cells
83 * @{
84 */
85
86 // for documentation, see the Mapping base class
87 virtual Point<spacedim>
88 transform_unit_to_real_cell(
89 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
90 const Point<dim> &p) const override;
91
92 // for documentation, see the Mapping base class
93 virtual Point<dim>
94 transform_real_to_unit_cell(
95 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
96 const Point<spacedim> &p) const override;
97
98 /**
99 * @}
100 */
101
102 /**
103 * @name Functions to transform tensors from reference to real coordinates
104 * @{
105 */
106
107 // for documentation, see the Mapping base class
108 virtual void
109 transform(const ArrayView<const Tensor<1, dim>> &input,
110 const MappingKind kind,
111 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
112 const ArrayView<Tensor<1, spacedim>> &output) const override;
113
114 // for documentation, see the Mapping base class
115 virtual void
116 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
117 const MappingKind kind,
118 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
119 const ArrayView<Tensor<2, spacedim>> &output) const override;
120
121 // for documentation, see the Mapping base class
122 virtual void
123 transform(const ArrayView<const Tensor<2, dim>> &input,
124 const MappingKind kind,
125 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
126 const ArrayView<Tensor<2, spacedim>> &output) const override;
127
128 // for documentation, see the Mapping base class
129 virtual void
130 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
131 const MappingKind kind,
132 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
133 const ArrayView<Tensor<3, spacedim>> &output) const override;
134
135 // for documentation, see the Mapping base class
136 virtual void
137 transform(const ArrayView<const Tensor<3, dim>> &input,
138 const MappingKind kind,
139 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
140 const ArrayView<Tensor<3, spacedim>> &output) const override;
141
142 /**
143 * @}
144 */
145
146 /**
147 * @name Interface with FEValues
148 * @{
149 */
150
151 /**
152 * Storage for internal data of polynomial mappings. See
153 * Mapping::InternalDataBase for an extensive description.
154 *
155 * For the current class, the InternalData class stores data that is
156 * computed once when the object is created (in get_data()) as well as data
157 * the class wants to store from between the call to fill_fe_values(),
158 * fill_fe_face_values(), or fill_fe_subface_values() until possible later
159 * calls from the finite element to functions such as transform(). The
160 * latter class of member variables are marked as 'mutable'.
161 */
162 class InternalData : public Mapping<dim, spacedim>::InternalDataBase
163 {
164 public:
165 /**
166 * Constructor.
167 */
168 InternalData() = default;
169
170 // Documentation see Mapping::InternalDataBase.
171 virtual void
172 reinit(const UpdateFlags update_flags,
173 const Quadrature<dim> &quadrature) override;
174
175 /**
176 * Initialize the object's member variables related to cell and face data
177 * based on the given arguments. In order to initialize cell data, this
178 * function calls initialize().
179 */
180 void
181 initialize_face(const UpdateFlags update_flags,
182 const Quadrature<dim> &quadrature,
183 const unsigned int n_original_q_points);
184
185 /**
186 * Compute the weights associated to the Manifold object, that
187 * need to be passed when computing the location of the quadrature
188 * points.
189 */
190 void
191 compute_manifold_quadrature_weights(const Quadrature<dim> &quadrature);
192
193 /**
194 * Store vertices internally.
195 */
196 void
197 store_vertices(
198 const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
199
200 /**
201 * Return an estimate (in bytes) for the memory consumption of this object.
202 */
203 virtual std::size_t
204 memory_consumption() const override;
205
206 /**
207 * The current cell vertices.
208 *
209 * Computed each.
210 */
211 mutable std::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell>
212 vertices;
213
214 /**
215 * The current cell.
216 *
217 * Computed each.
218 */
219 mutable typename Triangulation<dim, spacedim>::cell_iterator cell;
220
221 /**
222 * The actual quadrature on the reference cell.
223 *
224 * Computed once.
225 */
226 Quadrature<dim> quad;
227
228 /**
229 * Values of quadrature weights for manifold quadrature
230 * formulas.
231 *
232 * The Manifold class has a function (Manifold::get_new_point())
233 * that returns new points according to a weighted average of some
234 * surrounding points on the Manifold. For each quadrature point,
235 * we call this function with a Quadrature formula constructed
236 * using the vertices of the current cell, and the values of the
237 * basis functions of an FE_Q(1) finite element evaluated at the
238 * quadrature point itself. While the vertices of the cell change
239 * for every cell, the weights can be computed once for each
240 * quadrature point. We store this information in the following
241 * variable, where the first index runs through the quadrature
242 * points, and the second index runs through the vertex indices.
243 *
244 * Computed once.
245 */
246 std::vector<std::array<double, GeometryInfo<dim>::vertices_per_cell>>
247 cell_manifold_quadrature_weights;
248
249 /**
250 * An array of weights for use in Manifold::get_new_point(). For
251 * each point (interior to a cell), we compute the weight each
252 * vertex has for this point. If the point lies at a vertex, then
253 * this vertex has weight one and all others have weight zero. If
254 * the point lies interior to a cell, then the weight every vertex
255 * has is just the $d$-linear shape functions associated with each
256 * vertex evaluated at that point.
257 */
258 mutable std::array<double, GeometryInfo<dim>::vertices_per_cell>
259 vertex_weights;
260
261 /**
262 * Unit tangential vectors. Used for the computation of boundary forms and
263 * normal vectors.
264 *
265 * This array has `(dim-1) * GeometryInfo::faces_per_cell` entries. The
266 * first GeometryInfo::faces_per_cell contain the vectors in the first
267 * tangential direction for each face; the second set of
268 * GeometryInfo<dim>::faces_per_cell entries contain the vectors in the
269 * second tangential direction (only in 3d, since there we have 2 tangential
270 * directions per face), etc.
271 *
272 * Filled once.
273 */
274 std::array<std::vector<Tensor<1, dim>>,
275 GeometryInfo<dim>::faces_per_cell *(dim - 1)>
276 unit_tangentials;
277
278 /**
279 * Tensors of covariant transformation at each of the quadrature points.
280 * The matrix stored is the Jacobian * G^{-1}, where G = Jacobian^{t} *
281 * Jacobian, is the first fundamental form of the map; if dim=spacedim
282 * then it reduces to the transpose of the inverse of the Jacobian matrix,
283 * which itself is stored in the @p contravariant field of this structure.
284 *
285 * Computed on each cell.
286 */
287 mutable std::vector<DerivativeForm<1, dim, spacedim>> covariant;
288
289 /**
290 * Tensors of contravariant transformation at each of the quadrature
291 * points. The contravariant matrix is the Jacobian of the transformation,
292 * i.e. $J_{ij}=dx_i/d\hat x_j$.
293 *
294 * Computed on each cell.
295 */
296 mutable std::vector<DerivativeForm<1, dim, spacedim>> contravariant;
297
298 /**
299 * Auxiliary vectors for internal use.
300 */
301 mutable std::vector<std::vector<Tensor<1, spacedim>>> aux;
302
303 /**
304 * The determinant of the Jacobian in each quadrature point. Filled if
305 * #update_volume_elements.
306 */
307 mutable std::vector<double> volume_elements;
308
309 /**
310 * A pointer to the Manifold in use.
311 *
312 * Updated each.
313 */
314 mutable ObserverPointer<const Manifold<dim, spacedim>> manifold;
315 };
316
317 private:
318 // documentation can be found in Mapping::requires_update_flags()
319 virtual UpdateFlags
320 requires_update_flags(const UpdateFlags update_flags) const override;
321
322 // documentation can be found in Mapping::get_data()
323 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
324 get_data(const UpdateFlags, const Quadrature<dim> &quadrature) const override;
325
326 using Mapping<dim, spacedim>::get_face_data;
327
328 // documentation can be found in Mapping::get_face_data()
329 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
330 get_face_data(const UpdateFlags flags,
331 const hp::QCollection<dim - 1> &quadrature) const override;
332
333 // documentation can be found in Mapping::get_subface_data()
334 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
335 get_subface_data(const UpdateFlags flags,
336 const Quadrature<dim - 1> &quadrature) const override;
337
338 // documentation can be found in Mapping::fill_fe_values()
339 virtual CellSimilarity::Similarity
340 fill_fe_values(
341 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
342 const CellSimilarity::Similarity cell_similarity,
343 const Quadrature<dim> &quadrature,
344 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
345 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
346 &output_data) const override;
347
348 using Mapping<dim, spacedim>::fill_fe_face_values;
349
350 // documentation can be found in Mapping::fill_fe_face_values()
351 virtual void
352 fill_fe_face_values(
353 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
354 const unsigned int face_no,
355 const hp::QCollection<dim - 1> &quadrature,
356 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
357 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
358 &output_data) const override;
359
360 // documentation can be found in Mapping::fill_fe_subface_values()
361 virtual void
362 fill_fe_subface_values(
363 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
364 const unsigned int face_no,
365 const unsigned int subface_no,
366 const Quadrature<dim - 1> &quadrature,
367 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
368 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
369 &output_data) const override;
370
371 /**
372 * @}
373 */
374 };
375
376
377
378 /** @} */
379
380 /*----------------------------------------------------------------------*/
381
382 #ifndef DOXYGEN
383
384 template <int dim, int spacedim>
385 inline bool
386 MappingManifold<dim, spacedim>::preserves_vertex_locations() const
387 {
388 return true;
389 }
390
391
392 template <int dim, int spacedim>
393 bool
394 MappingManifold<dim, spacedim>::is_compatible_with(
395 const ReferenceCell &cell_type) const
396 {
397 if (cell_type.get_dimension() != dim)
398 return false; // TODO: or is this an error?
399
400 if (cell_type.is_hyper_cube())
401 return true;
402
403 return false;
404 }
405
406
407
408 #endif // DOXYGEN
409
410 /* -------------- declaration of explicit specializations ------------- */
411
412
413 DEAL_II_NAMESPACE_CLOSE
414
415 #endif