diff options
Diffstat (limited to 'doc/html/AMRwriter.html')
| -rw-r--r-- | doc/html/AMRwriter.html | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/doc/html/AMRwriter.html b/doc/html/AMRwriter.html new file mode 100644 index 0000000..7c3ec94 --- /dev/null +++ b/doc/html/AMRwriter.html @@ -0,0 +1,395 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<!-- </td><td valign=top><br><br><font face="arial,helvetica"color="#555588"><h2 align=left> Visualization and Virtual Environments</h2></font><p></td></tr> --> + +<html> + <head> + <title>AMR Writer</title> + </head> + + <body bgcolor="#F0F0F0"> + <font face="arial,helvetica"><h1>AMR Writer</h1></font> + 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.<p> + + <font face="arial,helvetica" color="#555588"><h2>Attribute Specification</h2></font> + The following NetCDF-style attributes are added to each + dataset to fully describe its position in the heirarchy. + A <b>grid</b> is one of the dataset blocks in the heirarchy. + These tags are applied to each grid in the heirarchy + to uniquely identify it. + <h4>real-valued attributes</h4> + <dl><DD> + <DL> + <DT><b>origin</b> + <DD>The floating-point origin of the dataset. + <DT><b>delta</b> + <DD>The physical spacing between grid points in the dataset. + <DT><b>min_ext</b> + <DD>The minimum coordinate of the dataset in physical space. + This is actually identical to the <b>origin</b>. + <DT><b>max_ext</b> + <DD>The maximum coordinate of the dataset in physical space. + <DT><b>time</b> + <DD>The current real-valued time that this grid represents. + </DL> + </dl> + <h4>integer-valued attributes</h4> + <dl><DD> + <DL> + <DT><b>level</b> + <DD>The level of this grid in the amr heirarchy. Levels are + numbered from 0-to-(nlevels-1). + <DT><b>timestep</b> + <DD>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. + <DT><b>level_timestep</b> + <DD>The integer timestep for the grid with respect to the + evolution on its particular level. + <DT><b>persistence</b> + <DD>The number of timesteps the grid persists on this + particular level. In terms of the other parameters it is + the number of <i>timestep</i>s per <i>level_timestep</i>. + <DT><b>spatial_refinement</b> + <DD>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. + <DT><b>time_refinement</b> + <DD>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. + <DT><b>grid_placement_refinement</b> + <DD>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). + <DT><b>iorigin</b> + <DD>This is the integer origin of the grid placed in the + coordinates of the spatial_refinement defined above. + </DL> + </dl> + <font face="arial,helvetica" color="#555588"><h2>The API</h2></font> + <UL> + <LI><a href="#CPP">C++ Interface</a> + <LI><a href="#C">C Interface</a> + <LI><a href="#F77">F77/F90 Interface</a> + </UL> + <hr> + <u><h2><a name="CPP">C++ Interface</a></h2></u> + <DL> + <DT><font color="#888888"><b>Constructors/Destructors</b></font> + <DD><DL> + <DT><b>AMRwriter::AMRwriter(IObase + &filehandle)</b> <i>constructor</i> + <DD>The <i>filehandle</i> is an already + <a href="UsingC++.html#Opening">open IEEEIO or HDFIO + file</a>. This initializes the writer and attaches it to that + datafile. + <DT><b>AMRwriter::~AMRwriter()</b> <i>destructor</i> + <DD>This flushes all of the necessary file buffers. + The filehandle that the writer was bound to must be + closed separately though. + </DL> + <DT><font color="#888888"><b>Initialization</b></font> + <DT><DL> + <DT><b>AMRwriter::setType(IObase::DataType datatype)</b> + <DD>Sets the <a href="DataTypes.html">datatype</a> + for datasets written to the file. + The default is Float32 if you don't set this. + <DT><b>AMRwriter::setTopLevelParameters(int rank, double *origin, + double *delta,double timestep)</b> + <DD>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. + <DT><b>AMRwriter::setRefinement(int maxdepth, + int interlevel_timerefinement, int + *interlevel_spatialrefinement, + int *initial_gridplacementrefinement {default=None})</b> + <DD>This sets the integer factors of refinement recursively + for all levels down to a depth of <i>maxdepth.</i> The + <i>interlevel</i> refinements are the integer factor of + refinement between levels. This is always > 1. <br> + The <i>initial_gridplacementrefinement</i> 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 + <i>initial_gridplacementrefinement</i> + 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 + <h4>spatialrefinement @ Level = + level^interlevel_refinement_ratio</h4> + <h4>gridplacementrefinement @ Level = + initial_gridplacement_refinement * + interlevel_spatialrefinement^Level</h4><p> + <DT><b>AMRwriter::setLevelRefinement(int level,int + timerefinement, int *spatialrefinement, int + *gridplacementrefinement)</b> + <DD>This sets the integer factors of refinement for a given + level with respect to the toplevel (0th level). Normally + you would use the <b>setRefinement()</b> method to set this + for all levels in one step. You only need to use + <b>setLevelRefinement()</b> if each level has a different + refinement criteria.<br> 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. + </DL> + <DT><font color="#888888"><b>Writing Data/Stepping</b></font> + <DD><DL> + <DT><b>AMRwriter::setLevel(int *dims)</b> + <DD>This sets the current level. Subsequent + <code>write()</code> operations will assume this + level for purposes of computing refinement and + setting grid attibutes. + <DT><b>AMRwriter::setTime(int time)</b> + <DD>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. + <DT><b>AMRwriter::incrementTime()</b> + <DD>This can be used in lieu of + <code>setTime()</code> 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. + <DT><b>AMRwriter::write(int *origin,int *dims,void *data)</b> + <DD>Write the data for a grid to the file. The origin + is the integer origin using coordinates which are in + terms of the <i>gridplacement refinement</i> + for the current level. + </DL> + </DL> + <hr> + <h2><u><a name="C">C Interface</a></u></h2> + <DL> + <DT><font color="#888888"><b>Opening/Closing</b></font> + <DD><DL> + <DT><b>AMRFile AMRbeginFile(IOFile filehandle)</b> + <DD>The <i>filehandle</i> is an already + <a href="UsingC.html#Opening">open IEEEIO or HDFIO + file</a>. This initializes the reader and attaches it to that + datafile. This also creates a WRFile pointer for use by the + AMRfile API. + <DT><b>AMRendFile(AMRFile filehandle)</b> + <DD>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. + </DL> + <DT><font color="#888888"><b>Initialization</b></font> + <DD><DL> + <DT><b>AMRsetType(AMRFile wrfile,int datatype)</b> + <DD>Sets the <a href="DataTypes.html">datatype</a> + for datasets written to the file. + The default is Float32 if you don't set this. + <DT><b>AMRsetToplevelParameters(AMRFile afile, int rank, double *origin, + double *delta,double timestep)</b> + <DD>This sets the floating-point coordinates and timestep for + the toplevel (level-0) grid. The <i>rank</i> 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. + <DT><b>AMRsetRefinement(AMRFile file,int maxdepth, + int interlevel_timerefinement, int + *interlevel_spatialrefinement, + int *initial_gridplacementrefinement)</b> + <DD>This sets the integer factors of refinement recursively + for all levels down to a depth of <i>maxdepth.</i> The + <i>interlevel</i> refinements are the integer factor of + refinement between levels. This is always > 1. <br> + The <i>initial_gridplacementrefinement</i> 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 + <i>initial_gridplacementrefinement</i> + 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 + <h4>spatial_refinement @ Level = + level^interlevelrefinement_ratio</h4> + <h4>gridplacement_refinement @ Level = + initial_gridplacement_refinement * + interlevel_spatial_refinement^Level</h4><p> + <DT><b>AMRsetLevelRefinement(AMRFile afile,int level,int + timerefinement, int *spatialrefinement, int + *gridplacementrefinement)</b> + <DD>This sets the integer factors of refinement for a given + level with respect to the toplevel (0th level). Normally + you would use the <b>AMRsetRefinement()</b> method to set this + for all levels in one step. You only need to use + <b>setLevelRefinement()</b> if each level has a different + refinement criteria.<br> 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. + </DL> + <DT><font color="#888888"><b>Writing Data/Stepping</b></font> + <DD><DL> + <DT><b>AMRsetLevel(AMRFile file,int level)</b> + <DD>This sets the current level. Subsequent + <code>AMRwrite()</code> operations will assume this + level for purposes of computing refinement and + setting grid attibutes. + <DT><b>AMRsetTime(AMRFile file,int time)</b> + <DD>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. + <DT><b>AMRincrementTime(AMRFile file)</b> + <DD>This can be used in lieu of + <code>AMRsetTime()</code> 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. + <DT><b>AMRwrite(AMRFile file,int *origin,int *dims,void *data)</b> + <DD>Write the data for a grid to the file. The origin + is the integer origin using coordinates which are in + terms of the <i>gridplacement refinement</i> + for the current level. The <i>dims</i> are the + actual dimensions of this grid of data you are writing. + </DL> + </DL> + <hr> + <h2><u><a name="F77">F77/F90 Interface</a></u></h2> + <DL> + <DT><font color="#888888"><b>Opening/Closing</b></font> + <DD><DL> + <DT><b>INTEGER*8 amr_begin(INTEGER*8 filehandle)</b> + <DD>The <i>filehandle</i> is an already + <a href="UsingF77.html#Opening">open IEEEIO or HDFIO + file</a>. This initializes the reader and attaches it to that + datafile. This also creates an INTEGER*8 pointer for use by the + this API. + <DT><b>amr_end(INTEGER*8 filehandle)</b> + <DD>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. + </DL> + <DT><font color="#888888"><b>Initialization</b></font> + <DD><DL> + <DT><b>amr_settype(INTEGER*8 wrfile, INTEGER datatype)</b> + <DD>Sets the <a href="DataTypes.html">datatype</a> + for datasets written to the file. + The default is Float32 if you don't set this. + <DT><b>amr_setparams(INTEGER*8 afile, INTEGER rank, REAL*8 origin(<i>rank</i>), + REAL*8 delta(<i>rank</i>),REAL*8 timestep)</b> + <DD>This sets the floating-point coordinates and timestep for + the toplevel (level-0) grid. The <i>rank</i> 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. + <DT><b>amr_setref(INTEGER*8 file, INTEGER maxdepth, + INTEGER interlevel_timerefinement, INTEGER + interlevel_spatialrefinement(), + INTEGER initial_gridplacementrefinement())</b> + <DD>Set refinement for all grids. + This sets the integer factors of refinement recursively + for all levels down to a depth of <i>maxdepth.</i> The + <i>interlevel</i> refinements are the integer factor of + refinement between levels. This is always > 1. <br> + The <i>initial_gridplacementrefinement</i> 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 + <i>initial_gridplacementrefinement</i> + 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 + <h4>spatialrefinement @ Level = + level^<i>interlevelrefinement_ratio</i></h4> + <h4>gridplacementrefinement @ Level = + <i>initial_gridplacementrefinement</i> * + <i>interlevelspatialrefinement</i>^Level</h4><p> + <DT><b>amr_setlref(INTEGER*8 afile, INTEGER level, INTEGER + timerefinement, INTEGER spatialrefinement(), INTEGER + gridplacementrefinement())</b> + <DD>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 <b>amr_setRefinement()</b> method to set this + for all levels in one step. You only need to use + <b>amr_setlref()</b> if each level has a different + refinement criteria.<br> 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. + </DL> + <DT><font color="#888888"><b>Writing Data/Stepping</b></font> + <DD><DL> + <DT><b>amr_setlevel(INTEGER*8 file, INTEGER level)</b> + <DD>This sets the current level. Subsequent + <code>write()</code> operations will assume this + level for purposes of computing refinement and + setting grid attibutes. + <DT><b>amr_settime(INTEGER*8 file,INTEGER time)</b> + <DD>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. + <DT><b>amr_inctime(INTEGER*8 file)</b> + <DD>This can be used in lieu of + <code>setTime()</code> 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. + <DT><b>amr_write(INTEGER*8 file, INTEGER origin(), INTEGER + dims(), <i>anytype</i> data())</b> + <DD>Write the data for a grid to the file. The origin + is the integer origin using coordinates which are in + terms of the <i>gridplacement refinement</i> + for the current level. The <i>dims</i> are the + actual dimensions of this grid of data you are writing. + </DL> + </DL> + <hr> + <address><a href="mailto:jshalf@suttung.aei-potsdam.mpg.de">John Shalf</a></address> + <!-- Created: Wed May 7 13:32:41 MDT 1997 --> + <!-- hhmts start --> +Last modified: Thu Feb 4 15:18:25 CST 1999 +<!-- hhmts end --> + </body> +</html> |