Design Concepts for the F5 API

Introduction

The purpose of this page is to explain the ideas and concepts behind the API of the F5 library.

The F5 library is an add-on to the HDF5 library. It guides using HDF5 towards saving and loading data in the F5-data model for scientific data. Core to the concept of the F5 data modeling is casting any kind of suitable data into a hierarchy of five mandatory and two optional levels. These levels are implemented as groups in HDF5.

The F5 library is a convenience library to ease using this data model in HDF5. It does not provide any functionality beyond guidance towards organizing data in HDF5.

The following concepts are central to the design of the F5 library:

1. The F5 library is a C library intentionally as portable as HDF5 itself.
2. The F5 library's API is similar to the HDF5 API.
3. The F5 API does not hide the HDF5 API, but exposes it; HDF5 id's are available and can be used to for specific needs, for instance setting data chunking properties.
4. Use as much of the underlaying HDF5 functionality as possible, i.e., do not try to add functionality that can be provided by HDF5 already.
5. Emulate future functionality of HDF5, but upgrade to use HDF5 for such once available
6. API functions come in three categories:
   1. Internal API - common functions to share logistics within the library
   2. Low-Level API - access to all construction elements (HDF5 identifiers) that participate in the construction of a data set or part thereof
   3. High-Level API - simple, "one-call" functions covering frequently occuring cases.

The F5Path object

The F5Path object is a central data structure containing all HDF5 identifiers describing a path in an HDF5 file towards a field, the final data element in the F5 model:

/Time/Grid/Skeleton/Representation/Field
 hid_t hid_t hid_t   hid_t         hid_t 

It furthermore provides additional meta-information as required for writing field data, in particular it contains a set of HDF5 type identifiers for usage in-memory (transient HDF5 types) and in-file (named HDF5 types).

Examples of the three API category levels:

1. Internal low-level function, operates directly on HDF5 ID's. Functions of this type are intended to be used only internally within the F5 library. Usually there is no need for application code to call these functions. Calling these functions requires detailed knowledge about their parameters. E.g.:

   F5Lwrite(hid_t R_id, const char*fieldname, int dimension,
            const hsize_t*dims, hid_t fieldtype, hid_t memtype,
            const void * dataPtr, hid_t enum_type, hid_t property_id);

2. Generic low-level API function, operating on a F5Path object which gives a unique location of the resulting operation. Via usage of the F5Path object these functions are relatively fail-safe as long as the F5Path object has only been modified via F5 functions itself, e.g.:

   F5Fwrite(F5Path*fpath, const char*fieldname, int dimension,
            hsize_t*dims, hid_t fieldtype, hid_t memtype,
            const void * dataPtr, hid_t property_id)

3. High-level function, writes complex data in one call for a specific scenario, e.g.:

   F5Fwrite_uniform_cartesian3D(hid_t file_id, double time, const char*gridname,
        const F5_vec3_point_t*origin, const F5_vec3_float_t*spacing, hsize_t dims[3],
        const char*fieldname, hid_t fieldtype, const void * dataPtr,
        const Char*coordinate_system,hid_t property_id);

The high-level functions are mostly useful for specific applications, for instance data converters or numerical code providing one special data type. The low-level functions are "building blocks" providing generic functionality; they can be used to add additional features to a specific data type, or to implement type-independent operations. The internal functions should not be used by application code, but they are provided such that new functionality to be added to the F5 library can be tested externally first.

F5F - Field Access Functions

The F5F prefix denotes functions that operate on Fields via F5Path objects. Fields are the final objects in the data model containing actual data.

The F5F functions

1. use the F5Path object to write data to the right location in the HDF5 file
2. handle additional meta-information in HDF5 that are related to Fields
3. perform additional semantic checks beyond HDF5 itself to ensure consistency of dataspace and with the F5 model

Fragmentation of fields is an optional property, therefore there are no dedicated fragmentation-specific functions. The "fragment" property is passed to F5F functions via an optional string (char*) containing the fragment name. If the fragment name is a null pointer, then the F5F function will operate on an unfragmented field.

F5L - Low-Level Functions

Functions of this group merely uses HDF5 identifiers, no additional data structures. In particular, they don't know about the F5Path object. These functions create HDF5 datasets with attributes as required by F5 for proper identification. The Caller must know the exact location where to place which data set.

Groups of Functions

1. F5R - Functions that deal with Representation objects
2. F5B - Functions that deal with Bundle objects and their properties, such as the semantic of time
3. F5T - Functions that deal with Topology (aka Skeleton) objects
4. F5LT - Low-Level functions dealing with Topology objects
5. F5uniform, F5AMR, F5image, F5particles, F5surface - Functions providing simple API calls for specific data types dealing with uniform grids, adaptive mesh refinement, particles and surfaces.