IWAVE Structure and Basic Use Cases

I/O

The FIELD array member of the IWaveInfo class defines the physical fields of a modeling application. The function data members describe the memory allocation and updating of the arrays representing these fields. It remains to describe initialization and finalization, that is, how external data is read to and written from these arrays.

The basic principle of IWAVE i/o is that the structure of a data item determines the manner in which it is read/written. Absent self-describing i/o formats, this principle implies that the relevant part of the code implements a case list. Persistent data is presumed to exist in disk files, or in any case be identified by single strings. Accordingly the case switch is the filename suffix. At this writing, two file data structures are realized: SEGY minus reel header, or Seismic Unix (SU) format, suffix su, and Regularly Sampled Function format, suffix rsf. [Other file or network data structures may be added to IWAVE later.]

Since the details of i/o are implicit in the choice of data structure, it remains only to connect external data units with the data arrays with which they communicate. Since the data arrays are indexed by keyword, and since several external data objects may communicate with the same data array, it follows that a keyword must be introduced to stand as a proxy for each external data object in the program text. At runtime, the keyword appears as an index into an associative array describing program inputs and ouputs; the value associated to each key is a path.

Accordingly, the final data member of the IWaveInfo class is the IOKEY array iwave_iokeys. IOKEY is a typedef for a struct consisting of

• an external data item keyword
• a field index
• a flag to indicate input (1) or output (0)
• an activity flag, which is key to defining the RVL Operator interface (see discussion below) - active arrays (1) define components of the operator domain (input) or range (output), whereas non-active arrays (0) represent auxiliary inputs/outputs.

For example, an input to the pressure Cauchy data for pressure-velocity acoustics, regarded as auxiliary data, might be represented by the IOKEY

{"init_p", 1, 1, 0}

(assuming that the pressure array has index 1) whereas the output of the same array data, regarded as defining part of the range of the simulation operator, might correspond to

{"movie_p",1, 0, 1}

Note that any sampling in space and/or time may be represented in this way, and is determined at the time of interaction with the external data unit. Some details of file structure controlling IWAVE i/o are discussed in later in this paper.

The indirection afforded by the external data unit keyword allows the the same IWAVE-based command to be used for many different combinations of inputs and outputs. Parameter pairs keyword = filename passed from a driver serve to connect specific disk files or other data repositories to external data keywords, hence to read/write operations.

The IOKEYS array defines i/o info for the basic simulation. Keywords for perturbation fields, used in derivatives and adjoint derivatives, are generated automatically. For example, if the keyword for density is rho, then the keyword for the first perturbation density (input to the first derivative) is rho_d1, The adjoint output density is rho_b1. The choices of suffix correspond to those generated by the Tapenade automatic differentiation package Hascoët and Pascual (2013). These keywords would be used in as parameter keys in pairs passed to driver routines, for example, rho_d1 = my_density_pert.rsf.

IWAVE Structure and Basic Use Cases