Propagation & channel modeling
API reference
Environment models
Create a generic underwater environment with the given parameters. The following parameters are supported:
bathymetry
= bathymetry modelaltimetry
= altimetry modeltemperature
= temperature modelsalinity
= salinity modelsoundspeed
= sound speed profile modeldensity
= density modelseabed
= seabed sediment modelsurface
= surface model
All parameters are optional and have default values. Parameters may be modified after construction by setting the corresponding property in the environment.
Propagation models
A fast differentiable mode propagation model that only supports iso-velocity constant depth environments.
ngrid
is the number of grid points to use for modal root finding for fluid bottom environments. If ngrid
is too small, the mode solver may miss some modes. If ngrid
is too large, the mode solver may take a long time to converge. The default value of ngrid
of 0 will use a heuristic to automatically determine the number of grid points to use.
Type representing a single acoustic ray arrival.
Properties:
t
/time
: arrival time (s)ϕ
/phasor
: complex amplitudens
/surface_bounces
: number of surface bouncesnb
/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.
Type representing a single acoustic mode arrival.
Properties:
m
/mode
: mode numberkᵣ
/hwavenumber
: horizontal wavenumber (rad/m)ψ(z)
/mode_function
: mode functionv
/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.
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.
Compute the acoustic field at the receivers rxs
due to the source tx
using propagation model pm
. If rxs
denotes a single receiver, the result is a complex scalar. If rxs
is an AbstractArray
, the result is an array of complex numbers with the same shape as rxs
. The amplitude of the field is related to the transmission loss, and the angle is related to the acoustic phase at the source frequency.
Compute the acoustic field at a receiver rxs
due to a transmitter tx
in the Pekeris waveguide. The field is computed incoherently if mode=:incoherent
. Otherwise, the field is computed coherently.
Compute the acoustic field at a receiver rxs
due to a transmitter tx
in the Pekeris waveguide. The field can be computed incoherently if mode=:incoherent
. Otherwise, the field is computed coherently.
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.
Channel models and simulation
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.
BasebandReplayChannel(h, θ, fs, fc, step=1; noise=nothing)
BasebandReplayChannel(h, fs, fc, step=1; noise=nothing)
Construct a baseband replay channel with impulse responses h
and phase estimates θ
. The phase estimates are optional. fs
is the sampling frequency in Sa/s, fc
is the carrier frequency in Hz, and step
is the decimation rate for the time axis of h
. The effective sampling frequency of the impulse responses is fs ÷ step
impulse responses per second.
An additive noise model may be optionally specified as noise
. If specified, it is used to corrupt the received signals.
Load a baseband replay channel from a file.
If upsample
is true
, the impulse responses are upsampled to the delay axis sampling rate. This makes applying the channel faster but requires more memory. rxs
controls which receivers to load from the file. By default, all receivers are loaded.
An additive noise model may be optionally specified as noise
. If specified, it is used to corrupt the received signals.
Supported formats:
.mat
(MATLAB) file in underwater acoustic channel repository (UACR) format. See https://github.com/uwa-channels/ for details.
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.
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.
If start
is specified, it specifies the starting time index in the replay channel. If not specified, a random start time is chosen.
Boundary conditions
reflection_coef(bc::AbstractAcousticBoundary, frequency, θ)
reflection_coef(bc::AbstractAcousticBoundary, frequency, θ, ρ, c)
Compute the complex reflection coefficient at a fluid-fluid boundary of type bc
at incidence angle θ
and frequency
. The density and sound speed in the water are given by ρ
and c
, respectively.
Pre-defined boundary conditions based on APL-UW Technical Report 9407:
# sea surface boundary conditions
const SeaState0 = WindySurface(0.8)
const SeaState1 = WindySurface(2.6)
const SeaState2 = WindySurface(4.4)
const SeaState3 = WindySurface(6.9)
const SeaState4 = WindySurface(9.8)
const SeaState5 = WindySurface(12.6)
const SeaState6 = WindySurface(19.3)
const SeaState7 = WindySurface(26.5)
const SeaState8 = WindySurface(30.6)
const SeaState9 = WindySurface(32.9)
# seabed boundary conditions
const Rock = FluidBoundary(2557.5, 3820.0, 0.01374)
const Pebbles = FluidBoundary(2557.5, 2750.4, 0.01374)
const SandyGravel = FluidBoundary(2547.8, 2041.6, 0.01705)
const CoarseSand = FluidBoundary(2282.3, 1911.1, 0.01638)
const MediumSand = FluidBoundary(1886.8, 1799.5, 0.01624)
const FineSand = FluidBoundary(1483.5, 1690.7, 0.01602)
const VeryFineSand = FluidBoundary(1297.8, 1613.4, 0.01875)
const ClayeySand = FluidBoundary(1251.0, 1581.3, 0.02019)
const CoarseSilt = FluidBoundary(1222.1, 1553.3, 0.02158)
const SandySilt = FluidBoundary(1195.0, 1525.9, 0.01261)
const Silt = FluidBoundary(1175.1, 1508.1, 0.00386)
const FineSilt = FluidBoundary(1173.8, 1506.3, 0.00306)
const SandyClay = FluidBoundary(1172.5, 1504.6, 0.00242)
const SiltyClay = FluidBoundary(1171.2, 1501.7, 0.00163)
const Clay = FluidBoundary(1169.8, 1498.4, 0.00148)
Sources and receivers
AcousticSource(pos, frequency; spl=0)
AcousticSource(x, z, frequency; spl=0)
AcousticSource(x, y, z, frequency; spl=0)
An source at location pos
with nominal frequency
and source level spl
(dB re 1 µPa @ 1 m). The source is assumed to be omnidirectional and well approximated by a point source. While the source may have some bandwidth, the nominal frequency is used to estimate propagation effects such as absorption, reflection coefficients, etc.
If the location of the source is unknown, it may be specified as nothing
. This is useful when the propagation model does not require the source location (e.g., data-driven models).
Noise models
rand([rng::AbstractRNG, ] noise::AbstractNoiseModel, nsamples; fs)
rand([rng::AbstractRNG, ] noise::AbstractNoiseModel, nsamples, nchannels; fs)
Generate random noise samples from the noise model noise
with the specified size nsamples
(can be a 2-tuple for multichannel noise). The noise is returned as a signal sampled at fs
. The optional rng
argument specifies the random number generator to use.