Debian Codegraph @

include/deal.II/base/partitioner.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_partitioner_h
16 #define dealii_partitioner_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/array_view.h>
21 #include <deal.II/base/communication_pattern_base.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/index_set.h>
24 #include <deal.II/base/memory_space.h>
25 #include <deal.II/base/mpi_stub.h>
26 #include <deal.II/base/types.h>
27
28 #include <deal.II/lac/vector_operation.h>
29
30 #include <Kokkos_Core.hpp>
31
32 #include <limits>
33 #include <memory>
34 #include <vector>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39 namespace Utilities
40 {
41 namespace MPI
42 {
43 /**
44 * This class defines a model for the partitioning of a vector (or, in
45 * fact, any linear data structure) among processors using MPI.
46 *
47 * The partitioner stores the global vector size and the locally owned
48 * range as a half-open interval [@p lower, @p upper) on each process. In
49 * other words, it assumes that every process stores a contiguous subset
50 * of the array mentioned in the documentation of the base class
51 * Utilities::MPI::CommunicationPatternBase. (If you want to store
52 * non-contiguous parts of these arrays on each process, take a look
53 * at Utilities::MPI::NoncontiguousPartitioner.)
54 *
55 * Furthermore, it includes a structure for the point-to-point communication
56 * patterns. It allows the inclusion of ghost indices (i.e. indices that a
57 * current processor needs to have access to, but are owned by another
58 * process) through an IndexSet. In addition, it also stores the other
59 * processors' ghost indices belonging to the current processor (see
60 * import_targets()), which are the indices where other processors might
61 * require information from. In a sense, these import indices form the dual
62 * of the ghost indices. This information is gathered once when constructing
63 * the partitioner, which obviates subsequent global communication steps
64 * when exchanging data.
65 *
66 * The figure below gives an example of index space $[0,74)$ being split
67 * into four parts that are each owned by one MPI process:
68 * @image html partitioner.png
69 * The first row (above the thick black line) shows which process owns which
70 * elements. Below it, the next four lines indicate which elements of
71 * the overall array each processor wants to know about -- this is
72 * generally a superset of the locally owned elements, with the difference
73 * being what are called "ghost elements".
74 *
75 * To understand the remaining pieces of the figure (and this class),
76 * remember that in MPI, you can't just ask another process for data.
77 * (That's not quite true: There are mechanisms in newer MPI standards
78 * for this, but as a general rule it's true.) Rather, if you need
79 * information, you need to send another process a message, the other
80 * process needs to expect the message and respond as appropriate with
81 * a message of its own. In practice, it is therefore easier and faster
82 * if each process will *already* know what it will be asked and, at
83 * the appropriate time, just send that data. The remaining lines of
84 * information set up this kind of scheme.
85 *
86 * To this end, note that process 0 will want to know about five
87 * elements it does not own itself: those with indices 20, 21 (owned
88 * by process 1); and 40, 41, 43 (owned by process 2). Similar information
89 * can be obtained from the following lines. To satisfy this need for
90 * knowledge, it would therefore be quite useful if process 1 stored
91 * that, at the appropriate time, it will have to send elements 20, 21
92 * to process 0. Similarly, if you go through lines 2-4 below the thick
93 * black line, you will see that process 0 should know that it will need
94 * to send elements 1, 2, 13, 18, 19 to process 1; 18, 19 to process 2;
95 * and elements 1, 2, 13 to process 3. These are called "import indices"
96 * because other processes will want to import them. Instead of storing
97 * these indices as a set, it is often useful to use half-open index
98 * sets instead, and so the import indices listed above form the following
99 * collection of sets: `[1,3)`, `[13,14)`, `[18,20)`, `[18,20)`,
100 * `[1,3)`, `[13,14)`. This is how the import indices are shown
101 * in the figure above. We now only have to know which of these
102 * half-open sets are to be sent to whom. This is done in the line
103 * above it where we list the "import targets" (i.e., the target
104 * processes for an import operations): Process 1 will receive 5
105 * elements (which are comprised of the first three half-open
106 * target index sets), process 2 will receive 2 indices
107 * (the fourth half-open interval), and process 3 will receive
108 * 3 indices (the remaining two half-open intervals). This information
109 * is encoded as the pairs `{1,5}`, `{2,2}`, `{3,3}` as the import
110 * targets. Similar considerations can be made for what processes
111 * 1, 2, and 3 will have to send out.
112 *
113 * Finally, when receiving information, it is useful to know how
114 * many indices each process will receive from whom since then one
115 * can already pre-allocate buffers of the right size. This is listed
116 * in the last line under "ghost targets": Process 0 will receive
117 * two elements from process 1 (namely those with indices 20, 21),
118 * and three from process 2 (namely those with indices 40, 41, 43).
119 * This is encoded as pairs `{1,2}` and `{2,3}`. Again, similar
120 * considerations can be made for what processes 1, 2, and 3
121 * should expect, and what is then shown in their respective columns.
122 *
123 * The main purpose of this class is to set up these data structures
124 * knowing only which process owns which elements, and for which
125 * additional ghost elements each process needs knowledge.
126 *
127 *
128 * <h4>Local and global numbering</h4>
129 *
130 * The partitioner includes a mechanism for converting global to local and
131 * local to global indices. Internally, this class stores vector elements
132 * using the convention as follows: The local range is associated with
133 * local indices [0, locally_owned_size()), and ghost indices are stored
134 * consecutively in [locally_owned_size(), locally_owned_size() +
135 * n_ghost_indices()). The ghost indices are sorted according to their
136 * global index.
137 *
138 *
139 * <h4>Parallel data exchange</h4>
140 *
141 * This class also handles the ghost data exchange for partitioned
142 * arrays of objects -- i.e., if a separate class stores the
143 * locally owned elements on each process, then this class
144 * facilitates the importation of those elements that are locally
145 * needed as ghosts but stored elsewhere. An example of where this class
146 * is used is the LinearAlgebra::distributed::Vector class.
147 *
148 * The data exchange happens through four functions:
149 * <ul>
150 * <li> export_to_ghosted_array_start() is used for initiating an export
151 * operation that sends data from the locally owned data field, passed as
152 * an array, to the ghost data arrays of other processes (according to the
153 * ghost indices stored in the present class).
154 * This call starts non-blocking MPI send communication
155 * routines, but does not wait for the routines to finish. Thus, the user
156 * may not write into the respective positions of the underlying arrays as
157 * the data might still be needed by MPI.
158 * <li> export_to_ghosted_array_finish() finalizes the MPI data exchange
159 * started in export_to_ghosted_array_start() and signals that the data in
160 * the arrays may be used for further processing or modified as
161 * appropriate.
162 * <li> import_from_ghosted_array_start() is used for initiating an import
163 * operation that sends data from a ghost data field, passed as an array,
164 * to the locally owned array according to the ghost indices stored in the
165 * present class. A VectorOperation::values flag can be passed to decide
166 * on how to combine the data in the ghost field with the data at the
167 * owner, since both relate to the same data entry. In assembly, this is
168 * usually an add-to operation where contributions from all processes to
169 * a locally owned element need to be added up. This call starts
170 * non-blocking MPI communication routines, but does not wait for the
171 * routines to finish. Thus, the user may not write into the respective
172 * positions of the underlying arrays as the data might still be needed by
173 * MPI.
174 * <li> import_from_ghosted_array_finish() finalizes the MPI data exchange
175 * started in import_from_ghosted_array_start() and signals that the data
176 * in the arrays may be used for further processing or modified as
177 * appropriate.
178 * </ul>
179 *
180 * The MPI communication routines are point-to-point communication patterns.
181 *
182 *
183 * <h4>Sending only selected ghost data</h4>
184 *
185 * This partitioner class operates on a fixed set of ghost indices and
186 * must always be compatible with the ghost indices inside the array whose
187 * partitioning it represents. In some cases,
188 * one only wants to send around some of the ghost indices present in
189 * a vector, but without creating a copy of the vector with a
190 * suitable index set - think e.g. of local time stepping where different
191 * regions of a vector might be exchanged at different stages of a time
192 * step slice. This class supports that case by the following model: A
193 * vector is first created with the full ghosted index set. Then, a second
194 * Partitioner instance is created that sets ghost indices with a tighter
195 * index set as ghosts, but specifying the larger index set as the second
196 * argument to the set_ghost_indices() call. When data is exchanged, the
197 * export_to_ghosted_array_start() and import_from_ghosted_array_start()
198 * detect this case and only send the selected indices, taken from the
199 * full array of ghost entries.
200 */
201 class Partitioner : public Utilities::MPI::CommunicationPatternBase
202 {
203 public:
204 /**
205 * Default constructor.
206 */
207 Partitioner();
208
209 /**
210 * Constructor with size argument. Creates an MPI_COMM_SELF structure
211 * where there is no real parallel layout.
212 */
213 Partitioner(const unsigned int size);
214
215 /**
216 * Constructor that takes the number of locally-owned degrees of freedom
217 * @p local_size and the number of ghost degrees of freedom @p ghost_size.
218 *
219 * The local index range is translated to global indices in an ascending
220 * and one-to-one fashion, i.e., the indices of process $p$ sit exactly
221 * between the indices of the processes $p-1$ and $p+1$, respectively.
222 *
223 * @note Setting the @p ghost_size variable to an appropriate value
224 * provides memory space for the ghost data in a vector's memory
225 * allocation as and allows access to it via local_element(). However,
226 * the associated global indices must be handled externally in this
227 * case.
228 */
229 Partitioner(const types::global_dof_index local_size,
230 const types::global_dof_index ghost_size,
231 const MPI_Comm communicator);
232
233 /**
234 * Constructor with index set arguments. This constructor creates a
235 * distributed layout based on a given communicators, an IndexSet
236 * describing the locally owned range and another one for describing
237 * ghost indices that are owned by other processors, but that we need to
238 * have read or write access to.
239 */
240 Partitioner(const IndexSet &locally_owned_indices,
241 const IndexSet &ghost_indices_in,
242 const MPI_Comm communicator_in);
243
244 /**
245 * Constructor with one index set argument. This constructor creates a
246 * distributed layout based on a given communicator, and an IndexSet
247 * describing the locally owned range. It allows to set the ghost
248 * indices at a later time. Apart from this, it is similar to the other
249 * constructor with two index sets.
250 */
251 Partitioner(const IndexSet &locally_owned_indices,
252 const MPI_Comm communicator_in);
253
254 /**
255 * Reinitialize the communication pattern.
256 *
257 * @param[in] locally_owned_indices The set of indices of elements
258 * in the array mentioned in the class documentation that are
259 * stored on the current process.
260 * @param[in] ghost_indices The set of indices of elements in the
261 * array mentioned in the class documentation that the current
262 * process will need to be able to import.
263 * @param[in] communicator The MPI communicator used to describe the
264 * entire set of processes that participate in the storage and
265 * access to elements of the array.
266 */
267 virtual void
268 reinit(const IndexSet &locally_owned_indices,
269 const IndexSet &ghost_indices,
270 const MPI_Comm communicator) override;
271
272 /**
273 * Set the locally owned indices. Used in the constructor.
274 */
275 void
276 set_owned_indices(const IndexSet &locally_owned_indices);
277
278 /**
279 * Set the ghost indices after the constructor has been
280 * called.
281 *
282 * The optional parameter @p larger_ghost_index_set allows defining an
283 * indirect addressing into a larger set of ghost indices. This setup is
284 * useful if a distributed vector is based on that larger ghost index
285 * set but only a tighter subset should be communicated according to
286 * @p ghost_indices.
287 */
288 void
289 set_ghost_indices(const IndexSet &ghost_indices,
290 const IndexSet &larger_ghost_index_set = IndexSet());
291
292 /**
293 * Return the global size.
294 */
295 types::global_dof_index
296 size() const;
297
298 /**
299 * Return the number of locally owned indices,
300 * i.e., local_range().second minus local_range().first.
301 * The returned numbers need to add up to the total number of indices when
302 * summed over all processes
303 */
304 unsigned int
305 locally_owned_size() const;
306
307 /**
308 * Return an IndexSet representation of the local range. This class
309 * only supports contiguous local ranges, so the IndexSet actually only
310 * consists of one single range of data, and is equivalent to the result
311 * of local_range().
312 */
313 const IndexSet &
314 locally_owned_range() const;
315
316 /**
317 * Return the local range. The returned pair consists of the index of
318 * the first element and the index of the element one past the last
319 * locally owned one.
320 */
321 std::pair<types::global_dof_index, types::global_dof_index>
322 local_range() const;
323
324 /**
325 * Return true if the given global index is in the local range of this
326 * processor.
327 */
328 bool
329 in_local_range(const types::global_dof_index global_index) const;
330
331 /**
332 * Return the local index corresponding to the given global index. If
333 * the given global index is neither locally owned nor a ghost, an
334 * exception is thrown.
335 *
336 * Note that the returned local index for locally owned indices will be
337 * between 0 and locally_owned_size() - 1, and the local index for
338 * ghosts is between locally_owned_size() and locally_owned_size() +
339 * n_ghost_indices() - 1.
340 */
341 unsigned int
342 global_to_local(const types::global_dof_index global_index) const;
343
344 /**
345 * Return the global index corresponding to the given local index.
346 *
347 * Note that the local index for locally owned indices must be between 0
348 * and locally_owned_size() - 1, and the local index for ghosts must be
349 * between locally_owned_size() and locally_owned_size() +
350 * n_ghost_indices() - 1.
351 */
352 types::global_dof_index
353 local_to_global(const unsigned int local_index) const;
354
355 /**
356 * Return whether the given global index is a ghost index on the
357 * present processor. Returns false for indices that are owned locally
358 * and for indices not present at all.
359 */
360 bool
361 is_ghost_entry(const types::global_dof_index global_index) const;
362
363 /**
364 * Return an IndexSet representation of all ghost indices.
365 */
366 const IndexSet &
367 ghost_indices() const;
368
369 /**
370 * Return the number of ghost indices. Same as
371 * ghost_indices().n_elements(), but cached for simpler access.
372 */
373 unsigned int
374 n_ghost_indices() const;
375
376 /**
377 * In case the partitioner was built to define ghost indices as a subset
378 * of indices in a larger set of ghosts, this function returns the
379 * numbering in terms of ranges within that set. Similar structure as in
380 * an IndexSet, but tailored to be iterated over.
381 *
382 * In case the partitioner did not take a second set of ghost indices
383 * into account, this subset is simply defined as the half-open interval
384 * <code>[0, n_ghost_indices())</code>.
385 */
386 const std::vector<std::pair<unsigned int, unsigned int>> &
387 ghost_indices_within_larger_ghost_set() const;
388
389 /**
390 * Return a list of processors (first entry) and the number of ghost
391 * degrees of freedom owned by that processor (second entry). The sum of
392 * the latter over all processors equals n_ghost_indices().
393 */
394 const std::vector<std::pair<unsigned int, unsigned int>> &
395 ghost_targets() const;
396
397 /**
398 * Return a vector of ranges of local indices that we are importing during
399 * compress(), i.e., others' ghosts that belong to the local range.
400 * Similar structure as in an IndexSet, but tailored to be iterated over,
401 * and some indices may be duplicated. The returned pairs consists of the
402 * index of the first element and the index of the element one past the
403 * last one in a range.
404 */
405 const std::vector<std::pair<unsigned int, unsigned int>> &
406 import_indices() const;
407
408 /**
409 * Number of import indices, i.e., indices that are ghosts on other
410 * processors and we will receive data from.
411 */
412 unsigned int
413 n_import_indices() const;
414
415 /**
416 * Return a list of processors (first entry) and the number of degrees
417 * of freedom imported from it during compress() operation (second entry)
418 * for all the processors that data is obtained from, i.e., locally owned
419 * indices that are ghosts on other processors.
420 *
421 * @note The returned vector only contains those processor id's for which
422 * the second entry is non-zero.
423 */
424 const std::vector<std::pair<unsigned int, unsigned int>> &
425 import_targets() const;
426
427 /**
428 * Check whether the given partitioner is compatible with the current
429 * partitioner. Two partitioners are compatible if
430 * they have the same local sizes and the same ghost indices. They do not
431 * necessarily need to correspond to the same data that is stored based
432 * on these partioner objects. This is a local operation
433 * only, i.e., if only some processors decide that the partitioning is
434 * not compatible, only these processors will return @p false, whereas
435 * the other processors will return @p true.
436 */
437 bool
438 is_compatible(const Partitioner &part) const;
439
440 /**
441 * Check whether the given partitioner is compatible with the
442 * current partitioner. Two partitioners are compatible if
443 * they have the same local size and the same ghost indices. They do not
444 * necessarily need to correspond to the same data that is stored based
445 * on these partioner objects. As opposed to
446 * is_compatible(), this method checks for compatibility among all
447 * processors and the method only returns @p true if the partitioner is
448 * the same on all processors. In other words, it does a global
449 * "and" operation over the results returned by is_compatible() on all
450 * involved processes.
451 *
452 * This method performs global communication, so make sure to use it
453 * only in a context where all processors call it the same number of
454 * times.
455 */
456 bool
457 is_globally_compatible(const Partitioner &part) const;
458
459 /**
460 * Return the MPI ID of the calling processor. Cached to have simple
461 * access.
462 */
463 unsigned int
464 this_mpi_process() const;
465
466 /**
467 * Return the total number of MPI processor participating in the given
468 * partitioner. Cached to have simple access.
469 */
470 unsigned int
471 n_mpi_processes() const;
472
473 /**
474 * Return the underlying MPI communicator.
475 */
476 virtual MPI_Comm
477 get_mpi_communicator() const override;
478
479 /**
480 * Return whether ghost indices have been explicitly added as a @p
481 * ghost_indices argument. Only true if a reinit() call or constructor
482 * provided that argument.
483 */
484 bool
485 ghost_indices_initialized() const;
486
487 #ifdef DEAL_II_WITH_MPI
488 /**
489 * Start the exportation of the data in a locally owned array to the
490 * range described by the ghost indices of this class.
491 *
492 * @param communication_channel Sets an offset to the MPI_Isend and
493 * MPI_Irecv calls that avoids interference with other ongoing
494 * export_to_ghosted_array_start() calls on different entries. Typically
495 * handled within the blocks of a block vector. Any value less than 200
496 * is a valid value.
497 *
498 * @param locally_owned_array The array of data from which the data is
499 * extracted and sent to the ghost entries on a remote processor.
500 *
501 * @param temporary_storage A temporary storage array of length
502 * n_import_indices() that is used to hold the packed data from the @p
503 * locally_owned_array to be sent. Note that this array must not be
504 * touched until the respective export_to_ghosted_array_finish() call
505 * has been made because the model uses non-blocking communication.
506 *
507 * @param ghost_array The array that will receive the exported data,
508 * i.e., the entries that a remote processor sent to the calling
509 * process. Its size must either be n_ghost_indices() or equal the
510 * number of ghost indices in the larger index set that was given as
511 * second argument to set_ghost_indices(). In case only selected indices
512 * are sent, no guarantee is made regarding the entries that do not get
513 * set. Some of them might be used to organize the transfer and later
514 * reset to zero, so make sure you do not use them in computations.
515 *
516 * @param requests The list of MPI requests for the ongoing non-blocking
517 * communication that will be finalized in the
518 * export_to_ghosted_array_finish() call.
519 *
520 * This functionality is used in
521 * LinearAlgebra::distributed::Vector::update_ghost_values().
522 */
523 template <typename Number, typename MemorySpaceType = MemorySpace::Host>
524 void
525 export_to_ghosted_array_start(
526 const unsigned int communication_channel,
527 const ArrayView<const Number, MemorySpaceType> &locally_owned_array,
528 const ArrayView<Number, MemorySpaceType> &temporary_storage,
529 const ArrayView<Number, MemorySpaceType> &ghost_array,
530 std::vector<MPI_Request> &requests) const;
531
532 /**
533 * Finish the exportation of the data in a locally owned array to the
534 * range described by the ghost indices of this class.
535 *
536 * @param ghost_array The array that will receive the exported data
537 * started in the @p export_to_ghosted_array_start(). This must be the
538 * same array as passed to that function, otherwise the behavior is
539 * undefined.
540 *
541 * @param requests The list of MPI requests for the ongoing non-blocking
542 * communication that were started in the
543 * export_to_ghosted_array_start() call. This must be the same array as
544 * passed to that function, otherwise MPI will likely throw an error.
545 *
546 * This functionality is used in
547 * LinearAlgebra::distributed::Vector::update_ghost_values().
548 */
549 template <typename Number, typename MemorySpaceType = MemorySpace::Host>
550 void
551 export_to_ghosted_array_finish(
552 const ArrayView<Number, MemorySpaceType> &ghost_array,
553 std::vector<MPI_Request> &requests) const;
554
555 /**
556 * Start importing the data on an array indexed by the ghost indices of
557 * this class that is later accumulated into a locally owned array with
558 * import_from_ghosted_array_finish().
559 *
560 * @param vector_operation Defines how the data sent to the owner should
561 * be combined with the existing entries, e.g., added into.
562 *
563 * @param communication_channel Sets an offset to the MPI_Isend and
564 * MPI_Irecv calls that avoids interference with other ongoing
565 * import_from_ghosted_array_start() calls on different
566 * entries. Typically handled within the blocks of a block vector.
567 * Any value less than 200 is a valid value.
568 *
569 * @param ghost_array The array of ghost data that is sent to a remote
570 * owner of the respective index in a vector. Its size must either be
571 * n_ghost_indices() or equal the number of ghost indices in the larger
572 * index set that was given as second argument to
573 * set_ghost_indices(). This or the subsequent
574 * import_from_ghosted_array_finish() function, the order is
575 * implementation-dependent, will set all data entries behind @p
576 * ghost_array to zero.
577 *
578 * @param temporary_storage A temporary storage array of length
579 * n_import_indices() that is used to hold the packed data from MPI
580 * communication that will later be written into the locally owned
581 * array. Note that this array must not be touched until the respective
582 * import_from_ghosted_array_finish() call has been made because the
583 * model uses non-blocking communication.
584 *
585 * @param requests The list of MPI requests for the ongoing non-blocking
586 * communication that will be finalized in the
587 * export_to_ghosted_array_finish() call.
588 *
589 * This functionality is used in
590 * LinearAlgebra::distributed::Vector::compress().
591 */
592 template <typename Number, typename MemorySpaceType = MemorySpace::Host>
593 void
594 import_from_ghosted_array_start(
595 const VectorOperation::values vector_operation,
596 const unsigned int communication_channel,
597 const ArrayView<Number, MemorySpaceType> &ghost_array,
598 const ArrayView<Number, MemorySpaceType> &temporary_storage,
599 std::vector<MPI_Request> &requests) const;
600
601 /**
602 * Finish importing the data from an array indexed by the ghost
603 * indices of this class into a specified locally owned array, combining
604 * the results according to the given input @p vector_operation.
605 *
606 * @param vector_operation Defines how the data sent to the owner should
607 * be combined with the existing entries, e.g., added into.
608 *
609 * @param temporary_storage The same array given to the
610 * import_from_ghosted_array_start() call that contains the packed data
611 * from MPI communication. In thus function, it is combined at the
612 * corresponding entries described by the ghost relations according to
613 * @p vector_operation.
614 *
615 * @param ghost_array The array of ghost data that is sent to a remote
616 * owner of the respective index in a vector. Its size must either be
617 * n_ghost_indices() or equal the number of ghost indices in the larger
618 * index set that was given as second argument to
619 * set_ghost_indices(). This function will set all data entries behind
620 * @p ghost_array to zero for the implementation-dependent cases when it
621 * was not already done in the import_from_ghosted_array_start() call.
622 *
623 * @param locally_owned_storage The array of data where the resulting data
624 * sent by remote processes to the calling process will be accumulated
625 * into.
626 *
627 * @param requests The list of MPI requests for the ongoing non-blocking
628 * communication that have been initiated in the
629 * import_to_ghosted_array_finish() call. This must be the same array as
630 * passed to that function, otherwise MPI will likely throw an error.
631 *
632 * This functionality is used in
633 * LinearAlgebra::distributed::Vector::compress().
634 */
635 template <typename Number, typename MemorySpaceType = MemorySpace::Host>
636 void
637 import_from_ghosted_array_finish(
638 const VectorOperation::values vector_operation,
639 const ArrayView<const Number, MemorySpaceType> &temporary_storage,
640 const ArrayView<Number, MemorySpaceType> &locally_owned_storage,
641 const ArrayView<Number, MemorySpaceType> &ghost_array,
642 std::vector<MPI_Request> &requests) const;
643 #endif
644
645 /**
646 * Compute the memory consumption of this structure.
647 */
648 std::size_t
649 memory_consumption() const;
650
651 /**
652 * Exception
653 */
654 DeclException2(ExcIndexNotPresent,
655 types::global_dof_index,
656 unsigned int,
657 << "Global index " << arg1
658 << " neither owned nor ghost on proc " << arg2 << '.');
659
660 /**
661 * Exception
662 */
663 DeclException3(ExcGhostIndexArrayHasWrongSize,
664 unsigned int,
665 unsigned int,
666 unsigned int,
667 << "The size of the ghost index array (" << arg1
668 << ") must either equal the number of ghost in the "
669 << "partitioner (" << arg2
670 << ") or be equal in size to a more comprehensive index"
671 << "set which contains " << arg3
672 << " elements for this partitioner.");
673
674 private:
675 /**
676 * Initialize import_indices_plain_dev from import_indices_data. This
677 * function is only used when using @ref GlossDevice "device"-aware MPI.
678 */
679 void
680 initialize_import_indices_plain_dev() const;
681
682 /**
683 * The global size of the vector over all processors
684 */
685 types::global_dof_index global_size;
686
687 /**
688 * The range of the vector that is stored locally.
689 */
690 IndexSet locally_owned_range_data;
691
692 /**
693 * The range of the vector that is stored locally. Extracted from
694 * locally_owned_range for performance reasons.
695 */
696 std::pair<types::global_dof_index, types::global_dof_index>
697 local_range_data;
698
699 /**
700 * The set of indices to which we need to have read access but that are
701 * not locally owned
702 */
703 IndexSet ghost_indices_data;
704
705 /**
706 * A variable caching the number of ghost indices. It would be expensive
707 * to use @p ghost_indices.n_elements() to compute this.
708 */
709 unsigned int n_ghost_indices_data;
710
711 /**
712 * An array that contains information which processors my ghost indices
713 * belong to and how many those indices are
714 */
715 std::vector<std::pair<unsigned int, unsigned int>> ghost_targets_data;
716
717 /**
718 * The set of (local) indices that we are importing during compress(),
719 * i.e., others' ghosts that belong to the local range. Similar
720 * structure as in an IndexSet, but tailored to be iterated over, and
721 * some indices may be duplicates.
722 */
723 std::vector<std::pair<unsigned int, unsigned int>> import_indices_data;
724
725 /**
726 * The set of (local) indices that we are importing during compress(),
727 * i.e., others' ghosts that belong to the local range. The data stored is
728 * the same as in import_indices_data but the data is expanded in plain
729 * arrays. This variable is only used when using @ref GlossDevice "device"-aware MPI.
730 */
731 // The variable is mutable to enable lazy initialization in
732 // export_to_ghosted_array_start().
733 mutable std::vector<
734 Kokkos::View<unsigned int *, MemorySpace::Default::kokkos_space>>
735 import_indices_plain_dev;
736
737 /**
738 * A variable caching the number of ghost indices. It would be expensive
739 * to compute it by iterating over the import indices and accumulate them.
740 */
741 unsigned int n_import_indices_data;
742
743 /**
744 * The set of processors and length of data field which send us their
745 * ghost data
746 */
747 std::vector<std::pair<unsigned int, unsigned int>> import_targets_data;
748
749 /**
750 * An array that caches the number of chunks in the import indices per MPI
751 * rank. The length is import_indices_data.size()+1.
752 */
753 std::vector<unsigned int> import_indices_chunks_by_rank_data;
754
755 /**
756 * A variable caching the number of ghost indices in a larger set of
757 * indices given by the optional argument to set_ghost_indices().
758 */
759 unsigned int n_ghost_indices_in_larger_set;
760
761 /**
762 * An array that caches the number of chunks in the import indices per MPI
763 * rank. The length is ghost_indices_subset_data.size()+1.
764 */
765 std::vector<unsigned int> ghost_indices_subset_chunks_by_rank_data;
766
767 /**
768 * The set of indices that appear for an IndexSet that is a subset of a
769 * larger set. Similar structure as in an IndexSet within all ghost
770 * indices, but tailored to be iterated over.
771 */
772 std::vector<std::pair<unsigned int, unsigned int>>
773 ghost_indices_subset_data;
774
775 /**
776 * The ID of the current processor in the MPI network
777 */
778 unsigned int my_pid;
779
780 /**
781 * The total number of processors active in the problem
782 */
783 unsigned int n_procs;
784
785 /**
786 * The MPI communicator involved in the problem
787 */
788 MPI_Comm communicator;
789
790 /**
791 * A variable storing whether the ghost indices have been explicitly set.
792 */
793 bool have_ghost_indices;
794 };
795
796
797
798 /*--------------------- Inline functions --------------------------------*/
799
800 #ifndef DOXYGEN
801
802 inline types::global_dof_index
803 Partitioner::size() const
804 {
805 return global_size;
806 }
807
808
809
810 inline const IndexSet &
811 Partitioner::locally_owned_range() const
812 {
813 return locally_owned_range_data;
814 }
815
816
817
818 inline std::pair<types::global_dof_index, types::global_dof_index>
819 Partitioner::local_range() const
820 {
821 return local_range_data;
822 }
823
824
825
826 inline unsigned int
827 Partitioner::locally_owned_size() const
828 {
829 types::global_dof_index size =
830 local_range_data.second - local_range_data.first;
831 Assert(size <= std::numeric_limits<unsigned int>::max(),
832 ExcNotImplemented());
833 return static_cast<unsigned int>(size);
834 }
835
836
837
838 inline bool
839 Partitioner::in_local_range(
840 const types::global_dof_index global_index) const
841 {
842 return (local_range_data.first <= global_index &&
843 global_index < local_range_data.second);
844 }
845
846
847
848 inline bool
849 Partitioner::is_ghost_entry(
850 const types::global_dof_index global_index) const
851 {
852 // if the index is in the global range, it is trivially not a ghost
853 if (in_local_range(global_index) == true)
854 return false;
855 else
856 return ghost_indices().is_element(global_index);
857 }
858
859
860
861 inline unsigned int
862 Partitioner::global_to_local(
863 const types::global_dof_index global_index) const
864 {
865 Assert(in_local_range(global_index) || is_ghost_entry(global_index),
866 ExcIndexNotPresent(global_index, my_pid));
867 if (in_local_range(global_index))
868 return static_cast<unsigned int>(global_index - local_range_data.first);
869 else
870 {
871 // avoid checking the ghost index set via a binary search twice by
872 // querying the index within set, which returns invalid_dof_index
873 // for non-existent entries
874 const types::global_dof_index index_within_ghosts =
875 ghost_indices_data.index_within_set(global_index);
876 if (index_within_ghosts == numbers::invalid_dof_index)
877 return numbers::invalid_unsigned_int;
878 else
879 return locally_owned_size() +
880 static_cast<unsigned int>(index_within_ghosts);
881 }
882 }
883
884
885
886 inline types::global_dof_index
887 Partitioner::local_to_global(const unsigned int local_index) const
888 {
889 AssertIndexRange(local_index,
890 locally_owned_size() + n_ghost_indices_data);
891 if (local_index < locally_owned_size())
892 return local_range_data.first + types::global_dof_index(local_index);
893 else
894 return ghost_indices_data.nth_index_in_set(local_index -
895 locally_owned_size());
896 }
897
898
899
900 inline const IndexSet &
901 Partitioner::ghost_indices() const
902 {
903 return ghost_indices_data;
904 }
905
906
907
908 inline unsigned int
909 Partitioner::n_ghost_indices() const
910 {
911 return n_ghost_indices_data;
912 }
913
914
915
916 inline const std::vector<std::pair<unsigned int, unsigned int>> &
917 Partitioner::ghost_indices_within_larger_ghost_set() const
918 {
919 return ghost_indices_subset_data;
920 }
921
922
923
924 inline const std::vector<std::pair<unsigned int, unsigned int>> &
925 Partitioner::ghost_targets() const
926 {
927 return ghost_targets_data;
928 }
929
930
931 inline const std::vector<std::pair<unsigned int, unsigned int>> &
932 Partitioner::import_indices() const
933 {
934 return import_indices_data;
935 }
936
937
938
939 inline unsigned int
940 Partitioner::n_import_indices() const
941 {
942 return n_import_indices_data;
943 }
944
945
946
947 inline const std::vector<std::pair<unsigned int, unsigned int>> &
948 Partitioner::import_targets() const
949 {
950 return import_targets_data;
951 }
952
953
954
955 inline unsigned int
956 Partitioner::this_mpi_process() const
957 {
958 // return the id from the variable stored in this class instead of
959 // Utilities::MPI::this_mpi_process() in order to make this query also
960 // work when MPI is not initialized.
961 return my_pid;
962 }
963
964
965
966 inline unsigned int
967 Partitioner::n_mpi_processes() const
968 {
969 // return the number of MPI processes from the variable stored in this
970 // class instead of Utilities::MPI::n_mpi_processes() in order to make
971 // this query also work when MPI is not initialized.
972 return n_procs;
973 }
974
975
976
977 inline MPI_Comm
978 Partitioner::get_mpi_communicator() const
979 {
980 return communicator;
981 }
982
983
984
985 inline bool
986 Partitioner::ghost_indices_initialized() const
987 {
988 return have_ghost_indices;
989 }
990
991 #endif // ifndef DOXYGEN
992
993 } // end of namespace MPI
994
995 } // end of namespace Utilities
996
997
998 DEAL_II_NAMESPACE_CLOSE
999
1000 #endif