MueLu_Hierarchy_decl.hpp

Go to the documentation of this file.

// @HEADER
//
// ***********************************************************************
//
//        MueLu: A package for multigrid based preconditioning
//                  Copyright 2012 Sandia Corporation
//
// Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
// the U.S. Government retains certain rights in this software.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact
//                    Jonathan Hu       (jhu@sandia.gov)
//                    Andrey Prokopenko (aprokop@sandia.gov)
//                    Ray Tuminaro      (rstumin@sandia.gov)
//
// ***********************************************************************
//
// @HEADER
#ifndef MUELU_HIERARCHY_DECL_HPP
#define MUELU_HIERARCHY_DECL_HPP

#include <Teuchos_ParameterList.hpp>
#include <Teuchos_Ptr.hpp>

#include <Xpetra_ConfigDefs.hpp>  // global_size_t
#include <Xpetra_Matrix_fwd.hpp>
#include <Xpetra_MultiVector_fwd.hpp>
#include <Xpetra_MultiVectorFactory_fwd.hpp>
#include <Xpetra_Operator_fwd.hpp>

#include <MueLu_SmootherCloner.hpp>
#include "MueLu_ConfigDefs.hpp"
#include "MueLu_BaseClass.hpp"
#include "MueLu_Hierarchy_fwd.hpp"

#include "MueLu_Types.hpp"

#include "MueLu_FactoryBase_fwd.hpp"
#include "MueLu_FactoryManager.hpp"  // no fwd declaration because constructor of FactoryManager is used as a default parameter of Setup()
#include "MueLu_KeepType.hpp"
#include "MueLu_Level_fwd.hpp"
#include "MueLu_MasterList.hpp"
#include "MueLu_NoFactory.hpp"
#include "MueLu_PerfUtils_fwd.hpp"
#include "MueLu_PFactory_fwd.hpp"
#include "MueLu_SmootherBase_fwd.hpp"
#include "MueLu_SmootherFactory_fwd.hpp"
#include "MueLu_Utilities_fwd.hpp"

namespace MueLu {

enum class ConvergenceStatus {
  Converged,
  Unconverged,
  Undefined
};

template <class Scalar        = DefaultScalar,
          class LocalOrdinal  = DefaultLocalOrdinal,
          class GlobalOrdinal = DefaultGlobalOrdinal,
          class Node          = DefaultNode>
class Hierarchy : public BaseClass {
#undef MUELU_HIERARCHY_SHORT
#include "MueLu_UseShortNames.hpp"

  typedef Teuchos::ScalarTraits<SC> STS;
  typedef typename STS::magnitudeType MagnitudeType;

  struct ConvData {
    ConvData()
      : maxIts_(1)
      , tol_(-STS::magnitude(STS::one())) {}
    ConvData(LO maxIts)
      : maxIts_(maxIts)
      , tol_(-STS::magnitude(STS::one())) {}
    ConvData(MagnitudeType tol)
      : maxIts_(10000)
      , tol_(tol) {}
    ConvData(std::pair<LO, MagnitudeType> p)
      : maxIts_(p.first)
      , tol_(p.second) {}

    LO maxIts_;
    MagnitudeType tol_;
  };

 public:


  Hierarchy();
  Hierarchy(const std::string& label);

  Hierarchy(const RCP<Matrix>& A);

  Hierarchy(const RCP<Matrix>& A, const std::string& label);

  virtual ~Hierarchy() {}




  static CycleType GetDefaultCycle() { return MasterList::getDefault<std::string>("cycle type") == "V" ? VCYCLE : WCYCLE; }
  static int GetDefaultCycleStartLevel() { return MasterList::getDefault<int>("W cycle start level"); }
  static bool GetDefaultImplicitTranspose() { return MasterList::getDefault<bool>("transpose: use implicit"); }
  static bool GetDefaultFuseProlongationAndUpdate() { return MasterList::getDefault<bool>("fuse prolongation and update"); }
  static Xpetra::global_size_t GetDefaultMaxCoarseSize() { return MasterList::getDefault<int>("coarse: max size"); }
  static int GetDefaultMaxLevels() { return MasterList::getDefault<int>("max levels"); }
  static bool GetDefaultPRrebalance() { return MasterList::getDefault<bool>("repartition: rebalance P and R"); }

  Xpetra::global_size_t GetMaxCoarseSize() const { return maxCoarseSize_; }
  bool GetImplicitTranspose() const { return implicitTranspose_; }
  bool GetFuseProlongationAndUpdate() const { return fuseProlongationAndUpdate_; }

  void SetMaxCoarseSize(Xpetra::global_size_t maxCoarseSize) { maxCoarseSize_ = maxCoarseSize; }
  void SetPRrebalance(bool doPRrebalance) { doPRrebalance_ = doPRrebalance; }
  void SetPRViaCopyrebalance(bool doPRViaCopyrebalance) { doPRViaCopyrebalance_ = doPRViaCopyrebalance; }
  void SetImplicitTranspose(const bool& implicit) { implicitTranspose_ = implicit; }
  void SetFuseProlongationAndUpdate(const bool& fuse) { fuseProlongationAndUpdate_ = fuse; }



  template <class S2, class LO2, class GO2, class N2>
  friend class Hierarchy;

