Debian Codegraph @

include/deal.II/fe/mapping_p1.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 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_p1_h
16 #define dealii_mapping_p1_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 * @brief Implementation of the classic affine transformation mapping used for
37 * simplices.
38 *
39 * For simplex cells, the transformation mapping the unit to real cell may be
40 * written as an affine transformation: that is
41 *
42 * @f[
43 * \begin{pmatrix}
44 * x \\
45 * y
46 * \end{pmatrix}
47 * =
48 * \begin{pmatrix}
49 * x_1 - x_0 & x_2 - x_0 \\
50 * y_1 - y_0 & y_2 - y_0
51 * \end{pmatrix}
52 * \begin{pmatrix}
53 * \hat{x} \\
54 * \hat{y}
55 * \end{pmatrix}
56 * +
57 * \begin{pmatrix}
58 * x_0 \\
59 * y_0
60 * \end{pmatrix}
61 * @f]
62 *
63 * in which $(x_0, y_0)$, $(x_1, y_1)$ and $(x_2, y_2)$ are the vertices of a
64 * triangle (in a codimension zero space). Unlike MappingQ1, this mapping is
65 * affine, not bilinear or trilinear. Hence, this mapping's transformation
66 * matrices (i.e., the covariant and contravariant transformations) and shift
67 * vector are constant on each cell. This property makes this mapping
68 * significantly more efficient than the equivalent MappingFE set up with a
69 * linear FE_SimplexP.
70 */
71 template <int dim, int spacedim = dim>
72 class MappingP1 : public Mapping<dim, spacedim>
73 {
74 public:
75 /**
76 * Default constructor.
77 */
78 MappingP1() = default;
79
80 virtual std::unique_ptr<Mapping<dim, spacedim>>
81 clone() const override;
82
83 /**
84 * Return @p true because MappingP1 preserves vertex locations.
85 */
86 virtual bool
87 preserves_vertex_locations() const override;
88
89 /**
90 * This mapping is compatible with simplex reference cells.
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 virtual Point<spacedim>
101 transform_unit_to_real_cell(
102 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
103 const Point<dim> &p) const override;
104
105 virtual Point<dim>
106 transform_real_to_unit_cell(
107 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
108 const Point<spacedim> &p) const override;
109
110 virtual void
111 transform_points_real_to_unit_cell(
112 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
113 const ArrayView<const Point<spacedim>> &real_points,
114 const ArrayView<Point<dim>> &unit_points) const override;
115
116 /**
117 * @}
118 */
119
120 /**
121 * @name Functions to transform tensors from reference to real coordinates
122 * @{
123 */
124
125 virtual void
126 transform(const ArrayView<const Tensor<1, dim>> &input,
127 const MappingKind kind,
128 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
129 const ArrayView<Tensor<1, spacedim>> &output) const override;
130
131 virtual void
132 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
133 const MappingKind kind,
134 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
135 const ArrayView<Tensor<2, spacedim>> &output) const override;
136
137 virtual void
138 transform(const ArrayView<const Tensor<2, dim>> &input,
139 const MappingKind kind,
140 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
141 const ArrayView<Tensor<2, spacedim>> &output) const override;
142
143 virtual void
144 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
145 const MappingKind kind,
146 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
147 const ArrayView<Tensor<3, spacedim>> &output) const override;
148
149 virtual void
150 transform(const ArrayView<const Tensor<3, dim>> &input,
151 const MappingKind kind,
152 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
153 const ArrayView<Tensor<3, spacedim>> &output) const override;
154
155 /**
156 * @}
157 */
158
159 /**
160 * As opposed to the other fill_fe_values() and fill_fe_face_values()
161 * functions that rely on pre-computed information of InternalDataBase, this
162 * function chooses the flexible evaluation path on the cell and points
163 * passed in to the current function.
164 *
165 * @param[in] cell The cell where to evaluate the mapping
166 *
167 * @param[in] unit_points The points in reference coordinates where the
168 * transformation (Jacobians, positions) should be computed.
169 *
170 * @param[in] update_flags The kind of information that should be computed.
171 *
172 * @param[out] output_data A struct containing the evaluated quantities such
173 * as the Jacobian resulting from application of the mapping on the given
174 * cell with its underlying manifolds.
175 */
176 void
177 fill_mapping_data_for_generic_points(
178 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
179 const ArrayView<const Point<dim>> &unit_points,
180 const UpdateFlags update_flags,
181 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
182 &output_data) const;
183
184 /**
185 * @name Interface with FEValues
186 * @{
187 */
188
189 /**
190 * Storage for internal data of the mapping. See Mapping::InternalDataBase
191 * for an extensive description.
192 *
193 * This includes data that is computed once when the object is created (in
194 * get_data()) as well as data the class wants to store from between the
195 * call to fill_fe_values(), fill_fe_face_values(), or
196 * fill_fe_subface_values() until possible later calls from the finite
197 * element to functions such as transform(). The latter class of member
198 * variables are marked as 'mutable'.
199 */
200 class InternalData : public Mapping<dim, spacedim>::InternalDataBase
201 {
202 public:
203 /**
204 * Constructor for use with arbitrary points.
205 */
206 InternalData(const ArrayView<const Point<dim>> &quadrature_points);
207
208 /**
209 * Constructor.
210 */
211 InternalData(const Quadrature<dim> &quadrature);
212
213 virtual void
214 reinit(const UpdateFlags update_flags,
215 const Quadrature<dim> &quadrature) override;
216
217 /**
218 * Return an estimate (in bytes) for the memory consumption of this object.
219 */
220 virtual std::size_t
221 memory_consumption() const override;
222
223 /**
224 * Affine component of the transformation.
225 */
226 mutable Tensor<1, spacedim> affine_component;
227
228 /**
229 * Linear component of the transformation (the contravariant).
230 */
231 mutable DerivativeForm<1, dim, spacedim> linear_component;
232
233 /**
234 * Covariant form of the linear transformation.
235 */
236 mutable DerivativeForm<1, dim, spacedim> covariant;
237
238 /**
239 * Determinant of linear_component.
240 */
241 mutable double determinant;
242
243 /**
244 * Quadrature. May be an amalgamation of rules created by, e.g.,
245 * QProjector::project_to_all_faces().
246 */
247 Quadrature<dim> quadrature;
248 };
249
250 private:
251 virtual UpdateFlags
252 requires_update_flags(const UpdateFlags update_flags) const override;
253
254 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
255 get_data(const UpdateFlags, const Quadrature<dim> &quadrature) const override;
256
257 using Mapping<dim, spacedim>::get_face_data;
258
259 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
260 get_face_data(const UpdateFlags flags,
261 const hp::QCollection<dim - 1> &quadrature) const override;
262
263 virtual std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
264 get_subface_data(const UpdateFlags flags,
265 const Quadrature<dim - 1> &quadrature) const override;
266
267 virtual CellSimilarity::Similarity
268 fill_fe_values(
269 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
270 const CellSimilarity::Similarity cell_similarity,
271 const Quadrature<dim> &quadrature,
272 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
273 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
274 &output_data) const override;
275
276 using Mapping<dim, spacedim>::fill_fe_face_values;
277
278 virtual void
279 fill_fe_face_values(
280 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
281 const unsigned int face_no,
282 const hp::QCollection<dim - 1> &quadrature,
283 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
284 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
285 &output_data) const override;
286
287 virtual void
288 fill_fe_subface_values(
289 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
290 const unsigned int face_no,
291 const unsigned int subface_no,
292 const Quadrature<dim - 1> &quadrature,
293 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
294 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
295 &output_data) const override;
296
297 /**
298 * @}
299 */
300
301 /**
302 * Update the affine and linear components fields of the incoming InternalData
303 * object.
304 */
305 void
306 update_transformation(
307 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
308 const InternalData &data) const;
309
310 /**
311 * Transform quadrature points from the unit cell to the real cell.
312 */
313 void
314 transform_quadrature_points(
315 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
316 const InternalData &data,
317 const typename QProjector<dim>::DataSetDescriptor &offset,
318 std::vector<Point<spacedim>> &quadrature_points) const;
319
320 /**
321 * Compute the normal vectors if the UpdateFlags of the incoming InternalData
322 * object say that they should be updated.
323 */
324 void
325 maybe_update_normal_vectors(
326 const unsigned int face_no,
327 const InternalData &data,
328 std::vector<Tensor<1, spacedim>> &normal_vectors) const;
329
330 /**
331 * Since the Jacobian is constant for this mapping all derivatives of the
332 * Jacobian are identically zero. Fill these quantities with zeros if the
333 * corresponding update flags say that they should be updated.
334 */
335 void
336 maybe_update_jacobian_derivatives(
337 const InternalData &data,
338 const CellSimilarity::Similarity cell_similarity,
339 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
340 &output_data) const;
341
342 /**
343 * Compute the Jacobians if the UpdateFlags of the incoming
344 * InternalData object say that they should be updated.
345 */
346 void
347 maybe_update_jacobians(
348 const InternalData &data,
349 const CellSimilarity::Similarity cell_similarity,
350 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
351 &output_data) const;
352
353 /**
354 * Compute the inverse Jacobians if the UpdateFlags of the incoming
355 * InternalData object say that they should be updated.
356 */
357 void
358 maybe_update_inverse_jacobians(
359 const InternalData &data,
360 const CellSimilarity::Similarity cell_similarity,
361 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
362 &output_data) const;
363 };
364
365 /** @} */
366
367 DEAL_II_NAMESPACE_CLOSE
368
369 #endif