\section{OASI: Environmental Inversion}

The OASES-OASI module is very similar to OASN, modeling the seismo-acoustic field on arbitrary
3-dimensional arrays of hydrophones and geophones in the presence of
surface noise sources and discrete signal sources. This module is used
to model the propagation of surface-generated ambient noise and for
providing simulated array responses as well as signal replicas for
matched field environmental inversion using  OASES-MFP. OASI and MFP
were used to generate the inversion and resolution results shown in
 Fig.\,4 of Ref.\cite{Saclant94}. 

\subsection{Input Files for OASI}

\begin{table}
\begin{center}
\small
\begin{tabular}{|l|l|c|c|}
\hline \hline
Input parameter & Description & Units & Limits \\
\hline \hline
\multicolumn{4}{|l|}{\bf Block I: TITLE}  \\ \hline
TITLE & Title of run  & - & $\leq$ 80 ch. \\
\hline
\multicolumn{4}{|l|}{\bf Block II: OPTIONS}  \\ \hline
A B C $\cdots$ & Output and computational options & - & $\leq$ 40 ch. \\
\hline
\multicolumn{4}{|l|}{\bf Block III: FREQUENCIES}  \\ \hline
FREQ1, FREQ2, NFREQ, COFF & FREQ1: Minimum frequency & Hz & $>0$ \\
 	& FREQ2: Maximum frequency & Hz & $>0$ \\
        & NFREQ: Number of frequencies & & $>0$ \\
 	& COFF: Integration contour offset & dB/$\Lambda$ & $\geq 0$ \\
\hline
\multicolumn{4}{|l|}{\bf Block IV: ENVIRONMENT}  \\ \hline
NL 	& Number of layers, incl. halfspaces	& - & $\geq 2$  \\
D,CC,CS,AC,AS,RO,RG,CL & D: Depth of interface. & m &  \\
.	& CC: Compressional speed & m/s & $\geq 0$ \\
.	& CS: Shear speed & m/s &  \\
.	& AC: Compressional attenuation & dB/$\Lambda$ & $\geq 0$ \\
.	& AS: Shear attenuation & dB/$\Lambda$ & $\geq 0$ \\
	& RO: Density 	& g/cm$^{3}$ & $\geq 0$ \\
	& RG: RMS of interface roughness & m &  \\
	& CL: Correlation length of roughness & m & $>0$ \\
\hline
\multicolumn{4}{|l|}{\bf Block V: RECEIVER ARRAY}  \\ \hline
NRCV & NRCV: Number of receivers in array & - & $>0$ \\
Z,X,Y,ITYP,GAIN & Z: Receiver depth & m & \\
.	& X: x-offset of receiver & m & \\ 
.	& Y: y-offset of receiver & m & \\
.	& ITYP: Receiver type  & - & $>0$ \\
	& GAIN: Receiver signal gain & dB & \\ 
\hline
\multicolumn{4}{|l|}{\bf Block VI: NOISE SOURCES}  \\ \hline
SSLEV,WNLEV,DSLEV,NDNS & SSLEV: Surface noise source strength & dB & \\
	& WNLEV: White noise level & dB & \\
	& DSLEV: Deep source level & dB & \\
	& NDNS: Number of discrete sources & & \\
\hline
\end{tabular}
\end{center}
\caption{OASI input file structure, mandatory components: Environment, 
Array geometry and Sources.
 \label{tab:oasiI} }
\end{table} 

\begin{table}
\begin{center}
\small
\begin{tabular}{|l|l|c|c|}
\hline \hline
Input parameter & Description & Units & Limits \\
\hline \hline
\multicolumn{4}{|l|}{\bf Block VII: SEA SURFACE NOISE (SSLEV $\neq$ 0)}  \\ 
\hline
CMINS,CMAXS & Phase velocity interval, {\em surface noise} & & \\ 
	& CMINS: Minimum phase velocity & m/s & $>0$ \\
	& CMAXS: Maximum phase velocity & m/s & $>0$ \\
NWSC,NWSD,NWSE & Wavenumber sampling, {\em surface noise} & & \\
	& NWSC: Samples in {\em continuous} spectrum &  &  \\
	& NWSD: Samples in {\em discrete} spectrum &  &  \\
	& NWSE: Samples in {\em evanescent} spectrum &  &  \\
\hline
\multicolumn{4}{|l|}{\bf Block VIII: DEEP NOISE SOURCES (DSLEV $\neq$ 0)}  \\ 
\hline
DPSD 	& DPSD: Depth of {\em deep} source sheet & & \\
CMIND,CMAXD & Phase velocity interval, {\em deep} sources & & \\ 
	& CMIND: Minimum phase velocity & m/s & $>0$ \\
	& CMAXD: Maximum phase velocity & m/s & $>0$ \\
NWDC,NWDD,NWDE & Wavenumber sampling, {\em deep} sources & & \\
	& NWDC: Samples in {\em continuous} spectrum &  &  \\
	& NWDD: Samples in {\em discrete} spectrum &  &  \\
	& NWDE: Samples in {\em evanescent} spectrum &  &  \\
\hline
\multicolumn{4}{|l|}{\bf Block IX: DISCRETE SOURCES (NDNS $>$ 0)}  \\ 
\hline
ZDN,XDN,YDN,DNLEV & ZDN: Depth of {\em discrete} source & m & \\
:	& XDN: x-offset of discrete source & km & \\ 
:	& YDN: y-offset of discrete source & km & \\
	& DNLEV: Source level of discrete source & dB & \\
CMIN,CMAX & Phase velocity interval, {\em discrete} sources & & \\ 
	& CMIN: Minimum phase velocity & m/s & $>0$ \\
	& CMAX: Maximum phase velocity & m/s & $>0$ \\
NW,IC1,IC2 & NW: Wavenumber sampling, {\em discrete} sources & - &   \\
	& IC1: First sampling point & - & $\geq 1$ \\
	& IC2: Last sampling point & - & $\leq$NW \\
\hline
\multicolumn{4}{|l|}{\bf Block X: SIGNAL REPLICAS (Option R)}  \\ 
\hline
ZSR,XSR,YSR,SRLEV & ZSR: Depth of replica source & m & \\
	& XSR: x-offset of replica source & km & \\ 
	& YSR: y-offset of replica source & km & \\
	& SRLEV: Source level of replicasource & dB & \\
LY1,PA1,VMIN1,VMAX1,NV1 & Replica parameter 1  &  & \\ 
LY2,PA2,VMIN2,VMAX2,NV2 & Replica parameter 2  &  & \\ 
CMINR,CMAXR & Phase velocity interval, {\em replicas} & & \\ 
	& CMINR: Minimum phase velocity & m/s & $>0$ \\
	& CMAXR: Maximum phase velocity & m/s & $>0$ \\
NWR,ICR1,ICR2 & NWR: Wavenumber sampling, {\em replicas} & - &   \\
	& ICR1: First sampling point & - & $\geq 1$ \\
	& ICR2: Last sampling point & - & $\leq$NWR \\
\hline
\end{tabular}
\end{center}
\caption{OASI input file structure, optional components: 
Computational parameters.
 \label{tab:oasiII} }
\end{table} 

The input file for oasi is structured in 10 blocks, of which most are
identical to the format for OASN. The first 6 blocks,
shown in Table~\ref{tab:oasiI},contain data which must always
be given, such as the  frequency selection, the environment and
receiver array. The last 4 blocks
should only be included for certain options and parameter settings, as
indicated in Table~\ref{tab:oasiII}. The various blocks and the
significance of the data is described in the following.

\subsubsection{Block I: Title of Run}

Title to appear on graphics output.

\subsubsection{Block II: Computational options}

Similarly to the other modules, the output is controlled by a number
of one-letter options:
\begin{itemize}
\item[C] Produces a contour plot of the spatial spectrum of the
surface generated ambient noise vs. frequency and horizontal slowness.
This
option overrides option {\bf K}.
\item[F] Produces a curve plot of the noise level in dB vs frequency for each
sensor in the receiving array.
\item[J] Applies a complex integration contour with offset given in
Block III for all wavenumber integrations.
\item[K] Creates a plot of the wavenumber spectrum of the surface
generated ambient noise for each individual frequency.
\item[N] Outputs the noise covariance matrices to a direct access
file with extension \tt .xsm \rm. The file format is described
below. Note that a discrete source must be specified corresponding to
the replica source.
\item[P] Produces plots of noise intensity vs. receiver number for
each selected frequency.
\item[R] Outputs the array replicas to a 
file with extension \tt .rpo \rm. The file format is described below.
\item[T] Produces a transfer function file with extension \tt .trf \rm 
for the selected array and 
one discrete source. Only allowed for \tt NDNS = 1 \rm. 
For file format see \tt OASP \rm. The ranges for the receivers in the 
\tt .trf \rm file are not the true ones, but simply the receiver numbers.
To plot all traces together use {\em range stacking} in \tt PP \rm.
\item[Z] Produces a plot of the sound speed profiles in the standard
format.
    \item[{\bf b}] Solves the depth-separated wave equation with the
