MueLu  Version of the Day
MueLu_ParameterListAcceptor.hpp
Go to the documentation of this file.
1 #ifndef MUELU_PARAMETERLISTACCEPTOR_HPP
2 #define MUELU_PARAMETERLISTACCEPTOR_HPP
3 
4 #include <iostream>
5 
6 #include "Teuchos_RCP.hpp"
9 #include "Teuchos_StandardParameterEntryValidators.hpp"
10 
11 // TODO See also: Teuchos::ParameterListAcceptor, Teko::Clonable
12 
13 namespace MueLu {
16  using Teuchos::RCP;
17 
18  // Printing the valid parameter list only showing documentation fields
19  inline void printParameterListOptions(std::ostream &os, const Teuchos::ParameterList & p) {
20  p.print(os, Teuchos::ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true));
21  os << std::endl;
22  }
23 
29 
30  public:
31 
35 
36  virtual ~ParameterListAcceptor() { }
37 
41 
46  // Questions:
47  // - Do we want this function to be static?
48  // => yes, but we also want it virtual. So static is not possible. But this method does not access any instance specific data.
49  // - Do we want to pass an optional param list as input parameter?
50  // yes => if some parameters depends of other parameters, this would allow to return different default / valid parameters according to already set parameters.
51  // Ex: fact: ILUT => extra param threshold; fact: ILUK => extra param level-of-fill
52  //
53  // If a parameter is unused AND default, it is printed as [default] by std::cout << paramList but printed as unused by paramList.unused(std::cout).
54  // So if we set default parameters in getValidParameters() that are not used, user will get a warning message. We don't want that for [default].
55  // One solution is to never set any unused parameter in getValidParameters().
56  // If some parameters are available only conditionnaly, do not set them by default in setValidParameters when the conditions are not met.
57  //
59 
61  //
62  // Questions:
63  // - Input: const ParameterList or not const? IE: do we want to modify user paramlist directly?
64  // => not const: user can make a copy outside if he do not want us to modify his initial paramlist.
65  // - Input: RCP or just reference? RCP avoid the copy of the parameter list but
66  // I'm afraid that a user modify the list outside of the class after doing a SetParameterList
67  // (this by-pass the validation and can create some confusion).
68  // In another hand, if we use a copy of the list, we do not set the "[used]"/["unused"] flag
69  // on the original list during Build(). GetParameterList has to be called to retrieve the list with the correct flags.
70  //
71  // What we really want is for the user to have a const version outside and MueLu having a non-const version inside.
72  // Is there a C++ pattern to do that?
73  virtual void SetParameterList(const ParameterList& paramList) = 0;
74 
75  // Get the parameter list.
76  // Teuchos::ParameterListAcceptor also provides a non-const version of this but I don't see why.
77  // We don't want a user to mess with the internal parameter list.
78  // To change a parameter, one can make a copy and call SetParameterList again.
79  // No need for RCP, it's just a view
80  virtual const Teuchos::ParameterList & GetParameterList() const = 0;
81 
83  virtual void SetParameter(const std::string &name, const ParameterEntry &entry) = 0;
84 
86  virtual const ParameterEntry & GetParameter(const std::string &name) const = 0;
87 
88  virtual void GetDocumentation(std::ostream &os) const = 0;
89 
91 
92  }; //class ParameterListAcceptor
93 
94  // Partial implementation of ParameterListAcceptor that stores the object parameters in an internal parameterList
96 
97  public:
98 
100 
102  // TAW: 3/17/2016
103  // The following code is useless. Comment it out to make coverity happy (CID22611)
104  /*bool warnings = false; //TODO
105  if (warnings)
106  paramList_.unused(std::cout);*/
107  }
108 
109  virtual void SetParameterList(const ParameterList& paramList) {
110  // This call is only for cosmetic reasons.
111  // If one calls SetParameterList before GetParameterList, that would mean
112  // that paramList_ has not been initialized yet. Therefore, the parameter
113  // would be put in it in the order user provided, and not in the order of
114  // valid parameter list. We'd like to have consistency in the order, so
115  // we do this extra call, which is no-op if paramList_ has already been
116  // initialized.
118 
119  paramList_.setParameters(paramList);
120 
121  // Validate and add defaults parameters.
123  if (validParamList != Teuchos::null) {
125  } else {
126  // Teuchos::null means that GetValidParameterList() not implemented.
127  // As such, we skip validation and have not way to set default values,
128  // which is potentially dangerous
129  }
130  }
131 
132  // The returned list always has an entry for each valid parameter.
133  // Therefore, there is not need to test if a parameter is present before getting it.
134  virtual const Teuchos::ParameterList& GetParameterList() const {
135  if (paramList_.numParams() == 0) {
136  // Set paramList_ to the default list
138  if (validParamList != Teuchos::null) {
139  // Instead of simply doing
140  // paramList_ = *validParamList;
141  // we use more complicated Teuchos calls, because we would like to
142  // have [default] values in the beginning
144  }
145 
146  } else {
147  // We are sure that the list has all the valid parameters defined
148  // because the parameter list validation process adds the default
149  // values to the user list
150  }
151 
152  return paramList_;
153  }
154 
155  void SetParameter(const std::string& name, const ParameterEntry& entry) {
156  Teuchos::ParameterList paramList;
157  paramList.setEntry(name, entry);
158  SetParameterList(paramList); // This forces revalidation of the list
159  }
160 
161  const ParameterEntry & GetParameter(const std::string &name) const {
162  return GetParameterList().getEntry(name);
163  }
164 
165  virtual void GetDocumentation(std::ostream &os) const {
166  // default implementation
167 
169  if (validParamList == Teuchos::null) {
170  os << "## Documentation not available:" << std::endl;
171  return;
172  }
173 
174  os << "## Parameters:" << std::endl;
175  printParameterListOptions(os, *validParamList);
176 
177  os << "## Fully described default method:" << std::endl;
178  validParamList->print(os, 2, true, false);
179  os << std::endl;
180  }
181 
182  private:
183 
184  mutable // mutable can be avoid by changing return type of GetParameterList() to RCP but conceptually, I like the fact that GetParameterList returns ref to param list.
185  Teuchos::ParameterList paramList_; // Private: Use GetParameterList() to access this list
186  // This list might be empty before calling GetParameterList()
187  // but it is populate with automatically if needed in SetParameterList/GetParameterList/...
188  // Therefore, there is no need to test if a parameter exist before accessing it with pL.get("paramName")
189  // in sub classes.
190 
191  // Note: Teuchos::ParameterListAcceptor has a getMyParamList() function to access paramList_ without going through the logic of getParameterList()
192  // Do we need that too?
193 
194  };
195 
196 
197 }
198 
199 #endif // MUELU_PARAMETERLISTACCEPTOR_HPP
Ordinal numParams() const
Namespace for MueLu classes and methods.
virtual void GetDocumentation(std::ostream &os) const
ParameterList & setEntry(const std::string &name, const ParameterEntry &entry)
virtual const ParameterEntry & GetParameter(const std::string &name) const =0
Retrieves a const entry with the name name.
virtual void SetParameterList(const ParameterList &paramList)=0
Set parameters from a parameter list and return with default values.
virtual void SetParameterList(const ParameterList &paramList)
Set parameters from a parameter list and return with default values.
virtual const Teuchos::ParameterList & GetParameterList() const =0
void validateParametersAndSetDefaults(ParameterList const &validParamList, int const depth=1000)
Abstract interface of a class accepting parameter lists.
ParameterList & setParameters(const ParameterList &source)
virtual const Teuchos::ParameterList & GetParameterList() const
void SetParameter(const std::string &name, const ParameterEntry &entry)
Set a parameter directly as a ParameterEntry.
virtual void SetParameter(const std::string &name, const ParameterEntry &entry)=0
Set a parameter directly as a ParameterEntry.
const ParameterEntry & GetParameter(const std::string &name) const
Retrieves a const entry with the name name.
virtual RCP< const ParameterList > GetValidParameterList() const =0
Return a const parameter list of valid parameters that setParameterList() will accept.
void printParameterListOptions(std::ostream &os, const Teuchos::ParameterList &p)
ParameterEntry & getEntry(const std::string &name)
virtual void GetDocumentation(std::ostream &os) const =0