added documentation for file open flags; added flags to...

added documentation for file open flags; added flags to h5pt_openr_par_align(); added H5PartSetViewEmpty() and h5pt_setview_empty() calls for creating empty hyperslab selections (previously kludge was to use H5PartSetViewIndices with a null list); fixed memory leak with file open flags in the Fortran interface; fixed missing statement in 1.6.x logic for _H5Part_have_group()

.gitattributes

@@ -18,6 +18,7 @@ doc/Doxyfile -text
 doc/H5X_File_Format.txt -text
 doc/Makefile.am -text
 doc/doxyfooter -text
+examples/simplef.F90 -text
 examples/stridedf.F90 -text
 examples/write_setview.c -text
 /install-sh -text

examples/simplef.F90

+program H5PartTest
+  implicit none
+
+  include 'mpif.h'
+  include 'H5PartF.h'
+
+  integer :: comm, rank, ierr
+  integer*8 :: file_id, status, npoints, i
+  real*8, allocatable :: particles(:)
+  integer*8, allocatable :: id(:)
+
+  comm = MPI_COMM_WORLD
+  call mpi_init(ierr)
+  call mpi_comm_rank(comm, rank, ierr)
+
+  ! open the a file for parallel writing
+  file_id = h5pt_openw_par('test.h5', comm)
+
+  ! in the Fortran API, time steps start at 1
+  status = h5pt_setstep(file_id, 1_8)
+
+  ! write an attribute to the file
+  status = h5pt_writefileattrib_string(file_id, 'desc', 'This is a test.')
+
+  ! create fake data
+  npoints = 99
+  allocate(particles(npoints), id(npoints))
+  do i=1,npoints
+    particles(i) = real(i+npoints*rank)
+    id(i) = i+npoints*rank
+  enddo
+
+  ! set the size of the 1D array
+  status = h5pt_setnpoints(file_id, npoints)
+
+  ! write the particles
+  status = h5pt_writedata_r8(file_id, "x",  particles)
+
+  ! write the ids
+  status = h5pt_writedata_i8(file_id, "id", id)
+
+  ! close the file
+  status = h5pt_close(file_id)
+
+  deallocate(particles, id)
+
+  call mpi_finalize(ierr)
+
+end program H5PartTest

src/H5Block.c

