Ir al contenido

underwater.sonar_equation

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

The sonar equation (passive and active), in decibels.

Combines the sonar performance terms (source level SL, propagation loss PL, noise level NL, directivity index DI, detection threshold DT, target strength TS and reverberation level RL) into the signal excess SE, the signal-to-noise ratio and the figure of merit (the maximum allowable propagation loss at the detection limit ):

  • passive_sonar_equation: .
  • active_sonar_equation: monostatic, noise-limited or, when a reverberation level is given, reverberation-limited .

Two of those terms have their own model here rather than having to be supplied from outside: array_directivity_index gives DI from the length of a line array and the wavelength, which is also its array gain when the noise is isotropic, and detection_threshold gives DT from the false-alarm probability alone. Both are Ainslie (2010).

All quantities are in dB (levels re a plane wave of 1 µPa rms; the terms are spectrum levels, i.e. referred to a 1 Hz band). Source: Urick, Principles of Underwater Sound, via Etter (2003), Table 10.2. The loss term is the propagation loss of ISO 18405:2017, 3.4.1.4, which is also the term its own passive and active sonar equations (3.6.2.7 and 3.6.2.11) are written with.

The figure of merit is the maximum allowable propagation loss, so inverting a propagation-loss law at gives the detection range, the range at which the detection probability is 50 %:

  • detection_range inverts the closed-form loss of phonometry.underwater.propagation.closed_form (spreading plus volume absorption), which is strictly increasing with range and therefore has a single crossing;
  • detection_range_from_curve reads the crossing off any computed loss curve (a normal-mode, parabolic-equation or Weston-regime prediction), where the oscillatory loss of a real waveguide can cross the figure of merit more than once (Ainslie, Principles of Sonar Performance Modelling, §11.2.8 makes exactly that point about convergence zones).

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

active_sonar_equation(
source_level: float,
propagation_loss: NumericArrayLike,
target_strength: float,
noise_level: float,
*,
directivity_index: float = 0.0,
detection_threshold: float = 0.0,
reverberation_level: float | None = None,
) -> SonarEquationResult

Monostatic active sonar equation with a two-way propagation loss.

Noise-limited: . When reverberation_level is given, reverberation-limited: (DI does not apply to reverberation).

Parameters

Name Description
source_level Source level SL, in dB.
propagation_loss One-way propagation loss PL, in dB (scalar or array); the equation applies .
target_strength Target strength TS, in dB.
noise_level Background noise level NL, in dB.
directivity_index Receiver directivity index DI, in dB.
detection_threshold Detection threshold DT, in dB.
reverberation_level Reverberation level RL in dB; when given, the case is reverberation-limited.

Returns: A SonarEquationResult.

Raises

Exception When
ValueError If an input is not finite.
TypeError if detection_threshold, directivity_index, noise_level, reverberation_level, source_level or target_strength is not a single number, or propagation_loss holds a text or a value that is not a real number.
array_directivity_index(
array_length_m: float,
wavelength_m: float,
*,
steer_angle_rad: float = 0.0,
) -> float

Directivity index of an unshaded line array (Ainslie 2010, Eq. (6.49)).

with the directivity factor the reciprocal of the solid-angle footprint of the beam. For a steered unshaded line array, Equation (6.56) on printed folio 267 gives that footprint in closed form:

with (Eq. (6.54)) and (Eq. (6.57)), the high-frequency limit of the broadside directivity factor.

This is the array gain whenever the noise is isotropic and the signal a plane wave, which is the case the sonar equation is written for (Section 6.1.3.1): the two coincide in that limit, so this is what passive_sonar_equation wants for its directivity_index.

The book states three limits, and they are what the implementation is checked against: at high frequency for every steer direction but endfire, near endfire, where the footprint halves, and 0 dB as , where the array stops resolving anything. That last one is a limit and not a cutoff: a finite array a wavelength long still returns 3.45 dB, and half a wavelength 1.11 dB. It is reached exactly only where the ratio itself underflows, and the value there is 0 dB rather than an error.

Parameters

Name Description
array_length_m Array length L, in metres (> 0).
wavelength_m Acoustic wavelength lambda, in metres (> 0).
steer_angle_rad Steer angle psi from broadside, in radians (Default: 0, broadside). Only its sine enters, so the two sides of broadside give the same index.

Returns: The directivity index DI, in dB (>= 0).

Raises

Exception When
ValueError for a non-positive or non-finite length or wavelength, or a non-finite steer angle.
TypeError if array_length_m, steer_angle_rad or wavelength_m is not a single number.
detection_range(
figure_of_merit: float,
frequency_hz: float,
*,
law: Literal['spherical', 'cylindrical', 'practical'] = 'spherical',
transition_range: float | None = None,
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',
max_range: float = 500000.0,
n_points: int | np.integer[Any] = 400,
) -> DetectionRangeResult

Range at which the closed-form propagation loss equals the figure of merit.

Solves for the loss of propagation_loss, which is strictly increasing in range, so the root is unique. A one-way figure of merit works for both sonar modes: the active figure of merit returned by active_sonar_equation is already the maximum allowable one-way loss.

Parameters

Name Description
figure_of_merit Maximum allowable one-way propagation loss, in dB.
frequency_hz Acoustic frequency, in Hz.
law Spreading law (see spreading_loss). One of "spherical", "cylindrical" or "practical".
transition_range Transition range for the "practical" law, in m.
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".
max_range Upper bound of the search, in metres.
n_points Number of ranges kept on the returned loss curve.

