Main Page   File List   File Members  

AMR-HDF5.h File Reference

#include "AMRData.h"

Include dependency graph for AMR-HDF5.h:

Include dependency graph

Go to the source code of this file.

Client-side functions

void AMR_OpenHDF5 (char *filename, int MPI_Communicator, int m, int *hdf5)
void AMR_CloseHDF5 (int hdf5)
void AMR_WriteData (int hdf5, int numLevels, int *levelData, int ncomp, char **compNames, int *refineFactor, double *spacing, double time, double dt, CONST int *domain_lo, CONST int *domain_hi)
void AMR_WriteStringAttribute (int hdf5, char *name, char *value)
void AMR_ReadMetaData (int hdf5, int *numLevels, int *ncomp, int *ndim, double *spacingCoarse, int *domain_lo_valid, int *domain_hi_valid, double *time, double *dtCoarse)
void AMR_ReadCompName (int hdf5, char **names)
void AMR_ReadNumBoxes (int hdf5, int level, int *ntotalBoxes)
void AMR_ReadBoxes (int hdf5, int level, int *loValid, int *hiValid, int *loRange, int *hiRange)
void AMR_ReadRefFactors (int hdf5, int *refs)
void AMR_ReadLevel (int hdf5, int level, int levelDatahandle, int compBegin, int ncomp)
void AMR_ReadPatch (int hdf5, int level, int patch, int comp, void *d_ptr)
void AMR_ReadStringAttribute (int hdf5, char *name, char **value)

Fortran binding for AMR-HDF5

void amropenhdf5_ (char *filename, long int length, int *MPI_Communicator, int *m, int *hdf5)
void amrclosehdf5_ (int *hdf5)
void amrwritedata_ (int *hdf5, int *numLevels, int *levelData, int *ncomp, int *refineFactor, double *spacing, double *time, double *dt, int *domain_lo, int *domain_hi)
void amrwritecompname_ (int *hdf5, int *compIndex, char *compname, long int length)
void amrreadmetadata_ (int *hdf5, int *numLevels, int *ncomp, int *ndim, double *spacingCoarse, int *domain_lo_valid, int *domain_hi_valid, double *time, double *dtCoarse)
void amrreadcompname_ (int *hdf5, int *compIndex, char *names, long int length)
void amrreadnumboxes_ (int *hdf5, int *level, int *ntotalBoxes)
void amrreadboxes_ (int *hdf5, int *level, int *loValid, int *hiValid, int *loRange, int *hiRange)
void amrreadreffactors_ (int *hdf5, int *refs)
void amrreadlevel_ (int *hdf5, int *level, int *levelDatahandle, int *compBegin, int *ncomp)
void amrreadpatch_ (int *hdf5, int *level, int *patch, int *comp, void *d_ptr)

Function Documentation

void AMR_CloseHDF5 (  int    hdf5 ) 
 

Close an HDF5 file. this integer opaque handle is will now cause the code to abort if used in other AMR_ functions.

void AMR_OpenHDF5 (  char *    filename,
int    MPI_Communicator,
int    m,
int *    hdf5
) 
 

Opens an AMR-HDF5 file

Parameters:
filename  : name of hdf5 file
m  : which mode, 0 - Create, 1 - OPEN_RDONLY, 2 - OPEN_RDWR
MPI_Communicator:  Integer representation of your MPI communicator. When not running under MPI this value is ignored. When running under MPI this communicator is used for the parallel file opening (MPI-IO interface). you can create an integer representation for the communicator using the functions MPI_Comm_c2f and MPI_Comm_f2c
hdf5  : an integer supplied by the caller, which is filled in with a handle.

void AMR_ReadBoxes (  int    hdf5,
int    level,
int *    loValid,
int *    hiValid,
int *    loRange,
int *    hiRange
) 
 

Caller allocates space to store arrays of data for the region definitions of all the patches and then makes a call to read them. Every processor that makes this call will receive a full list of box definitions. the int arrays are assumed to be allocated to hold ntotalBoxes of integers.

void AMR_ReadCompName (  int    hdf5,
char **    names
) 
 

