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>
54 #include <Xpetra_MultiVector_fwd.hpp>
55 #include <Xpetra_MultiVectorFactory_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,
101  class GlobalOrdinal = typename Xpetra::Operator<Scalar, LocalOrdinal>::global_ordinal_type,
102  class Node = typename Xpetra::Operator<Scalar, LocalOrdinal, GlobalOrdinal>::node_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 
118  MagnitudeType tol_;
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 
147  Xpetra::global_size_t GetMaxCoarseSize() const { return maxCoarseSize_; }
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);
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; }
324  Xpetra::UnderlyingLib lib() { return lib_; }
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
346  Xpetra::global_size_t maxCoarseSize_;
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
363  Xpetra::UnderlyingLib lib_;
364 
366  // If enabled, we dump the graph on a specified level into a specified file
369  std::string dumpFile_;
370 
372  MagnitudeType rate_;
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 {
385  typedef Xpetra::Matrix<Scalar, LocalOrdinal, GlobalOrdinal, Node2> CloneOperator;
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.
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)
Xpetra::global_size_t GetMaxCoarseSize() const
void AddNewLevel()
Add a new level at the end of the hierarchy.
static Xpetra::global_size_t GetDefaultMaxCoarseSize()
void DumpCurrentGraph() const
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.
void Write(const LO &start=-1, const LO &end=-1)
Print matrices in the multigrid hierarchy to file.
bool GetImplicitTranspose() const
const RCP< const FactoryManagerBase > & GetLevelManager(const int levelID) const
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.
Teuchos::RCP< Hierarchy< Scalar, LocalOrdinal, GlobalOrdinal, Node2 > > clone(const RCP< Node2 > &node2) const
void print(std::ostream &out=std::cout, const VerbLevel verbLevel=(MueLu::Parameters|MueLu::Statistics0)) const
Xpetra::UnderlyingLib lib()
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_
static CycleType GetDefaultCycle()
Class that holds all level-specific information.
Definition: MueLu_Level.hpp:99
std::string description() const
Return a simple one-line description of this object.
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.
void CheckLevel(Level &level, int levelID)
Helper function.
Always keep data, even accross run. This flag is set by Level::Keep(). This flag is propagated to coa...
static bool GetDefaultImplicitTranspose()
void SetPRrebalance(bool doPRrebalance)
Base class for smoothers.
int GetGlobalNumLevels() const
static int GetDefaultMaxLevels()
CycleType GetCycle() const
Returns multigrid cycle type (supports VCYCLE and WCYCLE)
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.
Array< RCP< Level > > Levels_
Container for Level objects.
static bool GetDefaultPRrebalance()
MagnitudeType GetRate() const
void describe(Teuchos::FancyOStream &out, const VerbLevel verbLevel=Default) const
Print the Hierarchy with some verbosity level to a FancyOStream object.
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)
double GetOperatorComplexity() const
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_