Debian Codegraph @

include/deal.II/lac/precondition_selector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_precondition_selector_h
16 #define dealii_precondition_selector_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/exceptions.h>
23 #include <deal.II/base/observer_pointer.h>
24
25 #include <string>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 // Forward declarations
30 #ifndef DOXYGEN
31 template <class number>
32 class Vector;
33 template <class number>
34 class SparseMatrix;
35 #endif
36
37
38 /**
39 * @addtogroup Preconditioners
40 * @{
41 */
42
43 /**
44 * Selects the preconditioner. The constructor of this class takes the name of
45 * the preconditioning and the damping parameter @p omega of the
46 * preconditioning and the @p use_matrix function takes the matrix that is
47 * used by the matrix-builtin precondition functions. Each time, the
48 * <tt>operator()</tt> function is called, this preselected preconditioner,
49 * this matrix and this @p omega is used for the preconditioning. This class
50 * is designed for being used as argument of the @p solve function of a @p
51 * Solver and it covers the selection of all matrix-builtin precondition
52 * functions. The selection of other preconditioners, like BlockSOR or ILU
53 * should be handled in derived classes by the user.
54 *
55 * <h3>Usage</h3> The simplest use of this class is the following:
56 * @code
57 * // generate a @p SolverControl and a @p VectorMemory
58 * SolverControl control;
59 * VectorMemory<Vector<double> > memory;
60 *
61 * // generate a solver
62 * SolverCG<SparseMatrix<double>, Vector<double> > solver(control, memory);
63 *
64 * // generate a @p PreconditionSelector
65 * PreconditionSelector<SparseMatrix<double>, Vector<double> >
66 * preconditioning("jacobi", 1.);
67 *
68 * // give a matrix whose diagonal entries are to be used for the
69 * // preconditioning. Generally the matrix of the linear equation system Ax=b.
70 * preconditioning.use_matrix(A);
71 *
72 * // call the @p solve function with this preconditioning as last argument
73 * solver.solve(A,x,b,preconditioning);
74 * @endcode
75 * The same example where also the @p SolverSelector class is used reads
76 * @code
77 * // generate a @p SolverControl and a @p VectorMemory
78 * SolverControl control;
79 * VectorMemory<Vector<double> > memory;
80 *
81 * // generate a @p SolverSelector that calls the @p SolverCG
82 * SolverSelector<SparseMatrix<double>, Vector<double> >
83 * solver_selector("cg", control, memory);
84 *
85 * // generate a @p PreconditionSelector
86 * PreconditionSelector<SparseMatrix<double>, Vector<double> >
87 * preconditioning("jacobi", 1.);
88 *
89 * preconditioning.use_matrix(A);
90 *
91 * solver_selector.solve(A,x,b,preconditioning);
92 * @endcode
93 * Now the use of the @p SolverSelector in combination with the @p
94 * PreconditionSelector allows the user to select both, the solver and the
95 * preconditioner, at the beginning of their program and each time the solver is
96 * started (that is several times e.g. in a nonlinear iteration) this
97 * preselected solver and preconditioner is called.
98 */
99 template <typename MatrixType = SparseMatrix<double>,
100 typename VectorType = dealii::Vector<double>>
101 class PreconditionSelector : public EnableObserverPointer
102 {
103 public:
104 /**
105 * Declare type for container size.
106 */
107 using size_type = typename MatrixType::size_type;
108
109 /**
110 * Constructor. @p omega denotes the damping parameter of the
111 * preconditioning.
112 */
113 PreconditionSelector(const std::string &preconditioning,
114 const typename VectorType::value_type &omega = 1.);
115
116 /**
117 * Destructor.
118 */
119 virtual ~PreconditionSelector() override;
120
121 /**
122 * Takes the matrix that is needed for preconditionings that involves a
123 * matrix. e.g. for @p precondition_jacobi, <tt>~_sor</tt>, <tt>~_ssor</tt>.
124 */
125 void
126 use_matrix(const MatrixType &M);
127
128 /**
129 * Return the dimension of the codomain (or range) space. Note that the
130 * matrix is of dimension $m \times n$.
131 */
132 size_type
133 m() const;
134
135 /**
136 * Return the dimension of the domain space. Note that the matrix is of
137 * dimension $m \times n$.
138 */
139 size_type
140 n() const;
141
142 /**
143 * Precondition procedure. Calls the preconditioning that was specified in
144 * the constructor.
145 */
146 virtual void
147 vmult(VectorType &dst, const VectorType &src) const;
148
149 /**
150 * Transpose precondition procedure. Calls the preconditioning that was
151 * specified in the constructor.
152 */
153 virtual void
154 Tvmult(VectorType &dst, const VectorType &src) const;
155
156 /**
157 * Get the names of all implemented preconditionings. The list of possible
158 * options includes:
159 * <ul>
160 * <li> "none" </li>
161 * <li> "jacobi" </li>
162 * <li> "sor" </li>
163 * <li> "ssor" </li>
164 * </ul>
165 */
166 static std::string
167 get_precondition_names();
168
169 /**
170 * @addtogroup Exceptions
171 * @{
172 */
173
174
175 /**
176 * Exception.
177 */
178 DeclException0(ExcNoMatrixGivenToUse);
179
180 /** @} */
181 protected:
182 /**
183 * Stores the name of the preconditioning.
184 */
185 std::string preconditioning;
186
187 private:
188 /**
189 * Matrix that is used for the matrix-builtin preconditioning function. cf.
190 * also @p PreconditionUseMatrix.
191 */
192 ObserverPointer<const MatrixType,
193 PreconditionSelector<MatrixType, VectorType>>
194 A;
195
196 /**
197 * Stores the damping parameter of the preconditioner.
198 */
199 const typename VectorType::value_type omega;
200 };
201
202 /** @} */
203 /* --------------------- Inline and template functions ------------------- */
204
205
206 template <typename MatrixType, typename VectorType>
207 PreconditionSelector<MatrixType, VectorType>::PreconditionSelector(
208 const std::string &preconditioning,
209 const typename VectorType::value_type &omega)
210 : preconditioning(preconditioning)
211 , omega(omega)
212 {}
213
214
215 template <typename MatrixType, typename VectorType>
216 PreconditionSelector<MatrixType, VectorType>::~PreconditionSelector()
217 {
218 // release the matrix A
219 A = nullptr;
220 }
221
222
223 template <typename MatrixType, typename VectorType>
224 void
225 PreconditionSelector<MatrixType, VectorType>::use_matrix(const MatrixType &M)
226 {
227 A = &M;
228 }
229
230
231 template <typename MatrixType, typename VectorType>
232 inline typename PreconditionSelector<MatrixType, VectorType>::size_type
233 PreconditionSelector<MatrixType, VectorType>::m() const
234 {
235 Assert(A != nullptr, ExcNoMatrixGivenToUse());
236 return A->m();
237 }
238
239
240 template <typename MatrixType, typename VectorType>
241 inline typename PreconditionSelector<MatrixType, VectorType>::size_type
242 PreconditionSelector<MatrixType, VectorType>::n() const
243 {
244 Assert(A != nullptr, ExcNoMatrixGivenToUse());
245 return A->n();
246 }
247
248
249
250 template <typename MatrixType, typename VectorType>
251 void
252 PreconditionSelector<MatrixType, VectorType>::vmult(VectorType &dst,
253 const VectorType &src) const
254 {
255 if (preconditioning == "none")
256 {
257 dst = src;
258 }
259 else
260 {
261 Assert(A != nullptr, ExcNoMatrixGivenToUse());
262
263 if (preconditioning == "jacobi")
264 {
265 A->precondition_Jacobi(dst, src, omega);
266 }
267 else if (preconditioning == "sor")
268 {
269 A->precondition_SOR(dst, src, omega);
270 }
271 else if (preconditioning == "ssor")
272 {
273 A->precondition_SSOR(dst, src, omega);
274 }
275 else
276 DEAL_II_NOT_IMPLEMENTED();
277 }
278 }
279
280
281 template <typename MatrixType, typename VectorType>
282 void
283 PreconditionSelector<MatrixType, VectorType>::Tvmult(
284 VectorType &dst,
285 const VectorType &src) const
286 {
287 if (preconditioning == "none")
288 {
289 dst = src;
290 }
291 else
292 {
293 Assert(A != nullptr, ExcNoMatrixGivenToUse());
294
295 if (preconditioning == "jacobi")
296 {
297 A->precondition_Jacobi(dst, src, omega); // Symmetric operation
298 }
299 else if (preconditioning == "sor")
300 {
301 A->precondition_TSOR(dst, src, omega);
302 }
303 else if (preconditioning == "ssor")
304 {
305 A->precondition_SSOR(dst, src, omega); // Symmetric operation
306 }
307 else
308 DEAL_II_NOT_IMPLEMENTED();
309 }
310 }
311
312
313 template <typename MatrixType, typename VectorType>
314 std::string
315 PreconditionSelector<MatrixType, VectorType>::get_precondition_names()
316 {
317 return "none|jacobi|sor|ssor";
318 }
319
320
321 DEAL_II_NAMESPACE_CLOSE
322
323 #endif