| 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 |