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”, (fin kHz,Uin 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
Section titled “AmbientNoiseResult”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()
Section titled “AmbientNoiseResult.plot()”AmbientNoiseResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the composite spectrum and its components versus frequency.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
ocean_ambient_noise
Section titled “ocean_ambient_noise”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,) -> AmbientNoiseResultComposite 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
Section titled “thermal_noise_spectrum”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
Section titled “wind_noise_spectrum”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. |