diff --git a/doc/Doxyfile b/doc/Doxyfile index 44929c3..8f1ad71 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -84,6 +84,9 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- INPUT += ../src/H5Part.c INPUT += ../src/H5Block.c +INPUT += ../src/H5MultiBlock.c +INPUT += ../src/H5BlockReadWrite.c +INPUT += ../src/H5MultiBlockReadWrite.c FILE_PATTERNS = RECURSIVE = YES EXCLUDE = diff --git a/src/H5Block.c b/src/H5Block.c index 958dc19..c2cef14 100644 --- a/src/H5Block.c +++ b/src/H5Block.c @@ -14,6 +14,19 @@ \defgroup h5block_private H5Block Private */ +/*! + \ingroup h5block_c_api + \defgroup h5block_write File Writing +*/ +/*! + \ingroup h5block_c_api + \defgroup h5block_read File Reading +*/ +/*! + \ingroup h5block_c_api + \defgroup h5block_attrib Reading and Writing Attributes +*/ + /*! \note Different field sizes are allowed in the same time-step. @@ -706,7 +719,7 @@ _release_hyperslab ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write Define the field layout given the dense index space at the actual time step. @@ -757,7 +770,7 @@ H5BlockDefine3DFieldLayout( } /*! - \ingroup h5block_c_api + \ingroup h5block_write Define the chunk dimensions and enable chunking in the underlying HDF5 dataset. @@ -795,7 +808,7 @@ H5BlockDefine3DChunkDims( } /*! - \ingroup h5block_c_api + \ingroup h5block_read Lookup the chunk dimensions of the underlying HDF5 dataset. @@ -854,7 +867,7 @@ H5BlockGet3DChunkDims( } /*! - \ingroup h5block_c_api + \ingroup h5block_read Return partition of processor \c proc as specified with \c H5BlockDefine3dLayout(). @@ -894,7 +907,7 @@ H5Block3dGetPartitionOfProc ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read Return reduced (ghost-zone free) partition of processor \c proc as specified with \c H5BlockDefine3dLayout(). @@ -935,7 +948,7 @@ H5Block3dGetReducedPartitionOfProc ( /*! - \ingroup h5block_c_api + \ingroup h5block_read Returns the processor computing the reduced (ghostzone-free) partition given by the coordinates \c i, \c j and \c k. @@ -1449,7 +1462,7 @@ _H5Block_write_data ( /********************** query information about available fields *************/ /*! - \ingroup h5block_c_api + \ingroup h5block_read Query number of fields in current time step. @@ -1537,7 +1550,7 @@ _get_field_info ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read Get the name, rank and dimensions of the field specified by the index \c idx. @@ -1578,7 +1591,7 @@ H5BlockGetFieldInfo ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read Get the rank and dimensions of the field specified by its name. @@ -1638,7 +1651,7 @@ _write_field_attrib ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write \c attrib_value with type \c attrib_type as attribute \c attrib_name to field \c field_name. @@ -1668,7 +1681,7 @@ H5BlockWriteFieldAttrib ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write string \c attrib_value as attribute \c attrib_name to field \c field_name.. @@ -1696,7 +1709,7 @@ H5BlockWriteFieldAttribString ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Query the number of attributes of field \c field_name. @@ -1727,7 +1740,7 @@ H5BlockGetNumFieldAttribs ( /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Query information about a attribute given by index \c attrib_idx and field name \c field_name. The function returns the name of the attribute, @@ -1803,7 +1816,7 @@ _read_field_attrib ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Read attribute \c attrib_name of field \c field_name. @@ -1827,7 +1840,7 @@ H5BlockReadFieldAttrib ( /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Get field origin. @@ -1861,7 +1874,7 @@ H5Block3dGetFieldOrigin ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Set field origin. @@ -1893,7 +1906,7 @@ H5Block3dSetFieldOrigin ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Get field spacing for field \c field_name in the current time step. @@ -1927,7 +1940,7 @@ H5Block3dGetFieldSpacing ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Set field spacing for field \c field_name in the current time step. @@ -1959,7 +1972,7 @@ H5Block3dSetFieldSpacing ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read */ /* Checks whether the current time-step has field data or not. diff --git a/src/H5BlockReadWrite.c b/src/H5BlockReadWrite.c index e62196d..69b9887 100644 --- a/src/H5BlockReadWrite.c +++ b/src/H5BlockReadWrite.c @@ -13,7 +13,7 @@ #include "H5BlockErrors.h" /*! - \ingroup h5block_c_api + \ingroup h5block_write 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 @@ -49,7 +49,7 @@ H5Block3dWriteScalarFieldFloat64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read 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 @@ -84,7 +84,7 @@ H5Block3dReadScalarFieldFloat64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write */ /*! Write a 3-dimensional field \c name with 3-dimensional vectors as values @@ -128,7 +128,7 @@ H5Block3dWrite3dVectorFieldFloat64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read */ /*! Read a 3-dimensional field \c name with 3-dimensional vectors as values @@ -171,7 +171,7 @@ H5Block3dRead3dVectorFieldFloat64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write 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 @@ -207,7 +207,7 @@ H5Block3dWriteScalarFieldFloat32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read 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 @@ -242,7 +242,7 @@ H5Block3dReadScalarFieldFloat32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write */ /*! Write a 3-dimensional field \c name with 3-dimensional vectors as values @@ -286,7 +286,7 @@ H5Block3dWrite3dVectorFieldFloat32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read */ /*! Read a 3-dimensional field \c name with 3-dimensional vectors as values @@ -329,7 +329,7 @@ H5Block3dRead3dVectorFieldFloat32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write 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 @@ -365,7 +365,7 @@ H5Block3dWriteScalarFieldInt64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read 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 @@ -400,7 +400,7 @@ H5Block3dReadScalarFieldInt64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write */ /*! Write a 3-dimensional field \c name with 3-dimensional vectors as values @@ -444,7 +444,7 @@ H5Block3dWrite3dVectorFieldInt64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read */ /*! Read a 3-dimensional field \c name with 3-dimensional vectors as values @@ -487,7 +487,7 @@ H5Block3dRead3dVectorFieldInt64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write 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 @@ -523,7 +523,7 @@ H5Block3dWriteScalarFieldInt32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read 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 @@ -558,7 +558,7 @@ H5Block3dReadScalarFieldInt32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_write */ /*! Write a 3-dimensional field \c name with 3-dimensional vectors as values @@ -602,7 +602,7 @@ H5Block3dWrite3dVectorFieldInt32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_read */ /*! Read a 3-dimensional field \c name with 3-dimensional vectors as values @@ -645,7 +645,7 @@ H5Block3dRead3dVectorFieldInt32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write \c attrib_value with type floating points (64-bit) as attribute \c attrib_name to field \c field_name. @@ -676,7 +676,7 @@ H5BlockWriteFieldAttribFloat64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write \c attrib_value with type floating points (32-bit) as attribute \c attrib_name to field \c field_name. @@ -707,7 +707,7 @@ H5BlockWriteFieldAttribFloat32 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write \c attrib_value with type integers (64-bit) as attribute \c attrib_name to field \c field_name. @@ -738,7 +738,7 @@ H5BlockWriteFieldAttribInt64 ( } /*! - \ingroup h5block_c_api + \ingroup h5block_attrib Write \c attrib_value with type integers (32-bit) as attribute \c attrib_name to field \c field_name. diff --git a/src/H5MultiBlock.c b/src/H5MultiBlock.c index ad685f2..8255372 100644 --- a/src/H5MultiBlock.c +++ b/src/H5MultiBlock.c @@ -14,9 +14,11 @@ * All blocks must be the same size (a requirement of the HDF5 chunking mechanism). + * The block dimensions must divide the field dimensions, to prevent fringe data that will lower performance by interfering with contiguous I/O operations. + * For load-balancing purposes, the total number of blocks that the field is decomposed into must be a multiple of the number of nodes in the distributed system. (For ease of implementation, we require that the @@ -24,6 +26,20 @@ */ +/*! + \ingroup h5multiblock_c_api + \defgroup h5multiblock_write File Writing +*/ +/*! + \ingroup h5multiblock_c_api + \defgroup h5multiblock_read File Reading +*/ +/*! + \ingroup h5multiblock_c_api + \defgroup h5multiblock_attrib Reading and Writing Attributes +*/ + + /*! \internal @@ -1115,7 +1131,7 @@ _H5MultiBlock_write_data ( *******************************************************************************/ /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Define the radius for halo exchanges between the blocks. Blocks on the edges of the field will be padded with zero values out to the radius. @@ -1143,7 +1159,7 @@ H5MultiBlock3dDefineRadius ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Define the radii for halo exchanges between the blocks. Blocks on the edges of the field will be padded with zero values out to the radius. @@ -1175,7 +1191,7 @@ H5MultiBlock3dDefineRadii ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Define the field and block dimensions for writing. @@ -1211,7 +1227,7 @@ H5MultiBlock3dDefineDims ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Returns the field dimensions of the last field that was read. @@ -1240,7 +1256,7 @@ H5MultiBlock3dGetFieldDims( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Returns the block dimensions of the last field that was read. @@ -1270,7 +1286,7 @@ H5MultiBlock3dGetBlockDims( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Return the offsets for the block belonging to processor \c proc. @@ -1326,7 +1342,7 @@ H5MultiBlock3dCalculateDecomp ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Frees a \c block that was allocated during a read. diff --git a/src/H5MultiBlockReadWrite.c b/src/H5MultiBlockReadWrite.c index 38bbcc5..8901853 100644 --- a/src/H5MultiBlockReadWrite.c +++ b/src/H5MultiBlockReadWrite.c @@ -11,7 +11,7 @@ #include "H5MultiBlockPrivate.h" /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Write a multiblock field \c name from the buffer starting at \c data to the current time-step using the defined block decomposition and dimensions. @@ -39,7 +39,7 @@ H5MultiBlock3dWriteFieldFloat64 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Allocate a buffer to hold a block from a multiblock field and place the pointer in \c data, then read the block into the buffer. Uses the block @@ -68,7 +68,7 @@ H5MultiBlock3dReadFieldFloat64 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Write a multiblock field \c name from the buffer starting at \c data to the current time-step using the defined block decomposition and dimensions. @@ -96,7 +96,7 @@ H5MultiBlock3dWriteFieldFloat32 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Allocate a buffer to hold a block from a multiblock field and place the pointer in \c data, then read the block into the buffer. Uses the block @@ -125,7 +125,7 @@ H5MultiBlock3dReadFieldFloat32 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Write a multiblock field \c name from the buffer starting at \c data to the current time-step using the defined block decomposition and dimensions. @@ -153,7 +153,7 @@ H5MultiBlock3dWriteFieldInt64 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Allocate a buffer to hold a block from a multiblock field and place the pointer in \c data, then read the block into the buffer. Uses the block @@ -182,7 +182,7 @@ H5MultiBlock3dReadFieldInt64 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_write Write a multiblock field \c name from the buffer starting at \c data to the current time-step using the defined block decomposition and dimensions. @@ -210,7 +210,7 @@ H5MultiBlock3dWriteFieldInt32 ( } /*! - \ingroup h5multiblock_c_api + \ingroup h5multiblock_read Allocate a buffer to hold a block from a multiblock field and place the pointer in \c data, then read the block into the buffer. Uses the block diff --git a/src/generate-h5bl-readwrite.py b/src/generate-h5bl-readwrite.py index 8d234df..7cdf06f 100755 --- a/src/generate-h5bl-readwrite.py +++ b/src/generate-h5bl-readwrite.py @@ -79,7 +79,7 @@ H5Block#DIM#dReadScalarField#TYPE_ABV# ( write_scalar_c = """ /*! - \\ingroup h5block_c_api + \\ingroup h5block_write 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 @@ -117,7 +117,7 @@ H5Block#DIM#dWriteScalarField#TYPE_ABV# ( read_scalar_c = """ /*! - \\ingroup h5block_c_api + \\ingroup h5block_read 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 @@ -246,7 +246,7 @@ H5Block#DIM#dRead3dVectorField#TYPE_ABV# ( write_vector_c = """ /*! - \\ingroup h5block_c_api + \\ingroup h5block_write */ /*! Write a 3-dimensional field \\c name with 3-dimensional vectors as values @@ -292,7 +292,7 @@ H5Block#DIM#dWrite3dVectorField#TYPE_ABV# ( read_vector_c = """ /*! - \\ingroup h5block_c_api + \\ingroup h5block_read */ /*! Read a 3-dimensional field \\c name with 3-dimensional vectors as values @@ -426,7 +426,7 @@ H5BlockWriteFieldAttrib#TYPE_ABV# ( write_attr_c = """ /*! - \\ingroup h5block_c_api + \\ingroup h5block_attrib Write \\c attrib_value with type #TYPE_FULL# as attribute \\c attrib_name to field \\c field_name. diff --git a/src/generate-h5multi-readwrite.py b/src/generate-h5multi-readwrite.py index c8c5313..530e76a 100755 --- a/src/generate-h5multi-readwrite.py +++ b/src/generate-h5multi-readwrite.py @@ -77,7 +77,7 @@ H5MultiBlock#DIM#dReadField#TYPE_ABV# ( write_c = """ /*! - \\ingroup h5multiblock_c_api + \\ingroup h5multiblock_write Write a multiblock field \\c name from the buffer starting at \\c data to the current time-step using the defined block decomposition and dimensions. @@ -107,7 +107,7 @@ H5MultiBlock#DIM#dWriteField#TYPE_ABV# ( read_c = """ /*! - \\ingroup h5multiblock_c_api + \\ingroup h5multiblock_read Allocate a buffer to hold a block from a multiblock field and place the pointer in \\c data, then read the block into the buffer. Uses the block