The Dataspace Interface (H5S)

1. Introduction

A dataspace describes the locations that dataset elements are located at. A dataspace is either a regular N-dimensional array of data points, called a simple dataspace, or a more general collection of data points organized in another manner, called a complex dataspace. A scalar dataspace is a special case of the simple data space and is defined to be a 0-dimensional single data point in size. Currently only scalar and simple dataspaces are supported with this version of the H5S interface. Complex dataspaces will be defined and implemented in a future version. Complex dataspaces are intended to be used for such structures which are awkward to express in simple dataspaces, such as irregularly gridded data or adaptive mesh refinement data. This interface provides functions to set and query properties of a dataspace.

Operations on a dataspace include defining or extending the extent of the dataspace, selecting portions of the dataspace for I/O and storing the dataspaces in the file. The extent of a dataspace is the range of coordinates over which dataset elements are defined and stored. Dataspace selections are subsets of the extent (up to the entire extent) which are selected for some operation.

For example, a 2-dimensional dataspace with an extent of 10 by 10 may have the following very simple selection:

Selections within dataspaces have an offset within the extent which is used to locate the selection within the extent of the dataspace. Selection offsets default to 0 in each dimension, but may be changed to move the selection within a dataspace. In example 2 above, if the offset was changed to 1,1, the selection would look like this:

Selections also have a linearization ordering of the points selected (defaulting to "C" order, ie. last dimension changing fastest). The linearization order may be specified for each point or it may be chosen by the axis of the dataspace. For example, with the default "C" ordering, example 1's selected points are iterated through in this order: (1,1), (1,2), (1,3), (2,1), (2,2), etc. With "FORTRAN" ordering, example 1's selected points would be iterated through in this order: (1,1), (2,1), (3,1), (4,1), (5,1), (1,2), (2,2), etc.

A dataspace may be stored in the file as a permanent object, to allow many datasets to use a commonly defined dataspace. Dataspaces with extendable extents (ie. unlimited dimensions) are not able to be stored as permanent dataspaces.

Dataspaces may be created using an existing permanent dataspace as a container to locate the new dataspace within. These dataspaces are complete dataspaces and may be used to define datasets. A dataspaces with a "parent" can be queried to determine the parent dataspace and the location within the parent. These dataspaces must currently be the same number of dimensions as the parent dataspace.

2. General Dataspace Operations

hid_t H5Screate(H5S_class_t type)

This function creates a new dataspace of a particular type. The types currently supported are H5S_SCALAR and H5S_SIMPLE; others are planned to be added later.

hid_t H5Scopy (hid_t space)

This function creates a new dataspace which is an exact copy of the dataspace space.

herr_t H5Sclose (hid_t space)

Releases resources associated with a dataspace. Subsequent use of the dataspace identifier after this call is undefined.

3. Dataspace Extent Operations

herr_t H5Sset_extent_simple (hid_t space, int rank, const hsize_t *current_size, const hsize_t *maximum_size)

Sets or resets the size of an existing dataspace, where rank is the dimensionality, or number of dimensions, of the dataspace. current_size is an array of size rank which contains the new size of each dimension in the dataspace. maximum_size is an array of size rank which contains the maximum size of each dimension in the dataspace. Any previous extent is removed from the dataspace, the dataspace type is set to H5S_SIMPLE and the extent is set as specified.

herr_t H5Sset_extent_none (hid_t space)

Removes the extent from a dataspace and sets the type to H5S_NO_CLASS.

herr_t H5Sextent_copy (hid_t dest_space, hid_t source_space)

Copies the extent from source_space to dest_space, which may change the type of the dataspace. Returns non-negative on success, negative on failure.

hsize_t H5Sget_simple_extent_npoints (hid_t space)

This function determines the number of elements in a dataspace. For example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 would have 24 elements. Returns the number of elements in the dataspace, negative on failure.

int H5Sget_simple_extent_ndims (hid_t space)

This function determines the dimensionality (or rank) of a dataspace. Returns the number of dimensions in the dataspace, negative on failure.

