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 throughmodel: 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 aPropagationLossResultwith 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
Section titled “propagation_loss”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,) -> PropagationLossResultTotal 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
Section titled “PropagationLossResult”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()
Section titled “PropagationLossResult.plot()”PropagationLossResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the propagation loss versus range with its two contributions.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
seawater_absorption
Section titled “seawater_absorption”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
Section titled “spreading_loss”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. |