Debian Codegraph @

include/deal.II/lac/trilinos_tpetra_precondition.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2024 - 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_tpetra_precondition_h
16 #define dealii_trilinos_tpetra_precondition_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/memory_space.h>
23
24 #include <deal.II/lac/vector.h>
25
26 #ifdef DEAL_II_TRILINOS_WITH_TPETRA
27
28 # include <deal.II/base/enable_observer_pointer.h>
29
30 # include <deal.II/lac/la_parallel_vector.h>
31 # include <deal.II/lac/trilinos_tpetra_sparse_matrix.h>
32
33 # include <Teuchos_BLAS_types.hpp>
34 # include <Teuchos_ConfigDefs.hpp>
35 # include <Teuchos_ParameterList.hpp>
36 # include <Teuchos_RCPDecl.hpp>
37 # include <Tpetra_Operator.hpp>
38
39
40 DEAL_II_NAMESPACE_OPEN
41
42 namespace LinearAlgebra
43 {
44 namespace TpetraWrappers
45 {
46
47 /**
48 * The base class for all preconditioners based on Tpetra sparse matrices.
49 *
50 * @ingroup TpetraWrappers
51 * @ingroup Preconditioners
52 */
53 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
54 class PreconditionBase : public EnableObserverPointer
55 {
56 public:
57 /**
58 * @brief Standardized data struct to pipe additional flags to the
59 * preconditioner.
60 *
61 */
62 struct AdditionalData
63 {};
64
65 /**
66 * @brief Constructor. Does not do anything. The <tt>initialize</tt> function of
67 * the derived classes will have to create the preconditioner from a given
68 * sparse matrix.
69 *
70 */
71 PreconditionBase() = default;
72
73 /**
74 * @brief Destructor.
75 * Destroys the preconditioner, leaving an object like just after having
76 * called the constructor.
77 */
78 void
79 clear();
80
81 /**
82 * @brief Apply the preconditioner.
83 *
84 * @param dst Input vector to apply the preconditioner to
85 * @param src Result vector
86 */
87 virtual void
88 vmult(Vector<Number, MemorySpace> &dst,
89 const Vector<Number, MemorySpace> &src) const;
90
91 /**
92 * @brief Apply the transpose preconditioner
93 *
94 * @param dst Input vector to apply the preconditioner to
95 * @param src Result vector
96 */
97 virtual void
98 Tvmult(Vector<Number, MemorySpace> &dst,
99 const Vector<Number, MemorySpace> &src) const;
100
101 /**
102 * @brief Apply the preconditioner
103 *
104 * @param dst Input vector to apply the preconditioner to
105 * @param src Result vector
106 */
107 virtual void
108 vmult(dealii::Vector<Number> &dst, dealii::Vector<Number> &src) const;
109
110 /**
111 * @brief Apply the transpose preconditioner
112 */
113 virtual void
114 Tvmult(dealii::Vector<Number> &dst, dealii::Vector<Number> &src) const;
115
116 /**
117 * @brief Access to underlying Trilinos data
118 *
119 * Calling this function from an uninitialized object will cause an
120 * exception.
121 */
122 const TpetraTypes::LinearOperator<Number, MemorySpace> &
123 trilinos_operator() const;
124
125 /**
126 * @brief Access to underlying Trilinos data
127 *
128 * Calling this function from an uninitialized object will cause an
129 * exception.
130 */
131 Teuchos::RCP<TpetraTypes::LinearOperator<Number, MemorySpace>>
132 trilinos_rcp() const;
133
134 /**
135 * @name Partitioners
136 */
137 /** @{ */
138
139 /**
140 * Return the partitioning of the domain space of this matrix, i.e., the
141 * partitioning of the vectors this matrix has to be multiplied with.
142 *
143 * @return IndexSet of the domain of this preconditioner
144 */
145 IndexSet
146 locally_owned_domain_indices() const;
147
148 /**
149 * Return the partitioning of the range space of this matrix, i.e., the
150 * partitioning of the vectors that are result from matrix-vector
151 * products.
152 *
153 * @return IndexSet of the range of this preconditioner
154 */
155 IndexSet
156 locally_owned_range_indices() const;
157
158 /** @} */
159
160 /**
161 * @addtogroup Exceptions
162 */
163 /** @{ */
164 /**
165 * The maps of the underlying matrix and one of the vectors
166 * do not match.
167 */
168 DeclException1(
169 ExcNonMatchingMaps,
170 std::string,
171 << "The sparse matrix the preconditioner is based on "
172 << "uses a map that is not compatible to the one in vector " << arg1
173 << ". Check preconditioner and matrix setup.");
174
175 /**
176 * The chosen preconditioner does not support a transposed apply.
177 */
178 DeclExceptionMsg(
179 ExcTransposeNotSupported,
180 "The chosen preconditioner does not support transposing the matrix.");
181 /** @} */
182
183 protected:
184 /**
185 * This is a pointer to the preconditioner object that is used when
186 * applying the preconditioner.
187 */
188 Teuchos::RCP<TpetraTypes::LinearOperator<Number, MemorySpace>>
189 preconditioner;
190
191 /**
192 * @brief The list of preconditioner parameters.
193 *
194 * This structure is Trilinos counterpart to the AdditionalData structures
195 * in deal.II. Therefore any initialize will at some point pass this to
196 * the preconditioner. Most derived classes will handle building this list
197 * based on an AdditionalData object that exposes and defaults the most
198 * sensible parameters. But some classes will also offer full
199 * customization for experienced Trilinos users.
200 *
201 */
202 Teuchos::ParameterList parameter_list;
203 };
204
205
206
207 # ifdef DEAL_II_TRILINOS_WITH_IFPACK2
208 /**
209 * @brief Wrapper class for the IdentitySolver preconditioner of Ifpack2.
210 *
211 * @ingroup TpetraWrappers
212 * @ingroup Preconditioners
213 *
214 * @tparam Number scalar type of the preconditioner
215 * @tparam MemorySpace
216 */
217 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
218 class PreconditionIdentity : public PreconditionBase<Number, MemorySpace>
219 {
220 public:
221 /**
222 * @brief Construct identity preconditioner.
223 *
224 */
225 PreconditionIdentity() = default;
226
227 /**
228 * @brief Initializes the preconditioner for the matrix <tt>A</tt>.
229 *
230 * Note that this only needs the matrix for information on the parallel
231 * distribution of the matrix and will return the original vector on
232 * <tt>vmult</tt> or <tt>Tvmult</tt>.
233 *
234 * @param A Matrix to base the preconditioner on.
235 */
236 void
237 initialize(const SparseMatrix<Number, MemorySpace> &A);
238 };
239
240
241
242 /**
243 * @brief The base class for all Ifpack2 preconditioners which are handled through its Factory.
244 *
245 * @ingroup TpetraWrappers
246 * @ingroup Preconditioners
247 */
248 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
249 class PreconditionIfpackBase : public PreconditionBase<Number, MemorySpace>
250 {
251 public:
252 /**
253 * @brief Constructor.
254 *
255 * This constructor will only save the type name given.
256 * The actual preconditioner has to be constructed through the
257 * initialize method of one of the underlying classes.
258 *
259 * @param preconditioner_type
260 */
261 PreconditionIfpackBase(const std::string &preconditioner_type);
262
263 /**
264 * Initializes the preconditioner for the matrix <tt>A</tt> based on
265 * the <tt>parameter_set</tt>.
266 *
267 */
268 void
269 initialize(const SparseMatrix<Number, MemorySpace> &A);
270
271 /**
272 * The chosen preconditioner is not supported or configured with Ifpack2.
273 */
274 DeclException1(
275 ExcTrilinosIpack2PreconditionerUnsupported,
276 std::string,
277 << "You tried to select the preconditioner type <" << arg1 << ">\n"
278 << "but this preconditioner is not supported by Trilinos/Ifpack22\n"
279 << "due to one of the following reasons:\n"
280 << "* This preconditioner does not exist\n"
281 << "* This preconditioner has a specialized constructor not supported by the Ifpack2 Factory.\n"
282 << "* This preconditioner is not (yet) supported by Trilinos/Ifpack2\n"
283 << "* Trilinos/Ifpack2 was not configured for its use.");
284
285 protected:
286 /**
287 * The set preconditioner type to be handed to
288 * <tt>Ifpack2::Factory::create()</tt>
289 */
290 std::string preconditioner_type;
291 };
292
293
294
295 /**
296 * @brief Wrapper to create custom Ifpack2 preconditioners.
297 *
298 * This general purpose class supports any preconditioner of Ifpack2
299 * that can be constructed through its <tt>Ifpack2::Factory::create()</tt>
300 * function.
301 *
302 * @note This is a class for users familiar with Trilinos.
303 *
304 *
305 * @ingroup TpetraWrappers
306 * @ingroup Preconditioners
307 */
308 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
309 class PreconditionIfpack
310 : public PreconditionIfpackBase<Number, MemorySpace>
311 {
312 public:
313 /**
314 * @brief Construct a new custom Ifpack2 preconditioner.
315 *
316 * The currently tested options for the type are
317 * <ul>
318 * <li> "RELAXATION" </li>
319 * <li> "CHEBYSHEV" </li>
320 * <li> "RILUK" </li>
321 * <li> "ILUT" </li>
322 * <li> "SCHWARZ" </li>
323 * </ul>
324 *
325 * But please refer to the User's Guide of Ifpack2 for more information.
326 *
327 * @param preconditioner_type the type based on Ifpack2 notation
328 */
329 PreconditionIfpack(const std::string &preconditioner_type);
330
331 /**
332 * @brief Set the parameter list for the preconditioner.
333 *
334 * This list will be passed to the Ifpack2 preconditioner during
335 * initialization. For parameter options based on the chosen
336 * preconditioner type see the User's Guide of Ifpack2.
337 *
338 * @param parameter_list
339 */
340 void
341 set_parameter_list(Teuchos::ParameterList &parameter_list);
342 };
343
344
345
346 /**
347 * @brief The classical Jacobi preconditioner within Ifpack2.
348 *
349 * @ingroup TpetraWrappers
350 * @ingroup Preconditioners
351 *
352 */
353 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
354 class PreconditionJacobi
355 : public PreconditionIfpackBase<Number, MemorySpace>
356 {
357 public:
358 /**
359 * @brief The set of additional parameters to tune the preconditioner.
360 *
361 */
362 struct AdditionalData
363 {
364 /**
365 * @brief Constructor.
366 *
367 * Set the parameters to be used in the preconditioner.
368 * The defaults yield a textbook Jacobi preconditioner.
369 *
370 * @param omega The damping factor for the relaxation.
371 * @param fix_diagonal Fix small diagonal entries for the inversion?
372 * @param min_diagonal Threshold for fix_diagonal.
373 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult.
374 */
375 AdditionalData(const double omega = 1.,
376 const bool fix_diagonal = false,
377 const double min_diagonal = 0.,
378 const int n_sweeps = 1);
379
380 /**
381 * @brief Relaxation damping factor.
382 *
383 */
384 double omega;
385 /**
386 * @brief Whether or not to enlarge entries below a threshold
387 *
388 * If the matrix diagonal contains entries close to zero, their
389 * inversion will be close to division by zero. This can be corrected by
390 * setting this value to <tt>true</tt>. This will result in additional
391 * computational work during initialization.
392 */
393 bool fix_diagonal;
394 /**
395 * @brief Threshold below which entries will be fixed.
396 *
397 * If the threshold is zero (default) only entries which are exactly
398 * zero will be replaced will small nonzero values.
399 *
400 */
401 double min_diagonal;
402 /**
403 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
404 *
405 */
406 int n_sweeps;
407 };
408 /**
409 * @brief Constructor.
410 *
411 */
412 PreconditionJacobi();
413
414 /**
415 * @brief Compute the preconditioner based on the given matrix and parameters.
416 *
417 * @param A The matrix to base the preconditioner on.
418 * @param additional_data The set of parameters to tune the preconditioner.
419 */
420 void
421 initialize(const SparseMatrix<Number, MemorySpace> &A,
422 const AdditionalData &additional_data = AdditionalData());
423 };
424
425
426
427 /**
428 * @brief l1 variant of the Jacobi preconditioner.
429 *
430 * This variant adds the l1-Norm of all off-processor entries of a local row
431 * i to its diagonal entry d_ii to improve coupling in MPI-parallel
432 * applications, as described and introduced in @cite BFKY2011.
433 *
434 * @ingroup TpetraWrappers
435 * @ingroup Preconditioners
436 */
437 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
438 class PreconditionL1Jacobi
439 : public PreconditionIfpackBase<Number, MemorySpace>
440 {
441 public:
442 /**
443 * @brief The set of additional parameters to tune the preconditioner.
444 *
445 */
446 struct AdditionalData
447 {
448 /**
449 * @brief Constructor.
450 *
451 * Set the parameters to be used in the preconditioner.
452 * The defaults yield the l1 Jacobi preconditioner specified in the
453 * original publication.
454 *
455 * @param omega The damping factor for the relaxation.
456 * @param fix_diagonal Fix small diagonal entries for the inversion?
457 * @param min_diagonal Threshold for fix_diagonal.
458 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult.
459 */
460 AdditionalData(const double omega = 1.,
461 const bool fix_diagonal = false,
462 const double min_diagonal = 0.,
463 const int n_sweeps = 1);
464
465 /**
466 * @brief Relaxation damping factor.
467 *
468 */
469 double omega;
470 /**
471 * @brief Whether or not to enlarge entries below a threshold
472 *
473 * If the matrix diagonal contains entries close to zero, their
474 * inversion will be close to division by zero. This can be corrected by
475 * setting this value to <tt>true</tt>. This will result in additional
476 * computational work during initialization.
477 */
478 bool fix_diagonal;
479 /**
480 * @brief Threshold below which entries will be fixed.
481 *
482 * If the threshold is zero (default) only entries which are exactly
483 * zero will be replaced will small nonzero values.
484 *
485 */
486 double min_diagonal;
487 /**
488 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
489 *
490 */
491 int n_sweeps;
492 };
493
494 /**
495 * @brief Constructor.
496 *
497 */
498 PreconditionL1Jacobi();
499
500 /**
501 * @brief Compute the preconditioner based on the given matrix and parameters.
502 *
503 * @param A The matrix to base the preconditioner on.
504 * @param additional_data The set of parameters to tune the preconditioner.
505 */
506 void
507 initialize(const SparseMatrix<Number, MemorySpace> &A,
508 const AdditionalData &additional_data = AdditionalData());
509 };
510
511
512
513 /**
514 * @brief l1 variant of the Gauss-Seidel preconditioner.
515 *
516 * This variant adds the l1-Norm of all off-processor entries of a single
517 * row i of the upper triangular part of A to its diagonal entry d_ii to
518 * improve coupling in MPI-parallel applications, , as described and
519 * introduced in @cite BFKY2011.
520 *
521 * @ingroup TpetraWrappers
522 * @ingroup Preconditioners
523 */
524 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
525 class PreconditionL1GaussSeidel
526 : public PreconditionIfpackBase<Number, MemorySpace>
527 {
528 public:
529 /**
530 * @brief The set of additional parameters to tune the preconditioner.
531 *
532 */
533 struct AdditionalData
534 {
535 /**
536 * @brief Constructor.
537 *
538 * Set the parameters to be used in the preconditioner.
539 * The defaults yield the l1 Gauss-Seidel preconditioner specified in
540 * the original publication.
541 *
542 * @param omega The damping factor for the relaxation.
543 * @param eta Threshold parameter for diagonal correction.
544 * @param fix_diagonal Fix small diagonal entries for the inversion?
545 * @param min_diagonal Threshold for fix_diagonal.
546 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult.
547 */
548 AdditionalData(const double omega = 1,
549 const double eta = 1.5,
550 const bool fix_diagonal = false,
551 const double min_diagonal = 0,
552 const int n_sweeps = 1);
553
554 /**
555 * @brief Relaxation damping factor.
556 *
557 */
558 double omega;
559
560 /**
561 * @brief Threshold parameter for diagonal correction.
562 *
563 * The l1 correction for a row i will only be added if it is more than
564 * eta times larger than the original diagonal entry.
565 *
566 */
567 double eta;
568 /**
569 * @brief Whether or not to enlarge entries below a threshold
570 *
571 * If the matrix diagonal contains entries close to zero, their
572 * inversion will be close to division by zero. This can be corrected by
573 * setting this value to <tt>true</tt>. This will result in additional
574 * computational work during initialization.
575 */
576 bool fix_diagonal;
577 /**
578 * @brief Threshold below which entries will be fixed.
579 *
580 * If the threshold is zero (default) only entries which are exactly
581 * zero will be replaced will small nonzero values.
582 *
583 */
584 double min_diagonal;
585 /**
586 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
587 *
588 */
589 int n_sweeps;
590 };
591
592 /**
593 * @brief Constructor.
594 *
595 */
596 PreconditionL1GaussSeidel();
597
598 /**
599 * @brief Compute the preconditioner based on the given matrix and parameters.
600 *
601 * @param A The matrix to base the preconditioner on.
602 * @param additional_data The set of parameters to tune the preconditioner.
603 */
604 void
605 initialize(const SparseMatrix<Number, MemorySpace> &A,
606 const AdditionalData &additional_data = AdditionalData());
607 };
608
609
610
611 /**
612 * @brief The class for the SOR preconditioner within Ifpack2.
613 *
614 * If the code is executed MPI-parallel the individual processors will be
615 * connected with an additive Schwarz method.
616 *
617 * @ingroup TpetraWrappers
618 * @ingroup Preconditioners
619 */
620 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
621 class PreconditionSOR : public PreconditionIfpackBase<Number, MemorySpace>
622 {
623 public:
624 /**
625 * @brief The set of additional parameters to tune the preconditioner.
626 *
627 */
628 struct AdditionalData
629 {
630 /**
631 * @brief Constructor.
632 *
633 * Set the parameters to be used in the preconditioner.
634 * The defaults yield a textbook Jacobi preconditioner.
635 *
636 * @param omega The damping factor for the relaxation.
637 * @param overlap Overlap between processor local matrices.
638 * @param fix_diagonal Fix small diagonal entries for the inversion?
639 * @param min_diagonal Threshold for fix_diagonal.
640 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult.
641 */
642 AdditionalData(const double omega = 1.,
643 const int overlap = 0,
644 const bool fix_diagonal = false,
645 const double min_diagonal = 0.,
646 const int n_sweeps = 1);
647
648 /**
649 * @brief Relaxation damping factor.
650 *
651 */
652 double omega;
653 /**
654 * @brief Overlap between processor local matrices.
655 *
656 * The amount of overlap between the processor local matrix blocks
657 * used in the underlying additive Schwarz method.
658 *
659 * The default will yield a block Jacobi preconditioner with each
660 * processor forming its own local block.
661 */
662 int overlap;
663 /**
664 * @brief Whether or not to enlarge entries below a threshold
665 *
666 * If the matrix diagonal contains entries close to zero, their
667 * inversion will be close to division by zero. This can be corrected by
668 * setting this value to <tt>true</tt>. This will result in additional
669 * computational work during initialization.
670 */
671 bool fix_diagonal;
672 /**
673 * @brief Threshold below which entries will be fixed.
674 *
675 * If the threshold is zero (default) only entries which are exactly
676 * zero will be replaced will small nonzero values.
677 *
678 */
679 double min_diagonal;
680 /**
681 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
682 *
683 */
684 int n_sweeps;
685 };
686
687 /**
688 * @brief Constructor.
689 *
690 */
691 PreconditionSOR();
692
693 /**
694 * @brief Compute the preconditioner based on the given matrix and parameters.
695 *
696 * @param A The matrix to base the preconditioner on.
697 * @param additional_data The set of parameters to tune the preconditioner.
698 */
699 void
700 initialize(const SparseMatrix<Number, MemorySpace> &A,
701 const AdditionalData &additional_data = AdditionalData());
702 };
703
704
705
706 /**
707 * The class for the classical SSOR preconditioner within Ifpack2.
708 *
709 * @ingroup TpetraWrappers
710 * @ingroup Preconditioners
711 */
712 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
713 class PreconditionSSOR : public PreconditionIfpackBase<Number, MemorySpace>
714 {
715 public:
716 /**
717 * @brief The set of additional parameters to tune the preconditioner.
718 *
719 */
720 struct AdditionalData
721 {
722 /**
723 * @brief Constructor.
724 *
725 * Set the parameters to be used in the preconditioner.
726 * The defaults yield a textbook Jacobi preconditioner.
727 *
728 * @param omega The damping factor for the relaxation.
729 * @param overlap Overlap between processor local matrices.
730 * @param fix_diagonal Fix small diagonal entries for the inversion?
731 * @param min_diagonal Threshold for fix_diagonal.
732 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult.
733 */
734 AdditionalData(const double omega = 1.,
735 const int overlap = 0,
736 const bool fix_diagonal = false,
737 const double min_diagonal = 0.,
738 const int n_sweeps = 1);
739
740 /**
741 * @brief Relaxation damping factor.
742 *
743 */
744 double omega;
745 /**
746 * @brief Overlap between processor local matrices.
747 *
748 * The amount of overlap between the processor local matrix blocks
749 * used in the underlying additive Schwarz method.
750 *
751 * The default will yield a block Jacobi preconditioner with each
752 * processor forming its own local block.
753 */
754 int overlap;
755 /**
756 * @brief Whether or not to enlarge entries below a threshold
757 *
758 * If the matrix diagonal contains entries close to zero, their
759 * inversion will be close to division by zero. This can be corrected by
760 * setting this value to <tt>true</tt>. This will result in additional
761 * computational work during initialization.
762 */
763 bool fix_diagonal;
764 /**
765 * @brief Threshold below which entries will be fixed.
766 *
767 * If the threshold is zero (default) only entries which are exactly
768 * zero will be replaced will small nonzero values.
769 *
770 */
771 double min_diagonal;
772 /**
773 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
774 *
775 */
776 int n_sweeps;
777 };
778
779
780 /**
781 * @brief Constructor.
782 *
783 */
784 PreconditionSSOR();
785
786 /**
787 * @brief Compute the preconditioner based on the given matrix and parameters.
788 *
789 * @param A The matrix to base the preconditioner on.
790 * @param additional_data The set of parameters to tune the preconditioner.
791 */
792 void
793 initialize(const SparseMatrix<Number, MemorySpace> &A,
794 const AdditionalData &additional_data = AdditionalData());
795 };
796
797
798
799 /**
800 * The class for the Chebyshev preconditioner within Ifpack2.
801 *
802 * @ingroup TpetraWrappers
803 * @ingroup Preconditioners
804 */
805 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
806 class PreconditionChebyshev
807 : public PreconditionIfpackBase<Number, MemorySpace>
808 {
809 public:
810 /**
811 * @brief The set of additional parameters to tune the preconditioner.
812 *
813 */
814 struct AdditionalData
815 {
816 /**
817 * @brief Constructor.
818 *
819 * @param degree Degree of the Chebyshev polynomial.
820 * @param max_eigenvalue Upper bound for the maximum eigenvalue of the matrix.
821 * @param min_eigenvalue Lower bound for the minimum eigenvalue of the matrix.
822 * @param eigenvalue_ratio Ratio between maximum and minimum eigenvalue.
823 * @param min_diagonal Threshold for increasing diagonal entries.
824 * @param nonzero_starting Do not zero starting entries of solution.
825 */
826 AdditionalData(const int degree = 1,
827 const double max_eigenvalue = 10.,
828 const double min_eigenvalue = 1.,
829 const double eigenvalue_ratio = 30.,
830 const double min_diagonal = 1e-12,
831 const bool nonzero_starting = false);
832 /**
833 * @brief Degree of the Chebyshev polynomial.
834 *
835 * The degree directly corresponds to the number of matrix-vector
836 * products that have to be performed during a single application of the
837 * vmult() and Tvmult() operations.
838 *
839 */
840 int degree;
841 /*
842 * @brief Upper bound for the maximum eigenvalue of the matrix.
843 *
844 * This needs to be set properly for the appropriate performance of this
845 * preconditioner.
846 */
847 double max_eigenvalue;
848 /*
849 * @brief Lower bound for the minimum eigenvalue of the matrix.
850 *
851 */
852 double min_eigenvalue;
853 /**
854 * @brief Estimated ratio between maximum and minimum eigenvalue.
855 *
856 */
857 double eigenvalue_ratio;
858 /**
859 * @brief Threshold below which entries will be fixed.
860 *
861 * If the threshold is zero (default) only entries which are exactly
862 * zero will be replaced will small nonzero values.
863 *
864 */
865 double min_diagonal;
866 /**
867 * @brief Do not zero starting entries of solution vector.
868 *
869 * The default (false) zeroes out the entries of dst during vmult() and
870 * Tvmult() which is the recommended setting.
871 *
872 * However, in some situations (e.g. high-frequency error smoothing) it
873 * can be useful to append previous data to the Chebyshev corrections.
874 * The user should really know what they are doing when setting this
875 * flag to true.
876 *
877 */
878 bool nonzero_starting;
879 };
880
881 /**
882 * @brief Constructor.
883 *
884 */
885 PreconditionChebyshev();
886
887 /**
888 * @brief Compute the preconditioner based on the given matrix and parameters.
889 *
890 * @param A The matrix to base the preconditioner on.
891 * @param additional_data The set of parameters to tune the preconditioner.
892 */
893 void
894 initialize(const SparseMatrix<Number, MemorySpace> &A,
895 const AdditionalData &additional_data = AdditionalData());
896 };
897
898
899
900 /**
901 * @brief The ILU/ILU(K)/RILU(K) preconditioner.
902 *
903 * The class for the modified incomplete LU factorization preconditioner
904 * RILUK within Ifpack2. This preconditioner works both in serial and
905 * parallel, depending on the matrix it is based on.
906 *
907 * In general, an incomplete factorization only has values on the sparsity
908 * pattern of the matrix, but one can gradually increase <tt>ilu_fill</tt>
909 * to eventually obtain a full LU factorization.
910 *
911 * For parallel applications this preconditioner implements an additive
912 * Schwarz preconditioner with RILUK as local smoothing on each processor.
913 *
914 * @ingroup TpetraWrappers
915 * @ingroup Preconditioners
916 */
917 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
918 class PreconditionILU : public PreconditionIfpackBase<Number, MemorySpace>
919 {
920 public:
921 /**
922 * @brief The set of additional parameters to tune the preconditioner.
923 *
924 */
925 struct AdditionalData
926 {
927 /**
928 * @brief Constructor.
929 *
930 * Before factorization each diagonal entry will be modified by the
931 * following formula \f[a_{ii}^{new} = \alpha\sign(a_{ii})+\beta a_{ii}
932 * \f] with \f[\alpha\f] given by ilu_atol and \f[\beta\f] given by
933 * ilu_rtol.
934 *
935 * @param ilu_fill Amount of additional fill-in.
936 * @param ilu_atol Constant to be to each diagonal entry before factorization.
937 * @param ilu_rtol Factor to scale all diagonal entries by before factorization.
938 * @param overlap Overlap between processor local matrices.
939 */
940 AdditionalData(const int ilu_fill = 0,
941 const double ilu_atol = 0.,
942 const double ilu_rtol = 1.,
943 const int overlap = 0);
944
945 /**
946 * @brief Amount of additional fill-in.
947 *
948 * Level-of-fill to increase the sparsity pattern of the preconditioner.
949 * A large enough value will result in a complete LU factorization.
950 *
951 */
952 int ilu_fill;
953 /**
954 * @brief Constant to be added to each diagonal entry before factorization.
955 *
956 */
957 double ilu_atol;
958 /**
959 * @brief Factor to scale all diagonal entries by before factorization.
960 *
961 */
962 double ilu_rtol;
963 /**
964 * @brief Overlap between processor local matrices.
965 *
966 * The amount of overlap between the processor local matrix blocks
967 * used in the underlying additive Schwarz method.
968 *
969 * The default will yield a block Jacobi preconditioner with each
970 * processor forming its own local block.
971 */
972 int overlap;
973 };
974
975 /**
976 * @brief Constructor.
977 *
978 */
979 PreconditionILU();
980
981 /**
982 * @brief Compute the preconditioner based on the given matrix and parameters.
983 *
984 * @param A The matrix to base the preconditioner on.
985 * @param additional_data The set of parameters to tune the preconditioner.
986 */
987 void
988 initialize(const SparseMatrix<Number, MemorySpace> &A,
989 const AdditionalData &additional_data = AdditionalData());
990 };
991
992
993
994 /**
995 * The class for the thresholded incomplete LU (ILUT) preconditioner within
996 * Ifpack2.
997 *
998 * @ingroup TpetraWrappers
999 * @ingroup Preconditioners
1000 */
1001 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
1002 class PreconditionILUT : public PreconditionIfpackBase<Number, MemorySpace>
1003 {
1004 public:
1005 /**
1006 * @brief The set of additional parameters to tune the preconditioner.
1007 *
1008 */
1009 struct AdditionalData
1010 {
1011 /**
1012 * @brief Constructor.
1013 *
1014 * Before factorization each diagonal entry will be modified by the
1015 * following formula \f[a_{ii}^{new} = \alpha\sign(a_{ii})+\beta a_{ii}
1016 * \f] with \f[\alpha\f] given by ilut_atol and \f[\beta\f] given by
1017 * ilut_rtol.
1018 *
1019 * @param ilut_drop Threshold for dropping entries.
1020 * @param ilut_fill Amount of additional fill-in.
1021 * @param ilut_atol Constant to be to each diagonal entry before factorization.
1022 * @param ilut_rtol Factor to scale all diagonal entries by before factorization.
1023 * @param overlap Overlap between processor local matrices.
1024 */
1025 AdditionalData(const double ilut_drop = 0.,
1026 const double ilut_fill = 0.,
1027 const double ilut_atol = 0.,
1028 const double ilut_rtol = 1.,
1029 const int overlap = 0);
1030
1031 /**
1032 * @brief Threshold for dropping entries.
1033 *
1034 * Together with <tt>ilut_fill</tt> this controls the amount of fill-in
1035 * and the actual values to be used or dropped.
1036 */
1037 double ilut_drop;
1038 /**
1039 * @brief Amount of additional fill-in.
1040 *
1041 * Level-of-fill to increase the sparsity pattern of the preconditioner.
1042 * A large enough value will result in a complete LU factorization.
1043 * Note, however, that this will drastically increase the memory
1044 * requirement, especially for 3d simulations.
1045 *
1046 */
1047 double ilut_fill;
1048 /**
1049 * @brief Constant to be added to each diagonal entry before factorization.
1050 *
1051 */
1052 double ilut_atol;
1053 /**
1054 * @brief Factor to scale all diagonal entries by before factorization.
1055 *
1056 */
1057 double ilut_rtol;
1058 /**
1059 * @brief Overlap between processor local matrices.
1060 *
1061 * The amount of overlap between the processor local matrix blocks
1062 * used in the underlying additive Schwarz method.
1063 *
1064 * The default will yield a block Jacobi preconditioner with each
1065 * processor forming its own local block.
1066 */
1067 int overlap;
1068 };
1069
1070
1071
1072 /**
1073 * @brief Constructor.
1074 *
1075 */
1076 PreconditionILUT();
1077
1078 /**
1079 * @brief Compute the preconditioner based on the given matrix and parameters.
1080 *
1081 * @param A The matrix to base the preconditioner on.
1082 * @param additional_data The set of parameters to tune the preconditioner.
1083 */
1084 void
1085 initialize(const SparseMatrix<Number, MemorySpace> &A,
1086 const AdditionalData &additional_data = AdditionalData());
1087 };
1088
1089
1090
1091 /**
1092 * The class for the BlockJacobi preconditioner within Ifpack2.
1093 *
1094 * @note This preconditioner always uses linear partitioning.
1095 * There are other partitioners available that need additional user provided
1096 * data, so we suggest using PreconditionIfpack with a custom
1097 * Teuchos::ParameterList. Details on the parameters can be found in the
1098 * User's Guide of Ifpack2.
1099 *
1100 *
1101 * @ingroup TpetraWrappers
1102 * @ingroup Preconditioners
1103 */
1104 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
1105 class PreconditionBlockJacobi
1106 : public PreconditionIfpackBase<Number, MemorySpace>
1107 {
1108 public:
1109 /**
1110 * @brief The set of additional parameters to tune the preconditioner.
1111 *
1112 */
1113 struct AdditionalData
1114 {
1115 /**
1116 * @brief Constructor.
1117 *
1118 * Set the parameters to be used in the preconditioner.
1119 * The defaults yield a textbook Jacobi preconditioner.
1120 *
1121 * @param n_local_parts The number of blocks per processor.
1122 * @param omega The damping factor for the relaxation.
1123 * @param block_overlap Amount of overlap between blocks
1124 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult
1125 */
1126 AdditionalData(const int n_local_parts = 1,
1127 const double omega = 1.,
1128 const int block_overlap = 0,
1129 const int n_sweeps = 1);
1130
1131 /**
1132 * @brief Number of blocks per processor.
1133 *
1134 * The default of 1 results in a single block per processor
1135 * which corresponds to Preconditioner from PreconditionJacobi
1136 */
1137 int n_local_parts;
1138 /**
1139 * @brief Relaxation damping factor.
1140 *
1141 */
1142 double omega;
1143 /**
1144 * @brief Amount of overlap between blocks
1145 *
1146 */
1147 int block_overlap;
1148 /**
1149 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
1150 *
1151 */
1152 int n_sweeps;
1153 };
1154
1155
1156 /**
1157 * @brief Constructor.
1158 *
1159 */
1160 PreconditionBlockJacobi();
1161
1162 /**
1163 * @brief Compute the preconditioner based on the given matrix and parameters.
1164 *
1165 * @param A The matrix to base the preconditioner on.
1166 * @param additional_data The set of parameters to tune the preconditioner.
1167 */
1168 void
1169 initialize(const SparseMatrix<Number, MemorySpace> &A,
1170 const AdditionalData &additional_data = AdditionalData());
1171 };
1172
1173
1174
1175 /**
1176 * @brief The class for the Block SOR preconditioner within Ifpack2.
1177 *
1178 * If the code is executed MPI-parallel the individual processors will be
1179 * connected with an additive Schwarz method.
1180 *
1181 * @ingroup TpetraWrappers
1182 * @ingroup Preconditioners
1183 */
1184 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
1185 class PreconditionBlockSOR
1186 : public PreconditionIfpackBase<Number, MemorySpace>
1187 {
1188 public:
1189 /**
1190 * @brief The set of additional parameters to tune the preconditioner.
1191 *
1192 */
1193 struct AdditionalData
1194 {
1195 /**
1196 * @brief Constructor.
1197 *
1198 * Set the parameters to be used in the preconditioner.
1199 *
1200 * @param n_local_parts The number of blocks per processor.
1201 * @param omega The damping factor for the relaxation.
1202 * @param overlap Overlap between processors
1203 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult
1204 */
1205 AdditionalData(const int n_local_parts = 1,
1206 const double omega = 1,
1207 const int overlap = 0,
1208 const int n_sweeps = 1);
1209
1210 /**
1211 * @brief Number of blocks per processor.
1212 *
1213 * The default of 1 results in a single block per processor
1214 * which corresponds to Preconditioner from PreconditionJacobi
1215 */
1216 int n_local_parts;
1217 /**
1218 * @brief Relaxation damping factor.
1219 *
1220 */
1221 double omega;
1222 /**
1223 * @brief Overlap between processor local matrices.
1224 *
1225 * The amount of overlap between the processor local matrix blocks
1226 * used in the underlying additive Schwarz method.
1227 *
1228 * The default will yield a block Jacobi preconditioner with each
1229 * processor forming its own local block.
1230 */
1231 int overlap;
1232 /**
1233 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
1234 *
1235 */
1236 int n_sweeps;
1237 };
1238
1239 PreconditionBlockSOR();
1240
1241 void
1242 initialize(const SparseMatrix<Number, MemorySpace> &A,
1243 const AdditionalData &additional_data = AdditionalData());
1244 };
1245
1246
1247
1248 /**
1249 * @brief The class for the Block SSOR preconditioner within Ifpack2.
1250 *
1251 * If the code is executed MPI-parallel the individual processors will be
1252 * connected with an additive Schwarz method.
1253 *
1254 * @ingroup TpetraWrappers
1255 * @ingroup Preconditioners
1256 */
1257 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
1258 class PreconditionBlockSSOR
1259 : public PreconditionIfpackBase<Number, MemorySpace>
1260 {
1261 public:
1262 /**
1263 * @brief The set of additional parameters to tune the preconditioner.
1264 *
1265 */
1266 struct AdditionalData
1267 {
1268 /**
1269 * @brief Constructor.
1270 *
1271 * Set the parameters to be used in the preconditioner.
1272 *
1273 * @param n_local_parts The number of blocks per processor.
1274 * @param omega The damping factor for the relaxation.
1275 * @param overlap Overlap between processors
1276 * @param n_sweeps Number of relaxation sweeps per call to vmult or Tvmult
1277 */
1278 AdditionalData(const int n_local_parts = 1,
1279 const double omega = 1,
1280 const int overlap = 1,
1281 const int n_sweeps = 1);
1282 /**
1283 * @brief Number of blocks per processor.
1284 *
1285 * The default of 1 results in a single block per processor
1286 * which corresponds to Preconditioner from PreconditionJacobi
1287 */
1288 int n_local_parts;
1289 /**
1290 * @brief Relaxation damping factor.
1291 *
1292 */
1293 double omega;
1294 /**
1295 * @brief Overlap between processor local matrices.
1296 *
1297 * The amount of overlap between the processor local matrix blocks
1298 * used in the underlying additive Schwarz method.
1299 *
1300 * The default will yield a block Jacobi preconditioner with each
1301 * processor forming its own local block.
1302 */
1303 int overlap;
1304 /**
1305 * @brief Set how often the preconditioner should be applied during vmult() or Tvmult().
1306 *
1307 */
1308 int n_sweeps;
1309 };
1310
1311 PreconditionBlockSSOR();
1312
1313 void
1314 initialize(const SparseMatrix<Number, MemorySpace> &A,
1315 const AdditionalData &additional_data = AdditionalData());
1316 };
1317 # endif // DEAL_II_TRILINOS_WITH_IFPACK2
1318
1319 } // namespace TpetraWrappers
1320 } // namespace LinearAlgebra
1321
1322
1323 DEAL_II_NAMESPACE_CLOSE
1324
1325 #else
1326
1327 // Make sure the scripts that create the C++20 module input files have
1328 // something to latch on if the preprocessor #ifdef above would
1329 // otherwise lead to an empty content of the file.
1330 DEAL_II_NAMESPACE_OPEN
1331 DEAL_II_NAMESPACE_CLOSE
1332
1333 #endif // DEAL_II_TRILINOS_WITH_TPETRA
1334
1335 #endif