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 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