Debian Codegraph @

include/deal.II/lac/solver_richardson.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_richardson_h
16 #define dealii_solver_richardson_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/logstream.h>
22 #include <deal.II/base/signaling_nan.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 #include <limits>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * @addtogroup Solvers
34 * @{
35 */
36
37 /**
38 * Implementation of the preconditioned Richardson iteration method. The
39 * stopping criterion is the norm of the residual.
40 *
41 * For the requirements on matrices and vectors in order to work with this
42 * class, see the documentation of the Solver base class.
43 *
44 * Like all other solver classes, this class has a local structure called @p
45 * AdditionalData which is used to pass additional parameters to the solver,
46 * like damping parameters or the number of temporary vectors. We use this
47 * additional structure instead of passing these values directly to the
48 * constructor because this makes the use of the @p SolverSelector and other
49 * classes much easier and guarantees that these will continue to work even if
50 * number or type of the additional parameters for a certain solver changes.
51 *
52 * For the Richardson method, the additional data is the damping parameter,
53 * which is the only content of the @p AdditionalData structure. By default,
54 * the constructor of the structure sets it to one.
55 *
56 *
57 * <h3>Observing the progress of linear solver iterations</h3>
58 *
59 * The solve() function of this class uses the mechanism described in the
60 * Solver base class to determine convergence. This mechanism can also be used
61 * to observe the progress of the iteration.
62 */
63 template <typename VectorType = Vector<double>>
64 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
65 class SolverRichardson : public SolverBase<VectorType>
66 {
67 public:
68 /**
69 * Standardized data struct to pipe additional data to the solver.
70 */
71 struct AdditionalData
72 {
73 /**
74 * Constructor. By default, set the damping parameter to one.
75 */
76 explicit AdditionalData(const double omega = 1,
77 const bool use_preconditioned_residual = false);
78
79 /**
80 * Relaxation parameter.
81 */
82 double omega;
83
84 /**
85 * Parameter for stopping criterion.
86 */
87 bool use_preconditioned_residual;
88 };
89
90 /**
91 * Constructor.
92 */
93 SolverRichardson(SolverControl &cn,
94 VectorMemory<VectorType> &mem,
95 const AdditionalData &data = AdditionalData());
96
97 /**
98 * Constructor. Use an object of type GrowingVectorMemory as a default to
99 * allocate memory.
100 */
101 SolverRichardson(SolverControl &cn,
102 const AdditionalData &data = AdditionalData());
103
104 /**
105 * Virtual destructor.
106 */
107 virtual ~SolverRichardson() override = default;
108
109 /**
110 * Solve the linear system $Ax=b$ for x.
111 */
112 template <typename MatrixType, typename PreconditionerType>
113 DEAL_II_CXX20_REQUIRES(
114 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
115 concepts::is_linear_operator_on<PreconditionerType, VectorType>))
116 void solve(const MatrixType &A,
117 VectorType &x,
118 const VectorType &b,
119 const PreconditionerType &preconditioner);
120
121 /**
122 * Solve $A^Tx=b$ for $x$.
123 */
124 template <typename MatrixType, typename PreconditionerType>
125 DEAL_II_CXX20_REQUIRES(
126 (concepts::is_transpose_linear_operator_on<MatrixType, VectorType> &&
127 concepts::is_transpose_linear_operator_on<PreconditionerType, VectorType>))
128 void Tsolve(const MatrixType &A,
129 VectorType &x,
130 const VectorType &b,
131 const PreconditionerType &preconditioner);
132
133 /**
134 * Set the damping-coefficient. Default is 1., i.e. no damping.
135 */
136 void
137 set_omega(const double om = 1.);
138
139 /**
140 * Interface for derived class. This function gets the current iteration
141 * vector, the residual and the update vector in each step. It can be used
142 * for graphical output of the convergence history.
143 */
144 virtual void
145 print_vectors(const unsigned int step,
146 const VectorType &x,
147 const VectorType &r,
148 const VectorType &d) const;
149
150 protected:
151 /**
152 * Implementation of the computation of the norm of the residual.
153 * Depending on the flags given to the solver, the default
154 * implementation of this function uses either the actual
155 * residual, @p r, or the preconditioned residual, @p d.
156 */
157 virtual typename VectorType::value_type
158 criterion(const VectorType &r, const VectorType &d) const;
159
160 /**
161 * Control parameters.
162 */
163 AdditionalData additional_data;
164 };
165
166 /** @} */
167 /*----------------- Implementation of the Richardson Method ------------------*/
168
169 #ifndef DOXYGEN
170
171 template <typename VectorType>
172 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
173 inline SolverRichardson<VectorType>::AdditionalData::AdditionalData(
174 const double omega,
175 const bool use_preconditioned_residual)
176 : omega(omega)
177 , use_preconditioned_residual(use_preconditioned_residual)
178 {}
179
180
181 template <typename VectorType>
182 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
183 SolverRichardson<VectorType>::SolverRichardson(SolverControl &cn,
184 VectorMemory<VectorType> &mem,
185 const AdditionalData &data)
186 : SolverBase<VectorType>(cn, mem)
187 , additional_data(data)
188 {}
189
190
191
192 template <typename VectorType>
193 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
194 SolverRichardson<VectorType>::SolverRichardson(SolverControl &cn,
195 const AdditionalData &data)
196 : SolverBase<VectorType>(cn)
197 , additional_data(data)
198 {}
199
200
201
202 template <typename VectorType>
203 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
204 template <typename MatrixType, typename PreconditionerType>
205 DEAL_II_CXX20_REQUIRES(
206 (concepts::is_linear_operator_on<MatrixType, VectorType> &&
207 concepts::is_linear_operator_on<PreconditionerType, VectorType>))
208 void SolverRichardson<VectorType>::solve(
209 const MatrixType &A,
210 VectorType &x,
211 const VectorType &b,
212 const PreconditionerType &preconditioner)
213 {
214 SolverControl::State conv = SolverControl::iterate;
215
216 double last_criterion = std::numeric_limits<double>::lowest();
217
218 unsigned int iter = 0;
219
220 // Memory allocation.
221 // 'Vr' holds the residual, 'Vd' the preconditioned residual
222 typename VectorMemory<VectorType>::Pointer Vr(this->memory);
223 typename VectorMemory<VectorType>::Pointer Vd(this->memory);
224
225 VectorType &r = *Vr;
226 r.reinit(x);
227
228 VectorType &d = *Vd;
229 d.reinit(x);
230
231 LogStream::Prefix prefix("Richardson");
232
233 // Main loop
234 while (conv == SolverControl::iterate)
235 {
236 // Do not use residual,
237 // but do it in 2 steps
238 A.vmult(r, x);
239 r.sadd(-1., 1., b);
240 preconditioner.vmult(d, r);
241
242 // get the required norm of the (possibly preconditioned)
243 // residual
244 last_criterion = criterion(r, d);
245 conv = this->iteration_status(iter, last_criterion, x);
246 if (conv != SolverControl::iterate)
247 break;
248
249 x.add(additional_data.omega, d);
250 print_vectors(iter, x, r, d);
251
252 ++iter;
253 }
254
255 // in case of failure: throw exception
256 if (conv != SolverControl::success)
257 AssertThrow(false, SolverControl::NoConvergence(iter, last_criterion));
258 // otherwise exit as normal
259 }
260
261
262
263 template <typename VectorType>
264 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
265 template <typename MatrixType, typename PreconditionerType>
266 DEAL_II_CXX20_REQUIRES(
267 (concepts::is_transpose_linear_operator_on<MatrixType, VectorType> &&
268 concepts::is_transpose_linear_operator_on<PreconditionerType, VectorType>))
269 void SolverRichardson<VectorType>::Tsolve(
270 const MatrixType &A,
271 VectorType &x,
272 const VectorType &b,
273 const PreconditionerType &preconditioner)
274 {
275 SolverControl::State conv = SolverControl::iterate;
276 double last_criterion = std::numeric_limits<double>::lowest();
277
278 unsigned int iter = 0;
279
280 // Memory allocation.
281 // 'Vr' holds the residual, 'Vd' the preconditioned residual
282 typename VectorMemory<VectorType>::Pointer Vr(this->memory);
283 typename VectorMemory<VectorType>::Pointer Vd(this->memory);
284
285 VectorType &r = *Vr;
286 r.reinit(x);
287
288 VectorType &d = *Vd;
289 d.reinit(x);
290
291 LogStream::Prefix prefix("RichardsonT");
292
293 // Main loop
294 while (conv == SolverControl::iterate)
295 {
296 // Do not use Tresidual,
297 // but do it in 2 steps
298 A.Tvmult(r, x);
299 r.sadd(-1., 1., b);
300 preconditioner.Tvmult(d, r);
301
302 last_criterion = criterion(r, d);
303 conv = this->iteration_status(iter, last_criterion, x);
304 if (conv != SolverControl::iterate)
305 break;
306
307 x.add(additional_data.omega, d);
308 print_vectors(iter, x, r, d);
309
310 ++iter;
311 }
312
313 // in case of failure: throw exception
314 if (conv != SolverControl::success)
315 AssertThrow(false, SolverControl::NoConvergence(iter, last_criterion));
316
317 // otherwise exit as normal
318 }
319
320
321
322 template <typename VectorType>
323 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
324 void SolverRichardson<VectorType>::print_vectors(const unsigned int,
325 const VectorType &,
326 const VectorType &,
327 const VectorType &) const
328 {}
329
330
331
332 template <typename VectorType>
333 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
334 inline typename VectorType::value_type
335 SolverRichardson<VectorType>::criterion(const VectorType &r,
336 const VectorType &d) const
337 {
338 if (!additional_data.use_preconditioned_residual)
339 return r.l2_norm();
340 else
341 return d.l2_norm();
342 }
343
344
345 template <typename VectorType>
346 DEAL_II_CXX20_REQUIRES(concepts::is_vector_space_vector<VectorType>)
347 inline void SolverRichardson<VectorType>::set_omega(const double om)
348 {
349 additional_data.omega = om;
350 }
351
352 #endif // DOXYGEN
353
354 DEAL_II_NAMESPACE_CLOSE
355
356 #endif