hdf5_utils.cu

Documentation for the functions that handle HDF5 file operations.

Functions

Functions

hdf5_blob hdf5_get_blob(const char *name)

Extracts an HDF5 object into an in-memory “blob.” This function uses the HDF5 “CORE” Virtual File Driver (VFD) to create a virtual file in RAM. It then copies an object (dataset or group) from the physical file into this virtual file.

Parameters:: name – The name of the object to extract.
Returns:: hdf5_blob A handle (hid_t) to the new in-memory HDF5 file image.

int hdf5_write_blob(hdf5_blob blob, const char *name)

Writes an in-memory HDF5 blob back to the main file. This function saves the data stored in a temporary RAM-resident HDF5 image into the permanent file structure. It is often used to save processed results or updated datasets that were modified in memory for speed.

Parameters:

blob – The handle (hid_t) to the in-memory HDF5 file image.
name – The target name for the object within the main file.

Returns:

0 on success, or a negative error code on failure.

int hdf5_close_blob(hdf5_blob blob)

Deallocates the in-memory HDF5 blob and releases system RAM.

Because the blob was created using the H5FD_CORE driver, the “file” exists entirely in a memory buffer. Calling this function tells the HDF5 library that the buffer is no longer needed, effectively performing a ‘free()’ operation on that block of memory.

Parameters:: blob – The handle (hid_t) to the in-memory HDF5 file image.
Returns:: 0 on success, or a negative error code on failure.

int hdf5_create(const char *fname)

Creates a new HDF5 file on disk, overwriting any existing file with the same name. This function sets up the environment for writing simulation data. It includes logic for both single-processor and parallel (MPI) environments.

Parameters:: fname – The string containing the path/name of the file to create (e.g., “data.h5”).
Returns:: 0 on success, or a negative error code on failure.

int hdf5_open(const char *fname)

Opens an existing HDF5 file for reading. Unlike hdf5_create, this function expects the file to already exist on disk. It uses the Read-Only flag to protect the data. Like the creation function, it supports parallel access if MPI is enabled.

Parameters:: fname – The path/name of the existing file to open.
Returns:: 0 on success, or a negative error code on failure.

int hdf5_close()

Flushes pending data to disk and closes the physical HDF5 file.

This is a function for data integrity. It forces the operating system to write any remaining “cached” data to the hard drive.

Returns:: 0 on success, or a negative error code on failure.

int hdf5_make_directory(const char *name)

Creates a new HDF5 Group at the current path location. This function builds a hierarchical structure within the file. It does not “move” into the new directory; it simply creates it and then releases the handle.

Parameters:: name – The name of the new group to create.
Returns:: 0 on success, or a negative error code on failure.