Debian Codegraph @

include/deal.II/lac/block_sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2000 - 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_block_sparse_matrix_h
16 #define dealii_block_sparse_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/lac/block_matrix_base.h>
22 #include <deal.II/lac/block_sparsity_pattern.h>
23 #include <deal.II/lac/block_vector.h>
24 #include <deal.II/lac/exceptions.h>
25 #include <deal.II/lac/sparse_matrix.h>
26
27 #include <cmath>
28
29 DEAL_II_NAMESPACE_OPEN
30
31
32 /**
33 * @addtogroup Matrix1
34 * @{
35 */
36
37
38 /**
39 * Blocked sparse matrix based on the SparseMatrix class. This class
40 * implements the functions that are specific to the SparseMatrix base objects
41 * for a blocked sparse matrix, and leaves the actual work relaying most of
42 * the calls to the individual blocks to the functions implemented in the base
43 * class. See there also for a description of when this class is useful.
44 *
45 * @see
46 * @ref GlossBlockLA "Block (linear algebra)"
47 */
48 template <typename number>
49 class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix<number>>
50 {
51 public:
52 /**
53 * Typedef the base class for simpler access to its own alias.
54 */
55 using BaseClass = BlockMatrixBase<SparseMatrix<number>>;
56
57 /**
58 * Typedef the type of the underlying matrix.
59 */
60 using BlockType = typename BaseClass::BlockType;
61
62 /**
63 * Import the alias from the base class.
64 */
65 using value_type = typename BaseClass::value_type;
66 using pointer = typename BaseClass::pointer;
67 using const_pointer = typename BaseClass::const_pointer;
68 using reference = typename BaseClass::reference;
69 using const_reference = typename BaseClass::const_reference;
70 using size_type = typename BaseClass::size_type;
71 using iterator = typename BaseClass::iterator;
72 using const_iterator = typename BaseClass::const_iterator;
73
74 /**
75 * @name Constructors and initialization
76 */
77 /** @{ */
78 /**
79 * Constructor; initializes the matrix to be empty, without any structure,
80 * i.e. the matrix is not usable at all. This constructor is therefore only
81 * useful for matrices which are members of a class. All other matrices
82 * should be created at a point in the data flow where all necessary
83 * information is available.
84 *
85 * You have to initialize the matrix before usage with
86 * reinit(BlockSparsityPattern). The number of blocks per row and column are
87 * then determined by that function.
88 */
89 BlockSparseMatrix() = default;
90
91 /**
92 * Constructor. Takes the given matrix sparsity structure to represent the
93 * sparsity pattern of this matrix. You can change the sparsity pattern
94 * later on by calling the reinit() function.
95 *
96 * This constructor initializes all sub-matrices with the sub-sparsity
97 * pattern within the argument.
98 *
99 * You have to make sure that the lifetime of the sparsity structure is at
100 * least as long as that of this matrix or as long as reinit() is not called
101 * with a new sparsity structure.
102 */
103 BlockSparseMatrix(const BlockSparsityPattern &sparsity);
104
105 /**
106 * Destructor.
107 */
108 virtual ~BlockSparseMatrix() override;
109
110
111
112 /**
113 * Pseudo copy operator only copying empty objects. The sizes of the block
114 * matrices need to be the same.
115 */
116 BlockSparseMatrix &
117 operator=(const BlockSparseMatrix &);
118
119 /**
120 * This operator assigns a scalar to a matrix. Since this does usually not
121 * make much sense (should we set all matrix entries to this value? Only the
122 * nonzero entries of the sparsity pattern?), this operation is only allowed
123 * if the actual value to be assigned is zero. This operator only exists to
124 * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
125 * of the matrix to zero, but keep the sparsity pattern previously used.
126 */
127 BlockSparseMatrix &
128 operator=(const double d);
129
130 /**
131 * Release all memory and return to a state just like after having called
132 * the default constructor. It also forgets the sparsity pattern it was
133 * previously tied to.
134 *
135 * This calls SparseMatrix::clear on all sub-matrices and then resets this
136 * object to have no blocks at all.
137 */
138 void
139 clear();
140
141 /**
142 * Reinitialize the sparse matrix with the given sparsity pattern. The
143 * latter tells the matrix how many nonzero elements there need to be
144 * reserved.
145 *
146 * Basically, this function only calls SparseMatrix::reinit() of the
147 * sub-matrices with the block sparsity patterns of the parameter.
148 *
149 * You have to make sure that the lifetime of the sparsity structure is at
150 * least as long as that of this matrix or as long as reinit(const
151 * SparsityPattern &) is not called with a new sparsity structure.
152 *
153 * The elements of the matrix are set to zero by this function.
154 */
155 virtual void
156 reinit(const BlockSparsityPattern &sparsity);
157 /** @} */
158
159 /**
160 * @name Information on the matrix
161 */
162 /** @{ */
163 /**
164 * Return whether the object is empty. It is empty if either both dimensions
165 * are zero or no BlockSparsityPattern is associated.
166 */
167 bool
168 empty() const;
169
170 /**
171 * Return the number of entries in a specific row.
172 */
173 size_type
174 get_row_length(const size_type row) const;
175
176 /**
177 * Return the number of nonzero elements of this matrix. Actually, it
178 * returns the number of entries in the sparsity pattern; if any of the
179 * entries should happen to be zero, it is counted anyway.
180 */
181 size_type
182 n_nonzero_elements() const;
183
184 /**
185 * Return the number of actually nonzero elements. Just counts the number of
186 * actually nonzero elements (with absolute value larger than threshold) of
187 * all the blocks.
188 */
189 size_type
190 n_actually_nonzero_elements(const double threshold = 0.0) const;
191
192 /**
193 * Return a (constant) reference to the underlying sparsity pattern of this
194 * matrix.
195 *
196 * Though the return value is declared <tt>const</tt>, you should be aware
197 * that it may change if you call any nonconstant function of objects which
198 * operate on it.
199 */
200 const BlockSparsityPattern &
201 get_sparsity_pattern() const;
202
203 /**
204 * Determine an estimate for the memory consumption (in bytes) of this
205 * object.
206 */
207 std::size_t
208 memory_consumption() const;
209 /** @} */
210
211 /**
212 * @name Multiplications
213 */
214 /** @{ */
215 /**
216 * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
217 * matrix.
218 */
219 template <typename block_number>
220 void
221 vmult(BlockVector<block_number> &dst,
222 const BlockVector<block_number> &src) const;
223
224 /**
225 * Matrix-vector multiplication. Just like the previous function, but only
226 * applicable if the matrix has only one block column.
227 */
228 template <typename block_number, typename nonblock_number>
229 void
230 vmult(BlockVector<block_number> &dst,
231 const Vector<nonblock_number> &src) const;
232
233 /**
234 * Matrix-vector multiplication. Just like the previous function, but only
235 * applicable if the matrix has only one block row.
236 */
237 template <typename block_number, typename nonblock_number>
238 void
239 vmult(Vector<nonblock_number> &dst,
240 const BlockVector<block_number> &src) const;
241
242 /**
243 * Matrix-vector multiplication. Just like the previous function, but only
244 * applicable if the matrix has only one block.
245 */
246 template <typename nonblock_number>
247 void
248 vmult(Vector<nonblock_number> &dst, const Vector<nonblock_number> &src) const;
249
250 /**
251 * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
252 * matrix. This function does the same as vmult() but takes the transposed
253 * matrix.
254 */
255 template <typename block_number>
256 void
257 Tvmult(BlockVector<block_number> &dst,
258 const BlockVector<block_number> &src) const;
259
260 /**
261 * Matrix-vector multiplication. Just like the previous function, but only
262 * applicable if the matrix has only one block row.
263 */
264 template <typename block_number, typename nonblock_number>
265 void
266 Tvmult(BlockVector<block_number> &dst,
267 const Vector<nonblock_number> &src) const;
268
269 /**
270 * Matrix-vector multiplication. Just like the previous function, but only
271 * applicable if the matrix has only one block column.
272 */
273 template <typename block_number, typename nonblock_number>
274 void
275 Tvmult(Vector<nonblock_number> &dst,
276 const BlockVector<block_number> &src) const;
277
278 /**
279 * Matrix-vector multiplication. Just like the previous function, but only
280 * applicable if the matrix has only one block.
281 */
282 template <typename nonblock_number>
283 void
284 Tvmult(Vector<nonblock_number> &dst,
285 const Vector<nonblock_number> &src) const;
286 /** @} */
287
288 /**
289 * @name Preconditioning methods
290 */
291 /** @{ */
292 /**
293 * Apply the Jacobi preconditioner, which multiplies every element of the
294 * <tt>src</tt> vector by the inverse of the respective diagonal element and
295 * multiplies the result with the relaxation parameter <tt>omega</tt>.
296 *
297 * All diagonal blocks must be square matrices for this operation.
298 */
299 template <typename BlockVectorType>
300 void
301 precondition_Jacobi(BlockVectorType &dst,
302 const BlockVectorType &src,
303 const number omega = 1.) const;
304
305 /**
306 * Apply the Jacobi preconditioner to a simple vector.
307 *
308 * The matrix must be a single square block for this.
309 */
310 template <typename number2>
311 void
312 precondition_Jacobi(Vector<number2> &dst,
313 const Vector<number2> &src,
314 const number omega = 1.) const;
315 /** @} */
316
317 /**
318 * @name Input/Output
319 */
320 /** @{ */
321 /**
322 * Print the matrix in the usual format, i.e., as a matrix and not as a list
323 * of nonzero elements. For better readability, elements not in the matrix
324 * are displayed as empty space, while matrix elements which are explicitly
325 * set to zero are displayed as such.
326 *
327 * The parameters allow for a flexible setting of the output format:
328 * @p precision and @p scientific are used to determine the number format,
329 * where <code>scientific = false</code> means fixed point notation. A zero
330 * entry for @p width makes the function compute a width, but it may be
331 * changed to a positive value, if output is crude.
332 *
333 * Additionally, a character for an empty value may be specified in
334 * @p zero_string, and a character to separate row entries can be set in
335 * @p separator.
336 *
337 * Finally, the whole matrix can be multiplied with a common @p denominator
338 * to produce more readable output, even integers.
339 *
340 * @attention This function may produce @em large amounts of output if
341 * applied to a large matrix!
342 */
343 void
344 print_formatted(std::ostream &out,
345 const unsigned int precision = 3,
346 const bool scientific = true,
347 const unsigned int width = 0,
348 const char *zero_string = " ",
349 const double denominator = 1.,
350 const char *separator = " ") const;
351 /** @} */
352 /**
353 * @addtogroup Exceptions
354 * @{
355 */
356
357 /**
358 * Exception
359 */
360 DeclException0(ExcBlockDimensionMismatch);
361 /** @} */
362
363 private:
364 /**
365 * Pointer to the block sparsity pattern used for this matrix. In order to
366 * guarantee that it is not deleted while still in use, we subscribe to it
367 * using the ObserverPointer class.
368 */
369 ObserverPointer<const BlockSparsityPattern, BlockSparseMatrix<number>>
370 sparsity_pattern;
371 };
372
373
374
375 /** @} */
376 /* ------------------------- Template functions ---------------------- */
377
378
379
380 template <typename number>
381 inline BlockSparseMatrix<number> &
382 BlockSparseMatrix<number>::operator=(const double d)
383 {
384 Assert(d == 0, ExcScalarAssignmentOnlyForZeroValue());
385
386 for (size_type r = 0; r < this->n_block_rows(); ++r)
387 for (size_type c = 0; c < this->n_block_cols(); ++c)
388 this->block(r, c) = d;
389
390 return *this;
391 }
392
393
394
395 template <typename number>
396 template <typename block_number>
397 inline void
398 BlockSparseMatrix<number>::vmult(BlockVector<block_number> &dst,
399 const BlockVector<block_number> &src) const
400 {
401 BaseClass::vmult_block_block(dst, src);
402 }
403
404
405
406 template <typename number>
407 template <typename block_number, typename nonblock_number>
408 inline void
409 BlockSparseMatrix<number>::vmult(BlockVector<block_number> &dst,
410 const Vector<nonblock_number> &src) const
411 {
412 BaseClass::vmult_block_nonblock(dst, src);
413 }
414
415
416
417 template <typename number>
418 template <typename block_number, typename nonblock_number>
419 inline void
420 BlockSparseMatrix<number>::vmult(Vector<nonblock_number> &dst,
421 const BlockVector<block_number> &src) const
422 {
423 BaseClass::vmult_nonblock_block(dst, src);
424 }
425
426
427
428 template <typename number>
429 template <typename nonblock_number>
430 inline void
431 BlockSparseMatrix<number>::vmult(Vector<nonblock_number> &dst,
432 const Vector<nonblock_number> &src) const
433 {
434 BaseClass::vmult_nonblock_nonblock(dst, src);
435 }
436
437
438
439 template <typename number>
440 template <typename block_number>
441 inline void
442 BlockSparseMatrix<number>::Tvmult(BlockVector<block_number> &dst,
443 const BlockVector<block_number> &src) const
444 {
445 BaseClass::Tvmult_block_block(dst, src);
446 }
447
448
449
450 template <typename number>
451 template <typename block_number, typename nonblock_number>
452 inline void
453 BlockSparseMatrix<number>::Tvmult(BlockVector<block_number> &dst,
454 const Vector<nonblock_number> &src) const
455 {
456 BaseClass::Tvmult_block_nonblock(dst, src);
457 }
458
459
460
461 template <typename number>
462 template <typename block_number, typename nonblock_number>
463 inline void
464 BlockSparseMatrix<number>::Tvmult(Vector<nonblock_number> &dst,
465 const BlockVector<block_number> &src) const
466 {
467 BaseClass::Tvmult_nonblock_block(dst, src);
468 }
469
470
471
472 template <typename number>
473 template <typename nonblock_number>
474 inline void
475 BlockSparseMatrix<number>::Tvmult(Vector<nonblock_number> &dst,
476 const Vector<nonblock_number> &src) const
477 {
478 BaseClass::Tvmult_nonblock_nonblock(dst, src);
479 }
480
481
482
483 template <typename number>
484 template <typename BlockVectorType>
485 inline void
486 BlockSparseMatrix<number>::precondition_Jacobi(BlockVectorType &dst,
487 const BlockVectorType &src,
488 const number omega) const
489 {
490 Assert(this->n_block_rows() == this->n_block_cols(), ExcNotQuadratic());
491 Assert(dst.n_blocks() == this->n_block_rows(),
492 ExcDimensionMismatch(dst.n_blocks(), this->n_block_rows()));
493 Assert(src.n_blocks() == this->n_block_cols(),
494 ExcDimensionMismatch(src.n_blocks(), this->n_block_cols()));
495
496 // do a diagonal preconditioning. uses only
497 // the diagonal blocks of the matrix
498 for (size_type i = 0; i < this->n_block_rows(); ++i)
499 this->block(i, i).precondition_Jacobi(dst.block(i), src.block(i), omega);
500 }
501
502
503
504 template <typename number>
505 template <typename number2>
506 inline void
507 BlockSparseMatrix<number>::precondition_Jacobi(Vector<number2> &dst,
508 const Vector<number2> &src,
509 const number omega) const
510 {
511 // check number of blocks. the sizes of the
512 // single block is checked in the function
513 // we call
514 Assert(this->n_block_cols() == 1,
515 ExcMessage("This function only works if the matrix has "
516 "a single block"));
517 Assert(this->n_block_rows() == 1,
518 ExcMessage("This function only works if the matrix has "
519 "a single block"));
520
521 // do a diagonal preconditioning. uses only
522 // the diagonal blocks of the matrix
523 this->block(0, 0).precondition_Jacobi(dst, src, omega);
524 }
525
526
527 DEAL_II_NAMESPACE_CLOSE
528
529 #endif // dealii_block_sparse_matrix_h