Zoltan2
Loading...
Searching...
No Matches
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>
61
62#include <iostream>
63#include <fstream>
64#include <sstream>
65#include <string>
66
67using std::string;
68using std::ostringstream;
69using std::endl;
70using std::cout;
71using std::cout;
72using Teuchos::RCP;
73using Teuchos::rcp;
74using Teuchos::Tuple;
75
76
77
78void createAllParameters(Teuchos::ParameterList &pList);
79
80int 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
112void 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}
Define IntegerRangeList validator.
Defines Parameter related enumerators, declares functions.
Gathering definitions used in software development.
int main()
XML conversion code for IntegerRangeListValidator.
A ParameterList validator for integer range lists.
@ NO_TIMERS
No timing data will be collected (the default).
@ MACRO_TIMERS
Time an algorithm (or other entity) as a whole.
@ TEST_TIMERS
Timers added while testing, removed later.
@ MICRO_TIMERS
Time the substeps of an entity.
@ BOTH_TIMERS
Run both MACRO and MICRO timers.
@ BASIC_STATUS
the status at each high level step
@ DETAILED_STATUS
sub-steps, each method's entry and exit
@ NO_STATUS
don't display status/debug messages
@ VERBOSE_DETAILED_STATUS
include more detail about sub-steps
@ BASIC_ASSERTION
fast typical checks for valid arguments
@ NO_ASSERTIONS
no assertion checks will be done
@ DEBUG_MODE_ASSERTION
checks for logic errors
@ COMPLEX_ASSERTION
more involved, like validate a graph
void createAllParameters(Teuchos::ParameterList &pList)
Definition: paramToXML.cpp:112