Debian Codegraph @

dune/istl/preconditioner.hh

raw
1 // SPDX-FileCopyrightText: Copyright © DUNE Project contributors, see file LICENSE.md in module root
2 // SPDX-License-Identifier: LicenseRef-GPL-2.0-only-with-DUNE-exception
3 // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
4 // vi: set et ts=4 sw=2 sts=2:
5 #ifndef DUNE_ISTL_PRECONDITIONER_HH
6 #define DUNE_ISTL_PRECONDITIONER_HH
7
8 #include <dune-istl-config.hh> // DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE
9 #include <dune/common/exceptions.hh>
10
11 #include "solvercategory.hh"
12
13 namespace Dune {
14 /**
15 * @addtogroup ISTL_Prec
16 * @{
17 */
18 //=====================================================================
19 /*! \brief Base class for matrix free definition of preconditioners.
20
21 Note that the operator, which is the basis for the preconditioning,
22 is supplied to the preconditioner from the outside in the
23 constructor or some other method.
24
25 This interface allows the encapsulation of all parallelization
26 aspects into the preconditioners.
27
28 \tparam X Type of the update
29 \tparam Y Type of the defect
30 */
31 //=====================================================================
32 template<class X, class Y>
33 class Preconditioner {
34 public:
35 //! \brief The domain type of the preconditioner.
36 typedef X domain_type;
37 //! \brief The range type of the preconditioner.
38 typedef Y range_type;
39 //! \brief The field type of the preconditioner.
40 typedef typename X::field_type field_type;
41
42 /*! \brief Prepare the preconditioner.
43
44 A solver solves a linear operator equation A(x)=b by applying
45 one or several steps of the preconditioner. The method pre()
46 is called before the first apply operation.
47 b and x are right hand side and solution vector of the linear
48 system respectively. It may. e.g., scale the system, allocate memory or
49 compute a (I)LU decomposition.
50 Note: The ILU decomposition could also be computed in the constructor
51 or with a separate method of the derived method if several
52 linear systems with the same matrix are to be solved.
53
54 \note if a preconditioner is copied (e.g. for a second thread)
55 again the pre() method has to be called to ensure proper memory
56 management.
57
58 \code
59 X x(0.0);
60 Y b = ...; // rhs
61 Preconditioner<X,Y> prec(...);
62 prec.pre(x,b); // prepare the preconditioner
63 prec.apply(x,b); // can be called multiple times now...
64 prec.post(x); // cleanup internal state
65 \endcode
66
67 \param x The left hand side of the equation.
68 \param b The right hand side of the equation.
69 */
70 virtual void pre (X& x, Y& b) = 0;
71
72 /*! \brief Apply one step of the preconditioner to the system A(v)=d.
73
74 On entry v=0 and d=b-A(x) (although this might not be
75 computed in that way. On exit v contains the update, i.e
76 one step computes \f$ v = M^{-1} d \f$ where \f$ M \f$ is the
77 approximate inverse of the operator \f$ A \f$ characterizing
78 the preconditioner.
79 \param[out] v The update to be computed
80 \param d The current defect.
81 */
82 virtual void apply (X& v, const Y& d) = 0;
83
84 /*! \brief Clean up.
85
86 This method is called after the last apply call for the
87 linear system to be solved. Memory may be deallocated safely
88 here. x is the solution of the linear equation.
89
90 \param x The right hand side of the equation.
91 */
92 virtual void post (X& x) = 0;
93
94 //! Category of the preconditioner (see SolverCategory::Category)
95 virtual SolverCategory::Category category() const
96 #if DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE
97 {
98 DUNE_THROW(Dune::Exception,"It is necessary to implement the category method in a derived classes, in the future this method will pure virtual.");
99 }
100 #else
101 = 0;
102 #endif
103
104 //! every abstract base class has a virtual destructor
105 virtual ~Preconditioner () {}
106
107 };
108
109 /**
110 * @}
111 */
112 }
113 #endif