src/hdf5/H5ecloud/ORG/H5Part.h

Go to the documentation of this file.

#ifndef _H5Part_H_
#define _H5Part_H_

#include <hdf5.h>
#ifdef PARALLEL_IO
#include <mpi.h>
#endif

/* 
   H5PartFile:  This is an essentially opaque datastructure that
   acts as the filehandle for all practical purposes.
   It is created by H5PartOpenFile<xx>() and destroyed by
   H5PartCloseFile().  
*/
typedef struct H5PartFile {
  hid_t file;
  int timestep;

  hid_t timegroup;
  hid_t properties;
  int myproc;
  hsize_t nparticles;
  hid_t shape;
  unsigned mode;
  int maxstep;
  hid_t xfer_prop,create_prop,access_prop;
  hid_t diskshape,memshape; /* for parallel I/O (this is on-disk) H5S_ALL 
                    if serial I/O */
#ifdef PARALLEL_IO
  long long *pnparticles;
  MPI_Comm comm;
  int nprocs,myproc;
#endif
}H5PartFile;

#define H5PART_READ 0x01
#define H5PART_WRITE 0x02

/*========== File Opening/Closing ===============*/
/*
  H5PartOpenFile:  Opens file with specified filename. 
    If you open with flag H5PART_WRITE, it will truncate any
    file with the specified filename and start writing to it.
    If you open with H5PART_READ, then it will open the file
    readonly.  I could probably do an APPEND mode as well, but
    just haven't done so yet.  APPEND would need to check the
    file to determine its current state and modify the 
    H5PartFile datastructure accordingly.

    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.

    returns: A new filehandle with an open file or NULL if error.
*/
#ifdef PARALLEL_IO
#include <mpi.h>
H5PartFile *H5PartOpenFileParallel(const char *filename,
                                   unsigned flags,
                                   MPI_Comm communicator);
#endif
/* the pure serial version */
#define H5PartOpenFileSerial(x,y) H5PartOpenFile(x,y)
H5PartFile *H5PartOpenFile(const char *filename, /* name of datafile */
                                 unsigned flags); /* H5PART_READ | H5PART_WRITE */

int H5PartFileIsValid(H5PartFile *f);

/*
  H5PartCloseFile:  Does what it says it does.
*/
void H5PartCloseFile(H5PartFile *f);


/*============== File Writing Functions ==================== */
/*
  H5PartSetNumParticles:  This function's sole purpose is to 
    prevent needless creation of new HDF5 DataSpace handles if
    the number of particles is invariant throughout the sim.
    That's its only reason for existence.  After you call this
    subroutine, all subsequent operations will assume this 
    number of particles will be written.
 */
void H5PartSetNumParticles(H5PartFile *f,long long nparticles);
/*
  H5PartWriteData:  This writes a dataset with the indicated
  name to the currently selected Timestep in the datafile.
  It will be an error if you don't call
     H5PartSetStep()
  before you use this function (but once those things are set, they
  are persistent values... no need to call them before *every* write.)
   Also, you need to have set the
  number of particles that you are storing in this timestep using
     H5PartSetNumParticles()
  It returns a negative value if the write fails.  This either
  indicates that the Timestep or number of particles were not 
  set, *or* you are storing two datasets in the same timestep 
  that have the same name (not allowed).
 */
int H5PartWriteDataFloat64(H5PartFile *f,char *name,double *array);
/* same deal as above, but for 64bit integers */
int H5PartWriteDataInt64(H5PartFile *f,char *name,long long *array);

/*================== File Reading Routines =================*/
/*
  H5PartSetStep:  This routine is *only* useful when you are reading
  data.  Using it while you are writing will generate nonsense results!
  (This file format is only half-baked... robustness is not std equipment!)
  So you use this to random-access the file for a particular timestep.
  Failure to explicitly set the timestep on each read will leave you
  stuck on the same timestep for *all* of your reads.  That is to say
  the writes auto-advance the file pointer, but the reads do not
  (they require explicit advancing by selecting a particular timestep).
*/
void H5PartSetStep(H5PartFile *f, /* file handle */
                   int step); /* current timestep to select (0 to n-1) */


