MueLu  Version of the Day
MueLu_TogglePFactory_def.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_TOGGLEPFACTORY_DEF_HPP
47 #define MUELU_TOGGLEPFACTORY_DEF_HPP
48 
49 #include <Xpetra_Matrix.hpp>
50 
52 
54 #include "MueLu_Level.hpp"
55 #include "MueLu_MasterList.hpp"
56 #include "MueLu_Monitor.hpp"
58 
59 namespace MueLu {
60 
61  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
63  RCP<ParameterList> validParamList = rcp(new ParameterList());
64 
65 #define SET_VALID_ENTRY(name) validParamList->setEntry(name, MasterList::getEntry(name))
66  SET_VALID_ENTRY("toggle: mode");
67  SET_VALID_ENTRY("semicoarsen: number of levels");
68 #undef SET_VALID_ENTRY
69 
70  return validParamList;
71  }
72 
73  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
75  // request/release "P" and coarse level "Nullspace"
76  for (std::vector<RCP<const FactoryBase> >::const_iterator it = prolongatorFacts_.begin(); it != prolongatorFacts_.end(); ++it) {
77  coarseLevel.DeclareInput("P", (*it).get(), this); // request/release "P" (dependencies are not affected)
78  (*it)->CallDeclareInput(coarseLevel); // request dependencies
79  }
80  for (std::vector<RCP<const FactoryBase> >::const_iterator it = ptentFacts_.begin(); it != ptentFacts_.end(); ++it) {
81  coarseLevel.DeclareInput("P", (*it).get(), this); // request/release "Ptent" (dependencies are not affected)
82  (*it)->CallDeclareInput(coarseLevel); // request dependencies
83  }
84  for (std::vector<RCP<const FactoryBase> >::const_iterator it = nspFacts_.begin(); it != nspFacts_.end(); ++it) {
85  coarseLevel.DeclareInput("Nullspace", (*it).get(), this); // request/release coarse "Nullspace" (dependencies are not affected)
86  (*it)->CallDeclareInput(coarseLevel); // request dependencies
87  }
88 
89  // The factory needs the information about the number of z-layers. While this information is
90  // provided by the user for the finest level, the factory itself is responsible to provide the
91  // corresponding information on the coarser levels. Since a factory cannot be dependent on itself
92  // we use the NoFactory class as generator class, but remove the UserData keep flag, such that
93  // "NumZLayers" is part of the request/release mechanism.
94  // Please note, that this prevents us from having several (independent) CoarsePFactory instances!
95  // TODO: allow factory to dependent on self-generated data for TwoLevelFactories -> introduce ExpertRequest/Release in Level
96  fineLevel.DeclareInput("NumZLayers", NoFactory::get(), this);
97  fineLevel.RemoveKeepFlag("NumZLayers", NoFactory::get(), MueLu::UserData);
98 
99  hasDeclaredInput_ = true;
100  }
101 
102  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
104  FactoryMonitor m(*this, "Prolongator toggle", coarseLevel);
105  std::ostringstream levelstr;
106  levelstr << coarseLevel.GetLevelID();
107 
108  TEUCHOS_TEST_FOR_EXCEPTION(nspFacts_.size() != prolongatorFacts_.size(), Exceptions::RuntimeError, "MueLu::TogglePFactory::Build: The number of provided prolongator factories and coarse nullspace factories must be identical.");
109  TEUCHOS_TEST_FOR_EXCEPTION(nspFacts_.size() != 2, Exceptions::RuntimeError, "MueLu::TogglePFactory::Build: TogglePFactory needs two different transfer operator strategies for toggling."); // TODO adapt this/weaken this as soon as other toggling strategies are introduced.
110 
111  // decision routine which prolongator factory to be used
112  int nProlongatorFactory = 0; // default behavior: use first prolongator in list
113 
114  // extract user parameters
115  const Teuchos::ParameterList & pL = GetParameterList();
116  std::string mode = Teuchos::as<std::string>(pL.get<std::string>("toggle: mode"));
117  int semicoarsen_levels = Teuchos::as<int>(pL.get<int>("semicoarsen: number of levels"));
118 
119  TEUCHOS_TEST_FOR_EXCEPTION(mode!="semicoarsen", Exceptions::RuntimeError, "MueLu::TogglePFactory::Build: The 'toggle: mode' parameter must be set to 'semicoarsen'. No other mode supported, yet.");
120 
121  LO NumZDir = -1;
122  if(fineLevel.IsAvailable("NumZLayers", NoFactory::get())) {
123  NumZDir = fineLevel.Get<LO>("NumZLayers", NoFactory::get()); //obtain info
124  GetOStream(Runtime1) << "Number of layers for semicoarsening: " << NumZDir << std::endl;
125  }
126 
127  // Make a decision which prolongator to be used.
128  if(fineLevel.GetLevelID() >= semicoarsen_levels || NumZDir == 1) {
129  nProlongatorFactory = 1;
130  } else {
131  nProlongatorFactory = 0;
132  }
133 
134  RCP<Matrix> P = Teuchos::null;
135  RCP<Matrix> Ptent = Teuchos::null;
136  RCP<MultiVector> coarseNullspace = Teuchos::null;
137 
138  // call Build for selected transfer operator
139  GetOStream(Runtime0) << "TogglePFactory: call transfer factory: " << (prolongatorFacts_[nProlongatorFactory])->description() << std::endl;
140  prolongatorFacts_[nProlongatorFactory]->CallBuild(coarseLevel);
141  P = coarseLevel.Get< RCP<Matrix> >("P", (prolongatorFacts_[nProlongatorFactory]).get());
142  // do not call "Build" for "Ptent" factory since it should automatically be called recursively
143  // through the "Build" call for "P"
144  Ptent = coarseLevel.Get< RCP<Matrix> >("P", (ptentFacts_[nProlongatorFactory]).get());
145  coarseNullspace = coarseLevel.Get< RCP<MultiVector> >("Nullspace", (nspFacts_[nProlongatorFactory]).get());
146 
147  // Release dependencies of all prolongator and coarse level null spaces
148  for(size_t t=0; t<nspFacts_.size(); ++t) {
149  coarseLevel.Release(*(prolongatorFacts_[t]));
150  coarseLevel.Release(*(ptentFacts_[t]));
151  coarseLevel.Release(*(nspFacts_[t]));
152  }
153 
154  // store prolongator with this factory identification.
155  Set(coarseLevel, "P", P);
156  Set(coarseLevel, "Nullspace", coarseNullspace);
157  Set(coarseLevel, "Ptent", Ptent);
158  Set(coarseLevel, "Chosen P", nProlongatorFactory);
159  } //Build()
160 
161  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
163  // check if it's a TwoLevelFactoryBase based transfer factory
164  TEUCHOS_TEST_FOR_EXCEPTION(Teuchos::rcp_dynamic_cast<const TwoLevelFactoryBase>(factory) == Teuchos::null, Exceptions::BadCast,
165  "MueLu::TogglePFactory::AddProlongatorFactory: Transfer factory is not derived from TwoLevelFactoryBase. "
166  "This is very strange. (Note: you can remove this exception if there's a good reason for)");
167  TEUCHOS_TEST_FOR_EXCEPTION(hasDeclaredInput_, Exceptions::RuntimeError, "MueLu::TogglePFactory::AddProlongatorFactory: Factory is being added after we have already declared input");
168  prolongatorFacts_.push_back(factory);
169  }
170 
171  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
173  // check if it's a TwoLevelFactoryBase based transfer factory
174  TEUCHOS_TEST_FOR_EXCEPTION(Teuchos::rcp_dynamic_cast<const TwoLevelFactoryBase>(factory) == Teuchos::null, Exceptions::BadCast,
175  "MueLu::TogglePFactory::AddPtentFactory: Transfer factory is not derived from TwoLevelFactoryBase. "
176  "This is very strange. (Note: you can remove this exception if there's a good reason for)");
177  TEUCHOS_TEST_FOR_EXCEPTION(hasDeclaredInput_, Exceptions::RuntimeError, "MueLu::TogglePFactory::AddPtentFactory: Factory is being added after we have already declared input");
178  ptentFacts_.push_back(factory);
179  }
180 
181  template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
183  // check if it's a TwoLevelFactoryBase based transfer factory
184  TEUCHOS_TEST_FOR_EXCEPTION(Teuchos::rcp_dynamic_cast<const TwoLevelFactoryBase>(factory) == Teuchos::null, Exceptions::BadCast,
185  "MueLu::TogglePFactory::AddCoarseNullspaceFactory: Transfer factory is not derived from TwoLevelFactoryBase. Make sure you provide the factory which generates the coarse level nullspace information. Usually this is a prolongator factory."
186  "This is very strange. (Note: you can remove this exception if there's a good reason for)");
187  TEUCHOS_TEST_FOR_EXCEPTION(hasDeclaredInput_, Exceptions::RuntimeError, "MueLu::TogglePFactory::AddCoarseNullspaceFactory: Factory is being added after we have already declared input");
188  nspFacts_.push_back(factory);
189  }
190 
191 
192 } //namespace MueLu
193 
194 #endif // MUELU_TOGGLEPFACTORY_DEF_HPP
Exception indicating invalid cast attempted.
T & Get(const std::string &ename, const FactoryBase *factory=NoFactory::get())
Get data without decrementing associated storage counter (i.e., read-only access). Usage: Level->Get< RCP<Matrix> >("A", factory) if factory == NULL => use default factory.
void Release(const FactoryBase &factory)
Decrement the storage counter for all the inputs of a factory.
void AddProlongatorFactory(const RCP< const FactoryBase > &factory)
Add a prolongator factory in the end of list of prolongator factories.
RCP< const ParameterList > GetValidParameterList() const
Return a const parameter list of valid parameters that setParameterList() will accept.
Timer to be used in factories. Similar to Monitor but with additional timers.
User data are always kept. This flag is set automatically when Level::Set("data", data) is used...
LocalOrdinal LO
One-liner description of what is happening.
Namespace for MueLu classes and methods.
static const NoFactory * get()
int GetLevelID() const
Return level number.
Definition: MueLu_Level.cpp:76
Class that holds all level-specific information.
Definition: MueLu_Level.hpp:99
void RemoveKeepFlag(const std::string &ename, const FactoryBase *factory, KeepType keep=MueLu::All)
void Build(Level &fineLevel, Level &coarseLevel) const
Build method.
void DeclareInput(Level &fineLevel, Level &coarseLevel) const
Input.
bool IsAvailable(const std::string &ename, const FactoryBase *factory=NoFactory::get()) const
Test whether a need&#39;s value has been saved.
Exception throws to report errors in the internal logical of the program.
Description of what is happening (more verbose)
void AddPtentFactory(const RCP< const FactoryBase > &factory)
Add a tentative prolongator factory in the end of list of prolongator factories.
void DeclareInput(const std::string &ename, const FactoryBase *factory, const FactoryBase *requestedBy=NoFactory::get())
Callback from FactoryBase::CallDeclareInput() and FactoryBase::DeclareInput()
#define SET_VALID_ENTRY(name)
void AddCoarseNullspaceFactory(const RCP< const FactoryBase > &factory)
Add a coarse nullspace factory in the end of list of coarse nullspace factories.