Setting up the Data Model [H5Block C API]

Functions
h5_int64_t	H5Block3dHasView (h5_file_t *const f)
h5_err_t	H5Block3dSetView (h5_file_t *const f, const h5_int64_t i_start, const h5_int64_t i_end, const h5_int64_t j_start, const h5_int64_t j_end, const h5_int64_t k_start, const h5_int64_t k_end)
h5_err_t	H5Block3dGetView (h5_file_t *const f, h5_size_t *i_start, h5_size_t *i_end, h5_size_t *j_start, h5_size_t *j_end, h5_size_t *k_start, h5_size_t *k_end)
h5_err_t	H5Block3dGetReducedView (h5_file_t *const f, h5_size_t *const i_start, h5_size_t *const i_end, h5_size_t *const j_start, h5_size_t *const j_end, h5_size_t *const k_start, h5_size_t *const k_end)
h5_err_t	H5Block3dSetChunk (h5_file_t *const f, const h5_size_t i, const h5_size_t j, const h5_size_t k)
h5_err_t	H5Block3dGetChunk (h5_file_t *const f, const char *field_name, h5_size_t *const i, h5_size_t *const j, h5_size_t *const k)
h5_err_t	H5Block3dSetGrid (h5_file_t *const f, const h5_size_t i, const h5_size_t j, const h5_size_t k)
h5_err_t	H5Block3dGetGridCoords (h5_file_t *const f, const int proc, h5_int64_t *i, h5_int64_t *j, h5_int64_t *k)
h5_err_t	H5Block3dSetDims (h5_file_t *const f, const h5_size_t i, const h5_size_t j, const h5_size_t k)
h5_err_t	H5Block3dSetHalo (h5_file_t *const f, const h5_size_t i, const h5_size_t j, const h5_size_t k)
h5_size_t	H5BlockGetNumFields (h5_file_t *const f)
h5_err_t	H5BlockGetFieldInfo (h5_file_t *const f, const h5_size_t idx, char *name, const h5_size_t len_name, h5_size_t *field_rank, h5_size_t *field_dims, h5_size_t *elem_rank, h5_int64_t *type)
h5_err_t	H5BlockGetFieldInfoByName (h5_file_t *const f, const char *name, h5_size_t *field_rank, h5_size_t *field_dims, h5_size_t *elem_rank, h5_int64_t *type)

---

Function Documentation

h5_int64_t H5Block3dHasView

(

h5_file_t *const

f )

Note:

Different field sizes are allowed in the same time-step.

The same layout can be used, if the size of the field matches the size of the layout. If the size of the layout doesn't match the size of the field, an error will be indicated.

In write mode partitions are shrinked to make them non-overlaping. This process may shrink the partitions more than required.

In read-mode partitions may not cross boundaries. This means, if the grid size is (X, Y, Z), all partitions must fit into this grid.

Todo:

check whether layout is reasonable

API function names

Tests whether a view has been set, either directly with H5Block3dSetView or indirectly with H5Block3dSetGrid.

Returns:

0 on false, 1 on true

Parameters:

f	IN: File handle

h5_err_t H5Block3dSetView	(	h5_file_t *const	f,
		const h5_int64_t	i_start,
		const h5_int64_t	i_end,
		const h5_int64_t	j_start,
		const h5_int64_t	j_end,
		const h5_int64_t	k_start,
		const h5_int64_t	k_end
	)

Defines the partition of the field that this processor owns, using Fortran ordering: the fastest moving index is i.

This routine uses an MPI_Allgather, so at large concurrency it should be called as infrequently as possible. For instance, if several timesteps use the same field dimensions, set the layout only once before the first timestep.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i_start	IN: start index of i
i_end	IN: end index of i
j_start	IN: start index of j
j_end	IN: end index of j
k_start	IN: start index of k
k_end	IN: end index of k

h5_err_t H5Block3dGetView	(	h5_file_t *const	f,
		h5_size_t *	i_start,
		h5_size_t *	i_end,
		h5_size_t *	j_start,
		h5_size_t *	j_end,
		h5_size_t *	k_start,
		h5_size_t *	k_end
	)

Return the view of this processor.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i_start	OUT: start index of i
i_end	OUT: end index of i
j_start	OUT: start index of j
j_end	OUT: end index of j
k_start	OUT: start index of k
k_end	OUT: end index of k

h5_err_t H5Block3dGetReducedView	(	h5_file_t *const	f,
		h5_size_t *const	i_start,
		h5_size_t *const	i_end,
		h5_size_t *const	j_start,
		h5_size_t *const	j_end,
		h5_size_t *const	k_start,
		h5_size_t *const	k_end
	)

