Skip to content

underwater.propagation.weston_regimes

Weston’s shallow-water propagation regimes (flux theory).

A source in a shallow-water waveguide loses energy in four successive range regimes, each with its own power law. The boundaries between them follow from the seabed reflectivity alone, which makes the set an inexpensive analytic reference for any numerical propagation model:

  • spherical spreading: (), while the sound has not yet felt the boundaries;
  • cylindrical spreading: (), once the energy is confined to a cylinder of height H and only rays within the critical angle survive;
  • mode stripping: (), once the accumulated reflection loss has eroded the steep paths;
  • single mode: an exponential decay dominated by the lowest-order mode.

Everything here is implemented clean-room from Ainslie, Principles of Sonar Performance Modelling (Springer 2010), §9.1.1.2 (printed pp. 452-458): Equations (9.42) to (9.61) and the seabed properties of Table 9.1 (WESTON_SEABEDS). The quantity computed is Ainslie’s propagation factor F (units m⁻²), reported as the propagation loss dB re 1 m², which reduces to spherical spreading for a point source in free water.

The regime formulae are energy-flux (incoherent) results: they describe the range-averaged field, not its modal interference. That is exactly what makes them a usable cross-check for phonometry.underwater.propagation.numerical: the range average of a normal-mode or parabolic-equation field over many interference cycles converges on the cylindrical-spreading law, with for a totally reflecting (pressure-release) bottom.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

critical_grazing_angle(sound_speed_ratio: float) -> float

Critical grazing angle , in radians.

A seabed slower than the water (, e.g. mud) has no critical angle; the function then returns 0, which correctly switches the reflection-loss gradient to the refracting-sediment branch of reflection_loss_gradient.

Parameters

Name Description
sound_speed_ratio , dimensionless and positive.

Returns: The critical grazing angle, in radians (0 if none exists).

Raises

Exception When
ValueError If the ratio is not positive and finite.
TypeError if sound_speed_ratio is not a single number.
effective_depth(
water_depth: float,
frequency_hz: float,
*,
seabed: Literal['sand', 'mud'] | WestonSeabed = 'sand',
speed_of_sound: float = 1500.0,
) -> float

Weston effective water depth He (Ainslie Eq. 9.55), in metres.

: the depth at which a pressure-release boundary appears to lie, a short distance below the true seabed. Only meaningful for a seabed with a critical angle.

Parameters

Name Description
water_depth Water-column depth H, in metres.
frequency_hz Acoustic frequency, in Hz.
seabed "sand", "mud" or a WestonSeabed.
speed_of_sound Water sound speed c_w, in m/s.

Returns: The effective depth He, in metres.

Raises

Exception When
ValueError If the seabed has no critical angle or an input is invalid.
TypeError if frequency_hz, speed_of_sound or water_depth is not a single number, or seabed is not a text.
loss_parameter(attenuation_db_per_wavelength: float) -> float

Sediment loss parameter (Ainslie Eq. 9.23).

Parameters

Name Description
attenuation_db_per_wavelength , in dB per wavelength.

Returns: The dimensionless loss parameter .

Raises

Exception When
ValueError If the attenuation is negative or non-finite.
TypeError if attenuation_db_per_wavelength is not a single number.
reflection_loss_gradient(
seabed: Literal['sand', 'mud'] | WestonSeabed = 'sand',
*,
frequency_hz: float | None = None,
) -> float

Reflection loss gradient , in nepers per radian.

The rate at which the seabed reflection loss grows with grazing angle, (Ainslie Eq. 9.45). Two branches:

  • a reflecting seabed with a critical angle (sand, coarse silt), (Eq. 9.51), frequency-independent;
  • a refracting seabed with none (mud, clay, fine silt), (Eq. 9.53), proportional to frequency.

Parameters

Name Description
seabed "sand", "mud" or an explicit WestonSeabed.
frequency_hz Acoustic frequency, in Hz; required only for the refracting branch ().

Returns: The reflection loss gradient , in Np/rad.

Raises

