next up previous print clean
Next: SU Up: R. Clapp: SEPlib programming Previous: SEP3D Review

DESIGN

To overcome the coding overhead associated with SEP3D, SEPlib contains the superset library. The general design principal is to hide everything that is complicated or cumbersome in SEP3D behind a simple interface. The superset library has an internal copy of each SEP3D dataset that is accessed through a sep3dtag. This tag is a pointer to an inaccessible C strucutre (the same basic concept that the normal SEP tag uses).

To use the C library you need to #include<superset.h> and a sep3d variable. For Fortran90 you need to use sep3d_struct_mod and use the type(sep3d).

Parameter Name Description
name The sep3dtag associated with the structure.
data_type The type of data (float, integer, or complex).
file_type The type of SEPlib data (regular, with headers, or with
& grid and headers).  
usage_type The purpose of the data (input, output, or scratch).
n,o,d,label,unit Properties describing the axes.
ntraces The number of traces in the dataset.
ndim The number of dimensions in the dataset.
keyname,keytype,keyfmt Description for the keys associated with the data.
drn The data_record_number associated with portion
  of the dataset currently in the structure.
nh The number of headers currently stored in the structure.

Parameter Name Description
headers The headers currently stored in memory.
ng The number of grid values currently stored in memory.
grid The grid currently stored in memory.
wrote_data,wrote_headers Whether or not the headers and data have been written for
  this dataset.
nkeys_in The number of keys in the dataset.
nextra_keys The number of keys not in the original dataset that
& will be created by some mathematical operation.  
exp The mathematical expressions associated with these
  extra keys.
su_input Whether or not this is a SU dataset.

The programmer does not directly access this internal structure. Instead he uses a local Fortran90 type or C struct. These structures contain a subset of the internal representation, with the items up to key description in the above list included and the addition of the total number of keys in the dataset.

The programmer begins by initializing the local dataset from a file or structure, or initializes an empty container. The structure is initialized by also describing its purpose (INPUT, OUTPUT, or SCRATCH). The programmer can modify their local version and synchronize it at any time with the internal version.

Reading a dataset is done in two steps. First a window (potentially the entire dataset) of the overlying hypercube is requested. The library reads in the grid (if it exists) and the headers associated with this window. The return value is the total number of traces within the hypercube. The user can then: request the header values associated with individual keys, look at the grid values associated with the hypercube currently in memory, or read the data associated with the hypercube.

Writing a dataset follows a similar pattern. The user can provide a grid (if applicable) for a dataset. They pass the individual header key values to the internal representation. They then tell the library where within the data's hypercube these values are, and what tag to write them out to. They can also specify data associated with the hypercube portion.

Having an accessible data structure for an irregular dataset has significant advantages. One of the advantages is it now becomes much easier to pass a complex object between routines. In fact, because both the C and Fortran90 structures are just representations of an underlying data type, it is possible to smoothly go between Fortran90 and C by simply passing the sep3dtag.


 
next up previous print clean
Next: SU Up: R. Clapp: SEPlib programming Previous: SEP3D Review
Stanford Exploration Project
7/8/2003