Acoustic Staggered Grid Modeling in IWAVE

Creating the examples - running IWAVE applications

IWAVE builds with SConstruct (http://www.scons.org), either as an independent package or as part of Madagascar (Fomel, 2009). See the Madagascar web site

http://www.ahay.org/wiki/Main_Page

for download and install instructions. Source for IWAVE and other TRIP software reside in the trip subdirectory of the top-level Madagascar source directory. A README file describes how to install TRIP software independently of the rest of Madagascar, which is useful to configuring TRIP differently from other parts of the package (for example, with MPI support).

The IWAVE acoustic staggered grid modeling command is sfasg for the Madagascar build, stored in the Madagascar $RSFROOT/bin directory, or

$RSFSRC/trip/iwave/asg/main/asg.x

for the standalone build. All IWAVE commands self-document: entering the command path prints a usage statement to the terminal, including descriptions of all parameters.

The paper you are currently reading follows the reproducible research pattern described on the Madagascar web site, using Madagascar reproducible research tools. You can find the LaTeX source in the subdirectory book/trip/asg of the Madagascar source directory, and the script for building the data in

$RSFSRC/book/trip/asg/project/SConstruct

This script, together with the self-doc for the acoustic staggered grid command and the remarks in the remainder of this section, should enable you to build your own examples after the pattern used in this project.

IWAVE applications currently expect model data files in the RSF format of Madagascar (Fomel, 2009). Data from other sources will need conversion to this format. An RSF data set consists of two files, an ascii header (grid metadata) file and a flat binary data file. The data set is referenced by the header file name; one of the parameters listed in the header file is the pathname of the binary data file, with key in. The header file is small and easily created by hand with an editor, if necessary. Madagascar commands add processing history information to header files, and modify their parameters. By convention, the last value of a parameter (key=value pair) appearing in the file is the current value. Many archival data formats make the grid sample values available as a flat binary file - this is true for instance of the gridded models output by GOCAD (http://www.gocad.org), for which the vo files contain virtually the same information as (so may easily be translated to) RSF header files in ascii form, and the vodat files are flat binary files which may be used unaltered as RSF binary files.

IWAVE uses two extensions of the Madagascar RSF standard. The first is the optional inclusion of the dim and gdim keywords. These permit IWAVE applications to treat an RSF file image as defining a gdim dimensional data hypercube divided into dim dimensional slices. The second is the axis identification keyword set, id1, id2, etc.: these supply information on the physical meaning of various axes. For an IWAVE dim space-dimensional modeling problem, axes labeled id1,...,id[dim-1] are the spatial grid axes. If gdim > dim, then id[dim] labels the time axis, and id[n], n > dim, axes other than those of space-time. The IWAVE structure paper (Symes, 2014) explains the use of the additional keywords in more detail.

An example of this construction appears in the script that builds the PML examples above, which are actually frames of movies. The output of the 2D simulations are 3D RSF files (gdim=3, dim=2) with id3=2, that is, the third axis is treated as time. Madagascar applications ignore these keywords: in particular, you can view the 3D RSF simulation output as a movie using sfgrey and xtpen as usual. The presence of the additional keywords is necessary in order for IWAVE to correctly interpret the data geometry.

This example illustrates another important feature of IWAVE applications: any output data files must exist prior to execution - their data samples are overwritten. The SConstruct for this project uses sfmakevel to create the movie output files and sfput to add the IWAVE-specific keywords to the headers, before invoking the IWAVE command.

By IWAVE convention, the dimension of the problem is that of the primary model grid. In the acoustic staggered grid application, the primary model grid is that associated with the bulk modulus data. This grid is also the primary grid of the simulation: that is, the space steps used in the finite difference method are precisely those of the bulk modulus data. Thus the choice of simulation grid is made externally to IWAVE.

The IWAVE acoustic application uses specific internal scales - m/ms for velocity, g/cm$^3$ for density, and corresponding units for other parameters. To ensure that data in other (metric) units are properly scaled during i/o, the RSF header file may specify a value for the scale key, equal to the power of 10 by which the data should be multiplied on being read into the application, to convert to the internal scale. For example, if velocities are given in m/s, the header file should include the line scale = -3. In forthcoming releases, this device will be deprecated in favor of explicit unit specifications.

The current release is configured to use Seismic Unix (``SU'') (SEGY without reel header) format for trace data i/o. Units of length and time are m and ms respectively, consistent with other internal unit choices. Two peculiarities of which the user should be aware: (i) receiver coordinates (gx, gy, and gelev keywords) always specify trace location , that is, the location at which values are sampled in space-time, and (ii) on input, traces are regarded as point sources, so that each trace multiplies a discrete spatial delta (hence values are scaled by the reciprocal grid cell volume). Both of these design choices stem from the migration (adjoint modeling) and inversion uses of IWAVE, discussed for example in (Symes, 2014; Symes et al., 2011).

Source traces must be modified to conform to this rubric. The sftowed_array application relieves the user of the necessity to manually adjust the headers of an SU file containing source traces. It accepts three arguments: (i) an input source source file containing gx, gy, and gelev values representing source trace location relative to a source center location - the source coordinates of source traces are ignored; (ii) a data file whose sx, sy, and selev values are the source center locations to be used - its receiver coordinates are ignored, and (iii) an output file (name), to which output source traces will be written, each with source coordinates equal to those of a data trace, and receiver coordinates equal to the sums of the source trace receiver coordinates and the data trace source coordinates. The result is a collection of source coordinate gathers with the same source coordinates as the data file, but within each gather the same receiver coordinates relative to the source coordinates as the source file. Thus the source array is translated to each of the source centers specified in the data file. Because the source file may contain arbitrarily many traces with arbitrary relative locations, any source radiation pattern may be approximated (Santosa and Symes, 2000).

The example scripts in the project subdirectory use Madagascar commands to create these prototype trace files.

One of IWAVE's design criteria is that acquisition geometry parameters should have no a priori relation to the computational grid geometry: source and receiver locations may be specified anywhere in Euclidean space.

Acoustic Staggered Grid Modeling in IWAVE