Debian Codegraph @

include/deal.II/fe/fe_values_extractors.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2012 - 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_fe_values_extractors_h
16 #define dealii_fe_values_extractors_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/types.h>
22
23 #include <string>
24
25
26 DEAL_II_NAMESPACE_OPEN
27
28
29 /**
30 * A namespace in which we declare "extractors", i.e. classes that when used
31 * as subscripts in operator[] expressions on FEValues, FEFaceValues, and
32 * FESubfaceValues objects extract certain components of a vector-valued
33 * element. The result of applying an extractor to these objects is an object
34 * with corresponding type from the namespace FEValuesViews. There are
35 * extractors for single scalar components, vector components consisting of
36 * <code>dim</code> elements, and second order symmetric tensors consisting of
37 * <code>(dim*dim + dim)/2</code> components, as well as second order
38 * nonsymmetric tensors.
39 *
40 * One can think of extractors as the equivalent of an index, or an index range.
41 * In the case of scalar extractors (i.e., the FEValuesExtractors::Scalar
42 * class), creating an object like (see step-20 for this use)
43 * @code
44 * const FEValuesExtractors::Scalar pressure(dim);
45 * @endcode
46 * can be thought of as creating a single index with value `dim`. By
47 * itself, an index does not know what it is an index to, so it takes
48 * the equivalent of an array to extract anything. Consequently,
49 * assume that there is a finite element with at least `dim+1` vector
50 * components (as indeed there is in step-20), and an FEValues object
51 * that operates on it, then writing
52 * @code
53 * fe_values[pressure]
54 * @endcode
55 * results in an object that represents the shape functions of only the
56 * `dim`th component of the overall element. In the example, these
57 * would be the values of the pressure shape functions, or more precisely:
58 * the (scalar) pressure values of all shape functions (even for shape
59 * functions that are not associated with the pressure, but for example
60 * the velocity). In the example above, the result of using
61 * `operator[]` on the `fe_values` object as shown is of type
62 * FEValuesViews::Scalar.
63 *
64 * Likewise, when using
65 * @code
66 * const FEValuesExtractors::Vector velocities(0);
67 * @endcode
68 * then the object so created can be thought of as an <i>index range</i>,
69 * starting at zero and extending exactly `dim` components on. In Matlab
70 * notation, one could write this as `0:dim-1`. Then, writing
71 * @code
72 * fe_values[velocities]
73 * @endcode
74 * will result in an object that represents the values of a subset of
75 * exactly `dim` vector components of the overall finite element, in
76 * much the same way as writing `array(3:7)` in Matlab would return
77 * an array of length 5 that has been extracted from the original
78 * array by looking at indices 3 through 7 (inclusive).
79 *
80 * See the description of the
81 * @ref vector_valued
82 * topic for examples how to use the features of this namespace.
83 *
84 * @ingroup feaccess vector_valued
85 */
86 namespace FEValuesExtractors
87 {
88 /**
89 * Extractor for a single scalar component of a vector-valued element. The
90 * result of applying an object of this type to an FEValues, FEFaceValues or
91 * FESubfaceValues object is of type FEValuesViews::Scalar. The concept of
92 * extractors is defined in the documentation of the namespace
93 * FEValuesExtractors and in the
94 * @ref vector_valued
95 * topic.
96 *
97 * @ingroup feaccess vector_valued
98 */
99 struct Scalar
100 {
101 /**
102 * The selected scalar component of the vector.
103 */
104 unsigned int component;
105
106 /**
107 * Default constructor. Initialize the object with an invalid component.
108 * This leads to an object that can not be used, but it allows objects of
109 * this kind to be put into arrays that require a default constructor upon
110 * resizing the array, and then later assigning a suitable object to each
111 * element of the array.
112 */
113 constexpr Scalar();
114
115 /**
116 * Constructor. Take the selected vector component as argument.
117 */
118 constexpr Scalar(const unsigned int component);
119
120 /**
121 * Return a string that uniquely identifies this finite element extractor.
122 */
123 std::string
124 get_name() const;
125 };
126
127
128 /**
129 * Extractor for a vector of <code>spacedim</code> components of a
130 * vector-valued element. The value of <code>spacedim</code> is defined by the
131 * FEValues object the extractor is applied to. The result of applying an
132 * object of this type to an FEValues, FEFaceValues or FESubfaceValues
133 * object is of type FEValuesViews::Vector.
134 *
135 * The concept of extractors is defined in the documentation of the
136 * namespace FEValuesExtractors and in the
137 * @ref vector_valued
138 * topic.
139 *
140 * Note that in the current context, a vector is meant in the sense physics
141 * uses it: it has <code>spacedim</code> components that behave in specific
142 * ways under coordinate system transformations. Examples include velocity
143 * or displacement fields. This is opposed to how mathematics uses the word
144 * "vector" (and how we use this word in other contexts in the library, for
145 * example in the Vector class), where it really stands for a collection of
146 * numbers. An example of this latter use of the word could be the set of
147 * concentrations of chemical species in a flame; however, these are really
148 * just a collection of scalar variables, since they do not change if the
149 * coordinate system is rotated, unlike the components of a velocity vector,
150 * and consequently, this class should not be used for this context.
151 *
152 * @ingroup feaccess vector_valued
153 */
154 struct Vector
155 {
156 /**
157 * The first component of the vector view.
158 */
159 unsigned int first_vector_component;
160
161 /**
162 * Default constructor. Initialize the object with an invalid component.
163 * This leads to an object that can not be used, but it allows objects of
164 * this kind to be put into arrays that require a default constructor upon
165 * resizing the array, and then later assigning a suitable object to each
166 * element of the array.
167 */
168 constexpr Vector();
169
170 /**
171 * Constructor. Take the first component of the selected vector inside the
172 * FEValues object as argument.
173 */
174 constexpr Vector(const unsigned int first_vector_component);
175
176 /**
177 * Return a string that uniquely identifies this finite element extractor.
178 */
179 std::string
180 get_name() const;
181 };
182
183
184 /**
185 * Extractor for a symmetric tensor of a rank specified by the template
186 * argument. For a second order symmetric tensor, this represents a
187 * collection of <code>(dim*dim + dim)/2</code> components of a vector-valued
188 * element. The value of <code>dim</code> is defined by the FEValues
189 * object the extractor is applied to. The result of applying an object of
190 * this type to an FEValues, FEFaceValues or FESubfaceValues object is of
191 * type FEValuesViews::SymmetricTensor.
192 *
193 * The concept of extractors is defined in the documentation of the
194 * namespace FEValuesExtractors and in the
195 * @ref vector_valued
196 * topic.
197 *
198 * @ingroup feaccess vector_valued
199 */
200 template <int rank>
201 struct SymmetricTensor
202 {
203 /**
204 * The first component of the tensor view.
205 */
206 unsigned int first_tensor_component;
207
208 /**
209 * Default constructor. Initialize the object with an invalid component.
210 * This leads to an object that can not be used, but it allows objects of
211 * this kind to be put into arrays that require a default constructor upon
212 * resizing the array, and then later assigning a suitable object to each
213 * element of the array.
214 */
215 constexpr SymmetricTensor();
216
217 /**
218 * Constructor. Take the first component of the selected tensor inside the
219 * FEValues object as argument.
220 */
221 constexpr SymmetricTensor(const unsigned int first_tensor_component);
222
223 /**
224 * Return a string that uniquely identifies this finite element extractor.
225 */
226 std::string
227 get_name() const;
228 };
229
230
231 /**
232 * Extractor for a general tensor of a given rank specified by
233 * the template argument. For a second order tensor, this represents a
234 * collection of <code>(dim*dim)</code> components of a vector-valued
235 * element. The value of <code>dim</code> is defined by the FEValues object
236 * the extractor is applied to. The result of applying an object of this
237 * type to an FEValues, FEFaceValues or FESubfaceValues object is of type
238 * FEValuesViews::Tensor.
239 *
240 * The concept of extractors is defined in the documentation of the
241 * namespace FEValuesExtractors and in the
242 * @ref vector_valued
243 * topic.
244 *
245 * @ingroup feaccess vector_valued
246 */
247 template <int rank>
248 struct Tensor
249 {
250 /**
251 * The first component of the tensor view.
252 */
253 unsigned int first_tensor_component;
254
255 /**
256 * Default constructor. Initialize the object with an invalid component.
257 * This leads to an object that can not be used, but it allows objects of
258 * this kind to be put into arrays that require a default constructor upon
259 * resizing the array, and then later assigning a suitable object to each
260 * element of the array.
261 */
262 constexpr Tensor();
263
264 /**
265 * Constructor. Take the first component of the selected tensor inside the
266 * FEValues object as argument.
267 */
268 constexpr Tensor(const unsigned int first_tensor_component);
269
270 /**
271 * Return a string that uniquely identifies this finite element extractor.
272 */
273 std::string
274 get_name() const;
275 };
276
277 /**
278 * Helper struct to associate an extractor to the first FEValuesBase
279 * sub-object of a FECouplingValues object.
280 */
281 template <typename Extractor>
282 struct FirstCoupling
283 {
284 /**
285 * Construct a new FirstCoupling object with the given extractor.
286 */
287 constexpr FirstCoupling(const Extractor &extractor);
288
289 /**
290 * The actual extractor object.
291 */
292 const Extractor extractor;
293 };
294
295 /**
296 * Helper struct to associate an extractor to the second FEValuesBase
297 * sub-object of a FECouplingValues object.
298 */
299 template <typename Extractor>
300 struct SecondCoupling
301 {
302 /**
303 * Construct a new SecondCoupling object with the given extractor.
304 */
305 constexpr SecondCoupling(const Extractor &extractor);
306
307 /**
308 * The actual extractor object.
309 */
310 const Extractor extractor;
311 };
312 } // namespace FEValuesExtractors
313
314
315 /*-------------- Inline functions: namespace FEValuesExtractors -------------*/
316
317 namespace FEValuesExtractors
318 {
319 constexpr inline Scalar::Scalar()
320 : component(numbers::invalid_unsigned_int)
321 {}
322
323
324
325 constexpr inline Scalar::Scalar(const unsigned int component)
326 : component(component)
327 {}
328
329
330
331 constexpr inline Vector::Vector()
332 : first_vector_component(numbers::invalid_unsigned_int)
333 {}
334
335
336 constexpr inline Vector::Vector(const unsigned int first_vector_component)
337 : first_vector_component(first_vector_component)
338 {}
339
340
341 template <int rank>
342 constexpr inline SymmetricTensor<rank>::SymmetricTensor()
343 : first_tensor_component(numbers::invalid_unsigned_int)
344 {}
345
346
347 template <int rank>
348 constexpr inline SymmetricTensor<rank>::SymmetricTensor(
349 const unsigned int first_tensor_component)
350 : first_tensor_component(first_tensor_component)
351 {}
352
353
354 template <int rank>
355 constexpr inline Tensor<rank>::Tensor()
356 : first_tensor_component(numbers::invalid_unsigned_int)
357 {}
358
359
360 template <int rank>
361 constexpr inline Tensor<rank>::Tensor(
362 const unsigned int first_tensor_component)
363 : first_tensor_component(first_tensor_component)
364 {}
365
366
367 template <typename Extractor>
368 constexpr inline FirstCoupling<Extractor>::FirstCoupling(
369 const Extractor &extractor)
370 : extractor(extractor)
371 {}
372
373
374 template <typename Extractor>
375 constexpr inline SecondCoupling<Extractor>::SecondCoupling(
376 const Extractor &extractor)
377 : extractor(extractor)
378 {}
379 } // namespace FEValuesExtractors
380
381
382 DEAL_II_NAMESPACE_CLOSE
383
384 #endif