Now that the caller know how many vars per cell exist, he can allocate an array of pointers to char (array length = ncomp, as obtained above). The caller then sends them in, where the callee mallocs memory to each element of the array and writes in the variable names. The caller frees the memory.

Parameters:
hdf5  : file handle
names  : pointer to the array of pointers that the caller allocates.

void AMR_ReadLevel (  int    hdf5,
int    level,
int    levelDatahandle,
int    compBegin,
int    ncomp
) 
 

At this point the caller has enough info to create Levels as per the methods in AMRData.h. Once these empty levels have been created, they can be filled up from the file. This method is called in a loop, looping over all the levels

Parameters:
hdf5  : file handle
level  : The caller needs data on this level
levelDatahandle  : used by the callee to refer back to his data structures
compBegin:  at which component in the file reading should begin
ncomp:  number of contiguous components to be read, starting at compBegin. it is assumed that the user is passing in a levelDatahandle that has sufficient storage allocated for this amount of data.

void AMR_ReadMetaData (  int    hdf5,
int *    numLevels,
int *    ncomp,
int *    ndim,
double *    spacingCoarse,
int *    domain_lo_valid,
int *    domain_hi_valid,
double *    time,
double *    dtCoarse
) 
 

The following methods are to be used when reading in a file for the first time. The caller has no idea how many levels exist and neither does he have the LevelDatas created. This it time t = 0.

In these calls, all the meomy is allocated by the caller and the callee only fills them up. The caller deletes the memory.

Parameters:
hdf5  : file handle, as obtained above.
numLevels  : an integer, supplied by caller and filled by callee, re the number of levels in the file.
ma ncomp : number of variables per grid cell stored in
the file.
Parameters:
ndim  : 1D/2D/3D ?
spacingCoarse  : an oversized double array, at least 3 long, into which the callee will write in the {dx, dy, dz} of the coarse mesh.
domain_lo_valid  : an oversized array, at least 3 long, into which the lower bounding box corner indices of the entire domain (and not just the piece on this processor) is written in by the callee. These indices exclude the ghost/halo cells
domain_hi_valid  : same as above, but for the upper bounding box corner
time  : This data dump corresponds to time = ?
dtCoarse  : And the dt on the coarse mesh at thie momemt was ?

void AMR_ReadNumBoxes (  int    hdf5,
int    level,
int *    ntotalBoxes
) 
 

The caller now knows the number of levels but needs to know the number of patches on each level. This method is called in a loop over numLevels, obtained above.

Parameters:
hdf5  : file handle
level  : give the caller info regarding this level
ntotalBoxes  : an integer, sent in by the caller, into which the callee fills in the total number of patches, on level "level" across all processors.

void AMR_ReadPatch (  int    hdf5,
int    level,
int    patch,
int    comp,
void *    d_ptr
) 
 

This method provides the ability to read data in a controled manner. This is useful for navigating a large data file on a computer that cannot read the entire data set.

Parameters:
hdf5  : file pointer
level  : which level
patch  : patch of interest
comp  : which variable is the caller interested in.
d_ptr  : start putting in data here. User is responsible for ensuring the memory address pointed to by d_ptr has sufficient space to hold the read data.

void AMR_ReadRefFactors (  int    hdf5,
int *    refs
) 
 

Now that the caller knows the total number of level, he allocates an int array, numLevels long into which the refinement factor for each level will be written.

Parameters:
hdf5  : file handle
refs  : an int array, numLevels long
NOTE : refinement factor for the level denotes how coarse it is w.r.t to the immediately finer level. The finest level will have its ref set to 1.

void AMR_ReadStringAttribute (  int    hdf5,
char *    name,
char **    value
) 
 

void AMR_WriteData (  int    hdf5,
int    numLevels,
int *    levelData,
int    ncomp,
char **    compNames,
int *    refineFactor,
double *    spacing,
double    time,
double    dt,
CONST int *    domain_lo,
CONST int *    domain_hi
) 
 

Write out a set of levels to file. This assumes that you have gone through the functions in AMRData.h, creates a number of Levels, have their handles and have filled them with data. Now it's time to write them to file

