Debian Codegraph @

include/deal.II/lac/ginkgo_solver.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 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_ginkgo_solver_h
16 #define dealii_ginkgo_solver_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_GINKGO
22
23 # include <deal.II/lac/block_sparse_matrix.h>
24 # include <deal.II/lac/exceptions.h>
25 # include <deal.II/lac/solver_control.h>
26 # include <deal.II/lac/sparse_matrix.h>
27 # include <deal.II/lac/vector.h>
28
29 # include <ginkgo/ginkgo.hpp>
30
31 # include <memory>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 namespace GinkgoWrappers
36 {
37 /**
38 * This class forms the base class for all of Ginkgo's iterative solvers.
39 * The various derived classes only take
40 * the additional data that is specific to them and solve the given linear
41 * system. The entire collection of solvers that Ginkgo implements is
42 * available at <a Ginkgo
43 * href="https://ginkgo-project.github.io/ginkgo/doc/develop/"> documentation
44 * and manual pages</a>.
45 */
46 template <typename ValueType, typename IndexType>
47 class SolverBase
48 {
49 public:
50 /**
51 * Constructor.
52 *
53 * The @p exec_type defines the paradigm where the solution is computed.
54 * It is a string and the choices are "omp" , "reference" or "cuda".
55 * The respective strings create the respective executors as given below.
56 *
57 * Ginkgo currently supports three different executor types:
58 *
59 * + OmpExecutor specifies that the data should be stored and the
60 * associated operations executed on an OpenMP-supporting device (e.g. host
61 * CPU);
62 * ```
63 * auto omp = gko::create<gko::OmpExecutor>();
64 * ```
65 * + CudaExecutor specifies that the data should be stored and the
66 * operations executed on the NVIDIA GPU accelerator;
67 * ```
68 * if(gko::CudaExecutor::get_num_devices() > 0 ) {
69 * auto cuda = gko::create<gko::CudaExecutor>();
70 * }
71 * ```
72 * + ReferenceExecutor executes a non-optimized reference implementation,
73 * which can be used to debug the library.
74 * ```
75 * auto ref = gko::create<gko::ReferenceExecutor>();
76 * ```
77 *
78 * The following code snippet demonstrates the using of the OpenMP executor
79 * to create a solver which would use the OpenMP paradigm to the solve the
80 * system on the CPU.
81 *
82 * ```
83 * auto omp = gko::create<gko::OmpExecutor>();
84 * using cg = gko::solver::Cg<>;
85 * auto solver_gen =
86 * cg::build()
87 * .with_criteria(
88 * gko::stop::Iteration::build().with_max_iters(20u).on(omp),
89 * gko::stop::ResidualNormReduction<>::build()
90 * .with_reduction_factor(1e-6)
91 * .on(omp))
92 * .on(omp);
93 * auto solver = solver_gen->generate(system_matrix);
94 *
95 * solver->apply(lend(rhs), lend(solution));
96 * ```
97 *
98 *
99 * The @p solver_control object is the same as for other
100 * deal.II iterative solvers.
101 */
102 SolverBase(SolverControl &solver_control, const std::string &exec_type);
103
104 /**
105 * Destructor.
106 */
107 virtual ~SolverBase() = default;
108
109 /**
110 * Initialize the matrix and copy over its data to Ginkgo's data structures.
111 */
112 void
113 initialize(const SparseMatrix<ValueType> &matrix);
114
115 /**
116 * Solve the linear system <tt>Ax=b</tt>. Dependent on the information
117 * provided by derived classes one of Ginkgo's linear solvers is
118 * chosen.
119 */
120 void
121 apply(Vector<ValueType> &solution, const Vector<ValueType> &rhs);
122
123 /**
124 * Solve the linear system <tt>Ax=b</tt>. Dependent on the information
125 * provided by derived classes one of Ginkgo's linear solvers is
126 * chosen.
127 */
128 void
129 solve(const SparseMatrix<ValueType> &matrix,
130 Vector<ValueType> &solution,
131 const Vector<ValueType> &rhs);
132
133 /**
134 * Access to the object that controls convergence.
135 */
136 SolverControl &
137 control() const;
138
139
140 protected:
141 /**
142 * Reference to the object that controls convergence of the iterative
143 * solvers.
144 */
145 SolverControl &solver_control;
146
147 /**
148 * The Ginkgo generated solver factory object.
149 */
150 std::shared_ptr<gko::LinOpFactory> solver_gen;
151
152 /**
153 * The residual criterion object that controls the reduction of the residual
154 * based on the tolerance set in the solver_control member.
155 */
156 std::shared_ptr<gko::stop::ResidualNormReduction<>::Factory>
157 residual_criterion;
158
159 /**
160 * The Ginkgo convergence logger used to check for convergence and other
161 * solver data if needed.
162 */
163 std::shared_ptr<gko::log::Convergence<>> convergence_logger;
164
165 /**
166 * The Ginkgo combined factory object is used to create a combined stopping
167 * criterion to be passed to the solver.
168 */
169 std::shared_ptr<gko::stop::Combined::Factory> combined_factory;
170
171 /**
172 * The execution paradigm in Ginkgo. The choices are between
173 * `gko::OmpExecutor`, `gko::CudaExecutor` and `gko::ReferenceExecutor`
174 * and more details can be found in Ginkgo's documentation.
175 */
176 std::shared_ptr<gko::Executor> executor;
177
178 private:
179 /**
180 * Initialize the Ginkgo logger object with event masks. Refer to
181 * <a
182 * href="https://github.com/ginkgo-project/ginkgo/blob/develop/include/ginkgo/core/log/logger.hpp">Ginkgo's
183 * logging event masks.</a>
184 */
185 void
186 initialize_ginkgo_log();
187
188 /**
189 * Ginkgo matrix data structure. First template parameter is for storing the
190 * array of the non-zeros of the matrix. The second is for the row pointers
191 * and the column indices.
192 *
193 * @todo Templatize based on Matrix type.
194 */
195 std::shared_ptr<gko::matrix::Csr<ValueType, IndexType>> system_matrix;
196
197 /**
198 * The execution paradigm as a string to be set by the user. The choices
199 * are between `omp`, `cuda` and `reference` and more details can be found
200 * in Ginkgo's documentation.
201 */
202 const std::string exec_type;
203 };
204
205
206 /**
207 * An implementation of the solver interface using the Ginkgo CG solver.
208 */
209 template <typename ValueType = double, typename IndexType = int32_t>
210 class SolverCG : public SolverBase<ValueType, IndexType>
211 {
212 public:
213 /**
214 * A standardized data struct to pipe additional data to the solver.
215 */
216 struct AdditionalData
217 {};
218
219 /**
220 * Constructor.
221 *
222 * @param[in,out] solver_control The solver control object is then used to
223 * set the parameters and set up the CG solver from the CG factory which
224 * solves the linear system.
225 *
226 * @param[in] exec_type The execution paradigm for the CG solver.
227 *
228 * @param[in] data The additional data required by the solver.
229 */
230 SolverCG(SolverControl &solver_control,
231 const std::string &exec_type,
232 const AdditionalData &data = AdditionalData());
233
234 /**
235 * Constructor.
236 *
237 * @param[in,out] solver_control The solver control object is then used to
238 * set the parameters and set up the CG solver from the CG factory which
239 * solves the linear system.
240 *
241 * @param[in] exec_type The execution paradigm for the CG solver.
242 *
243 * @param[in] preconditioner The preconditioner for the solver.
244 *
245 * @param[in] data The additional data required by the solver.
246 */
247 SolverCG(SolverControl &solver_control,
248 const std::string &exec_type,
249 const std::shared_ptr<gko::LinOpFactory> &preconditioner,
250 const AdditionalData &data = AdditionalData());
251
252 protected:
253 /**
254 * Store a copy of the settings for this particular solver.
255 */
256 const AdditionalData additional_data;
257 };
258
259
260 /**
261 * An implementation of the solver interface using the Ginkgo Bicgstab solver.
262 */
263 template <typename ValueType = double, typename IndexType = int32_t>
264 class SolverBicgstab : public SolverBase<ValueType, IndexType>
265 {
266 public:
267 /**
268 * A standardized data struct to pipe additional data to the solver.
269 */
270 struct AdditionalData
271 {};
272
273 /**
274 * Constructor.
275 *
276 * @param[in,out] solver_control The solver control object is then used to
277 * set the parameters and set up the Bicgstab solver from the Bicgstab
278 * factory which solves the linear system.
279 *
280 * @param[in] exec_type The execution paradigm for the Bicgstab solver.
281 *
282 * @param[in] data The additional data required by the solver.
283 */
284 SolverBicgstab(SolverControl &solver_control,
285 const std::string &exec_type,
286 const AdditionalData &data = AdditionalData());
287
288 /**
289 * Constructor.
290 *
291 * @param[in,out] solver_control The solver control object is then used to
292 * set the parameters and set up the Bicgstab solver from the Bicgstab
293 * factory which solves the linear system.
294 *
295 * @param[in] exec_type The execution paradigm for the Bicgstab solver.
296 *
297 * @param[in] preconditioner The preconditioner for the solver.
298 *
299 * @param[in] data The additional data required by the solver.
300 */
301 SolverBicgstab(SolverControl &solver_control,
302 const std::string &exec_type,
303 const std::shared_ptr<gko::LinOpFactory> &preconditioner,
304 const AdditionalData &data = AdditionalData());
305
306 protected:
307 /**
308 * Store a copy of the settings for this particular solver.
309 */
310 const AdditionalData additional_data;
311 };
312
313 /**
314 * An implementation of the solver interface using the Ginkgo CGS solver.
315 *
316 * CGS or the conjugate gradient square method is an iterative type Krylov
317 * subspace method which is suitable for general systems.
318 */
319 template <typename ValueType = double, typename IndexType = int32_t>
320 class SolverCGS : public SolverBase<ValueType, IndexType>
321 {
322 public:
323 /**
324 * A standardized data struct to pipe additional data to the solver.
325 */
326 struct AdditionalData
327 {};
328
329 /**
330 * Constructor.
331 *
332 * @param[in,out] solver_control The solver control object is then used to
333 * set the parameters and set up the CGS solver from the CGS factory which
334 * solves the linear system.
335 *
336 * @param[in] exec_type The execution paradigm for the CGS solver.
337 *
338 * @param[in] data The additional data required by the solver.
339 */
340 SolverCGS(SolverControl &solver_control,
341 const std::string &exec_type,
342 const AdditionalData &data = AdditionalData());
343
344 /**
345 * Constructor.
346 *
347 * @param[in,out] solver_control The solver control object is then used to
348 * set the parameters and set up the CGS solver from the CGS factory which
349 * solves the linear system.
350 *
351 * @param[in] exec_type The execution paradigm for the CGS solver.
352 *
353 * @param[in] preconditioner The preconditioner for the solver.
354 *
355 * @param[in] data The additional data required by the solver.
356 */
357 SolverCGS(SolverControl &solver_control,
358 const std::string &exec_type,
359 const std::shared_ptr<gko::LinOpFactory> &preconditioner,
360 const AdditionalData &data = AdditionalData());
361
362 protected:
363 /**
364 * Store a copy of the settings for this particular solver.
365 */
366 const AdditionalData additional_data;
367 };
368
369 /**
370 * An implementation of the solver interface using the Ginkgo FCG solver.
371 *
372 * FCG or the flexible conjugate gradient method is an iterative type Krylov
373 * subspace method which is suitable for symmetric positive definite methods.
374 *
375 * Though this method performs very well for symmetric positive definite
376 * matrices, it is in general not suitable for general matrices.
377 *
378 * In contrast to the standard CG based on the Polack-Ribiere formula, the
379 * flexible CG uses the Fletcher-Reeves formula for creating the orthonormal
380 * vectors spanning the Krylov subspace. This increases the computational cost
381 * of every Krylov solver iteration but allows for non-constant
382 * preconditioners.
383 */
384 template <typename ValueType = double, typename IndexType = int32_t>
385 class SolverFCG : public SolverBase<ValueType, IndexType>
386 {
387 public:
388 /**
389 * A standardized data struct to pipe additional data to the solver.
390 */
391 struct AdditionalData
392 {};
393
394 /**
395 * Constructor.
396 *
397 * @param[in,out] solver_control The solver control object is then used to
398 * set the parameters and set up the FCG solver from the FCG factory which
399 * solves the linear system.
400 *
401 * @param[in] exec_type The execution paradigm for the FCG solver.
402 *
403 * @param[in] data The additional data required by the solver.
404 */
405 SolverFCG(SolverControl &solver_control,
406 const std::string &exec_type,
407 const AdditionalData &data = AdditionalData());
408
409 /**
410 * Constructor.
411 *
412 * @param[in,out] solver_control The solver control object is then used to
413 * set the parameters and set up the FCG solver from the FCG factory which
414 * solves the linear system.
415 *
416 * @param[in] exec_type The execution paradigm for the FCG solver.
417 *
418 * @param[in] preconditioner The preconditioner for the solver.
419 *
420 * @param[in] data The additional data required by the solver.
421 */
422 SolverFCG(SolverControl &solver_control,
423 const std::string &exec_type,
424 const std::shared_ptr<gko::LinOpFactory> &preconditioner,
425 const AdditionalData &data = AdditionalData());
426
427 protected:
428 /**
429 * Store a copy of the settings for this particular solver.
430 */
431 const AdditionalData additional_data;
432 };
433
434 /**
435 * An implementation of the solver interface using the Ginkgo GMRES solver.
436 */
437 template <typename ValueType = double, typename IndexType = int32_t>
438 class SolverGMRES : public SolverBase<ValueType, IndexType>
439 {
440 public:
441 /**
442 * A standardized data struct to pipe additional data to the solver.
443 */
444 struct AdditionalData
445 {
446 /**
447 * Constructor. By default, set the number of temporary vectors to 30,
448 * i.e. do a restart every 30 iterations.
449 */
450 AdditionalData(const unsigned int restart_parameter = 30);
451
452 /**
453 * Maximum number of tmp vectors.
454 */
455 unsigned int restart_parameter;
456 };
457
458 /**
459 * Constructor.
460 *
461 * @param[in,out] solver_control The solver control object is then used to
462 * set the parameters and set up the GMRES solver from the GMRES factory
463 * which solves the linear system.
464 *
465 * @param[in] exec_type The execution paradigm for the GMRES solver.
466 *
467 * @param[in] data The additional data required by the solver.
468 */
469 SolverGMRES(SolverControl &solver_control,
470 const std::string &exec_type,
471 const AdditionalData &data = AdditionalData());
472
473 /**
474 * Constructor.
475 *
476 * @param[in,out] solver_control The solver control object is then used to
477 * set the parameters and set up the GMRES solver from the GMRES factory
478 * which solves the linear system.
479 *
480 * @param[in] exec_type The execution paradigm for the GMRES solver.
481 *
482 * @param[in] preconditioner The preconditioner for the solver.
483 *
484 * @param[in] data The additional data required by the solver.
485 */
486 SolverGMRES(SolverControl &solver_control,
487 const std::string &exec_type,
488 const std::shared_ptr<gko::LinOpFactory> &preconditioner,
489 const AdditionalData &data = AdditionalData());
490
491 protected:
492 /**
493 * Store a copy of the settings for this particular solver.
494 */
495 const AdditionalData additional_data;
496 };
497
498 /**
499 * An implementation of the solver interface using the Ginkgo IR solver.
500 *
501 * Iterative refinement (IR) is an iterative method that uses another coarse
502 * method to approximate the error of the current solution via the current
503 * residual.
504 */
505 template <typename ValueType = double, typename IndexType = int32_t>
506 class SolverIR : public SolverBase<ValueType, IndexType>
507 {
508 public:
509 /**
510 * A standardized data struct to pipe additional data to the solver.
511 */
512 struct AdditionalData
513 {};
514
515 /**
516 * Constructor.
517 *
518 * @param[in,out] solver_control The solver control object is then used to
519 * set the parameters and set up the IR solver from the IR factory which
520 * solves the linear system.
521 *
522 * @param[in] exec_type The execution paradigm for the IR solver.
523 *
524 * @param[in] data The additional data required by the solver.
525 */
526 SolverIR(SolverControl &solver_control,
527 const std::string &exec_type,
528 const AdditionalData &data = AdditionalData());
529
530 /**
531 * Constructor.
532 *
533 * @param[in,out] solver_control The solver control object is then used to
534 * set the parameters and set up the IR solver from the IR factory which
535 * solves the linear system.
536 *
537 * @param[in] exec_type The execution paradigm for the IR solver.
538 *
539 * @param[in] inner_solver The Inner solver for the IR solver.
540 *
541 * @param[in] data The additional data required by the solver.
542 */
543 SolverIR(SolverControl &solver_control,
544 const std::string &exec_type,
545 const std::shared_ptr<gko::LinOpFactory> &inner_solver,
546 const AdditionalData &data = AdditionalData());
547
548 protected:
549 /**
550 * Store a copy of the settings for this particular solver.
551 */
552 const AdditionalData additional_data;
553 };
554
555
556 } // namespace GinkgoWrappers
557
558 DEAL_II_NAMESPACE_CLOSE
559
560 #else
561
562 // Make sure the scripts that create the C++20 module input files have
563 // something to latch on if the preprocessor #ifdef above would
564 // otherwise lead to an empty content of the file.
565 DEAL_II_NAMESPACE_OPEN
566 DEAL_II_NAMESPACE_CLOSE
567
568 #endif // DEAL_II_WITH_GINKGO
569
570 #endif