From bf0225505894535a9ae36f02a3f6efa6642c5c00 Mon Sep 17 00:00:00 2001 From: tradke Date: Wed, 6 Aug 2003 12:23:27 +0000 Subject: Added FlexIO documentation in HTML format. Taken from the (almost forgotten) repository /afs/aei/cvsroot/IEEEIO/doc. Should be the same as on http://zeus.ncsa.uiuc.edu/~jshalf/FlexIO/. git-svn-id: http://svn.cactuscode.org/arrangements/CactusExternal/FlexIO/trunk@50 21a6bef8-4479-4f54-8f8d-0db94a2919ef --- doc/documentation.tex | 19 +- doc/html/AMRfileReader.html | 157 ++++++++++++ doc/html/AMRreaderBase.html | 100 ++++++++ doc/html/AMRucdReader.html | 142 +++++++++++ doc/html/AMRwriter.html | 395 +++++++++++++++++++++++++++++ doc/html/AmrGrid.html | 164 +++++++++++++ doc/html/Aquiring.html | 102 ++++++++ doc/html/DataTypes.html | 188 ++++++++++++++ doc/html/HighLev.html | 43 ++++ doc/html/IEEEIO.html | 48 ++++ doc/html/IOspeed.cc | 86 +++++++ doc/html/Images/FlexIO.gif | Bin 0 -> 15622 bytes doc/html/Images/ieeeiotitle.gif | Bin 0 -> 5346 bytes doc/html/Images/info.gif | Bin 0 -> 1123 bytes doc/html/Images/info.s.gif | Bin 0 -> 234 bytes doc/html/Performance.html | 423 ++++++++++++++++++++++++++++++++ doc/html/UCDwriter.html | 57 +++++ doc/html/Using.html | 68 +++++ doc/html/UsingC++.html | 442 +++++++++++++++++++++++++++++++++ doc/html/UsingC.html | 505 ++++++++++++++++++++++++++++++++++++++ doc/html/UsingF77.html | 532 ++++++++++++++++++++++++++++++++++++++++ doc/html/UsingIDL.html | 154 ++++++++++++ doc/html/Utilities.html | 120 +++++++++ doc/html/VizReaders.html | 109 ++++++++ doc/html/Writer.html | 172 +++++++++++++ doc/html/changes.html | 37 +++ doc/html/index.html | 65 +++++ doc/html/why.html | 115 +++++++++ doc/html/writef77.f | 17 ++ 29 files changed, 4250 insertions(+), 10 deletions(-) create mode 100644 doc/html/AMRfileReader.html create mode 100644 doc/html/AMRreaderBase.html create mode 100644 doc/html/AMRucdReader.html create mode 100644 doc/html/AMRwriter.html create mode 100644 doc/html/AmrGrid.html create mode 100644 doc/html/Aquiring.html create mode 100644 doc/html/DataTypes.html create mode 100644 doc/html/HighLev.html create mode 100644 doc/html/IEEEIO.html create mode 100644 doc/html/IOspeed.cc create mode 100644 doc/html/Images/FlexIO.gif create mode 100644 doc/html/Images/ieeeiotitle.gif create mode 100644 doc/html/Images/info.gif create mode 100644 doc/html/Images/info.s.gif create mode 100644 doc/html/Performance.html create mode 100644 doc/html/UCDwriter.html create mode 100644 doc/html/Using.html create mode 100644 doc/html/UsingC++.html create mode 100644 doc/html/UsingC.html create mode 100644 doc/html/UsingF77.html create mode 100644 doc/html/UsingIDL.html create mode 100644 doc/html/Utilities.html create mode 100644 doc/html/VizReaders.html create mode 100644 doc/html/Writer.html create mode 100644 doc/html/changes.html create mode 100644 doc/html/index.html create mode 100644 doc/html/why.html create mode 100644 doc/html/writef77.f diff --git a/doc/documentation.tex b/doc/documentation.tex index 5ddaefa..02fc640 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -1,7 +1,7 @@ \documentclass{article} % Use the Cactus ThornGuide style file -% (Automatically used from Cactus distribution, if you have a +% (Automatically used from Cactus distribution, if you have a % thorn without the Cactus Flesh download this from the Cactus % homepage at www.cactuscode.org) \usepackage{../../../../doc/ThornGuide/cactus} @@ -9,7 +9,7 @@ \begin{document} \title{FlexIO} -\author{Thomas Radke, John Shalf} +\author{John Shalf} \date{$ $Date$ $} \maketitle @@ -19,7 +19,7 @@ \section{Purpose} -Thorn FlexIO provides a library for writing multidimensional data from +Thorn FlexIO provides a library for writing multidimensional data from Cactus using the IEEEIO data format. The advantage of using this library is that it is distributed with Cactus and needs no additional libraries to be installed on a machine. @@ -53,20 +53,19 @@ MPIO interface provides access to parallel IO for MPI codes. \section{More Information} -For more information the reader is directed to the web pages for +For more information the reader is directed to the web pages for FlexIO at -{\tt http://infinite-entropy.lbl.gov/FlexIO/} +\begin{itemize} + \item \verb|http://infinite-entropy.lbl.gov/FlexIO/| + \item \verb|http://zeus.ncsa.uiuc.edu/~jshalf/FlexIO/| + \item in the thorn's directory \verb|CactusExternal/FlexIO/doc/html/| +\end{itemize} Information can be found on these web pages about - \begin{itemize} - \item{} Programming interfaces, including C, C++ and Fortran - \item{} Utilities, for finding information about IEEEIO data files - \item{} Data converters, between IEEEIO and HDF - \end{itemize} % Do not delete next line diff --git a/doc/html/AMRfileReader.html b/doc/html/AMRfileReader.html new file mode 100644 index 0000000..21749b3 --- /dev/null +++ b/doc/html/AMRfileReader.html @@ -0,0 +1,157 @@ + + + + AmrFileReader + + + +

AmrFileReader

 + + The AmrGridReader only provides + unfiltered access to the grids stored in the AMR datafile. For a + real visualization application, it is necessary to filter through + these grids to present only what is relevant for a particular + domain and timestep. The AmrFileReader provides that sort + of filtering capability.

+ The AmrFileReader selects all grids that are active at a + particular timestep in the evolution sequence. It also allows + you to mask out sets of levels (for example only show levels 1-3 + of a 7 level hierarchy). Since the stepping of grids proceeds + at different paces at different levels, the timestep is a global + quantity that refers to the finest granularity of stepping that + can occur during the evolution (the integer timesteps of the + deepest level of refinement). The API is intelligent enough to + only reload data from grids that have changed when a different + timestep has been selected since deeper-level grids will change + more rapidly than their parent grids.

+

+

The API

 + +
+

C++ Interface

 +
+
Constructors/Destructors +
+
AmrFileReader::AmrFileReader(IObase + &filehandle) constructor +
The filehandle is an already + open IEEEIO or HDFIO + file. This initializes the reader and attaches it to that + datafile. +
AmrFileReader::~AmrFileReader() destructor +
This flushes all of the necessary file buffers. + The filehandle that the reader was bound to must be + closed separately though. +
+
Queries about File Contents +
+
int AmrFileReader::nLevels() +
Returns the number of levels in the AMR hierarchy. This is + the deepest the hierarchy gets in this particular datafile as + opposed to the number of levels present at this time in the + evolution (this distinction is important for adaptive depth + schemes where the number of levels will change depending on + the demands of the solver). +
AmrFileReader::getTimeRange(int &mintime,int &maxtime) +
Gets the range of integer timesteps stored in the file. + The nonzero mintime exists to support schemes where the + evolution is broken up among several files. +
+
Filters +
The filter methods listed below select grids based on + the criteria of time and level number. Grids selected by the + filter are referred to as active grids.

+

+
AmrFileReader::setTime(int time) +
Sets the current timestep to select the data hierarchy for. + The timestep is defined with respect to the rate at which + grids change at the deepest level of the AMR hierarchy stored + in the file. Selecting a particular timestep selects a + snapshot of the hieararchy at a particular time in the + evolution. +
AmrFileReader::hideLevel(int level) +
By default all levels are visible and are read in when the + getGrids() method is called. You can hide + individual levels using this method. This is useful when + loading the entire hierarchy is either too confusing, too slow, or too + large for the workstation to handle. +
AmrFileReader::showLevel(int level) +
Shows a level that has otherwise been hidden. +
AmrFileReader::showAllLevels() +
A convenience method for making all of the levels visible. +
+
Getting the Data +
+
int AmrFileReader::getGrids(FlexArray<AmrGrid> &g) +
Gets all currently active grids and puts them into a + FlexArray of + AmrGrid datastructures. An + active grid is one that is currently selected by the + setTime() and show/hideLevel() filters. The + FlexArray is a simple template class for arrays that grow + automatically to accomodate new elements. If you or your + compiler do not like templates, then you can use the two-step + static allocation method + (getNumGrids()/getGrids()) defined + below. + This method returns the number of active grids. +
int AmrFileReader::getNumGrids() +
Returns the total number of active grids currently selected + by the setTime() and + show/hideLevel() + filters. This is used to determine how + large of an array of AmrGrid structures to allocate in order + to receive the data using the getGrids() method + call since this array length is static. +
int AmrFileReader::getGrids(AmrGrid *grids) +
This method reads the grid information and data for all + currently active grids into the pre-allocated array of + grids passed to it. The API will allocate memory + for the grids upon reading the data, but it is the responsibility of + the programmer to dispose of the array of grids and the data + stored within these datastructures once they are done with it. +
+
Utility and Debugging Methods +
+
AmrFileReader::setDataLoadingOff() +
This causes the getGrids() methods + to read in the informational part of + the AmrGrid datastructures, but not load any data. This is + useful for just aquiring bounding box information or + estimating the memory/computational requirements for loading + the entire hierarchy. +
AmrFileReader::setDataLoadingOn() +
This causes the getGrids() methods + to read both the informational and data part of + the AmrGrid datastructures. This is the default state for + this API. +
printGridInfo() +
Prints information about all grids in file to STDERR. Used + only for debugging. +
printActiveGrids() +
Prints information about all active grids to STDERR. + Used only for debugging. +
int debug + This is a public variable that can be set to a nonzero value + in order to print additional debugging information for each + method call. This printing is turned off when it is set to zero. +
+
+
+

C Interface

+ Not ready yet. +
+

F77/F90 Interface

+ Not ready yet. +
+
+ + +Last modified: Thu Feb 4 17:49:33 CST 1999 + + + diff --git a/doc/html/AMRreaderBase.html b/doc/html/AMRreaderBase.html new file mode 100644 index 0000000..7f3d1ea --- /dev/null +++ b/doc/html/AMRreaderBase.html @@ -0,0 +1,100 @@ + + + + Basic AMR Reader + + + +

Basic AMR Reader

 + This reads the file format written by the + AMRwriter API. It does not care if + the underlying file format is IEEEIO or + HDF-SDS/NetCDF.

+ This very simplistic API reads information about each grid + stored in the AMR file into a list of + AmrGrid datastructures without + actually loading the associated grid data. The user can + then use this information to tell the AMRreader which grids to + load data for. The higher-level AmrFileReader + provides its own filtering system for selecting grids by level + and timestep. At this time only a C++ interface is released. + C and F77 interfaces are available on request.

+

+

The API

 + +
+

C++ Interface

 +
+
Constructors/Destructors +
+
AmrGridReader::AmrGridReader(IObase + &filehandle) constructor +
The filehandle is an already + open IEEEIO or HDFIO + file. This initializes the reader and attaches it to that + datafile. +
AmrGridReader::~AmrGridReader() destructor +
This flushes all of the necessary file buffers. + The filehandle that the writer was bound to must be + closed separately though. +

+

Reading/Stepping through the + Data
+
+ Grids are indexed from 0 to nDatasets-1 (where nDatasets are + the total number of grids stored in the file). The grids are + indexed in exactly the order they are stored in the file + (there is no sorting of indices here). So its up to the user + of the API to use the AmrGrid + datastructures to select which grids to actually load data for.

+ There are two different types of "get" requests that + can be filled. When you "getGridInfo", only the + informational portions of the + AmrGrid datastructure are filled + out. When you "getGridData" then both the + grid information and associated data will be loaded into the + AmrGrid datastructure.

+

+
AmrGrid *AmrGridReader::getGridInfo(AmrGrid &grid,int index) +
Fills out the informational portions of the + AmrGrid datastructure. + The data member of the structure is left NULL. Returns + a pointer to the AmrGrid if it is successful and a NULL if it fails. +
AmrGrid *AmrGridReader::getGridData(AmrGrid &grid,int index) +
Fills out the informational portions of the + AmrGrid datastructure and also + loads the associated grid data into the data member of + the AmrGrid datastructure. If the data member is NULL, + it will allocate storage for it (which the user is responsible + for freeing), otherwise it will load the data directly into + existing storage pointed to by that member. Returns pointer + to the AmrGrid if it is successful and returns NULL if it fails. +
AmrGrid *AmrGridReader::getGrid(AmrGrid &grid,int index) +
Performs the same function as + AmrGridReader::getGridData(). Just a more + convenient name. +
AmrGrid *AmrGridReader::getGrid(int index) +
Performs the same function as + AmrGridReader::getGridData() except that it + allocates a new AmrGrid datastructure to store the information + and data in. The user is responsible for freeing this + structure when they are done with it though. +
+
+

C Interface

+ Not ready for primetime yet but available on request. +
+

F77/F90 Interface

+ Not ready for primetime yet but available on request. +
+
+ + +Last modified: Thu Feb 4 15:45:03 CST 1999 + + + diff --git a/doc/html/AMRucdReader.html b/doc/html/AMRucdReader.html new file mode 100644 index 0000000..6bad528 --- /dev/null +++ b/doc/html/AMRucdReader.html @@ -0,0 +1,142 @@ + + + + AMR-UCD Reader + + + +

AMR-UCD Reader

+ + Most visualization systems have no provisions for handling AMR + data. One solution is to resample all of the grids into a single + uniform sized grid. However for even a 7 level hierarchy, the + unigrid becomes far too large to be manageable and still retain + the fidelity of the original data. A second solution is use + unigrid visualization algorithms on each grid in the hierarchy and + then superimpose them on one-another. In this case geometries + from the coarser resolution datasets occlude the finer-resolution + geometry. An alternative solution is to convert the data into + hexahedral cells with the overlaps between parent levels and the + children are eliminated. This provides multi-resolution fidelity which + matches the nature of the original data but allows it to be + visualized using standard off-the-shelf visualizaton tools.

+ + The AmrUcdFileReader inherits directly from the + AmrFileReader and + all methods from its base class are public. They will be + listed again here for convenience. The only method (aside from + the constructor/destructor) that is contributed by this class is + the getUcd() method.

+ +

+

The API

 + +
+

C++ Interface

 +
