Debian Codegraph @

include/deal.II/base/communication_pattern_base.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2023 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_base_communication_pattern_base_h
16 #define dealii_base_communication_pattern_base_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/mpi_stub.h>
21
22 DEAL_II_NAMESPACE_OPEN
23
24 // Forward declaration
25 #ifndef DOXYGEN
26 class IndexSet;
27 #endif
28
29 namespace Utilities
30 {
31 namespace MPI
32 {
33 /**
34 * CommunicationPattern is an abstract class that is used to define a
35 * communication plan that can be called repeatedly to efficiently obtain
36 * off-processor elements. The idea is to decouple the communication pattern
37 * from the data that needs to be communicated. The goal is to reuse the
38 * same communication pattern for different containers. This is similar to
39 * the way SparseMatrix and SparsityPattern works.
40 *
41 * Conceptually, this class operates under the assumption that data
42 * are stored in one linearly indexed array of which every MPI process
43 * stores some elements (or possibly none). In practice it does of course
44 * not matter whether the elements are stored in contiguous arrays; the
45 * point is simply that a single integer index can be used to access a
46 * specific element. The elements of this logical array are (or at least
47 * may be) stored on different processes in a parallel MPI universe.
48 *
49 * In this world view, every process has a set of elements and their
50 * indices in the array form the "locally owned indices". Next, every
51 * process will as part of executing an algorithm require access to some
52 * of the elements stored elsewhere; we call the indices of these elements
53 * the "ghost indices", in analogy to how vectors and triangulations
54 * partition vector elements and mesh cells into locally
55 * owned ones and ghost ones (along, of course, with cells and ghosts stored
56 * on other processes that the current process simply does not care about
57 * and consequently needs not know anything about).
58 *
59 * The point of this class (and its implementations in derived classes) is
60 * to set up communication infrastructure whereby one process can inquire
61 * efficiently about the "ghost elements" stored on other processes, and
62 * to send those locally owned elements to those other processes that
63 * require knowledge of their value because they list these elements among
64 * their respective "ghost indices".
65 */
66 class CommunicationPatternBase
67 {
68 public:
69 /**
70 * Destructor.
71 */
72 virtual ~CommunicationPatternBase() = default;
73
74 /**
75 * Reinitialize the communication pattern.
76 *
77 * @param[in] locally_owned_indices The set of indices of elements
78 * in the array mentioned in the class documentation that are
79 * stored on the current process.
80 * @param[in] ghost_indices The set of indices of elements in the
81 * array mentioned in the class documentation that the current
82 * process will need to be able to import.
83 * @param[in] communicator The MPI communicator used to describe the
84 * entire set of processes that participate in the storage and
85 * access to elements of the array.
86 */
87 virtual void
88 reinit(const IndexSet &locally_owned_indices,
89 const IndexSet &ghost_indices,
90 const MPI_Comm communicator) = 0;
91
92 /**
93 * Return the underlying MPI communicator.
94 */
95 virtual MPI_Comm
96 get_mpi_communicator() const = 0;
97 };
98
99 } // namespace MPI
100
101 } // namespace Utilities
102
103 DEAL_II_NAMESPACE_CLOSE
104
105 #endif