/* 
   H5PartGetNumSteps:  This reads the number of datasteps that are 
     currently stored in the datafile.  (simple return of an int).
     It works for both reading and writing of files, but is probably
     only typically used when you are reading.

     returns: number of timesteps currently stored in the file.
*/
int H5PartGetNumSteps(H5PartFile *f);

/*
  H5PartGetNumDatasets/H5PartGetDatasetName() are both used together
  to find out how many datasets are stored at a particular timestep
  and what their names are if you don't know what they are a-priori.
 */
int H5PartGetNumDatasets(H5PartFile *f);
int H5PartGetDatasetName(H5PartFile *f,int index,char *name,int maxlen);
/*
  H5PartGetNumParticles:  This gets the number of particles 
    that are stored in the current timestep.  It will arbitrarily
    select a timestep if you haven't already set the timestep
    with H5PartSetStep().

    returns: number of particles in current timestep
 */
long long H5PartGetNumParticles(H5PartFile *f);


/*
  H5PartReadArray:  This reads in an individual array from a
    particlar timestep.  Unlike its "Write" mode sibling, this routine
    is completely public and will not have any wacky state dependencies.
    If you haven't selected a particular timestep, it will pick
    the current one.  Also, it assumes you allocated enough space to
    read in all of the particles in this timestep.

    returns: ignore returnval for now (should be used for error handling)
*/
int H5PartReadDataFloat64(H5PartFile *f,
                          char *name, /* name of the array to read
                                         "x"=position in x direction (y,z)
                                         "vx"=velocity in x directio (y,z)
                                         "px"=position in x dir (y,z) */
                          double *array); /* array to read data into */
int H5PartReadDataInt64(H5PartFile *f,
                          char *name, /* name of the array to read
                                         "x"=position in x direction (y,z)
                                         "vx"=velocity in x directio (y,z)
                                         "px"=position in x dir (y,z) */
                          long long *array); /* array to read data into */

/* the following is a back-door for extensions to the data writing */
#if 0
int H5PartReadData(H5PartFile *f,char *name,void *array,hid_t type);
int H5PartWriteData(H5PartFile *f,char *name,void *array,hid_t type);
#endif
/*
  H5PartReadParticleStep:  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
    H5PartSetStep() internally so that you don't have to 
    make that call separately.
    See also: H5PartReadArray() if you want to just
    read in one of the many arrays.

    At this point, I don't think it will be used (too rigid), 
    but it is for example purposes.
*/
int H5PartReadParticleStep(H5PartFile *f, /* filehandle */
                           int step, /* selects timestep to read from*/
                           double *x,double *y,double *z, /* particle positions */
                           double *px,double *py,double *pz, /* particle momenta */
                           long long *id); /* and phase */
/**********==============Attributes Interface============***************/
/* currently there is file attributes:  Attributes bound to the file
   and step attributes which are bound to the current timestep.  You 
   must set the timestep explicitly before writing the attributes (just
   as you must do when you write a new dataset.  Currently there are no
   attributes that are bound to a particular data array, but this could
   easily be done if requred.
*/
int H5PartWriteStepAttrib(H5PartFile *f,char *name,
    hid_t type,void *attrib,int nelem);
int H5PartWriteFileAttrib(H5PartFile *f,char *name,
    hid_t type,void *attrib,int nelem);
int H5PartWriteAttrib(H5PartFile *f,char *name,
                      hid_t type,void *attrib,int nelem); // this should be deprecated
int H5PartWriteFileAttribString(H5PartFile *f,char *name,
    char *attrib);
int H5PartWriteStepAttribString(H5PartFile *f,char *name,
    char *attrib);
int H5PartGetNumStepAttribs(H5PartFile *f); /* for current filestep */
int H5PartGetNumFileAttribs(H5PartFile *f);
void H5PartGetStepAttribInfo(H5PartFile *f,int idx,
    char *name,size_t maxnamelen,
                         hid_t *type,int *nelem);
void H5PartGetFileAttribInfo(H5PartFile *f,int idx,
    char *name,size_t maxnamelen,
    hid_t *type,int *nelem);
void H5PartReadStepAttrib(H5PartFile *f,char *name,void *data);
void H5PartReadAttrib(H5PartFile *f,char *name,void *data);
void H5PartReadFileAttrib(H5PartFile *f,char *name,void *data);


#endif

---