herr_t H5Sget_simple_extent_dims (hid_t space, hsize_t *dims, hsize_t *max)

The function retrieves the size of the extent of the dataspace space by placing the size of each dimension in the array dims. Also retrieves the size of the maximum extent of the dataspace, placing the results in max. Returns non-negative on success, negative on failure.

4. Dataspace Selection Operations

herr_t H5Sselect_hyperslab (hid_t space, h5s_seloper_t op, const hssize_t * start, const hsize_t * stride, const hsize_t * count, const hsize_t * block)

This function selects a hyperslab region to add to the current selected region for the space dataspace. The start, stride, count and block arrays must be the same size as the rank of the dataspace. The selection operator op determines how the new selection is to be combined with the already existing selection for the dataspace. Currently, The following operators are supported:

H5S_SELECT_SET	Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator.
H5S_SELECT_OR	Adds the new selection to the existing selection.

The start array determines the starting coordinates of the hyperslab to select. The stride array chooses array locations from the dataspace with each value in the stride array determining how many elements to move in each dimension. Setting a value in the stride array to 1 moves to each element in that dimension of the dataspace, setting a value of 2 in a location in the stride array moves to every other element in that dimension of the dataspace. In other words, the stride determines the number of elements to move from the start location in each dimension. Stride values of 0 are not allowed. If the stride parameter is NULL, a contiguous hyperslab is selected (as if each value in the stride array was set to all 1's). The count array determines how many blocks to select from the dataspace, in each dimension. The block array determines the size of the element block selected from the dataspace. If the block parameter is set to NULL, the block size defaults to a single element in each dimension (as if the block array was set to all 1's).

For example, in a 2-dimensional dataspace, setting start to [1,1], stride to [4,4], count to [3,7] and block to [2,2] selects 21 2x2 blocks of array elements starting with location (1,1) and selecting blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.

Regions selected with this function call default to 'C' order iteration when I/O is performed.

herr_t H5Sselect_elements (hid_t space, h5s_seloper_t op, const size_t num_elements, const hssize_t *coord[])

This function selects array elements to be included in the selection for the space dataspace. The number of elements selected must be set with the num_elements. The coord array is a two-dimensional array of size <dataspace rank> by <num_elements> in size (ie. a list of coordinates in the array). The order of the element coordinates in the coord array also specifies the order that the array elements are iterated through when I/O is performed. Duplicate coordinate locations are not checked for.

The selection operator op determines how the new selection is to be combined with the already existing selection for the dataspace. The following operators are supported:

H5S_SELECT_SET	Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator.
H5S_SELECT_OR	Adds the new selection to the existing selection.

When operators other than H5S_SELECT_SET are used to combine a new selection with an existing selection, the selection ordering is reset to 'C' array ordering.

herr_t H5Sselect_all (hid_t space)

This function selects the special H5S_SELECT_ALL region for the space dataspace. H5S_SELECT_ALL selects the entire dataspace for any dataspace is is applied to.

herr_t H5Sselect_none (hid_t space)

This function resets the selection region for the space dataspace not to include any elements.

htri_t H5Sselect_valid (hid_t space)

This function verifies that the selection for a dataspace is within the extent of the dataspace, if the currently set offset for the dataspace is used. Returns TRUE if the selection is contained within the extent, FALSE if it is not contained within the extent and FAIL on error conditions (such as if the selection or extent is not defined).

hsize_t H5Sget_select_npoints (hid_t space)

This function determines the number of elements in the current selection of a dataspace.

herr_t H5Soffset_simple (hid_t space, const hssize_t * offset)

Sets the offset of a simple dataspace space. The offset array must be the same number of elements as the number of dimensions for the dataspace. If the offset array is set to NULL, the offset for the dataspace is reset to 0.

5. Convenience Dataspace Operation

hid_t H5Screate_simple(int rank, const hsize_t *current_size, const hsize_t *maximum_size)

This function is a "convenience" wrapper to create a simple dataspace and set it's extent in one call. It is equivalent to calling H5Screate and H5Sset_extent_simple() in two steps.