Debian Codegraph @

include/deal.II/lac/solver_relaxation.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 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_relaxation_h
16 #define dealii_solver_relaxation_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/logstream.h>
23 #include <deal.II/base/template_constraints.h>
24
25 #include <deal.II/lac/solver.h>
26 #include <deal.II/lac/solver_control.h>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 /**
31 * Implementation of an iterative solver based on relaxation methods. The
32 * stopping criterion is the norm of the residual.
33 *
34 * For the requirements on matrices and vectors in order to work with this
35 * class, see the documentation of the Solver base class.
36 *
37 * Like all other solver classes, this class has a local structure called @p
38 * AdditionalData which is used to pass additional parameters to the solver,
39 * like damping parameters or the number of temporary vectors. We use this
40 * additional structure instead of passing these values directly to the
41 * constructor because this makes the use of the @p SolverSelector and other
42 * classes much easier and guarantees that these will continue to work even if
43 * number or type of the additional parameters for a certain solver changes.
44 * AdditionalData of this class currently does not contain any data.
45 *
46 *
47 * <h3>Observing the progress of linear solver iterations</h3>
48 *
49 * The solve() function of this class uses the mechanism described in the
50 * Solver base class to determine convergence. This mechanism can also be used
51 * to observe the progress of the iteration.
52 *
53 *
54 * @ingroup Solvers
55 */
56 template <typename VectorType = Vector<double>>
57 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
58 class SolverRelaxation : public SolverBase<VectorType>
59 {
60 public:
61 /**
62 * Standardized data struct to pipe additional data to the solver. There is
63 * no data in here for relaxation methods.
64 */
65 struct AdditionalData
66 {};
67
68 /**
69 * Constructor.
70 */
71 SolverRelaxation(SolverControl &cn,
72 const AdditionalData &data = AdditionalData());
73
74 /**
75 * Solve the system $Ax = b$ using the relaxation method $x_{k+1} =
76 * R(x_k,b)$. The matrix <i>A</i> itself is only used to compute the
77 * residual.
78 */
79 template <typename MatrixType, typename RelaxationType>
80 DEAL_II_CXX20_REQUIRES(
81 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
82 requires(const RelaxationType &R, VectorType &a, VectorType &b) {
83 R.step(a, b);
84 }))
85 void solve(const MatrixType &A,
86 VectorType &x,
87 const VectorType &b,
88 const RelaxationType &R);
89 };
90
91 //----------------------------------------------------------------------//
92
93 template <typename VectorType>
94 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
95 SolverRelaxation<VectorType>::SolverRelaxation(SolverControl &cn,
96 const AdditionalData &)
97 : SolverBase<VectorType>(cn)
98 {}
99
100
101
102 template <typename VectorType>
103 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
104 template <typename MatrixType, typename RelaxationType>
105 DEAL_II_CXX20_REQUIRES(
106 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
107 requires(const RelaxationType &R, VectorType &a, VectorType &b) {
108 R.step(a, b);
109 }))
110 void SolverRelaxation<VectorType>::solve(const MatrixType &A,
111 VectorType &x,
112 const VectorType &b,
113 const RelaxationType &R)
114 {
115 GrowingVectorMemory<VectorType> mem;
116 SolverControl::State conv = SolverControl::iterate;
117
118 // Memory allocation
119 typename VectorMemory<VectorType>::Pointer Vr(mem);
120 VectorType &r = *Vr;
121 r.reinit(x);
122 typename VectorMemory<VectorType>::Pointer Vd(mem);
123 VectorType &d = *Vd;
124 d.reinit(x);
125
126 LogStream::Prefix prefix("Relaxation");
127
128 int iter = 0;
129 // Main loop
130 for (; conv == SolverControl::iterate; ++iter)
131 {
132 // Compute residual
133 A.vmult(r, x);
134 r.sadd(-1., 1., b);
135
136 // The required norm of the
137 // (preconditioned)
138 // residual is computed in
139 // criterion() and stored
140 // in res.
141 conv = this->iteration_status(iter, r.l2_norm(), x);
142 if (conv != SolverControl::iterate)
143 break;
144 R.step(x, b);
145 }
146
147 // in case of failure: throw exception
148 AssertThrow(conv == SolverControl::success,
149 SolverControl::NoConvergence(iter, r.l2_norm()));
150 // otherwise exit as normal
151 }
152
153
154 DEAL_II_NAMESPACE_CLOSE
155
156 #endif