Debian Codegraph @

dune/istl/operators.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 // vi: set et ts=4 sw=2 sts=2:
4 #ifndef DUNE_ISTL_OPERATORS_HH
5 #define DUNE_ISTL_OPERATORS_HH
6
7 #include <dune-istl-config.hh> // DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE
8
9 #include <cmath>
10 #include <complex>
11 #include <iostream>
12 #include <iomanip>
13 #include <string>
14
15 #include <dune/common/exceptions.hh>
16 #include <dune/common/shared_ptr.hh>
17
18 #include "solvercategory.hh"
19
20
21 namespace Dune {
22
23 /**
24 * @defgroup ISTL_Operators Operator concept
25 * @ingroup ISTL_Solvers
26 *
27 * The solvers in ISTL do not work on matrices directly. Instead we use
28 * an abstract operator concept. This allows for using matrix-free
29 * operators, i.e. operators that are not stored as matrices in any
30 * form. Thus our solver algorithms can easily be turned into matrix-free
31 * solvers just by plugging in matrix-free representations of linear
32 * operators and preconditioners.
33 */
34 /** @addtogroup ISTL_Operators
35 @{
36 */
37
38
39 /** \file
40
41 \brief Define general, extensible interface for operators.
42 The available implementation wraps a matrix.
43 */
44
45 //=====================================================================
46 // Abstract operator interface
47 //=====================================================================
48
49
50 /*!
51 @brief A linear operator.
52
53 Abstract base class defining a linear operator \f$ A : X\to Y\f$,
54 i.e. \f$ A(\alpha x) = \alpha A(x) \f$ and
55 \f$ A(x+y) = A(x)+A(y)\f$ hold. The
56 simplest solvers just need the application \f$ A(x)\f$ of
57 the operator.
58
59
60 - enables on the fly computation through operator concept. If explicit
61 representation of the operator is required use AssembledLinearOperator
62
63 - Some inverters may need an explicit formation of the operator
64 as a matrix, e.g. BiCGStab, ILU, AMG, etc. In that case use the
65 derived class
66 */
67 template<class X, class Y>
68 class LinearOperator {
69 public:
70 //! The type of the domain of the operator.
71 typedef X domain_type;
72 //! The type of the range of the operator.
73 typedef Y range_type;
74 //! The field type of the operator.
75 typedef typename X::field_type field_type;
76
77 /*! \brief apply operator to x: \f$ y = A(x) \f$
78 The input vector is consistent and the output must also be
79 consistent on the interior+border partition.
80 */
81 virtual void apply (const X& x, Y& y) const = 0;
82
83 //! apply operator to x, scale and add: \f$ y = y + \alpha A(x) \f$
84 virtual void applyscaleadd (field_type alpha, const X& x, Y& y) const = 0;
85
86 //! every abstract base class has a virtual destructor
87 virtual ~LinearOperator () {}
88
89 //! Category of the linear operator (see SolverCategory::Category)
90 virtual SolverCategory::Category category() const
91 #if DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE
92 {
93 DUNE_THROW(Dune::Exception,"It is necessary to implement the category method in a derived classes, in the future this method will pure virtual.");
94 };
95 #else
96 = 0;
97 #endif
98 };
99
100
101 /*!
102 \brief A linear operator exporting itself in matrix form.
103
104 Linear Operator that exports the operator in
105 matrix form. This is needed for certain solvers, such as
106 LU decomposition, ILU preconditioners or BiCG-Stab (because
107 of multiplication with A^T).
108 */
109 template<class M, class X, class Y>
110 class AssembledLinearOperator : public LinearOperator<X,Y> {
111 public:
112 //! export types, usually they come from the derived class
113 typedef M matrix_type;
114 typedef X domain_type;
115 typedef Y range_type;
116 typedef typename X::field_type field_type;
117
118 //! get reference to matrix
119 virtual const M& getmat () const = 0;
120 };
121
122
123
124 //=====================================================================
125 // Implementation for ISTL-matrix based operator
126 //=====================================================================
127
128 /*!
129 \brief Adapter to turn a matrix into a linear operator.
130
131 Adapts a matrix to the assembled linear operator interface
132 */
133 template<class M, class X, class Y>
134 class MatrixAdapter : public AssembledLinearOperator<M,X,Y>
135 {
136 public:
137 //! export types
138 typedef M matrix_type;
139 typedef X domain_type;
140 typedef Y range_type;
141 typedef typename X::field_type field_type;
142
143 //! constructor: just store a reference to a matrix
144 explicit MatrixAdapter (const M& A) : _A_(stackobject_to_shared_ptr(A)) {}
145
146 //! constructor: store an std::shared_ptr to a matrix
147 explicit MatrixAdapter (std::shared_ptr<const M> A) : _A_(A) {}
148
149 //! apply operator to x: \f$ y = A(x) \f$
150 void apply (const X& x, Y& y) const override
151 {
152 _A_->mv(x,y);
153 }
154
155 //! apply operator to x, scale and add: \f$ y = y + \alpha A(x) \f$
156 void applyscaleadd (field_type alpha, const X& x, Y& y) const override
157 {
158 _A_->usmv(alpha,x,y);
159 }
160
161 //! get reference to matrix
162 const M& getmat () const override
163 {
164 return *_A_;
165 }
166
167 //! Category of the solver (see SolverCategory::Category)
168 SolverCategory::Category category() const override
169 {
170 return SolverCategory::sequential;
171 }
172
173 private:
174 const std::shared_ptr<const M> _A_;
175 };
176
177 /** @} end documentation */
178
179 } // end namespace
180
181 #endif
182
183 // Emacs configuration
184 // Local Variables:
185 // tab-width: 4
186 // indent-tabs-mode: nil
187 // c-basic-offset: 2
188 // End: