WARNING This documentation is a work in progress and does not reflect the full Decl'HDF5 potential.
The Decl'HDF5 plugin enables one to read and write data from HDF5 files in a declarative way. Decl'HDF5 does not support the full HDF5 feature set but offers a simple declarative interface to access a large subset of it.
At its root, the Decl'HDF5 configuration is made of either a single
FILE_DESC or a list of
FILE_DESC specifies a list of actions to execute in one file. It is specified by a key/value map that contains at least the
file key. Other keys are optional. The possible values for the keys are as follow:
file: a string that can contain $-expressions and specified the name of the file this
FILE_DESC refers to.
DATA_SECTION that defaults to an empty one. This
DATA_SECTION describes writes to execute.
DATA_SECTION that defaults to an empty one. This
DATA_SECTION describes reads to execute.
on_event: a string identifying an event when the whole file is accessed. If not specified, each data is written when it is exposed and the file is opened and closed every time.
when: a $-expression specifying a default condition to test before executing the reads and writes of this
FILE_DESC. This can be replaced by a more specific condition inside the
communicator: a $-expression referencing a MPI communicator to use for HDF5 parallel synchronized reads and writes. It defaults to MPI_COMM_SELF which stands for sequential writes. In case of data-triggered (vs. event-triggered) reads and writes, this can be replaced inside the
datasets: a key-value map associating a PDI type to string keys. Each string is the name of a dataset to create in the file on first access, with the type described in the value.
DATA_SECTION describes a set of I/O (read or write) to execute. A data section can take multiple forms:
data is both a PDI data and the HDF5 dataset name)
# and the name of the dataset or datagroup to which the attribute applies ( e.g.
attr is both a PDI data and the HDF5 attribute name applied to the
DATA_IO_DESC or a list of
DATA_IO_DESCs describing the I/O (read or write) to execute.
The first case behaves as if each data had its
DATA_IO_DESC specified with all default values.
DATA_IO_DESC is a key-velue map describing one I/O (read or write) to execute. All keys are optional and have default values. The possible values for the keys are as follow:
dataset: a $-expression identifying the name of the dataset to access in the file. If not specified this defaults to the name of the data. On writing, if the dataset does not exist in the file and is not specified in the
FILE_DESC then a dataset with the same size as the memory selection is automatically created.
attribute: a $-expression identifying the path of the attribute to access in the file. The path is specified as a
/-separated path to the object on which the attribute is set (a dataset or a datagroup) followed by a
# sign and the name of the attribute itself (e.g.
group/dset#attr). If the
attribute key is specified, then only the
when key can also be specified, no other key can be present.
size_of: a $-expression identifying the path of the dataset that size should be written to data descriptor.
when: a $-expression specifying a condition to test before executing the I/O operation (read or write). This defaults to the value specified in the
FILE_DESC if present or to unconditional I/O otherwise.
communicator: a $-expression referencing a MPI communicator to use for HDF5 parallel synchronized I/O operation (read or write). Specifying communicator at this level is incompatible with event-triggered (vs. data-triggered) This defaults to the value specified in the
FILE_DESC if present or to sequential (MPI_COMM_SELF) I/O otherwise.
SELECTION_DESC specifying the selection of data in memory to read or write. It defaults to selecting the whole data.
SELECTION_DESC specifying the selection of data in the file data to write or read. This is only valid if the
attributes: a key-value map specifying the set of attributes to read from (respectively, write to) the file when the associated dataset is read (respectively, written). Each key is the name of an attribute of the dataset. Each value is a $-expression (evaluated when the dataset is accessed) specifying the value to the attribute.
SELECTION_DESC is a key-value map that describes the selection of a subset of data from a larger set. All keys are optional and have default values. The possible values for the keys are as follow:
size is either a single $-expression or a list of $-expressions. It describes the size of the selection in each dimension. If not specified, it defaults to the dimension of the whole data.
start is either a single $-expression or a list of $-expressions. It describes the number of point to skip in each dimension. If not specified it defaults to 0 in all dimensions. In practice, it can only be specified if
size is also.