Zoltan2
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 
67 namespace Zoltan2 {
68 
83 
84 public:
85 
86  typedef long memory_t;
88  typedef Teuchos::RCP<const Teuchos::Comm<int> > Comm_t;
89  typedef Teuchos::RCP<DebugManager> DebugManager_t;
90  typedef Teuchos::RCP<MetricOutputManager<memory_t> > MemoryProfilerManager_t;
91  typedef Teuchos::RCP<TimerManager> Timer_t;
92 
93  int myRank_;
95  int numProcs_;
97  Comm_t comm_;
109  Environment(Teuchos::ParameterList &problemParams,
110  const Teuchos::RCP<const Teuchos::Comm<int> > &comm );
111 
118  Environment();
119 
122  ~Environment();
123 
130  void setTimer(RCP<TimerManager> &timer) { timerOut_=timer; timingOn_=true;}
131 
132 #ifdef Z2_OMIT_ALL_ERROR_CHECKING
133 
134  void localInputAssertion(const char *file, int lineNum,
135  const char *msg, bool ok, AssertionLevel level) const {}
136 
137  void globalInputAssertion(const char *file, int lineNum,
138  const char *msg, bool ok, AssertionLevel level,
139  const Comm_t &comm=comm_) const {}
140 
141  void localBugAssertion(const char *file, int lineNum,
142  const char *msg, bool ok, AssertionLevel level) const {}
143 
144  void globalBugAssertion(const char *file, int lineNum,
145  const char *msg, bool ok, AssertionLevel level,
146  const Comm_t &comm=comm_) const {}
147 
148  void localMemoryAssertion(const char *file, int lineNum,
149  size_t nobj, bool ok) const {}
150 
151  void globalMemoryAssertion(const char *file, int lineNum,
152  size_t nobj, bool ok, const Comm_t &comm=comm_) const {}
153 
154 #else
155 
169  void localInputAssertion(const char *file, int lineNum,
170  const char *msg, bool ok, AssertionLevel level) const {
171 
172  if (level <= errorCheckLevel_ && !ok){
173  std::ostringstream emsg;
174  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
175  if (msg)
176  emsg << myRank_ << ": error: " << msg << std::endl;
177  throw std::runtime_error(emsg.str());
178  }
179  }
196  void globalInputAssertion(const char *file, int lineNum,
197  const char *msg, bool ok, AssertionLevel level,
198  const Comm_t &comm) const {
199 
200  if (level <= errorCheckLevel_){
201  int anyFail=0, fail = (!ok ? 1 : 0);
202  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
203  &anyFail);
204  if (anyFail > 0){
205  std::ostringstream emsg;
206  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
207  if (msg && !ok)
208  emsg << myRank_ << ": error: " << msg << std::endl;
209  else
210  emsg << myRank_ << ": exiting" << std::endl;
211 
212  throw std::runtime_error(emsg.str());
213  }
214  }
215  }
216 
236  void localBugAssertion(const char *file, int lineNum,
237  const char *msg, bool ok, AssertionLevel level) const {
238 
239  if (level <= errorCheckLevel_ && !ok){
240  std::ostringstream emsg;
241  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
242  if (msg)
243  emsg << myRank_ << ": bug: " << msg << std::endl;
244  throw std::logic_error(emsg.str());
245  }
246  }
247 
269  void globalBugAssertion(const char *file, int lineNum,
270  const char *msg, bool ok, AssertionLevel level,
271  const Comm_t &comm) const {
272 
273  if (level <= errorCheckLevel_){
274  int anyFail=0, fail = (!ok ? 1 : 0);
275  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
276  &anyFail);
277  if (anyFail > 0){
278 
279  std::ostringstream emsg;
280  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
281  if (msg && !ok)
282  emsg << myRank_ << ": bug: " << msg << std::endl;
283  else
284  emsg << myRank_ << ": exiting" << std::endl;
285 
286  throw std::logic_error(emsg.str());
287  }
288  }
289  }
290 
304  void localMemoryAssertion(const char *file, int lineNum, size_t nobj,
305  bool ok) const {
306 
307  if (!ok){
308  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
309  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
310  throw std::bad_alloc();
311  }
312  }
313 
329  void globalMemoryAssertion(const char *file, int lineNum,
330  size_t nobj, bool ok, const Comm_t &comm) const {
331 
332  int anyFail=0, fail = (!ok ? 1 : 0);
333  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail, &anyFail);
334  if (anyFail > 0){
335  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
336  if (!ok)
337  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
338  else
339  std::cerr << myRank_ << ": exiting" << std::endl;
340 
341  throw std::bad_alloc();
342  }
343  }
344 #endif
345 
346  // For debugging and profiling output, we define "char *" versions
347  // as well as "string" versions to avoid runtime conversion of "char *"
348  // to "string".
349 
361 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
362  inline void debug(MessageOutputLevel level, const char *msg) const{ return;}
363  inline void debug(MessageOutputLevel level, const std::string& msg) const{
364  return;
365  }
366  inline void debug(int level, const char *msg) const{ return;}
367  inline void debug(int level, const std::string& msg) const{ return;}
368 #else
369  inline void debug(MessageOutputLevel level, const char *msg) const{
370  debugOut_->print(level, msg);
371  }
372 
373  inline void debug(MessageOutputLevel level, const std::string& msg) const{
374  debugOut_->print(level, msg);
375  }
376 
377  inline void debug(int level, const char *msg) const{
378  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
379  debugOut_->print(msg_enum, msg);
380  }
381 
382  inline void debug(int level, const std::string& msg) const{
383  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
384  debugOut_->print(msg_enum, msg);
385  }
386 #endif
387 
388 #ifdef Z2_OMIT_ALL_PROFILING
389 
390  void timerStart(TimerType tt, const char * timerName) const {return;}
391  void timerStart(TimerType tt, const std::string &timerName) const {return;}
392  void timerStart(TimerType tt, const char * timerName, int,
393  int fieldWidth=0) const {return;}
394  void timerStart(TimerType tt, const std::string &timerName, int,
395  int fieldWidth=0) const {return;}
396 
397  void timerStop(TimerType tt, const char * timerName) const {return;}
398  void timerStop(TimerType tt, const std::string &timerName) const {return;}
399  void timerStop(TimerType tt, const char * timerName, int,
400  int fieldWidth=0) const {return;}
401  void timerStop(TimerType tt, const std::string &timerName, int,
402  int fieldWidth=0) const {return;}
403 
404 #else
405 
408  void timerStart(TimerType tt, const char *timerName) const {
409  if (timingOn_) timerOut_->start(tt, timerName); }
410 
411  void timerStart(TimerType tt, const std::string &timerName) const {
412  if (timingOn_) timerOut_->start(tt, timerName); }
413 
416  void timerStart(TimerType tt, const char *timerName, int num,
417  int fieldWidth=0) const {
418  if (timingOn_){
419  std::ostringstream oss;
420  oss << timerName << " ";
421  if (fieldWidth > 0){
422  oss.width(fieldWidth);
423  oss.fill('0');
424  }
425  oss << num;
426  timerOut_->start(tt, oss.str());
427  }
428  }
429 
430  void timerStart(TimerType tt, const std::string &timerName, int num,
431  int fieldWidth=0) const {
432  if (timingOn_){
433  std::ostringstream oss;
434  oss << timerName << " ";
435  if (fieldWidth > 0){
436  oss.width(fieldWidth);
437  oss.fill('0');
438  }
439  oss << num;
440  timerOut_->start(tt, oss.str());
441  }
442  }
443 
447  void timerStop(TimerType tt, const char *timerName) const {
448  if (timingOn_) timerOut_->stop(tt, timerName); }
449 
450  void timerStop(TimerType tt, const std::string &timerName) const {
451  if (timingOn_) timerOut_->stop(tt, timerName); }
452 
456  void timerStop(TimerType tt, const char *timerName, int num,
457  int fieldWidth=0) const {
458  if (timingOn_){
459  std::ostringstream oss;
460  oss << timerName << " ";
461  if (fieldWidth > 0){
462  oss.width(fieldWidth);
463  oss.fill('0');
464  }
465  oss << num;
466  timerOut_->stop(tt, oss.str());
467  }
468  }
469 
470  void timerStop(TimerType tt, const std::string &timerName, int num,
471  int fieldWidth=0) const {
472  if (timingOn_){
473  std::ostringstream oss;
474  oss << timerName << " ";
475  if (fieldWidth > 0){
476  oss.width(fieldWidth);
477  oss.fill('0');
478  }
479  oss << num;
480  timerOut_->stop(tt, oss.str());
481  }
482  }
483 
484 #endif
485 
501 #ifdef Z2_OMIT_ALL_PROFILING
502  void memory(const char *msg) const {return;}
503 
504  void memory(const std::string &msg) const {return; }
505 #else
506  void memory(const char *msg) const
507  {if (memoryOn_)
508  memoryOut_->print(msg, getProcessKilobytes());}
509 
510  void memory(const std::string &msg) const
511  {if (memoryOn_)
512  memoryOut_->print(msg, getProcessKilobytes());}
513 #endif
514 
519  const Teuchos::ParameterList &getParameters() const { return params_; }
520 
525  Teuchos::ParameterList &getParametersNonConst() { return params_; }
526 
530  bool doTiming() const { return timingOn_; }
531 
535 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
536  inline bool doStatus() const { return false;}
537  inline MessageOutputLevel getDebugLevel() const {return NO_STATUS;}
538  inline std::ostream *getDebugOStream() const {return std::cout;}
539 #else
540  inline bool doStatus() const {
541  return (debugOut_->getDebugLevel() > NO_STATUS);
542  }
544  return debugOut_->getDebugLevel();
545  }
546  inline std::ostream *getDebugOStream() const {
547  return debugOut_->getOStream();
548  }
549 #endif
550 
554  bool doMemoryProfiling() const { return memoryOn_;}
555 
567  const Teuchos::ParameterList &getUnvalidatedParameters() const {
568  return unvalidatedParams_; }
569 
583  static void convertStringToInt(Teuchos::ParameterList &params);
584 
585 private:
586 
589  void commitParameters();
590 
595  Teuchos::ParameterList unvalidatedParams_;
596 
605  Teuchos::ParameterList params_;
606 
607  DebugManager_t debugOut_;
609  Timer_t timerOut_;
610  bool timingOn_;
611 
612  MemoryProfilerManager_t memoryOut_;
613  bool memoryOn_;
614  RCP<std::ofstream> memoryOutputFile_;
615 };
616 
620 #define Z2_UNSET_STRING std::string("notSet")
621 
623 // Templated namespace definitions used by the class
624 
637 template<typename metric_t>
638  void makeMetricOutputManager(int rank, bool iPrint,
639  std::string fname, int ost,
640  Teuchos::RCP<MetricOutputManager<metric_t> > &mgr,
641  std::string units, int fieldWidth,
642  RCP<std::ofstream> &fptr)
643 {
644  typedef MetricOutputManager<metric_t> manager_t;
645 
646  OSType os = static_cast<OSType>(ost);
647 
648  bool haveFname = (fname != Z2_UNSET_STRING);
649  bool haveStreamName = (os != NUM_OUTPUT_STREAMS);
650 
651  if (!haveFname && !haveStreamName){
652  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
653  units, fieldWidth));
654  return;
655  }
656 
657  if (haveFname){
658  std::ofstream *oFile = NULL;
659  if (iPrint){
660  oFile = new std::ofstream;
661  std::string newFname;
662  addNumberToFileName(rank, fname, newFname);
663  try{
664  oFile->open(newFname.c_str(), std::ios::out|std::ios::trunc);
665  }
666  catch(std::exception &e){
667  throw std::runtime_error(e.what());
668  }
669  fptr = rcp(oFile);
670  }
671  mgr = Teuchos::rcp(new manager_t(rank, iPrint, *oFile, true,
672  units, fieldWidth));
673  return;
674  }
675 
676  if (os == COUT_STREAM)
677  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
678  units, fieldWidth));
679  else if (os == CERR_STREAM)
680  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cerr, true,
681  units, fieldWidth));
682  else if (os == NULL_STREAM)
683  mgr = Teuchos::rcp(new manager_t(rank, false, std::cout, true,
684  units, fieldWidth));
685  else
686  throw std::logic_error("invalid metric output stream was not caught");
687 }
688 
689 } // namespace Zoltan2
690 
691 #endif
Environment()
Default Constructor.
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 void convertStringToInt(Teuchos::ParameterList &params)
Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator<int> 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
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.
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
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