H5Part  1.6.6
Functions
Setting up the Data Model
H5Part C API

Functions

h5part_int64_t H5PartSetChunkSize (H5PartFile *f, const h5part_int64_t size)
h5part_int64_t H5PartSetNumParticles (H5PartFile *f, const h5part_int64_t nparticles)
h5part_int64_t H5PartSetNumParticlesStrided (H5PartFile *f, const h5part_int64_t nparticles, const h5part_int64_t stride)
h5part_int64_t H5PartSetStep (H5PartFile *f, const h5part_int64_t step)
h5part_int64_t H5PartHasStep (H5PartFile *f, h5part_int64_t step)
h5part_int64_t H5PartGetNumSteps (H5PartFile *f)
h5part_int64_t H5PartGetNumDatasets (H5PartFile *f)
h5part_int64_t H5PartGetDatasetName (H5PartFile *f, const h5part_int64_t idx, char *name, const h5part_int64_t len_of_name)
h5part_int64_t H5PartGetDatasetInfo (H5PartFile *f, const h5part_int64_t idx, char *dataset_name, const h5part_int64_t len_dataset_name, h5part_int64_t *type, h5part_int64_t *nelem)
h5part_int64_t H5PartGetNumParticles (H5PartFile *f)
h5part_int64_t H5PartResetView (H5PartFile *f)
h5part_int64_t H5PartHasView (H5PartFile *f)
h5part_int64_t H5PartSetView (H5PartFile *f, const h5part_int64_t start, const h5part_int64_t end)
h5part_int64_t H5PartSetViewIndices (H5PartFile *f, const h5part_int64_t *indices, h5part_int64_t nelems)
h5part_int64_t H5PartGetView (H5PartFile *f, h5part_int64_t *start, h5part_int64_t *end)
h5part_int64_t H5PartSetCanonicalView (H5PartFile *f)

Function Documentation

h5part_int64_t H5PartGetDatasetInfo ( H5PartFile *  f,
const h5part_int64_t  idx,
char *  dataset_name,
const h5part_int64_t  len_dataset_name,
h5part_int64_t *  type,
h5part_int64_t *  nelem 
)

Gets the name, type and number of elements of a dataset based on its index in the current timestep.

Type is one of the following macros:

  • H5PART_FLOAT64 (for h5part_float64_t)
  • H5PART_FLOAT32 (for h5part_float32_t)
  • H5PART_INT64 (for h5part_int64_t)
  • H5PART_INT32 (for h5part_int32_t)
  • H5PART_CHAR (for char)
  • H5PART_STRING (for char*)
Returns:
H5PART_SUCCESS
Parameters:
[in]fHandle to open file
[in]idxIndex of the dataset
[out]dataset_nameName of dataset
[in]len_dataset_nameSize of buffer dataset_name
[out]typeType of data in dataset
[out]nelemNumber of elements.
h5part_int64_t H5PartGetDatasetName ( H5PartFile *  f,
const h5part_int64_t  idx,
char *  name,
const h5part_int64_t  len_of_name 
)

This reads the name of a dataset specified by it's index in the current time-step.

If the number of datasets is n, the range of _index is 0 to n-1.

Returns:
H5PART_SUCCESS
Parameters:
[in]fHandle to open file
[in]idxIndex of the dataset
[out]nameName of dataset
[in]len_of_nameSize of buffer name
h5part_int64_t H5PartGetNumDatasets ( H5PartFile *  f)

Get the number of datasets that are stored at the current time-step.

Returns:
number of datasets in current timestep or error code
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartGetNumParticles ( H5PartFile *  f)

This function returns the number of particles in the first dataset of the current timestep (or in the first timestep if none has been set).

If you have neither set the number of particles (read or write) nor set a view (read-only), then this returns the total number of elements on disk of the first dataset if is exists. Otherwise, it returns 0.

If you have set a view, this return the number of particles in the view.

Returns:
number of particles in current timestep or an error code.
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartGetNumSteps ( H5PartFile *  f)

Get the number of time-steps that are currently stored in the file f.

It works for both reading and writing of files, but is probably only typically used when you are reading.

Returns:
number of time-steps or error code
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartGetView ( H5PartFile *  f,
h5part_int64_t *  start,
h5part_int64_t *  end 
)

Allows you to query the current view. Start and End will be -1 if there is no current view established. Use H5PartHasView() to see if the view is smaller than the total dataset.

Returns:
number of elements in the view or error code
Parameters:
[in]fHandle to open file
[out]startStart particle
[out]endEnd particle
h5part_int64_t H5PartHasStep ( H5PartFile *  f,
h5part_int64_t  step 
)

Query whether a particular step already exists in the file f.