Returns: A DetectionRangeResult.

Raises

Exception When
ValueError If an input is invalid.
TypeError if figure_of_merit, max_range or ph is not a single number, or n_points is a flag, a text or an array where a count goes, or law or model is not a text.
detection_range_from_curve(
figure_of_merit: float,
range_m: NumericArrayLike,
propagation_loss: NumericArrayLike,
*,
crossing: Literal['first', 'last'] = 'first',
) -> float

Detection range read off a computed propagation-loss curve.

Finds where PL(r) crosses the figure of merit from below, interpolating linearly between the two bracketing samples. Real waveguides oscillate, so crossing selects which crossing to report.

Parameters

Name Description
figure_of_merit Maximum allowable propagation loss, in dB.
range_m Ranges, in metres (1-D, strictly increasing).
propagation_loss Loss at each range, in dB (same length).
crossing "first" (default) or "last" upward crossing.

Returns: The detection range, in metres. Two limiting cases carry no crossing and are distinguished by the loss at the last sample: inf when the loss is still below the figure of merit there (the target stays detectable past the end of the grid) and 0.0 when the loss exceeds it there, which without an upward crossing means it exceeded it at every sample and the target is detectable nowhere. detection_range returns the same two values for the same two situations.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if figure_of_merit is not a single number, or crossing is not a text, or propagation_loss or range_m holds a text or a value that is not a real number.
detection_threshold(false_alarm_probability: float) -> float

Detection threshold at 50 % detection probability (Ainslie Eq. (11.22)).

printed on folio 581. DT is , the signal-to-noise ratio after all processing that a 50 % detection probability needs (Eq. (3.31)); this closed form estimates it from the false-alarm probability alone.

The logarithm inside is base two, not a square. The book states the approximation is accurate to +/- 0.1 dB for with one-dominant-plus-Rayleigh signal statistics, which is the intermediate choice to make when the target statistics are unknown, and that assuming those statistics anyway costs no more than 0.8 dB even for a stable signal or a fully Rayleigh one.

Parameters

Name Description
false_alarm_probability p_fa, the probability of declaring a detection with no target present, in (0, 1/2).

Returns: The detection threshold DT, in dB.

Raises

Exception When
ValueError for a non-finite p_fa, or one outside (0, 1/2). At the inner logarithm is zero and the threshold diverges: half the empty beams are already called detections.
TypeError if false_alarm_probability is not a single number.
DetectionRangeResult(
detection_range: float,
figure_of_merit: float,
frequency: float,
range_m: NDArray[np.float64],
propagation_loss: NDArray[np.float64],
absorption_db_per_km: float,
law: Literal['spherical', 'cylindrical', 'practical'],
model: Literal['francois-garrison', 'ainslie-mccolm', 'thorp'],
)

Detection range obtained by inverting a propagation-loss law.

Attributes

Name Description
detection_range Range at which PL equals the figure of merit, in metres. inf when the loss never reaches it inside max_range (detectable throughout) and 0.0 when it already exceeds it at the search floor (detectable nowhere).
figure_of_merit The figure of merit inverted, in dB.
frequency Acoustic frequency, in Hz.
range_m Range grid over which the loss was evaluated, in metres.
propagation_loss Propagation loss at each range, in dB.
absorption_db_per_km 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".
DetectionRangeResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the propagation loss against the figure of merit.

Parameters

Name Description
language The language of the labels: "en" or "es".
passive_sonar_equation(
source_level: float,
propagation_loss: NumericArrayLike,
noise_level: float,
*,
directivity_index: float = 0.0,
detection_threshold: float = 0.0,
) -> SonarEquationResult

Passive sonar equation .

Parameters

Name Description
source_level Source level SL (of the target), in dB.
propagation_loss One-way propagation loss PL, in dB (scalar or array).
noise_level Background noise level NL, in dB.
directivity_index Receiver directivity index DI, in dB.
detection_threshold Detection threshold DT, in dB.

Returns: A SonarEquationResult.

Raises

Exception When
ValueError If an input is not finite.
TypeError if detection_threshold, directivity_index, noise_level or source_level is not a single number, or propagation_loss holds a text or a value that is not a real number.
SonarEquationResult(
mode: Literal['passive', 'active'],
signal_excess: NDArray[np.float64],
snr: NDArray[np.float64],
figure_of_merit: float,
propagation_loss: NDArray[np.float64],
source_level: float,
noise_level: float,
directivity_index: float,
detection_threshold: float,
target_strength: float | None,
*,
reverberation_limited: bool,
)

Sonar-equation solution.

Attributes

Name Description
mode "passive" or "active".
signal_excess Signal excess SE per propagation loss, in dB (detection when SE >= 0).
snr Signal-to-noise (or signal-to-reverberation) ratio, in dB ().
figure_of_merit Maximum allowable (one-way) propagation loss at the detection limit , in dB.
propagation_loss The propagation-loss values, in dB.
source_level Source level SL, in dB.
noise_level Background noise level NL input, in dB. The masking term is , except when reverberation_limited is true, where the reverberation level RL masks instead.
directivity_index Receiver directivity index DI, in dB.
detection_threshold Detection threshold DT, in dB.
target_strength Target strength TS, in dB (None for passive).
reverberation_limited Whether the active case is reverberation-limited.
SonarEquationResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot signal excess versus propagation loss with the detection limit.

Parameters

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