File I/O with HDF5¶
The class hdf_file facilitates I/O of data to hdf
files. This class implements a simple way to read and write basic data
types and O₂scl data types. All files created by the
o2scl_hdf::hdf_file class are normal HDF5 files, and can
be manipulated in the usual way, for example with h5dump
command-line tool. Users can easily mix code which performs I/O with
o2scl_hdf::hdf_file and other O₂scl functions with their
own HDF code. The caveat is that O₂scl has limited support for parsing
generic HDF5 files, so that HDF files which contain data not output
through O₂scl cannot always be read by O₂scl.
HDF5 files which are written by O₂scl can be viewed and manipulated on
the command line using the acol utility. See The acol Command Line Utility for more information.
Objects are stored by referring to their dataset name. I/O for basic
objects is provided directly in the hdf_file class.
Some classes also provide their own I/O functions named
hdf_output, hdf_input, and hdf_input_n based on the
hdf_file class. Some of the current classes which
provide I/O are hist, hist_2d,
kde_python, prob_dens_mdim_amr, prob_dens_mdim_gaussian, prob_dens_mdim_gmm, table, table_units, table3d, tensor_grid, and uniform_grid.
O₂scl formats complicated data types for HDF I/O by combining basic
data into groups. For that reason, one cannot use O₂scl to read or
write HDF files where groups have the same name as a dataset in the
current HDF id. All O₂scl groups in HDF files come with a fixed-length
string named o2scl_type, which refers to the type of object which
has been written to the HDF file as a group. Once an object of a
particular type is written to an HDF5 file, O₂scl does not support
overwriting an object with the same name but a different type to
the same HDF5 file. O₂scl does support overwriting an object with
different data if it has the same type.
Note
Vector I/O from HDF5 files can be performed directly only if
the vector object provides a pointer to a contiguous chunk
of memory. This works for std::vector objects, because
the C++ standard guarantees this. It is not necessarily
possible for uBlas vector objects (nor desirable for vectors
built upon slices of matrices or tensors), and thus HDF5 I/O
with uBlas vectors or matrices requires an extra copy.
Note
There are some current limitations regarding the matching of error handling policies between O₂scl and the HDF library. HDF functions do not always call the O₂scl error handler and thus do not always throw O₂scl exceptions.
Todo
(Future) Create an HDF file I/O example