MueLu  Version of the Day
MueLu_Hierarchy_decl.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_HIERARCHY_DECL_HPP
47 #define MUELU_HIERARCHY_DECL_HPP
48 
49 #include <Teuchos_ParameterList.hpp>
50 #include <Teuchos_Ptr.hpp>
51 
52 #include <Xpetra_ConfigDefs.hpp> // global_size_t
53 #include <Xpetra_Matrix_fwd.hpp>
56 #include <Xpetra_Operator_fwd.hpp>
57 
58 #include <Xpetra_Cloner.hpp>
59 #include <MueLu_SmootherCloner.hpp>
60 #include "MueLu_ConfigDefs.hpp"
61 #include "MueLu_BaseClass.hpp"
62 #include "MueLu_Hierarchy_fwd.hpp"
63 
64 #include "MueLu_Types.hpp"
65 
67 #include "MueLu_FactoryManager.hpp" // no fwd declaration because constructor of FactoryManager is used as a default parameter of Setup()
69 #include "MueLu_KeepType.hpp"
70 #include "MueLu_Level_fwd.hpp"
71 #include "MueLu_MasterList.hpp"
72 #include "MueLu_NoFactory.hpp"
73 #include "MueLu_PFactory_fwd.hpp"
74 #include "MueLu_RFactory_fwd.hpp"
79 #include "MueLu_Utilities_fwd.hpp"
80 
81 namespace MueLu {
82 
83  enum ReturnType {
87  };
88 
99  template <class Scalar = Xpetra::Operator<>::scalar_type,
100  class LocalOrdinal = typename Xpetra::Operator<Scalar>::local_ordinal_type,
103  class Hierarchy : public BaseClass {
104 #undef MUELU_HIERARCHY_SHORT
105 #include "MueLu_UseShortNames.hpp"
106 
107  typedef Teuchos::ScalarTraits<SC> STS;
108  typedef typename STS::magnitudeType MagnitudeType;
109 
111  struct ConvData {
112  ConvData() : maxIts_(1), tol_(-STS::magnitude(STS::one())) { }
113  ConvData(LO maxIts) : maxIts_(maxIts), tol_(-STS::magnitude(STS::one())) { }
114  ConvData(MagnitudeType tol) : maxIts_(10000), tol_(tol) { }
115  ConvData(std::pair<LO,MagnitudeType> p) : maxIts_(p.first), tol_(p.second) { }
116 
119  };
120 
121  public:
122 
124 
125 
127  Hierarchy();
128 
130  Hierarchy(const RCP<Matrix> & A);
131 
133  virtual ~Hierarchy() { }
134 
136 
138 
139 
141  static CycleType GetDefaultCycle() { return MasterList::getDefault<std::string>("cycle type") == "V" ? VCYCLE : WCYCLE; }
142  static bool GetDefaultImplicitTranspose() { return MasterList::getDefault<bool>("transpose: use implicit"); }
143  static Xpetra::global_size_t GetDefaultMaxCoarseSize() { return MasterList::getDefault<int>("coarse: max size"); }
144  static int GetDefaultMaxLevels() { return MasterList::getDefault<int>("max levels"); }
145  static bool GetDefaultPRrebalance() { return MasterList::getDefault<bool>("repartition: rebalance P and R"); }
146 
148  bool GetImplicitTranspose() const { return implicitTranspose_; }
149 
150  void SetMaxCoarseSize(Xpetra::global_size_t maxCoarseSize) { maxCoarseSize_ = maxCoarseSize; }
151  void SetPRrebalance(bool doPRrebalance) { doPRrebalance_ = doPRrebalance; }
152  void SetImplicitTranspose(const bool& implicit) { implicitTranspose_ = implicit; }
153 
155 
157 
158  template<class S2, class LO2, class GO2, class N2>
159  friend class Hierarchy;
160 
161  private:
162  int LastLevelID() const { return Levels_.size() - 1; }
163  void DumpCurrentGraph() const;
164 
165  public:
166 
168  void AddLevel(const RCP<Level> & level);
169 
171  void AddNewLevel();
172 
174  RCP<Level> & GetLevel(const int levelID = 0);
175 
176  int GetNumLevels() const;
177  int GetGlobalNumLevels() const;
178 
179  MagnitudeType GetRate() const { return rate_; }
180 
181  // This function is global
182  double GetOperatorComplexity() const;
183 
185  void CheckLevel(Level& level, int levelID);
186 
188 
225  bool Setup(int coarseLevelID, const RCP<const FactoryManagerBase> fineLevelManager /* = Teuchos::null */, const RCP<const FactoryManagerBase> coarseLevelManager,
226  const RCP<const FactoryManagerBase> nextLevelManager = Teuchos::null);
227 
229  void Setup(const FactoryManagerBase& manager = FactoryManager(), int startLevel = 0, int numDesiredLevels = GetDefaultMaxLevels());
230 
231  void SetupRe();
232 
234  void Clear(int startLevel = 0);
235  void ExpertClear();
236 
238  CycleType GetCycle() const { return Cycle_; }
239 
241  void SetCycle(CycleType Cycle) { Cycle_ = Cycle; }
242 
255  ReturnType Iterate(const MultiVector& B, MultiVector& X, ConvData conv = ConvData(),
256  bool InitialGuessIsZero = false, LO startLevel = 0);
257 
267  void Write(const LO &start=-1, const LO &end=-1, const std::string &suffix="");
268 
270 
272 
273 
275  void Keep(const std::string & ename, const FactoryBase* factory = NoFactory::get());
276 
278  void Delete(const std::string& ename, const FactoryBase* factory = NoFactory::get());
279 
281  void AddKeepFlag(const std::string & ename, const FactoryBase* factory = NoFactory::get(), KeepType keep = MueLu::Keep);
282 
284  void RemoveKeepFlag(const std::string & ename, const FactoryBase* factory, KeepType keep = MueLu::All);
285 
287 
289 
290 
292  std::string description() const;
293 
299  void describe(Teuchos::FancyOStream& out, const VerbLevel verbLevel = Default) const;
300  void describe(Teuchos::FancyOStream& out, const Teuchos::EVerbosityLevel verbLevel = Teuchos::VERB_HIGH) const;
301 
302  // Hierarchy::print is local hierarchy function, thus the statistics can be different from global ones
303  void print(std::ostream& out = std::cout, const VerbLevel verbLevel = (MueLu::Parameters | MueLu::Statistics0)) const;
304 
309  void IsPreconditioner(const bool flag);
310 
312 
313  void EnableGraphDumping(const std::string& filename, int levelID = 1) {
314  isDumpingEnabled_ = true;
315  dumpLevel_ = levelID;
316  dumpFile_ = filename;
317  }
318 
319  template<class Node2>
320  Teuchos::RCP< Hierarchy<Scalar, LocalOrdinal, GlobalOrdinal, Node2> >
321  clone (const RCP<Node2> &node2) const;
322 
323  void setlib(Xpetra::UnderlyingLib inlib) { lib_ = inlib; }
325 
326  protected:
327  const RCP<const FactoryManagerBase>& GetLevelManager(const int levelID) const {
328  return levelManagers_[levelID];
329  }
330 
331  private:
333  Hierarchy(const Hierarchy &h);
334 
336  Array<RCP<Level> > Levels_;
337 
338  // We replace coordinates GIDs to make them consistent with matrix GIDs,
339  // even if user does not do that. Ideally, though, we should completely
340  // remove any notion of coordinate GIDs, and deal only with LIDs, assuming
341  // that they are consistent with matrix block IDs
342  void ReplaceCoordinateMap(Level& level);
343 
344  // Minimum size of a matrix on any level. If we fall below that, we stop
345  // the coarsening
347 
348  // Potential speed up of the setup by skipping R construction, and using
349  // transpose matrix-matrix product for RAP
351 
352  // Potential speed up of the setup by skipping rebalancing of P and R, and
353  // doing extra import during solve
355 
356  // Hierarchy may be used in a standalone mode, or as a preconditioner
358 
359  // V- or W-cycle
361 
362  // Epetra/Tpetra mode
364 
366  // If enabled, we dump the graph on a specified level into a specified file
369  std::string dumpFile_;
370 
373 
374  // Level managers used during the Setup
375  Array<RCP<const FactoryManagerBase> > levelManagers_;
376 
377  }; //class Hierarchy
378 
379  template<class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
380  template<typename Node2>
381  Teuchos::RCP<Hierarchy<Scalar, LocalOrdinal, GlobalOrdinal, Node2> >
383  clone (const Teuchos::RCP<Node2> &node2) const {
387 
388  Teuchos::RCP<New_H_Type> new_h = Teuchos::rcp(new New_H_Type());
389  new_h->Levels_.resize(this->GetNumLevels());
390  new_h->maxCoarseSize_ = maxCoarseSize_;
391  new_h->implicitTranspose_ = implicitTranspose_;
392  new_h->isPreconditioner_ = isPreconditioner_;
393  new_h->isDumpingEnabled_ = isDumpingEnabled_;
394  new_h->dumpLevel_ = dumpLevel_;
395  new_h->dumpFile_ = dumpFile_;
396 
397  RCP<SmootherBase> Pre, Post;
398  RCP<CloneSmoother> clonePre, clonePost;
399  RCP<CloneOperator> cloneA, cloneR, cloneP;
400  RCP<Operator> A, R, P;
401  for (int i = 0; i < GetNumLevels(); i++) {
402  RCP<Level> level = this->Levels_[i];
403  RCP<Level> clonelevel = rcp(new Level());
404 
405  if (level->IsAvailable("A")) {
406  A = level->template Get<RCP<Operator> >("A");
407  cloneA = Xpetra::clone<Scalar, LocalOrdinal, GlobalOrdinal, Node, Node2>(*A, node2);
408  clonelevel->template Set<RCP<CloneOperator> >("A", cloneA);
409  }
410  if (level->IsAvailable("R")){
411  R = level->template Get<RCP<Operator> >("R");
412  cloneR = Xpetra::clone<Scalar, LocalOrdinal, GlobalOrdinal, Node, Node2>(*R, node2);
413  clonelevel->template Set<RCP<CloneOperator> >("R", cloneR);
414  }
415  if (level->IsAvailable("P")){
416  P = level->template Get<RCP<Operator> >("P");
417  cloneP = Xpetra::clone<Scalar, LocalOrdinal, GlobalOrdinal, Node, Node2>(*P, node2);
418  clonelevel->template Set<RCP<CloneOperator> >("P", cloneP);
419  }
420  if (level->IsAvailable("PreSmoother")){
421  Pre = level->template Get<RCP<SmootherBase> >("PreSmoother");
422  clonePre = MueLu::clone<Scalar, LocalOrdinal, GlobalOrdinal, Node, Node2> (Pre, cloneA, node2);
423  clonelevel->template Set<RCP<CloneSmoother> >("PreSmoother", clonePre);
424  }
425  if (level->IsAvailable("PostSmoother")){
426  Post = level->template Get<RCP<SmootherBase> >("PostSmoother");
427  clonePost = MueLu::clone<Scalar, LocalOrdinal, GlobalOrdinal, Node, Node2> (Post, cloneA, node2);
428  clonelevel-> template Set<RCP<CloneSmoother> >("PostSmoother", clonePost);
429  }
430  new_h->Levels_[i] = clonelevel;
431  }
432 
433  return new_h;
434  }
435 
436 } //namespace MueLu
437 
438 #define MUELU_HIERARCHY_SHORT
439 #endif // MUELU_HIERARCHY_DECL_HPP
void IsPreconditioner(const bool flag)
This class specifies the default factory that should generate some data on a Level if the data does n...
RCP< Level > & GetLevel(const int levelID=0)
Retrieve a certain level from hierarchy.
Teuchos::RCP< Hierarchy< Scalar, LocalOrdinal, GlobalOrdinal, Node2 > > clone(const RCP< Node2 > &node2) const
Hierarchy()
Default constructor.
Print parameters.
void AddLevel(const RCP< Level > &level)
Add a level at the end of the hierarchy.
short KeepType
void SetMaxCoarseSize(Xpetra::global_size_t maxCoarseSize)
void AddNewLevel()
Add a new level at the end of the hierarchy.
LocalOrdinal LO
static Xpetra::global_size_t GetDefaultMaxCoarseSize()
void SetCycle(CycleType Cycle)
Supports VCYCLE and WCYCLE types.
void Clear(int startLevel=0)
Clear impermanent data from previous setup.
Namespace for MueLu classes and methods.
Teuchos::ScalarTraits< SC > STS
MagnitudeType rate_
Convergece rate.
static const NoFactory * get()
void ReplaceCoordinateMap(Level &level)
void AddKeepFlag(const std::string &ename, const FactoryBase *factory=NoFactory::get(), KeepType keep=MueLu::Keep)
Call Level::AddKeepFlag for each level of the Hierarchy.
void print(std::ostream &out=std::cout, const VerbLevel verbLevel=(MueLu::Parameters|MueLu::Statistics0)) const
Xpetra::UnderlyingLib lib()
GlobalOrdinal global_ordinal_type
Base class for factories (e.g., R, P, and A_coarse).
Print statistics that do not involve significant additional computation.
ConvData(std::pair< LO, MagnitudeType > p)
Xpetra::UnderlyingLib lib_
CycleType GetCycle() const
Returns multigrid cycle type (supports VCYCLE and WCYCLE)
static CycleType GetDefaultCycle()
void Write(const LO &start=-1, const LO &end=-1, const std::string &suffix="")
Print matrices in the multigrid hierarchy to file.
Class that holds all level-specific information.
Definition: MueLu_Level.hpp:99
LocalOrdinal local_ordinal_type
Class that provides default factories within Needs class.
void RemoveKeepFlag(const std::string &ename, const FactoryBase *factory, KeepType keep=MueLu::All)
Call Level::RemoveKeepFlag for each level of the Hierarchy.
int GetGlobalNumLevels() const
void CheckLevel(Level &level, int levelID)
Helper function.
const RCP< const FactoryManagerBase > & GetLevelManager(const int levelID) const
Always keep data, even accross run. This flag is set by Level::Keep(). This flag is propagated to coa...
static bool GetDefaultImplicitTranspose()
void describe(Teuchos::FancyOStream &out, const VerbLevel verbLevel=Default) const
Print the Hierarchy with some verbosity level to a FancyOStream object.
bool GetImplicitTranspose() const
void SetPRrebalance(bool doPRrebalance)
size_t global_size_t
Base class for smoothers.
double GetOperatorComplexity() const
static int GetDefaultMaxLevels()
Base class for MueLu classes.
void SetImplicitTranspose(const bool &implicit)
virtual ~Hierarchy()
Destructor.
Data struct for defining stopping criteria of multigrid iteration.
STS::magnitudeType MagnitudeType
void Delete(const std::string &ename, const FactoryBase *factory=NoFactory::get())
Call Level::Delete(ename, factory) for each level of the Hierarchy.
MagnitudeType GetRate() const
Array< RCP< Level > > Levels_
Container for Level objects.
static bool GetDefaultPRrebalance()
Xpetra::global_size_t GetMaxCoarseSize() const
ReturnType Iterate(const MultiVector &B, MultiVector &X, ConvData conv=ConvData(), bool InitialGuessIsZero=false, LO startLevel=0)
Apply the multigrid preconditioner.
void Keep(const std::string &ename, const FactoryBase *factory=NoFactory::get())
Call Level::Keep(ename, factory) for each level of the Hierarchy.
bool isDumpingEnabled_
Graph dumping.
void setlib(Xpetra::UnderlyingLib inlib)
std::string description() const
Return a simple one-line description of this object.
bool Setup(int coarseLevelID, const RCP< const FactoryManagerBase > fineLevelManager, const RCP< const FactoryManagerBase > coarseLevelManager, const RCP< const FactoryManagerBase > nextLevelManager=Teuchos::null)
Multi-level setup phase: build a new level of the hierarchy.
void EnableGraphDumping(const std::string &filename, int levelID=1)
Provides methods to build a multigrid hierarchy and apply multigrid cycles.
Array< RCP< const FactoryManagerBase > > levelManagers_
Xpetra::global_size_t maxCoarseSize_