Exception When
ValueError If the frequency is missing or invalid for a refracting seabed.
TypeError if frequency_hz is not a single number, or seabed is not a text.
waveguide_cutoff_frequency(
water_depth: float,
*,
seabed: Literal['sand', 'mud'] | WestonSeabed = 'sand',
speed_of_sound: float = 1500.0,
) -> float

Shallow-water waveguide cut-off frequency fc (Ainslie Eq. 9.60), in Hz.

: below it no mode is cut on and ducted propagation does not occur.

Parameters

Name Description
water_depth Water-column depth H, in metres.
seabed "sand", "mud" or a WestonSeabed.
speed_of_sound Water sound speed c_w, in m/s.

Returns: The cut-off frequency, in Hz.

Raises

Exception When
ValueError If the seabed has no critical angle or an input is invalid.
TypeError if speed_of_sound or water_depth is not a single number, or seabed is not a text.
weston_propagation_loss(
range_m: NumericArrayLike,
frequency_hz: float,
water_depth: float,
*,
seabed: Literal['sand', 'mud'] | WestonSeabed = 'sand',
speed_of_sound: float = 1500.0,
source_depth: float | None = None,
receiver_depth: float | None = None,
critical_angle_deg: float | None = None,
reflection_loss_gradient_value_np_per_rad: float | None = None,
) -> WestonPropagationResult

Propagation loss across Weston’s four shallow-water regimes.

Assembles the piecewise loss from Ainslie’s Equations (9.42), (9.49) and (9.54), switching regime at the boundaries of weston_regime_boundaries, and returns each regime’s own law over the whole range grid so the transitions can be drawn.

Parameters

Name Description
range_m Range(s) from the source, in metres (scalar or array, strictly positive).
frequency_hz Acoustic frequency, in Hz.
water_depth Water-column depth H, in metres.
seabed "sand", "mud" or a WestonSeabed.
speed_of_sound Water sound speed c_w, in m/s.
source_depth Source depth z0, in metres; defaults to H/2 (used only by the single-mode formula).
receiver_depth Receiver depth z, in metres; defaults to H/2.
critical_angle_deg Override , in degrees (90 for an ideal totally reflecting waveguide).
reflection_loss_gradient_value_np_per_rad Override , in Np/rad (0 for a lossless bottom: no mode stripping, no single-mode regime).

Returns: A WestonPropagationResult.

Raises

Exception When
ValueError If an input is invalid.
TypeError if frequency_hz, speed_of_sound or water_depth is not a single number, or seabed is not a text, or range_m holds a text or a value that is not a real number. receiver_depth or source_depth are refused the same way when any is not one real number.
weston_regime_boundaries(
frequency_hz: float,
water_depth: float,
*,
seabed: Literal['sand', 'mud'] | WestonSeabed = 'sand',
speed_of_sound: float = 1500.0,
critical_angle_deg: float | None = None,
reflection_loss_gradient_value_np_per_rad: float | None = None,
) -> WestonRegimeBoundaries

Regime boundaries of a shallow-water waveguide (Ainslie §9.1.1.2).

Parameters

Name Description
frequency_hz Acoustic frequency, in Hz.
water_depth Water-column depth H, in metres.
seabed "sand", "mud" or a WestonSeabed.
speed_of_sound Water sound speed c_w, in m/s.
critical_angle_deg Override the seabed critical angle , in degrees. Use 90 for the ideal totally reflecting waveguide.
reflection_loss_gradient_value_np_per_rad Override , in Np/rad. Use 0 for a lossless bottom (no mode stripping, no single-mode regime).

Returns: A WestonRegimeBoundaries.

Raises

Exception When
ValueError If an input is invalid.
TypeError if critical_angle_deg, frequency_hz, reflection_loss_gradient_value_np_per_rad, speed_of_sound or water_depth is not a single number.

Constant (tuple).

WESTON_REGIMES = ('spherical', 'cylindrical', 'mode-stripping', 'single-mode')

Constant (mapping).

