Commit 99699d4b authored by gsell's avatar gsell

documentation updated

parent 9df1a577
......@@ -32,34 +32,114 @@ Previous developers:
For more information, please contact the
<a href="mailto:h5part@lists.psi.ch">h5part</a> mailing list.
*/
\defgroup c_api C API
@{
\note The C API is implemented with '\c static \c inline' functions to minimize overhead.
\defgroup h5_c_api H5
@{
\defgroup h5_file File interface
/*!
\defgroup c_api C API
@{
\note The C API is implemented with '\c static \c inline' functions to minimize overhead.
\defgroup h5_c_api H5
@{
\defgroup h5_file file interface
\defgroup h5_model setting up the data model
\defgroup h5_file_attribs reading and writing file attributes
\defgroup h5_step_attribs reading and writing step attributes
\defgroup h5_log control verbosity level
\defgroup h5_debug control debug output
\defgroup h5_error error handling interface
@}
\defgroup h5part_c_api H5Part
@{
\defgroup h5part_model setting up the data model
\defgroup h5part_io reading and writing datasets
@}
\defgroup h5block_c_api H5Block
@{
\defgroup h5block_model setting up the data model
\defgroup h5block_io reading and writing datasets
\defgroup h5block_attrib reading and writing attributes
@}
@}
In this section we document the interface for accessing H5hut files.
\defgroup h5_model Setting up the data model
The fundamental data model of H5hut is pretty simple. There
are (time-)steps to group data, that's it. In this section we
document the interface to these (time-)steps.
\defgroup h5_file_attribs File attributes interface
File attributes are small datasets that can be used to
describe specific properties of a file. The H5hut API provides
functions to attach (write), read and inquire file attributes.
\defgroup h5_step_attribs Step attributes interface
Step attributes are similar to file attributes but are
attached to (time-)steps. They can be used to describe
specific properties of a specific step. The H5hut API provides
functions to attach (write), read and inquire step attributes.
\defgroup h5_attach Attaching files
Sometimes it is required (or at least useful) to attach
additional information to H5hut files. H5hut provides
functions to attach other files to H5hut files. The attached
files can be of any type.
\defgroup h5_log Controlling verbosity level
Controlling the verbosity level of H5hut. By default only
error messages are printed. For debugging it might be helpful
to increase the verbosity level.
\defgroup h5_debug Controlling debug output
Debug output mainly intended for developers.
\defgroup h5_error Error handling interface
H5hut comes with two error handler. The default error handler
prints an error message (which can be suppressed by setting
the verbosity level to \c 0), sets an internal error number
and returns to the calling program with the value \c
H5_FAILURE. It is up to the programmer to handle the error
properly. In certain use-cases it make sense just to abort the
program, so no additional error handling is needed. H5hut
provides an abort error-handler for this use-cases-
@}
\defgroup h5part_c_api H5Part
@{
\defgroup h5part_model Setting up the data model
The H5Part data model interface provides functions to set and
inquire (per core) views on datasets.
\defgroup h5part_io Dataset interface
The dataset interface provides functions to read and write
datasets. The following data types are supported:
- 64-bit floating point numbers (\c h5_float64_t)
- 32-bit floating point numbers (\c h5_float32_t)
- 64-bit integers (\c h5_int64_t)
- 32-bit integers (\c h5_int32_t)
\note Before you can write or read a dataset, you have to
define a "view" on the dataset for each core.
@}
\defgroup h5block_c_api H5Block
@{
\defgroup h5block_model Setting up the data model
The H5Block data model interface provides functions to set and
inquire (per core) views on fields.
\defgroup h5block_io Interface to block structured data
H5Block provides functions to store and retrieve
- 3-dimensional fields with scalar values
- 3-dimensional fields with 3-dimensional vectors as values
The following datatypes are supported:
- 64-bit floating point numbers (\c h5_float64_t)
- 32-bit floating point numbers (\c h5_float32_t)
- 64-bit integers (\c h5_int64_t)
- 32-bit integers (\c h5_int32_t)
\defgroup h5block_attrib Attaching attributes to field data
Field attributes are small datasets that can be used to
describe specific properties of a field like origin, spacing
or coordinates. The H5hut API provides functions to attach
(write), read and inquire file attributes.
@}
@}
*/
/*!
......
This diff is collapsed.
This diff is collapsed.
......@@ -302,99 +302,6 @@ H5Block3dSetHalo (
H5_API_RETURN (h5b_3d_set_halo(f, i, j, k));
}
/**
Query number of fields in current time step.
\return \c number of fields
\return H5_FAILURE on error
*/
static inline h5_ssize_t
H5BlockGetNumFields (
const h5_file_t f ///< [in] file handle.
) {
H5_API_ENTER (h5_ssize_t,
"f=%p",
(h5_file_p)f);
H5_API_RETURN (h5b_get_num_fields(f));
}
/**
Get the name, rank and dimensions of the field specified by the
index \c idx.
\c 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 \c 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 \ref H5BlockGetNumFields.
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5BlockGetFieldInfo (
const h5_file_t f, ///< [in] file handle.
const h5_size_t idx, ///< [in] index of field.
char* name, ///< [out] field name.
const h5_size_t len_name, ///< [in] buffer size.
h5_size_t* field_rank, ///< [out] field rank.
h5_size_t* field_dims, ///< [out] field dimensions.
h5_size_t* elem_rank, ///< [out] element rank.
h5_int64_t* type ///< [out] datatype.
) {
H5_API_ENTER (h5_err_t,
"f=%p, idx=%llu, "
"name=%p, len_name=%llu, "
"field_rank=%p, field_dims=%p, elem_rank=%p, type=%p",
(h5_file_p)f, (long long unsigned)idx,
name, (long long unsigned)len_name,
field_rank, field_dims, elem_rank,
type);
H5_API_RETURN (
h5b_get_field_info (
f,
idx,
name,
len_name,
field_rank,
field_dims,
elem_rank,
type));
}
/**
Get the rank and dimensions of the field specified by its name.
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
\see H5BlockGetFieldInfo.
*/
static inline h5_err_t
H5BlockGetFieldInfoByName (
const h5_file_t f, ///< [in] file handle.
const char* name, ///< [in] field name.
h5_size_t* field_rank, ///< [out] field rank.
h5_size_t* field_dims, ///< [out] field dimensions.
h5_size_t* elem_rank, ///< [out] element rank.
h5_int64_t* type ///< [out] datatype.
) {
H5_API_ENTER (h5_err_t,
"f=%p, name='%s', "
"field_rank=%p, field_dims=%p, elem_rank=%p, type=%p",
(h5_file_p)f, name, field_rank, field_dims, elem_rank, type);
H5_API_RETURN (
h5b_get_field_info_by_name (
f,
name,
field_rank,
field_dims,
elem_rank,
type));
}
#ifdef __cplusplus
}
......
This diff is collapsed.
......@@ -144,125 +144,6 @@ H5PartSetChunkSize (
H5_API_RETURN (h5u_set_chunk (f, size));
}
/**
Get the number of datasets that are stored at the current time-step.
\return number of datasets in current timestep
\return \c H5_FAILURE on error
*/
static inline h5_ssize_t
H5PartGetNumDatasets (
const h5_file_t f ///< [in] file handle.
) {
H5_API_ENTER (h5_err_t,
"f=%p",
(h5_file_p)f);
H5_API_RETURN (h5u_get_num_datasets(f));
}
/**
This reads the name of a dataset specified by it's index in the current
time-step.
If the number of datasets is \c n, the range of \c _index is \c 0 to \c n-1.
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5PartGetDatasetName (
const h5_file_t f, ///< [in] file handle.
const h5_id_t idx, ///< [in] index of the dataset.
char* name, ///< [out] name of dataset.
const h5_size_t len ///< [in] size of buffer \c name.
) {
H5_API_ENTER (h5_err_t,
"f=%p, "
"idx=%lld, "
"name='%p', len=%llu, ",
(h5_file_p)f,
(long long)idx,
name, (unsigned long long)len);
H5_API_RETURN (h5u_get_dataset_info(f, idx, name, len, NULL, NULL));
}
/**
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 values:
- \c H5_FLOAT64_T (for \c h5_float64_t)
- \c H5_FLOAT32_T (for \c h5_float32_t)
- \c H5_INT64_T (for \c h5_int64_t)
- \c H5_INT32_T (for \c h5_int32_t)
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5PartGetDatasetInfo (
const h5_file_t f, ///< [in] file handle.
const h5_id_t idx, ///< [in] index of the dataset.
char* name, ///< [out] name of dataset.
const h5_size_t len_name, ///< [in] size of buffer \c name.
h5_int64_t* type, ///< [out] type of data in dataset.
h5_size_t* nelems ///< [out] number of elements.
) {
H5_API_ENTER (h5_int64_t,
"f=%p, "
"idx=%lld, "
"name='%p', len_name=%llu, "
"type=%p, nelems=%p",
(h5_file_p)f,
(long long)idx,
name, (long long unsigned)len_name,
type, nelems);
H5_API_RETURN (h5u_get_dataset_info (
f, idx, name, len_name, type, nelems));
}
/**
This function returns the number of particles in this processor's view,
if a view has been set.
If not, it returns the total number of particles across all processors
from the last \ref H5PartSetNumParticles() call.
If you have neither set the number of particles
nor set a view, then this returns the total number of
particles in the first data set of the current time step.
Note that H5Part assumes that all data sets within a given time step
have the same number of particles (although the number particles can
vary across time steps).
If none of these conditions are met, an error is thrown.
\return number of elements in datasets in current step.
\return \c H5_FAILURE on error.
*/
static inline h5_ssize_t
H5PartGetNumPoints (
const h5_file_t f ///< [in] file handle.
) {
H5_API_ENTER (h5_ssize_t,
"f=%p",
(h5_file_p)f);
H5_API_RETURN (h5u_get_num_points (f));
}
/**
\see H5PartGetNumPoints()
*/
static inline h5_ssize_t
H5PartGetNumParticles (
const h5_file_t f ///< [in] file handle.
) {
H5_API_ENTER (h5_ssize_t,
"f=%p",
(h5_file_p)f);
H5_API_RETURN (h5u_get_num_points (f));
}
/**
Reset the view.
......
......@@ -8,7 +8,7 @@
!
INTERFACE
!> \addtogroup h5_debug_f
!> \addtogroup h5_debug_fvalue
!! @{
!>
......
......@@ -14,11 +14,6 @@
#include "h5core/h5.h"
#include "h5core/h5_debug.h"
/**
\addtogroup h5_file
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
......@@ -29,6 +24,11 @@ extern "C" {
#define H5OpenFile1 H5OpenFile
#endif
/**
\addtogroup h5_file
@{
*/
/**
Create a new, empty file property list.
......
This diff is collapsed.
......@@ -186,6 +186,14 @@ H5TraverseSteps (
(h5_file_p)f);
H5_API_RETURN (h5_traverse_steps (f));
}
/**
@}
*/
/**
\addtogroup h5_attach
@{
*/
/**
Return number of attached files.
......
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment