AMR Writer

This writer stores additional information to fully define and AMR grid heirarchy that evolves through time. Currently it accepts integer grid coordinate definitions and generates floating-point positions internally. However, this interface will be extended to do the reverse for people who's codes use a floating-point representation of grid positions for internal storage.

Attribute Specification

The following NetCDF-style attributes are added to each dataset to fully describe its position in the heirarchy. A grid is one of the dataset blocks in the heirarchy. These tags are applied to each grid in the heirarchy to uniquely identify it.

real-valued attributes

origin
The floating-point origin of the dataset.
delta
The physical spacing between grid points in the dataset.
min_ext
The minimum coordinate of the dataset in physical space. This is actually identical to the origin.
max_ext
The maximum coordinate of the dataset in physical space.
time
The current real-valued time that this grid represents.

integer-valued attributes

level
The level of this grid in the amr heirarchy. Levels are numbered from 0-to-(nlevels-1).
timestep
The integer timestep in the file. This is with respect to the evolution of the finest-resolution grid in the heirarchy. This is in effect the global simulation timestep.
level_timestep
The integer timestep for the grid with respect to the evolution on its particular level.
persistence
The number of timesteps the grid persists on this particular level. In terms of the other parameters it is the number of timesteps per level_timestep.
spatial_refinement
The refinement in each cartesian direction. This is a divisor which defines the refinement with respect to the toplevel (0-th level) grid. So if the toplevel has a real delta of 1.0, then if a grid on a different level has a spatial refinement of 2, then the delta for the grid on that level is 0.5.
time_refinement
The refinement for the timestep with respect to the toplevel (0-th level) grid stepsize. So if the toplevel has a real timestep size of 1.0, then if a higher level grid has a time refinement of 2, then the timestep for the grid on that level is 0.5.
grid_placement_refinement
This was created independently from the spatial_refinement for people who need to place staggered grids. If you don't need staggered grids, then don't set this parameter (by default it is set equal to the spatial_refinement).
iorigin
This is the integer origin of the grid placed in the coordinates of the spatial_refinement defined above.

The API


C++ Interface

Constructors/Destructors
AMRwriter::AMRwriter(IObase &filehandle) constructor
The filehandle is an already open IEEEIO or HDFIO file. This initializes the writer and attaches it to that datafile.
AMRwriter::~AMRwriter() destructor
This flushes all of the necessary file buffers. The filehandle that the writer was bound to must be closed separately though.
Initialization
AMRwriter::setType(IObase::DataType datatype)
Sets the datatype for datasets written to the file. The default is Float32 if you don't set this.
AMRwriter::setTopLevelParameters(int rank, double *origin, double *delta,double timestep)
This sets number of dimentions (rank) for the dataset as well as the floating-point coordinates and timestep for the toplevel (level-0) grid. From this information the floating point parameters for all other grids can be automatically generated from the stored integer coordinate information.
AMRwriter::setRefinement(int maxdepth, int interlevel_timerefinement, int *interlevel_spatialrefinement, int *initial_gridplacementrefinement {default=None})
This sets the integer factors of refinement recursively for all levels down to a depth of maxdepth. The interlevel refinements are the integer factor of refinement between levels. This is always > 1.
The initial_gridplacementrefinement is only required if you need to position the grids at a higher level of refinement than the spatial refinement (eg. if you need to stagger the grids). If you do not specify this parameter, then it will assume the gridplacement refinement is identical to the spatial refinement for each level. The initial_gridplacementrefinement specified here is the initial value of the refinement at the toplevel. The refinement increased proportionally to the spatial refinement. So refinements are computed as

spatialrefinement @ Level = level^interlevel_refinement_ratio

gridplacementrefinement @ Level = initial_gridplacement_refinement * interlevel_spatialrefinement^Level

