F5B.h

Go to the documentation of this file.

#ifndef __F5_Bundle_h
#define __F5_Bundle_h
 
#include "hdf5inc.h"
#include "F5types.h"
#include "F5Bchart.h"
#include "F5F.h"
 
#include <time.h>
 
#include "F5WinDLLApi.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/**\defgroup bundle Basic Operations dealing with semantic structures below the end-user API.
  */
extern F5_API const char*F5_default_time_attrib_names[];
 
typedef enum
{
        /** No specification at all for time    */
        UNSPECIFIED,
        /** The time is in free units, i.e. all units involved can be scaled freely     */
        UNITLESS,
        NANOSECONDS,
        MICROSECONDS,
        MILLISECONDS,
        SECONDS,
        MINUTES,
        HOURS,
        DAYS,
        YEARS,
        MEGAYEARS,
        ELECTRONVOLTS,
 
        /** The time unit is the duration that it takes light to travel one meter       */
        METRES
 
}       F5_TimeSemantics;
 
 
struct  _F5_TimeParameter
{
        /** The numerical value of the time parameter   */
        double  value;
 
        /** The Greenwhich mean time to which the value is relative     */
        time_t  offset;
 
        /** The absolute value of time, which refers to offset + value  */
        time_t  datetime;
 
        /** How is the numerical value to be interpreted        */
        F5_TimeSemantics TimeSemantics;
 
        /** Some additional informative comment                 */
        /** This refers to a static string, it is used, but     */
        /** untouched by the F5 functions                       */
        char    *comment;
 
};
 
typedef struct _F5_TimeParameter F5_TimeParameter;
 
#define F5_TIMESLICE_NAME_LENGTH        (64-8)
 
/**@ingroup bundle
   Data type entry for time tables.
 */
typedef struct  _TimeTableEntry
{
        double  TimeValue;
        char    TimesliceName[F5_TIMESLICE_NAME_LENGTH];
}
        TimeTableEntry;
 
 
/**@ingroup bundle
   Create a transient type that is compatible
   with the TimeTableEntry data structure.
   It must be release via H5Tclose() by the
   calling code.
 */
F5_API hid_t F5Bcreate_timetable_type(void);
 
 
/**@ingroup bundle
   Initialize a time table for the given location.
   @param timetable_type_id The type for time table entries,
          such as provided by F5Bcreate_timetable_type(),
          but it may well be (and should be) a named type
          instead of a transient type.
   @return false if the time table already existed.
   F5_API       int F5Binit_timetable(hid_t loc_id, hid_t timetable_type_id);
 */
 
/**@ingroup bundle
   Append entries to the time table associated with a
   certain location.
   @param timetable_type_location_id the location ID where the
          named datatype for timetable entries will be stored,
          in case it needs to be created.
 */
F5_API  hsize_t F5Bappend_timetable(hid_t loc_id,
                                    hid_t timetable_type_location_id,
                                    const TimeTableEntry*TTE,
                                    hsize_t append_dims);
 
 
/**@ingroup bundle
   Get the number of entries in the respective time table.
 */
F5_API  hsize_t F5Bget_timetable_size(hid_t loc_id);
 
 
/**@ingroup bundle
   Read the entries of a time table.
 */
hsize_t F5Bread_timetable(hid_t loc_id,
                          TimeTableEntry*TTE,
                          hsize_t table_size);
 
 
 
 
/**@ingroup bundle
   Allocate a new F5_TimeParameter structure in memory.
   Actually, one could also pass a static structure, but
   using this function and F5deleteTimePArameter(), the call
   is safe even if the TimeParameter structure is changed
   in a future version of F5.
 */
F5_API F5_TimeParameter*F5BnewTimeParameter(void);
 
/**@ingroup bundle
   Deallocate a F5_TimeParameter structure from memory.
   It needs to be passed a pointer to a pointer, whereby
   the pointer is set to zero on deallocation. So it is
   safe to call this function multiple times on the
   same pointer (just for experimental convenience!).
 */
F5_API void F5deleteTimeParameter(F5_TimeParameter**);
 
/**@ingroup bundle
   Set the time unit globally for the given file.
   @return Non-zero indicates that an incompatible time unit has
           already been set and was not overriden. The caller should
           take special care to write new data into a different file
           then.
 */
F5_API int F5setTimeUnit(hid_t file_id, const F5_TimeParameter*);
 
/**@ingroup bundle
   Get the time unit information as specified in the file.
 */
F5_API int F5getTimeUnit(hid_t file_id, F5_TimeParameter*);
 
/**@ingroup bundle
   Construct the name used for a timeslice, the toplevel hierarchy.
 
  Retrieve the name of the time slice assocciated with the given time.
  The time is specified as a pointer, such that it may be NULL to indicate
  a static dataset.
*/
F5_API  char*F5I_timegroup(const double*time, char*destbuf, size_t len);
 
/**@ingroup bundle
   Append a time slice in the given time unit.
   Only one time unit is allowed per file.
   If another time unit has already been defined in the file,
   the function will return without touching the file.
 */
F5_API hid_t F5Bappend_timeslice(hid_t file_id, const F5_TimeParameter*time);
 
/**\ingroup bundle
   Get the HDF5 identifier for a given time slice.
   A new group is created in the file if none exists yet.
  @param file_id HDF5 File identifier.
  @param time The time is specified as a pointer, such that it may be NULL to indicate
              a static dataset.
  @return HDF5 identifier for the newly created or opened Time Slice group.
   \todo Maybe move to another header.
   @todo Add consistency check on re-open of an existing group
 */
F5_API hid_t F5Bappend_slice(hid_t file_id, const double*time);
 
/**\ingroup bundle
   Initialize an F5Path from a file for reading.
   The coordinate system is set to the default cartesian coordinates.
   No timeslice, grid, field etc. ID's are defined yet, these need
   to be filled in by iteration. This function is called internally
   by F5iterate_timeslices() for creating an F5Path object that
   is then modified to contain a valid group ID for each timeslice,
   grid, field, ...
   Currently, it is hard-coded for reading cartesian coordinates
   only. The preferred way is to employ iterators on reading files.
 */
F5_API F5Path*F5Binitialize_path(hid_t File_id);
 
 
/**\ingroup bundle
   Get the next slice for given time attriute names.
   @deprecated
 */
F5_API hid_t F5BgetMostRecentSlice(double*t, hid_t FileID,
                                   const char**time_attrib_names);
 
/**\ingroup bundle
   Get the MostRecentSlice out of a HDF5 file with the given name.
 */
F5_API hid_t F5BgetMostRecentFileSlice(double t, const char*filename);
 
/**\ingroup bundle
   Get the GridVertexData for given grid-, chart- and fieldnames.
 */
F5_API hid_t F5BgetGridVertexData(hid_t SliceID,
                                  const char*gridname,
                                  const char*chartname,
                                  const char*fieldname);
 
 
 
/** \brief Swap from C array order to Fortran array order and back.
 *
 *  \param dimensions
 *      Number of dimensions.
 *
 *  \param in
 *      Input vector.
 *
 *  \param out
 *      Output vector.
 *
 *  Use it like
\code
    hsize_t c_dims[FIBER_MAX_RANK];
 
    F5order_swap (3, dims, c_dims);
    id = F5Screate_simple (...);
\endcode
 */
F5_API void F5Bswap_dims (int dimensions, const hsize_t* in, hsize_t* out);
 
#ifdef __cplusplus
}
#endif
 
 
#endif /* __F5_Bundle_h */