Debian Codegraph @

include/deal.II/lac/trilinos_tpetra_block_sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2024 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_tpetra_trilinos_block_sparse_matrix_h
16 #define dealii_tpetra_trilinos_block_sparse_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_TRILINOS_WITH_TPETRA
22
23 # include <deal.II/base/template_constraints.h>
24
25 # include <deal.II/lac/block_matrix_base.h>
26 # include <deal.II/lac/block_sparse_matrix.h>
27 # include <deal.II/lac/exceptions.h>
28 # include <deal.II/lac/full_matrix.h>
29 # include <deal.II/lac/trilinos_tpetra_block_vector.h>
30 # include <deal.II/lac/trilinos_tpetra_sparse_matrix.h>
31
32 # include <cmath>
33
34 DEAL_II_NAMESPACE_OPEN
35
36 // forward declarations
37 # ifndef DOXYGEN
38 class BlockSparsityPattern;
39 template <typename number>
40 class BlockSparseMatrix;
41 # endif
42
43 namespace LinearAlgebra
44 {
45 /**
46 * @addtogroup TpetraWrappers
47 * @{
48 */
49 namespace TpetraWrappers
50 {
51 /**
52 * Blocked sparse matrix based on the
53 * LinearAlgebra::TpetraWrappers::SparseMatrix class. This class implements
54 * the functions that are specific to the Trilinos SparseMatrix base objects
55 * for a blocked sparse matrix, and leaves the actual work relaying most of
56 * the calls to the individual blocks to the functions implemented in the
57 * base class. See there also for a description of when this class is
58 * useful.
59 *
60 * In contrast to the deal.II-type SparseMatrix class, the Trilinos matrices
61 * do not have external objects for the sparsity patterns. Thus, one does
62 * not determine the size of the individual blocks of a block matrix of this
63 * type by attaching a block sparsity pattern, but by calling reinit() to
64 * set the number of blocks and then by setting the size of each block
65 * separately. In order to fix the data structures of the block matrix, it
66 * is then necessary to let it know that we have changed the sizes of the
67 * underlying matrices. For this, one has to call the collect_sizes()
68 * function, for much the same reason as is documented with the
69 * BlockSparsityPattern class.
70 *
71 * @ingroup Matrix1
72 * @see @ref GlossBlockLA "Block (linear algebra)"
73 */
74 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
75 class BlockSparseMatrix
76 : public BlockMatrixBase<SparseMatrix<Number, MemorySpace>>
77 {
78 public:
79 /**
80 * Typedef the base class for simpler access to its own alias.
81 */
82 using BaseClass = BlockMatrixBase<SparseMatrix<Number, MemorySpace>>;
83
84 /**
85 * Typedef the type of the underlying matrix.
86 */
87 using BlockType = typename BaseClass::BlockType;
88
89 /**
90 * Import the alias from the base class.
91 */
92 using value_type = typename BaseClass::value_type;
93 using pointer = typename BaseClass::pointer;
94 using const_pointer = typename BaseClass::const_pointer;
95 using reference = typename BaseClass::reference;
96 using const_reference = typename BaseClass::const_reference;
97 using size_type = typename BaseClass::size_type;
98 using iterator = typename BaseClass::iterator;
99 using const_iterator = typename BaseClass::const_iterator;
100
101 /**
102 * Constructor; initializes the matrix to be empty, without any structure,
103 * i.e. the matrix is not usable at all. This constructor is therefore
104 * only useful for matrices which are members of a class. All other
105 * matrices should be created at a point in the data flow where all
106 * necessary information is available.
107 *
108 * You have to initialize the matrix before usage with
109 * reinit(BlockSparsityPattern). The number of blocks per row and column
110 * are then determined by that function.
111 */
112 BlockSparseMatrix() = default;
113
114 /**
115 * Destructor.
116 */
117 ~BlockSparseMatrix() override;
118
119 /**
120 * Pseudo copy operator only copying empty objects. The sizes of the block
121 * matrices need to be the same.
122 */
123 BlockSparseMatrix<Number, MemorySpace> &
124 operator=(const BlockSparseMatrix<Number, MemorySpace> &) = default;
125
126 /**
127 * This operator assigns a scalar to a matrix. Since this does usually not
128 * make much sense (should we set all matrix entries to this value? Only
129 * the nonzero entries of the sparsity pattern?), this operation is only
130 * allowed if the actual value to be assigned is zero. This operator only
131 * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
132 * all elements of the matrix to zero, but keep the sparsity pattern
133 * previously used.
134 */
135 BlockSparseMatrix<Number, MemorySpace> &
136 operator=(const Number d);
137
138 /**
139 * Resize the matrix, by setting the number of block rows and columns.
140 * This deletes all blocks and replaces them with uninitialized ones, i.e.
141 * ones for which also the sizes are not yet set. You have to do that by
142 * calling the @p reinit functions of the blocks themselves. Do not forget
143 * to call collect_sizes() after that on this object.
144 *
145 * The reason that you have to set sizes of the blocks yourself is that
146 * the sizes may be varying, the maximum number of elements per row may be
147 * varying, etc. It is simpler not to reproduce the interface of the @p
148 * SparsityPattern class here but rather let the user call whatever
149 * function they desire.
150 */
151 void
152 reinit(const size_type n_block_rows, const size_type n_block_columns);
153
154 /**
155 * Resize the matrix, by using an array of index sets to determine the
156 * %parallel distribution of the individual matrices. This function
157 * assumes that a quadratic block matrix is generated.
158 */
159 template <typename BlockSparsityPatternType>
160 void
161 reinit(const std::vector<IndexSet> &input_maps,
162 const BlockSparsityPatternType &block_sparsity_pattern,
163 const MPI_Comm communicator = MPI_COMM_WORLD,
164 const bool exchange_data = false);
165
166 /**
167 * Resize the matrix and initialize it by the given sparsity pattern.
168 * Since no distribution map is given, the result is a block matrix for
169 * which all elements are stored locally.
170 */
171 template <typename BlockSparsityPatternType>
172 void
173 reinit(const BlockSparsityPatternType &block_sparsity_pattern);
174
175 /**
176 * This function initializes the Trilinos matrix using the deal.II sparse
177 * matrix and the entries stored therein. It uses a threshold to copy only
178 * elements whose modulus is larger than the threshold (so zeros in the
179 * deal.II matrix can be filtered away).
180 */
181 void
182 reinit(
183 const std::vector<IndexSet> &parallel_partitioning,
184 const ::dealii::BlockSparseMatrix<double> &dealii_block_sparse_matrix,
185 const MPI_Comm communicator = MPI_COMM_WORLD,
186 const double drop_tolerance = 1e-13);
187
188 /**
189 * This function initializes the Trilinos matrix using the deal.II sparse
190 * matrix and the entries stored therein. It uses a threshold to copy only
191 * elements whose modulus is larger than the threshold (so zeros in the
192 * deal.II matrix can be filtered away). Since no Epetra_Map is given, all
193 * the elements will be locally stored.
194 */
195 void
196 reinit(const ::dealii::BlockSparseMatrix<double> &deal_ii_sparse_matrix,
197 const double drop_tolerance = 1e-13);
198
199 /**
200 * Return the state of the matrix, i.e., whether compress() needs to be
201 * called after an operation requiring data exchange. Does only return
202 * non-true values when used in <tt>debug</tt> mode, since it is quite
203 * expensive to keep track of all operations that lead to the need for
204 * compress().
205 */
206 bool
207 is_compressed() const;
208
209 /**
210 * This function collects the sizes of the sub-objects and stores them in
211 * internal arrays, in order to be able to relay global indices into the
212 * matrix to indices into the subobjects. You *must* call this function
213 * each time after you have changed the size of the sub-objects. Note that
214 * this is a @ref GlossCollectiveOperation "collective operation", i.e.,
215 * it needs to be called on all MPI
216 * processes. This command internally calls the method
217 * <tt>compress()</tt>, so you don't need to call that function in case
218 * you use <tt>collect_sizes()</tt>.
219 */
220 void
221 collect_sizes();
222
223 /**
224 * Return the total number of nonzero elements of this matrix (summed
225 * over all MPI processes).
226 */
227 std::uint64_t
228 n_nonzero_elements() const;
229
230 /**
231 * Return the underlying MPI communicator.
232 */
233 MPI_Comm
234 get_mpi_communicator() const;
235
236 /**
237 * Return the partitioning of the domain space for the individual blocks
238 * of this matrix, i.e., the partitioning of the block vectors this matrix
239 * has to be multiplied with.
240 */
241 std::vector<IndexSet>
242 locally_owned_domain_indices() const;
243
244 /**
245 * Return the partitioning of the range space for the individual blocks of
246 * this matrix, i.e., the partitioning of the block vectors that result
247 * from matrix-vector products.
248 */
249 std::vector<IndexSet>
250 locally_owned_range_indices() const;
251
252 /**
253 * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
254 * matrix. The vector types can be block vectors or non-block vectors
255 * (only if the matrix has only one row or column, respectively), and need
256 * to define TrilinosWrappers::SparseMatrix::vmult.
257 */
258 template <typename VectorType1, typename VectorType2>
259 void
260 vmult(VectorType1 &dst, const VectorType2 &src) const;
261
262 /**
263 * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
264 * matrix. This function does the same as vmult() but takes the transposed
265 * matrix.
266 */
267 template <typename VectorType1, typename VectorType2>
268 void
269 Tvmult(VectorType1 &dst, const VectorType2 &src) const;
270
271 /**
272 * Compute the residual of an equation <i>Mx=b</i>, where the residual is
273 * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
274 * <i>l<sub>2</sub></i> norm of the residual vector is returned.
275 *
276 * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
277 *
278 * Note that both vectors have to be distributed vectors generated using
279 * the same Map as was used for the matrix.
280 *
281 * This function only applicable if the matrix only has one block row.
282 */
283 template <typename VectorType1,
284 typename VectorType2,
285 typename VectorType3>
286 Number
287 residual(VectorType1 &dst,
288 const VectorType2 &x,
289 const VectorType3 &b) const;
290
291 /**
292 * Make the clear() function in the base class visible, though it is
293 * protected.
294 */
295 using BlockMatrixBase<SparseMatrix<Number, MemorySpace>>::clear;
296
297 private:
298 /**
299 * Internal version of (T)vmult with two block vectors
300 */
301 template <typename VectorType1, typename VectorType2>
302 void
303 vmult(VectorType1 &dst,
304 const VectorType2 &src,
305 const bool transpose,
306 const std::bool_constant<true>,
307 const std::bool_constant<true>) const;
308
309 /**
310 * Internal version of (T)vmult where the source vector is a block vector
311 * but the destination vector is a non-block vector
312 */
313 template <typename VectorType1, typename VectorType2>
314 void
315 vmult(VectorType1 &dst,
316 const VectorType2 &src,
317 const bool transpose,
318 const std::bool_constant<false>,
319 const std::bool_constant<true>) const;
320
321 /**
322 * Internal version of (T)vmult where the source vector is a non-block
323 * vector but the destination vector is a block vector
324 */
325 template <typename VectorType1, typename VectorType2>
326 void
327 vmult(VectorType1 &dst,
328 const VectorType2 &src,
329 const bool transpose,
330 const std::bool_constant<true>,
331 const std::bool_constant<false>) const;
332
333 /**
334 * Internal version of (T)vmult where both source vector and the
335 * destination vector are non-block vectors (only defined if the matrix
336 * consists of only one block)
337 */
338 template <typename VectorType1, typename VectorType2>
339 void
340 vmult(VectorType1 &dst,
341 const VectorType2 &src,
342 const bool transpose,
343 const std::bool_constant<false>,
344 const std::bool_constant<false>) const;
345 };
346
347 } // namespace TpetraWrappers
348
349 /** @} */
350
351 // ------------- inline and template functions -----------------
352 namespace TpetraWrappers
353 {
354 template <typename Number, typename MemorySpace>
355 template <typename VectorType1, typename VectorType2>
356 inline void
357 BlockSparseMatrix<Number, MemorySpace>::vmult(VectorType1 &dst,
358 const VectorType2 &src) const
359 {
360 vmult(dst,
361 src,
362 false,
363 std::bool_constant<IsBlockVector<VectorType1>::value>(),
364 std::bool_constant<IsBlockVector<VectorType2>::value>());
365 }
366
367
368
369 template <typename Number, typename MemorySpace>
370 template <typename VectorType1, typename VectorType2>
371 inline void
372 BlockSparseMatrix<Number, MemorySpace>::Tvmult(VectorType1 &dst,
373 const VectorType2 &src) const
374 {
375 vmult(dst,
376 src,
377 true,
378 std::bool_constant<IsBlockVector<VectorType1>::value>(),
379 std::bool_constant<IsBlockVector<VectorType2>::value>());
380 }
381
382
383
384 template <typename Number, typename MemorySpace>
385 template <typename VectorType1, typename VectorType2>
386 inline void
387 BlockSparseMatrix<Number, MemorySpace>::vmult(
388 VectorType1 &dst,
389 const VectorType2 &src,
390 const bool transpose,
391 std::bool_constant<true>,
392 std::bool_constant<true>) const
393 {
394 if (transpose == true)
395 BaseClass::Tvmult_block_block(dst, src);
396 else
397 BaseClass::vmult_block_block(dst, src);
398 }
399
400
401
402 template <typename Number, typename MemorySpace>
403 template <typename VectorType1, typename VectorType2>
404 inline void
405 BlockSparseMatrix<Number, MemorySpace>::vmult(
406 VectorType1 &dst,
407 const VectorType2 &src,
408 const bool transpose,
409 std::bool_constant<false>,
410 std::bool_constant<true>) const
411 {
412 if (transpose == true)
413 BaseClass::Tvmult_nonblock_block(dst, src);
414 else
415 BaseClass::vmult_nonblock_block(dst, src);
416 }
417
418
419
420 template <typename Number, typename MemorySpace>
421 template <typename VectorType1, typename VectorType2>
422 inline void
423 BlockSparseMatrix<Number, MemorySpace>::vmult(
424 VectorType1 &dst,
425 const VectorType2 &src,
426 const bool transpose,
427 std::bool_constant<true>,
428 std::bool_constant<false>) const
429 {
430 if (transpose == true)
431 BaseClass::Tvmult_block_nonblock(dst, src);
432 else
433 BaseClass::vmult_block_nonblock(dst, src);
434 }
435
436
437
438 template <typename Number, typename MemorySpace>
439 template <typename VectorType1, typename VectorType2>
440 inline void
441 BlockSparseMatrix<Number, MemorySpace>::vmult(
442 VectorType1 &dst,
443 const VectorType2 &src,
444 const bool transpose,
445 std::bool_constant<false>,
446 std::bool_constant<false>) const
447 {
448 if (transpose == true)
449 BaseClass::Tvmult_nonblock_nonblock(dst, src);
450 else
451 BaseClass::vmult_nonblock_nonblock(dst, src);
452 }
453 } // namespace TpetraWrappers
454
455 } // namespace LinearAlgebra
456
457
458 DEAL_II_NAMESPACE_CLOSE
459
460 #else
461
462 // Make sure the scripts that create the C++20 module input files have
463 // something to latch on if the preprocessor #ifdef above would
464 // otherwise lead to an empty content of the file.
465 DEAL_II_NAMESPACE_OPEN
466 DEAL_II_NAMESPACE_CLOSE
467
468 #endif // DEAL_II_TRILINOS_WITH_TPETRA
469
470 #endif // dealii_tpetra_trilinos_block_sparse_matrix_h