 private:
  int LastLevelID() const { return Levels_.size() - 1; }
  void DumpCurrentGraph(int level) const;

 public:
  void AddLevel(const RCP<Level>& level);

  void AddNewLevel();

  RCP<Level>& GetLevel(const int levelID = 0);

  int GetNumLevels() const;
  int GetGlobalNumLevels() const;

  MagnitudeType GetRate() const { return rate_; }

  // This function is global
  double GetOperatorComplexity() const;

  // This function is global
  double GetSmootherComplexity() const;

  void CheckLevel(Level& level, int levelID);

  void SetMatvecParams(RCP<ParameterList> matvecParams);


  bool Setup(int coarseLevelID, const RCP<const FactoryManagerBase> fineLevelManager /* = Teuchos::null */, const RCP<const FactoryManagerBase> coarseLevelManager,
             const RCP<const FactoryManagerBase> nextLevelManager = Teuchos::null);

  void Setup(const FactoryManagerBase& manager = FactoryManager(), int startLevel = 0, int numDesiredLevels = GetDefaultMaxLevels());

  void SetupRe();

  void CheckForEmptySmoothersAndCoarseSolve();

  void Clear(int startLevel = 0);
  void ExpertClear();

  CycleType GetCycle() const { return Cycle_; }

  void SetCycle(CycleType Cycle) { Cycle_ = Cycle; }

  void SetCycleStartLevel(int cycleStart) { WCycleStartLevel_ = cycleStart; }

  void SetProlongatorScalingFactor(double scalingFactor) { scalingFactor_ = scalingFactor; }

  ConvergenceStatus Iterate(const MultiVector& B, MultiVector& X, ConvData conv = ConvData(),
                            bool InitialGuessIsZero = false, LO startLevel = 0);

  void Write(const LO& start = -1, const LO& end = -1, const std::string& suffix = "");




  void Keep(const std::string& ename, const FactoryBase* factory = NoFactory::get());

  void Delete(const std::string& ename, const FactoryBase* factory = NoFactory::get());

  void AddKeepFlag(const std::string& ename, const FactoryBase* factory = NoFactory::get(), KeepType keep = MueLu::Keep);

  void RemoveKeepFlag(const std::string& ename, const FactoryBase* factory, KeepType keep = MueLu::All);




  std::string description() const;

  void describe(Teuchos::FancyOStream& out, const VerbLevel verbLevel = Default) const;
  void describe(Teuchos::FancyOStream& out, const Teuchos::EVerbosityLevel verbLevel = Teuchos::VERB_HIGH) const;

  void print(std::ostream& out = std::cout, const VerbLevel verbLevel = (MueLu::Parameters | MueLu::Statistics0)) const;

  void IsPreconditioner(const bool flag);


  void EnableGraphDumping(const std::string& filename, int levelID = 1) {
    isDumpingEnabled_ = true;
    dumpLevel_        = levelID;
    dumpFile_         = filename;
  }

  void setlib(Xpetra::UnderlyingLib inlib) { lib_ = inlib; }
  Xpetra::UnderlyingLib lib() { return lib_; }

  void ResetDescription() {
    description_ = "";
  }

  void AllocateLevelMultiVectors(int numvecs, bool forceMapCheck = false);
  void DeleteLevelMultiVectors();

 protected:
  const RCP<const FactoryManagerBase>& GetLevelManager(const int levelID) const {
    return levelManagers_[levelID];
  }

 private:
  Hierarchy(const Hierarchy& h);

  bool IsCalculationOfResidualRequired(const LO startLevel, const ConvData& conv) const;

  ConvergenceStatus IsConverged(const Teuchos::Array<MagnitudeType>& residualNorm,
                                const MagnitudeType convergenceTolerance) const;

  void PrintResidualHistory(const LO iteration,
                            const Teuchos::Array<MagnitudeType>& residualNorm) const;

  ConvergenceStatus ComputeResidualAndPrintHistory(const Operator& A, const MultiVector& X,
                                                   const MultiVector& B, const LO iteration,
                                                   const LO startLevel, const ConvData& conv, MagnitudeType& previousResidualNorm);

  Array<RCP<Level> > Levels_;

  void ReplaceCoordinateMap(Level& level);

  Xpetra::global_size_t maxCoarseSize_;

  bool implicitTranspose_;

  bool fuseProlongationAndUpdate_;

  bool doPRrebalance_;
  bool doPRViaCopyrebalance_;  // fully explicit, needed for CombinePFactory

  bool isPreconditioner_;

  CycleType Cycle_;

  int WCycleStartLevel_;

  double scalingFactor_;

  Xpetra::UnderlyingLib lib_;

  mutable std::string description_ = "";  // mutable so that we can lazily initialize in description(), which is declared const

  bool isDumpingEnabled_;
  // -1 = dump all levels, -2 = dump nothing
  int dumpLevel_;
  std::string dumpFile_;

  MagnitudeType rate_;

  Array<RCP<const FactoryManagerBase> > levelManagers_;

  int sizeOfAllocatedLevelMultiVectors_;
  Array<RCP<MultiVector> > residual_, coarseRhs_, coarseX_, coarseImport_, coarseExport_, correction_;

};  // class Hierarchy

}  // namespace MueLu

#define MUELU_HIERARCHY_SHORT
#endif  // MUELU_HIERARCHY_DECL_HPP