Zoltan2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
paramToXML.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 
51 #include <Teuchos_ParameterList.hpp>
52 #include <Teuchos_XMLObject.hpp>
53 #include <Teuchos_XMLParameterListWriter.hpp>
54 #include <Teuchos_ParameterXMLFileReader.hpp>
55 #include <Teuchos_ValidatorXMLConverterDB.hpp>
56 
57 #include <Teuchos_StandardParameterEntryValidators.hpp>
58 #include <Zoltan2_Standards.hpp>
59 #include <Zoltan2_Parameters.hpp>
61 
62 #include <iostream>
63 #include <fstream>
64 #include <sstream>
65 #include <string>
66 
67 using std::string;
68 using std::ostringstream;
69 using std::endl;
70 using std::cout;
71 using std::cout;
72 using Teuchos::RCP;
73 using Teuchos::rcp;
74 using Teuchos::Tuple;
75 
76 
77 
78 void createAllParameters(Teuchos::ParameterList &pList);
79 
80 int main(int argc, char *argv[])
81 {
82  string xmlFile("initParams.xml");
83  Teuchos::XMLParameterListWriter plw;
84 
85  // XML converter for Zoltan2::IntegerRangeListValidator must be added
86  // once to the validator database.
87 
89  RCP<irlConverter_t > converter = rcp(new irlConverter_t);
91  RCP<const irl_t> intRangeValidatorP = rcp(new irl_t);
92 
93  Teuchos::ValidatorXMLConverterDB::addConverter(
94  intRangeValidatorP, // can be a dummy of this type
95  converter);
96 
97  Teuchos::ParameterList pl("zoltan2ValidatingParameters");
99 
100  // Write out to XML
101  Teuchos::XMLObject obj = plw.toXML(pl);
102 
103  cout << "Parameter list: " << endl;
104  cout << obj << endl;
105 
106  std::ofstream of;
107  of.open(xmlFile.c_str());
108  of << obj << endl;
109  of.close();
110 }
111 
112 void createAllParameters(Teuchos::ParameterList &pList)
113 {
114  using Teuchos::tuple;
115  using std::string;
116 
117  using Teuchos::AnyNumberParameterEntryValidator;
118  RCP<const AnyNumberParameterEntryValidator> anyNumValidatorP;
119 
120  using Teuchos::EnhancedNumberValidator;
121  RCP<const EnhancedNumberValidator<int> > intValidatorP;
122 
123  using Teuchos::StringValidator;
124  RCP<const StringValidator> strValidatorP;
125 
126  using Teuchos::FileNameValidator;
127  RCP<const FileNameValidator > fnameValidatorP;
128 
129  using Teuchos::StringToIntegralParameterEntryValidator;
130  typedef StringToIntegralParameterEntryValidator<int> str2intValidator;
131  RCP<const str2intValidator> str2intValidatorP;
132 
133  Tuple<string,8> yesNoStrings =
134  tuple<string>( "true", "yes", "1", "on", "false", "no", "0", "off");
135 
136  Tuple<int,8> yesNoIntegrals =
137  tuple<int>( 1, 1, 1, 1, 0, 0, 0, 0);
138 
139  // allowed values for output streams
140 
141  Tuple<string,8> ostreamStrings =
142  tuple<string>( "std::cout", "cout", "stdout",
143  "std::cerr", "cerr", "stderr",
144  "/dev/null", "null");
145 
146  Tuple<int,8> ostreamIntegrals =
147  tuple<int>( 0, 0, 0, 1, 1, 1, 2, 2);
148 
149  RCP<const Zoltan2::IntegerRangeListValidator<int> > intRangeValidatorP;
150 
151  string parameterName;
152  std::ostringstream docString;
153 
154  parameterName = string("error_check_level");
155 
156  str2intValidatorP = rcp(new str2intValidator(
157 
158  tuple<string>("no_assertions",
159  "basic_assertions",
160  "complex_assertions",
161  "debug_mode_assertions"),
162 
163  tuple<string>(
164  "no assertions will be performed",
165  "typical checks of argument validity (fast, default)",
166  "additional checks, i.e. is input graph a valid graph)",
167  "check for everything including logic errors (slowest)"),
168 
169  tuple<int>(Zoltan2::NO_ASSERTIONS,
173 
174  parameterName));
175 
176  string omitInfo("the amount of error checking performed\n");
177  omitInfo.append("(If the compile flag Z2_OMIT_ALL_ERROR_CHECKING was set,\n");
178  omitInfo.append("then error checking code is not executed at runtime.)\n");
179  docString.str("");
180  str2intValidatorP->printDoc(omitInfo, docString);
181 
182  pList.set<string>(parameterName, "basic_assertions", docString.str(),
183  str2intValidatorP);
184 
186  parameterName = string("debug_level");
187 
188  str2intValidatorP = rcp(new str2intValidator(
189  tuple<string>("no_status",
190  "basic_status",
191  "detailed_status",
192  "verbose_detailed_status"),
193 
194  tuple<string>(
195  "library outputs no status information",
196  "library outputs basic status information (default)",
197  "library outputs detailed information",
198  "library outputs very detailed information"),
199 
200  tuple<int>(
205 
206  parameterName));
207 
208  omitInfo = string("the amount of status/warning/debugging info printed\n");
209  omitInfo.append("(If the compile flag Z2_OMIT_ALL_STATUS_MESSAGES was set,\n");
210  omitInfo.append("then message output code is not executed at runtime.)\n");
211  docString.str("");
212  str2intValidatorP->printDoc(
213  "the amount of status/debugging/warning information to print\n", docString);
214 
215  pList.set<string>(parameterName, "basic_status", docString.str(),
216  str2intValidatorP);
217 
219 
220  parameterName = string("timer_type");
221 
222  str2intValidatorP = rcp(new str2intValidator(
223  tuple<string>(
224  "no_timers", "macro_timers", "micro_timers", "both_timers", "test_timers"),
225 
226  tuple<string>(
227  "No timing data will be collected (the default).",
228  "Time an algorithm (or other entity) as a whole.",
229  "Time the substeps of an entity.",
230  "Run both MACRO and MICRO timers.",
231  "Run timers added to code for testing, removed later"),
232 
234 
235  parameterName));
236 
237  omitInfo = string("the type of timing information to collect\n");
238  omitInfo.append("(If the compile flag Z2_OMIT_ALL_PROFILING was set,\n");
239  omitInfo.append("then the timing code is not executed at runtime.)\n");
240  docString.str("");
241  str2intValidatorP->printDoc(omitInfo, docString);
242 
243  pList.set<string>(parameterName, "no_timers", docString.str(),
244  str2intValidatorP);
245 
247  parameterName = string("debug_output_stream");
248 
249  str2intValidatorP =
250  rcp(new str2intValidator(ostreamStrings, ostreamIntegrals, parameterName));
251 
252  docString.str("");
253  str2intValidatorP->printDoc(
254  "output stream for debug/status/warning messages (default cout)\n",
255  docString);
256 
257  pList.set<string>(parameterName, "cout", docString.str(),
258  str2intValidatorP);
259 
261  parameterName = string("timer_output_stream");
262 
263  str2intValidatorP =
264  rcp(new str2intValidator(ostreamStrings, ostreamIntegrals, parameterName));
265 
266  docString.str("");
267  str2intValidatorP->printDoc(
268  "output stream for timing report (default cout)\n",
269  docString);
270 
271  pList.set<string>(parameterName, "cout", docString.str(),
272  str2intValidatorP);
273 
275  parameterName = string("memory_output_stream");
276 
277  str2intValidatorP =
278  rcp(new str2intValidator(ostreamStrings, ostreamIntegrals, parameterName));
279 
280  docString.str("");
281  str2intValidatorP->printDoc(
282  "output stream for memory usage messages (default cout)\n",
283  docString);
284 
285  pList.set<string>(parameterName, "cout", docString.str(),
286  str2intValidatorP);
287 
288 
290  parameterName = string("debug_output_file");
291 
292  fnameValidatorP = rcp(new FileNameValidator(false));
293  docString.str("");
294  fnameValidatorP->printDoc(
295  "name of file to which debug/status messages should be written\n"
296  "(process rank will be included in file name)\n",
297  docString);
298 
299  pList.set<string>(parameterName, "/dev/null", docString.str(), fnameValidatorP);
300 
302  parameterName = string("timer_output_file");
303 
304  docString.str("");
305  fnameValidatorP->printDoc(
306  "name of file to which timing information should be written\n"
307  "(process rank will be included in file name)\n",
308  docString);
309 
310  pList.set<string>(parameterName, "/dev/null", docString.str(), fnameValidatorP);
311 
313  parameterName = string("memory_output_file");
314 
315  docString.str("");
316  fnameValidatorP->printDoc(
317  "name of file to which memory profiling information should be written\n"
318  "(process rank will be included in file name)\n",
319  docString);
320 
321  pList.set<string>(parameterName, "/dev/null", docString.str(), fnameValidatorP);
322 
324  parameterName = string("debug_procs");
325 
326  RCP<const Zoltan2::IntegerRangeListValidator<int> > intRangeValidatorUnsertedP = rcp(new Zoltan2::IntegerRangeListValidator<int>(true));
327 
328  docString.str("");
329  intRangeValidatorUnsertedP->printDoc(
330  "list of ranks that output debugging/status messages (default \"0\")\n",
331  docString);
332 
333  pList.set<string>(parameterName, "0", docString.str(), intRangeValidatorUnsertedP);
334 
336  parameterName = string("pqParts");
337 
338  RCP<const Zoltan2::IntegerRangeListValidator<int> > pqRangeRangeValidatorP = rcp(new Zoltan2::IntegerRangeListValidator<int>(true));
339 
340  docString.str("");
341  pqRangeRangeValidatorP->printDoc(
342  "list of parts for pqJagged partitioning algorithm. As many as the dimension count.\n",
343  docString);
344 
345  pList.set<string>(parameterName, "0", docString.str(), pqRangeRangeValidatorP);
346 
348  intRangeValidatorP = rcp(new Zoltan2::IntegerRangeListValidator<int>(true));
349  parameterName = string("memory_procs");
350 
351  docString.str("");
352  intRangeValidatorP->printDoc(
353  "list of ranks that memory profiling information (default \"0\")\n",
354  docString);
355 
356  pList.set<string>(parameterName, "0", docString.str(), intRangeValidatorP);
357 
359  parameterName = string("speed_versus_quality");
360 
361  strValidatorP = rcp(new StringValidator(
362  tuple<string>("speed", "balance", "quality")));
363 
364  docString.str("");
365  strValidatorP->printDoc(
366  "When algorithm choices exist, opt for speed or solution quality?\n"
367  "(Default is a balance of speed and quality)\n",
368  docString);
369 
370  pList.set<string>(parameterName, "balance", docString.str(), strValidatorP);
371 
373  parameterName = string("memory_versus_speed");
374 
375  strValidatorP = rcp(new StringValidator(
376  tuple<string>("memory", "balance", "speed")));
377 
378  docString.str("");
379  strValidatorP->printDoc(
380  "When algorithm choices exist, opt for the use of less memory\n"
381  "at the expense of runtime\n"
382  "(Default is a balance of memory conservation and speed)\n",
383  docString);
384 
385  pList.set<string>(parameterName, "balance", docString.str(), strValidatorP);
386 
388  parameterName = string("random_seed");
389 
390  anyNumValidatorP = rcp(new AnyNumberParameterEntryValidator);
391 
392  docString.str("");
393  anyNumValidatorP->printDoc("random seed\n", docString);
394 
395  pList.set<string>(parameterName, "0.5", docString.str(), anyNumValidatorP);
396 
398  parameterName = string("order_method");
399  strValidatorP = rcp(new StringValidator(
400  tuple<string>("rcm", "minimum_degree", "method3")));
401 
402  docString.str("");
403  strValidatorP->printDoc(
404  "Document the order_method parameter here\n"
405  "(Default is ?)\n",
406  docString);
407 
408  pList.set<string>(parameterName, "rcm", docString.str(), strValidatorP);
409 
411  parameterName = string("order_package");
412  strValidatorP = rcp(new StringValidator(
413  tuple<string>("amd", "package2", "package3")));
414 
415  docString.str("");
416  strValidatorP->printDoc(
417  "Document the order_package parameter here\n"
418  "(Default is ?)\n",
419  docString);
420 
421  pList.set<string>(parameterName, "amd", docString.str(), strValidatorP);
422 
424  parameterName = string("compute_metrics");
425 
426  str2intValidatorP =
427  rcp(new str2intValidator(yesNoStrings, yesNoIntegrals, parameterName));
428 
429  docString.str("");
430  str2intValidatorP->printDoc("Compute metrics after computing solution\n",
431  docString);
432 
433  pList.set<string>(parameterName, "no", docString.str(),
434  str2intValidatorP);
435 
437  parameterName = string("topology");
438 
439  strValidatorP = rcp(new StringValidator);
440 
441  docString.str("");
442  docString << "Topology of node to be used in hierarchical partitioning\n";
443  docString << " \"2,4\" for dual-socket quad-core\n";
444  docString << " \"2,2,6\" for dual-socket, dual-die, six-core\n";
445  docString << " \"2,2,3\" for dual-socket, dual-die, six-core but\n";
446  docString << " with only three partitions per die\n";
447 
448  pList.set<string>(parameterName, "", docString.str(), strValidatorP);
449 
451  parameterName = string("randomize_input");
452 
453  str2intValidatorP =
454  rcp(new str2intValidator(yesNoStrings, yesNoIntegrals, parameterName));
455 
456  docString.str("");
457  str2intValidatorP->printDoc("randomize input prior to partitioning\n",
458  docString);
459 
460  pList.set<string>(parameterName, "no", docString.str(),
461  str2intValidatorP);
462 
464  parameterName = string("partitioning_objective"); // TODO
465 
466  strValidatorP = rcp(new StringValidator(
467  tuple<string>(
468  "balance_object_count",
469  "balance_object_weight",
470  "multicriteria_minimize_total_weight",
471  "multicriteria_minimize_maximum_weight",
472  "multicriteria_balance_total_maximum",
473  "minimize_cut_edge_count",
474  "minimize_cut_edge_weight",
475  "minimize_neighboring_parts",
476  "minimize_boundary_vertices")));
477 
478  docString.str("");
479  strValidatorP->printDoc(
480  "objective of partitioning (default depends on algorithm)\n",
481  docString);
482 
483  pList.set<string>(parameterName, "balance_object_weight",
484  docString.str(), strValidatorP);
485 
487  parameterName = string("imbalance_tolerance");
488 
489  anyNumValidatorP = rcp(new AnyNumberParameterEntryValidator);
490 
491  docString.str("");
492  anyNumValidatorP->printDoc(
493  "imbalance tolerance, ratio of maximum load over average load"
494  " (default 1.1)\n",
495  docString);
496 
497  pList.set<string>(parameterName, "1.1", docString.str(),
498  anyNumValidatorP);
499 
501  parameterName = string("num_global_parts");
502 
503  anyNumValidatorP = rcp(new AnyNumberParameterEntryValidator);
504 
505  docString.str("");
506  anyNumValidatorP->printDoc(
507  "global number of parts to compute (default is number of processes)\n",
508  docString);
509 
510  pList.set<string>(parameterName, "0", docString.str(),
511  anyNumValidatorP);
512 
514  parameterName = string("num_local_parts");
515 
516  anyNumValidatorP = rcp(new AnyNumberParameterEntryValidator);
517 
518  docString.str("");
519  anyNumValidatorP->printDoc(
520  "number of parts to compute for this process(default is one)\n",
521  docString);
522 
523  pList.set<string>(parameterName, "0", docString.str(),
524  anyNumValidatorP);
525 
527  parameterName = string("partitioning_approach"); // TODO
528 
529  strValidatorP = rcp(new StringValidator(
530  tuple<string>("partition", "repartition", "maximize_overlap")));
531 
532  docString.str("");
533  strValidatorP->printDoc(
534  "Partition from scratch, partition incrementally from current\n"
535  "partition, of partition from scratch but maximize overlap\n"
536  "with the current partition (default is \"partition\" from scratch)\n",
537  docString);
538 
539  pList.set<string>(parameterName, "partition", docString.str(),
540  strValidatorP);
541 
543  parameterName = string("objects_to_partition"); // TODO
544 
545  strValidatorP = rcp(new StringValidator(
546  tuple<string>(
547  "matrix_rows",
548  "matrix_columns",
549  "matrix_nonzeros",
550  "mesh_elements",
551  "mesh_nodes",
552  "graph_edges",
553  "graph_vertices",
554  "coordinates",
555  "identifiers")));
556 
557  docString.str("");
558  strValidatorP->printDoc(
559  "Objects to be partitioned (defaults are \"matrix_rows\" for\n"
560  "matrix input, \"mesh_nodes\" for mesh input, and \"graph_vertices\"\n"
561  "for graph input)\n",
562  docString);
563 
564  pList.set<string>(parameterName, "graph_vertices", docString.str(),
565  strValidatorP);
566 
568  parameterName = string("model");
569 
570  strValidatorP = rcp(new StringValidator(
571  tuple<string>("hypergraph", "graph", "geometry", "ids")));
572 
573  docString.str("");
574  strValidatorP->printDoc(
575  "This is a low level parameter. Normally the library will choose\n"
576  "a computational model based on the algorithm or objective specified\n"
577  "by the user.\n",
578  docString);
579 
580  pList.set<string>(parameterName, "graph", docString.str(),
581  strValidatorP);
582 
584  parameterName = string("algorithm");
585 
586  strValidatorP = rcp(new StringValidator(
587  tuple<string>(
588  "rcb",
589  "multijagged",
590  "rib",
591  "hsfc",
592  "patoh",
593  "phg",
594  "metis",
595  "parmetis",
596  "scotch",
597  "ptscotch",
598  "block",
599  "cyclic",
600  "random")));
601 
602  docString.str("");
603  strValidatorP->printDoc("partitioning algorithm\n", docString);
604 
605  pList.set<string>(parameterName, "random", docString.str(),
606  strValidatorP);
607 
609  parameterName = string("rectilinear");
610 
611  str2intValidatorP =
612  rcp(new str2intValidator(yesNoStrings, yesNoIntegrals, parameterName));
613 
614  docString.str("");
615  str2intValidatorP->printDoc(
616  "If true, then when a cut is made, all of the dots located on the cut\n"
617  "are moved to the same side of the cut. The resulting regions are then\n"
618  "rectilinear. The resulting load balance may not be as good as when\n"
619  "the group of dots is split by the cut. Default is false.\n",
620  docString);
621 
622  pList.set<string>(parameterName, "no", docString.str(),
623  str2intValidatorP);
624 
626  parameterName = string("average_cuts");
627 
628  str2intValidatorP =
629  rcp(new str2intValidator(yesNoStrings, yesNoIntegrals, parameterName));
630 
631  docString.str("");
632  str2intValidatorP->printDoc(
633  "When true, coordinates of RCB cutting planes are computed to be \n"
634  "the average of the coordinates of the closest object on each side \n"
635  "of the cut. Otherwise, coordinates of cutting planes may equal \n"
636  "those of one of the closest objects. Default is false.\n",
637  docString);
638 
639  pList.set<string>(parameterName, "no", docString.str(),
640  str2intValidatorP);
641 
643  parameterName = string("symmetrize_input");
644 
645  strValidatorP = rcp(new StringValidator(
646  tuple<string>( "no", "transpose", "bipartite")));
647 
648  docString.str("");
649  strValidatorP->printDoc(
650  "Symmetrize input prior to pList. If \"transpose\",\n"
651  "symmetrize A by computing A plus ATranspose. If \"bipartite\",\n"
652  "A becomes [[0 A][ATranspose 0]]. \n",
653  docString);
654 
655  pList.set<string>(parameterName, "no", docString.str(),
656  strValidatorP);
657 
659  parameterName = string("subset_graph");
660 
661  str2intValidatorP =
662  rcp(new str2intValidator(yesNoStrings, yesNoIntegrals, parameterName));
663 
664  docString.str("");
665  str2intValidatorP->printDoc(
666  "If \"yes\", the graph input is to be subsetted. If a vertex neighbor\n"
667  "is not a valid vertex, it will be omitted from the pList. Otherwise,\n"
668  "an invalid neighbor identifier is considered an error.\n",
669  docString);
670 
671  pList.set<string>(parameterName, "no", docString.str(),
672  str2intValidatorP);
673 }
checks for logic errors
Time an algorithm (or other entity) as a whole.
fast typical checks for valid arguments
Defines Parameter related enumerators, declares functions.
XML conversion code for IntegerRangeListValidator.
more involved, like validate a graph
int main(int narg, char **arg)
Definition: coloring1.cpp:199
Time the substeps of an entity.
sub-steps, each method&#39;s entry and exit
Run both MACRO and MICRO timers.
A ParameterList validator for integer range lists.
no assertion checks will be done
Timers added while testing, removed later.
don&#39;t display status/debug messages
the status at each high level step
Define IntegerRangeList validator.
void createAllParameters(Teuchos::ParameterList &pList)
Definition: paramToXML.cpp:112
Gathering definitions used in software development.
include more detail about sub-steps
No timing data will be collected (the default).