Input and output files

Bellhop input files (with extension *.env) are required to be compatible with Kraken (a normal mode model) input files. Thus some of the parameters are not used to perform the ray tracing. The general structure of the *.env input file used by Bellhop is as follows:

TITLE 
Frequency (in Hz)
nmedia    (dummy integer < 20)
OPTIONS1
SURFACE-LINE  
nmesh sigmas z(nssp)       |
z(1) cp(1) /               |
z(2) cp(2) /               |  Sound
 .    .                    |  Speed
 .    .                    |  Block
 .    .                    |
z(nssp) cp(nssp) /        _|_
OPTIONS2 sigmab            |  Bottom 
BOTTOM-LINE               _|_ Block 
nsources     (number of sources)                     |
source-depth(1) source-depth(nsources)     / (in m)  |
nrd          (number of receivers x depth)           |  Array
receiver-depth(1) receiver-depth(nrd)      / (in m)  |  Block
nrr          (number of receivers x range)           |
receiver-range(1) receiver-range(nrr)      / (in km)_|_
OPTIONS3                                             |
nbeams       (number of launching angles)            |  Output
theta(1) theta(nbeams) (launching angles in degrees) |  Block
ray-step  zmax  rmax                                _|_
OPTIONS4 epmult rloop isingl                         |  Beam
nimage ibwin component                              _|_ Block

OPTIONS1 is a five-character string enclosed in single quotes. Here it follows the description of each character:

• OPTIONS1(1): describes the method of interpolation used by Bellhop to calculate sound speed and its derivatives along the ray. This character can correspond to one of the following:
  • 'S': cubic spline interpolation;
  • 'C': C-linear interpolation;
  • 'N': N2-linear interpolation;
  • 'A': analytic interpolation (requires adaptation of the subroutine SSP and further model recompilation);
  • 'Q': quadratic approximation to the sound speed field (requires the creation of a *.ssp file containing the field).
• OPTIONS1(2): describes the type of surface and can correspond to one of the following:
  • 'V': vacuum above surface (the SURFACE-LINE is not required);
  • 'R': perfectly rigid media above surface (the SURFACE-LINE is not required);
  • 'A': acoustic half-space; SURFACE-LINE should be written as z-surface cp-surface cs-surface density-surface alpha-surface /
  • 'F': read a list of reflection coefficients from a *irc file (requires running first the bounce program).
• OPTIONS1(3): describes attenuation in the bottom (for more details see [5]) and can correspond to one of the following:
  • 'F': attenuation units correspond to (dB/m)kHz;
  • 'L': attenuation units correspond to the parameter loss;
  • 'M': attenuation units correspond to dB/m;
  • 'N': attenuation units correspond to Nepers/m;
  • 'Q': attenuation units correspond to Q-factor;
  • 'W': attenuation units correspond to dB/wavelength.
• OPTIONS1(4): optional parameter describing Thorpe volume attenuation in the watercolumn; if set it should correspond to 'T'.
• OPTIONS1(5): optional parameter describing the surface shape; if not specified the surface is considered flat, if specified it should correspond to '*'. In the former case the surface coordinates should be described in a *.ati file, with the following structure:

  interpolation type
  npoints 
  r(1)	   z(1)
  r(2)	   z(2)
   .          .
   .          .
   .          .
  r(npoints) z(npoints)
  

  The parameter interpolation type is a character, equal to 'L' (for a linear interpolation of the surface) or 'C' (for curvilinear interpolation); surface ranges should be specified in km, surface depths in m.

The parameters nmesh and sigmas are not used by Bellhop, while the parameter z(nssp) is used to detect the last point of the sound speed profile. The values of z() and cp() correspond to depth in m and P-wave speed in m/s.

OPTIONS2 is a two-character string enclosed in single quotes. Here it follows the description of each character:

