Skip to content

underwater.propagation.closed_form

Underwater sound propagation: propagation loss (closed-form).

Propagation loss PL, (dB) is the difference between the source level in a given direction and the mean-square sound pressure level at the receiver, (ISO 18405:2017, 3.4.1.4). Here it is the sum of geometrical spreading and volume absorption:

  • spreading_loss: geometrical spreading, (spherical), (cylindrical) or spherical-then-cylindrical ("practical").
  • seawater_absorption: the volume absorption coefficient in dB/km, from three coexisting formulations selectable through model: Francois & Garrison (1982, the default and reference), Ainslie & McColm (1998, a legible simplification of it) and Thorp (1967, a frequency-only form).
  • propagation_loss: the total versus range, returned as a PropagationLossResult with a .plot().

Not transmission loss, which ISO 18405:2017, 3.4.1.3 reserves for the reduction in a specified level between two specified points and whose Note 6 to entry deprecates as a synonym of this quantity.

Sources (clean-room, implemented from the published equations): Francois & Garrison, JASA 72 (1982) via Medwin & Clay; Ainslie & McColm, JASA 103 (1998); Thorp (1967) via Etter (2003). Absorption is validated by the mutual agreement of Francois-Garrison and Ainslie-McColm (~10 % as the latter’s paper states; marginally exceeded at the extreme corners of the stated domain, e.g. 10.4 % at T = −6 °C / 1 MHz and 12.3 % at z = 7 km, a property of the published simplification, both transcriptions verified digit-for-digit).

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

propagation_loss(
range_m: NumericArrayLike,
frequency_hz: float,
*,
law: Literal['spherical', 'cylindrical', 'practical'] = 'spherical',
temperature_c: float = 10.0,
salinity: float = 35.0,
depth: float = 0.0,
ph: float = 8.0,
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'] = 'francois-garrison',
transition_range: float | None = None,
) -> PropagationLossResult

Total propagation loss versus range.

Parameters

Name Description
range_m Range(s) from the source, in metres (scalar or array).
frequency_hz Acoustic frequency, in Hz.
law Spreading law (see spreading_loss). One of "spherical", "cylindrical" or "practical".
temperature_c Temperature T, in degrees Celsius.
salinity Salinity S, in parts per thousand.
depth Depth, in metres.
ph Acidity (default 8).
model Absorption model (see seawater_absorption). One of "francois-garrison", "ainslie-mccolm" or "thorp".
transition_range Transition range for the "practical" law, in m.

Returns: A PropagationLossResult.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if frequency_hz is not a single number, or law or model is not a text, or range_m holds a text or a value that is not a real number, or ph is not a single number.
PropagationLossResult(
range_m: NDArray[np.float64],
pl: NDArray[np.float64],
spreading: NDArray[np.float64],
absorption: NDArray[np.float64],
frequency: float,
absorption_db_per_km: float,
law: Literal['spherical', 'cylindrical', 'practical'],
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'],
)

Propagation loss versus range (closed-form).

Attributes

Name Description
range_m Ranges from the source, in metres.
pl Total propagation loss per range, in dB.
spreading Geometrical-spreading contribution per range, in dB.
absorption Volume-absorption contribution per range, in dB.
frequency The acoustic frequency, in Hz.
absorption_db_per_km The absorption coefficient , in dB/km.
law The spreading law used. One of "spherical", "cylindrical" or "practical".
model The absorption model used. One of "francois-garrison", "ainslie-mccolm" or "thorp".
PropagationLossResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the propagation loss versus range with its two contributions.

Parameters

Name Description
language The language of the labels: "en" or "es".
seawater_absorption(
frequency_hz: float | np.floating[Any] | np.integer[Any],
*,
temperature_c: float = ...,
salinity: float = ...,
depth: float = ...,
ph: float = ...,
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'] = ...,
) -> float
seawater_absorption(
frequency_hz: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
temperature_c: float = ...,
salinity: float = ...,
depth: float = ...,
ph: float = ...,
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'] = ...,
) -> NDArray[np.float64]
seawater_absorption(
frequency_hz: NumericArrayLike,
*,
temperature_c: float = ...,
salinity: float = ...,
depth: float = ...,
ph: float = ...,
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'] = ...,
) -> float | NDArray[np.float64]

Volume absorption coefficient , in dB/km.

Parameters

Name Description
frequency_hz Acoustic frequency, in Hz (scalar or array).
temperature_c Temperature T, in degrees Celsius.
salinity Salinity S, in parts per thousand.
depth Depth, in metres (>= 0).
ph Acidity (used by Francois-Garrison and Ainslie-McColm; default 8).
model "francois-garrison" (default), "ainslie-mccolm" or "thorp" (the Thorp 1967 frequency-only form of Etter, valid below ~50 kHz; ignores temperature_c/salinity/depth/ph).

Returns: Absorption coefficient per frequency, in dB/km. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If model is unknown or an input is invalid.
TypeError if depth, salinity or temperature_c is not a single number, or model is not a text, or frequency_hz holds a text or a value that is not a real number, or ph is not a single number.
spreading_loss(
range_m: float | np.floating[Any] | np.integer[Any],
*,
law: Literal['spherical', 'cylindrical', 'practical'] = ...,
transition_range: float | None = ...,
) -> float
spreading_loss(
range_m: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
law: Literal['spherical', 'cylindrical', 'practical'] = ...,
transition_range: float | None = ...,
) -> NDArray[np.float64]
spreading_loss(
range_m: NumericArrayLike,
*,
law: Literal['spherical', 'cylindrical', 'practical'] = ...,
transition_range: float | None = ...,
) -> float | NDArray[np.float64]

Geometrical spreading loss, in dB.

"spherical" gives (free field), "cylindrical" gives (perfect waveguide) and "practical" is spherical up to transition_range R0 then cylindrical: (mode stripping in a channel).

Parameters

Name Description
range_m Range R from the source, in metres (scalar or array, strictly positive).
law "spherical" (default), "cylindrical" or "practical".
transition_range Transition range R0 in metres; required for "practical".

Returns: Spreading loss per range, in dB. 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 transition_range is not a single number, or law is not a text, or range_m holds a text or a value that is not a real number.