grvy.h

Go to the documentation of this file.

// -*-c++-*-
//-----------------------------------------------------------------------bl-
//--------------------------------------------------------------------------
// 
// libGRVY - a utility library for scientific computing.
//
// Copyright (C) 2008-2013,2018-2022 The PECOS Development Team
// Additional Copyright (C) 2018 individual authors
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the Version 2.1 GNU Lesser General
// Public License as published by the Free Software Foundation.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc. 51 Franklin Street, Fifth Floor, 
// Boston, MA  02110-1301  USA
//
//-----------------------------------------------------------------------el-
//
// grvy.h: Basic API Definitions
//
//--------------------------------------------------------------------------
//--------------------------------------------------------------------------
 
#include<stddef.h>
 
#ifndef GRVY_H_
#define GRVY_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Library version/build information */
 
#define GRVY_MAJOR_VERSION  0
#define GRVY_MINOR_VERSION  39
#define GRVY_MICRO_VERSION  0
 
#define GRVY_BUILD_USER     "runner"
#define GRVY_BUILD_ARCH     "x86_64-pc-linux-gnu"
#define GRVY_BUILD_HOST     "runnervmmklqx"
#define GRVY_BUILD_DATE     "2026-06-30 15:16"
#define GRVY_BUILD_VERSION  "a84dc03"
 
#define GRVY_LIB_VERSION    "0.39.0"
#define GRVY_LIB_RELEASE    "Development Build"
 
#define GRVY_CXX            "g++"
#define GRVY_CXXFLAGS       "-g -O2"
 
#define GRVY_FC             "gfortran"
#define GRVY_FCFLAGS        "-g -O2"
#define GRVY_MPI_ENABLED    0
#define GRVY_OCORE_ENABLED  0
 
#if GRVY_MPI_ENABLED == 1
// MPI implementations try to include C++ code via mpi.h unless you
// tell them not to; this breaks when we do it in an extern "C" block.
#define MPICH_SKIP_MPICXX
#define OMPI_SKIP_MPICXX
#include <mpi.h>
#endif
 
 
  //-----------------------------------------------------------------
  // Versioning Utilities
  //-----------------------------------------------------------------
 
  extern void grvy_version_stdout           ();
 
  extern int grvy_get_numeric_version       ();
 
  //-----------------------------------------------------------------
  // Input Parsing Utilities
  //-----------------------------------------------------------------
 
  extern int grvy_input_fopen               (const char *filename);
 
  extern int grvy_input_fclose              ();
 
  extern int grvy_input_fdump               ();
 
  extern int grvy_input_fdump_delim         (const char* prefix);
 
  extern int grvy_input_fdump_file          (const char* prefix, const char *filename);
 
   extern int grvy_input_fread_int           (const char* keyword, int *value);
 
   extern int grvy_input_fread_float         (const char* keyword, float *value);
 
   extern int grvy_input_fread_double        (const char* keyword, double *value);
 
   extern int grvy_input_fread_char          (const char* keyword, char **value);
 
  extern int grvy_input_fread_int_vec       (const char* keyword, int *values,    int nelems);
 
  extern int grvy_input_fread_float_vec     (const char* keyword, float *values,  int nelems);
 
  extern int grvy_input_fread_double_vec    (const char* keyword, double *values, int nelems);
 
  extern int grvy_input_fread_char_ivec     (const char* keyword, char **values,  int elem);
 
 
  extern int grvy_input_fread_int_ivec      (const char* keyword, int *value,    int elem);
 
  extern int grvy_input_fread_float_ivec    (const char* keyword, float *value,  int elem);
 
  extern int grvy_input_fread_double_ivec   (const char* keyword, double *value, int elem);
 
  extern int grvy_input_register_int        (const char *keyword,     int value);
 
  extern int grvy_input_register_float      (const char *keyword,   float value);
 
  extern int grvy_input_register_double     (const char *keyword,  double value);
 
  extern int grvy_input_register_char       (const char *keyword,   char *value);
 
  extern int grvy_input_register_get_int    (const char *keyword,    int *value);
 
  extern int grvy_input_register_get_float  (const char *keyword,  float *value);
 
  extern int grvy_input_register_get_double (const char *keyword, double *value);
 
  extern int grvy_input_register_get_char   (const char *keyword,  char **value);
 
  //-----------------------------------------------------------------
  // Performance Timer Utilities
  //-----------------------------------------------------------------
 
  extern   void grvy_timer_init                (const char *description);
 
  extern   void grvy_timer_begin               (const char *id);
 
  extern   void grvy_timer_end                 (const char *id);
 
  extern   void grvy_timer_reset               ();
 
  extern   void grvy_timer_finalize            ();
 
  extern double grvy_timer                     ();
 
  extern double grvy_timer_elapsed_global      ();
 
  extern   void grvy_timer_summarize           ();
 
  int grvy_timer_set_summarize_width (const int maxwidth);
 
  extern double grvy_timer_elapsedseconds      (const char *id);
  extern double grvy_timer_stats_mean          (const char *id);
  extern double grvy_timer_stats_variance      (const char *id);
  extern double grvy_timer_stats_min           (const char *id);
  extern double grvy_timer_stats_max           (const char *id);
  extern    int grvy_timer_stats_count         (const char *id);
 
  extern double grvy_timer_elapsedseconds_inc  (const char *id);
  extern double grvy_timer_stats_mean_inc      (const char *id);
  extern double grvy_timer_stats_variance_inc  (const char *id);
  extern double grvy_timer_stats_min_inc       (const char *id);
  extern double grvy_timer_stats_max_inc       (const char *id);
 
  // Mode 1: Saving internal GRVY timer values to historical repository
 
  extern    int grvy_timer_save_hist         (const char *experiment_name, const char *comment, 
                                              int num_procs, const char *filename);
 
  extern    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);
                                              
  // Mode 2: Saving external user-provided global timing to historical repository
 
  extern    int grvy_timer_save_hist_ext     (double timing, const char *machinename,const char*experiment, 
                                              const char *comment,int num_procs, const char *filename);
 
  extern    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);
 
  //-----------------------------------------------------------------
  // MPI Out-of-Core Utilities
  //-----------------------------------------------------------------
 
