MueLu_Level.hpp

Go to the documentation of this file.

// @HEADER
// *****************************************************************************
//        MueLu: A package for multigrid based preconditioning
//
// Copyright 2012 NTESS and the MueLu contributors.
// SPDX-License-Identifier: BSD-3-Clause
// *****************************************************************************
// @HEADER

#ifndef MUELU_LEVEL_HPP
#define MUELU_LEVEL_HPP

#include <algorithm>  // for swap
#include <map>        // for _Rb_tree_const_iterator, etc
#include <ostream>    // for basic_ostream, etc
#include <string>     // for char_traits, string, etc
#include <utility>    // for pair

#include <Teuchos_Describable.hpp>       // for operator<<
#include <Teuchos_FancyOStream.hpp>      // for FancyOStream
#include <Teuchos_RCPDecl.hpp>           // for RCP
#include <Teuchos_RCP.hpp>               // for RCP::operator->, etc
#include <Teuchos_TestForException.hpp>  // for TEUCHOS_TEST_FOR_EXCEPTION

#include <Xpetra_Map.hpp>  // for UnderlyingLib definition

#include "MueLu_BoostGraphviz.hpp"
#include "MueLu_Exceptions.hpp"  // for RuntimeError
#include "MueLu_FactoryManagerBase_fwd.hpp"
#include "MueLu_KeepType.hpp"
#include "MueLu_NoFactory.hpp"
#include "MueLu_Utilities.hpp"
#include "MueLu_VariableContainer.hpp"
#include "MueLu_VerbosityLevel.hpp"  // for MsgType::Default, VerbLevel

namespace MueLu {

class Level : public BaseClass {
 public:


  Level();

  Level(RCP<FactoryManagerBase>& factoryManager);

  virtual ~Level();


  RCP<Level> Build();



  int GetLevelID() const;

  void SetLevelID(int levelID);

  RCP<Level>& GetPreviousLevel();

  void SetPreviousLevel(const RCP<Level>& previousLevel);


  // Users should not use this method.
  void SetFactoryManager(const RCP<const FactoryManagerBase>& factoryManager);

  // Users should not use this method
  const RCP<const FactoryManagerBase> GetFactoryManager();


  template <class T>
  void Set(const std::string& ename, const T& entry, const FactoryBase* factory = NoFactory::get()) {
    const FactoryBase* fac = GetFactory(ename, factory);

    if (fac == NoFactory::get()) {
      // Any data set with a NoFactory gets UserData keep flag by default
      AddKeepFlag(ename, NoFactory::get(), MueLu::UserData);
    }

    // Store entry only if data have been requested (or any keep flag)
    if (IsRequested(ename, factory) || GetKeepFlag(ename, factory) != 0) {
      TEUCHOS_TEST_FOR_EXCEPTION(!IsKey(factory, ename), Exceptions::RuntimeError, "" + ename + " not found in");
      map_[factory][ename]->SetData(entry);

    } else {
      GetOStream(Runtime1) << "Level::Set: Not storing \"" << ename << "\" generated by factory " << factory->ShortClassName() << "[" << factory->GetID() << "]"
                           << " on level " << toString(GetLevelID()) << ", as it has not been requested and no keep flags were set for it" << std::endl;
    }
  }  // Set




  template <class T>
  T& Get(const std::string& ename, const FactoryBase* factory = NoFactory::get()) {
    const FactoryBase* fac = GetFactory(ename, factory);
    /*      printf("(l=%d)                                               getting    \"%20s\" generated by %10p  [actually, generated by %p (%43s)]\n",
            levelID_, ename.c_str(), factory, fac, fac->description().c_str());*/

    TEUCHOS_TEST_FOR_EXCEPTION(!IsKey(fac, ename), Exceptions::RuntimeError, "\"" + ename + "\" generated by factory \"" + fac->description() + "\" not found on level " + toString(GetLevelID()) + ".");

    if (!IsAvailable(ename, fac)) {
      TEUCHOS_TEST_FOR_EXCEPTION(NumRequests(fac, ename) < 1 && GetKeepFlag(ename, fac) == 0, Exceptions::RuntimeError,
                                 "\"" << ename << "\" has not been requested (counter = " << NumRequests(fac, ename) << ", "
                                                                                                                        "KeepFlag = "
                                      << GetKeepFlag(ename, fac) << "). " << std::endl
                                      << "Generating factory:" << *fac << " NoFactory = " << NoFactory::get());
      fac->CallBuild(*this);
      Release(*fac);
    }

    TEUCHOS_TEST_FOR_EXCEPTION(!IsAvailable(ename, fac), Exceptions::RuntimeError,
                               "MueLu::Level::Get(): factory did not produce expected output on level " << GetLevelID()
                                                                                                        << ". The data \"" << ename << "\" has not been generated by " << *fac);

    return map_[fac][ename]->template GetData<T>();
  }

  template <class T>
  void Get(const std::string& ename, T& rValue, const FactoryBase* factory = NoFactory::get()) {
    rValue = Get<T>(ename, factory);
  }

