Propagation & channel modeling

API reference

Environment models

UnderwaterEnvironment(; kwargs...)

Create a generic underwater environment with the given parameters. The following parameters are supported:

  • bathymetry = bathymetry model
  • altimetry = altimetry model
  • temperature = temperature model
  • salinity = salinity model
  • soundspeed = sound speed profile model
  • density = density model
  • seabed = seabed sediment model
  • surface = surface model

All parameters are optional and have default values. Parameters may be modified after construction by setting the corresponding property in the environment.

is_range_dependent(env)

Return true if any quantity (e.g. sound speed, bathymetry, etc) in the environment env depends on the horizontal location, and false otherwise.

is_isovelocity(env)

Return true if the sound speed in the environment env is a constant.

env_type(env)

Return the base number type for the environment. Typically, this is a Float64, but could differ if the environment was constructed using other number types.

Propagation models

models()
models(mtype::Type{<:AbstractPropagationModel})

Return a list of all available propagation models. If mtype is specified, return only models of that type.

models(env::UnderwaterEnvironment)

Return only models that are compatible with the environment env.

PekerisRayTracer(env; max_bounces=3)

A fast differentiable ray tracer that only supports iso-velocity constant depth environments. max_bounces is the number of surface/bottom bounces to consider in the ray tracing.

PekerisModeSolver(env; ngrid=0)

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.

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.

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.

acoustic_field(pm, tx, rxs)

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.

acoustic_field(pm::PekerisRayTracer, tx, rxs; mode=:coherent)

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.

acoustic_field(pm::PekerisModeSolver, tx, rxs; mode=:coherent)

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.

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.

impulse_response(pm, tx, rx, fs; abstime=false, ntaps=nothing)

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

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.

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.

BasebandReplayChannel(filename; upsample=false, rxs=:, noise=nothing)

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.
transmit(ch, x; txs=:, rxs=:, abstime=false, noisy=true, fs=nothing)

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.

transmit(ch::BasebandReplayChannel, x; rxs=:, abstime=false, noisy=true, fs=nothing, start=nothing)

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.

PressureReleaseBoundary

Pressure-release boundary condition.

RigidBoundary

Rigid boundary condition.

FluidBoundary(ρ, c, δ)

Create a fluid half-space boundary with density ρ, sound speed c, and dimensionless absorption coefficient δ.

WindySurface(windspeed)

Reflection model for a water surface affected by wind. windspeed is given in m/s.

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).

AcousticReceiver(pos)
AcousticReceiver(x, z)
AcousticReceiver(x, y, z)

Receiver at location pos.

AcousticReceiverGrid2D(xrange, zrange)

A 2D grid of receivers with the specified location ranges.

AcousticReceiverGrid3D(xrange, yrange, zrange)

A 3D grid of receivers with the specified location ranges.

location(tx::AbstractAcousticSource)
location(rx::AbstractAcousticReceiver)

Get the location of the source or receiver.

frequency(tx::AbstractAcousticSource)

Get the nominal frequency of an acoustic source.

spl(tx::AbstractAcousticSource)

Get the source level of an acoustic source.

Noise models

WhiteGaussianNoise(σ)
WhiteGaussianNoise(psd, fs)

Create a white Gaussian ambient noise model with variance σ² µPa² or with power spectral density psd µPa²/Hz and bandwidth fs/2 Hz.

RedGaussianNoise(σ)

Create an ambient noise model with variance σ² µPa² and 1/f² variation in power spectral density.

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.