+
Constructors/Destructors +
+
AmrUcdFileReader::AmrUcdFileReader(IObase + &filehandle) constructor +
The filehandle is an already + open IEEEIO or HDFIO + file. This initializes the reader and attaches it to that + datafile. +
AmrUcdFileReader::~AmrUcdFileReader() destructor +
This flushes all of the necessary file buffers. + The filehandle that the reader was bound to must be + closed separately though. +
+
Queries about File Contents +
+
int AmrUcdFileReader::nLevels() +
Returns the number of levels in the AMR hierarchy. This is + the deepest the hierarchy gets in this particular datafile as + opposed to the number of levels present at this time in the + evolution (this distinction is important for adaptive depth + schemes where the number of levels will change depending on + the demands of the solver). +
AmrUcdFileReader::getTimeRange(int &mintime,int &maxtime) +
Gets the range of integer timesteps stored in the file. + The nonzero mintime exists to support schemes where the + evolution is broken up among several files. +
+
Filters +
The filter methods listed below select grids based on + the criteria of time and level number. Grids selected by the + filter are referred to as active grids.

+

+
AmrUcdFileReader::setTime(int time) +
Sets the current timestep to select the data hierarchy for. + The timestep is defined with respect to the rate at which + grids change at the deepest level of the AMR hierarchy stored + in the file. Selecting a particular timestep selects a + snapshot of the hieararchy at a particular time in the + evolution. +
AmrUcdFileReader::hideLevel(int level) +
By default all levels are visible and are read in when the + getGrids() method is called. You can hide + individual levels using this method. This is useful when + loading the entire hierarchy is either too confusing, too slow, or too + large for the workstation to handle. +
AmrUcdFileReader::showLevel(int level) +
Shows a level that has otherwise been hidden. +
AmrUcdFileReader::showAllLevels() +
A convenience method for making all of the levels visible. +
+
Getting the UCD Data +
+
int AmrUcdFileReader::getUcd(FlexArray<AmrNode*> + &nodes, FlexArray<int> &cells) +
Gets all currently active grids and converts them into a + finite element form composed of hexahedral cells. The node + list contains the coordinates of the vertices of the cells and + the cell list contains the connectivity of the hexahedral + cells (indexed into the nodes list where the first element is + an index of 0 and the last is NumNodes-1). +
+
Utility and Debugging Methods +
+
AmrUcdFileReader::setDataLoadingOff() +
This causes the getGrids() methods + to read in the informational part of + the AmrGrid datastructures, but not load any data. This is + useful for just aquiring bounding box information or + estimating the memory/computational requirements for loading + the entire hierarchy. +
AmrUcdFileReader::setDataLoadingOn() +
This causes the getGrids() methods + to read both the informational and data part of + the AmrGrid datastructures. This is the default state for + this API. +
printGridInfo() +
Prints information about all grids in file to STDERR. Used + only for debugging. +
printActiveGrids() +
Prints information about all active grids to STDERR. + Used only for debugging. +
int debug + This is a public variable that can be set to a nonzero value + in order to print additional debugging information for each + method call. This printing is turned off when it is set to zero. +
+
+
+

C Interface

+ Not ready yet. +
+

F77/F90 Interface

+ Not ready yet. + +
+
+ + +Last modified: Thu Feb 4 21:31:06 CST 1999 + + + 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 @@ + + + + + + AMR Writer + + + +

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 + + + diff --git a/doc/html/AmrGrid.html b/doc/html/AmrGrid.html new file mode 100644 index 0000000..f0b5a82 --- /dev/null +++ b/doc/html/AmrGrid.html @@ -0,0 +1,164 @@ + + + + AMR Grid Data Structure + + + + + +

AMR Grid Datastructure

 + + Common to all of the AMR readers is an AmrGrid + informational datastructure. This datastructure is not + necessary for the AMRwriter. + This structure stores all of the + AMR parameters related to the grid that enable you to determine + where it should fit into the AMR hierarchy, the type of data + that it stores and the rank, dimensions, and physical size of + the grid. It also has a pointer which can be used optionally + to store the grid data.

+ + The structure has both a C and a C++ representation. The only + difference between the two is that the C structure represents + the datatype as an integer and the C++ version represents the + datatype as an enum. Since the C++ struct is inherited + directly from the C version, the two interoperate + seamlessly.

+ +

Datastructure Specification

+ + + + + + +
+ C Datastructure + + C++ Datastructure +
+
+typedef struct AmrGrid {          
+  int level;
+  int maxlevel;
+  int maxtime;
+  int timestep;
+  int persistence; 
+  int rank;
+  int dims[3];
+  double delta[3];
+  double origin[3];
+  int timerefinement;
+  int nbytes;
+  int dataveclen;
+  int datatype;
+  void *data;
+} AmrGrid;
+
+		 + 
+struct AmrGrid {
+  // Members inherited from C AmrGrid 
+  int level;
+  int maxlevel;
+  int maxtime;
+  int timestep;
+  int persistence; 
+  int rank;
+  int dims[3];
+  double delta[3];
+  double origin[3];
+  int timerefinement;
+  int nbytes;
+  int dataveclen;
+  void *data;
+  // Members specific to C++ AmrGrid  
+  IObase::DataType datatype;
+};
+
+ + +

Datastructure Member Descriptions

+ +
+
int level +
The level in the AMR hierarchy. Level 0 is the Top (least refined) + level. +
int maxlevel +
The maximum number of levels in the AMR hierarchy for all + timesteps stored in this file. Levels are numbered from 0 + to maxlevel-1. +
int maxtime +
Maximum timestep in the datafile. This parameter is optional + (and generally unused) and will be removed from + future releases. +
int timestep +
This is the current integer timestep with respect to the finest + granularity timestep that can occur in the file. It is not + necessarily uniform in time. It simply delineates the order + in which things change in the file. It is a fundamental + parameter written by the AMRwriter. +
int persistence +
This is the number of timesteps that the grid remains active from + the timestep that it is created. Like the timestep + parameter, it can also be non-uniform. It is an optional + parameter that is often automatically computed by the + AMRreader class from available data. +
int rank +
The number of dimensions for the grid. Currently you cannot mix + grids of different dimensions together (ie. a 2D grid cannot + be embedded in a 3D grid), so if one grid is rank=3, then + all of the grids in the file must have the same rank. +
int dims[3] +
The dimensions of the grid (only the first rank values of + this array will be filled). +
double delta[3] +
The physical spacing between gridpoints. This is actually + redundant information since the same information can be + inferred/computed from the origin and integer + refinement information. It is there for convenience though + even though it is not as precise as the integer specification. +
double origin[3] +
The physical origin (minimum extent in 3-space) of the grid. +
int timerefinement +
The rate at which the grid steps at this level with respect to the + topgrid. This is an optional parameter and will likely be + dropped from future implementations of this system. +
int nbytes +
Number of bytes of storage required for the grid data if it were loaded + into memory.. This is useful for memory allocation/management. +
int dataveclen +
The number of elements-per-point in the data. For instance a + 3D vector velocity field would have a dataveclen=3 for the i,j,k + direction of the vector components. dataveclen=1 for all + scalar values like density and temperature. + Currently this is not + used, but will be in future implementations of the readers. +
int/IObase::DataType datatype +
The type of the data as it is stored on disk. This is represented + as an integer for C and as an enum of type + IObase::DataType for C++. The definitions for the + datatypes are defined + by the FlexIO libraries. + Integer datatypes are implemented in IO.h + and the C++ IObase::DataType is implemented in + IO.hh. +
void *data +
Pointer to memory array storing the data. This is NULL + if the data has not been loaded into memory. So you can use + this datastructure just to aquire information about the + grids and then load the data only when it is needed. +
+ + + + +
+
+ + +Last modified: Thu Jan 28 17:14:34 CST 1999 + + + diff --git a/doc/html/Aquiring.html b/doc/html/Aquiring.html new file mode 100644 index 0000000..2d17f0d --- /dev/null +++ b/doc/html/Aquiring.html @@ -0,0 +1,102 @@ + + + Aquiring IEEEIO + + +

Aquiring IEEEIO

+ + IEEEIO is currently availible directly from this server. + +
+ +

Precompiled Binaries

 +Precompiled binaries of IEEEIO are availible for the following architectures. +The versions of these binaries labeled +hdf also include the full + +HDF 4.1r1 library binaries for convenience.

+

+
+

Compiling IEEEIO

 +To compile IEEEIO you need the following +
    +
  • GNU make +(make-2.75.tar.gz) + +
  • A C++ compiler (CC or +g++) + +
  • If you need to get any of the gnu utilities, you may also need + gzip. + +
+ +The makefile sets up make parameters based on the identification of +the machine using the 'uname' command. It currently recognizes the +following architectures +
    +
  • Cray T3E +
  • DEC Alpha/OSF +
  • HP/Convex +
  • Intel/Windows Cygwin +
  • Macintosh MachTen +
  • SGI IRIX 5.x +
  • SGI IRIX64 6.x +
  • Sun Solaris 2.x +
+ +The Makefile is very small so you should take a look a it with a text editor to make certain that all of the parameters are correct for your machine. Most notably, if you want to be able to use the ieeeio libraries with HDF then you need to make certain that the correct paths to your HDF installation have been set.

+ +Simply type gmake to build the default ieeeio library and utilities. Type gmake libhdfio.a to build the HDF interoperability libraries and related utilities.

+ +To test the operation of of the library type gmake data3d.raw. This will build a test program that will write an IEEEIO file and then reopen it for reading. If this program runs successfully, then the library has been built successfully.

+ + + +

+
John Shalf
+ + +Last modified: Fri May 29 12:33:03 CDT 1998 + + + diff --git a/doc/html/DataTypes.html b/doc/html/DataTypes.html new file mode 100644 index 0000000..80423ae --- /dev/null +++ b/doc/html/DataTypes.html @@ -0,0 +1,188 @@ + + + + DataTypes + + + +

DataTypes

 + HDF and IEEEIO must be able to store any of the basic datatypes + available to a given computer architecture (various sized integers + and floating point numbers). In Fortran the datatype is + identified by an integer. In C we use #defines. In C++ we + use enums. There are also simple built-in utility operations + available which allow computation of data space used by these + various datatypes ( + sizeOf(), + nElements(), + nBytes() + )

+ +Here is how the types are related.

+ + + + + + + + + + + + + + + + + + + + + + + +
Datatype Num Bytes C++ TypeID C TypeID Fortran TypeID
byte binary data (not to be confused with text/strings) +1 +Byte,Int8 +BYTE,INT8 +0 +
short (16bit) integer +2 +Int16 +INT16 +1 +
32bit integer +4 +Int32 +INT32 +2 +
64bit integer +8 +Int64 +INT64 +3 +
single precision floating point +4 +Float32 +FLOAT32 +4 +
double precision floating point +8 +Float64 +FLOAT64 +5 +
unsigned byte +1 +uChar,uInt8 +UCHAR,UINT8 +6 +
unsigned short (16 bit) integer +2 +uInt16 +UINT16 +7 +
unsigned 32bit integer +4 +uInt32 +UINT32 +8 +
unsigned 64bit integer +8 +uInt64 +UINT64 +9 +
special byte type for text data (to differentiate it from binary byte data) +1 +Char,Char8,String +CHAR,CHAR8,STRING +10 +
special type for unicode (16bit) text to differentiate from binary + unsigned integer data +2 +Unicode,Char16 +UNICODE,CHAR16 +11 + +

+ +

+

Utility Subroutines

 + Various utility subroutines can be used to use the type + information to compute data array sizes. +

Number of Bytes in a Dataset

 +
+
+
+
C++ Call Format +
int IObase::nBytes(IObase::DataType datatype,int rank,int *dims) +
C Call Format +
int IOnBytes(int datatype,int rank,int *dims) +
F77 Call Format +
INTEGER IO_NBYTES(INTEGER datatype,INTEGER + rank,INTEGER dims(*))
+
+
+
datatype: +
The datatype for elements of the array +
rank: +
The number of dimensions of the array +
dims: +
A vector of the dimensions of the array +
returns +
Returns the number of bytes required to store the array +
+
+
+ +

Number of Elements in a Dataset

 +
+
+
+
C++ Call Format +
int IObase::nElements(int rank,int *dims) +
C Call Format +
int IOnElements(int rank,int *dims) +
F77 Call Format +
INTEGER IO_NELEMENTS(INTEGER rank,INTEGER dims(*))
+
+
+
rank: +
The number of dimensions of the array +
dims: +
A vector of the dimensions of the array +
returns +
Returns the number of elements required in the array +
+
+
+ +

Size of a DataType in Bytes

 +
+
+
+
C++ Call Format +
int IObase::sizeOf(IObase::DataType datatype) +
C Call Format +
int IOsizeOf(int datatype) +
F77 Call Format +
INTEGER IO_SIZEOF(INTEGER datatype)
+
+
+
datatype: +
The datatype for elements of the array. +
returns +
Returns the number of bytes used by an element of the + specified datatype. +
+
+
+ +
+
+ + +Last modified: Wed Feb 3 22:02:45 CST 1999 + + + diff --git a/doc/html/HighLev.html b/doc/html/HighLev.html new file mode 100644 index 0000000..978563e --- /dev/null +++ b/doc/html/HighLev.html @@ -0,0 +1,43 @@ + + + + High Level IEEEIO Interfaces + + + +

High Level IEEEIO Interfaces

+ + These interfaces sit on top of the basic IO interfaces defined + in the IEEEIO/HDFIO document to describe specific types of data. + So the file format can be read using the low-level IEEEIO/HDF + interfaces without difficulty. These interfaces simply codify + certain file attributes to describe particular types of + data.

+ + These are each separate APIs that take a pointer to the + IEEEIO or HDFIO interfaces in order to do their work.

+ +

Writers

+ +
+
John Shalf
+ + +Last modified: Thu Feb 4 20:35:57 CST 1999 + + + diff --git a/doc/html/IEEEIO.html b/doc/html/IEEEIO.html new file mode 100644 index 0000000..43584a8 --- /dev/null +++ b/doc/html/IEEEIO.html @@ -0,0 +1,48 @@ + + + IEEEIO Info + + + +
+

Introduction

+ IEEEIO is a compact library for storing multidimensional + scientific data in a binary format that can be transported + between different computer systems. It derives its name from the + fact that it depends on the + IEEE + 754 + standard representations + for floating point numbers to achieve its portability. It + provides many of the capabilities of the + HDF-SDS and NetCDF + file formats however it is much smaller and simpler than + either. In addition, it is + reasonably fast when compared + to raw f77 unformatted IO. + + The programming interface allows complete + interoperability with the HDF and NetCDF formats if those + libraries are linked in. It is not intended to supercede these + formats. It is designed to replace them only where the extra + functionality and consequent size of these libraries is not + desired.

+

+

Information

