Propagation modeling API

Model database

Core interfaces

UnderwaterAcoustics.altitudeFunction
altitude(alt::Altimetry, x, y)

Get water surface altitude at location (x, y). The nominal water surface is considered to have an altitude of zero. However, the water surface may not be flat, and the Altimetry provisions for variations of altitude around the nominal altitutde of zero.

source
UnderwaterAcoustics.arrivalsFunction
arrivals(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver)

Compute the arrivals from tx1 to rx1. Returns an array of Arrival structs.

source
UnderwaterAcoustics.channelmatrixFunction
channelmatrix(rec::Recorder, fs, ntaps=0; tx=1, rx=1, approx=false)
channelmatrix(rec::Vector{<:Arrival}, fs, ntaps=0; approx=false)

Generate a sampled channel matrix at a sampling rate of fs Hz. If ntaps is zero, the number of taps of the channel matrix are chosen automatically.

If approx is true, a fast algorithm is used to generate a sparse channel matrix that assigns an arrival to the nearest sampling time.

source
UnderwaterAcoustics.checkFunction
check(pm::Type{<:PropagationModel}, env::UnderwaterEnvironment)
check(pm::Type{<:PropagationModel}, env=missing)

Check if an propagation model is available, and can simulate the specified environment. Returns the environment if it can be simulated, or throws an error with a descriptive error message if it cannot be simulated.

This function is internally used by the propagation modeling toolbox to choose a model or offer a selection of models to the user.

source
UnderwaterAcoustics.eigenraysFunction
eigenrays(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver)

Compute the eigenrays from tx1 to rx1. Returns an array of RayArrival structs.

source
UnderwaterAcoustics.impulseresponseFunction
impulseresponse(arrivals, fs)
impulseresponse(arrivals, fs, ntaps; reltime, approx)

Convert a vector of arrivals to a sampled impulse response time series at a sampling rate of fs Hz. If ntaps is zero, the number of taps of the impulse response are chosen automatically.

If reltime is true, the impulse response start time is relative to the first arrival, otherwise it is relative to the absolute time. If approx is true, a fast algorithm is used to generate a sparse impulse response that assigns an arrival to the nearest sampling time.

source
UnderwaterAcoustics.locationFunction
location(src::AcousticSource)
location(src::AcousticReceiver)

Get the location of an acoustic source or receiver as a 3-tuple (x, y, z).

source
UnderwaterAcoustics.phasorFunction
nominalfrequency(src::AcousticSource)

Get the complex phasor representation (amplitude & phase) of a narrowband acoustic source at the nominal frequency.

source
UnderwaterAcoustics.raysFunction
rays(pm::PropagationModel, tx1::AcousticSource, θ::Real, rmax)

Compute the rays from tx1 launched at angle θ (or all angles in θ, if it is a vector). Returns an array of RayArrival datatypes. rmax is the maximum horizontal range in meters to track the rays over.

source
UnderwaterAcoustics.recordFunction
record(src::AcousticSource, duration, fs; start=0.0)
record(noise::NoiseModel, duration, fs; start=0.0)
record(model::PropagationModel, tx, rx, duration, fs; start=0.0)
record(model::PropagationModel, tx, rx, sig; reltime=true)

Make a recording of an acoustic source or ambient noise. The start time and duration are specified in seconds, and the recording is made at a sampling rate of fs Hz.

For an recording of an acoustic source, free space propagation is assumed, and the recording is made at a nominal range of 1 meter from the acoustic center of the source.

For a recording through a propagation model, tx and rx may be single AcousticSource and AcousticReceiver, or an array each. The returned signal is always complex, irrespective of whether the source is real or complex.

When a sig is specified, the sources are assumed to transmit the sampled signal in sig. The number of channels in sig must match the number of sources. The returned signal is the same type as the input signal (real or complex). If reltime is true, the recorded signal starts at the first arrival, otherwise it starts at the beginning of the transmission.

source
UnderwaterAcoustics.recorderFunction
recorder(model::PropagationModel, tx, rx)

Create a recorder function that may be called later to make an acoustic recording of sources in tx at receviers rx. tx and rx may be single AcousticSource and AcousticReceiver, or an array each.

The recorder function may be called later with duration, fs, and optionally a start time. Alternatively, the recorder function may also be called with a sampled signal. It functions in a similar way as the record() function.

