MueLu  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
MueLu_ML2MueLuParameterTranslator.cpp
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 
47 #include "MueLu_ConfigDefs.hpp"
48 #if defined(HAVE_MUELU_ML) && defined(HAVE_MUELU_EPETRA)
49 #include <ml_ValidateParameters.h>
50 #include <ml_MultiLevelPreconditioner.h> // for default values
51 #endif
52 
54 
55 namespace MueLu {
56 
57 
58  std::string ML2MueLuParameterTranslator::GetSmootherFactory(const Teuchos::ParameterList& paramList, Teuchos::ParameterList& adaptingParamList, const std::string& pname, const std::string& value) {
59 
60  TEUCHOS_TEST_FOR_EXCEPTION(pname != "coarse: type" && pname != "coarse: list" && pname != "smoother: type" && pname.find("smoother: list",0) != 0,
62  "MueLu::MLParameterListInterpreter::Setup(): Only \"coarse: type\", \"smoother: type\" or \"smoother: list\" (\"coarse: list\") are "
63  "supported as ML parameters for transformation of smoother/solver parameters to MueLu");
64 
65  // string stream containing the smoother/solver xml parameters
66  std::stringstream mueluss;
67 
68  // Check whether we are dealing with coarse level (solver) parameters or level smoother parameters
69  std::string mode = "smoother:";
70  if (pname.find("coarse:", 0) == 0)
71  mode = "coarse:";
72 
73  // check whether pre and/or post smoothing
74  std::string PreOrPost = "both";
75  if (paramList.isParameter(mode + " pre or post"))
76  PreOrPost = paramList.get<std::string>(mode + " pre or post");
77 
78  TEUCHOS_TEST_FOR_EXCEPTION(mode == "coarse:" && PreOrPost != "both", Exceptions::RuntimeError,
79  "MueLu::MLParameterListInterpreter::Setup(): The parameter \"coarse: pre or post\" is not supported by MueLu. "
80  "It does not make sense for direct solvers. For iterative solvers you obtain the same effect by increasing, "
81  "e.g., the number of sweeps for the coarse grid smoother. Please remove it from your parameters.");
82 
83  // select smoother type
84  std::string valuestr = value; // temporary variable
85  std::transform(valuestr.begin(), valuestr.end(), valuestr.begin(), ::tolower);
86  if ( valuestr == "jacobi" || valuestr == "gauss-seidel" || valuestr == "symmetric gauss-seidel" ) {
87  std::string my_name;
88  if ( PreOrPost == "both" ) my_name = "\"" + pname + "\"";
89  else my_name = "\"smoother: " + PreOrPost + " type\"";
90  mueluss << "<Parameter name=" << my_name << " type=\"string\" value=\"RELAXATION\"/>" << std::endl;
91 
92  } else if ( valuestr == "ifpack" ) {
93  std::string my_name = "\"" + pname + "\"";
94  if ( paramList.isParameter("smoother: ifpack type") ) {
95  if ( paramList.get<std::string>("smoother: ifpack type") == "ILU" ) {
96  mueluss << "<Parameter name=" << my_name << " type=\"string\" value=\"ILU\"/>" << std::endl;
97  adaptingParamList.remove("smoother: ifpack type",false);
98  }
99  if ( paramList.get<std::string>("smoother: ifpack type") == "ILUT" ) {
100  mueluss << "<Parameter name=" << my_name << " type\" type=\"string\" value=\"ILUT\"/>" << std::endl;
101  adaptingParamList.remove("smoother: ifpack type",false);
102  }
103  }
104 
105  } else if ( valuestr == "chebyshev" ) {
106  std::string my_name = "\"" + pname + "\"";
107  mueluss << "<Parameter name=" << my_name << " type=\"string\" value=\"CHEBYSHEV\"/>" << std::endl;
108 
109  } else if (valuestr.length() > strlen("amesos") && valuestr.substr(0, strlen("amesos")) == "amesos") { /* catch Amesos-* */
110  std::string solverType = valuestr.substr(strlen("amesos")+1); /* ("amesos-klu" -> "klu") */
111 
112  bool valid = false;
113  const int validatorSize = 5;
114  std::string validator[validatorSize] = {"superlu", "superludist", "klu", "umfpack"};
115  for (int i=0; i < validatorSize; i++)
116  if (validator[i] == solverType)
117  valid = true;
119  "MueLu::MLParameterListInterpreter: unknown smoother type. '" << solverType << "' not supported.");
120 
121  mueluss << "<Parameter name=\"" << pname << "\" type=\"string\" value=\"" << solverType << "\"/>" << std::endl;
122 
123  } else {
124  // TODO error message
125  std::cout << "error in " << __FILE__ << ":" << __LINE__ << " could not find valid smoother/solver" << std::endl;
126  }
127 
128  // set smoother: pre or post parameter
129  // Note that there is no "coarse: pre or post" in MueLu!
130  if ( paramList.isParameter("smoother: pre or post") && mode == "smoother:") {
131  //std::cout << "paramList" << paramList << std::endl;
132  //std::string smootherPreOrPost = paramList.get<std::string>("smoother: pre or post");
133  //std::cout << "Create pre or post parameter with " << smootherPreOrPost << std::endl;
134  mueluss << "<Parameter name=\"smoother: pre or post\" type=\"string\" value=\"" << PreOrPost << "\"/>" << std::endl;
135  adaptingParamList.remove("smoother: pre or post",false);
136  }
137 
138  // create smoother parameter list
139  if (PreOrPost != "both") {
140  mueluss << "<ParameterList name=\"smoother: " << PreOrPost << " params\">" << std::endl;
141  } else {
142  mueluss << "<ParameterList name=\"" << mode << " params\">" << std::endl;
143  }
144 
145  // relaxation based smoothers:
146 
147  if ( valuestr == "jacobi" || valuestr == "gauss-seidel" || valuestr == "symmetric gauss-seidel" ) {
148  if ( valuestr == "jacobi" ) { mueluss << "<Parameter name=\"relaxation: type\" type=\"string\" value=\"Jacobi\"/>" << std::endl; adaptingParamList.remove("relaxation: type",false); }
149  if ( valuestr == "gauss-seidel" ) { mueluss << "<Parameter name=\"relaxation: type\" type=\"string\" value=\"Gauss-Seidel\"/>" << std::endl; adaptingParamList.remove("relaxation: type",false); }
150  if ( valuestr == "symmetric gauss-seidel" ) { mueluss << "<Parameter name=\"relaxation: type\" type=\"string\" value=\"Symmetric Gauss-Seidel\"/>" << std::endl; adaptingParamList.remove("relaxation: type",false); }
151 
152  if ( paramList.isParameter("smoother: sweeps") ) { mueluss << "<Parameter name=\"relaxation: sweeps\" type=\"int\" value=\"" << paramList.get<int>("smoother: sweeps") << "\"/>" << std::endl; adaptingParamList.remove("smoother: sweeps",false); }
153  if ( paramList.isParameter("smoother: damping factor") ) { mueluss << "<Parameter name=\"relaxation: damping factor\" type=\"double\" value=\"" << paramList.get<double>("smoother: damping factor") << "\"/>" << std::endl; adaptingParamList.remove("smoother: damping factor",false); }
154  }
155 
156  // Chebyshev
157  if ( valuestr == "chebyshev") {
158  if ( paramList.isParameter("smoother: polynomial order") ) { mueluss << "<Parameter name=\"chebyshev: degree\" type=\"int\" value=\"" << paramList.get<int>("smoother: polynomial order") << "\"/>" << std::endl; adaptingParamList.remove("smoother: polynomial order",false); }
159  else { mueluss << "<Parameter name=\"chebyshev: degree\" type=\"int\" value=\"2\"/>" << std::endl; }
160  if ( paramList.isParameter("smoother: Chebyshev alpha") ) { mueluss << "<Parameter name=\"chebyshev: ratio eigenvalue\" type=\"double\" value=\"" << paramList.get<double>("smoother: Chebyshev alpha") << "\"/>" << std::endl; adaptingParamList.remove("smoother: Chebyshev alpha",false); }
161  else { mueluss << "<Parameter name=\"chebyshev: ratio eigenvalue\" type=\"double\" value=\"20\"/>" << std::endl; adaptingParamList.remove("smoother: Chebyshev alpha",false); }
162  }
163 
164  // parameters for ILU based preconditioners
165  if ( valuestr == "ifpack") {
166 
167  // add Ifpack parameters
168  if ( paramList.isParameter("smoother: ifpack overlap") ) { mueluss << "<Parameter name=\"partitioner: overlap\" type=\"int\" value=\"" << paramList.get<int>("smoother: ifpack overlap") << "\"/>" << std::endl; adaptingParamList.remove("smoother: ifpack overlap",false); }
169  if ( paramList.isParameter("smoother: ifpack level-of-fill") ) { mueluss << "<Parameter name=\"fact: level-of-fill\" type=\"int\" value=\"" << paramList.get<int>("smoother: ifpack level-of-fill") << "\"/>" << std::endl; adaptingParamList.remove("smoother: ifpack level-of-fill",false); }
170  if ( paramList.isParameter("smoother: ifpack absolute threshold") ) { mueluss << "<Parameter name=\"fact: absolute threshold\" type=\"int\" value=\"" << paramList.get<double>("smoother: ifpack absolute threshold") << "\"/>" << std::endl; adaptingParamList.remove("smoother: ifpack absolute threshold",false); }
171  if ( paramList.isParameter("smoother: ifpack relative threshold") ) { mueluss << "<Parameter name=\"fact: relative threshold\" type=\"int\" value=\"" << paramList.get<double>("smoother: ifpack relative threshold") << "\"/>" << std::endl; adaptingParamList.remove("smoother: ifpack relative threshold",false); }
172  }
173 
174  mueluss << "</ParameterList>" << std::endl;
175 
176  // max coarse level size parameter (outside of smoother parameter lists)
177  if ( paramList.isParameter("smoother: max size") ) {
178  mueluss << "<Parameter name=\"coarse: max size\" type=\"int\" value=\"" << paramList.get<int>("smoother: max size") << "\"/>" << std::endl; adaptingParamList.remove("smoother: max size",false);
179  }
180 
181  return mueluss.str();
182  }
183 
184  std::string ML2MueLuParameterTranslator::SetParameterList(const Teuchos::ParameterList & paramList_in, const std::string& defaultVals) {
185  Teuchos::ParameterList paramList = paramList_in;
186 
187  RCP<Teuchos::FancyOStream> out = Teuchos::fancyOStream(Teuchos::rcpFromRef(std::cout)); // TODO: use internal out (GetOStream())
188 
189 #if defined(HAVE_MUELU_ML) && defined(HAVE_MUELU_EPETRA)
190 
191  // TODO alternative with standard parameterlist from ML user guide?
192 
193  if (defaultVals != "") {
194  TEUCHOS_TEST_FOR_EXCEPTION(defaultVals!="SA" && defaultVals!="NSSA", Exceptions::RuntimeError,
195  "MueLu::MLParameterListInterpreter: only \"SA\" and \"NSSA\" allowed as options for ML default parameters.");
196  Teuchos::ParameterList ML_defaultlist;
197  ML_Epetra::SetDefaults(defaultVals,ML_defaultlist);
198 
199  // merge user parameters with default parameters
200  MueLu::MergeParameterList(paramList_in, ML_defaultlist, true);
201  paramList = ML_defaultlist;
202  }
203 #else
204  if (defaultVals != "") {
205  // If no validator available: issue a warning and set parameter value to false in the output list
206  *out << "Warning: MueLu_ENABLE_ML=OFF. No ML default values available." << std::endl;
207  }
208 #endif // HAVE_MUELU_ML
209 
210  //
211  // Move smoothers/aggregation/coarse parameters to sublists
212  //
213 
214  // ML allows to have level-specific smoothers/aggregation/coarse parameters at the top level of the list or/and defined in sublists:
215  // See also: ML Guide section 6.4.1, MueLu::CreateSublists, ML_CreateSublists
216  ParameterList paramListWithSubList;
217  MueLu::CreateSublists(paramList, paramListWithSubList);
218  paramList = paramListWithSubList; // swap
219  Teuchos::ParameterList adaptingParamList = paramList; // copy of paramList which is used to removed already interpreted parameters
220 
221  //
222  // Validate parameter list
223  //
224  {
225  bool validate = paramList.get("ML validate parameter list", true); /* true = default in ML */
226  if (validate) {
227 
228 #if defined(HAVE_MUELU_ML) && defined(HAVE_MUELU_EPETRA)
229  // Validate parameter list using ML validator
230  int depth = paramList.get("ML validate depth", 5); /* 5 = default in ML */
231  TEUCHOS_TEST_FOR_EXCEPTION(! ML_Epetra::ValidateMLPParameters(paramList, depth), Exceptions::RuntimeError,
232  "ERROR: ML's Teuchos::ParameterList contains incorrect parameter!");
233 #else
234  // If no validator available: issue a warning and set parameter value to false in the output list
235  *out << "Warning: MueLu_ENABLE_ML=OFF. The parameter list cannot be validated." << std::endl;
236  paramList.set("ML validate parameter list", false);
237 
238 #endif // HAVE_MUELU_ML
239  } // if(validate)
240  } // scope
241 
242  // stringstream for concatenating xml parameter strings.
243  std::stringstream mueluss;
244 
245  // create surrounding MueLu parameter list
246  mueluss << "<ParameterList name=\"MueLu\">" << std::endl;
247 
248  // loop over all ML parameters in provided parameter list
249  for (ParameterList::ConstIterator param = paramListWithSubList.begin(); param != paramListWithSubList.end(); ++param) {
250 
251  // extract ML parameter name
252  const std::string & pname=paramListWithSubList.name(param);
253 
254  // extract corresponding (ML) value
255  // remove ParameterList specific information from result string
256  std::stringstream valuess;
257  valuess << paramList.entry(param);
258  std::string valuestr = valuess.str();
259  replaceAll(valuestr, "[unused]", "");
260  replaceAll(valuestr, "[default]", "");
261  valuestr = trim(valuestr);
262 
263  // transform ML parameter to corresponding MueLu parameter and generate XML string
264  std::string valueInterpreterStr = "\"" + valuestr + "\"";
265  std::string ret = MasterList::interpretParameterName(MasterList::ML2MueLu(pname),valueInterpreterStr);
266 
267  // add XML string
268  if (ret != "") {
269  mueluss << ret << std::endl;
270 
271  // remove parameter from ML parameter list
272  adaptingParamList.remove(pname,false);
273  }
274 
275  // special handling for energy minimization
276  // TAW: this is not optimal for symmetric problems but at least works.
277  // for symmetric problems the "energy minimization" parameter should not exist anyway...
278  if (pname == "energy minimization: enable") {
279  mueluss << "<Parameter name=\"problem: symmetric\" type=\"bool\" value=\"false\"/>" << std::endl;
280  mueluss << "<Parameter name=\"transpose: use implicit\" type=\"bool\" value=\"false\"/>" << std::endl;
281  }
282 
283  // special handling for smoothers
284  if (pname == "smoother: type") {
285 
286  mueluss << GetSmootherFactory(paramList, adaptingParamList, pname, valuestr);
287 
288  }
289 
290  // special handling for level-specific smoothers
291  if (pname.find("smoother: list (level",0) == 0) {
292  // Scan pname (ex: pname="smoother: type (level 2)")
293  std::string type, option;
294  int levelID=-1;
295  {
296  typedef Teuchos::ArrayRCP<char>::size_type size_type;
297  Teuchos::Array<char> ctype (size_type(pname.size()+1));
298  Teuchos::Array<char> coption(size_type(pname.size()+1));
299 
300  int matched = sscanf(pname.c_str(),"%s %[^(](level %d)", ctype.getRawPtr(), coption.getRawPtr(), &levelID); // use [^(] instead of %s to allow for strings with white-spaces (ex: "ifpack list")
301  type = std::string(ctype.getRawPtr());
302  option = std::string(coption.getRawPtr()); option.resize(option.size () - 1); // remove final white-space
303 
304  if (matched != 3 || (type != "smoother:")) {
305  TEUCHOS_TEST_FOR_EXCEPTION(true, MueLu::Exceptions::RuntimeError, "MueLu::CreateSublist(), Line " << __LINE__ << ". "
306  << "Error in creating level-specific sublists" << std::endl
307  << "Offending parameter: " << pname << std::endl);
308  }
309 
310  mueluss << "<ParameterList name=\"level " << levelID << "\">" << std::endl;
311  mueluss << GetSmootherFactory(paramList.sublist(pname),adaptingParamList.sublist(pname), "smoother: type", paramList.sublist(pname).get<std::string>("smoother: type"));
312  mueluss << "</ParameterList>" << std::endl;
313  }
314  }
315 
316  // special handling for coarse level
317  TEUCHOS_TEST_FOR_EXCEPTION(paramList.isParameter("coarse: type"), Exceptions::RuntimeError, "MueLu::MLParameterListInterpreter::Setup(): The parameter \"coarse: type\" should not exist but being stored in \"coarse: list\" instead.");
318  if ( pname == "coarse: list" ) {
319 
320  // interpret smoother/coarse solver data.
321  // Note, that we inspect the "coarse: list" sublist to define the "coarse" smoother/solver
322  // Be aware, that MueLu::CreateSublists renames the prefix of the parameters in the "coarse: list" from "coarse" to "smoother".
323  // Therefore, we have to check the values of the "smoother" parameters
324  TEUCHOS_TEST_FOR_EXCEPTION(!paramList.sublist("coarse: list").isParameter("smoother: type"), Exceptions::RuntimeError, "MueLu::MLParameterListInterpreter::Setup(): no coarse grid solver defined.");
325  mueluss << GetSmootherFactory(paramList.sublist("coarse: list"), adaptingParamList.sublist("coarse: list"), "coarse: type", paramList.sublist("coarse: list").get<std::string>("smoother: type"));
326 
327 
328  }
329  } // for
330 
331  mueluss << "</ParameterList>" << std::endl;
332 
333  return mueluss.str();
334  }
335 
336 
337 } // namespace MueLu
static std::string SetParameterList(const Teuchos::ParameterList &paramList_in, const std::string &defaultVals)
: Interpret parameter list
const std::string & name() const
void MergeParameterList(const Teuchos::ParameterList &source, Teuchos::ParameterList &dest, bool overWrite)
: merge two parameter lists
ConstIterator end() const
T & get(const std::string &name, T def_value)
ParameterList & set(std::string const &name, T const &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
static std::string interpretParameterName(const std::string &name, const std::string &value)
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
std::string tolower(const std::string &str)
bool isParameter(const std::string &name) const
static std::string GetSmootherFactory(const Teuchos::ParameterList &paramList, Teuchos::ParameterList &adaptingParamList, const std::string &pname, const std::string &value)
: Helper function which translates ML smoother/solver paramters to MueLu XML string ...
void CreateSublists(const ParameterList &List, ParameterList &newList)
bool remove(std::string const &name, bool throwIfNotExists=true)
params_t::ConstIterator ConstIterator
ConstIterator begin() const
const ParameterEntry & entry(ConstIterator i) const
static std::string ML2MueLu(const std::string &name)
Translate ML parameter to corresponding MueLu parameter.
ParameterList & sublist(const std::string &name, bool mustAlreadyExist=false, const std::string &docString="")
Exception throws to report errors in the internal logical of the program.
void replaceAll(std::string &str, const std::string &from, const std::string &to)