Sierra Toolkit Version of the Day
EnvDetail

Classes

class  sierra::Env::Startup
 Class Startup is a sentry class for starting the application. It ensures that the command line arguments, platform and MPI are ready to go at the start of the application. More...

Enumerations

enum  sierra::Env::ExecType {
  sierra::Env::EXEC_TYPE_WORLD = 0,
  sierra::Env::EXEC_TYPE_FLUID = 1,
  sierra::Env::EXEC_TYPE_LAG = 2,
  sierra::Env::EXEC_TYPE_PEER = 3
}
 Enumeration ExecutableType defines the known types of coordinated executables that operate with a sierra application. Unfortunately, this scheme for coordination is currently defined by Gemini whose implementation forces a limit of two executables, namely it and a fluid code. The startup_multi_exec() function handles the creation of groups which are contiguous processor groups, each with lead processor being the least ranked processor in the group. More...

Functions

bool sierra::Env::StartupSierra (int *argc, char ***argv, const char *product_name, const char *build_date_time, ExecType mpi_key=EXEC_TYPE_WORLD, const std::vector< int > *peer_sizes=NULL)
 Initialize MPI related operations for sierra, outputs banner, etc. returns 1 if MPI was initialized, 0 otherwise.
void sierra::Env::ShutDownSierra (bool mpiInitFlag)
void sierra::Env::reset (MPI_Comm mpi_comm)
 Function reset determines new parallel_size and parallel_rank. Flushes, closes, and reopens log files.
void sierra::Env::setMpiCommunicator (MPI_Comm communicator)
bool sierra::Env::is_comm_valid ()
const std::string & sierra::Env::get_param (const char *const option)
 Function query_env_param searches the command line options for the specified option. If not found, a const reference to an empty string is returned.
void sierra::Env::set_param (const char *option, const std::string &value)
 Member function set_param assigns the value to the parameter option.
const std::string & sierra::Env::product_name ()
 Function product_name returns the product's name. This name is used to query the product registry for information concerning this product.
bool sierra::Env::developer_mode ()
 Function developer_mode returns true if the.
void sierra::Env::set_input_file_required (bool value)
 Function set_input_file_required sets whether lack of an input file specification will automatically cause failure. The default behavior corresponds to true.
void sierra::Env::setInputFileName (std::string name)
std::string sierra::Env::getInputFileName ()
void sierra::Env::set_check_subcycle (bool value)
 Function set_check_subcycle sets whether to check input file for subcycling. The default behavior corresponds to false.
const std::string & sierra::Env::architecture ()
 Function architecture returns the platform executing this product. This is obtained during startup by searching for a file which contains this information.
const std::string & sierra::Env::executable_file ()
 Function executable_file returns the path of this executable file. information.
const std::string & sierra::Env::executable_date ()
 Function executable_date returns the build date of the executable file as a string in the form Mmm dd yyyy hh:mm::ss.
const std::string & sierra::Env::startup_date ()
 Function startup_date returns the startup date of this application execution.
double sierra::Env::start_time ()
 Function start_time returns the start time of this application execution.
double sierra::Env::wall_now ()
 Member function wall_now returns the epoch as a double precision value in seconds to "millisecond" accuracy.
double sierra::Env::cpu_now ()
 Member function cpu_now returns the accumlated cpu time for the process as a double precision value in seconds to "millisecond" accuracy.
double sierra::Env::vm_now ()
 Member function vm_now returns the virtual memory in use for the process as a double precision value in bytes.
const std::string sierra::Env::working_directory ()
 Function working_directory returns the current working directory of this application execution.
std::ostream & sierra::Env::output ()
 Function output returns the processor output log stream. This stream is connected via an mpi_filebuf to processor 0. Upon output_flush() the output from all processors is collected on processor 0 in a sequential by process and is logged to output file in a non-jumbled manner.
std::ostream & sierra::Env::outputP0 ()
 Function outputP0 returns the processor output log stream on processor 0 and the null log stream on all other processors.
std::ostream & sierra::Env::outputNull ()
 Function outputNull returns the null output stream. All data is simply discarded by the buffer associated with this stream.