Examples:

julia> rec = recorder(pm, tx, rx);
julia> s = rec(1.0, 44100.0; start=0.0);  # make a recording of 1 second at 44.1 kHz
julia> s = rec(signal(randn(44100), 44100));  # transmit a random 1 second signal
source
UnderwaterAcoustics.soundspeedFunction
soundspeed(ssp::SoundSpeedProfile, x, y, z)

Get sound speed at location (x, y, z). If a sound speed profile is range independent, x and y may be ignored. z is generally negative, since the sea surface is the datum and z-axis points upwards.

source
UnderwaterAcoustics.sspFunction
ssp(env::UnderwaterEnvironment)::SoundSpeedProfile

Get the sound speed profile for the underwater environment.

source
UnderwaterAcoustics.transfercoefFunction
transfercoef(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver; mode=:coherent)
transfercoef(pm::PropagationModel, tx1::AcousticSource, rx::AbstractArray{<:AcousticReceiver}; mode=:coherent)

Compute the complex transfer coefficients from tx1 to rx1 or all receivers in rx. The mode may be :coherent or :incoherent.

source
UnderwaterAcoustics.transmissionlossFunction
transmissionloss(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver; mode=:coherent)
transmissionloss(pm::PropagationModel, tx1::AcousticSource, rx::AbstractArray{<:AcousticReceiver}; mode=:coherent)

Compute the transmission loss in dB from tx1 to rx1 or all receivers in rx. The mode may be :coherent or :incoherent.

source

Common models

UnderwaterAcoustics.AcousticReceiverGrid2DMethod
AcousticReceiverGrid2D(xmin, xstep, nx, zmin, zstep, nz)

Create a 2D Cartesian grid of omnidirectional acoustic receivers with nx × nz receviers starting (xmin, zmin) with step sizes xstep and zstep.

source
UnderwaterAcoustics.AcousticReceiverGrid3DMethod
AcousticReceiverGrid3D(
    xmin,
    xstep,
    nx,
    ymin,
    ystep,
    ny,
    zmin,
    zstep,
    nz
)

Create a 3D Cartesian grid of omnidirectional acoustic receivers with nx × ny × nz receviers starting (xmin, ymin, zmin) with step sizes xstep, ystep, and zstep.

source
UnderwaterAcoustics.AcousticSourceMethod
AcousticSource(x, y, z, f; sourcelevel, ϕ)

Create a narrowband acoustic source with frequency f Hz at location (x, y, z). The sourcelevel is in µPa @ 1m. A phase ϕ may be optionlly specified.

source
UnderwaterAcoustics.AcousticSourceMethod
AcousticSource(x, z, f; sourcelevel, ϕ)

Create a narrowband acoustic source with frequency f Hz at location (x, y, z). The sourcelevel is in µPa @ 1m. A phase ϕ may be optionlly specified.

source
UnderwaterAcoustics.IsoSSPType
struct IsoSSP{T} <: SoundSpeedProfile

Isovelocity sound speed profile.


IsoSSP(c)

Create an isovelocity sound speed profile with sound speed c.

source
UnderwaterAcoustics.NarrowbandAcousticSourceMethod
NarrowbandAcousticSource(x, y, z, f; sourcelevel, ϕ)

Create a narrowband acoustic source with frequency f Hz at location (x, y, z). The sourcelevel is in µPa @ 1m. A phase ϕ may be optionlly specified.

source
UnderwaterAcoustics.NarrowbandAcousticSourceMethod
NarrowbandAcousticSource(x, z, f; sourcelevel, ϕ)

