Debian Codegraph @

include/deal.II/base/mpi.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_mpi_h
16 #define dealii_mpi_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/array_view.h>
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/init_finalize.h>
23 #include <deal.II/base/mpi_stub.h>
24 #include <deal.II/base/mpi_tags.h>
25 #include <deal.II/base/numbers.h>
26 #include <deal.II/base/template_constraints.h>
27 #include <deal.II/base/types.h>
28 #include <deal.II/base/utilities.h>
29
30 #include <complex>
31 #include <limits>
32 #include <map>
33 #include <numeric>
34 #include <set>
35 #include <vector>
36
37 #ifdef DEAL_II_WITH_MPI
38 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
39 # include <mpi.h>
40 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
41 #endif
42
43
44 /**
45 * Helper macro to remove const from the pointer arguments to some MPI_*
46 * functions.
47 *
48 * This is needed as the input arguments of functions like MPI_Allgather() are
49 * not marked as const in OpenMPI 1.6.5. If using MPI 3 or newer, this macro
50 * is a NOOP, while we do the following otherwise:
51 *
52 * 1. remove * from type of @p expr
53 * 2. remove const from resulting type
54 * 3. add * to resulting type
55 * 4. const_cast the given expression @p expr to this new type.
56 */
57 #ifdef DEAL_II_WITH_MPI
58 # define DEAL_II_MPI_CONST_CAST(expr) (expr)
59 #endif
60
61
62
63 DEAL_II_NAMESPACE_OPEN
64
65
66 // Forward type declarations to allow MPI sums over tensorial types
67 #ifndef DOXYGEN
68 template <int rank, int dim, typename Number>
69 class Tensor;
70 template <int rank, int dim, typename Number>
71 class SymmetricTensor;
72 template <typename Number>
73 class SparseMatrix;
74 class IndexSet;
75 #endif
76
77 namespace Utilities
78 {
79 /**
80 * Given the total number of elements @p total_size, create an evenly
81 * distributed 1:1 partitioning of the elements for across @p n_partitions.
82 * The local sizes will be equal to the @p total_size divided by the number
83 * of partitions plus the remainder being divided amongst the first
84 * processes. Each process will store a contiguous subset of indices, and the
85 * index set on process p+1 starts at the index one larger than the last one
86 * stored on process p.
87 * For example, a @p total_size of 11 with 3 processes will result
88 * in the IndexSets { [0,4), [4,8), [8,11)] }, and this function will
89 * return the @p my_partition_id 's IndexSet.
90 */
91 IndexSet
92 create_evenly_distributed_partitioning(
93 const unsigned int my_partition_id,
94 const unsigned int n_partitions,
95 const types::global_dof_index total_size);
96
97 /**
98 * A namespace for utility functions that abstract certain operations using
99 * the Message Passing Interface (MPI) or provide fallback operations in
100 * case deal.II is configured not to use MPI at all.
101 *
102 * @ingroup utilities
103 */
104 namespace MPI
105 {
106 /**
107 * A template variable that is `true` if the template argument `T` is a data
108 * type that is natively supported by MPI, and `false` otherwise. This
109 * variable can be used together with `std::enable_if` to selectively allow
110 * template functions only for those data types for which the template type
111 * is supported by MPI. The variable is, in essence, a concept in the sense
112 * of C++20.
113 */
114 template <typename T>
115 constexpr bool is_mpi_type = is_same_as_any_of<T,
116 char,
117 signed short,
118 signed int,
119 signed long,
120 signed long long,
121 signed char,
122 unsigned char,
123 unsigned short,
124 unsigned int,
125 unsigned long int,
126 unsigned long long,
127 float,
128 double,
129 long double,
130 bool,
131 std::complex<float>,
132 std::complex<double>,
133 std::complex<long double>,
134 wchar_t>::value;
135
136 /**
137 * Return the number of MPI processes there exist in the given
138 * @ref GlossMPICommunicator "communicator"
139 * object. If this is a sequential job (i.e., the program
140 * is not using MPI at all, or is using MPI but has been started with
141 * only one MPI process), then the communicator necessarily involves
142 * only one process and the function returns 1.
143 */
144 unsigned int
145 n_mpi_processes(const MPI_Comm mpi_communicator);
146
147 /**
148 * Return the
149 * @ref GlossMPIRank "rank of the present MPI process"
150 * in the space of processes described by the given
151 * @ref GlossMPICommunicator "communicator".
152 * This will be a unique value for each process between zero and (less
153 * than) the number of all processes (given by get_n_mpi_processes()).
154 */
155 unsigned int
156 this_mpi_process(const MPI_Comm mpi_communicator);
157
158 /**
159 * Return a vector of the ranks (within @p comm_large) of a subset of
160 * processes specified by @p comm_small.
161 */
162 std::vector<unsigned int>
163 mpi_processes_within_communicator(const MPI_Comm comm_large,
164 const MPI_Comm comm_small);
165
166 /**
167 * Consider an unstructured communication pattern where every process in
168 * an MPI universe wants to send some data to a subset of the other
169 * processors. To do that, the other processors need to know who to expect
170 * messages from. This function computes this information.
171 *
172 * @param mpi_comm A
173 * @ref GlossMPICommunicator "communicator"
174 * that describes the processors that are going to communicate with each
175 * other.
176 *
177 * @param destinations The list of processors the current process wants to
178 * send information to. This list need not be sorted in any way. If it
179 * contains duplicate entries that means that multiple messages are
180 * intended for a given destination.
181 *
182 * @return A list of processors that have indicated that they want to send
183 * something to the current processor. The resulting list is not sorted.
184 * It may contain duplicate entries if processors enter the same
185 * destination more than once in their destinations list.
186 */
187 std::vector<unsigned int>
188 compute_point_to_point_communication_pattern(
189 const MPI_Comm mpi_comm,
190 const std::vector<unsigned int> &destinations);
191
192 /**
193 * Simplified (for efficiency) version of the
194 * compute_point_to_point_communication_pattern()
195 * which only computes the number of processes in an MPI universe to expect
196 * communication from.
197 *
198 * @param mpi_comm A
199 * @ref GlossMPICommunicator "communicator"
200 * that describes the processors that are going to communicate with each
201 * other.
202 *
203 * @param destinations The list of processors the current process wants to
204 * send information to. This list need not be sorted in any way. If it
205 * contains duplicate entries that means that multiple messages are
206 * intended for a given destination.
207 *
208 * @return A number of processors that want to send something to the current
209 * processor.
210 */
211 unsigned int
212 compute_n_point_to_point_communications(
213 const MPI_Comm mpi_comm,
214 const std::vector<unsigned int> &destinations);
215
216 /**
217 * Given a
218 * @ref GlossMPICommunicator "communicator",
219 * generate a new communicator that contains the same set of processors
220 * but that has a different, unique identifier.
221 *
222 * This functionality can be used to ensure that different objects, such
223 * as distributed matrices, each have unique communicators over which they
224 * can interact without interfering with each other.
225 *
226 * When no longer needed, the communicator created here needs to be
227 * destroyed using free_communicator().
228 *
229 * This function is equivalent to calling
230 * <code>MPI_Comm_dup(mpi_communicator, &return_value);</code>.
231 */
232 MPI_Comm
233 duplicate_communicator(const MPI_Comm mpi_communicator);
234
235 /**
236 * Free the given
237 * @ref GlossMPICommunicator "communicator"
238 * @p mpi_communicator that was duplicated using duplicate_communicator().
239 *
240 * The argument is passed by reference and will be invalidated and set to
241 * the MPI null handle. This function is equivalent to calling
242 * <code>MPI_Comm_free(&mpi_communicator);</code>.
243 */
244 void
245 free_communicator(MPI_Comm mpi_communicator);
246
247 /**
248 * Helper class to automatically duplicate and free an MPI
249 * @ref GlossMPICommunicator "communicator".
250 *
251 * This class duplicates the communicator given in the constructor
252 * using duplicate_communicator() and frees it automatically when
253 * this object gets destroyed by calling free_communicator(). You
254 * can access the wrapped communicator using operator*.
255 *
256 * This class exists to easily allow duplicating communicators without
257 * having to worry when and how to free it after usage.
258 */
259 class DuplicatedCommunicator
260 {
261 public:
262 /**
263 * Create a duplicate of the given @p communicator.
264 */
265 explicit DuplicatedCommunicator(const MPI_Comm communicator)
266 : comm(duplicate_communicator(communicator))
267 {}
268
269 /**
270 * Do not allow making copies.
271 */
272 DuplicatedCommunicator(const DuplicatedCommunicator &) = delete;
273
274 /**
275 * The destructor will free the communicator automatically.
276 */
277 ~DuplicatedCommunicator()
278 {
279 free_communicator(comm);
280 }
281
282 /**
283 * Access the stored communicator.
284 */
285 MPI_Comm
286 operator*() const
287 {
288 return comm;
289 }
290
291
292 /**
293 * Do not allow assignment of this class.
294 */
295 DuplicatedCommunicator &
296 operator=(const DuplicatedCommunicator &) = delete;
297
298 private:
299 /**
300 * The communicator of course.
301 */
302 MPI_Comm comm;
303 };
304
305
306
307 /**
308 * This class represents a mutex to guard a critical section for a set of
309 * processors in a parallel computation using MPI.
310 *
311 * The lock() commands waits until all MPI ranks in the communicator have
312 * released a previous lock using unlock().
313 *
314 * A typical usage involves guarding a critical section using a lock guard:
315 * @code
316 * {
317 * static CollectiveMutex mutex;
318 * CollectiveMutex::ScopedLock lock(mutex, comm);
319 * // [ critical code to be guarded]
320 * }
321 * @endcode
322 *
323 * Here, the critical code will finish on all processors before the mutex
324 * can be acquired again (for example by a second execution of the block
325 * above. The critical code block typically involves MPI communication that
326 * would yield incorrect results without the lock. For example, if the code
327 * contains nonblocking receives with MPI_ANY_SOURCE, packets can be
328 * confused between iterations.
329 *
330 * Note that the mutex needs to be the same instance between calls to the
331 * same critical region. While not required, this can be achieved by making
332 * the instance static (like in the example above). The variable can also be
333 * a global variable, or a member variable of the object to which the
334 * executing function belongs.
335 */
336 class CollectiveMutex
337 {
338 public:
339 /**
340 * This helper class provides a scoped lock for the CollectiveMutex.
341 *
342 * See the class documentation of CollectiveMutex for details.
343 */
344 class ScopedLock
345 {
346 public:
347 /**
348 * Constructor. Blocks until it can acquire the lock.
349 */
350 explicit ScopedLock(CollectiveMutex &mutex, const MPI_Comm comm)
351 : mutex(mutex)
352 , comm(comm)
353 {
354 mutex.lock(comm);
355 }
356
357 /**
358 * Destructor. Releases the lock.
359 */
360 ~ScopedLock()
361 {
362 mutex.unlock(comm);
363 }
364
365 private:
366 /**
367 * A reference to the mutex.
368 */
369 CollectiveMutex &mutex;
370 /**
371 * The communicator.
372 */
373 const MPI_Comm comm;
374 };
375
376 /**
377 * Constructor of this class.
378 */
379 CollectiveMutex();
380
381 /**
382 * Destroy the mutex. Assumes the lock is not currently held.
383 */
384 ~CollectiveMutex();
385
386 /**
387 * Acquire the mutex and, if necessary, wait until we can do so.
388 *
389 * This is a collective call that needs to be executed by all processors
390 * in the communicator.
391 */
392 void
393 lock(const MPI_Comm comm);
394
395 /**
396 * Release the lock.
397 *
398 * This is a collective call that needs to be executed by all processors
399 * in the communicator.
400 */
401 void
402 unlock(const MPI_Comm comm);
403
404 private:
405 /**
406 * Keep track if we have this lock right now.
407 */
408 bool locked;
409
410 /**
411 * The request to keep track of the non-blocking barrier.
412 */
413 MPI_Request request;
414 };
415
416
417
418 /**
419 * An object that acts like a
420 * [std::future](https://en.cppreference.com/w/cpp/thread/future)
421 * object except that it does not encode the operation of waiting
422 * for an operation to finish what may be happening on a different
423 * thread, but for an "immediate" MPI operation such as
424 * `MPI_Isend` or `MPI_Irecv`. An object of this kind is returned,
425 * for example, by the isend() and irecv() functions in this
426 * namespace.
427 *
428 * If the operation being waited for produces a result (such as
429 * a *receive* operation, then the produced result is returned
430 * by the get() function and its type is indicated by the
431 * template argument `T`. If the operation does not produce
432 * a result (such as waiting for a send operation to complete),
433 * then `T=void` is the right choice for the template argument.
434 *
435 *
436 * <h3> Implementation </h3>
437 *
438 * Immediate MPI operations are typically associated with two
439 * additional actions. The first is that one has to be able to
440 * *wait* for them to finish. In many cases, this is done using
441 * a call to `MPI_Wait` that is given an `MPI_Request` object
442 * (in the case of send operations) or a call to `MPI_Probe`
443 * or a variant of this function (in the case of receive
444 * operations). The wait operation may be called more than
445 * once and would immediately return once the first one
446 * has succeeded.
447 *
448 * Secondly, immediate MPI operations often require clean-up
449 * actions that must be executed once the operation has
450 * finished. An example is releasing a buffer in which data
451 * has been stored (for an immediate send operation), or
452 * allocating a receive buffer, calling the MPI function that
453 * puts the received data into this buffer, calling the unpacking
454 * function for the data received, and releasing the receive buffer
455 * (for an immediate receive operation).
456 *
457 * This class models these two steps by taking two constructor
458 * arguments that correspond to these two operations. It ensures
459 * that upon destruction of the current object, both the
460 * wait and clean-up functions are called. Because the clean-up
461 * function can only be called once, objects of the current
462 * class can not be copied, but they can be moved.
463 */
464 template <typename T>
465 class Future
466 {
467 public:
468 /**
469 * Constructor. Take both the wait and clean-up functions mentioned
470 * in the class documentation as arguments.
471 */
472 template <typename W, typename G>
473 Future(W &&wait_operation, G &&get_and_cleanup_operation);
474
475 /**
476 * Copy constructor. This operation is not possible, as explained
477 * in the class documentation, and consequently the constructor
478 * is deleted.
479 */
480 Future(const Future &) = delete;
481
482 /**
483 * Move constructor.
484 */
485 Future(Future &&) noexcept = default;
486
487 /**
488 * Destructor.
489 *
490 * If the current object has not been the right hand side of a move
491 * operation, and if get() has not been called on the current object,
492 * then the destructor blocks until the operation is completed so that
493 * the clean-up operations can be performed. As a consequence, if you
494 * write code such as
495 * @code
496 * Utilities::MPI::isend(data, mpi_communicator, receiver, tag);
497 * @endcode
498 * where you do not capture the isend() functions' returned object,
499 * then the destructor of the returned object will run immediately at the
500 * end of executing this line, and this implies waiting for the isend()
501 * function's operations to finish -- in other words, you are turning
502 * the "immediate send" into a "waiting send" where the line only
503 * terminates once the data has been sent and the send buffer is no
504 * longer needed. (Note, however, that that is not the same as MPI's
505 * concept of a "synchronous send" in which the function only returns
506 * once the data has been *received*.)
507 *
508 * Of course, the same happens if you write
509 * @code
510 * {
511 * Utilities::MPI::Future<void> future
512 * = Utilities::MPI::isend(data, mpi_communicator, receiver, tag);
513 * }
514 * @endcode
515 * where you do capture the returned object, but the destructor is run
516 * at the closing brace -- also immediately after returning from isend().
517 */
518 ~Future();
519
520 /**
521 * Copy operator. This operation is not possible, as explained
522 * in the class documentation, and consequently the operator
523 * is deleted.
524 */
525 Future &
526 operator=(const Future &) = delete;
527
528 /**
529 * Move operator.
530 */
531 Future &
532 operator=(Future &&) noexcept = default;
533
534 /**
535 * Wait for the operation to complete. This function can safely be called
536 * more than once. It will wait for the operation to complete the first
537 * time it is called; because the operation will have completed once
538 * it has been called for the first time, it will immediately return
539 * if called again at a later time.
540 */
541 void
542 wait();
543
544 /**
545 * Wait for the operation to complete and return the object the
546 * operation produces (if `T` is not equal to `void`).
547 *
548 * Like for std::future, this function can only be called once
549 * because the class does not store the object produced. (It
550 * can not store the object being produced because returning
551 * it from this function would require the ability to copy
552 * it; however, not all objects can be copied, whereas all
553 * useful objects can be moved.)
554 */
555 T
556 get();
557
558 private:
559 /**
560 * Function objects encoding the wait and clean-up operations.
561 */
562 std::function<void()> wait_function;
563 std::function<T()> get_and_cleanup_function;
564
565 /**
566 * Whether or not wait() has already been called.
567 */
568 bool is_done;
569
570 /**
571 * Whether or not get() has already been called.
572 */
573 bool get_was_called;
574 };
575
576 /**
577 * Given the number of locally owned elements @p locally_owned_size,
578 * create a 1:1 partitioning of the of elements across the MPI
579 * communicator @p comm. The total size of elements is the sum of
580 * @p locally_owned_size across the MPI communicator. Each process will
581 * store contiguous subset of indices, and the index set on process p+1
582 * starts at the index one larger than the last one stored on process p.
583 */
584 std::vector<IndexSet>
585 create_ascending_partitioning(
586 const MPI_Comm comm,
587 const types::global_dof_index locally_owned_size);
588
589 /**
590 * Given the total number of elements @p total_size, create an evenly
591 * distributed 1:1 partitioning of the elements across the
592 * MPI communicator @p comm.
593 * Uses @p comm to determine number of partitions and processor ID to call the
594 * @p create_evenly_distributed_partitioning() function above.
595 */
596 IndexSet
597 create_evenly_distributed_partitioning(
598 const MPI_Comm comm,
599 const types::global_dof_index total_size);
600
601 #ifdef DEAL_II_WITH_MPI
602 /**
603 * Calculate mean and standard deviation across the MPI communicator @p comm
604 * for values provided as a range `[begin,end)`.
605 * The mean is computed as $\bar x=\frac 1N \sum x_k$ where the $x_k$ are
606 * the elements pointed to by the `begin` and `end` iterators on all
607 * processors (i.e., each processor's `[begin,end)` range points to a subset
608 * of the overall number of elements). The standard deviation is calculated
609 * as $\sigma=\sqrt{\frac {1}{N-1} \sum |x_k -\bar x|^2}$, which is known as
610 * unbiased sample variance.
611 *
612 * @tparam Number specifies the type to store the mean value.
613 * The standard deviation is stored as the corresponding real type.
614 * This allows, for example, to calculate statistics from integer input
615 * values.
616 */
617 template <class Iterator, typename Number = long double>
618 std::pair<Number, typename numbers::NumberTraits<Number>::real_type>
619 mean_and_standard_deviation(const Iterator begin,
620 const Iterator end,
621 const MPI_Comm comm);
622 #endif
623
624
625 /**
626 * Create a object that contains an `MPI_Datatype` that represents @p n_bytes bytes.
627 *
628 * The resulting data type can be used in MPI send/receive or MPI IO to
629 * process messages of sizes larger than 2 GB with MPI_Byte as the
630 * underlying data type. This helper is required for MPI versions before 4.0
631 * because routines like `MPI_Send`
632 * use a signed integer for the @p count variable. Instead, you can use this
633 * data type with the appropriate size set to the size of your message and
634 * by passing
635 * 1 as the @p count.
636 *
637 * @note The function does not just return an object of type `MPI_Datatype`
638 * because such objects need to be destroyed by a call to `MPI_Type_free`
639 * and it is easy to forget to do so (thereby creating a resource leak).
640 * Rather, the function returns an object that *points* to such an
641 * `MPI_Datatype` object, but also has a "deleter" function that ensures
642 * that `MPI_Type_free` is called whenever the object returned by this
643 * function goes out of scope.
644 *
645 * Usage example:
646 * <code>
647 * std::vector<char> buffer;
648 * [...]
649 * if (buffer.size()<(1U<<31))
650 * { // less than 2GB of data
651 * MPI_Send(buffer.data(), buffer.size(), MPI_BYTE, dest, tag, comm);
652 * }
653 * else
654 * { // more than 2GB of data
655 * const auto bigtype =
656 * Utilities::MPI::create_mpi_data_type_n_bytes(buffer.size());
657 * MPI_Send(buffer.data(), 1, *bigtype, dest, tag, comm);
658 * }
659 * </code>
660 * Alternatively, the code in the `else` branch can be simplified to
661 * the following:
662 * <code>
663 * [...]
664 * else
665 * { // more than 2GB of data
666 * MPI_Send(buffer.data(), 1,
667 * *Utilities::MPI::create_mpi_data_type_n_bytes(buffer.size()),
668 * dest, tag, comm);
669 * }
670 * </code>
671 */
672 std::unique_ptr<MPI_Datatype, void (*)(MPI_Datatype *)>
673 create_mpi_data_type_n_bytes(const std::size_t n_bytes);
674
675 /**
676 * Return the sum over all processors of the value @p t. This function is
677 * collective over all processors given in the
678 * @ref GlossMPICommunicator "communicator".
679 * If deal.II is not configured for use of MPI, this function simply
680 * returns the value of @p t. This function corresponds to the
681 * <code>MPI_Allreduce</code> function, i.e. all processors receive the
682 * result of this operation.
683 *
684 * @note Sometimes, not all processors need a result and in that case one
685 * would call the <code>MPI_Reduce</code> function instead of the
686 * <code>MPI_Allreduce</code> function. The latter is at most twice as
687 * expensive, so if you are concerned about performance, it may be
688 * worthwhile investigating whether your algorithm indeed needs the result
689 * everywhere.
690 *
691 * @note This function is only implemented for certain template arguments
692 * <code>T</code>, namely <code>float, double, int, unsigned int</code>.
693 */
694 template <typename T>
695 T
696 sum(const T &t, const MPI_Comm mpi_communicator);
697
698 /**
699 * Like the previous function, but take the sums over the elements of an
700 * array of type T. In other words, the i-th element of the results
701 * array is the sum over the i-th entries of the input arrays from each
702 * processor. T and U must decay to the same type, e.g. they just differ by
703 * one of them having a const type qualifier and the other not.
704 *
705 * Input and output arrays may be the same.
706 */
707 template <typename T, typename U>
708 void
709 sum(const T &values, const MPI_Comm mpi_communicator, U &sums);
710
711 /**
712 * Like the previous function, but take the sums over the elements of an
713 * array as specified by the ArrayView arguments.
714 * In other words, the i-th element of the results
715 * array is the sum over the i-th entries of the input arrays from each
716 * processor.
717 *
718 * Input and output arrays may be the same.
719 */
720 template <typename T>
721 void
722 sum(const ArrayView<const T> &values,
723 const MPI_Comm mpi_communicator,
724 const ArrayView<T> &sums);
725
726 /**
727 * Perform an MPI sum of the entries of a symmetric tensor.
728 *
729 * @relatesalso SymmetricTensor
730 */
731 template <int rank, int dim, typename Number>
732 SymmetricTensor<rank, dim, Number>
733 sum(const SymmetricTensor<rank, dim, Number> &local,
734 const MPI_Comm mpi_communicator);
735
736 /**
737 * Perform an MPI sum of the entries of a tensor.
738 *
739 * @relatesalso Tensor
740 */
741 template <int rank, int dim, typename Number>
742 Tensor<rank, dim, Number>
743 sum(const Tensor<rank, dim, Number> &local,
744 const MPI_Comm mpi_communicator);
745
746 /**
747 * Perform an MPI sum of the entries of a SparseMatrix.
748 *
749 * @note @p local and @p global should have the same sparsity
750 * pattern and it should be the same for all MPI processes.
751 *
752 * @relatesalso SparseMatrix
753 */
754 template <typename Number>
755 void
756 sum(const SparseMatrix<Number> &local,
757 const MPI_Comm mpi_communicator,
758 SparseMatrix<Number> &global);
759
760 /**
761 * Return the maximum over all processors of the value @p t. This function
762 * is collective over all processors given in the
763 * @ref GlossMPICommunicator "communicator".
764 * If deal.II is not configured for use of MPI, this function simply
765 * returns the value of @p t. This function corresponds to the
766 * <code>MPI_Allreduce</code> function, i.e. all processors receive the
767 * result of this operation.
768 *
769 * @note Sometimes, not all processors need a result and in that case one
770 * would call the <code>MPI_Reduce</code> function instead of the
771 * <code>MPI_Allreduce</code> function. The latter is at most twice as
772 * expensive, so if you are concerned about performance, it may be
773 * worthwhile investigating whether your algorithm indeed needs the result
774 * everywhere.
775 *
776 * @note This function is only implemented for certain template arguments
777 * <code>T</code>, namely <code>float, double, int, unsigned int</code>.
778 */
779 template <typename T>
780 T
781 max(const T &t, const MPI_Comm mpi_communicator);
782
783 /**
784 * Like the previous function, but take the maximum over the elements of an
785 * array of type T. In other words, the i-th element of the results array is
786 * the maximum over the i-th entries of the input arrays from each
787 * processor. T and U must decay to the same type, e.g. they just differ by
788 * one of them having a const type qualifier and the other not.
789 *
790 * Input and output vectors may be the same.
791 */
792 template <typename T, typename U>
793 void
794 max(const T &values, const MPI_Comm mpi_communicator, U &maxima);
795
796 /**
797 * Like the previous function, but take the maximum over the elements of an
798 * array as specified by the ArrayView arguments.
799 * In other words, the i-th element of the results
800 * array is the maximum over the i-th entries of the input arrays from each
801 * processor.
802 *
803 * Input and output arrays may be the same.
804 */
805 template <typename T>
806 void
807 max(const ArrayView<const T> &values,
808 const MPI_Comm mpi_communicator,
809 const ArrayView<T> &maxima);
810
811 /**
812 * Return the minimum over all processors of the value @p t. This function
813 * is collective over all processors given in the
814 * @ref GlossMPICommunicator "communicator".
815 * If deal.II is not configured for use of MPI, this function simply
816 * returns the value of @p t. This function corresponds to the
817 * <code>MPI_Allreduce</code> function, i.e. all processors receive the
818 * result of this operation.
819 *
820 * @note Sometimes, not all processors need a result and in that case one
821 * would call the <code>MPI_Reduce</code> function instead of the
822 * <code>MPI_Allreduce</code> function. The latter is at most twice as
823 * expensive, so if you are concerned about performance, it may be
824 * worthwhile investigating whether your algorithm indeed needs the result
825 * everywhere.
826 *
827 * @note This function is only implemented for certain template arguments
828 * <code>T</code>, namely <code>float, double, int, unsigned int</code>.
829 */
830 template <typename T>
831 T
832 min(const T &t, const MPI_Comm mpi_communicator);
833
834 /**
835 * Like the previous function, but take the minima over the elements of an
836 * array of type T. In other words, the i-th element of the results
837 * array is the minimum of the i-th entries of the input arrays from each
838 * processor. T and U must decay to the same type, e.g. they just differ by
839 * one of them having a const type qualifier and the other not.
840 *
841 * Input and output arrays may be the same.
842 */
843 template <typename T, typename U>
844 void
845 min(const T &values, const MPI_Comm mpi_communicator, U &minima);
846
847 /**
848 * Like the previous function, but take the minimum over the elements of an
849 * array as specified by the ArrayView arguments.
850 * In other words, the i-th element of the results
851 * array is the minimum over the i-th entries of the input arrays from each
852 * processor.
853 *
854 * Input and output arrays may be the same.
855 */
856 template <typename T>
857 void
858 min(const ArrayView<const T> &values,
859 const MPI_Comm mpi_communicator,
860 const ArrayView<T> &minima);
861
862 /**
863 * Performs a <i>logical or</i> operation over all processors of the value
864 * @p t. The <i>logical or</i> operator `||` returns the boolean value
865 * `true` if either or all operands are `true` and returns `false`
866 * otherwise. If the provided value @p t corresponds to `0` in its
867 * associated data type `T`, it will be interpreted as `false`, and `true`
868 * otherwise. Data type `T` must be of type `integral`, i.e., `bool`,
869 * `char`, `short`, `int`, `long`, or any of their variations.
870 *
871 * This function is collective over all processors given in the
872 * @ref GlossMPICommunicator "communicator".
873 * If deal.II is not configured for use of MPI, this function simply
874 * returns the value of @p value. This function corresponds to the
875 * <code>MPI_Allreduce</code> function, i.e., all processors receive the
876 * result of this operation.
877 *
878 * @note Sometimes, not all processors need a result and in that case one
879 * would call the <code>MPI_Reduce</code> function instead of the
880 * <code>MPI_Allreduce</code> function. The latter is at most twice as
881 * expensive, so if you are concerned about performance, it may be
882 * worthwhile investigating whether your algorithm indeed needs the result
883 * everywhere.
884 */
885 template <typename T>
886 T
887 logical_or(const T &t, const MPI_Comm mpi_communicator);
888
889 /**
890 * Like the previous function, but performs the <i>logical or</i> operation
891 * on each element of an array. In other words, the i-th element of the
892 * results array is the result of the <i>logical or</i> operation applied on
893 * the i-th entries of the input arrays from each processor. T and U must
894 * decay to the same type, e.g., they just differ by one of them having a
895 * const type qualifier and the other not.
896 *
897 * Input and output arrays may be the same.
898 *
899 * @note Depending on your standard library, this function may not work with
900 * specializations of `std::vector` for the data type `bool`. In that
901 * case, use a different container or data type.
902 */
903 template <typename T, typename U>
904 void
905 logical_or(const T &values, const MPI_Comm mpi_communicator, U &results);
906
907 /**
908 * Like the previous function, but performs the <i>logical or</i> operation
909 * on each element of an array as specified by the ArrayView arguments.
910 * In other words, the i-th element of the results array is the result of
911 * the <i>logical or</i> operation applied on the i-th entries of the input
912 * arrays from each processor.
913 *
914 * Input and output arrays may be the same.
915 */
916 template <typename T>
917 void
918 logical_or(const ArrayView<const T> &values,
919 const MPI_Comm mpi_communicator,
920 const ArrayView<T> &results);
921
922 /**
923 * A data structure to store the result of the min_max_avg() function.
924 * The structure stores the minimum, maximum, and average of one
925 * value contributed by each processor that participates in an
926 * @ref GlossMPICommunicator "MPI communicator".
927 * The structure also stores
928 * the indices (or, more precisely, the
929 * @ref GlossMPIRank "MPI rank")
930 * of the processors that hold the minimum and maximum values,
931 * as well as the sum over all values.
932 *
933 * @note This structure has no constructors because MPI requires it
934 * to be a POD type.
935 */
936 struct MinMaxAvg
937 {
938 /**
939 * The sum over all values contributed by the processors that
940 * participate in the call to min_max_avg().
941 */
942 double sum;
943
944 /**
945 * The minimum value over all values contributed by the processors that
946 * participate in the call to min_max_avg().
947 */
948 double min;
949
950 /**
951 * The maximum value over all values contributed by the processors that
952 * participate in the call to min_max_avg().
953 */
954 double max;
955
956 /**
957 * One of the ranks (i.e.,
958 * @ref GlossMPIRank "MPI rank"
959 * within an
960 * @ref GlossMPICommunicator "MPI communicator")
961 * of the
962 * processors that hold the minimal value.
963 */
964 unsigned int min_index;
965
966 /**
967 * One of the ranks (i.e.,
968 * @ref GlossMPIRank "MPI rank"
969 * within an
970 * @ref GlossMPICommunicator "MPI communicator")
971 * of the
972 * processors that hold the maximal value.
973 */
974 unsigned int max_index;
975
976 /**
977 * The average of the values contributed by the processors that
978 * participate in the call to min_max_avg().
979 */
980 double avg;
981 };
982
983 /**
984 * Return sum, average, minimum, maximum, processor id of minimum and
985 * maximum as a @ref GlossCollectiveOperation "collective operation" of on the given MPI
986 * @ref GlossMPICommunicator "communicator"
987 * @p mpi_communicator. Each processor's value is given in @p my_value and
988 * the result will be returned. The result is available on all machines.
989 *
990 * @note Sometimes, not all processors need a result and in that case one
991 * would call the <code>MPI_Reduce</code> function instead of the
992 * <code>MPI_Allreduce</code> function. The latter is at most twice as
993 * expensive, so if you are concerned about performance, it may be
994 * worthwhile investigating whether your algorithm indeed needs the result
995 * everywhere.
996 */
997 MinMaxAvg
998 min_max_avg(const double my_value, const MPI_Comm mpi_communicator);
999
1000 /**
1001 * Same as above but returning the sum, average, minimum, maximum,
1002 * process id of minimum and maximum as a @ref GlossCollectiveOperation "collective operation" on the
1003 * given MPI
1004 * @ref GlossMPICommunicator "communicator"
1005 * @p mpi_communicator for each entry of the vector.
1006 *
1007 * @note This function performs a single reduction sweep.
1008 *
1009 * @pre Size of the input vector has to be the same on all processes.
1010 */
1011 std::vector<MinMaxAvg>
1012 min_max_avg(const std::vector<double> &my_value,
1013 const MPI_Comm mpi_communicator);
1014
1015
1016 /**
1017 * Same as above but returning the sum, average, minimum, maximum,
1018 * process id of minimum and maximum as a @ref GlossCollectiveOperation "collective operation" on the
1019 * given MPI
1020 * @ref GlossMPICommunicator "communicator"
1021 * @p mpi_communicator for each entry of the ArrayView.
1022 *
1023 * @note This function performs a single reduction sweep.
1024 *
1025 * @pre Size of the input ArrayView has to be the same on all processes
1026 * and the input and output ArrayView have to have the same size.
1027 */
1028 void
1029 min_max_avg(const ArrayView<const double> &my_values,
1030 const ArrayView<MinMaxAvg> &result,
1031 const MPI_Comm mpi_communicator);
1032
1033
1034 /**
1035 * A class that is used to initialize the MPI system at the beginning of a
1036 * program and to shut it down again at the end. It also allows you to
1037 * control the number of threads used within each MPI process.
1038 *
1039 * If deal.II is configured with PETSc, PETSc will be initialized
1040 * via `PetscInitialize` in the beginning (constructor of this
1041 * class) and de-initialized via `PetscFinalize` at the end (i.e.,
1042 * in the destructor of this class). The same is true for SLEPc.
1043 *
1044 * If deal.II is configured with p4est, that library will also be
1045 * initialized in the beginning, and de-initialized at the end
1046 * (by calling sc_init(), p4est_init(), and sc_finalize()).
1047 *
1048 * If a program uses MPI one would typically just create an object
1049 * of this type at the beginning of <code>main()</code>. The
1050 * constructor of this class then runs <code>MPI_Init()</code>
1051 * with the given arguments and also initializes the other
1052 * libraries mentioned above. At the end of the program, the
1053 * compiler will invoke the destructor of this object which in
1054 * turns calls <code>MPI_Finalize</code> to shut down the MPI
1055 * system.
1056 *
1057 * This class is used in step-17, step-18, step-40, step-32, and
1058 * several others.
1059 *
1060 * @note This class performs initialization of the MPI subsystem
1061 * as well as the dependent libraries listed above through the
1062 * `MPI_COMM_WORLD` communicator. This means that you will have to
1063 * create an MPI_InitFinalize object on <i>all</i> MPI processes,
1064 * whether or not you intend to use deal.II on a given
1065 * processor. In most use cases, one will of course want to work
1066 * on all MPI processes using essentially the same program, and so
1067 * this is not an issue. But if you plan to run deal.II-based work
1068 * on only a subset of MPI processes, using an
1069 * @ref GlossMPICommunicator "MPI communicator" that is a subset of
1070 * `MPI_COMM_WORLD` (for example, in client-server settings where
1071 * only a subset of processes is responsible for the finite
1072 * element communications and the remaining processes do other
1073 * things), then you still need to create this object here on all
1074 * MPI processes at the beginning of the program because it uses
1075 * `MPI_COMM_WORLD` during initialization.
1076 */
1077 class MPI_InitFinalize : public InitFinalize
1078 {
1079 public:
1080 /**
1081 * Initialize MPI (and, if deal.II was configured to use it, PETSc) and
1082 * set the number of threads used by deal.II (via the underlying
1083 * Threading Building Blocks library) to the given parameter.
1084 *
1085 * @param[in,out] argc A reference to the 'argc' argument passed to
1086 * main. This argument is used to initialize MPI (and, possibly, PETSc)
1087 * as they read arguments from the command line.
1088 * @param[in,out] argv A reference to the 'argv' argument passed to
1089 * main.
1090 * @param[in] max_num_threads The maximal number of threads this MPI
1091 * process should utilize. If this argument is set to
1092 * numbers::invalid_unsigned_int (the default value), then the number of
1093 * threads is determined automatically in the following way: the number
1094 * of threads to run on this MPI process is set in such a way that all
1095 * of the cores in your node are spoken for. In other words, if you have
1096 * started one MPI process per node, setting this argument is equivalent
1097 * to setting it to the number of cores present in the node this MPI
1098 * process runs on. If you have started as many MPI processes per node
1099 * as there are cores on each node, then this is equivalent to passing 1
1100 * as the argument. On the other hand, if, for example, you start 4 MPI
1101 * processes on each 16-core node, then this option will start 4 worker
1102 * threads for each node. If you start 3 processes on an 8 core node,
1103 * then they will start 3, 3 and 2 threads, respectively.
1104 *
1105 * @note This function calls MultithreadInfo::set_thread_limit() with
1106 * either @p max_num_threads or, following the discussion above, a
1107 * number of threads equal to the number of cores allocated to this MPI
1108 * process. However, MultithreadInfo::set_thread_limit() in turn also
1109 * evaluates the environment variable DEAL_II_NUM_THREADS. Finally, the
1110 * worker threads can only be created on cores to which the current MPI
1111 * process has access to; some MPI implementations limit the number of
1112 * cores each process may access to one or a subset of cores in order to
1113 * ensure better cache behavior. Consequently, the number of threads
1114 * that will really be created will be the minimum of the argument
1115 * passed here, the environment variable (if set), and the number of
1116 * cores accessible to the thread.
1117 *
1118 * @note MultithreadInfo::set_thread_limit() can only work if it is
1119 * called before any threads are created. The safest place for a call to
1120 * it is therefore at the beginning of <code>main()</code>.
1121 * Consequently, this extends to the current class: the best place to
1122 * create an object of this type is also at or close to the top of
1123 * <code>main()</code>.
1124 */
1125 MPI_InitFinalize(
1126 int &argc,
1127 char **&argv,
1128 const unsigned int max_num_threads = numbers::invalid_unsigned_int);
1129
1130 /**
1131 * Destructor. Calls <tt>MPI_Finalize()</tt> in case this class owns the
1132 * MPI process.
1133 */
1134 ~MPI_InitFinalize() = default;
1135 };
1136
1137 /**
1138 * Return whether (i) deal.II has been compiled to support MPI (for
1139 * example by compiling with <code>CXX=mpiCC</code>) and if so whether
1140 * (ii) <code>MPI_Init()</code> has been called (for example using the
1141 * Utilities::MPI::MPI_InitFinalize class). In other words, the result
1142 * indicates whether the current job is running under MPI.
1143 *
1144 * @note The function does not take into account whether an MPI job
1145 * actually runs on more than one processor or is, in fact, a single-node
1146 * job that happens to run under MPI.
1147 */
1148 bool
1149 job_supports_mpi();
1150
1151 /**
1152 * Initiate a some-to-some communication, and exchange arbitrary objects
1153 * (the class T should be serializable using boost::serialize) between
1154 * processors.
1155 *
1156 * @param[in] comm MPI communicator.
1157 *
1158 * @param[in] objects_to_send A map from the rank (unsigned int) of the
1159 * process meant to receive the data and the object to send (the type `T`
1160 * must be serializable for this function to work properly). If this
1161 * map contains an entry with a key equal to the rank of the current
1162 * process (i.e., an instruction to a process to send data to itself),
1163 * then this data item is simply copied to the returned object.
1164 *
1165 * @return A map from the rank (unsigned int) of the process
1166 * which sent the data and object received.
1167 */
1168 template <typename T>
1169 std::map<unsigned int, T>
1170 some_to_some(const MPI_Comm comm,
1171 const std::map<unsigned int, T> &objects_to_send);
1172
1173 /**
1174 * A generalization of the classic MPI_Allgather function, that accepts
1175 * arbitrary data types T, as long as boost::serialize accepts T as an
1176 * argument.
1177 *
1178 * @param[in] comm MPI communicator.
1179 * @param[in] object_to_send An object to send to all other processes
1180 *
1181 * @return A vector of objects, with size equal to the number of
1182 * processes in the MPI communicator. Each entry contains the object
1183 * received from the processor with the corresponding rank within the
1184 * communicator.
1185 */
1186 template <typename T>
1187 [[nodiscard]] std::vector<T>
1188 all_gather(const MPI_Comm comm, const T &object_to_send);
1189
1190 /**
1191 * A generalization of the classic MPI_Gather function, that accepts
1192 * arbitrary data types T, as long as boost::serialize accepts T as an
1193 * argument.
1194 *
1195 * @param[in] comm MPI communicator.
1196 * @param[in] object_to_send an object to send to the root process
1197 * @param[in] root_process The process, which receives the objects from all
1198 * processes. By default the process with rank 0 is the root process.
1199 *
1200 * @return The @p root_process receives a vector of objects, with size equal to the number of
1201 * processes in the MPI communicator. Each entry contains the object
1202 * received from the processor with the corresponding rank within the
1203 * communicator. All other processes receive an empty vector.
1204 */
1205 template <typename T>
1206 [[nodiscard]] std::vector<T>
1207 gather(const MPI_Comm comm,
1208 const T &object_to_send,
1209 const unsigned int root_process = 0);
1210
1211 /**
1212 * A generalization of the classic MPI_Scatter function, that accepts
1213 * arbitrary data types T, as long as boost::serialize accepts T as an
1214 * argument.
1215 *
1216 * @param[in] comm MPI communicator.
1217 * @param[in] objects_to_send A vector of objects to send from the root
1218 * process, with size equal to the number of processes. On all other
1219 * processes the vector is empty.
1220 * @param[in] root_process The process, which sends the objects to all
1221 * processes. By default the process with rank 0 is the root process.
1222 *
1223 * @return Every process receives an object from the root_process.
1224 */
1225 template <typename T>
1226 [[nodiscard]] T
1227 scatter(const MPI_Comm comm,
1228 const std::vector<T> &objects_to_send,
1229 const unsigned int root_process = 0);
1230
1231 /**
1232 * This function sends an object @p object_to_send from the process @p
1233 * root_process to all other processes.
1234 *
1235 * This function is a generalization of the classic `MPI_Bcast` function
1236 * that accepts arbitrary data types `T`. If `T` is an MPI type then this
1237 * function immediately calls `MPI_Bcast`. Otherwise it will serialize and
1238 * deserialize the object by calling `object_to_send.serialize()`. If T is
1239 * not an MPI type and also does not define that member function then this
1240 * template will not compile.
1241 *
1242 * If you have an array of objects natively supported by MPI (e.g., `int`s
1243 * or `double`s) to broadcast then you should use the broadcast() function
1244 * in this namespace which takes pointer and count arguments.
1245 *
1246 * @param[in] comm MPI communicator.
1247 * @param[in] object_to_send An object to send to all processes.
1248 * @param[in] root_process The process that sends the object to all
1249 * processes. By default the process with rank 0 is the root process.
1250 *
1251 * @tparam T A type which is either a natively supported MPI type or a type
1252 * for which the Utilities::pack() and Utilities::unpack() functions can
1253 * be used to convert the object into an array of `char`.
1254 *
1255 * @return On the root process, return a copy of @p object_to_send.
1256 * On every other process, return a copy of the object sent by
1257 * the @p root_process.
1258 *
1259 * @warning For non-MPI types (e.g., any kind of class such as std::map or
1260 * Tensor) this function is typically a lot more expensive than an a single
1261 * call to `MPI_Bcast` because it will use boost::serialization to serialize
1262 * @p object_to_send, execute a first `MPI_Bcast` to transmit the size of
1263 * the serialized object, execute a second `MPI_Bcast` to broadcast the
1264 * serialized object, and then deserialize and return. On the other hand, if
1265 * you have a single element of a data type `T` which is natively supported
1266 * by MPI, then this function will skip all of those steps and simply call
1267 * `MPI_Bcast` and return the result.
1268 */
1269 template <typename T>
1270 [[nodiscard]] T
1271 broadcast(const MPI_Comm comm,
1272 const T &object_to_send,
1273 const unsigned int root_process = 0);
1274
1275 /**
1276 * Broadcast the information in @p buffer from @p root to all
1277 * other ranks.
1278 *
1279 * Like `MPI_Bcast` but with support to send data with a @p count
1280 * bigger than 2^31. The datatype to send needs to be supported
1281 * directly by MPI and is automatically deduced from T.
1282 *
1283 * Throws an exception if any MPI command fails.
1284 *
1285 * @param buffer Buffer of @p count objects.
1286 * @param count The number of objects to send. All processes need
1287 * to specify the correct size.
1288 * @param root The rank of the process with the data.
1289 * @param comm The MPI communicator to use.
1290 */
1291 template <typename T>
1292 void
1293 broadcast(T *buffer,
1294 const std::size_t count,
1295 const unsigned int root,
1296 const MPI_Comm comm);
1297
1298 /**
1299 * A function that combines values @p local_value from all processes
1300 * via a user-specified binary operation @p combiner on the @p root_process.
1301 * As such this function is similar to MPI_Reduce (and
1302 * Utilities::MPI::min/max()): however on the one hand due to the
1303 * user-specified binary operation it is slower for built-in types but
1304 * on the other hand general object types, including ones that store
1305 * variable amounts of data, can be handled.
1306 *
1307 * In contrast to all_reduce, the result will be only available on a
1308 * single rank. On all other processes, the returned value is undefined.
1309 */
1310 template <typename T>
1311 [[nodiscard]] T
1312 reduce(const T &local_value,
1313 const MPI_Comm comm,
1314 const std::function<T(const T &, const T &)> &combiner,
1315 const unsigned int root_process = 0);
1316
1317
1318 /**
1319 * For each process $p$ on a communicator with $P$ processes, compute both
1320 * the (exclusive) partial sum $\sum_{i=0}^{p-1} v_i$ and the total
1321 * sum $\sum_{i=0}^{P-1} v_i$, and return these two values as a pair.
1322 * The former is computed via the `MPI_Exscan` function where the partial
1323 * sum is typically called "(exclusive) scan" of the values $v_p$ provided
1324 * by the individual processes. The term "prefix sum" is also used.
1325 *
1326 * This function is only available if `T` is a type natively supported
1327 * by MPI.
1328 */
1329 template <typename T, typename = std::enable_if_t<is_mpi_type<T> == true>>
1330 [[nodiscard]] std::pair<T, T>
1331 partial_and_total_sum(const T &value, const MPI_Comm comm);
1332
1333
1334 /**
1335 * A function that combines values @p local_value from all processes
1336 * via a user-specified binary operation @p combiner and distributes the
1337 * result back to all processes. As such this function is similar to
1338 * MPI_Allreduce (if it were implemented by a global reduction followed
1339 * by a broadcast step) but due to the user-specified binary operation also
1340 * general object types, including ones that store variable amounts of data,
1341 * can be handled.
1342 */
1343 template <typename T>
1344 [[nodiscard]] T
1345 all_reduce(const T &local_value,
1346 const MPI_Comm comm,
1347 const std::function<T(const T &, const T &)> &combiner);
1348
1349
1350 /**
1351 * A function that takes a given argument `object` and, using MPI,
1352 * sends it to MPI process indicated by the given `target_rank`.
1353 * This function is "immediate" (corresponding to the `MPI_Isend`
1354 * function), i.e., it immediately returns rather than waiting
1355 * for the send operation to succeed. Instead, it returns a
1356 * Future object that can be used to wait for the send operation
1357 * to complete.
1358 *
1359 * Unlike `MPI_Isend`, the object to be sent does not need to
1360 * have a lifetime that extends until the send operation is
1361 * complete. As a consequence, the first argument to this function
1362 * may be a temporary variable (such as the result of another
1363 * function call). That is because the object is internally
1364 * packaged into a buffer whose lifetime is automatically
1365 * managed. Using the buffer enables sending arbitrary objects,
1366 * not just those natively supported by MPI. The only restriction
1367 * on the type is that it needs to be possible to call
1368 * Utilities::pack() and Utilities::unpack() on the object.
1369 */
1370 template <typename T>
1371 Future<void>
1372 isend(const T &object,
1373 MPI_Comm communicator,
1374 const unsigned int target_rank,
1375 const unsigned int mpi_tag = 0);
1376
1377
1378 /**
1379 * A function that encodes an MPI "receive" function for an object
1380 * whose type is represented by the template argument. The object
1381 * is expected to be sent by the MPI process indicated by the given
1382 * `source_rank`. This function is "immediate" (corresponding to the
1383 * `MPI_Irecv` or a variant of this function),
1384 * i.e., it immediately returns rather than waiting
1385 * for the receive operation to succeed. Instead, it returns a
1386 * Future object that can be used to wait for the send operation
1387 * to complete, and then to obtain the object received via the
1388 * Future::get() function.
1389 *
1390 * Unlike `MPI_Irecv`, the object to be received may be of any
1391 * type on which one can call Utilities::pack() and Utilities::unpack(),
1392 * not just those natively supported by MPI.
1393 */
1394 template <typename T>
1395 Future<T>
1396 irecv(MPI_Comm communicator,
1397 const unsigned int source_rank,
1398 const unsigned int mpi_tag = 0);
1399
1400
1401 /**
1402 * Given a partitioned index set space, compute the owning MPI process rank
1403 * of each element of a second index set according to the partitioned index
1404 * set. A natural usage of this function is to compute for each ghosted
1405 * degree of freedom the MPI rank of the process owning that index.
1406 *
1407 * One might think: "But we know which rank a ghost DoF belongs to based on
1408 * the subdomain id of the cell it is on". But this heuristic fails for DoFs
1409 * on interfaces between ghost cells with different subdomain_ids, or
1410 * between a ghost cell and an artificial cell. Furthermore, this function
1411 * enables a completely abstract exchange of information without the help of
1412 * the mesh in terms of neighbors.
1413 *
1414 * The first argument passed to this function, @p owned_indices, must
1415 * uniquely partition an index space between all processes.
1416 * Otherwise, there are no limitations on this argument: In particular,
1417 * there is no need in partitioning
1418 * the index space into contiguous subsets. Furthermore, there are no
1419 * limitations
1420 * on the second index set @p indices_to_look_up as long as the size matches
1421 * the first one. It can be chosen arbitrarily and independently on each
1422 * process. In the case that the second index set also contains locally
1423 * owned indices, these indices will be treated correctly and the rank of
1424 * this process is returned for those entries.
1425 *
1426 * @note This is a @ref GlossCollectiveOperation "collective operation":
1427 * all processes within the given
1428 * communicator have to call this function. Since this function does not
1429 * use MPI_Alltoall or MPI_Allgather, but instead uses non-blocking
1430 * point-to-point communication instead, and only a single non-blocking
1431 * barrier, it reduces the memory consumption significantly. This function
1432 * is suited for large-scale simulations with >100k MPI ranks.
1433 *
1434 * @param[in] owned_indices Index set with indices locally owned by this
1435 * process.
1436 * @param[in] indices_to_look_up Index set containing indices of which the
1437 * user is interested the rank of the owning process.
1438 * @param[in] comm MPI communicator.
1439 *
1440 * @return List containing the MPI process rank for each entry in the index
1441 * set @p indices_to_look_up. The order coincides with the order
1442 * within the ElementIterator.
1443 */
1444 std::vector<unsigned int>
1445 compute_index_owner(const IndexSet &owned_indices,
1446 const IndexSet &indices_to_look_up,
1447 const MPI_Comm comm);
1448
1449 /**
1450 * Just like the function above, this function computes the owning MPI
1451 * process rank of each element of a second index set according to the
1452 * partitioned index set, given a partitioned index set space. In addition,
1453 * it returns a map of processes and associated sets of indices that are
1454 * requested from the current rank. In other words, this function returns
1455 * for each rank that has requested indices owned by the current rank
1456 * those indices that have been queried. The values of the map are
1457 * therefore all index sets describing subsets of the owned set of indices.
1458 */
1459 std::pair<std::vector<unsigned int>, std::map<unsigned int, IndexSet>>
1460 compute_index_owner_and_requesters(const IndexSet &owned_indices,
1461 const IndexSet &indices_to_look_up,
1462 const MPI_Comm &comm);
1463
1464 /**
1465 * Compute the union of the input vectors @p vec of all processes in the
1466 * MPI communicator @p comm.
1467 *
1468 * @note This is a @ref GlossCollectiveOperation "collective operation". The result will available on all
1469 * processes.
1470 */
1471 template <typename T>
1472 std::vector<T>
1473 compute_set_union(const std::vector<T> &vec, const MPI_Comm comm);
1474
1475 /**
1476 * The same as above but for std::set.
1477 */
1478 template <typename T>
1479 std::set<T>
1480 compute_set_union(const std::set<T> &set, const MPI_Comm comm);
1481
1482
1483
1484 /* --------------------------- inline functions ------------------------- */
1485
1486 namespace internal
1487 {
1488 /**
1489 * Given a pointer to an object of class T, the functions in this
1490 * namespace return the matching
1491 * `MPI_Datatype` to be used for MPI communication.
1492 */
1493 namespace MPIDataTypes
1494 {
1495 #ifdef DEAL_II_WITH_MPI
1496 inline MPI_Datatype
1497 mpi_type_id(const bool *)
1498 {
1499 return MPI_CXX_BOOL;
1500 }
1501
1502
1503
1504 inline MPI_Datatype
1505 mpi_type_id(const char *)
1506 {
1507 return MPI_CHAR;
1508 }
1509
1510
1511
1512 inline MPI_Datatype
1513 mpi_type_id(const signed char *)
1514 {
1515 return MPI_SIGNED_CHAR;
1516 }
1517
1518
1519
1520 inline MPI_Datatype
1521 mpi_type_id(const wchar_t *)
1522 {
1523 return MPI_WCHAR;
1524 }
1525
1526
1527
1528 inline MPI_Datatype
1529 mpi_type_id(const short *)
1530 {
1531 return MPI_SHORT;
1532 }
1533
1534
1535
1536 inline MPI_Datatype
1537 mpi_type_id(const int *)
1538 {
1539 return MPI_INT;
1540 }
1541
1542
1543
1544 inline MPI_Datatype
1545 mpi_type_id(const long int *)
1546 {
1547 return MPI_LONG;
1548 }
1549
1550
1551
1552 inline MPI_Datatype
1553 mpi_type_id(const long long int *)
1554 {
1555 return MPI_LONG_LONG;
1556 }
1557
1558
1559
1560 inline MPI_Datatype
1561 mpi_type_id(const unsigned char *)
1562 {
1563 return MPI_UNSIGNED_CHAR;
1564 }
1565
1566
1567
1568 inline MPI_Datatype
1569 mpi_type_id(const unsigned short *)
1570 {
1571 return MPI_UNSIGNED_SHORT;
1572 }
1573
1574
1575
1576 inline MPI_Datatype
1577 mpi_type_id(const unsigned int *)
1578 {
1579 return MPI_UNSIGNED;
1580 }
1581
1582
1583
1584 inline MPI_Datatype
1585 mpi_type_id(const unsigned long int *)
1586 {
1587 return MPI_UNSIGNED_LONG;
1588 }
1589
1590
1591
1592 inline MPI_Datatype
1593 mpi_type_id(const unsigned long long int *)
1594 {
1595 return MPI_UNSIGNED_LONG_LONG;
1596 }
1597
1598
1599
1600 inline MPI_Datatype
1601 mpi_type_id(const float *)
1602 {
1603 return MPI_FLOAT;
1604 }
1605
1606
1607
1608 inline MPI_Datatype
1609 mpi_type_id(const double *)
1610 {
1611 return MPI_DOUBLE;
1612 }
1613
1614
1615
1616 inline MPI_Datatype
1617 mpi_type_id(const long double *)
1618 {
1619 return MPI_LONG_DOUBLE;
1620 }
1621
1622
1623
1624 inline MPI_Datatype
1625 mpi_type_id(const std::complex<float> *)
1626 {
1627 return MPI_COMPLEX;
1628 }
1629
1630
1631
1632 inline MPI_Datatype
1633 mpi_type_id(const std::complex<double> *)
1634 {
1635 return MPI_DOUBLE_COMPLEX;
1636 }
1637 #endif
1638 } // namespace MPIDataTypes
1639 } // namespace internal
1640
1641
1642
1643 #ifdef DEAL_II_WITH_MPI
1644 /**
1645 * A template variable that translates from the data type given as
1646 * template argument to the corresponding
1647 * `MPI_Datatype` to be used for MPI communication.
1648 *
1649 * As an example, the value of `mpi_type_id_for_type<int>` is `MPI_INT`. A
1650 * common way to use this variable is when sending an object `obj`
1651 * via MPI functions to another process, and using
1652 * `mpi_type_id_for_type<decltype(obj)>` to infer the correct MPI type to
1653 * use for the communication.
1654 *
1655 * The type `T` given here must be one of the data types supported
1656 * by MPI, such as `int` or `double`. It may not be an array of
1657 * objects of such a type, or a pointer to an object of such a
1658 * type. The compiler will produce an error if this requirement is
1659 * not satisfied.
1660 */
1661 template <typename T>
1662 inline const MPI_Datatype mpi_type_id_for_type =
1663 internal::MPIDataTypes::mpi_type_id(
1664 static_cast<std::remove_cv_t<std::remove_reference_t<T>> *>(nullptr));
1665 #endif
1666
1667 #ifndef DOXYGEN
1668 namespace internal
1669 {
1670 // declaration for an internal function that lives in mpi.templates.h
1671 template <typename T>
1672 void
1673 all_reduce(const MPI_Op &mpi_op,
1674 const ArrayView<const T> &values,
1675 const MPI_Comm mpi_communicator,
1676 const ArrayView<T> &output);
1677 } // namespace internal
1678
1679
1680 template <typename T>
1681 template <typename W, typename G>
1682 Future<T>::Future(W &&wait_operation, G &&get_and_cleanup_operation)
1683 : wait_function(wait_operation)
1684 , get_and_cleanup_function(get_and_cleanup_operation)
1685 , is_done(false)
1686 , get_was_called(false)
1687 {}
1688
1689
1690
1691 template <typename T>
1692 Future<T>::~Future()
1693 {
1694 // If there is a clean-up function, and if it has not been
1695 // called yet, then do so. Note that we may not have a
1696 // clean-up function (not even an empty one) if the current
1697 // object has been moved from, into another object, and as
1698 // a consequence the std::function objects are now empty
1699 // even though they were initialized in the constructor.
1700 // (A std::function object whose object is a an empty lambda
1701 // function, [](){}, is not an empty std::function object.)
1702 if ((get_was_called == false) && get_and_cleanup_function)
1703 get();
1704 }
1705
1706
1707
1708 template <typename T>
1709 void
1710 Future<T>::wait()
1711 {
1712 if (is_done == false)
1713 {
1714 wait_function();
1715
1716 is_done = true;
1717 }
1718 }
1719
1720
1721 template <typename T>
1722 T
1723 Future<T>::get()
1724 {
1725 Assert(get_was_called == false,
1726 ExcMessage(
1727 "You can't call get() more than once on a Future object."));
1728 get_was_called = true;
1729
1730 wait();
1731 return get_and_cleanup_function();
1732 }
1733
1734
1735
1736 template <typename T, unsigned int N>
1737 void
1738 sum(const T (&values)[N], const MPI_Comm mpi_communicator, T (&sums)[N])
1739 {
1740 internal::all_reduce(MPI_SUM,
1741 ArrayView<const T>(values, N),
1742 mpi_communicator,
1743 ArrayView<T>(sums, N));
1744 }
1745
1746
1747
1748 template <typename T, unsigned int N>
1749 void
1750 max(const T (&values)[N], const MPI_Comm mpi_communicator, T (&maxima)[N])
1751 {
1752 internal::all_reduce(MPI_MAX,
1753 ArrayView<const T>(values, N),
1754 mpi_communicator,
1755 ArrayView<T>(maxima, N));
1756 }
1757
1758
1759
1760 template <typename T, unsigned int N>
1761 void
1762 min(const T (&values)[N], const MPI_Comm mpi_communicator, T (&minima)[N])
1763 {
1764 internal::all_reduce(MPI_MIN,
1765 ArrayView<const T>(values, N),
1766 mpi_communicator,
1767 ArrayView<T>(minima, N));
1768 }
1769
1770
1771
1772 template <typename T, unsigned int N>
1773 void
1774 logical_or(const T (&values)[N],
1775 const MPI_Comm mpi_communicator,
1776 T (&results)[N])
1777 {
1778 static_assert(std::is_integral_v<T>,
1779 "The MPI_LOR operation only allows integral data types.");
1780
1781 internal::all_reduce(MPI_LOR,
1782 ArrayView<const T>(values, N),
1783 mpi_communicator,
1784 ArrayView<T>(results, N));
1785 }
1786
1787
1788
1789 template <typename T>
1790 std::map<unsigned int, T>
1791 some_to_some(const MPI_Comm comm,
1792 const std::map<unsigned int, T> &objects_to_send)
1793 {
1794 # ifndef DEAL_II_WITH_MPI
1795 (void)comm;
1796 Assert(objects_to_send.size() < 2,
1797 ExcMessage("Cannot send to more than one processor."));
1798 Assert(objects_to_send.find(0) != objects_to_send.end() ||
1799 objects_to_send.empty(),
1800 ExcMessage("Can only send to myself or to nobody."));
1801 return objects_to_send;
1802 # else
1803 const auto my_proc = this_mpi_process(comm);
1804
1805 std::map<unsigned int, T> received_objects;
1806
1807 std::vector<unsigned int> send_to;
1808 send_to.reserve(objects_to_send.size());
1809 for (const auto &m : objects_to_send)
1810 if (m.first == my_proc)
1811 received_objects[my_proc] = m.second;
1812 else
1813 send_to.emplace_back(m.first);
1814
1815 const unsigned int n_expected_incoming_messages =
1816 Utilities::MPI::compute_n_point_to_point_communications(comm, send_to);
1817
1818 // Protect the following communication:
1819 static CollectiveMutex mutex;
1820 CollectiveMutex::ScopedLock lock(mutex, comm);
1821
1822 // If we have something to send, or we expect something from other
1823 // processors, we need to visit one of the two scopes below. Otherwise,
1824 // no other action is required by this mpi process, and we can safely
1825 // return.
1826 if (send_to.empty() && n_expected_incoming_messages == 0)
1827 return received_objects;
1828
1829 const int mpi_tag =
1830 internal::Tags::compute_point_to_point_communication_pattern;
1831
1832 // Sending buffers
1833 std::vector<std::vector<char>> buffers_to_send(send_to.size());
1834 std::vector<MPI_Request> buffer_send_requests(send_to.size());
1835 {
1836 unsigned int i = 0;
1837 for (const auto &rank_obj : objects_to_send)
1838 if (rank_obj.first != my_proc)
1839 {
1840 const auto &rank = rank_obj.first;
1841 buffers_to_send[i] = Utilities::pack(rank_obj.second,
1842 /*allow_compression=*/false);
1843 const int ierr = MPI_Isend(buffers_to_send[i].data(),
1844 buffers_to_send[i].size(),
1845 MPI_CHAR,
1846 rank,
1847 mpi_tag,
1848 comm,
1849 &buffer_send_requests[i]);
1850 AssertThrowMPI(ierr);
1851 ++i;
1852 }
1853 }
1854
1855 // Fill the output map
1856 {
1857 std::vector<char> buffer;
1858 // We do this on a first come/first served basis
1859 for (unsigned int i = 0; i < n_expected_incoming_messages; ++i)
1860 {
1861 // Probe what's going on. Take data from the first available sender
1862 MPI_Status status;
1863 int ierr = MPI_Probe(MPI_ANY_SOURCE, mpi_tag, comm, &status);
1864 AssertThrowMPI(ierr);
1865
1866 // Length of the message
1867 int len;
1868 ierr = MPI_Get_count(&status, MPI_CHAR, &len);
1869 AssertThrowMPI(ierr);
1870 buffer.resize(len);
1871
1872 // Source rank
1873 const unsigned int rank = status.MPI_SOURCE;
1874
1875 // Actually receive the message
1876 ierr = MPI_Recv(buffer.data(),
1877 len,
1878 MPI_CHAR,
1879 status.MPI_SOURCE,
1880 status.MPI_TAG,
1881 comm,
1882 MPI_STATUS_IGNORE);
1883 AssertThrowMPI(ierr);
1884 Assert(received_objects.find(rank) == received_objects.end(),
1885 ExcInternalError(
1886 "I should not receive again from this rank"));
1887 received_objects[rank] =
1888 Utilities::unpack<T>(buffer,
1889 /*allow_compression=*/false);
1890 }
1891 }
1892
1893 // Wait to have sent all objects.
1894 const int ierr = MPI_Waitall(send_to.size(),
1895 buffer_send_requests.data(),
1896 MPI_STATUSES_IGNORE);
1897 AssertThrowMPI(ierr);
1898
1899 return received_objects;
1900 # endif // deal.II with MPI
1901 }
1902
1903
1904
1905 template <typename T, typename>
1906 std::pair<T, T>
1907 partial_and_total_sum(const T &value, const MPI_Comm comm)
1908 {
1909 # ifndef DEAL_II_WITH_MPI
1910 (void)comm;
1911 return {0, value};
1912 # else
1913 if (Utilities::MPI::n_mpi_processes(comm) == 1)
1914 return {0, value};
1915 else
1916 {
1917 T prefix = {};
1918
1919 // First obtain every process's prefix sum:
1920 int ierr =
1921 MPI_Exscan(&value,
1922 &prefix,
1923 1,
1924 Utilities::MPI::mpi_type_id_for_type<decltype(value)>,
1925 MPI_SUM,
1926 comm);
1927 AssertThrowMPI(ierr);
1928
1929 // Then we also need the total sum. We could obtain it by
1930 // calling Utilities::MPI::sum(), but it is cheaper if we
1931 // broadcast it from the last process, which can compute it
1932 // from its own prefix sum plus its own value.
1933 const T sum = Utilities::MPI::broadcast(
1934 comm, prefix + value, Utilities::MPI::n_mpi_processes(comm) - 1);
1935
1936 return {prefix, sum};
1937 }
1938 # endif
1939 }
1940
1941
1942
1943 template <typename T>
1944 std::vector<T>
1945 all_gather(const MPI_Comm comm, const T &object)
1946 {
1947 if (job_supports_mpi() == false)
1948 return {object};
1949
1950 # ifndef DEAL_II_WITH_MPI
1951 (void)comm;
1952 std::vector<T> v(1, object);
1953 return v;
1954 # else
1955 const auto n_procs = dealii::Utilities::MPI::n_mpi_processes(comm);
1956
1957 std::vector<char> buffer = Utilities::pack(object);
1958
1959 int n_local_data = buffer.size();
1960
1961 // Vector to store the size of loc_data_array for every process
1962 std::vector<int> size_all_data(n_procs, 0);
1963
1964 // Exchanging the size of each buffer
1965 int ierr = MPI_Allgather(
1966 &n_local_data, 1, MPI_INT, size_all_data.data(), 1, MPI_INT, comm);
1967 AssertThrowMPI(ierr);
1968
1969 // Now computing the displacement, relative to recvbuf,
1970 // at which to store the incoming buffer
1971 std::vector<int> rdispls(n_procs);
1972 rdispls[0] = 0;
1973 for (unsigned int i = 1; i < n_procs; ++i)
1974 rdispls[i] = rdispls[i - 1] + size_all_data[i - 1];
1975
1976 // Step 3: exchange the buffer:
1977 std::vector<char> received_unrolled_buffer(rdispls.back() +
1978 size_all_data.back());
1979
1980 ierr = MPI_Allgatherv(buffer.data(),
1981 n_local_data,
1982 MPI_CHAR,
1983 received_unrolled_buffer.data(),
1984 size_all_data.data(),
1985 rdispls.data(),
1986 MPI_CHAR,
1987 comm);
1988 AssertThrowMPI(ierr);
1989
1990 std::vector<T> received_objects(n_procs);
1991 for (unsigned int i = 0; i < n_procs; ++i)
1992 {
1993 std::vector<char> local_buffer(received_unrolled_buffer.begin() +
1994 rdispls[i],
1995 received_unrolled_buffer.begin() +
1996 rdispls[i] + size_all_data[i]);
1997 received_objects[i] = Utilities::unpack<T>(local_buffer);
1998 }
1999
2000 return received_objects;
2001 # endif
2002 }
2003
2004
2005
2006 template <typename T>
2007 std::vector<T>
2008 gather(const MPI_Comm comm,
2009 const T &object_to_send,
2010 const unsigned int root_process)
2011 {
2012 # ifndef DEAL_II_WITH_MPI
2013 (void)comm;
2014 (void)root_process;
2015 std::vector<T> v(1, object_to_send);
2016 return v;
2017 # else
2018 const auto n_procs = dealii::Utilities::MPI::n_mpi_processes(comm);
2019 const auto my_rank = dealii::Utilities::MPI::this_mpi_process(comm);
2020
2021 AssertIndexRange(root_process, n_procs);
2022
2023 std::vector<char> buffer = Utilities::pack(object_to_send);
2024 int n_local_data = buffer.size();
2025
2026 // Vector to store the size of loc_data_array for every process
2027 // only the root process needs to allocate memory for that purpose
2028 std::vector<int> size_all_data;
2029 if (my_rank == root_process)
2030 size_all_data.resize(n_procs, 0);
2031
2032 // Exchanging the size of each buffer
2033 int ierr = MPI_Gather(&n_local_data,
2034 1,
2035 MPI_INT,
2036 size_all_data.data(),
2037 1,
2038 MPI_INT,
2039 root_process,
2040 comm);
2041 AssertThrowMPI(ierr);
2042
2043 // Now computing the displacement, relative to recvbuf,
2044 // at which to store the incoming buffer; only for root
2045 std::vector<int> rdispls;
2046 if (my_rank == root_process)
2047 {
2048 rdispls.resize(n_procs, 0);
2049 for (unsigned int i = 1; i < n_procs; ++i)
2050 rdispls[i] = rdispls[i - 1] + size_all_data[i - 1];
2051 }
2052 // exchange the buffer:
2053 std::vector<char> received_unrolled_buffer;
2054 if (my_rank == root_process)
2055 received_unrolled_buffer.resize(rdispls.back() + size_all_data.back());
2056
2057 ierr = MPI_Gatherv(buffer.data(),
2058 n_local_data,
2059 MPI_CHAR,
2060 received_unrolled_buffer.data(),
2061 size_all_data.data(),
2062 rdispls.data(),
2063 MPI_CHAR,
2064 root_process,
2065 comm);
2066 AssertThrowMPI(ierr);
2067
2068 std::vector<T> received_objects;
2069
2070 if (my_rank == root_process)
2071 {
2072 received_objects.resize(n_procs);
2073
2074 for (unsigned int i = 0; i < n_procs; ++i)
2075 {
2076 const std::vector<char> local_buffer(
2077 received_unrolled_buffer.begin() + rdispls[i],
2078 received_unrolled_buffer.begin() + rdispls[i] +
2079 size_all_data[i]);
2080 received_objects[i] = Utilities::unpack<T>(local_buffer);
2081 }
2082 }
2083 return received_objects;
2084 # endif
2085 }
2086
2087
2088
2089 template <typename T>
2090 T
2091 scatter(const MPI_Comm comm,
2092 const std::vector<T> &objects_to_send,
2093 const unsigned int root_process)
2094 {
2095 # ifndef DEAL_II_WITH_MPI
2096 (void)comm;
2097 (void)root_process;
2098
2099 AssertDimension(objects_to_send.size(), 1);
2100
2101 return objects_to_send[0];
2102 # else
2103 const auto n_procs = dealii::Utilities::MPI::n_mpi_processes(comm);
2104 const auto my_rank = dealii::Utilities::MPI::this_mpi_process(comm);
2105
2106 AssertIndexRange(root_process, n_procs);
2107 AssertThrow(
2108 (my_rank != root_process && objects_to_send.empty()) ||
2109 objects_to_send.size() == n_procs,
2110 ExcMessage(
2111 "The number of objects to be scattered must correspond to the number processes."));
2112
2113 std::vector<char> send_buffer;
2114 std::vector<int> send_counts;
2115 std::vector<int> send_displacements;
2116
2117 if (my_rank == root_process)
2118 {
2119 send_counts.resize(n_procs, 0);
2120 send_displacements.resize(n_procs + 1, 0);
2121
2122 for (unsigned int i = 0; i < n_procs; ++i)
2123 {
2124 const auto packed_data = Utilities::pack(objects_to_send[i]);
2125 send_buffer.insert(send_buffer.end(),
2126 packed_data.begin(),
2127 packed_data.end());
2128 send_counts[i] = packed_data.size();
2129 }
2130
2131 for (unsigned int i = 0; i < n_procs; ++i)
2132 send_displacements[i + 1] = send_displacements[i] + send_counts[i];
2133 }
2134
2135 int n_local_data;
2136 int ierr = MPI_Scatter(send_counts.data(),
2137 1,
2138 MPI_INT,
2139 &n_local_data,
2140 1,
2141 MPI_INT,
2142 root_process,
2143 comm);
2144 AssertThrowMPI(ierr);
2145
2146 std::vector<char> recv_buffer(n_local_data);
2147
2148 ierr = MPI_Scatterv(send_buffer.data(),
2149 send_counts.data(),
2150 send_displacements.data(),
2151 MPI_CHAR,
2152 recv_buffer.data(),
2153 n_local_data,
2154 MPI_CHAR,
2155 root_process,
2156 comm);
2157 AssertThrowMPI(ierr);
2158
2159 return Utilities::unpack<T>(recv_buffer);
2160 # endif
2161 }
2162
2163
2164 template <typename T>
2165 void
2166 broadcast(T *buffer,
2167 const std::size_t count,
2168 const unsigned int root,
2169 const MPI_Comm comm)
2170 {
2171 # ifndef DEAL_II_WITH_MPI
2172 (void)buffer;
2173 (void)count;
2174 (void)root;
2175 (void)comm;
2176 # else
2177 Assert(root < n_mpi_processes(comm),
2178 ExcMessage("Invalid root rank specified."));
2179
2180 // MPI_Bcast's count is a signed int, so send at most 2^31 in each
2181 // iteration:
2182 const size_t max_send_count = std::numeric_limits<signed int>::max();
2183
2184 size_t total_sent_count = 0;
2185 while (total_sent_count < count)
2186 {
2187 const size_t current_count =
2188 std::min(count - total_sent_count, max_send_count);
2189
2190 const int ierr = MPI_Bcast(buffer + total_sent_count,
2191 current_count,
2192 mpi_type_id_for_type<decltype(*buffer)>,
2193 root,
2194 comm);
2195 AssertThrowMPI(ierr);
2196 total_sent_count += current_count;
2197 }
2198 # endif
2199 }
2200
2201
2202
2203 template <typename T>
2204 T
2205 broadcast(const MPI_Comm comm,
2206 const T &object_to_send,
2207 const unsigned int root_process)
2208 {
2209 # ifndef DEAL_II_WITH_MPI
2210 (void)comm;
2211 (void)root_process;
2212 return object_to_send;
2213 # else
2214 const auto n_procs = dealii::Utilities::MPI::n_mpi_processes(comm);
2215 AssertIndexRange(root_process, n_procs);
2216 (void)n_procs;
2217
2218 if constexpr (is_mpi_type<T>)
2219 {
2220 T object = object_to_send;
2221 int ierr =
2222 MPI_Bcast(&object, 1, mpi_type_id_for_type<T>, root_process, comm);
2223 AssertThrowMPI(ierr);
2224
2225 return object;
2226 }
2227 else
2228 {
2229 std::vector<char> buffer;
2230 std::size_t buffer_size = numbers::invalid_size_type;
2231
2232 // On the root process, pack the data and determine what the
2233 // buffer size needs to be.
2234 if (this_mpi_process(comm) == root_process)
2235 {
2236 buffer = Utilities::pack(object_to_send, false);
2237 buffer_size = buffer.size();
2238 }
2239
2240 // Exchange the size of buffer
2241 int ierr = MPI_Bcast(&buffer_size,
2242 1,
2243 mpi_type_id_for_type<decltype(buffer_size)>,
2244 root_process,
2245 comm);
2246 AssertThrowMPI(ierr);
2247
2248 // If not on the root process, correctly size the buffer to
2249 // receive the data, then do exactly that.
2250 if (this_mpi_process(comm) != root_process)
2251 buffer.resize(buffer_size);
2252
2253 broadcast(buffer.data(), buffer_size, root_process, comm);
2254
2255 if (Utilities::MPI::this_mpi_process(comm) == root_process)
2256 return object_to_send;
2257 else
2258 return Utilities::unpack<T>(buffer, false);
2259 }
2260 # endif
2261 }
2262
2263
2264
2265 template <typename T>
2266 Future<void>
2267 isend(const T &object,
2268 MPI_Comm communicator,
2269 const unsigned int target_rank,
2270 const unsigned int mpi_tag)
2271 {
2272 # ifndef DEAL_II_WITH_MPI
2273 Assert(false, ExcNeedsMPI());
2274 (void)object;
2275 (void)communicator;
2276 (void)target_rank;
2277 (void)mpi_tag;
2278 return Future<void>([]() {}, []() {});
2279 # else
2280 // Create a pointer to a send buffer into which we pack the object
2281 // to be sent. The buffer will be released by the Future object once
2282 // the send has been verified to have succeeded.
2283 //
2284 // Conceptually, we would like this send buffer to be a
2285 // std::unique_ptr object whose ownership is later handed over
2286 // to the cleanup function. That has the disadvantage that the
2287 // cleanup object is a non-copyable lambda capture, leading to
2288 // awkward semantics. Instead, we use a std::shared_ptr; we move
2289 // this shared pointer into the cleanup function, which means
2290 // that there is exactly one shared pointer who owns the buffer
2291 // at any given time, though the latter is not an important
2292 // optimization.
2293 std::shared_ptr<std::vector<char>> send_buffer =
2294 std::make_unique<std::vector<char>>(Utilities::pack(object, false));
2295
2296 // Now start the send, and store the result in a request object that
2297 // we can then wait for later:
2298 MPI_Request request;
2299 const int ierr =
2300 MPI_Isend(send_buffer->data(),
2301 send_buffer->size(),
2302 mpi_type_id_for_type<decltype(*send_buffer->data())>,
2303 target_rank,
2304 mpi_tag,
2305 communicator,
2306 &request);
2307 AssertThrowMPI(ierr);
2308
2309 // Then return a std::future-like object that has a wait()
2310 // function one can use to wait for the communication to finish,
2311 // and that has a cleanup function to be called at some point
2312 // after that makes sure the send buffer gets deallocated. This
2313 // cleanup function takes over ownership of the send buffer.
2314 //
2315 // Note that the body of the lambda function of the clean-up
2316 // function could be left empty. If that were so, once the
2317 // lambda function object goes out of scope, the 'send_buffer'
2318 // member of the closure object goes out of scope as well and so
2319 // the send_buffer is destroyed. But we may want to release the
2320 // buffer itself as early as possible, and so we clear the
2321 // buffer when the Future::get() function is called.
2322 auto wait = [request]() mutable {
2323 const int ierr = MPI_Wait(&request, MPI_STATUS_IGNORE);
2324 AssertThrowMPI(ierr);
2325 };
2326 auto cleanup = [send_buffer = std::move(send_buffer)]() {
2327 send_buffer->clear();
2328 };
2329 return Future<void>(wait, cleanup);
2330 # endif
2331 }
2332
2333
2334
2335 template <typename T>
2336 Future<T>
2337 irecv(MPI_Comm communicator,
2338 const unsigned int source_rank,
2339 const unsigned int mpi_tag)
2340 {
2341 # ifndef DEAL_II_WITH_MPI
2342 Assert(false, ExcNeedsMPI());
2343 (void)communicator;
2344 (void)source_rank;
2345 (void)mpi_tag;
2346 return Future<void>([]() {}, []() { return T{}; });
2347 # else
2348 // Use a 'probe' operation for the 'wait' operation of the
2349 // Future this function returns. It will trigger whenever we get
2350 // the incoming message. Later, once we have received the message, we
2351 // can query its size and allocate a receiver buffer.
2352 //
2353 // Since we may be waiting for multiple messages from the same
2354 // incoming process (with possibly the same tag -- we can't
2355 // know), we must make sure that the 'probe' operation we have
2356 // here (and which we use to determine the buffer size) matches
2357 // the 'recv' operation with which we actually get the data
2358 // later on. This is exactly what the 'MPI_Mprobe' function and
2359 // its 'I'mmediate variant is there for, coupled with the
2360 // 'MPI_Mrecv' call that would put into the clean-up function
2361 // below.
2362 std::shared_ptr<MPI_Message> message = std::make_shared<MPI_Message>();
2363 std::shared_ptr<MPI_Status> status = std::make_shared<MPI_Status>();
2364
2365 auto wait = [source_rank, mpi_tag, communicator, message, status]() {
2366 const int ierr = MPI_Mprobe(
2367 source_rank, mpi_tag, communicator, message.get(), status.get());
2368 AssertThrowMPI(ierr);
2369 };
2370
2371
2372 // Now also define the function that actually gets the data:
2373 auto get = [status, message]() {
2374 int number_amount;
2375 int ierr;
2376 ierr = MPI_Get_count(status.get(), MPI_CHAR, &number_amount);
2377 AssertThrowMPI(ierr);
2378
2379 std::vector<char> receive_buffer(number_amount);
2380
2381 // Then actually get the data, using the matching MPI_Mrecv to the above
2382 // MPI_Mprobe:
2383 ierr = MPI_Mrecv(receive_buffer.data(),
2384 number_amount,
2385 mpi_type_id_for_type<decltype(*receive_buffer.data())>,
2386 message.get(),
2387 status.get());
2388 AssertThrowMPI(ierr);
2389
2390 // Return the unpacked object:
2391 return Utilities::unpack<T>(receive_buffer, false);
2392 };
2393
2394 return Future<T>(wait, get);
2395 # endif
2396 }
2397
2398
2399
2400 # ifdef DEAL_II_WITH_MPI
2401 template <class Iterator, typename Number>
2402 std::pair<Number, typename numbers::NumberTraits<Number>::real_type>
2403 mean_and_standard_deviation(const Iterator begin,
2404 const Iterator end,
2405 const MPI_Comm comm)
2406 {
2407 // below we do simple and straight-forward implementation. More elaborate
2408 // options are:
2409 // http://dx.doi.org/10.1145/2807591.2807644 section 3.1.2
2410 // https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm
2411 // https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Online
2412 using Std = typename numbers::NumberTraits<Number>::real_type;
2413 const Number sum = std::accumulate(begin, end, Number(0.));
2414
2415 const auto size = Utilities::MPI::sum(std::distance(begin, end), comm);
2416 Assert(size > 0, ExcDivideByZero());
2417 const Number mean =
2418 Utilities::MPI::sum(sum, comm) / static_cast<Std>(size);
2419 Std sq_sum = 0.;
2420 std::for_each(begin, end, [&mean, &sq_sum](const Number &v) {
2421 sq_sum += numbers::NumberTraits<Number>::abs_square(v - mean);
2422 });
2423 sq_sum = Utilities::MPI::sum(sq_sum, comm);
2424 return std::make_pair(mean,
2425 std::sqrt(sq_sum / static_cast<Std>(size - 1)));
2426 }
2427 # endif
2428
2429 #endif
2430 } // end of namespace MPI
2431 } // end of namespace Utilities
2432
2433
2434 DEAL_II_NAMESPACE_CLOSE
2435
2436 #endif