const char * sierra::Env::section_separator ()
 Function output_open opens an output file on processor zero for synchronous data output from all processors via the mpi_filebuf class. The output is synchronized via the output_flush() function and maintain in the output stream list so that it is flushed and closed on application rundown.
const char * sierra::Env::subsection_separator ()
 Function subsection_separator returns a c-style string to be used as a output subsection separator.
std::string sierra::Env::section_title (const std::string &title)
 Function section_title returns a section title. The title has date and time concatenated and right justified to the length of the section_separator. The date and time is 20 characters wide, so adjust your titles accordingly.
void sierra::Env::output_flush ()
 Function output_flush flushes all output on all currently open synchronous outptu files which were opened via output_open.
void sierra::Env::output_flush (std::ostream &stream)
 Function output_flush synchronously flushes stream which was created using an mpi_filebuf.
void sierra::Env::request_shutdown (bool shutdown)
bool sierra::Env::is_shutdown_requested ()
void sierra::Env::abort ()
 Function abort aborts the execution of the sierra application.
MPI_Comm sierra::Env::parallel_comm ()
 Function parallel_comm returns the current MPI communicator used by the sierra environment.
MPI_Comm sierra::Env::parallel_world_comm ()
 Function parallel_world_comm returns the MPI_COMM_WORLD communicator used by the sierra environment in a MPMD parallel application.
int sierra::Env::peer_group ()
 Function peer_group returns the peer group rank for an application of type EXEC_TYPE_PEER.
int sierra::Env::parallel_fluid_master ()
 Function parallel_lag_master returns the global rank of the Gemini Euler application.
int sierra::Env::parallel_lag_master ()
 Function parallel_lag_master returns the global rank of the Sierra lagrangian application.
int sierra::Env::parallel_size ()
 function parallel_size returns the number of processors in the current mpi communicator.
int sierra::Env::parallel_rank ()
 function parallel_rank returns the rank of this processor in the current mpi communicator.
void sierra::Env::startup_preparallel_platform ()
 Function startup_preparallel_platform ...
std::string sierra::Env::hostname ()
 Function hostname returns the hostname of the host running the application.
std::string sierra::Env::domainname ()
 Function domainname returns the domainname of the domain running the application.
std::string sierra::Env::username ()
 Function username returns the username of the user running the application.
std::string sierra::Env::hardware ()
 Function hardware returns the hardware type of the host running the application.
std::string sierra::Env::osname ()
 Function osname returns the operating system nameof the host running the application.
std::string sierra::Env::osversion ()
 Function osversion returns the hardware type of the host running the application.
int sierra::Env::pid ()
 Function pid returns the process id of the process running the application.
int sierra::Env::pgrp ()
 Function pgrp returns the process group id of the process running the application.
void sierra::Env::get_heap_info (size_t &heap_size, size_t &largest_free)
 Member function get_heap_info returns the amount of heap memory used in bytes and the largest free block of memory in bytes.
size_t sierra::Env::get_heap_usage ()
 Function get_heap_usage returns the number of bytes used by the heap.
size_t sierra::Env::get_available_memory ()
 Function get_available_memory returns an estimation of the amount of memory available to the process.
void sierra::Env::get_memory_info (size_t &memory_usage, size_t &faults)
 Function get_memory_info returns the total memory usage of the process and the number of page faults accumulated by the process.
bool sierra::Env::path_exists (const std::string &path)
 Function path_exists returns true if the path exists.
bool sierra::Env::path_access (const std::string &path, int mode)
 Function path_access returns true if the process has permission to access path with the specified mode.
bool sierra::Env::path_read_access (const std::string &path)
 Function path_read_access returns true if the process has read access to the path.
bool sierra::Env::path_write_access (const std::string &path)
 Function path_write_access returns true if the process has write access to the path.
bool sierra::Env::read_lock (int fd)
 Function read_lock returns true if the process was able to place a shared lock on the specified file descriptor.
bool sierra::Env::write_lock (int fd)
 Function write_lock returns true if the process was able to place an exclusive lock on the specified file descriptor.
bool sierra::Env::append_lock (int fd)
 Function append_lock returns true if the process was able to place an exclusive lock on the end of the specified file descriptor. Existing records may still be accessed.
