Debian Codegraph @

include/deal.II/lac/petsc_block_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 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_petsc_block_vector_h
16 #define dealii_petsc_block_vector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_PETSC
22
23 # include <deal.II/lac/block_indices.h>
24 # include <deal.II/lac/block_vector_base.h>
25 # include <deal.II/lac/exceptions.h>
26 # include <deal.II/lac/petsc_vector.h>
27 # include <deal.II/lac/vector_type_traits.h>
28
29 # include <cstddef>
30
31 DEAL_II_NAMESPACE_OPEN
32
33
34 namespace PETScWrappers
35 {
36 // forward declaration
37 class BlockVector;
38
39 namespace MPI
40 {
41 /**
42 * @addtogroup PETScWrappers
43 * @{
44 */
45
46 /**
47 * An implementation of block vectors based on the parallel vector class
48 * implemented in PETScWrappers. While the base class provides for most of
49 * the interface, this class handles the actual allocation of vectors and
50 * provides functions that are specific to the underlying vector type.
51 *
52 * The model of distribution of data is such that each of the blocks is
53 * distributed across all MPI processes named in the MPI communicator.
54 * I.e. we don't just distribute the whole vector, but each component. In
55 * the constructors and reinit() functions, one therefore not only has to
56 * specify the sizes of the individual blocks, but also the number of
57 * elements of each of these blocks to be stored on the local process.
58 *
59 * @ingroup Vectors
60 * @see @ref GlossBlockLA "Block (linear algebra)"
61 */
62 class BlockVector : public BlockVectorBase<Vector>
63 {
64 public:
65 /**
66 * Typedef the base class for simpler access to its own alias.
67 */
68 using BaseClass = BlockVectorBase<Vector>;
69
70 /**
71 * Typedef the type of the underlying vector.
72 */
73 using BlockType = BaseClass::BlockType;
74
75 /**
76 * Import the alias from the base class.
77 */
78 using value_type = BaseClass::value_type;
79 using pointer = BaseClass::pointer;
80 using const_pointer = BaseClass::const_pointer;
81 using reference = BaseClass::reference;
82 using const_reference = BaseClass::const_reference;
83 using size_type = BaseClass::size_type;
84 using iterator = BaseClass::iterator;
85 using const_iterator = BaseClass::const_iterator;
86
87 /**
88 * Default constructor. Generate an empty vector without any blocks.
89 */
90 BlockVector();
91
92 /**
93 * Constructor. Generate a block vector with @p n_blocks blocks, each of
94 * which is a parallel vector across @p communicator with @p block_size
95 * elements of which @p locally_owned_size elements are stored on the
96 * present process.
97 */
98 explicit BlockVector(const unsigned int n_blocks,
99 const MPI_Comm communicator,
100 const size_type block_size,
101 const size_type locally_owned_size);
102
103 /**
104 * Copy constructor. Set all the properties of the parallel vector to
105 * those of the given argument and copy the elements.
106 */
107 BlockVector(const BlockVector &V);
108
109 /**
110 * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt>
111 * and initialize each block with <tt>block_sizes[i]</tt> zero elements.
112 * The individual blocks are distributed across the given communicator,
113 * and each store <tt>local_elements[i]</tt> elements on the present
114 * process.
115 */
116 BlockVector(const std::vector<size_type> &block_sizes,
117 const MPI_Comm communicator,
118 const std::vector<size_type> &local_elements);
119
120 /**
121 * Create a BlockVector with parallel_partitioning.size() blocks, each
122 * initialized with the given IndexSet.
123 */
124 explicit BlockVector(const std::vector<IndexSet> &parallel_partitioning,
125 const MPI_Comm communicator = MPI_COMM_WORLD);
126
127 /**
128 * Same as above, but include ghost elements
129 */
130 BlockVector(const std::vector<IndexSet> &parallel_partitioning,
131 const std::vector<IndexSet> &ghost_indices,
132 const MPI_Comm communicator);
133
134 /**
135 * Create a BlockVector with a PETSc Vec
136 * It infers the number of blocks from the Vec if it is of type VECNEST,
137 * otherwise the block vector will only have a single block.
138 * Internally, we always store a VECNEST vector.
139 */
140 explicit BlockVector(Vec v);
141
142 /**
143 * Create a BlockVector with an array of PETSc vectors.
144 */
145 template <std::size_t num_blocks>
146 explicit BlockVector(const std::array<Vec, num_blocks> &);
147
148 /**
149 * Destructor. Clears memory
150 */
151 ~BlockVector() override;
152
153 /**
154 * Copy operator: fill all components of the vector that are locally
155 * stored with the given scalar value.
156 */
157 BlockVector &
158 operator=(const value_type s);
159
160 /**
161 * Copy operator for arguments of the same type. Resize the present vector
162 * if necessary to the correct number of blocks, then copy the individual
163 * blocks from `v` using the copy-assignment operator of the class that
164 * represents the individual blocks.
165 *
166 * Copying the vectors that make up individual blocks can have complex
167 * semantics in parallel vector classes. See the information provided
168 * by the class used to represent the individual blocks.
169 */
170 BlockVector &
171 operator=(const BlockVector &V);
172
173 /**
174 * This method associates the PETSc Vec to the instance of the class.
175 * Infers the number of blocks from v if it is of type VECNEST, otherwise
176 * the block vector will only have a single block.
177 */
178 void
179 reinit(Vec v);
180
181 /**
182 * Reinitialize the BlockVector to contain @p n_blocks of size @p
183 * block_size, each of which stores @p locally_owned_size elements
184 * locally. The @p communicator argument denotes which MPI channel each
185 * of these blocks shall communicate.
186 *
187 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
188 * zeros.
189 */
190 void
191 reinit(const unsigned int n_blocks,
192 const MPI_Comm communicator,
193 const size_type block_size,
194 const size_type locally_owned_size,
195 const bool omit_zeroing_entries = false);
196
197 /**
198 * Reinitialize the BlockVector such that it contains
199 * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
200 * dimension <tt>block_sizes[i]</tt>. Each of them stores
201 * <tt>locally_owned_sizes[i]</tt> elements on the present process.
202 *
203 * If the number of blocks is the same as before this function was
204 * called, all vectors remain the same and reinit() is called for each
205 * vector.
206 *
207 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
208 * zeros.
209 *
210 * Note that you must call this (or the other reinit() functions)
211 * function, rather than calling the reinit() functions of an individual
212 * block, to allow the block vector to update its caches of vector
213 * sizes. If you call reinit() of one of the blocks, then subsequent
214 * actions on this object may yield unpredictable results since they may
215 * be routed to the wrong block.
216 */
217 void
218 reinit(const std::vector<size_type> &block_sizes,
219 const MPI_Comm communicator,
220 const std::vector<size_type> &locally_owned_sizes,
221 const bool omit_zeroing_entries = false);
222
223 /**
224 * Change the dimension to that of the vector <tt>V</tt>. The same
225 * applies as for the other reinit() function.
226 *
227 * The elements of <tt>V</tt> are not copied, i.e. this function is the
228 * same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>.
229 *
230 * Note that you must call this (or the other reinit() functions)
231 * function, rather than calling the reinit() functions of an individual
232 * block, to allow the block vector to update its caches of vector
233 * sizes. If you call reinit() on one of the blocks, then subsequent
234 * actions on this object may yield unpredictable results since they may
235 * be routed to the wrong block.
236 */
237 void
238 reinit(const BlockVector &V, const bool omit_zeroing_entries = false);
239
240 /**
241 * Reinitialize the BlockVector using IndexSets. See the constructor
242 * with the same arguments for details.
243 */
244 void
245 reinit(const std::vector<IndexSet> &parallel_partitioning,
246 const MPI_Comm communicator);
247
248 /**
249 * Same as above but include ghost entries.
250 */
251 void
252 reinit(const std::vector<IndexSet> &parallel_partitioning,
253 const std::vector<IndexSet> &ghost_entries,
254 const MPI_Comm communicator);
255
256 /**
257 * Initialize each block given to each parallel partitioning described in
258 * @p partitioners.
259 *
260 * You can decide whether your vector will contain ghost elements with
261 * @p make_ghosted.
262 */
263 void
264 reinit(
265 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
266 &partitioners,
267 const bool make_ghosted = true);
268
269 /**
270 * This function collects the sizes of the sub-objects and stores them
271 * in internal arrays, in order to be able to relay global indices into
272 * the vector to indices into the subobjects. You *must* call this
273 * function each time after you have changed the size of the sub-objects.
274 */
275 void
276 collect_sizes();
277
278 /**
279 * Call the compress() function on all the subblocks of the vector
280 * and update the internal state of the nested PETSc vector.
281 *
282 * See
283 * @ref GlossCompress "Compressing distributed objects"
284 * for more information.
285 */
286 void
287 compress(VectorOperation::values operation);
288
289 /**
290 * Change the number of blocks to <tt>num_blocks</tt>. The individual
291 * blocks will get initialized with zero size, so it is assumed that the
292 * user resizes the individual blocks by herself in an appropriate way,
293 * and calls <tt>collect_sizes</tt> afterwards.
294 */
295 void
296 reinit(const unsigned int num_blocks);
297
298 /**
299 * Return if this vector is a ghosted vector (and thus read-only).
300 */
301 bool
302 has_ghost_elements() const;
303
304 /**
305 * Return the underlying MPI communicator.
306 */
307 MPI_Comm
308 get_mpi_communicator() const;
309
310 /**
311 * Conversion operator to gain access to the underlying PETSc type. If you
312 * do this, you cut this class off some information it may need, so this
313 * conversion operator should only be used if you know what you do. In
314 * particular, it should only be used for read-only operations into the
315 * vector.
316 */
317 operator const Vec &() const;
318
319 /**
320 * Return a reference to the underlying PETSc type. It can be used to
321 * modify the underlying data, so use it only when you know what you
322 * are doing.
323 */
324 Vec &
325 petsc_vector();
326
327 /**
328 * Swap the contents of this vector and the other vector <tt>v</tt>. One
329 * could do this operation with a temporary variable and copying over
330 * the data elements, but this function is significantly more efficient
331 * since it only swaps the pointers to the data of the two vectors and
332 * therefore does not need to allocate temporary storage and move data
333 * around.
334 *
335 * Limitation: right now this function only works if both vectors have
336 * the same number of blocks. If needed, the numbers of blocks should be
337 * exchanged, too.
338 *
339 * This function is analogous to the swap() function of all C++
340 * standard containers. Also, there is a global function swap(u,v) that
341 * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
342 * functions.
343 */
344 void
345 swap(BlockVector &v) noexcept;
346
347 /**
348 * Print to a stream.
349 */
350 void
351 print(std::ostream &out,
352 const unsigned int precision = 3,
353 const bool scientific = true,
354 const bool across = true) const;
355
356 /**
357 * Exception
358 */
359 DeclException0(ExcIteratorRangeDoesNotMatchVectorSize);
360 /**
361 * Exception
362 */
363 DeclException0(ExcNonMatchingBlockVectors);
364
365 private:
366 /**
367 * A PETSc Vec object that describes the entire block vector.
368 * Internally, this is done by creating
369 * a "nested" vector using PETSc's VECNEST object whose individual
370 * blocks are the blocks of this vector.
371 */
372 Vec petsc_nest_vector;
373
374 /**
375 * Utility to set up the VECNEST object
376 */
377 void
378 setup_nest_vec();
379 };
380
381 /** @} */
382
383 /*--------------------- Inline functions --------------------------------*/
384
385 inline BlockVector::BlockVector()
386 : BlockVectorBase<Vector>()
387 , petsc_nest_vector(nullptr)
388 {}
389
390
391
392 inline BlockVector::BlockVector(const unsigned int n_blocks,
393 const MPI_Comm communicator,
394 const size_type block_size,
395 const size_type locally_owned_size)
396 : BlockVector()
397 {
398 reinit(n_blocks, communicator, block_size, locally_owned_size);
399 }
400
401
402
403 inline BlockVector::BlockVector(
404 const std::vector<size_type> &block_sizes,
405 const MPI_Comm communicator,
406 const std::vector<size_type> &local_elements)
407 : BlockVector()
408 {
409 reinit(block_sizes, communicator, local_elements, false);
410 }
411
412
413
414 inline BlockVector::BlockVector(const BlockVector &v)
415 : BlockVector()
416 {
417 this->block_indices = v.block_indices;
418
419 this->components.resize(this->n_blocks());
420 for (unsigned int i = 0; i < this->n_blocks(); ++i)
421 this->components[i] = v.components[i];
422
423 this->collect_sizes();
424 }
425
426
427
428 inline BlockVector::BlockVector(
429 const std::vector<IndexSet> &parallel_partitioning,
430 const MPI_Comm communicator)
431 : BlockVector()
432 {
433 reinit(parallel_partitioning, communicator);
434 }
435
436
437
438 inline BlockVector::BlockVector(
439 const std::vector<IndexSet> &parallel_partitioning,
440 const std::vector<IndexSet> &ghost_indices,
441 const MPI_Comm communicator)
442 : BlockVector()
443 {
444 reinit(parallel_partitioning, ghost_indices, communicator);
445 }
446
447
448
449 inline BlockVector::BlockVector(Vec v)
450 : BlockVector()
451 {
452 this->reinit(v);
453 }
454
455
456
457 template <std::size_t num_blocks>
458 inline BlockVector::BlockVector(const std::array<Vec, num_blocks> &arrayV)
459 : BlockVector()
460 {
461 this->block_indices.reinit(num_blocks, 0);
462
463 this->components.resize(num_blocks);
464 for (auto i = 0; i < num_blocks; ++i)
465 this->components[i].reinit(arrayV[i]);
466 this->collect_sizes();
467 }
468
469
470
471 inline BlockVector &
472 BlockVector::operator=(const value_type s)
473 {
474 BaseClass::operator=(s);
475 return *this;
476 }
477
478
479
480 inline BlockVector &
481 BlockVector::operator=(const BlockVector &v)
482 {
483 // we only allow assignment to vectors with the same number of blocks
484 // or to an empty BlockVector
485 Assert(this->n_blocks() == 0 || this->n_blocks() == v.n_blocks(),
486 ExcDimensionMismatch(this->n_blocks(), v.n_blocks()));
487
488 if (this->n_blocks() != v.n_blocks())
489 this->block_indices = v.block_indices;
490
491 this->components.resize(this->n_blocks());
492 for (unsigned int i = 0; i < this->n_blocks(); ++i)
493 this->components[i] = v.components[i];
494
495 this->collect_sizes();
496
497 return *this;
498 }
499
500
501
502 inline void
503 BlockVector::reinit(const unsigned int n_blocks,
504 const MPI_Comm communicator,
505 const size_type block_size,
506 const size_type locally_owned_size,
507 const bool omit_zeroing_entries)
508 {
509 reinit(std::vector<size_type>(n_blocks, block_size),
510 communicator,
511 std::vector<size_type>(n_blocks, locally_owned_size),
512 omit_zeroing_entries);
513 }
514
515
516
517 inline void
518 BlockVector::reinit(const std::vector<size_type> &block_sizes,
519 const MPI_Comm communicator,
520 const std::vector<size_type> &locally_owned_sizes,
521 const bool omit_zeroing_entries)
522 {
523 this->block_indices.reinit(block_sizes);
524
525 this->components.resize(this->n_blocks());
526 for (unsigned int i = 0; i < this->n_blocks(); ++i)
527 this->components[i].reinit(communicator,
528 block_sizes[i],
529 locally_owned_sizes[i],
530 omit_zeroing_entries);
531
532 this->collect_sizes();
533 }
534
535
536 inline void
537 BlockVector::reinit(const BlockVector &v, const bool omit_zeroing_entries)
538 {
539 if (this->n_blocks() != v.n_blocks())
540 this->block_indices = v.get_block_indices();
541
542 this->components.resize(this->n_blocks());
543 for (unsigned int i = 0; i < this->n_blocks(); ++i)
544 this->components[i].reinit(v.components[i], omit_zeroing_entries);
545
546 this->collect_sizes();
547 }
548
549
550
551 inline void
552 BlockVector::reinit(const std::vector<IndexSet> &parallel_partitioning,
553 const MPI_Comm communicator)
554 {
555 // update the number of blocks
556 this->block_indices.reinit(parallel_partitioning.size(), 0);
557
558 // initialize each block
559 this->components.resize(this->n_blocks());
560 for (unsigned int i = 0; i < this->n_blocks(); ++i)
561 this->components[i].reinit(parallel_partitioning[i], communicator);
562
563 // update block_indices content
564 this->collect_sizes();
565 }
566
567
568
569 inline void
570 BlockVector::reinit(const std::vector<IndexSet> &parallel_partitioning,
571 const std::vector<IndexSet> &ghost_entries,
572 const MPI_Comm communicator)
573 {
574 AssertDimension(parallel_partitioning.size(), ghost_entries.size());
575
576 // update the number of blocks
577 this->block_indices.reinit(parallel_partitioning.size(), 0);
578
579 // initialize each block
580 this->components.resize(this->n_blocks());
581 for (unsigned int i = 0; i < this->n_blocks(); ++i)
582 this->components[i].reinit(parallel_partitioning[i],
583 ghost_entries[i],
584 communicator);
585
586 // update block_indices content
587 this->collect_sizes();
588 }
589
590
591
592 inline void
593 BlockVector::reinit(
594 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
595 &partitioners,
596 const bool make_ghosted)
597 {
598 // update the number of blocks
599 this->block_indices.reinit(partitioners.size(), 0);
600
601 // initialize each block
602 this->components.resize(this->n_blocks());
603 for (unsigned int i = 0; i < this->n_blocks(); ++i)
604 this->components[i].reinit(partitioners[i], make_ghosted);
605
606 // update block_indices content
607 this->collect_sizes();
608 }
609
610
611
612 inline MPI_Comm
613 BlockVector::get_mpi_communicator() const
614 {
615 return PetscObjectComm(reinterpret_cast<PetscObject>(petsc_nest_vector));
616 }
617
618
619
620 inline bool
621 BlockVector::has_ghost_elements() const
622 {
623 bool ghosted = block(0).has_ghost_elements();
624 if constexpr (running_in_debug_mode())
625 {
626 for (unsigned int i = 0; i < this->n_blocks(); ++i)
627 Assert(block(i).has_ghost_elements() == ghosted,
628 ExcInternalError());
629 }
630 return ghosted;
631 }
632
633
634
635 inline void
636 BlockVector::swap(BlockVector &v) noexcept
637 {
638 std::swap(this->components, v.components);
639 std::swap(this->petsc_nest_vector, v.petsc_nest_vector);
640
641 ::dealii::swap(this->block_indices, v.block_indices);
642 }
643
644
645
646 inline void
647 BlockVector::print(std::ostream &out,
648 const unsigned int precision,
649 const bool scientific,
650 const bool across) const
651 {
652 for (unsigned int i = 0; i < this->n_blocks(); ++i)
653 {
654 if (across)
655 out << 'C' << i << ':';
656 else
657 out << "Component " << i << std::endl;
658 this->components[i].print(out, precision, scientific, across);
659 }
660 }
661
662
663
664 /**
665 * Global function which overloads the default implementation of the C++
666 * standard library which uses a temporary object. The function simply
667 * exchanges the data of the two vectors.
668 *
669 * @relatesalso PETScWrappers::MPI::BlockVector
670 */
671 inline void
672 swap(BlockVector &u, BlockVector &v) noexcept
673 {
674 u.swap(v);
675 }
676 } // namespace MPI
677
678 } // namespace PETScWrappers
679
680 namespace internal
681 {
682 namespace LinearOperatorImplementation
683 {
684 template <typename>
685 class ReinitHelper;
686
687 /**
688 * A helper class used internally in linear_operator.h. Specialization for
689 * PETScWrappers::MPI::BlockVector.
690 */
691 template <>
692 class ReinitHelper<PETScWrappers::MPI::BlockVector>
693 {
694 public:
695 template <typename Matrix>
696 static void
697 reinit_range_vector(const Matrix &matrix,
698 PETScWrappers::MPI::BlockVector &v,
699 bool /*omit_zeroing_entries*/)
700 {
701 v.reinit(matrix.locally_owned_range_indices(),
702 matrix.get_mpi_communicator());
703 }
704
705 template <typename Matrix>
706 static void
707 reinit_domain_vector(const Matrix &matrix,
708 PETScWrappers::MPI::BlockVector &v,
709 bool /*omit_zeroing_entries*/)
710 {
711 v.reinit(matrix.locally_owned_domain_indices(),
712 matrix.get_mpi_communicator());
713 }
714 };
715
716 } // namespace LinearOperatorImplementation
717 } /* namespace internal */
718
719
720 /**
721 * Declare dealii::PETScWrappers::MPI::BlockVector as distributed vector.
722 */
723 template <>
724 struct is_serial_vector<PETScWrappers::MPI::BlockVector> : std::false_type
725 {};
726
727
728 DEAL_II_NAMESPACE_CLOSE
729
730 #else
731
732 // Make sure the scripts that create the C++20 module input files have
733 // something to latch on if the preprocessor #ifdef above would
734 // otherwise lead to an empty content of the file.
735 DEAL_II_NAMESPACE_OPEN
736 DEAL_II_NAMESPACE_CLOSE
737
738 #endif // DEAL_II_WITH_PETSC
739
740 #endif