MueLu  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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>
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  RCP<ParameterList> validParamList = rcp(new ParameterList());
87 
88  validParamList->set<bool>("keep smoother data", false, "Keep constructed smoothers for later reuse");
89 
90  validParamList->set< RCP<SmootherPrototype> >("PreSmoother data", null, "Pre-smoother data for reuse");
91  validParamList->set< RCP<SmootherPrototype> >("PostSmoother data", null, "Post-smoother data for reuse");
92 
93  return validParamList;
94  }
95 
96  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
98  TEUCHOS_TEST_FOR_EXCEPTION(preSmootherPrototype_ != Teuchos::null && preSmootherPrototype_->IsSetup() == true,
99  Exceptions::RuntimeError, "preSmoother prototype is not a smoother prototype (IsSetup() == true)");
100  TEUCHOS_TEST_FOR_EXCEPTION(postSmootherPrototype_ != Teuchos::null && postSmootherPrototype_->IsSetup() == true,
101  Exceptions::RuntimeError, "postSmoother prototype is not a smoother prototype (IsSetup() == true)");
102  }
103 
104  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
106  RCP<SmootherPrototype>& postSmootherPrototype) const {
107  preSmootherPrototype = preSmootherPrototype_;
108  postSmootherPrototype = postSmootherPrototype_;
109  }
110 
111  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
113  if (preSmootherPrototype_ != Teuchos::null)
114  preSmootherPrototype_->DeclareInput(currentLevel);
115 
116  if ((postSmootherPrototype_ != Teuchos::null) && (preSmootherPrototype_ != postSmootherPrototype_))
117  postSmootherPrototype_->DeclareInput(currentLevel);
118  }
119 
120  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
122  return BuildSmoother(currentLevel, BOTH);
123  }
124 
125  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
127  // SmootherFactory is quite tricky because of the fact that one of the smoother prototypes may be zero.
128  // The challenge is that we have no way of knowing how user uses this factory. For instance, lets say
129  // user wants to use s1 prototype as a presmoother, and s2 as a postsmoother. He could do:
130  // (a) create SmootherFactory(s1, s2), or
131  // (b) create SmootherFactory(s1, null) and SmootherFactory(null, s2)
132  // It may also happen that somewhere somebody set presmoother factory = postsmoother factory = (a)
133  // How do you do DeclareInput in this case? It could easily introduce a bug if a user does not check
134  // whether presmoother = postsmoother. A buggy code could look like that:
135  // RCP<SmootherFactory> s = rcp(new SmootherFactory(s1,s2));
136  // level.Request("PreSmoother", s.get());
137  // level.Request("PostSmoother", s.get());
138  // Get<RCP<SmootherBase> > pre = Get<RCP<SmootherBase> >("PreSmoother", s.get());
139  // Get<RCP<SmootherBase> > post = Get<RCP<SmootherBase> >("PostSmoother", s.get());
140  // This code would call DeclareInput in request mode twice, but as the Build method generates both Pre and Post
141  // smoothers, it would call DelcareInput in release mode only once, leaving requests.
142  // This code has another problem if s2 = Teuchos::null. In that case, despite the request for PostSmoother, the factory
143  // would not generate one, and second Get would throw. The real issue here is that given a Factory pointer
144  // there is no way to be sure that this factory would generate any of "PreSmoother" or "PostSmoother", unless you are
145  // able to cast it to SmootherFactory, do GetPrototypes and to check whether any of those is Teuchos::null.
146 
147  const Teuchos::ParameterList& pL = GetParameterList();
148 
149  RCP<SmootherPrototype> preSmoother, postSmoother;
150  ParameterList preSmootherParams, postSmootherParams;
151 
152  if ((preOrPost & PRE) && !preSmootherPrototype_.is_null()) {
153 
154  if (currentLevel.IsAvailable("PreSmoother data", this))
155  preSmoother = currentLevel.Get<RCP<SmootherPrototype> >("PreSmoother data", this);
156  else
157  preSmoother = preSmootherPrototype_->Copy();
158 
159  int oldRank = -1;
160  if (!currentLevel.GetComm().is_null())
161  oldRank = preSmoother->SetProcRankVerbose(currentLevel.GetComm()->getRank());
162 
163  preSmoother->Setup(currentLevel);
164  preSmootherParams = preSmoother->GetParameterList();
165 
166  if (oldRank != -1)
167  preSmoother->SetProcRankVerbose(oldRank);
168 
169  currentLevel.Set<RCP<SmootherBase> >("PreSmoother", preSmoother, this);
170 
171  if (pL.get<bool>("keep smoother data"))
172  Set(currentLevel, "PreSmoother data", preSmoother);
173  }
174 
175  if ((preOrPost & POST) && !postSmootherPrototype_.is_null()) {
176  if (preOrPost == BOTH && preSmootherPrototype_ == postSmootherPrototype_) {
177  // Simple reuse
178  // Same prototypes for pre- and post-smoothers mean that we only need to call Setup only once
179  postSmoother = preSmoother;
180 
181  // else if (preOrPost == BOTH &&
182  // preSmootherPrototype_ != Teuchos::null &&
183  // preSmootherPrototype_->GetType() == postSmootherPrototype_->GetType()) {
184 
185  // // More complex reuse case: need implementation of CopyParameters() and a smoothers smart enough to know when parameters affect the setup phase.
186 
187  // // YES: post-smoother == pre-smoother
188  // // => copy the pre-smoother to avoid the setup phase of the post-smoother.
189  // postSmoother = preSmoother->Copy();
190  // // If the post-smoother parameters are different from
191  // // pre-smoother, the parameters stored in the post-smoother
192  // // prototype are copied in the new post-smoother object.
193  // postSmoother->CopyParameters(postSmootherPrototype_);
194  // // If parameters don't influence the Setup phase (it is the case
195  // // for Jacobi, Chebyshev...), PostSmoother is already setup. Nothing
196  // // more to do. In the case of ILU, parameters of the smoother
197  // // are in fact the parameters of the Setup phase. The call to
198  // // CopyParameters resets the smoother (only if parameters are
199  // // different) and we must call Setup() again.
200  // postSmoother->Setup(currentLevel);
201  // }
202 
203  // // TODO: if CopyParameters do not exist, do setup twice.
204 
205  } else {
206 
207  if (currentLevel.IsAvailable("PostSmoother data", this)) {
208  postSmoother = currentLevel.Get<RCP<SmootherPrototype> >("PostSmoother data", this);
209  } else {
210  // No reuse:
211  // - either we only do postsmoothing without any presmoothing
212  // - or our postsmoother is different from presmoother
213  postSmoother = postSmootherPrototype_->Copy();
214  }
215 
216  int oldRank = -1;
217  if (!currentLevel.GetComm().is_null())
218  oldRank = postSmoother->SetProcRankVerbose(GetProcRankVerbose());
219 
220  postSmoother->Setup(currentLevel);
221  postSmootherParams = postSmoother->GetParameterList();
222 
223  if (oldRank != -1)
224  postSmoother->SetProcRankVerbose(oldRank);
225  }
226 
227  currentLevel.Set<RCP<SmootherBase> >("PostSmoother", postSmoother, this);
228 
229  if (pL.get<bool>("keep smoother data"))
230  Set(currentLevel, "PostSmoother data", preSmoother);
231  }
232 
233  ParameterList& paramList = const_cast<ParameterList&>(this->GetParameterList());
234  if (postSmoother == preSmoother && !preSmoother.is_null()) {
235  paramList.sublist("smoother", false) = preSmoother->GetParameterList();
236 
237  } else {
238  if (!preSmoother.is_null())
239  paramList.sublist("presmoother", false) = preSmootherParams;
240 
241  if (!postSmoother.is_null())
242  paramList.sublist("postsmoother", false) = postSmootherParams;
243  }
244 
245  } // Build()
246 
247  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
249  std::ostringstream out;
251  std::string preStr = (preSmootherPrototype_ == Teuchos::null) ? "null" : preSmootherPrototype_->description();
252  std::string postStr = (preSmootherPrototype_ == postSmootherPrototype_) ? "pre" : ( (postSmootherPrototype_ == Teuchos::null) ? "null" : postSmootherPrototype_->description() );
253  out << "{pre = " << preStr << ", post = "<< postStr << "}";
254  return out.str();
255  }
256 
257  template <class Scalar,class LocalOrdinal, class GlobalOrdinal, class Node>
260 
261  if (verbLevel & Parameters0) {
262  out0 << "PreSmoother : ";
263  if (preSmootherPrototype_.is_null()) {
264  out0 << "null" << std::endl;
265  } else {
266  Teuchos::OSTab tab2(out);
267  preSmootherPrototype_->describe(out, verbLevel);
268  }
269 
270  out0 << "PostSmoother: ";
271  if (postSmootherPrototype_ == preSmootherPrototype_) { out0 << "same as PreSmoother" << std::endl; }
272  else if (postSmootherPrototype_ == Teuchos::null) { out0 << "null" << std::endl; }
273  else {
274  Teuchos::OSTab tab2(out);
275  postSmootherPrototype_->describe(out, verbLevel);
276  out0 << "PostSmoother is different than PreSmoother (not the same object)" << std::endl;
277  }
278  }
279 
280  if (verbLevel & Debug) {
281  if (preSmootherPrototype_ != Teuchos::null || postSmootherPrototype_ != Teuchos::null) { out0 << "-" << std::endl; }
282  if (preSmootherPrototype_ != Teuchos::null) { out0 << "RCP<preSmootherPrototype_> : " << preSmootherPrototype_ << std::endl; }
283  if (postSmootherPrototype_ != Teuchos::null) { out0 << "RCP<postSmootherPrototype_>: " << postSmootherPrototype_ << std::endl; }
284  }
285  }
286 
287 
288 } // namespace MueLu
289 
290 //TODO: doc: setup done twice if PostSmoother object != PreSmoother object and no adv. reused capability
291 
292 // TODO ReUse: If only one smoother is missing, SmootherFactory can be smart and build only the missing smoother.
293 // TODO (optim): we can also reuse if preOrPost = post and preSmoother available in Level
294 // we can also reuse if preOrPost = pre and postSmoother available in Level
295 
296 #endif // MUELU_SMOOTHERFACTORY_DEF_HPP
virtual const Teuchos::ParameterList & GetParameterList() const
SmootherFactory(RCP< SmootherPrototype > preAndPostSmootherPrototype=Teuchos::null)
Constructor.
T & Get(const std::string &ename, const FactoryBase *factory=NoFactory::get())
Get data without decrementing associated storage counter (i.e., read-only access). Usage: Level-&gt;Get&lt; RCP&lt;Matrix&gt; &gt;(&quot;A&quot;, factory) if factory == NULL =&gt; use default factory.
T & get(const std::string &name, T def_value)
ParameterList & set(std::string const &name, T const &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
RCP< const ParameterList > GetValidParameterList() const
Input.
virtual void Setup(Level &)=0
Print additional debugging information.
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.
virtual RCP< SmootherPrototype > Copy() const =0
void SetSmootherPrototypes(RCP< SmootherPrototype > preAndPostSmootherPrototype)
Set smoother prototypes.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
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.
int SetProcRankVerbose(int procRank) const
Set proc rank used for printing.
void GetSmootherPrototypes(RCP< SmootherPrototype > &preSmootherPrototype, RCP< SmootherPrototype > &postSmootherPrototype) const
Get smoother prototypes.
ParameterList & sublist(const std::string &name, bool mustAlreadyExist=false, const std::string &docString="")
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.
bool IsAvailable(const std::string &ename, const FactoryBase *factory=NoFactory::get()) const
Test whether a need&#39;s value has been saved.
void DeclareInput(Level &currentLevel) const
Specifies the data that this class needs, and the factories that generate that data.
bool is_null() const