Documentation

SGFVector is an out-of-core vector class, implementing sampled functions on a uniform rectilinear grid as HCL_Vectors. SGF stands for Sampled Grid Function. It designates an out-of-core data structure for arbitrary (< 10) dimensional regularly sampled real single and double precision hypercubical data, plus auxiliary scalar data (integer, single or double precision floating point, or string) describing the grid geometry and other information necessary to properly interpret the data. Many natural data types in science and engineering fit this description. Other types of data do not conform to the SGF design, for example because the data sampling is geometrically irregular. Such data and associated processing tasks are beyond the scope of SGF.

From the user point of view, SGF is in fact identical to the Stanford Exploration Project's ``classic'' (pre-1996) disk data storage format, with a few restrictions and extensions noted below.

The SGFSpace class implements the vector spaces in which SGFVectors live. Grid and scalar attribute specification is proper to SGFSpace, and the user should consult the documentation on that class for details. Every SGFVector knows what space it belongs to (as does every HCL_Vector), and in particular has access to all of the dimensional and auxiliary information proper to the space. The SGFVector class provides convenient access functions, described below, which return values of these parameters by keyword (the keywords are described in the SGFSpace documentation).

Sample data of an SGFVector is stored in a (native) binary data file, designated by the in keyword in the SGFSpace parameter table. The storage order is as indicated by the ordering of directions in the SGFSpace: the first direction has the fastest index, followed by the second, etc. For example if the first direction represents time, the second a space coordinate, then the fastest index is time.

SGFVector is designed to realize as HCL_Vectors data sets too large to store conveniently (or at all) in-core. Accordingly only a portion of the data resides in-core at any time during the life of an SGFVector object. This portion is called a record and has a dimension specified by the rd keyword. In other words, if rd = k, then the j-th record consists of the samples (j-1)*n1*n2*...*nk+1,..., j*n1*n2*...*nk. It is accessed through the Data() method, which returns a float or double pointer to the data buffer holding the current in-core record.

SGFVector has two constructors, one for ``old'' vectors based on preexisting data files, the other for ``new'' data for which no data file need exist. The old data constructor automatically reads the first record from disk, so the first record is accessible via Data() with no further effort on the user's part. The new data constructor presumes that the data is either nonexistent or out-of-date, so does not populate the data buffer on construction.

Next() and Rewind() will typically be the only i/o functions needed in most programs using SGFVector. The Next() method advances to the next record, and returns 1 if the current record is not the last, else 0. Next() writes the current record but does not read next record for new data sets, but has the opposite behaviour for old data sets. The Rewind() method repositions the SGFVector at its first record; if that record is old (i.e. has already been initialized), then Rewind() reads it into the data buffer.

Thus data which your program treats as either read-only or write-only is implicitly handled correctly by a loop of the form

MyVector.Rewind();
do {
  float * mydata = MyVector.Data();
  ...
} while (MyVector.Next())

These methods, and all of the arithmetic methods required by the HCL_Vector class, depend on the basic i/o methods Seek(int,int), Get() and Put(), which the user will seldom need to use directly. In the present version, if you need to read and write data, you must use these lower level methods.

Notes:

• Since the ``old'' SGFVectors automatically read the first data record into core on construction, and ``new'' SGFVectors automatically write the data to disk on destruction, data sets consisting of a single record are de-facto treated as if the data were in-core.
• Since every SGFVector keeps its private copy of the SGFSpace to which it belongs, it is practical - if somewhat inconsistent - to store the data file name, which pertains to the SGFVector, in the SGFSpace parameter table. Thus the SGFSpace parameter tables of various SGFVectors belonging to the same SGFSpace will actually differ, in that the in keyword will take different values. Since the in keyword is not tested in comparison of SGFSpaces, this convention yields consistent results.
• The new vector constructor, when called without a filename, creates a temporary file which is unlinked from the file system when the object is deleted. This is the standard method for creating workspace vectors which should disappear at the end of program execution. It is also the device used by the virtual constructor (the Member() method of the SGFSpace class).

This class has no child classes.