AMRwriter::setLevelRefinement(int level,int timerefinement, int *spatialrefinement, int *gridplacementrefinement)
This sets the integer factors of refinement for a given level with respect to the toplevel (0th level). Normally you would use the setRefinement() method to set this for all levels in one step. You only need to use setLevelRefinement() if each level has a different refinement criteria.
From this, and the Toplevel floating point information, floating point grid-placement information can be computed automatically. If gridplacementrefinement is left NULL, then it is assumed that it is identical to the spatialrefinement. Storing this information as integers reduces the chance of problems caused by roundoff error. Perhaps an "epsilon" should be stored to specify a tolerance for the roundoff.
Writing Data/Stepping
AMRwriter::setLevel(int *dims)
This sets the current level. Subsequent write() operations will assume this level for purposes of computing refinement and setting grid attibutes.
AMRwriter::setTime(int time)
This sets the integer timestep for the data. This is normally with respect to the finest level of refinement. However, if you are only writing the hierarchy when the toplevel timestep is changed, then this can be with respect to the toplevel timestep.
AMRwriter::incrementTime()
This can be used in lieu of setTime() if you don't have a global time counter availible to you in the IO routines. The timestep is maintained internally by the class and incremented whenever you call this incrementTime() method.
AMRwriter::write(int *origin,int *dims,void *data)
Write the data for a grid to the file. The origin is the integer origin using coordinates which are in terms of the gridplacement refinement for the current level.

C Interface

Opening/Closing
AMRFile AMRbeginFile(IOFile filehandle)
The filehandle is an already open IEEEIO or HDFIO file. This initializes the reader and attaches it to that datafile. This also creates a WRFile pointer for use by the AMRfile API.
AMRendFile(AMRFile filehandle)
This flushes all of the necessary file buffer and deallocates the AMRFile pointer. The filehandle that the writer was bound to must be closed separately though.
Initialization
AMRsetType(AMRFile wrfile,int datatype)
Sets the datatype for datasets written to the file. The default is Float32 if you don't set this.
AMRsetToplevelParameters(AMRFile afile, int rank, double *origin, double *delta,double timestep)
This sets the floating-point coordinates and timestep for the toplevel (level-0) grid. The rank is the number of dimensions for the dataset and is set for all subgrids of this dataset. From this information the floating point parameters for all other grids can be automatically generated from the stored integer coordinate information.
AMRsetRefinement(AMRFile file,int maxdepth, int interlevel_timerefinement, int *interlevel_spatialrefinement, int *initial_gridplacementrefinement)
This sets the integer factors of refinement recursively for all levels down to a depth of maxdepth. The interlevel refinements are the integer factor of refinement between levels. This is always > 1.
The initial_gridplacementrefinement is only required if you need to position the grids at a higher level of refinement than the spatial refinement (eg. if you need to stagger the grids). If you specify this parameter as NULL, then it will assume the gridplacement refinement is identical to the spatial refinement for each level. The initial_gridplacementrefinement specified here is the initial value of the refinement at the toplevel. The refinement increased proportionally to the spatial refinement. So refinements are computed as

spatial_refinement @ Level = level^interlevelrefinement_ratio

gridplacement_refinement @ Level = initial_gridplacement_refinement * interlevel_spatial_refinement^Level

AMRsetLevelRefinement(AMRFile afile,int level,int timerefinement, int *spatialrefinement, int *gridplacementrefinement)
This sets the integer factors of refinement for a given level with respect to the toplevel (0th level). Normally you would use the AMRsetRefinement() method to set this for all levels in one step. You only need to use setLevelRefinement() if each level has a different refinement criteria.
From this, and the Toplevel floating point information, floating point grid-placement information can be computed automatically. If gridplacementrefinement is left NULL, then it is assumed that it is identical to the spatialrefinement. Storing this information as integers reduces the chance of problems caused by roundoff error. Perhaps an "epsilon" should be stored to specify a tolerance for the roundoff.
Writing Data/Stepping
AMRsetLevel(AMRFile file,int level)
This sets the current level. Subsequent AMRwrite() operations will assume this level for purposes of computing refinement and setting grid attibutes.
AMRsetTime(AMRFile file,int time)
This sets the integer timestep for the data. This is normally with respect to the finest level of refinement. However, if you are only writing the hierarchy when the toplevel timestep is changed, then this can be with respect to the toplevel timestep.
AMRincrementTime(AMRFile file)
This can be used in lieu of AMRsetTime() if you don't have a global time counter availible to you in the IO routines. The timestep is maintained internally by the class and incremented whenever you call this AMRincrementTime() method.
AMRwrite(AMRFile file,int *origin,int *dims,void *data)
Write the data for a grid to the file. The origin is the integer origin using coordinates which are in terms of the gridplacement refinement for the current level. The dims are the actual dimensions of this grid of data you are writing.