  template <class T>
  bool IsType(const std::string& ename, const FactoryBase* factory = NoFactory::get()) {
    const FactoryBase* fac = GetFactory(ename, factory);

    TEUCHOS_TEST_FOR_EXCEPTION(!IsKey(fac, ename), Exceptions::RuntimeError, "\"" + ename + "\" generated by factory \"" + fac->description() + "\" not found on level " + toString(GetLevelID()) + ".");

    if (!IsAvailable(ename, fac)) {
      TEUCHOS_TEST_FOR_EXCEPTION(NumRequests(fac, ename) < 1 && GetKeepFlag(ename, fac) == 0, Exceptions::RuntimeError,
                                 "\"" << ename << "\" has not been requested (counter = " << NumRequests(fac, ename) << ", "
                                                                                                                        "KeepFlag = "
                                      << GetKeepFlag(ename, fac) << "). " << std::endl
                                      << "Generating factory:" << *fac << " NoFactory = " << NoFactory::get());
      fac->CallBuild(*this);
      Release(*fac);
    }

    TEUCHOS_TEST_FOR_EXCEPTION(!IsAvailable(ename, fac), Exceptions::RuntimeError,
                               "MueLu::Level::Get(): factory did not produce expected output on level " << GetLevelID()
                                                                                                        << ". The data \"" << ename << "\" has not been generated by " << *fac);

    return map_[fac][ename]->template CheckType<T>();
  }

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




  //  This method is intented to be used by user drivers for printing, debugging or to keep some computed data for a next run of the setup phase.
  //
  //  This method is an alias for: AddKeepFlag(ename, factory, MueLu::Keep)
  //  See also the description of KeepEnum for more information.
  //
  //  To undo a keep request, one can use:
  //  - Delete(ename, factory) to delete the data and remove the "Keep" flag
  //  - or RemoveKeepFlag(ename, factory, MueLu::Keep) to go back to previous condition (data are kept only if internal MueLu logic need so).
  //
  // Note: Level variables tagged using this methods are also keep on the levels built using this.Build().
  //       This means that is you request to keep a specific variable on a fine level, all the coarser level that are created automatically during the setup phase will also retain the same variable.
  void Keep(const std::string& ename, const FactoryBase* factory) { AddKeepFlag(ename, factory, MueLu::Keep); }  // Note: do not add default value for input parameter 'factory'

  // Special cases:
  // - If entry (ename, factory) does not exist, nothing is done.
  // - If entry exists but counter !=, entry cannot be desallocated before counter set to 0 (using Release()) so an exeption is thrown.
  void Delete(const std::string& ename, const FactoryBase* factory);

  void Clear();

  void ExpertClear();

  bool IsKept(const std::string& ename, const FactoryBase* factory, KeepType keep) const { return GetKeepFlag(ename, factory) & keep; }

  void AddKeepFlag(const std::string& ename, const FactoryBase* factory = NoFactory::get(), KeepType keep = MueLu::Keep);  // TODO: remove default value for input parameter 'factory'?

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

  KeepType GetKeepFlag(const std::string& ename, const FactoryBase* factory) const;




  void Request(const FactoryBase& factory);

  void Release(const FactoryBase& factory);

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

  void DeclareDependencies(const FactoryBase* factory, bool bRequestOnly = false, bool bReleaseOnly = false);

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

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




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

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



  std::string description() const;

  // TODO: print only shows requested variables. check if we also list kept factories with ref counter=0?
  void print(std::ostream& out, const VerbLevel verbLevel = Default) const;

#if defined(HAVE_MUELU_BOOST) && defined(HAVE_MUELU_BOOST_FOR_REAL) && defined(BOOST_VERSION) && (BOOST_VERSION >= 104400)
  void UpdateGraph(std::map<const FactoryBase*, BoostVertex>& vindices,
                   std::map<std::pair<BoostVertex, BoostVertex>, std::string>& edges,
                   BoostProperties& dp,
                   BoostGraph& graph) const;
#endif


  enum RequestMode { REQUEST,
                     RELEASE,
                     UNDEF };
  RequestMode GetRequestMode() const { return requestMode_; }

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

  void SetComm(RCP<const Teuchos::Comm<int> > const& comm) { comm_ = comm; }
  RCP<const Teuchos::Comm<int> > GetComm() const { return comm_; }

 private:
  Level(const Level& source);

  //
  //  If factory == NULL, the default factory is defined as follow:
  // - If user data is available, it is considered as the default and the factory manager is ignored.
  //   => The default factory is then NoFactory.
  // - Else, the factory manager is used to get the default factory.
  //
  // This strategy allows to use the same factory manager on the fine and coarse level without any trouble.
  //     Example :
  //
  //     FineLevel:
  //     ----------
  //     A          -> User provided
  //     Nullspace  -> User provided
  //
  //     CoarseLevel:
  //     ------------
  //     A         -> RAPFactory
  //     NullSpace -> NullspaceFactory
  //
  const FactoryBase* GetFactory(const std::string& varname, const FactoryBase* factory) const;

  static RequestMode requestMode_;
  Xpetra::UnderlyingLib lib_;
  RCP<const Teuchos::Comm<int> > comm_;

  using Key1      = const FactoryBase*;
  using Key2      = const std::string;
  using Value     = RCP<VariableContainer>;
  using SubMap    = Teuchos::map<Key2, Value>;   
  using TwoKeyMap = Teuchos::map<Key1, SubMap>;  

  int levelID_;  // id number associated with level
  RCP<const FactoryManagerBase> factoryManager_;
  RCP<Level> previousLevel_;  // linked list of Level
  TwoKeyMap map_;



  bool IsKey(const FactoryBase* factory, const std::string& ename) const;

  bool IsAvailableFactory(const FactoryBase* factory) const;

  bool IsRequested(const Value& v) const;

  bool IsRequestedBy(const FactoryBase* factory, const std::string& ename, const FactoryBase* requestedBy) const;

  bool IsRequestedBy(const Value& v, const FactoryBase* requestedBy) const;

  bool IsRequestedFactory(const FactoryBase* factory) const;

  const Value& Get(const FactoryBase* factory, const std::string& ename) const;

  int NumRequests(const FactoryBase* factory, const std::string& ename) const;

  int CountRequestedFactory(const FactoryBase* factory) const;


};  // class Level

}  // namespace MueLu

// TODO: Caps should not matter

#endif  // MUELU_LEVEL_HPP