Parameters:
hdf5  : the file handle, returned by openHDF5() above.
numLevels  : an integer which tells the callee how many levels exist
levelData  : an int array, numLevels long, containing the level handles created by the methods in AMRData.h
ncomp  : number of variables per cell, being stored in the HDF5 file.
compNames  : pointer to an array of pointers to char (array length = ncomp). The callee will malloc memory to each of the array elements and fill them up with the names of the components (e.g. "Pressure", "rho"). The caller deletes this memory.
refineFactor  : an array, numLevels long, that the caller fills up with the refinement factor. refinement factor is the factor by which a level is coarser that the immediately finer level. The finest level will have its refineFactor set to -1 - this serves as an error check, in case someone misinterprets refineFactor. NOTE: For GrACE, refineFactor is a constant; for Chombo it varies.
spacing  : a double array, dimension long, into which dx, dy and dz for the coarse mesh has been written by the caller. dx, dy, dz for finer meshes can be derived using refineFactor.
double  time : unsteady simulation's time variable at which this data existed.
dt  : delta t on the coarse mesh, when the data was dumped.
domain_lo  : int array, dimension long, containing the indices of the lower bounding box corner for the entire domain (and not just the subdomain on this processor).
domain_hi  : ditto as above, but for upper bounding box corner.

void AMR_WriteStringAttribute (  int    hdf5,
char *    name,
char *    value
) 
 

Parameters:
hdf5:  file handle.
name:  attribute name. Cannot use '/' in name
value:  value of attribute.

void amrclosehdf5_ (  int *    hdf5 ) 
 

void amropenhdf5_ (  char *    filename,
long int    length,
int *    MPI_Communicator,
int *    m,
int *    hdf5
) 
 

amropenhdf5_ takes is invoked in Fortran as : 

	INTEGER communicator, m, filehandle
	CHARACTER(LEN=12):: filename = 'output.hdf5'
	filename(12) = CHAR(0)
	CALL amropenhdf5(filename, communicator, m, filehandle)
This works for some fortran compilers. Fortran compilers automatically add the 'length' argument for you. I'm not an expert in passing strings between fortran and C. the c implmentation is expecting a null terminated string. If somone wants to help debug the fortran binding, that would be nice.

This applies for the component name writing routines as well

void amrreadboxes_ (  int *    hdf5,
int *    level,
int *    loValid,
int *    hiValid,
int *    loRange,
int *    hiRange
) 
 

void amrreadcompname_ (  int *    hdf5,
int *    compIndex,
char *    names,
long int    length
) 
 

See also:
amropenhdf5_ , amrwritecompname_

void amrreadlevel_ (  int *    hdf5,
int *    level,
int *    levelDatahandle,
int *    compBegin,
int *    ncomp
) 
 

void amrreadmetadata_ (  int *    hdf5,
int *    numLevels,
int *    ncomp,
int *    ndim,
double *    spacingCoarse,
int *    domain_lo_valid,
int *    domain_hi_valid,
double *    time,
double *    dtCoarse
) 
 

void amrreadnumboxes_ (  int *    hdf5,
int *    level,
int *    ntotalBoxes
) 
 

void amrreadpatch_ (  int *    hdf5,
int *    level,
int *    patch,
int *    comp,
void *    d_ptr
) 
 

void amrreadreffactors_ (  int *    hdf5,
int *    refs
) 
 

void amrwritecompname_ (  int *    hdf5,
int *    compIndex,
char *    compname,
long int    length
) 
 

See also:
amropenhdf5_

void amrwritedata_ (  int *    hdf5,
int *    numLevels,
int *    levelData,
int *    ncomp,
int *    refineFactor,
double *    spacing,
double *    time,
double *    dt,
int *    domain_lo,
int *    domain_hi
) 
 

Fortran wrapper for AMR_WriteData, except it does not pass in an array of strings for component names. passing strings from Fortan and C is tricky. Other functions handle the work of IO for fortran component names

See also:
AMR_WriteData , amrwritecompname_ , amrreadcompname_

Generated on Wed Apr 16 14:57:22 2003 for AMRInteroperability by doxygen1.2.16