1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
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>
|
