Debian Codegraph @

include/deal.II/lac/trilinos_precondition.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2008 - 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_trilinos_precondition_h
16 #define dealii_trilinos_precondition_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_TRILINOS
22
23 # include <deal.II/base/enable_observer_pointer.h>
24
25 # include <deal.II/lac/la_parallel_vector.h>
26 # include <deal.II/lac/trilinos_vector.h>
27
28 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
29 # include <Epetra_Map.h>
30 # include <Epetra_MpiComm.h>
31 # include <Epetra_MultiVector.h>
32 # include <Epetra_RowMatrix.h>
33 # include <Epetra_Vector.h>
34 # include <Teuchos_ParameterList.hpp>
35 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
36
37 # include <memory>
38
39 // forward declarations
40 # ifndef DOXYGEN
41 class Ifpack_Preconditioner;
42 class Ifpack_Chebyshev;
43 namespace ML_Epetra
44 {
45 class MultiLevelPreconditioner;
46 }
47 # endif
48
49 DEAL_II_NAMESPACE_OPEN
50
51 // forward declarations
52 # ifndef DOXYGEN
53 template <typename number>
54 class SparseMatrix;
55 template <typename number>
56 class Vector;
57 class SparsityPattern;
58 # endif
59
60 /**
61 * @addtogroup TrilinosWrappers
62 * @{
63 */
64
65 namespace TrilinosWrappers
66 {
67 // forward declarations
68 class SparseMatrix;
69 class BlockSparseMatrix;
70 class SolverBase;
71
72 /**
73 * The base class for all preconditioners based on Trilinos sparse matrices.
74 *
75 * @ingroup TrilinosWrappers
76 * @ingroup Preconditioners
77 */
78 class PreconditionBase : public EnableObserverPointer
79 {
80 public:
81 /**
82 * Declare the type for container size.
83 */
84 using size_type = dealii::types::global_dof_index;
85
86 /**
87 * Standardized data struct to pipe additional flags to the
88 * preconditioner.
89 */
90 struct AdditionalData
91 {};
92
93 /**
94 * Constructor. Does not do anything. The <tt>initialize</tt> function of
95 * the derived classes will have to create the preconditioner from a given
96 * sparse matrix.
97 */
98 PreconditionBase();
99
100 /**
101 * Destroys the preconditioner, leaving an object like just after having
102 * called the constructor.
103 */
104 void
105 clear();
106
107 /**
108 * Return the underlying MPI communicator.
109 */
110 MPI_Comm
111 get_mpi_communicator() const;
112
113 /**
114 * Sets an internal flag so that all operations performed by the matrix,
115 * i.e., multiplications, are done in transposed order. However, this does
116 * not reshape the matrix to transposed form directly, so care should be
117 * taken when using this flag.
118 *
119 * @note Calling this function any even number of times in succession will
120 * return the object to its original state.
121 */
122 void
123 transpose();
124
125 /**
126 * Apply the preconditioner.
127 */
128 virtual void
129 vmult(MPI::Vector &dst, const MPI::Vector &src) const;
130
131 /**
132 * Apply the transpose preconditioner.
133 */
134 virtual void
135 Tvmult(MPI::Vector &dst, const MPI::Vector &src) const;
136
137 /**
138 * Apply the preconditioner on deal.II data structures instead of the ones
139 * provided in the Trilinos wrapper class.
140 */
141 virtual void
142 vmult(dealii::Vector<double> &dst, const dealii::Vector<double> &src) const;
143
144 /**
145 * Apply the transpose preconditioner on deal.II data structures instead
146 * of the ones provided in the Trilinos wrapper class.
147 */
148 virtual void
149 Tvmult(dealii::Vector<double> &dst,
150 const dealii::Vector<double> &src) const;
151
152 /**
153 * Apply the preconditioner on deal.II parallel data structures instead of
154 * the ones provided in the Trilinos wrapper class.
155 */
156 virtual void
157 vmult(dealii::LinearAlgebra::distributed::Vector<double> &dst,
158 const dealii::LinearAlgebra::distributed::Vector<double> &src) const;
159
160 /**
161 * Apply the transpose preconditioner on deal.II parallel data structures
162 * instead of the ones provided in the Trilinos wrapper class.
163 */
164 virtual void
165 Tvmult(dealii::LinearAlgebra::distributed::Vector<double> &dst,
166 const dealii::LinearAlgebra::distributed::Vector<double> &src) const;
167
168 /**
169 * @name Access to underlying Trilinos data
170 */
171 /** @{ */
172 /**
173 *
174 * Calling this function from an uninitialized object will cause an
175 * exception.
176 */
177 Epetra_Operator &
178 trilinos_operator() const;
179 /** @} */
180
181 /**
182 * @name Partitioners
183 */
184 /** @{ */
185
186 /**
187 * Return the partitioning of the domain space of this matrix, i.e., the
188 * partitioning of the vectors this matrix has to be multiplied with.
189 */
190 IndexSet
191 locally_owned_domain_indices() const;
192
193 /**
194 * Return the partitioning of the range space of this matrix, i.e., the
195 * partitioning of the vectors that are result from matrix-vector
196 * products.
197 */
198 IndexSet
199 locally_owned_range_indices() const;
200
201 /** @} */
202
203 /**
204 * @addtogroup Exceptions
205 */
206 /** @{ */
207 /**
208 * Exception.
209 */
210 DeclException1(ExcNonMatchingMaps,
211 std::string,
212 << "The sparse matrix the preconditioner is based on "
213 << "uses a map that is not compatible to the one in vector "
214 << arg1 << ". Check preconditioner and matrix setup.");
215 /** @} */
216
217 friend class SolverBase;
218
219 protected:
220 /**
221 * This is a pointer to the preconditioner object that is used when
222 * applying the preconditioner.
223 */
224 Teuchos::RCP<Epetra_Operator> preconditioner;
225
226 /**
227 * Internal communication pattern in case the matrix needs to be copied
228 * from deal.II format.
229 */
230 Epetra_MpiComm communicator;
231 };
232
233
234 /**
235 * A wrapper class for a (pointwise) Jacobi preconditioner for Trilinos
236 * matrices. This preconditioner works both in serial and in parallel,
237 * depending on the matrix it is based on.
238 *
239 * The AdditionalData data structure allows to set preconditioner options.
240 * For the Jacobi preconditioner, these options are the damping parameter
241 * <tt>omega</tt> and a <tt>min_diagonal</tt> argument that can be used to
242 * make the preconditioner work even if the matrix contains some zero
243 * elements on the diagonal. The default settings are 1 for the damping
244 * parameter and zero for the diagonal augmentation.
245 *
246 * @ingroup TrilinosWrappers
247 * @ingroup Preconditioners
248 */
249 class PreconditionJacobi : public PreconditionBase
250 {
251 public:
252 /**
253 * Standardized data struct to pipe additional flags to the
254 * preconditioner. The parameter <tt>omega</tt> specifies the relaxation
255 * parameter in the Jacobi preconditioner. The parameter
256 * <tt>min_diagonal</tt> can be used to make the application of the
257 * preconditioner also possible when some diagonal elements are zero. In a
258 * default application this would mean that we divide by zero, so by
259 * setting the parameter <tt>min_diagonal</tt> to a small nonzero value
260 * the SOR will work on a matrix that is not too far away from the one we
261 * want to treat.
262 */
263 struct AdditionalData
264 {
265 /**
266 * Constructor. By default, set the damping parameter to one, and do not
267 * modify the diagonal.
268 */
269 AdditionalData(const double omega = 1,
270 const double min_diagonal = 0,
271 const unsigned int n_sweeps = 1);
272
273 /**
274 * This specifies the relaxation parameter in the Jacobi preconditioner.
275 */
276 double omega;
277
278 /**
279 * This specifies the minimum value the diagonal elements should have.
280 * This might be necessary when the Jacobi preconditioner is used on
281 * matrices with zero diagonal elements. In that case, a
282 * straight-forward application would not be possible since we would
283 * divide by zero.
284 */
285 double min_diagonal;
286
287 /**
288 * Sets how many times the given operation should be applied during the
289 * vmult() operation.
290 */
291 unsigned int n_sweeps;
292 };
293
294 /**
295 * Take the sparse matrix the preconditioner object should be built of,
296 * and additional flags (damping parameter, etc.) if there are any.
297 */
298 void
299 initialize(const SparseMatrix &matrix,
300 const AdditionalData &additional_data = AdditionalData());
301 };
302
303
304
305 /**
306 * A wrapper class for a (pointwise) SSOR preconditioner for Trilinos
307 * matrices. This preconditioner works both in serial and in parallel,
308 * depending on the matrix it is based on.
309 *
310 * The AdditionalData data structure allows to set preconditioner options.
311 * For the SSOR preconditioner, these options are the damping/relaxation
312 * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
313 * used to make the preconditioner work even if the matrix contains some
314 * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
315 * determines if and how much overlap there should be between the matrix
316 * partitions on the various MPI processes. The default settings are 1 for
317 * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
318 * overlap.
319 *
320 * Note that a parallel application of the SSOR preconditioner is actually a
321 * block-Jacobi preconditioner with block size equal to the local matrix
322 * size. Spoken more technically, this parallel operation is an <a
323 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
324 * Schwarz method</a> with an SSOR <em>approximate solve</em> as inner
325 * solver, based on the outer parallel partitioning.
326 *
327 * @ingroup TrilinosWrappers
328 * @ingroup Preconditioners
329 */
330 class PreconditionSSOR : public PreconditionBase
331 {
332 public:
333 /**
334 * Standardized data struct to pipe additional flags to the
335 * preconditioner. The parameter <tt>omega</tt> specifies the relaxation
336 * parameter in the SSOR preconditioner. The parameter
337 * <tt>min_diagonal</tt> can be used to make the application of the
338 * preconditioner also possible when some diagonal elements are zero. In a
339 * default application this would mean that we divide by zero, so by
340 * setting the parameter <tt>min_diagonal</tt> to a small nonzero value
341 * the SOR will work on a matrix that is not too far away from the one we
342 * want to treat. Finally, <tt>overlap</tt> governs the overlap of the
343 * partitions when the preconditioner runs in parallel, forming a
344 * so-called additive Schwarz preconditioner.
345 */
346 struct AdditionalData
347 {
348 /**
349 * Constructor. By default, set the damping parameter to one, we do not
350 * modify the diagonal, and there is no overlap (i.e. in parallel, we
351 * run a BlockJacobi preconditioner, where each block is inverted
352 * approximately by an SSOR).
353 */
354 AdditionalData(const double omega = 1,
355 const double min_diagonal = 0,
356 const unsigned int overlap = 0,
357 const unsigned int n_sweeps = 1);
358
359 /**
360 * This specifies the (over-) relaxation parameter in the SSOR
361 * preconditioner.
362 */
363 double omega;
364
365 /**
366 * This specifies the minimum value the diagonal elements should have.
367 * This might be necessary when the SSOR preconditioner is used on
368 * matrices with zero diagonal elements. In that case, a
369 * straight-forward application would not be possible since we divide by
370 * the diagonal element.
371 */
372 double min_diagonal;
373
374 /**
375 * This determines how large the overlap of the local matrix portions on
376 * each processor in a parallel application should be.
377 */
378 unsigned int overlap;
379
380 /**
381 * Sets how many times the given operation should be applied during the
382 * vmult() operation.
383 */
384 unsigned int n_sweeps;
385 };
386
387 /**
388 * Take the sparse matrix the preconditioner object should be built of,
389 * and additional flags (damping parameter, overlap in parallel
390 * computations, etc.) if there are any.
391 */
392 void
393 initialize(const SparseMatrix &matrix,
394 const AdditionalData &additional_data = AdditionalData());
395 };
396
397
398
399 /**
400 * A wrapper class for a (pointwise) SOR preconditioner for Trilinos
401 * matrices. This preconditioner works both in serial and in parallel,
402 * depending on the matrix it is based on.
403 *
404 * The AdditionalData data structure allows to set preconditioner options.
405 * For the SOR preconditioner, these options are the damping/relaxation
406 * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
407 * used to make the preconditioner work even if the matrix contains some
408 * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
409 * determines if and how much overlap there should be between the matrix
410 * partitions on the various MPI processes. The default settings are 1 for
411 * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
412 * overlap.
413 *
414 * Note that a parallel application of the SOR preconditioner is actually a
415 * block-Jacobi preconditioner with block size equal to the local matrix
416 * size. Spoken more technically, this parallel operation is an <a
417 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
418 * Schwarz method</a> with an SOR <em>approximate solve</em> as inner
419 * solver, based on the outer parallel partitioning.
420 *
421 * @ingroup TrilinosWrappers
422 * @ingroup Preconditioners
423 */
424 class PreconditionSOR : public PreconditionBase
425 {
426 public:
427 /**
428 * Standardized data struct to pipe additional flags to the
429 * preconditioner. The parameter <tt>omega</tt> specifies the relaxation
430 * parameter in the SOR preconditioner. The parameter
431 * <tt>min_diagonal</tt> can be used to make the application of the
432 * preconditioner also possible when some diagonal elements are zero. In a
433 * default application this would mean that we divide by zero, so by
434 * setting the parameter <tt>min_diagonal</tt> to a small nonzero value
435 * the SOR will work on a matrix that is not too far away from the one we
436 * want to treat. Finally, <tt>overlap</tt> governs the overlap of the
437 * partitions when the preconditioner runs in parallel, forming a
438 * so-called additive Schwarz preconditioner.
439 */
440 struct AdditionalData
441 {
442 /**
443 * Constructor. By default, set the damping parameter to one, we do not
444 * modify the diagonal, and there is no overlap (i.e. in parallel, we
445 * run a BlockJacobi preconditioner, where each block is inverted
446 * approximately by an SOR.
447 */
448 AdditionalData(const double omega = 1,
449 const double min_diagonal = 0,
450 const unsigned int overlap = 0,
451 const unsigned int n_sweeps = 1);
452
453 /**
454 * This specifies the (over-) relaxation parameter in the SOR
455 * preconditioner.
456 */
457 double omega;
458
459 /**
460 * This specifies the minimum value the diagonal elements should have.
461 * This might be necessary when the SOR preconditioner is used on
462 * matrices with zero diagonal elements. In that case, a
463 * straight-forward application would not be possible since we divide by
464 * the diagonal element.
465 */
466 double min_diagonal;
467
468 /**
469 * This determines how large the overlap of the local matrix portions on
470 * each processor in a parallel application should be.
471 */
472 unsigned int overlap;
473
474 /**
475 * Sets how many times the given operation should be applied during the
476 * vmult() operation.
477 */
478 unsigned int n_sweeps;
479 };
480
481 /**
482 * Take the sparse matrix the preconditioner object should be built of,
483 * and additional flags (damping parameter, overlap in parallel
484 * computations etc.) if there are any.
485 */
486 void
487 initialize(const SparseMatrix &matrix,
488 const AdditionalData &additional_data = AdditionalData());
489 };
490
491
492
493 /**
494 * A wrapper class for a block Jacobi preconditioner for Trilinos matrices.
495 * As opposed to PreconditionSOR where each row is treated separately, this
496 * scheme collects block of a given size and inverts a full matrix for all
497 * these rows simultaneously. Trilinos allows to select several strategies
498 * for selecting which rows form a block, including "linear" (i.e., divide
499 * the local range of the matrix in slices of the block size), "greedy" or
500 * "metis". Note that the term <em>block Jacobi</em> does not relate to
501 * possible blocks in the MPI setting, but small blocks of dense matrices
502 * extracted from the sparse matrix local to each processor.
503 *
504 * The AdditionalData data structure allows to set preconditioner options.
505 *
506 * @ingroup TrilinosWrappers
507 * @ingroup Preconditioners
508 */
509 class PreconditionBlockJacobi : public PreconditionBase
510 {
511 public:
512 /**
513 * Standardized data struct to pipe additional flags to the
514 * preconditioner. The parameter <tt>block_size</tt> sets the size of
515 * small blocks. It is recommended to choose this parameter not too large
516 * (a few hundreds at most) since this implementation uses a dense matrix
517 * for the block. The parameter <tt>block_creation_type</tt> allows to
518 * pass the strategy for finding the blocks to Ifpack. The parameter
519 * <tt>omega</tt> specifies the relaxation parameter in the SOR
520 * preconditioner. The parameter <tt>min_diagonal</tt> can be used to make
521 * the application of the preconditioner also possible when some diagonal
522 * elements are zero. In a default application this would mean that we
523 * divide by zero, so by setting the parameter <tt>min_diagonal</tt> to a
524 * small nonzero value the SOR will work on a matrix that is not too far
525 * away from the one we want to treat.
526 */
527 struct AdditionalData
528 {
529 /**
530 * Constructor. By default, use a block size of 1, use linear
531 * subdivision of the rows, set the damping parameter to one, and do not
532 * modify the diagonal.
533 */
534 AdditionalData(const unsigned int block_size = 1,
535 const std::string &block_creation_type = "linear",
536 const double omega = 1,
537 const double min_diagonal = 0,
538 const unsigned int n_sweeps = 1);
539
540 /**
541 * This specifies the size of blocks.
542 */
543 unsigned int block_size;
544
545 /**
546 * Strategy for creation of blocks passed on to Ifpack block relaxation
547 * (variable 'partitioner: type') with this string as the given value.
548 * Available types in Ifpack include "linear" (i.e., divide the local
549 * range of the matrix in slices of the block size), "greedy" "metis".
550 * For a full list, see the documentation of Ifpack.
551 */
552 std::string block_creation_type;
553
554 /**
555 * This specifies the (over-) relaxation parameter in the Jacobi
556 * preconditioner.
557 */
558 double omega;
559
560 /**
561 * This specifies the minimum value the diagonal elements should have.
562 * This might be necessary when the block Jacobi preconditioner is used
563 * on matrices with zero diagonal elements. In that case, a
564 * straight-forward application would not be possible since we divide by
565 * the diagonal element.
566 */
567 double min_diagonal;
568
569 /**
570 * Sets how many times the given operation should be applied during the
571 * vmult() operation.
572 */
573 unsigned int n_sweeps;
574 };
575
576 /**
577 * Take the sparse matrix the preconditioner object should be built of,
578 * and additional flags (damping parameter, etc.) if there are any.
579 */
580 void
581 initialize(const SparseMatrix &matrix,
582 const AdditionalData &additional_data = AdditionalData());
583 };
584
585
586
587 /**
588 * A wrapper class for a block SSOR preconditioner for Trilinos matrices. As
589 * opposed to PreconditionSSOR where each row is treated separately
590 * (point-wise), this scheme collects block of a given size and inverts a full
591 * matrix for all these rows simultaneously. Trilinos allows to select
592 * several strategies for selecting which rows form a block, including
593 * "linear" (i.e., divide the local range of the matrix in slices of the
594 * block size), "greedy" or "metis".
595 *
596 * The AdditionalData data structure allows to set preconditioner options.
597 *
598 * Note that a parallel application of this preconditioner is actually a
599 * block-Jacobi preconditioner with (outer) block size equal to the local
600 * matrix size. Spoken more technically, this parallel operation is an <a
601 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
602 * Schwarz method</a> with a block SSOR <em>approximate solve</em> as inner
603 * solver, based on the outer parallel partitioning.
604 *
605 * @ingroup TrilinosWrappers
606 * @ingroup Preconditioners
607 */
608 class PreconditionBlockSSOR : public PreconditionBase
609 {
610 public:
611 /**
612 * Standardized data struct to pipe additional flags to the
613 * preconditioner. The parameter <tt>block_size</tt> sets the size of
614 * small blocks. It is recommended to choose this parameter not too large
615 * (a few hundreds at most) since this implementation uses a dense matrix
616 * for the block. The parameter <tt>block_creation_type</tt> allows to
617 * pass the strategy for finding the blocks to Ifpack. The parameter
618 * <tt>omega</tt> specifies the relaxation parameter in the SSOR
619 * preconditioner. The parameter <tt>min_diagonal</tt> can be used to make
620 * the application of the preconditioner also possible when some diagonal
621 * elements are zero. In a default application this would mean that we
622 * divide by zero, so by setting the parameter <tt>min_diagonal</tt> to a
623 * small nonzero value the SOR will work on a matrix that is not too far
624 * away from the one we want to treat. Finally, <tt>overlap</tt> governs
625 * the overlap of the partitions when the preconditioner runs in parallel,
626 * forming a so-called additive Schwarz preconditioner.
627 */
628 struct AdditionalData
629 {
630 /**
631 * Constructor. By default, use a block size of 1, use linear
632 * subdivision of the rows, set the damping parameter to one, we do not
633 * modify the diagonal, and there is no overlap (i.e. in parallel, we
634 * run a BlockJacobi preconditioner, where each block is inverted
635 * approximately by a block SOR).
636 */
637 AdditionalData(const unsigned int block_size = 1,
638 const std::string &block_creation_type = "linear",
639 const double omega = 1,
640 const double min_diagonal = 0,
641 const unsigned int overlap = 0,
642 const unsigned int n_sweeps = 1);
643
644 /**
645 * This specifies the size of blocks.
646 */
647 unsigned int block_size;
648
649 /**
650 * Strategy for creation of blocks passed on to Ifpack block relaxation
651 * (variable 'partitioner: type') with this string as the given value.
652 * Available types in Ifpack include "linear" (i.e., divide the local
653 * range of the matrix in slices of the block size), "greedy" "metis".
654 * For a full list, see the documentation of Ifpack.
655 */
656 std::string block_creation_type;
657
658 /**
659 * This specifies the (over-) relaxation parameter in the SOR
660 * preconditioner.
661 */
662 double omega;
663
664 /**
665 * This specifies the minimum value the diagonal elements should have.
666 * This might be necessary when the SSOR preconditioner is used on
667 * matrices with zero diagonal elements. In that case, a
668 * straight-forward application would not be possible since we divide by
669 * the diagonal element.
670 */
671 double min_diagonal;
672
673 /**
674 * This determines how large the overlap of the local matrix portions on
675 * each processor in a parallel application should be.
676 */
677 unsigned int overlap;
678
679 /**
680 * Sets how many times the given operation should be applied during the
681 * vmult() operation.
682 */
683 unsigned int n_sweeps;
684 };
685
686 /**
687 * Take the sparse matrix the preconditioner object should be built of,
688 * and additional flags (damping parameter, overlap in parallel
689 * computations, etc.) if there are any.
690 */
691 void
692 initialize(const SparseMatrix &matrix,
693 const AdditionalData &additional_data = AdditionalData());
694 };
695
696
697
698 /**
699 * A wrapper class for a block SOR preconditioner for Trilinos matrices. As
700 * opposed to PreconditionSOR where each row is treated separately, this
701 * scheme collects block of a given size and inverts a full matrix for all
702 * these rows simultaneously. Trilinos allows to select several strategies
703 * for selecting which rows form a block, including "linear" (i.e., divide
704 * the local range of the matrix in slices of the block size), "greedy" or
705 * "metis".
706 *
707 * The AdditionalData data structure allows to set preconditioner options.
708 *
709 * Note that a parallel application of this preconditioner is actually a
710 * block-Jacobi preconditioner with (outer) block size equal to the local
711 * matrix size. Spoken more technically, this parallel operation is an <a
712 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
713 * Schwarz method</a> with a block SOR <em>approximate solve</em> as inner
714 * solver, based on the outer parallel partitioning.
715 *
716 * @ingroup TrilinosWrappers
717 * @ingroup Preconditioners
718 */
719 class PreconditionBlockSOR : public PreconditionBase
720 {
721 public:
722 /**
723 * Standardized data struct to pipe additional flags to the
724 * preconditioner. The parameter <tt>block_size</tt> sets the size of
725 * small blocks. It is recommended to choose this parameter not too large
726 * (a few hundreds at most) since this implementation uses a dense matrix
727 * for the block. The parameter <tt>block_creation_type</tt> allows to
728 * pass the strategy for finding the blocks to Ifpack. The parameter
729 * <tt>omega</tt> specifies the relaxation parameter in the SOR
730 * preconditioner. The parameter <tt>min_diagonal</tt> can be used to make
731 * the application of the preconditioner also possible when some diagonal
732 * elements are zero. In a default application this would mean that we
733 * divide by zero, so by setting the parameter <tt>min_diagonal</tt> to a
734 * small nonzero value the SOR will work on a matrix that is not too far
735 * away from the one we want to treat. Finally, <tt>overlap</tt> governs
736 * the overlap of the partitions when the preconditioner runs in parallel,
737 * forming a so-called additive Schwarz preconditioner.
738 */
739 struct AdditionalData
740 {
741 /**
742 * Constructor. By default, use a block size of 1, use linear
743 * subdivision of the rows, set the damping parameter to one, we do not
744 * modify the diagonal, and there is no overlap (i.e. in parallel, we
745 * run a BlockJacobi preconditioner, where each block is inverted
746 * approximately by a block SOR).
747 */
748 AdditionalData(const unsigned int block_size = 1,
749 const std::string &block_creation_type = "linear",
750 const double omega = 1,
751 const double min_diagonal = 0,
752 const unsigned int overlap = 0,
753 const unsigned int n_sweeps = 1);
754
755 /**
756 * This specifies the size of blocks.
757 */
758 unsigned int block_size;
759
760 /**
761 * Strategy for creation of blocks passed on to Ifpack block relaxation
762 * (variable 'partitioner: type') with this string as the given value.
763 * Available types in Ifpack include "linear" (i.e., divide the local
764 * range of the matrix in slices of the block size), "greedy" "metis".
765 * For a full list, see the documentation of Ifpack.
766 */
767 std::string block_creation_type;
768
769 /**
770 * This specifies the (over-) relaxation parameter in the SOR
771 * preconditioner.
772 */
773 double omega;
774
775 /**
776 * This specifies the minimum value the diagonal elements should have.
777 * This might be necessary when the SOR preconditioner is used on
778 * matrices with zero diagonal elements. In that case, a
779 * straight-forward application would not be possible since we divide by
780 * the diagonal element.
781 */
782 double min_diagonal;
783
784 /**
785 * This determines how large the overlap of the local matrix portions on
786 * each processor in a parallel application should be.
787 */
788 unsigned int overlap;
789
790 /**
791 * Sets how many times the given operation should be applied during the
792 * vmult() operation.
793 */
794 unsigned int n_sweeps;
795 };
796
797 /**
798 * Take the sparse matrix the preconditioner object should be built of,
799 * and additional flags (damping parameter, overlap in parallel
800 * computations etc.) if there are any.
801 */
802 void
803 initialize(const SparseMatrix &matrix,
804 const AdditionalData &additional_data = AdditionalData());
805 };
806
807
808
809 /**
810 * A wrapper class for an incomplete Cholesky factorization (IC)
811 * preconditioner for @em symmetric Trilinos matrices. This preconditioner
812 * works both in serial and in parallel, depending on the matrix it is based
813 * on. In general, an incomplete factorization does not take all fill-in
814 * elements that would appear in a full factorization (that is the basis for
815 * a direct solve). Trilinos allows to set the amount of fill-in elements,
816 * governed by the additional data argument <tt>ic_fill</tt>, so one can
817 * gradually choose between a factorization on the sparse matrix structure
818 * only (<tt>ic_fill=0</tt>) to a full factorization (<tt>ic_fill</tt> in
819 * the range of 10 to 50, depending on the spatial dimension of the PDE
820 * problem and the degree of the finite element basis functions; generally,
821 * more required fill-in elements require this parameter to be set to a
822 * higher integer value).
823 *
824 * The AdditionalData data structure allows to set preconditioner options.
825 * Besides the fill-in argument, these options are some options for
826 * perturbations (see the documentation of the AdditionalData structure for
827 * details), and a parameter <tt>overlap</tt> that determines if and how
828 * much overlap there should be between the matrix partitions on the various
829 * MPI processes. The default settings are 0 for the additional fill-in, 0
830 * for the absolute augmentation tolerance, 1 for the relative augmentation
831 * tolerance, 0 for the overlap.
832 *
833 * Note that a parallel application of the IC preconditioner is actually a
834 * block-Jacobi preconditioner with block size equal to the local matrix
835 * size. Spoken more technically, this parallel operation is an <a
836 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
837 * Schwarz method</a> with an IC <em>approximate solve</em> as inner solver,
838 * based on the (outer) parallel partitioning.
839 *
840 * @ingroup TrilinosWrappers
841 * @ingroup Preconditioners
842 */
843 class PreconditionIC : public PreconditionBase
844 {
845 public:
846 /**
847 * Standardized data struct to pipe additional parameters to the
848 * preconditioner. The Trilinos IC decomposition allows for some fill-in,
849 * so it actually is a threshold incomplete Cholesky factorization. The
850 * amount of fill-in, and hence, the amount of memory used by this
851 * preconditioner, is controlled by the parameter <tt>ic_fill</tt>, which
852 * specifies this as a double. When forming the preconditioner, for
853 * certain problems bad conditioning (or just bad luck) can cause the
854 * preconditioner to be very poorly conditioned. Hence it can help to add
855 * diagonal perturbations to the original matrix and form the
856 * preconditioner for this slightly better matrix. <tt>ic_atol</tt> is an
857 * absolute perturbation that is added to the diagonal before forming the
858 * prec, and <tt>ic_rtol</tt> is a scaling factor $rtol \geq 1$. The last
859 * parameter specifies the overlap of the partitions when the
860 * preconditioner runs in parallel.
861 */
862 struct AdditionalData
863 {
864 /**
865 * Constructor. By default, set the drop tolerance to 0, the level of
866 * extra fill-ins is set to be zero (just use the matrix structure, do
867 * not generate any additional fill-in), the tolerance level are 0 and
868 * 1, respectively, and the overlap in case of a parallel execution is
869 * zero. This overlap in a block-application of the IC in the parallel
870 * case makes the preconditioner a so-called additive Schwarz
871 * preconditioner.
872 */
873 AdditionalData(const unsigned int ic_fill = 0,
874 const double ic_atol = 0.,
875 const double ic_rtol = 1.,
876 const unsigned int overlap = 0);
877
878 /**
879 * This specifies the amount of additional fill-in elements besides the
880 * sparse matrix structure. When <tt>ic_fill</tt> is large, this means
881 * that many fill-ins will be added, so that the IC preconditioner comes
882 * closer to a direct sparse Cholesky decomposition. Note, however, that
883 * this will drastically increase the memory requirement, especially
884 * when the preconditioner is used in 3d.
885 */
886 unsigned int ic_fill;
887
888 /**
889 * This specifies the amount of an absolute perturbation that will be
890 * added to the diagonal of the matrix, which sometimes can help to get
891 * better preconditioners.
892 */
893 double ic_atol;
894
895 /**
896 * This specifies the factor by which the diagonal of the matrix will be
897 * scaled, which sometimes can help to get better preconditioners.
898 */
899 double ic_rtol;
900
901 /**
902 * This determines how large the overlap of the local matrix portions on
903 * each processor in a parallel application should be.
904 */
905 unsigned int overlap;
906 };
907
908 /**
909 * Initialize function. Takes the matrix the preconditioner should be
910 * computed of, and additional flags if there are any.
911 */
912 void
913 initialize(const SparseMatrix &matrix,
914 const AdditionalData &additional_data = AdditionalData());
915 };
916
917
918
919 /**
920 * A wrapper class for an incomplete LU factorization (ILU(k))
921 * preconditioner for Trilinos matrices. This preconditioner works both in
922 * serial and in parallel, depending on the matrix it is based on. In
923 * general, an incomplete factorization does not take all fill-in elements
924 * that would appear in a full factorization (that is the basis for a direct
925 * solve). Trilinos allows to set the amount of fill-in elements, governed
926 * by the additional data argument <tt>ilu_fill</tt>, so one can gradually
927 * choose between a factorization on the sparse matrix structure only
928 * (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in the
929 * range of 10 to 50, depending on the spatial dimension of the PDE problem
930 * and the degree of the finite element basis functions; generally, more
931 * required fill-in elements require this parameter to be set to a higher
932 * integer value).
933 *
934 * The AdditionalData data structure allows to set preconditioner options.
935 * See the documentation of the AdditionalData structure for details.
936 *
937 * Note that a parallel application of the ILU preconditioner is actually a
938 * block-Jacobi preconditioner with block size equal to the local matrix
939 * size. Spoken more technically, this parallel operation is an <a
940 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
941 * Schwarz method</a> with an ILU <em>approximate solve</em> as inner
942 * solver, based on the (outer) parallel partitioning.
943 *
944 * @ingroup TrilinosWrappers
945 * @ingroup Preconditioners
946 */
947 class PreconditionILU : public PreconditionBase
948 {
949 public:
950 /**
951 * Standardized data struct to pipe additional parameters to the
952 * preconditioner:
953 * <ul>
954 *
955 * <li> @p ilu_fill: This specifies the amount of additional fill-in
956 * elements besides the original sparse matrix structure. If $k$ is @p
957 * fill, the sparsity pattern of $A^{k+1}$ is used for the storage of the
958 * result of the Gaussian elimination. This is known as ILU($k$) in the
959 * literature. When @p fill is large, the preconditioner comes closer to
960 * a (direct) sparse LU decomposition. Note, however, that this will
961 * drastically increase the memory requirement, especially when the
962 * preconditioner is used in 3d.
963 *
964 * <li> @p ilu_atol and @p ilu_rtol: These two parameters allow
965 * perturbation of the diagonal of the matrix, which sometimes can help to
966 * get better preconditioners especially in the case of bad conditioning.
967 * Before factorization, the diagonal entry $a_{ii}$ is replaced by
968 * $\alpha sign(a_{ii}) + \beta a_{ii}$, where $\alpha\geq 0$ is the
969 * absolute threshold @p ilu_atol and $\beta\geq 1$ is the relative
970 * threshold @p ilu_rtol. The default values ($\alpha = 0$, $\beta = 1$)
971 * therefore use the original, unmodified diagonal entry. Suggested values
972 * are in the order of $10^{-5}$ to $10^{-2}$ for @p ilu_atol and 1.01 for
973 * @p ilu_rtol.
974 *
975 * <li> @p overlap: This determines how large the overlap of the local
976 * matrix portions on each processor in a parallel application should be.
977 * An overlap of 0 corresponds to a block diagonal decomposition on each
978 * processor, an overlap of 1 will additionally include a row j if there
979 * is a nonzero entry in column j in one of the own rows. Higher overlap
980 * numbers work accordingly in a recursive fashion. Increasing @p overlap
981 * will increase communication and storage cost. According to the IFPACK
982 * documentation, an overlap of 1 is often effective and values of more
983 * than 3 are rarely needed.
984 *
985 * </ul>
986 */
987 struct AdditionalData
988 {
989 /**
990 * Constructor with default values for all parameters.
991 */
992 AdditionalData(const unsigned int ilu_fill = 0,
993 const double ilu_atol = 0.,
994 const double ilu_rtol = 1.,
995 const unsigned int overlap = 0);
996
997 /**
998 * Additional fill-in, see class documentation above.
999 */
1000 unsigned int ilu_fill;
1001
1002 /**
1003 * The amount of perturbation to add to diagonal entries. See the class
1004 * documentation above for details.
1005 */
1006 double ilu_atol;
1007
1008 /**
1009 * Scaling actor for diagonal entries. See the class documentation above
1010 * for details.
1011 */
1012 double ilu_rtol;
1013
1014 /**
1015 * Overlap between processors. See the class documentation for details.
1016 */
1017 unsigned int overlap;
1018 };
1019
1020 /**
1021 * Initialize function. Takes the matrix which is used to form the
1022 * preconditioner, and additional flags if there are any.
1023 */
1024 void
1025 initialize(const SparseMatrix &matrix,
1026 const AdditionalData &additional_data = AdditionalData());
1027 };
1028
1029
1030
1031 /**
1032 * A wrapper class for a thresholded incomplete LU factorization (ILU-T)
1033 * preconditioner for Trilinos matrices. This preconditioner works both in
1034 * serial and in parallel, depending on the matrix it is based on. In
1035 * general, an incomplete factorization does not take all fill-in elements
1036 * that would appear in a full factorization (that is the basis for a direct
1037 * solve). For the ILU-T preconditioner, the parameter <tt>ilut_drop</tt>
1038 * lets the user specify which elements should be dropped (i.e., should not
1039 * be part of the incomplete decomposition). Trilinos calculates first the
1040 * complete factorization for one row, and then skips those elements that
1041 * are lower than the threshold. This is the main difference to the
1042 * non-thresholded ILU preconditioner, where the parameter <tt>ilut_fill</tt>
1043 * governs the incomplete factorization structure. This parameter is
1044 * available here as well, but provides only some extra information here.
1045 *
1046 * The AdditionalData data structure allows to set preconditioner options.
1047 * Besides the fill-in arguments, these options are some options for
1048 * perturbations (see the documentation of the AdditionalData structure for
1049 * details), and a parameter <tt>overlap</tt> that determines if and how
1050 * much overlap there should be between the matrix partitions on the various
1051 * MPI processes. The default settings are 0 for the additional fill-in, 0
1052 * for the absolute augmentation tolerance, 1 for the relative augmentation
1053 * tolerance, 0 for the overlap.
1054 *
1055 * Note that a parallel application of the ILU-T preconditioner is actually
1056 * a block-Jacobi preconditioner with block size equal to the local matrix
1057 * size. Spoken more technically, this parallel operation is an <a
1058 * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
1059 * Schwarz method</a> with an ILU <em>approximate solve</em> as inner
1060 * solver, based on the (outer) parallel partitioning.
1061 *
1062 * @ingroup TrilinosWrappers
1063 * @ingroup Preconditioners
1064 */
1065 class PreconditionILUT : public PreconditionBase
1066 {
1067 public:
1068 /**
1069 * Standardized data struct to pipe additional parameters to the
1070 * preconditioner. The Trilinos ILU-T decomposition allows for some
1071 * fill-in, so it actually is a threshold incomplete LU factorization. The
1072 * amount of fill-in, and hence, the amount of memory used by this
1073 * preconditioner, is controlled by the parameters <tt>ilut_drop</tt> and
1074 * <tt>ilut_fill</tt>, which specifies a threshold about which values
1075 * should form the incomplete factorization and the level of additional
1076 * fill-in. When forming the preconditioner, for certain problems bad
1077 * conditioning (or just bad luck) can cause the preconditioner to be very
1078 * poorly conditioned. Hence it can help to add diagonal perturbations to
1079 * the original matrix and form the preconditioner for this slightly
1080 * better matrix. <tt>ilut_atol</tt> is an absolute perturbation that is
1081 * added to the diagonal before forming the prec, and <tt>ilu_rtol</tt> is
1082 * a scaling factor $rtol \geq 1$. The last parameter specifies the
1083 * overlap of the partitions when the preconditioner runs in parallel.
1084 */
1085 struct AdditionalData
1086 {
1087 /**
1088 * Constructor. By default, no element will be dropped, the level of
1089 * extra fill-ins is set to be zero (just use the matrix structure, do
1090 * not generate any additional fill-in except the one that results from
1091 * non-dropping large elements), the tolerance level are 0 and 1,
1092 * respectively, and the overlap in case of a parallel execution is
1093 * zero. This overlap in a block-application of the ILU in the parallel
1094 * case makes the preconditioner a so-called additive Schwarz
1095 * preconditioner.
1096 */
1097 AdditionalData(const double ilut_drop = 0.,
1098 const unsigned int ilut_fill = 0,
1099 const double ilut_atol = 0.,
1100 const double ilut_rtol = 1.,
1101 const unsigned int overlap = 0);
1102
1103 /**
1104 * This specifies the relative size of elements which should be dropped
1105 * when forming an incomplete LU decomposition with threshold.
1106 */
1107 double ilut_drop;
1108
1109 /**
1110 * This specifies the amount of additional fill-in elements besides the
1111 * sparse matrix structure. When <tt>ilu_fill</tt> is large, this means
1112 * that many fill-ins will be added, so that the ILU preconditioner
1113 * comes closer to a (direct) sparse LU decomposition. Note, however,
1114 * that this will drastically increase the memory requirement,
1115 * especially when the preconditioner is used in 3d.
1116 */
1117 unsigned int ilut_fill;
1118
1119 /**
1120 * This specifies the amount of an absolute perturbation that will be
1121 * added to the diagonal of the matrix, which sometimes can help to get
1122 * better preconditioners.
1123 */
1124 double ilut_atol;
1125
1126 /**
1127 * This specifies the factor by which the diagonal of the matrix will be
1128 * scaled, which sometimes can help to get better preconditioners.
1129 */
1130 double ilut_rtol;
1131
1132 /**
1133 * This determines how large the overlap of the local matrix portions on
1134 * each processor in a parallel application should be.
1135 */
1136 unsigned int overlap;
1137 };
1138
1139 /**
1140 * Initialize function. Takes the matrix which is used to form the
1141 * preconditioner, and additional flags if there are any.
1142 */
1143 void
1144 initialize(const SparseMatrix &matrix,
1145 const AdditionalData &additional_data = AdditionalData());
1146 };
1147
1148
1149
1150 /**
1151 * A wrapper class for a sparse direct LU decomposition on parallel blocks
1152 * for Trilinos matrices. When run in serial, this corresponds to a direct
1153 * solve on the matrix.
1154 *
1155 * The AdditionalData data structure allows to set preconditioner options.
1156 *
1157 * Note that a parallel application of the block direct solve preconditioner
1158 * is actually a block-Jacobi preconditioner with block size equal to the
1159 * local matrix size. Spoken more technically, this parallel operation is an
1160 * <a href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
1161 * Schwarz method</a> with an <em>exact solve</em> as inner solver, based on
1162 * the (outer) parallel partitioning.
1163 *
1164 * @ingroup TrilinosWrappers
1165 * @ingroup Preconditioners
1166 */
1167 class PreconditionBlockwiseDirect : public PreconditionBase
1168 {
1169 public:
1170 /**
1171 * Standardized data struct to pipe additional parameters to the
1172 * preconditioner.
1173 */
1174 struct AdditionalData
1175 {
1176 /**
1177 * Constructor.
1178 */
1179 AdditionalData(const unsigned int overlap = 0);
1180
1181
1182 /**
1183 * This determines how large the overlap of the local matrix portions on
1184 * each processor in a parallel application should be.
1185 */
1186 unsigned int overlap;
1187 };
1188
1189 /**
1190 * Initialize function. Takes the matrix which is used to form the
1191 * preconditioner, and additional flags if there are any.
1192 */
1193 void
1194 initialize(const SparseMatrix &matrix,
1195 const AdditionalData &additional_data = AdditionalData());
1196 };
1197
1198
1199
1200 /**
1201 * A wrapper class for a Chebyshev preconditioner for Trilinos matrices.
1202 *
1203 * The AdditionalData data structure allows to set preconditioner options.
1204 *
1205 * @ingroup TrilinosWrappers
1206 * @ingroup Preconditioners
1207 */
1208 class PreconditionChebyshev : public PreconditionBase
1209 {
1210 public:
1211 /**
1212 * Standardized data struct to pipe additional parameters to the
1213 * preconditioner.
1214 */
1215 struct AdditionalData
1216 {
1217 /**
1218 * Constructor.
1219 */
1220 AdditionalData(const unsigned int degree = 1,
1221 const double max_eigenvalue = 10.,
1222 const double eigenvalue_ratio = 30.,
1223 const double min_eigenvalue = 1.,
1224 const double min_diagonal = 1e-12,
1225 const bool nonzero_starting = false);
1226
1227 /**
1228 * This determines the degree of the Chebyshev polynomial. The degree of
1229 * the polynomial gives the number of matrix-vector products to be
1230 * performed for one application of the vmult() operation.
1231 */
1232 unsigned int degree;
1233
1234 /**
1235 * This sets the maximum eigenvalue of the matrix, which needs to be set
1236 * properly for appropriate performance of the Chebyshev preconditioner.
1237 */
1238 double max_eigenvalue;
1239
1240 /**
1241 * This sets the ratio between the maximum and the minimum eigenvalue.
1242 */
1243 double eigenvalue_ratio;
1244
1245 /**
1246 * This sets the minimum eigenvalue, which is an optional parameter only
1247 * used internally for checking whether we use an identity matrix.
1248 */
1249 double min_eigenvalue;
1250
1251 /**
1252 * This sets a threshold below which the diagonal element will not be
1253 * inverted in the Chebyshev algorithm.
1254 */
1255 double min_diagonal;
1256
1257 /**
1258 * When this flag is set to <tt>true</tt>, it enables the method
1259 * <tt>vmult(dst, src)</tt> to use non-zero data in the vector
1260 * <tt>dst</tt>, appending to it the Chebyshev corrections. This can be
1261 * useful in some situations (e.g. when used for high-frequency error
1262 * smoothing), but not the way the solver classes expect a
1263 * preconditioner to work (where one ignores the content in <tt>dst</tt>
1264 * for the preconditioner application). The user should really know what
1265 * they are doing when touching this flag.
1266 */
1267 bool nonzero_starting;
1268 };
1269
1270 /**
1271 * Initialize function. Takes the matrix which is used to form the
1272 * preconditioner, and additional flags if there are any.
1273 */
1274 void
1275 initialize(const SparseMatrix &matrix,
1276 const AdditionalData &additional_data = AdditionalData());
1277 };
1278
1279
1280
1281 /**
1282 * This class implements an algebraic multigrid (AMG) preconditioner based
1283 * on the Trilinos ML implementation, which is a black-box preconditioner
1284 * that works well for many PDE-based linear problems. What this class does
1285 * is twofold. When the initialize() function is invoked, a ML
1286 * preconditioner object is created based on the matrix that we want the
1287 * preconditioner to be based on. A call of the respective
1288 * <code>vmult</code> function does call the respective operation in the
1289 * Trilinos package, where it is called <code>ApplyInverse</code>. Use of
1290 * this class is explained in the step-31 tutorial program.
1291 *
1292 * Since the Trilinos objects we want to use are heavily dependent on Epetra
1293 * objects, we recommend using this class in conjunction with Trilinos
1294 * (Epetra) sparse matrices and vectors. There is support for use with
1295 * matrices of the dealii::SparseMatrix class and corresponding vectors,
1296 * too, but this requires generating a copy of the matrix, which is slower
1297 * and takes (much) more memory. When doing such a copy operation, we can
1298 * still profit from the fact that some of the entries in the preconditioner
1299 * matrix are zero and hence can be neglected.
1300 *
1301 * The implementation is able to distinguish between matrices from elliptic
1302 * problems and convection dominated problems. We use the standard options
1303 * provided by Trilinos ML for elliptic problems, except that we use a
1304 * Chebyshev smoother instead of a symmetric Gauss-Seidel smoother. For
1305 * most elliptic problems, Chebyshev provides a better damping of high
1306 * frequencies (in the algebraic sense) than Gauss-Seidel (SSOR), and is
1307 * faster (Chebyshev requires only some matrix-vector products, whereas SSOR
1308 * requires substitutions which are more expensive). Moreover, Chebyshev is
1309 * perfectly parallel in the sense that it does not degenerate when used on
1310 * many processors. SSOR, on the other hand, gets more Jacobi-like on many
1311 * processors.
1312 *
1313 * This class can be used as a preconditioner for linear solvers. It
1314 * also provides a `vmult()` function (implemented in the
1315 * PreconditionBase base class) that, when called, performs one
1316 * multigrid cycle. By default, this is a V-cycle, but the
1317 * AdditionalData class allows to also select a W-cycle.
1318 *
1319 * @ingroup TrilinosWrappers
1320 * @ingroup Preconditioners
1321 */
1322 class PreconditionAMG : public PreconditionBase
1323 {
1324 public:
1325 /**
1326 * A data structure that is used to control details of how the algebraic
1327 * multigrid is set up. The flags detailed in here are then passed to the
1328 * Trilinos ML implementation. A structure of the current type are passed
1329 * to the constructor of PreconditionAMG.
1330 */
1331 struct AdditionalData
1332 {
1333 /**
1334 * Constructor. By default, we pretend to work on elliptic problems with
1335 * linear finite elements on a scalar equation.
1336 *
1337 * Making use of the DoFTools::extract_constant_modes() function, the
1338 * @p constant_modes vector can be initialized for a given field in the
1339 * following manner:
1340 *
1341 * @code
1342 * #include <deal.II/dofs/dof_tools.h>
1343 * ...
1344 *
1345 * DoFHandler<...> dof_handler;
1346 * FEValuesExtractors::Type... field_extractor;
1347 * ...
1348 *
1349 * TrilinosWrappers::PreconditionAMG::AdditionalData data;
1350 * DoFTools::extract_constant_modes(
1351 * dof_handler,
1352 * dof_handler.get_fe_collection().component_mask(field_extractor),
1353 * data.constant_modes );
1354 * @endcode
1355 */
1356 AdditionalData(const bool elliptic = true,
1357 const bool higher_order_elements = false,
1358 const unsigned int n_cycles = 1,
1359 const bool w_cycle = false,
1360 const double aggregation_threshold = 1e-4,
1361 const std::vector<std::vector<bool>> &constant_modes =
1362 std::vector<std::vector<bool>>(0),
1363 const unsigned int smoother_sweeps = 2,
1364 const unsigned int smoother_overlap = 0,
1365 const bool output_details = false,
1366 const char *smoother_type = "Chebyshev",
1367 const char *coarse_type = "Amesos-KLU");
1368
1369 /**
1370 * Fill in a @p parameter_list that can be used to initialize the
1371 * AMG preconditioner.
1372 *
1373 * The @p matrix is used in conjunction with the @p constant_modes to
1374 * configure the null space settings for the preconditioner.
1375 * The @p distributed_constant_modes are initialized by this function, and
1376 * must remain in scope until PreconditionAMG::initialize() has been
1377 * called.
1378 *
1379 * @note The set parameters reflect the current settings in this
1380 * object, with various options being set both directly though the state
1381 * of the member variables (e.g. the "smoother: type") as well as
1382 * indirectly (e.g. the "aggregation: type"). If you wish to have
1383 * fine-grained control over the configuration of the AMG preconditioner,
1384 * then you can create the parameter list using this function (which
1385 * conveniently sets the null space of the operator), change the relevant
1386 * settings, and use the amended parameters list as an argument to
1387 * PreconditionAMG::initialize(), instead of the AdditionalData object
1388 * itself.
1389 *
1390 * See the documentation for the
1391 * <a
1392 * href="https://trilinos.org/docs/dev/packages/ml/doc/html/index.html">
1393 * Trilinos ML package</a> for details on what options are available for
1394 * modification.
1395 *
1396 * @note Any user-defined parameters that are not in conflict with those
1397 * set by this data structure will be retained.
1398 */
1399 void
1400 set_parameters(
1401 Teuchos::ParameterList &parameter_list,
1402 std::unique_ptr<Epetra_MultiVector> &distributed_constant_modes,
1403 const Epetra_RowMatrix &matrix) const;
1404
1405 /**
1406 * Fill in a parameter list that can be used to initialize the
1407 * AMG preconditioner.
1408 *
1409 * @note Any user-defined parameters that are not in conflict with those
1410 * set by this data structure will be retained.
1411 */
1412 void
1413 set_parameters(
1414 Teuchos::ParameterList &parameter_list,
1415 std::unique_ptr<Epetra_MultiVector> &distributed_constant_modes,
1416 const SparseMatrix &matrix) const;
1417
1418 /**
1419 * Configure the null space setting in the @p parameter_list for
1420 * the input @p matrix based on the state of the @p constant_modes
1421 * variable.
1422 */
1423 void
1424 set_operator_null_space(
1425 Teuchos::ParameterList &parameter_list,
1426 std::unique_ptr<Epetra_MultiVector> &distributed_constant_modes,
1427 const Epetra_RowMatrix &matrix) const;
1428
1429 /**
1430 * Configure the null space setting in the @p parameter_list for
1431 * the input @p matrix based on the state of the @p constant_modes
1432 * variable.
1433 */
1434 void
1435 set_operator_null_space(
1436 Teuchos::ParameterList &parameter_list,
1437 std::unique_ptr<Epetra_MultiVector> &distributed_constant_modes,
1438 const SparseMatrix &matrix) const;
1439
1440 /**
1441 * Determines whether the AMG preconditioner should be optimized for
1442 * elliptic problems (ML option smoothed aggregation SA, using a
1443 * Chebyshev smoother) or for non-elliptic problems (ML option
1444 * non-symmetric smoothed aggregation NSSA, smoother is SSOR with
1445 * underrelaxation).
1446 */
1447 bool elliptic;
1448
1449 /**
1450 * Determines whether the matrix that the preconditioner is built upon
1451 * is generated from linear or higher-order elements.
1452 */
1453 bool higher_order_elements;
1454
1455 /**
1456 * Defines how many multigrid cycles should be performed by the
1457 * preconditioner.
1458 */
1459 unsigned int n_cycles;
1460
1461 /**
1462 * Defines whether a w-cycle should be used instead of the standard
1463 * setting of a v-cycle.
1464 */
1465 bool w_cycle;
1466
1467 /**
1468 * This threshold tells the AMG setup how the coarsening should be
1469 * performed. In the AMG used by ML, all points that strongly couple
1470 * with the tentative coarse-level point form one aggregate. The term
1471 * <em>strong coupling</em> is controlled by the variable
1472 * <tt>aggregation_threshold</tt>, meaning that all elements that are
1473 * not smaller than <tt>aggregation_threshold</tt> times the diagonal
1474 * element do couple strongly.
1475 */
1476 double aggregation_threshold;
1477
1478 /**
1479 * Specifies the constant modes (near null space) of the matrix. This
1480 * parameter tells AMG whether we work on a scalar equation (where the
1481 * near null space only consists of ones, and default value is OK) or on
1482 * a vector-valued equation. For vector-valued problem with
1483 * <tt>n_components</tt> components, the provided @p constant_modes
1484 * should fulfill the following requirements:
1485 * <ul>
1486 * <li> <tt>constant_modes.size() == n_components</tt> </li>
1487 * <li> <tt>constant_modes[*].size()</tt> needs to be equal to either
1488 * the total number of degrees of freedom associated with the linear
1489 * system (<tt>constant_modes[*].size() == n_dofs</tt>), or the
1490 * number of locally owned degrees of freedom
1491 * (<tt>constant_modes[*].size() == n_locally_owned_dofs</tt>). In
1492 * parallel computations, the latter is the more appropriate choice
1493 * since one does not want to store vectors of global size on
1494 * individual processes. </li>
1495 * <li> <tt>constant_modes[ic][id] == true</tt> if DoF <tt>id</tt> is a
1496 * degree of freedom that is part of vector component <tt>ic</tt>.
1497 * </li>
1498 * </ul>
1499 * We obtain the <tt>constant_modes</tt> fulfilling the above requirements
1500 * with the function DoFTools::extract_constant_modes.
1501 */
1502 std::vector<std::vector<bool>> constant_modes;
1503
1504 /**
1505 * Same as above, but with values instead of Booleans. This
1506 * is useful if you want to specify rotational modes
1507 * in addition to the translational modes. See also:
1508 * DoFTools::extract_rigid_body_modes
1509 * and DoFTools::extract_level_rigid_body_modes.
1510 */
1511 std::vector<std::vector<double>> constant_modes_values;
1512
1513 /**
1514 * Determines how many sweeps of the smoother should be performed. When
1515 * the flag <tt>elliptic</tt> is set to <tt>true</tt>, i.e., for
1516 * elliptic or almost elliptic problems, the polynomial degree of the
1517 * Chebyshev smoother is set to <tt>smoother_sweeps</tt>. The term
1518 * sweeps refers to the number of matrix-vector products performed in
1519 * the Chebyshev case. In the non-elliptic case,
1520 * <tt>smoother_sweeps</tt> sets the number of SSOR relaxation sweeps
1521 * for post-smoothing to be performed.
1522 */
1523 unsigned int smoother_sweeps;
1524
1525 /**
1526 * Determines the overlap in the SSOR/Chebyshev error smoother when run
1527 * in parallel.
1528 */
1529 unsigned int smoother_overlap;
1530
1531 /**
1532 * If this flag is set to <tt>true</tt>, then internal information from
1533 * the ML preconditioner is printed to screen. This can be useful when
1534 * debugging the preconditioner.
1535 */
1536 bool output_details;
1537
1538 /**
1539 * Determines which smoother to use for the AMG cycle. Possibilities for
1540 * smoother_type are the following:
1541 * <ul>
1542 * <li> "Aztec" </li>
1543 * <li> "IFPACK" </li>
1544 * <li> "Jacobi" </li>
1545 * <li> "ML symmetric Gauss-Seidel" </li>
1546 * <li> "symmetric Gauss-Seidel" </li>
1547 * <li> "ML Gauss-Seidel" </li>
1548 * <li> "Gauss-Seidel" </li>
1549 * <li> "block Gauss-Seidel" </li>
1550 * <li> "symmetric block Gauss-Seidel" </li>
1551 * <li> "Chebyshev" </li>
1552 * <li> "MLS" </li>
1553 * <li> "Hiptmair" </li>
1554 * <li> "Amesos-KLU" </li>
1555 * <li> "Amesos-Superlu" </li>
1556 * <li> "Amesos-UMFPACK" </li>
1557 * <li> "Amesos-Superludist" </li>
1558 * <li> "Amesos-MUMPS" </li>
1559 * <li> "user-defined" </li>
1560 * <li> "SuperLU" </li>
1561 * <li> "IFPACK-Chebyshev" </li>
1562 * <li> "self" </li>
1563 * <li> "do-nothing" </li>
1564 * <li> "IC" </li>
1565 * <li> "ICT" </li>
1566 * <li> "ILU" </li>
1567 * <li> "ILUT" </li>
1568 * <li> "Block Chebyshev" </li>
1569 * <li> "IFPACK-Block Chebyshev" </li>
1570 * </ul>
1571 */
1572 const char *smoother_type;
1573
1574 /**
1575 * Determines which solver to use on the coarsest level. The same
1576 * settings as for the smoother type are possible.
1577 */
1578 const char *coarse_type;
1579 };
1580
1581 /**
1582 * Destructor.
1583 */
1584 ~PreconditionAMG() override;
1585
1586
1587 /**
1588 * Let Trilinos compute a multilevel hierarchy for the solution of a
1589 * linear system with the given matrix. The function uses the matrix
1590 * format specified in TrilinosWrappers::SparseMatrix.
1591 */
1592 void
1593 initialize(const SparseMatrix &matrix,
1594 const AdditionalData &additional_data = AdditionalData());
1595
1596 /**
1597 * Let Trilinos compute a multilevel hierarchy for the solution of a
1598 * linear system with the given matrix. As opposed to the other initialize
1599 * function above, this function uses an abstract interface to an object
1600 * of type Epetra_RowMatrix which allows a user to pass quite general
1601 * objects to the ML preconditioner.
1602 *
1603 * This initialization routine is useful in cases where the operator to be
1604 * preconditioned is not a TrilinosWrappers::SparseMatrix object but still
1605 * allows getting a copy of the entries in each of the locally owned matrix
1606 * rows (method ExtractMyRowCopy) and implements a matrix-vector product
1607 * (methods Multiply or Apply). An example are operators which provide
1608 * faster matrix-vector multiplications than possible with matrix entries
1609 * (matrix-free methods). These implementations can be beneficially
1610 * combined with Chebyshev smoothers that only perform matrix-vector
1611 * products. The interface class Epetra_RowMatrix is very flexible to
1612 * enable this kind of implementation.
1613 */
1614 void
1615 initialize(const Epetra_RowMatrix &matrix,
1616 const AdditionalData &additional_data = AdditionalData());
1617
1618 /**
1619 * Let Trilinos compute a multilevel hierarchy for the solution of a
1620 * linear system with the given matrix. The function uses the matrix
1621 * format specified in TrilinosWrappers::SparseMatrix.
1622 *
1623 * This function is similar to the one above, but allows the user
1624 * to set all the options of the Trilinos ML preconditioner. In
1625 * order to find out about all the options for ML, we refer to the
1626 * <a
1627 * href="https://trilinos.org/docs/dev/packages/ml/doc/html/index.html">ML
1628 * documentation page</a>. In particular, users need to follow the
1629 * ML instructions in case a vector-valued problem ought to be
1630 * solved.
1631 */
1632 void
1633 initialize(const SparseMatrix &matrix,
1634 const Teuchos::ParameterList &ml_parameters);
1635
1636 /**
1637 * Let Trilinos compute a multilevel hierarchy for the solution of a
1638 * linear system with the given matrix. As opposed to the other initialize
1639 * function above, this function uses an abstract interface to an object
1640 * of type Epetra_RowMatrix which allows a user to pass quite general
1641 * objects to the ML preconditioner.
1642 */
1643 void
1644 initialize(const Epetra_RowMatrix &matrix,
1645 const Teuchos::ParameterList &ml_parameters);
1646
1647 /**
1648 * Let Trilinos compute a multilevel hierarchy for the solution of a
1649 * linear system with the given matrix. This function takes a deal.II
1650 * matrix and copies the content into a Trilinos matrix, so the function
1651 * can be considered rather inefficient.
1652 */
1653 template <typename number>
1654 void
1655 initialize(const ::dealii::SparseMatrix<number> &deal_ii_sparse_matrix,
1656 const AdditionalData &additional_data = AdditionalData(),
1657 const double drop_tolerance = 1e-13,
1658 const ::dealii::SparsityPattern *use_this_sparsity = nullptr);
1659
1660 /**
1661 * This function can be used for a faster recalculation of the
1662 * preconditioner construction when the matrix entries underlying the
1663 * preconditioner have changed, but the matrix sparsity pattern has
1664 * remained the same. What this function does is taking the already
1665 * generated coarsening structure, computing the AMG prolongation and
1666 * restriction according to a smoothed aggregation strategy and then
1667 * building the whole multilevel hierarchy. This function can be
1668 * considerably faster than the initialize function, since the coarsening
1669 * pattern is usually the most difficult thing to do when setting up the
1670 * AMG ML preconditioner.
1671 */
1672 void
1673 reinit();
1674
1675 /**
1676 * Destroys the preconditioner, leaving an object like just after having
1677 * called the constructor.
1678 */
1679 void
1680 clear();
1681
1682 /**
1683 * Prints an estimate of the memory consumption of this class.
1684 */
1685 size_type
1686 memory_consumption() const;
1687
1688 private:
1689 /**
1690 * A copy of the deal.II matrix into Trilinos format.
1691 */
1692 std::shared_ptr<SparseMatrix> trilinos_matrix;
1693 };
1694
1695
1696
1697 # if defined(DOXYGEN) || defined(DEAL_II_TRILINOS_WITH_MUELU)
1698 /**
1699 * This class implements an algebraic multigrid (AMG) preconditioner based
1700 * on the Trilinos MueLu implementation, which is a black-box preconditioner
1701 * that works well for many PDE-based linear problems. The interface of
1702 * PreconditionerAMGMueLu is the same as the interface of PreconditionerAMG
1703 * (which, instead of the Trilinos package MueLu is built on the older
1704 * Trilinos package ML). The only functional difference between the two
1705 * classes is the `higher_order_elements` parameter which does not exist in
1706 * PreconditionerAMGMueLu.
1707 *
1708 * This class can be used as a preconditioner for linear solvers. It
1709 * also provides a `vmult()` function (implemented in the
1710 * PreconditionBase base class) that, when called, performs one
1711 * multigrid cycle. By default, this is a V-cycle, but the
1712 * AdditionalData class allows to also select a W-cycle.
1713 *
1714 * @note You need to configure Trilinos with MueLU support for this
1715 * preconditioner to work.
1716 *
1717 * @note At the moment 64bit-indices are not supported.
1718 *
1719 * @warning This interface should not be considered as stable.
1720 *
1721 * @ingroup TrilinosWrappers
1722 * @ingroup Preconditioners
1723 */
1724 class PreconditionAMGMueLu : public PreconditionBase
1725 {
1726 public:
1727 /**
1728 * A data structure that is used to control details of how the algebraic
1729 * multigrid is set up. The flags detailed in here are then passed to the
1730 * Trilinos MueLu implementation. A structure of the current type are
1731 * passed to the constructor of PreconditionAMGMueLu.
1732 */
1733 struct AdditionalData
1734 {
1735 /**
1736 * Constructor. By default, we pretend to work on elliptic problems with
1737 * linear finite elements on a scalar equation.
1738 */
1739 AdditionalData(const bool elliptic = true,
1740 const unsigned int n_cycles = 1,
1741 const bool w_cycle = false,
1742 const double aggregation_threshold = 1e-4,
1743 const std::vector<std::vector<bool>> &constant_modes =
1744 std::vector<std::vector<bool>>(0),
1745 const unsigned int smoother_sweeps = 2,
1746 const unsigned int smoother_overlap = 0,
1747 const bool output_details = false,
1748 const char *smoother_type = "Chebyshev",
1749 const char *coarse_type = "Amesos-KLU");
1750
1751 /**
1752 * Determines whether the AMG preconditioner should be optimized for
1753 * elliptic problems (MueLu option smoothed aggregation SA, using a
1754 * Chebyshev smoother) or for non-elliptic problems (MueLu option
1755 * non-symmetric smoothed aggregation NSSA, smoother is SSOR with
1756 * underrelaxation).
1757 */
1758 bool elliptic;
1759
1760 /**
1761 * Defines how many multigrid cycles should be performed by the
1762 * preconditioner.
1763 */
1764 unsigned int n_cycles;
1765
1766 /**
1767 * Defines whether a w-cycle should be used instead of the standard
1768 * setting of a v-cycle.
1769 */
1770 bool w_cycle;
1771
1772 /**
1773 * This threshold tells the AMG setup how the coarsening should be
1774 * performed. In the AMG used by MueLu, all points that strongly couple
1775 * with the tentative coarse-level point form one aggregate. The term
1776 * <em>strong coupling</em> is controlled by the variable
1777 * <tt>aggregation_threshold</tt>, meaning that all elements that are
1778 * not smaller than <tt>aggregation_threshold</tt> times the diagonal
1779 * element do couple strongly.
1780 */
1781 double aggregation_threshold;
1782
1783 /**
1784 * Specifies the constant modes (near null space) of the matrix. This
1785 * parameter tells AMG whether we work on a scalar equation (where the
1786 * near null space only consists of ones) or on a vector-valued
1787 * equation.
1788 */
1789 std::vector<std::vector<bool>> constant_modes;
1790
1791 /**
1792 * Determines how many sweeps of the smoother should be performed. When
1793 * the flag <tt>elliptic</tt> is set to <tt>true</tt>, i.e., for
1794 * elliptic or almost elliptic problems, the polynomial degree of the
1795 * Chebyshev smoother is set to <tt>smoother_sweeps</tt>. The term
1796 * sweeps refers to the number of matrix-vector products performed in
1797 * the Chebyshev case. In the non-elliptic case,
1798 * <tt>smoother_sweeps</tt> sets the number of SSOR relaxation sweeps
1799 * for post-smoothing to be performed.
1800 */
1801 unsigned int smoother_sweeps;
1802
1803 /**
1804 * Determines the overlap in the SSOR/Chebyshev error smoother when run
1805 * in parallel.
1806 */
1807 unsigned int smoother_overlap;
1808
1809 /**
1810 * If this flag is set to <tt>true</tt>, then internal information from
1811 * the ML preconditioner is printed to screen. This can be useful when
1812 * debugging the preconditioner.
1813 */
1814 bool output_details;
1815
1816 /**
1817 * Determines which smoother to use for the AMG cycle. Possibilities for
1818 * smoother_type are the following:
1819 * <ul>
1820 * <li> "Aztec" </li>
1821 * <li> "IFPACK" </li>
1822 * <li> "Jacobi" </li>
1823 * <li> "ML symmetric Gauss-Seidel" </li>
1824 * <li> "symmetric Gauss-Seidel" </li>
1825 * <li> "ML Gauss-Seidel" </li>
1826 * <li> "Gauss-Seidel" </li>
1827 * <li> "block Gauss-Seidel" </li>
1828 * <li> "symmetric block Gauss-Seidel" </li>
1829 * <li> "Chebyshev" </li>
1830 * <li> "MLS" </li>
1831 * <li> "Hiptmair" </li>
1832 * <li> "Amesos-KLU" </li>
1833 * <li> "Amesos-Superlu" </li>
1834 * <li> "Amesos-UMFPACK" </li>
1835 * <li> "Amesos-Superludist" </li>
1836 * <li> "Amesos-MUMPS" </li>
1837 * <li> "user-defined" </li>
1838 * <li> "SuperLU" </li>
1839 * <li> "IFPACK-Chebyshev" </li>
1840 * <li> "self" </li>
1841 * <li> "do-nothing" </li>
1842 * <li> "IC" </li>
1843 * <li> "ICT" </li>
1844 * <li> "ILU" </li>
1845 * <li> "ILUT" </li>
1846 * <li> "Block Chebyshev" </li>
1847 * <li> "IFPACK-Block Chebyshev" </li>
1848 * </ul>
1849 */
1850 const char *smoother_type;
1851
1852 /**
1853 * Determines which solver to use on the coarsest level. The same
1854 * settings as for the smoother type are possible.
1855 */
1856 const char *coarse_type;
1857 };
1858
1859 /**
1860 * Constructor.
1861 */
1862 PreconditionAMGMueLu();
1863
1864 /**
1865 * Destructor.
1866 */
1867 virtual ~PreconditionAMGMueLu() override = default;
1868
1869 /**
1870 * Let Trilinos compute a multilevel hierarchy for the solution of a
1871 * linear system with the given matrix. The function uses the matrix
1872 * format specified in TrilinosWrappers::SparseMatrix.
1873 */
1874 void
1875 initialize(const SparseMatrix &matrix,
1876 const AdditionalData &additional_data = AdditionalData());
1877
1878 /**
1879 * Let Trilinos compute a multilevel hierarchy for the solution of a
1880 * linear system with the given matrix. As opposed to the other initialize
1881 * function above, this function uses an object of type
1882 * Epetra_CrsMatrix.
1883 */
1884 void
1885 initialize(const Epetra_CrsMatrix &matrix,
1886 const AdditionalData &additional_data = AdditionalData());
1887
1888 /**
1889 * Let Trilinos compute a multilevel hierarchy for the solution of a
1890 * linear system with the given matrix. The function uses the matrix
1891 * format specified in TrilinosWrappers::SparseMatrix.
1892 *
1893 * This function is similar to the one above, but allows the user
1894 * to set most of the options of the Trilinos ML
1895 * preconditioner. In order to find out about all the options for
1896 * ML, we refer to the <a
1897 * href="https://trilinos.org/docs/dev/packages/ml/doc/html/index.html">ML
1898 * documentation page</a>. Not all ML options have a corresponding
1899 * MueLu option.
1900 */
1901 void
1902 initialize(const SparseMatrix &matrix,
1903 Teuchos::ParameterList &muelu_parameters);
1904
1905 /**
1906 * Let Trilinos compute a multilevel hierarchy for the solution of a
1907 * linear system with the given matrix. As opposed to the other initialize
1908 * function above, this function uses an object of type Epetra_CrsMatrix.
1909 */
1910 void
1911 initialize(const Epetra_CrsMatrix &matrix,
1912 Teuchos::ParameterList &muelu_parameters);
1913
1914 /**
1915 * Let Trilinos compute a multilevel hierarchy for the solution of a
1916 * linear system with the given matrix. This function takes a deal.II
1917 * matrix and copies the content into a Trilinos matrix, so the function
1918 * can be considered rather inefficient.
1919 */
1920 template <typename number>
1921 void
1922 initialize(const ::dealii::SparseMatrix<number> &deal_ii_sparse_matrix,
1923 const AdditionalData &additional_data = AdditionalData(),
1924 const double drop_tolerance = 1e-13,
1925 const ::dealii::SparsityPattern *use_this_sparsity = nullptr);
1926
1927 /**
1928 * Destroys the preconditioner, leaving an object like just after having
1929 * called the constructor.
1930 */
1931 void
1932 clear();
1933
1934 /**
1935 * Prints an estimate of the memory consumption of this class.
1936 */
1937 size_type
1938 memory_consumption() const;
1939
1940 private:
1941 /**
1942 * A copy of the deal.II matrix into Trilinos format.
1943 */
1944 std::shared_ptr<SparseMatrix> trilinos_matrix;
1945 };
1946 # endif
1947
1948
1949
1950 /**
1951 * A wrapper class for an identity preconditioner for Trilinos matrices.
1952 *
1953 * @ingroup TrilinosWrappers
1954 * @ingroup Preconditioners
1955 */
1956 class PreconditionIdentity : public PreconditionBase
1957 {
1958 public:
1959 /**
1960 * This function is only present to provide the interface of a
1961 * preconditioner to be handed to a smoother. This does nothing.
1962 */
1963 struct AdditionalData
1964 {};
1965
1966 /**
1967 * The matrix argument is ignored and here just for compatibility with more
1968 * complex preconditioners.
1969 * @note This function must be called when this preconditioner is to be
1970 * wrapped in a LinearOperator without an exemplar materix.
1971 */
1972 void
1973 initialize(const SparseMatrix &matrix,
1974 const AdditionalData &additional_data = AdditionalData());
1975
1976 /**
1977 * Apply the preconditioner, i.e., dst = src.
1978 */
1979 void
1980 vmult(MPI::Vector &dst, const MPI::Vector &src) const override;
1981
1982 /**
1983 * Apply the transport conditioner, i.e., dst = src.
1984 */
1985 void
1986 Tvmult(MPI::Vector &dst, const MPI::Vector &src) const override;
1987
1988 /**
1989 * Apply the preconditioner on deal.II data structures instead of the ones
1990 * provided in the Trilinos wrapper class, i.e., dst = src.
1991 */
1992 void
1993 vmult(dealii::Vector<double> &dst,
1994 const dealii::Vector<double> &src) const override;
1995
1996 /**
1997 * Apply the transpose preconditioner on deal.II data structures instead
1998 * of the ones provided in the Trilinos wrapper class, i.e. dst = src.
1999 */
2000 void
2001 Tvmult(dealii::Vector<double> &dst,
2002 const dealii::Vector<double> &src) const override;
2003
2004 /**
2005 * Apply the preconditioner on deal.II parallel data structures instead of
2006 * the ones provided in the Trilinos wrapper class, i.e., dst = src.
2007 */
2008 void
2009 vmult(LinearAlgebra::distributed::Vector<double> &dst,
2010 const dealii::LinearAlgebra::distributed::Vector<double> &src)
2011 const override;
2012
2013 /**
2014 * Apply the transpose preconditioner on deal.II parallel data structures
2015 * instead of the ones provided in the Trilinos wrapper class, i.e., dst =
2016 * src.
2017 */
2018 void
2019 Tvmult(LinearAlgebra::distributed::Vector<double> &dst,
2020 const dealii::LinearAlgebra::distributed::Vector<double> &src)
2021 const override;
2022 };
2023
2024
2025
2026 // ----------------------- inline and template functions --------------------
2027
2028
2029 # ifndef DOXYGEN
2030
2031
2032 inline void
2033 PreconditionBase::transpose()
2034 {
2035 // This only flips a flag that tells
2036 // Trilinos that any vmult operation
2037 // should be done with the
2038 // transpose. However, the matrix
2039 // structure is not reset.
2040 int ierr;
2041
2042 if (!preconditioner->UseTranspose())
2043 {
2044 ierr = preconditioner->SetUseTranspose(true);
2045 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2046 }
2047 else
2048 {
2049 ierr = preconditioner->SetUseTranspose(false);
2050 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2051 }
2052 }
2053
2054
2055 inline void
2056 PreconditionBase::vmult(MPI::Vector &dst, const MPI::Vector &src) const
2057 {
2058 Assert(dst.trilinos_partitioner().SameAs(
2059 preconditioner->OperatorRangeMap()),
2060 ExcNonMatchingMaps("dst"));
2061 Assert(src.trilinos_partitioner().SameAs(
2062 preconditioner->OperatorDomainMap()),
2063 ExcNonMatchingMaps("src"));
2064
2065 const int ierr = preconditioner->ApplyInverse(src.trilinos_vector(),
2066 dst.trilinos_vector());
2067 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2068 }
2069
2070 inline void
2071 PreconditionBase::Tvmult(MPI::Vector &dst, const MPI::Vector &src) const
2072 {
2073 Assert(dst.trilinos_partitioner().SameAs(
2074 preconditioner->OperatorRangeMap()),
2075 ExcNonMatchingMaps("dst"));
2076 Assert(src.trilinos_partitioner().SameAs(
2077 preconditioner->OperatorDomainMap()),
2078 ExcNonMatchingMaps("src"));
2079
2080 preconditioner->SetUseTranspose(true);
2081 const int ierr = preconditioner->ApplyInverse(src.trilinos_vector(),
2082 dst.trilinos_vector());
2083 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2084 preconditioner->SetUseTranspose(false);
2085 }
2086
2087
2088 // For the implementation of the <code>vmult</code> function with deal.II
2089 // data structures we note that invoking a call of the Trilinos
2090 // preconditioner requires us to use Epetra vectors as well. We do this by
2091 // providing a view, i.e., feed Trilinos with a pointer to the data, so we
2092 // avoid copying the content of the vectors during the iteration (this
2093 // function is only useful when used in serial anyway). In the declaration
2094 // of the right hand side, we need to cast the source vector (that is
2095 // <code>const</code> in all deal.II calls) to non-constant value, as this
2096 // is the way Trilinos wants to have them.
2097 inline void
2098 PreconditionBase::vmult(dealii::Vector<double> &dst,
2099 const dealii::Vector<double> &src) const
2100 {
2101 AssertDimension(dst.size(),
2102 preconditioner->OperatorDomainMap().NumMyElements());
2103 AssertDimension(src.size(),
2104 preconditioner->OperatorRangeMap().NumMyElements());
2105 Epetra_Vector tril_dst(View,
2106 preconditioner->OperatorDomainMap(),
2107 dst.begin());
2108 Epetra_Vector tril_src(View,
2109 preconditioner->OperatorRangeMap(),
2110 const_cast<double *>(src.begin()));
2111
2112 const int ierr = preconditioner->ApplyInverse(tril_src, tril_dst);
2113 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2114 }
2115
2116
2117 inline void
2118 PreconditionBase::Tvmult(dealii::Vector<double> &dst,
2119 const dealii::Vector<double> &src) const
2120 {
2121 AssertDimension(dst.size(),
2122 preconditioner->OperatorDomainMap().NumMyElements());
2123 AssertDimension(src.size(),
2124 preconditioner->OperatorRangeMap().NumMyElements());
2125 Epetra_Vector tril_dst(View,
2126 preconditioner->OperatorDomainMap(),
2127 dst.begin());
2128 Epetra_Vector tril_src(View,
2129 preconditioner->OperatorRangeMap(),
2130 const_cast<double *>(src.begin()));
2131
2132 preconditioner->SetUseTranspose(true);
2133 const int ierr = preconditioner->ApplyInverse(tril_src, tril_dst);
2134 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2135 preconditioner->SetUseTranspose(false);
2136 }
2137
2138
2139
2140 inline void
2141 PreconditionBase::vmult(
2142 LinearAlgebra::distributed::Vector<double> &dst,
2143 const LinearAlgebra::distributed::Vector<double> &src) const
2144 {
2145 AssertDimension(dst.locally_owned_size(),
2146 preconditioner->OperatorDomainMap().NumMyElements());
2147 AssertDimension(src.locally_owned_size(),
2148 preconditioner->OperatorRangeMap().NumMyElements());
2149 Epetra_Vector tril_dst(View,
2150 preconditioner->OperatorDomainMap(),
2151 dst.begin());
2152 Epetra_Vector tril_src(View,
2153 preconditioner->OperatorRangeMap(),
2154 const_cast<double *>(src.begin()));
2155
2156 const int ierr = preconditioner->ApplyInverse(tril_src, tril_dst);
2157 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2158 }
2159
2160 inline void
2161 PreconditionBase::Tvmult(
2162 LinearAlgebra::distributed::Vector<double> &dst,
2163 const LinearAlgebra::distributed::Vector<double> &src) const
2164 {
2165 AssertDimension(dst.locally_owned_size(),
2166 preconditioner->OperatorDomainMap().NumMyElements());
2167 AssertDimension(src.locally_owned_size(),
2168 preconditioner->OperatorRangeMap().NumMyElements());
2169 Epetra_Vector tril_dst(View,
2170 preconditioner->OperatorDomainMap(),
2171 dst.begin());
2172 Epetra_Vector tril_src(View,
2173 preconditioner->OperatorRangeMap(),
2174 const_cast<double *>(src.begin()));
2175
2176 preconditioner->SetUseTranspose(true);
2177 const int ierr = preconditioner->ApplyInverse(tril_src, tril_dst);
2178 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2179 preconditioner->SetUseTranspose(false);
2180 }
2181
2182 # endif
2183
2184 } // namespace TrilinosWrappers
2185
2186
2187 /** @} */
2188
2189
2190 DEAL_II_NAMESPACE_CLOSE
2191
2192 #else
2193
2194 // Make sure the scripts that create the C++20 module input files have
2195 // something to latch on if the preprocessor #ifdef above would
2196 // otherwise lead to an empty content of the file.
2197 DEAL_II_NAMESPACE_OPEN
2198 DEAL_II_NAMESPACE_CLOSE
2199
2200 #endif // DEAL_II_WITH_TRILINOS
2201
2202 #endif