#if GRVY_OCORE_ENABLED == 1
 
  //  extern    int grvy_ocore_split_comm          (MPI_Comm GLOB_COMM, MPI_Comm WORK_COMM, MPI_Comm OCORE_COMM, int mode);
  extern    int grvy_ocore_init                (const char *input_file, int num_ocore_tasks, MPI_Comm GLOB_COMM);
  extern    int grvy_ocore_init_fortran        (const char *input_file, int num_ocore_tasks, int GLOB_COMM_COMM);
  extern   void grvy_ocore_finalize            ();
 
  extern    int grvy_ocore_master              ();
  extern    int grvy_ocore_enabled             ();
  extern    int grvy_ocore_blocksize           ();
  extern size_t grvy_ocore_num_active          ();
 
  extern    int grvy_ocore_write_double        (size_t record_id,    double     *data);
  extern    int grvy_ocore_write_float         (size_t record_id,     float     *data);
  extern    int grvy_ocore_write_int           (size_t record_id,       int     *data);
  extern    int grvy_ocore_write_int64         (size_t record_id, long long int *data);
 
  extern    int grvy_ocore_read_double         (size_t record_id,    double     *data);
  extern    int grvy_ocore_read_float          (size_t record_id,     float     *data);
  extern    int grvy_ocore_read_int            (size_t record_id,       int     *data);
  extern    int grvy_ocore_read_int64          (size_t record_id, long long int *data);
 
  extern size_t grvy_ocore_pop_record_float         (        float *data);
  extern size_t grvy_ocore_pop_record_double        (       double *data);
  extern size_t grvy_ocore_pop_record_int           (          int *data);
  extern size_t grvy_ocore_pop_record_int64         (long long int *data);
 
