Using IWAVE

Using IWAVE commands in other contexts

To use the acoustic modeling command outside of the scripted examples, the user needs to create a parameter list. The job parameters for the use case of the scripted examples are described in detail in Appendix A. The html documentation (Terentyev et al., 2012) describes other parameter choices, corresponding the wide variety of use cases accommodated by this application. Key parameters are pathnames to the model data files (velocity and density, or equivalent parameters) and to seismic trace files containing prototype output trace headers and (possibly) source pulse traces, and output traces on normal completion.

The acoustic application currently expect model data files in the RSF format of Madagascar (Fomel, 2009). The scripts use standardmodel to store gridded model data in RSF format, and 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. 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.

By convention, the dimension of the problem is that of the primary model grid, that associated with the bulk modulus data, if it is given, or failing that, the velocity. 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, or velocity, 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, the RSF header file should 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.

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. The current release accepts a SU (SEGY without reel header) format data file specified by the hdrfile keyword: the trace headers in this file are those of the output (pressure) traces. Units of length and time are m and ms respectively, consistent with other internal unit choices. The example scripts use SU or Madagascar commands to create these prototype trace files.

The source pulse may be specified as a Ricker wavelet, or read from another SU file, whose pathname is the value associated with the source keyword. Source calibrarion is regulated by several other keywords, as described in Appendix A. In the examples, the Ricker option is used, simply because it avoids some small incompatibilities between SU and Madagascar filter implementations which would otherwise prevent the standalone and Madagascar versions of the examples from generating the same pulses, and therefore prevent the results from matching precisely.

Because the number of parameters describing a simulation task is reasonably large (roughly 15 in a simple case), the job parameters for IWAVE's acoustic application are most conveniently stored in a file, passed to the application via a command line parameter. Denoting by $ASG either $TOP/asg/main/asg.x for the standalone implementation, or $RSFROOT/bin/sfasg for the Madagascar install, the proper command takes the form

[prefix] $ASG par=[parfile].

Here [prefix] is any necessary command prefix, eg. mpirun ..., and [parfile] is the pathname of the parameter file. On successful completion, the output data will be stored in a file (SU format) indicated by the key datafile in the parameter file.

Using IWAVE