Debian Codegraph @

include/deal.II/lac/solver_selector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2024 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_solver_selector_h
16 #define dealii_solver_selector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/observer_pointer.h>
22 #include <deal.II/base/template_constraints.h>
23
24 #include <deal.II/lac/precondition.h>
25 #include <deal.II/lac/solver.h>
26 #include <deal.II/lac/solver_bicgstab.h>
27 #include <deal.II/lac/solver_cg.h>
28 #include <deal.II/lac/solver_control.h>
29 #include <deal.II/lac/solver_gmres.h>
30 #include <deal.II/lac/solver_minres.h>
31 #include <deal.II/lac/solver_richardson.h>
32 #include <deal.II/lac/vector.h>
33
34 DEAL_II_NAMESPACE_OPEN
35
36
37 /**
38 * @addtogroup Solvers
39 * @{
40 */
41
42 /**
43 * Selects a solver by changing a parameter.
44 *
45 * By calling the @p solve function of this @p SolverSelector, it selects the
46 * @p solve function of that @p Solver that was specified in the constructor
47 * of this class.
48 *
49 * <h3>Usage</h3> The simplest use of this class is the following:
50 * @code
51 * // generate a @p SolverSelector that calls the @p SolverCG
52 * SolverControl control;
53 * SolverSelector<Vector<double> > solver_selector ("cg", control);
54 *
55 * // generate e.g. a @p PreconditionRelaxation
56 * PreconditionRelaxation<SparseMatrix<double>, Vector<double> >
57 * preconditioning(
58 * A, &SparseMatrix<double>::template precondition_SSOR<double>,0.8);
59 *
60 * // call the @p solve function with this preconditioning as last argument
61 * solver_selector.solve(A,x,b,preconditioning);
62 * @endcode
63 * But the full usefulness of the @p SolverSelector class is not clear until
64 * the presentation of the following example that assumes the user using the
65 * @p ParameterHandler class and having declared a "solver" entry, e.g. with
66 * @code
67 * Parameter_Handler prm;
68 * prm.declare_entry ("solver", "none",
69 * Patterns::Selection(
70 * SolverSelector<>::get_solver_names()));
71 * ...
72 * @endcode
73 * Assuming that in the users parameter file there exists the line
74 * @code
75 * set solver = cg
76 * @endcode
77 * then the constructor call in the above example can be written as
78 * @code
79 * SolverSelector<SparseMatrix<double>, Vector<double> >
80 * solver_selector(prm.get("solver"), control);
81 * @endcode
82 *
83 *
84 * If at some time there exists a new solver "xyz" then the user does not need
85 * to change their program. Only in the implementation of the @p SolverSelector
86 * the calling of this solver has to be added and each user with program lines
87 * quoted above only needs to 'set solver = xyz' in their parameter file to get
88 * access to that new solver.
89 */
90 template <typename VectorType = Vector<double>>
91 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
92 class SolverSelector : public EnableObserverPointer
93 {
94 public:
95 /**
96 * An alias for the underlying vector type
97 */
98 using vector_type = VectorType;
99
100 /**
101 * Constructor, filling in default values
102 */
103 SolverSelector() = default;
104
105 /**
106 * Constructor, selecting the solver @p name
107 * and the SolverControl object @p control already.
108 */
109 SolverSelector(const std::string &name, SolverControl &control);
110
111 /**
112 * Destructor
113 */
114 virtual ~SolverSelector() override = default;
115
116 /**
117 * Solver procedure. Calls the @p solve function of the @p solver whose @p
118 * SolverName was specified in the constructor.
119 */
120 template <typename MatrixType, typename PreconditionerType>
121 DEAL_II_CXX20_REQUIRES(
122 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
123 concepts::is_linear_operator_on<PreconditionerType, VectorType>))
124 void solve(const MatrixType &A,
125 VectorType &x,
126 const VectorType &b,
127 const PreconditionerType &precond) const;
128
129 /**
130 * Select a new solver. Note that all solver names used in this class are
131 * all lower case.
132 */
133 void
134 select(const std::string &name);
135
136 /**
137 * Set a new SolverControl. This needs to be set before solving.
138 */
139 void
140 set_control(SolverControl &ctrl);
141
142 /**
143 * Set the additional data. For more information see the @p Solver class.
144 */
145 void
146 set_data(const typename SolverRichardson<VectorType>::AdditionalData &data);
147
148 /**
149 * Set the additional data. For more information see the @p Solver class.
150 */
151 void
152 set_data(const typename SolverCG<VectorType>::AdditionalData &data);
153
154 /**
155 * Set the additional data. For more information see the @p Solver class.
156 */
157 void
158 set_data(const typename SolverMinRes<VectorType>::AdditionalData &data);
159
160 /**
161 * Set the additional data. For more information see the @p Solver class.
162 */
163 void
164 set_data(const typename SolverBicgstab<VectorType>::AdditionalData &data);
165
166 /**
167 * Set the additional data. For more information see the @p Solver class.
168 */
169 void
170 set_data(const typename SolverGMRES<VectorType>::AdditionalData &data);
171
172 /**
173 * Set the additional data. For more information see the @p Solver class.
174 */
175 void
176 set_data(const typename SolverFGMRES<VectorType>::AdditionalData &data);
177
178 /**
179 * Get the names of all implemented solvers. The list of possible
180 * options includes:
181 * <ul>
182 * <li> "richardson" </li>
183 * <li> "cg" </li>
184 * <li> "bicgstab" </li>
185 * <li> "gmres" </li>
186 * <li> "fgmres" </li>
187 * <li> "minres" </li>
188 * </ul>
189 */
190 static std::string
191 get_solver_names();
192
193 /**
194 * Exception.
195 */
196 DeclException1(ExcSolverDoesNotExist,
197 std::string,
198 << "Solver " << arg1 << " does not exist. Use one of "
199 << std::endl
200 << get_solver_names());
201
202
203
204 protected:
205 /**
206 * Stores the @p SolverControl that is needed in the constructor of each @p
207 * Solver class. This can be changed with @p set_control().
208 */
209 ObserverPointer<SolverControl, SolverSelector<VectorType>> control;
210
211 /**
212 * Stores the name of the solver.
213 */
214 std::string solver_name;
215
216 private:
217 /**
218 * Stores the additional data.
219 */
220 typename SolverRichardson<VectorType>::AdditionalData richardson_data;
221
222 /**
223 * Stores the additional data.
224 */
225 typename SolverCG<VectorType>::AdditionalData cg_data;
226
227 /**
228 * Stores the additional data.
229 */
230 typename SolverMinRes<VectorType>::AdditionalData minres_data;
231
232 /**
233 * Stores the additional data.
234 */
235 typename SolverBicgstab<VectorType>::AdditionalData bicgstab_data;
236
237 /**
238 * Stores the additional data.
239 */
240 typename SolverGMRES<VectorType>::AdditionalData gmres_data;
241
242 /**
243 * Stores the additional data.
244 */
245 typename SolverFGMRES<VectorType>::AdditionalData fgmres_data;
246 };
247
248 /** @} */
249 /* --------------------- Inline and template functions ------------------- */
250
251
252 template <typename VectorType>
253 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
254 SolverSelector<VectorType>::SolverSelector(const std::string &name,
255 SolverControl &solver_control)
256 : solver_name(name)
257 , control(&solver_control)
258 {}
259
260
261
262 template <typename VectorType>
263 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
264 void SolverSelector<VectorType>::select(const std::string &name)
265 {
266 solver_name = name;
267 }
268
269
270
271 template <typename VectorType>
272 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
273 template <typename MatrixType, typename PreconditionerType>
274 DEAL_II_CXX20_REQUIRES(
275 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
276 concepts::is_linear_operator_on<PreconditionerType, VectorType>))
277 void SolverSelector<VectorType>::solve(const MatrixType &A,
278 VectorType &x,
279 const VectorType &b,
280 const PreconditionerType &precond) const
281 {
282 if (solver_name == "richardson")
283 {
284 SolverRichardson<VectorType> solver(*control, richardson_data);
285 solver.solve(A, x, b, precond);
286 }
287 else if (solver_name == "cg")
288 {
289 SolverCG<VectorType> solver(*control, cg_data);
290 solver.solve(A, x, b, precond);
291 }
292 else if (solver_name == "minres")
293 {
294 SolverMinRes<VectorType> solver(*control, minres_data);
295 solver.solve(A, x, b, precond);
296 }
297 else if (solver_name == "bicgstab")
298 {
299 SolverBicgstab<VectorType> solver(*control, bicgstab_data);
300 solver.solve(A, x, b, precond);
301 }
302 else if (solver_name == "gmres")
303 {
304 SolverGMRES<VectorType> solver(*control, gmres_data);
305 solver.solve(A, x, b, precond);
306 }
307 else if (solver_name == "fgmres")
308 {
309 SolverFGMRES<VectorType> solver(*control, fgmres_data);
310 solver.solve(A, x, b, precond);
311 }
312 else
313 Assert(false, ExcSolverDoesNotExist(solver_name));
314 }
315
316
317
318 template <typename VectorType>
319 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
320 void SolverSelector<VectorType>::set_control(SolverControl &ctrl)
321 {
322 control = &ctrl;
323 }
324
325
326
327 template <typename VectorType>
328 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
329 std::string SolverSelector<VectorType>::get_solver_names()
330 {
331 return "richardson|cg|bicgstab|gmres|fgmres|minres";
332 }
333
334
335
336 template <typename VectorType>
337 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
338 void SolverSelector<VectorType>::set_data(
339 const typename SolverGMRES<VectorType>::AdditionalData &data)
340 {
341 gmres_data = data;
342 }
343
344
345
346 template <typename VectorType>
347 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
348 void SolverSelector<VectorType>::set_data(
349 const typename SolverFGMRES<VectorType>::AdditionalData &data)
350 {
351 fgmres_data = data;
352 }
353
354
355
356 template <typename VectorType>
357 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
358 void SolverSelector<VectorType>::set_data(
359 const typename SolverRichardson<VectorType>::AdditionalData &data)
360 {
361 richardson_data = data;
362 }
363
364
365
366 template <typename VectorType>
367 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
368 void SolverSelector<VectorType>::set_data(
369 const typename SolverCG<VectorType>::AdditionalData &data)
370 {
371 cg_data = data;
372 }
373
374
375
376 template <typename VectorType>
377 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
378 void SolverSelector<VectorType>::set_data(
379 const typename SolverMinRes<VectorType>::AdditionalData &data)
380 {
381 minres_data = data;
382 }
383
384
385
386 template <typename VectorType>
387 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
388 void SolverSelector<VectorType>::set_data(
389 const typename SolverBicgstab<VectorType>::AdditionalData &data)
390 {
391 bicgstab_data = data;
392 }
393
394 DEAL_II_NAMESPACE_CLOSE
395
396 #endif