+ +
+
John Shalf
+ + +Last modified: Fri May 29 10:06:40 CDT 1998 + + + diff --git a/doc/html/IOspeed.cc b/doc/html/IOspeed.cc new file mode 100644 index 0000000..ab72a2b --- /dev/null +++ b/doc/html/IOspeed.cc @@ -0,0 +1,86 @@ +#include +#include +#include +#include +#include +#include "IO.hh" +#include "IEEEIO.hh" +#include "HDFIO.hh" +extern "C" { +void openf77_(); +void writef77_(double *data); +void closef77_(); +} + +void main(){ + double data[64*64*64]; + int dims[3]={64,64,64}; + int i,nds; + puts("--------------IEEE--------------"); + for(i=0,nds=5;i<8;i++,nds+=5){ + time_t stm,etm; + struct tms stms,etms; + time(&stm); + times(&stms); + IObase *file = new IEEEIO("speed.raw",IObase::Write); + fprintf(stderr,"Write %2u:",nds); + for(int n=0;nwrite(IObase::Float64,3,dims,data); + } + delete file; + times(&etms); + time(&etm); + printf("\n\tRealtime=%d, UserTime=%d, SystemTime=%d, Combined=%u\n", + etm-stm, + etms.tms_utime-stms.tms_utime, + etms.tms_stime-stms.tms_stime, + etms.tms_utime-stms.tms_utime+etms.tms_stime-stms.tms_stime); + } + + puts("--------------HDF---------------"); + for(i=0,nds=5;i<8;i++,nds+=5){ + time_t stm,etm; + struct tms stms,etms; + time(&stm); + times(&stms); + IObase *file = new HDFIO("speed.hdf",IObase::Write); + fprintf(stderr,"Write %2u:",nds); + for(int n=0;nwrite(IObase::Float64,3,dims,data); + } + delete file; + times(&etms); + time(&etm); + printf("\n\tRealtime=%d, UserTime=%d, SystemTime=%d, Combined=%u\n", + etm-stm, + etms.tms_utime-stms.tms_utime, + etms.tms_stime-stms.tms_stime, + etms.tms_utime-stms.tms_utime+etms.tms_stime-stms.tms_stime); + } + + puts("-------------F77 Unformatted---------------"); + for(i=0,nds=5;i<8;i++,nds+=5){ + time_t stm,etm; + struct tms stms,etms; + time(&stm); + times(&stms); + fprintf(stderr,"Write %2u:",nds); + openf77_(); + // writef77_(dat,&nds); + for(int n=0;n + + + IEEEIO Performance + + + +

IEEEIO Performance Comparisons

+ +The performance of IEEEIO, HDF 4.1r1, and F77 unformatted IO are +compared. Each system is set up to write between 5 and 40 +datasets. Each dataset is 64^3 double precision floats. +The realtime (wallclock time) +is measured in seconds using time() which is +coarse, but good enough for this comparison. The system and +user times (CPU times) were measured using the times() +system call which reports in clock ticks. The combined +time is the sum of user and system times. +The timing of each of the IO systems includes the opening and +closing of the files so that buffer flushing and file indexing +can be taken into account. The program used to do the testing +is IOspeed.cc and uses +writef77.f to handle the F77 IO. + +Testing hasn't been done on too many architectures yet but as +data is collected it will be posted here. + +
+

Octane Performance

 +5 to 40 double precision float datasets with 64 x 64 x 64 elements +were written to the scratch disk. +(each * represents writing a single datasets)

+ +The test was performed on Octane while +the machine was unloaded. The machine has one 195 MHz +R10000 processor, 512 Megs RAM. A 2-disk fast-wide SCSI-3 +RAID 0 array was used as the data drive for the test. +This data is from a single run. +More tests will be done to build an averaged score.

+ +

+--------------IEEE--------------
+Write  5:*****
+        Realtime=0, UserTime=0, SystemTime=11, Combined=11
+Write 10:**********
+        Realtime=1, UserTime=2, SystemTime=22, Combined=24
+Write 15:***************
+        Realtime=3, UserTime=0, SystemTime=32, Combined=32
+Write 20:********************
+        Realtime=4, UserTime=0, SystemTime=43, Combined=43
+Write 25:*************************
+        Realtime=6, UserTime=1, SystemTime=54, Combined=55
+Write 30:******************************
+        Realtime=7, UserTime=0, SystemTime=64, Combined=64
+Write 35:***********************************
+        Realtime=8, UserTime=1, SystemTime=75, Combined=76
+Write 40:****************************************
+        Realtime=9, UserTime=1, SystemTime=86, Combined=87
+--------------HDF---------------
+Write  5:*****
+        Realtime=1, UserTime=30, SystemTime=25, Combined=55
+Write 10:**********
+        Realtime=2, UserTime=61, SystemTime=49, Combined=110
+Write 15:***************
+        Realtime=4, UserTime=91, SystemTime=75, Combined=166
+Write 20:********************
+        Realtime=16, UserTime=122, SystemTime=99, Combined=221
+Write 25:*************************
+        Realtime=8, UserTime=153, SystemTime=124, Combined=277
+Write 30:******************************
+        Realtime=9, UserTime=181, SystemTime=150, Combined=331
+Write 35:***********************************
+        Realtime=11, UserTime=213, SystemTime=175, Combined=388
+Write 40:****************************************
+        Realtime=13, UserTime=241, SystemTime=200, Combined=441
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=0, UserTime=1, SystemTime=11, Combined=12
+Write 10:**********
+        Realtime=1, UserTime=0, SystemTime=24, Combined=24
+Write 15:***************
+        Realtime=3, UserTime=0, SystemTime=36, Combined=36
+Write 20:********************
+        Realtime=14, UserTime=0, SystemTime=48, Combined=48
+Write 25:*************************
+        Realtime=5, UserTime=0, SystemTime=60, Combined=60
+Write 30:******************************
+        Realtime=7, UserTime=1, SystemTime=72, Combined=73
+Write 35:***********************************
+        Realtime=8, UserTime=0, SystemTime=84, Combined=84
+Write 40:****************************************
+        Realtime=10, UserTime=0, SystemTime=96, Combined=96
+
+
+

Origin 2000

 +5-40 64^3 double-precision float datasets were written +(each '*' represents +writing a single datasets)

+Test performed on the SGI Origin 2000 origin.aei-potsdam.mpg.de +while the machine was moderately loaded. The machine has 32 195 MHz +R10000 processors, 8Gigabytes RAM. A mulit-disk RAID 0 array was used +as the data drive for the test. This is from a single run. +More tests will be done to create an averaged score.

+

+--------------IEEE--------------
+Write  5:*****
+        Realtime=0, UserTime=2, SystemTime=18, Combined=20
+Write 10:**********
+        Realtime=2, UserTime=0, SystemTime=26, Combined=26
+Write 15:***************
+        Realtime=1, UserTime=0, SystemTime=39, Combined=39
+Write 20:********************
+        Realtime=3, UserTime=1, SystemTime=53, Combined=54
+Write 25:*************************
+        Realtime=3, UserTime=0, SystemTime=65, Combined=65
+Write 30:******************************
+        Realtime=3, UserTime=1, SystemTime=76, Combined=77
+Write 35:***********************************
+        Realtime=6, UserTime=1, SystemTime=97, Combined=98
+Write 40:****************************************
+        Realtime=6, UserTime=1, SystemTime=107, Combined=108
+--------------HDF---------------
+Write  5:*****
+        Realtime=1, UserTime=44, SystemTime=33, Combined=77
+Write 10:**********
+        Realtime=3, UserTime=86, SystemTime=61, Combined=147
+Write 15:***************
+        Realtime=3, UserTime=129, SystemTime=85, Combined=214
+Write 20:********************
+        Realtime=7, UserTime=171, SystemTime=115, Combined=286
+Write 25:*************************
+        Realtime=6, UserTime=215, SystemTime=139, Combined=354
+Write 30:******************************
+        Realtime=8, UserTime=258, SystemTime=169, Combined=427
+Write 35:***********************************
+        Realtime=10, UserTime=300, SystemTime=200, Combined=500
+Write 40:****************************************
+        Realtime=12, UserTime=340, SystemTime=231, Combined=571
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=0, UserTime=0, SystemTime=20, Combined=20
+Write 10:**********
+        Realtime=2, UserTime=0, SystemTime=30, Combined=30
+Write 15:***************
+        Realtime=2, UserTime=0, SystemTime=45, Combined=45
+Write 20:********************
+        Realtime=1, UserTime=1, SystemTime=60, Combined=61
+Write 25:*************************
+        Realtime=5, UserTime=0, SystemTime=77, Combined=77
+Write 30:******************************
+        Realtime=4, UserTime=0, SystemTime=93, Combined=93
+Write 35:***********************************
+        Realtime=6, UserTime=1, SystemTime=108, Combined=109
+Write 40:****************************************
+        Realtime=5, UserTime=0, SystemTime=123, Combined=123
+
+
+

HP/Convex SPP-1200

 +5-40 64^3 double-precision float datasets were written +(each '*' represents writing a single datasets)

+Test performed on an HP/Convex SPP-1200 (lena.ncsa.uiuc.edu) +while the machine was moderately loaded. The machine has 64 120 MHz +PA7200 processors, 8Gigabytes RAM. A mulit-disk RAID 0 array was used +as the data drive for the test. This is from a single run. +More tests will be done to create an averaged score.

+

+--------------IEEE--------------
+Write  5:*****
+        Realtime=2, UserTime=0, SystemTime=1, Combined=1
+Write 10:**********
+        Realtime=1, UserTime=1, SystemTime=0, Combined=1
+Write 15:***************
+        Realtime=3, UserTime=0, SystemTime=0, Combined=0
+Write 20:********************
+        Realtime=4, UserTime=1, SystemTime=0, Combined=1
+Write 25:*************************
+        Realtime=4, UserTime=2, SystemTime=0, Combined=2
+Write 30:******************************
+        Realtime=6, UserTime=3, SystemTime=0, Combined=3
+Write 35:***********************************
+        Realtime=5, UserTime=2, SystemTime=0, Combined=2
+Write 40:****************************************
+        Realtime=7, UserTime=2, SystemTime=1, Combined=3
+--------------HDF---------------
+Write  5:*****
+        Realtime=3, UserTime=134, SystemTime=12, Combined=146
+Write 10:**********
+        Realtime=5, UserTime=254, SystemTime=7, Combined=261
+Write 15:***************
+        Realtime=8, UserTime=379, SystemTime=19, Combined=398
+Write 20:********************
+        Realtime=11, UserTime=524, SystemTime=19, Combined=543
+Write 25:*************************
+        Realtime=18, UserTime=688, SystemTime=24, Combined=712
+Write 30:******************************
+        Realtime=23, UserTime=801, SystemTime=22, Combined=823
+Write 35:***********************************
+        Realtime=24, UserTime=947, SystemTime=27, Combined=974
+Write 40:****************************************
+        Realtime=25, UserTime=1087, SystemTime=28, Combined=1115
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=1, UserTime=39, SystemTime=15, Combined=54
+Write 10:**********
+        Realtime=2, UserTime=91, SystemTime=1, Combined=92
+Write 15:***************
+        Realtime=4, UserTime=133, SystemTime=0, Combined=133
+Write 20:********************
+        Realtime=4, UserTime=169, SystemTime=1, Combined=170
+Write 25:*************************
+        Realtime=7, UserTime=211, SystemTime=2, Combined=213
+Write 30:******************************
+        Realtime=11, UserTime=275, SystemTime=0, Combined=275
+Write 35:***********************************
+        Realtime=10, UserTime=318, SystemTime=3, Combined=321
+Write 40:****************************************
+        Realtime=9, UserTime=348, SystemTime=6, Combined=354
+
+
+

HP/Convex S-Class

 +5-40 64^3 double-precision float datasets were written +(each '*' represents +writing a single datasets)

+Test performed on an alpha-version of the HP/Convex S-Class +while the machine was moderately loaded. The machine has 16 180 MHz +PA8000 processors, 4Gigabytes RAM. A mulit-disk RAID 0 array was used +as the data drive for the test. This is from a single run. +More tests will be done to create an averaged score.

+

+--------------IEEE--------------
+Write  5:*****
+        Realtime=7, UserTime=0, SystemTime=1, Combined=1
+Write 10:**********
+        Realtime=1, UserTime=0, SystemTime=0, Combined=0
+Write 15:***************
+        Realtime=1, UserTime=0, SystemTime=0, Combined=0
+Write 20:********************
+        Realtime=1, UserTime=0, SystemTime=1, Combined=1
+Write 25:*************************
+        Realtime=1, UserTime=1, SystemTime=0, Combined=1
+Write 30:******************************
+        Realtime=2, UserTime=1, SystemTime=0, Combined=1
+Write 35:***********************************
+        Realtime=2, UserTime=2, SystemTime=1, Combined=3
+Write 40:****************************************
+        Realtime=3, UserTime=3, SystemTime=1, Combined=4
+--------------HDF---------------
+Write  5:*****
+        Realtime=4, UserTime=52, SystemTime=4, Combined=56
+Write 10:**********
+        Realtime=3, UserTime=121, SystemTime=5, Combined=126
+Write 15:***************
+        Realtime=4, UserTime=159, SystemTime=8, Combined=167
+Write 20:********************
+        Realtime=7, UserTime=216, SystemTime=16, Combined=232
+Write 25:*************************
+        Realtime=7, UserTime=262, SystemTime=23, Combined=285
+Write 30:******************************
+        Realtime=11, UserTime=322, SystemTime=19, Combined=341
+Write 35:***********************************
+        Realtime=9, UserTime=361, SystemTime=33, Combined=394
+Write 40:****************************************
+        Realtime=13, UserTime=422, SystemTime=31, Combined=453
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=1, UserTime=27, SystemTime=8, Combined=35
+Write 10:**********
+        Realtime=2, UserTime=58, SystemTime=0, Combined=58
+Write 15:***************
+        Realtime=2, UserTime=90, SystemTime=0, Combined=90
+Write 20:********************
+        Realtime=2, UserTime=112, SystemTime=0, Combined=112
+Write 25:*************************
+        Realtime=3, UserTime=137, SystemTime=2, Combined=139
+Write 30:******************************
+        Realtime=3, UserTime=174, SystemTime=0, Combined=174
+Write 35:***********************************
+        Realtime=6, UserTime=203, SystemTime=0, Combined=203
+Write 40:****************************************
+        Realtime=4, UserTime=223, SystemTime=1, Combined=224
+
+
+

DEC AlphaServer 2100 4/275

 +5-40 64^3 double-precision float datasets were written +(each '*' represents +writing a single datasets)

+Test performed on a DEC AlphaServer 2100 4/275 +while the machine was unloaded. The machine has 1 275 MHz +Alpha ev 4 processor, 32Megabytes RAM. A single SCSI-2 disk was used +as the data drive for the test. This is from a single run. +More tests will be done to create an averaged score.

+

+--------------IEEE--------------
+Write  5:*****
+        Realtime=1, UserTime=1, SystemTime=29, Combined=30
+Write 10:**********
+        Realtime=8, UserTime=0, SystemTime=49, Combined=49
+Write 15:***************
+        Realtime=9, UserTime=0, SystemTime=75, Combined=75
+Write 20:********************
+        Realtime=14, UserTime=0, SystemTime=101, Combined=101
+Write 25:*************************
+        Realtime=16, UserTime=1, SystemTime=126, Combined=127
+Write 30:******************************
+        Realtime=18, UserTime=0, SystemTime=152, Combined=152
+Write 35:***********************************
+        Realtime=23, UserTime=1, SystemTime=178, Combined=179
+Write 40:****************************************
+        Realtime=26, UserTime=1, SystemTime=204, Combined=205
+--------------HDF---------------
+Write  5:*****
+        Realtime=8, UserTime=106, SystemTime=47, Combined=153
+Write 10:**********
+        Realtime=17, UserTime=214, SystemTime=89, Combined=303
+Write 15:***************
+        Realtime=25, UserTime=317, SystemTime=138, Combined=455
+Write 20:********************
+        Realtime=31, UserTime=425, SystemTime=185, Combined=610
+Write 25:*************************
+        Realtime=34, UserTime=533, SystemTime=228, Combined=761
+Write 30:******************************
+        Realtime=40, UserTime=640, SystemTime=276, Combined=916
+Write 35:***********************************
+        Realtime=49, UserTime=743, SystemTime=326, Combined=1069
+Write 40:****************************************
+        Realtime=55, UserTime=852, SystemTime=369, Combined=1221
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=3, UserTime=11, SystemTime=32, Combined=43
+Write 10:**********
+        Realtime=6, UserTime=20, SystemTime=64, Combined=84
+Write 15:***************
+        Realtime=10, UserTime=28, SystemTime=85, Combined=113
+Write 20:********************
+        Realtime=12, UserTime=40, SystemTime=117, Combined=157
+Write 25:*************************
+        Realtime=18, UserTime=52, SystemTime=139, Combined=191
+Write 30:******************************
+        Realtime=18, UserTime=64, SystemTime=170, Combined=234
+Write 35:***********************************
+        Realtime=21, UserTime=66, SystemTime=199, Combined=265
+Write 40:****************************************
+        Realtime=28, UserTime=80, SystemTime=226, Combined=306
+
+
+
+

