Debian Codegraph @

include/deal.II/lac/relaxation_block.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_relaxation_block_h
16 #define dealii_relaxation_block_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/observer_pointer.h>
22
23 #include <deal.II/lac/precondition_block_base.h>
24 #include <deal.II/lac/sparsity_pattern.h>
25 #include <deal.II/lac/vector.h>
26
27 #include <vector>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 /**
32 * Base class for the implementation of overlapping, multiplicative Schwarz
33 * relaxation methods and smoothers.
34 *
35 * This class uses the infrastructure provided by PreconditionBlockBase. It
36 * adds functions to initialize with a block list and to do the relaxation
37 * step. The actual relaxation method with the interface expected by
38 * SolverRelaxation and MGSmootherRelaxation is in the derived classes.
39 *
40 * This class allows for more general relaxation methods than
41 * PreconditionBlock, since the index sets may be arbitrary and overlapping,
42 * while there only contiguous, disjoint sets of equal size are allowed. As a
43 * drawback, this class cannot be used as a preconditioner, since its
44 * implementation relies on a straight forward implementation of the
45 * Gauss-Seidel process.
46 *
47 * Parallel computations require you to specify an initialized
48 * ghost vector in AdditionalData::temp_ghost_vector.
49 *
50 * @ingroup Preconditioners
51 */
52 template <typename MatrixType,
53 typename InverseNumberType = typename MatrixType::value_type,
54 typename VectorType = Vector<double>>
55 class RelaxationBlock : protected PreconditionBlockBase<InverseNumberType>
56 {
57 private:
58 /**
59 * Define number type of matrix.
60 */
61 using number = typename MatrixType::value_type;
62
63 /**
64 * Value type for inverse matrices.
65 */
66 using value_type = InverseNumberType;
67
68 public:
69 /**
70 * Declare type for container size.
71 */
72 using size_type = types::global_dof_index;
73
74 /**
75 * Parameters for block relaxation methods. In addition to typical control
76 * parameters like #relaxation, this object also contains the block
77 * structure in #block_list and an optional ordering of the blocks in
78 * #order.
79 */
80 class AdditionalData : public EnableObserverPointer
81 {
82 public:
83 /**
84 * Constructor.
85 */
86 AdditionalData(
87 const double relaxation = 1.,
88 const bool invert_diagonal = true,
89 const bool same_diagonal = false,
90 const typename PreconditionBlockBase<InverseNumberType>::Inversion
91 inversion = PreconditionBlockBase<InverseNumberType>::gauss_jordan,
92 const double threshold = 0.,
93 VectorType *temp_ghost_vector = nullptr);
94
95 /**
96 * The mapping from indices to blocks. Each row of this pattern enumerates
97 * the indices constituting a diagonal block to be inverted.
98 */
99 SparsityPattern block_list;
100
101 /**
102 * Relaxation parameter.
103 */
104 double relaxation;
105
106 /**
107 * Invert diagonal during initialization. Alternatively, diagonal blocks
108 * are inverted on the fly, whenever they are used. While inverting blocks
109 * in advance requires more memory, it usually saves a lot of computation.
110 * See #same_diagonal on how you can avoid memory overhead.
111 */
112 bool invert_diagonal;
113
114 /**
115 * Assume all diagonal blocks are equal to save memory. If this flag is
116 * true, then only the first diagonal block of the matrix is inverted and
117 * stored. It is then used for all other blocks.
118 *
119 * \note Avoid setting this true if your blocks are not equal, in
120 * particular if their sizes differ.
121 */
122 bool same_diagonal;
123
124 /**
125 * Choose the inversion method for the blocks.
126 */
127 typename PreconditionBlockBase<InverseNumberType>::Inversion inversion;
128
129 /**
130 * If #inversion is SVD, we can compute the Penrose-Moore inverse of the
131 * blocks. In order to do so, we can specify here the threshold below
132 * which a singular value will be considered zero and thus not inverted.
133 * Setting this parameter to a value greater than zero takes precedence over
134 * threshold, i.e. kernel_size must be zero if you want to use threshold.
135 * This parameter is used in the call to
136 * LAPACKFullMatrix::compute_inverse_svd().
137 */
138 double threshold = 0.;
139
140 /**
141 * If #inversion is SVD, we can compute the Penrose-Moore inverse of the
142 * blocks. In order to do so, we can specify here the size of the kernel
143 * that will not be inverted but considered zero. Setting this parameter
144 * to a value greater than zero takes precedence over threshold, i.e.
145 * kernel_size must be zero if you want to use threshold.
146 * This parameter is used in the call to
147 * LAPACKFullMatrix::compute_inverse_svd().
148 */
149 unsigned int kernel_size = 0;
150
151 /**
152 * The order in which blocks should be traversed. This vector can initiate
153 * several modes of execution:
154 *
155 * <ol>
156 *
157 * <li>If the length of the vector is zero, then the relaxation method
158 * will be executed from first to last block.</li>
159 *
160 * <li> If the length is one, then the inner vector must have the same
161 * size as the number of blocks. The relaxation method is applied in the
162 * order given in this vector.</li>
163 *
164 * <li> If the outer vector has length greater one, then the relaxation
165 * method is applied several times, each time in the order given by the
166 * inner vector of the corresponding index. This mode can for instance be
167 * used for ADI methods and similar direction sweeps.</li>
168 *
169 * </ol>
170 */
171 std::vector<std::vector<unsigned int>> order;
172
173 /**
174 * Temporary ghost vector that is used in the relaxation method when
175 * performing parallel MPI computations. The user is required to have this
176 * point to an initialized vector that contains all indices
177 * that appear in the @p block_list sa ghost values. Typically, this the
178 * set of locally active level DoFs. Unused when VectorType is a serial
179 * vector type like Vector<double>.
180 */
181 mutable VectorType *temp_ghost_vector;
182
183 /**
184 * Return the memory allocated in this object.
185 */
186 std::size_t
187 memory_consumption() const;
188 };
189
190 /**
191 * Initialize matrix and additional information. In a second step, the
192 * inverses of the diagonal blocks may be computed.
193 *
194 * Note that AdditionalData, different from other preconditioners, defines
195 * quite large objects, and that therefore the object is not copied, but
196 * rather a pointer is stored. Thus, the lifetime of
197 * <code>additional_data</code> hast to exceed the lifetime of this object.
198 */
199 void
200 initialize(const MatrixType &A, const AdditionalData &parameters);
201
202 /**
203 * Deletes the inverse diagonal block matrices if existent, sets the
204 * blocksize to 0, hence leaves the class in the state that it had directly
205 * after calling the constructor.
206 */
207 void
208 clear();
209
210 /**
211 * Stores the inverse of the diagonal blocks in @p inverse. This costs some
212 * additional memory - for DG methods about 1/3 (for double inverses) or 1/6
213 * (for float inverses) of that used for the matrix - but it makes the
214 * preconditioning much faster.
215 *
216 * It is not allowed to call this function twice (will produce an error)
217 * before a call of <tt>clear(...)</tt> because at the second time there
218 * already exist the inverse matrices.
219 *
220 * After this function is called, the lock on the matrix given through the
221 * @p use_matrix function is released, i.e. you may overwrite of delete it.
222 * You may want to do this in case you use this matrix to precondition
223 * another matrix.
224 */
225 void
226 invert_diagblocks();
227
228 protected:
229 /**
230 * Perform one block relaxation step.
231 *
232 * Depending on the arguments @p dst and @p pref, this performs an SOR step
233 * (both reference the same vector) or a Jacobi step (both are different
234 * vectors). For the Jacobi step, the calling function must copy @p dst to
235 * @p prev after this.
236 */
237 void
238 do_step(VectorType &dst,
239 const VectorType &prev,
240 const VectorType &src,
241 const bool backward) const;
242
243 /**
244 * Pointer to the matrix. Make sure that the matrix exists as long as this
245 * class needs it, i.e. until calling @p invert_diagblocks, or (if the
246 * inverse matrices should not be stored) until the last call of the
247 * preconditioning @p vmult function of the derived classes.
248 */
249 ObserverPointer<const MatrixType,
250 RelaxationBlock<MatrixType, InverseNumberType, VectorType>>
251 A;
252
253 /**
254 * Control information.
255 */
256 ObserverPointer<const AdditionalData,
257 RelaxationBlock<MatrixType, InverseNumberType, VectorType>>
258 additional_data;
259
260 private:
261 /**
262 * Computes (the inverse of) a range of blocks.
263 */
264 void
265 block_kernel(const size_type block_begin, const size_type block_end);
266 };
267
268
269 /**
270 * Block Jacobi (additive Schwarz) method with possibly overlapping blocks.
271 *
272 * This class implements the step() and Tstep() functions expected by the
273 * @ref ConceptRelaxationType "relaxation concept".
274 * They perform an additive Schwarz method on the blocks provided in the block
275 * list of AdditionalData. Differing from PreconditionBlockJacobi, these
276 * blocks may be of varying size, non- contiguous, and overlapping. On the
277 * other hand, this class does not implement the preconditioner interface
278 * expected by Solver objects.
279 *
280 * @ingroup Preconditioners
281 */
282 template <typename MatrixType,
283 typename InverseNumberType = typename MatrixType::value_type,
284 typename VectorType = Vector<double>>
285 class RelaxationBlockJacobi
286 : public virtual EnableObserverPointer,
287 protected RelaxationBlock<MatrixType, InverseNumberType, VectorType>
288 {
289 public:
290 /**
291 * Default constructor.
292 */
293 // RelaxationBlockJacobi();
294
295 /**
296 * Define number type of matrix.
297 */
298 using number = typename MatrixType::value_type;
299
300 /**
301 * Make type publicly available.
302 */
303 using typename RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
304 AdditionalData;
305
306 /**
307 * Make initialization function publicly available.
308 */
309 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::initialize;
310
311 /**
312 * Make function of base class public again.
313 */
314 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::clear;
315
316 /**
317 * Make function of base class public again.
318 */
319 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::size;
320 /**
321 * Make function of base class public again.
322 */
323 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse;
324 /**
325 * Make function of base class public again.
326 */
327 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
328 inverse_householder;
329 /**
330 * Make function of base class public again.
331 */
332 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse_svd;
333 /**
334 * Make function of base class public again.
335 */
336 using PreconditionBlockBase<InverseNumberType>::log_statistics;
337 /**
338 * Perform one step of the Jacobi iteration.
339 */
340 void
341 step(VectorType &dst, const VectorType &rhs) const;
342
343 /**
344 * Perform one step of the Jacobi iteration.
345 */
346 void
347 Tstep(VectorType &dst, const VectorType &rhs) const;
348
349 /**
350 * Implements a vmult() operation, which for this class first sets the dst()
351 * vector to zero before calling the step() method.
352 */
353 void
354 vmult(VectorType &dst, const VectorType &rhs) const;
355
356 /**
357 * Implements a transpose vmult operation, which for this class first sets
358 * the dst() vector to zero before calling the Tstep() method.
359 */
360 void
361 Tvmult(VectorType &dst, const VectorType &rhs) const;
362 };
363
364
365 /**
366 * Block Gauss-Seidel method with possibly overlapping blocks.
367 *
368 * This class implements the step() and Tstep() functions expected by the
369 * @ref ConceptRelaxationType "relaxation concept".
370 * They perform a multiplicative Schwarz method on the blocks provided in the
371 * block list of AdditionalData. Differing from PreconditionBlockSOR, these
372 * blocks may be of varying size, non-contiguous, and overlapping. On the
373 * other hand, this class does not implement the preconditioner interface
374 * expected by Solver objects.
375 *
376 * @ingroup Preconditioners
377 */
378 template <typename MatrixType,
379 typename InverseNumberType = typename MatrixType::value_type,
380 typename VectorType = Vector<double>>
381 class RelaxationBlockSOR
382 : public virtual EnableObserverPointer,
383 protected RelaxationBlock<MatrixType, InverseNumberType, VectorType>
384 {
385 public:
386 /**
387 * Default constructor.
388 */
389 // RelaxationBlockSOR();
390
391 /**
392 * Define number type of matrix.
393 */
394 using number = typename MatrixType::value_type;
395
396 /**
397 * Make type publicly available.
398 */
399 using typename RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
400 AdditionalData;
401
402 /**
403 * Make initialization function publicly available.
404 */
405 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::initialize;
406
407 /**
408 * Make function of base class public again.
409 */
410 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::clear;
411
412 /**
413 * Make function of base class public again.
414 */
415 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::size;
416 /**
417 * Make function of base class public again.
418 */
419 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse;
420 /**
421 * Make function of base class public again.
422 */
423 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
424 inverse_householder;
425 /**
426 * Make function of base class public again.
427 */
428 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse_svd;
429 /**
430 * Make function of base class public again.
431 */
432 using PreconditionBlockBase<InverseNumberType>::log_statistics;
433 /**
434 * Perform one step of the SOR iteration.
435 */
436 void
437 step(VectorType &dst, const VectorType &rhs) const;
438
439 /**
440 * Perform one step of the transposed SOR iteration.
441 */
442 void
443 Tstep(VectorType &dst, const VectorType &rhs) const;
444
445 /**
446 * Implements a vmult() operation, which for this class first sets the dst()
447 * vector to zero before calling the step() method.
448 */
449 void
450 vmult(VectorType &dst, const VectorType &rhs) const;
451
452 /**
453 * Implements a transpose vmult operation, which for this class first sets
454 * the dst() vector to zero before calling the Tstep() method.
455 */
456 void
457 Tvmult(VectorType &dst, const VectorType &rhs) const;
458 };
459
460
461 /**
462 * Symmetric block Gauss-Seidel method with possibly overlapping blocks.
463 *
464 * This class implements the step() and Tstep() functions expected by the
465 * @ref ConceptRelaxationType "relaxation concept".
466 * They perform a multiplicative Schwarz method on the blocks provided in the
467 * block list of AdditionalData in symmetric fashion. Differing from
468 * PreconditionBlockSSOR, these blocks may be of varying size, non-contiguous,
469 * and overlapping. On the other hand, this class does not implement the
470 * preconditioner interface expected by Solver objects.
471 *
472 * @ingroup Preconditioners
473 */
474 template <typename MatrixType,
475 typename InverseNumberType = typename MatrixType::value_type,
476 typename VectorType = Vector<double>>
477 class RelaxationBlockSSOR
478 : public virtual EnableObserverPointer,
479 protected RelaxationBlock<MatrixType, InverseNumberType, VectorType>
480 {
481 public:
482 /**
483 * Define number type of matrix.
484 */
485 using number = typename MatrixType::value_type;
486
487 /**
488 * Make type publicly available.
489 */
490 using typename RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
491 AdditionalData;
492
493 /**
494 * Make initialization function publicly available.
495 */
496 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::initialize;
497
498 /**
499 * Make function of base class public again.
500 */
501 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::clear;
502
503 /**
504 * Make function of base class public again.
505 */
506 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::size;
507 /**
508 * Make function of base class public again.
509 */
510 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse;
511 /**
512 * Make function of base class public again.
513 */
514 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::
515 inverse_householder;
516 /**
517 * Make function of base class public again.
518 */
519 using RelaxationBlock<MatrixType, InverseNumberType, VectorType>::inverse_svd;
520 /**
521 * Make function of base class public again.
522 */
523 using PreconditionBlockBase<InverseNumberType>::log_statistics;
524 /**
525 * Perform one step of the SSOR iteration.
526 */
527 void
528 step(VectorType &dst, const VectorType &rhs) const;
529
530 /**
531 * Perform one step of the transposed SSOR iteration.
532 */
533 void
534 Tstep(VectorType &dst, const VectorType &rhs) const;
535
536 /**
537 * Implements a vmult() operation, which for this class first sets the dst()
538 * vector to zero before calling the step() method.
539 */
540 void
541 vmult(VectorType &dst, const VectorType &rhs) const;
542
543 /**
544 * Implements a transpose vmult operation, which for this class first sets
545 * the dst() vector to zero before calling the Tstep() method.
546 */
547 void
548 Tvmult(VectorType &dst, const VectorType &rhs) const;
549 };
550
551
552 DEAL_II_NAMESPACE_CLOSE
553
554 #endif