Returns:
0 or 1
Parameters:
[in]fHandle to open file
[in]stepStep number to query
h5part_int64_t H5PartHasView ( H5PartFile *  f)
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartResetView ( H5PartFile *  f)
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartSetCanonicalView ( H5PartFile *  f)

If it is too tedious to manually set the start and end coordinates for a view, the H5SetCanonicalView() will automatically select an appropriate domain decomposition of the data arrays for the degree of parallelism and set the "view" accordingly.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
h5part_int64_t H5PartSetChunkSize ( H5PartFile *  f,
const h5part_int64_t  size 
)

Define the chunk size and enables chunking in the underlying HDF5 layer. When combined with the align value in the H5PartOpenFileAlign or H5PartOpenFileParallelAlign function, this causes each group of size particles to be padded on disk out to the nearest multiple of align bytes.

Note that this policy wastes disk space, but can improve write bandwidth on parallel filesystems that are sensitive to alignment to stripe boundaries (e.g. lustre).

Returns:
H5PART_SUCCESS or error code
h5part_int64_t H5PartSetNumParticles ( H5PartFile *  f,
const h5part_int64_t  nparticles 
)

Set the number of particles for the current time-step. After you call this subroutine, all subsequent operations will assume this number of particles will be written.

For the parallel library, the nparticles value is the number of particles that the individual task will write. You can use a different value on different tasks. This function uses an MPI_Allgather call to aggregate each tasks number of particles and determine the appropiate offsets. Because of the use of this MPI collective, it is advisable to call this function as few times as possible when running at large concurrency.

This function assumes that your particles' data fields are in stored in contiguous 1D arrays. For instance, the fields x and y for your particles are stored in separate arrays x[] and y[].

If instead you store your particles as tuples, so that the values are arranged $ x_1,y_1,x_2,y_2$... than you need to setup striding (in this case with value 2) using H5PartSetNumParticlesStrided.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
[in]nparticlesNumber of particles
h5part_int64_t H5PartSetNumParticlesStrided ( H5PartFile *  f,
const h5part_int64_t  nparticles,
const h5part_int64_t  stride 
)

Set the number of particles for the current time-step. After you call this subroutine, all subsequent operations will assume this number of particles will be written.

For the parallel library, the nparticles value is the number of particles that the individual task will write. You can use a different value on different tasks. This function uses an MPI_Allgather call to aggregate each tasks number of particles and determine the appropiate offsets. Because of the use of this MPI collective, it is advisable to call this function as few times as possible when running at large concurrency.

This function assumes that your particles' data fields are stored tuples. For instance, the fields x and y of your particles are arranged $x_1,y_1,x_2,y_2$... in a single data array. In this example, the stride value would be 2.

If you instead have a separate array for each fields, such as x[] and y[], use H5PartSetNumParticles.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
[in]nparticlesNumber of particles
[in]strideStride value (e.g. number of fields in the particle array)
h5part_int64_t H5PartSetStep ( H5PartFile *  f,
const h5part_int64_t  step 
)

Set the current time-step.

When writing data to a file the current time step must be set first (even if there is only one). In write-mode this function creates a new time-step! You are not allowed to step to an already existing time-step. This prevents you from overwriting existing data. Another consequence is, that you must write all data before going to the next time-step.

In read-mode you can use this function to random-access the file for a particular timestep.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
[in]stepTime-step to set.
h5part_int64_t H5PartSetView ( H5PartFile *  f,
const h5part_int64_t  start,
const h5part_int64_t  end 
)

For parallel I/O or for subsetting operations on the datafile, the H5PartSetView() function allows you to define a subset of the total particle dataset to operate on. The concept of "view" works for both serial and for parallel I/O. The "view" will remain in effect until a new view is set, or the number of particles in a dataset changes, or the view is "unset" by calling H5PartSetView(file,-1,-1);

Before you set a view, the H5PartGetNumParticles() will return the total number of particles in the current time-step (even for the parallel reads). However, after you set a view, it will return the number of particles contained in the view.

The range is inclusive: the end value is the last index of the data.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
[in]startStart particle
[in]endEnd particle
h5part_int64_t H5PartSetViewIndices ( H5PartFile *  f,
const h5part_int64_t *  indices,
h5part_int64_t  nelems 
)

For parallel I/O or for subsetting operations on the datafile, this function allows you to define a subset of the total dataset to operate on by specifying a list of indices. The concept of "view" works for both serial and for parallel I/O. The "view" will remain in effect until a new view is set, or the number of particles in a dataset changes, or the view is "unset" by calling H5PartSetViewIndices(NULL,0);

Before you set a view, the H5PartGetNumParticles() will return the total number of particles in the current time-step (even for the parallel reads). However, after you set a view, it will return the number of particles contained in the view.

Returns:
H5PART_SUCCESS or error code
Parameters:
[in]fHandle to open file
[in]indicesList of indices
[in]nelemsSize of list