DEC AlphaStation 600 5/266

 +5-40 64^3 double-precision float datasets were written +(each '*' represents writing a single datasets)

+Test performed on a DEC AlphaStation 600 5/266 +while the machine was moderately loaded. The machine has 1 266 MHz +Alpha ev 5 processor, 64Megabytes RAM. A single SCSI-2 disk was used +as the data drive for the test. This is from a single run. +More tests will be done to create an averaged score.

+

+--------------IEEE--------------
+Write  5:*****
+        Realtime=1, UserTime=1, SystemTime=18, Combined=19
+Write 10:**********
+        Realtime=4, UserTime=0, SystemTime=43, Combined=43
+Write 15:***************
+        Realtime=6, UserTime=0, SystemTime=65, Combined=65
+Write 20:********************
+        Realtime=7, UserTime=0, SystemTime=82, Combined=82
+Write 25:*************************
+        Realtime=9, UserTime=0, SystemTime=109, Combined=109
+Write 30:******************************
+        Realtime=11, UserTime=1, SystemTime=146, Combined=147
+Write 35:***********************************
+        Realtime=12, UserTime=0, SystemTime=183, Combined=183
+Write 40:****************************************
+        Realtime=16, UserTime=1, SystemTime=196, Combined=197
+--------------HDF---------------
+Write  5:*****
+        Realtime=4, UserTime=71, SystemTime=30, Combined=101
+Write 10:**********
+        Realtime=8, UserTime=145, SystemTime=55, Combined=200
+Write 15:***************
+        Realtime=12, UserTime=218, SystemTime=84, Combined=302
+Write 20:********************
+        Realtime=14, UserTime=292, SystemTime=113, Combined=405
+Write 25:*************************
+        Realtime=19, UserTime=361, SystemTime=145, Combined=506
+Write 30:******************************
+        Realtime=22, UserTime=433, SystemTime=174, Combined=607
+Write 35:***********************************
+        Realtime=27, UserTime=503, SystemTime=202, Combined=705
+Write 40:****************************************
+        Realtime=30, UserTime=580, SystemTime=231, Combined=811
+-------------F77 Unformatted---------------
+Write  5:*****
+        Realtime=3, UserTime=11, SystemTime=21, Combined=32
+Write 10:**********
+        Realtime=3, UserTime=25, SystemTime=38, Combined=63
+Write 15:***************
+        Realtime=7, UserTime=37, SystemTime=59, Combined=96
+Write 20:********************
+        Realtime=8, UserTime=49, SystemTime=83, Combined=132
+Write 25:*************************
+        Realtime=10, UserTime=60, SystemTime=115, Combined=175
+Write 30:******************************
+        Realtime=12, UserTime=74, SystemTime=134, Combined=208
+Write 35:***********************************
+        Realtime=13, UserTime=86, SystemTime=154, Combined=240
+Write 40:****************************************
+        Realtime=15, UserTime=95, SystemTime=192, Combined=287
+
+
+
John Shalf
+ + +Last modified: Wed Jun 4 10:19:46 CDT 1997 + + + diff --git a/doc/html/UCDwriter.html b/doc/html/UCDwriter.html new file mode 100644 index 0000000..1dec11c --- /dev/null +++ b/doc/html/UCDwriter.html @@ -0,0 +1,57 @@ + + + + UCD Writer + + + +

UCD Writer

+ + The UCD Writer stores finite-element cell-connectivity data. + The UCD format is used by popular FEM simulation packages like + ABAQUS and by visualization systems like AVS and Explorer. It + is also a useful format to store AMR data into for visualization + systems since virtually no visualization system understands + heirarchial grids.

+ + The writer API has a lot of beginSomething() and + endSomething() statements. This is because there may + be several independent lists of nodes and cells at a given + timestep in a completely arbitrary UCD dataset. This + interface allows this to be dealt with in pieces.

+ +

The API

+ +
+ C++ Interface +
+
constructor UCDwriter::UCDWriter( + IObase &iofile, + IObase::DataType defaultnodetype=IObase::Float32, + IObase::DataType defaultcelltype=IObase::Int32 + ) +
The filehandle is an already open IEEEIO or HDFIO + file. This initializes the reader and attaches it to that + datafile. You can optionally set the datatype for the + node/vertex coordinates and the cell indices. Normally + these would be Float32 and Int32 respectively. +
destructor UCDwriter::~UCDwriter() +
This flushes all of the necessary file buffers and + destroys the UCDwriter object. + The filehandle that the writer was bound to must be + closed separately though. +
+
+ +
+
John Shalf
+ + +Last modified: Wed May 7 13:32:18 MDT + + + diff --git a/doc/html/Using.html b/doc/html/Using.html new file mode 100644 index 0000000..f4c8c5e --- /dev/null +++ b/doc/html/Using.html @@ -0,0 +1,68 @@ + + + Using FlexIO + + + +
+

Introduction

+ FlexIO borrows its terminology and storage-style from + HDF and NetCDF. The file stores a sequence of multidimesional + arrays which are referred to generically as datasets. + The rank of the dataset is the number of dimensions the + data array has. The dimensions themselves are stored as + an array of integers. The dataset has a + datatype which + identifies the type of data stored in the array {32-bit float, + 64-bit float, 32-bit integer, 64-bit integer, character}. The + datasets are stored sequentially in the file and can be accessed + by their index which ranges from 0 to (<number of datasets> - + 1).

+ + It is important to note that the data is always stored in + Fortan order. That is, the first element of the + dimensions array always refers to the number of + elements that are most closely packed in the array + (eg. stride = 1). The next dimension has a stride equal to + the product of the lower dimensions. This is opposite of + default C/C++ array indexing order but can be accomodated + easily in those languages.

+ + In addition to raw dataset storage, you can attach + additional descriptions to the data using annotations + and attributes.

+ + An annotation is a text-string description of a + dataset which can be attached to dataset. You can use it to + add comments or other such information to the file.

+ + An attribute is a named vector of data (of any type) + attached to a dataset. This can function like an + annotation but it is primarily intended to add more + information to a dataset that can be interpreted by + visualization system or other such programs that would read + the datafile. The type of data attached in an attribute can + be the origin in 3D space of the dataset or a list of + floating point coordinates. + coordinates or a componentname etc... The name + identifies the semantic meaning of the array's contents and + readers can be configured to look for particular names to + add descriptive information to the dataset.

. + +

+

Documentation

+ +
+
John Shalf
+ + +Last modified: Thu Feb 4 21:38:53 CST 1999 + + + diff --git a/doc/html/UsingC++.html b/doc/html/UsingC++.html new file mode 100644 index 0000000..15622d0 --- /dev/null +++ b/doc/html/UsingC++.html @@ -0,0 +1,442 @@ + + + IEEE IO C++ Interface + + + + + +

C++

+
+

Using the C++ Interface

+ To use the C++ interface, you must include the + headers IO.hh and IEEEIO.hh. If you only require + the IEEEIO interface, you link only with libieeeio.a using + -L$IEEE_DIRECTORY/lib -lieeeio.

+ + If you + also want HDF support you must also include the header + HDFIO.hh and link with libhdfio.a and + the usual complement of HDF libraries using + -L$HDF_DIRECTORY/lib -L$IEEE_DIRECTORY/lib -lhdfio + -lieeeio -lmfhdf -ldf -ljpeg -lz. +

+

C++ Methods

+ + +
+

Opening

 + To open an IEEEIO file, you simply create a new IEEEIO object. + The constructor handles the opening.

+ C++ Prototype
+ IEEEIO::IEEEIO(char *filename,IObase::AccessMode accessmode);
+

+
filename: +
The name of the IEEEIO data file to + open. The typical extension for these files is .raw +
accessmode: +
The accessmode for the file. This is + one of 3 different access modes + +
    +
  • IObase::Read: + Opens a file in read-only mode. +
  • IObase::Create: + Opens a file in write-only mode. If the file does not exist, it will be created. If it does exist, it will be truncated. +
  • IObase::Append: + Opens a file in read/write mode. The file pointer is automatically placed at the end of the file for appending, but random-access read operations are allowed as well. +
+
+ + Since this is inherited from the IO base class, you can assign + the newly created object to a pointer to the base class and + deal with it generically.
+
+    IO *writer = new IEEEIO("datafileout.raw",IObase::Create);
+    IO *reader = new IEEEIO("datafilein.raw",IObase::Read);
+

+ You can test if the file was opened successfully using the IObase::isValid() method.
+
+    if(!reader->isValid())
+       puts("The file you specified does not exist or is not in a readable format");
+

+ + Other IO systems can be inherited from the IO base class. So + for instance, to read HDF files you simply link with the the HDFIO + and HDF libraries and open using; + 
+    IO *writer = new HDFIO("datafileout.raw",IObase::Create);
+    IO *reader = new HDFIO("datafilein.raw",IObase::Read);
+
+ + After the files are opened, you can use the methods in the + baseclass IO to do all of your reading and writing in a completely + generic manner regardless of the implementation of the underlying + IO system so long as the underlying IO system implements the + methods of the base class. There are plans, for example, to have + a SocketIO system that allows the data to be written out to a TCP + socket instead of to a file for real-time simulation-visualization + systems. There are also plans to use this interface to drive an + existing Parallel IO system.

+ +To close the file, you simply delete the object. +

+   delete writer;
+   delete reader;
+
+ Since virtual destructors are used, you can delete them as + objects of the base IO class (no casts required). + +
+

Writing

 + To write data you simply use the method write(). +

C++ Prototype
+ IEEEIO::write(IObase::DataType numbertype,int rank,int *dimensions,void *data); +

