Zoltan2
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes
Zoltan2::Environment Class Reference

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

#include <Zoltan2_Environment.hpp>

List of all members.

Public Types

typedef long memory_t
 data type for Kilobytes
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.
 Environment ()
 Default Constructor.
 ~Environment ()
 Destructor.
void setTimer (RCP< TimerManager > &timer)
 Provide the Timer object to the Environment.
void localInputAssertion (const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
 Test for valid user input on local process only.
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 localBugAssertion (const char *file, int lineNum, const char *msg, bool ok, AssertionLevel level) const
 Test for valid library behavior on local process only.
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 localMemoryAssertion (const char *file, int lineNum, size_t nobj, bool ok) const
 Test for successful memory allocation on local process only.
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.
void debug (MessageOutputLevel level, const char *msg) const
 Send a message to the debug output manager.
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.
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.
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.
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.
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.
void memory (const std::string &msg) const
const Teuchos::ParameterList & getParameters () const
 Returns a reference to the user's parameter list.
Teuchos::ParameterList & getParametersNonConst ()
 Returns a reference to a non-const copy of the parameters.
bool doTiming () const
 Return true if timing was requested, even if this process is not printing out timing messages.
bool doStatus () const
 Return true if debug output was requested, even if this process is not printing out debug messages.
MessageOutputLevel getDebugLevel () const
bool doMemoryProfiling () const
 Return true if memory usage output was requested, even if this process is not printing out memory used messages.
const Teuchos::ParameterList & getUnvalidatedParameters () const
 Returns a const reference to the user's original list.

Static Public Member Functions

static void convertStringToInt (Teuchos::ParameterList &params)
 Convert parameters of type Teuchos::StringToIntegralParameterEntryValidator<int> to integer.

Public Attributes

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

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 82 of file Zoltan2_Environment.hpp.


Member Typedef Documentation

data type for Kilobytes

Definition at line 86 of file Zoltan2_Environment.hpp.

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

Definition at line 88 of file Zoltan2_Environment.hpp.

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.


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

Note that the communicator is for the application, not the problem.

Definition at line 112 of file Zoltan2_Environment.cpp.

Zoltan2::Environment::Environment ( )

Default Constructor.

The default constructor uses the Teuchos default communicator, BASIC_STATUS for debug_level, and does not timing or memory profiling. It has error_check_level BASIC_ASSERTION. It has no other parameters.

Definition at line 126 of file Zoltan2_Environment.cpp.

Zoltan2::Environment::~Environment ( )

Destructor.

Definition at line 142 of file Zoltan2_Environment.cpp.


Member Function Documentation

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 130 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 169 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 196 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 236 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 269 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 304 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 329 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 369 of file Zoltan2_Environment.hpp.

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

Definition at line 373 of file Zoltan2_Environment.hpp.

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

Definition at line 377 of file Zoltan2_Environment.hpp.

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

Definition at line 382 of file Zoltan2_Environment.hpp.

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

Start a named timer.

Definition at line 408 of file Zoltan2_Environment.hpp.

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

Definition at line 411 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 416 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 430 of file Zoltan2_Environment.hpp.

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

Stop a named timer.

Definition at line 447 of file Zoltan2_Environment.hpp.

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

Definition at line 450 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 456 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 470 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 506 of file Zoltan2_Environment.hpp.

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

Definition at line 510 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 519 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 525 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 530 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 539 of file Zoltan2_Environment.hpp.

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

Definition at line 541 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 547 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 560 of file Zoltan2_Environment.hpp.

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

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

Parameters:
paramson input, a list of parameter, on return, all of the StringToIntegral parameters have been converted to integer 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.

Definition at line 281 of file Zoltan2_Environment.cpp.


Member Data Documentation

mpi rank (relative to comm_)

Definition at line 93 of file Zoltan2_Environment.hpp.

number of processes (relative to comm_)

Definition at line 95 of file Zoltan2_Environment.hpp.

communicator for environment

Definition at line 97 of file Zoltan2_Environment.hpp.

level of error checking to do

Definition at line 99 of file Zoltan2_Environment.hpp.


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