The following methods should be defined for MyPropagationModel:
acoustic_field
The acoustic field is represented by complex numbers with amplitude that is related to the source level (spl) and transmission loss, and angle that is related to the acoustic phase at the source frequency.
Additional options
The acoustic_field(), transmission_loss(), arrivals() and impulse_response() methods may support propagation model specific keyword arguments (options) to control finer details of the propagation model.
A transmission_loss() method may be optionally defined for MyPropagationModel:
transmission_loss(pm, tx, rxs)
Compute the transmission loss from the source tx to the receivers rxs using propagation model pm. If rxs denotes a single receiver, the result is a scalar. If rxs is an AbstractArray, the result is an array of transmission losses (in dB) with the same shape as rxs.
If it is not defined, the transmission loss is automatically computed as 20 * log10(acoustic_field(...)).
A propagation model should also typically define:
arrivals(pm, tx, rx; paths=true)
Compute the arrivals at the receiver rx due to the source tx using propagation model pm. Returns an array of arrivals.
The eigenray paths are typically included in the arrivals. However, if they are not needed, one may set paths=false to allow the propagation model to avoid computing them.
The returned arrivals should be an array of arrivals that extend:
AbstractAcousticArrival
Superclass for all acoustic arrivals.
The information held in an arrival is propagation model dependent. For example, ray models may return arrivals that contain ray information such as time of arrival, angle of arrival, amplitude and phase of arrival, eigenpath, etc. On the other hand, models based on normal modes may return arrivals containing mode information such as mode number, horizontal and vertical wavenumber, etc. For ray and mode arrivals, the following concrete subtypes should be used when possible:
RayArrival
Type representing a single acoustic ray arrival.
Properties:
t / time: arrival time (s)
ϕ / phasor: complex amplitude
ns / surface_bounces: number of surface bounces
nb / bottom_bounces: number of bottom bounces
θₛ / launch_angle: launch angle at source (rad)
θᵣ / arrival_angle: arrival angle at receiver (rad)
path: ray path (optional, vector of 3-tuples or missing)
The properties are accessible with the short names for brevity, and longer more descriptive names where readability is desired or unicode symbols are undesired.
ModeArrival
Type representing a single acoustic mode arrival.
Properties:
m / mode: mode number
kᵣ / hwavenumber: horizontal wavenumber (rad/m)
ψ(z) / mode_function: mode function
v / group_velocity: group velocity (m/s)
The properties are accessible with the short names for brevity, and longer more descriptive names where readability is desired or unicode symbols are undesired.
Some propagation models may be able to generate an impulse response. If so, they should define:
Compute the impulse response at the receiver rx due to the source tx using propagation model pm at the given sampling frequency fs. If abstime is true, the result is in absolute time from the start of transmission. Otherwise, the result is relative to the earliest arrival time of the signal at the receiver (possibly with some guard period to accommodate acausal response). ntaps specifies the number of taps in the impulse response. If not specified, the number of taps is chosen automatically based on the arrival times.
If defined, the impulse response may be used to generate a channel model automatically (by calling channel()).
Channel model
If a propagation model can estimate a received signal from a transmit signal without having to compute an impulse response and convolve it, it may wish to implement the channel modeling API directly:
channel(pm, txs, rxs, fs; noise=nothing)
Compute a channel model from the sources txs to the receivers rxs using propagation model pm. The result is a channel model with the same number of input channels as the number of sources and output channels as the number of receivers. The channel model accepts signals sampled at rate fs and returns signals sampled at the same rate.
An additive noise model may be optionally specified as noise. If specified, it is used to corrupt the received signals.
Simulate the transmission of passband signal x through the channel model ch. If txs is specified, it specifies the indices of the sources active in the simulation. The number of sources must match the number of channels in the input signal. If rxs is specified, it specifies the indices of the receivers active in the simulation. Returns the received signal at the specified (or all) receivers.
fs specifies the sampling rate of the input signal. The output signal is sampled at the same rate. If fs is not specified but x is a SampledSignal, the sampling rate of x is used. Otherwise, the signal is assumed to be sampled at the channel’s sampling rate.
If abstime is true, the returned signals begin at the start of transmission. Otherwise, the result is relative to the earliest arrival time of the signal at any receiver. If noisy is true and the channel has a noise model associated with it, the received signal is corrupted by additive noise.
In some cases (e.g. channel replay techniques), a channel model may be defined without the need to derive it from a propagation model. In such a case, one may extend UnderwaterAcoustics.jl by directly defining the channel model.