Line data Source code
1 : /*
2 : * Copyright (c) 2010-2015: G-CSC, Goethe University Frankfurt
3 : * Author: Andreas Vogel
4 : *
5 : * This file is part of UG4.
6 : *
7 : * UG4 is free software: you can redistribute it and/or modify it under the
8 : * terms of the GNU Lesser General Public License version 3 (as published by the
9 : * Free Software Foundation) with the following additional attribution
10 : * requirements (according to LGPL/GPL v3 §7):
11 : *
12 : * (1) The following notice must be displayed in the Appropriate Legal Notices
13 : * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
14 : *
15 : * (2) The following notice must be displayed at a prominent place in the
16 : * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
17 : *
18 : * (3) The following bibliography is recommended for citation and must be
19 : * preserved in all covered files:
20 : * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
21 : * parallel geometric multigrid solver on hierarchically distributed grids.
22 : * Computing and visualization in science 16, 4 (2013), 151-164"
23 : * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
24 : * flexible software system for simulating pde based models on high performance
25 : * computers. Computing and visualization in science 16, 4 (2013), 165-179"
26 : *
27 : * This program is distributed in the hope that it will be useful,
28 : * but WITHOUT ANY WARRANTY; without even the implied warranty of
29 : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 : * GNU Lesser General Public License for more details.
31 : */
32 :
33 : #ifndef __H__LIB_ALGEBRA__OPERATOR__INTERFACE__OPERATOR_ITERATOR__
34 : #define __H__LIB_ALGEBRA__OPERATOR__INTERFACE__OPERATOR_ITERATOR__
35 :
36 : #include "lib_algebra/operator/damping.h"
37 : #include "common/util/smart_pointer.h"
38 :
39 : namespace ug{
40 :
41 : ///////////////////////////////////////////////////////////////////////////////
42 : // Iterator Operator
43 : ///////////////////////////////////////////////////////////////////////////////
44 :
45 : /// describes a linear iterator
46 : /**
47 : * This class is the base class for all linear iterators. Iterators (also called
48 : * preconditioners) are used in iterative schemes when solving a linear system.
49 : * Usually, a linear problem like L*u = f is intended to be solved. This is
50 : * done in an iterative way by performing an iteration of
51 : *
52 : * start: compute d := f - L*u
53 : * iterate: - c := B*d (compute correction)
54 : * - u := u + c (update solution)
55 : * - d := d - L*c (update defect)
56 : *
57 : * This iterator class describes the application of B in the scheme above.
58 : * The application has been split up into two parts.
59 : *
60 : * 1. init(L, u) or init(L):
61 : * These methods initialize the iterator and one of these methods has to
62 : * be called before any of the apply methods can be used. Passing the
63 : * linear operator indicates that this operator is used as underlying
64 : * for the iterator.
65 : *
66 : * 2. apply or apply_return_defect:
67 : * These methods are used to compute the correction (and to update the
68 : * defect at the same time). Note, that these methods can only be called
69 : * when the iterator has been initialized.
70 : *
71 : * This splitting has been made, since initialization may be computationally
72 : * expensive. Thus, the user of this class has the choice when to call this
73 : * initialization. E.g. when the operator is applied several times the init of
74 : * the iterator is only needed once.
75 : *
76 : * \tparam X Domain space function
77 : * \tparam Y Range space function
78 : */
79 : template <typename X, typename Y = X>
80 : class ILinearIterator
81 : {
82 : public:
83 : /// Domain space
84 : typedef X domain_function_type;
85 :
86 : /// Range space
87 : typedef Y codomain_function_type;
88 :
89 : public:
90 : /// returns the name of iterator
91 : /**
92 : * This method returns the name of the iterator operator. This function is
93 : * typically needed, when the iterator operator is used inside of another
94 : * operator and some debug output should be printed
95 : *
96 : * \returns const char* name of inverse operator
97 : */
98 : virtual const char* name() const = 0;
99 :
100 : /// returns if parallel solving is supported
101 : virtual bool supports_parallel() const = 0;
102 :
103 : /// initialize for operator J(u) and linearization point u
104 : /**
105 : * This method passes the linear operator J(u) that should be used as
106 : * underlying by this iterator. As second argument the linearization point
107 : * is passed. This is needed e.g. for the geometric multigrid method.
108 : *
109 : * \param[in] J linearized operator to use as underlying
110 : * \param[in] u linearization point
111 : * \returns bool success flag
112 : */
113 : virtual bool init(SmartPtr<ILinearOperator<Y,X> > J, const Y& u) = 0;
114 :
115 : /// initialize for linear operator L
116 : /**
117 : * This method passes the operator L that used as underlying by this
118 : * operator. In addition some preparation step can be made.
119 : *
120 : * \param[in] L linear operator to use as underlying
121 : * \returns bool success flag
122 : */
123 : virtual bool init(SmartPtr<ILinearOperator<Y,X> > L) = 0;
124 :
125 : /// compute new correction c = B*d
126 : /**
127 : * This method applies the iterator operator, i.e. c = B*d. The
128 : * domain function d remains unchanged.
129 : * Note, that this method can always be implemented by creating a copy of
130 : * d and calling apply_update_defect with this copy.
131 : *
132 : * \param[in] d defect
133 : * \param[out] c correction
134 : * \returns bool success flag
135 : */
136 : virtual bool apply(Y& c, const X& d) = 0;
137 :
138 : /// compute new correction c = B*d and update defect d := d - A*c
139 : /**
140 : * This method applies the inverse operator, i.e. c = B*d. The
141 : * domain function d is changed in the way, that the defect d := d - A*c
142 : * is returned in the function. This is always useful, when the iterating
143 : * algorithm can (or must) update the defect during computation (this is
144 : * e.g. the case for the geometric multigrid method).
145 : * Note, that this method can always be implemented by calling apply and
146 : * then computing d := d - A*c.
147 : *
148 : * \param[in,out] d defect
149 : * \param[out] u correction
150 : * \returns bool success flag
151 : */
152 : virtual bool apply_update_defect(Y& c, X& d) = 0;
153 :
154 : /// sets a scaling for the correction
155 : /**
156 : * Sets a scaling for the correction, i.e., once the correction has been
157 : * computed, c = B*d, the correction is scaled by a factor, c := s*c, where
158 : * s is provided by the passed scaling class. Note, that the scaling factor
159 : * may depend on the defect and correction. The internal update of the defect
160 : * as done in apply_update_defect must be performed with respect to the
161 : * scaled correction.
162 : */
163 0 : void set_damp(SmartPtr<IDamping<X,Y> > spScaling) {
164 0 : m_spDamping = spScaling;
165 0 : }
166 :
167 : /// sets the damping to a constant factor
168 0 : void set_damp(number factor) {
169 0 : m_spDamping = make_sp(new ConstantDamping<X,Y>(factor));
170 0 : }
171 :
172 : /// returns the scaling
173 : SmartPtr<IDamping<X,Y> > damping() {return m_spDamping;}
174 :
175 : /// clone
176 : virtual SmartPtr<ILinearIterator<X,Y> > clone() = 0;
177 :
178 : /// virtual destructor
179 0 : virtual ~ILinearIterator() {};
180 :
181 : /// constructor
182 0 : ILinearIterator() {set_damp(1.0);};
183 :
184 : /// copy constructor
185 0 : ILinearIterator(const ILinearIterator<X, Y> &parent)
186 0 : {
187 0 : set_damp(parent.m_spDamping);
188 0 : };
189 :
190 0 : virtual std::string config_string() const
191 : {
192 0 : std::stringstream ss; ss << name() << "( damping = " << m_spDamping->config_string() << ")"; return ss.str();
193 0 : }
194 :
195 : protected:
196 : /// the scaling
197 : SmartPtr<IDamping<X,Y> > m_spDamping;
198 : };
199 :
200 : } // end namespace ug
201 :
202 : #endif /* __H__LIB_ALGEBRA__OPERATOR__INTERFACE__OPERATOR_ITERATOR__ */
203 :
|
