From 353689b4eb0bb8b2d6a60ed12561675797937e8f Mon Sep 17 00:00:00 2001 From: Achim Gsell Date: Tue, 26 Sep 2006 23:33:04 +0000 Subject: [PATCH] src/H5Part.c - grouping function in doxygen groups --- src/H5Part.c | 257 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 215 insertions(+), 42 deletions(-) diff --git a/src/H5Part.c b/src/H5Part.c index 1f8ec43..9bcd6e6 100644 --- a/src/H5Part.c +++ b/src/H5Part.c @@ -1,7 +1,58 @@ -/* - H5Part C API +/*! \mainpage H5Part: A Portable High Performance Parallel Data Interface to HDF5 + +Particle based simulations of accelerator beam-lines, especially in +six dimensional phase space, generate vast amounts of data. Even +though a subset of statistical information regarding phase space or +analysis needs to be preserved, reading and writing such enormous +restart files on massively parallel supercomputing systems remains +challenging. + +H5Part consists of Particles, Block structured Fields and unstructured +data (Topo). + +Developed by . + +For further information contact: xxxxxx - +xxxx xxxxx, (xxx) xxx. + +Last modified on xxx xx, 2006. + +Papers: + +LBNL Vis Group
*/ + +/*! + \defgroup h5part_api H5Part API + +*/ +/*! + \ingroup h5part_api + \defgroup h5part_openclose File Opening and Closing +*/ +/*! + \ingroup h5part_api + \defgroup h5part_write File Writing +*/ +/*! + \ingroup h5part_api + \defgroup h5part_read File Reading +*/ +/*! + \ingroup h5part_api + \defgroup h5part_attrib Reading and Writing Attributes +*/ +/*! + \ingroup h5part_api + \defgroup h5part_errhandle Error Handling +*/ +/*! + \internal + \defgroup h5partkernel H5Part private functions +*/ + + #include #include #include /* va_arg - System dependent ?! */ @@ -43,6 +94,8 @@ _h5_error_handler ( /*========== File Opening/Closing ===============*/ /*! + \ingroup h5part_openclose + Opens file with specified filename. If you open with flag \c H5PART_WRITE, it will truncate any @@ -60,7 +113,6 @@ _h5_error_handler ( \return File handle or \c NULL */ - H5PartFile* H5PartOpenFileParallel ( const char *filename, /*!< [in] The name of the data file to open. */ @@ -198,6 +250,8 @@ H5PartOpenFileParallel ( } /*! + \ingroup h5part_openclose + Opens file with specified filename. If you open with flag \c H5PART_WRITE, it will truncate any @@ -325,6 +379,8 @@ _file_is_valid ( } /*! + \ingroup h5part_openclose + Closes an open file. \return \c H5PART_SUCCESS or error code @@ -390,7 +446,10 @@ H5PartCloseFile ( } /*============== File Writing Functions ==================== */ + /*! + \ingroup h5part_write + Set number of particles for current time-step. This function's sole purpose is to prevent @@ -574,6 +633,8 @@ _write_data ( } /*! + \ingroup h5part_write + Write array of 64 bit floating point data to file. After setting the number of particles with \c H5PartSetNumParticles() and @@ -618,6 +679,8 @@ H5PartWriteDataFloat64 ( } /*! + \ingroup h5part_write + Write array of 64 bit integer data to file. After setting the number of particles with \c H5PartSetNumParticles() and @@ -665,6 +728,12 @@ H5PartWriteDataInt64 ( /********************** reading and writing attribute ************************/ /********************** private functions to handle attributes ***************/ + +/*! + \ingroup h5partkernel + @{ +*/ + /*! Normalize HDF5 type */ @@ -828,6 +897,8 @@ _H5Part_get_attrib_info ( /********************** attribute API ****************************************/ /*! + \ingroup h5part_attrib + Writes a string attribute bound to a file. This function creates a new attribute \c name with the string \c value as @@ -839,7 +910,6 @@ _H5Part_get_attrib_info ( \return \c H5PART_SUCCESS or error code */ - h5part_int64_t H5PartWriteFileAttribString ( H5PartFile *f, /*!< [in] Handle to open file */ @@ -870,6 +940,8 @@ H5PartWriteFileAttribString ( } /*! + \ingroup h5part_attrib + Writes a string attribute bound to the current time-step. This function creates a new attribute \c name with the string \c value as @@ -907,6 +979,8 @@ H5PartWriteStepAttribString ( } /*! + \ingroup h5part_attrib + Writes a attribute bound to the current time-step. This function creates a new attribute \c name with the string \c value as @@ -952,6 +1026,8 @@ H5PartWriteStepAttrib ( } /*! + \ingroup h5part_attrib + Writes a attribute bound to a file. This function creates a new attribute \c name with the string \c value as @@ -1002,8 +1078,9 @@ H5PartWriteFileAttrib ( return H5PART_SUCCESS; } - /*! + \ingroup h5part_attrib + Gets the number of attributes bound to the current step. \return Number of attributes bound to current time step or error code. @@ -1025,6 +1102,8 @@ H5PartGetNumStepAttribs ( } /*! + \ingroup h5part_attrib + Gets the number of attributes bound to the file. \return Number of attributes bound to file \c f or error code. @@ -1052,6 +1131,8 @@ H5PartGetNumFileAttribs ( } /*! + \ingroup h5part_attrib + Gets the name, type and number of elements of the step attribute specified by its index. @@ -1093,6 +1174,8 @@ H5PartGetStepAttribInfo ( } /*! + \ingroup h5part_attrib + Gets the name, type and number of elements of the file attribute specified by its index. @@ -1141,11 +1224,12 @@ H5PartGetFileAttribInfo ( } /*! + \ingroup h5part_attrib + Reads an attribute bound to current time-step. \return \c H5PART_SUCCESS or error code */ - h5part_int64_t H5PartReadStepAttrib ( H5PartFile *f, /*!< [in] Handle to open file */ @@ -1166,11 +1250,12 @@ H5PartReadStepAttrib ( } /*! + \ingroup h5part_attrib + Reads an attribute bound to file \c f. \return \c H5PART_SUCCESS or error code */ - h5part_int64_t H5PartReadFileAttrib ( H5PartFile *f, @@ -1255,8 +1340,9 @@ _H5Part_set_step ( return H5PART_SUCCESS; } - /*! + \ingroup h5part_read + Set the current time-step. When writing data to a file the current time step must be set first @@ -1270,7 +1356,6 @@ _H5Part_set_step ( \return \c H5PART_SUCCESS or error code */ - h5part_int64_t H5PartSetStep ( H5PartFile *f, /*!< [in] Handle to open file */ @@ -1286,7 +1371,11 @@ H5PartSetStep ( /********************** query file structure *********************************/ +/*! + \ingroup h5part_kernel + Iterator for \c H5Giterate(). +*/ herr_t _H5Part_iteration_operator ( hid_t group_id, /*!< [in] group id */ @@ -1321,6 +1410,11 @@ _H5Part_iteration_operator ( return 0; /* continue iteration */ } +/*! + \ingroup h5part_kernel + + Iterator for \c H5Giterate(). +*/ h5part_int64_t _H5Part_get_num_objects ( hid_t group_id, @@ -1335,6 +1429,11 @@ _H5Part_get_num_objects ( NULL ); } +/*! + \ingroup h5part_kernel + + Iterator for \c H5Giterate(). +*/ h5part_int64_t _H5Part_get_num_objects_matching_pattern ( hid_t group_id, @@ -1358,6 +1457,11 @@ _H5Part_get_num_objects_matching_pattern ( return data.count; } +/*! + \ingroup h5part_kernel + + Iterator for \c H5Giterate(). +*/ h5part_int64_t _H5Part_get_object_name ( hid_t group_id, @@ -1390,6 +1494,8 @@ _H5Part_get_object_name ( } /*! + \ingroup h5part_read + Get the number of time-steps that are currently stored in the file \c f. @@ -1415,6 +1521,8 @@ H5PartGetNumSteps ( } /*! + \ingroup h5part_read + Get the number of datasets that are stored at the current time-step. \return number of datasets in current timestep or error code @@ -1438,6 +1546,8 @@ H5PartGetNumDatasets ( } /*! + \ingroup h5part_read + This reads the name of a dataset specified by it's index in the current time-step. @@ -1473,6 +1583,8 @@ H5PartGetDatasetName ( } /*! + \ingroup h5part_read + Gets the name, type and number of elements of a dataset specified by it's index in the current time-step. @@ -1534,10 +1646,6 @@ H5PartGetDatasetInfo ( return H5PART_SUCCESS; } -/*! - \intenal - -*/ static hid_t _get_diskshape_for_reading ( H5PartFile *f, @@ -1612,15 +1720,6 @@ _get_memshape_for_reading ( } } -/*! - This gets the number of particles stored in the current timestep. - It will arbitrarily select a time-step if you haven't already set - the timestep with \c H5PartSetStep(). - - \return number of particles in current timestep or an error - code. - */ - h5part_int64_t _H5Part_get_num_particles ( H5PartFile *f /*!< [in] Handle to open file */ @@ -1671,6 +1770,16 @@ _H5Part_get_num_particles ( return (h5part_int64_t) nparticles; } +/*! + \ingroup h5part_read + + This gets the number of particles stored in the current timestep. + It will arbitrarily select a time-step if you haven't already set + the timestep with \c H5PartSetStep(). + + \return number of particles in current timestep or an error + code. + */ h5part_int64_t H5PartGetNumParticles ( H5PartFile *f /*!< [in] Handle to open file */ @@ -1716,6 +1825,9 @@ _reset_view ( return H5PART_SUCCESS; } +/*! + \ingroup h5part_read +*/ h5part_int64_t H5PartResetView ( H5PartFile *f /*!< [in] Handle to open file */ @@ -1728,6 +1840,9 @@ H5PartResetView ( return _reset_view ( f ); } +/*! + \ingroup h5part_read +*/ h5part_int64_t H5PartHasView ( H5PartFile *f /*!< [in] Handle to open file */ @@ -1740,23 +1855,6 @@ H5PartHasView ( return ( f->viewstart >= 0 ) && ( f->viewend >= 0 ); } -/*! - For parallel I/O or for subsetting operations on the datafile, the - \c H5PartSetView() function allows you to define a subset of the total - particle dataset to read. 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 \c H5PartSetView(file,-1,-1); - - Before you set a view, the \c 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 start and the end index). - - \return \c H5PART_SUCCESS or error code -*/ static h5part_int64_t _set_view ( H5PartFile *f, /*!< [in] Handle to open file */ @@ -1834,6 +1932,25 @@ _set_view ( return H5PART_SUCCESS; } +/*! + \ingroup h5part_read + + For parallel I/O or for subsetting operations on the datafile, the + \c H5PartSetView() function allows you to define a subset of the total + particle dataset to read. 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 \c H5PartSetView(file,-1,-1); + + Before you set a view, the \c 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 start and the end index). + + \return \c H5PART_SUCCESS or error code +*/ h5part_int64_t H5PartSetView ( H5PartFile *f, /*!< [in] Handle to open file */ @@ -1855,6 +1972,8 @@ H5PartSetView ( } /*! + \ingroup h5part_read + Allows you to query the current view. Start and End will be \c -1 if there is no current view established. Use \c H5PartHasView() to see if the view is smaller than the @@ -1900,6 +2019,8 @@ H5PartGetView ( } /*! + \ingroup h5part_read + If it is too tedious to manually set the start and end coordinates for a view, the \c H5SetCanonicalView() will automatically select an appropriate domain decomposition of the data arrays for the degree @@ -1921,11 +2042,12 @@ H5PartSetCanonicalView ( SET_FNAME ( "H5PartSetCanonicalView" ); + h5part_int64_t herr; CHECK_FILEHANDLE( f ); CHECK_READONLY_MODE ( f ) - h5part_int64_t herr = _reset_view ( f ); + herr = _reset_view ( f ); if ( herr < 0 ) return HANDLE_H5PART_SET_VIEW_ERR( herr, -1, -1 ); #ifdef PARALLEL_IO @@ -2023,6 +2145,8 @@ _read_data ( } /*! + \ingroup h5part_read + Read array of 64 bit floating point data from file. When retrieving datasets from disk, you ask for them @@ -2051,7 +2175,9 @@ H5PartReadDataFloat64 ( return H5PART_SUCCESS; } -/** +/*! + \ingroup h5part_read + Read array of 64 bit floating point data from file. When retrieving datasets from disk, you ask for them @@ -2081,6 +2207,8 @@ H5PartReadDataInt64 ( } /*! + \ingroup h5part_read + This is the mongo read function that pulls in all of the data for a given timestep in one shot. It also takes the timestep as an argument and will call \c H5PartSetStep() internally so that you don't have to @@ -2139,6 +2267,13 @@ H5PartReadParticleStep ( /****************** error handling ******************/ +/*! + \ingroup h5part_errhandle + + Set verbosity level to \c level. + + \return \c H5PART_SUCCESS +*/ h5part_int64_t H5PartSetVerbosityLevel ( h5part_int64_t level @@ -2148,6 +2283,13 @@ H5PartSetVerbosityLevel ( return H5PART_SUCCESS; } +/*! + \ingroup h5part_errhandle + + Set error handler to \c handler. + + \return \c H5PART_SUCCESS +*/ h5part_int64_t H5PartSetErrorHandler ( h5part_error_handler handler @@ -2156,6 +2298,13 @@ H5PartSetErrorHandler ( return H5PART_SUCCESS; } +/*! + \ingroup h5part_errhandle + + Get current error handler. + + \return Pointer to error handler. +*/ h5part_error_handler H5PartGetErrorHandler ( void @@ -2163,6 +2312,13 @@ H5PartGetErrorHandler ( return _err_handler; } +/*! + \ingroup h5part_errhandle + + Get last error code. + + \return error code +*/ h5part_int64_t H5PartGetErrno ( void @@ -2170,6 +2326,14 @@ H5PartGetErrno ( return _errno; } +/*! + \ingroup h5part_errhandle + + This is the H5Part default error handler. If an error occures, an + error message will be printed and an error number will be returned. + + \return value given in \c eno +*/ h5part_int64_t H5PartDefaultErrorHandler ( const char *funcname, @@ -2188,6 +2352,12 @@ H5PartDefaultErrorHandler ( return _errno; } +/*! + \ingroup h5part_errhandle + + If an error occures, an error message will be printed and the + program exists with the error code given in \c eno. +*/ h5part_int64_t H5PartAbortErrorHandler ( const char *funcname, @@ -2207,7 +2377,9 @@ H5PartAbortErrorHandler ( exit (-_errno); } - +/*! + Initialize H5Part +*/ static h5part_int64_t _init ( void ) { static int __init = 0; @@ -2220,6 +2392,7 @@ _init ( void ) { __init = 1; return H5PART_SUCCESS; } +/*! @} */ static herr_t _h5_error_handler ( void* unused ) {