Functions
Versioning Routines:
Obtain libGRVY runtime versioning information.
void	grvy_version_stdout ()

int	grvy_get_numeric_version ()

Input Parsing - File open/close:
Routines for accessing input parameters from a libGRVY style input file. Note that an input file must be opened prior to reading any keyword/value pairs or performing input file dump operations.
int	grvy_input_fopen (const char *filename)

int	grvy_input_fclose ()

Input Parsing - Dump input file contents:
The following routines are used to dump the entire contents of a parsed libGRVY style input file to stdout or to an ASCII file (note that all comments within the original input file are stripped). The prefix variable can be used to include an additional delimiter which prepends each line of the output. Note that an input file must be open prior to reading any performing input file dump operations. These routines are normally used to save all relevant input parameters in the application output for future traceability and repeatability.
int	grvy_input_fdump ()

int	grvy_input_fdump_delim (const char *prefix)

int	grvy_input_fdump_file (const char prefix, const char filename)

Input Parsing - Read scalar values:
The following routines are used to read individual input values for common intrinsic datatypes given a desired keyword character string (keyword). All grvy_input_fread_() routines return 1 on sucess and 0 on failure. This return behavior is intended as a convenience for applications to check input file parsing errors over consecutive reads via multiplicative operations.
int	grvy_input_fread_int (const char keyword, int value)

int	grvy_input_fread_float (const char keyword, float value)

int	grvy_input_fread_double (const char keyword, double value)

int	grvy_input_fread_char (const char keyword, char *value)

Input Parsing - Read vector values:
The following routines are used to read vector valued input values for common intrinsic datatypes given a desired keyword character string (keyword). If successful, the resulting data is stored in the array values.
int	grvy_input_fread_int_vec (const char keyword, int values, int nelems)

int	grvy_input_fread_float_vec (const char keyword, float values, int nelems)

int	grvy_input_fread_double_vec (const char keyword, double values, int nelems)

int	grvy_input_fread_char_ivec (const char keyword, char *values, int elem)

Input Parsing - Read ith vector values:
The following routines are used to read the ith entry (elem) of vector valued input values for common intrinsic datatypes given a desired keyword character string (keyword). If successful, the resulting data is stored in value.
int	grvy_input_fread_int_ivec (const char keyword, int value, int elem)

int	grvy_input_fread_float_ivec (const char keyword, float value, int elem)

int	grvy_input_fread_double_ivec (const char keyword, double value, int elem)

Input Parsing - Default value registration:
The following routines provide a mechanism to register a default value with the input parsing mechanism. If a particular keyword has a registered default value and is subsequently queried with an input file which does not contain the keyword, the registered default value will be returned instead. A convenient use for these registration functions is to provide sensible defaults to newly added input keywords which are not present in older input file revisions.
int	grvy_input_register_int (const char *keyword, int value)

int	grvy_input_register_float (const char *keyword, float value)

int	grvy_input_register_double (const char *keyword, double value)

int	grvy_input_register_char (const char keyword, char value)

Input Parsing - Default registration query:
The following routines can be used to query the current hashed values of any keyword variables which have been registered previously.
int	grvy_input_register_get_int (const char keyword, int value)

int	grvy_input_register_get_float (const char keyword, float value)

int	grvy_input_register_get_double (const char keyword, double value)

int	grvy_input_register_get_char (const char keyword, char *value)

Performance Timer - Initialization and Timer Demarcation:
The following routines provide support for defining one or more wall-clock timers around specific code regions. Individual timers are delineated by a unique id. In addition to timing specific code regions identified with begin/end calls, the library also tracks the total application time from when the timing library was first initialized.
void	grvy_timer_init (const char *description)

void	grvy_timer_begin (const char *id)

void	grvy_timer_end (const char *id)

void	grvy_timer_reset ()

void	grvy_timer_finalize ()

double	grvy_timer ()

Performance Timer - Global Timing Summary:
The following routines are useful for summarizing the measured performance timings for all defined timers and the global runtime.
double	grvy_timer_elapsed_global ()

void	grvy_timer_summarize ()

int	grvy_timer_set_summarize_width (const int maxwidth)

Performance Timer - Individual Timer Query Tools (exclusive timings):
The following routines allow for the querying of defined performance timers. Note that, except for the global timer, these routines provide exclusive timing measurements (ie. they do not include runtime contributions from any embedded timers).
double	grvy_timer_elapsedseconds (const char *id)

double	grvy_timer_stats_mean (const char *id)

double	grvy_timer_stats_variance (const char *id)

double	grvy_timer_stats_min (const char *id)

double	grvy_timer_stats_max (const char *id)

int	grvy_timer_stats_count (const char *id)

Performance Timer - Individual Timer Query Tools (inclusive timings):
The following routines also allow for the querying of defined performance timers. These are similar to the timing utilities above, except these versions provide inclusive timing measurements (ie. they provide wallclock measurements between the begin/end of each timer, including the time associated with any embedded timers).
double	grvy_timer_elapsedseconds_inc (const char *id)

double	grvy_timer_stats_mean_inc (const char *id)

double	grvy_timer_stats_variance_inc (const char *id)

double	grvy_timer_stats_min_inc (const char *id)

double	grvy_timer_stats_max_inc (const char *id)

Performance Timing - Historical Logging:
These routines provide support to store measured runtime performance into an HDF5 file for logging purposes (this functionality requires HDF5 library linkage during the libGRVY configuration phase). Results are stored on a per-machine basis and are appended to the HDF5 file with timestamps to document historical performance over time. Stored results can be retrieved using the API below or via standalone executables installed with libGRVY. There are two primary modes for saving historical performance data: Mode 1: you are using the grvy_timer_* class of routines to define individual sections to monitor and want to save the global runtime measurement along with all individually defined subtimers. Mode 2: you are using other means to profile the application code and want to save a single global timing value. Routines for this mode are distinguished by the presence of an extra "timing" argument in the calling sequence. In both modes, standard and expanded (exp) calling sequences are supported with the expanded version allowing additional optional runtime documentation (e.g. flops, code revision) to be provided.
int	grvy_timer_save_hist (const char experiment_name, const char comment, int num_procs, const char *filename)

int	grvy_timer_save_hist_exp (const char experiment_name, const char comment, int num_procs, int jobId, const char code_revision, double flops, const char filename)

int	grvy_timer_save_hist_ext (double timing, const char machinename, const char experiment, const char comment, int num_procs, const char filename)

int	grvy_timer_save_hist_ext_exp (double timing, const char machinename, const char experiment, const char comment, int num_procs, int jobId, const char code_revision, double flops, const char *filename)

void	grvy_summarize_hist_timing (const char filename, const char delimiter, const char *outdir)

Floating-Point Utilities
Routines for detecting floating-point errors. Return value is set to 1 if the input \value matches the requested floating point exception.
int	grvy_double_isnan (double *value)

int	grvy_double_isinf (double *vauel)

int	grvy_float_isnan (float *value)

int	grvy_float_isinf (float *value)

Logging Utilities
Logging utilities. Note that the default logging priority is set to GRVY_ERROR.
void	grvy_log_setlevel (int priority)

int	grvy_log_getlevel ()

void	grvy_log_setmask (int loglevel, const char *delimiter)

int	grvy_printf (int loglevel, const char *format,...)

Miscellaneous File Path Utilities
I/O Utilities for directory creation and various copy utilities. These routines all return 0 on success.
int	grvy_check_file_path (const char *name_template)

int	grvy_create_unique_dir (char *name_template)

int	grvy_create_scratch_dir (char *name_template)

int	grvy_copy_dir (const char from_dir, const char to_dir)

Detailed Description

This section outlines the available GRVY functions for C/C++. To access, make sure to #include <grvy.h> within your source code files. Several simple examples using these functions are provided in the examples section. Unless specified otherwise, functions which have an integer return value return "0" upon success (and the primary excepton to this rule is with a subset of the Input Parsing routines).

Functions

Detailed Description