MueLu Version of the Day
Loading...
Searching...
No Matches
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
59#include "MueLu_ConfigDefs.hpp"
60#include "MueLu_BaseClass.hpp"
62
63#include "MueLu_Types.hpp"
64
66#include "MueLu_FactoryManager.hpp" // no fwd declaration because constructor of FactoryManager is used as a default parameter of Setup()
68#include "MueLu_KeepType.hpp"
69#include "MueLu_Level_fwd.hpp"
70#include "MueLu_MasterList.hpp"
71#include "MueLu_NoFactory.hpp"
80
81namespace MueLu {
82
83 enum class ConvergenceStatus {
87 };
88
99 template <class Scalar = DefaultScalar,
102 class Node = DefaultNode>
103 class Hierarchy : public BaseClass {
104#undef MUELU_HIERARCHY_SHORT
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();
129 Hierarchy(const std::string& label);
130
132 Hierarchy(const RCP<Matrix> & A);
133
135 Hierarchy(const RCP<Matrix> & A, const std::string& label);
136
138 virtual ~Hierarchy() { }
139
141
143
144
146 static CycleType GetDefaultCycle() { return MasterList::getDefault<std::string>("cycle type") == "V" ? VCYCLE : WCYCLE; }
147 static int GetDefaultCycleStartLevel() { return MasterList::getDefault<int>("W cycle start level"); }
148 static bool GetDefaultImplicitTranspose() { return MasterList::getDefault<bool>("transpose: use implicit"); }
149 static bool GetDefaultFuseProlongationAndUpdate() { return MasterList::getDefault<bool>("fuse prolongation and update"); }
150 static Xpetra::global_size_t GetDefaultMaxCoarseSize() { return MasterList::getDefault<int>("coarse: max size"); }
151 static int GetDefaultMaxLevels() { return MasterList::getDefault<int>("max levels"); }
152 static bool GetDefaultPRrebalance() { return MasterList::getDefault<bool>("repartition: rebalance P and R"); }
153
154 Xpetra::global_size_t GetMaxCoarseSize() const { return maxCoarseSize_; }
157
158 void SetMaxCoarseSize(Xpetra::global_size_t maxCoarseSize) { maxCoarseSize_ = maxCoarseSize; }
159 void SetPRrebalance(bool doPRrebalance) { doPRrebalance_ = doPRrebalance; }
160 void SetImplicitTranspose(const bool& implicit) { implicitTranspose_ = implicit; }
162
164
166
167 template<class S2, class LO2, class GO2, class N2>
168 friend class Hierarchy;
169
170 private:
171 int LastLevelID() const { return Levels_.size() - 1; }
172 void DumpCurrentGraph(int level) const;
173
174 public:
175
177 void AddLevel(const RCP<Level> & level);
178
180 void AddNewLevel();
181
183 RCP<Level> & GetLevel(const int levelID = 0);
184
185 int GetNumLevels() const;
186 int GetGlobalNumLevels() const;
187
188 MagnitudeType GetRate() const { return rate_; }
189
190 // This function is global
191 double GetOperatorComplexity() const;
192
193 // This function is global
194 double GetSmootherComplexity() const;
195
197 void CheckLevel(Level& level, int levelID);
198
199 void SetMatvecParams(RCP<ParameterList> matvecParams);
200
202
239 bool Setup(int coarseLevelID, const RCP<const FactoryManagerBase> fineLevelManager /* = Teuchos::null */, const RCP<const FactoryManagerBase> coarseLevelManager,
240 const RCP<const FactoryManagerBase> nextLevelManager = Teuchos::null);
241
243 void Setup(const FactoryManagerBase& manager = FactoryManager(), int startLevel = 0, int numDesiredLevels = GetDefaultMaxLevels());
244
245 void SetupRe();
246
248 void Clear(int startLevel = 0);
249 void ExpertClear();
250
252 CycleType GetCycle() const { return Cycle_; }
253
255 void SetCycle(CycleType Cycle) { Cycle_ = Cycle; }
256
257 void SetCycleStartLevel(int cycleStart) { WCycleStartLevel_ = cycleStart; }
258
260 void SetProlongatorScalingFactor(double scalingFactor) { scalingFactor_ = scalingFactor; }
261
274 ConvergenceStatus Iterate(const MultiVector& B, MultiVector& X, ConvData conv = ConvData(),
275 bool InitialGuessIsZero = false, LO startLevel = 0);
276
286 void Write(const LO &start=-1, const LO &end=-1, const std::string &suffix="");
287
289
291
292
294 void Keep(const std::string & ename, const FactoryBase* factory = NoFactory::get());
295
297 void Delete(const std::string& ename, const FactoryBase* factory = NoFactory::get());
298
300 void AddKeepFlag(const std::string & ename, const FactoryBase* factory = NoFactory::get(), KeepType keep = MueLu::Keep);
301
303 void RemoveKeepFlag(const std::string & ename, const FactoryBase* factory, KeepType keep = MueLu::All);
304
306
308
309
311 std::string description() const;
312
318 void describe(Teuchos::FancyOStream& out, const VerbLevel verbLevel = Default) const;
319 void describe(Teuchos::FancyOStream& out, const Teuchos::EVerbosityLevel verbLevel = Teuchos::VERB_HIGH) const;
320
322 void print(std::ostream& out = std::cout, const VerbLevel verbLevel = (MueLu::Parameters | MueLu::Statistics0)) const;
323
328 void IsPreconditioner(const bool flag);
329
331
332 void EnableGraphDumping(const std::string& filename, int levelID = 1) {
333 isDumpingEnabled_ = true;
334 dumpLevel_ = levelID;
335 dumpFile_ = filename;
336 }
337
338 void setlib(Xpetra::UnderlyingLib inlib) { lib_ = inlib; }
339 Xpetra::UnderlyingLib lib() { return lib_; }
340
343 description_ = "";
344 }
345
346 void AllocateLevelMultiVectors(int numvecs, bool forceMapCheck=false);
348
349 protected:
350 const RCP<const FactoryManagerBase>& GetLevelManager(const int levelID) const {
351 return levelManagers_[levelID];
352 }
353
354 private:
357
359 bool IsCalculationOfResidualRequired(const LO startLevel, const ConvData& conv) const;
360
368 ConvergenceStatus IsConverged(const Teuchos::Array<MagnitudeType>& residualNorm,
369 const MagnitudeType convergenceTolerance) const;
370
372 void PrintResidualHistory(const LO iteration,
373 const Teuchos::Array<MagnitudeType>& residualNorm) const;
374
376 ConvergenceStatus ComputeResidualAndPrintHistory(const Operator& A, const MultiVector& X,
377 const MultiVector& B, const LO iteration,
378 const LO startLevel, const ConvData& conv, MagnitudeType& previousResidualNorm);
379
381 Array<RCP<Level> > Levels_;
382
387 void ReplaceCoordinateMap(Level& level);
388
391 Xpetra::global_size_t maxCoarseSize_;
392
396
400
404
407
410
413
416
418 Xpetra::UnderlyingLib lib_;
419
421 mutable std::string description_ = ""; // mutable so that we can lazily initialize in description(), which is declared const
422
429 // -1 = dump all levels, -2 = dump nothing
431 std::string dumpFile_;
432
435
437 Array<RCP<const FactoryManagerBase> > levelManagers_;
438
442
443
444 }; //class Hierarchy
445
446} //namespace MueLu
447
448#define MUELU_HIERARCHY_SHORT
449#endif // MUELU_HIERARCHY_DECL_HPP
MueLu::DefaultLocalOrdinal LocalOrdinal
MueLu::DefaultScalar Scalar
MueLu::DefaultGlobalOrdinal GlobalOrdinal
MueLu::DefaultNode Node
Base class for MueLu classes.
Base class for factories (e.g., R, P, and A_coarse).
Class that provides default factories within Needs class.
This class specifies the default factory that should generate some data on a Level if the data does n...
Provides methods to build a multigrid hierarchy and apply multigrid cycles.
void AddLevel(const RCP< Level > &level)
Add a level at the end of the hierarchy.
double GetSmootherComplexity() const
void Write(const LO &start=-1, const LO &end=-1, const std::string &suffix="")
Print matrices in the multigrid hierarchy to file.
RCP< Level > & GetLevel(const int levelID=0)
Retrieve a certain level from hierarchy.
Array< RCP< MultiVector > > residual_
void CheckLevel(Level &level, int levelID)
Helper function.
int WCycleStartLevel_
Level at which to start W-cycle.
std::string description() const
Return a simple one-line description of this object.
std::string description_
cache description to avoid recreating in each call to description() - use ResetDescription() to force...
void IsPreconditioner(const bool flag)
static CycleType GetDefaultCycle()
Array< RCP< Level > > Levels_
Container for Level objects.
static bool GetDefaultPRrebalance()
Array< RCP< MultiVector > > coarseRhs_
Array< RCP< MultiVector > > coarseExport_
void setlib(Xpetra::UnderlyingLib inlib)
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 ResetDescription()
force recreation of cached description_ next time description() is called:
STS::magnitudeType MagnitudeType
void SetFuseProlongationAndUpdate(const bool &fuse)
void describe(Teuchos::FancyOStream &out, const VerbLevel verbLevel=Default) const
Print the Hierarchy with some verbosity level to a FancyOStream object.
virtual ~Hierarchy()
Destructor.
bool isPreconditioner_
Hierarchy may be used in a standalone mode, or as a preconditioner.
void SetPRrebalance(bool doPRrebalance)
CycleType GetCycle() const
Returns multigrid cycle type (supports VCYCLE and WCYCLE)
Xpetra::global_size_t GetMaxCoarseSize() const
ConvergenceStatus IsConverged(const Teuchos::Array< MagnitudeType > &residualNorm, const MagnitudeType convergenceTolerance) const
Decide if the multigrid iteration is converged.
ConvergenceStatus Iterate(const MultiVector &B, MultiVector &X, ConvData conv=ConvData(), bool InitialGuessIsZero=false, LO startLevel=0)
Apply the multigrid preconditioner.
void SetCycleStartLevel(int cycleStart)
void DumpCurrentGraph(int level) const
int sizeOfAllocatedLevelMultiVectors_
Caching (Multi)Vectors used in Hierarchy::Iterate()
static bool GetDefaultImplicitTranspose()
void SetMatvecParams(RCP< ParameterList > matvecParams)
static Xpetra::global_size_t GetDefaultMaxCoarseSize()
Xpetra::UnderlyingLib lib_
Epetra/Tpetra mode.
void Clear(int startLevel=0)
Clear impermanent data from previous setup.
void EnableGraphDumping(const std::string &filename, int levelID=1)
bool IsCalculationOfResidualRequired(const LO startLevel, const ConvData &conv) const
Decide if the residual needs to be computed.
void SetMaxCoarseSize(Xpetra::global_size_t maxCoarseSize)
CycleType Cycle_
V- or W-cycle.
ConvergenceStatus ComputeResidualAndPrintHistory(const Operator &A, const MultiVector &X, const MultiVector &B, const LO iteration, const LO startLevel, const ConvData &conv, MagnitudeType &previousResidualNorm)
Compute the residual norm and print it depending on the verbosity level.
Teuchos::ScalarTraits< SC > STS
double GetOperatorComplexity() const
MagnitudeType rate_
Convergece rate.
void PrintResidualHistory(const LO iteration, const Teuchos::Array< MagnitudeType > &residualNorm) const
Print residualNorm for this iteration to the screen.
Array< RCP< MultiVector > > coarseX_
void AllocateLevelMultiVectors(int numvecs, bool forceMapCheck=false)
void print(std::ostream &out=std::cout, const VerbLevel verbLevel=(MueLu::Parameters|MueLu::Statistics0)) const
Hierarchy::print is local hierarchy function, thus the statistics can be different from global ones.
double scalingFactor_
Scaling factor to be applied to coarse grid correction.
Hierarchy(const Hierarchy &h)
Copy constructor is not implemented.
bool GetFuseProlongationAndUpdate() const
void Delete(const std::string &ename, const FactoryBase *factory=NoFactory::get())
Call Level::Delete(ename, factory) for each level of the Hierarchy.
Xpetra::UnderlyingLib lib()
static bool GetDefaultFuseProlongationAndUpdate()
const RCP< const FactoryManagerBase > & GetLevelManager(const int levelID) const
MagnitudeType GetRate() const
Array< RCP< MultiVector > > coarseImport_
bool isDumpingEnabled_
Graph dumping.
Xpetra::global_size_t maxCoarseSize_
void AddKeepFlag(const std::string &ename, const FactoryBase *factory=NoFactory::get(), KeepType keep=MueLu::Keep)
Call Level::AddKeepFlag for each level of the Hierarchy.
static int GetDefaultCycleStartLevel()
Array< RCP< MultiVector > > correction_
void SetCycle(CycleType Cycle)
Supports VCYCLE and WCYCLE types.
void AddNewLevel()
Add a new level at the end of the hierarchy.
void RemoveKeepFlag(const std::string &ename, const FactoryBase *factory, KeepType keep=MueLu::All)
Call Level::RemoveKeepFlag for each level of the Hierarchy.
void SetProlongatorScalingFactor(double scalingFactor)
Specify damping factor alpha such that x = x + alpha*P*c, where c is the coarse grid correction.
Array< RCP< const FactoryManagerBase > > levelManagers_
Level managers used during the Setup.
bool GetImplicitTranspose() const
void SetImplicitTranspose(const bool &implicit)
void ReplaceCoordinateMap(Level &level)
Class that holds all level-specific information.
static const NoFactory * get()
Namespace for MueLu classes and methods.
@ Keep
Always keep data, even accross run. This flag is set by Level::Keep(). This flag is propagated to coa...
KokkosClassic::DefaultNode::DefaultNodeType DefaultNode
@ Parameters
Print parameters.
@ Statistics0
Print statistics that do not involve significant additional computation.
short KeepType
Tpetra::Details::DefaultTypes::scalar_type DefaultScalar
Data struct for defining stopping criteria of multigrid iteration.
ConvData(std::pair< LO, MagnitudeType > p)