Debian Codegraph @

include/deal.II/lac/petsc_precondition.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 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_petsc_precondition_h
16 #define dealii_petsc_precondition_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/mpi_stub.h>
23 #include <deal.II/base/point.h>
24
25 #ifdef DEAL_II_WITH_PETSC
26
27 # include <deal.II/lac/exceptions.h>
28
29 # include <petscpc.h>
30
31 # include <functional>
32
33 DEAL_II_NAMESPACE_OPEN
34
35
36
37 namespace PETScWrappers
38 {
39 // forward declarations
40 # ifndef DOXYGEN
41 class MatrixBase;
42 class VectorBase;
43 # endif
44
45 /**
46 * Base class for preconditioner classes using the PETSc functionality. The
47 * classes in this hierarchy don't do a whole lot, except for providing a
48 * function that sets the preconditioner and certain parameters on the
49 * preconditioning context of the solver. These classes are basically here
50 * only to allow a similar interface as already used for the deal.II solver
51 * and preconditioner classes.
52 *
53 * Note that derived classes only provide interfaces to the relevant
54 * functionality of PETSc. PETSc does not implement all preconditioners for
55 * all matrix types. In particular, some preconditioners are not going to
56 * work for parallel jobs, such as for example the ILU preconditioner.
57 *
58 * @ingroup PETScWrappers
59 */
60 class PreconditionBase : public EnableObserverPointer
61 {
62 public:
63 /**
64 * Constructor.
65 */
66 explicit PreconditionBase(const MPI_Comm mpi_communicator);
67
68 /**
69 * Constructor.
70 *
71 */
72 PreconditionBase();
73
74 /**
75 * Destructor.
76 */
77 virtual ~PreconditionBase();
78
79 /**
80 * Destroys the preconditioner, leaving an object like just after having
81 * called the default constructor.
82 */
83 void
84 clear();
85
86 /**
87 * Apply the preconditioner once to the given src vector.
88 */
89 void
90 vmult(VectorBase &dst, const VectorBase &src) const;
91
92 /**
93 * Apply the transpose preconditioner once to the given src vector.
94 */
95 void
96 Tvmult(VectorBase &dst, const VectorBase &src) const;
97
98 /**
99 * Explicitly call setup. This is usually not needed since PETSc will
100 * automatically call the setup function when needed.
101 */
102 void
103 setup();
104
105 /**
106 * Give access to the underlying PETSc object.
107 */
108 const PC &
109 get_pc() const;
110
111 /**
112 * Return the underlying MPI communicator.
113 */
114 MPI_Comm
115 get_mpi_communicator() const;
116
117 protected:
118 /**
119 * The PETSc preconditioner object
120 */
121 PC pc;
122
123 /**
124 * Internal function to create the PETSc preconditioner object. Fails if
125 * called twice.
126 */
127 void
128 create_pc_with_mat(const MatrixBase &);
129
130 /**
131 * Internal function to create the PETSc preconditioner object.
132 */
133 void
134 create_pc_with_comm(const MPI_Comm);
135 };
136
137
138
139 /**
140 * A class that implements the interface to use the PETSc Jacobi
141 * preconditioner.
142 *
143 * See the comment in the base class
144 * @ref PreconditionBase
145 * for when this preconditioner may or may not work.
146 *
147 * @ingroup PETScWrappers
148 */
149 class PreconditionJacobi : public PreconditionBase
150 {
151 public:
152 /**
153 * Standardized data struct to pipe additional flags to the
154 * preconditioner.
155 */
156 struct AdditionalData
157 {};
158
159 /**
160 * Empty Constructor. You need to call initialize() before using this
161 * object.
162 */
163 PreconditionJacobi();
164
165 /**
166 * Constructor. Take the matrix which is used to form the preconditioner,
167 * and additional flags if there are any.
168 */
169 PreconditionJacobi(
170 const MatrixBase &matrix,
171 const AdditionalData &additional_data = AdditionalData());
172
173 /**
174 * Same as above but without setting a matrix to form the preconditioner.
175 * Intended to be used with SLEPc objects.
176 */
177 PreconditionJacobi(
178 const MPI_Comm communicator,
179 const AdditionalData &additional_data = AdditionalData());
180
181 /**
182 * Initialize the preconditioner object and calculate all data that is
183 * necessary for applying it in a solver. This function is automatically
184 * called when calling the constructor with the same arguments and is only
185 * used if you create the preconditioner without arguments.
186 */
187 void
188 initialize(const MatrixBase &matrix,
189 const AdditionalData &additional_data = AdditionalData());
190
191 protected:
192 /**
193 * Store a copy of the flags for this particular preconditioner.
194 */
195 AdditionalData additional_data;
196
197 /**
198 * Initialize the preconditioner object without knowing a particular
199 * matrix. This function sets up appropriate parameters to the underlying
200 * PETSc object after it has been created.
201 */
202 void
203 initialize();
204 };
205
206
207
208 /**
209 * A class that implements the interface to use the PETSc Block Jacobi
210 * preconditioner. PETSc defines the term "block Jacobi" as a preconditioner
211 * in which it looks at a number of diagonal blocks of the matrix and then
212 * defines a preconditioner in which the preconditioner matrix has the same
213 * block structure as only these diagonal blocks, and each diagonal block
214 * of the preconditioner is an approximation of the inverse of the
215 * corresponding block of the original matrix.
216 * The blocking structure of the matrix is determined by the
217 * association of degrees of freedom to the individual processors in an
218 * MPI-parallel job. If you use this preconditioner on a sequential job (or an
219 * MPI job with only one process) then the entire matrix is the only block.
220 *
221 * By default, PETSc uses an ILU(0) decomposition of each diagonal block of
222 * the matrix for preconditioning. This can be changed, as is explained in
223 * the relevant section of the PETSc manual, but is not implemented here.
224 *
225 * See the comment in the base class
226 * @ref PreconditionBase
227 * for when this preconditioner may or may not work.
228 *
229 * @ingroup PETScWrappers
230 */
231 class PreconditionBlockJacobi : public PreconditionBase
232 {
233 public:
234 /**
235 * Standardized data struct to pipe additional flags to the
236 * preconditioner.
237 */
238 struct AdditionalData
239 {};
240
241 /**
242 * Empty Constructor. You need to call initialize() before using this
243 * object.
244 */
245 PreconditionBlockJacobi();
246
247 /**
248 * Constructor. Take the matrix which is used to form the preconditioner,
249 * and additional flags if there are any.
250 */
251 PreconditionBlockJacobi(
252 const MatrixBase &matrix,
253 const AdditionalData &additional_data = AdditionalData());
254
255 /**
256 * Same as above but without setting a matrix to form the preconditioner.
257 * Intended to be used with SLEPc objects.
258 */
259 PreconditionBlockJacobi(
260 const MPI_Comm communicator,
261 const AdditionalData &additional_data = AdditionalData());
262
263
264 /**
265 * Initialize the preconditioner object and calculate all data that is
266 * necessary for applying it in a solver. This function is automatically
267 * called when calling the constructor with the same arguments and is only
268 * used if you create the preconditioner without arguments.
269 */
270 void
271 initialize(const MatrixBase &matrix,
272 const AdditionalData &additional_data = AdditionalData());
273
274 protected:
275 /**
276 * Store a copy of the flags for this particular preconditioner.
277 */
278 AdditionalData additional_data;
279
280 /**
281 * Initialize the preconditioner object without knowing a particular
282 * matrix. This function sets up appropriate parameters to the underlying
283 * PETSc object after it has been created.
284 */
285 void
286 initialize();
287 };
288
289
290
291 /**
292 * A class that implements the interface to use the PETSc SOR
293 * preconditioner.
294 *
295 * @note Only works in serial with a PETScWrappers::SparseMatrix.
296 *
297 * @ingroup PETScWrappers
298 */
299 class PreconditionSOR : public PreconditionBase
300 {
301 public:
302 /**
303 * Standardized data struct to pipe additional flags to the
304 * preconditioner.
305 */
306 struct AdditionalData
307 {
308 /**
309 * Constructor. By default, set the damping parameter to one.
310 */
311 AdditionalData(const double omega = 1);
312
313 /**
314 * Relaxation parameter.
315 */
316 double omega;
317 };
318
319 /**
320 * Empty Constructor. You need to call initialize() before using this
321 * object.
322 */
323 PreconditionSOR();
324
325 /**
326 * Constructor. Take the matrix which is used to form the preconditioner,
327 * and additional flags if there are any.
328 */
329 PreconditionSOR(const MatrixBase &matrix,
330 const AdditionalData &additional_data = AdditionalData());
331
332 /**
333 * Initialize the preconditioner object and calculate all data that is
334 * necessary for applying it in a solver. This function is automatically
335 * called when calling the constructor with the same arguments and is only
336 * used if you create the preconditioner without arguments.
337 */
338 void
339 initialize(const MatrixBase &matrix,
340 const AdditionalData &additional_data = AdditionalData());
341
342 protected:
343 /**
344 * Store a copy of the flags for this particular preconditioner.
345 */
346 AdditionalData additional_data;
347 };
348
349
350
351 /**
352 * A class that implements the interface to use the PETSc SSOR
353 * preconditioner.
354 *
355 * @note Only works in serial with a PETScWrappers::SparseMatrix.
356 *
357 * @ingroup PETScWrappers
358 */
359 class PreconditionSSOR : public PreconditionBase
360 {
361 public:
362 /**
363 * Standardized data struct to pipe additional flags to the
364 * preconditioner.
365 */
366 struct AdditionalData
367 {
368 /**
369 * Constructor. By default, set the damping parameter to one.
370 */
371 explicit AdditionalData(const double omega = 1);
372
373 /**
374 * Relaxation parameter.
375 */
376 double omega;
377 };
378
379 /**
380 * Empty Constructor. You need to call initialize() before using this
381 * object.
382 */
383 PreconditionSSOR();
384
385 /**
386 * Constructor. Take the matrix which is used to form the preconditioner,
387 * and additional flags if there are any.
388 */
389 PreconditionSSOR(const MatrixBase &matrix,
390 const AdditionalData &additional_data = AdditionalData());
391
392 /**
393 * Initialize the preconditioner object and calculate all data that is
394 * necessary for applying it in a solver. This function is automatically
395 * called when calling the constructor with the same arguments and is only
396 * used if you create the preconditioner without arguments.
397 */
398 void
399 initialize(const MatrixBase &matrix,
400 const AdditionalData &additional_data = AdditionalData());
401
402 protected:
403 /**
404 * Store a copy of the flags for this particular preconditioner.
405 */
406 AdditionalData additional_data;
407 };
408
409 /**
410 * A class that implements the interface to use the PETSc Incomplete
411 * Cholesky preconditioner.
412 *
413 * @note Only works in serial with a PETScWrappers::SparseMatrix.
414 *
415 * @ingroup PETScWrappers
416 */
417 class PreconditionICC : public PreconditionBase
418 {
419 public:
420 /**
421 * Standardized data struct to pipe additional flags to the
422 * preconditioner.
423 */
424 struct AdditionalData
425 {
426 /**
427 * Constructor. By default, set the fill-in parameter to zero.
428 */
429 AdditionalData(const unsigned int levels = 0);
430
431 /**
432 * Fill-in parameter.
433 */
434 unsigned int levels;
435 };
436
437 /**
438 * Empty Constructor. You need to call initialize() before using this
439 * object.
440 */
441 PreconditionICC();
442
443 /**
444 * Constructor. Take the matrix which is used to form the preconditioner,
445 * and additional flags if there are any.
446 */
447 PreconditionICC(const MatrixBase &matrix,
448 const AdditionalData &additional_data = AdditionalData());
449
450 /**
451 * Initialize the preconditioner object and calculate all data that is
452 * necessary for applying it in a solver. This function is automatically
453 * called when calling the constructor with the same arguments and is only
454 * used if you create the preconditioner without arguments.
455 */
456 void
457 initialize(const MatrixBase &matrix,
458 const AdditionalData &additional_data = AdditionalData());
459
460 protected:
461 /**
462 * Store a copy of the flags for this particular preconditioner.
463 */
464 AdditionalData additional_data;
465 };
466
467
468
469 /**
470 * A class that implements the interface to use the PETSc ILU
471 * preconditioner.
472 *
473 * @note Only works in serial with a PETScWrappers::SparseMatrix.
474 *
475 * @ingroup PETScWrappers
476 */
477 class PreconditionILU : public PreconditionBase
478 {
479 public:
480 /**
481 * Standardized data struct to pipe additional flags to the
482 * preconditioner.
483 */
484 struct AdditionalData
485 {
486 /**
487 * Constructor. By default, set the fill-in parameter to zero.
488 */
489 AdditionalData(const unsigned int levels = 0);
490
491 /**
492 * Fill-in parameter.
493 */
494 unsigned int levels;
495 };
496
497 /**
498 * Empty Constructor. You need to call initialize() before using this
499 * object.
500 */
501 PreconditionILU();
502
503 /**
504 * Constructor. Take the matrix which is used to form the preconditioner,
505 * and additional flags if there are any.
506 */
507 PreconditionILU(const MatrixBase &matrix,
508 const AdditionalData &additional_data = AdditionalData());
509
510 /**
511 * Initialize the preconditioner object and calculate all data that is
512 * necessary for applying it in a solver. This function is automatically
513 * called when calling the constructor with the same arguments and is only
514 * used if you create the preconditioner without arguments.
515 */
516 void
517 initialize(const MatrixBase &matrix,
518 const AdditionalData &additional_data = AdditionalData());
519
520 protected:
521 /**
522 * Store a copy of the flags for this particular preconditioner.
523 */
524 AdditionalData additional_data;
525 };
526
527
528
529 /**
530 * A class that implements the interface to use the PETSc LU preconditioner
531 * (@p PCLU). Unlike classes like PreconditionILU, this class usually
532 * (depending on the settings) performs an exact factorization of the
533 * matrix, so it is not necessary to wrap it in an iterative solver. This
534 * class is typically used with SolverPreOnly to get a direct
535 * solver. Alternatively, you can use PreconditionBase::vmult() directly.
536 *
537 * @note This is not a parallel preconditioner so it only works in serial
538 * computations with a single processor.
539 *
540 * @ingroup PETScWrappers
541 */
542 class PreconditionLU : public PreconditionBase
543 {
544 public:
545 /**
546 * Standardized data struct to pipe additional flags to the
547 * preconditioner.
548 */
549 struct AdditionalData
550 {
551 /**
552 * Constructor. (Default values taken from function PCCreate_LU of the
553 * PETSc lib.)
554 */
555 AdditionalData(const double pivoting = 1.e-6,
556 const double zero_pivot = 1.e-12,
557 const double damping = 0.0);
558
559 /**
560 * Determines, when Pivoting is done during LU decomposition. 0.0
561 * indicates no pivoting, and 1.0 complete pivoting. Confer PETSc manual
562 * for more details.
563 */
564 double pivoting;
565
566 /**
567 * Size at which smaller pivots are declared to be zero. Confer PETSc
568 * manual for more details.
569 */
570 double zero_pivot;
571
572 /**
573 * This quantity is added to the diagonal of the matrix during
574 * factorization.
575 */
576 double damping;
577 };
578
579 /**
580 * Empty Constructor. You need to call initialize() before using this
581 * object.
582 */
583 PreconditionLU();
584
585 /**
586 * Constructor. Take the matrix which is used to form the preconditioner,
587 * and additional flags if there are any.
588 */
589 PreconditionLU(const MatrixBase &matrix,
590 const AdditionalData &additional_data = AdditionalData());
591
592 /**
593 * Initialize the preconditioner object and calculate all data that is
594 * necessary for applying it in a solver. This function is automatically
595 * called when calling the constructor with the same arguments and is only
596 * used if you create the preconditioner without arguments.
597 */
598 void
599 initialize(const MatrixBase &matrix,
600 const AdditionalData &additional_data = AdditionalData());
601
602 protected:
603 /**
604 * Store a copy of the flags for this particular preconditioner.
605 */
606 AdditionalData additional_data;
607 };
608
609
610
611 /**
612 * A class that implements the interface to use the BoomerAMG algebraic
613 * multigrid preconditioner from the HYPRE suite. Note that PETSc has to be
614 * configured with HYPRE (e.g. with \--download-hypre=1).
615 *
616 * This preconditioner does support parallel distributed computations. See
617 * step-40 for an example.
618 *
619 * This class can be used as a preconditioner for linear solvers. It
620 * also provides a `vmult()` function (implemented in the
621 * PreconditionBase base class) that, when called, performs one
622 * multigrid cycle. By default, this is a V-cycle, but the
623 * AdditionalData class allows to also select a W-cycle.
624 *
625 * @ingroup PETScWrappers
626 */
627 class PreconditionBoomerAMG : public PreconditionBase
628 {
629 public:
630 /**
631 * Standardized data struct to pipe additional flags to the
632 * preconditioner.
633 */
634 struct AdditionalData
635 {
636 /**
637 * Defines the available relaxation types for BoomerAMG.
638 */
639 enum class RelaxationType
640 {
641 Jacobi,
642 sequentialGaussSeidel,
643 seqboundaryGaussSeidel,
644 SORJacobi,
645 backwardSORJacobi,
646 symmetricSORJacobi,
647 l1scaledSORJacobi,
648 GaussianElimination,
649 l1GaussSeidel,
650 backwardl1GaussSeidel,
651 CG,
652 Chebyshev,
653 FCFJacobi,
654 l1scaledJacobi,
655 None
656 };
657
658 /**
659 * Constructor. Note that BoomerAMG offers a lot more options to set
660 * than what is exposed here.
661 */
662 AdditionalData(
663 const bool symmetric_operator = false,
664 const double strong_threshold = 0.25,
665 const double max_row_sum = 0.9,
666 const unsigned int aggressive_coarsening_num_levels = 0,
667 const bool output_details = false,
668 const RelaxationType relaxation_type_up = RelaxationType::SORJacobi,
669 const RelaxationType relaxation_type_down = RelaxationType::SORJacobi,
670 const RelaxationType relaxation_type_coarse =
671 RelaxationType::GaussianElimination,
672 const unsigned int n_sweeps_coarse = 1,
673 const double tol = 0.0,
674 const unsigned int max_iter = 1,
675 const bool w_cycle = false);
676
677 /**
678 * Set this flag to true if you have a symmetric system matrix and you
679 * want to use a solver which assumes a symmetric preconditioner like
680 * CG.
681 */
682 bool symmetric_operator;
683
684 /**
685 * Threshold of when nodes are considered strongly connected. See
686 * HYPRE_BoomerAMGSetStrongThreshold(). Recommended values are 0.25 for
687 * 2d and 0.5 for 3d problems, but it is problem dependent.
688 */
689 double strong_threshold;
690
691 /**
692 * If set to a value smaller than 1.0 then diagonally dominant parts of
693 * the matrix are treated as having no strongly connected nodes. If the
694 * row sum weighted by the diagonal entry is bigger than the given
695 * value, it is considered diagonally dominant. This feature is turned
696 * of by setting the value to 1.0. This is the default as some matrices
697 * can result in having only diagonally dominant entries and thus no
698 * multigrid levels are constructed. The default in BoomerAMG for this
699 * is 0.9. When you try this, check for a reasonable number of levels
700 * created.
701 */
702 double max_row_sum;
703
704 /**
705 * Number of levels of aggressive coarsening. Increasing this value
706 * reduces the construction time and memory requirements but may
707 * decrease effectiveness.
708 */
709 unsigned int aggressive_coarsening_num_levels;
710
711 /**
712 * Setting this flag to true produces debug output from HYPRE, when the
713 * preconditioner is constructed.
714 */
715 bool output_details;
716
717 /**
718 * Choose relaxation type up.
719 */
720 RelaxationType relaxation_type_up;
721
722 /**
723 * Choose relaxation type down.
724 */
725 RelaxationType relaxation_type_down;
726
727 /**
728 * Choose relaxation type coarse.
729 */
730 RelaxationType relaxation_type_coarse;
731
732 /**
733 * Choose number of sweeps on coarse grid.
734 */
735 unsigned int n_sweeps_coarse;
736
737 /**
738 * Choose BommerAMG tolerance.
739 */
740 double tol;
741
742 /**
743 * Choose BommerAMG maximum number of cycles.
744 */
745 unsigned int max_iter;
746
747 /**
748 * Defines whether a w-cycle should be used instead of the standard
749 * setting of a v-cycle.
750 */
751 bool w_cycle;
752 };
753
754 /**
755 * Empty Constructor. You need to call initialize() before using this
756 * object.
757 */
758 PreconditionBoomerAMG();
759
760 /**
761 * Constructor. Take the matrix which is used to form the preconditioner,
762 * and additional flags if there are any.
763 */
764 PreconditionBoomerAMG(
765 const MatrixBase &matrix,
766 const AdditionalData &additional_data = AdditionalData());
767
768 /**
769 * Same as above but without setting a matrix to form the preconditioner.
770 * Intended to be used with SLEPc objects.
771 */
772 PreconditionBoomerAMG(
773 const MPI_Comm communicator,
774 const AdditionalData &additional_data = AdditionalData());
775
776
777 /**
778 * Initialize the preconditioner object and calculate all data that is
779 * necessary for applying it in a solver. This function is automatically
780 * called when calling the constructor with the same arguments and is only
781 * used if you create the preconditioner without arguments.
782 */
783 void
784 initialize(const MatrixBase &matrix,
785 const AdditionalData &additional_data = AdditionalData());
786
787 protected:
788 /**
789 * Store a copy of the flags for this particular preconditioner.
790 */
791 AdditionalData additional_data;
792
793 /**
794 * Initialize the preconditioner object without knowing a particular
795 * matrix. This function sets up appropriate parameters to the underlying
796 * PETSc object after it has been created.
797 */
798 void
799 initialize();
800 };
801
802
803
804 /**
805 * A class that implements the interface to use the ParaSails sparse
806 * approximate inverse preconditioner from the HYPRE suite. Note that PETSc
807 * has to be configured with HYPRE (e.g. with \--download-hypre=1).
808 *
809 * ParaSails uses least-squares minimization to compute a sparse approximate
810 * inverse. The sparsity pattern used is the pattern of a power of a
811 * sparsified matrix. ParaSails also uses a post-filtering technique to
812 * reduce the cost of applying the preconditioner.
813 *
814 * ParaSails solves symmetric positive definite (SPD) problems using a
815 * factorized SPD preconditioner and can also solve general (nonsymmetric
816 * and/or indefinite) problems with a nonfactorized preconditioner. The
817 * problem type has to be set in @p AdditionalData.
818 *
819 * The preconditioner does support parallel distributed computations.
820 *
821 * @ingroup PETScWrappers
822 */
823 class PreconditionParaSails : public PreconditionBase
824 {
825 public:
826 /**
827 * Standardized data struct to pipe additional flags to the
828 * preconditioner.
829 */
830 struct AdditionalData
831 {
832 /**
833 * Constructor.
834 */
835 AdditionalData(const unsigned int symmetric = 1,
836 const unsigned int n_levels = 1,
837 const double threshold = 0.1,
838 const double filter = 0.05,
839 const bool output_details = false);
840
841 /**
842 * This parameter specifies the type of problem to solve:
843 * <ul>
844 * <li> @p 0: nonsymmetric and/or indefinite problem, and nonsymmetric
845 * preconditioner
846 * <li> @p 1: SPD problem, and SPD (factored) preconditioner
847 * <li> @p 2: nonsymmetric, definite problem, and SPD (factored)
848 * preconditioner
849 * </ul>
850 * Default is <tt>symmetric = 1</tt>.
851 */
852 unsigned int symmetric;
853
854 /**
855 * The sparsity pattern used for the approximate inverse is the pattern
856 * of a power <tt>B^m</tt> where <tt>B</tt> has been sparsified from the
857 * given matrix <tt>A</tt>, <tt>n_level</tt> is equal to <tt>m+1</tt>.
858 * Default value is <tt>n_levels = 1</tt>.
859 */
860 unsigned int n_levels;
861
862 /**
863 * Sparsification is performed by dropping nonzeros which are smaller
864 * than <tt>thresh</tt> in magnitude. Lower values of <tt>thresh</tt>
865 * lead to more accurate, but also more expensive preconditioners.
866 * Default value is <tt>thresh = 0.1</tt>. Setting <tt>thresh < 0</tt> a
867 * threshold is selected automatically, such that <tt>-thresh</tt>
868 * represents the fraction of nonzero elements that are dropped. For
869 * example, if <tt>thresh = -0.9</tt>, then <tt>B</tt> will contain
870 * about ten percent of the nonzeros of the given matrix <tt>A</tt>.
871 */
872 double threshold;
873
874 /**
875 * Filtering is a post-processing procedure, <tt>filter</tt> represents
876 * a fraction of nonzero elements that are dropped after creating the
877 * approximate inverse sparsity pattern. Default value is <tt>filter =
878 * 0.05</tt>. Setting <tt>filter < 0</tt> a value is selected
879 * automatically, such that <tt>-filter</tt> represents the fraction of
880 * nonzero elements that are dropped. For example, if <tt>thresh =
881 * -0.9</tt>, then about 90 percent of the entries in the computed
882 * approximate inverse are dropped.
883 */
884 double filter;
885
886 /**
887 * Setting this flag to true produces output from HYPRE, when the
888 * preconditioner is constructed.
889 */
890 bool output_details;
891 };
892
893
894
895 /**
896 * Empty Constructor. You need to call initialize() before using this
897 * object.
898 */
899 PreconditionParaSails();
900
901 /**
902 * Constructor. Take the matrix which is used to form the preconditioner,
903 * and additional flags if there are any.
904 */
905 PreconditionParaSails(
906 const MatrixBase &matrix,
907 const AdditionalData &additional_data = AdditionalData());
908
909 /**
910 * Initialize the preconditioner object and calculate all data that is
911 * necessary for applying it in a solver. This function is automatically
912 * called when calling the constructor with the same arguments and is only
913 * used if you create the preconditioner without arguments.
914 */
915 void
916 initialize(const MatrixBase &matrix,
917 const AdditionalData &additional_data = AdditionalData());
918
919 private:
920 /**
921 * Store a copy of the flags for this particular preconditioner.
922 */
923 AdditionalData additional_data;
924 };
925
926
927
928 /**
929 * A class that implements a non-preconditioned method.
930 *
931 * @ingroup PETScWrappers
932 */
933 class PreconditionNone : public PreconditionBase
934 {
935 public:
936 /**
937 * Standardized data struct to pipe additional flags to the
938 * preconditioner.
939 */
940 struct AdditionalData
941 {};
942
943 /**
944 * Empty Constructor. You need to call initialize() before using this
945 * object.
946 */
947 PreconditionNone();
948
949 /**
950 * Constructor. Take the matrix which is used to form the preconditioner,
951 * and additional flags if there are any. The matrix is completely ignored
952 * in computations.
953 */
954 PreconditionNone(const MatrixBase &matrix,
955 const AdditionalData &additional_data = AdditionalData());
956
957 /**
958 * Initialize the preconditioner object and calculate all data that is
959 * necessary for applying it in a solver. This function is automatically
960 * called when calling the constructor with the same arguments and is only
961 * used if you create the preconditioner without arguments. The matrix is
962 * completely ignored in computations.
963 */
964 void
965 initialize(const MatrixBase &matrix,
966 const AdditionalData &additional_data = AdditionalData());
967
968 private:
969 /**
970 * Store a copy of the flags for this particular preconditioner.
971 */
972 AdditionalData additional_data;
973 };
974
975 /**
976 * A class that implements the interface to use the BDDC preconditioner from
977 * PETSc (<a
978 * href="https://petsc.org/release/docs/manualpages/PC/PCBDDC.html">PCBDDC</a>),
979 * which is a two-level, substructuring, non-overlapping domain decomposition
980 * preconditioner. Details of the implementation can be found in
981 * @cite zampini2016pcbddc. It mainly consists of two elements:
982 *
983 * <ul>
984 * <li> Local solvers: Solvers for each subdomain. These are performed
985 * concurrently by each processor</li>
986 * <li> A coarse solver: Continuity between each subdomain is imposed in a
987 * small number of DoFs, referred to as <em>primal DoFs</em>. This solver
988 * solves such problem.</li>
989 * </ul>
990 *
991 * The size of the primal space is determined through the @p AdditionalData
992 * parameters. A thorough study of the performance of this solver in the
993 * context of cardiac mechanics, together with further details on this
994 * interface, is available in @cite Barnafi2022.
995 *
996 * @ingroup PETScWrappers
997 */
998 template <int dim>
999 class PreconditionBDDC : public PreconditionBase
1000 {
1001 public:
1002 /**
1003 * Standardized data struct to pipe additional flags to the
1004 * preconditioner.
1005 */
1006 struct AdditionalData
1007 {
1008 /**
1009 * Constructor. Note that BDDC offers a lot more options to set
1010 * than what is exposed here.
1011 */
1012 AdditionalData(const bool use_vertices = true,
1013 const bool use_edges = false,
1014 const bool use_faces = false,
1015 const bool symmetric = false,
1016 const std::vector<Point<dim>> coords = {});
1017
1018 /**
1019 * This flag sets the use of degrees of freedom in the vertices of the
1020 * subdomains as primal variables for the creation of the coarse space.
1021 */
1022 bool use_vertices;
1023
1024 /**
1025 * This flag sets the use of degrees of freedom in the edges of the
1026 * subdomain as primal variables for the creation of the coarse space.
1027 * Continuity is actually imposed at the edge average.
1028 */
1029 bool use_edges;
1030
1031 /**
1032 * This flag sets the use of degrees of freedom in the faces of the
1033 * subdomain as primal variables for the creation of the coarse space.
1034 * Continuity is actually imposed at the face average.
1035 */
1036 bool use_faces;
1037
1038 /**
1039 * Set whether the matrix is symmetric or not.
1040 */
1041 bool symmetric;
1042
1043 /**
1044 * Set the location of each DoF. This helps in improving the definition of
1045 * the vertices for unstructured meshes.
1046 */
1047 std::vector<Point<dim>> coords;
1048 };
1049
1050 /**
1051 * Empty Constructor. You need to call initialize() before using this
1052 * object.
1053 */
1054 PreconditionBDDC();
1055
1056 /**
1057 * Constructor. Take the matrix which is used to form the preconditioner,
1058 * and additional flags if there are any.
1059 */
1060 PreconditionBDDC(const MatrixBase &matrix,
1061 const AdditionalData &additional_data = AdditionalData());
1062
1063 /**
1064 * Same as above but without setting a matrix to form the preconditioner.
1065 * Intended to be used with SLEPc objects.
1066 */
1067 PreconditionBDDC(const MPI_Comm communicator,
1068 const AdditionalData &additional_data = AdditionalData());
1069
1070 /**
1071 * Initialize the preconditioner object and calculate all data that is
1072 * necessary for applying it in a solver. This function is automatically
1073 * called when calling the constructor with the same arguments and is only
1074 * used if you create the preconditioner without arguments.
1075 */
1076 void
1077 initialize(const MatrixBase &matrix,
1078 const AdditionalData &additional_data = AdditionalData());
1079
1080 protected:
1081 /**
1082 * Store a copy of the flags for this particular preconditioner.
1083 */
1084 AdditionalData additional_data;
1085
1086 /**
1087 * Initialize the preconditioner object without knowing a particular
1088 * matrix. This function sets up appropriate parameters to the underlying
1089 * PETSc object after it has been created.
1090 */
1091 void
1092 initialize();
1093 };
1094
1095 class PreconditionShell : public PreconditionBase
1096 {
1097 public:
1098 /**
1099 * Empty Constructor. You need to call initialize() before using this
1100 * object.
1101 */
1102 PreconditionShell() = default;
1103
1104 /**
1105 * Constructor. Take the matrix which is used to form the preconditioner.
1106 */
1107 PreconditionShell(const MatrixBase &matrix);
1108
1109 /**
1110 * Same as above but without setting a matrix to form the preconditioner.
1111 */
1112 PreconditionShell(const MPI_Comm communicator);
1113
1114 /**
1115 * The callback for the application of the preconditioner.
1116 *
1117 * @note This variable represents a
1118 * @ref GlossUserProvidedCallBack "user provided callback".
1119 * See there for a description of how to deal with errors and other
1120 * requirements and conventions.
1121 */
1122 std::function<void(VectorBase &dst, const VectorBase &src)> vmult;
1123
1124 /**
1125 * The callback for the transposed application of the preconditioner.
1126 *
1127 * @note This variable represents a
1128 * @ref GlossUserProvidedCallBack "user provided callback".
1129 * See there for a description of how to deal with errors and other
1130 * requirements and conventions.
1131 */
1132 std::function<void(VectorBase &dst, const VectorBase &src)> vmultT;
1133
1134 protected:
1135 /**
1136 * Initialize the preconditioner object without knowing a particular
1137 * matrix. This function sets up the PCSHELL preconditioner
1138 */
1139 void
1140 initialize(const MPI_Comm comm);
1141
1142 /**
1143 * Initialize the preconditioner object with a particular
1144 * matrix. This function sets up the PCSHELL preconditioner
1145 */
1146 void
1147 initialize(const MatrixBase &matrix);
1148
1149 private:
1150 /**
1151 * Callback-function invoked by PCApply
1152 */
1153 static PetscErrorCode
1154 pcapply(PC pc, Vec src, Vec dst);
1155
1156 /**
1157 * Callback-function invoked by PCApplyTranspose
1158 */
1159 static PetscErrorCode
1160 pcapply_transpose(PC pc, Vec src, Vec dst);
1161
1162 /**
1163 * Callback-function invoked by PCSetUp
1164 */
1165 static PetscErrorCode
1166 pcsetup(PC pc);
1167 };
1168 } // namespace PETScWrappers
1169
1170
1171 DEAL_II_NAMESPACE_CLOSE
1172
1173
1174 #else
1175
1176 // Make sure the scripts that create the C++20 module input files have
1177 // something to latch on if the preprocessor #ifdef above would
1178 // otherwise lead to an empty content of the file.
1179 DEAL_II_NAMESPACE_OPEN
1180 DEAL_II_NAMESPACE_CLOSE
1181
1182 #endif // DEAL_II_WITH_PETSC
1183
1184 #endif