Description of Environmental File

The following can be repeated as many times as wanted in a single ENVFIL. KRAKEN and KRAKENC will generate a separate MODFIL for each case stopping when it detects an end-of-file.

(1) - Title

(2) - Frequency

(3) - Number of Media

The problem is divided into media within which it is assumed that the material properties vary smoothly. A new medium should be used at fluid/elastic interfaces or at interfaces where the density changes discontinuously. The number of media in the problem is defined excluding the upper and lower half-space.

BELLHOP is limited to one medium (NMEDIA=1) and actually ignores this parameter.

(4) - Top Option

'C' for C-linear,
'N' for N2-linear (n the index of refraction),
'P' for PCHIP (Piecewise Cubic Hermite Interpolating Polynomial),
'S' for cubic Spline,
'Q' for Quadrilatteral 2D SSP (BELLHOP   only; reads the SSP from a file)
'H' for Hexahedral     3D SSP (BELLHOP3D only; reads the SSP from a file)
'A' for Analytic.
    The user must modify the analytic formulas in ANALYT.FOR then re-compile and link.

If your not sure which option to take, I'd suggest you use 'C'. The 'N' option is virtually identical to 'C'. It's provided to facilitate precise inter-model comparisons with codes that use a certain numerical technique that requires that type of interpolation. Both these piecewise-linear approximations can produce false caustics in BELLHOP; however, the Gaussian beam option in BELLHOP mitigates that effect to some degree.

Option 'S' is a little dangerous because splines yield a poor fit to certain kinds of curves, e.g. curves with sharp bends. If you insist on splines, you can fix a bad fit by dividing the water column into two 'media' at the bend.

Option 'P' is a recently added option that is intended to provide a smooth interpolation without the artifacts that sometimes come with cubic splines. We will need to get some more experience with this, but the expectation is that this will often be the best choice for BELLHOP by providing a smoother profile free of false caustics.

If 'A' is selected, then only the first line of block (5) for the SSP is used and the tabulated SSP itself is omitted.

Run PLOTSSP to check that the SSP looks the way you thought it should. Apart from potential typos, this will also show up fit-problems.

'V' VACUUM above top
'A' ACOUSTO-ELASTIC half-space.
Requires another line with the halfspace parameters as described in block (4a).
'R' Perfectly RIGID
'F' Reflection coefficient from a FILE

These files for complicated, multi-layered media can be generated using BOUNCE. (Available in KRAKENC, SCOOTER, and BELLHOP. Not available in KRAKEN and SPARC.) For a Top Reflection Coefficient, the file should have the extension '.TRC'. For KRAKEN/KRAKENC this option for tabulated reflection coefficients is somewhat experimental at this time. A complicated reflection coefficient may well cause problems for the mode-finder. Finally, a reflection coefficient tabulated only for real angles does not provide a good result for complex angles of incidence. This happens when the sediment sound speed is less than the water sound speed. In that case, the modes are evanescent in the upper part of the water column and therefore have a complex angle of incidence.

For open ocean problems option 'V' should be used for the top BC.

'N' Nepers/m.
'F' dB/(kmHz)       (F as in Freq. dependent)
'M' dB/m            (M as in per Meter)
'm' dB/m            (m as in per Meter) Scaled with frequency; quadratically, then linearly above fT
'W' dB/wavelength   (W as in per Wavelength)
'Q' quality factor
'L' Loss parameter (a.k.a. loss tangent)

KRAKEN ignores material attenuation in elastic media. (KRAKENC treats it properly).
The option 'm' for attenuation is a new one designed to capture a power-law frequency dependence. You provide an attenuation in dB/m at the frequency specified above (FREQ). Then in a broadband run, with multiple frequencies that attenuation as automatically scaled according to the power that you specify.

The power-law scaling is based on the frequency to a power beta, up to a transition frequency, fT. Above fT, the scaling is linear with frequency. The parameters that control this are specified in the first line of block (5) and block (6) and allow a different beta and fT to be specified independently for every layer. The actual attenuation in dB/m is the value at the reference frequency given in block (2) above.