Create a narrowband acoustic source with frequency f Hz at location (x, z). Thesourcelevelis in µPa @ 1m. A phaseϕ` may be optionlly specified.

source
UnderwaterAcoustics.PingerMethod
Pinger(x, y, z, f; sourcelevel, phase, duration, start, interval, window)

Create a pulsed narrowband acoustic source with frequency f Hz at location (x, y, z). Additional parameters that may be specified:

  • sourcelevel in µPa @ 1m (default 180 dB)
  • phase of the narrowband signal (default 0)
  • duration of the pulse in seconds (default 20 ms)
  • start time of one of the pulses in seconds (default 0)
  • pulse repetition interval in seconds (default 1 second)
  • window type (from DSP.jl) (default nothing)
source
UnderwaterAcoustics.PingerMethod
Pinger(x, z, f; sourcelevel, phase, duration, start, interval, window)

Create a pulsed narrowband acoustic source with frequency f Hz at location (x, z). Additional parameters that may be specified:

  • sourcelevel in µPa @ 1m (default 180 dB)
  • phase of the narrowband signal (default 0)
  • duration of the pulse in seconds (default 20 ms)
  • start time of one of the pulses in seconds (default 0)
  • pulse repetition interval in seconds (default 1 second)
  • window type (from DSP.jl) (default nothing)
source
UnderwaterAcoustics.RayleighReflectionCoefType
struct RayleighReflectionCoef{T1, T2, T3} <: ReflectionModel

Reflection model for a surface with a Rayleigh reflection coefficient.


RayleighReflectionCoef(ρᵣ, cᵣ, δ)
RayleighReflectionCoef(ρᵣ, cᵣ)

Create a reflection model for a surface with a Rayleigh reflection coefficient with relative density ρᵣ, relative sound speed cᵣ, and dimensionless attentuation δ. If attentuation δ is unspecified, it is assumed to be zero.

See reflectioncoef() for more details.

source
UnderwaterAcoustics.RedGaussianNoiseType
struct RedGaussianNoise{T} <: NoiseModel

Ambient noise model with Gaussian noise with a 1/f² power spectral density.


RedGaussianNoise(σ)

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

source
UnderwaterAcoustics.ReflectionCoefType
struct ReflectionCoef{T<:Number} <: ReflectionModel

Reflection model for a surface with a constant reflection coefficient.


ReflectionCoef(coef)

Create a reflection model for a surface with a constant reflection coefficient coef.

source
UnderwaterAcoustics.SampledAcousticSourceMethod
SampledAcousticSource(x, z, sig; fs, frequency)

Create a sampled acoustic source transmitting signal sig at location (x, z). The samples are assumed to be in µPa @ 1m from the source.

Additional parameters that may be specified:

  • fs is the sampling rate of signal sig
  • nominal frequency in Hz (nothing to auto-estimate)
source
UnderwaterAcoustics.SampledAcousticSourceMethod
SampledAcousticSource(x, y, z, sig; fs, frequency)

Create a sampled acoustic source transmitting signal sig at location (x, y, z). The samples are assumed to be in µPa @ 1m from the source.

Additional parameters that may be specified:

  • fs is the sampling rate of the signal sig
  • nominal frequency in Hz (nothing to auto-estimate)
source
UnderwaterAcoustics.SampledAltitudeMethod
SampledAltitude(x, altitude)
SampledAltitude(x, altitude, interp)

Create an altimetry given discrete altitude measurements at locations given in x. interp may be either :linear or :smooth, and defaults to :linear if unspecified.

source
UnderwaterAcoustics.SampledDepthMethod
SampledDepth(x, depth)
SampledDepth(x, depth, interp)

Create a bathymetry given discrete depth measurements at locations given in x. interp may be either :linear or :smooth, and defaults to :linear if unspecified.

source
UnderwaterAcoustics.SampledSSPMethod
SampledSSP(depth, c)
SampledSSP(depth, c, interp)
SampledSSP(range, depth, c)
SampledSSP(range, depth, c, interp)

Create a sound speed profile based on measurements at discrete depths. interp may be either :linear or :smooth, and defaults to :linear if unspecified. :smooth is currently only supported for range-independent sound speed profiles.

source
UnderwaterAcoustics.SurfaceLossType
struct SurfaceLoss{T} <: ReflectionModel

Reflection model for a water surface affected by wind.


SurfaceLoss(windspeed)

Create a reflection model for a surface affected by wind. windspeed is given in m/s.

source
UnderwaterAcoustics.WhiteGaussianNoiseType
struct WhiteGaussianNoise{T} <: NoiseModel

Ambient noise model with Gaussian noise with a flat power spectral density.


WhiteGaussianNoise(σ)

Create an white Gaussian ambient noise model with variance σ².

source

Propagation models

UnderwaterAcoustics.PekerisRayModelType
struct PekerisRayModel{T} <: PropagationModel{T}

A fast differentiable ray model that only supports isovelocity constant depth environments.


PekerisRayModel(env, rays)

Create a Pekeris ray propagation model with a maximum of rays ray arrivals.

source