bool sierra::Env::release_lock (int fd)
 Function release_lock returns true if the process was able to release a lock previously palced on the specified file descriptor.
void sierra::Env::activate_signals ()
 Function activate_signals enables the signal handlers.
void sierra::Env::deactivate_signals ()
 Function deactivate_signals disables the signal handlers.
sigjmp_buf * sierra::Env::get_sigjmpbuf ()
 Function get_sigjmpbuf enables signal handling and returns a pointer to the jump buffer for ::sigsetjmp and ::siglongjmp().
const std::string & sierra::Env::get_signal_message ()
 Function disable_siglongjmp disables the long jump buffer. When signals are received, they return to the caller without long jumping to the set jump point.
bool sierra::Env::HUP_received ()
 Function request_shutdown sets the shutdown requested flag so that future calls to shutdown_requested() return true;.
bool sierra::Env::shutdown_requested ()
 Function shutdown_requested returns true if an application shutdown has requested via the request_shutdown has been called.

Enumeration Type Documentation

Enumeration ExecutableType defines the known types of coordinated executables that operate with a sierra application. Unfortunately, this scheme for coordination is currently defined by Gemini whose implementation forces a limit of two executables, namely it and a fluid code. The startup_multi_exec() function handles the creation of groups which are contiguous processor groups, each with lead processor being the least ranked processor in the group.

Modification of the startup_multi_exec() function would need to be made to enable more than the two executable types.

Enumerator:
EXEC_TYPE_WORLD 

Generic application using entire communicator (MPI_COMM_WORLD)

EXEC_TYPE_FLUID 

Gemini Euler application.

EXEC_TYPE_LAG 

Sierra Lagrangian application.

EXEC_TYPE_PEER 

Split communicator application; non-Gemini.

Definition at line 62 of file Env.hpp.


Function Documentation

bool sierra::Env::StartupSierra ( int *  argc,
char ***  argv,
const char *  product_name,
const char *  build_date_time,
ExecType  mpi_key = EXEC_TYPE_WORLD,
const std::vector< int > *  peer_sizes = NULL 
)

Initialize MPI related operations for sierra, outputs banner, etc. returns 1 if MPI was initialized, 0 otherwise.

Parameters:
argcan int pointer to the main argc.
argva char pointer to the main argv.
product_namea char const pointer to the name of the product.
build_date_timea char const pointer to __DATE__ " " __TIME__
mpi_keyan optional ExecType enumeration specifying the type of executable. Default is a single executable using MPI_COMM_WORLD. Other options result in a split communicator.
peer_sizesan optional std::vector<int> const pointer containing the number of processors that each peer communicator (
See also:
parrallel_peer_comm()) will support. The number of peers is determined by the size of the vector. Only used if mpi_key = EXEC_TYPE_PEER

Definition at line 392 of file Env.cpp.

void sierra::Env::reset ( MPI_Comm  mpi_comm)

Function reset determines new parallel_size and parallel_rank. Flushes, closes, and reopens log files.

This is a very dangerous method, if the previous communicator had been queried and given to an external library then Sierra and that external library will be out-of-sync. It is strongly recommended that parser-interface singletons do not query and save the communicator.

This capability is provided to support dakota.

Parameters:
mpi_comma MPI_Comm value for the new mpi communicator.
work_dira char const pointer to the new working directory.

Definition at line 1065 of file Env.cpp.

const std::string & sierra::Env::get_param ( const char *const  option)

Function query_env_param searches the command line options for the specified option. If not found, a const reference to an empty string is returned.

Parameters:
optiona char const pointer to the option to search for.
Returns:
a std::string const reference to the options value or an empty string if not found.

Definition at line 1162 of file Env.cpp.

void sierra::Env::set_param ( const char *  option,
const std::string &  value 
)

Member function set_param assigns the value to the parameter option.

Parameters:
optiona char const pointer to the option to search for.
valuea char const pointer to the value to assign to the param.

Definition at line 1177 of file Env.cpp.

const std::string & sierra::Env::product_name ( )

Function product_name returns the product's name. This name is used to query the product registry for information concerning this product.

Returns:
a std::string const reference to the product's name.

Definition at line 172 of file Env.cpp.

bool sierra::Env::developer_mode ( )

Function developer_mode returns true if the.

