Debian Codegraph @

include/deal.II/lac/trilinos_solver.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2008 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_trilinos_solver_h
16 #define dealii_trilinos_solver_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_TRILINOS
22
23 # include <deal.II/base/template_constraints.h>
24
25 # include <deal.II/lac/exceptions.h>
26 # include <deal.II/lac/la_parallel_vector.h>
27 # include <deal.II/lac/solver_control.h>
28 # include <deal.II/lac/vector.h>
29
30 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
31
32 // for AztecOO solvers
33 # include <Amesos.h>
34 # include <AztecOO.h>
35 # include <Epetra_LinearProblem.h>
36 # include <Epetra_Operator.h>
37
38 // for Belos solvers
39 # ifdef DEAL_II_TRILINOS_WITH_BELOS
40 # include <BelosBlockCGSolMgr.hpp>
41 # include <BelosBlockGmresSolMgr.hpp>
42 # include <BelosEpetraAdapter.hpp>
43 # include <BelosIteration.hpp>
44 # include <BelosMultiVec.hpp>
45 # include <BelosOperator.hpp>
46 # include <BelosSolverManager.hpp>
47 # endif
48
49 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
50
51
52 # include <memory>
53
54
55 DEAL_II_NAMESPACE_OPEN
56
57 namespace TrilinosWrappers
58 {
59 // forward declarations
60 # ifndef DOXYGEN
61 class SparseMatrix;
62 class PreconditionBase;
63 # endif
64
65
66 /**
67 * Base class for solver classes using the Trilinos solvers. Since solvers
68 * in Trilinos are selected based on flags passed to a generic solver
69 * object, basically all the actual solver calls happen in this class, and
70 * derived classes simply set the right flags to select one solver or
71 * another, or to set certain parameters for individual solvers. For a
72 * general discussion on the Trilinos solver package AztecOO, we refer to
73 * the <a
74 * href="https://trilinos.org/docs/dev/packages/aztecoo/doc/html/index.html">AztecOO
75 * user guide</a>.
76 *
77 * This solver class can also be used as a standalone class, where the
78 * respective Krylov method is set via the flag <tt>solver_name</tt>. This
79 * can be done at runtime (e.g., when parsing the solver from a
80 * ParameterList) and is similar to the deal.II class SolverSelector.
81 *
82 * @ingroup TrilinosWrappers
83 */
84 class SolverBase
85 {
86 public:
87 /**
88 * Enumeration object that is set in the constructor of the derived
89 * classes and tells Trilinos which solver to use. This option can also be
90 * set in the user program, so one might use this base class instead of
91 * one of the specialized derived classes when the solver should be set at
92 * runtime. Currently enabled options are:
93 */
94 enum SolverName
95 {
96 /**
97 * Use the conjugate gradient (CG) algorithm.
98 */
99 cg,
100 /**
101 * Use the conjugate gradient squared (CGS) algorithm.
102 */
103 cgs,
104 /**
105 * Use the generalized minimum residual (GMRES) algorithm.
106 */
107 gmres,
108 /**
109 * Use the biconjugate gradient stabilized (BICGStab) algorithm.
110 */
111 bicgstab,
112 /**
113 * Use the transpose-free quasi-minimal residual (TFQMR) method.
114 */
115 tfqmr
116 } solver_name;
117
118 /**
119 * Standardized data struct to pipe additional data to the solver.
120 */
121
122 struct AdditionalData
123 {
124 /**
125 * Set the additional data field to the desired output format and puts
126 * the restart parameter in case the derived class is GMRES.
127 *
128 * TODO: Find a better way for setting the GMRES restart parameter since
129 * it is quite inelegant to set a specific option of one solver in the
130 * base class for all solvers.
131 */
132 explicit AdditionalData(const bool output_solver_details = false,
133 const unsigned int gmres_restart_parameter = 30);
134
135 /**
136 * Enables/disables the output of solver details (residual in each
137 * iterations etc.).
138 */
139 const bool output_solver_details;
140
141 /**
142 * Restart parameter for GMRES solver.
143 */
144 const unsigned int gmres_restart_parameter;
145 };
146
147 /**
148 * Constructor. Takes the solver control object and creates the solver.
149 */
150 SolverBase(SolverControl &cn,
151 const AdditionalData &data = AdditionalData());
152
153 /**
154 * Second constructor. This constructor takes an enum object that
155 * specifies the solver name and sets the appropriate Krylov method.
156 */
157 SolverBase(const enum SolverName solver_name,
158 SolverControl &cn,
159 const AdditionalData &data = AdditionalData());
160
161 /**
162 * Destructor.
163 */
164 virtual ~SolverBase() = default;
165
166 /**
167 * Solve the linear system <tt>Ax=b</tt>. Depending on the information
168 * provided by derived classes and the object passed as a preconditioner,
169 * one of the linear solvers and preconditioners of Trilinos is chosen.
170 */
171 void
172 solve(const SparseMatrix &A,
173 MPI::Vector &x,
174 const MPI::Vector &b,
175 const PreconditionBase &preconditioner);
176
177 /**
178 * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
179 * This function can be used for matrix free computation. Depending on the
180 * information provided by derived classes and the object passed as a
181 * preconditioner, one of the linear solvers and preconditioners of
182 * Trilinos is chosen.
183 */
184 void
185 solve(const Epetra_Operator &A,
186 MPI::Vector &x,
187 const MPI::Vector &b,
188 const PreconditionBase &preconditioner);
189
190 /**
191 * Solve the linear system <tt>Ax=b</tt> where both <tt>A</tt> and its
192 * @p preconditioner are an operator.
193 * This function can be used when both <tt>A</tt> and the @p preconditioner
194 * are LinearOperators derived from a TrilinosPayload.
195 * Depending on the information provided by derived classes and the object
196 * passed as a preconditioner, one of the linear solvers and preconditioners
197 * of Trilinos is chosen.
198 */
199 void
200 solve(const Epetra_Operator &A,
201 MPI::Vector &x,
202 const MPI::Vector &b,
203 const Epetra_Operator &preconditioner);
204
205 /**
206 * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator,
207 * and the vectors @p x and @p b are native Trilinos vector types.
208 * This function can be used when <tt>A</tt> is a LinearOperators derived
209 * from a TrilinosPayload.
210 * Depending on the information provided by derived classes and the object
211 * passed as a preconditioner, one of the linear solvers and preconditioners
212 * of Trilinos is chosen.
213 */
214 void
215 solve(const Epetra_Operator &A,
216 Epetra_MultiVector &x,
217 const Epetra_MultiVector &b,
218 const PreconditionBase &preconditioner);
219
220 /**
221 * Solve the linear system <tt>Ax=b</tt> where both <tt>A</tt> and its
222 * @p preconditioner are an operator, and the vectors @p x and @p b are
223 * native Trilinos vector types.
224 * This function can be used when both <tt>A</tt> and the @p preconditioner
225 * are LinearOperators derived from a TrilinosPayload.
226 * Depending on the information provided by derived classes and the object
227 * passed as a preconditioner, one of the linear solvers and preconditioners
228 * of Trilinos is chosen.
229 */
230 void
231 solve(const Epetra_Operator &A,
232 Epetra_MultiVector &x,
233 const Epetra_MultiVector &b,
234 const Epetra_Operator &preconditioner);
235
236
237
238 /**
239 * Solve the linear system <tt>Ax=b</tt>. Depending on the information
240 * provided by derived classes and the object passed as a preconditioner,
241 * one of the linear solvers and preconditioners of Trilinos is chosen.
242 * This class works with matrices according to the TrilinosWrappers
243 * format, but can take deal.II vectors as argument. Since deal.II are
244 * serial vectors (not distributed), this function does only what you
245 * expect in case the matrix is locally owned. Otherwise, an exception
246 * will be thrown.
247 */
248 void
249 solve(const SparseMatrix &A,
250 dealii::Vector<double> &x,
251 const dealii::Vector<double> &b,
252 const PreconditionBase &preconditioner);
253
254 /**
255 * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
256 * This function can be used for matrix free computations. Depending on
257 * the information provided by derived classes and the object passed as a
258 * preconditioner, one of the linear solvers and preconditioners of
259 * Trilinos is chosen. This class works with matrices according to the
260 * TrilinosWrappers format, but can take deal.II vectors as argument.
261 * Since deal.II are serial vectors (not distributed), this function does
262 * only what you expect in case the matrix is locally owned. Otherwise, an
263 * exception will be thrown.
264 */
265 void
266 solve(Epetra_Operator &A,
267 dealii::Vector<double> &x,
268 const dealii::Vector<double> &b,
269 const PreconditionBase &preconditioner);
270
271 /**
272 * Solve the linear system <tt>Ax=b</tt> for deal.II's parallel
273 * distributed vectors. Depending on the information provided by derived
274 * classes and the object passed as a preconditioner, one of the linear
275 * solvers and preconditioners of Trilinos is chosen.
276 */
277 void
278 solve(const SparseMatrix &A,
279 dealii::LinearAlgebra::distributed::Vector<double> &x,
280 const dealii::LinearAlgebra::distributed::Vector<double> &b,
281 const PreconditionBase &preconditioner);
282
283 /**
284 * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
285 * This function can be used for matrix free computation. Depending on the
286 * information provided by derived classes and the object passed as a
287 * preconditioner, one of the linear solvers and preconditioners of
288 * Trilinos is chosen.
289 */
290 void
291 solve(Epetra_Operator &A,
292 dealii::LinearAlgebra::distributed::Vector<double> &x,
293 const dealii::LinearAlgebra::distributed::Vector<double> &b,
294 const PreconditionBase &preconditioner);
295
296
297 /**
298 * Access to object that controls convergence.
299 */
300 SolverControl &
301 control() const;
302
303 /**
304 * Exception
305 */
306 DeclException1(ExcTrilinosError,
307 int,
308 << "An error with error number " << arg1
309 << " occurred while calling a Trilinos function");
310
311 protected:
312 /**
313 * Reference to the object that controls convergence of the iterative
314 * solver. In fact, for these Trilinos wrappers, Trilinos does so itself,
315 * but we copy the data from this object before starting the solution
316 * process, and copy the data back into it afterwards.
317 */
318 SolverControl &solver_control;
319
320 private:
321 /**
322 * The solve function is used to set properly the Epetra_LinearProblem,
323 * once it is done this function solves the linear problem.
324 */
325 template <typename Preconditioner>
326 void
327 do_solve(const Preconditioner &preconditioner);
328
329 /**
330 * A function that sets the preconditioner that the solver will apply
331 */
332 template <typename Preconditioner>
333 void
334 set_preconditioner(AztecOO &solver, const Preconditioner &preconditioner);
335
336 /**
337 * A structure that collects the Trilinos sparse matrix, the right hand
338 * side vector and the solution vector, which is passed down to the
339 * Trilinos solver.
340 */
341 std::unique_ptr<Epetra_LinearProblem> linear_problem;
342
343 /**
344 * A structure that contains a Trilinos object that can query the linear
345 * solver and determine whether the convergence criterion have been met.
346 */
347 std::unique_ptr<AztecOO_StatusTest> status_test;
348
349 /**
350 * A structure that contains the Trilinos solver and preconditioner
351 * objects.
352 */
353 AztecOO solver;
354
355 /**
356 * Store a copy of the flags for this particular solver.
357 */
358 const AdditionalData additional_data;
359 };
360
361
362 // provide a declaration for two explicit specializations
363 template <>
364 void
365 SolverBase::set_preconditioner(AztecOO &solver,
366 const PreconditionBase &preconditioner);
367
368 template <>
369 void
370 SolverBase::set_preconditioner(AztecOO &solver,
371 const Epetra_Operator &preconditioner);
372
373
374 /**
375 * An implementation of the solver interface using the Trilinos CG solver.
376 *
377 * @ingroup TrilinosWrappers
378 */
379 class SolverCG : public SolverBase
380 {
381 public:
382 /**
383 * Constructor. In contrast to deal.II's own solvers, there is no need to
384 * give a vector memory object.
385 *
386 * The last argument takes a structure with additional, solver dependent
387 * flags for tuning.
388 */
389 SolverCG(SolverControl &cn, const AdditionalData &data = AdditionalData());
390 };
391
392
393
394 /**
395 * An implementation of the solver interface using the Trilinos CGS solver.
396 *
397 * @ingroup TrilinosWrappers
398 */
399 class SolverCGS : public SolverBase
400 {
401 public:
402 /**
403 * Constructor. In contrast to deal.II's own solvers, there is no need to
404 * give a vector memory object.
405 *
406 * The last argument takes a structure with additional, solver dependent
407 * flags for tuning.
408 */
409 SolverCGS(SolverControl &cn, const AdditionalData &data = AdditionalData());
410 };
411
412
413
414 /**
415 * An implementation of the solver interface using the Trilinos GMRES
416 * solver.
417 */
418 class SolverGMRES : public SolverBase
419 {
420 public:
421 /**
422 * Constructor. In contrast to deal.II's own solvers, there is no need to
423 * give a vector memory object.
424 *
425 * The last argument takes a structure with additional, solver dependent
426 * flags for tuning.
427 */
428 SolverGMRES(SolverControl &cn,
429 const AdditionalData &data = AdditionalData());
430 };
431
432
433
434 /**
435 * An implementation of the solver interface using the Trilinos BiCGStab
436 * solver.
437 *
438 * @ingroup TrilinosWrappers
439 */
440 class SolverBicgstab : public SolverBase
441 {
442 public:
443 /**
444 * Constructor. In contrast to deal.II's own solvers, there is no need to
445 * give a vector memory object.
446 *
447 * The last argument takes a structure with additional, solver dependent
448 * flags for tuning.
449 */
450 SolverBicgstab(SolverControl &cn,
451 const AdditionalData &data = AdditionalData());
452 };
453
454
455
456 /**
457 * An implementation of the solver interface using the Trilinos TFQMR
458 * solver.
459 *
460 * @ingroup TrilinosWrappers
461 */
462 class SolverTFQMR : public SolverBase
463 {
464 public:
465 /**
466 * Constructor. In contrast to deal.II's own solvers, there is no need to
467 * give a vector memory object.
468 *
469 * The last argument takes a structure with additional, solver dependent
470 * flags for tuning.
471 */
472 SolverTFQMR(SolverControl &cn,
473 const AdditionalData &data = AdditionalData());
474 };
475
476
477
478 /**
479 * An implementation of Trilinos direct solvers (using the Amesos package).
480 * The data field AdditionalData::solver_type can be used to specify the
481 * type of solver. It allows the use of built-in solvers Amesos_Klu as well
482 * as third-party solvers Amesos_Superludist or Amesos_Mumps.
483 *
484 * For instructions on how to install Trilinos for use with direct solvers
485 * other than KLU, see the link to the Trilinos installation instructions
486 * linked to from the deal.II ReadMe file.
487 *
488 * @ingroup TrilinosWrappers
489 */
490 class SolverDirect : public EnableObserverPointer
491 {
492 public:
493 /**
494 * Standardized data struct to pipe additional data to the solver.
495 */
496
497 struct AdditionalData
498 {
499 /**
500 * Set the additional data field to the desired output format.
501 */
502 explicit AdditionalData(const bool output_solver_details = false,
503 const std::string &solver_type = "Amesos_Klu");
504
505 /**
506 * Enables/disables the output of solver details (residual in each
507 * iterations etc.).
508 */
509 bool output_solver_details;
510
511 /**
512 * Set the solver type (for third party solver support of Trilinos
513 * Amesos package). Possibilities are:
514 * <ul>
515 * <li> "Amesos_Lapack" </li>
516 * <li> "Amesos_Scalapack" </li>
517 * <li> "Amesos_Klu" </li>
518 * <li> "Amesos_Umfpack" </li>
519 * <li> "Amesos_Pardiso" </li>
520 * <li> "Amesos_Taucs" </li>
521 * <li> "Amesos_Superlu" </li>
522 * <li> "Amesos_Superludist" </li>
523 * <li> "Amesos_Dscpack" </li>
524 * <li> "Amesos_Mumps" </li>
525 * </ul>
526 * Note that the availability of these solvers in deal.II depends on
527 * which solvers were set when configuring Trilinos.
528 */
529 std::string solver_type;
530 };
531
532 /**
533 * Constructor. Creates the solver without solver control object.
534 */
535 explicit SolverDirect(const AdditionalData &data = AdditionalData());
536
537 /**
538 * Constructor. Takes the solver control object and creates the solver.
539 */
540 SolverDirect(SolverControl &cn,
541 const AdditionalData &data = AdditionalData());
542
543 /**
544 * Destructor.
545 */
546 virtual ~SolverDirect() = default;
547
548 /**
549 * Initializes the direct solver for the matrix <tt>A</tt> and creates a
550 * factorization for it with the package chosen from the additional
551 * data structure. Note that there is no need for a preconditioner
552 * here and solve() is not called.
553 */
554 void
555 initialize(const SparseMatrix &A);
556
557 /**
558 * Initializes the direct solver for the matrix <tt>A</tt> and creates a
559 * factorization for it with the package chosen from the additional
560 * data structure. Note that there is no need for a preconditioner
561 * here and solve() is not called. Furthermore, @p data replaces the
562 * data stored in this instance.
563 */
564 void
565 initialize(const SparseMatrix &A, const AdditionalData &data);
566
567 /**
568 * Solve the linear system <tt>Ax=b</tt> based on the
569 * package set in the constructor on initialize(). Note the matrix is not
570 * refactored during this call.
571 */
572 void
573 solve(MPI::Vector &x, const MPI::Vector &b);
574
575 /**
576 * Solve the linear system <tt>Ax=b</tt> based on the package set in
577 * initialize() for deal.II's own parallel vectors. Note the matrix is not
578 * refactored during this call.
579 */
580 void
581 solve(dealii::LinearAlgebra::distributed::Vector<double> &x,
582 const dealii::LinearAlgebra::distributed::Vector<double> &b);
583
584 /**
585 * Solve the linear system <tt>Ax=b</tt> based on the
586 * package set in the constructor or initialize(). Note the matrix is not
587 * refactored during this call.
588 */
589 void
590 vmult(MPI::Vector &x, const MPI::Vector &b) const;
591
592 /**
593 * Solve the linear system <tt>Ax=b</tt> based on the package set in
594 * initialize() for deal.II's own parallel vectors. Note the matrix is not
595 * refactored during this call.
596 */
597 void
598 vmult(dealii::LinearAlgebra::distributed::Vector<double> &x,
599 const dealii::LinearAlgebra::distributed::Vector<double> &b) const;
600
601 /**
602 * Solve the linear system <tt>Ax=b</tt>. Creates a factorization of the
603 * matrix with the package chosen from the additional data structure and
604 * performs the solve. Note that there is no need for a preconditioner
605 * here.
606 */
607 void
608 solve(const SparseMatrix &A, MPI::Vector &x, const MPI::Vector &b);
609
610 /**
611 * Solve the linear system <tt>Ax=b</tt>. This class works with Trilinos
612 * matrices, but takes deal.II serial vectors as argument. Since these
613 * vectors are not distributed, this function does only what you expect in
614 * case the matrix is serial (i.e., locally owned). Otherwise, an
615 * exception will be thrown.
616 */
617 void
618 solve(const SparseMatrix &A,
619 dealii::Vector<double> &x,
620 const dealii::Vector<double> &b);
621
622 /**
623 * Solve the linear system <tt>Ax=b</tt> for deal.II's own parallel
624 * vectors. Creates a factorization of the matrix with the package chosen
625 * from the additional data structure and performs the solve. Note that
626 * there is no need for a preconditioner here.
627 */
628 void
629 solve(const SparseMatrix &A,
630 dealii::LinearAlgebra::distributed::Vector<double> &x,
631 const dealii::LinearAlgebra::distributed::Vector<double> &b);
632
633 /**
634 * Solve the linear system <tt>Ax=b</tt> where A is an operator,
635 * and the vectors x and b are native Trilinos vector types.
636 * This function can be used when A is a LinearOperators derived
637 * from a TrilinosPayload.
638 */
639 void
640 solve(const Epetra_Operator &A,
641 Epetra_MultiVector &x,
642 const Epetra_MultiVector &b);
643
644 /**
645 * Solve the linear system <tt>AX=B</tt> where A is an operator,
646 * and the X and B are FullMatrix types. The matrices are
647 * converted to multi vector and the resulting problem is solved
648 * in a batched way.
649 */
650 void
651 solve(const SparseMatrix &sparse_matrix,
652 FullMatrix<double> &solution,
653 const FullMatrix<double> &rhs);
654
655 /**
656 * Access to object that controls convergence.
657 */
658 SolverControl &
659 control() const;
660
661 /**
662 * Exception
663 */
664 DeclException1(ExcTrilinosError,
665 int,
666 << "An error with error number " << arg1
667 << " occurred while calling a Trilinos function");
668
669 private:
670 /**
671 * Actually performs the operations for solving the linear system,
672 * including the factorization and forward and backward substitution.
673 */
674 void
675 do_solve();
676
677 /**
678 * Local dummy solver control object.
679 */
680 SolverControl solver_control_own;
681
682 /**
683 * Reference to the object that controls convergence of the iterative
684 * solver. In fact, for these Trilinos wrappers, Trilinos does so itself,
685 * but we copy the data from this object before starting the solution
686 * process, and copy the data back into it afterwards.
687 */
688 SolverControl &solver_control;
689
690 /**
691 * A structure that collects the Trilinos sparse matrix, the right hand
692 * side vector and the solution vector, which is passed down to the
693 * Trilinos solver.
694 */
695 std::unique_ptr<Epetra_LinearProblem> linear_problem;
696
697 /**
698 * A structure that contains the Trilinos solver and preconditioner
699 * objects.
700 */
701 std::unique_ptr<Amesos_BaseSolver> solver;
702
703 /**
704 * Store a copy of the flags for this particular solver.
705 */
706 AdditionalData additional_data;
707 };
708
709
710
711 # ifdef DEAL_II_TRILINOS_WITH_BELOS
712 /**
713 * Wrapper around the iterate solver package from the Belos
714 * package
715 * (https://docs.trilinos.org/latest-release/packages/belos/doc/html/index.html),
716 * targeting deal.II data structures.
717 */
718 template <typename VectorType>
719 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
720 class SolverBelos
721 {
722 public:
723 /**
724 * Enumeration object that Trilinos which solver to use.
725 * Currently enabled options are:
726 */
727 enum SolverName
728 {
729 /**
730 * Use the conjugate gradient (CG) algorithm.
731 */
732 cg,
733 /**
734 * Use the generalized minimum residual (GMRES) algorithm.
735 */
736 gmres,
737 } solver_name;
738
739 /**
740 * Struct that helps to configure SolverBelos. More advanced
741 * parameters are passed to the constructor SolverBelos
742 * directly via a Teuchos::ParameterList.
743 */
744 struct AdditionalData
745 {
746 /**
747 * Constructor.
748 */
749 AdditionalData(const SolverName solver_name = SolverName::cg,
750 const bool right_preconditioning = false)
751 : solver_name(solver_name)
752 , right_preconditioning(right_preconditioning)
753 {}
754
755 /**
756 * Solver type;
757 */
758 SolverName solver_name;
759
760 /**
761 * Flag for right preconditioning.
762 */
763 bool right_preconditioning;
764 };
765
766 /**
767 * Constructor.
768 */
769 SolverBelos(SolverControl &solver_control,
770 const AdditionalData &additional_data,
771 const Teuchos::RCP<Teuchos::ParameterList> &belos_parameters);
772
773 /**
774 * Solve the linear system <tt>Ax=b</tt> with a given preconditioner.
775 */
776 template <typename OperatorType, typename PreconditionerType>
777 void
778 solve(const OperatorType &a,
779 VectorType &x,
780 const VectorType &b,
781 const PreconditionerType &p);
782
783 private:
784 SolverControl &solver_control;
785 const AdditionalData additional_data;
786 const Teuchos::RCP<Teuchos::ParameterList> &belos_parameters;
787 };
788 # endif
789
790 } // namespace TrilinosWrappers
791
792
793
794 # ifndef DOXYGEN
795
796 # ifdef DEAL_II_TRILINOS_WITH_BELOS
797 namespace TrilinosWrappers
798 {
799 namespace internal
800 {
801 /**
802 * Implementation of the abstract interface
803 * Belos::MultiVec for deal.II vectors. For details,
804 * see
805 * https://docs.trilinos.org/latest-release/packages/belos/doc/html/classBelos_1_1MultiVec.html.
806 */
807 template <typename VectorType>
808 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
809 class MultiVecWrapper
810 : public Belos::MultiVec<typename VectorType::value_type>
811 {
812 public:
813 /**
814 * Underlying value type.
815 */
816 using value_type = typename VectorType::value_type;
817
818 /**
819 * Indicate that specialization exists.
820 */
821 static bool
822 this_type_is_missing_a_specialization()
823 {
824 return false;
825 }
826
827 /**
828 * Constructor that takes a mutable deal.II vector.
829 */
830 MultiVecWrapper(VectorType &vector)
831 {
832 this->vectors.resize(1);
833 this->vectors[0].reset(
834 &vector,
835 [](auto *) { /*Nothing to do, since vector is owned outside.*/ });
836 }
837
838 /**
839 * Constructor that takes a const deal.II vector.
840 */
841 MultiVecWrapper(const VectorType &vector)
842 {
843 this->vectors.resize(1);
844 this->vectors[0].reset(
845 &const_cast<VectorType &>(vector),
846 [](auto *) { /*Nothing to do, since vector is owned outside.*/ });
847 }
848
849 /**
850 * Destructor.
851 */
852 virtual ~MultiVecWrapper() = default;
853
854 /**
855 * Create a new MultiVec with numvecs columns.
856 */
857 virtual Belos::MultiVec<value_type> *
858 Clone(const int numvecs) const
859 {
860 auto new_multi_vec = new MultiVecWrapper<VectorType>;
861
862 new_multi_vec->vectors.resize(numvecs);
863
864 for (auto &vec : new_multi_vec->vectors)
865 {
866 vec = std::make_shared<VectorType>();
867
868 AssertThrow(this->vectors.size() > 0, ExcInternalError());
869 vec->reinit(*this->vectors[0]);
870 }
871
872 return new_multi_vec;
873 }
874
875 /**
876 * Create a new MultiVec and copy contents of *this into it (deep copy).
877 */
878 virtual Belos::MultiVec<value_type> *
879 CloneCopy() const
880 {
881 AssertThrow(false, ExcNotImplemented());
882 }
883
884 /**
885 * Creates a new Belos::MultiVec and copies the selected contents of
886 * *this into the new multivector (deep copy). The copied vectors
887 * from *this are indicated by the index.size() indices in index.
888 */
889 virtual Belos::MultiVec<value_type> *
890 CloneCopy(const std::vector<int> &index) const
891 {
892 auto new_multi_vec = new MultiVecWrapper<VectorType>;
893
894 new_multi_vec->vectors.resize(index.size());
895
896 for (unsigned int i = 0; i < index.size(); ++i)
897 {
898 AssertThrow(static_cast<unsigned int>(index[i]) <
899 this->vectors.size(),
900 ExcInternalError());
901
902 new_multi_vec->vectors[i] = std::make_shared<VectorType>();
903
904 AssertIndexRange(index[i], this->vectors.size());
905 *new_multi_vec->vectors[i] = *this->vectors[index[i]];
906 }
907
908 return new_multi_vec;
909 }
910
911 /**
912 * Creates a new Belos::MultiVec that shares the selected contents
913 * of *this. The index of the numvecs vectors copied from *this
914 * are indicated by the indices given in index.
915 */
916 virtual Belos::MultiVec<value_type> *
917 CloneViewNonConst(const std::vector<int> &index)
918 {
919 auto new_multi_vec = new MultiVecWrapper<VectorType>;
920
921 new_multi_vec->vectors.resize(index.size());
922
923 for (unsigned int i = 0; i < index.size(); ++i)
924 {
925 AssertThrow(static_cast<unsigned int>(index[i]) <
926 this->vectors.size(),
927 ExcInternalError());
928
929 new_multi_vec->vectors[i].reset(
930 this->vectors[index[i]].get(),
931 [](
932 auto
933 *) { /*Nothing to do, since we are creating only a view.*/ });
934 }
935
936 return new_multi_vec;
937 }
938
939 /**
940 * Creates a new Belos::MultiVec that shares the selected contents
941 * of *this. The index of the numvecs vectors copied from *this
942 * are indicated by the indices given in index.
943 */
944 virtual const Belos::MultiVec<value_type> *
945 CloneView(const std::vector<int> &index) const
946 {
947 auto new_multi_vec = new MultiVecWrapper<VectorType>;
948
949 new_multi_vec->vectors.resize(index.size());
950
951 for (unsigned int i = 0; i < index.size(); ++i)
952 {
953 AssertThrow(static_cast<unsigned int>(index[i]) <
954 this->vectors.size(),
955 ExcInternalError());
956
957 new_multi_vec->vectors[i].reset(
958 this->vectors[index[i]].get(),
959 [](
960 auto
961 *) { /*Nothing to do, since we are creating only a view.*/ });
962 }
963
964 return new_multi_vec;
965 }
966
967 /**
968 * The number of rows in the multivector.
969 */
970 virtual std::ptrdiff_t
971 GetGlobalLength() const
972 {
973 AssertThrow(this->vectors.size() > 0, ExcInternalError());
974
975 for (unsigned int i = 1; i < this->vectors.size(); ++i)
976 AssertDimension(this->vectors[0]->size(), this->vectors[i]->size());
977
978 return this->vectors[0]->size();
979 }
980
981 /**
982 * The number of vectors (i.e., columns) in the multivector.
983 */
984 virtual int
985 GetNumberVecs() const
986 {
987 return vectors.size();
988 }
989
990 /**
991 * Update *this with alpha * A * B + beta * (*this).
992 */
993 virtual void
994 MvTimesMatAddMv(const value_type alpha,
995 const Belos::MultiVec<value_type> &A_,
996 const Teuchos::SerialDenseMatrix<int, value_type> &B,
997 const value_type beta)
998 {
999 const auto &A = try_to_get_underlying_vector(A_);
1000
1001 const unsigned int n_rows = B.numRows();
1002 const unsigned int n_cols = B.numCols();
1003
1004 AssertThrow(n_rows == static_cast<unsigned int>(A.GetNumberVecs()),
1005 ExcInternalError());
1006 AssertThrow(n_cols == static_cast<unsigned int>(this->GetNumberVecs()),
1007 ExcInternalError());
1008
1009 for (unsigned int i = 0; i < n_cols; ++i)
1010 (*this->vectors[i]) *= beta;
1011
1012 for (unsigned int i = 0; i < n_cols; ++i)
1013 for (unsigned int j = 0; j < n_rows; ++j)
1014 this->vectors[i]->add(alpha * B(j, i), *A.vectors[j]);
1015 }
1016
1017 /**
1018 * Replace *this with alpha * A + beta * B.
1019 */
1020 virtual void
1021 MvAddMv(const value_type alpha,
1022 const Belos::MultiVec<value_type> &A_,
1023 const value_type beta,
1024 const Belos::MultiVec<value_type> &B_)
1025 {
1026 const auto &A = try_to_get_underlying_vector(A_);
1027 const auto &B = try_to_get_underlying_vector(B_);
1028
1029 AssertThrow(this->vectors.size() == A.vectors.size(),
1030 ExcInternalError());
1031 AssertThrow(this->vectors.size() == B.vectors.size(),
1032 ExcInternalError());
1033
1034 for (unsigned int i = 0; i < this->vectors.size(); ++i)
1035 {
1036 this->vectors[i]->equ(alpha, *A.vectors[i]);
1037 this->vectors[i]->add(beta, *B.vectors[i]);
1038 }
1039 }
1040
1041 /**
1042 * Scale each element of the vectors in *this with alpha.
1043 */
1044 virtual void
1045 MvScale(const value_type alpha)
1046 {
1047 for (unsigned int i = 0; i < this->vectors.size(); ++i)
1048 (*this->vectors[i]) *= alpha;
1049 }
1050
1051 /**
1052 * Scale each element of the i-th vector in *this with alpha[i].
1053 */
1054 virtual void
1055 MvScale(const std::vector<value_type> & /*alpha*/)
1056 {
1057 AssertThrow(false, ExcNotImplemented());
1058 }
1059
1060 /**
1061 * Compute a dense matrix B through the matrix-matrix multiply
1062 * alpha * A^T * (*this).
1063 */
1064 virtual void
1065 MvTransMv(const value_type alpha,
1066 const Belos::MultiVec<value_type> &A_,
1067 Teuchos::SerialDenseMatrix<int, value_type> &B) const
1068 {
1069 const auto &A = try_to_get_underlying_vector(A_);
1070
1071 const unsigned int n_rows = B.numRows();
1072 const unsigned int n_cols = B.numCols();
1073
1074 AssertThrow(n_rows == static_cast<unsigned int>(A.GetNumberVecs()),
1075 ExcInternalError());
1076 AssertThrow(n_cols == static_cast<unsigned int>(this->GetNumberVecs()),
1077 ExcInternalError());
1078
1079 for (unsigned int i = 0; i < n_rows; ++i)
1080 for (unsigned int j = 0; j < n_cols; ++j)
1081 B(i, j) = alpha * ((*A.vectors[i]) * (*this->vectors[j]));
1082 }
1083
1084 /**
1085 * Compute the dot product of each column of *this with the
1086 * corresponding column of A.
1087 */
1088 virtual void
1089 MvDot(const Belos::MultiVec<value_type> &A_,
1090 std::vector<value_type> &b) const
1091 {
1092 const auto &A = try_to_get_underlying_vector(A_);
1093
1094 AssertThrow(this->vectors.size() == A.vectors.size(),
1095 ExcInternalError());
1096 AssertThrow(this->vectors.size() == b.size(), ExcInternalError());
1097
1098 for (unsigned int i = 0; i < this->vectors.size(); ++i)
1099 b[i] = (*this->vectors[i]) * (*A.vectors[i]);
1100 }
1101
1102 /**
1103 * Compute the norm of each vector in *this.
1104 */
1105 virtual void
1106 MvNorm(
1107 std::vector<typename Teuchos::ScalarTraits<value_type>::magnitudeType>
1108 &normvec,
1109 Belos::NormType type = Belos::TwoNorm) const
1110 {
1111 AssertThrow(type == Belos::TwoNorm, ExcNotImplemented());
1112 AssertThrow(this->vectors.size() == normvec.size(), ExcInternalError());
1113
1114 for (unsigned int i = 0; i < this->vectors.size(); ++i)
1115 normvec[i] = this->vectors[i]->l2_norm();
1116 }
1117
1118 /**
1119 * Copy the vectors in A to a set of vectors in *this.
1120 */
1121 virtual void
1122 SetBlock(const Belos::MultiVec<value_type> & /*A*/,
1123 const std::vector<int> & /*index*/)
1124 {
1125 AssertThrow(false, ExcNotImplemented());
1126 }
1127
1128 /**
1129 * Fill all the vectors in *this with random numbers.
1130 */
1131 virtual void
1132 MvRandom()
1133 {
1134 AssertThrow(false, ExcNotImplemented());
1135 }
1136
1137 /**
1138 * Replace each element of the vectors in *this with alpha.
1139 */
1140 virtual void
1141 MvInit(const value_type /*alpha*/)
1142 {
1143 AssertThrow(false, ExcNotImplemented());
1144 }
1145
1146 /**
1147 * Print *this multivector to the os output stream.
1148 */
1149 virtual void
1150 MvPrint(std::ostream & /*os*/) const
1151 {
1152 AssertThrow(false, ExcNotImplemented());
1153 }
1154
1155 /**
1156 * Get underlying vector.
1157 */
1158 VectorType &
1159 genericVector()
1160 {
1161 AssertThrow(GetNumberVecs() == 1, ExcNotImplemented());
1162
1163 return *vectors[0];
1164 }
1165
1166 /**
1167 * Get underlying vector (const version).
1168 */
1169 const VectorType &
1170 genericVector() const
1171 {
1172 AssertThrow(GetNumberVecs() == 1, ExcNotImplemented());
1173
1174 return *vectors[0];
1175 }
1176
1177 /**
1178 * Cast Belos::MultiVec to MultiVecWrapper.
1179 */
1180 static MultiVecWrapper<VectorType> &
1181 try_to_get_underlying_vector(Belos::MultiVec<value_type> &vec_in)
1182 {
1183 auto vec = dynamic_cast<MultiVecWrapper<VectorType> *>(&vec_in);
1184
1185 AssertThrow(vec, ExcInternalError());
1186
1187 return *vec;
1188 }
1189
1190 /**
1191 * Cast Belos::MultiVec to MultiVecWrapper (const version).
1192 */
1193 const static MultiVecWrapper<VectorType> &
1194 try_to_get_underlying_vector(const Belos::MultiVec<value_type> &vec_in)
1195 {
1196 auto vec = dynamic_cast<const MultiVecWrapper<VectorType> *>(&vec_in);
1197
1198 AssertThrow(vec, ExcInternalError());
1199
1200 return *vec;
1201 }
1202
1203
1204 # ifdef HAVE_BELOS_TSQR
1205 virtual void
1206 factorExplicit(Belos::MultiVec<value_type> &,
1207 Teuchos::SerialDenseMatrix<int, value_type> &,
1208 const bool = false)
1209 {
1210 DEAL_II_NOT_IMPLEMENTED();
1211 }
1212
1213 virtual int
1214 revealRank(
1215 Teuchos::SerialDenseMatrix<int, value_type> &,
1216 const typename Teuchos::ScalarTraits<value_type>::magnitudeType &)
1217 {
1218 DEAL_II_NOT_IMPLEMENTED();
1219 }
1220
1221 # endif
1222
1223 private:
1224 /**
1225 * Underlying vectors.
1226 */
1227 std::vector<std::shared_ptr<VectorType>> vectors;
1228
1229 /**
1230 * Default constructor. Only used internally to create new MultiVecWrapper
1231 * instances.
1232 */
1233 MultiVecWrapper() = default;
1234 };
1235
1236 /**
1237 * Implementation of the abstract interface
1238 * Belos::Operator for deal.II vectors and deal.II
1239 * operators/preconditioners. For details, see
1240 * https://docs.trilinos.org/latest-release/packages/belos/doc/html/classBelos_1_1Operator.html.
1241 */
1242 template <typename OperatorType, typename VectorType>
1243 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
1244 class OperatorWrapper
1245 : public Belos::Operator<typename VectorType::value_type>
1246 {
1247 public:
1248 /**
1249 * Underlying value type.
1250 */
1251 using value_type = typename VectorType::value_type;
1252
1253 /**
1254 * Indicate that specialization exists.
1255 */
1256 static bool
1257 this_type_is_missing_a_specialization()
1258 {
1259 return false;
1260 }
1261
1262 /**
1263 * Constructor.
1264 */
1265 OperatorWrapper(const OperatorType &op)
1266 : op(op)
1267 {}
1268
1269 /**
1270 * Destructor.
1271 */
1272 virtual ~OperatorWrapper() = default;
1273
1274 /**
1275 * Apply the operator to x, putting the result in y.
1276 */
1277 virtual void
1278 Apply(const Belos::MultiVec<value_type> &x,
1279 Belos::MultiVec<value_type> &y,
1280 Belos::ETrans trans = Belos::NOTRANS) const
1281 {
1282 // TODO: check for Tvmult
1283 AssertThrow(trans == Belos::NOTRANS, ExcNotImplemented());
1284
1285 op.vmult(MultiVecWrapper<VectorType>::try_to_get_underlying_vector(y)
1286 .genericVector(),
1287 MultiVecWrapper<VectorType>::try_to_get_underlying_vector(x)
1288 .genericVector());
1289 }
1290
1291 /**
1292 * Whether this operator implements applying the transpose.
1293 */
1294 virtual bool
1295 HasApplyTranspose() const
1296 {
1297 // TODO: check for Tvmult
1298 return false;
1299 }
1300
1301 private:
1302 /**
1303 * Underlying operator.
1304 */
1305 const OperatorType &op;
1306 };
1307
1308 } // namespace internal
1309
1310
1311
1312 template <typename VectorType>
1313 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
1314 SolverBelos<VectorType>::SolverBelos(
1315 SolverControl &solver_control,
1316 const AdditionalData &additional_data,
1317 const Teuchos::RCP<Teuchos::ParameterList> &belos_parameters)
1318 : solver_control(solver_control)
1319 , additional_data(additional_data)
1320 , belos_parameters(belos_parameters)
1321 {}
1322
1323
1324
1325 template <typename VectorType>
1326 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
1327 template <typename OperatorType, typename PreconditionerType>
1328 void SolverBelos<VectorType>::solve(const OperatorType &A_dealii,
1329 VectorType &x_dealii,
1330 const VectorType &b_dealii,
1331 const PreconditionerType &P_dealii)
1332 {
1333 using value_type = typename VectorType::value_type;
1334
1335 using MV = Belos::MultiVec<value_type>;
1336 using OP = Belos::Operator<value_type>;
1337
1338 Teuchos::RCP<OP> A = Teuchos::rcp(
1339 new internal::OperatorWrapper<OperatorType, VectorType>(A_dealii));
1340 Teuchos::RCP<OP> P = Teuchos::rcp(
1341 new internal::OperatorWrapper<PreconditionerType, VectorType>(P_dealii));
1342 Teuchos::RCP<MV> X =
1343 Teuchos::rcp(new internal::MultiVecWrapper<VectorType>(x_dealii));
1344 Teuchos::RCP<MV> B =
1345 Teuchos::rcp(new internal::MultiVecWrapper<VectorType>(b_dealii));
1346
1347 Teuchos::RCP<Belos::LinearProblem<value_type, MV, OP>> problem =
1348 Teuchos::rcp(new Belos::LinearProblem<value_type, MV, OP>(A, X, B));
1349
1350 if (additional_data.right_preconditioning == false)
1351 problem->setLeftPrec(P);
1352 else
1353 problem->setRightPrec(P);
1354
1355 const bool problem_set = problem->setProblem();
1356 AssertThrow(problem_set, ExcInternalError());
1357
1358 // compute initial residal
1359 VectorType r;
1360 r.reinit(x_dealii, true);
1361 A_dealii.vmult(r, x_dealii);
1362 r.sadd(-1., 1., b_dealii);
1363 const auto norm_0 = r.l2_norm();
1364
1365 if (solver_control.check(0, norm_0) != SolverControl::iterate)
1366 return;
1367
1368 double relative_tolerance_to_be_achieved =
1369 solver_control.tolerance() / norm_0;
1370 const unsigned int max_steps = solver_control.max_steps();
1371
1372 if (const auto *reduction_control =
1373 dynamic_cast<ReductionControl *>(&solver_control))
1374 relative_tolerance_to_be_achieved =
1375 std::max(relative_tolerance_to_be_achieved,
1376 reduction_control->reduction());
1377
1378 Teuchos::RCP<Teuchos::ParameterList> belos_parameters_copy(
1379 Teuchos::rcp(new Teuchos::ParameterList(*belos_parameters)));
1380
1381 belos_parameters_copy->set("Convergence Tolerance",
1382 relative_tolerance_to_be_achieved);
1383 belos_parameters_copy->set("Maximum Iterations",
1384 static_cast<int>(max_steps));
1385
1386 Teuchos::RCP<Belos::SolverManager<value_type, MV, OP>> solver;
1387
1388 if (additional_data.solver_name == SolverName::cg)
1389 solver = Teuchos::rcp(
1390 new Belos::BlockCGSolMgr<value_type, MV, OP>(problem,
1391 belos_parameters_copy));
1392 else if (additional_data.solver_name == SolverName::gmres)
1393 solver = Teuchos::rcp(
1394 new Belos::BlockGmresSolMgr<value_type, MV, OP>(problem,
1395 belos_parameters_copy));
1396 else
1397 AssertThrow(false, ExcNotImplemented());
1398
1399 const auto flag = solver->solve();
1400
1401 solver_control.check(solver->getNumIters(), solver->achievedTol() * norm_0);
1402
1403 AssertThrow(flag == Belos::ReturnType::Converged ||
1404 ((dynamic_cast<IterationNumberControl *>(&solver_control) !=
1405 nullptr) &&
1406 (solver_control.last_step() == max_steps)),
1407 SolverControl::NoConvergence(solver_control.last_step(),
1408 solver_control.last_value()));
1409 }
1410
1411 } // namespace TrilinosWrappers
1412 # endif
1413
1414 # endif
1415
1416 DEAL_II_NAMESPACE_CLOSE
1417
1418 #else
1419
1420 // Make sure the scripts that create the C++20 module input files have
1421 // something to latch on if the preprocessor #ifdef above would
1422 // otherwise lead to an empty content of the file.
1423 DEAL_II_NAMESPACE_OPEN
1424 DEAL_II_NAMESPACE_CLOSE
1425
1426 #endif // DEAL_II_WITH_TRILINOS
1427
1428 #endif