#endif
 
  //-----------------------------------------------------------------
  // Floating-Point Utilities
  //-----------------------------------------------------------------
 
  extern int grvy_double_isnan            (double *value);
  extern int grvy_double_isinf            (double *vauel);
  extern int grvy_float_isnan             (float  *value);
  extern int grvy_float_isinf             (float  *value);
 
  //-----------------------------------------------------------------
  // Logging Utilities
  //-----------------------------------------------------------------
 
  /* Available logging priorities; roughly mimics syslog priority levels.
   * Also provides a NOLOG option to disable all log messages. 
   */
 
  typedef enum {GRVY_NOLOG  =  -1,
                GRVY_FATAL  =   0,
                GRVY_ERROR  = 100,
                GRVY_WARN   = 200,
                GRVY_INFO   = 300,
                GRVY_DEBUG  = 400,
                GRVY_ALL    = 500
  } PriorityLevel;
 
  extern void grvy_log_setlevel           (int priority);
  extern int  grvy_log_getlevel           ();
  extern void grvy_log_setmask            (int loglevel, const char *delimiter);
  extern  int grvy_printf                 (int loglevel, const char *format,...);
 
  extern int  grvy_check_file_path        (const char *name_template);
 
  extern int  grvy_create_unique_dir      (      char *name_template);
 
  extern int  grvy_create_scratch_dir     (      char *name_template);
 
  extern int  grvy_copy_dir              (const char *from_dir, const char *to_dir);
 
  /*
   * Doxygen API Definitions
   */
 
#ifdef __cplusplus
}
 
 
//--------------------------
// C++ GRVY Interfaces
//--------------------------
 
#include<vector>
#include<map>
#include<string>
#include<memory>
 
// Forward declare GetPot class so we don't need
// to include header here.
 
namespace GRVYGetPot
  {
    class GetPot;
  }
 
//--------------------
// Input Parsing Class
//--------------------
 
 
// \namespace GRVY 
// \brief Namespace containing all libGRVY classes.
 
namespace GRVY {
 
  void GRVY_version_stdout();
  int  GRVY_get_numeric_version();
 
  /* \brief Input Parsing Class 
   * 
   */
 
class GRVY_Input_Class {
 
 public:
  GRVY_Input_Class  ();
 ~GRVY_Input_Class  ();
 
  int  Open         (const char *filename);
  int  Load         (std::stringstream &buffer);
 
  int  Close        ();
 
  int  Fdump        ();
 
  int  Fdump        (const char *prefix);
 
  int  Fdump        (const char *prefix, const char *filename);
 
  template <typename T> int Read_Var      (std::string keyword, T *value );           
  template <typename T> int Read_Var      (std::string keyword, T *value, T vardef);  
 
  template <typename T> int Read_Var      (const char *keyword, T *value );           
  template <typename T> int Read_Var      (const char *keyword, T *value, T vardef);  
 
  // Character string reads
 
  int Read_Var                            (const char *keyword, std::string *value);                     
  int Read_Var                            (const char *keyword, char **value);                           
  int Read_Var                            (const char *keyword, std::string *value, std::string vardef); 
 
  // Bool Read Functions
 
  int Read_Var                            (const char *var, bool *value, bool vardef); 
  int Read_Var                            (std::string var, bool *value, bool vardef); 
 
  template <typename T> int Read_Var_Vec  (std::string keyword, T *values, int nelems);            
  template <typename T> int Read_Var_Vec  (const char *keyword, T *values, int nelems);            
  template <typename T> int Read_Var_Vec  (std::string keyword, T *values, int nelems, T vardef);  
  template <typename T> int Read_Var_Vec  (const char *keyword, T *values, int nelems, T vardef);  
 
  template <typename T> int Read_Var_iVec (std::string keyword, T *value, int elem);               
  template <typename T> int Read_Var_iVec (const char *keyword, T *value, int elem);               
  template <typename T> int Read_Var_iVec (std::string keyword, T *value, int elem,   T vardef);   
  template <typename T> int Read_Var_iVec (const char *keyword, T *value, int elem,   T vardef);   
 
  // Character String Read Functions
 
