addmodel!(mtype)

Register model in the list of available models.

models()
models(env::UnderwaterEnvironment)

List available models, optionally for a given environment.

altimetry(env::UnderwaterEnvironment)::Altimetry

Get the altimetry for the underwater environment.

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.

arrivals(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver)

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

bathymetry(env::UnderwaterEnvironment)::Bathymetry

Get the bathymetry for the underwater environment.

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.

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.

depth(bathy::Bathymetry, x, y)

Get water depth at location (x, y).

eigenrays(pm::PropagationModel, tx1::AcousticSource, rx1::AcousticReceiver)

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

environment(pm::PropagationModel)

Get the environment associated with the propagation model.

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.

location(src::AcousticSource)
location(src::AcousticReceiver)

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

maxdepth(bathy::Bathymetry)

Get the maximum water depth.

noise(env::UnderwaterEnvironment)::NoiseModel

Get the noise model for the underwater environment.

nominalfrequency(src::AcousticSource)

Get the nominal frequency of an acoustic source in Hz.

nominalfrequency(src::AcousticSource)

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

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.

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.

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

reflectioncoef(rm::ReflectionModel, f, θ)

Get complex reflection coefficient at frequency f Hz and incidence angle θ (w.r.t. the surface normal).

salinity(env::UnderwaterEnvironment)

Get the salinity of the underwater environment.

seabed(env::UnderwaterEnvironment)::ReflectionModel

Get the seabed reflection model for the underwater environment.

seasurface(env::UnderwaterEnvironment)::ReflectionModel

Get the sea surface reflection model for the underwater environment.

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.

ssp(env::UnderwaterEnvironment)::SoundSpeedProfile

Get the sound speed profile for the underwater environment.

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.

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.

waterdensity(env::UnderwaterEnvironment)

Get the nominal water density for the underwater environment.

AcousticReceiver(x, y, z)

Create an omnidirectional acoustic receiver at location (x, y, z).

AcousticReceiver(x, z)

Create an omnidirectional acoustic receiver at location (x, z).

struct AcousticReceiverGrid2D{T} <: AbstractArray{UnderwaterAcoustics.BasicAcousticReceiver{T}, 2}

A 2D Cartesian grid of omnidirectional acoustic receivers.

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.

struct AcousticReceiverGrid3D{T} <: AbstractArray{UnderwaterAcoustics.BasicAcousticReceiver{T}, 3}

A 3D Cartesian grid of omnidirectional acoustic receivers.

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.

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.

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.

struct BasicAcousticReceiver{T} <: AcousticReceiver

Omnidirectional acoustic receiver.

BasicAcousticReceiver(x, y, z)

Create an omnidirectional acoustic receiver at location (x, y, z).

BasicAcousticReceiver(x, z)

Create an omnidirectional acoustic receiver at location (x, z).

struct ConstantDepth{T} <: Bathymetry

Bathymetry with constant depth.

ConstantDepth(depth)

Create a constant depth bathymetry.

struct FlatSurface <: Altimetry

Altimetry for a flat surface with constant altitude of zero.

struct IsoSSP{T} <: SoundSpeedProfile

Isovelocity sound speed profile.

IsoSSP(c)

Create an isovelocity sound speed profile with sound speed c.

struct MunkSSP <: SoundSpeedProfile

Munk sound speed profile.

struct NarrowbandAcousticSource{T1, T2, T3, T4} <: AcousticSource

Narrowband acoustic source.

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.

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.

struct Pinger{T1, T2, T3, T4, T5, T6, T7, T8} <: AcousticSource

Narrowband pulsed acoustic source.

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)

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)

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.

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.

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.

struct SampledAcousticSource{T1, T2, T3<:AbstractArray} <: AcousticSource

Acoustic source transmitting a sampled signal.

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)

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)

struct SampledAltitude{T1, T2, T3} <: Altimetry

Altimetry based on altitude samples.

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.

struct SampledDepth{T1, T2, T3} <: Bathymetry

Bathymetry based on depth samples.

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.

abstract type SampledSSP <: SoundSpeedProfile

Sound speed profile based on discrete measurements.

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.

struct SampledSSP1D{T1, T2, T3} <: SampledSSP

Sound speed profile based on measurements at discrete depths.

struct SampledSSP2D{T1, T2, T3, T4} <: SampledSSP

Sound speed profile based on measurements at discrete depths and ranges.

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.

UnderwaterEnvironment(; altimetry, bathymetry, ssp, salinity, seasurface, seabed, noise)

Create an underwater environment.

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 σ².

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.