IWAVE Grid I/O package

1.0

Authors: William W. Symes and Xin Wang

Implements regular grid data structure and related i/o, based on RSF file format (http://www.reproducibility.org/wiki/Guide_to_RSF_file_format)

• struct axis defines a grid axis. An axis has four attributes: the number of gridpoints on the axis (n), the step between gridpoints (d), the coordinate of the first gridpoint (o), and the axis index (id) which indicates its position in the a reference ordering of axes (see Notes below for more on this). Functions provided:
  • init_default_axis : default initialization
  • fprint_axis< print axis to stream /li>
  • print_axis : print axis to stdout
  • compare_axis : compare two axes for equality
• struct grid consists of up to IWAVEBASE::RARR_MAX_NDIM axes. Functions provided:
  • init_grid : initializes grid of dimension dim - default-initializes dim axes, assigns id's in natural order
  • fprint_grid : print grid to stream
  • fprint_grid : print grid to stdout
  • compare_grid : compare two grids by comparing dimensions, axes
  • get_datasize_grid : return number of gridpoints
  • get_n : extract array (IPNT) of axis lengths (n's)
  • get_d : extract array (RPNT) of grid steps (d's)
  • get_o : extract array (RPNT) of grid origin coordinates (o's)
  • get_gs : extract array (IPNT) of global indices of grid origin
  • get_ord : extract axis order array (IPNT)
• Grid i/o package consists of functions
  • read_grid : read grid from RSF header file
  • par_grid : construct grid from PARARRAY
  • extend_array : extrapolate array data by constant along an axis
  • rsfread : read ireal array from RSF file pair
  • rsfwrite : write ireal array to RSF file pair

Notes:

1. The implementation is independent of the Madagascar code package - it uses only the RSF file format as described in the document referenced above.

2. IWAVE::grid does not implement these two features of Madagascar's package:
   • DATAPATH: The output file (value associated to keyword in) is a relative or fully qualified pathname in IWAVE::grid usage, without any implicit completion. In particular, IWAVE::grid ignores any DATAPATH environment variable, datapath= specification on command line, datapath file in the working directory, and so on.
   • Only two data formats are currently recognized, namely native 4-byte floating point real and XDR-encoded 4-byte floating point real, signalled by data_format=native_float and data_format=xdr_float respectively. The esize keyword (a holdover from SEPlib) is ignored. Thus all data is stored in 4-byte floating point form. The data can however be read to, or written from, any format for which implicit type conversion in C is defined, for example 8-byte real (double). The the ireal typedef (see IWAVE base library docs for more on this) defines the choice of internal data representation.

3. IWAVE::grid provides two keyword choices in addition to those defined by Madagascar:
   • Value scaling: inclusion of the scale keyword causes the data to be multiplied (divided) by the power of 10 indicated by the corresponding value, as it is read (written). This feature permits the user to change metric units 'on the fly', and avoid external pre/postprocessing of data files. For example, to read data in m/ms when it is stored on disk in m/s, insert 'scale=-3' in the RSF header file.
   • Physical axis assignment: typical applications assign physical meaning to the coordinate axes (such as depth). To permit the axis ordering to be intperpreted properly without requiring that data files be transposed, IWAVE::grid provides keywords x_axis, y_axis, and z_axis to tag up to three axes in the data. The internal tags (axis id numbers) corresponding to these keywords are 2, 3, and 1 respectively. For example, including 'x_axis=1' in the RSF header file causes axis 1 (that is the fastest array index) to assigned with id=2. Applications using the grid data structure can use this information to identify axis 1 as 'the x axis', whatever that means in the application's terms. For example, for trace sampling it permits a sampling application to interpret shot and receiver x coordinates as indicating positions on axis 1.

4. Parallel implementation: all i/o takes place on rank 0. Implementation assumes that a chunk consisting of a number N_SLOWEST_AXIS_SLICE of (dim-1) slices may be safely stored in an in-core buffer. Reads: data read into buffer from file on rank 0, then broadcast to all other ranks. Each rank computes that part of the data needed locally, then stores it. Writes: roughly the reverse of read, but implemented with point-to-point communication, hence slower.

---

IWAVE Home Page

---