If you use 'm' without doing a broadband run, then 'M' and 'm' will do the same thing, i.e. interpret your attenuation as dB/m at the given frequency.

'T' Thorp attenuation formula.
'F' Francois-Garrison formula (more accurate).
'B' Biological layer (fish).

If you invoke this option, volume attenuation is added to the explicitly specified attenuation (ap, as).
The Francois-Garrison formula depends on salinity (S), temperature (T), pH, and depth (z_bar). That information is then provided on the line immediately following, e.g.:
19.3 33.5 7.5 4000.7 ! T, Salinity, pH, z_bar

'~' Read in a *.ati file containing the top altimetry. (BELLHOP only; '*' was used earlier and still works)
'_' Flat surface, i.e. no altimetry file. (BELLHOP only; this is the default if blank)
'.' As in: I want all the modes and I don't care how long it takes. Period.

The '.' option works only with KRAKENC, which sometimes has trouble finding a complete set of modes in the complex plane.

TOPOPT(6:6): Single beam (BELLHOP only)

'I' Calculate only a single beam from the specified fan.
The actual beam number is specified after NBEAMS, under
the section describing the beam fan.
' ' Default: trace all beams

Broadband run (currently implemented in KRAKEN and SCOOTER)

'B' Select a broadband run where multiple frequencies are specified.
The actual frequencies are given as a vector in the last two lines of the envfil using the standard format:

2 ! Nfreq
50 500 / ! freqVec( 1 : Nfreq )

TOPOPT(7:7): Use 0 (zero) to disable stabilizing attenuation in SCOOTER

(4a) - Top Halfspace Properties

ZT: Depth (m).
CPT: Top P-wave speed (m/s).
CST: Top S-wave speed (m/s).
RHOT: Top density (g/cm3).
APT: Top P-wave attenuation. (units as given by Option(3:3) )
AST: Top S-wave attenuation. ( " " " " " " )

This line should only be included if TOPOPT(2:2)='A', i.e. if the user has specified a homogeneous halfspace for the top BC.

(4b) - Biological Layer Parameters (for attenuation due to fish)

NBioLayers Z1(1) Z2(1) f0(1) Q(1) a0(1)
Z1(2) Z2(2) f0(2) Q(2) a0(2) . . . Z1(NBioLayers) Z2(NBioLayers) f0(NBioLayers) Q(NBioLayers) a0(NBioLayers)

        z1: Top    of layer (m)
        z2: Bottom of layer (m)
        f0: Resonance frequency (Hz)
        Q: Quality factor
        a0: Amplitude in dB/km at resonance but scaled by Q^2

The loss becomes a = a0 / [ ( 1 - f0^2 / freq^2 )^2 + 1 / Q^2 ] dB / km (formula suggested by Orest Diachok).
The units here in dB/km are not affected by the attenuation units selected in TopOpt( 3 : 3 ).

(5) - Sound Speed Profile

NMESH SIGMA Z(NSSP) Z(1) CP(1) CS(1) RHO(1) AP(1) AS(1) Z(2) CP(2) CS(2) RHO(2) AP(2) AS(2) . . . Z(NSSP) CP(NSSP) CS(NSSP) RHO(NSSP) AP(NSSP) AS(NSSP)

The number of mesh points should be about 10 per vertical wavelength in acoustic media. In elastic media, the number needed can vary quite a bit; 20 per wavelength is a reasonable starting point. For elastic media, the wavelength associated with the shear wave speed is the reference; this is always shorter than that for the p-wave.

The number of mesh points used depends on the initial mesh and the number of times it is refined (doubled). The number of mesh doublings can vary from 1 to 5 depending on the parameter RMAX described below.

If you type 0 for the number of mesh points, the code will calculate NMESH automatically.

Z(NSSP): Depth at bottom of medium (m).
This value is used to detect the last SSP point when reading in the profile that follows/

Z(): Depth (m).
The surface starts at the first depth point specified. Thus if you have say, XBT data which starts at 50 m below the surface, then you'll need to put in some SSP point at 0 m, otherwise the free-surface would be placed at 50 m giving erroneous results. The points Z(1) and Z(NSSP) MUST correspond to the depths of interfaces between media.

