Debian Codegraph @

include/deal.II/fe/component_mask.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_component_mask_h
16 #define dealii_fe_component_mask_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/memory_consumption.h>
22 #include <deal.II/base/types.h>
23
24 #include <algorithm>
25 #include <iosfwd>
26 #include <vector>
27
28 DEAL_II_NAMESPACE_OPEN
29
30
31
32 /**
33 * This class represents a mask that can be used to select individual vector
34 * components of a finite element (see also
35 * @ref GlossComponentMask "this glossary entry").
36 * It will typically have as many elements as the finite element has vector
37 * components, and one can use <code>operator[]</code> to query whether a
38 * particular component has been selected.
39 *
40 * @note A "mask" represents a data structure with @p true and @p false
41 * entries that is generally used to enable or disable an operation
42 * for a particular vector component. By this definition, disabled
43 * vector components still exist -- they are simply not touched. As
44 * a consequence, when you apply a component mask for interpolating
45 * boundary values (to choose just one example) of a problem with
46 * $C$ vector components, the input argument that describes the
47 * boundary values will still have to provide $C$ components even
48 * if the mask says that we only want to interpolate a subset of
49 * these components onto the finite element space. In other words,
50 * a component mask does not represent a <i>reduction</i> operation;
51 * it represents a <i>selection</i>.
52 *
53 * Objects of this kind are used in many places where one wants to restrict
54 * operations to a certain subset of components, e.g. in
55 * DoFTools::make_zero_boundary_values() or
56 * VectorTools::interpolate_boundary_values(). These objects can either be
57 * created by hand, or, simpler, by asking the finite element to generate a
58 * component mask from certain selected components using code such as this
59 * where we create a mask that only denotes the velocity components of a
60 * Stokes element (see
61 * @ref vector_valued):
62 * @code
63 * // Q2 element for the velocities, Q1 element for the pressure
64 * FESystem<dim> stokes_fe (FE_Q<dim>(2), dim,
65 * FE_Q<dim>(1), 1);
66 * FEValuesExtractors::Scalar pressure(dim);
67 * ComponentMask pressure_mask = stokes_fe.component_mask (pressure);
68 * @endcode
69 * The result is a component mask that, in 2d, would have values <code>[false,
70 * false, true]</code>. Similarly, using
71 * @code
72 * FEValuesExtractors::Vector velocities(0);
73 * ComponentMask velocity_mask = stokes_fe.component_mask (velocities);
74 * @endcode
75 * would result in a mask <code>[true, true, false]</code> in 2d. Of course,
76 * in 3d, the result would be <code>[true, true, true, false]</code>.
77 *
78 * @ingroup fe
79 * @ingroup vector_valued
80 */
81 class ComponentMask
82 {
83 public:
84 /**
85 * Initialize a component mask. The default is that a component mask
86 * represents a set of components that are <i>all</i> selected, i.e.,
87 * calling this constructor results in a component mask that always returns
88 * <code>true</code> whenever asked whether a component is selected.
89 */
90 ComponentMask() = default;
91
92 /**
93 * Deprecated constructor allowing implicit conversion.
94 */
95 template <typename = void>
96 DEAL_II_DEPRECATED_WITH_COMMENT(
97 "Implicit conversions from std::vector<bool> to ComponentMask are deprecated!")
98 ComponentMask(const std::vector<bool> &block_mask);
99
100 /**
101 * Initialize an object of this type with a set of selected components
102 * specified by the argument.
103 *
104 * @param component_mask A vector of <code>true/false</code> entries that
105 * determine which components of a finite element are selected. If the
106 * length of the given vector is zero, then this interpreted as the case
107 * where <i>every</i> component is selected.
108 */
109 explicit ComponentMask(const std::vector<bool> &component_mask);
110
111 /**
112 * Initialize the component mask with a number of elements that are either
113 * all true or false.
114 *
115 * @param n_components The number of elements of this mask
116 * @param initializer The value each of these elements is supposed to have:
117 * either true or false.
118 */
119 ComponentMask(const unsigned int n_components, const bool initializer);
120
121 /**
122 * Set a particular entry in the mask to a value.
123 */
124 void
125 set(const unsigned int index, const bool value);
126
127 /**
128 * If this component mask has been initialized with a mask of size greater
129 * than zero, then return the size of the mask represented by this object.
130 * On the other hand, if this mask has been initialized as an empty object
131 * that represents a mask that is true for every element (i.e., if this
132 * object would return true when calling represents_the_all_selected_mask())
133 * then return zero since no definite size is known.
134 */
135 unsigned int
136 size() const;
137
138 /**
139 * Return whether a particular component is selected by this mask. If this
140 * mask represents the case of an object that selects <i>all components</i>
141 * (e.g. if it is created using the default constructor or is converted from
142 * an empty vector of type bool) then this function returns true regardless
143 * of the given argument.
144 *
145 * @param component_index The index for which the function should return
146 * whether the component is selected. If this object represents a mask in
147 * which all components are always selected then any index is allowed here.
148 * Otherwise, the given index needs to be between zero and the number of
149 * components that this mask represents.
150 */
151 bool
152 operator[](const unsigned int component_index) const;
153
154 /**
155 * Return whether this component mask represents a mask with exactly
156 * <code>n</code> components. This is true if either it was initialized with
157 * a vector with exactly <code>n</code> entries of type <code>bool</code>
158 * (in this case, @p n must equal the result of size()) or if it was
159 * initialized with an empty vector (or using the default constructor) in
160 * which case it can represent a mask with an arbitrary number of components
161 * and will always say that a component is selected.
162 */
163 bool
164 represents_n_components(const unsigned int n) const;
165
166 /**
167 * Return the number of components that are selected by this mask.
168 *
169 * Since empty component masks represent a component mask that would return
170 * <code>true</code> for every component, this function may not know the
171 * true size of the component mask and it therefore requires an argument
172 * that denotes the overall number of components.
173 *
174 * If the object has been initialized with a non-empty mask (i.e., if the
175 * size() function returns something greater than zero, or equivalently if
176 * represents_the_all_selected_mask() returns false) then the argument can
177 * be omitted and the result of size() is taken.
178 */
179 unsigned int
180 n_selected_components(const unsigned int overall_number_of_components =
181 numbers::invalid_unsigned_int) const;
182
183 /**
184 * Return the index of the first selected component. The argument is there
185 * for the same reason it exists with the n_selected_components() function.
186 *
187 * The function throws an exception if no component is selected at all.
188 */
189 unsigned int
190 first_selected_component(const unsigned int overall_number_of_components =
191 numbers::invalid_unsigned_int) const;
192
193 /**
194 * Return true if this mask represents a default constructed mask that
195 * corresponds to one in which all components are selected. If true, then
196 * the size() function will return zero.
197 */
198 bool
199 represents_the_all_selected_mask() const;
200
201 /**
202 * Return a component mask that contains the union of the components
203 * selected by the current object and the one passed as an argument.
204 */
205 ComponentMask
206 operator|(const ComponentMask &mask) const;
207
208 /**
209 * Return a component mask that has only those elements set that are set
210 * both in the current object as well as the one passed as an argument.
211 */
212 ComponentMask
213 operator&(const ComponentMask &mask) const;
214
215 /**
216 * Return whether this object and the argument are identical.
217 */
218 bool
219 operator==(const ComponentMask &mask) const;
220
221 /**
222 * Return whether this object and the argument are not identical.
223 */
224 bool
225 operator!=(const ComponentMask &mask) const;
226
227 /**
228 * Determine an estimate for the memory consumption (in bytes) of this
229 * object.
230 */
231 std::size_t
232 memory_consumption() const;
233
234 /**
235 * Exception
236 */
237 DeclExceptionMsg(ExcNoComponentSelected,
238 "The number of selected components in a mask "
239 "must be greater than zero.");
240
241 private:
242 /**
243 * The actual component mask.
244 */
245 std::vector<bool> component_mask;
246
247 // make the output operator a friend so it can access
248 // the component_mask array
249 friend std::ostream &
250 operator<<(std::ostream &out, const ComponentMask &mask);
251 };
252
253
254 /**
255 * Write a component mask to an output stream. If the component mask
256 * represents one where all components are selected without specifying a
257 * particular size of the mask, then it writes the string <code>[all
258 * components selected]</code> to the stream. Otherwise, it prints the
259 * component mask in a form like <code>[true,true,true,false]</code>.
260 *
261 * @param out The stream to write to.
262 * @param mask The mask to write. @return A reference to the first argument.
263 */
264 std::ostream &
265 operator<<(std::ostream &out, const ComponentMask &mask);
266
267 #ifndef DOXYGEN
268 // -------------------- inline functions ---------------------
269
270 template <typename>
271 inline ComponentMask::ComponentMask(const std::vector<bool> &component_mask)
272 : component_mask(component_mask)
273 {}
274
275
276 inline ComponentMask::ComponentMask(const std::vector<bool> &component_mask)
277 : component_mask(component_mask)
278 {}
279
280
281 inline ComponentMask::ComponentMask(const unsigned int n_components,
282 const bool initializer)
283 : component_mask(n_components, initializer)
284 {}
285
286
287 inline unsigned int
288 ComponentMask::size() const
289 {
290 return component_mask.size();
291 }
292
293
294 inline void
295 ComponentMask::set(const unsigned int index, const bool value)
296 {
297 AssertIndexRange(index, component_mask.size());
298 component_mask[index] = value;
299 }
300
301
302 inline bool
303 ComponentMask::operator[](const unsigned int component_index) const
304 {
305 // if the mask represents the all-component mask
306 // then always return true
307 if (component_mask.empty())
308 return true;
309 else
310 {
311 // otherwise check the validity of the index and
312 // return whatever is appropriate
313 AssertIndexRange(component_index, component_mask.size());
314 return component_mask[component_index];
315 }
316 }
317
318
319 inline bool
320 ComponentMask::represents_n_components(const unsigned int n) const
321 {
322 return ((component_mask.empty()) || (component_mask.size() == n));
323 }
324
325
326 inline unsigned int
327 ComponentMask::n_selected_components(const unsigned int n) const
328 {
329 if ((n != numbers::invalid_unsigned_int) && (size() > 0))
330 AssertDimension(n, size());
331
332 const unsigned int real_n = (n != numbers::invalid_unsigned_int ? n : size());
333 if (component_mask.empty())
334 return real_n;
335 else
336 {
337 AssertDimension(real_n, component_mask.size());
338 return std::count_if(component_mask.begin(),
339 component_mask.end(),
340 [](const bool selected) { return selected; });
341 }
342 }
343
344
345 inline unsigned int
346 ComponentMask::first_selected_component(const unsigned int n) const
347 {
348 if ((n != numbers::invalid_unsigned_int) && (size() > 0))
349 AssertDimension(n, size());
350
351 if (component_mask.empty())
352 return 0;
353 else
354 {
355 for (unsigned int c = 0; c < component_mask.size(); ++c)
356 if (component_mask[c] == true)
357 return c;
358
359 Assert(false, ExcMessage("No component is selected at all!"));
360 return numbers::invalid_unsigned_int;
361 }
362 }
363
364
365
366 inline bool
367 ComponentMask::represents_the_all_selected_mask() const
368 {
369 return (component_mask.empty());
370 }
371
372
373
374 inline ComponentMask
375 ComponentMask::operator|(const ComponentMask &mask) const
376 {
377 // if one of the two masks denotes the all-component mask,
378 // then return the other one
379 if (component_mask.empty())
380 return mask;
381 else if (mask.component_mask.empty())
382 return *this;
383 else
384 {
385 // if both masks have individual entries set, form
386 // the combination of the two
387 AssertDimension(component_mask.size(), mask.component_mask.size());
388 std::vector<bool> new_mask(component_mask.size());
389 for (unsigned int i = 0; i < component_mask.size(); ++i)
390 new_mask[i] = (component_mask[i] || mask.component_mask[i]);
391
392 return ComponentMask(new_mask);
393 }
394 }
395
396
397 inline ComponentMask
398 ComponentMask::operator&(const ComponentMask &mask) const
399 {
400 // if one of the two masks denotes the all-component mask,
401 // then return the other one
402 if (component_mask.empty())
403 return mask;
404 else if (mask.component_mask.empty())
405 return *this;
406 else
407 {
408 // if both masks have individual entries set, form
409 // the combination of the two
410 AssertDimension(component_mask.size(), mask.component_mask.size());
411 std::vector<bool> new_mask(component_mask.size());
412 for (unsigned int i = 0; i < component_mask.size(); ++i)
413 new_mask[i] = (component_mask[i] && mask.component_mask[i]);
414
415 return ComponentMask(new_mask);
416 }
417 }
418
419
420 inline bool
421 ComponentMask::operator==(const ComponentMask &mask) const
422 {
423 return component_mask == mask.component_mask;
424 }
425
426
427 inline bool
428 ComponentMask::operator!=(const ComponentMask &mask) const
429 {
430 return component_mask != mask.component_mask;
431 }
432 #endif // DOXYGEN
433
434
435 DEAL_II_NAMESPACE_CLOSE
436
437 #endif