lowermost  interface condition expressed in terms of a complex
reflection coefficient. The reflection coefficient must be tabulated in a input file \tt input.trc \rm
which may either be produced from experimental data or by the
reflection coefficient module OASR as described on
Page\,\pageref{trc-form}. See also there for the file format.
The lower halfspace must be specified as vacuum and the last layer as
an isovelocity fluid without sources for this option. Add dummy layer
if necessary. Further, the
frequency sampling must be consistent. 
Using \tt OASR \rm this is optained by using
the same minimum and maximum frequencies, and number of frequencies, but without option \tt C \rm.
Note: Care should be taken using this option with a complex
integration contour, option \tt J \rm. The tabulated reflection
coefficient must clearly correspond to the same imaginary wavenumber
components for \tt OASI \rm to yield proper results. \tt OASR \rm calculates
the reflection coefficient for real horizontal wavenumbers.
\item[{\bf c}] This option - unique to OASI - generates plots of the
    eigenvectors of the Cramer-Rao bounds over the selected replica
    space, to be plotted by mplot. If multiple frequencies are
    specified, option 'c' will generate bounds for both coherent and
    incoherent wideband processing.
    \item[{\bf t}] Solves the depth-separated wave equation with the
top  interface condition expressed in terms of a complex
reflection coefficient. The reflection coefficient must be tabulated in a input file \tt input.trc \rm
which may either be produced from experimental data or by the
reflection coefficient module \tt OASR \rm as described on
Page\,\pageref{trc-form}. See also there for the file format.
The upper halfspace must be specified as vacuum and the first layer as
an isovelocity fluid without sources for this option. Add dummy layer
if necessary. Further, the
frequency sampling must be consistent. 
Using \tt OASR \rm this is optained by using the same minimum and 
maximum frequencies, and number of frequencies, but without option \tt C \rm.
Note: Care should be taken using this option with a complex
integration contour, option \tt J \rm. The tabulated reflection
coefficient must clearly correspond to the same imaginary wavenumber
components for \tt OASI \rm to yield proper results. \tt OASR \rm calculates
the reflection coefficient for real horizontal wavenumbers.
\item[\#] A digit (1--9) identifying the order of the surface source
correllation. The default is totally uncorrelated sources.
Higher numbers yield more vertical directionality.
\end{itemize}

\subsubsection{Block III: Frequency Selection}

This block controls the frequency sampling. Covariance matrices,
replicas and graphics will be produced for \tt NFREQ \rm frequencies
equidistantly sampled between \tt FREQ1 \rm and \tt FREQ2 \rm. \tt
COFF \rm is the wavenumber integration offset in DB/$\lambda$ and only
has significance for option {\bf J}. Option {\bf J} and \tt COFF = 0
\rm will invoke the default integartion offset.
 
\subsubsection{Block IV: Environmental Data }

The environmental data are specified in the standard SAFARI format.

\subsubsection{Block V: Receiver Array}

OASI will compute the noise and signal field on arbitrary
three dimensional arrays. The first line of this block specifies the
number of sensors. Then follows the position, type and gain for each
sensor in the array. The the sensor positions are specified in
cartesian coordinates \underline{in meters}. The types currently
implemented are as follows

\begin{enumerate}
\item Hydrophone. Normal stress $ \sigma_{zz}$ (negative of pressure in
water) in Pa for source level 1 Pa (or $\mu$Pa for source level 1 $\mu$Pa). 
\item Geophone. Particle velocity $\dot{u}$ in $x$-direction
(horizontal).  Unit is
m/s for source level 1 Pa (or $\mu$m/s for source level 1 $\mu$Pa).
\item Geophone. Particle velocity $\dot{v}$ in $y$-direction
(horizontal).  Unit is
m/s for source level 1 Pa (or $\mu$m/s for source level 1 $\mu$Pa).
\item Geophone. Particle velocity $\dot{w}$ in $z$-direction
(vertical, positive downwards).  Unit is
m/s for source level 1 Pa (or $\mu$m/s for source level 1 $\mu$Pa).
\end{enumerate}

The gain is a calibration factor in dB which is applied to
ambient noise and signal on all sensors. {\em Note that the gain is not
applied to the white noise!} When combining hydrophones and geophones
in array processing it is important to note that there is a  difference in
order of magnitude of pressure and particle velocity of the order of
the acoustic impedance. Therefore the geophone sensors should usually
have a gain which is of the order 120 dB higher than the gain applied to the
hydrophone sensors.

\subsubsection{Block VI: Noise and Signal Sources}

OASI treats 4 types of noise and signal sources simultaneously,
depending on the value of the parameters in this block:

\begin{description}
\item[SSLEV] Strength in dB of sea surface noise sources. Per
definition the source strength corresponds to the acoustic pressure
the same source distribution would yield in an infinitely deep ocean
\cite{jkps,sk:jasa88}.
The value of \tt SSLEV \rm is interpreted in two different ways,
depending on its sign:
\begin{itemize}
\item[SSLEV$\ge0$:] Level in dB of white surface source spectrum.
\item[SSLEV$<0$:] A negative value identifies a logical unit for a file
containing the frequency dependence of the surface source level. The format of
the source level files is described in Section~\ref{sec:slevf}.
\end{itemize}
\item[WNLEV] Level of white noise on sensor in dB. Note that the white
noise is added after the sensor gain.
\item[DSLEV] To allow for more horizontal directionality of the noise
field than predicted by the surface noise model, an additional, deeper
sheet of sources can be introduced.
\item[NDNS] This parameter specifies the number of discrete sources present
(targets or interferers).
\end{description}

\subsubsection{Block VII: Surface Noise Parameters}

This block contains the wavenumber sampling parameters for computing the
noise covariance matrix. The parameters \tt CMINS \rm and \tt CMAXS
\rm are the phase phase velocities defining the wavenumber integration
interval. Note here that the continuous spectrum is always important
for surface noise. Therefore \tt CMAXS \rm must be specified to a
large number (e.g. $10^8$) to include the steep propagation angles.
\tt CMINS \rm should be chosen small enough to include all important
evanescent components. 

Similar to OASN, the wavenumber sampling parameters \tt NWSC, NWSD \rm and \tt NWSE \rm are
interpreted in two different ways by OASI, depending of the
value specified for \tt NWSD \rm:

\begin{description}
\item[NWSD $< 10$] The wavenumber sampling parameters are given in the standard
SAFARI format, with the parameters interpreted as follows:
	\begin{itemize}
	\item[NWSC] Total number of wavenumber samples, distributed
		equidistantly between $k_{min} = \omega / c_{max} $ and 
		$k_{max} = \omega / c_{min} $.
	\item[NWSD] Sampling point where the kernel computation starts. The
		kernel will be Hermite extrapolated. In
		this  format NWSD will usually be set to 1 since the
		steep  angles are always important. 
	\item[NWSE] Sampling point where the kernel computation ends. The
		kernel will be Hermite extrapolated.
	\end{itemize} 
\underline{NOTE:} The sampling parameters must be specified in this format for options {\bf K} and {\bf C}, which require equidistant sampling.
\item[NWSD $\ge 10$] The wavenumber sampling parameters are given
individually for each of the three spectral regimes. This allows for a
much denser sampling in the discrete spectrum without forcing a dense sampling
of the smooth kernel in the other regimes. 
	\begin{itemize}
	\item[NWSC] Number of wavenumber wavenumber samples distributed
		equidistantly over the {\em continuous spectrum} 
		between $k_{min} = \omega / c_{max} $ and
		the critical wavenumber $k_c$ corresponding to the 
		compressional speed in the sub-bottom. 
	\item[NWSD] Number of wavenumber wavenumber samples distributed
		equidistantly over the {\em discrete spectrum} 
		between the critical wavenumber $k_c$ corresponding to the 
		compressional speed in the sub-bottom and the
		wavenumber $k_w$ corresponding to the minimum sound
		speed in the water column.  
	\item[NWSE] Number of wavenumber wavenumber samples distributed
		equidistantly over the {\em evanescent spectrum} 
		between the
		wavenumber $k_w$ corresponding to the minimum sound
		speed in the water column and $k_{max} = \omega / c_{min} $.  
	\end{itemize} 
\end{description}

\subsubsection{Block VIII: Deep Noise Source Parameters}

The parameter \tt DPSD \rm is the depth of the deep noise source
sheet. The other parameters in this block are specified in a format
identical to that described above for the surface sources.

\subsubsection{Block IX: Discrete Noise and Signal Sources}

If \tt NDNS\rm$>0$, then this block should first contain the
coordinates and source level for each discrete source. Note that the
depth is specified first in {\em meters}, followed by the $x$- and
$y$-ranges in {\em kilometer} (in contrast to the array element
coordinates which were all given in meters).

The source levels \tt DNLEV \rm are interpreted in two different ways,
dependent on whether specified value is positive or negative:

\begin{description}
\item[DNLEV$\ge0$:] Level in dB of white source spectrum.
\item[DNLEV$<0$:] A negative value identifies a logical unit of a file
containing the frequency dependence of the source level. The format of
the source level files is described in Section~\ref{sec:slevf}.
\end{description}

The wavenumber sampling parameters for the discrete sources should
follow in the standard OASES format. In Version 2.2 automatic sampling
is supported, and activated by NW=-1. In this case Ic1 and IC2 are
insignificant. As is the case for automatic sampling in all OASES
modules, the desired phase velocity interval must be specified
manually. The kernel tapering invoked by the automatic sampling will
be initiated at the specified phase velocities.

   
\subsubsection{Block X: Signal Replica Parameters}

The first three lines of this block defines the sampling of the
environmental parameters for replicas and resolution bounds. This
block is the only one that differs from the OASN format. The first
line specifies the source coordinates and level used for generating
the environmental replicas, in the same format used for the discrete
sources in Block IX.

The next two lines identifies the environmental parameters searched,
and specifies the sampling:

\begin{description}
\item[LY1:] Layer number for parameter 1.
\item[PA1:] Parameter number (1: depth, 2: Cp, 3: Cs, 4: Ap, 5: As, 6:
Rho)
\item[VMIN1:] Minimum value of parameter 1
\item[VMAX1:] Minimum value of parameter 1
\item[NV1:] Number of samples in parameter 1
\end{description}



The wavenumber sampling parameters for the replica sources should
follow in the standard OASES format. In Version 2.2 automatic sampling
is supported, and activated by NW=-1. In this case IC1 and IC2 are
insignificant. As is the case for automatic sampling in all OASES
modules, the desired phase velocity interval must be specified
manually. The kernel tapering invoked by the automatic sampling will
be initiated at the specified phase velocities.


\subsubsection{Examples}
\label{sec:oasiex}

The following OASI input file \tt nrlcr.dat \rm produces the
covariance matrix and replicas, and Cramer-rao bounds shown in
Ref.\,\cite{Saclant94}.

\small
\begin{verbatim}
Workshop case. nl=50 dB, sl=120 dB.
N J 1 R c  
100 100 1 0
4
0 0 0 0 0 0 0
0 1500 0 0 0 1 0
102.5 1600 -1750 0.35 0. 1.75 0
200 1750 0 0.35 0. 1.75 0

15
10 0 0 1 0
15 0 0 1 0
20 0 0 1 0
25 0 0 1 0
30 0 0 1 0
35 0 0 1 0
40 0 0 1 0
45 0 0 1 0
50 0 0 1 0
55 0 0 1 0
60 0 0 1 0
65 0 0 1 0
70 0 0 1 0
75 0 0 1 0
80 0 0 1 0

0 50 0 1
50 1 0 120
1400 1e8
-1 1 480                        # Automatic sampling


50 1 0 120             		# source coordinates
3 2 1550 1650 11		# seabed speed
4 2 1700 1800 11	        # subbottom speed

1400 1e8
-1 1 480

\end{verbatim}
\normalsize

\subsection{Execution of OASI}

    As  for the other OASES modules,  filenames  are  passed  to OASI   via 
environmental parameters. In Unix systems a typical command  file 
{\bf oasi} (in  \$HOME/Oases/bin) is:

\small
\begin{verbatim}
    #                            the number sign invokes the C-shell 
    setenv FOR001 $1.dat       # input file 
    setenv FOR019 $1.plp       # plot parameter file
    setenv FOR020 $1.plt       # plot data file  
    setenv FOR023 $1.trc       # reflection coefficient table (input)
    setenv FOR028 $1.cdr       # contour plot parameter file 
    setenv FOR029 $1.bdr       # contour plot data file 
    setenv FOR014 $1.rpo       # signal replicas
    setenv FOR016 $1.xsm       # covariance matrices
    oasi2_bin                  # executable
\end{verbatim}
\normalsize

    After preparing a data file with the name {\bf input.dat}, OASI  is 
executed by the command:

    {\bf oasi input}

\subsection{Graphics}  

    Command files are provided in a path directory for generating 
the graphics produced by oasi.

\noindent    To generate curve plots, issue the command:

    {\bf mplot input}

\noindent    To generate contour plots, issue the command:

    {\bf cplot input}


\subsection{Output Files}

In addition to the graphics output files, OASI optionally produces
files containing the computed covariance matrices and replica fields
for use by the array processing module OASES-MFP, similar to those
produced by OASN, and described in Sec.\,\ref{sec:cova} (Page\,\pageref{sec:cova}), and \ref{sec:repl} (Page\,\pageref{sec:repl}).