If the attenuation units were specified with option letter 'm' and a broadband run is selected, then the attenuation is scaled with frequency. The scaling is based on the frequency to a power beta, up to a transition frequency, fT. Above fT, the scaling is linear with frequency. The parameters that control this are specified in the first line of this block using the syntax:

CP():    P-wave speed (m/s).
CS():    S-wave speed (m/s).
RHO():   Density (g/cm3).
   Density variations within an acoustic medium are at present ignored.

AP(): P-wave attenuation (units as given in Block 2)
AS(): S-wave attenuation ( " " " " " ")

These lines giving the SSP should be omitted when the 'A' option is used (indicating that an analytic profile is supplied by a user written subroutine).

The '/' character signals that the remaining data on the line is the same as in the previous line of SSP data. For the very first line the default or 'previous' line is:

Only KRAKEN, SCOOTER, and BOUNCE can use the shear wave information. SPARC and BELLHOP ignore it.

(6) - Bottom Option

'V' VACUUM below bottom.
'A' ACOUSTO-ELASTIC half-space.
Requires another line with the half-space parameters as described in Block (6a).

'R' Perfectly RIGID.
'G' Grain size
'F' Reflection coefficient from a FILE

These files for complicated, multi-layered media can be generated using BOUNCE. (Available in KRAKENC, SCOOTER, and BELLHOP. Not available in KRAKEN and SPARC.) For a Bottom Reflection Coefficient, the file should have the extension '.BRC'. For KRAKEN/KRAKENC this option for tabulated reflection coefficients is somewhat experimental at this time. A complicated reflection coefficient may well cause problems for the mode-finder. Finally, a reflection coefficient tabulated only for real angles does not provide a good result for complex angles of incidence. This happens when the sediment sound speed is less than the water sound speed. In that case, the modes are evanescent in the upper part of the water column and therefore have a complex angle of incidence.

'P' Precaculated internal reflection coefficient from a FILE (available in KRAKENC and SCOOTER, not KRAKEN).
These files are generated using BOUNCE.

BOTOPT(2:2):
'~' Read in a *.bty file containing the bottom bathymetry. (BELLHOP only; '*' was used earlier and still works)
'_' Flat surface, i.e. no bathymetry file. (BELLHOP only; this is the default if blank)

(6a) - Bottom Halfspace Properties from geoacoustic values

ZB: Depth (m).
CPB: Bottom P-wave speed (m/s).
CSB: Bottom S-wave speed (m/s).
RHOB: Bottom density (g/cm3).
APB: Bottom P-wave attenuation. (units as given by TOPOPT(3:3) )
ASB: Bottom S-wave attenuation. ( " " " " " " )

This line should only be included if BOTOPT(1:1)='A', i.e. if the user has specified a homogeneous halfspace for the bottom BC.

These lines should be contained in a separate '.BRC' file. This file is only required if BOTOPT(2:2)='F', i.e. if the user has specified that the bottom BC is read from a '.BRC' (Bottom Reflection Coefficient) file.

For KRAKEN/KRAKENC this option for tabulated reflection coefficients is somewhat experimental at this time. A complicated reflection coefficient may well cause problems for the mode-finder. Finally, a reflection coefficient tabulated only for real angles does not provide a good result for complex angles of incidence. This happens when the sediment sound speed is less than the water sound speed. In that case, the modes are evanescent in the upper part of the water column and therefore have a complex angle of incidence.

(6b) - Bottom Halfspace Properties from grain size

ZB: Depth (m).
MZ: Grain size (phi units).

This line should only be included if BOTOPT(1:1)='G', i.e. if the user has specified a homogeneous halfspace for the bottom BC defined by grain size. The bottom sound speed, attenuation, and density is calculated using formulas from the UW_APL High-Frequency handbook.

Description of Environmental File

1. Title

2. Frequency

3. Number of Media

4. Top Option

Top Halfspace Properties

Top Reflection Coefficient

5. Sound Speed Profile

6. Bottom Option

Bottom Halfspace Properties

Bottom Reflection Coefficient