--developer option was specified on the application command line.

Returns:
a std::string const reference to the applications operating platform string.

Definition at line 217 of file Env.cpp.

const std::string & sierra::Env::architecture ( )

Function architecture returns the platform executing this product. This is obtained during startup by searching for a file which contains this information.

Returns:
a std::string const reference to the applications operating platform string.

Definition at line 243 of file Env.cpp.

const std::string & sierra::Env::executable_file ( )

Function executable_file returns the path of this executable file. information.

Returns:
a std::string const reference to the executable file path string.

Definition at line 179 of file Env.cpp.

const std::string & sierra::Env::executable_date ( )

Function executable_date returns the build date of the executable file as a string in the form Mmm dd yyyy hh:mm::ss.

Returns:
a std::string const reference to the executable file's build date and time.

Definition at line 186 of file Env.cpp.

const std::string & sierra::Env::startup_date ( )

Function startup_date returns the startup date of this application execution.

Returns:
a std::string const reference to the application execution start date and time.

Definition at line 198 of file Env.cpp.

double sierra::Env::start_time ( )

Function start_time returns the start time of this application execution.

Returns:
a double value of the application execution start time.

Definition at line 210 of file Env.cpp.

double sierra::Env::wall_now ( )

Member function wall_now returns the epoch as a double precision value in seconds to "millisecond" accuracy.

Returns:
a double ...

Definition at line 261 of file Platform.cpp.

double sierra::Env::cpu_now ( )

Member function cpu_now returns the accumlated cpu time for the process as a double precision value in seconds to "millisecond" accuracy.

Returns:
a double ...

Definition at line 271 of file Platform.cpp.

double sierra::Env::vm_now ( )

Member function vm_now returns the virtual memory in use for the process as a double precision value in bytes.

Returns:
a double value of the number of bytes of virtual memory currently in use.

Definition at line 442 of file Platform.cpp.

const std::string sierra::Env::working_directory ( )

Function working_directory returns the current working directory of this application execution.

,

Returns:
a std::string to the application execution working directory.

Definition at line 250 of file Env.cpp.

std::ostream & sierra::Env::output ( )

Function output returns the processor output log stream. This stream is connected via an mpi_filebuf to processor 0. Upon output_flush() the output from all processors is collected on processor 0 in a sequential by process and is logged to output file in a non-jumbled manner.

Returns:
a std::ostream reference to the application log stream.

Definition at line 262 of file Env.cpp.

std::ostream & sierra::Env::outputP0 ( )

Function outputP0 returns the processor output log stream on processor 0 and the null log stream on all other processors.

Returns:
a std::ostream reference to the application log stream on processor 0 or null stream on the processors.

Definition at line 269 of file Env.cpp.

std::ostream & sierra::Env::outputNull ( )

Function outputNull returns the null output stream. All data is simply discarded by the buffer associated with this stream.

Returns:
a std::ostream reference to the null output stream.

Definition at line 276 of file Env.cpp.

const char * sierra::Env::section_separator ( )

Function output_open opens an output file on processor zero for synchronous data output from all processors via the mpi_filebuf class. The output is synchronized via the output_flush() function and maintain in the output stream list so that it is flushed and closed on application rundown.

Must be executed concurrently on all processor in the current Env::parallel_comm() group.

Parameters:
filenamea char const pointer to the path of file to open.
Returns:
a std::ostream reference to the newly opened output stream. Function section_separator returns a c-style string to be used as a output section separator.
a char const pointer to the section separator string.

Definition at line 282 of file Env.cpp.

const char * sierra::Env::subsection_separator ( )

Function subsection_separator returns a c-style string to be used as a output subsection separator.

Returns:
a char const pointer to the subsection separator

Definition at line 291 of file Env.cpp.

std::string sierra::Env::section_title ( const std::string &  title)

Function section_title returns a section title. The title has date and time concatenated and right justified to the length of the section_separator. The date and time is 20 characters wide, so adjust your titles accordingly.

Parameters:
titlea std::string const reference to the title string.
Returns:
a std::string value with the date and time right justified to section_separator's length.

Definition at line 300 of file Env.cpp.

void sierra::Env::output_flush ( )

