GUI Wrapper:

ACT: Matlab front-end for the Acoustic Toolbox written by Alec Duncan from the Centre for Marine Science and Technology at Curtin University.

See also at/Matlab/Menumaster for another GUI.

Which version should I download?

There is only one version of the source code; however, you may see options for different pre-compiled binaries. If you're using another machine or operating systems you'll need to recompile it which requires a Fortran95 compiler. (Fortran 90 and 95 are almost identical so you should be able to get it to work under f90.)

atWinPII_f95. Version for a Windows, Pentium II machine. The Makefiles are in a sort of Unix style. If you download cygwin (publicly available on the web) you get a sort of pseudo-Unix window in which you can just type 'make all' and 'make install' to recompile and install.
atLinuxPII_f95. Same as above but with binaries compiled under Linux.
atOSXintel. For the Mac. Compiled with gfortran. You need to have gfortran installed (which is very easy) to have access to a certain dynamically linked library.

Overview

The Acoustic ToolBox includes four acoustic models:

BELLHOP: A beam/ray trace code

KRAKEN: A normal mode code

SCOOTER: A finite element FFP code

SPARC: A time domain FFP code

A common input structure has been used throughout so that only minor modifications are needed to switch from one program to another.

All the models produce `shade' files that can be processed using a common set of plotting routines to plot transmission loss vs. range or vs. range and depth.

Porting the code

Record length

Fortran compilers differ in whether record lengths should be declared as bytes or words. To ensure the programs run, I declare lengths in bytes. If your compiler uses words as the default, look for a compiler switch to override that so that your files are not unnecessarily large.

Some of the programs in this package use direct access I/O and need to know a record length. Many systems do not maintain this information as part of the file info so the code writes that information directly into the file. Then the file is opened twice. First it is opened with a dummy record length to read the actual record length from the file. Then it is re-opened with the correct record length. On machines that do know the correct record length, that first open may generate an error message and will have to be removed. The RECL specifier should then also be removed from the second open.

Ice Scatter module

The Twersky-scatter option is problematic because it calls mathieu.f and slbessel.f which don't adhere to a rigorous Fortran standard. To avoid this problem, the current distribution has this option disabled.

If you want to put it back in, you will need to link to twersk.f instead of twerskfuse.f. These routines call mathieu.f which needs to be compiled with a switch to initialize all variables to zero. Most compilers have some such switch.

Plotting:

Plot packages come and go. However, the output formats of the various models are all fairly simple to work with. The distribution includes Matlab scripts which I currently use for plotting. If you don’t have Matlab, then these will at least provide an example of how to read the file formats.

If you use Matlab and prefer a GUI, check out at/matlab/menumaster.

Installation Notes

On PC's you should add the following to your autoexec.bat to make the scripts executables in your default path:

SET PATH=%PATH%;C:\AT\SCRIPTS;C:\AT\BIN

Obviously these lines should be updated to reflect whichever directory you installed things in. You may need to reboot to make sure this takes effect. Under Windows 2000 (and presumably NT) set the path by right clicking the “My Computer” icon and selecting “Properties”, “advanced”. Under Windows XP, go to control panel/Performance and Maintenance/System/Advanced and look for the pushbutton labled “Environment Variables”. There you can edit the system variable “Path”.

A common problem people have with the installation is getting things properly in the search path. The scripts must be in the path. The scripts in turn call the executables and they too must therefore be in the search path. If you’re having problems, verify your path includes these by typing “path” from a DOS window. Pay attention also to the order of scripts and bin in the path. Typically you run KRAKEN by typing something like “kraken pekeris”. DOS first needs to find kraken.bat and run that script. If \bin is first in your path, DOS will find kraken.exe and run that instead. You can run kraken.exe directly without using the kraken.bat script but the way you’d do that is slightly different, as follows (and this is another good check to do). Type

cd c:\at\bin

kraken.exe < ..\tests\pekeris.env

Again, the cd statement above should reflect whichever directory you installed things in.

If this doesn’t work, I can’t imagine what your problem is. Assuming it does work, then you just need to resolve an error in setting up your path.

Once you have the basic code working, you might want to run some of the test batteries in at/tests to completely verify your installation. (This is mainly for your own peace of mind, since I run these tests before exporting the code and it would be quite strange if you didn’t get virtually identical results on another PC.) The m-file, plottests.m there is a good way to do that.

On Unix/Linux/MacOSX systems you can ensure that path info is set in Matlab at start up by editing .../bin/matlab to add something like:

source ~/.profile

where .profile is the shell start up script that initializes your path.

Warranty

The sale of this product is `as is' and without any express warranties. Liability, if any, is limited to refund of purchase price only upon return of product and package to manufacturer.

Updates

(Check also the individual subdirectories for updates on individual components of the Acoustics Toolbox.)

December 1997

Minor changes have been made to the package for improved f77 to f90 portability. Fortran 90 seems to treat parameters differently in terms of precision so some of those changes are important for the most accurate results.

July 1999

The whole package has been converted to f90/95 standard with free-format lines and taking advantage of dynamic allocation. The code is more concise and portable. Dynamic allocation means that you will not have to worry about dimensional limits--- the size of the problem you can solve is limited only by RAM on your system.

The change to dynamic allocation has forced a small change in the input structure. Previously an input format was often used with a number of items in a vector followed by the actual vector. For instance, the vector of receiver depths is read this way.

In the new version the number of items in the vector must appear on a separate line so that the code can read it, allocate the space, and then read the vector contents.

May 2009

The Matlab version of BELLHOP has been replaced by a new version that traces one beam at a time. The ealier version traced all the beams in parallel for efficiency; however, the logic is too complicated to maintain.

Frequently Asked Questions

Why do I get an end-of-file in reading the very last line of the envfil?

You left off a carriage return/line feed after the last line, or other appropriate end-of-line marker for your system.

Why do I get a segmentation violation?

You ran a case that required an outrageous amount of storage. The code is supposed to catch all such cases by detecting an error in the allocation of dynamic variables (or limits for the few arrays with fixed dimensions). However, we see cases where the compiler simply does not handle huge arrays properly.