Debian Codegraph @

include/deal.II/lac/precondition_block_base.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 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_precondition_block_base_h
16 #define dealii_precondition_block_base_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/logstream.h>
24 #include <deal.II/base/memory_consumption.h>
25 #include <deal.II/base/observer_pointer.h>
26
27 #include <deal.II/lac/householder.h>
28 #include <deal.II/lac/lapack_full_matrix.h>
29
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 #ifndef DOXYGEN
36 template <typename number>
37 class FullMatrix;
38 template <typename number>
39 class Vector;
40 #endif
41
42 /**
43 * A class storing the inverse diagonal blocks for block preconditioners and
44 * block relaxation methods.
45 *
46 * This class does the book keeping for preconditioners and relaxation methods
47 * based on inverting blocks on the diagonal of a matrix. It allows us to
48 * either store all diagonal blocks and their inverses or the same block for
49 * each entry, and it keeps track of the choice. Thus, after initializing it
50 * and filling the inverse diagonal blocks correctly, a derived class can use
51 * inverse() with an integer argument referring to the block number.
52 *
53 * Additionally, it allows the storage of the original diagonal blocks, not
54 * only the inverses. These are for instance used in the intermediate step of
55 * the SSOR preconditioner.
56 */
57 template <typename number>
58 class PreconditionBlockBase
59 {
60 public:
61 /**
62 * Declare type for container size.
63 */
64 using size_type = types::global_dof_index;
65
66 /**
67 * Choose a method for inverting the blocks, and thus the data type for the
68 * inverses.
69 */
70 enum Inversion
71 {
72 /**
73 * Use the standard Gauss-Jacobi method implemented in
74 * FullMatrix::inverse().
75 */
76 gauss_jordan,
77 /**
78 * Use QR decomposition of the Householder class.
79 */
80 householder,
81 /**
82 * Use the singular value decomposition of LAPACKFullMatrix.
83 */
84 svd
85 };
86
87 /**
88 * Constructor initializing default values.
89 */
90 PreconditionBlockBase(bool store_diagonals = false,
91 Inversion method = gauss_jordan);
92
93 /**
94 * The virtual destructor
95 */
96 ~PreconditionBlockBase() = default;
97
98 /**
99 * Deletes the inverse diagonal block matrices if existent hence leaves the
100 * class in the state that it had directly after calling the constructor.
101 */
102 void
103 clear();
104
105 /**
106 * Resize to this number of diagonal blocks with the given block size. If
107 * <tt>compress</tt> is true, then only one block will be stored.
108 */
109 void
110 reinit(unsigned int nblocks,
111 size_type blocksize,
112 bool compress,
113 Inversion method = gauss_jordan);
114
115 /**
116 * Tell the class that inverses are computed.
117 */
118 void
119 inverses_computed(bool are_they);
120
121 /**
122 * Does the matrix use only one diagonal block?
123 */
124 bool
125 same_diagonal() const;
126
127 /**
128 * Check, whether diagonal blocks (not their inverses) should be stored.
129 */
130 bool
131 store_diagonals() const;
132
133 /**
134 * Return true, if inverses are ready for use.
135 */
136 bool
137 inverses_ready() const;
138
139 /**
140 * The number of blocks.
141 */
142 unsigned int
143 size() const;
144
145 /**
146 * Multiply with the inverse block at position <tt>i</tt>.
147 */
148 template <typename number2>
149 void
150 inverse_vmult(size_type i,
151 Vector<number2> &dst,
152 const Vector<number2> &src) const;
153
154 /**
155 * Multiply with the transposed inverse block at position <tt>i</tt>.
156 */
157 template <typename number2>
158 void
159 inverse_Tvmult(size_type i,
160 Vector<number2> &dst,
161 const Vector<number2> &src) const;
162
163 /**
164 * Access to the inverse diagonal blocks if Inversion is #gauss_jordan.
165 */
166 FullMatrix<number> &
167 inverse(size_type i);
168
169 /**
170 * Access to the inverse diagonal blocks if Inversion is #householder.
171 */
172 Householder<number> &
173 inverse_householder(size_type i);
174
175 /**
176 * Access to the inverse diagonal blocks if Inversion is #householder.
177 */
178 LAPACKFullMatrix<number> &
179 inverse_svd(size_type i);
180
181 /**
182 * Access to the inverse diagonal blocks.
183 */
184 const FullMatrix<number> &
185 inverse(size_type i) const;
186
187 /**
188 * Access to the inverse diagonal blocks if Inversion is #householder.
189 */
190 const Householder<number> &
191 inverse_householder(size_type i) const;
192
193 /**
194 * Access to the inverse diagonal blocks if Inversion is #householder.
195 */
196 const LAPACKFullMatrix<number> &
197 inverse_svd(size_type i) const;
198
199 /**
200 * Access to the diagonal blocks.
201 */
202 FullMatrix<number> &
203 diagonal(size_type i);
204
205 /**
206 * Access to the diagonal blocks.
207 */
208 const FullMatrix<number> &
209 diagonal(size_type i) const;
210
211 /**
212 * Print some statistics about the inverses to @p deallog. Output depends on
213 * #Inversion. It is richest for svd, where we obtain statistics on extremal
214 * singular values and condition numbers.
215 */
216 void
217 log_statistics() const;
218
219 /**
220 * Determine an estimate for the memory consumption (in bytes) of this
221 * object.
222 */
223 std::size_t
224 memory_consumption() const;
225
226 /**
227 * You are trying to access a diagonal block (not its inverse), but you
228 * decided not to store the diagonal blocks.
229 */
230 DeclException0(ExcDiagonalsNotStored);
231
232 /**
233 * You are accessing a diagonal block, assuming that it has a certain type.
234 * But, the method used for inverting the diagonal blocks does not use this
235 * type
236 */
237 DeclException0(ExcInverseNotAvailable);
238
239 protected:
240 /**
241 * The method used for inverting blocks.
242 */
243 Inversion inversion;
244
245 private:
246 /**
247 * The number of (inverse) diagonal blocks, if only one is stored.
248 */
249 unsigned int n_diagonal_blocks;
250
251 /**
252 * Storage of the inverse matrices of the diagonal blocks matrices as
253 * <tt>FullMatrix<number></tt> matrices, if Inversion #gauss_jordan is used.
254 * Using <tt>number=float</tt> saves memory in comparison with
255 * <tt>number=double</tt>, but may introduce numerical instability.
256 */
257 std::vector<FullMatrix<number>> var_inverse_full;
258
259 /**
260 * Storage of the inverse matrices of the diagonal blocks matrices as
261 * <tt>Householder</tt> matrices if Inversion #householder is used. Using
262 * <tt>number=float</tt> saves memory in comparison with
263 * <tt>number=double</tt>, but may introduce numerical instability.
264 */
265 std::vector<Householder<number>> var_inverse_householder;
266
267 /**
268 * Storage of the inverse matrices of the diagonal blocks matrices as
269 * <tt>LAPACKFullMatrix</tt> matrices if Inversion #svd is used. Using
270 * <tt>number=float</tt> saves memory in comparison with
271 * <tt>number=double</tt>, but may introduce numerical instability.
272 */
273 std::vector<LAPACKFullMatrix<number>> var_inverse_svd;
274
275 /**
276 * Storage of the original diagonal blocks.
277 *
278 * Used by the blocked SSOR method.
279 */
280 std::vector<FullMatrix<number>> var_diagonal;
281
282
283 /**
284 * This is true, if the field #var_diagonal is to be used.
285 */
286 bool var_store_diagonals;
287
288 /**
289 * This is true, if only one inverse is stored.
290 */
291 bool var_same_diagonal;
292
293 /**
294 * The inverse matrices are usable. Set by the parent class via
295 * inverses_computed().
296 */
297 bool var_inverses_ready;
298 };
299
300 //----------------------------------------------------------------------//
301
302 template <typename number>
303 inline PreconditionBlockBase<number>::PreconditionBlockBase(bool store,
304 Inversion method)
305 : inversion(method)
306 , n_diagonal_blocks(0)
307 , var_store_diagonals(store)
308 , var_same_diagonal(false)
309 , var_inverses_ready(false)
310 {}
311
312
313 template <typename number>
314 inline void
315 PreconditionBlockBase<number>::clear()
316 {
317 if (var_inverse_full.size() != 0)
318 var_inverse_full.erase(var_inverse_full.begin(), var_inverse_full.end());
319 if (var_inverse_householder.size() != 0)
320 var_inverse_householder.erase(var_inverse_householder.begin(),
321 var_inverse_householder.end());
322 if (var_inverse_svd.size() != 0)
323 var_inverse_svd.erase(var_inverse_svd.begin(), var_inverse_svd.end());
324 if (var_diagonal.size() != 0)
325 var_diagonal.erase(var_diagonal.begin(), var_diagonal.end());
326 var_same_diagonal = false;
327 var_inverses_ready = false;
328 n_diagonal_blocks = 0;
329 }
330
331 template <typename number>
332 inline void
333 PreconditionBlockBase<number>::reinit(unsigned int n,
334 size_type b,
335 bool compress,
336 Inversion method)
337 {
338 inversion = method;
339 var_same_diagonal = compress;
340 var_inverses_ready = false;
341 n_diagonal_blocks = n;
342
343 if (compress)
344 {
345 switch (inversion)
346 {
347 case gauss_jordan:
348 var_inverse_full.resize(1);
349 var_inverse_full[0].reinit(b, b);
350 break;
351 case householder:
352 var_inverse_householder.resize(1);
353 break;
354 case svd:
355 var_inverse_svd.resize(1);
356 var_inverse_svd[0].reinit(b, b);
357 break;
358 default:
359 DEAL_II_NOT_IMPLEMENTED();
360 }
361
362 if (store_diagonals())
363 {
364 var_diagonal.resize(1);
365 var_diagonal[0].reinit(b, b);
366 }
367 }
368 else
369 {
370 // set the arrays to the right
371 // size. we could do it like this:
372 // var_inverse = vector<>(nblocks,FullMatrix<>())
373 // but this would involve copying many
374 // FullMatrix objects.
375 //
376 // the following is a neat trick which
377 // avoids copying
378 if (store_diagonals())
379 {
380 std::vector<FullMatrix<number>> tmp(n, FullMatrix<number>(b));
381 var_diagonal.swap(tmp);
382 }
383
384 switch (inversion)
385 {
386 case gauss_jordan:
387 {
388 std::vector<FullMatrix<number>> tmp(n, FullMatrix<number>(b));
389 var_inverse_full.swap(tmp);
390 break;
391 }
392 case householder:
393 var_inverse_householder.resize(n);
394 break;
395 case svd:
396 {
397 std::vector<LAPACKFullMatrix<number>> tmp(
398 n, LAPACKFullMatrix<number>(b));
399 var_inverse_svd.swap(tmp);
400 break;
401 }
402 default:
403 DEAL_II_NOT_IMPLEMENTED();
404 }
405 }
406 }
407
408
409 template <typename number>
410 inline unsigned int
411 PreconditionBlockBase<number>::size() const
412 {
413 return n_diagonal_blocks;
414 }
415
416 template <typename number>
417 template <typename number2>
418 inline void
419 PreconditionBlockBase<number>::inverse_vmult(size_type i,
420 Vector<number2> &dst,
421 const Vector<number2> &src) const
422 {
423 const size_type ii = same_diagonal() ? 0U : i;
424
425 switch (inversion)
426 {
427 case gauss_jordan:
428 AssertIndexRange(ii, var_inverse_full.size());
429 var_inverse_full[ii].vmult(dst, src);
430 break;
431 case householder:
432 AssertIndexRange(ii, var_inverse_householder.size());
433 var_inverse_householder[ii].vmult(dst, src);
434 break;
435 case svd:
436 AssertIndexRange(ii, var_inverse_svd.size());
437 var_inverse_svd[ii].vmult(dst, src);
438 break;
439 default:
440 DEAL_II_NOT_IMPLEMENTED();
441 }
442 }
443
444
445 template <typename number>
446 template <typename number2>
447 inline void
448 PreconditionBlockBase<number>::inverse_Tvmult(size_type i,
449 Vector<number2> &dst,
450 const Vector<number2> &src) const
451 {
452 const size_type ii = same_diagonal() ? 0U : i;
453
454 switch (inversion)
455 {
456 case gauss_jordan:
457 AssertIndexRange(ii, var_inverse_full.size());
458 var_inverse_full[ii].Tvmult(dst, src);
459 break;
460 case householder:
461 AssertIndexRange(ii, var_inverse_householder.size());
462 var_inverse_householder[ii].Tvmult(dst, src);
463 break;
464 case svd:
465 AssertIndexRange(ii, var_inverse_svd.size());
466 var_inverse_svd[ii].Tvmult(dst, src);
467 break;
468 default:
469 DEAL_II_NOT_IMPLEMENTED();
470 }
471 }
472
473
474 template <typename number>
475 inline const FullMatrix<number> &
476 PreconditionBlockBase<number>::inverse(size_type i) const
477 {
478 if (same_diagonal())
479 return var_inverse_full[0];
480
481 AssertIndexRange(i, var_inverse_full.size());
482 return var_inverse_full[i];
483 }
484
485
486 template <typename number>
487 inline const Householder<number> &
488 PreconditionBlockBase<number>::inverse_householder(size_type i) const
489 {
490 if (same_diagonal())
491 return var_inverse_householder[0];
492
493 AssertIndexRange(i, var_inverse_householder.size());
494 return var_inverse_householder[i];
495 }
496
497
498 template <typename number>
499 inline const LAPACKFullMatrix<number> &
500 PreconditionBlockBase<number>::inverse_svd(size_type i) const
501 {
502 if (same_diagonal())
503 return var_inverse_svd[0];
504
505 AssertIndexRange(i, var_inverse_svd.size());
506 return var_inverse_svd[i];
507 }
508
509
510 template <typename number>
511 inline const FullMatrix<number> &
512 PreconditionBlockBase<number>::diagonal(size_type i) const
513 {
514 Assert(store_diagonals(), ExcDiagonalsNotStored());
515
516 if (same_diagonal())
517 return var_diagonal[0];
518
519 AssertIndexRange(i, var_diagonal.size());
520 return var_diagonal[i];
521 }
522
523
524 template <typename number>
525 inline FullMatrix<number> &
526 PreconditionBlockBase<number>::inverse(size_type i)
527 {
528 Assert(var_inverse_full.size() != 0, ExcInverseNotAvailable());
529
530 if (same_diagonal())
531 return var_inverse_full[0];
532
533 AssertIndexRange(i, var_inverse_full.size());
534 return var_inverse_full[i];
535 }
536
537
538 template <typename number>
539 inline Householder<number> &
540 PreconditionBlockBase<number>::inverse_householder(size_type i)
541 {
542 Assert(var_inverse_householder.size() != 0, ExcInverseNotAvailable());
543
544 if (same_diagonal())
545 return var_inverse_householder[0];
546
547 AssertIndexRange(i, var_inverse_householder.size());
548 return var_inverse_householder[i];
549 }
550
551
552 template <typename number>
553 inline LAPACKFullMatrix<number> &
554 PreconditionBlockBase<number>::inverse_svd(size_type i)
555 {
556 Assert(var_inverse_svd.size() != 0, ExcInverseNotAvailable());
557
558 if (same_diagonal())
559 return var_inverse_svd[0];
560
561 AssertIndexRange(i, var_inverse_svd.size());
562 return var_inverse_svd[i];
563 }
564
565
566 template <typename number>
567 inline FullMatrix<number> &
568 PreconditionBlockBase<number>::diagonal(size_type i)
569 {
570 Assert(store_diagonals(), ExcDiagonalsNotStored());
571
572 if (same_diagonal())
573 return var_diagonal[0];
574
575 AssertIndexRange(i, var_diagonal.size());
576 return var_diagonal[i];
577 }
578
579
580 template <typename number>
581 inline bool
582 PreconditionBlockBase<number>::same_diagonal() const
583 {
584 return var_same_diagonal;
585 }
586
587
588 template <typename number>
589 inline bool
590 PreconditionBlockBase<number>::store_diagonals() const
591 {
592 return var_store_diagonals;
593 }
594
595
596 template <typename number>
597 inline void
598 PreconditionBlockBase<number>::inverses_computed(bool x)
599 {
600 var_inverses_ready = x;
601 }
602
603
604 template <typename number>
605 inline bool
606 PreconditionBlockBase<number>::inverses_ready() const
607 {
608 return var_inverses_ready;
609 }
610
611
612 template <typename number>
613 inline void
614 PreconditionBlockBase<number>::log_statistics() const
615 {
616 deallog << "PreconditionBlockBase: " << size() << " blocks; ";
617
618 if (inversion == svd)
619 {
620 unsigned int kermin = 100000000, kermax = 0;
621 double sigmin = 1.e300, sigmax = -1.e300;
622 double kappamin = 1.e300, kappamax = -1.e300;
623
624 for (size_type b = 0; b < size(); ++b)
625 {
626 const LAPACKFullMatrix<number> &matrix = inverse_svd(b);
627 size_type k = 1;
628 while (k <= matrix.n_cols() &&
629 matrix.singular_value(matrix.n_cols() - k) == 0)
630 ++k;
631 const double s0 = matrix.singular_value(0);
632 const double sm = matrix.singular_value(matrix.n_cols() - k);
633 const double co = sm / s0;
634
635 if (kermin > k)
636 kermin = k - 1;
637 if (kermax < k)
638 kermax = k - 1;
639 if (s0 < sigmin)
640 sigmin = s0;
641 if (sm > sigmax)
642 sigmax = sm;
643 if (co < kappamin)
644 kappamin = co;
645 if (co > kappamax)
646 kappamax = co;
647 }
648 deallog << "dim ker [" << kermin << ':' << kermax << "] sigma [" << sigmin
649 << ':' << sigmax << "] kappa [" << kappamin << ':' << kappamax
650 << ']' << std::endl;
651 }
652 else if (inversion == householder)
653 {
654 }
655 else if (inversion == gauss_jordan)
656 {
657 }
658 else
659 {
660 DEAL_II_NOT_IMPLEMENTED();
661 }
662 }
663
664
665 template <typename number>
666 inline std::size_t
667 PreconditionBlockBase<number>::memory_consumption() const
668 {
669 std::size_t mem = sizeof(*this);
670 for (size_type i = 0; i < var_inverse_full.size(); ++i)
671 mem += MemoryConsumption::memory_consumption(var_inverse_full[i]);
672 for (size_type i = 0; i < var_diagonal.size(); ++i)
673 mem += MemoryConsumption::memory_consumption(var_diagonal[i]);
674 return mem;
675 }
676
677
678 DEAL_II_NAMESPACE_CLOSE
679
680 #endif