Skip to content

underwater.sources.ambient_noise

Ocean ambient-noise spectrum levels (Wenz framework).

Deep-water ambient-noise spectrum levels (dB re 1 µPa²/Hz) from the two physically grounded components of the Wenz curves:

  • wind_noise_spectrum: wind / sea-surface (Knudsen) noise via Wenz’s “rule of fives”, (f in kHz, U in knots; the historical 25 dB anchor is re 20 µPa and becomes re 1 µPa), valid over roughly 500 Hz-5 kHz.
  • thermal_noise_spectrum: the molecular thermal-noise limit (Mellen 1952), (Pa²/Hz), dominant above ~50 kHz.

ocean_ambient_noise energy-sums the enabled components (and an optional caller-supplied shipping spectrum) into a composite AmbientNoiseResult with a .plot() of the Wenz-style curves.

The low-frequency turbulence band and a built-in distant-shipping model are out of scope: Wenz (1962) and Carey & Evans note these bands are strongly variable and shipping-dependent, with no single fixed analytic parametrisation; a shipping spectrum may be supplied by the caller. Source: Carey & Evans, Ocean Ambient Noise (2011): the rule of fives (p. 2) and the thermal-noise derivation (Appendix F).

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

AmbientNoiseResult(
frequencies: NDArray[np.float64],
spectrum_level: NDArray[np.float64],
wind: NDArray[np.float64],
thermal: NDArray[np.float64],
shipping: NDArray[np.float64] | None,
wind_speed_kt: float,
)

Composite ambient-noise spectrum (Wenz framework).

Attributes

Name Description
frequencies Frequencies, in Hz.
spectrum_level Composite spectrum level (energy sum of the enabled components), in dB re 1 µPa²/Hz.
wind Wind-noise component per frequency, in dB re 1 µPa²/Hz.
thermal Thermal-noise component per frequency, in dB re 1 µPa²/Hz.
shipping Caller-supplied shipping component, or None.
wind_speed_kt The wind speed used, in knots.
AmbientNoiseResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the composite spectrum and its components versus frequency.

Parameters

Name Description
language The language of the labels: "en" or "es".
ocean_ambient_noise(
frequencies_hz: NumericArrayLike,
*,
wind_speed_kt: float,
shipping: NumericArrayLike | None = None,
temperature_c: float = 16.85,
density: float = 1025.0,
speed_of_sound: float = 1500.0,
) -> AmbientNoiseResult

Composite deep-water ambient-noise spectrum (wind + thermal [+ shipping]).

Energy-sums the wind-noise (rule of fives) and thermal-noise (Mellen) components, plus an optional caller-supplied shipping spectrum.

Parameters

Name Description
frequencies_hz Frequencies, in Hz (1-D, strictly positive).
wind_speed_kt Wind speed U, in knots.
shipping Optional shipping-noise spectrum level per frequency, in dB re 1 µPa²/Hz (same length as frequencies_hz), or None.
temperature_c Water temperature, in degrees Celsius.
density Water density, in kg/m³.
speed_of_sound Sound speed, in m/s.

Returns: An AmbientNoiseResult.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if frequencies_hz or shipping holds a text or a value that is not a real number.
thermal_noise_spectrum(
frequency_hz: float | np.floating[Any] | np.integer[Any],
*,
temperature_c: float = ...,
density: float = ...,
speed_of_sound: float = ...,
) -> float
thermal_noise_spectrum(
frequency_hz: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
temperature_c: float = ...,
density: float = ...,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
thermal_noise_spectrum(
frequency_hz: NumericArrayLike,
*,
temperature_c: float = ...,
density: float = ...,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Molecular thermal-noise spectrum level (Mellen 1952), dB re 1 µPa²/Hz.

(Pa²/Hz); the level is .

Parameters

Name Description
frequency_hz Frequency, in Hz (scalar or array).
temperature_c Water temperature, in degrees Celsius (default 16.85 °C = 290 K).
density Water density , in kg/m³ (default 1025).
speed_of_sound Sound speed c, in m/s (default 1500).

Returns: Thermal-noise spectrum level per frequency, in dB re 1 µPa²/Hz. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if density, speed_of_sound or temperature_c is not a single number, or frequency_hz holds a text or a value that is not a real number.
wind_noise_spectrum(
frequency_hz: float | np.floating[Any] | np.integer[Any],
wind_speed_kt: float,
) -> float
wind_noise_spectrum(
frequency_hz: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
wind_speed_kt: float,
) -> NDArray[np.float64]
wind_noise_spectrum(
frequency_hz: NumericArrayLike,
wind_speed_kt: float,
) -> float | NDArray[np.float64]

Wind / sea-surface noise spectrum level (Wenz rule of fives), dB re 1 µPa²/Hz.

with f in kHz and U in knots: −5 dB per octave and +5 dB per doubling of wind speed about the canonical anchor, which Wenz/Knudsen state as “25 dB (5 × 5)” at 1 kHz for 5 knots re 0.0002 dyn/cm² (20 µPa), i.e. dB once referenced to the ISO 18405 1 µPa. Valid over roughly 500 Hz-5 kHz and winds of 2.5-40 knots (the stated range of the wind-doubling law); outside both the formula extrapolates.

Parameters

Name Description
frequency_hz Frequency, in Hz (scalar or array).
wind_speed_kt Wind speed U, in knots. A calm sea (0) has no wind-driven noise, returning -inf (zero contribution in the energy sum).

Returns: Wind-noise spectrum level per frequency, in dB re 1 µPa²/Hz. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If the inputs are invalid (a negative wind speed).
TypeError if wind_speed_kt is not a single number, or frequency_hz holds a text or a value that is not a real number.