F77/F90 Interface

Opening/Closing
INTEGER*8 amr_begin(INTEGER*8 filehandle)
The filehandle is an already open IEEEIO or HDFIO file. This initializes the reader and attaches it to that datafile. This also creates an INTEGER*8 pointer for use by the this API.
amr_end(INTEGER*8 filehandle)
This flushes all of the necessary file buffer and deallocates the INTEGER*8 pointer. The filehandle that the writer was bound to must be closed separately though.
Initialization
amr_settype(INTEGER*8 wrfile, INTEGER datatype)
Sets the datatype for datasets written to the file. The default is Float32 if you don't set this.
amr_setparams(INTEGER*8 afile, INTEGER rank, REAL*8 origin(rank), REAL*8 delta(rank),REAL*8 timestep)
This sets the floating-point coordinates and timestep for the toplevel (level-0) grid. The rank is the number of dimensions for the dataset and is set for all subgrids of this dataset. From this information the floating point parameters for all other grids can be automatically generated from the stored integer coordinate information.
amr_setref(INTEGER*8 file, INTEGER maxdepth, INTEGER interlevel_timerefinement, INTEGER interlevel_spatialrefinement(), INTEGER initial_gridplacementrefinement())
Set refinement for all grids. This sets the integer factors of refinement recursively for all levels down to a depth of maxdepth. The interlevel refinements are the integer factor of refinement between levels. This is always > 1.
The initial_gridplacementrefinement is only required if you need to position the grids at a higher level of refinement than the spatial refinement (eg. if you need to stagger the grids). If you specify this parameter as NULL, then it will assume the gridplacement refinement is identical to the spatial refinement for each level. The initial_gridplacementrefinement specified here is the initial value of the refinement at the toplevel. The refinement increased proportionally to the spatial refinement. So refinements are computed as

spatialrefinement @ Level = level^interlevelrefinement_ratio

gridplacementrefinement @ Level = initial_gridplacementrefinement * interlevelspatialrefinement^Level

amr_setlref(INTEGER*8 afile, INTEGER level, INTEGER timerefinement, INTEGER spatialrefinement(), INTEGER gridplacementrefinement())
LevelRefinement (refinement per level). This sets the integer factors of refinement for a given level with respect to the toplevel (0th level). Normally you would use the amr_setRefinement() method to set this for all levels in one step. You only need to use amr_setlref() if each level has a different refinement criteria.
From this, and the Toplevel floating point information, floating point grid-placement information can be computed automatically. If gridplacementrefinement is left NULL, then it is assumed that it is identical to the spatialrefinement. Storing this information as integers reduces the chance of problems caused by roundoff error. Perhaps an "epsilon" should be stored to specify a tolerance for the roundoff.
Writing Data/Stepping
amr_setlevel(INTEGER*8 file, INTEGER level)
This sets the current level. Subsequent write() operations will assume this level for purposes of computing refinement and setting grid attibutes.
amr_settime(INTEGER*8 file,INTEGER time)
This sets the integer timestep for the data. This is normally with respect to the finest level of refinement. However, if you are only writing the hierarchy when the toplevel timestep is changed, then this can be with respect to the toplevel timestep.
amr_inctime(INTEGER*8 file)
This can be used in lieu of setTime() if you don't have a global time counter availible to you in the IO routines. The timestep is maintained internally by the class and incremented whenever you call this incrementTime() method.
amr_write(INTEGER*8 file, INTEGER origin(), INTEGER dims(), anytype data())
Write the data for a grid to the file. The origin is the integer origin using coordinates which are in terms of the gridplacement refinement for the current level. The dims are the actual dimensions of this grid of data you are writing.

John Shalf
Last modified: Thu Feb 4 15:18:25 CST 1999