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 #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_;
110  Environment(Teuchos::ParameterList &problemParams,
111  const Teuchos::RCP<const Teuchos::Comm<int> > &comm );
112 
119  Environment();
120 
123  ~Environment();
124 
127  static void getValidParameters(ParameterList & pl);
128 
131  static RCP<Teuchos::BoolParameterEntryValidator> getBoolValidator();
132 
135  static RCP<Teuchos::AnyNumberParameterEntryValidator>
137 
140  static RCP<Teuchos::AnyNumberParameterEntryValidator>
142 
149  void setTimer(RCP<TimerManager> &timer) { timerOut_=timer; timingOn_=true;}
150 
151 #ifdef Z2_OMIT_ALL_ERROR_CHECKING
152 
153  void localInputAssertion(const char *file, int lineNum,
154  const char *msg, bool ok, AssertionLevel level) const {}
155 
156  void globalInputAssertion(const char *file, int lineNum,
157  const char *msg, bool ok, AssertionLevel level,
158  const Comm_t &comm=comm_) const {}
159 
160  void localBugAssertion(const char *file, int lineNum,
161  const char *msg, bool ok, AssertionLevel level) const {}
162 
163  void globalBugAssertion(const char *file, int lineNum,
164  const char *msg, bool ok, AssertionLevel level,
165  const Comm_t &comm=comm_) const {}
166 
167  void localMemoryAssertion(const char *file, int lineNum,
168  size_t nobj, bool ok) const {}
169 
170  void globalMemoryAssertion(const char *file, int lineNum,
171  size_t nobj, bool ok, const Comm_t &comm=comm_) const {}
172 
173 #else
174 
188  void localInputAssertion(const char *file, int lineNum,
189  const char *msg, bool ok, AssertionLevel level) const {
190 
191  if (level <= errorCheckLevel_ && !ok){
192  std::ostringstream emsg;
193  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
194  if (msg)
195  emsg << myRank_ << ": error: " << msg << std::endl;
196  throw std::runtime_error(emsg.str());
197  }
198  }
215  void globalInputAssertion(const char *file, int lineNum,
216  const char *msg, bool ok, AssertionLevel level,
217  const Comm_t &comm) const {
218 
219  if (level <= errorCheckLevel_){
220  int anyFail=0, fail = (!ok ? 1 : 0);
221  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
222  &anyFail);
223  if (anyFail > 0){
224  std::ostringstream emsg;
225  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
226  if (msg && !ok)
227  emsg << myRank_ << ": error: " << msg << std::endl;
228  else
229  emsg << myRank_ << ": exiting" << std::endl;
230 
231  throw std::runtime_error(emsg.str());
232  }
233  }
234  }
235 
255  void localBugAssertion(const char *file, int lineNum,
256  const char *msg, bool ok, AssertionLevel level) const {
257 
258  if (level <= errorCheckLevel_ && !ok){
259  std::ostringstream emsg;
260  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
261  if (msg)
262  emsg << myRank_ << ": bug: " << msg << std::endl;
263  throw std::logic_error(emsg.str());
264  }
265  }
266 
288  void globalBugAssertion(const char *file, int lineNum,
289  const char *msg, bool ok, AssertionLevel level,
290  const Comm_t &comm) const {
291 
292  if (level <= errorCheckLevel_){
293  int anyFail=0, fail = (!ok ? 1 : 0);
294  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail,
295  &anyFail);
296  if (anyFail > 0){
297 
298  std::ostringstream emsg;
299  emsg << myRank_<< ": " << file << "," << lineNum<< std::endl;
300  if (msg && !ok)
301  emsg << myRank_ << ": bug: " << msg << std::endl;
302  else
303  emsg << myRank_ << ": exiting" << std::endl;
304 
305  throw std::logic_error(emsg.str());
306  }
307  }
308  }
309 
323  void localMemoryAssertion(const char *file, int lineNum, size_t nobj,
324  bool ok) const {
325 
326  if (!ok){
327  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
328  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
329  throw std::bad_alloc();
330  }
331  }
332 
348  void globalMemoryAssertion(const char *file, int lineNum,
349  size_t nobj, bool ok, const Comm_t &comm) const {
350 
351  int anyFail=0, fail = (!ok ? 1 : 0);
352  Teuchos::reduceAll<int,int>(*comm, Teuchos::REDUCE_MAX, 1, &fail, &anyFail);
353  if (anyFail > 0){
354  std::cerr << myRank_ << ": " << file << ", " << lineNum<< std::endl;
355  if (!ok)
356  std::cerr << myRank_ << ": " << nobj << " objects" << std::endl;
357  else
358  std::cerr << myRank_ << ": exiting" << std::endl;
359 
360  throw std::bad_alloc();
361  }
362  }
363 #endif
364 
365  // For debugging and profiling output, we define "char *" versions
366  // as well as "string" versions to avoid runtime conversion of "char *"
367  // to "string".
368 
380 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
381  inline void debug(MessageOutputLevel level, const char *msg) const{ return;}
382  inline void debug(MessageOutputLevel level, const std::string& msg) const{
383  return;
384  }
385  inline void debug(int level, const char *msg) const{ return;}
386  inline void debug(int level, const std::string& msg) const{ return;}
387 #else
388  inline void debug(MessageOutputLevel level, const char *msg) const{
389  debugOut_->print(level, msg);
390  }
391 
392  inline void debug(MessageOutputLevel level, const std::string& msg) const{
393  debugOut_->print(level, msg);
394  }
395 
396  inline void debug(int level, const char *msg) const{
397  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
398  debugOut_->print(msg_enum, msg);
399  }
400 
401  inline void debug(int level, const std::string& msg) const{
402  MessageOutputLevel msg_enum = static_cast<MessageOutputLevel>(level);
403  debugOut_->print(msg_enum, msg);
404  }
405 #endif
406 
407 #ifdef Z2_OMIT_ALL_PROFILING
408 
409  void timerStart(TimerType tt, const char * timerName) const {return;}
410  void timerStart(TimerType tt, const std::string &timerName) const {return;}
411  void timerStart(TimerType tt, const char * timerName, int,
412  int fieldWidth=0) const {return;}
413  void timerStart(TimerType tt, const std::string &timerName, int,
414  int fieldWidth=0) const {return;}
415 
416  void timerStop(TimerType tt, const char * timerName) const {return;}
417  void timerStop(TimerType tt, const std::string &timerName) const {return;}
418  void timerStop(TimerType tt, const char * timerName, int,
419  int fieldWidth=0) const {return;}
420  void timerStop(TimerType tt, const std::string &timerName, int,
421  int fieldWidth=0) const {return;}
422 
423 #else
424 
427  void timerStart(TimerType tt, const char *timerName) const {
428  if (timingOn_) timerOut_->start(tt, timerName); }
429 
430  void timerStart(TimerType tt, const std::string &timerName) const {
431  if (timingOn_) timerOut_->start(tt, timerName); }
432 
435  void timerStart(TimerType tt, const char *timerName, int num,
436  int fieldWidth=0) const {
437  if (timingOn_){
438  std::ostringstream oss;
439  oss << timerName << " ";
440  if (fieldWidth > 0){
441  oss.width(fieldWidth);
442  oss.fill('0');
443  }
444  oss << num;
445  timerOut_->start(tt, oss.str());
446  }
447  }
448 
449  void timerStart(TimerType tt, const std::string &timerName, int num,
450  int fieldWidth=0) const {
451  if (timingOn_){
452  std::ostringstream oss;
453  oss << timerName << " ";
454  if (fieldWidth > 0){
455  oss.width(fieldWidth);
456  oss.fill('0');
457  }
458  oss << num;
459  timerOut_->start(tt, oss.str());
460  }
461  }
462 
466  void timerStop(TimerType tt, const char *timerName) const {
467  if (timingOn_) timerOut_->stop(tt, timerName); }
468 
469  void timerStop(TimerType tt, const std::string &timerName) const {
470  if (timingOn_) timerOut_->stop(tt, timerName); }
471 
475  void timerStop(TimerType tt, const char *timerName, int num,
476  int fieldWidth=0) const {
477  if (timingOn_){
478  std::ostringstream oss;
479  oss << timerName << " ";
480  if (fieldWidth > 0){
481  oss.width(fieldWidth);
482  oss.fill('0');
483  }
484  oss << num;
485  timerOut_->stop(tt, oss.str());
486  }
487  }
488 
489  void timerStop(TimerType tt, const std::string &timerName, int num,
490  int fieldWidth=0) const {
491  if (timingOn_){
492  std::ostringstream oss;
493  oss << timerName << " ";
494  if (fieldWidth > 0){
495  oss.width(fieldWidth);
496  oss.fill('0');
497  }
498  oss << num;
499  timerOut_->stop(tt, oss.str());
500  }
501  }
502 
503 #endif
504 
520 #ifdef Z2_OMIT_ALL_PROFILING
521  void memory(const char *msg) const {return;}
522 
523  void memory(const std::string &msg) const {return; }
524 #else
525  void memory(const char *msg) const
526  {if (memoryOn_)
527  memoryOut_->print(msg, getProcessKilobytes());}
528 
529  void memory(const std::string &msg) const
530  {if (memoryOn_)
531  memoryOut_->print(msg, getProcessKilobytes());}
532 #endif
533 
538  const Teuchos::ParameterList &getParameters() const { return params_; }
539 
544  Teuchos::ParameterList &getParametersNonConst() { return params_; }
545 
549  bool doTiming() const { return timingOn_; }
550 
554 #ifdef Z2_OMIT_ALL_STATUS_MESSAGES
555  inline bool doStatus() const { return false;}
556  inline MessageOutputLevel getDebugLevel() const {return NO_STATUS;}
557  inline std::ostream *getDebugOStream() const {return std::cout;}
558 #else
559  inline bool doStatus() const {
560  return (debugOut_->getDebugLevel() > NO_STATUS);
561  }
563  return debugOut_->getDebugLevel();
564  }
565  inline std::ostream *getDebugOStream() const {
566  return debugOut_->getOStream();
567  }
568 #endif
569 
573  bool doMemoryProfiling() const { return memoryOn_;}
574 
586  const Teuchos::ParameterList &getUnvalidatedParameters() const {
587  return unvalidatedParams_; }
588 
605  static void convertStringToInt(Teuchos::ParameterList &params);
606 
607 private:
608 
611  void commitParameters();
612 
617  Teuchos::ParameterList unvalidatedParams_;
618 
627  Teuchos::ParameterList params_;
628 
629  DebugManager_t debugOut_;
631  Timer_t timerOut_;
632  bool timingOn_;
633 
634  MemoryProfilerManager_t memoryOut_;
635  bool memoryOn_;
636  RCP<std::ofstream> memoryOutputFile_;
637 };
638 
642 #define Z2_UNSET_STRING std::string("notSet")
643 
645 // Templated namespace definitions used by the class
646 
659 template<typename metric_t>
660  void makeMetricOutputManager(int rank, bool iPrint,
661  std::string fname, int ost,
662  Teuchos::RCP<MetricOutputManager<metric_t> > &mgr,
663  std::string units, int fieldWidth,
664  RCP<std::ofstream> &fptr)
665 {
666  typedef MetricOutputManager<metric_t> manager_t;
667 
668  OSType os = static_cast<OSType>(ost);
669 
670  bool haveFname = (fname != Z2_UNSET_STRING);
671  bool haveStreamName = (os != NUM_OUTPUT_STREAMS);
672 
673  if (!haveFname && !haveStreamName){
674  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
675  units, fieldWidth));
676  return;
677  }
678 
679  if (haveFname){
680  std::ofstream *oFile = NULL;
681  if (iPrint){
682  oFile = new std::ofstream;
683  std::string newFname;
684  addNumberToFileName(rank, fname, newFname);
685  try{
686  oFile->open(newFname.c_str(), std::ios::out|std::ios::trunc);
687  }
688  catch(std::exception &e){
689  throw std::runtime_error(e.what());
690  }
691  fptr = rcp(oFile);
692  }
693  mgr = Teuchos::rcp(new manager_t(rank, iPrint, *oFile, true,
694  units, fieldWidth));
695  return;
696  }
697 
698  if (os == COUT_STREAM)
699  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cout, true,
700  units, fieldWidth));
701  else if (os == CERR_STREAM)
702  mgr = Teuchos::rcp(new manager_t(rank, iPrint, std::cerr, true,
703  units, fieldWidth));
704  else if (os == NULL_STREAM)
705  mgr = Teuchos::rcp(new manager_t(rank, false, std::cout, true,
706  units, fieldWidth));
707  else
708  throw std::logic_error("invalid metric output stream was not caught");
709 }
710 
711 } // namespace Zoltan2
712 
713 #endif
Environment()
Default Constructor.
void memory(const char *msg) const
Print a message and the kilobytes in use by this process.
Defines the MetricOutputManager class.
void debug(int level, const std::string &msg) const
void timerStop(TimerType tt, const std::string &timerName) const
void setTimer(RCP< TimerManager > &timer)
Provide the Timer object to the Environment.
MetricOutputManager handles output of profiling messages.
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.
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.
void memory(const std::string &msg) const
static RCP< Teuchos::BoolParameterEntryValidator > getBoolValidator()
Exists to make setting up validators less cluttered.
static void convertStringToInt(Teuchos::ParameterList &params)
Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator<int> to integer...
MessageOutputLevel getDebugLevel() const
void timerStop(TimerType tt, const char *timerName) const
Stop a named timer.
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.
const Teuchos::ParameterList & getUnvalidatedParameters() const
Returns a const reference to the user&#39;s original list.
bool doMemoryProfiling() const
Return true if memory usage output was requested, even if this process is not printing out memory use...
Debug output manager for Zoltan2.
TimerType
The type of timers which should be active.
/dev/null: do actions but don&#39;t output results
void debug(MessageOutputLevel level, const char *msg) const
Send a message to the debug output manager.
void timerStart(TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
void timerStart(TimerType tt, const std::string &timerName) const
static RCP< Teuchos::AnyNumberParameterEntryValidator > getAnyDoubleValidator()
Exists to make setting up validators less cluttered.
Teuchos::RCP< const Teuchos::Comm< int > > Comm_t
long getProcessKilobytes()
AssertionLevel
Level of error checking or assertions desired.
std::ostream * getDebugOStream() const
int numProcs_
number of processes (relative to comm_)
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.
Comm_t comm_
communicator for environment
Teuchos::RCP< MetricOutputManager< memory_t > > MemoryProfilerManager_t
void localBugAssertion(const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
Test for valid library behavior on local process only.
don&#39;t display status/debug messages
static void getValidParameters(ParameterList &pl)
Collect the paramaters specific to Environment.
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.
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.
The user parameters, debug, timing and memory profiling output objects, and error checking methods...
Teuchos::RCP< TimerManager > Timer_t
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.
static RCP< Teuchos::AnyNumberParameterEntryValidator > getAnyIntValidator()
Exists to make setting up validators less cluttered.
static const std::string fail
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.
void debug(MessageOutputLevel level, const std::string &msg) const
void timerStart(TimerType tt, const char *timerName) const
Start a named timer.
void timerStop(TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
void debug(int level, const char *msg) 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.
const Teuchos::ParameterList & getParameters() const
Returns a reference to the user&#39;s parameter list.
bool doStatus() const
Return true if debug output was requested, even if this process is not printing out debug messages...
AssertionLevel errorCheckLevel_
level of error checking to do
void localMemoryAssertion(const char *file, int lineNum, size_t nobj, bool ok) const
Test for successful memory allocation on local process only.
Declarations for TimerManager.
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.
Teuchos::RCP< DebugManager > DebugManager_t