• OPTIONS2(1): describes the type of media below the watercolumn and it can correspond to one of the following:
  • 'V': vacuum below watercolumn (the BOTTOM-LINE is not required);
  • 'R': rigid below watercolumn (the BOTTOM-LINE is not required);
  • 'A': acoustic half-space; the BOTTOM-LINE should be written as z-bottom cp-bottom cs-bottom density-bottom alpha-bottom / for obvious reasons z-bottom should be equal to z(nssp); cs(bottom) is ignored, density(bottom) should be specified in g/cm$^3$ and the units of alpha(bottom) depend on OPTIONS1(3).
  • 'F': read a list of reflection coefficients from a *.brc file (requires running first the bounce program).
• OPTIONS2(2): describes the shape of the bottom. It can be empty (which corresponds to a flat bottom) or it can correspond to '*'. In the former case the bottom coordinates should be described in a *.bty file, with the following structure:

  interpolation type
  npoints 
  r(1)	   z(1)
  r(2)	   z(2)
   .          .
   .          .
   .          .
  r(npoints) z(npoints)
  

  again interpolation type can be equal to 'L' or 'C'; bottom ranges should be specified in km, bottom depths in m.

  The following six lines describe the number of sources and corresponding depths (in m), and the number of receivers along range and depth. Those lines are self-describing.

OPTIONS3 is a five-character string, which describes output options. Here it follows the description of each character:

• OPTIONS3(1): describes the type of information that should be written to the output file. It can correspond to
  • 'A': write amplitudes and travel times;
  • 'E': write eigenray coordinates;
  • 'R': write ray coordinates;
  • 'C': write coherent acoustic pressure;
  • 'I': write incoherent acoustic pressure;
  • 'S': write semi-coherent acoustic pressure.
• OPTIONS3(2): describes the approximation used to calculate acoustic pressure; it can be empty or it can correspond to one of the following:
  • 'G': use geometric beams (default);
  • 'C': use Cartesian beams;
  • 'R': use ray-centered beams;
  • 'B': use Gaussian beam bundles.
• OPTIONS3(3): selects the inclusion of the beam shift effect; it can be empty or it can correspond to one of the following:
  • ' ': do not include beam shift effect (default);
  • 'S': include beam shift effect;
  • '*': use a source beam pattern file (requires a *.sbp file, similar to the *.ati and *.bty files, with angles in degrees and amplitudes, instead of ranges and depths).
• OPTIONS3(4): describes the type of source; it can be empty or it can correspond to one of the following:
  • 'R': point source in cylindrical coordinates (default);
  • 'X': line source in Cartesian coordinates.
• OPTIONS3(5): describes the type of array; it can be empty or it can correspond to one of the following:
  • 'R': rectilinear receiver grid, receivers at rr( : ) $\times$ rd( : ) (default);
  • 'I': irregular grid, receivers at rr( : ) , rd( : ).

  The integer nbeams indicates the number of launching angles and the pair or reals theta(1) and theta(nbeams) determine the first and last launching angles, in degrees. Launching angles directed towards the bottom are considered positive, while launching angles directed towards the surface are considered negative. The parameters ray-step (in m), zmax (in m) and rmax (in km) define the ray step $ds$ used in the integration of the ray and dynamic equations, and the ``box'' dimensions used to stop the tracing of rays leaving the box.

  When the parameter OPTIONS3 is composed of a single character there is no need to include more lines in the *.env input file. Otherwise the model expects two additional lines, which contain additional information regarding the beam characteristics. In those two lines one can find the OPTIONS4 parameter, which is a string composed of two characters. Here it follows the description of each character:

• OPTIONS4(1): describes the type of beam and it can correspond to one of the following:
  • 'C': Cerveny type;
  • 'F': space-filling;
  • 'M': minimum width;
  • 'W': WKB beams.
• OPTIONS4(2): describes the type of beam curvature and it can correspond to one of the following:
  • 'D': use curvature doubling;
  • 'S': use standard curvature;
  • 'Z': use zeroing curvature.

  The parameters epmult and rloop should be positive reals, while isingl, nimage and ibwin should be integers. The integer nimage can take the values 1, 2 or 3. Component is a single character, which is used only when the acoustic pressure is calculated using ray-centered coordinates (when OPTIONS3(2) = 'R'); it can be empty (acoustic pressure will be written to the output file), equal to 'H' (write the horizontal component of pressure to the output file) or equal to 'V' (write the vertical component of pressure to the output file).