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
- 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.
- 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.
- 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