Function output_flush flushes all output on all currently open synchronous outptu files which were opened via output_open.

Must be executed concurrently on all processor in the current Env::parallel_comm() group.

Definition at line 1103 of file Env.cpp.

void sierra::Env::output_flush ( std::ostream &  stream)

Function output_flush synchronously flushes stream which was created using an mpi_filebuf.

Must be executed concurrently on all processor in the current Env::parallel_comm() group.

Parameters:
streama std::ostream reference to the synchronous output stream to flush.
MPI_Comm sierra::Env::parallel_comm ( )

Function parallel_comm returns the current MPI communicator used by the sierra environment.

Returns:
a MPI_Comm value of the current MPI communicator.

Definition at line 321 of file Env.cpp.

MPI_Comm sierra::Env::parallel_world_comm ( )

Function parallel_world_comm returns the MPI_COMM_WORLD communicator used by the sierra environment in a MPMD parallel application.

Returns:
a MPI_Comm value of the current MPI_COMM_WORLD communicator.

Definition at line 327 of file Env.cpp.

int sierra::Env::peer_group ( )

Function peer_group returns the peer group rank for an application of type EXEC_TYPE_PEER.

Returns:
a int value of the peer group for the peer application.

Definition at line 340 of file Env.cpp.

int sierra::Env::parallel_fluid_master ( )

Function parallel_lag_master returns the global rank of the Gemini Euler application.

Returns:
a int value of the global rank of the Gemini Euler application.

Definition at line 336 of file Env.cpp.

int sierra::Env::parallel_lag_master ( )

Function parallel_lag_master returns the global rank of the Sierra lagrangian application.

Returns:
a int value of the global rank of the Sierra lagrangian application.

Definition at line 332 of file Env.cpp.

int sierra::Env::parallel_size ( )

function parallel_size returns the number of processors in the current mpi communicator.

Returns:
an int value of the number of processors in the current mpi communicator.

Definition at line 312 of file Env.cpp.

int sierra::Env::parallel_rank ( )

function parallel_rank returns the rank of this processor in the current mpi communicator.

Returns:
an int value of the rank for this processors in the current mpi communicator.

Definition at line 316 of file Env.cpp.

std::string sierra::Env::hostname ( )

Function hostname returns the hostname of the host running the application.

Returns:
a String value of the host name obtained from the operating system.

Definition at line 454 of file Platform.cpp.

std::string sierra::Env::domainname ( )

Function domainname returns the domainname of the domain running the application.

Returns:
a String value of the domain name obtained from the operating system.

Definition at line 463 of file Platform.cpp.

std::string sierra::Env::username ( )

Function username returns the username of the user running the application.

Returns:
a String value of the username obtained from the operating system.

Definition at line 493 of file Platform.cpp.

std::string sierra::Env::hardware ( )

Function hardware returns the hardware type of the host running the application.

Returns:
a String value of the machine field of the uname system call or equivalent obtained from the operating system.

Definition at line 509 of file Platform.cpp.

std::string sierra::Env::osname ( )

Function osname returns the operating system nameof the host running the application.

Returns:
a String value of the sysname field of the uname system call or equivalent obtained from the operating system.

Definition at line 525 of file Platform.cpp.

std::string sierra::Env::osversion ( )

Function osversion returns the hardware type of the host running the application.

Returns:
a String value of the release field of the uname system call or equivalent obtained from the operating system.

Definition at line 541 of file Platform.cpp.

int sierra::Env::pid ( )

Function pid returns the process id of the process running the application.

Returns:
a int value of the process id obtained from the operating system.

Definition at line 557 of file Platform.cpp.

int sierra::Env::pgrp ( )

Function pgrp returns the process group id of the process running the application.

Returns:
a int value of the process group id obtained from the operating system.

Definition at line 564 of file Platform.cpp.

void sierra::Env::get_heap_info ( size_t &  heap_size,
size_t &  largest_free 
)

Member function get_heap_info returns the amount of heap memory used in bytes and the largest free block of memory in bytes.

Parameters:
heap_sizea size_t returns the amount of heap memory used in bytes.
largest_freea size_t returns the largest free block of memory.

Definition at line 295 of file Platform.cpp.

size_t sierra::Env::get_heap_usage ( ) [inline]