  int Read_Var_iVec                       (const char *keyword, char **value, int elem);           
  int Read_Var_iVec                       (const char *keyword, std::string *value, int elem);     
 
  void Register_Var  (const char *keyword, int     var);           
  void Register_Var  (const char *keyword, float   var);           
  void Register_Var  (const char *keyword, double  var);           
  void Register_Var  (const char *keyword, bool    var);           
  void Register_Var  (const char *keyword, const char  *var);      
  void Register_Var  (const char *keyword, std::string  var);      
 
  int  Get_Var       (const char *keyword, int    *value);       
  int  Get_Var       (const char *keyword, float  *value);       
  int  Get_Var       (const char *keyword, double *value);       
  int  Get_Var       (const char *keyword, char  **value);       
  int  Get_Var       (const char *keyword, std::string *value);  
 
  void PrintRegVars  (const char *prefix); 
 
 private:
  class GRVY_Input_ClassImp       ;           // forward declaration to Input class implementation
  std::unique_ptr<GRVY_Input_ClassImp> m_pimpl; // pointer to implementation
 
};
 
  /* @} */  
 
//--------------------------
// Performance Timing Class
//--------------------------
 
class GRVY_Timer_Class {
 
 public:
  GRVY_Timer_Class        (); 
 ~GRVY_Timer_Class        ();
 
  void   Init             (std::string name); 
  void   BeginTimer       (std::string id);   
  void   EndTimer         (std::string id);   
  void   Finalize         ();                 
 
  double ElapsedSeconds   (std::string id);   // return elapsed time for specifc timer id
  double ElapsedGlobal    ();                 // return elapsed time since Init()
  double RawTimer         ();                 // raw timer
 
  void   Reset            ();                 // reset all timers
  void   Summarize        ();                 // pretty-print timing information
  int    SetSummarizeWidth(const int width);  // set max output width for summarize stdout
 
  size_t StatsCount       (std::string id);   // # of calls to timer (id)
  double StatsMean        (std::string id);   // mean time for timer (id)
  double StatsVariance    (std::string id);   // variance for timer  (id)
  double StatsMin         (std::string id);   // min value for timer (id)
  double StatsMax         (std::string id);   // max value for timer (id)
 
  /* Inclusive timing routines */
 
  double ElapsedSeconds_inc(std::string id);  // return elapsed time for specifc timer id
  double StatsMean_inc     (std::string id);  // mean time for timer (id)
  double StatsVariance_inc (std::string id);  // variance for timer  (id)
  double StatsMin_inc      (std::string id);  // min value for timer (id)
  double StatsMax_inc      (std::string id);  // max value for timer (id)
 
  // Mode 1: Saving internal GRVY timer values to historical repository
 
  int  SaveHistTiming      (std::string experiment, std::string comment, int num_procs, 
                            std::string filename);
 
  int  SaveHistTiming      (std::string experiment, std::string comment, int num_procs, 
                            int jobId, std::string code_revision, double flops, std::string filename);
 
  // Mode 2: Saving user-provided global timing to historical repository
 
  int  SaveHistTiming      (double timing, std::string machinename, std::string experiment, 
                            std::string comment, int num_procs, std::string filename);
 
  int  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);
 
  // ---------------
  // Query Functions
  // ---------------
 
  void SummarizeHistTiming (std::string filename,   std::string delimiter, std::string outdir);
 
  // Class options 
 
  int  SetOption           (std::string option, bool flag);
 
private:
  class GRVY_Timer_ClassImp;                    // forward declaration to Timer implementation
  std::unique_ptr<GRVY_Timer_ClassImp> m_pimpl; // pointer to implementation
 
};
 
  //--------------------------
  // MPI Out-of-Core Class
  //--------------------------
 