@@ -721,8 +721,8 @@ _release_hyperslab (
 /*!
   \ingroup h5block_model
 
-  Define the field layout given the dense index space at the actual
-  time step.
+  Defines the partition of the field that this processor owns, using
+  Fortran ordering: the fastest moving index is \c i.
 
   This routine uses an MPI_Allgather, so at large concurrency it should
   be called as infrequently as possible. For instance, if several timesteps

src/H5Part.c

@@ -401,13 +401,17 @@ _H5Part_open_file (
 
   Opens file with specified filename. 
 
-  If you open with flag \c H5PART_WRITE, it will truncate any
-  file with the specified filename and start writing to it. If 
-  you open with \c H5PART_APPEND, then you can append new timesteps.
-  If you open with \c H5PART_READ, then it will open the file
-  readonly.
+  Flags are bit values that can be combined with the bit operator \c |
+  and include:
 
-  The typical extension for these files is \c .h5.
+  - \c H5PART_WRITE - truncate file and open for writing
+  - \c H5PART_APPEND - open file for writing without truncating
+  - \c H5PART_READ - open file read-only
+  - \c H5PART_FS_LUSTRE - enable optimizations for the Lustre file system
+  - \c H5PART_VFD_MPIPOSIX - use the HDF5 MPI-POSIX virtual file driver
+  - \c H5PART_VFD_MPIO_IND - use MPI-IO in indepedent mode
+
+  The typical file extension is \c .h5.
   
   H5PartFile should be treated as an essentially opaque
   datastructure.  It acts as the file handle, but internally
@@ -437,6 +441,23 @@ H5PartOpenFileParallel (
   Opens file with specified filename, and also specifices an alignment
   value used for HDF5 tuning parameters.
 
+  Flags are bit values that can be combined with the bit operator \c |
+  and include:
+
+  - \c H5PART_WRITE - truncate file and open for writing
+  - \c H5PART_APPEND - open file for writing without truncating
+  - \c H5PART_READ - open file read-only
+  - \c H5PART_FS_LUSTRE - enable optimizations for the Lustre file system
+  - \c H5PART_VFD_MPIPOSIX - use the HDF5 MPI-POSIX virtual file driver
+  - \c H5PART_VFD_MPIO_IND - use MPI-IO in indepedent mode
+
+  The typical file extension is \c .h5.
+  
+  H5PartFile should be treated as an essentially opaque
+  datastructure.  It acts as the file handle, but internally
+  it maintains several key state variables associated with 
+  the file.
+
   \return	File handle or \c NULL
  */
 H5PartFile*
@@ -460,13 +481,14 @@ H5PartOpenFileParallelAlign (
 
   Opens file with specified filename. 
 
-  If you open with flag \c H5PART_WRITE, it will truncate any
-  file with the specified filename and start writing to it. If 
-  you open with \c H5PART_APPEND, then you can append new timesteps.
-  If you open with \c H5PART_READ, then it will open the file
-  readonly.
+  Flags are bit values that can be combined with the bit operator \c |
+  and include:
+
+  - \c H5PART_WRITE - truncate file and open for writing
+  - \c H5PART_APPEND - open file for writing without truncating
+  - \c H5PART_READ - open file read-only
 
-  The typical extension for these files is \c .h5.
+  The typical file extension is \c .h5.
   
   H5PartFile should be treated as an essentially opaque
   datastructure.  It acts as the file handle, but internally
@@ -496,6 +518,20 @@ H5PartOpenFile (
   Opens file with specified filename, and also specifices an alignment
   value used for HDF5 tuning parameters.
 
+  Flags are bit values that can be combined with the bit operator \c |
+  and include:
+
+  - \c H5PART_WRITE - truncate file and open for writing
+  - \c H5PART_APPEND - open file for writing without truncating
+  - \c H5PART_READ - open file read-only
+
+  The typical file extension is \c .h5.
+  
+  H5PartFile should be treated as an essentially opaque
+  datastructure.  It acts as the file handle, but internally
+  it maintains several key state variables associated with 
+  the file.
+
   \return	File handle or \c NULL
  */
 H5PartFile*
@@ -2970,6 +3006,34 @@ H5PartSetViewIndices (
 	return _set_view_indices ( f, indices, nelems );
 }
 
+/*!
+  \ingroup h5part_model
+
+  In MPI-IO collective mode, all MPI tasks must participate in I/O
+  operations. \c H5PartSetViewEmpty() allows a task to participate
+  but with an empty view of the file, so that it contributes no data
+  to the I/O operation.
+
+  \return	\c H5PART_SUCCESS or error code
+*/
+h5part_int64_t
+H5PartSetViewEmpty (
+	H5PartFile *f			/*!< [in]  Handle to open file */
+	) {
+
+	SET_FNAME ( "H5PartSetViewEmpty" );
+
+	CHECK_FILEHANDLE( f );
+
+	if ( f->timegroup < 0 ) {
+		h5part_int64_t herr = _H5Part_set_step ( f, 0 );
+		if ( herr < 0 ) return herr;
+	}
+
+        /* using a null indices list will set an empty view */
+	return _set_view_indices ( f, NULL, 0 );
+}
+
 /*!
   \ingroup h5part_model
 

src/H5Part.f90

@@ -108,17 +108,32 @@ END FUNCTION
 !> \ingroup h5partf_open
 !! Opens a parallel file for reading and specifies an HDF5 alignment.
 !! See \ref H5PartOpenFileParallelAlign
+!!
+!! Flags are specified as a comma separated string that can include:
+!!
+!! - \c fs_lustre - enable optimizations for the Lustre file system
+!! - \c vfd_mpiposix - use the HDF5 MPI-POSIX virtual file driver
+!! - \c vfd_mpio_ind - use MPI-IO in indepedent mode
+!!
 !! \return 0 on success or error code
 !<
 INTEGER*8 FUNCTION h5pt_openr_par_align ( filename, mpi_communicator, align )
     CHARACTER(LEN=*), INTENT(IN) :: filename    !< the filename to open for reading
     INTEGER, INTENT(IN) :: mpi_communicator     !< the MPI_Communicator used by the program
     INTEGER*8, INTENT(IN) :: align              !< alignment value in bytes
+    CHARACTER(LEN=*), INTENT(IN) :: flags       !< additional flags
 END FUNCTION
 
 !> \ingroup h5partf_open
 !! Opens a parallel file for writing in truncate mode and specifies
 !! an HDF5 alignment.
+!!
+!! Flags are specified as a comma separated string that can include:
+!!
+!! - \c fs_lustre - enable optimizations for the Lustre file system
+!! - \c vfd_mpiposix - use the HDF5 MPI-POSIX virtual file driver
+!! - \c vfd_mpio_ind - use MPI-IO in indepedent mode
+!!
 !! See \ref H5PartOpenFileParallelAlign
 !! \return 0 on success or error code
 !<
@@ -132,6 +147,13 @@ END FUNCTION
 !> \ingroup h5partf_open
 !! Opens a parallel file for writing in append mode and specifies
 !! an HDF5 alignment.
+!!
+!! Flags are specified as a comma separated string that can include:
+!!
+!! - \c fs_lustre - enable optimizations for the Lustre file system
+!! - \c vfd_mpiposix - use the HDF5 MPI-POSIX virtual file driver
+!! - \c vfd_mpio_ind - use MPI-IO in indepedent mode
+!!
 !! See \ref H5PartOpenFileParallelAlign
 !! \return 0 on success or error code
 !<
@@ -243,6 +265,14 @@ INTEGER*8 FUNCTION h5pt_setview_indices (filehandle,indices,nelem)
     INTEGER*8, INTENT(IN) :: nelem      !< number of particles in the list
 END FUNCTION
 
+!> \ingroup h5partf_model
+!! See \ref H5PartSetViewEmpty
+!! \return 0 on success or error code
+!<
+INTEGER*8 FUNCTION h5pt_setview_empty (filehandle)
+    INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open
+END FUNCTION
+
 !> \ingroup h5partf_model
 !! See \ref H5PartResetView
 !! \return 0 on success or error code

src/H5Part.h

@@ -219,6 +219,11 @@ H5PartSetViewIndices (
 	h5part_int64_t nelems		/*!< [in]  Size of list */
 	);
 
+h5part_int64_t
+H5PartSetViewEmpty (
+	H5PartFile *f
+	);
+
 h5part_int64_t
 H5PartGetView (
 	H5PartFile *f,

src/H5PartF.c

@@ -100,6 +100,9 @@
 #define h5pt_setview_indices F77NAME (					\
 					h5pt_setview_indices_,		\
 					H5PT_SETVIEW_INDICES )
+#define h5pt_setview_empty F77NAME (					\
+					h5pt_setview_empty_,		\
+					H5PT_SETVIEW_EMPTY )
 #define h5pt_resetview F77NAME (					\
 					h5pt_resetview_,		\
 					H5PT_RESETVIEW )
