HDF5¶

Constants¶

HIGHFM_HDF5_CHUNK¶: Set the chunk size for the HDF5 files. This is only applicable for HighFM objects. Default: 1M entries.

HIGHFM_HDF5_COMPRESSION¶: Set the compression level of the HDF5 file. This is only applicable for HighFM objects. Default: 5.

HIGHFM_HDF5_CACHE¶: Set the cache size when reading HighFM objects from HDF5 files. Default: 16 MB.

HIGHFM_HDF5_CACHE_SLOTS¶: Set the number of cache slots when reading HighFM objects from HDF5 files. This should be a prime number. Default: 127.

constexpr hid_t default_flags = H5P_DEFAULT¶: Default HDF5 flags.

constexpr hid_t invalid_id = H5I_INVALID_HID¶: Invalid HDF5 id.

High-Level Interface¶

template<typename ...Args> void read_hdf5(const hdf5::Group &group, Args&&... args)¶

Imports data from a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v;
hdf5::File file("test.h5", "r");
hdf5::Group group = file.root().open("G1");
read_hdf5(group, "mat", A, "vec", v);

This code will read “mat” and “vec” from the group “G1” in the file “test.h5”.

Parameters:

group – [in] a HDF5 group
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to store the data

template<typename ...Args> void read_hdf5(hdf5::File &file, Args&&... args)¶

Imports data from a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v
hdf5::File file("test.h5", "r");
read_hdf5(file, "mat", A, "G1/vec", v);

This code will read “mat” from the file “test.h5” and store into A, and then read “vec” from the group “G1” in the file and store into v.

Parameters:

file – [in] a HDF5 file
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to store the data

template<typename ...Args> void read_hdf5(const std::string &path, Args&&... args)¶

Imports data from a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v;
read_hdf5("path/to/test.h5", "mat", A, "G1/vec", v);

This code will read “mat” from the file “test.h5” and store into A, and then read “vec” from the group “G1” in the file and store into v.

Parameters:

path – [in] path to the HDF5 file
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to store the data

template<typename ...Args> void write_hdf5(const hdf5::Group &group, Args&&... args)¶

Writes data to a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v;
hdf5::File file("test.h5", "w");
hdf5::Group group = file.root().open("G1");
write_hdf5(group, "mat", A, "vec", v);

This code will create_group a file “test.h5” and a group “G1”, and then write A and v as “mat” and “vec” in the group “G1”, respectively.

Parameters:

group – [in] a HDF5 group
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to use as the data source

template<typename ...Args> void write_hdf5(hdf5::File &file, Args&&... args)¶

Writes data to a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v;
hdf5::File file("test.h5", "w");
write_hdf5(file, "mat", A, "G1/vec", v);

This code will create_group a file “test.h5” and then write A as “mat” and v as “vec” in the group “G1”.

Parameters:

file – [in] a HDF5 file
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to use as the data source

template<typename ...Args> void write_hdf5(const std::string &path, Args&&... args)¶

Writes data to a HDF5 file.

Usage:

Matrix<int> A;
Vector<double> v;
io::write_hdf5("/path/to/test.h5", "mat", A, "G1/vec", v);

This code will create_group a file “test.h5” and then write A as “mat” and v as “vec” in the group “G1”.

Parameters:

path – [in] path to the HDF5 file
args – [in] pattern: (“name”, obj, …). Here name specify the name of the variable and obj, the object to use as a data source

File¶

class File¶

An object representing a HDF5 file. This object is only movable, but not copyable to avoid multiple objects pointing to the same file.

There are 4 available modes when opening a file:

r: open for reading (default)
a: open for updating (reading and writing)
w: open for writing, truncating or creating the file first
x: open for exclusive creation, failing if the file already exists

Public Functions

File()¶: Constructs a new empty File.

File(std::string path, char mode = 'r')¶

Construct a new File.

Parameters:

path – [in] path to the HDF5 file
mode – [in] opening mode (optional).

File(File &&other) noexcept¶: Move constructor.

File &operator=(File &&other) noexcept¶: Move assignment.

virtual ~File()¶: Closes the associated file and deletes the File.

inline hid_t id() const¶

Returns:: the HDF5 file identifier.

inline std::string_view path() const¶

Returns:: the path to the HDF5 file.

inline bool is_open() const¶

Returns:: true if the file is already opened.

void open(std::string path, char mode)¶

Opens a HDF5 file. Depending on the mode, this routine will create or truncate the file first.

Parameters:

path – [in] path to the file (optional)
mode – [in] opening mode (optional).

void close()¶: Closes the HDF5 file.

Group root() const¶

Returns:: the “root” of the file.

template<typename T> inline void write_attribute(std::string name, T val) const¶

Set the attribute to be equal to val.

Parameters:

name – [in] name of the attribute
val – [in] value of the attribute

template<typename T> inline T read_attribute(std::string name) const¶

Parameters:: name – [in] name of the attribute
Returns:: the value of the attribute.

void swap(File &other) noexcept¶: Swaps the content between this object and other.

Group¶

class Group¶

An object representing a HDF5 Group within a file or another group. This object is only movable, but not copyable to avoid multiple objects pointing to the same group.

Warning

Group objects should not be constructed explicitly. Instead, use root() method in the File to access the root group. From there, a subgroup can then be created or opened using the create_group() and open methods from the “parent” group, e.g., file.root().open("A").

Public Functions

Group &operator=(Group &&other) noexcept¶: Move Assignment.

virtual ~Group()¶: Closes the associated group and deletes the Group.

void close()¶: Closes the HDF5 group.

inline hid_t id() const¶

Returns:: the HDF5 group identifier.

inline std::string_view path() const¶

Returns:: the path to the HDF5 group.

inline bool is_open() const¶

Returns:: true if the file is already opened.

Group open(const std::string &path) const¶: Opens the group specified by the path. If the group does not exist, creates a new group.

template<typename T> inline void read(const std::string &name, Matrix<T, Host> &mat) const¶

Reads a Matrix object from a HDF5 file.

Parameters:

name – [in] name of the object
mat – [out] Matrix with the contents of the file

template<typename T> inline void read(const std::string &name, Vector<T, Host> &vec) const¶

Reads a Vector object from a HDF5 file.

Parameters:

name – [in] name of the object
vec – [out] Vector with the contents of the file

template<typename T> inline void read(const std::string &name, CSRMatrix<T, Host> &csr_mat) const¶

Reads a CSRMatrix object from a HDF5 file.

Parameters:

name – [in] name of the object
csr_mat – [out] CSRMatrix with the contents of the file

template<typename T> inline void write(const std::string &name, const Matrix<T, Host> &mat) const¶

Writes a Matrix object to a HDF5 file.

Parameters:

name – [in] name of the object
mat – [in] Matrix to use as the data source

template<typename T> inline void write(const std::string &name, const Vector<T, Host> &vec) const¶

Writes a Vector object to a HDF5 file.

Parameters:

name – [in] name of the object
vec – [in] Vector to use as the data source

template<typename T> inline void write(const std::string &name, const CSRMatrix<T, Host> &csr_mat) const¶

Writes a CSRMatrix object to a HDF5 file.

Parameters:

name – [in] name of the object
csr_mat – [in] CSRMatrix to use as the data source

template<typename T> inline void write_attribute(const std::string &name, T val) const¶

Set the attribute to be equal to val.

Parameters:

name – [in] name of the attribute
val – [in] value of the attribute

template<typename T> inline T read_attribute(const std::string &name) const¶

Parameters:: name – [in] name of the attribute
Returns:: the value of the attribute.

void swap(Group &other) noexcept¶

Swap the contents of Group with an other.

Parameters:: other – [in] another Group

Dataset¶

template<typename T> class Dataset¶

An object representing a HDF5 dataset of an Array. This object also stores the associated datatype and dataspace of the container. This object is only movable, but not copyable to avoid multiple objects pointing to the same dataset.

Public Functions

explicit Dataset(const hid_t parent)¶: Constructor.

Dataset(Dataset &&other) noexcept¶: Move constructor.

Dataset &operator=(Dataset &&other) noexcept¶: Move assignment.

virtual ~Dataset()¶: Destructor.

inline hid_t id() const¶

Returns:: the id of the dataset.

inline hid_t dataspace() const¶

Returns:: the id of the associated dataspace.

inline bool is_open() const¶

Returns:: true if the file is already opened.

void close()¶: Closes the HDF5 dataset.

void create(const std::string &name, hsize_t size)¶: Creates a chunked and compressed HDF5 dataset.

void open(const std::string &name)¶: Opens a HDF5 dataset. If it does not exist, creates a new chunked and compressed dataset.

void write(const Array<T, Host> &buffer)¶

Writes the contents of buffer to the dataset.

Parameters:: buffer – [in] data source

void read(Array<T, Host> &buffer)¶

Reads the contents of the Dataset into buffer.

Parameters:: buffer – [out] output container

void write(const DataMap<T, Host> &buffer)¶

Writes the contents of buffer to the dataset.

Parameters:: buffer – [in] data source

void write(const Matrix<T, Host> &mat)¶

Writes the contents of buffer to the dataset.

Parameters:: mat – [in] data source

void read(Matrix<T, Host> &mat)¶

Reads the contents of the Dataset into buffer.

Parameters:: mat – [out] output container

template<typename U> inline void write_attribute(std::string name, U val) const¶

Sets the attribute to be equal to val.

Parameters:

name – [in] name of the attribute
val – [in] value of the attribute

template<typename U> inline U read_attribute(std::string name) const¶

Parameters:: name – [in] name of the attribute
Returns:: the value of the attribute.

void swap(Dataset &other) noexcept¶: Swaps the content between this object and other.