Debian Codegraph @

include/deal.II/lac/trilinos_parallel_block_vector.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_trilinos_parallel_block_vector_h
16 #define dealii_trilinos_parallel_block_vector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_TRILINOS
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/trilinos_vector.h>
27
28 # include <functional>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // forward declaration
33 # ifndef DOXYGEN
34 template <typename Number>
35 class BlockVectorBase;
36
37 namespace TrilinosWrappers
38 {
39 // forward declaration
40 namespace MPI
41 {
42 class BlockVector;
43 }
44 class BlockSparseMatrix;
45 } // namespace TrilinosWrappers
46 # endif
47
48 /**
49 * @addtogroup TrilinosWrappers
50 * @{
51 */
52
53 namespace TrilinosWrappers
54 {
55 namespace MPI
56 {
57 /**
58 * An implementation of block vectors based on the vector class
59 * implemented in TrilinosWrappers. While the base class provides for most
60 * of the interface, this class handles the actual allocation of vectors
61 * and provides functions that are specific to the underlying vector type.
62 *
63 * The model of distribution of data is such that each of the blocks is
64 * distributed across all MPI processes named in the MPI communicator.
65 * I.e. we don't just distribute the whole vector, but each component. In
66 * the constructors and reinit() functions, one therefore not only has to
67 * specify the sizes of the individual blocks, but also the number of
68 * elements of each of these blocks to be stored on the local process.
69 *
70 * @ingroup Vectors
71 * @ingroup TrilinosWrappers
72 * @see @ref GlossBlockLA "Block (linear algebra)"
73 */
74 class BlockVector : public dealii::BlockVectorBase<MPI::Vector>
75 {
76 public:
77 /**
78 * Typedef the base class for simpler access to its own alias.
79 */
80 using BaseClass = dealii::BlockVectorBase<MPI::Vector>;
81
82 /**
83 * Typedef the type of the underlying vector.
84 */
85 using BlockType = BaseClass::BlockType;
86
87 /**
88 * Import the alias from the base class.
89 */
90 using value_type = BaseClass::value_type;
91 using pointer = BaseClass::pointer;
92 using const_pointer = BaseClass::const_pointer;
93 using reference = BaseClass::reference;
94 using const_reference = BaseClass::const_reference;
95 using size_type = BaseClass::size_type;
96 using iterator = BaseClass::iterator;
97 using const_iterator = BaseClass::const_iterator;
98
99 /**
100 * Default constructor. Generate an empty vector without any blocks.
101 */
102 BlockVector() = default;
103
104 /**
105 * Constructor. Generate a block vector with as many blocks as there are
106 * entries in @p partitioning. Each IndexSet together with the MPI
107 * communicator contains the layout of the distribution of data among
108 * the MPI processes.
109 */
110 explicit BlockVector(const std::vector<IndexSet> &parallel_partitioning,
111 const MPI_Comm communicator = MPI_COMM_WORLD);
112
113 /**
114 * Creates a BlockVector with ghost elements. See the respective
115 * reinit() method for more details. @p ghost_values may contain any
116 * elements in @p parallel_partitioning, they will be ignored.
117 */
118 BlockVector(const std::vector<IndexSet> &parallel_partitioning,
119 const std::vector<IndexSet> &ghost_values,
120 const MPI_Comm communicator,
121 const bool vector_writable = false);
122
123 /**
124 * Copy-Constructor. Set all the properties of the parallel vector to
125 * those of the given argument and copy the elements.
126 */
127 BlockVector(const BlockVector &v);
128
129 /**
130 * Move constructor. Creates a new vector by stealing the internal data
131 * of the vector @p v.
132 */
133 BlockVector(BlockVector &&v) noexcept;
134
135 /**
136 * Creates a block vector consisting of <tt>num_blocks</tt> components,
137 * but there is no content in the individual components and the user has
138 * to fill appropriate data using a reinit of the blocks.
139 */
140 explicit BlockVector(const size_type num_blocks);
141
142 /**
143 * Destructor. Clears memory
144 */
145 ~BlockVector() override = default;
146
147 /**
148 * Copy operator: fill all components of the vector that are locally
149 * stored with the given scalar value.
150 */
151 BlockVector &
152 operator=(const value_type s);
153
154 /**
155 * Copy operator for arguments of the same type. Resize the present vector
156 * if necessary to the correct number of blocks, then copy the individual
157 * blocks from `v` using the copy-assignment operator of the class that
158 * represents the individual blocks.
159 *
160 * Copying the vectors that make up individual blocks can have complex
161 * semantics in parallel vector classes. See the information provided
162 * by the class used to represent the individual blocks.
163 */
164 BlockVector &
165 operator=(const BlockVector &v);
166
167 /**
168 * Move the given vector. This operator replaces the present vector with
169 * @p v by efficiently swapping the internal data structures.
170 */
171 BlockVector &
172 operator=(BlockVector &&v) noexcept;
173
174 /**
175 * Another copy function. This one takes a deal.II block vector and
176 * copies it into a TrilinosWrappers block vector. Note that the number
177 * of blocks has to be the same in the vector as in the input vector.
178 * Use the reinit() command for resizing the BlockVector or for changing
179 * the internal structure of the block components.
180 *
181 * Since Trilinos only works on doubles, this function is limited to
182 * accept only one possible number type in the deal.II vector.
183 */
184 template <typename Number>
185 BlockVector &
186 operator=(const ::dealii::BlockVector<Number> &v);
187
188 /**
189 * Reinitialize the BlockVector to contain as many blocks as there are
190 * index sets given in the input argument, according to the parallel
191 * distribution of the individual components described in the maps.
192 *
193 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
194 * zeros.
195 */
196 void
197 reinit(const std::vector<IndexSet> &parallel_partitioning,
198 const MPI_Comm communicator = MPI_COMM_WORLD,
199 const bool omit_zeroing_entries = false);
200
201 /**
202 * Reinit functionality. This function destroys the old vector content
203 * and generates a new one based on the input partitioning. In addition
204 * to just specifying one index set as in all the other methods above,
205 * this method allows to supply an additional set of ghost entries.
206 * There are two different versions of a vector that can be created. If
207 * the flag @p vector_writable is set to @p false, the vector only
208 * allows read access to the joint set of @p parallel_partitioning and
209 * @p ghost_entries. The effect of the reinit method is then equivalent
210 * to calling the other reinit method with an index set containing both
211 * the locally owned entries and the ghost entries.
212 *
213 * If the flag @p vector_writable is set to true, this creates an
214 * alternative storage scheme for ghost elements that allows multiple
215 * threads to write into the vector (for the other reinit methods, only
216 * one thread is allowed to write into the ghost entries at a time).
217 */
218 void
219 reinit(const std::vector<IndexSet> &partitioning,
220 const std::vector<IndexSet> &ghost_values,
221 const MPI_Comm communicator = MPI_COMM_WORLD,
222 const bool vector_writable = false);
223
224 /**
225 * Initialize each block given to each parallel partitioning described in
226 * @p partitioners.
227 *
228 * You can decide whether your vector will contain ghost elements with
229 * @p make_ghosted.
230 *
231 * The parameter @p vector_writable only has effect on ghosted vectors
232 * and is ignored for non-ghosted vectors.
233 */
234 void
235 reinit(
236 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
237 &partitioners,
238 const bool make_ghosted = true,
239 const bool vector_writable = false);
240
241 /**
242 * Change the dimension to that of the vector <tt>V</tt>. The same
243 * applies as for the other reinit() function.
244 *
245 * The elements of <tt>V</tt> are not copied, i.e. this function is the
246 * same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>.
247 *
248 * Note that you must call this (or the other reinit() functions)
249 * function, rather than calling the reinit() functions of an individual
250 * block, to allow the block vector to update its caches of vector
251 * sizes. If you call reinit() on one of the blocks, then subsequent
252 * actions on this object may yield unpredictable results since they may
253 * be routed to the wrong block.
254 */
255 void
256 reinit(const BlockVector &V, const bool omit_zeroing_entries = false);
257
258 /**
259 * Change the number of blocks to <tt>num_blocks</tt>. The individual
260 * blocks will get initialized with zero size, so it is assumed that the
261 * user resizes the individual blocks by herself in an appropriate way,
262 * and calls <tt>collect_sizes</tt> afterwards.
263 */
264 void
265 reinit(const size_type num_blocks);
266
267 /**
268 * This reinit function is meant to be used for parallel calculations
269 * where some non-local data has to be used. The typical situation where
270 * one needs this function is the call of the
271 * FEValues<dim>::get_function_values function (or of some derivatives)
272 * in parallel. Since it is usually faster to retrieve the data in
273 * advance, this function can be called before the assembly forks out to
274 * the different processors. What this function does is the following:
275 * It takes the information in the columns of the given matrix and looks
276 * which data couples between the different processors. That data is
277 * then queried from the input vector. Note that you should not write to
278 * the resulting vector any more, since the some data can be stored
279 * several times on different processors, leading to unpredictable
280 * results. In particular, such a vector cannot be used for
281 * matrix-vector products as for example done during the solution of
282 * linear systems.
283 */
284 void
285 import_nonlocal_data_for_fe(const TrilinosWrappers::BlockSparseMatrix &m,
286 const BlockVector &v);
287
288 /**
289 * Return if this Vector contains ghost elements.
290 *
291 * @see
292 * @ref GlossGhostedVector "vectors with ghost elements"
293 */
294 bool
295 has_ghost_elements() const;
296
297 /**
298 * Swap the contents of this vector and the other vector <tt>v</tt>. One
299 * could do this operation with a temporary variable and copying over
300 * the data elements, but this function is significantly more efficient
301 * since it only swaps the pointers to the data of the two vectors and
302 * therefore does not need to allocate temporary storage and move data
303 * around.
304 *
305 * Limitation: right now this function only works if both vectors have
306 * the same number of blocks. If needed, the numbers of blocks should be
307 * exchanged, too.
308 *
309 * This function is analogous to the swap() function of all C++
310 * standard containers. Also, there is a global function swap(u,v) that
311 * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
312 * functions.
313 */
314 void
315 swap(BlockVector &v) noexcept;
316
317 /**
318 * Print to a stream.
319 */
320 void
321 print(std::ostream &out,
322 const unsigned int precision = 3,
323 const bool scientific = true,
324 const bool across = true) const;
325
326 /**
327 * Exception
328 */
329 DeclException0(ExcIteratorRangeDoesNotMatchVectorSize);
330
331 /**
332 * Exception
333 */
334 DeclException0(ExcNonMatchingBlockVectors);
335 };
336
337
338
339 /*-------------------------- Inline functions ---------------------------*/
340 inline BlockVector::BlockVector(
341 const std::vector<IndexSet> &parallel_partitioning,
342 const MPI_Comm communicator)
343 {
344 reinit(parallel_partitioning, communicator, false);
345 }
346
347
348
349 inline BlockVector::BlockVector(
350 const std::vector<IndexSet> &parallel_partitioning,
351 const std::vector<IndexSet> &ghost_values,
352 const MPI_Comm communicator,
353 const bool vector_writable)
354 {
355 reinit(parallel_partitioning,
356 ghost_values,
357 communicator,
358 vector_writable);
359 }
360
361
362
363 inline BlockVector::BlockVector(const size_type num_blocks)
364 {
365 reinit(num_blocks);
366 }
367
368
369
370 inline BlockVector::BlockVector(const BlockVector &v)
371 : dealii::BlockVectorBase<MPI::Vector>()
372 {
373 this->block_indices = v.block_indices;
374
375 this->components.resize(this->n_blocks());
376 for (unsigned int i = 0; i < this->n_blocks(); ++i)
377 this->components[i] = v.components[i];
378
379 this->collect_sizes();
380 }
381
382
383
384 inline BlockVector::BlockVector(BlockVector &&v) noexcept
385 {
386 // initialize a minimal, valid object and swap
387 reinit(0);
388 swap(v);
389 }
390
391
392
393 template <typename Number>
394 BlockVector &
395 BlockVector::operator=(const ::dealii::BlockVector<Number> &v)
396 {
397 // we only allow assignment to vectors with the same number of blocks
398 // or to an empty BlockVector
399 Assert(this->n_blocks() == 0 || this->n_blocks() == v.n_blocks(),
400 ExcDimensionMismatch(this->n_blocks(), v.n_blocks()));
401
402 if (this->n_blocks() != v.n_blocks())
403 this->block_indices = v.get_block_indices();
404
405 this->components.resize(this->n_blocks());
406 for (unsigned int i = 0; i < this->n_blocks(); ++i)
407 this->components[i] = v.block(i);
408
409 this->collect_sizes();
410
411 return *this;
412 }
413
414
415
416 inline bool
417 BlockVector::has_ghost_elements() const
418 {
419 bool ghosted = block(0).has_ghost_elements();
420 if constexpr (running_in_debug_mode())
421 {
422 for (unsigned int i = 0; i < this->n_blocks(); ++i)
423 Assert(block(i).has_ghost_elements() == ghosted,
424 ExcInternalError());
425 }
426 return ghosted;
427 }
428
429
430
431 inline void
432 BlockVector::swap(BlockVector &v) noexcept
433 {
434 std::swap(this->components, v.components);
435
436 dealii::swap(this->block_indices, v.block_indices);
437 }
438
439
440
441 /**
442 * Global function which overloads the default implementation of the C++
443 * standard library which uses a temporary object. The function simply
444 * exchanges the data of the two vectors.
445 *
446 * @relatesalso TrilinosWrappers::MPI::BlockVector
447 */
448 inline void
449 swap(BlockVector &u, BlockVector &v) noexcept
450 {
451 u.swap(v);
452 }
453
454 } /* namespace MPI */
455
456 } /* namespace TrilinosWrappers */
457
458 /** @} */
459
460
461 namespace internal
462 {
463 namespace LinearOperatorImplementation
464 {
465 template <typename>
466 class ReinitHelper;
467
468 /**
469 * A helper class used internally in linear_operator.h. Specialization for
470 * TrilinosWrappers::MPI::BlockVector.
471 */
472 template <>
473 class ReinitHelper<TrilinosWrappers::MPI::BlockVector>
474 {
475 public:
476 template <typename Matrix>
477 static void
478 reinit_range_vector(const Matrix &matrix,
479 TrilinosWrappers::MPI::BlockVector &v,
480 bool omit_zeroing_entries)
481 {
482 v.reinit(matrix.locally_owned_range_indices(),
483 matrix.get_mpi_communicator(),
484 omit_zeroing_entries);
485 }
486
487 template <typename Matrix>
488 static void
489 reinit_domain_vector(const Matrix &matrix,
490 TrilinosWrappers::MPI::BlockVector &v,
491 bool omit_zeroing_entries)
492 {
493 v.reinit(matrix.locally_owned_domain_indices(),
494 matrix.get_mpi_communicator(),
495 omit_zeroing_entries);
496 }
497 };
498
499 } // namespace LinearOperatorImplementation
500 } /* namespace internal */
501
502
503 /**
504 * Declare dealii::TrilinosWrappers::MPI::BlockVector as distributed vector.
505 */
506 template <>
507 struct is_serial_vector<TrilinosWrappers::MPI::BlockVector> : std::false_type
508 {};
509
510 DEAL_II_NAMESPACE_CLOSE
511
512 #else
513
514 // Make sure the scripts that create the C++20 module input files have
515 // something to latch on if the preprocessor #ifdef above would
516 // otherwise lead to an empty content of the file.
517 DEAL_II_NAMESPACE_OPEN
518 DEAL_II_NAMESPACE_CLOSE
519
520 #endif // DEAL_II_WITH_TRILINOS
521
522 #endif