Debian Codegraph @

include/deal.II/lac/la_parallel_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_la_parallel_vector_h
16 #define dealii_la_parallel_vector_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/communication_pattern_base.h>
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/memory_space.h>
23 #include <deal.II/base/memory_space_data.h>
24 #include <deal.II/base/mpi_stub.h>
25 #include <deal.II/base/numbers.h>
26 #include <deal.II/base/parallel.h>
27 #include <deal.II/base/partitioner.h>
28
29 #include <deal.II/lac/read_vector.h>
30 #include <deal.II/lac/vector_operation.h>
31 #include <deal.II/lac/vector_type_traits.h>
32
33 #include <iomanip>
34 #include <memory>
35
36 #if defined(DEAL_II_WITH_MPI)
37 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
38 # include <mpi.h>
39 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
40 #endif
41
42
43 DEAL_II_NAMESPACE_OPEN
44
45 // Forward declarations
46 #ifndef DOXYGEN
47 namespace LinearAlgebra
48 {
49 /**
50 * A namespace for parallel implementations of vectors.
51 */
52 namespace distributed
53 {
54 template <typename, typename>
55 class BlockVector;
56 }
57
58 template <typename>
59 class ReadWriteVector;
60 } // namespace LinearAlgebra
61
62 # ifdef DEAL_II_WITH_PETSC
63 namespace PETScWrappers
64 {
65 namespace MPI
66 {
67 class Vector;
68 }
69 } // namespace PETScWrappers
70 # endif
71
72 # ifdef DEAL_II_WITH_TRILINOS
73 namespace TrilinosWrappers
74 {
75 namespace MPI
76 {
77 class Vector;
78 }
79 } // namespace TrilinosWrappers
80 # endif
81 #endif
82
83 namespace LinearAlgebra
84 {
85 namespace distributed
86 {
87 /**
88 * @addtogroup Vectors
89 * @{
90 */
91
92 /**
93 * Implementation of a parallel vector class. The design of this class is
94 * similar to the standard ::dealii::Vector class in deal.II, with the
95 * exception that storage is distributed with MPI.
96 *
97 * The vector is designed for the following scheme of parallel
98 * partitioning:
99 * <ul>
100 * <li> The indices held by individual processes (locally owned part) in
101 * the MPI parallelization form a contiguous range
102 * <code>[my_first_index,my_last_index)</code>.
103 * <li> Ghost indices residing on arbitrary positions of other processors
104 * are allowed. It is in general more efficient if ghost indices are
105 * clustered, since they are stored as a set of intervals. The
106 * communication pattern of the ghost indices is determined when calling
107 * the function <code>reinit (locally_owned, ghost_indices,
108 * communicator)</code>, and retained until the partitioning is changed.
109 * This allows for efficient parallel communication of indices. In
110 * particular, it stores the communication pattern, rather than having to
111 * compute it again for every communication. For more information on ghost
112 * vectors, see also the
113 * @ref GlossGhostedVector "glossary entry on vectors with ghost elements".
114 * <li> Besides the usual global access operator() it is also possible to
115 * access vector entries in the local index space with the function @p
116 * local_element(). Locally owned indices are placed first, [0,
117 * locally_owned_size()), and then all ghost indices follow after them
118 * contiguously, [locally_owned_size(),
119 * locally_owned_size()+get_partitioner()->n_ghost_indices()).
120 * </ul>
121 *
122 * Functions related to parallel functionality:
123 * <ul>
124 * <li> The function <code>compress()</code> goes through the data
125 * associated with ghost indices and communicates it to the owner process,
126 * which can then add it to the correct position. This can be used e.g.
127 * after having run an assembly routine involving ghosts that fill this
128 * vector. Note that the @p insert mode of @p compress() does not set the
129 * elements included in ghost entries but simply discards them, assuming
130 * that the owning processor has set them to the desired value already
131 * (See also the
132 * @ref GlossCompress "glossary entry on compress").
133 * <li> The <code>update_ghost_values()</code> function imports the data
134 * from the owning processor to the ghost indices in order to provide read
135 * access to the data associated with ghosts.
136 * <li> It is possible to split the above functions into two phases, where
137 * the first initiates the communication and the second one finishes it.
138 * These functions can be used to overlap communication with computations
139 * in other parts of the code.
140 * <li> Of course, reduction operations (like norms) make use of
141 * collective all-to-all MPI communications.
142 * </ul>
143 *
144 * This vector can take two different states with respect to ghost
145 * elements:
146 * <ul>
147 * <li> After creation and whenever zero_out_ghost_values() is called (or
148 * <code>operator= (0.)</code>), the vector does only allow writing into
149 * ghost elements but not reading from ghost elements.
150 * <li> After a call to update_ghost_values(), the vector does not allow
151 * writing into ghost elements but only reading from them. This is to
152 * avoid undesired ghost data artifacts when calling compress() after
153 * modifying some vector entries. The current status of the ghost entries
154 * (read mode or write mode) can be queried by the method
155 * has_ghost_elements(), which returns <code>true</code> exactly when
156 * ghost elements have been updated and <code>false</code> otherwise,
157 * irrespective of the actual number of ghost entries in the vector layout
158 * (for that information, use
159 * <code>get_partitioner()->n_ghost_indices()</code> instead).
160 * </ul>
161 *
162 * This vector uses the facilities of the class dealii::Vector<Number> for
163 * implementing the operations on the local range of the vector. In
164 * particular, it also inherits thread parallelism that splits most
165 * vector-vector operations into smaller chunks if the program uses
166 * multiple threads. This may or may not be desired when working also with
167 * MPI.
168 *
169 * <h4>Limitations regarding the vector size</h4>
170 *
171 * This vector class is based on two different number types for indexing.
172 * The so-called global index type encodes the overall size of the vector.
173 * Its type is types::global_dof_index. The largest possible value is
174 * <code>2^32-1</code> or approximately 4 billion in case 64 bit integers
175 * are disabled at configuration of deal.II (default case) or
176 * <code>2^64-1</code> or approximately <code>10^19</code> if 64 bit
177 * integers are enabled (see the glossary entry on
178 * @ref GlobalDoFIndex
179 * for further information).
180 *
181 * The second relevant index type is the local index used within one MPI
182 * rank. As opposed to the global index, the implementation assumes 32-bit
183 * unsigned integers unconditionally. In other words, to actually use a
184 * vector with more than four billion entries, you need to use MPI with
185 * more than one rank (which in general is a safe assumption since four
186 * billion entries consume at least 16 GB of memory for floats or 32 GB of
187 * memory for doubles) and enable 64-bit indices. If more than 4 billion
188 * local elements are present, the implementation tries to detect that,
189 * which triggers an exception and aborts the code. Note, however, that
190 * the detection of overflow is tricky and the detection mechanism might
191 * fail in some circumstances. Therefore, it is strongly recommended to
192 * not rely on this class to automatically detect the unsupported case.
193 *
194 * <h4>GPU support</h4>
195 *
196 * This vector class supports two different memory spaces: Host and Default.
197 * If the MemorySpace template argument is not specified, the memory space
198 * is Host and all the data is allocated on the CPU. When the memory space
199 * is Default, all the data is allocated on Kokkos' default memory space.
200 * That means that if Kokkos was configured with a GPU backend, the data is
201 * allocated on a GPU. The operations on the vector are performed on the
202 * chosen memory space. From the host, there are two methods to access the
203 * elements of the Vector when using the Default memory space:
204 * <ul>
205 * <li> use get_values():
206 * @code
207 * Vector<double, MemorySpace::Default> vector(local_range, comm);
208 * double* vector_dev = vector.get_values();
209 * const int n_local_elements = local_range.n_elements();
210 * std::vector<double> vector_host(n_local_elements, 1.);
211 * Kokkos::deep_copy(Kokkos::View<double, Kokkos::HostSpace>(
212 * vector_host.data(), n_local_elements),
213 * Kokkos::View<double,
214 * MemorySpace::Default::kokkos_space>( vector_dev, n_local_elements));
215 * @endcode
216 * <li> use import_elements():
217 * @code
218 * Vector<double, MemorySpace::Default> vector(local_range, comm);
219 * ReadWriteVector<double> rw_vector(local_range);
220 * for (auto & val : rw_vector)
221 * val = 1.;
222 * vector.import_elements(rw_vector, VectorOperations::insert);
223 * @endcode
224 * </ul>
225 * The import method is a lot safer and will perform an MPI communication if
226 * necessary. Since an MPI communication may be performed, import needs to
227 * be called on all the processors.
228 *
229 * @note By default, the GPU @ref GlossDevice "device" id is chosen in a round-robin fashion
230 * according to the local MPI rank id. To choose a different @ref GlossDevice "device", Kokkos
231 * has to be initialized explicitly providing the respective device id
232 * explicitly.
233 *
234 * <h4>MPI-3 shared-memory support</h4>
235 *
236 * In Host mode, this class allows to use MPI-3 shared-memory features
237 * by providing a separate MPI communicator that consists of processes on
238 * the same shared-memory domain. By calling
239 * `vector.shared_vector_data();`,
240 * users have read-only access to both locally-owned and ghost values of
241 * processes combined in the shared-memory communicator (@p comm_sm in
242 * reinit()).
243 *
244 * For this to work, you have to call the constructor or one of the reinit()
245 * functions of this class with a non-default value for the `comm_sm`
246 * argument, where the argument corresponds to a communicator consisting of
247 * all processes on the same shared-memory domain. This kind of communicator
248 * can be created using the following code snippet:
249 * @code
250 * MPI_Comm comm_sm;
251 * MPI_Comm_split_type(comm, MPI_COMM_TYPE_SHARED, rank, MPI_INFO_NULL,
252 * &comm_sm);
253 * @endcode
254 */
255 template <typename Number, typename MemorySpace = MemorySpace::Host>
256 class Vector : public ::dealii::ReadVector<Number>
257 {
258 public:
259 using memory_space = MemorySpace;
260 using value_type = Number;
261 using pointer = value_type *;
262 using const_pointer = const value_type *;
263 using iterator = value_type *;
264 using const_iterator = const value_type *;
265 using reference = value_type &;
266 using const_reference = const value_type &;
267 using size_type = types::global_dof_index;
268 using real_type = typename numbers::NumberTraits<Number>::real_type;
269
270 static_assert(
271 std::is_same_v<MemorySpace, ::dealii::MemorySpace::Host> ||
272 std::is_same_v<MemorySpace, ::dealii::MemorySpace::Default>,
273 "MemorySpace should be Host or Default");
274
275 static_assert(
276 (!std::is_same_v<MemorySpace, ::dealii::MemorySpace::Default>) ||
277 std::is_same_v<Number, float> || std::is_same_v<Number, double>,
278 "Number should be float or double for Default memory space");
279
280 /**
281 * @name 1: Basic Object-handling
282 */
283 /** @{ */
284 /**
285 * Empty constructor.
286 */
287 Vector();
288
289 /**
290 * Copy constructor. Uses the parallel partitioning of @p in_vector.
291 * It should be noted that this constructor automatically sets ghost
292 * values to zero. Call @p update_ghost_values() directly following
293 * construction if a ghosted vector is required.
294 */
295 Vector(const Vector<Number, MemorySpace> &in_vector);
296
297 /**
298 * Move constructor. Uses the swap method.
299 *
300 * @note In order for this constructor to leave the moved-from object in a
301 * valid state it must allocate memory (in this case, an empty
302 * partitioner) - hence it cannot be marked as noexcept.
303 */
304 Vector(Vector<Number, MemorySpace> &&in_vector); // NOLINT
305
306 /**
307 * Construct a parallel vector of the given global size without any
308 * actual parallel distribution.
309 */
310 Vector(const size_type size);
311
312 /**
313 * Construct a parallel vector. The local range is specified by @p
314 * locally_owned_set (note that this must be a contiguous interval,
315 * multiple intervals are not possible). The IndexSet @p ghost_indices
316 * specifies ghost indices, i.e., indices which one might need to read
317 * data from or accumulate data from. It is allowed that the set of
318 * ghost indices also contains the local range, but it does not need to.
319 *
320 * This function involves global communication, so it should only be
321 * called once for a given layout. Use the constructor with
322 * Vector<Number> argument to create additional vectors with the same
323 * parallel layout.
324 *
325 * @see
326 * @ref GlossGhostedVector "vectors with ghost elements"
327 */
328 Vector(const IndexSet &local_range,
329 const IndexSet &ghost_indices,
330 const MPI_Comm communicator);
331
332 /**
333 * Same constructor as above but without any ghost indices.
334 */
335 Vector(const IndexSet &local_range, const MPI_Comm communicator);
336
337 /**
338 * Create the vector based on the parallel partitioning described in @p
339 * partitioner. The input argument is a shared pointer, which stores the
340 * partitioner data only once and share it between several vectors with
341 * the same layout.
342 */
343 Vector(
344 const std::shared_ptr<const Utilities::MPI::Partitioner> &partitioner);
345
346 /**
347 * Destructor.
348 */
349 ~Vector();
350
351 /**
352 * Set the global size of the vector to @p size without any actual
353 * parallel distribution.
354 */
355 void
356 reinit(const size_type size, const bool omit_zeroing_entries = false);
357
358 /**
359 * Uses the parallel layout of the input vector @p in_vector and
360 * allocates memory for this vector. Recommended initialization function
361 * when several vectors with the same layout should be created.
362 *
363 * If the flag @p omit_zeroing_entries is set to false, the memory will
364 * be initialized with zero, otherwise the memory will be untouched (and
365 * the user must make sure to fill it with reasonable data before using
366 * it).
367 */
368 template <typename Number2>
369 void
370 reinit(const Vector<Number2, MemorySpace> &in_vector,
371 const bool omit_zeroing_entries = false);
372
373 /**
374 * Initialize the vector. The local range is specified by @p local_range
375 * (note that this must be a contiguous interval, multiple intervals are
376 * not possible). The IndexSet @p ghost_indices specifies ghost indices,
377 * i.e., indices which one might need to read data from or accumulate data
378 * from. It is allowed that the set of ghost indices also contains the
379 * local range, but it does not need to.
380 *
381 * This function involves global communication, so it should only be
382 * called once for a given layout. Use the @p reinit function with
383 * Vector<Number> argument to create additional vectors with the same
384 * parallel layout.
385 *
386 * @see
387 * @ref GlossGhostedVector "vectors with ghost elements"
388 */
389 void
390 reinit(const IndexSet &local_range,
391 const IndexSet &ghost_indices,
392 const MPI_Comm communicator);
393
394 /**
395 * Same as above, but without ghost entries.
396 */
397 void
398 reinit(const IndexSet &local_range, const MPI_Comm communicator);
399
400 /**
401 * Initialize the vector given to the parallel partitioning described in
402 * @p partitioner. The input argument is a shared pointer, which stores
403 * the partitioner data only once and can be shared between several
404 * vectors with the same layout.
405 *
406 * The optional argument @p comm_sm, which consists of processes on
407 * the same shared-memory domain, allows users have read-only access to
408 * both locally-owned and ghost values of processes combined in the
409 * shared-memory communicator. See the general documentation of this class
410 * for more information about this argument.
411 */
412 void
413 reinit(
414 const std::shared_ptr<const Utilities::MPI::Partitioner> &partitioner,
415 const MPI_Comm comm_sm = MPI_COMM_SELF);
416
417 /**
418 * This function exists purely for reasons of compatibility with the
419 * PETScWrappers::MPI::Vector and TrilinosWrappers::MPI::Vector classes.
420 *
421 * It calls the function above, and ignores the parameter @p make_ghosted.
422 */
423 void
424 reinit(
425 const std::shared_ptr<const Utilities::MPI::Partitioner> &partitioner,
426 const bool make_ghosted,
427 const MPI_Comm &comm_sm = MPI_COMM_SELF);
428
429 /**
430 * Initialize vector with @p local_size locally-owned and @p ghost_size
431 * ghost degrees of freedoms.
432 *
433 * The optional argument @p comm_sm, which consists of processes on
434 * the same shared-memory domain, allows users have read-only access to
435 * both locally-owned and ghost values of processes combined in the
436 * shared-memory communicator. See the general documentation of this class
437 * for more information about this argument.
438 *
439 * @note In the created underlying partitioner, the local index range is
440 * translated to global indices in an ascending and one-to-one fashion,
441 * i.e., the indices of process $p$ sit exactly between the indices of
442 * the processes $p-1$ and $p+1$, respectively. Setting the
443 * @p ghost_size variable to an appropriate value provides memory space
444 * for the ghost data in a vector's memory allocation as and allows
445 * access to it via local_element(). However, the associated global
446 * indices must be handled externally in this case.
447 */
448 void
449 reinit(const types::global_dof_index local_size,
450 const types::global_dof_index ghost_size,
451 const MPI_Comm comm,
452 const MPI_Comm comm_sm = MPI_COMM_SELF);
453
454 /**
455 * Swap the contents of this vector and the other vector @p v. One could
456 * do this operation with a temporary variable and copying over the data
457 * elements, but this function is significantly more efficient since it
458 * only swaps the pointers to the data of the two vectors and therefore
459 * does not need to allocate temporary storage and move data around.
460 *
461 * This function is analogous to the @p swap function of all C++
462 * standard containers. Also, there is a global function
463 * <tt>swap(u,v)</tt> that simply calls <tt>u.swap(v)</tt>, again in
464 * analogy to standard functions.
465 */
466 void
467 swap(Vector<Number, MemorySpace> &v) noexcept;
468
469 /**
470 * Move assignment operator.
471 *
472 * @note This method may throw an exception (should an MPI check fail) and
473 * is consequently not `noexcept`.
474 */
475 Vector<Number, MemorySpace> &
476 operator=(Vector<Number, MemorySpace> &&in_vector); // NOLINT
477
478 /**
479 * Assigns the vector to the parallel partitioning of the input vector
480 * @p in_vector, and copies all the data.
481 *
482 * The semantics of this operator are complex. If the two vectors have
483 * the same size, and
484 * if either the left or right hand side vector of the assignment (i.e.,
485 * either the input vector on the right hand side, or the calling vector
486 * to the left of the assignment operator) currently has ghost elements,
487 * then the left hand side vector will also have ghost values and will
488 * consequently be a read-only vector (see also the
489 * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the
490 * left hand vector will be a writable vector after this operation.
491 * These semantics facilitate having a vector with ghost elements on the
492 * left hand side of the assignment, and a vector without ghost elements
493 * on the right hand side, with the resulting left hand side vector
494 * having the correct values in both its locally owned and its ghost
495 * elements.
496 *
497 * On the other hand, if the left hand side vector does not have the
498 * correct size yet, or is perhaps an entirely uninitialized vector,
499 * then the assignment is simply a copy operation in the usual sense:
500 * In that case, if the right hand side has no ghost elements (i.e.,
501 * is a completely distributed vector), then the left hand side will
502 * have no ghost elements either. And if the right hand side has
503 * ghost elements (and is consequently read-only), then the left
504 * hand side will have these same properties after the operation.
505 */
506 Vector<Number, MemorySpace> &
507 operator=(const Vector<Number, MemorySpace> &in_vector);
508
509 /**
510 * Assigns the vector to the parallel partitioning of the input vector
511 * @p in_vector, and copies all the data.
512 *
513 * If one of the input vector or the calling vector (to the left of the
514 * assignment operator) had ghost elements set before this operation,
515 * the calling vector will have ghost values set. Otherwise, it will be
516 * in write mode. If the input vector does not have any ghost elements
517 * at all, the vector will also update its ghost values in analogy to
518 * the respective setting the Trilinos and PETSc vectors.
519 */
520 template <typename Number2>
521 Vector<Number, MemorySpace> &
522 operator=(const Vector<Number2, MemorySpace> &in_vector);
523
524 /** @} */
525
526 /**
527 * @name 2: Parallel data exchange
528 */
529 /** @{ */
530 /**
531 * This function copies the data that has accumulated in the data buffer
532 * for ghost indices to the owning processor. For the meaning of the
533 * argument @p operation, see the entry on
534 * @ref GlossCompress "Compressing distributed vectors and matrices"
535 * in the glossary.
536 *
537 * There are four variants for this function. If called with argument @p
538 * VectorOperation::add adds all the data accumulated in ghost elements
539 * to the respective elements on the owning processor and clears the
540 * ghost array afterwards. If called with argument @p
541 * VectorOperation::insert, a set operation is performed. Since setting
542 * elements in a vector with ghost elements is ambiguous (as one can set
543 * both the element on the ghost site as well as the owning site), this
544 * operation makes the assumption that all data is set correctly on the
545 * owning processor. Upon call of compress(VectorOperation::insert), all
546 * ghost entries are thus simply zeroed out (using zero_ghost_values()).
547 * In debug mode, a check is performed for whether the data set is
548 * actually consistent between processors, i.e., whenever a non-zero
549 * ghost element is found, it is compared to the value on the owning
550 * processor and an exception is thrown if these elements do not agree.
551 * If called with VectorOperation::min or VectorOperation::max, the
552 * minimum or maximum on all elements across the processors is set.
553 * @note This vector class has a fixed set of ghost entries attached to
554 * the local representation. As a consequence, all ghost entries are
555 * assumed to be valid and will be exchanged unconditionally according
556 * to the given VectorOperation. Make sure to initialize all ghost
557 * entries with the neutral element of the given VectorOperation or
558 * touch all ghost entries. The neutral element is zero for
559 * VectorOperation::add and VectorOperation::insert, `+inf` for
560 * VectorOperation::min, and `-inf` for VectorOperation::max. If all
561 * values are initialized with values below zero and compress is called
562 * with VectorOperation::max two times subsequently, the maximal value
563 * after the second calculation will be zero.
564 */
565 void
566 compress(VectorOperation::values operation);
567
568 /**
569 * Fills the data field for ghost indices with the values stored in the
570 * respective positions of the owning processor. This function is needed
571 * before reading from ghosts. The function is @p const even though
572 * ghost data is changed. This is needed to allow functions with a @p
573 * const vector to perform the data exchange without creating
574 * temporaries.
575 *
576 * After calling this method, write access to ghost elements of the
577 * vector is forbidden and an exception is thrown. Only read access to
578 * ghost elements is allowed in this state. Note that all subsequent
579 * operations on this vector, like global vector addition, etc., will
580 * also update the ghost values by a call to this method after the
581 * operation. However, global reduction operations like norms or the
582 * inner product will always ignore ghost elements in order to avoid
583 * counting the ghost data more than once. To allow writing to ghost
584 * elements again, call zero_out_ghost_values().
585 *
586 * @see
587 * @ref GlossGhostedVector "vectors with ghost elements"
588 */
589 void
590 update_ghost_values() const;
591
592 /**
593 * Initiates communication for the @p compress() function with
594 * non-blocking communication. This function does not wait for the
595 * transfer to finish, in order to allow for other computations during the
596 * time it takes until all data arrives.
597 *
598 * Before the data is actually exchanged, the function must be followed
599 * by a call to @p compress_finish().
600 *
601 * In case this function is called for more than one vector before @p
602 * compress_finish() is invoked, it is mandatory to specify a unique
603 * communication channel to each such call, in order to avoid several
604 * messages with the same ID that will corrupt this operation. Any
605 * communication channel less than 100 is a valid value (in particular,
606 * the range $[100, 200)$ is reserved for
607 * LinearAlgebra::distributed::BlockVector).
608 */
609 void
610 compress_start(const unsigned int communication_channel = 0,
611 VectorOperation::values operation = VectorOperation::add);
612
613 /**
614 * For all requests that have been initiated in compress_start, wait for
615 * the communication to finish. Once it is finished, add or set the data
616 * (depending on the flag operation) to the respective positions in the
617 * owning processor, and clear the contents in the ghost data fields.
618 * The meaning of this argument is the same as in compress().
619 *
620 * This function should be called exactly once per vector after calling
621 * compress_start, otherwise the result is undefined. In particular, it
622 * is not well-defined to call compress_start on the same vector again
623 * before compress_finished has been called. However, there is no
624 * warning to prevent this situation.
625 *
626 * Must follow a call to the @p compress_start function.
627 *
628 * When the MemorySpace is Default and MPI is not GPU-aware, data changed
629 * on the @ref GlossDevice "device" after the call to compress_start will be lost.
630 */
631 void
632 compress_finish(VectorOperation::values operation);
633
634 /**
635 * Initiates communication for the @p update_ghost_values() function
636 * with non-blocking communication. This function does not wait for the
637 * transfer to finish, in order to allow for other computations during
638 * the time it takes until all data arrives.
639 *
640 * Before the data is actually exchanged, the function must be followed
641 * by a call to @p update_ghost_values_finish().
642 *
643 * In case this function is called for more than one vector before @p
644 * update_ghost_values_finish() is invoked, it is mandatory to specify a
645 * unique communication channel to each such call, in order to avoid
646 * several messages with the same ID that will corrupt this operation.
647 * Any communication channel less than 100 is a valid value (in
648 * particular, the range $[100, 200)$ is reserved for
649 * LinearAlgebra::distributed::BlockVector).
650 */
651 void
652 update_ghost_values_start(
653 const unsigned int communication_channel = 0) const;
654
655
656 /**
657 * For all requests that have been started in update_ghost_values_start,
658 * wait for the communication to finish.
659 *
660 * Must follow a call to the @p update_ghost_values_start function
661 * before reading data from ghost indices.
662 */
663 void
664 update_ghost_values_finish() const;
665
666 /**
667 * This method zeros the entries on ghost dofs, but does not touch
668 * locally owned DoFs.
669 *
670 * After calling this method, read access to ghost elements of the
671 * vector is forbidden and an exception is thrown. Only write access to
672 * ghost elements is allowed in this state.
673 */
674 void
675 zero_out_ghost_values() const;
676
677 /**
678 * Return whether the vector currently is in a state where ghost values
679 * can be read or not. This is the same functionality as other parallel
680 * vectors have. If this method returns false, this only means that
681 * read-access to ghost elements is prohibited whereas write access is
682 * still possible (to those entries specified as ghosts during
683 * initialization), not that there are no ghost elements at all.
684 *
685 * @see
686 * @ref GlossGhostedVector "vectors with ghost elements"
687 */
688 bool
689 has_ghost_elements() const;
690
691 /**
692 * This method copies the data in the locally owned range from another
693 * distributed vector @p src into the calling vector. As opposed to
694 * operator= that also includes ghost entries, this operation ignores
695 * the ghost range. The only prerequisite is that the local range on the
696 * calling vector and the given vector @p src are the same on all
697 * processors. It is explicitly allowed that the two vectors have
698 * different ghost elements that might or might not be related to each
699 * other.
700 *
701 * Since no data exchange is performed, make sure that neither @p src
702 * nor the calling vector have pending communications in order to obtain
703 * correct results.
704 */
705 template <typename Number2>
706 void
707 copy_locally_owned_data_from(const Vector<Number2, MemorySpace> &src);
708
709 /**
710 * Import all the elements present in the distributed vector @p src.
711 * VectorOperation::values @p operation is used to decide if the elements
712 * in @p V should be added to the current vector or replace the current
713 * elements. The main purpose of this function is to get data from one
714 * memory space, e.g. Default, to the other, e.g. the Host.
715 *
716 * @note The partitioners of the two distributed vectors need to be the
717 * same as no MPI communication is performed.
718 */
719 template <typename MemorySpace2>
720 void
721 import_elements(const Vector<Number, MemorySpace2> &src,
722 VectorOperation::values operation);
723
724 /**
725 * @deprecated Use import_elements() instead.
726 */
727 template <typename MemorySpace2>
728 DEAL_II_DEPRECATED void
729 import(const Vector<Number, MemorySpace2> &src,
730 VectorOperation::values operation)
731 {
732 import_elements(src, operation);
733 }
734
735 /** @} */
736
737 /**
738 * @name 3: Implementation of vector space operations
739 */
740 /** @{ */
741
742 /**
743 * Multiply the entire vector by a fixed factor.
744 */
745 Vector<Number, MemorySpace> &
746 operator*=(const Number factor);
747
748 /**
749 * Divide the entire vector by a fixed factor.
750 */
751 Vector<Number, MemorySpace> &
752 operator/=(const Number factor);
753
754 /**
755 * Add the vector @p V to the present one.
756 */
757 Vector<Number, MemorySpace> &
758 operator+=(const Vector<Number, MemorySpace> &V);
759
760 /**
761 * Subtract the vector @p V from the present one.
762 */
763 Vector<Number, MemorySpace> &
764 operator-=(const Vector<Number, MemorySpace> &V);
765
766 /**
767 * Import all the elements present in the vector's IndexSet from the input
768 * vector @p V. VectorOperation::values @p operation is used to decide if
769 * the elements in @p V should be added to the current vector or replace the
770 * current elements. The last parameter can be used if the same
771 * communication pattern is used multiple times. This can be used to
772 * improve performance.
773 *
774 * @note If the MemorySpace is Default, the data in the ReadWriteVector will
775 * be moved to the @ref GlossDevice "device".
776 */
777 void
778 import_elements(
779 const LinearAlgebra::ReadWriteVector<Number> &V,
780 const VectorOperation::values operation,
781 const std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
782 &communication_pattern = {});
783
784 /**
785 * @deprecated Use import_elements() instead.
786 */
787 DEAL_II_DEPRECATED void
788 import(const LinearAlgebra::ReadWriteVector<Number> &V,
789 VectorOperation::values operation,
790 std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
791 communication_pattern = {})
792 {
793 import_elements(V, operation, communication_pattern);
794 }
795
796 /**
797 * Return the scalar product of two vectors.
798 */
799 Number
800 operator*(const Vector<Number, MemorySpace> &V) const;
801
802 /**
803 * Add @p a to all components. Note that @p a is a scalar not a vector.
804 */
805 void
806 add(const Number a);
807
808 /**
809 * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>.
810 */
811 void
812 add(const Number a, const Vector<Number, MemorySpace> &V);
813
814 /**
815 * Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>.
816 */
817 void
818 add(const Number a,
819 const Vector<Number, MemorySpace> &V,
820 const Number b,
821 const Vector<Number, MemorySpace> &W);
822
823 /**
824 * A collective add operation: This function adds a whole set of values
825 * stored in @p values to the vector components specified by @p indices.
826 */
827 void
828 add(const std::vector<size_type> &indices,
829 const std::vector<Number> &values);
830
831 /**
832 * Scaling and simple addition of a multiple of a vector, i.e. <tt>*this =
833 * s*(*this)+a*V</tt>.
834 */
835 void
836 sadd(const Number s,
837 const Number a,
838 const Vector<Number, MemorySpace> &V);
839
840 /**
841 * Scale each element of this vector by the corresponding element in the
842 * argument. This function is mostly meant to simulate multiplication (and
843 * immediate re-assignment) by a diagonal scaling matrix.
844 */
845 void
846 scale(const Vector<Number, MemorySpace> &scaling_factors);
847
848 /**
849 * Assignment <tt>*this = a*V</tt>.
850 */
851 void
852 equ(const Number a, const Vector<Number, MemorySpace> &V);
853
854 /**
855 * Return the l<sub>1</sub> norm of the vector (i.e., the sum of the
856 * absolute values of all entries among all processors).
857 */
858 real_type
859 l1_norm() const;
860
861 /**
862 * Return the $l_2$ norm of the vector (i.e., the square root of
863 * the sum of the square of all entries among all processors).
864 */
865 real_type
866 l2_norm() const;
867
868 /**
869 * Return the square of the $l_2$ norm of the vector.
870 */
871 real_type
872 norm_sqr() const;
873
874 /**
875 * Return the maximum norm of the vector (i.e., the maximum absolute value
876 * among all entries and among all processors).
877 */
878 real_type
879 linfty_norm() const;
880
881 /**
882 * Perform a combined operation of a vector addition and a subsequent
883 * inner product, returning the value of the inner product. In other
884 * words, the result of this function is the same as if the user called
885 * @code
886 * this->add(a, V);
887 * return_value = *this * W;
888 * @endcode
889 *
890 * The reason this function exists is that this operation involves less
891 * memory transfer than calling the two functions separately. This method
892 * only needs to load three vectors, @p this, @p V, @p W, whereas calling
893 * separate methods means to load the calling vector @p this twice. Since
894 * most vector operations are memory transfer limited, this reduces the
895 * time by 25\% (or 50\% if @p W equals @p this).
896 *
897 * For complex-valued vectors, the scalar product in the second step is
898 * implemented as
899 * $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
900 */
901 Number
902 add_and_dot(const Number a,
903 const Vector<Number, MemorySpace> &V,
904 const Vector<Number, MemorySpace> &W);
905
906 /**
907 * Return the global size of the vector, equal to the sum of the number of
908 * locally owned indices among all processors.
909 */
910 virtual size_type
911 size() const override;
912
913 /**
914 * Return an index set that describes which elements of this vector are
915 * owned by the current processor. As a consequence, the index sets
916 * returned on different processors if this is a distributed vector will
917 * form disjoint sets that add up to the complete index set. Obviously, if
918 * a vector is created on only one processor, then the result would
919 * satisfy
920 * @code
921 * vec.locally_owned_elements() == complete_index_set(vec.size())
922 * @endcode
923 */
924 dealii::IndexSet
925 locally_owned_elements() const;
926
927 /**
928 * Print the vector to the output stream @p out.
929 */
930 void
931 print(std::ostream &out,
932 const unsigned int precision = 3,
933 const bool scientific = true,
934 const bool across = true) const;
935
936 /**
937 * Return the memory consumption of this class in bytes.
938 */
939 std::size_t
940 memory_consumption() const;
941 /** @} */
942
943 /**
944 * @name 4: Other vector operations
945 */
946 /** @{ */
947
948 /**
949 * Sets all elements of the vector to the scalar @p s. If the scalar is
950 * zero, also ghost elements are set to zero, otherwise they remain
951 * unchanged.
952 */
953 Vector<Number, MemorySpace> &
954 operator=(const Number s);
955
956 /**
957 * This is a collective add operation that adds a whole set of values
958 * stored in @p values to the vector components specified by @p indices.
959 */
960 template <typename OtherNumber>
961 void
962 add(const std::vector<size_type> &indices,
963 const ::dealii::Vector<OtherNumber> &values);
964
965 /**
966 * Take an address where n_elements are stored contiguously and add them
967 * into the vector.
968 */
969 template <typename OtherNumber>
970 void
971 add(const size_type n_elements,
972 const size_type *indices,
973 const OtherNumber *values);
974
975 /**
976 * Scaling and simple vector addition, i.e. <tt>*this =
977 * s*(*this)+V</tt>.
978 */
979 void
980 sadd(const Number s, const Vector<Number, MemorySpace> &V);
981
982 /** @} */
983
984
985 /**
986 * @name 5: Entry access and local data representation
987 */
988 /** @{ */
989
990 /**
991 * Return the local size of the vector, i.e., the number of indices
992 * owned locally.
993 */
994 size_type
995 locally_owned_size() const;
996
997 /**
998 * Return true if the given global index is in the local range of this
999 * processor.
1000 */
1001 bool
1002 in_local_range(const size_type global_index) const;
1003
1004 /**
1005 * Make the @p Vector class a bit like the <tt>vector<></tt> class of
1006 * the C++ standard library by returning iterators to the start and end
1007 * of the <i>locally owned</i> elements of this vector.
1008 *
1009 * It holds that end() - begin() == locally_owned_size().
1010 *
1011 * @note For the Default memory space, the iterator might point to memory
1012 * on the @ref GlossDevice "device".
1013 */
1014 iterator
1015 begin();
1016
1017 /**
1018 * Return constant iterator to the start of the locally owned elements
1019 * of the vector.
1020 *
1021 * @note For the Default memory space, the iterator might point to memory
1022 * on the @ref GlossDevice "device".
1023 */
1024 const_iterator
1025 begin() const;
1026
1027 /**
1028 * Return an iterator pointing to the element past the end of the array
1029 * of locally owned entries.
1030 *
1031 * @note For the Default memory space, the iterator might point to memory
1032 * on the @ref GlossDevice "device".
1033 */
1034 iterator
1035 end();
1036
1037 /**
1038 * Return a constant iterator pointing to the element past the end of
1039 * the array of the locally owned entries.
1040 *
1041 * @note For the Default memory space, the iterator might point to memory
1042 * on the @ref GlossDevice "device".
1043 */
1044 const_iterator
1045 end() const;
1046
1047 /**
1048 * Read access to the data in the position corresponding to @p
1049 * global_index. The index must be either in the local range of the
1050 * vector or be specified as a ghost index at construction.
1051 *
1052 * Performance: <tt>O(1)</tt> for locally owned elements that represent
1053 * a contiguous range and <tt>O(log(n<sub>ranges</sub>))</tt> for ghost
1054 * elements (quite fast, but slower than local_element()).
1055 */
1056 Number
1057 operator()(const size_type global_index) const;
1058
1059 /**
1060 * Read and write access to the data in the position corresponding to @p
1061 * global_index. The index must be either in the local range of the
1062 * vector or be specified as a ghost index at construction.
1063 *
1064 * Performance: <tt>O(1)</tt> for locally owned elements that represent
1065 * a contiguous range and <tt>O(log(n<sub>ranges</sub>))</tt> for ghost
1066 * elements (quite fast, but slower than local_element()).
1067 */
1068 Number &
1069 operator()(const size_type global_index);
1070
1071 /**
1072 * Read access to the data in the position corresponding to @p
1073 * global_index. The index must be either in the local range of the
1074 * vector or be specified as a ghost index at construction.
1075 *
1076 * This function does the same thing as operator().
1077 */
1078 Number
1079 operator[](const size_type global_index) const;
1080 /**
1081 * Read and write access to the data in the position corresponding to @p
1082 * global_index. The index must be either in the local range of the
1083 * vector or be specified as a ghost index at construction.
1084 *
1085 * This function does the same thing as operator().
1086 */
1087 Number &
1088 operator[](const size_type global_index);
1089
1090 /**
1091 * Read access to the data field specified by @p local_index. Locally
1092 * owned indices can be accessed with indices
1093 * <code>[0,locally_owned_size)</code>, and ghost indices with indices
1094 * <code>[locally_owned_size,locally_owned_size+get_partitioner()->n_ghost_indices()]</code>.
1095 *
1096 * Performance: Direct array access (fast).
1097 */
1098 Number
1099 local_element(const size_type local_index) const;
1100
1101 /**
1102 * Read and write access to the data field specified by @p local_index.
1103 * Locally owned indices can be accessed with indices
1104 * <code>[0,locally_owned_size())</code>, and ghost indices with indices
1105 * <code>[locally_owned_size(), locally_owned_size()+n_ghosts]</code>.
1106 *
1107 * Performance: Direct array access (fast).
1108 */
1109 Number &
1110 local_element(const size_type local_index);
1111
1112 /**
1113 * Return the pointer to the underlying raw array.
1114 *
1115 * @note For the Default memory space, the pointer might point to memory
1116 * on the @ref GlossDevice "device".
1117 */
1118 Number *
1119 get_values() const;
1120
1121 /**
1122 * Instead of getting individual elements of a vector via operator(),
1123 * this function allows getting a whole set of elements at once. The
1124 * indices of the elements to be read are stated in the first argument,
1125 * the corresponding values are returned in the second.
1126 *
1127 * If the current vector is called @p v, then this function is the equivalent
1128 * to the code
1129 * @code
1130 * for (unsigned int i=0; i<indices.size(); ++i)
1131 * values[i] = v[indices[i]];
1132 * @endcode
1133 *
1134 * @pre The sizes of the @p indices and @p values arrays must be identical.
1135 *
1136 * @note This function is not implemented for Default memory space.
1137 */
1138 template <typename OtherNumber>
1139 void
1140 extract_subvector_to(const std::vector<size_type> &indices,
1141 std::vector<OtherNumber> &values) const;
1142
1143 /**
1144 * Extract a range of elements all at once.
1145 */
1146 virtual void
1147 extract_subvector_to(
1148 const ArrayView<const types::global_dof_index> &indices,
1149 const ArrayView<Number> &elements) const override;
1150
1151 /**
1152 * Instead of getting individual elements of a vector via operator(),
1153 * this function allows getting a whole set of elements at once. In
1154 * contrast to the previous function, this function obtains the
1155 * indices of the elements by dereferencing all elements of the iterator
1156 * range provided by the first two arguments, and puts the vector
1157 * values into memory locations obtained by dereferencing a range
1158 * of iterators starting at the location pointed to by the third
1159 * argument.
1160 *
1161 * If the current vector is called @p v, then this function is the equivalent
1162 * to the code
1163 * @code
1164 * ForwardIterator indices_p = indices_begin;
1165 * OutputIterator values_p = values_begin;
1166 * while (indices_p != indices_end)
1167 * {
1168 * *values_p = v[*indices_p];
1169 * ++indices_p;
1170 * ++values_p;
1171 * }
1172 * @endcode
1173 *
1174 * @pre It must be possible to write into as many memory locations
1175 * starting at @p values_begin as there are iterators between
1176 * @p indices_begin and @p indices_end.
1177 */
1178 template <typename ForwardIterator, typename OutputIterator>
1179 void
1180 extract_subvector_to(ForwardIterator indices_begin,
1181 const ForwardIterator indices_end,
1182 OutputIterator values_begin) const;
1183 /**
1184 * Return whether the vector contains only elements with value zero.
1185 * This is a @ref GlossCollectiveOperation "collective operation". This function is expensive, because
1186 * potentially all elements have to be checked.
1187 */
1188 bool
1189 all_zero() const;
1190
1191 /**
1192 * Compute the mean value of all the entries in the vector.
1193 */
1194 Number
1195 mean_value() const;
1196
1197 /**
1198 * $l_p$-norm of the vector. The pth root of the sum of the pth powers
1199 * of the absolute values of the elements.
1200 */
1201 real_type
1202 lp_norm(const real_type p) const;
1203 /** @} */
1204
1205 /**
1206 * @name 6: Mixed stuff
1207 */
1208 /** @{ */
1209
1210 /**
1211 * Return the underlying MPI communicator.
1212 */
1213 MPI_Comm
1214 get_mpi_communicator() const;
1215
1216 /**
1217 * Return the MPI partitioner that describes the parallel layout of the
1218 * vector. This object can be used to initialize another vector with the
1219 * respective reinit() call, for additional queries regarding the
1220 * parallel communication, or the compatibility of partitioners.
1221 */
1222 const std::shared_ptr<const Utilities::MPI::Partitioner> &
1223 get_partitioner() const;
1224
1225 /**
1226 * Check whether the given partitioner is compatible with the
1227 * partitioner used for this vector. Two partitioners are compatible if
1228 * they have the same local size and the same ghost indices. They do not
1229 * necessarily need to be the same data field of the shared pointer.
1230 * This is a local operation only, i.e., if only some processors decide
1231 * that the partitioning is not compatible, only these processors will
1232 * return @p false, whereas the other processors will return @p true.
1233 */
1234 bool
1235 partitioners_are_compatible(
1236 const Utilities::MPI::Partitioner &part) const;
1237
1238 /**
1239 * Check whether the given partitioner is compatible with the
1240 * partitioner used for this vector. Two partitioners are compatible if
1241 * they have the same local size and the same ghost indices. They do not
1242 * necessarily need to be the same data field. As opposed to
1243 * partitioners_are_compatible(), this method checks for compatibility
1244 * among all processors and the method only returns @p true if the
1245 * partitioner is the same on all processors.
1246 *
1247 * This method performs global communication, so make sure to use it
1248 * only in a context where all processors call it the same number of
1249 * times.
1250 */
1251 bool
1252 partitioners_are_globally_compatible(
1253 const Utilities::MPI::Partitioner &part) const;
1254
1255 /**
1256 * Change the ghost state of this vector to @p ghosted.
1257 */
1258 void
1259 set_ghost_state(const bool ghosted) const;
1260
1261 /**
1262 * Get pointers to the beginning of the values of the other
1263 * processes of the same shared-memory domain.
1264 */
1265 const std::vector<ArrayView<const Number>> &
1266 shared_vector_data() const;
1267
1268 /** @} */
1269
1270 /**
1271 * Attempt to perform an operation between two incompatible vector types.
1272 *
1273 * @ingroup Exceptions
1274 */
1275 DeclException0(ExcVectorTypeNotCompatible);
1276
1277 /**
1278 * Exception
1279 */
1280 DeclException3(ExcNonMatchingElements,
1281 Number,
1282 Number,
1283 unsigned int,
1284 << "Called compress(VectorOperation::insert), but"
1285 << " the element received from a remote processor, value "
1286 << std::setprecision(16) << arg1
1287 << ", does not match with the value "
1288 << std::setprecision(16) << arg2
1289 << " on the owner processor " << arg3);
1290
1291 /**
1292 * Exception
1293 */
1294 DeclException4(
1295 ExcAccessToNonLocalElement,
1296 size_type,
1297 size_type,
1298 size_type,
1299 size_type,
1300 << "You tried to access element " << arg1
1301 << " of a distributed vector, but this element is not "
1302 << "stored on the current processor. Note: The range of "
1303 << "locally owned elements is [" << arg2 << ',' << arg3
1304 << "], and there are " << arg4 << " ghost elements "
1305 << "that this vector can access."
1306 << "\n\n"
1307 << "A common source for this kind of problem is that you "
1308 << "are passing a 'fully distributed' vector into a function "
1309 << "that needs read access to vector elements that correspond "
1310 << "to degrees of freedom on ghost cells (or at least to "
1311 << "'locally active' degrees of freedom that are not also "
1312 << "'locally owned'). You need to pass a vector that has these "
1313 << "elements as ghost entries.");
1314
1315 private:
1316 /**
1317 * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>
1318 * without MPI communication.
1319 */
1320 void
1321 add_local(const Number a, const Vector<Number, MemorySpace> &V);
1322
1323 /**
1324 * Scaling and simple addition of a multiple of a vector, i.e. <tt>*this =
1325 * s*(*this)+a*V</tt> without MPI communication.
1326 */
1327 void
1328 sadd_local(const Number s,
1329 const Number a,
1330 const Vector<Number, MemorySpace> &V);
1331
1332 /**
1333 * Local part of the inner product of two vectors.
1334 */
1335 template <typename Number2>
1336 Number
1337 inner_product_local(const Vector<Number2, MemorySpace> &V) const;
1338
1339 /**
1340 * Local part of norm_sqr().
1341 */
1342 real_type
1343 norm_sqr_local() const;
1344
1345 /**
1346 * Local part of mean_value().
1347 */
1348 Number
1349 mean_value_local() const;
1350
1351 /**
1352 * Local part of l1_norm().
1353 */
1354 real_type
1355 l1_norm_local() const;
1356
1357 /**
1358 * Local part of lp_norm().
1359 */
1360 real_type
1361 lp_norm_local(const real_type p) const;
1362
1363 /**
1364 * Local part of linfty_norm().
1365 */
1366 real_type
1367 linfty_norm_local() const;
1368
1369 /**
1370 * Local part of the addition followed by an inner product of two
1371 * vectors. The same applies for complex-valued vectors as for
1372 * the add_and_dot() function.
1373 */
1374 Number
1375 add_and_dot_local(const Number a,
1376 const Vector<Number, MemorySpace> &V,
1377 const Vector<Number, MemorySpace> &W);
1378
1379 /**
1380 * Assert that there are no spurious non-zero entries in the ghost
1381 * region of the vector caused by some forgotten compress() or
1382 * zero_out_ghost_values() calls, which is an invariant of the vector
1383 * space operations such as the addition of vectors, scaling a vector,
1384 * and similar.
1385 */
1386 void
1387 assert_no_residual_content_in_ghost_region() const;
1388
1389 /**
1390 * Shared pointer to store the parallel partitioning information. This
1391 * information can be shared between several vectors that have the same
1392 * partitioning.
1393 */
1394 std::shared_ptr<const Utilities::MPI::Partitioner> partitioner;
1395
1396 /**
1397 * The size that is currently allocated in the val array.
1398 */
1399 size_type allocated_size;
1400
1401 /**
1402 * Underlying data structure storing the local elements of this vector.
1403 */
1404 mutable ::dealii::MemorySpace::MemorySpaceData<Number, MemorySpace> data;
1405
1406 /**
1407 * For parallel loops with TBB, this member variable stores the affinity
1408 * information of loops.
1409 */
1410 mutable std::shared_ptr<::dealii::parallel::internal::TBBPartitioner>
1411 thread_loop_partitioner;
1412
1413 /**
1414 * Temporary storage that holds the data that is sent to this processor
1415 * in compress() or sent from this processor in update_ghost_values().
1416 */
1417 mutable ::dealii::MemorySpace::MemorySpaceData<Number, MemorySpace>
1418 import_data;
1419
1420 /**
1421 * Stores whether the vector currently allows for reading ghost elements
1422 * or not. Note that this is to ensure consistent ghost data and does
1423 * not indicate whether the vector actually can store ghost elements. In
1424 * particular, when assembling a vector we do not allow reading
1425 * elements, only writing them.
1426 */
1427 mutable bool vector_is_ghosted;
1428
1429 #ifdef DEAL_II_WITH_MPI
1430 /**
1431 * A vector that collects all requests from compress() operations.
1432 * This class uses persistent MPI communicators, i.e., the communication
1433 * channels are stored during successive calls to a given function. This
1434 * reduces the overhead involved with setting up the MPI machinery, but
1435 * it does not remove the need for a receive operation to be posted
1436 * before the data can actually be sent.
1437 */
1438 std::vector<MPI_Request> compress_requests;
1439
1440 /**
1441 * A vector that collects all requests from update_ghost_values()
1442 * operations. This class uses persistent MPI communicators.
1443 */
1444 mutable std::vector<MPI_Request> update_ghost_values_requests;
1445 #endif
1446
1447 /**
1448 * A lock that makes sure that the compress() and update_ghost_values()
1449 * functions give reasonable results also when used
1450 * with several threads.
1451 */
1452 mutable std::mutex mutex;
1453
1454 /**
1455 * Communicator to be used for the shared-memory domain. See the general
1456 * documentation of this class for more information about the purpose of
1457 * `comm_sm`.
1458 */
1459 MPI_Comm comm_sm;
1460
1461 /**
1462 * A helper function that clears the compress_requests and
1463 * update_ghost_values_requests field. Used in reinit() functions.
1464 */
1465 void
1466 clear_mpi_requests();
1467
1468 /**
1469 * A helper function that is used to resize the val array.
1470 */
1471 void
1472 resize_val(const size_type new_allocated_size,
1473 const MPI_Comm comm_sm = MPI_COMM_SELF);
1474
1475 // Make all other vector types friends.
1476 template <typename Number2, typename MemorySpace2>
1477 friend class Vector;
1478
1479 // Make BlockVector type friends.
1480 template <typename Number2, typename MemorySpace2>
1481 friend class BlockVector;
1482 };
1483 /** @} */
1484
1485
1486 /*-------------------- Inline functions ---------------------------------*/
1487
1488 #ifndef DOXYGEN
1489
1490 template <typename Number, typename MemorySpace>
1491 inline bool
1492 Vector<Number, MemorySpace>::has_ghost_elements() const
1493 {
1494 return vector_is_ghosted;
1495 }
1496
1497
1498
1499 template <typename Number, typename MemorySpace>
1500 inline typename Vector<Number, MemorySpace>::size_type
1501 Vector<Number, MemorySpace>::size() const
1502 {
1503 return partitioner->size();
1504 }
1505
1506
1507
1508 template <typename Number, typename MemorySpace>
1509 inline typename Vector<Number, MemorySpace>::size_type
1510 Vector<Number, MemorySpace>::locally_owned_size() const
1511 {
1512 return partitioner->locally_owned_size();
1513 }
1514
1515
1516
1517 template <typename Number, typename MemorySpace>
1518 inline bool
1519 Vector<Number, MemorySpace>::in_local_range(
1520 const size_type global_index) const
1521 {
1522 return partitioner->in_local_range(global_index);
1523 }
1524
1525
1526
1527 template <typename Number, typename MemorySpace>
1528 inline IndexSet
1529 Vector<Number, MemorySpace>::locally_owned_elements() const
1530 {
1531 IndexSet is(size());
1532
1533 is.add_range(partitioner->local_range().first,
1534 partitioner->local_range().second);
1535
1536 return is;
1537 }
1538
1539
1540
1541 template <typename Number, typename MemorySpace>
1542 inline typename Vector<Number, MemorySpace>::iterator
1543 Vector<Number, MemorySpace>::begin()
1544 {
1545 return data.values.data();
1546 }
1547
1548
1549
1550 template <typename Number, typename MemorySpace>
1551 inline typename Vector<Number, MemorySpace>::const_iterator
1552 Vector<Number, MemorySpace>::begin() const
1553 {
1554 return data.values.data();
1555 }
1556
1557
1558
1559 template <typename Number, typename MemorySpace>
1560 inline typename Vector<Number, MemorySpace>::iterator
1561 Vector<Number, MemorySpace>::end()
1562 {
1563 return data.values.data() + partitioner->locally_owned_size();
1564 }
1565
1566
1567
1568 template <typename Number, typename MemorySpace>
1569 inline typename Vector<Number, MemorySpace>::const_iterator
1570 Vector<Number, MemorySpace>::end() const
1571 {
1572 return data.values.data() + partitioner->locally_owned_size();
1573 }
1574
1575
1576
1577 template <typename Number, typename MemorySpace>
1578 const std::vector<ArrayView<const Number>> &
1579 Vector<Number, MemorySpace>::shared_vector_data() const
1580 {
1581 return data.values_sm;
1582 }
1583
1584
1585
1586 template <typename Number, typename MemorySpace>
1587 inline Number
1588 Vector<Number, MemorySpace>::operator()(const size_type global_index) const
1589 {
1590 Assert((std::is_same_v<MemorySpace, ::dealii::MemorySpace::Host>),
1591 ExcMessage(
1592 "This function is only implemented for the Host memory space"));
1593 Assert(
1594 partitioner->in_local_range(global_index) ||
1595 partitioner->ghost_indices().is_element(global_index),
1596 ExcAccessToNonLocalElement(global_index,
1597 partitioner->local_range().first,
1598 partitioner->local_range().second == 0 ?
1599 0 :
1600 (partitioner->local_range().second - 1),
1601 partitioner->ghost_indices().n_elements()));
1602 // do not allow reading a vector which is not in ghost mode
1603 Assert(partitioner->in_local_range(global_index) ||
1604 vector_is_ghosted == true,
1605 ExcMessage("You tried to read a ghost element of this vector, "
1606 "but it has not imported its ghost values."));
1607 return data.values[partitioner->global_to_local(global_index)];
1608 }
1609
1610
1611
1612 template <typename Number, typename MemorySpace>
1613 inline Number &
1614 Vector<Number, MemorySpace>::operator()(const size_type global_index)
1615 {
1616 Assert((std::is_same_v<MemorySpace, ::dealii::MemorySpace::Host>),
1617 ExcMessage(
1618 "This function is only implemented for the Host memory space"));
1619 Assert(
1620 partitioner->in_local_range(global_index) ||
1621 partitioner->ghost_indices().is_element(global_index),
1622 ExcAccessToNonLocalElement(global_index,
1623 partitioner->local_range().first,
1624 partitioner->local_range().second == 0 ?
1625 0 :
1626 (partitioner->local_range().second - 1),
1627 partitioner->ghost_indices().n_elements()));
1628 // we would like to prevent reading ghosts from a vector that does not
1629 // have them imported, but this is not possible because we might be in a
1630 // part of the code where the vector has enabled ghosts but is non-const
1631 // (then, the compiler picks this method according to the C++ rule book
1632 // even if a human would pick the const method when this subsequent use
1633 // is just a read)
1634 return data.values[partitioner->global_to_local(global_index)];
1635 }
1636
1637
1638
1639 template <typename Number, typename MemorySpace>
1640 inline Number
1641 Vector<Number, MemorySpace>::operator[](const size_type global_index) const
1642 {
1643 return operator()(global_index);
1644 }
1645
1646
1647
1648 template <typename Number, typename MemorySpace>
1649 inline Number &
1650 Vector<Number, MemorySpace>::operator[](const size_type global_index)
1651 {
1652 return operator()(global_index);
1653 }
1654
1655
1656
1657 template <typename Number, typename MemorySpace>
1658 inline Number
1659 Vector<Number, MemorySpace>::local_element(
1660 const size_type local_index) const
1661 {
1662 Assert((std::is_same_v<MemorySpace, ::dealii::MemorySpace::Host>),
1663 ExcMessage(
1664 "This function is only implemented for the Host memory space"));
1665 AssertIndexRange(local_index,
1666 partitioner->locally_owned_size() +
1667 partitioner->n_ghost_indices());
1668 // do not allow reading a vector which is not in ghost mode
1669 Assert(local_index < locally_owned_size() || vector_is_ghosted == true,
1670 ExcMessage("You tried to read a ghost element of this vector, "
1671 "but it has not imported its ghost values."));
1672
1673 return data.values[local_index];
1674 }
1675
1676
1677
1678 template <typename Number, typename MemorySpace>
1679 inline Number &
1680 Vector<Number, MemorySpace>::local_element(const size_type local_index)
1681 {
1682 Assert((std::is_same_v<MemorySpace, ::dealii::MemorySpace::Host>),
1683 ExcMessage(
1684 "This function is only implemented for the Host memory space"));
1685
1686 AssertIndexRange(local_index,
1687 partitioner->locally_owned_size() +
1688 partitioner->n_ghost_indices());
1689
1690 return data.values[local_index];
1691 }
1692
1693
1694
1695 template <typename Number, typename MemorySpace>
1696 inline Number *
1697 Vector<Number, MemorySpace>::get_values() const
1698 {
1699 return data.values.data();
1700 }
1701
1702
1703
1704 template <typename Number, typename MemorySpace>
1705 template <typename OtherNumber>
1706 inline void
1707 Vector<Number, MemorySpace>::extract_subvector_to(
1708 const std::vector<size_type> &indices,
1709 std::vector<OtherNumber> &values) const
1710 {
1711 for (size_type i = 0; i < indices.size(); ++i)
1712 values[i] = operator()(indices[i]);
1713 }
1714
1715
1716
1717 template <typename Number, typename MemorySpace>
1718 template <typename ForwardIterator, typename OutputIterator>
1719 inline void
1720 Vector<Number, MemorySpace>::extract_subvector_to(
1721 ForwardIterator indices_begin,
1722 const ForwardIterator indices_end,
1723 OutputIterator values_begin) const
1724 {
1725 while (indices_begin != indices_end)
1726 {
1727 *values_begin = operator()(*indices_begin);
1728 ++indices_begin;
1729 ++values_begin;
1730 }
1731 }
1732
1733
1734
1735 template <typename Number, typename MemorySpace>
1736 template <typename OtherNumber>
1737 inline void
1738 Vector<Number, MemorySpace>::add(
1739 const std::vector<size_type> &indices,
1740 const ::dealii::Vector<OtherNumber> &values)
1741 {
1742 AssertDimension(indices.size(), values.size());
1743 for (size_type i = 0; i < indices.size(); ++i)
1744 {
1745 Assert(
1746 numbers::is_finite(values[i]),
1747 ExcMessage(
1748 "The given value is not finite but either infinite or Not A Number (NaN)"));
1749 this->operator()(indices[i]) += values(i);
1750 }
1751 }
1752
1753
1754
1755 template <typename Number, typename MemorySpace>
1756 template <typename OtherNumber>
1757 inline void
1758 Vector<Number, MemorySpace>::add(const size_type n_elements,
1759 const size_type *indices,
1760 const OtherNumber *values)
1761 {
1762 for (size_type i = 0; i < n_elements; ++i, ++indices, ++values)
1763 {
1764 Assert(
1765 numbers::is_finite(*values),
1766 ExcMessage(
1767 "The given value is not finite but either infinite or Not A Number (NaN)"));
1768 this->operator()(*indices) += *values;
1769 }
1770 }
1771
1772
1773
1774 template <typename Number, typename MemorySpace>
1775 inline MPI_Comm
1776 Vector<Number, MemorySpace>::get_mpi_communicator() const
1777 {
1778 return partitioner->get_mpi_communicator();
1779 }
1780
1781
1782
1783 template <typename Number, typename MemorySpace>
1784 inline const std::shared_ptr<const Utilities::MPI::Partitioner> &
1785 Vector<Number, MemorySpace>::get_partitioner() const
1786 {
1787 return partitioner;
1788 }
1789
1790
1791
1792 template <typename Number, typename MemorySpace>
1793 inline void
1794 Vector<Number, MemorySpace>::set_ghost_state(const bool ghosted) const
1795 {
1796 vector_is_ghosted = ghosted;
1797 }
1798
1799 #endif
1800
1801 } // namespace distributed
1802 } // namespace LinearAlgebra
1803
1804
1805 /**
1806 * Global function @p swap which overloads the default implementation of the
1807 * C++ standard library which uses a temporary object. The function simply
1808 * exchanges the data of the two vectors.
1809 *
1810 * @relatesalso Vector
1811 */
1812 template <typename Number, typename MemorySpace>
1813 inline void
1814 swap(LinearAlgebra::distributed::Vector<Number, MemorySpace> &u,
1815 LinearAlgebra::distributed::Vector<Number, MemorySpace> &v) noexcept
1816 {
1817 u.swap(v);
1818 }
1819
1820
1821 /**
1822 * Declare dealii::LinearAlgebra::distributed::Vector as distributed vector.
1823 */
1824 template <typename Number, typename MemorySpace>
1825 struct is_serial_vector<LinearAlgebra::distributed::Vector<Number, MemorySpace>>
1826 : std::false_type
1827 {};
1828
1829
1830
1831 namespace internal
1832 {
1833 namespace LinearOperatorImplementation
1834 {
1835 template <typename>
1836 class ReinitHelper;
1837
1838 /**
1839 * A helper class used internally in linear_operator.h. Specialization for
1840 * LinearAlgebra::distributed::Vector.
1841 */
1842 template <typename Number>
1843 class ReinitHelper<LinearAlgebra::distributed::Vector<Number>>
1844 {
1845 public:
1846 // A helper type-trait that leverage SFINAE to figure out if type T has
1847 // void T::get_mpi_communicator()
1848 template <typename T>
1849 using get_mpi_communicator_t =
1850 decltype(std::declval<T>().get_mpi_communicator());
1851
1852 template <typename T>
1853 static constexpr bool has_get_mpi_communicator =
1854 is_supported_operation<get_mpi_communicator_t, T>;
1855
1856 // A helper type-trait that leverage SFINAE to figure out if type T has
1857 // void T::locally_owned_domain_indices()
1858 template <typename T>
1859 using locally_owned_domain_indices_t =
1860 decltype(std::declval<T>().locally_owned_domain_indices());
1861
1862 template <typename T>
1863 static constexpr bool has_locally_owned_domain_indices =
1864 is_supported_operation<locally_owned_domain_indices_t, T>;
1865
1866 // A helper type-trait that leverage SFINAE to figure out if type T has
1867 // void T::locally_owned_range_indices()
1868 template <typename T>
1869 using locally_owned_range_indices_t =
1870 decltype(std::declval<T>().locally_owned_range_indices());
1871
1872 template <typename T>
1873 static constexpr bool has_locally_owned_range_indices =
1874 is_supported_operation<locally_owned_range_indices_t, T>;
1875
1876 // A helper type-trait that leverage SFINAE to figure out if type T has
1877 // void T::initialize_dof_vector(VectorType v)
1878 template <typename T>
1879 using initialize_dof_vector_t =
1880 decltype(std::declval<T>().initialize_dof_vector(
1881 std::declval<LinearAlgebra::distributed::Vector<Number> &>()));
1882
1883 template <typename T>
1884 static constexpr bool has_initialize_dof_vector =
1885 is_supported_operation<initialize_dof_vector_t, T>;
1886
1887 // Used for (Trilinos/PETSc)Wrappers::SparseMatrix
1888 template <typename MatrixType,
1889 #if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
1890 std::enable_if_t<has_get_mpi_communicator<MatrixType> &&
1891 has_locally_owned_domain_indices<MatrixType>,
1892 #else
1893 // workaround for Intel 18
1894 std::enable_if_t<
1895 is_supported_operation<get_mpi_communicator_t, MatrixType> &&
1896 is_supported_operation<locally_owned_domain_indices_t,
1897 MatrixType>,
1898 #endif
1899 MatrixType> * = nullptr>
1900 static void
1901 reinit_domain_vector(MatrixType &mat,
1902 LinearAlgebra::distributed::Vector<Number> &vec,
1903 bool /*omit_zeroing_entries*/)
1904 {
1905 vec.reinit(mat.locally_owned_domain_indices(),
1906 mat.get_mpi_communicator());
1907 }
1908
1909 // Used for MatrixFree and DiagonalMatrix
1910 template <typename MatrixType,
1911 #if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
1912 std::enable_if_t<has_initialize_dof_vector<MatrixType>,
1913 #else
1914 // workaround for Intel 18
1915 std::enable_if_t<
1916 is_supported_operation<initialize_dof_vector_t, MatrixType>,
1917 #endif
1918 MatrixType> * = nullptr>
1919 static void
1920 reinit_domain_vector(MatrixType &mat,
1921 LinearAlgebra::distributed::Vector<Number> &vec,
1922 bool omit_zeroing_entries)
1923 {
1924 mat.initialize_dof_vector(vec);
1925 if (!omit_zeroing_entries)
1926 vec = Number();
1927 }
1928
1929 // Used for (Trilinos/PETSc)Wrappers::SparseMatrix
1930 template <typename MatrixType,
1931 #if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
1932 std::enable_if_t<has_get_mpi_communicator<MatrixType> &&
1933 has_locally_owned_range_indices<MatrixType>,
1934 #else
1935 // workaround for Intel 18
1936 std::enable_if_t<
1937 is_supported_operation<get_mpi_communicator_t, MatrixType> &&
1938 is_supported_operation<locally_owned_range_indices_t,
1939 MatrixType>,
1940 #endif
1941 MatrixType> * = nullptr>
1942 static void
1943 reinit_range_vector(MatrixType &mat,
1944 LinearAlgebra::distributed::Vector<Number> &vec,
1945 bool /*omit_zeroing_entries*/)
1946 {
1947 vec.reinit(mat.locally_owned_range_indices(),
1948 mat.get_mpi_communicator());
1949 }
1950
1951 // Used for MatrixFree and DiagonalMatrix
1952 template <typename MatrixType,
1953 #if !defined(__INTEL_COMPILER) || __INTEL_COMPILER >= 1900
1954 std::enable_if_t<has_initialize_dof_vector<MatrixType>,
1955 #else
1956 // workaround for Intel 18
1957 std::enable_if_t<
1958 is_supported_operation<initialize_dof_vector_t, MatrixType>,
1959 #endif
1960 MatrixType> * = nullptr>
1961 static void
1962 reinit_range_vector(MatrixType &mat,
1963 LinearAlgebra::distributed::Vector<Number> &vec,
1964 bool omit_zeroing_entries)
1965 {
1966 mat.initialize_dof_vector(vec);
1967 if (!omit_zeroing_entries)
1968 vec = Number();
1969 }
1970 };
1971
1972 } // namespace LinearOperatorImplementation
1973 } /* namespace internal */
1974
1975
1976 DEAL_II_NAMESPACE_CLOSE
1977
1978 #endif