Debian Codegraph @

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