class GRVY_MPI_Ocore_Class {
 
public:
  GRVY_MPI_Ocore_Class(); 
  ~GRVY_MPI_Ocore_Class();
 
#if GRVY_OCORE_ENABLED == 1
  int    Initialize   (std::string inputfile, int num_ocore_tasks, MPI_Comm GLOB_COMM);
  void   Finalize     ();
  size_t NumActive    ();       // number of currently active records
  bool   isMaster     ();       // is the calling task the master task (in GLOB_COMM)?
  bool   isWorkTask   ();       // is the calling task a worker task used by application (in GLOB_COMM)?
  bool   isOcoreTask  ();       // is the calling task used by Ocore (in GLOB_COMM)?
  bool   isEnabled    ();       // is MPI Ocore enabled? (can be controlled via input file)
  int    Blocksize    ();       // Ocore blocksize
 
  // Read/Write Functions
 
  template <typename T> int Write (size_t offset,T *data );
  template <typename T> int Read  (size_t offset,T *data );
 
  // Record retrieval/removal
 
  template <typename T> size_t PopRecord (T *data );
 
#endif
 
private:
  class GRVY_MPI_Ocore_ClassImp;                    // forward declaration to Ocore implementation
  std::unique_ptr<GRVY_MPI_Ocore_ClassImp> m_pimpl; // pointer to implementation
};
 
 
 
//--------------------
// HDF5 Utility Class
//--------------------
 
 class GRVY_HDF5_Class //: private boost::noncopyable
 {
   friend class GRVY_Timer_Class;
 
 public:
   GRVY_HDF5_Class  ();
  ~GRVY_HDF5_Class  ();
 
   GRVY_HDF5_Class  (const GRVY_HDF5_Class &rhs);
   GRVY_HDF5_Class  &operator= (GRVY_HDF5_Class );
 
   // File-related functions
   
   int  Create  (std::string filename, bool overwrite_existing);
   int  Open    (std::string filename, bool read_only         );
   bool Exists  (std::string filename);
   int  Close   ();
 
   // Group-related functions
   
   int  GroupCreate (std::string groupname);
   int  GroupOpen   (std::string groupname);
   bool GroupExists (std::string groupname);
 
   std::vector<std::string> ListSubGroups(std::string groupname);
 
   // Dataset-related functions
 
   int  DatasetOpen  (std::string groupname, std::string datasetname);
   bool DatasetExists(std::string groupname, std::string datasetname);
 
   // Attribute-related functions
 
   int  AttributeOpen  (std::string groupname, std::string attribute);
   bool AttributeExists(std::string groupname, std::string attribute);
 
   int AttributeWrite(std::string groupname, std::string attribute,          short int  value);
   int AttributeWrite(std::string groupname, std::string attribute,                int  value);
   int AttributeWrite(std::string groupname, std::string attribute,               long  value);
   int AttributeWrite(std::string groupname, std::string attribute, unsigned short int  value);
   int AttributeWrite(std::string groupname, std::string attribute,       unsigned int  value);
   int AttributeWrite(std::string groupname, std::string attribute,      unsigned long  value);
   int AttributeWrite(std::string groupname, std::string attribute,              float  value);
   int AttributeWrite(std::string groupname, std::string attribute,             double  value);
   int AttributeWrite(std::string groupname, std::string attribute,        std::string  value);
 
   int AttributeRead (std::string groupname, std::string attribute,          short int &value);
   int AttributeRead (std::string groupname, std::string attribute,                int &value);
   int AttributeRead (std::string groupname, std::string attribute,               long &value);
   int AttributeRead (std::string groupname, std::string attribute, unsigned short int &value);
   int AttributeRead (std::string groupname, std::string attribute,       unsigned int &value);
   int AttributeRead (std::string groupname, std::string attribute,      unsigned long &value);
   int AttributeRead (std::string groupname, std::string attribute,              float &value);
   int AttributeRead (std::string groupname, std::string attribute,             double &value);
   int AttributeRead (std::string groupname, std::string attribute,        std::string &value);
 
   // Dataset-related functions
 
   // Packet Table related functions
   
 private:
   class GRVY_HDF5_ClassImp;                     // forward declaration of HDF5 implementation
   std::unique_ptr<GRVY_HDF5_ClassImp> m_pimpl;  // pointer to implementation
 };
}
 
#endif
 
#endif