Debian Codegraph @

include/deal.II/lac/trilinos_tpetra_block_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2024 - 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_trilinos_tpetra_block_vector_h
16 #define dealii_trilinos_tpetra_block_vector_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_TRILINOS_WITH_TPETRA
21
22 # include <deal.II/lac/block_indices.h>
23 # include <deal.II/lac/block_vector_base.h>
24 # include <deal.II/lac/trilinos_tpetra_vector.h>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 namespace LinearAlgebra
29 {
30 /**
31 * @addtogroup TpetraWrappers
32 * @{
33 */
34 namespace TpetraWrappers
35 {
36 /**
37 * An implementation of block vectors based on the vector class
38 * implemented in LinearAlgebra::TpetraWrappers.
39 * While the base class provides for most of the interface, this class
40 * handles the actual allocation of vectors and provides functions that
41 * are specific to the underlying vector type.
42 *
43 * The model of distribution of data is such that each of the blocks is
44 * distributed across all MPI processes named in the MPI communicator.
45 * I.e. we don't just distribute the whole vector, but each component. In
46 * the constructors and reinit() functions, one therefore not only has to
47 * specify the sizes of the individual blocks, but also the number of
48 * elements of each of these blocks to be stored on the local process.
49 *
50 * @ingroup Vectors
51 * @ingroup TrilinosWrappers
52 * @see @ref GlossBlockLA "Block (linear algebra)"
53 */
54 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
55 class BlockVector : public dealii::BlockVectorBase<
56 TpetraWrappers::Vector<Number, MemorySpace>>
57 {
58 public:
59 /**
60 * Typedef the base class for simpler access to its own alias.
61 */
62 using BaseClass =
63 dealii::BlockVectorBase<TpetraWrappers::Vector<Number, MemorySpace>>;
64
65 /**
66 * Typedef the type of the underlying vector.
67 */
68 using BlockType = typename BaseClass::BlockType;
69
70 /**
71 * Import the alias from the base class.
72 */
73 using value_type = typename BaseClass::value_type;
74 using pointer = typename BaseClass::pointer;
75 using const_pointer = typename BaseClass::const_pointer;
76 using reference = typename BaseClass::reference;
77 using const_reference = typename BaseClass::const_reference;
78 using size_type = typename BaseClass::size_type;
79 using iterator = typename BaseClass::iterator;
80 using const_iterator = typename BaseClass::const_iterator;
81
82 /**
83 * Default constructor. Generate an empty vector without any blocks.
84 */
85 BlockVector() = default;
86
87 /**
88 * Constructor. Generate a block vector with as many blocks as there are
89 * entries in @p partitioning. Each IndexSet together with the MPI
90 * communicator contains the layout of the distribution of data among
91 * the MPI processes.
92 */
93 BlockVector(const std::vector<IndexSet> &parallel_partitioning,
94 const MPI_Comm communicator = MPI_COMM_WORLD);
95
96 /**
97 * Creates a BlockVector with ghost elements. See the respective
98 * reinit() method for more details. @p ghost_values may contain any
99 * elements in @p parallel_partitioning, they will be ignored.
100 */
101 BlockVector(const std::vector<IndexSet> &parallel_partitioning,
102 const std::vector<IndexSet> &ghost_values,
103 const MPI_Comm communicator,
104 const bool vector_writable = false);
105
106 /**
107 * Copy-Constructor. Set all the properties of the parallel vector to
108 * those of the given argument and copy the elements.
109 */
110 BlockVector(const BlockVector<Number, MemorySpace> &v);
111
112 /**
113 * Creates a block vector consisting of <tt>num_blocks</tt> components,
114 * but there is no content in the individual components and the user has
115 * to fill appropriate data using a reinit of the blocks.
116 */
117 explicit BlockVector(const size_type num_blocks);
118
119 /**
120 * Destructor. Clears memory
121 */
122 ~BlockVector() override = default;
123
124 /**
125 * Copy operator: fill all components of the vector that are locally
126 * stored with the given scalar value.
127 */
128 BlockVector<Number, MemorySpace> &
129 operator=(const Number s);
130
131 /**
132 * Copy operator for arguments of the same type. Resize the present vector
133 * if necessary to the correct number of blocks, then copy the individual
134 * blocks from `v` using the copy-assignment operator of the class that
135 * represents the individual blocks.
136 *
137 * Copying the vectors that make up individual blocks can have complex
138 * semantics in parallel vector classes. See the information provided
139 * by the class used to represent the individual blocks.
140 */
141 BlockVector<Number, MemorySpace> &
142 operator=(const BlockVector<Number, MemorySpace> &v);
143
144 /**
145 * Reinitialize the BlockVector to contain as many blocks as there are
146 * index sets given in the input argument, according to the parallel
147 * distribution of the individual components described in the maps.
148 *
149 * If <tt>omit_zeroing_entries==false</tt>, the vector is filled with
150 * zeros.
151 */
152 void
153 reinit(const std::vector<IndexSet> &parallel_partitioning,
154 const MPI_Comm communicator = MPI_COMM_WORLD,
155 const bool omit_zeroing_entries = false);
156
157 /**
158 * Reinit functionality. This function destroys the old vector content
159 * and generates a new one based on the input partitioning. In addition
160 * to just specifying one index set as in all the other methods above,
161 * this method allows to supply an additional set of ghost entries.
162 * There are two different versions of a vector that can be created. If
163 * the flag @p vector_writable is set to @p false, the vector only
164 * allows read access to the joint set of @p parallel_partitioning and
165 * @p ghost_entries. The effect of the reinit method is then equivalent
166 * to calling the other reinit method with an index set containing both
167 * the locally owned entries and the ghost entries.
168 *
169 * If the flag @p vector_writable is set to true, this creates an
170 * alternative storage scheme for ghost elements that allows multiple
171 * threads to write into the vector (for the other reinit methods, only
172 * one thread is allowed to write into the ghost entries at a time).
173 */
174 void
175 reinit(const std::vector<IndexSet> &partitioning,
176 const std::vector<IndexSet> &ghost_values,
177 const MPI_Comm communicator = MPI_COMM_WORLD,
178 const bool vector_writable = false);
179
180 /**
181 * Change the dimension to that of the vector <tt>V</tt>. The same
182 * applies as for the other reinit() function.
183 *
184 * The elements of <tt>V</tt> are not copied, i.e. this function is the
185 * same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>.
186 *
187 * Note that you must call this (or the other reinit() functions)
188 * function, rather than calling the reinit() functions of an individual
189 * block, to allow the block vector to update its caches of vector
190 * sizes. If you call reinit() on one of the blocks, then subsequent
191 * actions on this object may yield unpredictable results since they may
192 * be routed to the wrong block.
193 */
194 void
195 reinit(const BlockVector<Number, MemorySpace> &V,
196 const bool omit_zeroing_entries = false);
197
198 /**
199 * Change the number of blocks to <tt>num_blocks</tt>. The individual
200 * blocks will get initialized with zero size, so it is assumed that the
201 * user resizes the individual blocks by herself in an appropriate way,
202 * and calls <tt>collect_sizes</tt> afterwards.
203 */
204 void
205 reinit(const size_type num_blocks);
206
207 /**
208 * Return if this Vector contains ghost elements.
209 *
210 * @see
211 * @ref GlossGhostedVector "vectors with ghost elements"
212 */
213 bool
214 has_ghost_elements() const;
215
216 /**
217 * Print to a stream.
218 */
219 void
220 print(std::ostream &out,
221 const unsigned int precision = 3,
222 const bool scientific = true,
223 const bool across = true) const;
224 };
225 } // namespace TpetraWrappers
226
227 /** @} */
228
229 } // namespace LinearAlgebra
230
231 /**
232 * Declare dealii::LinearAlgebra::TpetraWrappers::BlockVector as distributed
233 * vector.
234 */
235 template <typename Number, typename MemorySpace>
236 struct is_serial_vector<
237 LinearAlgebra::TpetraWrappers::BlockVector<Number, MemorySpace>>
238 : std::false_type
239 {};
240
241 DEAL_II_NAMESPACE_CLOSE
242
243 #else
244
245 // Make sure the scripts that create the C++20 module input files have
246 // something to latch on if the preprocessor #ifdef above would
247 // otherwise lead to an empty content of the file.
248 DEAL_II_NAMESPACE_OPEN
249 DEAL_II_NAMESPACE_CLOSE
250
251 #endif // DEAL_II_TRILINOS_WITH_TPETRA
252
253 #endif // dealii_trilinos_tpetra_block_vector_h