+
numbertype: +
The type of the data being stored + (as defined in DataType.html). + It can be one of +
    +
  • IObase::Float32
    32-bit single-precision IEEE float +
  • IObase::Float64
    64-bit double-precision IEEE float +
  • IObase::Int8
    byte +
  • IObase::Int16
    16-bit short integer +
  • IObase::Int32
    32-bit standard integer +
  • IObase::Int64
    64-bit long integer. (note: + this is not availible on the Intel/Windows + platform) +
  • IObase::uInt8
    unsigned character +
  • IObase::uInt16
    unsigned 16-bit short integer +
  • IObase::uInt32
    unsigned 32-bit standard integer +
  • IObase::uInt64
    unsigned 64-bit long integer. (note: this is not availible on the Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions of the dataset +
data: +
Your data array. +
+ + So to write a sample array of data. + 
+	float myarray[40][50][60]; // our bogus data array
+	int rank=3;
+	int dims[3]={60,50,40}; // notice these are reversed.
+		// this is because ieeeio assumes f77 order for data 
+		// and c/c++ use exactly the opposite ordering for data in memory.
+	IO *writer=new IEEEIO("datafile.raw",IObase::Create); // create a outfile
+	writer->write(IObase::Float32,rank,dims,myarray); // write a dataset
+	. . . . you can write as many datasets as you want
+	delete writer; // then close the file
+
+ +
+

Reading Data

 + Reading is a two step process. First you get information on + the size and type of the data you intend to read. This allows + you to allocate an array of the proper size and type for the + reading. Then you actually read the data into a pre-allocated + array. The methods for this are readInfo() and read().

+ C++ Prototype
+ readInfo(IObase::DataType &numbertype,int &rank,int + *dims,int maxdims=3);

+

+
numbertype: +
The type of the data being stored + (datatype definition). + It can be one of +
    +
  • IObase::Float32
    32-bit single-precision IEEE float +
  • IObase::Float64
    64-bit double-precision IEEE float +
  • IObase::Int8
    byte +
  • IObase::Int16
    16-bit short integer +
  • IObase::Int32
    32-bit standard integer +
  • IObase::Int64
    64-bit long integer. (note: + this is not availible on the Intel/Windows + platform) +
  • IObase::uInt8
    unsigned character +
  • IObase::uInt16
    unsigned 16-bit short integer +
  • IObase::uInt32
    unsigned 32-bit standard integer +
  • IObase::uInt64
    unsigned 64-bit long integer. (note: this is not availible on the Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions + of the dataset +
maxdims: +
The maximum size of the dimensions array you given it. + This prevents array overruns if the dataset has more + dimensions than you were anticipating. The default is 3 but + it can be any arbitrary positive integer. +
+ This retrieves information about the datatype, rank, + and dimensions of the dataset to be retrieved. + By default the maximum size of the dimensions array is 3, + but you can set it to be larger.

+ C++ Prototype
+ + IEEEIO::read(void *data); +

+ This actually reads the dataset into the preallocated array data.

+ + Another useful utility function is IObase::sizeOf() which returns the number of bytes in a give IObase:: datatype in manner analogous to the standard C sizeof() operator. + + So for instance, to read a simple dataset, you would do + 

+	int rank;
+	IObase::DataType numbertype;
+	int dims[3];
+	float *data; // assumes float data
+	IO *infile = new IEEEIO("dataset.raw",IObase::Read);
+	infile->readInfo(numbertype,rank,dims);
+	// OK, we are assuming a 3D IObase::Float32 array, 
+	// but you can be more sophisticated...
+	data = new char[IObase::nBytes(numbertype,rank,dims)];
+        // You can also use
+        // data = new float[IObase::nElements(rank,dims)];
+	infile->read(data); // read in the data
+

+ + Since multiple datasets can be stored in a file, you can + retrieve them in the order they were written (there is a seek() function that allows random access as well). The method readInfo() implies reading the next dataset stored in the file. The method nDatasets() tells how many datasets are in a file. So typically if you want to read all datasets in a file in order, you would use code similar to; + 

+	IO *infile = new IEEEIO("dataset.raw",IObase::Read);
+	for(int i=0;i<infile->nDatasets();i++){
+	  .....lots of code....
+	  infile->readInfo(numbertype,rank,dims); // increments to next dataset
+	  .....more code....
+	}
+
+ +
+

Random Access to Datasets + (Seeking)

 + You can select specific datasets in a file using the seek() + method.

+ C++ Prototype + IEEEIO::seek(int index) +

+
index +
The index of the dataset you want to read from. This can + be any number from 0 to (number_of_datasets - 1). +
+ +
+

Writing Attributes

 + Attributes allow you to attach extra information to each + dataset stored in the file. Each attribute has a name and an + array of data (of any of the standard IObase:: types) stored with + it. These attributes can be retrieved by name or by integer + index in the order in which they were stored. A typical + attribute would typically be parameters that describe the grid + or the data like, "origin" which would be the 3-vector of floats + which locates of the origin of a grid in 3-space. The method + used to write these attributes is writeAttribute();

+ C++ Prototype
+ + IEEEIO::writeAttribute(char *name,IObase::DataType numbertype,int length,void *data) +

+

+
name: +
Name of the attribute (like "origin" or "coordinates") +
numbertype: +
The type of the data array associated with the attribute + (datatype definition) +
length: +
The number of elements in the data array. +
data: +
The attribute data. +

+ So to write an attribute named origin along with a 3-vector float for the coordinates of the origin, you would use; + 

+	float origin[3]={5.1,0.3,0.5};
+	// and assuming the file is already open for writing
+	// the following attribute will be attached to the last 
+	// written dataset. (you must have write data before adding attribs)
+	writer->writeAttribute("origin",IObase::Float32,3,origin);
+
+ +
+

Reading Attributes

 + The attributes can be retrieved in the order they were written + or they can be retrieved by their name. To retrieve the + attributes in order, you would utilize the nAttributes() + method to determine how many attributes are attached, + readAttributeInfo() to get the size and type of the + attribute, and readAttribute() to read the attribute + data.

+ C++ Prototype
+ int IEEEIO::nAttributes()

+

+
returnvalue: +
Number of attributes in the file +

+ C++ Prototype
+ IEEEIO::readAttributeInfo(int index,char *name,IObase::DataType &numbertype,int &length,int maxnamelength=128); + +

+
index: +
The index of the attribute which can be 0 to (nattributes-1) +
name: +
A buffer in which the name of the attribute will be placed. +
numbertype: +
The type of the attribute data + (datatype definition) +
length: +
The number of elements in the attribute data. +
maxnamelength:
The maximum size of a name that can be stored in the name buffer. The default maximum is 128, but can be set to any size. +
+

+ C++ Prototype
+ IEEEIO::readAttribute(int index,void *data); +

+
index: +
The index of the attribute data to read +
data: +
The array into which the attribute data is copied. +
+ So for example, to read the attributes in order, you can use + 
+	for(int i=0;i<infile->nAttributes();i++){
+	    char name[128];
+	    int length;
+	    IObase::DataType datatype;
+	    ...
+	    infile->readAttributeInfo(i,name,datatype,length);
+	    ... // allocate some data for storage
+	    infile->readAttribute(i,data);
+	}
+

+ + The attributes can also be retrieve by name. In fact, + the is the most likely way you will use the attibutes interface. + The readAttributeInfo() method is overloaded to allow retrieval + by name as well. It returns the index of the attribute if one + is found with a matching name: it returns -1 if one is not + found. +

C++ Prototype
+ + int IEEEIO::readAttributeInfo(char *name,IObase::DataType &numbertype,int &length); + +

+
returnvalue: +
The index of the attribute if found or -1 if no attribute with matching name is found. +
name: +
The name of the attribute to find. +
numbertype: +
Returns the numbertype of the stored attribute data + (datatype definition) +
length: +
he length of the stored attribute data. +
+ So a typical use of this interface would be to find an attribute named "origin" and retrieve its data if it exists. + 
+	int index = infile->readAttributeInfo("origin",datatype,length);
+	if(index>=0) // the attribute exists
+		infile->readAttribute(index,data);
+	else 
+		puts("The attribute origin could not be found");
+
+ + + +
+

Writing Annotations

 + An annotation is a text string which can be used to + describe a dataset. To write an annotation, you use the + writeAnnotation() method.

+ C++ Prototype
+ + IEEEIO::writeAnnotation(char *annotationtext) + +

+
annotationtext: +
A null terminated string of the annotation text +
+ The annotation will be attached to the last written dataset. + You can store more than one annotation per dataset and the + annotations can be of arbitrary length.

+ +

+

Reading Annotations

 + The annotations are stored in the order they are written. The + method nAnnotations() is used to find out how many + attributes are attached to a dataset. The method + readAnnotationInfo() is used to find the length of the + annotation and readAnnotatin() reads the actual + annotation text.

+ C++ Prototype
+ + int nAnnotations(); + +

+
returnvalue: +
Number of annotations attached to current dataset. +

+ C++ Prototype
+ readAnnotationInfo(int index,int &length) + +

+
index: +
Index of the annotations which can be 0 to (nannotations-1) +
length: +
Length in characters of the annotation. This includes the null-terminating character. +
+
+

Writing and Reading in Chunks

 + For distributed-memory programming paradigms like HPF, MPI, or + PVM, it is often not unfeasible to write data to disk in a + single operation. For this reason, a chunking interface + is provided which allows you to write data in blocks to the + disk.

+ To begin a chunk writing operation, you must first reserve a + data chunk in the file. This is accomplished using reserveChunk() + C++ Prototype
+ IObase::reserveChunk(IObase::DataType datatype,int rank,int *dims); +

+ Once space has been allocated in the datafile, you can write + blocks of data specified by their dimensions and origin using + writeChunk() + C++ Prototype
+ + int IObase::IOwriteChunk(int *dims,int *origin,void *data); +

+ Likewise, it is possible to read chunks from the disk as + well. No special procedure is required to select a record to + read in chunks. Simply use readInfo() + to get the dimensions and + type of the dataset and then use readChunk() in place + of read() in order to read-in the data. + C++ Prototype
+ + int IObase::readChunk(int *dims,int *origin,void *data); +

+

+
John Shalf
+ + +Last modified: Thu Feb 4 21:53:13 CST 1999 + + + diff --git a/doc/html/UsingC.html b/doc/html/UsingC.html new file mode 100644 index 0000000..3acab85 --- /dev/null +++ b/doc/html/UsingC.html @@ -0,0 +1,505 @@ + + + IEEEIO C Interface + + + + + +

ANSI and K&R C

+
+

Using the C Interface

+ To use the C interface, you must include the + headers IO.h and IEEEIO.h. By default the headers + are treated as K&R C (eg. no prototypes) because that is the + default of for many workstation C compilers. To enable the ANSI + C prototypes compile with -DANSI or use #define ANSI in + your source files before you include the IO.h and + IEEEIO.h headers. If you only require + the IEEEIO interface, you link only with libieeeio.a using + -L$IEEE_DIRECTORY/lib -lieeeio

+ + If you also want HDF support you must also include the header + HDFIO.hh and link with libhdfio.a and + the usual complement of HDF libraries using + -L$HDF_DIRECTORY/lib -L$IEEE_DIRECTORY/lib -lhdfio -lieeeio -lmfhdf -ldf -ljpeg -lz

+ +

+

C Subroutines

+ + +
+

Opening

 + Just like the familiar FILE* type for C stdio operations, all + IEEEIO operations require a file handle. The type of this handle is + IOFile (and 8-byte integer number). The IEEEopen() and + HDFIOopen() + routines are used to create this handle and the IOclose() subroutine can + be used to close file handles of either type.

+ ANSI C Prototype
+ IOFile IEEEopen(char *filename,char *accessmode);
+

+
filename: +
The name of the IEEEIO data file to + open. The typical extension for these files is .raw +
accessmode: +
The accessmode for the file. This is + one of 3 different access modes +
    +
  • "read":Opens a file in read-only mode. This + can also be selected using any of the standard fopen() + modes; "r" and "rb" +
  • "write":Opens a file in write-only mode. If the + file does not exist, it will be created. If it does exist, it will be + truncated. This + can also be selected using any of the standard fopen() + modes; "w","wb","w+","w+b", and "wb+" +
  • "append": Opens a file in read/write mode. The file + pointer is automatically placed at the end of the file for appending, + but random-access read operations are allowed as well.This + can also be selected using any of the standard fopen() + modes; "a","ab","a+","a+b", and "ab+" +
+
+ + After you open the file handle you can use the same set of + subroutines for operations on the file regardless of whether the + file is HDF or IEEEIO. The libraries manage all of this internally. So + the open step is the only thing that is important to differentiating + between your HDF and IEEEIO files. + There are plans, for example, to have a SocketIO system + that allows the data to be written out to a TCP socket instead of to a + file for real-time simulation-visualization systems. There are also + plans to use this interface to drive an existing Parallel IO + system.


+ 

+	/* write an IEEEIO file */
+    IOFile writer = IEEEopen("datafileout.raw","write"); 
+	/* write an HDF file */
+    IOFile writer = HDFIOopen("datafileout.raw","w"); /* "w" is also valid */
+	/* another way to open for writing */
+    IOFile writer = IEEEopenWrite("datafileout.raw");
+    /* open HDF file for reading */ 
+    IOFile reader = HDFIOopen("datafilein.raw","read"); 
+    /* another way to open an HDF file for reading */
+    IOFile reader = HDFIOopenRead("datafileout.raw");
+    /* another way to open an IEEEIO file for reading */
+    IOFile reader = IEEEopenRead("datafileout.raw"); 
+

+ + You can test if the file was opened successfully using the + IOisValid() function.
+ 

+    IOFile fileID = IEEEopen("datafileout.raw","write");
+    if(!IOisValid(fileID))
+       puts("The file you specified does not exist or is not in a
+readable format");
+

+ + To close the file, you simply use IOclose. + 
+   IOclose(IOFile filehandle);
+
+ + +
+

Writing

 + To write data you simply use the method write(). +

ANSI C Prototype
+ int IOwrite(IOFile filehandle,int numbertype,int rank,int + *dimensions,void *data); +

+
filehandle +
An open filehandle for the datafile. +
numbertype: +
The type of the data being stored + (datatype definition). + It can be one of +
    +
  • FLOAT32
    32-bit single-precision IEEE + float +
  • FLOAT64
    64-bit double-precision IEEE + float +
  • STRING
    Character string. This is + null-terminated automatically by the API. This is + interpreted differently from the byte datatype + which is raw data. +
  • INT8
    byte +
  • INT16
    16-bit short integer +
  • INT32
    32-bit standard integer +
  • INT64
    64-bit long integer. (note: this is not + availible on the Intel/Windows platform because it + does not allow 64-bit integers) +
  • UINT8
    unsigned character +
  • UINT16
    unsigned 16-bit short integer +
  • UINT32
    unsigned 32-bit standard integer +
  • UINT64
    unsigned 64-bit long + integer. (note: this is not availible on the + Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions of + the dataset +
data: +
Your data array. +
+ + So to write a sample array of data. + 
+	float myarray[40][50][60]; /* our bogus data array */
+	int i,rank=3;
+	int dims[3]={60,50,40}; /* notice these are reversed. */
+		/* this is because ieeeio assumes f77 order for data 
+		  and c/c++ use exactly the opposite ordering for data in */
+memory.
+	IOFile writer=IEEEopen("datafile.raw","write"); /* create a outfile */
+	for(i=0;i<ndatasets;i++){
+		. . . . computation . . .
+		IOwrite(writer,FLOAT32,rank,dims,myarray); /* write a dataset */
+		. . . . you can write as many datasets as you want
+	}
+	IOclose(writer); /* then close the file */
+
+ +
+

Reading Data

 + Reading is a two step process. First you get information on + the size and type of the data you intend to read. This allows + you to allocate an array of the proper size and type for the + reading. Then you actually read the data into a pre-allocated + array. The methods for this are IOreadInfo() and + IOread().

+ ANSI C Prototype
+ int IOreadInfo(IOFile filehandle,int *numbertype,int *rank,int + *dims,int maxdims);

+

+
filehandle +
A filehandle open for reading or appending. +
numbertype: +
The type of the data being stored + (datatype definition). + It can be one of +
    +
  • FLOAT32
    32-bit single-precision IEEE float +
  • FLOAT64
    64-bit double-precision IEEE float +
  • INT8
    byte +
  • INT16
    16-bit short integer +
  • INT32
    32-bit standard integer +
  • INT64
    64-bit long integer. (note: this is not + availible on the Intel/Windows platform) +
  • UINT8
    unsigned character +
  • UINT16
    unsigned 16-bit short integer +
  • UINT32
    unsigned 32-bit standard integer +
  • UINT64
    unsigned 64-bit long integer. (note: this is not availible on the Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions + of the dataset +
maxdims: +
The maximum size of the dimensions array you given it. + This prevents array overruns if the dataset has more + dimensions than you were anticipating. It can be any positive + integer. +
+ This retrieves information about the datatype, rank, + and dimensions of the dataset to be retrieved. + By default the maximum size of the dimensions array is 3, + but you can set it to be larger.

+ ANSI C Prototype
+ + int IOread(IOFile filehandle,void *data); +

+ This actually reads the dataset into the preallocated array + data.

+ + Another useful utility function is IOsizeOf() which returns the + number of bytes in a give IO datatype in manner analogous to the + standard C sizeof() operator. + + So for instance, to read a simple dataset, you would do + 

+	int rank;
+	int numbertype;
+	int dims[3];
+	float *data; /* assumes float data */
+	IOFile infile = IEEEopen("dataset.raw","read");
+	IOreadInfo(infile,&numbertype,&rank,dims);
+	/* OK, we are assuming a 3D IO::Float32 array, 
+	 but you can be more sophisticated... */
+        data = (float*)malloc(IOnBytes(numbertype,rank,dims));
+        /* nBytes() is a convenience function... you could also use
+           data = (float*)malloc(dims[0] * dims[1] * dims[2] * IOsizeOf(numbertype)); */
+	IOread(infile,data); /* read in the data */
+

+ + Since multiple datasets can be stored in a file, you can + retrieve them in the order they were written (there is a seek() function that allows random access as + well). The method readInfo() implies reading the next + dataset stored in the file. The method nDatasets() tells how + many datasets are in a file. So typically if you want to read all + datasets in a file in order, you would use code similar to; + 

+	IOFile infile = IEEEopen("dataset.raw","r");
+	for(int i=0;i< IOnDatasets(infile);i++){
+	  .....lots of code....
+	  IOreadInfo(infile,&numbertype,&rank,dims); /* increments to next dataset */
+	  .....more code....
+	}
+
+ +
+

Random Access to Datasets + (Seeking)

 + You can select specific datasets in a file using the seek() + method.

+ ANSI C Prototype + int IOseek(IOFile filehandle,int index) +

+
filehandle: +
Handle to a file open for reading. +
index: +
The index of the dataset you want to read from. This can + be any number from 0 to (number_of_datasets - 1). +
+ +
+

Writing Attributes

 + Attributes allow you to attach extra information to each + dataset stored in the file. Each attribute has a name and an + array of data (of any of the standard IO datatypes) stored with + it. These attributes can be retrieved by name or by integer + index in the order in which they were stored. A typical + attribute would typically be parameters that describe the grid + or the data like, "origin" which would be the 3-vector of floats + which locates of the origin of a grid in 3-space. The method + used to write these attributes is IOwriteAttribute().

+ ANSI C Prototype
+ + int IOwriteAttribute(IOFile filehandle,char *name,int numbertype,int + length,void *data) +

+

+
filehandle +
An open filehandle for the datafile. +
name: +
Name of the attribute (like "origin" or "coordinates") +
numbertype: +
The type of the data array associated with the attribute + (datatype definition) +
length: +
The number of elements in the data array. +
data: +
The attribute data. +

+ So to write an attribute named origin along with a + 3-vector float for the coordinates of the origin, you would use; + 

+	float origin[3]={5.1,0.3,0.5};
+	/* and assuming the file is already open for writing
+	 the following attribute will be attached to the last 
+         written dataset. (you must have write data before adding
+         attribs) */
+	IOwriteAttribute(writer,"origin",FLOAT32,3,origin);
+
+ +
+

Reading Attributes

 + The attributes can be retrieved in the order they were written + or they can be retrieved by their name. To retrieve the + attributes in order, you would utilize the IOnAttributes() + method to determine how many attributes are attached, + IOreadIndexedAttributeInfo() to get the size and type of the + attribute based on its index (use IOreadAttributeInfo() to get size + and type for the attribute based on its name), + and IOreadAttribute() to read the attribute + data.

+ ANSI C Prototype
+ int IOnAttributes()

+

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
Number of attributes in the file +

+ ANSI C Prototype
+ int IOreadIndexedAttributeInfo(IOFile filehandle,int index,char *name,int *numbertype,int *length,int maxnamelength); + +

+
filehandle +
An open filehandle for the datafile. +
index: +
The index of the attribute which can be 0 to (nattributes-1) +
name: +
A buffer in which the name of the attribute will be placed. +
numbertype: +
The type of the attribute data + (datatype definition) +
length: +
The number of elements in the attribute data. +
maxnamelength:
The maximum size of a name that can be + stored in the name buffer. It can be any positive integer. +
+

+ ANSI C Prototype
+ int IOreadAttribute(IOFile filehandle,int index,void + *data); +

+
filehandle +
An open filehandle for the datafile. +
index: +
The index of the attribute data to read +
data: +
The array into which the attribute data is copied. +
+ So for example, to read the attributes in order, you can use + 
+	for(int i=0;i<IOnAttributes(infile);i++){
+	    char name[128];
+	    int length,datatype;
+	    ...
+	    IOreadIndexedAttributeInfo(infile,i,name,&datatype,&length,128);
+	    ... allocate some data for storage
+	    IOreadAttribute(infile,i,data);
+	}
+

+ + The attributes can also be retrieve by name. In fact, the is + the most likely way you will use the attributes interface. The + IOreadAttributeInfo() method is overloaded to allow retrieval by + name as + well. It returns the index of the attribute if one is found with a + matching name: it returns -1 if one is not found. +

ANSI C Prototype
+ + int IOreadAttributeInfo(char *name,int *numbertype,int *length); + +

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
The index of the attribute if found or -1 if no attribute with + matching name is found. +
name: +
The name of the attribute to find. +
numbertype: +
Returns the numbertype of the stored attribute data + (datatype definition) +
length: +
he length of the stored attribute data. +
+ So a typical use of this interface would be to find an attribute + named "origin" and retrieve its data if it exists. + 
+	int index = IOreadAttributeInfo(infile,"origin",&datatype,&length);
+	if(index>=0) /* the attribute exists */
+		IOreadAttribute(infile,index,data);
+	else
+		puts("The attribute origin could not be found");
+
+ + + +
+

Writing Annotations

 + An annotation is a text string which can be used to + describe a dataset. To write an annotation, you use the + writeAnnotation() method.

+ ANSI C Prototype
+ + int IOwriteAnnotation(IOFile filehandle,char *annotationtext) + +

+
filehandle +
An open filehandle for the datafile. +
annotationtext: +
A null terminated string of the annotation text +
+ The annotation will be attached to the last written dataset. + You can store more than one annotation per dataset and the + annotations can be of arbitrary length.

+ +

+

Reading Annotations

 + The annotations are stored in the order they are written. The + method nAnnotations() is used to find out how many + attributes are attached to a dataset. The method + readAnnotationInfo() is used to find the length of the + annotation and readAnnotatin() reads the actual + annotation text.

+ ANSI C Prototype
+ + int IOnAnnotations(IOFile filehandle); + +

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
Number of annotations attached to current dataset. +

+ ANSI C Prototype
+ IOreadAnnotationInfo(IOFile filehandle,int index,int *length) + +

+
filehandle +
An open filehandle for the datafile. +
index: +
Index of the annotations which can be 0 to (nannotations-1) +
length: +
Length in characters of the annotation. This includes the + null-terminating character. +
+
+

Writing and Reading in Chunks

 + For distributed-memory programming paradigms like HPF, MPI, or + PVM, it is often not unfeasible to write data to disk in a + single operation. For this reason, a chunking interface + is provided which allows you to write data in blocks to the + disk.

+ To begin a chunk writing operation, you must first reserve a + data chunk in the file. This is accomplished using IOreserveChunk() + ANSI C Prototype
+ + int IOreserveChunk(IOFile filehandle,int datatype,int rank,int *dims); +

+ Once space has been allocated in the datafile, you can write + blocks of data specified by their dimensions and origin using + IOwriteChunk() + ANSI C Prototype
+ + int IOwriteChunk(IOFile filehandle,int *dims,int *origin,void *data); +

+ Likewise, it is possible to read chunks from the disk as + well. No special procedure is required to select a record to + read in chunks. Simply use IOreadInfo() + to get the dimensions and + type of the dataset and then use IOreadChunk() in place + of IOread() in order to read-in the data. + ANSI C Prototype
+ + int IOreadChunk(IOFile filehandle,int *dims,int *origin,void *data); +

+

+
John + Shalf
+ + +Last modified: Thu Feb 4 21:58:57 CST 1999 + + + diff --git a/doc/html/UsingF77.html b/doc/html/UsingF77.html new file mode 100644 index 0000000..5118411 --- /dev/null +++ b/doc/html/UsingF77.html @@ -0,0 +1,532 @@ + + + IEEEIO F77 Interface + + + + + +

Fortran77

+
+

Using the F77 Interface

+ To use the F77 interface you must link to ieeeio.a and + the C++ libraries using +
+
All machines except SGI Irix 6.4 +
f77 link_line_stuff -L$IEEE_DIRECTORY/lib + -lieeeio -lC -lc +
SGI machines running Irix 6.4 (eg. O2k and + Octane) +
f77 link_line_stuff -L$IEEE_DIRECTORY/lib + -lieeeio -lC -lCsup -lc +
+ The -lC and -lc links in the C and C++ + libraries with the fortran libraries. Irix 6.4 also requires + -lCsup for reasons I do not know.

+ + If you + also want HDF support you must also link with libhdfio.a and + the usual complement of HDF libraries using + -L$HDF_DIRECTORY/lib -L$IEEE_DIRECTORY/lib -lhdfio + -lieeeio -lmfhdf -ldf -ljpeg -lz. +

+

F77 Subroutines

+ + +
+

Opening

 + Just like the familiar FILE* type for F77 stdio operations, all + IEEEIO operations require a file handle. The type of this handle is + INTEGER*8 (and 8-byte integer number). The ieee_open() and hdf_open() + routines are used to create this handle and the io_close() subroutine can + be used to close file handles of either type.

+ F77 Call Format
+ INTEGER*8 ieee_open(CHARACTER filename(*),CHARACTER accessmode(*))
+ INTEGER*8 ieee_openr(CHARACTER filename(*))
+ INTEGER*8 ieee_openw(CHARACTER filename(*))
+ INTEGER*8 ieee_opena(CHARACTER filename(*))
+

+
filename: +
The name of the IEEEIO data file to + open. The typical extension for these files is .raw. +
accessmode +
This is the type of access for the file. You can either + pass an accesstype option to the function or use the + appropriately + named function for the type of access you desire. +
    +
  • openr = 'READ':Opens a file in read-only mode. +
  • openw = 'WRITE':Opens a file in write-only mode. If the + file does not exist, it will be created. If it does exist, it will be + truncated. +
  • opena = 'APPEND': Opens a file in read/write mode. The file + pointer is automatically placed at the end of the file for appending, + but random-access read operations are allowed as well. +
+
+ + After you open the file handle you can use the same set of + subroutines for operations on the file regardless of whether the + file is HDF or IEEEIO. The libraries manage all of this internally. So + the open step is the only thing that is important to differentiating + between your HDF and IEEEIO files. + There are plans, for example, to have a SocketIO system + that allows the data to be written out to a TCP socket instead of to a + file for real-time simulation-visualization systems. There are also + plans to use this interface to drive an existing Parallel IO + system.


+ 

+c The file handles are INTEGER*8's
+    INTEGER*8 writer
+    INTEGER*8 reader
+c open a file for writing
+    writer = ieee_openw('datafileout.raw')
+c open an HDF file for writing
+    writer = hdf_openw('datafileout.raw')
+c open HDF file for reading  
+    reader = hdf_openr('datafilein.raw')
+c open an IEEEIO file for reading
+    reader = ieee_openr('datafileout.raw')
+

+ + You can test if the file was opened successfully using the + io_isvalid() function.
+ 

+    IF io_isvalid(infile).EQ.0 THEN
+    	write(*) 'The file you specified does not exist or is not in a
+readable format'
+

+ + To close the file, you simply use io_close. + 
+   INTEGER io_close(INTEGER*8 filehandle)
+
+ +
+

Writing

 + To write data you simply use the method write(). +

F77 Call Format
+ INTEGER io_write(INTEGER*8 filehandle,INTEGER numbertype,INTEGER rank,INTEGER + dimensions(*),type data(*)) +

+
filehandle +
An open filehandle for the datafile. +
numbertype: +
The type of the data being stored + (datatype definition). + It can be one of +
    +
  • INT8=0
    CHARACTER byte +
  • INT16=1
    INTEGER*2 short integer +
  • INT32=2
    INTEGER*4 standard integer +
  • INT64=3
    INTEGER*8 long integer. (note: this is not + availible on the Intel/Windows platform) +
  • FLOAT32=4
    REAL*4 32-bit single-precision IEEE + float +
  • FLOAT64=5
    REAL*8 64-bit double-precision IEEE + float +
  • UINT8=6
    unsigned character +
  • UINT16=7
    unsigned INTEGER*2 short integer +
  • UINT32=8
    unsigned INTEGER*4 standard integer +
  • UINT64=9
    unsigned INTEGER*8 long + integer. (note: this is not availible on the + Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions of + the dataset +
data: +
Your data array. +
+ + So to write a sample array of data. + 
+	REAL*4 myarray(40,50,60) // our bogus data array
+	INTEGER i,rank
+	INTEGER dims(3)
+	rank=3
+	dims(1)=40
+	dims(2)=50
+	dims(3)=60
+c this is because ieeeio assumes f77 order for data 
+c and c/c++ use exactly the opposite ordering for data 
+c in memory.
+c   create a outfile
+	INTEGER*8 writer,ieee_openw
+	writer = ieee_openw('datafile.raw')
+	DO i=0,ndatasets
+		. . . . computation . . .
+c 		write a dataset 
+		CALL io_write(writer,FLOAT32,rank,dims,myarray)
+		. . . . you can write as many datasets as you want
+	ENDDO
+c then close the file 
+	CALL io_close(writer) 
+
+ +
+

Reading Data

 + Reading is a two step process. First you get information on + the size and type of the data you intend to read. This allows + you to allocate an array of the proper size and type for the + reading. Then you actually read the data into a pre-allocated + array. The methods for this are io_readInfo() and + io_read().

+ F77 Call Format
+ INTEGER io_readInfo(INTEGER*8 filehandle,INTEGER numbertype,INTEGER rank,INTEGER + dims(*),INTEGER maxdims)

+

+
filehandle +
A filehandle open for reading or appending. +
numbertype: +
The type of the data being stored + (datatype definition). + It can be one of +
    +
  • INT8=0
    CHARACTER type +
  • INT16=1
    INTEGER*2 short integer +
  • INT32=2
    INTEGER*4 standard integer +
  • INT64=3
    INTEGER*8 long integer. (note: this is not + availible on the Intel/Windows platform) +
  • FLOAT32=4
    REAL*4 32-bit single-precision IEEE + float +
  • FLOAT64=5
    REAL*8 64-bit double-precision IEEE + float +
  • UINT8=6
    unsigned CHARACTER character +
  • UINT16=7
    unsigned INTEGER*2 short integer +
  • UINT32=8
    unsigned INTEGER*4 standard integer +
  • UINT64=9
    unsigned INTEGER*8 long + integer. (note: this is not availible on the + Intel/Windows platform) +
+
rank +
Number of dimensions of the dataset +
dimensions: +
An array of rank integers that give the dimensions + of the dataset +
maxdims: +
The maximum size of the dimensions array you given it. + This prevents array overruns if the dataset has more + dimensions than you were anticipating. It can be any positive + integer. +
+ This retrieves information about the datatype, rank, + and dimensions of the dataset to be retrieved. + By default the maximum size of the dimensions array is 3, + but you can set it to be larger.

+ F77 Call Format
+ + INTEGER io_read(INTEGER*8 filehandle,sometype data(*)) +

+ This actually reads the dataset into the preallocated array + data.

+ + Another useful utility function is io_sizeof() which returns the + number of bytes in a give IO datatype in manner analogous to the + standard C sizeof() operator. This may not be of consequence for most + f77 codes. + + So for instance, to read a simple dataset, you would do + 

+	INTEGER rank
+	INTEGER numbertype
+	INTEGER dims(3)
+c Note: The "PTR" is the architecture dependent definition of
+c a dynamically-allocated memory handle. (my vary from system to
+c system under F77.
+	PTR data
+	INTEGER*8 infile,ieee_openr
+	infile = ieee_openr('dataset.raw')
+	io_readInfo(infile,numbertype,rank,dims)
+c OK, we are assuming a 3D IO::Float32 array, 
+c but you can be more sophisticated... 
+c Note: The "allocate" statement is a stand-in for
+c your architecture dependent dynamic memory allocation function
+c for your particular system.
+        data = allocate(io_nbytes(numbertype,rank,dims))
+c io_nbytes() is a convenience function.. you can just as easily use
+c	data = allocate(dims(1) * dims(2) * dims(3) * io_sizeof(numbertype))
+	CALL io_read(infile,data) // read in the data
+

+ + Since multiple datasets can be stored in a file, you can + retrieve them in the order they were written (there is a seek() function that allows random access as + well). The method io_readinfo() implies reading the next + dataset stored in the file. The method io_numdata() tells how + many datasets are in a file. So typically if you want to read all + datasets in a file in order, you would use code similar to; + 

+	INTEGER*8 infile,ieee_openr
+	infile = ieee_openr('dataset.raw')
+	ndatasets = io_numdata(infile)
+	DO i=1,ndatasets BEGIN
+	  .....lots of code....
+c increments to next dataset
+	  CALL io_readinfo(infile,numbertype,rank,dims) 
+	  .....more code....
+        ENDDO
+
+ +
+

Random Access to Datasets + (Seeking)

 + You can select specific datasets in a file using the seek() + method.

+ F77 Call Format + INTEGER io_seek(INTEGER*8 filehandle,INTEGER index) +

+
filehandle: +
Handle to a file open for reading. +
index: +
The index of the dataset you want to read from. This can + be any number from 0 to (number_of_datasets - 1). +
+ +
+

Writing Attributes

 + Attributes allow you to attach extra information to each + dataset stored in the file. Each attribute has a name and an + array of data (of any of the standard IO datatypes) stored with + it. These attributes can be retrieved by name or by integer + index in the order in which they were stored. A typical + attribute would typically be parameters that describe the grid + or the data like, 'origin' which would be the 3-vector of floats + which locates of the origin of a grid in 3-space. The method + used to write these attributes is io_writeAttribute().

+ F77 Call Format
+ + INTEGER io_writeatt(INTEGER*8 filehandle,CHARACTER name(*),INTEGER numbertype,INTEGER + length,(some type) data(*)) +

+

+
filehandle +
An open filehandle for the datafile. +
name: +
Name of the attribute (like 'origin' or 'coordinates') +
numbertype: +
The type of the data array associated with the attribute + (datatype definition) +
length: +
The number of elements in the data array. +
data: +
The attribute data. +

+ So to write an attribute named origin along with a + 3-vector float for the coordinates of the origin, you would use; + 

+	REAL*4 origin(3)
+	origin(1)=5.
+	origin(2)=0.3
+	origin(3)=0.5
+c and assuming the file is already open for writing
+c the following attribute will be attached to the last 
+c written dataset. (you must have write data before adding attribs)
+	io_writeatt(writer,'origin',FLOAT32,3,origin)
+
+ +
+

Reading Attributes

 + The attributes can be retrieved in the order they were written + or they can be retrieved by their name. To retrieve the + attributes in order, you would utilize the io_numatt() + method to determine how many attributes are attached, + io_iattinfo() to get the size and type of the + attribute based on its index (use io_attinfo() to get size + and type for the attribute based on its name), + and io_readatt() to read the attribute + data.

+ F77 Call Format
+ INTEGER io_numatt(INTEGER*8 filehandle)

+

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
Number of attributes in the file +

+ F77 Call Format
+ INTEGER io_iattinfo(INTEGER index,CHARACTER name(*),INTEGER + numbertype,INTEGER length,INTEGER maxnamelength) + +

+
index: +
The index of the attribute which can be 0 to (nattributes-1) +
name: +
A buffer in which the name of the attribute will be placed. +
numbertype: +
The type of the attribute data + (datatype definition) +
length: +
The number of elements in the attribute data. +
maxnamelength:
The maximum size of a name that can be + stored in the name buffer. It can be any positive integer. +
+

+ F77 Call Format
+ INTEGER io_readatt(INTEGER*8 filehandle,INTEGER index,(sometype) data(*)) +

+
filehandle +
An open filehandle for the datafile. +
index: +
The index of the attribute data to read +
data: +
The array into which the attribute data is copied. +
+ So for example, to read the attributes in order, you can use + 
+    INTEGER io_numatt
+    CHARACTER*128 name
+    INTEGER length,datatype
+    nattributes=io_numatt(infile)
+	DO i=0,nattributes
+	    ...
+	    CALL io_iattinfo(infile,i,name,&datatype,&length)
+	    ... allocate some data for storage or put in preallocated data
+	    CALL io_readatt(infile,i,data)
+	ENDDO
+

+ + The attributes can also be retrieve by name. In fact, the is + the most likely way you will use the attibutes interface. The + io_attinfo() method is overloaded to allow retrieval by + name as + well. It returns the index of the attribute if one is found with a + matching name: it returns -1 if one is not found. +

F77 Call Format
+ + INTEGER io_attinfo(CHARACTER name(*),INTEGER numbertype,INTEGER + length) + +

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
The index of the attribute if found or -1 if no attribute with + matching name is found. +
name: +
The name of the attribute to find. +
numbertype: +
Returns the numbertype of the stored attribute data + (datatype definition) +
length: +
The length of the stored attribute data. +
+ So a typical use of this interface would be to find an attribute + named 'origin' and retrieve its data if it exists. + 
+	INTEGER io_attinfo
+	index = io_attinfo(infile,'origin',datatype,length)
+	IF (index.LE.0) THEN 
+c the attribute exists
+		CALL io_readatt(infile,index,data)
+	ELSE
+		write (*) 'The attribute origin could not be found'
+	ENDIF
+
+ + + +
+

Writing Annotations

 + An annotation is a text string which can be used to + describe a dataset. To write an annotation, you use the + writeAnnotation() method.

+ F77 Call Format
+ + INTEGER io_writenote(INTEGER*8 filehandle,CHARACTER annotationtext(*),INTEGER length) + +

+
filehandle +
An open filehandle for the datafile. +
annotationtext: +
A character array of the annotation text +
annotationlength +
The length of the character array +
+ The annotation will be attached to the last written dataset. + You can store more than one annotation per dataset and the + annotations can be of arbitrary length.

+ +

+

Reading Annotations

 + The annotations are stored in the order they are written. The + method io_numnote() is used to find out how many + attributes are attached to a dataset. The method + io_readnoteinfo() is used to find the length of the + annotation and io_readnote() reads the actual + annotation text.

+ F77 Call Format
+ + INTEGER io_numnote(INTEGER*8 filehandle) + +

+
filehandle +
An open filehandle for the datafile. +
returnvalue: +
Number of annotations attached to current dataset. +

+ F77 Call Format
+ io_readnoteinfo(INTEGER*8 filehandle,INTEGER index,INTEGER length) + +

+
filehandle +
An open filehandle for the datafile. +
index: +
Index of the annotations which can be 0 to (nannotations-1) +
length: +
Length in characters of the annotation. This includes the + null-terminating character. +
+ +
+

Writing and Reading in Chunks

 + For distributed-memory programming paradigms like HPF, MPI, or + PVM, it is often not unfeasible to write data to disk in a + single operation. For this reason, a chunking interface + is provided which allows you to write data in blocks to the + disk.

+ To begin a chunk writing operation, you must first reserve a + data chunk in the file. This is accomplished using io_reservck() + F77 Call Format
+ + INTEGER io_reservck(INTEGER*8 filehandle,INTEGER datatype,INTEGER rank,INTEGER dims(*)) +

+ Once space has been allocated in the datafile, you can write + blocks of data specified by their dimensions and origin using + io_writeck() + F77 Call Format
+ + INTEGER io_writeck(INTEGER*8 filehandle,INTEGER dims(*),INTEGER origin(*),(sometype) data(*...)) +

+ Likewise, it is possible to read chunks from the disk as + well. No special procedure is required to select a record to + read in chunks. Simply use io_readinfo() + to get the dimensions and + type of the dataset and then use io_readck() in place + of io_read() in order to read-in the data. + F77 Call Format
+ + INTEGER io_readck(INTEGER*8 filehandle,INTEGER dims(*),INTEGER origin(*),(sometype) data(*...)) +

+

+
John + Shalf
+ + +Last modified: Thu Feb 4 22:02:39 CST 1999 + + + diff --git a/doc/html/UsingIDL.html b/doc/html/UsingIDL.html new file mode 100644 index 0000000..42f2048 --- /dev/null +++ b/doc/html/UsingIDL.html @@ -0,0 +1,154 @@ + + + + IEEEIO IDL/PV-Wave Interface + + + + + +

IDL/PV-Wave

+
+

Using the IDL/PV-Wave Interface

+ The IDL/PV-Wave interface is only for reading. In the future + file writing may be supported, but there hasn't been a need for + this as of yet. The reader is very simplistic right now so you + must convert files to native byte order using the convert2native utility + in order for this reader to understand the file. Likewise, + there is support for reading attributes but annotation reading + has been delayed due to lack of interest in the short term.

+ + The procedures are contained in the file + ieeereader.pro. They can be + read into IDL using the command .run + ieeereader.pro. You can configure this file to + autoload by breaking the routines ieeeopen, + ieeeclose, ieeeread, and + ieeereadattr + into separate files named + procedurename.pro.

+ +

+ + +
+

Opening and Closing Files

 + Like openr you must open a file handle to access + the IEEEIO files in IDL.

+ IDL Function
+ filedescriptor=ieeeopen('filename.raw')

+ This function opens a file descriptor for reading. Currently + the IDL interface is a read-only interface.

+ To close an IEEEIO filedescriptor and reclaim its resources you + use ieeeclose.

+ IDL Procedure
+ ieeeclose,filedescriptor + Closes the filedescriptor. It will also deallocate any existing + IDL handles when I get this thing converted to use dynamic + datastructures.

+

+

Querying File Information

 + IDL Function + ieeendatasets(descriptor)
+ Returns number of datasets in the file

+ + IDL Function + ieeenattribs(descriptor,datasetnumber)
+ Returns number of attributes bound to a particular dataset.

+ +

+

Reading Datasets

 + IDL Procedure + ieeeread,filedescriptor[,datasetnumber] +
+
The datasetnumber defaults to 0 if you don't specify +
Named Params +
    +
  • RANK = returns rank of dataset +
  • DIMENSIONS = returns dims (allocates if none specified) +
  • TYPE = Integer datatype...
    + In terms of IDL datatypes + 0=Byte, 1=Fix, 2=Long,3=not availible in IDL, + 4=Float,5=Double +
  • DATA = Returns data. If storage is provided, + then it will + copy into that storage space. Otherwise it will + allocate. +
+
The following switches affect Data allocation/management +
    +
  • /INFO : Makes it skip reading the data +
  • /ASSOC_1D : Associates data as a sequence of 1D x-columns + (eg data=assoc(unit,xarr(dims(0))) +
  • /ASSOC_2D : Associates data as a sequence of 2D xy-slices +
  • /ASSOC_3D : Associates data as a sequence of 3D + blocks of data + (note: only block #0 is valid of course) +
  • /ASSOC_ELEMENTS : Associates data as a sequence of elements +
  • /ALLOCATE : Forces it to nuke any existing data and + allocate + new storage for the data before copying +
  • /COPY : Forces it to copy into preallocated data space. + This will force an error if no data is availible + or if the availible preallocated data space is too + small. +
+
+ +
+

Reading Attributes

 + IDL Procedure
+ ieeereadattr,descriptor,[datasetnumber] +
+
datasetnumber defaults to 0 if not specified +
Named parameters are +
    +
  • NUMBER =the index of the attribute (ranges from + 0 to nattribs-1) + nattributes is computed per dataset. +
  • NAME = The name of the attribute. If you + specify a NAME= + without the NUMBER=, it will search for the attribute + based on its name. However, if you specify a number + with NUMBER=, it will retrieve the attribute based + on its index and replace the NAME parameter with + the name of the attrib it read. +
  • LENGTH = number of elements in the attribute + data array +
  • TYPE = datatype of the attribute +
  • DATA = The place to put the attribute data. + If the array + exists and it is the proper size, then it will copy + into the array. Otherwise it will nuke the array + and replace it with a properly sized one. +
+
Data reading is affected by the following flags +
    +
  • /ASSOC_ELEMENTS : Associate as an array of elements +
  • /ASSOC_1D : Associate as a 1D array +
  • /COPY : Forces an error if the DATA= you + provided is not the + correct size. +
  • /ALLOCATE : Forces destruction and reallocation + of the array + you provide with DATA= +
  • /INFO : Does not read data. Just for getting info. +
+
+
+
John Shalf
+ + +Last modified: Wed Apr 9 11:41:11 MDT + + + diff --git a/doc/html/Utilities.html b/doc/html/Utilities.html new file mode 100644 index 0000000..e901176 --- /dev/null +++ b/doc/html/Utilities.html @@ -0,0 +1,120 @@ + + + IEEEIO Utilities + + + +

Utilities

+
+ +

convert2native

 + Converts an IEEEIO file to the native byte-ordering so that reading can + occur as efficiently as possible. The -byteswap flag causes the + utility to do the opposite (switch to non-native byte ordering). Please + note that ieeeio does not have any problem reading files of any + byte-order, however, byteswapping does exact a performance penalty on + any system. So converting to native byte order improves performance.

+ + usage
+ convert2native [-byteswap] infile outfile +

+
infile +
The file to read for translation +
oufile +
The file to write to. It will be truncated before it is written to + so don't attempt to write to the input file. +
-byteswap +
Forces byte swapping to the opposite of native byte ordering. The + default is to convert to native byte ordering. +
+ +
+

ioconvert

 + A more general utility than convert2native; ioconvert + converts a file from source format (IEEEIO or HDF) to any allowable + destination format (currently only IEEEIO or HDF). It can also perform + byteswapping to convert to native or the opposite of native format. The + default is native format. convert2native only exists for people + who want the byte-swapping capability but don't wish to compile the full + HDF libraries.

+ + ioconvert senses the filetype by the extension you use for the filename. + .ieee and .raw are interpreted as IEEEIO files and + .hdf is interpreted as an HDF file.

+ + usage
+ ioconvert [-byteswap] infile{.hdf|.ieee|.raw} + outfile{.hdf|.ieee|.raw} +

+
infile +
The file to read for translation +
oufile +
The file to write to. It will be truncated before it is written to + so don't attempt to write to the input file. +
-byteswap +
Forces byte swapping to the opposite of native byte ordering. The + default is to convert to native byte ordering. +
+ +
+

ioinfo

 + Prints out a variety of diagnostic information about IEEEIO and HDF + datafiles. A variety of flags are used to control the amount and the + type of information printed. By default, only information about the + datasets (rank, dimensions and datatype) as well as the number + of attachments will be printed.

+ + usage
+ ioinfo datafile [-showdata | -hidedata] + [-showanndata | -hideanndata] [-showanninfo | -hideanninfo] + [-showattdata | -hideattdata] [-showattinfo | -hideattinfo] + +

+
datafile +
The file you wish to examine +
-showdata or -data +
Shows the first 10 elements of each dataset. +
-hidedata [default] +
Does not show the data, but shows all information about the + datsets like the datatype and the dimensions etc... + +
-showannotationinfo or -showanninfo +
Shows information about the length of each annotation + bound to a dataset. Otherwise + only the number of annotations is shown for each dataset. +
-hideannotationinfo or -hideanninfo [default] +
Only the number of annotations is shown for each dataset. + +
-showannotationdata or -showanndata +
Shows the first 10 characters of each annotation. +
-hideannotationdata or -hideanndata [default] +
None of the contents of the annotations are printed. + +
-showattributeinfo or -showattinfo +
Shows information about the name, length and datatype of the + attributes for each attribute attached to a dataset. Otherwise + only the number of attributes is shown for each dataset. +
-hideattributeinfo or -hideattinfo [default] +
Only the number of attributes is shown for each dataset. + +
-showattributedata or -showattdata +
Shows the first 10 elements of data stored in an attribute. +
-hideattributedata or -hideattdata [default] +
None of the contents of the attribute is printed (except + information if requested). +
+ + +
+
John Shalf
+ + +Last modified: Tue Apr 8 19:01:45 MDT + + + diff --git a/doc/html/VizReaders.html b/doc/html/VizReaders.html new file mode 100644 index 0000000..a6e23cf --- /dev/null +++ b/doc/html/VizReaders.html @@ -0,0 +1,109 @@ + + + + IEEIO Readers + + + +

Readers for Visualization Systems

+
+

AVS Reader

+ AVS is a product + of + Advanced Visual Systems Inc. + and is very popular for 3D data visualization problems. The + reader for AVS is a module called Read_IEEEIO and + provides roughly the same user interface as the HDF reader + module provided by NCSA. You use the file browser to select an + IEEEIO file to open (the file extension for this type of file is + .ieee or .raw. If more than one record is found + in the file then an integer dial will appear that allows you to + select records in the file.

+ + By default, the module will set the extents of the dataset to be + equal to the dimensions of the object with an origin at 0,0,0 + (eg. if your object is an array with dimensions {30,40,50} + then the extents will be set so that the origin of the data in + 3D space is {0.0,0.0,0.0} and its maximum extent will be + {30.0,40.0,50.0}). The module recognizes attributes with the + following names + (F77, + C, + C++) + +

    +
  • origin
    + This will set the origin (min_extent) of the dataset in 3D + space in AVS. + This can be a vector of Float32 or Float64 numbers with a + length equal to the number of dimensions in the dataset. +
  • delta
    + This is the delta-spacing (dx) between elements of the + dataset. This is multiplied by the number of elements in + the dimension to get the total size of that coordinate of + the dataset. It normally used with the origin attribute. + This can be a vector of Float32 or Float64 numbers with a + length equal to the number of dimensions in the dataset. +
  • min_ext
    + This will treat the dataset as a bounding box and + set the min_extent of the dataset in 3D space in AVS. + This can be a vector of Float32 or Float64 numbers with a + length equal to the number of dimensions in the dataset. +
  • max_ext
    + This works with min_ext and sets the maximum extent + of the bounding box of the dataset in AVS (the max_extent). + This can be a vector of Float32 or Float64 numbers with a + length equal to the number of dimensions in the dataset. +
+

+ + Download Read_IEEEE for AVS
+

    +
  • AVSreadIEEE.tar.Z : + The full tarred source (the files it contains are described + below). +
  • Makefile : + The makefile to build the module. + It assumes you have already built libieeeio.a. +
  • AVSreadIEEE.c : + The AVS module wrapper for the reader. +
  • AVSreadcpp.cc : + The actual guts of the module that does the reading using libieeeio.a. +
+ To compile, you need to change the AVS_PATH variable + to point to the root of your avs installation and then type + make to build the module.

+

+ +

IDL/PV-Wave Reader

+ IDL and PV-Wave have a common + root in that they originated from a language developed by + David Stearns at the University of Colorado. Both + are now competing products with many differences in their + capabilities but the underlying language is pretty + much the identical. So this reader will work in either system.

+ + Since this is implemented as a native IDL/Wave procedure, you + need not compile or link the IEEEIO libraries on your system + to make use of this. It is completely portable since IDL is + an interpreted language.

+ + Download IDL/PV-Wave IEEEIO reader
+

+ +
+
John Shalf
+ + +Last modified: Tue Apr 8 18:27:05 MDT + + + diff --git a/doc/html/Writer.html b/doc/html/Writer.html new file mode 100644 index 0000000..d9b04f1 --- /dev/null +++ b/doc/html/Writer.html @@ -0,0 +1,172 @@ + + + + Simple Unigrid Writer + + + +

Simple Unigrid Writer

+ + Stores a sequence of multidimensional arrays including physical + grid dimensions. It assumes the grid is spaced uniformly in + each dimension.

+ +

Attribute Specification

+ The writer stores the dataset with dimensions and datatype + (thats standard HDF practice). In addition, it stores the + following NetCDF-style attributes to extend the description + of the data. +
+
+
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. +

+ +

The API

+ +
+

C++ Interface

+
+
constructor Writer::Writer(IObase &filehandle) +
The filehandle is an already open IEEEIO or HDFIO + file. This initializes the reader and attaches it to that + datafile. +
destructor ~Writer() +
This flushes all of the necessary file buffer and destroys + the Writer object. + The filehandle that the writer was bound to must be + closed separately though. +
Writer::setRank(int rank) +
Sets the rank (number of dimensions) of the datasets that + will be written. The default is 3. +
Writer::setType(int datatype) +
Sets the data type datasets written to the file. + The default is Float32 if you don't set this. +
Writer::setDims(int *dims) +
Sets the dimension sizes for data that will be written to + the file. This assumes you have already set the rank. + There is no default for this parameter. +
Writer::setOrigin(double *origin) +
This sets the real-valued origin of the dataset. It + assumes the rank has been set. The default is a 0 origin. +
Writer::setDelta(double *delta) +
Sets the real-valued grid spacing in each dimension. + Also assumes the rank has been set. +
Writer::setParams(int rank,int *dims,int type, + double *origin,double *delta) +
Set all of the above parameters in a single call. +
Writer::write(void *data) +
Writes a dataset as defined by set parameters. +
Writer::reserveChunk(WRFile wrfile) +
Reserves a chunk of size defined by the set parameters. +
Writer::writeChunk(int *dims,int *origin,void + *data) +
Write a chunk of data at the specified integer (logical) + origin and of specified dimensions into the space that has + been reserved in the datafile. +
+ +
+

C Interface

+
+
WRFile WRbeginFile(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 + WRfile API. +
WRendFile(IOFile filehandle) +
This flushes all of the necessary file buffer and + deallocates the WRFile pointer. + The filehandle that the writer was bound to must be + closed separately though. +
WRsetRank(WRFile wrfile,int rank) +
Sets the rank (number of dimensions) of the datasets that + will be written. The default is 3. +
WRsetType(WRFile wrfile,int datatype) +
Sets the data type datasets written to the file. + The default is Float32 if you don't set this. +
WRsetDims(WRFile wrfile,int *dims) +
Sets the dimension sizes for data that will be written to + the file. This assumes you have already set the rank. + There is no default for this parameter. +
WRsetOrigin(WRFile wrfile,double *origin) +
This sets the real-valued origin of the dataset. It + assumes the rank has been set. The default is a 0 origin. +
WRsetDelta(WRFile wrfile,double *delta) +
Sets the real-valued grid spacing in each dimension. + Also assumes the rank has been set. +
WRsetParams(WRFile wrfile,int rank,int *dims,int type, + double *origin,double *delta) +
Set all of the above parameters in a single call. +
WRwrite(WRFile wrfile,void *data) +
Writes a dataset as defined by set parameters. +
WRreserveChunk(WRFile wrfile) +
Reserves a chunk of size defined by the set parameters. +
WRwriteChunk(WRFile wrfile,int *dims,int *origin,void + *data) +
Write a chunk of data at the specified integer (logical) + origin and of specified dimensions into the space that has + been reserved in the datafile. +
+
+

F77 Interface

+
+
INTEGER*8 wr_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 a INTEGER*8 pointer for use by the + WRfile API. +
wr_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. +
wr_setrank(INTEGER*8 wrfile,INTEGER rank) +
Sets the rank (number of dimensions) of the datasets that + will be written. The default is 3. +
wr_settype(INTEGER*8 wrfile,INTEGER datatype) +
Sets the data type datasets written to the file. + The default is Float32 if you don't set this. +
wr_setdims(INTEGER*8 wrfile,INTEGER dims(*)) +
Sets the dimension sizes for data that will be written to + the file. This assumes you have already set the rank. + There is no default for this parameter. +
wr_setorigin(INTEGER*8 wrfile,REAL*8 origin(*)) +
This sets the real-valued origin of the dataset. It + assumes the rank has been set. The default is a 0 origin. +
wr_setdelta(INTEGER*8 wrfile,REAL*8 delta(*)) +
Sets the real-valued grid spacing in each dimension. + Also assumes the rank has been set. +
wr_setparams(INTEGER*8 wrfile,INTEGER rank,INTEGER + *dims,INTEGER type, + REAL*8 origin(*),REAL*8 delta(*)) +
Set all of the above parameters in a single call. +
wr_write(INTEGER*8 wrfile,(sometype) data(*...)) +
Writes a dataset as defined by set parameters. +
wr_reserveck(INTEGER*8 wrfile) +
Reserves a chunk of size defined by the set parameters. +
wr_writeck(INTEGER*8 wrfile,INTEGER dims(*),INTEGER + origin(*),(sometype) data(*...)) +
Write a chunk of data at the specified integer (logical) + origin and of specified dimensions into the space that has + been reserved in the datafile. +
+
+
John Shalf
+ + +Last modified: Wed May 7 16:31:19 MDT + + + diff --git a/doc/html/changes.html b/doc/html/changes.html new file mode 100644 index 0000000..ecdfa24 --- /dev/null +++ b/doc/html/changes.html @@ -0,0 +1,37 @@ +changes +---------- +done +*1) Should change Long8 to FileHandle * which is a caddr_t +*2) Should change open() arguments for C to be "r" "rw" "r+" standard +ANSI. +*3) Get rid of the IO::Write mode with IO::Create +*4) For f77, need to have modenames that are consistent with + the standard f77 IO names (maybe define in a common block). + +*6) Convert all ' to " in the C++ file +*7) Need to add IOisValid() subroutine to C and fortran libraries. + Actually instead, have the IOopen() methods return NULL if failure + and do the delete automatically internally!!!! + Keep IOisValid() around for the possible SocketIO option since the + validity can change in midstream... +*8) As well as sizeOf() and nBytes() and nElements() +*9) Need static members nBytes(int rank,int *dims,IO::DataType datatype); + nElements(int rank,int *dims,IO::DataType datatype); +*10) Need to have Unsigned integer types uInt8 uInt16 uInt32 uInt64 + + +------------ +Put off +5) Need to have full prototypes for c++ version with the meaning of the +returnvalue. +11) Change the seeking to have "current_dataset" and "ndatainfo". where +the ndatainfo is a counter for the number of times datainfo has been +called. So it acts as a trigger for incrementing the dataset pointer. +And that a data info read is not necessary to enable reading other +things like attributes. It also makes it easier to determine the +end-of-file condition. +----------- +Might not do +12) Change datatype names to IOFLOAT32 from FLOAT32 for C. + +// need a plan for 64-bit ints on the PC. diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..84ba7a7 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,65 @@ + + + FlexIO Info + + + +
+

Introduction

+ FlexIO is a compact API for storing multidimensional scientific + data. It hides the differences between underlying file formats + including + HDF-SDS, + IEEEIO, and network socket connections. + (Support for HDF5 will be added soon). It is designed to + allow you to use exactly the same subroutine/method calls to store + your data regardless of the underlying file format. + FlexIO includes C++, C, and Fortran77/F90 interfaces and it has + been ported to Sun-Solaris, Digital Unix, Cray-Unicos, SGI-Irix + (32 and 64 bit), Windows95 and NT.

+ + FlexIO borrows its terminology and storage-style from + HDF and NetCDF. + The file stores a sequence of multidimesional + arrays which are referred to generically as datasets. + The dimensions and datatype are stored with each dataset so that + the data is completely self-describing. In addition, + NetCDF-style named attributes can be stored with each dataset to + add information like coordinates, units, and other auxillary + information.

+ + A set of higher level API's sit on top of FlexIO which permit + simplified access to complex datastructures like Finite-Element, + Adaptive Mesh Refinement, and Unigrid datastructures. In + addition the MPIO interface provides access to parallel IO for + MPI codes.

+ +

+

Information

+
+
Supported Datafile Formats +
IEEEIO binary file format +
HDF 4.x SDS file format +
Network Socket remote file +
FlexIO API's +
C, C++, and Fortran programming + interface +
Higher level interfaces for + complex datastructures +
FlexIO based Software Tools +
Utilities and Data Translators +
Readers for Visualization + Systems +
Getting the Source Code and Compiling +
Download the source code +
Download precompiled libraries +
Compiling FlexIO-IEEEIO +
+
+
John Shalf
+ + +Last modified: Fri May 29 12:31:38 CDT 1998 + + + diff --git a/doc/html/why.html b/doc/html/why.html new file mode 100644 index 0000000..bccad6d --- /dev/null +++ b/doc/html/why.html @@ -0,0 +1,115 @@ + + + Why IEEEIO + + + +

Why use IEEEIO?

+
+
Its compact +
On the SGI Origin 2000, the entire library is 206k. + It contains only a little over 2,500 lines of code for + the C++, C, and F77 versions combined.

+ +

Its fast +
Most simulation applications end up writing a lot more + data than they read, the I/O interface is optimized for + maximum writing speed. No seeking is required during writing + and the low-level raw unix I/O interface + is used to maximize performance. + Preliminary performance tests + show that it is + comparable with f77 unformatted IO for writing + speed. + + Data is translated to the + machines native representation (ie. byte-swapping) + only during reading. + If speed is required for reading as well, then there is a + 'convert2native' + utility which will optimize the file + for the type of machine that is reading it.

+ +

It interoperates with HDF +
If you use HDF-SDS, you should have no problem using IEEEIO + because they share the same programming interface. You + indicate the type of file you want to use when you open + the file. From there on, the same subroutines are used + for reading or writing data to the file, whether it be HDF + or IEEEIO. In addition there is an + 'ioconvert' + utility that can translate + either direction between IEEEIO and HDF files and preserve + all of the HDF annotations and NetCDF attributes.

+ IEEEIO doesn't supercede HDF. It is designed + to be a lightweight IO system which you would use when + the broader functionality of HDF is not required.

+ +

It is crash-safe +
Since no seeking is required to maintain file integrity + during writes, you will not lose data if the + simulation program exits without having properly + closed the file.

+ +

Most machines use IEEE standard floating point number + formats +
When HDF and XDR were first created, almost every machine + architecture had its own native floating point representation. + There were VAX floats, Cray floats, and Convex floating point + representations... all mutually incompatible. Now, virtually + every major supercomputer architecture supports IEEE standard + floating number representations. The primary differences + between number formats now it the byte-order which is trival + to convert. + As a result, the XDR and HDF support for platform neutral + floating point formats is more work than is necessary for + most machines. By depending on + IEEE standard number formats, the data storage can be made + much simpler and more efficient. + If + the machine you use doesn't support IEEE floating point + numbers, then you should continue to use HDF. Since IEEEIO + interoperates with HDF, this does not require significant + modifications to your code to switch back and forth between + the two. Currently IEEEIO has been ported to SGI IRIX {5.x,6.x}, + IRIX64 6.x, HP-UX 9.01, ConvexOS {on SPP-1200 and SPP-2000}, + DEC Alpha OSF/1, and the Cray T3E. The only machine that is + not supported is the Cray C90.

+ +

Why not use XDR? +
+ So if the aim is to create a lightweight portable binary file + format, this leads to the question of why not use XDR for the + encoding? Well the answer is that in early testing it was + discovered that HDF is significantly faster and more efficient than + XDR. So if you really need XDR then you should be asking + yourself why not use HDF?

+ + Again, this file format is + primarily designed to take advantage of the fact that most of + the operations that XDR and HDF do to make the data platform + neutral are not always necessary given current binary formats + for floating point numbers. It also leads to a very simple-to-parse + file structure which brings us to the next point... +

+ +

Simple file structure +
Its extremely simple file structure makes it + easy to build readers in a variety of languages. + This is important for interpreted data processing + languages like IDL because the reader can be implemented + in native IDL instead of writing native methods. + The same is true of Java. Instead of creating native + methods that directly call the libieeeio interfaces, + the format is simple enough that it can be implemented + using java itself.

+

+ +
+
John Shalf
+ + +Last modified: Tue May 27 18:14:25 CDT 1997 + + + diff --git a/doc/html/writef77.f b/doc/html/writef77.f new file mode 100644 index 0000000..1ca4d2f --- /dev/null +++ b/doc/html/writef77.f @@ -0,0 +1,17 @@ + + subroutine openf77() + OPEN(UNIT=10,FILE='f77speed.unf',FORM='UNFORMATTED') + RETURN + END + + subroutine writef77(array) + REAL*8 array(64,64,64) + WRITE(10) array + RETURN + END + + subroutine closef77() + CLOSE(10) + RETURN + END + -- cgit v1.2.3