Zoltan2
Zoltan2_Parameters.cpp
Go to the documentation of this file.
1 // @HEADER
2 //
3 // ***********************************************************************
4 //
5 // Zoltan2: A package of combinatorial algorithms for scientific computing
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 Karen Devine (kddevin@sandia.gov)
39 // Erik Boman (egboman@sandia.gov)
40 // Siva Rajamanickam (srajama@sandia.gov)
41 //
42 // ***********************************************************************
43 //
44 // @HEADER
45 
50 #include <Zoltan2_Parameters.hpp>
52 
53 #include <Teuchos_StringInputSource.hpp>
54 #include <Teuchos_XMLParser.hpp>
55 #include <Teuchos_XMLObject.hpp>
56 #include <Teuchos_XMLParameterListReader.hpp>
57 #include <Teuchos_ValidatorXMLConverterDB.hpp>
58 
59 // A generated header file in {zoltan2-binary-directory}/src
60 // which defines ZOLTAN2_XML_PARAMETER_STRING.
61 
63 
64 namespace Zoltan2 {
65 
74 void createAllParameters(Teuchos::ParameterList &pList)
75 {
76  // An XML converter for IntegerRangeListValidator
77  // needs to be added to the converter database.
78 
81 
82  RCP<const irl_t> intRangeValidatorP = rcp(new irl_t); // dummy
83  RCP<irlConverter_t > converter = rcp(new irlConverter_t);
84  Teuchos::ValidatorXMLConverterDB::addConverter(
85  intRangeValidatorP,
86  converter);
87 
88  // Create a Teuchos::ParameterList from an XML string.
89  // To add a parameter to Zoltan2, edit zoltan2/data/parameters.xml.
90 
91  std::string xmlParameterString(ZOLTAN2_XML_PARAMETER_STRING);
92  Teuchos::StringInputSource src(xmlParameterString);
93 
94  Teuchos::XMLObject xmlObj;
95  std::ostringstream errMsg;
96 
97  Teuchos::XMLParser parser(src.stream());
98 
99  try{
100  xmlObj = parser.parse();
101  }
102  catch (std::exception &e){
103  errMsg << e.what() << " invalid xml";
104  }
105 
106  if (errMsg.str().size() == 0){
107  try{
108  Teuchos::XMLParameterListReader rdr;
109  pList = rdr.toParameterList(xmlObj);
110  }
111  catch (std::exception &e){
112  errMsg << e.what() << " invalid parameter list";
113  }
114  }
115 
116  if (errMsg.str().size() > 0)
117  throw std::logic_error(errMsg.str().c_str());
118 }
119 
144  const Teuchos::ParameterList &plSome, // in: user's parameters
145  const Teuchos::ParameterList &plAll, // in: validators for all params
146  Teuchos::ParameterList &plVal) // out: validators for user's params
147 {
148  ParameterList::ConstIterator next = plSome.begin();
149 
150  while (next != plSome.end()){
151 
152  const std::string &name = next->first;
153  const ParameterEntry &entrySome = plSome.getEntry(name);
154  const ParameterEntry &entryAll = plAll.getEntry(name);
155 
156  if (entrySome.isList()){
157  plVal.sublist(name); // create & get
158  // Don't set validators for sublists; sublists are for TPL's parameters
159  }
160  else{
161  plVal.setEntry(name, entryAll);
162  }
163 
164  ++next;
165  }
166 }
167 
175  const Teuchos::ParameterList &plIn,
176  Teuchos::ParameterList &plOut)
177 {
178  ParameterList allParameters;
179 
180  try{
181  createAllParameters(allParameters);
182  }
184 
185  setValidatorsInList(plIn, allParameters, plOut);
186 }
187 
188 // Why isn't there a Teuchos method that does this?
189 
191  const Teuchos::ParameterList &pl,
192  std::ostream &os,
193  std::string listNames)
194 {
195 
196  if (listNames.size() == 0)
197  listNames = std::string("top");
198 
199  Array<std::string> subLists;
200  ParameterList::ConstIterator next = pl.begin();
201 
202  while (next != pl.end()){
203  const std::string &name = next->first;
204  const ParameterEntry &entry = pl.getEntry(name);
205 
206  if (entry.isList()){
207  subLists.append(name);
208  }
209  else{
210  std::string doc = entry.docString();
211  os << "List: "<< listNames << ", parameter: " << name << "\n";
212  if (doc.size())
213  os << doc << "\n";
214  }
215 
216  ++next;
217  }
218 
219  for (int i=0; i < subLists.size(); i++){
220  std::string newListName = listNames + std::string("/") + subLists[i];
221  const ParameterList &sublist = pl.sublist(subLists[i]);
222  printListDocumentation(sublist, os, newListName);
223  }
224 }
225 
226 
227 } //namespace Zoltan2
#define ZOLTAN2_XML_PARAMETER_STRING
#define Z2_FORWARD_EXCEPTIONS
Forward an exception back through call stack.
Defines Parameter related enumerators, declares functions.
XML conversion code for IntegerRangeListValidator.
void createValidatorList(const Teuchos::ParameterList &plIn, Teuchos::ParameterList &plOut)
Create a list by adding validators to the users parameter list.
void createAllParameters(Teuchos::ParameterList &pList)
Create a list of all Zoltan2 parameters and validators.
void printListDocumentation(const Teuchos::ParameterList &pl, std::ostream &os, std::string listNames)
A ParameterList validator for integer range lists.
Define IntegerRangeList validator.
static void setValidatorsInList(const Teuchos::ParameterList &plSome, const Teuchos::ParameterList &plAll, Teuchos::ParameterList &plVal)
Create a parameter list that can validate a specific list of parameters.