Return the reduced (ghost-zone free) view of this processor.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i_start	OUT: start index of i
i_end	OUT: end index of i
j_start	OUT: start index of j
j_end	OUT: end index of j
k_start	OUT: start index of j
k_end	OUT: end index of j

h5_err_t H5Block3dSetChunk	(	h5_file_t *const	f,
		const h5_size_t	i,
		const h5_size_t	j,
		const h5_size_t	k
	)

Define the chunk dimensions and enable chunking in the underlying HDF5 dataset.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i	IN: size of i
j	IN: size of j
k	IN: size of k

h5_err_t H5Block3dGetChunk	(	h5_file_t *const	f,
		const char *	field_name,
		h5_size_t *const	i,
		h5_size_t *const	j,
		h5_size_t *const	k
	)

Lookup the chunk dimensions of the underlying HDF5 dataset.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
field_name	IN: name of dataset
i	OUT: size of i
j	OUT: size of j
k	OUT: size of k

h5_err_t H5Block3dSetGrid	(	h5_file_t *const	f,
		const h5_size_t	i,
		const h5_size_t	j,
		const h5_size_t	k
	)

Define an underlying 3D Cartesian grid on the processors with dimensions (i,j,k). You can look up a processor's index into the grid using H5Block3dGetGridCoords.

This function can be used in conjunction with H5Block3dSetDims to setup the view for a regular grid.

The product of the dimensions must equal the size of the MPI communicator.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i	IN: dimension in i
j	IN: dimension in j
k	IN: dimension in k

h5_err_t H5Block3dGetGridCoords	(	h5_file_t *const	f,
		const int	proc,
		h5_int64_t *	i,
		h5_int64_t *	j,
		h5_int64_t *	k
	)

Look up the index (i, j, k) in the grid belonging to MPI processor proc.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
proc	IN: MPI processor
i	OUT: index in i
j	OUT: index in j
k	OUT: index in k

h5_err_t H5Block3dSetDims	(	h5_file_t *const	f,
		const h5_size_t	i,
		const h5_size_t	j,
		const h5_size_t	k
	)

Set the dimensions of each processor's block when the field is a regular grid.

A grid must be already set with H5Block3dSetGrid, and all processors must specify the same dimensions.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i	IN: dimension in i
j	IN: dimension in j
k	IN: dimension in k

h5_err_t H5Block3dSetHalo	(	h5_file_t *const	f,
		const h5_size_t	i,
		const h5_size_t	j,
		const h5_size_t	k
	)

Sets the additional cells (i, j, k) in each direction to use as the `halo` region (or `ghost zone`) that overlaps between neighboring processors on the grid.

A grid with dimensions must already be set with H5Block3dSetGrid and H5Block3dSetDims, and all processors must specify the same halo radii.

Returns:

H5_SUCCESS on success

Parameters:

f	IN: File handle
i	IN: radius in i
j	IN: radius in j
k	IN: radius in k

h5_size_t H5BlockGetNumFields

(

h5_file_t *const

f )

Query number of fields in current time step.

Returns:

H5_SUCCESS or error code

Parameters:

f	IN: file handle

h5_err_t H5BlockGetFieldInfo	(	h5_file_t *const	f,
		const h5_size_t	idx,
		char *	name,
		const h5_size_t	len_name,
		h5_size_t *	field_rank,
		h5_size_t *	field_dims,
		h5_size_t *	elem_rank,
		h5_int64_t *	type
	)

Get the name, rank and dimensions of the field specified by the index idx.

elem_rank reports the rank of the elements in the field (e.g. scalar or vector).

This function can be used to retrieve all fields bound to the current time-step by looping from 0 to the number of fields minus one. The number of fields bound to the current time-step can be queried by calling the function H5BlockGetNumFields.

Returns:

H5_SUCCESS or error code

Parameters:

f	IN: file handle
idx	IN: index of field
name	OUT: field name
len_name	IN: buffer size
field_rank	OUT: field rank
field_dims	OUT: field dimensions
elem_rank	OUT: element rank
type	OUT: datatype

h5_err_t H5BlockGetFieldInfoByName	(	h5_file_t *const	f,
		const char *	name,
		h5_size_t *	field_rank,
		h5_size_t *	field_dims,
		h5_size_t *	elem_rank,
		h5_int64_t *	type
	)

Get the rank and dimensions of the field specified by its name. See H5BlockGetFieldInfo.

Returns:

H5_SUCCESS or error code

Parameters:

f	IN: file handle
name	IN: field name
field_rank	OUT: field rank
field_dims	OUT: field dimensions
elem_rank	OUT: element rank
type	OUT: datatype