| 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 |