Zoltan2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Zoltan2_Environment.hpp
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 #ifndef _ZOLTAN2_ENVIRONMENT_HPP_
51 #define _ZOLTAN2_ENVIRONMENT_HPP_
52 
53 #include <Zoltan2_config.h>
54 #include <Zoltan2_Util.hpp>
55 #include <Zoltan2_IO.hpp>
56 #include <Zoltan2_Parameters.hpp>
57 #include <Zoltan2_DebugManager.hpp>
58 #include <Zoltan2_TimerManager.hpp>
60 
61 #include <Teuchos_RCP.hpp>
62 #include <Teuchos_ParameterList.hpp>
63 #include <Teuchos_Comm.hpp>
64 #include <Teuchos_DefaultComm.hpp>
65 #include <Teuchos_CommHelpers.hpp>
66 #include <Teuchos_StandardParameterEntryValidators.hpp>
67 
68 namespace Zoltan2 {
69 
84 
85 public:
86 
87  typedef long memory_t;
89  typedef Teuchos::RCP<const Teuchos::Comm<int> > Comm_t;
90  typedef Teuchos::RCP<DebugManager> DebugManager_t;
91  typedef Teuchos::RCP<MetricOutputManager<memory_t> > MemoryProfilerManager_t;
92  typedef Teuchos::RCP<TimerManager> Timer_t;
93 
94  int myRank_;
96  int numProcs_;
108  Environment(Teuchos::ParameterList &problemParams,
109  const Teuchos::RCP<const Teuchos::Comm<int> > &comm );
110 
118  Environment(const Teuchos::RCP<const Teuchos::Comm<int> > &comm);
119 
122  ~Environment();
123 
126  void resetParameters(Teuchos::ParameterList &problemParams);
127 
130  static void getValidParameters(ParameterList & pl);
131 
134  static RCP<Teuchos::BoolParameterEntryValidator> getBoolValidator();
135 
138  static RCP<Teuchos::AnyNumberParameterEntryValidator>
140 
143  static RCP<Teuchos::AnyNumberParameterEntryValidator>
145 
152  void setTimer(RCP<TimerManager> &timer) { timerOut_=timer; timingOn_=true;}
153 
154 #ifdef Z2_OMIT_ALL_ERROR_CHECKING
155 
156  inline void localInputAssertion(const char *file, int lineNum,
157  const char *msg, bool ok, AssertionLevel level) const {}
158 
159  inline void globalInputAssertion(const char *file, int lineNum,
160  const char *msg, bool ok, AssertionLevel level,
161  const Comm_t &comm=comm_) const {}
162 
163  inline void localBugAssertion(const char *file, int lineNum,
164  const char *msg, bool ok, AssertionLevel level) const {}
165 
166  inline void globalBugAssertion(const char *file, int lineNum,
167  const char *msg, bool ok, AssertionLevel level,
168  const Comm_t &comm=comm_) const {}
169 
170  inline void localMemoryAssertion(const char *file, int lineNum,
171  size_t nobj, bool ok) const {}
172 
173  inline void globalMemoryAssertion(const char *file, int lineNum,
174  size_t nobj, bool ok, const Comm_t &comm=comm_) const {}
175 
176 #else
177 
191  inline void localInputAssertion(const char *file, int lineNum,
192  const char *msg, bool ok, AssertionLevel level) const {
193 
194  if (level <= errorCheckLevel_ && !ok){
195  std::ostringstream emsg;
196  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
197  if (msg)
198  emsg << myRank_ << ": error: " << msg << std::endl;
199  throw std::runtime_error(emsg.str());
200  }
201  }
218  inline void globalInputAssertion(const char *file, int lineNum,
219  const char *msg, bool ok, AssertionLevel level,
220  const Comm_t &comm) const {
221 
222  if (level <= errorCheckLevel_){
223  int anyFail=0, fail = (!ok ? 1 : 0);
224  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
225  &anyFail);
226  if (anyFail > 0){
227  std::ostringstream emsg;
228  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
229  if (msg && !ok)
230  emsg << myRank_ << ": error: " << msg << std::endl;
231  else
232  emsg << myRank_ << ": exiting" << std::endl;
233 
234  throw std::runtime_error(emsg.str());
235  }
236  }
237  }
238 
258  inline void localBugAssertion(const char *file, int lineNum,
259  const char *msg, bool ok, AssertionLevel level) const {
260 
261  if (level <= errorCheckLevel_ && !ok){
262  std::ostringstream emsg;
263  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
264  if (msg)
265  emsg << myRank_ << ": bug: " << msg << std::endl;
266  throw std::logic_error(emsg.str());
267  }
268  }
269 
291  inline void globalBugAssertion(const char *file, int lineNum,
292  const char *msg, bool ok, AssertionLevel level,
293  const Comm_t &comm) const {
294 
295  if (level <= errorCheckLevel_){
296  int anyFail=0, fail = (!ok ? 1 : 0);
297  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
298  &anyFail);
299  if (anyFail > 0){
300 
301  std::ostringstream emsg;
302  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
303  if (msg && !ok)
304  emsg << myRank_ << ": bug: " << msg << std::endl;
305  else
306  emsg << myRank_ << ": exiting" << std::endl;
307 
308  throw std::logic_error(emsg.str());
309  }
310  }
311  }
312 
326  inline void localMemoryAssertion(const char *file, int lineNum, size_t nobj,
327  bool ok) const {
328 
329  if (!ok){
330  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
331  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
332  throw std::bad_alloc();
333  }
334  }
335 
351  inline void globalMemoryAssertion(const char *file, int lineNum,
352  size_t nobj, bool ok, const Comm_t &comm) const {
353 
354  int anyFail=0, fail = (!ok ? 1 : 0);
355  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail, &anyFail);
356  if (anyFail > 0){
357  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
358  if (!ok)
359  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
360  else
361  std::cerr << myRank_ << ": exiting" << std::endl;
362 
363  throw std::bad_alloc();
364  }
365  }
366 #endif
367 
368  // For debugging and profiling output, we define "char *" versions
369  // as well as "string" versions to avoid runtime conversion of "char *"
370  // to "string".
371 
383 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
384  inline void debug(MessageOutputLevel level, const char *msg) const{ return;}
385  inline void debug(MessageOutputLevel level, const std::string& msg) const{
386  return;
387  }
388  inline void debug(int level, const char *msg) const{ return;}
389  inline void debug(int level, const std::string& msg) const{ return;}
390 #else
391  inline void debug(MessageOutputLevel level, const char *msg) const{
392  debugOut_->print(level, msg);
393  }
394 
395  inline void debug(MessageOutputLevel level, const std::string& msg) const{
396  debugOut_->print(level, msg);
397  }
398 
399  inline void debug(int level, const char *msg) const{
400  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
401  debugOut_->print(msg_enum, msg);
402  }
403 
404  inline void debug(int level, const std::string& msg) const{
405  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
406  debugOut_->print(msg_enum, msg);
407  }
408 #endif
409 
410 #ifdef Z2_OMIT_ALL_PROFILING
411 
412  inline void timerStart(TimerType tt, const char * timerName) const {return;}
413  inline void timerStart(TimerType tt, const std::string &timerName) const {return;}
414  inline void timerStart(TimerType tt, const char * timerName, int,
415  int fieldWidth=0) const {return;}
416  inline void timerStart(TimerType tt, const std::string &timerName, int,
417  int fieldWidth=0) const {return;}
418 
419  inline void timerStop(TimerType tt, const char * timerName) const {return;}
420  inline void timerStop(TimerType tt, const std::string &timerName) const {return;}
421  inline void timerStop(TimerType tt, const char * timerName, int,
422  int fieldWidth=0) const {return;}
423  inline void timerStop(TimerType tt, const std::string &timerName, int,
424  int fieldWidth=0) const {return;}
425 
426 #else
427 
430  inline void timerStart(TimerType tt, const char *timerName) const {
431  if (timingOn_) timerOut_->start(tt, timerName); }
432 
433  inline void timerStart(TimerType tt, const std::string &timerName) const {
434  if (timingOn_) timerOut_->start(tt, timerName); }
435 
438  inline void timerStart(TimerType tt, const char *timerName, int num,
439  int fieldWidth=0) const {
440  if (timingOn_){
441  std::ostringstream oss;
442  oss << timerName << " ";
443  if (fieldWidth > 0){
444  oss.width(fieldWidth);
445  oss.fill('0');
446  }
447  oss << num;
448  timerOut_->start(tt, oss.str());
449  }
450  }
451 
452  inline void timerStart(TimerType tt, const std::string &timerName, int num,
453  int fieldWidth=0) const {
454  if (timingOn_){
455  std::ostringstream oss;
456  oss << timerName << " ";
457  if (fieldWidth > 0){
458  oss.width(fieldWidth);
459  oss.fill('0');
460  }
461  oss << num;
462  timerOut_->start(tt, oss.str());
463  }
464  }
465 
469  inline void timerStop(TimerType tt, const char *timerName) const {
470  if (timingOn_) timerOut_->stop(tt, timerName); }
471 
472  inline void timerStop(TimerType tt, const std::string &timerName) const {
473  if (timingOn_) timerOut_->stop(tt, timerName); }
474 
478  inline void timerStop(TimerType tt, const char *timerName, int num,
479  int fieldWidth=0) const {
480  if (timingOn_){
481  std::ostringstream oss;
482  oss << timerName << " ";
483  if (fieldWidth > 0){
484  oss.width(fieldWidth);
485  oss.fill('0');
486  }
487  oss << num;
488  timerOut_->stop(tt, oss.str());
489  }
490  }
491 
492  inline void timerStop(TimerType tt, const std::string &timerName, int num,
493  int fieldWidth=0) const {
494  if (timingOn_){
495  std::ostringstream oss;
496  oss << timerName << " ";
497  if (fieldWidth > 0){
498  oss.width(fieldWidth);
499  oss.fill('0');
500  }
501  oss << num;
502  timerOut_->stop(tt, oss.str());
503  }
504  }
505 
506 #endif
507 
523 #ifdef Z2_OMIT_ALL_PROFILING
524  inline void memory(const char *msg) const {return;}
525 
526  inline void memory(const std::string &msg) const {return; }
527 #else
528  inline void memory(const char *msg) const
529  {if (memoryOn_)
530  memoryOut_->print(msg, getProcessKilobytes());}
531 
532  inline void memory(const std::string &msg) const
533  {if (memoryOn_)
534  memoryOut_->print(msg, getProcessKilobytes());}
535 #endif
536 
541  const Teuchos::ParameterList &getParameters() const { return params_; }
542 
547  Teuchos::ParameterList &getParametersNonConst() { return params_; }
548 
552  bool doTiming() const { return timingOn_; }
553 
557 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
558  inline bool doStatus() const { return false;}
559  inline MessageOutputLevel getDebugLevel() const {return NO_STATUS;}
560  inline std::ostream *getDebugOStream() const {return std::cout;}
561 #else
562  inline bool doStatus() const {
563  return (debugOut_->getDebugLevel() > NO_STATUS);
564  }
566  return debugOut_->getDebugLevel();
567  }
568  inline std::ostream *getDebugOStream() const {
569  return debugOut_->getOStream();
570  }
571 #endif
572 
576  bool doMemoryProfiling() const { return memoryOn_;}
577 
589  const Teuchos::ParameterList &getUnvalidatedParameters() const {
590  return unvalidatedParams_; }
591 
608  static void convertStringToInt(Teuchos::ParameterList &params);
609 
610 private:
611 
614  void commitParameters();
615 
620  Teuchos::ParameterList unvalidatedParams_;
621 
630  Teuchos::ParameterList params_;
631 
632  DebugManager_t debugOut_;
634  Timer_t timerOut_;
635  bool timingOn_;
636 
637  MemoryProfilerManager_t memoryOut_;
638  bool memoryOn_;
639  RCP<std::ofstream> memoryOutputFile_;
640 };
641 
645 #define Z2_UNSET_STRING std::string("notSet")
646 
648 // Templated namespace definitions used by the class
649 
662 template<typename metric_t>
663  void makeMetricOutputManager(int rank, bool iPrint,
664  std::string fname, int ost,
665  Teuchos::RCP<MetricOutputManager<metric_t> > &mgr,
666  std::string units, int fieldWidth,
667  RCP<std::ofstream> &fptr)
668 {
669  typedef MetricOutputManager<metric_t> manager_t;
670 
671  OSType os = static_cast<OSType>(ost);
672 
673  bool haveFname = (fname != Z2_UNSET_STRING);
674  bool haveStreamName = (os != NUM_OUTPUT_STREAMS);
675 
676  if (!haveFname && !haveStreamName){
677  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
678  units, fieldWidth));
679  return;
680  }
681 
682  if (haveFname){
683  std::ofstream *oFile = NULL;
684  if (iPrint){
685  oFile = new std::ofstream;
686  std::string newFname;
687  addNumberToFileName(rank, fname, newFname);
688  try{
689  oFile->open(newFname.c_str(), std::ios::out|std::ios::trunc);
690  }
691  catch(std::exception &e){
692  throw std::runtime_error(e.what());
693  }
694  fptr = rcp(oFile);
695  }
696  mgr = Teuchos::rcp(new manager_t(rank, iPrint, *oFile, true,
697  units, fieldWidth));
698  return;
699  }
700 
701  if (os == COUT_STREAM)
702  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
703  units, fieldWidth));
704  else if (os == CERR_STREAM)
705  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cerr, true,
706  units, fieldWidth));
707  else if (os == NULL_STREAM)
708  mgr = Teuchos::rcp(new manager_t(rank, false, std::cout, true,
709  units, fieldWidth));
710  else
711  throw std::logic_error("invalid metric output stream was not caught");
712 }
713 
714 } // namespace Zoltan2
715 
716 #endif
const Teuchos::ParameterList & getParameters() const
Returns a reference to the user&#39;s parameter list.
void globalMemoryAssertion(const char *file, int lineNum, size_t nobj, bool ok, const Comm_t &comm) const
Test for successful memory allocation on every process.
bool doStatus() const
Return true if debug output was requested, even if this process is not printing out debug messages...
void timerStop(TimerType tt, const char *timerName, int num, int fieldWidth=0) const
Stop a named timer, with a number as part of the name.
std::ostream * getDebugOStream() const
Defines the MetricOutputManager class.
void setTimer(RCP< TimerManager > &timer)
Provide the Timer object to the Environment.
MetricOutputManager handles output of profiling messages.
void timerStart(TimerType tt, const char *timerName, int num, int fieldWidth=0) const
Start a named timer, with a number as part of the name.
void localInputAssertion(const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
Test for valid user input on local process only.
MessageOutputLevel
The amount of debugging or status output to print.
Defines Parameter related enumerators, declares functions.
static RCP< Teuchos::BoolParameterEntryValidator > getBoolValidator()
Exists to make setting up validators less cluttered.
Environment(Teuchos::ParameterList &problemParams, const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
Constructor.
static void convertStringToInt(Teuchos::ParameterList &params)
Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator&lt;int&gt; to integer...
void makeMetricOutputManager(int rank, bool iPrint, std::string fname, int ost, Teuchos::RCP< MetricOutputManager< metric_t > > &mgr, std::string units, int fieldWidth, RCP< std::ofstream > &fptr)
Create an output manager for a metric value.
Debug output manager for Zoltan2.
TimerType
The type of timers which should be active.
void localMemoryAssertion(const char *file, int lineNum, size_t nobj, bool ok) const
Test for successful memory allocation on local process only.
/dev/null: do actions but don&#39;t output results
static RCP< Teuchos::AnyNumberParameterEntryValidator > getAnyDoubleValidator()
Exists to make setting up validators less cluttered.
void globalBugAssertion(const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level, const Comm_t &comm) const
Test for valid library behavior on every process.
Teuchos::RCP< const Teuchos::Comm< int > > Comm_t
bool doMemoryProfiling() const
Return true if memory usage output was requested, even if this process is not printing out memory use...
long getProcessKilobytes()
void globalInputAssertion(const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level, const Comm_t &comm) const
Test globally for valid user input.
AssertionLevel
Level of error checking or assertions desired.
int numProcs_
number of processes (relative to comm_)
void debug(MessageOutputLevel level, const char *msg) const
Send a message to the debug output manager.
void timerStop(TimerType tt, const char *timerName) const
Stop a named timer.
Teuchos::ParameterList & getParametersNonConst()
Returns a reference to a non-const copy of the parameters.
Declaration of methods to assist in file input/output.
int myRank_
mpi rank (relative to comm_)
OSType
Output stream types.
void debug(int level, const char *msg) const
Comm_t comm_
communicator for environment
void debug(MessageOutputLevel level, const std::string &msg) const
Teuchos::RCP< MetricOutputManager< memory_t > > MemoryProfilerManager_t
const Teuchos::ParameterList & getUnvalidatedParameters() const
Returns a const reference to the user&#39;s original list.
don&#39;t display status/debug messages
void localBugAssertion(const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
Test for valid library behavior on local process only.
static void getValidParameters(ParameterList &pl)
Collect the paramaters specific to Environment.
void debug(int level, const std::string &msg) const
long memory_t
data type for Kilobytes
void addNumberToFileName(int number, std::string fname, std::string &newf)
Helper method to add number to a file name.
Definition: Zoltan2_IO.cpp:56
#define Z2_UNSET_STRING
A value to indicate a string parameter that was not set by the user.
void memory(const char *msg) const
Print a message and the kilobytes in use by this process.
The user parameters, debug, timing and memory profiling output objects, and error checking methods...
Teuchos::RCP< TimerManager > Timer_t
void resetParameters(Teuchos::ParameterList &problemParams)
resetParameters and validate them - preserve the comm
static RCP< Teuchos::AnyNumberParameterEntryValidator > getAnyIntValidator()
Exists to make setting up validators less cluttered.
static const std::string fail
void timerStop(TimerType tt, const std::string &timerName) const
MessageOutputLevel getDebugLevel() const
void timerStart(TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
void memory(const std::string &msg) const
void timerStop(TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
bool doTiming() const
Return true if timing was requested, even if this process is not printing out timing messages...
A gathering of useful namespace methods.
void timerStart(TimerType tt, const char *timerName) const
Start a named timer.
AssertionLevel errorCheckLevel_
level of error checking to do
Declarations for TimerManager.
void timerStart(TimerType tt, const std::string &timerName) const
Teuchos::RCP< DebugManager > DebugManager_t