src/hdf5/H5ecloud/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;
  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 */
  long long viewstart,viewend; /* -1 if no view is available: A "view" looks at a subset of the data. */
  
#ifdef PARALLEL_IO
  long long *pnparticles; /* the number of particles in each processor.
                             With respect to the "VIEW", these numbers
                             can be regarded as non-overlapping subsections
                             of the particle array stored in the file.
                             So they can be used to compute the offset of
                             the view for each processor */
  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);

/*
  H5SetView: For parallel I/O or for subsetting operations on
  the datafile, the H5SetView subroutine 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 H5SetView(file,-1,-1);

    Before you set a view, the H5PartGetNumParticles will
    return the total number of particles in a file (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).
*/
void H5PartSetView(H5PartFile *f,long long start,long long end);
#define H5PartResetView(f) H5PartSetView(f,-1,-1)
#define H5PartHasView(f) ((f->viewstart<0||f->viewend<0)?0:1)
/*
  H5PartGetView: Allows you to query the current view.
  it will return 0 and np if there is no view established.
  Use H5PartHasView to see if the view is smaller than the
  total dataset.
 */
int H5PartGetView(H5PartFile *f,long long *start,long long *end);

/* 
   H5SetCanonicalView: If it is too tedious to manually set the
   start and end coordinates for a view, the H5SetCanonicalView()
   will automatically select an appropriate domain decomposition of
   the data arrays for the degree of parallelism and set the "view" 
   accordingly.
*/
void H5PartSetCanonicalView(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);
int H5PartReadStepAttrib(H5PartFile *f,char *name,void *data);
void H5PartReadAttrib(H5PartFile *f,char *name,void *data);
int H5PartReadFileAttrib(H5PartFile *f,char *name,void *data);


/**************** File Stashing Interfaces *************************/
int H5PartStashFile(H5PartFile *f,char *filename);
int H5PartUnstashFile(H5PartFile *f, char *filename, char *outputpath); /* outputpath can be null for cwd */
int H5PartGetNumStashFiles(H5PartFile *f);
int H5PartFileGetStashFileName(H5PartFile *f,int nameindex,char *filename,int maxnamelen);

#endif

---