Debian Codegraph @

include/deal.II/lac/petsc_solver.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_solver_h
16 #define dealii_petsc_solver_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_PETSC
22
23 # include <deal.II/base/mpi_stub.h>
24 # include <deal.II/base/observer_pointer.h>
25
26 # include <deal.II/lac/exceptions.h>
27 # include <deal.II/lac/solver_control.h>
28
29 # include <petscksp.h>
30
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 # ifndef DOXYGEN
36 # ifdef DEAL_II_WITH_SLEPC
37 namespace SLEPcWrappers
38 {
39 // forward declarations
40 class TransformationBase;
41 } // namespace SLEPcWrappers
42 # endif
43 # endif
44
45 namespace PETScWrappers
46 {
47 // forward declarations
48 # ifndef DOXYGEN
49 class MatrixBase;
50 class VectorBase;
51 class PreconditionBase;
52 # endif
53
54
55 /**
56 * Base class for solver classes using the PETSc solvers. Since solvers in
57 * PETSc are selected based on flags passed to a generic solver object,
58 * basically all the actual solver calls happen in this class, and derived
59 * classes simply set the right flags to select one solver or another, or to
60 * set certain parameters for individual solvers.
61 *
62 * Optionally, the user can create a solver derived from the SolverBase
63 * class and can set the default arguments necessary to solve the linear
64 * system of equations with SolverControl. These default options can be
65 * overridden by specifying command line arguments of the form @p -ksp_*.
66 * For example, @p -ksp_monitor_true_residual prints out true residual norm
67 * (unpreconditioned) at each iteration and @p -ksp_view provides
68 * information about the linear solver and the preconditioner used in the
69 * current context. The type of the solver can also be changed during
70 * runtime by specifying @p -ksp_type {richardson, cg, gmres, fgmres, ..} to
71 * dynamically test the optimal solver along with a suitable preconditioner
72 * set using @p -pc_type {jacobi, bjacobi, ilu, lu, ..}. There are several
73 * other command line options available to modify the behavior of the PETSc
74 * linear solver and can be obtained from the <a
75 * href="http://www.mcs.anl.gov/petsc">documentation and manual pages</a>.
76 *
77 * @note Command line options relative to convergence tolerances are ignored
78 * when the solver is instantiated with a SolverControl.
79 *
80 * @note Repeated calls to solve() on a solver object with a Preconditioner
81 * must be used with care. The preconditioner is initialized in the first
82 * call to solve() and subsequent calls reuse the solver and preconditioner
83 * object. This is done for performance reasons. The solver and
84 * preconditioner can be reset by calling reset() or by using the command
85 * line option "-ksp_reuse_preconditioner false".
86 *
87 * @ingroup PETScWrappers
88 */
89 class SolverBase
90 {
91 public:
92 /**
93 * Default constructor without SolverControl. The resulting solver will
94 * use PETSc's default convergence testing routines.
95 */
96 SolverBase();
97
98 /**
99 * Constructor with a SolverControl instance.
100 */
101 SolverBase(SolverControl &cn);
102
103 /**
104 * Destructor.
105 */
106 virtual ~SolverBase();
107
108 /**
109 * Solve the linear system <tt>Ax=b</tt>. Depending on the information
110 * provided by derived classes and the object passed as a preconditioner,
111 * one of the linear solvers and preconditioners of PETSc is chosen.
112 * Repeated calls to solve() do not reconstruct the preconditioner for
113 * performance reasons. See class Documentation.
114 */
115 void
116 solve(const MatrixBase &A,
117 VectorBase &x,
118 const VectorBase &b,
119 const PreconditionBase &preconditioner);
120
121 /**
122 * Resets the contained preconditioner and solver object. See class
123 * description for more details.
124 */
125 virtual void
126 reset();
127
128 /**
129 * Sets a prefix name for the solver object. Useful when customizing the
130 * PETSc KSP object with command-line options.
131 */
132 void
133 set_prefix(const std::string &prefix);
134
135 /**
136 * Access to object that controls convergence.
137 */
138 SolverControl &
139 control() const;
140
141 /**
142 * initialize the solver with the preconditioner. This function is
143 * intended for use with SLEPc spectral transformation class.
144 */
145 void
146 initialize(const PreconditionBase &preconditioner);
147
148 /**
149 * Return the PETSc KSP object.
150 */
151 KSP
152 petsc_ksp();
153
154 /**
155 * Conversion operator to gain access to the underlying PETSc type. If you
156 * do this, you cut this class off some information it may need, so this
157 * conversion operator should only be used if you know what you do.
158 */
159 operator KSP() const;
160
161 protected:
162 /**
163 * The PETSc KSP object.
164 */
165 KSP ksp;
166
167 /**
168 * Reference to the object that controls convergence of the iterative
169 * solver. In fact, for these PETSc wrappers, PETSc does so itself, but we
170 * copy the data from this object before starting the solution process,
171 * and copy the data back into it afterwards.
172 */
173 ObserverPointer<SolverControl, SolverBase> solver_control;
174
175 /**
176 * Utility to create the KSP object and attach convergence test.
177 */
178 void
179 initialize_ksp_with_comm(const MPI_Comm comm);
180
181 /**
182 * %Function that takes a Krylov Subspace Solver context object, and sets
183 * the type of solver that is requested by the derived class.
184 */
185 virtual void
186 set_solver_type(KSP &ksp) const;
187
188 /**
189 * Utility to use deal.II convergence testing.
190 *
191 * This call changes the convergence criterion when the instance of the
192 * class has a SolverControl object associated.
193 */
194 void
195 perhaps_set_convergence_test() const;
196
197 /**
198 * Solver prefix name to qualify options specific to the PETSc KSP object
199 * in the current context. Note: A hyphen (-) must NOT be given at the
200 * beginning of the prefix name. The first character of all runtime
201 * options is AUTOMATICALLY the hyphen.
202 */
203 std::string prefix_name;
204
205 private:
206 /**
207 * A function that is used in PETSc as a callback to check on convergence.
208 * It takes the information provided from PETSc and checks it against
209 * deal.II's own SolverControl objects to see if convergence has been
210 * reached.
211 */
212 static PetscErrorCode
213 convergence_test(KSP ksp,
214 const PetscInt iteration,
215 const PetscReal residual_norm,
216 KSPConvergedReason *reason,
217 void *solver_control);
218
219
220 # ifdef DEAL_II_WITH_SLEPC
221 // Make the transformation class a friend, since it needs to set the KSP
222 // solver.
223 friend class SLEPcWrappers::TransformationBase;
224 # endif
225 };
226
227
228
229 /**
230 * An implementation of the solver interface using the PETSc Richardson
231 * solver.
232 *
233 * @ingroup PETScWrappers
234 */
235 class SolverRichardson : public SolverBase
236 {
237 public:
238 /**
239 * Standardized data struct to pipe additional data to the solver.
240 */
241 struct AdditionalData
242 {
243 /**
244 * Constructor. By default, set the damping parameter to one.
245 */
246 explicit AdditionalData(const double omega = 1);
247
248 /**
249 * Relaxation parameter.
250 */
251 double omega;
252 };
253
254 /**
255 * Constructor. In contrast to deal.II's own solvers, there is no need to
256 * give a vector memory object.
257 *
258 * The last argument takes a structure with additional, solver dependent
259 * flags for tuning.
260 */
261 SolverRichardson(SolverControl &cn,
262 const AdditionalData &data = AdditionalData());
263
264 /**
265 * Constructor. This constructor is deprecated and ignores the MPI
266 * communicator argument. Use the other constructor instead.
267 *
268 * @deprecated
269 */
270 DEAL_II_DEPRECATED
271 SolverRichardson(SolverControl &cn,
272 const MPI_Comm mpi_communicator,
273 const AdditionalData &data = AdditionalData());
274
275 protected:
276 /**
277 * Store a copy of the flags for this particular solver.
278 */
279 const AdditionalData additional_data;
280
281 /**
282 * %Function that takes a Krylov Subspace Solver context object, and sets
283 * the type of solver that is appropriate for this class.
284 */
285 virtual void
286 set_solver_type(KSP &ksp) const override;
287 };
288
289
290
291 /**
292 * An implementation of the solver interface using the PETSc Chebyshev (or,
293 * prior version 3.3, Chebychev) solver.
294 *
295 * @ingroup PETScWrappers
296 */
297 class SolverChebychev : public SolverBase
298 {
299 public:
300 /**
301 * Standardized data struct to pipe additional data to the solver.
302 */
303 struct AdditionalData
304 {};
305
306 /**
307 * Constructor. In contrast to deal.II's own solvers, there is no need to
308 * give a vector memory object.
309 *
310 * The last argument takes a structure with additional, solver dependent
311 * flags for tuning.
312 */
313 SolverChebychev(SolverControl &cn,
314 const AdditionalData &data = AdditionalData());
315
316 /**
317 * Constructor. This constructor is deprecated and ignores the MPI
318 * communicator argument. Use the other constructor instead.
319 *
320 * @deprecated
321 */
322 DEAL_II_DEPRECATED
323 SolverChebychev(SolverControl &cn,
324 const MPI_Comm mpi_communicator,
325 const AdditionalData &data = AdditionalData());
326
327 protected:
328 /**
329 * Store a copy of the flags for this particular solver.
330 */
331 const AdditionalData additional_data;
332
333 /**
334 * %Function that takes a Krylov Subspace Solver context object, and sets
335 * the type of solver that is appropriate for this class.
336 */
337 virtual void
338 set_solver_type(KSP &ksp) const override;
339 };
340
341
342
343 /**
344 * An implementation of the solver interface using the PETSc CG solver.
345 *
346 * @ingroup PETScWrappers
347 */
348 class SolverCG : public SolverBase
349 {
350 public:
351 /**
352 * Standardized data struct to pipe additional data to the solver.
353 */
354 struct AdditionalData
355 {};
356
357 /**
358 * Constructor. In contrast to deal.II's own solvers, there is no need to
359 * give a vector memory object.
360 *
361 * The last argument takes a structure with additional, solver dependent
362 * flags for tuning.
363 */
364 SolverCG(SolverControl &cn, const AdditionalData &data = AdditionalData());
365
366 /**
367 * Constructor. This constructor is deprecated and ignores the MPI
368 * communicator argument. Use the other constructor instead.
369 *
370 * @deprecated
371 */
372 DEAL_II_DEPRECATED
373 SolverCG(SolverControl &cn,
374 const MPI_Comm mpi_communicator,
375 const AdditionalData &data = AdditionalData());
376
377 protected:
378 /**
379 * Store a copy of the flags for this particular solver.
380 */
381 const AdditionalData additional_data;
382
383 /**
384 * %Function that takes a Krylov Subspace Solver context object, and sets
385 * the type of solver that is appropriate for this class.
386 */
387 virtual void
388 set_solver_type(KSP &ksp) const override;
389 };
390
391
392
393 /**
394 * An implementation of the solver interface using the PETSc BiCG solver.
395 *
396 * @ingroup PETScWrappers
397 */
398 class SolverBiCG : public SolverBase
399 {
400 public:
401 /**
402 * Standardized data struct to pipe additional data to the solver.
403 */
404 struct AdditionalData
405 {};
406
407 /**
408 * Constructor. In contrast to deal.II's own solvers, there is no need to
409 * give a vector memory object.
410 *
411 * The last argument takes a structure with additional, solver dependent
412 * flags for tuning.
413 */
414 SolverBiCG(SolverControl &cn,
415 const AdditionalData &data = AdditionalData());
416
417 /**
418 * Constructor. This constructor is deprecated and ignores the MPI
419 * communicator argument. Use the other constructor instead.
420 *
421 * @deprecated
422 */
423 DEAL_II_DEPRECATED
424 SolverBiCG(SolverControl &cn,
425 const MPI_Comm mpi_communicator,
426 const AdditionalData &data = AdditionalData());
427
428 protected:
429 /**
430 * Store a copy of the flags for this particular solver.
431 */
432 const AdditionalData additional_data;
433
434 /**
435 * %Function that takes a Krylov Subspace Solver context object, and sets
436 * the type of solver that is appropriate for this class.
437 */
438 virtual void
439 set_solver_type(KSP &ksp) const override;
440 };
441
442
443
444 /**
445 * An implementation of the solver interface using the PETSc GMRES solver.
446 *
447 * @ingroup PETScWrappers
448 */
449 class SolverGMRES : public SolverBase
450 {
451 public:
452 /**
453 * Standardized data struct to pipe additional data to the solver.
454 */
455 struct AdditionalData
456 {
457 /**
458 * Constructor. By default, set the number of temporary vectors to 30,
459 * i.e. do a restart every 30 iterations.
460 */
461 AdditionalData(const unsigned int restart_parameter = 30,
462 const bool right_preconditioning = false);
463
464 /**
465 * Maximum number of tmp vectors.
466 */
467 unsigned int restart_parameter;
468
469 /**
470 * Flag for right preconditioning.
471 */
472 bool right_preconditioning;
473 };
474
475 /**
476 * Constructor. In contrast to deal.II's own solvers, there is no need to
477 * give a vector memory object.
478 *
479 * The last argument takes a structure with additional, solver dependent
480 * flags for tuning.
481 */
482 SolverGMRES(SolverControl &cn,
483 const AdditionalData &data = AdditionalData());
484
485 /**
486 * Constructor. This constructor is deprecated and ignores the MPI
487 * communicator argument. Use the other constructor instead.
488 *
489 * @deprecated
490 */
491 DEAL_II_DEPRECATED
492 SolverGMRES(SolverControl &cn,
493 const MPI_Comm mpi_communicator,
494 const AdditionalData &data = AdditionalData());
495
496 protected:
497 /**
498 * Store a copy of the flags for this particular solver.
499 */
500 const AdditionalData additional_data;
501
502 /**
503 * %Function that takes a Krylov Subspace Solver context object, and sets
504 * the type of solver that is appropriate for this class.
505 */
506 virtual void
507 set_solver_type(KSP &ksp) const override;
508 };
509
510
511
512 /**
513 * An implementation of the solver interface using the PETSc BiCGStab
514 * solver.
515 *
516 * @ingroup PETScWrappers
517 */
518 class SolverBicgstab : public SolverBase
519 {
520 public:
521 /**
522 * Standardized data struct to pipe additional data to the solver.
523 */
524 struct AdditionalData
525 {};
526
527 /**
528 * Constructor. In contrast to deal.II's own solvers, there is no need to
529 * give a vector memory object.
530 *
531 * The last argument takes a structure with additional, solver dependent
532 * flags for tuning.
533 */
534 SolverBicgstab(SolverControl &cn,
535 const AdditionalData &data = AdditionalData());
536
537 /**
538 * Constructor. This constructor is deprecated and ignores the MPI
539 * communicator argument. Use the other constructor instead.
540 *
541 * @deprecated
542 */
543 DEAL_II_DEPRECATED
544 SolverBicgstab(SolverControl &cn,
545 const MPI_Comm mpi_communicator,
546 const AdditionalData &data = AdditionalData());
547
548 protected:
549 /**
550 * Store a copy of the flags for this particular solver.
551 */
552 const AdditionalData additional_data;
553
554 /**
555 * %Function that takes a Krylov Subspace Solver context object, and sets
556 * the type of solver that is appropriate for this class.
557 */
558 virtual void
559 set_solver_type(KSP &ksp) const override;
560 };
561
562
563
564 /**
565 * An implementation of the solver interface using the PETSc CG Squared
566 * solver.
567 *
568 * @ingroup PETScWrappers
569 */
570 class SolverCGS : public SolverBase
571 {
572 public:
573 /**
574 * Standardized data struct to pipe additional data to the solver.
575 */
576 struct AdditionalData
577 {};
578
579 /**
580 * Constructor. In contrast to deal.II's own solvers, there is no need to
581 * give a vector memory object.
582 *
583 * The last argument takes a structure with additional, solver dependent
584 * flags for tuning.
585 */
586 SolverCGS(SolverControl &cn, const AdditionalData &data = AdditionalData());
587
588 /**
589 * Constructor. This constructor is deprecated and ignores the MPI
590 * communicator argument. Use the other constructor instead.
591 *
592 * @deprecated
593 */
594 DEAL_II_DEPRECATED
595 SolverCGS(SolverControl &cn,
596 const MPI_Comm mpi_communicator,
597 const AdditionalData &data = AdditionalData());
598
599 protected:
600 /**
601 * Store a copy of the flags for this particular solver.
602 */
603 const AdditionalData additional_data;
604
605 /**
606 * %Function that takes a Krylov Subspace Solver context object, and sets
607 * the type of solver that is appropriate for this class.
608 */
609 virtual void
610 set_solver_type(KSP &ksp) const override;
611 };
612
613
614
615 /**
616 * An implementation of the solver interface using the PETSc TFQMR solver.
617 *
618 * @ingroup PETScWrappers
619 */
620 class SolverTFQMR : public SolverBase
621 {
622 public:
623 /**
624 * Standardized data struct to pipe additional data to the solver.
625 */
626 struct AdditionalData
627 {};
628
629 /**
630 * Constructor. In contrast to deal.II's own solvers, there is no need to
631 * give a vector memory object.
632 *
633 * The last argument takes a structure with additional, solver dependent
634 * flags for tuning.
635 */
636 SolverTFQMR(SolverControl &cn,
637 const AdditionalData &data = AdditionalData());
638
639 /**
640 * Constructor. This constructor is deprecated and ignores the MPI
641 * communicator argument. Use the other constructor instead.
642 *
643 * @deprecated
644 */
645 DEAL_II_DEPRECATED
646 SolverTFQMR(SolverControl &cn,
647 const MPI_Comm mpi_communicator,
648 const AdditionalData &data = AdditionalData());
649
650 protected:
651 /**
652 * Store a copy of the flags for this particular solver.
653 */
654 const AdditionalData additional_data;
655
656 /**
657 * %Function that takes a Krylov Subspace Solver context object, and sets
658 * the type of solver that is appropriate for this class.
659 */
660 virtual void
661 set_solver_type(KSP &ksp) const override;
662 };
663
664
665
666 /**
667 * An implementation of the solver interface using the PETSc TFQMR-2 solver
668 * (called TCQMR in PETSc). Note that this solver had a serious bug in
669 * versions up to and including PETSc 2.1.6, in that it did not check
670 * convergence and always returned an error code. Thus, this class will
671 * abort with an error indicating failure to converge with PETSc 2.1.6 and
672 * prior. This should be fixed in later versions of PETSc, though.
673 *
674 * @ingroup PETScWrappers
675 */
676 class SolverTCQMR : public SolverBase
677 {
678 public:
679 /**
680 * Standardized data struct to pipe additional data to the solver.
681 */
682 struct AdditionalData
683 {};
684
685 /**
686 * Constructor. In contrast to deal.II's own solvers, there is no need to
687 * give a vector memory object.
688 *
689 * The last argument takes a structure with additional, solver dependent
690 * flags for tuning.
691 */
692 SolverTCQMR(SolverControl &cn,
693 const AdditionalData &data = AdditionalData());
694
695 /**
696 * Constructor. This constructor is deprecated and ignores the MPI
697 * communicator argument. Use the other constructor instead.
698 *
699 * @deprecated
700 */
701 DEAL_II_DEPRECATED
702 SolverTCQMR(SolverControl &cn,
703 const MPI_Comm mpi_communicator,
704 const AdditionalData &data = AdditionalData());
705
706 protected:
707 /**
708 * Store a copy of the flags for this particular solver.
709 */
710 const AdditionalData additional_data;
711
712 /**
713 * %Function that takes a Krylov Subspace Solver context object, and sets
714 * the type of solver that is appropriate for this class.
715 */
716 virtual void
717 set_solver_type(KSP &ksp) const override;
718 };
719
720
721
722 /**
723 * An implementation of the solver interface using the PETSc CR solver.
724 *
725 * @ingroup PETScWrappers
726 */
727 class SolverCR : public SolverBase
728 {
729 public:
730 /**
731 * Standardized data struct to pipe additional data to the solver.
732 */
733 struct AdditionalData
734 {};
735
736 /**
737 * Constructor. In contrast to deal.II's own solvers, there is no need to
738 * give a vector memory object.
739 *
740 * The last argument takes a structure with additional, solver dependent
741 * flags for tuning.
742 */
743 SolverCR(SolverControl &cn, const AdditionalData &data = AdditionalData());
744
745 /**
746 * Constructor. This constructor is deprecated and ignores the MPI
747 * communicator argument. Use the other constructor instead.
748 *
749 * @deprecated
750 */
751 DEAL_II_DEPRECATED
752 SolverCR(SolverControl &cn,
753 const MPI_Comm mpi_communicator,
754 const AdditionalData &data = AdditionalData());
755
756 protected:
757 /**
758 * Store a copy of the flags for this particular solver.
759 */
760 const AdditionalData additional_data;
761
762 /**
763 * %Function that takes a Krylov Subspace Solver context object, and sets
764 * the type of solver that is appropriate for this class.
765 */
766 virtual void
767 set_solver_type(KSP &ksp) const override;
768 };
769
770
771
772 /**
773 * An implementation of the solver interface using the PETSc Least Squares
774 * solver.
775 *
776 * @ingroup PETScWrappers
777 */
778 class SolverLSQR : public SolverBase
779 {
780 public:
781 /**
782 * Standardized data struct to pipe additional data to the solver.
783 */
784 struct AdditionalData
785 {};
786
787 /**
788 * Constructor. In contrast to deal.II's own solvers, there is no need to
789 * give a vector memory object.
790 *
791 * The last argument takes a structure with additional, solver dependent
792 * flags for tuning.
793 */
794 SolverLSQR(SolverControl &cn,
795 const AdditionalData &data = AdditionalData());
796
797 /**
798 * Constructor. This constructor is deprecated and ignores the MPI
799 * communicator argument. Use the other constructor instead.
800 *
801 * @deprecated
802 */
803 DEAL_II_DEPRECATED
804 SolverLSQR(SolverControl &cn,
805 const MPI_Comm mpi_communicator,
806 const AdditionalData &data = AdditionalData());
807
808 protected:
809 /**
810 * Store a copy of the flags for this particular solver.
811 */
812 const AdditionalData additional_data;
813
814 /**
815 * %Function that takes a Krylov Subspace Solver context object, and sets
816 * the type of solver that is appropriate for this class.
817 */
818 virtual void
819 set_solver_type(KSP &ksp) const override;
820 };
821
822
823 /**
824 * An implementation of the solver interface using the PETSc PREONLY solver.
825 * Actually this is NOT a real solution algorithm. solve() only applies the
826 * preconditioner once and returns immediately. Its only purpose is to
827 * provide a solver object, when the preconditioner should be used as a real
828 * solver. It is very useful in conjunction with the complete LU
829 * decomposition preconditioner <tt> PreconditionLU </tt>, which in
830 * conjunction with this solver class becomes a direct solver.
831 *
832 * @ingroup PETScWrappers
833 */
834 class SolverPreOnly : public SolverBase
835 {
836 public:
837 /**
838 * Standardized data struct to pipe additional data to the solver.
839 */
840 struct AdditionalData
841 {};
842
843 /**
844 * Constructor. In contrast to deal.II's own solvers, there is no need to
845 * give a vector memory object.
846 *
847 * The last argument takes a structure with additional, solver dependent
848 * flags for tuning.
849 */
850 SolverPreOnly(SolverControl &cn,
851 const AdditionalData &data = AdditionalData());
852
853 /**
854 * Constructor. This constructor is deprecated and ignores the MPI
855 * communicator argument. Use the other constructor instead.
856 *
857 * @deprecated
858 */
859 DEAL_II_DEPRECATED
860 SolverPreOnly(SolverControl &cn,
861 const MPI_Comm mpi_communicator,
862 const AdditionalData &data = AdditionalData());
863
864 protected:
865 /**
866 * Store a copy of the flags for this particular solver.
867 */
868 const AdditionalData additional_data;
869
870 /**
871 * %Function that takes a Krylov Subspace Solver context object, and sets
872 * the type of solver that is appropriate for this class.
873 */
874 virtual void
875 set_solver_type(KSP &ksp) const override;
876 };
877
878 /**
879 * An implementation of the solver interface using the sparse direct MUMPS
880 * solver through PETSc. This class has the usual interface of all other
881 * solver classes but it is of course different in that it doesn't implement
882 * an iterative solver. As a consequence, things like the SolverControl
883 * object have no particular meaning here.
884 *
885 * MUMPS allows to make use of symmetry in this matrix. In this class this
886 * is made possible by the set_symmetric_mode() function. If your matrix is
887 * symmetric, you can use this class as follows:
888 * @code
889 * SolverControl cn;
890 * PETScWrappers::SparseDirectMUMPS solver(cn, mpi_communicator);
891 * solver.set_symmetric_mode(true);
892 * solver.solve(system_matrix, solution, system_rhs);
893 * @endcode
894 *
895 * @note The class internally calls KSPSetFromOptions thus you are able to
896 * use all the PETSc parameters for MATSOLVERMUMPS package. See
897 * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMUMPS.html
898 *
899 * @ingroup PETScWrappers
900 */
901 class SparseDirectMUMPS : public SolverBase
902 {
903 public:
904 /**
905 * Standardized data structure to pipe additional data to the solver.
906 */
907 struct AdditionalData
908 {};
909
910 /**
911 * Constructor.
912 */
913 SparseDirectMUMPS(SolverControl &cn,
914 const AdditionalData &data = AdditionalData());
915
916 /**
917 * Constructor. This constructor is deprecated and ignores the MPI
918 * communicator argument. Use the other constructor instead.
919 *
920 * @deprecated
921 */
922 DEAL_II_DEPRECATED
923 SparseDirectMUMPS(SolverControl &cn,
924 const MPI_Comm mpi_communicator,
925 const AdditionalData &data = AdditionalData());
926
927 /**
928 * The method to solve the linear system.
929 */
930 void
931 solve(const MatrixBase &A, VectorBase &x, const VectorBase &b);
932
933 /**
934 * If called with `true` as argument, tell the direct solver
935 * to assume that the system matrix is symmetric.
936 * It does so by computing the LDL^T decomposition (in effect, a
937 * Cholesky decomposition) instead of more expensive LU decomposition.
938 * The argument indicates whether the matrix can be assumed to be
939 * symmetric or not.
940 *
941 * Note that most finite element matrices are "structurally symmetric",
942 * i.e., the *sparsity pattern* is symmetric, even though the matrix
943 * is not. An example of a matrix that is structurally symmetric
944 * but not symmetric is the matrix you obtain by discretizing the
945 * advection equation $\nabla \cdot (\vec\beta u) = f$ (see, for
946 * example step-12). Because the operator here is not symmetric, the
947 * matrix is not symmetric either; however, if matrix entry $A_{ij}$
948 * is nonzero, then matrix entry $A_{ji}$ is generally not zero either
949 * (and in any case, DoFTools::make_sparsity_pattern() will create a
950 * symmetric sparsity pattern). That said, the current function
951 * is not meant to indicate whether the *sparsity* pattern is symmetric,
952 * but whether the *matrix* itself is symmetric, and this typically
953 * requires that the differential operator you are considering is
954 * symmetric.
955 */
956 void
957 set_symmetric_mode(const bool matrix_is_symmetric);
958
959 protected:
960 /**
961 * Store a copy of flags for this particular solver.
962 */
963 const AdditionalData additional_data;
964
965 virtual void
966 set_solver_type(KSP &ksp) const override;
967
968 /**
969 * Flag specifies whether matrix being factorized is symmetric or not. It
970 * influences the type of the used preconditioner (PCLU or PCCHOLESKY)
971 */
972 bool symmetric_mode;
973 };
974 } // namespace PETScWrappers
975
976 DEAL_II_NAMESPACE_CLOSE
977
978 #else
979
980 // Make sure the scripts that create the C++20 module input files have
981 // something to latch on if the preprocessor #ifdef above would
982 // otherwise lead to an empty content of the file.
983 DEAL_II_NAMESPACE_OPEN
984 DEAL_II_NAMESPACE_CLOSE
985
986 #endif // DEAL_II_WITH_PETSC
987
988 #endif