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...

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

Member Typedef Documentation

typedef long Zoltan2::Environment::memory_t

data type for Kilobytes

Definition at line 51 of file Zoltan2_Environment.hpp.

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

Definition at line 53 of file Zoltan2_Environment.hpp.

typedef Teuchos::RCP<DebugManager> Zoltan2::Environment::DebugManager_t

Definition at line 54 of file Zoltan2_Environment.hpp.

typedef Teuchos::RCP<MetricOutputManager<memory_t> > Zoltan2::Environment::MemoryProfilerManager_t

Definition at line 55 of file Zoltan2_Environment.hpp.

typedef Teuchos::RCP<TimerManager> Zoltan2::Environment::Timer_t

Definition at line 56 of file Zoltan2_Environment.hpp.

Constructor & Destructor Documentation

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

Constructor.

Parameters

problemParams	the parameters supplied by the user, and not yet validated by the Environment
comm	the default communicator for the application

Definition at line 77 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

comm	the default communicator for the application

Definition at line 91 of file Zoltan2_Environment.cpp.

Zoltan2::Environment::~Environment ( )

Destructor.

Definition at line 104 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 110 of file Zoltan2_Environment.cpp.

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

static

Collect the paramaters specific to Environment.

Definition at line 144 of file Zoltan2_Environment.cpp.

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

static

Exists to make setting up validators less cluttered.

Definition at line 116 of file Zoltan2_Environment.cpp.

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

static

Exists to make setting up validators less cluttered.

Definition at line 123 of file Zoltan2_Environment.cpp.

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

static

Exists to make setting up validators less cluttered.

Definition at line 134 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 116 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
msg	an optional descriptive message
ok	a boolean which if false indicates an error
level	a 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 155 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
msg	an optional descriptive message
ok	a boolean which if false indicates an error
level	a AssertionLevel value
comm	a 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 182 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
msg	an optional descriptive message
ok	a boolean which if false indicates an error
level	a 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 222 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
msg	an optional descriptive message
ok	a boolean which if false indicates an error
level	a AssertionLevel value
comm	a 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 255 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
nobj	a value indicating the amount of memory wanted
ok	a 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 290 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

file	the FILE value of the caller.
lineNum	the LINE value of the caller.
nobj	a value indicating the amount of memory wanted
ok	a boolean which if false indicates failure
comm	a 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 315 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

level	If `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`.
msg	The message to be output.

Definition at line 355 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 359 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 363 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 368 of file Zoltan2_Environment.hpp.

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

inline

Start a named timer.

Definition at line 394 of file Zoltan2_Environment.hpp.

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

inline

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

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

inline

Stop a named timer.

Definition at line 433 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 436 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 442 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 456 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

msg The 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 492 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 496 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 505 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 511 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 516 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 526 of file Zoltan2_Environment.hpp.

MessageOutputLevel Zoltan2::Environment::getDebugLevel ( ) const

inline

Definition at line 529 of file Zoltan2_Environment.hpp.

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

inline

Definition at line 532 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 540 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 553 of file Zoltan2_Environment.hpp.

Member Data Documentation

int Zoltan2::Environment::myRank_

mpi rank (relative to comm_)

Definition at line 58 of file Zoltan2_Environment.hpp.

int Zoltan2::Environment::numProcs_

number of processes (relative to comm_)

Definition at line 60 of file Zoltan2_Environment.hpp.

Comm_t Zoltan2::Environment::comm_

communicator for environment

Definition at line 62 of file Zoltan2_Environment.hpp.

AssertionLevel Zoltan2::Environment::errorCheckLevel_

level of error checking to do

Definition at line 64 of file Zoltan2_Environment.hpp.

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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation