MueLu  Version of the Day
MueLu_SmootherFactory_def.hpp
Go to the documentation of this file.
1 // @HEADER
2 //
3 // ***********************************************************************
4 //
5 // MueLu: A package for multigrid based preconditioning
6 // Copyright 2012 Sandia Corporation
7 //
8 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
9 // the U.S. Government retains certain rights in this software.
10 //
11 // Redistribution and use in source and binary forms, with or without
12 // modification, are permitted provided that the following conditions are
13 // met:
14 //
15 // 1. Redistributions of source code must retain the above copyright
16 // notice, this list of conditions and the following disclaimer.
17 //
18 // 2. Redistributions in binary form must reproduce the above copyright
19 // notice, this list of conditions and the following disclaimer in the
20 // documentation and/or other materials provided with the distribution.
21 //
22 // 3. Neither the name of the Corporation nor the names of the
23 // contributors may be used to endorse or promote products derived from
24 // this software without specific prior written permission.
25 //
26 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
27 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
30 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
31 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
32 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
33 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
34 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
35 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
36 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 //
38 // Questions? Contact
39 // Jonathan Hu (jhu@sandia.gov)
40 // Andrey Prokopenko (aprokop@sandia.gov)
41 // Ray Tuminaro (rstumin@sandia.gov)
42 //
43 // ***********************************************************************
44 //
45 // @HEADER
46 #ifndef MUELU_SMOOTHERFACTORY_DEF_HPP
47 #define MUELU_SMOOTHERFACTORY_DEF_HPP
48 
50 
51 #include "MueLu_Level.hpp"
52 #include "MueLu_Exceptions.hpp"
53 #include "MueLu_SmootherPrototype.hpp"
54 #include "MueLu_Ifpack2Smoother.hpp"
55 
56 
57 namespace MueLu {
58 
59  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
60  SmootherFactory<Scalar, LocalOrdinal, GlobalOrdinal, Node>::SmootherFactory(RCP<SmootherPrototype> preAndPostSmootherPrototype) {
61  SetSmootherPrototypes(preAndPostSmootherPrototype);
62  }
63 
64  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
66  RCP<SmootherPrototype> postSmootherPrototype) {
67  SetSmootherPrototypes(preSmootherPrototype, postSmootherPrototype);
68  }
69 
70  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
71  void SmootherFactory<Scalar, LocalOrdinal, GlobalOrdinal, Node>::SetSmootherPrototypes(RCP<SmootherPrototype> preAndPostSmootherPrototype) {
72  preSmootherPrototype_ = postSmootherPrototype_ = preAndPostSmootherPrototype;
73  CheckPrototypes();
74  }
75 
76  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
78  RCP<SmootherPrototype> postSmootherPrototype) {
79  preSmootherPrototype_ = preSmootherPrototype;
80  postSmootherPrototype_ = postSmootherPrototype;
81  CheckPrototypes();
82  }
83 
84  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
86  TEUCHOS_TEST_FOR_EXCEPTION(preSmootherPrototype_ != Teuchos::null && preSmootherPrototype_->IsSetup() == true,
87  Exceptions::RuntimeError, "preSmoother prototype is not a smoother prototype (IsSetup() == true)");
88  TEUCHOS_TEST_FOR_EXCEPTION(postSmootherPrototype_ != Teuchos::null && postSmootherPrototype_->IsSetup() == true,
89  Exceptions::RuntimeError, "postSmoother prototype is not a smoother prototype (IsSetup() == true)");
90  }
91 
92  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
94  RCP<SmootherPrototype>& postSmootherPrototype) const {
95  preSmootherPrototype = preSmootherPrototype_;
96  postSmootherPrototype = postSmootherPrototype_;
97  }
98 
99  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
101  if (preSmootherPrototype_ != Teuchos::null)
102  preSmootherPrototype_->DeclareInput(currentLevel);
103 
104  if ((postSmootherPrototype_ != Teuchos::null) && (preSmootherPrototype_ != postSmootherPrototype_))
105  postSmootherPrototype_->DeclareInput(currentLevel);
106  }
107 
108  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
110  return BuildSmoother(currentLevel, BOTH);
111  }
112 
113  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
115  // SmootherFactory is quite tricky because of the fact that one of the smoother prototypes may be zero.
116  // The challenge is that we have no way of knowing how user uses this factory. For instance, lets say
117  // user wants to use s1 prototype as a presmoother, and s2 as a postsmoother. He could do:
118  // (a) create SmootherFactory(s1, s2), or
119  // (b) create SmootherFactory(s1, null) and SmootherFactory(null, s2)
120  // It may also happen that somewhere somebody set presmoother factory = postsmoother factory = (a)
121  // How do you do DeclareInput in this case? It could easily introduce a bug if a user does not check
122  // whether presmoother = postsmoother. A buggy code could look like that:
123  // RCP<SmootherFactory> s = rcp(new SmootherFactory(s1,s2));
124  // level.Request("PreSmoother", s.get());
125  // level.Request("PostSmoother", s.get());
126  // Get<RCP<SmootherBase> > pre = Get<RCP<SmootherBase> >("PreSmoother", s.get());
127  // Get<RCP<SmootherBase> > post = Get<RCP<SmootherBase> >("PostSmoother", s.get());
128  // This code would call DeclareInput in request mode twice, but as the Build method generates both Pre and Post
129  // smoothers, it would call DelcareInput in release mode only once, leaving requests.
130  // This code has another problem if s2 = Teuchos::null. In that case, despite the request for PostSmoother, the factory
131  // would not generate one, and second Get would throw. The real issue here is that given a Factory pointer
132  // there is no way to be sure that this factory would generate any of "PreSmoother" or "PostSmoother", unless you are
133  // able to cast it to SmootherFactory, do GetPrototypes and to check whether any of those is Teuchos::null.
134 
135  RCP<SmootherPrototype> preSmoother, postSmoother;
136  ParameterList preSmootherParams, postSmootherParams;
137 
138  if ((preOrPost & PRE) && !preSmootherPrototype_.is_null()) {
139  preSmoother = preSmootherPrototype_->Copy();
140 
141  int oldRank = -1;
142  if (!currentLevel.GetComm().is_null())
143  oldRank = preSmoother->SetProcRankVerbose(currentLevel.GetComm()->getRank());
144 
145  preSmoother->Setup(currentLevel);
146  preSmootherParams = preSmoother->GetParameterList();
147 
148  if (oldRank != -1)
149  preSmoother->SetProcRankVerbose(oldRank);
150 
151  currentLevel.Set<RCP<SmootherBase> >("PreSmoother", preSmoother, this);
152  }
153 
154  if ((preOrPost & POST) && !postSmootherPrototype_.is_null()) {
155  if (preOrPost == BOTH && preSmootherPrototype_ == postSmootherPrototype_) {
156  // Simple reuse
157  // Same prototypes for pre- and post-smoothers mean that we only need to call Setup only once
158  postSmoother = preSmoother;
159 
160  // } else if (preOrPost == BOTH &&
161  // preSmootherPrototype_ != Teuchos::null &&
162  // preSmootherPrototype_->GetType() == postSmootherPrototype_->GetType()) {
163 
164  // // More complex reuse case: need implementation of CopyParameters() and a smoothers smart enough to know when parameters affect the setup phase.
165 
166  // // YES: post-smoother == pre-smoother
167  // // => copy the pre-smoother to avoid the setup phase of the post-smoother.
168  // postSmoother = preSmoother->Copy();
169  // // If the post-smoother parameters are different from
170  // // pre-smoother, the parameters stored in the post-smoother
171  // // prototype are copied in the new post-smoother object.
172  // postSmoother->CopyParameters(postSmootherPrototype_);
173  // // If parameters don't influence the Setup phase (it is the case
174  // // for Jacobi, Chebyshev...), PostSmoother is already setup. Nothing
175  // // more to do. In the case of ILU, parameters of the smoother
176  // // are in fact the parameters of the Setup phase. The call to
177  // // CopyParameters resets the smoother (only if parameters are
178  // // different) and we must call Setup() again.
179  // postSmoother->Setup(currentLevel);
180 
181  // // TODO: if CopyParameters do not exist, do setup twice.
182 
183  } else {
184  // No reuse:
185  // - either we only do postsmoothing without any presmoothing
186  // - or our postsmoother is different from presmoother
187  postSmoother = postSmootherPrototype_->Copy();
188 
189  int oldRank = -1;
190  if (!currentLevel.GetComm().is_null())
191  oldRank = postSmoother->SetProcRankVerbose(GetProcRankVerbose());
192 
193  postSmoother->Setup(currentLevel);
194 
195  if (oldRank != -1)
196  postSmoother->SetProcRankVerbose(oldRank);
197  }
198  postSmootherParams = postSmoother->GetParameterList();
199 
200  currentLevel.Set<RCP<SmootherBase> >("PostSmoother", postSmoother, this);
201  }
202 
203  ParameterList& paramList = const_cast<ParameterList&>(this->GetParameterList());
204  if (postSmoother == preSmoother && !preSmoother.is_null()) {
205  paramList = preSmoother->GetParameterList();
206 
207  } else {
208  if (!preSmoother.is_null()) {
209  ParameterList& preList = paramList.sublist("presmoother", false);
210  preList = preSmootherParams;
211  }
212 
213  if (!postSmoother.is_null()) {
214  ParameterList& postList = paramList.sublist("postsmoother", false);
215  postList = postSmootherParams;
216  }
217  }
218 
219  } // Build()
220 
221  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
223  std::ostringstream out;
225  std::string preStr = (preSmootherPrototype_ == Teuchos::null) ? "null" : preSmootherPrototype_->description();
226  std::string postStr = (preSmootherPrototype_ == postSmootherPrototype_) ? "pre" : ( (postSmootherPrototype_ == Teuchos::null) ? "null" : postSmootherPrototype_->description() );
227  out << "{pre = " << preStr << ", post = "<< postStr << "}";
228  return out.str();
229  }
230 
231  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
232  void SmootherFactory<Scalar, LocalOrdinal, GlobalOrdinal, Node>::describe(Teuchos::FancyOStream& out, const VerbLevel verbLevel) const {
234 
235  if (verbLevel & Parameters0) {
236  out0 << "PreSmoother : ";
237  if (preSmootherPrototype_.is_null()) {
238  out0 << "null" << std::endl;
239  } else {
240  Teuchos::OSTab tab2(out);
241  preSmootherPrototype_->describe(out, verbLevel);
242  }
243 
244  out0 << "PostSmoother: ";
245  if (postSmootherPrototype_ == preSmootherPrototype_) { out0 << "same as PreSmoother" << std::endl; }
246  else if (postSmootherPrototype_ == Teuchos::null) { out0 << "null" << std::endl; }
247  else {
248  Teuchos::OSTab tab2(out);
249  postSmootherPrototype_->describe(out, verbLevel);
250  out0 << "PostSmoother is different than PreSmoother (not the same object)" << std::endl;
251  }
252  }
253 
254  if (verbLevel & Debug) {
255  if (preSmootherPrototype_ != Teuchos::null || postSmootherPrototype_ != Teuchos::null) { out0 << "-" << std::endl; }
256  if (preSmootherPrototype_ != Teuchos::null) { out0 << "RCP<preSmootherPrototype_> : " << preSmootherPrototype_ << std::endl; }
257  if (postSmootherPrototype_ != Teuchos::null) { out0 << "RCP<postSmootherPrototype_>: " << postSmootherPrototype_ << std::endl; }
258  }
259  }
260 
261 
262 } // namespace MueLu
263 
264 //TODO: doc: setup done twice if PostSmoother object != PreSmoother object and no adv. reused capability
265 
266 // TODO ReUse: If only one smoother is missing, SmootherFactory can be smart and build only the missing smoother.
267 // TODO (optim): we can also reuse if preOrPost = post and preSmoother available in Level
268 // we can also reuse if preOrPost = pre and postSmoother available in Level
269 
270 #endif // MUELU_SMOOTHERFACTORY_DEF_HPP
SmootherFactory(RCP< SmootherPrototype > preAndPostSmootherPrototype=Teuchos::null)
Constructor.
Print additional debugging information.
Namespace for MueLu classes and methods.
void BuildSmoother(Level &currentLevel, const PreOrPost preOrPost=BOTH) const
void describe(Teuchos::FancyOStream &out, const VerbLevel verbLevel=Default) const
void Build(Level &currentLevel) const
Creates pre and post smoothers.
void SetSmootherPrototypes(RCP< SmootherPrototype > preAndPostSmootherPrototype)
Set smoother prototypes.
Class that holds all level-specific information.
Definition: MueLu_Level.hpp:99
#define MUELU_DESCRIBE
Helper macro for implementing Describable::describe() for BaseClass objects.
void Set(const std::string &ename, const T &entry, const FactoryBase *factory=NoFactory::get())
Print class parameters.
std::string description() const
Return a simple one-line description of this object.
void GetSmootherPrototypes(RCP< SmootherPrototype > &preSmootherPrototype, RCP< SmootherPrototype > &postSmootherPrototype) const
Get smoother prototypes.
Exception throws to report errors in the internal logical of the program.
RCP< const Teuchos::Comm< int > > GetComm() const
virtual std::string description() const
Return a simple one-line description of this object.
void DeclareInput(Level &currentLevel) const
Input.