Debian Codegraph @

include/deal.II/fe/mapping_cartesian.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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_cartesian_h
16 #define dealii_mapping_cartesian_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/qprojector.h>
22
23 #include <deal.II/fe/mapping.h>
24
25 #include <cmath>
26
27
28 DEAL_II_NAMESPACE_OPEN
29
30 /**
31 * @addtogroup mapping
32 * @{
33 */
34
35 /**
36 * A class providing a mapping from the reference cell to cells that are
37 * axiparallel, i.e., that have the shape of rectangles (in 2d) or
38 * boxes (in 3d) with edges parallel to the coordinate directions. The
39 * class therefore provides functionality that is equivalent to what,
40 * for example, MappingQ would provide for such cells. However, knowledge
41 * of the shape of cells allows this class to be substantially more
42 * efficient.
43 *
44 * Specifically, the mapping is meant for cells for which the mapping from
45 * the reference to the real cell is a scaling along the coordinate
46 * directions: The transformation from reference coordinates $\hat {\mathbf
47 * x}$ to real coordinates $\mathbf x$ on each cell is of the form
48 * @f{align*}{
49 * {\mathbf x}(\hat {\mathbf x})
50 * =
51 * \begin{pmatrix}
52 * h_x & 0 \\
53 * 0 & h_y
54 * \end{pmatrix}
55 * \hat{\mathbf x}
56 * + {\mathbf v}_0
57 * @f}
58 * in 2d, and
59 * @f{align*}{
60 * {\mathbf x}(\hat {\mathbf x})
61 * =
62 * \begin{pmatrix}
63 * h_x & 0 & 0 \\
64 * 0 & h_y & 0 \\
65 * 0 & 0 & h_z
66 * \end{pmatrix}
67 * \hat{\mathbf x}
68 * + {\mathbf v}_0
69 * @f}
70 * in 3d, where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$
71 * are the extents of the cell along the axes.
72 *
73 * The class is intended for efficiency, and it does not do a whole lot of
74 * error checking. If you apply this mapping to a cell that does not conform
75 * to the requirements above, you will get strange results.
76 */
77 template <int dim, int spacedim = dim>
78 class MappingCartesian : public Mapping<dim, spacedim>
79 {
80 public:
81 // for documentation, see the Mapping base class
82 virtual std::unique_ptr<Mapping<dim, spacedim>>
83 clone() const override;
84
85 /**
86 * Return @p true because MappingCartesian preserves vertex
87 * locations.
88 */
89 virtual bool
90 preserves_vertex_locations() const override;
91
92 virtual bool
93 is_compatible_with(const ReferenceCell &reference_cell) const override;
94
95 /**
96 * @name Mapping points between reference and real cells
97 * @{
98 */
99
100 // for documentation, see the Mapping base class
101 virtual Point<spacedim>
102 transform_unit_to_real_cell(
103 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
104 const Point<dim> &p) const override;
105
106 // for documentation, see the Mapping base class
107 virtual Point<dim>
108 transform_real_to_unit_cell(
109 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
110 const Point<spacedim> &p) const override;
111
112 // for documentation, see the Mapping base class
113 virtual void
114 transform_points_real_to_unit_cell(
115 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
116 const ArrayView<const Point<spacedim>> &real_points,
117 const ArrayView<Point<dim>> &unit_points) const override;
118
119 /**
120 * @}
121 */
122
123 /**
124 * @name Functions to transform tensors from reference to real coordinates
125 * @{
126 */
127
128 // for documentation, see the Mapping base class
129 virtual void
130 transform(const ArrayView<const Tensor<1, dim>> &input,
131 const MappingKind kind,
132 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
133 const ArrayView<Tensor<1, spacedim>> &output) const override;
134
135 // for documentation, see the Mapping base class
136 virtual void
137 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
138 const MappingKind kind,
139 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
140 const ArrayView<Tensor<2, spacedim>> &output) const override;
141
142 // for documentation, see the Mapping base class
143 virtual void
144 transform(const ArrayView<const Tensor<2, dim>> &input,
145 const MappingKind kind,
146 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
147 const ArrayView<Tensor<2, spacedim>> &output) const override;
148
149 // for documentation, see the Mapping base class
150 virtual void
151 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
152 const MappingKind kind,
153 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
154 const ArrayView<Tensor<3, spacedim>> &output) const override;
155
156 // for documentation, see the Mapping base class
157 virtual void
158 transform(const ArrayView<const Tensor<3, dim>> &input,
159 const MappingKind kind,
160 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
161 const ArrayView<Tensor<3, spacedim>> &output) const override;
162
163 /**
164 * @}
165 */
166
167 /**
168 * As opposed to the other fill_fe_values() and fill_fe_face_values()
169 * functions that rely on pre-computed information of InternalDataBase, this
170 * function chooses the flexible evaluation path on the cell and points
171 * passed in to the current function.
172 *
173 * @param[in] cell The cell where to evaluate the mapping
174 *
175 * @param[in] unit_points The points in reference coordinates where the
176 * transformation (Jacobians, positions) should be computed.
177 *
178 * @param[in] update_flags The kind of information that should be computed.
179 *
180 * @param[out] output_data A struct containing the evaluated quantities such
181 * as the Jacobian resulting from application of the mapping on the given
182 * cell with its underlying manifolds.
183 */
184 void
185 fill_mapping_data_for_generic_points(
186 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
187 const ArrayView<const Point<dim>> &unit_points,
188 const UpdateFlags update_flags,
189 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
190 &output_data) const;
191
192 /**
193 * @name Interface with FEValues
194 * @{
195 */
196
197 /**
198 * Storage for internal data of the mapping. See Mapping::InternalDataBase
199 * for an extensive description.
200 *
201 * This includes data that is computed once when the object is created (in
202 * get_data()) as well as data the class wants to store from between the
203 * call to fill_fe_values(), fill_fe_face_values(), or
204 * fill_fe_subface_values() until possible later calls from the finite
205 * element to functions such as transform(). The latter class of member
206 * variables are marked as 'mutable'.
207 */
208 class InternalData : public Mapping<dim, spacedim>::InternalDataBase
209 {
210 public:
211 /**
212 * Default constructor.
213 */
214 InternalData() = default;
215
216 /**
217 * Constructor that initializes the object with a quadrature.
218 */
219 InternalData(const Quadrature<dim> &quadrature);
220
221 // Documentation see Mapping::InternalDataBase.
222 virtual void
223 reinit(const UpdateFlags update_flags,
224 const Quadrature<dim> &quadrature) override;
225
226 /**
227 * Return an estimate (in bytes) for the memory consumption of this object.
228 */
229 virtual std::size_t
230 memory_consumption() const override;
231
232 /**
233 * Extents of the last cell we have seen in the coordinate directions,
234 * i.e., <i>h<sub>x</sub></i>, <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
235 */
236 mutable Tensor<1, dim> cell_extents;
237
238 /**
239 * Reciprocal of the extents of the last cell we have seen in the
240 * coordinate directions, i.e., <i>h<sub>x</sub></i>,
241 * <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
242 */
243 mutable Tensor<1, dim> inverse_cell_extents;
244
245 /**
246 * The volume element
247 */
248 mutable double volume_element;
249
250 /**
251 * Location of quadrature points of faces or subfaces in 3d with all
252 * possible orientations. Can be accessed with the correct offset provided
253 * via QProjector::DataSetDescriptor. Not needed/used for cells.
254 */
255 std::vector<Point<dim>> quadrature_points;
256 };
257
258 private:
259 // documentation can be found in Mapping::requires_update_flags()
260 virtual UpdateFlags
261 requires_update_flags(const UpdateFlags update_flags) const override;
262
263 // documentation can be found in Mapping::get_data()
264 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
265 get_data(const UpdateFlags, const Quadrature<dim> &quadrature) const override;
266
267 using Mapping<dim, spacedim>::get_face_data;
268
269 // documentation can be found in Mapping::get_face_data()
270 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
271 get_face_data(const UpdateFlags flags,
272 const hp::QCollection<dim - 1> &quadrature) const override;
273
274 // documentation can be found in Mapping::get_subface_data()
275 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
276 get_subface_data(const UpdateFlags flags,
277 const Quadrature<dim - 1> &quadrature) const override;
278
279 // documentation can be found in Mapping::fill_fe_values()
280 virtual CellSimilarity::Similarity
281 fill_fe_values(
282 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
283 const CellSimilarity::Similarity cell_similarity,
284 const Quadrature<dim> &quadrature,
285 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
286 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
287 &output_data) const override;
288
289 using Mapping<dim, spacedim>::fill_fe_face_values;
290
291 // documentation can be found in Mapping::fill_fe_face_values()
292 virtual void
293 fill_fe_face_values(
294 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
295 const unsigned int face_no,
296 const hp::QCollection<dim - 1> &quadrature,
297 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
298 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
299 &output_data) const override;
300
301 // documentation can be found in Mapping::fill_fe_subface_values()
302 virtual void
303 fill_fe_subface_values(
304 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
305 const unsigned int face_no,
306 const unsigned int subface_no,
307 const Quadrature<dim - 1> &quadrature,
308 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
309 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
310 &output_data) const override;
311
312 // documentation can be found in Mapping::fill_fe_immersed_surface_values()
313 virtual void
314 fill_fe_immersed_surface_values(
315 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
316 const NonMatching::ImmersedSurfaceQuadrature<dim> &quadrature,
317 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
318 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
319 &output_data) const override;
320
321 /**
322 * @}
323 */
324
325 /**
326 * Update the cell_extents field of the incoming InternalData object with the
327 * size of the incoming cell.
328 */
329 void
330 update_cell_extents(
331 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
332 const CellSimilarity::Similarity cell_similarity,
333 const InternalData &data) const;
334
335 /**
336 * Compute the quadrature points if the UpdateFlags of the incoming
337 * InternalData object say that they should be updated.
338 *
339 * Called from fill_fe_values.
340 */
341 void
342 maybe_update_cell_quadrature_points(
343 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
344 const InternalData &data,
345 const ArrayView<const Point<dim>> &unit_quadrature_points,
346 std::vector<Point<dim>> &quadrature_points) const;
347
348 /**
349 * Compute the quadrature points if the UpdateFlags of the incoming
350 * InternalData object say that they should be updated.
351 *
352 * Called from fill_fe_face_values.
353 */
354 void
355 maybe_update_face_quadrature_points(
356 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
357 const unsigned int face_no,
358 const InternalData &data,
359 std::vector<Point<dim>> &quadrature_points) const;
360
361 /**
362 * Compute the quadrature points if the UpdateFlags of the incoming
363 * InternalData object say that they should be updated.
364 *
365 * Called from fill_fe_subface_values.
366 */
367 void
368 maybe_update_subface_quadrature_points(
369 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
370 const unsigned int face_no,
371 const unsigned int sub_no,
372 const InternalData &data,
373 std::vector<Point<dim>> &quadrature_points) const;
374
375 /**
376 * Compute the normal vectors if the UpdateFlags of the incoming InternalData
377 * object say that they should be updated.
378 */
379 void
380 maybe_update_normal_vectors(
381 const unsigned int face_no,
382 const InternalData &data,
383 std::vector<Tensor<1, dim>> &normal_vectors) const;
384
385 /**
386 * Since the Jacobian is constant for this mapping all derivatives of the
387 * Jacobian are identically zero. Fill these quantities with zeros if the
388 * corresponding update flags say that they should be updated.
389 */
390 void
391 maybe_update_jacobian_derivatives(
392 const InternalData &data,
393 const CellSimilarity::Similarity cell_similarity,
394 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
395 &output_data) const;
396
397
398 /**
399 * Compute the volume elements if the UpdateFlags of the incoming
400 * InternalData object say that they should be updated.
401 */
402 void
403 maybe_update_volume_elements(const InternalData &data) const;
404
405 /**
406 * Compute the Jacobians if the UpdateFlags of the incoming
407 * InternalData object say that they should be updated.
408 */
409 void
410 maybe_update_jacobians(
411 const InternalData &data,
412 const CellSimilarity::Similarity cell_similarity,
413 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
414 &output_data) const;
415
416 /**
417 * Compute the inverse Jacobians if the UpdateFlags of the incoming
418 * InternalData object say that they should be updated.
419 */
420 void
421 maybe_update_inverse_jacobians(
422 const InternalData &data,
423 const CellSimilarity::Similarity cell_similarity,
424 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
425 &output_data) const;
426 };
427
428 /** @} */
429
430 DEAL_II_NAMESPACE_CLOSE
431
432 #endif