Debian Codegraph @

include/deal.II/lac/la_parallel_block_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 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_la_parallel_block_vector_h
16 #define dealii_la_parallel_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/la_parallel_vector.h>
26 #include <deal.II/lac/vector_operation.h>
27 #include <deal.II/lac/vector_type_traits.h>
28
29 #include <cstdio>
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34
35 // Forward declarations
36 #ifndef DOXYGEN
37 # ifdef DEAL_II_WITH_PETSC
38 namespace PETScWrappers
39 {
40 namespace MPI
41 {
42 class BlockVector;
43 }
44 } // namespace PETScWrappers
45 # endif
46
47 # ifdef DEAL_II_WITH_TRILINOS
48 namespace TrilinosWrappers
49 {
50 namespace MPI
51 {
52 class BlockVector;
53 }
54 } // namespace TrilinosWrappers
55 # endif
56 #endif
57
58 namespace LinearAlgebra
59 {
60 namespace distributed
61 {
62 /**
63 * @addtogroup Vectors
64 * @{
65 */
66
67
68 /**
69 * An implementation of block vectors based on distributed deal.II
70 * vectors. While the base class provides for most of the interface, this
71 * class handles the actual allocation of vectors and provides functions
72 * that are specific to the underlying vector type.
73 *
74 * @note Instantiations for this template are provided for <tt>@<float@>
75 * and @<double@></tt>; others can be generated in application programs
76 * (see the section on
77 * @ref Instantiations
78 * in the manual).
79 *
80 * @see
81 * @ref GlossBlockLA "Block (linear algebra)"
82 */
83 template <typename Number, typename MemorySpace = MemorySpace::Host>
84 class BlockVector : public BlockVectorBase<Vector<Number, MemorySpace>>
85 {
86 public:
87 /**
88 * The chunks size to split communication in update_ghost_values()
89 * and compress() calls.
90 *
91 * Most common MPI implementations will get slow when too many
92 * messages/requests are outstanding. Even when messages are small,
93 * say 1 kB only, we should collect enough data with @p communication_block_size
94 * to cover typical infiniband latencies which are around a few
95 * microseconds. Sending 20 kB at a throughput of 5 GB/s takes 4
96 * microseconds, so we should arrive at the bandwidth dominated regime
97 * then which is good enough.
98 */
99 static constexpr unsigned int communication_block_size = 20;
100
101 /**
102 * Typedef the base class for simpler access to its own alias.
103 */
104 using BaseClass = BlockVectorBase<Vector<Number, MemorySpace>>;
105
106 /**
107 * Typedef the type of the underlying vector.
108 */
109 using BlockType = typename BaseClass::BlockType;
110
111 /**
112 * Import the alias from the base class.
113 */
114 using value_type = typename BaseClass::value_type;
115 using real_type = typename BaseClass::real_type;
116 using pointer = typename BaseClass::pointer;
117 using const_pointer = typename BaseClass::const_pointer;
118 using reference = typename BaseClass::reference;
119 using const_reference = typename BaseClass::const_reference;
120 using size_type = typename BaseClass::size_type;
121 using iterator = typename BaseClass::iterator;
122 using const_iterator = typename BaseClass::const_iterator;
123
124 /**
125 * @name 1: Basic operations
126 */
127 /** @{ */
128
129 /**
130 * Constructor. There are three ways to use this constructor. First,
131 * without any arguments, it generates an object with no blocks. Given
132 * one argument, it initializes <tt>num_blocks</tt> blocks, but these
133 * blocks have size zero. The third variant finally initializes all
134 * blocks to the same size <tt>block_size</tt>.
135 *
136 * Confer the other constructor further down if you intend to use blocks
137 * of different sizes.
138 */
139 explicit BlockVector(const size_type num_blocks = 0,
140 const size_type block_size = 0);
141
142 /**
143 * Copy-Constructor. Dimension set to that of V, all components are
144 * copied from V
145 */
146 BlockVector(const BlockVector<Number, MemorySpace> &V);
147
148 /**
149 * Copy constructor taking a BlockVector of another data type. This will
150 * fail if there is no conversion path from <tt>OtherNumber</tt> to
151 * <tt>Number</tt>. Note that you may lose accuracy when copying to a
152 * BlockVector with data elements with less accuracy.
153 */
154 template <typename OtherNumber>
155 explicit BlockVector(const BlockVector<OtherNumber, MemorySpace> &v);
156
157 /**
158 * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt>
159 * and initialize each block with <tt>block_sizes[i]</tt> zero elements.
160 */
161 BlockVector(const std::vector<size_type> &block_sizes);
162
163 /**
164 * Construct a block vector with an IndexSet for the local range and
165 * ghost entries for each block.
166 */
167 BlockVector(const std::vector<IndexSet> &local_ranges,
168 const std::vector<IndexSet> &ghost_indices,
169 const MPI_Comm communicator);
170
171 /**
172 * Same as above but the ghost indices are assumed to be empty.
173 */
174 BlockVector(const std::vector<IndexSet> &local_ranges,
175 const MPI_Comm communicator);
176
177 /**
178 * Construct a block vector with a Utilities::MPI::Partitioner for each
179 * block.
180 *
181 * The optional argument @p comm_sm, which consists of processes on
182 * the same shared-memory domain, allows users have read-only access to
183 * both locally-owned and ghost values of processes combined in the
184 * shared-memory communicator. See the general documentation of the
185 * LinearAlgebra::distributed::Vector class for more information about
186 * this argument.
187 */
188 BlockVector(
189 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
190 &partitioners,
191 const MPI_Comm &comm_sm = MPI_COMM_SELF);
192
193 /**
194 * Destructor.
195 *
196 * @note We need to explicitly provide a destructor, otherwise the
197 * linker may think it is unused and discards it, although required
198 * in a different section. The Intel compiler is prone to this
199 * behavior.
200 */
201 ~BlockVector() = default;
202
203 /**
204 * Copy operator: fill all components of the vector with the given
205 * scalar value.
206 */
207 BlockVector &
208 operator=(const value_type s);
209
210 /**
211 * Copy operator for arguments of the same type. Resize the present vector
212 * if necessary to the correct number of blocks, then copy the individual
213 * blocks from `v` using the copy-assignment operator of the class that
214 * represents the individual blocks.
215 *
216 * Copying the vectors that make up individual blocks can have complex
217 * semantics in parallel vector classes. See the information provided
218 * by the class used to represent the individual blocks.
219 */
220 BlockVector &
221 operator=(const BlockVector &V);
222
223 /**
224 * Copy operator for arguments of different type. Resize the present
225 * vector if necessary to the correct number of blocks, then copy the
226 * individual blocks from `v` using the copy-assignment operator of the
227 * class that represents the individual blocks.
228 *
229 * Copying the vectors that make up individual blocks can have complex
230 * semantics in parallel vector classes. See the information provided
231 * by the class used to represent the individual blocks.
232 */
233 template <class Number2>
234 BlockVector &
235 operator=(const BlockVector<Number2, MemorySpace> &V);
236
237 /**
238 * Copy a regular vector into a block vector.
239 */
240 BlockVector &
241 operator=(const Vector<Number, MemorySpace> &V);
242
243 #ifdef DEAL_II_WITH_PETSC
244 /**
245 * Copy the content of a PETSc vector into the calling vector. This
246 * function assumes that the vectors layouts have already been
247 * initialized to match.
248 *
249 * This operator is only available if deal.II was configured with PETSc.
250 */
251 BlockVector<Number, MemorySpace> &
252 operator=(const PETScWrappers::MPI::BlockVector &petsc_vec);
253 #endif
254
255 #ifdef DEAL_II_WITH_TRILINOS
256 /**
257 * Copy the content of a Trilinos vector into the calling vector. This
258 * function assumes that the vectors layouts have already been
259 * initialized to match.
260 *
261 * This operator is only available if deal.II was configured with
262 * Trilinos.
263 */
264 BlockVector<Number, MemorySpace> &
265 operator=(const TrilinosWrappers::MPI::BlockVector &trilinos_vec);
266 #endif
267
268 /**
269 * Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
270 * size <tt>block_size</tt> each.
271 *
272 * If the second argument is left at its default value, then the block
273 * vector allocates the specified number of blocks but leaves them at
274 * zero size. You then need to later reinitialize the individual blocks,
275 * and call collect_sizes() to update the block system's knowledge of
276 * its individual block's sizes.
277 *
278 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
279 * zeros.
280 */
281 void
282 reinit(const size_type num_blocks,
283 const size_type block_size = 0,
284 const bool omit_zeroing_entries = false);
285
286 /**
287 * Reinitialize the BlockVector such that it contains
288 * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
289 * dimension <tt>block_sizes[i]</tt>.
290 *
291 * If the number of blocks is the same as before this function was
292 * called, all vectors remain the same and reinit() is called for each
293 * vector.
294 *
295 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
296 * zeros.
297 *
298 * Note that you must call this (or the other reinit() functions)
299 * function, rather than calling the reinit() functions of an individual
300 * block, to allow the block vector to update its caches of vector
301 * sizes. If you call reinit() on one of the blocks, then subsequent
302 * actions on this object may yield unpredictable results since they may
303 * be routed to the wrong block.
304 */
305 void
306 reinit(const std::vector<size_type> &block_sizes,
307 const bool omit_zeroing_entries = false);
308
309 /**
310 * Change the dimension to that of the vector <tt>V</tt>. The same
311 * applies as for the other reinit() function.
312 *
313 * The elements of <tt>V</tt> are not copied, i.e. this function is the
314 * same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>.
315 *
316 * Note that you must call this (or the other reinit() functions)
317 * function, rather than calling the reinit() functions of an individual
318 * block, to allow the block vector to update its caches of vector
319 * sizes. If you call reinit() of one of the blocks, then subsequent
320 * actions of this object may yield unpredictable results since they may
321 * be routed to the wrong block.
322 */
323 template <typename Number2>
324 void
325 reinit(const BlockVector<Number2, MemorySpace> &V,
326 const bool omit_zeroing_entries = false);
327
328 /**
329 * Initialize the block vector. For each block, the local range is
330 * specified by the corresponding entry in @p local_ranges (note that this
331 * must be a contiguous interval, multiple intervals are not possible).
332 * The parameter @p ghost_indices specifies ghost indices for each block,
333 * i.e., indices which one might need to read data from or accumulate data
334 * from. It is allowed that the set of ghost indices also contains the
335 * local range, but it does not need to.
336 *
337 * This function involves global communication, so it should only be
338 * called once for a given layout. Use the @p reinit function with
339 * BlockVector<Number, MemorySpace> argument to create additional vectors
340 * with the same parallel layout.
341 *
342 * @see
343 * @ref GlossGhostedVector "vectors with ghost elements"
344 */
345 void
346 reinit(const std::vector<IndexSet> &local_ranges,
347 const std::vector<IndexSet> &ghost_indices,
348 const MPI_Comm communicator);
349
350 /**
351 * Same as above, but without ghost entries.
352 */
353 void
354 reinit(const std::vector<IndexSet> &local_ranges,
355 const MPI_Comm communicator);
356
357 /**
358 * Initialize each block with the corresponding parallel partitioning
359 * in @p partitioners. The input arguments are shared pointers, which
360 * store the partitioner data only once and can be shared between several
361 * vectors with the same layout.
362 *
363 * The optional argument @p comm_sm, which consists of processes on
364 * the same shared-memory domain, allows users have read-only access to
365 * both locally-owned and ghost values of processes combined in the
366 * shared-memory communicator. See the general documentation of the
367 * LinearAlgebra::distributed::Vector class for more information about
368 * this argument.
369 */
370 void
371 reinit(
372 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
373 &partitioners,
374 const MPI_Comm &comm_sm = MPI_COMM_SELF);
375
376 /**
377 * This function exists purely for reasons of compatibility with the
378 * PETScWrappers::MPI::Vector and TrilinosWrappers::MPI::Vector classes.
379 *
380 * It calls the function above, and ignores the parameter @p make_ghosted.
381 */
382 void
383 reinit(
384 const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
385 &partitioners,
386 const bool make_ghosted,
387 const MPI_Comm &comm_sm = MPI_COMM_SELF);
388
389 /**
390 * This function copies the data that has accumulated in the data buffer
391 * for ghost indices to the owning processor. For the meaning of the
392 * argument @p operation, see the entry on
393 * @ref GlossCompress "Compressing distributed vectors and matrices"
394 * in the glossary.
395 *
396 * There are two variants for this function. If called with argument @p
397 * VectorOperation::add adds all the data accumulated in ghost elements
398 * to the respective elements on the owning processor and clears the
399 * ghost array afterwards. If called with argument @p
400 * VectorOperation::insert, a set operation is performed. Since setting
401 * elements in a vector with ghost elements is ambiguous (as one can set
402 * both the element on the ghost site as well as the owning site), this
403 * operation makes the assumption that all data is set correctly on the
404 * owning processor. Upon call of compress(VectorOperation::insert), all
405 * ghost entries are therefore simply zeroed out (using
406 * zero_ghost_values()). In debug mode, a check is performed that makes
407 * sure that the data set is actually consistent between processors,
408 * i.e., whenever a non-zero ghost element is found, it is compared to
409 * the value on the owning processor and an exception is thrown if these
410 * elements do not agree.
411 */
412 void
413 compress(VectorOperation::values operation);
414
415 /**
416 * Fills the data field for ghost indices with the values stored in the
417 * respective positions of the owning processor. This function is needed
418 * before reading from ghosts. The function is @p const even though
419 * ghost data is changed. This is needed to allow functions with a @p
420 * const vector to perform the data exchange without creating
421 * temporaries.
422 */
423 void
424 update_ghost_values() const;
425
426 /**
427 * This method zeros the entries on ghost dofs, but does not touch
428 * locally owned DoFs.
429 *
430 * After calling this method, read access to ghost elements of the
431 * vector is forbidden and an exception is thrown. Only write access to
432 * ghost elements is allowed in this state.
433 */
434 void
435 zero_out_ghost_values() const;
436
437 /**
438 * Return if any of the blocks in this vector contains ghost elements.
439 */
440 bool
441 has_ghost_elements() const;
442
443 /**
444 * Change the ghost state of all blocks in this vector to @p ghosted.
445 */
446 void
447 set_ghost_state(const bool ghosted) const;
448
449 /**
450 * This method copies the data in the locally owned range from another
451 * distributed vector @p src into the calling vector. As opposed to
452 * operator= that also includes ghost entries, this operation ignores
453 * the ghost range. The only prerequisite is that the local range on the
454 * calling vector and the given vector @p src are the same on all
455 * processors. It is explicitly allowed that the two vectors have
456 * different ghost elements that might or might not be related to each
457 * other.
458 *
459 * Since no data exchange is performed, make sure that neither @p src
460 * nor the calling vector have pending communications in order to obtain
461 * correct results.
462 */
463 template <typename Number2>
464 void
465 copy_locally_owned_data_from(
466 const BlockVector<Number2, MemorySpace> &src);
467
468 /**
469 * This is a collective add operation that adds a whole set of values
470 * stored in @p values to the vector components specified by @p indices.
471 */
472 template <typename OtherNumber>
473 void
474 add(const std::vector<size_type> &indices,
475 const ::dealii::Vector<OtherNumber> &values);
476
477 /**
478 * Scaling and simple vector addition, i.e. <tt>*this =
479 * s*(*this)+V</tt>.
480 */
481 void
482 sadd(const Number s, const BlockVector<Number, MemorySpace> &V);
483
484 /**
485 * Return whether the vector contains only elements with value zero.
486 * This function is mainly for internal consistency checks and should
487 * seldom be used when not in debug mode since it uses quite some time.
488 */
489 bool
490 all_zero() const;
491
492 /**
493 * Compute the mean value of all the entries in the vector.
494 */
495 Number
496 mean_value() const;
497
498 /**
499 * $l_p$-norm of the vector. The pth root of the sum of the pth powers
500 * of the absolute values of the elements.
501 */
502 real_type
503 lp_norm(const real_type p) const;
504
505 /**
506 * Swap the contents of this vector and the other vector <tt>v</tt>. One
507 * could do this operation with a temporary variable and copying over
508 * the data elements, but this function is significantly more efficient
509 * since it only swaps the pointers to the data of the two vectors and
510 * therefore does not need to allocate temporary storage and move data
511 * around.
512 *
513 * Limitation: right now this function only works if both vectors have
514 * the same number of blocks. If needed, the numbers of blocks should be
515 * exchanged, too.
516 *
517 * This function is analogous to the swap() function of all C++
518 * standard containers. Also, there is a global function swap(u,v) that
519 * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
520 * functions.
521 */
522 void
523 swap(BlockVector<Number, MemorySpace> &v) noexcept;
524 /** @} */
525
526 /**
527 * @name 2: Vector space operations
528 */
529 /** @{ */
530
531 /**
532 * Multiply the entire vector by a fixed factor.
533 */
534 BlockVector<Number, MemorySpace> &
535 operator*=(const Number factor);
536
537 /**
538 * Divide the entire vector by a fixed factor.
539 */
540 BlockVector<Number, MemorySpace> &
541 operator/=(const Number factor);
542
543 /**
544 * Add the vector @p V to the present one.
545 */
546 BlockVector<Number, MemorySpace> &
547 operator+=(const BlockVector<Number, MemorySpace> &V);
548
549 /**
550 * Subtract the vector @p V from the present one.
551 */
552 BlockVector<Number, MemorySpace> &
553 operator-=(const BlockVector<Number, MemorySpace> &V);
554
555 /**
556 * Import all the elements present in the vector's IndexSet from the input
557 * vector @p V. VectorOperation::values @p operation is used to decide if
558 * the elements in @p V should be added to the current vector or replace the
559 * current elements. The last parameter can be used if the same
560 * communication pattern is used multiple times. This can be used to
561 * improve performance.
562 */
563 void
564 import_elements(
565 const LinearAlgebra::ReadWriteVector<Number> &V,
566 const VectorOperation::values operation,
567 const std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
568 &communication_pattern = {});
569
570 /**
571 * @deprecated Use import_elements() instead.
572 */
573 DEAL_II_DEPRECATED void
574 import(const LinearAlgebra::ReadWriteVector<Number> &V,
575 VectorOperation::values operation,
576 std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
577 communication_pattern = {})
578 {
579 import_elements(V, operation, communication_pattern);
580 }
581
582 /**
583 * Return the scalar product of two vectors.
584 */
585 Number
586 operator*(const BlockVector<Number, MemorySpace> &V) const;
587
588 /**
589 * Calculate the scalar product between each block of this vector and @p V
590 * and store the result in a full matrix @p matrix. This function
591 * computes the result by forming $A_{ij}=U_i \cdot V_j$ where $U_i$
592 * and $V_j$ indicate the $i$th block (not element!) of $U$ and the
593 * $j$th block of $V$, respectively. If @p symmetric is
594 * <code>true</code>, it is assumed that inner product results in a
595 * square symmetric matrix and almost half of the scalar products can be
596 * avoided.
597 *
598 * Obviously, this function can only be used if all blocks of both vectors
599 * are of the same size.
600 *
601 * @note Internally, a single global reduction will be called to
602 * accumulate scalar product between locally owned degrees of freedom.
603 */
604 template <typename FullMatrixType>
605 void
606 multivector_inner_product(FullMatrixType &matrix,
607 const BlockVector<Number, MemorySpace> &V,
608 const bool symmetric = false) const;
609
610 /**
611 * Calculate the scalar product between each block of this vector and @p V
612 * using a metric tensor @p matrix. This function
613 * computes the result of $ \sum_{ij} A^{ij} U_i \cdot V_j$ where $U_i$
614 * and $V_j$ indicate the $i$th block (not element) of $U$ and the
615 * $j$th block of $V$, respectively. If @p symmetric is
616 * <code>true</code>, it is assumed that $U_i \cdot V_j$ and $A^{ij}$ are
617 * symmetric matrices and almost half of the scalar products can be
618 * avoided.
619 *
620 * Obviously, this function can only be used if all blocks of both vectors
621 * are of the same size.
622 *
623 * @note Internally, a single global reduction will be called to
624 * accumulate the scalar product between locally owned degrees of freedom.
625 */
626 template <typename FullMatrixType>
627 Number
628 multivector_inner_product_with_metric(
629 const FullMatrixType &matrix,
630 const BlockVector<Number, MemorySpace> &V,
631 const bool symmetric = false) const;
632
633 /**
634 * Set each block of this vector as follows:
635 * $V^i = s V^i + b \sum_{j} U_j A^{ji}$ where $V^i$
636 * and $U_j$ indicate the $i$th block (not element) of $V$ and the
637 * $j$th block of $U$, respectively.
638 *
639 * Obviously, this function can only be used if all blocks of both vectors
640 * are of the same size.
641 */
642 template <typename FullMatrixType>
643 void
644 mmult(BlockVector<Number, MemorySpace> &V,
645 const FullMatrixType &matrix,
646 const Number s = Number(0.),
647 const Number b = Number(1.)) const;
648
649 /**
650 * Add @p a to all components. Note that @p a is a scalar not a vector.
651 */
652 void
653 add(const Number a);
654
655 /**
656 * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>.
657 */
658 void
659 add(const Number a, const BlockVector<Number, MemorySpace> &V);
660
661 /**
662 * Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>.
663 */
664 void
665 add(const Number a,
666 const BlockVector<Number, MemorySpace> &V,
667 const Number b,
668 const BlockVector<Number, MemorySpace> &W);
669
670 /**
671 * A collective add operation: This function adds a whole set of values
672 * stored in @p values to the vector components specified by @p indices.
673 */
674 void
675 add(const std::vector<size_type> &indices,
676 const std::vector<Number> &values);
677
678 /**
679 * Scaling and simple addition of a multiple of a vector, i.e. <tt>*this =
680 * s*(*this)+a*V</tt>.
681 */
682 void
683 sadd(const Number s,
684 const Number a,
685 const BlockVector<Number, MemorySpace> &V);
686
687 /**
688 * Scale each element of this vector by the corresponding element in the
689 * argument. This function is mostly meant to simulate multiplication (and
690 * immediate re-assignment) by a diagonal scaling matrix.
691 */
692 void
693 scale(const BlockVector<Number, MemorySpace> &scaling_factors);
694
695 /**
696 * Assignment <tt>*this = a*V</tt>.
697 */
698 void
699 equ(const Number a, const BlockVector<Number, MemorySpace> &V);
700
701 /**
702 * Return the l<sub>1</sub> norm of the vector (i.e., the sum of the
703 * absolute values of all entries among all processors).
704 */
705 real_type
706 l1_norm() const;
707
708 /**
709 * Return the $l_2$ norm of the vector (i.e., the square root of
710 * the sum of the square of all entries among all processors).
711 */
712 real_type
713 l2_norm() const;
714
715 /**
716 * Return the square of the $l_2$ norm of the vector.
717 */
718 real_type
719 norm_sqr() const;
720
721 /**
722 * Return the maximum norm of the vector (i.e., the maximum absolute value
723 * among all entries and among all processors).
724 */
725 real_type
726 linfty_norm() const;
727
728 /**
729 * Perform a combined operation of a vector addition and a subsequent
730 * inner product, returning the value of the inner product. In other
731 * words, the result of this function is the same as if the user called
732 * @code
733 * this->add(a, V);
734 * return_value = *this * W;
735 * @endcode
736 *
737 * The reason this function exists is that this operation involves less
738 * memory transfer than calling the two functions separately. This method
739 * only needs to load three vectors, @p this, @p V, @p W, whereas calling
740 * separate methods means to load the calling vector @p this twice. Since
741 * most vector operations are memory transfer limited, this reduces the
742 * time by 25\% (or 50\% if @p W equals @p this).
743 *
744 * For complex-valued vectors, the scalar product in the second step is
745 * implemented as
746 * $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
747 */
748 Number
749 add_and_dot(const Number a,
750 const BlockVector<Number, MemorySpace> &V,
751 const BlockVector<Number, MemorySpace> &W);
752
753 /**
754 * Return the global size of the vector, equal to the sum of the number of
755 * locally owned indices among all processors.
756 */
757 virtual size_type
758 size() const override;
759
760 /**
761 * Return an index set that describes which elements of this vector are
762 * owned by the current processor. As a consequence, the index sets
763 * returned on different processors if this is a distributed vector will
764 * form disjoint sets that add up to the complete index set. Obviously, if
765 * a vector is created on only one processor, then the result would
766 * satisfy
767 * @code
768 * vec.locally_owned_elements() == complete_index_set(vec.size())
769 * @endcode
770 */
771 dealii::IndexSet
772 locally_owned_elements() const;
773
774 /**
775 * Print the vector to the output stream @p out.
776 */
777 void
778 print(std::ostream &out,
779 const unsigned int precision = 3,
780 const bool scientific = true,
781 const bool across = true) const;
782
783 /**
784 * Return the memory consumption of this class in bytes.
785 */
786 std::size_t
787 memory_consumption() const;
788 /** @} */
789
790 /**
791 * @addtogroup Exceptions
792 * @{
793 */
794
795 /**
796 * Attempt to perform an operation between two incompatible vector types.
797 *
798 * @ingroup Exceptions
799 */
800 DeclException0(ExcVectorTypeNotCompatible);
801
802 /**
803 * Exception
804 */
805 DeclException0(ExcIteratorRangeDoesNotMatchVectorSize);
806 /** @} */
807 };
808
809 /** @} */
810
811 } // end of namespace distributed
812
813 } // end of namespace LinearAlgebra
814
815
816 /**
817 * Global function which overloads the default implementation of the C++
818 * standard library which uses a temporary object. The function simply
819 * exchanges the data of the two vectors.
820 *
821 * @relatesalso BlockVector
822 */
823 template <typename Number, typename MemorySpace>
824 inline void
825 swap(LinearAlgebra::distributed::BlockVector<Number, MemorySpace> &u,
826 LinearAlgebra::distributed::BlockVector<Number, MemorySpace> &v) noexcept
827 {
828 u.swap(v);
829 }
830
831
832 /**
833 * Declare dealii::LinearAlgebra::distributed::BlockVector as distributed
834 * vector.
835 */
836 template <typename Number, typename MemorySpace>
837 struct is_serial_vector<
838 LinearAlgebra::distributed::BlockVector<Number, MemorySpace>>
839 : std::false_type
840 {};
841
842
843 DEAL_II_NAMESPACE_CLOSE
844
845 #endif