Zoltan2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
Zoltan2::Environment Class Reference

The user parameters, debug, timing and memory profiling output objects, and error checking methods. More...

#include <Zoltan2_Environment.hpp>

Public Types

typedef long memory_t
 data type for Kilobytes More...
 
typedef Teuchos::RCP< const
Teuchos::Comm< int > > 
Comm_t
 
typedef Teuchos::RCP
< DebugManager
DebugManager_t
 
typedef Teuchos::RCP
< MetricOutputManager
< memory_t > > 
MemoryProfilerManager_t
 
typedef Teuchos::RCP
< TimerManager
Timer_t
 

Public Member Functions

 Environment (Teuchos::ParameterList &problemParams, const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
 Constructor. More...
 
 Environment (const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
 Constructor. More...
 
 ~Environment ()
 Destructor. More...
 
void resetParameters (Teuchos::ParameterList &problemParams)
 resetParameters and validate them - preserve the comm More...
 
void setTimer (RCP< TimerManager > &timer)
 Provide the Timer object to the Environment. More...
 
void localInputAssertion (const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
 Test for valid user input on local process only. More...
 
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. More...
 
void localBugAssertion (const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
 Test for valid library behavior on local process only. More...
 
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. More...
 
void localMemoryAssertion (const char *file, int lineNum, size_t nobj, bool ok) const
 Test for successful memory allocation on local process only. More...
 
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. More...
 
void debug (MessageOutputLevel level, const char *msg) const
 Send a message to the debug output manager. More...
 
void debug (MessageOutputLevel level, const std::string &msg) const
 
void debug (int level, const char *msg) const
 
void debug (int level, const std::string &msg) const
 
void timerStart (TimerType tt, const char *timerName) const
 Start a named timer. More...
 
void timerStart (TimerType tt, const std::string &timerName) const
 
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. More...
 
void timerStart (TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
 
void timerStop (TimerType tt, const char *timerName) const
 Stop a named timer. More...
 
void timerStop (TimerType tt, const std::string &timerName) const
 
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. More...
 
void timerStop (TimerType tt, const std::string &timerName, int num, int fieldWidth=0) const
 
void memory (const char *msg) const
 Print a message and the kilobytes in use by this process. More...
 
void memory (const std::string &msg) const
 
const Teuchos::ParameterList & getParameters () const
 Returns a reference to the user's parameter list. More...
 
Teuchos::ParameterList & getParametersNonConst ()
 Returns a reference to a non-const copy of the parameters. More...
 
bool doTiming () const
 Return true if timing was requested, even if this process is not printing out timing messages. More...
 
bool doStatus () const
 Return true if debug output was requested, even if this process is not printing out debug messages. More...
 
MessageOutputLevel getDebugLevel () const
 
std::ostream * getDebugOStream () const
 
bool doMemoryProfiling () const
 Return true if memory usage output was requested, even if this process is not printing out memory used messages. More...
 
const Teuchos::ParameterList & getUnvalidatedParameters () const
 Returns a const reference to the user's original list. More...
 

Static Public Member Functions

static void getValidParameters (ParameterList &pl)
 Collect the paramaters specific to Environment. More...
 
static RCP
< Teuchos::BoolParameterEntryValidator > 
getBoolValidator ()
 Exists to make setting up validators less cluttered. More...
 
static RCP
< Teuchos::AnyNumberParameterEntryValidator > 
getAnyDoubleValidator ()
 Exists to make setting up validators less cluttered. More...
 
static RCP
< Teuchos::AnyNumberParameterEntryValidator > 
getAnyIntValidator ()
 Exists to make setting up validators less cluttered. More...
 
static void convertStringToInt (Teuchos::ParameterList &params)
 Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator<int> to integer. More...
 

Public Attributes

int myRank_
 mpi rank (relative to comm_) More...
 
int numProcs_
 number of processes (relative to comm_) More...
 
Comm_t comm_
 communicator for environment More...
 
AssertionLevel errorCheckLevel_
 level of error checking to do More...
 

Detailed Description

The user parameters, debug, timing and memory profiling output objects, and error checking methods.

This is object is passed to almost every method in the library. It has the problem parameters and the configuration information that governs how the library should behave when reporting status information, testing for errors, and so on.

The environment holds the application's default communicator. Note that this communicator may differ from the problem communicator for any given problem.

Definition at line 83 of file Zoltan2_Environment.hpp.

Member Typedef Documentation

data type for Kilobytes

Definition at line 87 of file Zoltan2_Environment.hpp.

typedef Teuchos::RCP<const Teuchos::Comm<int> > Zoltan2::Environment::Comm_t

Definition at line 89 of file Zoltan2_Environment.hpp.

Definition at line 90 of file Zoltan2_Environment.hpp.

Definition at line 91 of file Zoltan2_Environment.hpp.

Definition at line 92 of file Zoltan2_Environment.hpp.

Constructor & Destructor Documentation

Zoltan2::Environment::Environment ( Teuchos::ParameterList &  problemParams,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm 
)

Constructor.

Parameters
problemParamsthe parameters supplied by the user, and not yet validated by the Environment
commthe default communicator for the application

Definition at line 112 of file Zoltan2_Environment.cpp.

Zoltan2::Environment::Environment ( const Teuchos::RCP< const Teuchos::Comm< int > > &  comm)

Constructor.

This constructor does not take a Parameter list, BASIC_STATUS for debug_level, and does not timing or memory profiling. It has error_check_level BASIC_ASSERTION. It has no other parameters.

Parameters
commthe default communicator for the application

Definition at line 126 of file Zoltan2_Environment.cpp.

Zoltan2::Environment::~Environment ( )

Destructor.

Definition at line 139 of file Zoltan2_Environment.cpp.

Member Function Documentation

void Zoltan2::Environment::resetParameters ( Teuchos::ParameterList &  problemParams)

resetParameters and validate them - preserve the comm

Definition at line 145 of file Zoltan2_Environment.cpp.

void Zoltan2::Environment::getValidParameters ( ParameterList &  pl)
static

Collect the paramaters specific to Environment.

Definition at line 179 of file Zoltan2_Environment.cpp.

RCP< Teuchos::BoolParameterEntryValidator > Zoltan2::Environment::getBoolValidator ( )
static

Exists to make setting up validators less cluttered.

Definition at line 151 of file Zoltan2_Environment.cpp.

RCP< Teuchos::AnyNumberParameterEntryValidator > Zoltan2::Environment::getAnyDoubleValidator ( )
static

Exists to make setting up validators less cluttered.

Definition at line 158 of file Zoltan2_Environment.cpp.

RCP< Teuchos::AnyNumberParameterEntryValidator > Zoltan2::Environment::getAnyIntValidator ( )
static

Exists to make setting up validators less cluttered.

Definition at line 169 of file Zoltan2_Environment.cpp.

void Zoltan2::Environment::setTimer ( RCP< TimerManager > &  timer)
inline

Provide the Timer object to the Environment.

Having a Timer implies that the user asked for for timing. The Problem creates and holds the Timer.

Definition at line 152 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::localInputAssertion ( const char *  file,
int  lineNum,
const char *  msg,
bool  ok,
AssertionLevel  level 
) const
inline

Test for valid user input on local process only.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
msgan optional descriptive message
oka boolean which if false indicates an error
levela AssertionLevel value

If the level does not exceed the error_check_level parameter set by the user, then the assertion is tested and a std::runtime error is thrown if it is false.

Definition at line 191 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::globalInputAssertion ( const char *  file,
int  lineNum,
const char *  msg,
bool  ok,
AssertionLevel  level,
const Comm_t comm 
) const
inline

Test globally for valid user input.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
msgan optional descriptive message
oka boolean which if false indicates an error
levela AssertionLevel value
comma RCP<const Comm<int> > for the global check, if not specified we use the Environment's communicator.

If the level does not exceed the error_check_level parameter set by the user, then the assertion is tested on all processes in the comm. If it fails on any process a std::runtime error is thrown.

Definition at line 218 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::localBugAssertion ( const char *  file,
int  lineNum,
const char *  msg,
bool  ok,
AssertionLevel  level 
) const
inline

Test for valid library behavior on local process only.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
msgan optional descriptive message
oka boolean which if false indicates an error
levela AssertionLevel value

If the level does not exceed the error_check_level parameter set by the user, then the assertion is tested and a std::logic_error error is thrown if it is false.

A failure of this test indicates a bug in Zoltan2. Because of this consider doing these tests at the level of COMPLEX_ASSERTION, so they they only get checked when we specifically ask for this higher level of checking. An exception would be a test that is unlikely to be executed (the default in a switch for example).

Definition at line 258 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::globalBugAssertion ( const char *  file,
int  lineNum,
const char *  msg,
bool  ok,
AssertionLevel  level,
const Comm_t comm 
) const
inline

Test for valid library behavior on every process.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
msgan optional descriptive message
oka boolean which if false indicates an error
levela AssertionLevel value
comma RCP<const Comm<int> > for the global check, if not specified we use the Environment's communicator.

If the level does not exceed the error_check_level parameter set by the user, then the assertion is tested and a std::logic_error error is thrown if it is false on any process.

A failure of this test indicates a bug in Zoltan2. Because of this consider doing these tests at the level of COMPLEX_ASSERTION, so they they only get checked when we specifically ask for this higher level of checking. An exception would be a test that is unlikely to be executed (the default in a switch for example).

Definition at line 291 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::localMemoryAssertion ( const char *  file,
int  lineNum,
size_t  nobj,
bool  ok 
) const
inline

Test for successful memory allocation on local process only.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
nobja value indicating the amount of memory wanted
oka boolean which if false indicates failure

If the assertion fails, we throw std::bad_alloc. There is no level to this macro because memory assertions are BASIC_ASSERTIONs. We always check for successful memory allocation unless compiled with -DZ2_OMIT_ALL_ERROR_CHECKING.

Definition at line 326 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::globalMemoryAssertion ( const char *  file,
int  lineNum,
size_t  nobj,
bool  ok,
const Comm_t comm 
) const
inline

Test for successful memory allocation on every process.

Parameters
filethe FILE value of the caller.
lineNumthe LINE value of the caller.
nobja value indicating the amount of memory wanted
oka boolean which if false indicates failure
comma RCP<const Comm<int> > for the global check, if not specified we use the Environment's communicator.

If the assertion fails anywhere, we throw std::bad_alloc. There is no level to this macro because memory assertions are BASIC_ASSERTIONs. We always check for successful memory allocation unless compiled with -DZ2_OMIT_ALL_ERROR_CHECKING.

Definition at line 351 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::debug ( MessageOutputLevel  level,
const char *  msg 
) const
inline

Send a message to the debug output manager.

Parameters
levelIf level does not exceed the debug_level parameter set by the user, then if this process is one that prints debug messages (as indicated by the parameter debug_profiling_procs) then the msg will be output to either debug_output_stream or debug_output_file.
msgThe message to be output.

Definition at line 391 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::debug ( MessageOutputLevel  level,
const std::string &  msg 
) const
inline

Definition at line 395 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::debug ( int  level,
const char *  msg 
) const
inline

Definition at line 399 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::debug ( int  level,
const std::string &  msg 
) const
inline

Definition at line 404 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStart ( TimerType  tt,
const char *  timerName 
) const
inline

Start a named timer.

Definition at line 430 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStart ( TimerType  tt,
const std::string &  timerName 
) const
inline

Definition at line 433 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStart ( TimerType  tt,
const char *  timerName,
int  num,
int  fieldWidth = 0 
) const
inline

Start a named timer, with a number as part of the name.

Definition at line 438 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStart ( TimerType  tt,
const std::string &  timerName,
int  num,
int  fieldWidth = 0 
) const
inline

Definition at line 452 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStop ( TimerType  tt,
const char *  timerName 
) const
inline

Stop a named timer.

Definition at line 469 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStop ( TimerType  tt,
const std::string &  timerName 
) const
inline

Definition at line 472 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStop ( TimerType  tt,
const char *  timerName,
int  num,
int  fieldWidth = 0 
) const
inline

Stop a named timer, with a number as part of the name.

Definition at line 478 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::timerStop ( TimerType  tt,
const std::string &  timerName,
int  num,
int  fieldWidth = 0 
) const
inline

Definition at line 492 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::memory ( const char *  msg) const
inline

Print a message and the kilobytes in use by this process.

Parameters
msgThe message to be output. If this process is one that prints memory profiling messages (as indicated by the parameter memory_procs), the msg (along with kilobytes currently allocated to this process) will issued. The output target is either the memory_output_stream or memory_output_file. If neither was set, it goes to std::cout.

Memory profiling is only supported on Linux nodes that have /proc/pid/statm. If this is an unsupported node, the call does nothing.

Definition at line 528 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::memory ( const std::string &  msg) const
inline

Definition at line 532 of file Zoltan2_Environment.hpp.

const Teuchos::ParameterList& Zoltan2::Environment::getParameters ( ) const
inline

Returns a reference to the user's parameter list.

This is the parameter list after validation and modification.

Definition at line 541 of file Zoltan2_Environment.hpp.

Teuchos::ParameterList& Zoltan2::Environment::getParametersNonConst ( )
inline

Returns a reference to a non-const copy of the parameters.

This is the parameter list after validation and modification.

Definition at line 547 of file Zoltan2_Environment.hpp.

bool Zoltan2::Environment::doTiming ( ) const
inline

Return true if timing was requested, even if this process is not printing out timing messages.

Definition at line 552 of file Zoltan2_Environment.hpp.

bool Zoltan2::Environment::doStatus ( ) const
inline

Return true if debug output was requested, even if this process is not printing out debug messages.

Definition at line 562 of file Zoltan2_Environment.hpp.

MessageOutputLevel Zoltan2::Environment::getDebugLevel ( ) const
inline

Definition at line 565 of file Zoltan2_Environment.hpp.

std::ostream* Zoltan2::Environment::getDebugOStream ( ) const
inline

Definition at line 568 of file Zoltan2_Environment.hpp.

bool Zoltan2::Environment::doMemoryProfiling ( ) const
inline

Return true if memory usage output was requested, even if this process is not printing out memory used messages.

Definition at line 576 of file Zoltan2_Environment.hpp.

const Teuchos::ParameterList& Zoltan2::Environment::getUnvalidatedParameters ( ) const
inline

Returns a const reference to the user's original list.

This is the parameter list before it was validated. It is not the version supplied to algorithms.

It is made available in case a Problem wants to create a new Environment by augmenting the user's original parameters. See PartitioningProblem::createPartitioningProblem() for an example of doing this.

Definition at line 589 of file Zoltan2_Environment.hpp.

void Zoltan2::Environment::convertStringToInt ( Teuchos::ParameterList &  params)
static

Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator<int> to integer.

Teuchos::StringToIntegralParameterEntryValidator<bool> to bool.

Parameters
paramson input, a list of parameter, on return, all of the StringToIntegral parameters have been converted to integer values or bool values.

Given a parameter list, this function converts all of the entries that have valiator of type StringToIntegralParameterEntryValidator<int> from their string value to their int value. Also StringToIntegralParameterEntryValidator<bool> to bool

Definition at line 423 of file Zoltan2_Environment.cpp.

Member Data Documentation

int Zoltan2::Environment::myRank_

mpi rank (relative to comm_)

Definition at line 94 of file Zoltan2_Environment.hpp.

int Zoltan2::Environment::numProcs_

number of processes (relative to comm_)

Definition at line 96 of file Zoltan2_Environment.hpp.

Comm_t Zoltan2::Environment::comm_

communicator for environment

Definition at line 98 of file Zoltan2_Environment.hpp.

AssertionLevel Zoltan2::Environment::errorCheckLevel_

level of error checking to do

Definition at line 100 of file Zoltan2_Environment.hpp.


The documentation for this class was generated from the following files: