Performance Timer Utilities

Performance Timer - Initialization and Timer Demarcation:
The following member functions 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::GRVY_Timer_Class::Init (std::string name)
void	GRVY::GRVY_Timer_Class::BeginTimer (std::string id)
void	GRVY::GRVY_Timer_Class::EndTimer (std::string id)
void	GRVY::GRVY_Timer_Class::Finalize ()

Performance Timer - Query Tools:
The following member functions allow for the querying of defined performance timers.
double	GRVY::GRVY_Timer_Class::ElapsedSeconds (std::string id)
double	GRVY::GRVY_Timer_Class::ElapsedGlobal ()
double	GRVY::GRVY_Timer_Class::RawTimer ()
void	GRVY::GRVY_Timer_Class::Reset ()
void	GRVY::GRVY_Timer_Class::Summarize ()
int	GRVY::GRVY_Timer_Class::SetSummarizeWidth (const int width)
size_t	GRVY::GRVY_Timer_Class::StatsCount (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMean (std::string id)
double	GRVY::GRVY_Timer_Class::StatsVariance (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMin (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMax (std::string id)
double	GRVY::GRVY_Timer_Class::ElapsedSeconds_inc (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMean_inc (std::string id)
double	GRVY::GRVY_Timer_Class::StatsVariance_inc (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMin_inc (std::string id)
double	GRVY::GRVY_Timer_Class::StatsMax_inc (std::string id)

Performance Timing - Historical Logging:
These member functions 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 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::GRVY_Timer_Class::SaveHistTiming (std::string experiment, std::string comment, int num_procs, std::string filename)
int	GRVY::GRVY_Timer_Class::SaveHistTiming (std::string experiment, std::string comment, int num_procs, int jobId, std::string code_revision, double flops, std::string filename)
int	GRVY::GRVY_Timer_Class::SaveHistTiming (double timing, std::string machinename, std::string experiment, std::string comment, int num_procs, std::string filename)
int	GRVY::GRVY_Timer_Class::SaveHistTiming (double timing, std::string machinename, std::string experiment, std::string comment, int num_procs, int jobId, std::string code_revision, double flops, std::string filename)
void	GRVY::GRVY_Timer_Class::SummarizeHistTiming (std::string filename, std::string delimiter, std::string outdir)

Detailed Description

This section presents the C++ class for measuring runtime performance of specific code sections to aid in overall performance/statistical analysis, and to maintain historical performance records as application codes evolve or across alternate compute platforms. Individual code timers are defined based on BeginTimer/EndTimer demarcation around the desired code snippet to measure along with a unique user-provided id string. Note that individual timers can be nested and the library will report exclusive timing of the innermost timers. Various options are provided to interrogate timer measurements, statistics, and relative timer comparisons. A convenient use of these routines is to define timers around various important work constructs within your application and use the Summarize() function to obtain a concise summary of the runtime performance, variability, and relative wallclock comparisions. Example output using this approach is shown below:

-----------------------------------------------------------------------------------------------
GRVY Example Timing - Performance Timings:              |      Mean      Variance       Count
--> foo                 : 3.00978e+00 secs ( 64.0889 %) | [3.00978e-01  2.70727e-08         10]
--> boo                 : 1.17648e+00 secs ( 25.0513 %) | [1.17648e-01  2.35981e-08         10]
--> bar                 : 5.09513e-01 secs ( 10.8493 %) | [5.09513e-02  5.02795e-08         10]
--> Main Program        : 4.48704e-04 secs (  0.0096 %) | [4.48704e-04  0.00000e+00          1]
--> GRVY_Unassigned     : 4.02927e-05 secs (  0.0009 %)
 
    Total Measured Time = 4.69626e+00 secs (100.0000 %)
-----------------------------------------------------------------------------------------------

Namespace: All libGRVY C++ classes are contained with the GRVY namespace.

Class Name: GRVY::GRVY_Timer_Class

Code Example: A specific C++ example using the performance timing routines is available in cpp-timer.cpp.

---