Function get_heap_usage returns the number of bytes used by the heap.

Returns:
a size_t value of the number of bytes used by the heap.

Definition at line 152 of file Platform.hpp.

size_t sierra::Env::get_available_memory ( )

Function get_available_memory returns an estimation of the amount of memory available to the process.

Returns:
a size_t value of the number of bytes available to the process.

Definition at line 358 of file Platform.cpp.

void sierra::Env::get_memory_info ( size_t &  memory_usage,
size_t &  faults 
)

Function get_memory_info returns the total memory usage of the process and the number of page faults accumulated by the process.

Parameters:
memory_usagea size_t reference to receive the number of bytes currently used by the process.
faultsa size_t reference to treceive the number of page faults incurred by the process.

Definition at line 386 of file Platform.cpp.

bool sierra::Env::path_exists ( const std::string &  path)

Function path_exists returns true if the path exists.

Parameters:
patha String const reference to the path to have existence tested.
Returns:
a bool value of true if the path exists.

Definition at line 585 of file Platform.cpp.

bool sierra::Env::path_access ( const std::string &  path,
int  mode 
)

Function path_access returns true if the process has permission to access path with the specified mode.

Parameters:
patha String const reference to the path to check for mode access.
modean int value of the mode to test.
Returns:
a bool value of true of the process has permission to access the path with mode access.

Definition at line 575 of file Platform.cpp.

bool sierra::Env::path_read_access ( const std::string &  path)

Function path_read_access returns true if the process has read access to the path.

Parameters:
patha String const reference to the path to check for read access.
Returns:
a bool value of true of the process has permission to access the path with read access.

Definition at line 593 of file Platform.cpp.

bool sierra::Env::path_write_access ( const std::string &  path)

Function path_write_access returns true if the process has write access to the path.

Parameters:
patha String const reference to the path to check for write access.
Returns:
a bool value of true of the process has permission to access the path with write access.

Definition at line 601 of file Platform.cpp.

bool sierra::Env::read_lock ( int  fd)

Function read_lock returns true if the process was able to place a shared lock on the specified file descriptor.

Parameters:
fdan int value of the file description to attempt to lock.
Returns:
a bool value of true of the lock succeeded.

Definition at line 652 of file Platform.cpp.

bool sierra::Env::write_lock ( int  fd)

Function write_lock returns true if the process was able to place an exclusive lock on the specified file descriptor.

Parameters:
fdan int value of the file description to attempt to lock.
Returns:
a bool value of true of the lock succeeded.

Definition at line 628 of file Platform.cpp.

bool sierra::Env::append_lock ( int  fd)

Function append_lock returns true if the process was able to place an exclusive lock on the end of the specified file descriptor. Existing records may still be accessed.

Parameters:
fdan int value of the file description to attempt to lock.
Returns:
a bool value of true of the lock succeeded.

Definition at line 660 of file Platform.cpp.

bool sierra::Env::release_lock ( int  fd)

Function release_lock returns true if the process was able to release a lock previously palced on the specified file descriptor.

Parameters:
fdan int value of the file description to have the lock released.
Returns:
a bool value of true of the lock release succeeded.

Definition at line 640 of file Platform.cpp.

sigjmp_buf * sierra::Env::get_sigjmpbuf ( )

Function get_sigjmpbuf enables signal handling and returns a pointer to the jump buffer for ::sigsetjmp and ::siglongjmp().

if (::sigsetjmp(*sierra::Env::get_signalException(), 1)) throw sierra::RuntimeError(sierra::Env::get_signal_message());

Returns:
a sigjmp_buf pointer to the jmp buffer.

Definition at line 257 of file Signal.cpp.

const std::string & sierra::Env::get_signal_message ( )

Function disable_siglongjmp disables the long jump buffer. When signals are received, they return to the caller without long jumping to the set jump point.

Function get_signal_message returns the message associated with the most recent signal.

Returns:
a std::string const reference to the most recent signal message.

Definition at line 271 of file Signal.cpp.

bool sierra::Env::shutdown_requested ( )

Function shutdown_requested returns true if an application shutdown has requested via the request_shutdown has been called.

Returns:
a bool value of true if application has been requested to shutdown.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines