Description

template<typename ValueType>
class gmx::H5mdFrameDataSet< ValueType >

Class which provides an interface for reading and writing frame data to H5mdDataSet objects.

Can be made either by opening an existing data set via its name within a container or from a base H5mdDataSetBase object created by H5mdFrameDataSetBuilder.

The data set dimensions and templated type is checked to confirm that it describes framed data. In practice this affirms:

That the data set has at least 1 dimension (for frames).
For non-primitive types that the remaining dimensions can store the data in row-major order (e.g. for RVecs the data set dimensions must be [numFrames][...][3] where middle [...] may be one or more dimensions for the frame).

The full data set dimensions of the managed HDF5 data set is for the storage layout of primitive data in the set in row-major order, where the outer dimension (0) is for frame indexing. This function returns the dimensions of a single frame of the data set.

For a 1d data set of dimensions [30] the frame dimension is [] (each frame is a single value). For a 3d data set of size [30, 50, 3] the frame dimension is [50, 3].

Note: For compound types such as BasicVector<float> which consists of 3 floats the frame dimension is slightly more complex. A data set which was created to store 30 frames, each storing 50 BasicVector<float> values has an actual dimension of [30, 50, 3] and the frame dimension returned by this function is [50].

I/O methods for this class use 1d ArrayRef buffers of ValueType. The size of the input buffers is checked before the read or write operation. frameDims() is used to get the shape of each frame in terms of ValueType and is used to allocate memory for these buffers.

Template Parameters

ValueType Type of values stored in data set (not limited to base primitives).

Public Types
using	Base = H5mdDataSetBase< ValueType >

Public Member Functions
	H5mdFrameDataSet (H5mdDataSetBase< ValueType > &&dataSet)
	Constructor to manage a given `dataSet`.

	H5mdFrameDataSet (hid_t container, const char *name)
	Constructor to open an existing data set (called `name`, in `container`).

	~H5mdFrameDataSet () noexcept
	Destructor.

	H5mdFrameDataSet (H5mdFrameDataSet< ValueType > &&) noexcept
	Move constructor.

H5mdFrameDataSet &	operator= (H5mdFrameDataSet< ValueType > &&) noexcept
	Move assignment.

const DataSetDims &	frameDims () const
	Return the dimensions of a single frame of the templated type in data set. More...

hsize_t	numFrames () const noexcept
	Return the number of frames in the data set. More...

void	readFrame (hsize_t index, ArrayRef< ValueType > values)
	Read data from frame at `index` into `values`. More...

void	writeNextFrame (ArrayRef< const ValueType > values)
	Write data from `values` into the next frame. More...

Member Function Documentation

template<typename ValueType >

const DataSetDims & gmx::H5mdFrameDataSet< ValueType >::frameDims ( ) const

Return the dimensions of a single frame of the templated type in data set.

The full data set dimensions of the managed HDF5 data set is for the storage layout of primitive data in the set in row-major order, where the outer dimension (0) is for frame indexing. This function returns the dimensions of a single frame of the data set.

For a 1d data set of dimensions [30] the frame dimension is []. For a 3d data set of size [30, 50, 3] the frame dimension is [50, 3].

Note: For compound types such as BasicVector<float> which consists of 3 floats the frame dimension is slightly more complex. A data set which was created to store 30 frames, each storing 50 BasicVector<float> values has an actual dimension of [30, 50, 3] and the frame dimension returned by this function is [50].

template<typename ValueType >

hsize_t gmx::H5mdFrameDataSet< ValueType >::numFrames ( ) const

noexcept

Return the number of frames in the data set.

Number of frames refers to the size of the major axis of the data set. For example, a 1d data set with dimensions [30] obviously has 30 frames. A 3d data set with dimensions [30, 150, 3] also has 30 frames.

template<typename ValueType>

void gmx::H5mdFrameDataSet< ValueType >::readFrame	(	hsize_t	index,
		ArrayRef< ValueType >	values
	)

Read data from frame at index into values.

The output buffer values must have a size which is identical to the size of a single frame in the data set as described by frameDims().

For a 1d data set of size [30] the frame dimension is scalar, so values must store a single value of the base type. For a 3d data set of size [30, 50, 3] the frame dimension is [50, 3] so values must be of type ArrayRef<ValueType> with size 150.

Note: For compound types such as BasicVector<float> which consists of 3 floats the frame dimension is slightly more complex. A data set which was created to store 30 frames, each storing 50 BasicVector<float> values has an actual dimension of [30, 50, 3] and the frame dimension is [50]. Thus values must be of type ArrayRef<BasicVector<float>> and store exactly 50 values.

Parameters

[in]	index	Frame index to read data from.
[out]	values	Container of values to read data into.

Exceptions

gmx::FileIOError if the size of values does not match the frame dimensions or if an error occurred when reading the data.

template<typename ValueType>

void gmx::H5mdFrameDataSet< ValueType >::writeNextFrame ( ArrayRef< const ValueType > values )

Write data from values into the next frame.

The input buffer values must have a size which is identical to the size of a single frame in the data set as described by frameDims().

For a 1d data set of size [30] the frame dimension is scalar, so values must store a single value of the base type. For a 3d data set of size [30, 50, 3] the frame dimension is [50, 3] so values must be of type ArrayRef<const ValueType> with size 150.

Note: For compound types such as BasicVector<float> which consists of 3 floats the frame dimension is slightly more complex. A data set which was created to store 30 frames, each storing 50 BasicVector<float> values has an actual dimension of [30, 50, 3] and the frame dimension is [50]. Thus values must be of type ArrayRef<BasicVector<float>> and store exactly 50 values.; HDF5 data sets have a maximum extent which is set when the data set is created. We cannot write a new frame if the maximum extent along the frame axis has been reached. This is by default set to be unlimited for data sets created with H5mdFrameDataSetBuilder, in which case there is no limit on the amount of frames we can write (only the available disk space will limit the number of frames).

Parameters

[in] values Container of values to write.

Exceptions

gmx::FileIOError if the size of values does not match the frame dimensions, if the maximum number of frames set for the data set has already been written, or if another error occurred when writing the data.

The documentation for this class was generated from the following files:

src/gromacs/fileio/h5md/h5md_framedataset.h
src/gromacs/fileio/h5md/h5md_framedataset.cpp

Description

template<typename ValueType> class gmx::H5mdFrameDataSet< ValueType >

Public Types

Public Member Functions

Member Function Documentation

template<typename ValueType>
class gmx::H5mdFrameDataSet< ValueType >