@@ -197,6 +200,8 @@ _H5Part_flagsfor2c (
 	while ( flags != NULL ) {
 		if ( strcmp ( flags, "vfd_mpiposix" ) == 0 )
 				fbits |= H5PART_VFD_MPIPOSIX;
+		else if ( strcmp ( flags, "vfd_mpio_ind" ) == 0 )
+				fbits |= H5PART_VFD_MPIIO_IND;
 		else if ( strcmp ( flags, "fs_lustre" ) == 0 )
 		    		fbits |= H5PART_FS_LUSTRE;
 		flags = strtok ( NULL, "," );
@@ -351,16 +356,22 @@ h5pt_openr_par_align (
 	const char *file_name,
 	MPI_Fint *fcomm,
 	const h5part_int64_t *align,
-	const int l_file_name
+	const char *flags,
+	const int l_file_name,
+	const int l_flags
 	) {
 
 	MPI_Comm ccomm = MPI_Comm_f2c (*fcomm);
 	char *file_name2 = _H5Part_strdupfor2c ( file_name, l_file_name );
+	char *flags2 = _H5Part_strdupfor2c ( flags, l_flags );
+
+	char fbits = H5PART_READ | _H5Part_flagsfor2c ( flags2 );
 
 	H5PartFile* f = H5PartOpenFileParallelAlign (
-		file_name2, H5PART_READ, ccomm, *align );
+		file_name2, fbits, ccomm, *align );
 
 	free ( file_name2 );
+	free ( flags2 );
 	return (h5part_int64_t)(size_t)f; 
 }
 
@@ -384,6 +395,7 @@ h5pt_openw_par_align (
 		file_name2, fbits, ccomm, *align );
 
 	free ( file_name2 );
+	free ( flags2 );
 	return (h5part_int64_t)(size_t)f; 
 }
 
@@ -407,6 +419,7 @@ h5pt_opena_par_align (
 		file_name2, fbits, ccomm, *align );
 
 	free ( file_name2 );
+	free ( flags2 );
 	return (h5part_int64_t)(size_t)f;
 }
 #endif
@@ -626,6 +639,16 @@ h5pt_setview_indices (
 	return H5PartSetViewIndices ( filehandle, indices, *nelem );
 }
 
+h5part_int64_t
+h5pt_setview_empty (
+	const h5part_int64_t *f
+	) {
+
+	H5PartFile *filehandle = (H5PartFile*)(size_t)*f;
+
+	return H5PartSetViewEmpty ( filehandle );
+}
+
 h5part_int64_t
 h5pt_resetview (
 	const h5part_int64_t *f