Debian Codegraph @

include/deal.II/matrix_free/mapping_info_storage.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2023 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
16 #ifndef dealii_matrix_free_mapping_info_storage_h
17 #define dealii_matrix_free_mapping_info_storage_h
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/aligned_vector.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/quadrature.h>
25 #include <deal.II/base/tensor.h>
26 #include <deal.II/base/vectorization.h>
27
28 #include <deal.II/fe/fe_update_flags.h>
29
30 #include <deal.II/hp/q_collection.h>
31
32 #include <memory>
33
34
35 DEAL_II_NAMESPACE_OPEN
36
37
38 namespace internal
39 {
40 namespace MatrixFreeFunctions
41 {
42 // forward declaration
43 struct TaskInfo;
44
45 /**
46 * An enum to identify various types of cells and faces. The most general
47 * type is what we typically compute in the FEValues context but for many
48 * geometries we can save significant storage.
49 *
50 * @ingroup matrixfree
51 */
52 enum GeometryType : unsigned char
53 {
54 /**
55 * The cell or face is Cartesian.
56 */
57 cartesian = 0,
58
59 /**
60 * The cell or face can be described with an affine mapping.
61 */
62 affine = 1,
63
64 /**
65 * The face is flat, i.e., the normal factor on a face is the same on
66 * all quadrature points. This type is not assigned for cells.
67 */
68 flat_faces = 2,
69
70 /**
71 * There is no special information available for compressing the
72 * representation of the object under consideration.
73 */
74 general = 3
75 };
76
77
78
79 /**
80 * Definition of a structure that stores all cached data related to the
81 * evaluated geometry from the mapping. In order to support hp-adaptivity
82 * and compressed storage (in particular for Jacobians, JxW values, and
83 * normals), storage length can be different for different rows. Thus, it
84 * allows to jump at the data of individual rows similar to compressed row
85 * storage in sparse matrices. We have two different start indices for
86 * fields with different sizes. The first category of offsets are the
87 * indices for Jacobians of the transformation from unit to real cell (we
88 * store the inverse Jacobian), second derivatives, JxW values, and normal
89 * vectors. We keep separate arrays for all these data structures because
90 * a user code might access only some of them. In such a case, one array
91 * will be gone through in a contiguous order with access to all entries,
92 * which makes it easy for the processor to prefetch data. Having all data
93 * in a single array would require some strides in the access pattern,
94 * which is much more complicated for the processor to predict (and indeed
95 * leads to prefetching of data that does not get used on Intel processors
96 * such as BroadwellEP).
97 *
98 * The second category of indices are the offsets for the quadrature
99 * points. Quadrature points can be compressed less than the other fields
100 * and thus need longer fields. Quadrature point indices are often used in
101 * other contexts such as evaluation of right hand sides.
102 *
103 * The third component is a descriptor of data from the unit cells, called
104 * QuadratureDescriptor, which contains the quadrature weights and
105 * permutations of how to go through quadrature points in case of face
106 * data. The latter comes in a vector for the support of hp-adaptivity,
107 * with several data fields for the individual quadrature formulas.
108 *
109 * @ingroup matrixfree
110 */
111 template <int structdim, int spacedim, typename Number>
112 struct MappingInfoStorage
113 {
114 struct QuadratureDescriptor
115 {
116 /**
117 * In case this class is instantiated for VectorizedArray types, this
118 * indicates the underlying scalar type for data which is the same on
119 * all lanes like the quadrature weights.
120 */
121 using ScalarNumber = typename VectorizedArrayTrait<Number>::value_type;
122
123 /**
124 * Constructor. Does nothing.
125 */
126 QuadratureDescriptor();
127
128 /**
129 * Set up the lengths in the various members of this struct.
130 */
131 template <int dim_q>
132 void
133 initialize(const Quadrature<dim_q> &quadrature);
134
135 /**
136 * Set up the lengths in the various members of this struct.
137 */
138 void
139 initialize(const Quadrature<1> &quadrature_1d);
140
141 /**
142 * Returns the memory consumption in bytes.
143 */
144 std::size_t
145 memory_consumption() const;
146
147 /**
148 * Number of quadrature points applied on the given cell or face.
149 */
150 unsigned int n_q_points;
151
152 /**
153 * Original one-dimensional quadrature formula applied on the given
154 * cell or face.
155 */
156 Quadrature<1> quadrature_1d;
157
158 /**
159 * Quadrature formula applied on the given cell or face.
160 */
161 Quadrature<structdim> quadrature;
162
163 /**
164 * Quadrature weights separated by dimension for use in specific
165 * situations.
166 */
167 std::array<AlignedVector<ScalarNumber>, structdim>
168 tensor_quadrature_weights;
169
170 /**
171 * A cached vector of quadrature weights in the given number format
172 * (non-vectorized, as it is cheap to broadcast the value to all lanes
173 * when it is used in a vectorized context).
174 */
175 AlignedVector<ScalarNumber> quadrature_weights;
176 };
177
178 /**
179 * A class describing the layout of the sections in the @p data_storage
180 * field and also includes some data that depends on the number of
181 * quadrature points in the hp-context such as the inner quadrature
182 * formula and re-indexing for faces that are not in the standard
183 * orientation.
184 */
185 std::vector<QuadratureDescriptor> descriptor;
186
187 /**
188 * Collection of quadrature formulae applied on the given face.
189 *
190 * @note Only filled for faces, since faces might be quadrilateral or
191 * triangle shaped.
192 */
193 std::vector<dealii::hp::QCollection<structdim>> q_collection;
194
195 /**
196 * Stores the index offset into the arrays @p jxw_values, @p jacobians,
197 * @p normal_vectors and the second derivatives. Note that affine cells
198 * have shorter fields of length 1, where the others have lengths equal
199 * to the number of quadrature points of the given cell.
200 */
201 AlignedVector<unsigned int> data_index_offsets;
202
203 /**
204 * The storage of the Jacobian determinant (times the quadrature weight
205 * in case the transformation is non-affine) on quadrature
206 * points.
207 *
208 * Indexed by @p data_index_offsets.
209 */
210 AlignedVector<Number> JxW_values;
211
212 /**
213 * Stores the normal vectors.
214 *
215 * Indexed by @p data_index_offsets.
216 */
217 AlignedVector<Tensor<1, spacedim, Number>> normal_vectors;
218
219 /**
220 * The storage of covariant transformation on quadrature points, i.e.,
221 * the inverse and transposed Jacobians of the transformation from the
222 * unit to the real cell.
223 *
224 * Indexed by @p data_index_offsets.
225 *
226 * Contains two fields for access from both sides for interior faces,
227 * but the default case (cell integrals or boundary integrals) only
228 * fills the zeroth component and ignores the first one.
229 *
230 * If the cell is Cartesian/affine then the Jacobian is stored at index 1
231 * of the AlignedVector. For faces on hypercube elements, the derivatives
232 * are reorder s.t the derivative orthogonal to the face is stored last,
233 * i.e for dim = 3 and face_no = 0 or 1, the derivatives are ordered as
234 * [dy, dz, dx], face_no = 2 or 3: [dz, dx, dy], and face_no = 5 or 6:
235 * [dx, dy, dz]. If the Jacobian also is stored, the components are
236 * instead reordered in the same way.
237 */
238 std::array<AlignedVector<Tensor<2, spacedim, Number>>, 2> jacobians;
239
240 /**
241 * The storage of the gradients of the inverse Jacobian
242 * transformation. Because of symmetry, only the upper diagonal and
243 * diagonal part are needed. The first index runs through the
244 * derivatives, starting with the diagonal and then continuing row-wise,
245 * i.e., $\partial^2/\partial x_1 \partial x_2$ first, then
246 * $\partial^2/\partial x_1 \partial x_3$, and so on. The second index
247 * is the spatial coordinate.
248 *
249 * Indexed by @p data_index_offsets.
250 *
251 * Contains two fields for access from both sides for interior faces,
252 * but the default case (cell integrals or boundary integrals) only
253 * fills the zeroth component and ignores the first one.
254 */
255 std::array<
256 AlignedVector<
257 Tensor<1, spacedim *(spacedim + 1) / 2, Tensor<1, spacedim, Number>>>,
258 2>
259 jacobian_gradients;
260
261 /**
262 * The storage of the gradients of the Jacobian transformation. Because of
263 * symmetry, only the upper diagonal and diagonal part are needed. The
264 * first index runs through the derivatives, starting with the diagonal
265 * and then continuing row-wise, i.e., $\partial^2/\partial x_1 \partial
266 * x_2$ first, then
267 * $\partial^2/\partial x_1 \partial x_3$, and so on. The second index
268 * is the spatial coordinate.
269 *
270 * Indexed by @p data_index_offsets.
271 *
272 * Contains two fields for access from both sides for interior faces,
273 * but the default case (cell integrals or boundary integrals) only
274 * fills the zeroth component and ignores the first one.
275 */
276 std::array<
277 AlignedVector<
278 Tensor<1, spacedim *(spacedim + 1) / 2, Tensor<1, spacedim, Number>>>,
279 2>
280 jacobian_gradients_non_inverse;
281
282 /**
283 * Stores the Jacobian transformations times the normal vector (this
284 * represents a shortcut that is accessed often and can thus get higher
285 * performance).
286 *
287 * Indexed by @p data_index_offsets.
288 */
289 std::array<AlignedVector<Tensor<1, spacedim, Number>>, 2>
290 normals_times_jacobians;
291
292 /**
293 * Stores the index offset of a particular cell into the quadrature
294 * points array in real coordinates. Note that Cartesian cells have
295 * shorter fields (length is @p n_q_points_1d) than non-Cartesian cells
296 * (length is @p n_q_points) or faces.
297 */
298 AlignedVector<unsigned int> quadrature_point_offsets;
299
300 /**
301 * Stores the quadrature points in real coordinates, including a
302 * compression scheme for Cartesian cells where we do not need to store
303 * the full data on all points.
304 *
305 * Indexed by @p quadrature_point_offsets.
306 */
307 AlignedVector<Point<spacedim, Number>> quadrature_points;
308
309 /**
310 * Clears all data fields except the descriptor vector.
311 */
312 void
313 clear_data_fields();
314
315 /**
316 * Returns the quadrature index for a given number of quadrature
317 * points. If not in hp-mode or if the index is not found, this
318 * function always returns index 0. Hence, this function does not
319 * check whether the given degree is actually present.
320 */
321 unsigned int
322 quad_index_from_n_q_points(const unsigned int n_q_points) const;
323
324 /**
325 * Helper function to determine which update flags must be set in the
326 * internal functions to initialize all data as requested by the user.
327 */
328 static UpdateFlags
329 compute_update_flags(
330 const UpdateFlags update_flags,
331 const std::vector<dealii::hp::QCollection<spacedim>> &quads =
332 std::vector<dealii::hp::QCollection<spacedim>>(),
333 const bool piola_transform = false);
334
335 /**
336 * Prints a detailed summary of memory consumption in the different
337 * structures of this class to the given output stream.
338 */
339 template <typename StreamType>
340 void
341 print_memory_consumption(StreamType &out,
342 const TaskInfo &task_info) const;
343
344 /**
345 * Returns the memory consumption in bytes.
346 */
347 std::size_t
348 memory_consumption() const;
349 };
350
351
352
353 /* ------------------- inline functions ----------------------------- */
354
355 template <int structdim, int spacedim, typename Number>
356 inline unsigned int
357 MappingInfoStorage<structdim, spacedim, Number>::quad_index_from_n_q_points(
358 const unsigned int n_q_points) const
359 {
360 for (unsigned int i = 0; i < descriptor.size(); ++i)
361 if (n_q_points == descriptor[i].n_q_points)
362 return i;
363 return 0;
364 }
365
366 } // end of namespace MatrixFreeFunctions
367 } // end of namespace internal
368
369 DEAL_II_NAMESPACE_CLOSE
370
371 #endif