Debian Codegraph @

include/deal.II/fe/fe_update_flags.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_fe_update_flags_h
16 #define dealii_fe_update_flags_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/table.h>
22 #include <deal.II/base/tensor.h>
23
24 #include <vector>
25
26
27 DEAL_II_NAMESPACE_OPEN
28
29 // Forward declaration
30 #ifndef DOXYGEN
31 template <int, int>
32 class FiniteElement;
33 #endif
34
35 /** @addtogroup feaccess */
36 /** @{ */
37
38 /**
39 * The enum type given to the constructors of FEValues, FEFaceValues and
40 * FESubfaceValues, telling those objects which data will be needed on each
41 * mesh cell.
42 *
43 * Selecting these flags in a restrictive way is crucial for the efficiency of
44 * FEValues::reinit(), FEFaceValues::reinit() and FESubfaceValues::reinit().
45 * Therefore, only the flags actually needed should be selected. It is the
46 * responsibility of the involved Mapping and FiniteElement to add additional
47 * flags according to their own requirements. For instance, most finite
48 * elements will add #update_covariant_transformation if #update_gradients is
49 * selected. By default, all flags are off, i.e. no reinitialization will be
50 * done.
51 *
52 * You can select more than one flag by concatenation using the bitwise or
53 * operator|(UpdateFlags,UpdateFlags).
54 *
55 * <h3>Use of these flags flags</h3>
56 *
57 * More information on the use of this type both in user code as well as
58 * internally can be found in the documentation topics pages on
59 * @ref UpdateFlags "The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues"
60 * and
61 * @ref FE_vs_Mapping_vs_FEValues "How Mapping, FiniteElement, and FEValues work together".
62 */
63 enum UpdateFlags
64 {
65 //! No update
66 update_default = 0,
67 //! Shape function values
68 /**
69 * Compute the values of the shape functions at the quadrature points on the
70 * real space cell. For the usual Lagrange elements, these values are equal
71 * to the values of the shape functions at the quadrature points on the unit
72 * cell, but they are different for more complicated elements, such as
73 * FE_RaviartThomas elements.
74 */
75 update_values = 0x0001,
76 //! Shape function gradients
77 /**
78 * Compute the gradients of the shape functions in coordinates of the real
79 * cell.
80 */
81 update_gradients = 0x0002,
82 //! Second derivatives of shape functions
83 /**
84 * Compute the second derivatives of the shape functions in coordinates of
85 * the real cell.
86 */
87 update_hessians = 0x0004,
88 //! Third derivatives of shape functions
89 /**
90 * Compute the third derivatives of the shape functions in coordinates of
91 * the real cell
92 */
93 update_3rd_derivatives = 0x0008,
94 //! Outer normal vector, not normalized
95 /**
96 * Vector product of tangential vectors, yielding a normal vector with a
97 * length corresponding to the surface element; may be more efficient than
98 * computing both.
99 */
100 update_boundary_forms = 0x0010,
101 //! Transformed quadrature points
102 /**
103 * Compute the quadrature points location in real cell coordinates.
104 *
105 * FEValues objects take the quadrature point locations on the
106 * reference cell as an argument of the constructor (via the
107 * Quadrature object). For most finite elements, knowing the
108 * location of quadrature points on the reference cell is all that
109 * is necessary to evaluate shape functions, evaluate the mapping,
110 * and other things. On the other hand, if you want to evaluate a
111 * right hand side function $f(\mathbf x_q)$ at quadrature point
112 * locations $\mathbf x_q$ on the real cell, you need to pass this
113 * flag to the FEValues constructor to make sure you can later
114 * access them.
115 *
116 * There are contexts other than FEValues (and related classes) that
117 * take update flags. An example is the DataPostprocessor class
118 * (and derived classes). In these cases, the `update_quadrature_points`
119 * flag is generally understood to update the location of "evaluation
120 * points", i.e., the physical locations of the points at which
121 * the solution is evaluated. As a consequence, the flag is
122 * misnamed in these contexts: No quadrature (i.e., computation of
123 * integrals) is involved, and consequently what is being
124 * updated is, in the context of DataPostprocessor, the member variable
125 * DataPostprocessorInputs::CommonInputs::evaluation_points.
126 */
127 update_quadrature_points = 0x0020,
128 //! Transformed quadrature weights
129 /**
130 * Compute the quadrature weights on the real cell, i.e. the weights of the
131 * quadrature rule multiplied with the determinant of the Jacobian of the
132 * transformation from reference to real cell.
133 */
134 update_JxW_values = 0x0040,
135 //! Normal vectors
136 /**
137 * Compute the normal vectors, either for a face or for a cell of
138 * codimension one. Setting this flag for any other object will raise an
139 * error.
140 */
141 update_normal_vectors = 0x0080,
142 //! Volume element
143 /**
144 * Compute the Jacobian of the transformation from the reference cell to the
145 * real cell.
146 */
147 update_jacobians = 0x0100,
148 //! Gradient of volume element
149 /**
150 * Compute the derivatives of the Jacobian of the transformation.
151 */
152 update_jacobian_grads = 0x0200,
153 //! Volume element
154 /**
155 * Compute the inverse Jacobian of the transformation from the reference
156 * cell to the real cell.
157 */
158 update_inverse_jacobians = 0x0400,
159 //! Covariant transformation
160 /**
161 * Compute all values the Mapping needs to perform a contravariant
162 * transformation of vectors. For special mappings like MappingCartesian
163 * this may be simpler than #update_inverse_jacobians.
164 */
165 update_covariant_transformation = 0x0800,
166 //! Contravariant transformation
167 /**
168 * Compute all values the Mapping needs to perform a contravariant
169 * transformation of vectors. For special mappings like MappingCartesian
170 * this may be simpler than #update_jacobians.
171 */
172 update_contravariant_transformation = 0x1000,
173 //! Shape function values of transformation
174 /**
175 * Compute the shape function values of the transformation defined by the
176 * Mapping.
177 */
178 update_transformation_values = 0x2000,
179 //! Shape function gradients of transformation
180 /**
181 * Compute the shape function gradients of the transformation defined by the
182 * Mapping.
183 */
184 update_transformation_gradients = 0x4000,
185 //! Determinant of the Jacobian
186 /**
187 * Compute the volume element in each quadrature point.
188 */
189 update_volume_elements = 0x10000,
190 /**
191 * Compute the derivatives of the Jacobian of the transformation pushed
192 * forward to the real cell coordinates.
193 */
194 update_jacobian_pushed_forward_grads = 0x100000,
195 /**
196 * Compute the second derivatives of the Jacobian of the transformation.
197 */
198 update_jacobian_2nd_derivatives = 0x200000,
199 /**
200 * Compute the second derivatives of the Jacobian of the transformation
201 * pushed forward to the real cell coordinates.
202 */
203 update_jacobian_pushed_forward_2nd_derivatives = 0x400000,
204 /**
205 * Compute the third derivatives of the Jacobian of the transformation.
206 */
207 update_jacobian_3rd_derivatives = 0x800000,
208 /**
209 * Compute the third derivatives of the Jacobian of the transformation
210 * pushed forward to the real cell coordinates.
211 */
212 update_jacobian_pushed_forward_3rd_derivatives = 0x1000000,
213 /**
214 * Update rescaling for Hermite elements.
215 */
216 update_rescale = 0x2000000,
217 //! Values needed for Piola transform
218 /**
219 * Combination of the flags needed for Piola transform of Hdiv elements.
220 */
221 update_piola = update_volume_elements | update_contravariant_transformation,
222 /**
223 * Combination of the flags that require a mapping calculation
224 */
225 update_mapping =
226 // Direct data
227 update_quadrature_points | update_JxW_values | update_jacobians |
228 update_jacobian_grads | update_jacobian_pushed_forward_grads |
229 update_jacobian_2nd_derivatives |
230 update_jacobian_pushed_forward_2nd_derivatives |
231 update_jacobian_3rd_derivatives |
232 update_jacobian_pushed_forward_3rd_derivatives | update_inverse_jacobians |
233 update_boundary_forms | update_normal_vectors |
234 // Transformation dependence
235 update_covariant_transformation | update_contravariant_transformation |
236 update_transformation_values | update_transformation_gradients |
237 // Volume data
238 update_volume_elements |
239 // Hermite needs several DOFs to be rescaled each time
240 update_rescale
241 };
242
243
244 /**
245 * Output operator which outputs update flags as a set of or'd text values.
246 *
247 * @ref UpdateFlags
248 */
249 template <typename StreamType>
250 inline StreamType &
251 operator<<(StreamType &s, const UpdateFlags u)
252 {
253 s << " UpdateFlags|";
254 if (u & update_values)
255 s << "values|";
256 if (u & update_gradients)
257 s << "gradients|";
258 if (u & update_hessians)
259 s << "hessians|";
260 if (u & update_3rd_derivatives)
261 s << "3rd_derivatives|";
262 if (u & update_quadrature_points)
263 s << "quadrature_points|";
264 if (u & update_JxW_values)
265 s << "JxW_values|";
266 if (u & update_normal_vectors)
267 s << "normal_vectors|";
268 if (u & update_jacobians)
269 s << "jacobians|";
270 if (u & update_inverse_jacobians)
271 s << "inverse_jacobians|";
272 if (u & update_jacobian_grads)
273 s << "jacobian_grads|";
274 if (u & update_covariant_transformation)
275 s << "covariant_transformation|";
276 if (u & update_contravariant_transformation)
277 s << "contravariant_transformation|";
278 if (u & update_transformation_values)
279 s << "transformation_values|";
280 if (u & update_transformation_gradients)
281 s << "transformation_gradients|";
282 if (u & update_jacobian_pushed_forward_grads)
283 s << "jacobian_pushed_forward_grads|";
284 if (u & update_jacobian_2nd_derivatives)
285 s << "jacobian_2nd_derivatives|";
286 if (u & update_jacobian_pushed_forward_2nd_derivatives)
287 s << "jacobian_pushed_forward_2nd_derivatives|";
288 if (u & update_jacobian_3rd_derivatives)
289 s << "jacobian_3rd_derivatives|";
290 if (u & update_jacobian_pushed_forward_3rd_derivatives)
291 s << "jacobian_pushed_forward_3rd_derivatives|";
292
293 // TODO: check that 'u' really only has the flags set that are handled above
294 return s;
295 }
296
297
298 /**
299 * Global operator which returns an object in which all bits are set which are
300 * either set in the first or the second argument. This operator exists since
301 * if it did not then the result of the bit-or <tt>operator |</tt> would be an
302 * integer which would in turn trigger a compiler warning when we tried to
303 * assign it to an object of type UpdateFlags.
304 *
305 * @ref UpdateFlags
306 */
307 inline UpdateFlags
308 operator|(const UpdateFlags f1, const UpdateFlags f2)
309 {
310 return static_cast<UpdateFlags>(static_cast<unsigned int>(f1) |
311 static_cast<unsigned int>(f2));
312 }
313
314
315
316 /**
317 * Global operator which sets the bits from the second argument also in the
318 * first one.
319 *
320 * @ref UpdateFlags
321 */
322 inline UpdateFlags &
323 operator|=(UpdateFlags &f1, const UpdateFlags f2)
324 {
325 f1 = f1 | f2;
326 return f1;
327 }
328
329
330 /**
331 * Global operator which returns an object in which all bits are set which are
332 * set in the first as well as the second argument. This operator exists since
333 * if it did not then the result of the bit-and <tt>operator &</tt> would be
334 * an integer which would in turn trigger a compiler warning when we tried to
335 * assign it to an object of type UpdateFlags.
336 *
337 * @ref UpdateFlags
338 */
339 inline UpdateFlags
340 operator&(const UpdateFlags f1, const UpdateFlags f2)
341 {
342 return static_cast<UpdateFlags>(static_cast<unsigned int>(f1) &
343 static_cast<unsigned int>(f2));
344 }
345
346
347 /**
348 * Global operator which clears all the bits in the first argument if they are
349 * not also set in the second argument.
350 *
351 * @ref UpdateFlags
352 */
353 inline UpdateFlags &
354 operator&=(UpdateFlags &f1, const UpdateFlags f2)
355 {
356 f1 = f1 & f2;
357 return f1;
358 }
359
360
361
362 /**
363 * This enum definition is used for storing similarities of the current cell
364 * to the previously visited cell. This information is used for reusing data
365 * when calling the method FEValues::reinit() (like derivatives, which do not
366 * change if one cell is just a translation of the previous). Currently, this
367 * variable does only recognize a translation and an inverted translation (if
368 * dim<spacedim). However, this concept makes it easy to add additional states
369 * to be detected in FEValues/FEFaceValues for making use of these
370 * similarities as well.
371 */
372 namespace CellSimilarity
373 {
374 enum Similarity
375 {
376 /**
377 * The cells differ by something besides a translation or inverted
378 * translations.
379 */
380 none,
381 /**
382 * The cells differ by a translation.
383 */
384 translation,
385 /**
386 * The cells differ by an inverted translation.
387 */
388 inverted_translation,
389 /**
390 * The next cell is not valid.
391 */
392 invalid_next_cell
393 };
394 }
395
396
397 namespace internal
398 {
399 namespace FEValuesImplementation
400 {
401 /**
402 * A class that stores all of the shape function related data used in
403 * dealii::FEValues, dealii::FEFaceValues, and dealii::FESubfaceValues
404 * objects. Objects of this kind will be given as <i>output</i> argument
405 * when dealii::FEValues::reinit() calls FiniteElement::fill_fe_values().
406 *
407 * @ingroup feaccess
408 */
409 template <int dim, int spacedim = dim>
410 class FiniteElementRelatedData
411 {
412 public:
413 /**
414 * Initialize all vectors to correct size.
415 */
416 void
417 initialize(const unsigned int n_quadrature_points,
418 const FiniteElement<dim, spacedim> &fe,
419 const UpdateFlags flags);
420
421 /**
422 * Compute and return an estimate for the memory consumption (in bytes)
423 * of this object.
424 */
425 std::size_t
426 memory_consumption() const;
427
428 /**
429 * Storage type for shape values. Each row in the matrix denotes the
430 * values of a single shape function at the different points, columns
431 * are for a single point with the different shape functions.
432 *
433 * If a shape function has more than one non-zero component (in deal.II
434 * diction: it is non-primitive), then we allocate one row per non-zero
435 * component, and shift subsequent rows backward. Lookup of the correct
436 * row for a shape function is thus simple in case the entire finite
437 * element is primitive (i.e. all shape functions are primitive), since
438 * then the shape function number equals the row number. Otherwise, use
439 * the #shape_function_to_row_table array to get at the first row that
440 * belongs to this particular shape function, and navigate among all the
441 * rows for this shape function using the
442 * FiniteElement::get_nonzero_components() function which tells us which
443 * components are non-zero and thus have a row in the array presently
444 * under discussion.
445 */
446 using ShapeVector = dealii::Table<2, double>;
447
448 /**
449 * Storage type for gradients. The layout of data is the same as for the
450 * #ShapeVector data type.
451 */
452 using GradientVector = dealii::Table<2, Tensor<1, spacedim>>;
453
454 /**
455 * Likewise for second order derivatives.
456 */
457 using HessianVector = dealii::Table<2, Tensor<2, spacedim>>;
458
459 /**
460 * And the same also applies to the third order derivatives.
461 */
462 using ThirdDerivativeVector = dealii::Table<2, Tensor<3, spacedim>>;
463
464 /**
465 * Store the values of the shape functions at the quadrature points. See
466 * the description of the data type for the layout of the data in this
467 * field.
468 */
469 ShapeVector shape_values;
470
471 /**
472 * Store the gradients of the shape functions at the quadrature points.
473 * See the description of the data type for the layout of the data in
474 * this field.
475 */
476 GradientVector shape_gradients;
477
478 /**
479 * Store the 2nd derivatives of the shape functions at the quadrature
480 * points. See the description of the data type for the layout of the
481 * data in this field.
482 */
483 HessianVector shape_hessians;
484
485 /**
486 * Store the 3rd derivatives of the shape functions at the quadrature
487 * points. See the description of the data type for the layout of the
488 * data in this field.
489 */
490 ThirdDerivativeVector shape_3rd_derivatives;
491
492 /**
493 * When asked for the value (or gradient, or Hessian) of shape function
494 * i's c-th vector component, we need to look it up in the
495 * #shape_values, #shape_gradients and #shape_hessians arrays. The
496 * question is where in this array does the data for shape function i,
497 * component c reside. This is what this table answers.
498 *
499 * The format of the table is as follows: - It has dofs_per_cell times
500 * n_components entries. - The entry that corresponds to shape function
501 * i, component c is <code>i * n_components + c</code>. - The value
502 * stored at this position indicates the row in #shape_values and the
503 * other tables where the corresponding datum is stored for all the
504 * quadrature points.
505 *
506 * In the general, vector-valued context, the number of components is
507 * larger than one, but for a given shape function, not all vector
508 * components may be nonzero (e.g., if a shape function is primitive,
509 * then exactly one vector component is non-zero, while the others are
510 * all zero). For such zero components, #shape_values and friends do not
511 * have a row. Consequently, for vector components for which shape
512 * function i is zero, the entry in the current table is
513 * numbers::invalid_unsigned_int.
514 *
515 * On the other hand, the table is guaranteed to have at least one valid
516 * index for each shape function. In particular, for a primitive finite
517 * element, each shape function has exactly one nonzero component and so
518 * for each i, there is exactly one valid index within the range
519 * <code>[i*n_components, (i+1)*n_components)</code>.
520 */
521 std::vector<unsigned int> shape_function_to_row_table;
522 };
523 } // namespace FEValuesImplementation
524 } // namespace internal
525
526
527 /** @} */
528
529
530
531 DEAL_II_NAMESPACE_CLOSE
532
533 #endif