WESTON_SEABEDS = {'sand': WestonSeabed(name='sand', grain_size=1.5, sound_speed_ratio=1.2, density_ratio=2.1, attenuation_db_per_wavelength=0.88, loss_parameter=0.0161, sound_speed_gradient_per_s=0.0), 'mud': WestonSeabed(name='mud', grain_size=8.0, sound_speed_ratio=1.0, density_ratio=1.4, attenuation_db_per_wavelength=0.09, loss_parameter=0.00165, sound_speed_gradient_per_s=1.0)}
WestonPropagationResult(
range_m: NDArray[np.float64],
propagation_loss: NDArray[np.float64],
propagation_factor: NDArray[np.float64],
spherical: NDArray[np.float64],
cylindrical: NDArray[np.float64],
mode_stripping: NDArray[np.float64],
single_mode: NDArray[np.float64],
multipath: NDArray[np.float64],
boundaries: WestonRegimeBoundaries,
frequency: float,
water_depth: float,
source_depth: float,
receiver_depth: float,
seabed: str,
)

Weston regime propagation loss versus range.

Attributes

Name Description
range_m Ranges from the source, in metres.
propagation_loss Composite propagation loss per range, in dB re 1 m².
propagation_factor The composite propagation factor F, in m⁻².
spherical Spherical-spreading loss at every range, in dB.
cylindrical Cylindrical-spreading loss (Eq. 9.42) at every range, dB.
mode_stripping Mode-stripping loss (Eq. 9.49) at every range, dB (nan when the bottom is lossless: without reflection loss there is nothing to strip).
single_mode Single-mode loss (Eq. 9.54) at every range, in dB.
multipath Loss from the continuous multipath integral (Eq. 9.46), which joins the cylindrical and mode-stripping regimes smoothly, in dB.
boundaries The WestonRegimeBoundaries in force.
frequency Acoustic frequency, in Hz.
water_depth Water-column depth H, in metres.
source_depth Source depth z0, in metres.
receiver_depth Receiver depth z, in metres.
seabed Name of the seabed used.

The regime in force at each range (regime) is read from the ranges and the boundaries, so it is not a field.

WestonPropagationResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the composite loss with each regime’s law and the boundaries.

Parameters

Name Description
language The language of the labels: "en" or "es".

property

The regime in force at each range, one of WESTON_REGIMES.

Read from range_m and boundaries: each regime holds from its own boundary onwards, the boundary itself included.

Returns: One label per range.

WestonRegimeBoundaries(
spherical_to_cylindrical: float,
cylindrical_to_mode_stripping: float,
mode_stripping_to_single_mode: float,
critical_angle_rad: float,
reflection_loss_gradient_np_per_rad: float,
effective_depth: float,
cutoff_frequency: float,
n_modes: float,
)

Range boundaries between Weston’s four propagation regimes.

Attributes

Name Description
spherical_to_cylindrical Range at which and are equal, , in metres.
cylindrical_to_mode_stripping Ainslie Eq. (9.50) , in metres (inf for a lossless bottom).
mode_stripping_to_single_mode , in metres (inf for a lossless bottom). See the module note on Eq. (9.57).
critical_angle_rad Critical grazing angle , in radians.
reflection_loss_gradient_np_per_rad , in Np/rad.
effective_depth Weston effective depth He, in metres.
cutoff_frequency Waveguide cut-off frequency, in Hz (nan when the seabed has no critical angle).
n_modes Number of cut-on modes, (Eq. 9.58), as a real number.
WestonSeabed(
*,
name: str,
grain_size: float,
sound_speed_ratio: float,
density_ratio: float,
attenuation_db_per_wavelength: float,
loss_parameter: float,
sound_speed_gradient_per_s: float,
)

Characteristic seabed properties (Ainslie Table 9.1, printed p. 454).

Attributes

Name Description
name Sediment name.
grain_size Grain size Mz (phi units).
sound_speed_ratio .
density_ratio .
attenuation_db_per_wavelength , in dB per wavelength.
loss_parameter (Equation 9.23).
sound_speed_gradient_per_s c', the sediment sound-speed gradient, in s⁻¹ (0 for sand, 1 for mud).