Debian Codegraph @

include/deal.II/lac/petsc_block_sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 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_petsc_block_sparse_matrix_h
16 #define dealii_petsc_block_sparse_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_PETSC
22
23 # include <deal.II/lac/block_matrix_base.h>
24 # include <deal.II/lac/block_sparsity_pattern.h>
25 # include <deal.II/lac/exceptions.h>
26 # include <deal.II/lac/petsc_block_vector.h>
27 # include <deal.II/lac/petsc_sparse_matrix.h>
28
29 # include <cmath>
30 # include <cstddef>
31
32 DEAL_II_NAMESPACE_OPEN
33
34
35
36 namespace PETScWrappers
37 {
38 namespace MPI
39 {
40 /**
41 * @addtogroup PETScWrappers
42 * @{
43 */
44
45 /**
46 * Blocked sparse matrix based on the PETScWrappers::MPI::SparseMatrix
47 * class. This class implements the functions that are specific to the
48 * PETSc SparseMatrix base objects for a blocked sparse matrix, and leaves
49 * the actual work relaying most of the calls to the individual blocks to
50 * the functions implemented in the base class. See there also for a
51 * description of when this class is useful.
52 *
53 * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices
54 * do not have external objects for the sparsity patterns. Thus, one does
55 * not determine the size of the individual blocks of a block matrix of
56 * this type by attaching a block sparsity pattern, but by calling
57 * reinit() to set the number of blocks and then by setting the size of
58 * each block separately. In order to fix the data structures of the block
59 * matrix, it is then necessary to let it know that we have changed the
60 * sizes of the underlying matrices. For this, one has to call the
61 * collect_sizes() function, for much the same reason as is documented
62 * with the BlockSparsityPattern class.
63 *
64 * @ingroup Matrix1
65 * @see @ref GlossBlockLA "Block (linear algebra)"
66 */
67 class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix>
68 {
69 public:
70 /**
71 * Typedef the base class for simpler access to its own alias.
72 */
73 using BaseClass = BlockMatrixBase<SparseMatrix>;
74
75 /**
76 * Typedef the type of the underlying matrix.
77 */
78 using BlockType = BaseClass::BlockType;
79
80 /**
81 * Import the alias from the base class.
82 */
83 using value_type = BaseClass::value_type;
84 using pointer = BaseClass::pointer;
85 using const_pointer = BaseClass::const_pointer;
86 using reference = BaseClass::reference;
87 using const_reference = BaseClass::const_reference;
88 using size_type = BaseClass::size_type;
89 using iterator = BaseClass::iterator;
90 using const_iterator = BaseClass::const_iterator;
91
92 /**
93 * Constructor; initializes the matrix to be empty, without any
94 * structure, i.e. the matrix is not usable at all. This constructor is
95 * therefore only useful for matrices which are members of a class. All
96 * other matrices should be created at a point in the data flow where
97 * all necessary information is available.
98 *
99 * You have to initialize the matrix before usage with
100 * reinit(BlockSparsityPattern). The number of blocks per row and column
101 * are then determined by that function.
102 */
103 BlockSparseMatrix();
104
105 /**
106 * Create a BlockSparseMatrix with a PETSc Mat that describes the entire
107 * block matrix.
108 * It infers the number of blocks from the Mat if it is of type MATNEST,
109 * otherwise the block operator will only have a single block.
110 * Internally, we always store a MATNEST matrix.
111 */
112 explicit BlockSparseMatrix(const Mat &);
113
114 /**
115 * Create a BlockSparseMatrix with an array of PETSc matrices.
116 */
117 template <std::size_t block_rows, std::size_t block_columns>
118 explicit BlockSparseMatrix(
119 const std::array<std::array<Mat, block_columns>, block_rows> &);
120
121 /**
122 * Destructor.
123 */
124 ~BlockSparseMatrix() override;
125
126 /**
127 * Pseudo copy operator only copying empty objects. The sizes of the
128 * block matrices need to be the same.
129 */
130 BlockSparseMatrix &
131 operator=(const BlockSparseMatrix &);
132
133 /**
134 * This operator assigns a scalar to a matrix. Since this does usually
135 * not make much sense (should we set all matrix entries to this value?
136 * Only the nonzero entries of the sparsity pattern?), this operation is
137 * only allowed if the actual value to be assigned is zero. This
138 * operator only exists to allow for the obvious notation
139 * <tt>matrix=0</tt>, which sets all elements of the matrix to zero, but
140 * keep the sparsity pattern previously used.
141 */
142 BlockSparseMatrix &
143 operator=(const double d);
144
145 /**
146 * Resize the matrix, by setting the number of block rows and columns.
147 * This deletes all blocks and replaces them with uninitialized ones,
148 * i.e. ones for which also the sizes are not yet set. You have to do
149 * that by calling the @p reinit functions of the blocks themselves. Do
150 * not forget to call collect_sizes() after that on this object.
151 *
152 * The reason that you have to set sizes of the blocks yourself is that
153 * the sizes may be varying, the maximum number of elements per row may
154 * be varying, etc. It is simpler not to reproduce the interface of the
155 * SparsityPattern class here but rather let the user call whatever
156 * function they desire.
157 */
158 void
159 reinit(const size_type n_block_rows, const size_type n_block_columns);
160
161
162 /**
163 * Efficiently reinit the block matrix for a parallel computation. Only
164 * the BlockSparsityPattern of the Simple type can efficiently store
165 * large sparsity patterns in parallel, so this is the only supported
166 * argument. The IndexSets describe the locally owned range of DoFs for
167 * each block. Note that the IndexSets needs to be ascending and 1:1.
168 * For a symmetric structure hand in the same vector for the first two
169 * arguments.
170 */
171 void
172 reinit(const std::vector<IndexSet> &rows,
173 const std::vector<IndexSet> &cols,
174 const BlockDynamicSparsityPattern &bdsp,
175 const MPI_Comm com);
176
177
178 /**
179 * Same as above but for a symmetric structure only.
180 */
181 void
182 reinit(const std::vector<IndexSet> &sizes,
183 const BlockDynamicSparsityPattern &bdsp,
184 const MPI_Comm com);
185
186
187 /**
188 * This method associates the PETSc Mat to the instance of the class.
189 * Infers the number of blocks from A if it is of type MATNEST, otherwise
190 * the block operator will only have a single block.
191 */
192 void
193 reinit(Mat A);
194
195
196 /**
197 * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
198 * matrix.
199 */
200 void
201 vmult(BlockVector &dst, const BlockVector &src) const;
202
203 /**
204 * Matrix-vector multiplication. Just like the previous function, but
205 * only applicable if the matrix has only one block column.
206 */
207 void
208 vmult(BlockVector &dst, const Vector &src) const;
209
210 /**
211 * Matrix-vector multiplication. Just like the previous function, but
212 * only applicable if the matrix has only one block row.
213 */
214 void
215 vmult(Vector &dst, const BlockVector &src) const;
216
217 /**
218 * Matrix-vector multiplication. Just like the previous function, but
219 * only applicable if the matrix has only one block.
220 */
221 void
222 vmult(Vector &dst, const Vector &src) const;
223
224 /**
225 * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
226 * matrix. This function does the same as vmult() but takes the
227 * transposed matrix.
228 */
229 void
230 Tvmult(BlockVector &dst, const BlockVector &src) const;
231
232 /**
233 * Matrix-vector multiplication. Just like the previous function, but
234 * only applicable if the matrix has only one block row.
235 */
236 void
237 Tvmult(BlockVector &dst, const Vector &src) const;
238
239 /**
240 * Matrix-vector multiplication. Just like the previous function, but
241 * only applicable if the matrix has only one block column.
242 */
243 void
244 Tvmult(Vector &dst, const BlockVector &src) const;
245
246 /**
247 * Matrix-vector multiplication. Just like the previous function, but
248 * only applicable if the matrix has only one block.
249 */
250 void
251 Tvmult(Vector &dst, const Vector &src) const;
252
253 /**
254 * This function collects the sizes of the sub-objects and stores them
255 * in internal arrays, in order to be able to relay global indices into
256 * the matrix to indices into the subobjects. You *must* call this
257 * function each time after you have changed the size of the sub-objects.
258 */
259 void
260 collect_sizes();
261
262 /**
263 * Call the compress() function on all the subblocks of the matrix
264 * and update the internal state of the PETSc object.
265 *
266 * See
267 * @ref GlossCompress "Compressing distributed objects"
268 * for more information.
269 */
270 void
271 compress(VectorOperation::values operation);
272
273 /**
274 * Return the partitioning of the domain space of this matrix, i.e., the
275 * partitioning of the vectors this matrix has to be multiplied with.
276 */
277 std::vector<IndexSet>
278 locally_owned_domain_indices() const;
279
280 /**
281 * Return the partitioning of the range space of this matrix, i.e., the
282 * partitioning of the vectors that are result from matrix-vector
283 * products.
284 */
285 std::vector<IndexSet>
286 locally_owned_range_indices() const;
287
288 /**
289 * Return the number of nonzero elements of this matrix. Actually, it
290 * returns the number of entries in the sparsity pattern; if any of the
291 * entries should happen to be zero, it is counted anyway.
292 */
293 std::uint64_t
294 n_nonzero_elements() const;
295
296 /**
297 * Return the underlying MPI communicator.
298 */
299 MPI_Comm
300 get_mpi_communicator() const;
301
302 /**
303 * Make the clear() function in the base class visible, though it is
304 * protected.
305 */
306 using BlockMatrixBase<SparseMatrix>::clear;
307
308 /**
309 * Conversion operator to gain access to the underlying PETSc type. If you
310 * do this, you cut this class off some information it may need, so this
311 * conversion operator should only be used if you know what you do. In
312 * particular, it should only be used for read-only operations into the
313 * matrix.
314 */
315 operator const Mat &() const;
316
317 /**
318 * Return a reference to the underlying PETSc type. It can be used to
319 * modify the underlying data, so use it only when you know what you
320 * are doing.
321 *
322 * The PETSc Mat object returned here describes the *entire* matrix,
323 * not just one of its blocks. Internally, this is done using
324 * a "nested" matrix using PETSc's MATNEST object whose individual
325 * blocks are the blocks of this matrix.
326 */
327 Mat &
328 petsc_matrix();
329
330 private:
331 /**
332 * A PETSc Mat object that describes the entire block matrix.
333 * Internally, this is done by creating
334 * a "nested" matrix using PETSc's MATNEST object whose individual
335 * blocks are the blocks of this matrix.
336 */
337 Mat petsc_nest_matrix;
338
339 /**
340 * Utility to set up the MATNEST object.
341 */
342 void
343 setup_nest_mat();
344
345 /**
346 * An utility method to populate empty blocks with actual objects.
347 * This is needed because MATNEST supports nullptr as a block,
348 * while the BlockMatrixBase class does not.
349 */
350 void
351 create_empty_matrices_if_needed();
352 };
353
354
355
356 /** @} */
357
358 // ------------- inline and template functions -----------------
359 inline BlockSparseMatrix::BlockSparseMatrix()
360 : BaseClass()
361 , petsc_nest_matrix(nullptr)
362 {}
363
364
365
366 inline BlockSparseMatrix::BlockSparseMatrix(const Mat &A)
367 : BlockSparseMatrix()
368 {
369 this->reinit(A);
370 }
371
372
373
374 template <std::size_t block_rows, std::size_t block_columns>
375 inline BlockSparseMatrix::BlockSparseMatrix(
376 const std::array<std::array<Mat, block_columns>, block_rows> &arrayA)
377 : BlockSparseMatrix()
378 {
379 this->reinit(block_rows, block_columns);
380 this->sub_objects.reinit(block_rows, block_columns);
381 for (auto r = 0; r < block_rows; ++r)
382 for (auto c = 0; c < block_columns; ++c)
383 {
384 if (arrayA[r][c])
385 this->sub_objects[r][c] = new BlockType(arrayA[r][c]);
386 else
387 this->sub_objects[r][c] = nullptr;
388 }
389 this->collect_sizes();
390 }
391
392
393
394 inline BlockSparseMatrix &
395 BlockSparseMatrix::operator=(const double d)
396 {
397 Assert(d == 0, ExcScalarAssignmentOnlyForZeroValue());
398
399 for (size_type r = 0; r < this->n_block_rows(); ++r)
400 for (size_type c = 0; c < this->n_block_cols(); ++c)
401 this->block(r, c) = d;
402
403 return *this;
404 }
405
406
407
408 inline void
409 BlockSparseMatrix::vmult(BlockVector &dst, const BlockVector &src) const
410 {
411 BaseClass::vmult_block_block(dst, src);
412 }
413
414
415
416 inline void
417 BlockSparseMatrix::vmult(BlockVector &dst, const Vector &src) const
418 {
419 BaseClass::vmult_block_nonblock(dst, src);
420 }
421
422
423
424 inline void
425 BlockSparseMatrix::vmult(Vector &dst, const BlockVector &src) const
426 {
427 BaseClass::vmult_nonblock_block(dst, src);
428 }
429
430
431
432 inline void
433 BlockSparseMatrix::vmult(Vector &dst, const Vector &src) const
434 {
435 BaseClass::vmult_nonblock_nonblock(dst, src);
436 }
437
438
439 inline void
440 BlockSparseMatrix::Tvmult(BlockVector &dst, const BlockVector &src) const
441 {
442 BaseClass::Tvmult_block_block(dst, src);
443 }
444
445
446
447 inline void
448 BlockSparseMatrix::Tvmult(BlockVector &dst, const Vector &src) const
449 {
450 BaseClass::Tvmult_block_nonblock(dst, src);
451 }
452
453
454
455 inline void
456 BlockSparseMatrix::Tvmult(Vector &dst, const BlockVector &src) const
457 {
458 BaseClass::Tvmult_nonblock_block(dst, src);
459 }
460
461
462
463 inline void
464 BlockSparseMatrix::Tvmult(Vector &dst, const Vector &src) const
465 {
466 BaseClass::Tvmult_nonblock_nonblock(dst, src);
467 }
468
469 } // namespace MPI
470
471 } // namespace PETScWrappers
472
473
474 DEAL_II_NAMESPACE_CLOSE
475
476
477 #else
478
479 // Make sure the scripts that create the C++20 module input files have
480 // something to latch on if the preprocessor #ifdef above would
481 // otherwise lead to an empty content of the file.
482 DEAL_II_NAMESPACE_OPEN
483 DEAL_II_NAMESPACE_CLOSE
484
485 #endif // DEAL_II_WITH_PETSC
486
487 #endif // dealii_petsc_block_sparse_matrix_h