The Acoustics Toolbox

The Acoustics Toolbox is a collection of acoustic models and related software for studying sound propagation in an ocean waveguide. Actually, the models have been structured to be suitable for general wave propagation problems; however, the ocean application is our main focus.

The acoustic models in the package are:

• KRAKEN normal mode approach
• SCOOTER spectral integral (also know as wavenumber integration or the reflectivity method
• BOUNCE calculation of a reflection coefficient for a stack of layers
• BELLHOP Gaussian beam tracing and ray tracing code
• SPARC A spectral integral code that operates directly in the time domain.

There are generally no limits on the dimensions that can be handled (up to virtual memory). The code uses dynamic allocation for virtually all arrays. There are a few exceptions. You will generally get a flag if for some reason any dynamic memory allocation fails or if you have exceeded an intrinsic limit in the code.

The documentation uses a common Fortran or Matlab syntax where a ( 1 : 5 ) represents a vector ( 1, 2, 3, 4, 5 ). The convention on model input is that such vectors are defined by first reading a line with the number of elements in the vector. Then the vector itself is read in. However, in reading the vector one can optionally provide just the first and last elements followed by a '/'. Thus, after specifying 5 elements, the vector (1:5) can be read is as '1 5 /'

For option letters in the various models, you will often see that there is a default. For instance, BELLHOP defaults to a point source in cylindrical coordinates, but you can explicitly select a point source ('R') or a line source ('X'). If you just want to go with the default, then simply put in a blank space for that position.

The following modules are part of the package.

Group I: Mode Computations:

• KRAKEN    Solves for the modes and writes them to disk. Elastic media are allowed but material attenuation in an elastic medium is ignored.
• KRAKENC   A version of KRAKEN which finds the eigenvalues in the complex plane.  KRAKEN uses perturbation theory to obtain imaginary parts of the eigenvalues while KRAKENC computes the complex eigenvalues exactly.  KRAKENC runs about 3 times slower but is necessary for leaky mode computations or for including material attenuation in elastic media.  Internally KRAKENC replaces elastic layers by an equivalent reflection coefficent. For this reason, you cannot use KRAKENC to look at fields within the elastic layers.
• KRAKEL    Analogous to KRAKENC but also computes elastic displacements and stresses for elastic media. KRAKEL is seldom used and tends to not be kept up-to-date.

Group II: Basic Plotting Routines:

•   PLOTSSP   Plots the sound speed profile.
•   PLOTMODE  Plots selected modes.
•   PLOTGRN   Plots the Green's funtion for the depth separated wave equation for a particular source/receiver combination.
•   PLOTTRI   Plots the triangular elements used for 3-D field calculations.

Group III: Field Computations:

•   FIELD     Computes fields on a vertical array over a specified range and for a series of source depths. Individual phones in the array may be displaced from the vertical. Range dependence is handled by either adiabatic or one-way coupled mode theory.
•   FIELD3D   Computes field for a three-dimensionally varying SSP using adiabatic mode theory.

Group IV: Plotting Routines that use Group III Program Output:

•   PLOTSHD      Plots tranmission loss in plan or elevation, i.e. an (x,y) plot or an (r,z) plot.
•   PLOTRAYXY    Plots the ray paths of the Gaussian beams generated during 3D field calculations.

The various programs for computing fields (GROUP III) are only needed for PLOTSHD, or for special user programs (e.g. ambiguity surfaces).

The following extensions are used with these programs:

•   .F90        The Fortran90/95 source code
•   .HLP        A HeLP file documenting the module
•   .BAT        A BATch file which runs the module

All user input in all modules is read using list-directed I/O. Thus data can be typed in free-format using space, tabs, commas or slashes as delimeters. Character input should be enclosed in single quotes like this: 'CHARACTER INPUT'. You will see the '/' character in a number of the input files. This terminates an input line causing the program to use default values.

Directory Structure

• AT:      This is the Acoustics Toolbox directory which contains command files for running KRAKEN and other models in the toolbox.
• Bellhop: Bellhop and Bellhop3D beam tracing models
  
• doc:     html files with brief notes about how to run the models
• Krakel:  A version of KRAKEN that provides the displacement field in elastic media. It does not presently include attenuation and is of limited practical use.
• Kraken:  Kraken and Krakenc normal mode codes
• KrakenField: Routines that sum the Kraken normal modes to produce acoustic fields. Includes options for range-independent, range-dependent, and 3D fields.
• Matlab:  Includes routines for plotting the results of all the models, as well as Matlab equivalents of some of the Fortran models.
• misc:    Miscellaneous subroutines (root-finders, linear equation solvers, etc.) used by the various models.
• Scooter: Includes the Scooter wavenumber integration model and the Sparc time-domain version.
• tests:   A huge battery of test cases used to exercise and demonstrate the various model capabilities.
• tslib:   Miscellaneous subroutines specifically related to timeseries manipulations.