Debian Codegraph @

include/deal.II/lac/block_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_block_vector_h
16 #define dealii_block_vector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <deal.II/lac/block_indices.h>
24 #include <deal.II/lac/block_vector_base.h>
25 #include <deal.II/lac/vector_operation.h>
26 #include <deal.II/lac/vector_type_traits.h>
27
28 #include <cstdio>
29 #include <vector>
30
31 DEAL_II_NAMESPACE_OPEN
32
33
34 // Forward declaration
35 #ifndef DOXYGEN
36 # ifdef DEAL_II_WITH_TRILINOS
37 namespace TrilinosWrappers
38 {
39 namespace MPI
40 {
41 class BlockVector;
42 }
43 } // namespace TrilinosWrappers
44 # endif
45 #endif
46
47
48 /**
49 * @addtogroup Vectors
50 * @{
51 */
52
53
54 /**
55 * An implementation of block vectors based on deal.II vectors. While the base
56 * class provides for most of the interface, this class handles the actual
57 * allocation of vectors and provides functions that are specific to the
58 * underlying vector type.
59 *
60 * @note Instantiations for this template are provided for <tt>@<float@> and
61 * @<double@></tt>; others can be generated in application programs (see the
62 * section on
63 * @ref Instantiations
64 * in the manual).
65 *
66 * @see
67 * @ref GlossBlockLA "Block (linear algebra)"
68 */
69 template <typename Number>
70 class BlockVector : public BlockVectorBase<Vector<Number>>
71 {
72 public:
73 /**
74 * Typedef the base class for simpler access to its own alias.
75 */
76 using BaseClass = BlockVectorBase<Vector<Number>>;
77
78 /**
79 * Typedef the type of the underlying vector.
80 */
81 using BlockType = typename BaseClass::BlockType;
82
83 /**
84 * Import the alias from the base class.
85 */
86 using value_type = typename BaseClass::value_type;
87 using real_type = typename BaseClass::real_type;
88 using pointer = typename BaseClass::pointer;
89 using const_pointer = typename BaseClass::const_pointer;
90 using reference = typename BaseClass::reference;
91 using const_reference = typename BaseClass::const_reference;
92 using size_type = typename BaseClass::size_type;
93 using iterator = typename BaseClass::iterator;
94 using const_iterator = typename BaseClass::const_iterator;
95
96 /**
97 * Constructor. There are three ways to use this constructor. First, without
98 * any arguments, it generates an object with no blocks. Given one argument,
99 * it initializes <tt>n_blocks</tt> blocks, but these blocks have size zero.
100 * The third variant finally initializes all blocks to the same size
101 * <tt>block_size</tt>.
102 *
103 * Confer the other constructor further down if you intend to use blocks of
104 * different sizes.
105 */
106 explicit BlockVector(const unsigned int n_blocks = 0,
107 const size_type block_size = 0);
108
109 /**
110 * Copy Constructor. Dimension set to that of @p v, all components are
111 * copied from @p v.
112 */
113 BlockVector(const BlockVector<Number> &V);
114
115
116 /**
117 * Move constructor. Creates a new vector by stealing the internal data of
118 * the given argument vector.
119 */
120 BlockVector(BlockVector<Number> && /*v*/) noexcept = default;
121
122 /**
123 * Copy constructor taking a BlockVector of another data type. This will
124 * fail if there is no conversion path from <tt>OtherNumber</tt> to
125 * <tt>Number</tt>. Note that you may lose accuracy when copying to a
126 * BlockVector with data elements with less accuracy.
127 */
128 template <typename OtherNumber>
129 explicit BlockVector(const BlockVector<OtherNumber> &v);
130
131 #ifdef DEAL_II_WITH_TRILINOS
132 /**
133 * A copy constructor taking a (parallel) Trilinos block vector and copying
134 * it into the deal.II own format.
135 */
136 BlockVector(const TrilinosWrappers::MPI::BlockVector &v);
137
138 #endif
139 /**
140 * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt> and
141 * initialize each block with <tt>block_sizes[i]</tt> zero elements.
142 */
143 BlockVector(const std::vector<size_type> &block_sizes);
144
145 /**
146 * Constructor. Initialize vector to the structure found in the BlockIndices
147 * argument.
148 */
149 BlockVector(const BlockIndices &block_indices);
150
151 /**
152 * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt>.
153 * Initialize the vector with the elements pointed to by the range of
154 * iterators given as second and third argument. Apart from the first
155 * argument, this constructor is in complete analogy to the respective
156 * constructor of the <tt>std::vector</tt> class, but the first argument is
157 * needed in order to know how to subdivide the block vector into different
158 * blocks.
159 */
160 template <typename InputIterator>
161 BlockVector(const std::vector<size_type> &block_sizes,
162 const InputIterator first,
163 const InputIterator end);
164
165 /**
166 * Destructor. Clears memory
167 */
168 ~BlockVector() override = default;
169
170 /**
171 * Call the compress() function on all the subblocks.
172 *
173 * This functionality only needs to be called if using MPI based vectors and
174 * exists in other objects for compatibility.
175 *
176 * See
177 * @ref GlossCompress "Compressing distributed objects"
178 * for more information.
179 */
180 void
181 compress(VectorOperation::values operation = VectorOperation::unknown);
182
183 /**
184 * Returns `false` as this is a serial block vector.
185 *
186 * This functionality only needs to be called if using MPI based vectors and
187 * exists in other objects for compatibility.
188 */
189 bool
190 has_ghost_elements() const;
191
192 /**
193 * Copy operator: fill all components of the vector with the given scalar
194 * value.
195 */
196 BlockVector &
197 operator=(const value_type s);
198
199 /**
200 * Copy operator for arguments of the same type. Resize the present vector
201 * if necessary to the correct number of blocks, then copy the individual
202 * blocks from `v` using the copy-assignment operator of the class that
203 * represents the individual blocks.
204 */
205 BlockVector<Number> &
206 operator=(const BlockVector<Number> &v);
207
208 /**
209 * Move the given vector. This operator replaces the present vector with
210 * the contents of the given argument vector.
211 */
212 BlockVector<Number> &
213 operator=(BlockVector<Number> && /*v*/) = default; // NOLINT
214
215 /**
216 * Copy operator for template arguments of different types. Resize the
217 * present vector if necessary.
218 */
219 template <class Number2>
220 BlockVector<Number> &
221 operator=(const BlockVector<Number2> &V);
222
223 /**
224 * Copy a regular vector into a block vector.
225 */
226 BlockVector<Number> &
227 operator=(const Vector<Number> &V);
228
229 #ifdef DEAL_II_WITH_TRILINOS
230 /**
231 * A copy constructor from a Trilinos block vector to a deal.II block
232 * vector.
233 */
234 BlockVector<Number> &
235 operator=(const TrilinosWrappers::MPI::BlockVector &V);
236 #endif
237
238 /**
239 * Reinitialize the BlockVector to contain <tt>n_blocks</tt> blocks of size
240 * <tt>block_size</tt> each.
241 *
242 * If the second argument is left at its default value, then the block
243 * vector allocates the specified number of blocks but leaves them at zero
244 * size. You then need to later reinitialize the individual blocks, and call
245 * collect_sizes() to update the block system's knowledge of its individual
246 * block's sizes.
247 *
248 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
249 */
250 void
251 reinit(const unsigned int n_blocks,
252 const size_type block_size = 0,
253 const bool omit_zeroing_entries = false);
254
255 /**
256 * Reinitialize the BlockVector such that it contains
257 * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
258 * dimension <tt>block_sizes[i]</tt>.
259 *
260 * If the number of blocks is the same as before this function was called,
261 * all vectors remain the same and reinit() is called for each vector.
262 *
263 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
264 *
265 * Note that you must call this (or the other reinit() functions) function,
266 * rather than calling the reinit() functions of an individual block, to
267 * allow the block vector to update its caches of vector sizes. If you call
268 * reinit() on one of the blocks, then subsequent actions on this object may
269 * yield unpredictable results since they may be routed to the wrong block.
270 */
271 void
272 reinit(const std::vector<size_type> &block_sizes,
273 const bool omit_zeroing_entries = false);
274
275 /**
276 * Reinitialize the BlockVector to reflect the structure found in
277 * BlockIndices.
278 *
279 * If the number of blocks is the same as before this function was called,
280 * all vectors remain the same and reinit() is called for each vector.
281 *
282 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with zeros.
283 */
284 void
285 reinit(const BlockIndices &block_indices,
286 const bool omit_zeroing_entries = false);
287
288 /**
289 * Change the dimension to that of the vector <tt>V</tt>. The same applies
290 * as for the other reinit() function.
291 *
292 * The elements of <tt>V</tt> are not copied, i.e. this function is the
293 * same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>.
294 *
295 * Note that you must call this (or the other reinit() functions) function,
296 * rather than calling the reinit() functions of an individual block, to
297 * allow the block vector to update its caches of vector sizes. If you call
298 * reinit() of one of the blocks, then subsequent actions of this object may
299 * yield unpredictable results since they may be routed to the wrong block.
300 */
301 template <typename Number2>
302 void
303 reinit(const BlockVector<Number2> &V,
304 const bool omit_zeroing_entries = false);
305
306 /**
307 * Multiply each element of this vector by the corresponding element of
308 * <tt>v</tt>.
309 */
310 template <class BlockVector2>
311 void
312 scale(const BlockVector2 &v);
313
314 /**
315 * Swap the contents of this vector and the other vector <tt>v</tt>. One
316 * could do this operation with a temporary variable and copying over the
317 * data elements, but this function is significantly more efficient since it
318 * only swaps the pointers to the data of the two vectors and therefore does
319 * not need to allocate temporary storage and move data around.
320 *
321 * This function is analogous to the swap() function of all C++ standard
322 * containers. Also, there is a global function swap(u,v) that simply calls
323 * <tt>u.swap(v)</tt>, again in analogy to standard functions.
324 */
325 void
326 swap(BlockVector<Number> &v) noexcept;
327
328 /**
329 * Print to a stream.
330 */
331 void
332 print(std::ostream &out,
333 const unsigned int precision = 3,
334 const bool scientific = true,
335 const bool across = true) const;
336
337 /**
338 * Write the vector en bloc to a stream. This is done in a binary mode, so
339 * the output is neither readable by humans nor (probably) by other
340 * computers using a different operating system or number format.
341 */
342 void
343 block_write(std::ostream &out) const;
344
345 /**
346 * Read a vector en block from a file. This is done using the inverse
347 * operations to the above function, so it is reasonably fast because the
348 * bitstream is not interpreted.
349 *
350 * The vector is resized if necessary.
351 *
352 * A primitive form of error checking is performed which will recognize the
353 * bluntest attempts to interpret some data as a vector stored bitwise to a
354 * file, but not more.
355 */
356 void
357 block_read(std::istream &in);
358
359 /**
360 * @addtogroup Exceptions
361 * @{
362 */
363
364 /**
365 * Exception
366 */
367 DeclException0(ExcIteratorRangeDoesNotMatchVectorSize);
368 /** @} */
369 };
370
371 /** @} */
372
373 #ifndef DOXYGEN
374 /*----------------------- Inline functions ----------------------------------*/
375
376
377
378 template <typename Number>
379 template <typename InputIterator>
380 BlockVector<Number>::BlockVector(const std::vector<size_type> &block_sizes,
381 const InputIterator first,
382 const InputIterator end)
383 {
384 // first set sizes of blocks, but
385 // don't initialize them as we will
386 // copy elements soon
387 reinit(block_sizes, true);
388 InputIterator start = first;
389 for (size_type b = 0; b < block_sizes.size(); ++b)
390 {
391 InputIterator end = start;
392 std::advance(end, static_cast<signed int>(block_sizes[b]));
393 std::copy(start, end, this->block(b).begin());
394 start = end;
395 };
396 Assert(start == end, ExcIteratorRangeDoesNotMatchVectorSize());
397 }
398
399
400
401 template <typename Number>
402 inline BlockVector<Number> &
403 BlockVector<Number>::operator=(const value_type s)
404 {
405 AssertIsFinite(s);
406
407 BaseClass::operator=(s);
408 return *this;
409 }
410
411
412
413 template <typename Number>
414 inline BlockVector<Number> &
415 BlockVector<Number>::operator=(const BlockVector<Number> &v)
416 {
417 reinit(v, true);
418 BaseClass::operator=(v);
419 return *this;
420 }
421
422
423
424 template <typename Number>
425 inline BlockVector<Number> &
426 BlockVector<Number>::operator=(const Vector<Number> &v)
427 {
428 BaseClass::operator=(v);
429 return *this;
430 }
431
432
433
434 template <typename Number>
435 template <typename Number2>
436 inline BlockVector<Number> &
437 BlockVector<Number>::operator=(const BlockVector<Number2> &v)
438 {
439 reinit(v, true);
440 BaseClass::operator=(v);
441 return *this;
442 }
443
444 template <typename Number>
445 inline void
446 BlockVector<Number>::compress(VectorOperation::values operation)
447 {
448 for (size_type i = 0; i < this->n_blocks(); ++i)
449 this->components[i].compress(operation);
450 }
451
452
453
454 template <typename Number>
455 inline bool
456 BlockVector<Number>::has_ghost_elements() const
457 {
458 return false;
459 }
460
461
462
463 template <typename Number>
464 template <class BlockVector2>
465 void
466 BlockVector<Number>::scale(const BlockVector2 &v)
467 {
468 BaseClass::scale(v);
469 }
470
471 #endif // DOXYGEN
472
473
474 /**
475 * Global function which overloads the default implementation of the C++
476 * standard library which uses a temporary object. The function simply
477 * exchanges the data of the two vectors.
478 *
479 * @relatesalso BlockVector
480 */
481 template <typename Number>
482 inline void
483 swap(BlockVector<Number> &u, BlockVector<Number> &v) noexcept
484 {
485 u.swap(v);
486 }
487
488
489 namespace internal
490 {
491 namespace LinearOperatorImplementation
492 {
493 template <typename>
494 class ReinitHelper;
495
496 /**
497 * A helper class used internally in linear_operator.h. Specialization for
498 * BlockVector<number>.
499 */
500 template <typename number>
501 class ReinitHelper<BlockVector<number>>
502 {
503 public:
504 template <typename Matrix>
505 static void
506 reinit_range_vector(const Matrix &matrix,
507 BlockVector<number> &v,
508 bool omit_zeroing_entries)
509 {
510 v.reinit(matrix.get_row_indices(), omit_zeroing_entries);
511 }
512
513 template <typename Matrix>
514 static void
515 reinit_domain_vector(const Matrix &matrix,
516 BlockVector<number> &v,
517 bool omit_zeroing_entries)
518 {
519 v.reinit(matrix.get_column_indices(), omit_zeroing_entries);
520 }
521 };
522
523 } // namespace LinearOperatorImplementation
524 } /* namespace internal */
525
526
527 /**
528 * Declare dealii::BlockVector as serial vector.
529 */
530 template <typename Number>
531 struct is_serial_vector<BlockVector<Number>> : std::true_type
532 {};
533
534 DEAL_II_NAMESPACE_CLOSE
535
536 #endif