Debian Codegraph @

include/deal.II/lac/block_sparse_matrix_ez.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2002 - 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_ez_h
16 #define dealii_block_sparse_matrix_ez_h
17
18
19 // TODO: Derive BlockSparseMatrixEZ from BlockMatrixBase, like all the
20 // other block matrices as well; this would allow to instantiate a few
21 // functions with this template argument as well (in particular
22 // AffineConstraints::distribute_local_to_global)
23
24 #include <deal.II/base/config.h>
25
26 #include <deal.II/base/enable_observer_pointer.h>
27 #include <deal.II/base/exceptions.h>
28 #include <deal.II/base/observer_pointer.h>
29 #include <deal.II/base/table.h>
30
31 #include <deal.II/lac/block_indices.h>
32 #include <deal.II/lac/sparse_matrix_ez.h>
33
34 DEAL_II_NAMESPACE_OPEN
35
36 // Forward declaration
37 #ifndef DOXYGEN
38 template <typename Number>
39 class BlockVector;
40 #endif
41
42 /**
43 * @addtogroup Matrix1
44 * @{
45 */
46
47
48 /**
49 * A block matrix consisting of blocks of type SparseMatrixEZ.
50 *
51 * Like the other Block-objects, this matrix can be used like a
52 * SparseMatrixEZ, when it comes to access to entries. Then, there are
53 * functions for the multiplication with BlockVector and access to the
54 * individual blocks.
55 *
56 * @see
57 * @ref GlossBlockLA "Block (linear algebra)"
58 */
59 template <typename Number>
60 class BlockSparseMatrixEZ : public EnableObserverPointer
61 {
62 public:
63 /**
64 * Declare type for container size.
65 */
66 using size_type = types::global_dof_index;
67
68 /**
69 * Default constructor. The result is an empty object with zero dimensions.
70 */
71 BlockSparseMatrixEZ() = default;
72
73 /**
74 * Constructor setting up an object with given number of block rows and
75 * columns. The blocks themselves still have zero dimension.
76 */
77 BlockSparseMatrixEZ(const unsigned int block_rows,
78 const unsigned int block_cols);
79
80 /**
81 * Copy constructor. This is needed for some container classes. It creates
82 * an object of the same number of block rows and columns. Since it calls
83 * the copy constructor of SparseMatrixEZ, the block s must be empty.
84 */
85 BlockSparseMatrixEZ(const BlockSparseMatrixEZ<Number> &);
86
87 /**
88 * Copy operator. Like the copy constructor, this may be called for objects
89 * with empty blocks only.
90 */
91 BlockSparseMatrixEZ &
92 operator=(const BlockSparseMatrixEZ<Number> &);
93
94 /**
95 * This operator assigns a scalar to a matrix. Since this does usually not
96 * make much sense (should we set all matrix entries to this value? Only the
97 * nonzero entries of the sparsity pattern?), this operation is only allowed
98 * if the actual value to be assigned is zero. This operator only exists to
99 * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
100 * of the matrix to zero, but keep the sparsity pattern previously used.
101 */
102 BlockSparseMatrixEZ &
103 operator=(const double d);
104
105
106 /**
107 * Set matrix to zero dimensions and release memory.
108 */
109 void
110 clear();
111
112 /**
113 * Initialize to given block numbers. After this operation, the matrix will
114 * have the block dimensions provided. Each block will have zero dimensions
115 * and must be initialized subsequently. After setting the sizes of the
116 * blocks, collect_sizes() must be called to update internal data
117 * structures.
118 */
119 void
120 reinit(const unsigned int n_block_rows, const unsigned int n_block_cols);
121 /**
122 * This function collects the sizes of the sub-objects and stores them in
123 * internal arrays, in order to be able to relay global indices into the
124 * matrix to indices into the subobjects. You *must* call this function each
125 * time after you have changed the size of the sub-objects.
126 */
127 void
128 collect_sizes();
129
130 /**
131 * Access the block with the given coordinates.
132 */
133 SparseMatrixEZ<Number> &
134 block(const unsigned int row, const unsigned int column);
135
136
137 /**
138 * Access the block with the given coordinates. Version for constant
139 * objects.
140 */
141 const SparseMatrixEZ<Number> &
142 block(const unsigned int row, const unsigned int column) const;
143
144 /**
145 * Return the number of blocks in a column.
146 */
147 unsigned int
148 n_block_rows() const;
149
150 /**
151 * Return the number of blocks in a row.
152 */
153 unsigned int
154 n_block_cols() const;
155
156 /**
157 * Return whether the object is empty. It is empty if no memory is
158 * allocated, which is the same as that both dimensions are zero. This
159 * function is just the concatenation of the respective call to all
160 * sub-matrices.
161 */
162 bool
163 empty() const;
164
165 /**
166 * Return number of rows of this matrix, which equals the dimension of the
167 * codomain (or range) space. It is the sum of the number of rows over the
168 * sub-matrix blocks of this matrix. Recall that the matrix is of size m()
169 * times n().
170 */
171 size_type
172 m() const;
173
174 /**
175 * Return number of columns of this matrix, which equals the dimension of
176 * the domain space. It is the sum of the number of columns over the
177 * sub-matrix blocks of this matrix. Recall that the matrix is of size m()
178 * times n().
179 */
180 size_type
181 n() const;
182
183 /**
184 * Set the element <tt>(i,j)</tt> to @p value. Throws an error if the entry
185 * does not exist or if <tt>value</tt> is not a finite number. Still, it is
186 * allowed to store zero values in non-existent fields.
187 */
188 void
189 set(const size_type i, const size_type j, const Number value);
190
191 /**
192 * Add @p value to the element <tt>(i,j)</tt>. Throws an error if the entry
193 * does not exist or if <tt>value</tt> is not a finite number. Still, it is
194 * allowed to store zero values in non-existent fields.
195 */
196 void
197 add(const size_type i, const size_type j, const Number value);
198
199
200 /**
201 * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
202 * matrix.
203 */
204 template <typename somenumber>
205 void
206 vmult(BlockVector<somenumber> &dst, const BlockVector<somenumber> &src) const;
207
208 /**
209 * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
210 * matrix. This function does the same as vmult() but takes the transposed
211 * matrix.
212 */
213 template <typename somenumber>
214 void
215 Tvmult(BlockVector<somenumber> &dst,
216 const BlockVector<somenumber> &src) const;
217
218 /**
219 * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
220 * this matrix.
221 */
222 template <typename somenumber>
223 void
224 vmult_add(BlockVector<somenumber> &dst,
225 const BlockVector<somenumber> &src) const;
226
227 /**
228 * Adding Matrix-vector multiplication. Add $M^T*src$ to $dst$ with $M$
229 * being this matrix. This function does the same as vmult_add() but takes
230 * the transposed matrix.
231 */
232 template <typename somenumber>
233 void
234 Tvmult_add(BlockVector<somenumber> &dst,
235 const BlockVector<somenumber> &src) const;
236
237
238 /**
239 * Print statistics. If @p full is @p true, prints a histogram of all
240 * existing row lengths and allocated row lengths. Otherwise, just the
241 * relation of allocated and used entries is shown.
242 */
243 template <typename StreamType>
244 void
245 print_statistics(StreamType &s, bool full = false);
246
247 private:
248 /**
249 * Object storing and managing the transformation of row indices to indices
250 * of the sub-objects.
251 */
252 BlockIndices row_indices;
253
254 /**
255 * Object storing and managing the transformation of column indices to
256 * indices of the sub-objects.
257 */
258 BlockIndices column_indices;
259
260 /**
261 * The actual matrices
262 */
263 Table<2, SparseMatrixEZ<Number>> blocks;
264 };
265
266 /** @} */
267 /*----------------------------------------------------------------------*/
268
269
270 template <typename Number>
271 inline unsigned int
272 BlockSparseMatrixEZ<Number>::n_block_rows() const
273 {
274 return row_indices.size();
275 }
276
277
278
279 template <typename Number>
280 inline unsigned int
281 BlockSparseMatrixEZ<Number>::n_block_cols() const
282 {
283 return column_indices.size();
284 }
285
286
287
288 template <typename Number>
289 inline SparseMatrixEZ<Number> &
290 BlockSparseMatrixEZ<Number>::block(const unsigned int row,
291 const unsigned int column)
292 {
293 AssertIndexRange(row, n_block_rows());
294 AssertIndexRange(column, n_block_cols());
295
296 return blocks[row][column];
297 }
298
299
300
301 template <typename Number>
302 inline const SparseMatrixEZ<Number> &
303 BlockSparseMatrixEZ<Number>::block(const unsigned int row,
304 const unsigned int column) const
305 {
306 AssertIndexRange(row, n_block_rows());
307 AssertIndexRange(column, n_block_cols());
308
309 return blocks[row][column];
310 }
311
312
313
314 template <typename Number>
315 inline typename BlockSparseMatrixEZ<Number>::size_type
316 BlockSparseMatrixEZ<Number>::m() const
317 {
318 return row_indices.total_size();
319 }
320
321
322
323 template <typename Number>
324 inline typename BlockSparseMatrixEZ<Number>::size_type
325 BlockSparseMatrixEZ<Number>::n() const
326 {
327 return column_indices.total_size();
328 }
329
330
331
332 template <typename Number>
333 inline void
334 BlockSparseMatrixEZ<Number>::set(const size_type i,
335 const size_type j,
336 const Number value)
337 {
338 AssertIsFinite(value);
339
340 const std::pair<size_type, size_type> row_index =
341 row_indices.global_to_local(i),
342 col_index =
343 column_indices.global_to_local(j);
344 block(row_index.first, col_index.first)
345 .set(row_index.second, col_index.second, value);
346 }
347
348
349
350 template <typename Number>
351 inline void
352 BlockSparseMatrixEZ<Number>::add(const size_type i,
353 const size_type j,
354 const Number value)
355 {
356 AssertIsFinite(value);
357
358 const std::pair<unsigned int, size_type> row_index =
359 row_indices.global_to_local(i),
360 col_index =
361 column_indices.global_to_local(j);
362 block(row_index.first, col_index.first)
363 .add(row_index.second, col_index.second, value);
364 }
365
366
367 template <typename Number>
368 template <typename somenumber>
369 void
370 BlockSparseMatrixEZ<Number>::vmult(BlockVector<somenumber> &dst,
371 const BlockVector<somenumber> &src) const
372 {
373 Assert(dst.n_blocks() == n_block_rows(),
374 ExcDimensionMismatch(dst.n_blocks(), n_block_rows()));
375 Assert(src.n_blocks() == n_block_cols(),
376 ExcDimensionMismatch(src.n_blocks(), n_block_cols()));
377
378 dst = 0.;
379
380 for (unsigned int row = 0; row < n_block_rows(); ++row)
381 for (unsigned int col = 0; col < n_block_cols(); ++col)
382 block(row, col).vmult_add(dst.block(row), src.block(col));
383 }
384
385
386
387 template <typename Number>
388 template <typename somenumber>
389 void
390 BlockSparseMatrixEZ<Number>::vmult_add(BlockVector<somenumber> &dst,
391 const BlockVector<somenumber> &src) const
392 {
393 Assert(dst.n_blocks() == n_block_rows(),
394 ExcDimensionMismatch(dst.n_blocks(), n_block_rows()));
395 Assert(src.n_blocks() == n_block_cols(),
396 ExcDimensionMismatch(src.n_blocks(), n_block_cols()));
397
398 for (unsigned int row = 0; row < n_block_rows(); ++row)
399 for (unsigned int col = 0; col < n_block_cols(); ++col)
400 block(row, col).vmult_add(dst.block(row), src.block(col));
401 }
402
403
404
405 template <typename Number>
406 template <typename somenumber>
407 void
408 BlockSparseMatrixEZ<Number>::Tvmult(BlockVector<somenumber> &dst,
409 const BlockVector<somenumber> &src) const
410 {
411 Assert(dst.n_blocks() == n_block_cols(),
412 ExcDimensionMismatch(dst.n_blocks(), n_block_cols()));
413 Assert(src.n_blocks() == n_block_rows(),
414 ExcDimensionMismatch(src.n_blocks(), n_block_rows()));
415
416 dst = 0.;
417
418 for (unsigned int row = 0; row < n_block_rows(); ++row)
419 for (unsigned int col = 0; col < n_block_cols(); ++col)
420 block(row, col).Tvmult_add(dst.block(col), src.block(row));
421 }
422
423
424
425 template <typename Number>
426 template <typename somenumber>
427 void
428 BlockSparseMatrixEZ<Number>::Tvmult_add(
429 BlockVector<somenumber> &dst,
430 const BlockVector<somenumber> &src) const
431 {
432 Assert(dst.n_blocks() == n_block_cols(),
433 ExcDimensionMismatch(dst.n_blocks(), n_block_cols()));
434 Assert(src.n_blocks() == n_block_rows(),
435 ExcDimensionMismatch(src.n_blocks(), n_block_rows()));
436
437 for (unsigned int row = 0; row < n_block_rows(); ++row)
438 for (unsigned int col = 0; col < n_block_cols(); ++col)
439 block(row, col).Tvmult_add(dst.block(col), src.block(row));
440 }
441
442
443 template <typename number>
444 template <typename StreamType>
445 inline void
446 BlockSparseMatrixEZ<number>::print_statistics(StreamType &out, bool full)
447 {
448 size_type used_total = 0;
449 size_type allocated_total = 0;
450 size_type reserved_total = 0;
451 std::vector<size_type> used_by_line_total;
452
453 size_type used;
454 size_type allocated;
455 size_type reserved;
456 std::vector<size_type> used_by_line;
457
458 for (size_type i = 0; i < n_block_rows(); ++i)
459 for (size_type j = 0; j < n_block_cols(); ++j)
460 {
461 used_by_line.clear();
462 out << "block:\t" << i << '\t' << j << std::endl;
463 block(i, j).compute_statistics(
464 used, allocated, reserved, used_by_line, full);
465
466 out << "used:" << used << std::endl
467 << "allocated:" << allocated << std::endl
468 << "reserved:" << reserved << std::endl;
469
470 used_total += used;
471 allocated_total += allocated;
472 reserved_total += reserved;
473
474 if (full)
475 {
476 used_by_line_total.resize(used_by_line.size());
477 for (size_type i = 0; i < used_by_line.size(); ++i)
478 if (used_by_line[i] != 0)
479 {
480 out << "row-entries\t" << i << "\trows\t" << used_by_line[i]
481 << std::endl;
482 used_by_line_total[i] += used_by_line[i];
483 }
484 }
485 }
486 out << "Total" << std::endl
487 << "used:" << used_total << std::endl
488 << "allocated:" << allocated_total << std::endl
489 << "reserved:" << reserved_total << std::endl;
490 for (size_type i = 0; i < used_by_line_total.size(); ++i)
491 if (used_by_line_total[i] != 0)
492 {
493 out << "row-entries\t" << i << "\trows\t" << used_by_line_total[i]
494 << std::endl;
495 }
496 }
497
498
499 DEAL_II_NAMESPACE_CLOSE
500
501 #endif // dealii_block_sparse_matrix_ez_h