Debian Codegraph @

include/deal.II/lac/trilinos_tpetra_solver_direct.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2024 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_trilinos_tpetra_solver_direct_h
16 #define dealii_trilinos_tpetra_solver_direct_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/grid/grid_generator.h>
21
22 #include <deal.II/lac/trilinos_tpetra_types.h>
23
24 #include <string>
25
26 #ifdef DEAL_II_TRILINOS_WITH_TPETRA
27 # ifdef DEAL_II_TRILINOS_WITH_AMESOS2
28
29 # include <deal.II/base/types.h>
30
31 # include <deal.II/lac/la_parallel_vector.h>
32 # include <deal.II/lac/solver_control.h>
33 # include <deal.II/lac/trilinos_tpetra_sparse_matrix.h>
34
35 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
36 # include <Amesos2.hpp>
37 # include <Teuchos_ConfigDefs.hpp>
38 # include <Teuchos_ParameterList.hpp>
39 # include <Teuchos_RCPDecl.hpp>
40 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
41
42 DEAL_II_NAMESPACE_OPEN
43
44 namespace LinearAlgebra
45 {
46 namespace TpetraWrappers
47 {
48 // forward declarations
49 # ifndef DOXYGEN
50 template <typename Number, typename MemorySpace>
51 class SparseMatrix;
52 # endif
53
54 /// The chosen Solver is not supported or configured with Amesos2.
55 DeclException1(
56 ExcTrilinosAmesos2SolverUnsupported,
57 std::string,
58 << "You tried to select the solver type <" << arg1 << ">\n"
59 << "but this solver is not supported by Trilinos/Amesos2\n"
60 << "due to one of the following reasons:\n"
61 << "* This solver does not exist\n"
62 << "* This solver is not (yet) supported by Trilinos/Amesos2\n"
63 << "* Trilinos/Amesos2 was not configured for its use.");
64
65
66 /**
67 * The base class for all direct solvers based on the Amesos2 package
68 * of Trilinos.
69 *
70 * @ingroup TpetraWrappers
71 */
72 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
73 class SolverDirectBase
74 {
75 public:
76 /**
77 * Destructor.
78 */
79 virtual ~SolverDirectBase() = default;
80
81 /**
82 * Initializes the direct solver for the matrix <tt>A</tt> and creates a
83 * factorization for it with the package chosen from the additional
84 * data structure. Note that there is no need for a preconditioner
85 * here and solve() is not called.
86 */
87 void
88 initialize(const SparseMatrix<Number, MemorySpace> &A);
89
90 /**
91 * Solve the linear system <tt>Ax=b</tt> based on the
92 * package set in initialize(). Note the matrix is not refactorized during
93 * this call.
94 */
95 void
96 solve(Vector<Number, MemorySpace> &x,
97 const Vector<Number, MemorySpace> &b);
98
99 /**
100 * Solve the linear system <tt>Ax=b</tt>. Creates a factorization of the
101 * matrix with the package chosen from the additional data structure and
102 * performs the solve. Note that there is no need for a preconditioner
103 * here.
104 */
105 void
106 solve(const SparseMatrix<Number, MemorySpace> &A,
107 Vector<Number, MemorySpace> &x,
108 const Vector<Number, MemorySpace> &b);
109
110
111 /**
112 * Access to object that controls convergence.
113 */
114 SolverControl &
115 control() const;
116
117 /**
118 * Exception
119 */
120 DeclException1(ExcTrilinosError,
121 int,
122 << "An error with error number " << arg1
123 << " occurred while calling a Trilinos function");
124
125 protected:
126 /**
127 * Constructor. Takes the solver control object and name
128 * and creates the solver.
129 */
130 SolverDirectBase(SolverControl &cn, const std::string &solver_type);
131 /**
132 * Actually performs the operations for solving the linear system,
133 * including the factorization and forward and backward substitution.
134 */
135 void
136 do_solve();
137
138 /**
139 * Reference to the object that controls convergence of the iterative
140 * solver. In fact, for these Trilinos wrappers, Trilinos does so itself,
141 * but we copy the data from this object before starting the solution
142 * process, and copy the data back into it afterwards.
143 */
144 SolverControl &solver_control;
145
146 /**
147 * A structure that contains the Trilinos solver object.
148 */
149 Teuchos::RCP<
150 Amesos2::Solver<TpetraTypes::MatrixType<Number, MemorySpace>,
151 TpetraTypes::MultiVectorType<Number, MemorySpace>>>
152 solver;
153
154 /*
155 * The set solver type to be handed to the solver factory of Amesos2.
156 */
157 std::string solver_type;
158
159 /**
160 * An optional Teuchos::ParameterList for fine tuning the solver.
161 * Please refer to the Amesos2 manual to see which parameters
162 * to set for each individual solver.
163 */
164 Teuchos::ParameterList parameter_list;
165 }; // Base
166
167
168
169 /**
170 * A general purpose class to support any solver that the Amesos2 package
171 * of Trilinos provides.
172 *
173 * Notes for users switching from TrilinosWrappers to TpetraWrappers:
174 * The general interface of this class is kept identical to the Amesos(1)
175 * wrapper with the notable exception of being templated.
176 *
177 * A further addition is the option to fine tune each solver with a
178 * Teuchos::ParameterList, to change default parameters.
179 *
180 * @ingroup TpetraWrappers
181 */
182 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
183 class SolverDirect : public SolverDirectBase<Number, MemorySpace>
184 {
185 public:
186 /**
187 * A structure whose member variables describe details of the algorithm
188 * to be employed by the surrounding class. An object of this type can be
189 * used to initialize an object of the surrounding class.
190 */
191 struct AdditionalData
192 {
193 AdditionalData(const std::string &solver_name);
194
195
196 /**
197 * Set the solver type (for third party solver support of Trilinos
198 * Amesos package). Current possibilities are:
199 * <ul>
200 * <li> "Basker" </li>
201 * <li> "Cholmod" </li>
202 * <li> "cuSOLVER" </li>
203 * <li> "KLU2" </li>
204 * <li> "LAPACK" </li>
205 * <li> "MUMPS" </li>
206 * <li> "PardisoMKL" </li>
207 * <li> "ShyLUBasker" </li>
208 * <li> "SuperLU" </li>
209 * <li> "SuperLU_DIST" </li>
210 * <li> "SuperLU_MT" </li>
211 * <li> "Tacho" </li>
212 * <li> "UMFPACK" </li>
213 * </ul>
214 * Note that the availability of these solvers in deal.II depends on
215 * which solvers were set when configuring Trilinos.
216 * Additionally, Amesos2 may add support for solvers not listed here
217 * that can nevertheless be used if configured.
218 */
219 std::string solver_name;
220 };
221
222 /**
223 * Constructor. Takes the solver control object and creates the solver.
224 */
225 SolverDirect(SolverControl &cn,
226 const AdditionalData &additional_data = AdditionalData());
227
228 /**
229 * Set a parameter list to fine tune the solver.
230 * The valid parameters depend on the solver you use
231 * and the possible parameters can be found in the
232 * documentation of Amesos2.
233 */
234 void
235 set_pararameter_list(Teuchos::ParameterList &parameter_list);
236 }; // SolverDirect
237
238
239 /**
240 * A wrapper class for the solver KLU2 that works in serial and parallel.
241 * This solver is part of Amesos2 and enabled by default.
242 *
243 * The AdditionalData structure allows to pass options specific to this
244 * solver and the default will result in the same solver as constructing
245 * SolverDirect with solver_name KLU2.
246 *
247 * @ingroup TpetraWrappers
248 */
249 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
250 class SolverDirectKLU2 : public SolverDirectBase<Number, MemorySpace>
251 {
252 public:
253 /**
254 * A structure whose member variables describe details of the algorithm
255 * to be employed by the surrounding class. An object of this type can be
256 * used to initialize an object of the surrounding class.
257 */
258 struct AdditionalData
259 {
260 AdditionalData(const std::string &transpose_mode = "NOTRANS",
261 const bool symmetric_mode = false,
262 const bool equilibrate_matrix = true,
263 const std::string &column_permutation = "COLAMD",
264 const std::string &iterative_refinement = "NO");
265 /**
266 * Decide which system to solve
267 * "NOTRANS": Ax=b (default)
268 * "TRANS": A^Tx=b
269 * "CONJ": A^*x=b
270 */
271 std::string transpose_mode;
272
273 /**
274 * Is A symmetric or not?
275 */
276 bool symmetric_mode;
277
278 /**
279 * Equilibrate matrix before solving? (default: true)
280 */
281 bool equilibrate_matrix;
282
283 /**
284 * Choose an ordering strategy
285 * "COLAMD": approximate minimum degree column ordering (default).
286 * "NATURAL": natural ordering.
287 * "MMD_ATA": minimum degree ordering on the structure of A^TA.
288 * "MMD_AT_PLUS_A": minimum degree ordering on the structure of A^T+A.
289 */
290 std::string column_permutation;
291
292 /**
293 * Perform iterative refinement?
294 * "NO": no (default)
295 * "SINGLE": yes, use single precision for the residual
296 * "DOUBLE": yes, use double precision for the residual
297 * "EXTRA": ??
298 */
299 std::string iterative_refinement;
300 };
301
302 /**
303 * Constructor. Takes the solver control object and creates the solver.
304 */
305 SolverDirectKLU2(
306 SolverControl &cn,
307 const AdditionalData &additional_data = AdditionalData());
308 }; // KLU2
309
310 } // namespace TpetraWrappers
311 } // namespace LinearAlgebra
312
313 DEAL_II_NAMESPACE_CLOSE
314
315 # endif // DEAL_II_TRILINOS_WITH_AMESOS2
316 #else
317
318 // Make sure the scripts that create the C++20 module input files have
319 // something to latch on if the preprocessor #ifdef above would
320 // otherwise lead to an empty content of the file.
321 DEAL_II_NAMESPACE_OPEN
322 DEAL_II_NAMESPACE_CLOSE
323
324 #endif // DEAL_II_TRILINOS_WITH_TPETRA
325
326 #endif