rimLG_readme.txt, Nov. 22nd 2015, Richard B. Evans, North Stonington, CT

 run_rimLG.m is a Matlab script that runs the computational function
rimLG and computes the range independent modal (rim) acoustic field 
using the Legendre-Galerkin method. The method is described in the
document Legendre_Galerkin.pdf.

 To run rimLG, type run_rimLG at the Matlab prompt in the directory 
containing rimLG and the other supporting files. The generic input file 
is rimLG.dat.

 run_rimLG invokes the Matlab editor so that the user can make changes to
rimLG.dat for the desired calculation. rimLG.dat contains the parameters
defining the modal calculation. These include: frequency(Hz), source 
depth(m), receiver depths(m), receiver ranges(km) and tables of 
environmental parameter. These units are dep(m), svp(m/s), dbpwl(dB/wave
length) and rho(gm/cm^3).  There are two tables: one for the water and one
for the bottom sediment, with NW and NB points in each. It is necessary 
that depw(NW)=depb(1) where the density usually has a discontinuity. The 
first entry depw(1)=0 is the free surface. The last entry depb(NB) 
determines the total thickness of the waveguide and is also a free surface. 
An absorbing layer is usually used at the bottom of the sediment. See the 
following example:

 Here is an annotated excerpt from rimLG.dat. See the full rimLG.dat that 
comes with the code for other examples, with gradients. % Matlab does not 
allow inline annotations so the part of rimLG.dat, read by Matlab, can not
contain the ! annotations.

Jensen-Kuperman, 200 m, NL=50  !Case name
25.0   100.0                   !Frequency(Hz) Source Depth (m)
10                             !NL,# of Legendre polynomials
2   30.0    120.0              !NDEP,# of Receiver depths and interval(m)
0.01   4.01   .01              !Receiver range interval and increment(km)
2  3                           !NW in water, NB in sediment
0.0      1500.0   .0    1.00   !depw,svpw,dbpwlw,rhow (1:NW)
200.0    1500.0   .0    1.00
200.0    1700.0   .5    1.50   !depb,svpb,dbpwlb,rhob (1:NB)
1000.0   1700.0   .5    1.50
1500.0   1700.0  2.5    1.50

Any changes to rimLG.dat should be saved in the editor to reflect the 
parameters of the desired calculation. The Matlab window is paused for
the editing. 

 On returning to the Matlab window and after answering a few 'y' or 'n'
questions, the calculation proceeds. When the calculation is finished
a transmission loss curve is plotted, for a representative receiver depth.
The resulting Matlab plot can be viewed by loading the file JK_200.fig.
 
 run_rimLG also writes a generic transmission loss file rimLG.tl 
containing all the receiver depths. The complex acoustic pressure field 
is also returned by rimLG and could be used in other calculations.

List of files:

rimLG.dat: Input data file for rimLG
rimLG.tl: Output transmission loss file from rimLG
run_rimLG.m: Matlab script that reads rimLG.dat and calls rimLG.m to 
             compute the acoustic field

rimLG.m: Main computational function that calls table_gen, abmat, 
         csrt, basic_depth_fct and the Matlab function 'eig'

table_gen.m: Generates tables of complex index of refraction
csrt.m: Complex square root with a positive imaginary part
abmat.m: Generates matrices A and B by calling 'legpts' and 'legpoly'
legpts.m: Generates quadrature points and weights for Gauss-Legendre
          integration from Chebfun
legpoly.m: Evaluates Legendre polynomials and their derivatives by
           Zoltan Csati
basic_depth_fct.m: Evaluates functions in the Legendre polynomial
                   spanning set at depth Z