Commit 91316f31 authored by gsell's avatar gsell

src/include/*:

- update/review documentation
- re-introduce old API functions
parent 538c9cdd
......@@ -1958,7 +1958,7 @@ PERLMOD_MAKEVAR_PREFIX =
# C-preprocessor directives found in the sources and include files.
# The default value is: YES.
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES
# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
# in the source code. If set to NO, only conditional compilation will be
......@@ -1967,7 +1967,7 @@ ENABLE_PREPROCESSING = NO
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
......@@ -2007,7 +2007,8 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED = PARALLEL_IO
PREDEFINED = PARALLEL_IO \
H5HUT_API_VERSION=2
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
......
......@@ -45,12 +45,12 @@ For more information, please contact the
\defgroup h5hut_error error handling
@}
\defgroup h5hut_c_api H5
\defgroup h5_c_api H5
@{
\defgroup h5hut_file file handling
\defgroup h5hut_model setting up the data model
\defgroup h5hut_file_attribs reading and writing file attributes
\defgroup h5hut_step_attribs reading and writing step attributes
\defgroup h5_file file handling
\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 h5part_c_api H5Part
@{
......
This diff is collapsed.
......@@ -16,14 +16,18 @@
#include "h5core/h5.h"
#include "h5core/h5_debug.h"
#include "h5core/h5b_attribs.h"
/**
\ingroup h5block_c_api
\addtogroup h5block_attrib
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
\ingroup h5block_attrib
\anchor H5BlockGetNumFieldAttribs
Query the number of attributes of field \c field_name.
\return number of attributes
......@@ -41,9 +45,6 @@ H5BlockGetNumFieldAttribs (
}
/**
\ingroup h5block_attrib
\anchor H5BlockGetFieldAttribInfo
Gets the name, type and number of elements of the field attribute
specified by its index.
......@@ -91,9 +92,6 @@ H5BlockGetFieldAttribInfo (
/********************** reading and writing attribute ************************/
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribString
Write the string in \c buffer as attribute \c attrib_name of field
\c field_name.
......@@ -127,9 +125,6 @@ H5BlockWriteFieldAttribString (
}
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribString (
Read the string value from attribute \c attrib_name of field
\c field_name into \c buffer.
......@@ -163,9 +158,6 @@ H5BlockReadFieldAttribString (
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribFloat64
Write float64 \c values as attribute \c attrib_name of field
\c field_name.
......@@ -195,9 +187,6 @@ H5BlockWriteFieldAttribFloat64 (
}
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribFloat64
Read float64 values from attribute \c attrib_name of field
\c field_name into a \c buffer.
......@@ -225,9 +214,6 @@ H5BlockReadFieldAttribFloat64 (
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribFloat32
Write float32 \c values as attribute \c attrib_name of field
\c field_name.
......@@ -257,9 +243,6 @@ H5BlockWriteFieldAttribFloat32 (
}
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribFloat32
Read float32 values from attribute \c attrib_name of field
\c field_name into a \c buffer.
......@@ -286,9 +269,6 @@ H5BlockReadFieldAttribFloat32 (
}
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribInt64
Write int64 \c values as attribute \c attrib_name of field
\c field_name.
......@@ -317,9 +297,6 @@ H5BlockWriteFieldAttribInt64 (
}
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribInt64
Read int64 values from attribute \c attrib_name of field
\c field_name into a \c buffer.
......@@ -347,9 +324,6 @@ H5BlockReadFieldAttribInt64 (
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribInt32
Write int32 \c values as attribute \c attrib_name of field
\c field_name.
......@@ -379,9 +353,6 @@ H5BlockWriteFieldAttribInt32 (
}
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribInt32
Read int32 values from attribute \c attrib_name of field
\c field_name into a \c buffer.
......@@ -407,9 +378,6 @@ H5BlockReadFieldAttribInt32 (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dGetFieldOrigin
Get field origin.
\return \c H5_SUCCESS on success
......@@ -443,9 +411,6 @@ H5Block3dGetFieldOrigin (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dSetFieldOrigin
Set field origin.
\return \c H5_SUCCESS on success
......@@ -473,9 +438,6 @@ H5Block3dSetFieldOrigin (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dGetFieldSpacing
Get field spacing for field \c field_name in the current time step.
\return \c H5_SUCCESS on success
......@@ -507,9 +469,6 @@ H5Block3dGetFieldSpacing (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dSetFieldSpacing
Set field spacing for field \c field_name in the current time step.
\return \c H5_SUCCESS on success
......@@ -537,9 +496,6 @@ H5Block3dSetFieldSpacing (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dSetFieldXCoords
Set an explicit list of X coordinates for field \c field_name in the current
time step. The coordinates are a 1D array of floating point values with
dimension \c n_coords.
......@@ -571,9 +527,6 @@ H5Block3dSetFieldXCoords (
/**
\ingroup h5block_attrib
\anchor H5Block3dGetFieldXCoords
Get the explicit list of X coordinates for field \c field_name in the current
time step. The coordinates are read into the 1D array \c coords which has
length \c n_coords.
......@@ -604,9 +557,6 @@ H5Block3dGetFieldXCoords (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dSetFieldYCoords
Set an explicit list of Y coordinates for field \c field_name in the current
time step. The coordinates are a 1D array of floating point values with
dimension \c n_coords.
......@@ -638,9 +588,6 @@ H5Block3dSetFieldYCoords (
/**
\ingroup h5block_attrib
\anchor H5Block3dGetFieldYCoords
Get the explicit list of Y coordinates for field \c field_name in the current
time step. The coordinates are read into the 1D array \c coords which has
length \c n_coords.
......@@ -671,9 +618,6 @@ H5Block3dGetFieldYCoords (
}
/**
\ingroup h5block_attrib
\anchor H5Block3dSetFieldZCoords
Set an explicit list of Z coordinates for field \c field_name in the current
time step. The coordinates are a 1D array of floating point values with
dimension \c n_coords.
......@@ -705,9 +649,6 @@ H5Block3dSetFieldZCoords (
/**
\ingroup h5block_attrib
\anchor H5Block3dGetFieldZCoords
Get the explicit list of Z coordinates for field \c field_name in the current
time step. The coordinates are read into the 1D array \c coords which has
length \c n_coords.
......@@ -741,4 +682,6 @@ H5Block3dGetFieldZCoords (
}
#endif
///< @}
#endif
......@@ -15,13 +15,17 @@
#include "h5core/h5_debug.h"
#include "h5core/h5b_io.h"
/**
\ingroup h5block_c_api
\addtogroup h5block_io
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
\ingroup h5block_io
Attempts to write the 3-dimensional field \p name from the
buffer pointed to by \p buffer to the current step using the
previously defined field view.
......@@ -48,9 +52,6 @@ H5Block3dWriteScalarFieldFloat64 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadScalarFieldFloat64
Read a 3-dimensional field \c name into the buffer starting at \c data from
the current time-step using the defined field layout. Values are
floating points (64-bit).
......@@ -74,9 +75,6 @@ H5Block3dReadScalarFieldFloat64 (
}
/**
\ingroup h5block_io
\anchor H5Block3dWriteVector3dFieldFloat64
Write a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -104,9 +102,6 @@ H5Block3dWriteVector3dFieldFloat64 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadVector3dFieldFloat64
Read a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -135,9 +130,6 @@ H5Block3dReadVector3dFieldFloat64 (
/**
\ingroup h5block_io
\anchor H5Block3dWriteScalarFieldFloat32
Write a 3-dimensional field \c name from the buffer starting at \c data
to the current time-step using the defined field layout. Values are
floating points (32-bit).
......@@ -161,9 +153,6 @@ H5Block3dWriteScalarFieldFloat32 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadScalarFieldFloat32
Read a 3-dimensional field \c name into the buffer starting at \c data from
the current time-step using the defined field layout. Values are
floating points (32-bit).
......@@ -187,9 +176,6 @@ H5Block3dReadScalarFieldFloat32 (
}
/**
\ingroup h5block_io
\anchor H5Block3dWriteVector3dFieldFloat32
Write a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -217,9 +203,6 @@ H5Block3dWriteVector3dFieldFloat32 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadVector3dFieldFloat32
Read a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -248,9 +231,6 @@ H5Block3dReadVector3dFieldFloat32 (
/**
\ingroup h5block_io
\anchor H5Block3dWriteScalarFieldInt64
Write a 3-dimensional field \c name from the buffer starting at \c data
to the current time-step using the defined field layout. Values are
integers (64-bit).
......@@ -274,9 +254,6 @@ H5Block3dWriteScalarFieldInt64 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadScalarFieldInt64
Read a 3-dimensional field \c name into the buffer starting at \c data from
the current time-step using the defined field layout. Values are
integers (64-bit).
......@@ -301,9 +278,6 @@ H5Block3dReadScalarFieldInt64 (
/**
\ingroup h5block_io
\anchor H5Block3dWriteVector3dFieldInt64
Write a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -331,9 +305,6 @@ H5Block3dWriteVector3dFieldInt64 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadVector3dFieldInt64
Read a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -362,9 +333,6 @@ H5Block3dReadVector3dFieldInt64 (
/**
\ingroup h5block_io
\anchor H5Block3dWriteScalarFieldInt32
Write a 3-dimensional field \c name from the buffer starting at \c data
to the current time-step using the defined field layout. Values are
integers (32-bit).
......@@ -388,9 +356,6 @@ H5Block3dWriteScalarFieldInt32 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadScalarFieldInt32
Read a 3-dimensional field \c name into the buffer starting at \c data from
the current time-step using the defined field layout. Values are
integers (32-bit).
......@@ -415,9 +380,6 @@ H5Block3dReadScalarFieldInt32 (
/**
\ingroup h5block_io
\anchor H5Block3dWriteVector3dFieldInt32
Write a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -445,9 +407,6 @@ H5Block3dWriteVector3dFieldInt32 (
}
/**
\ingroup h5block_io
\anchor H5Block3dReadVector3dFieldInt32
Read a 3-dimensional field \c name with 3-dimensional vectors as values
from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the
current time-step using the defined field layout. Values are 3-dimensional
......@@ -474,9 +433,10 @@ H5Block3dReadVector3dFieldInt32 (
x_buf, y_buf, z_buf, H5T_NATIVE_INT32));
}
#ifdef __cplusplus
}
#endif
///< @}
#endif
......@@ -15,6 +15,12 @@
#include "h5core/h5_debug.h"
#include "h5core/h5b_model.h"
/**
\ingroup h5block_c_api
\addtogroup h5block_model
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
......@@ -22,14 +28,11 @@ extern "C" {
/********************** defining the layout **********************************/
/**
\ingroup h5block_model
\anchor H5BlockHasFieldData
Checks whether the current time-step has field data or not.
\return \c H5_OK if field data is available
\return \c H5_NOK if no field data is available
\return \c H5_FAILURE on error
\return true (value \c >0) if step exists
\return false (\c 0) if step does not exist
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5BlockHasFieldData (
......@@ -42,15 +45,12 @@ H5BlockHasFieldData (
}
/**
\ingroup h5block_model
\anchor H5Block3dHasView
Tests whether a view has been set, either directly with
\ref H5Block3dSetView or indirectly with \ref H5Block3dSetGrid.
\return \c H5_OK if field data is available
\return \c H5_NOK if no field data is available
\return \c H5_FAILURE on error
\return true (value \c >0) if step exists
\return false (\c 0) if step does not exist
\return \c H5_FAILURE on error
*/
static inline h5_int64_t
H5Block3dHasView (
......@@ -63,9 +63,6 @@ H5Block3dHasView (
}
/**
\ingroup h5block_model
\anchor H5Block3dSetView
Defines the partition of the field that this processor owns, using
Fortran ordering: the fastest moving index is \c i.
......@@ -103,8 +100,6 @@ H5Block3dSetView (
}
/**
\ingroup h5block_model
\anchor H5Block3dGetView
Return the view of this processor.
\return \c H5_SUCCESS on success
......@@ -133,9 +128,6 @@ H5Block3dGetView (
}
/**
\ingroup h5block_model
\anchor H5Block3dGetReducedView
Return the reduced (ghost-zone free) view of this processor.
\return \c H5_SUCCESS on success
......@@ -164,9 +156,6 @@ H5Block3dGetReducedView (
}
/**
\ingroup h5block_model
\anchor H5Block3dSetChunkSize
Define the chunk dimensions and enable chunking in the underlying
HDF5 dataset.
......@@ -190,9 +179,6 @@ H5Block3dSetChunkSize (
}
/**
\ingroup h5block_model
\anchor H5Block3dGetChunkSize
Lookup the chunk dimensions of the underlying HDF5 dataset.
\return \c H5_SUCCESS on success
......@@ -214,9 +200,6 @@ H5Block3dGetChunkSize (
#ifdef PARALLEL_IO
/**
\ingroup h5block_model
\anchor H5Block3dSetGrid
Define an underlying 3D Cartesian grid on the processors with dimensions
(\c i,\c j,\c k). You can look up a processor's index into the grid
using \ref H5Block3dGetGridCoords.
......@@ -246,9 +229,6 @@ H5Block3dSetGrid (
}
/**
\ingroup h5block_model
\anchor H5Block3dGetGridCoords
Look up the index (\c i, \c j, \c k) in the grid belonging to MPI processor
\c proc.
......@@ -270,9 +250,6 @@ H5Block3dGetGridCoords (
}
/**
\ingroup h5block_model
\anchor H5Block3dSetDims
Set the dimensions of each processor's block when the field is a regular
grid.
......@@ -300,9 +277,6 @@ H5Block3dSetDims (
#endif
/**
\ingroup h5block_model
\anchor H5Block3dSetHalo
Sets the additional cells (\c i, \c j, \c k) in each direction to use as
the `halo` region (or `ghost zone`) that overlaps between neighboring
processors on the grid.
......@@ -330,9 +304,6 @@ H5Block3dSetHalo (
}
/**
\ingroup h5block_model
\anchor H5BlockGetNumFields
Query number of fields in current time step.
\return \c number of fields
......@@ -350,9 +321,6 @@ H5BlockGetNumFields (
/**
\ingroup h5block_model
\anchor H5BlockGetFieldInfo
Get the name, rank and dimensions of the field specified by the
index \c idx.
......@@ -399,9 +367,6 @@ H5BlockGetFieldInfo (
}
/**
\ingroup h5block_model
\anchor H5BlockGetFieldInfoByName
Get the rank and dimensions of the field specified by its name.
\return \c H5_SUCCESS on success
......@@ -432,6 +397,8 @@ H5BlockGetFieldInfoByName (
type));
}
///< @}
#ifdef __cplusplus
}
#endif
......
......@@ -15,13 +15,17 @@
#include "h5core/h5_debug.h"
#include "h5core/h5u_io.h"
/**
\ingroup h5part_c_api
\addtogroup h5part_io
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
\ingroup h5part_io
Write array of 64 bit floating point data to file.
After setting the number of elements with \c H5PartSetNumParticles() and
......@@ -59,8 +63,6 @@ H5PartWriteDataFloat64 (
}
/**
\ingroup h5part_io
Write array of 32 bit floating point data to file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -81,8 +83,6 @@ H5PartWriteDataFloat32 (
}
/**
\ingroup h5part_io
Write array of 64 bit integer data to file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -103,8 +103,6 @@ H5PartWriteDataInt64 (
}
/**
\ingroup h5part_io
Write array of 32 bit integer data to file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -125,8 +123,6 @@ H5PartWriteDataInt32 (
}
/**
\ingroup h5part_io
Read array of 64 bit floating point data from file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -147,8 +143,6 @@ H5PartReadDataFloat64 (
}
/**
\ingroup h5part_io
Read array of 32 bit floating point data from file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -169,8 +163,6 @@ H5PartReadDataFloat32 (
}
/**
\ingroup h5part_io
Read array of 64 bit integer data from file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -191,8 +183,6 @@ H5PartReadDataInt64 (
}
/**
\ingroup h5part_io
Read array of 32 bit integer data from file.
See \ref H5PartWriteDataFloat64() for more details.
......@@ -216,4 +206,6 @@ H5PartReadDataInt32 (
}
#endif
///< @}
#endif
......@@ -15,13 +15,17 @@
#include "h5core/h5_debug.h"
#include "h5core/h5u_model.h"
/**
\ingroup h5part_c_api
\addtogroup h5part_model
@{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
\ingroup h5part_model
Set the number of points/particles for the current time-step.
After you call this subroutine, all subsequent
operations will assume this number of particles will be written.
......@@ -60,8 +64,6 @@ H5PartSetNumPoints (
}
/**
\ingroup h5part_model
\see H5PartSetNumPoints()
*/
static inline h5_err_t
......@@ -77,8 +79,6 @@ H5PartSetNumParticles (
}
/**
\ingroup h5part_model
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.
......@@ -119,8 +119,6 @@ H5PartSetNumParticlesStrided (
}
/**
\ingroup h5part_model
Define the chunk \c size and enables chunking in the underlying
HDF5 layer.
......@@ -148,8 +146,6 @@ H5PartSetChunkSize (