# underwater.acoustics

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-15
Updated: 2026-11-11T17:49:24Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Underwater-acoustics reference levels (ISO 18405:2017).

---

Underwater-acoustics reference levels (ISO 18405:2017).

Underwater sound levels use a reference pressure of **1 µPa** (not the 20 µPa of
airborne acoustics) and a reference sound exposure of **1 µPa²·s**. This module
realises the ISO 18405 terminology as the shared level primitives used by the
ship-radiated-noise and pile-driving modules:

* [`sound_pressure_level`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#sound_pressure_level): the mean-square sound pressure level,
  $\mathrm{SPL} = 10 \log_{10}(\langle p^2 \rangle / p_0^2)$ dB re 1 µPa.
* [`sound_exposure_level`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#sound_exposure_level): the time-integrated exposure level,
  $\mathrm{SEL} = 10 \log_{10}\!\left( \int p^2 \, dt / E_0 \right)$ dB re
  1 µPa²·s.
* [`peak_sound_pressure_level`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#peak_sound_pressure_level): the zero-to-peak level
  $20 \log_{10}(\max \lvert p \rvert / p_0)$ dB re 1 µPa.

[`underwater_to_in_air_spl`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#underwater_to_in_air_spl) / [`in_air_to_underwater_spl`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#in_air_to_underwater_spl) convert a
level between the two reference pressures (a
$20 \log_{10}(20) \approx 26.02$ dB reference
change, **not** an energy/intensity equivalence, which would additionally
involve the media impedances). For background-noise subtraction of a measured
level, reuse the ISO 3744 `background_noise_correction` (`K1`) helper.

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

## in_air_to_underwater_spl

```python
in_air_to_underwater_spl(level: float) -> float
```

Re-reference an in-air SPL (re 20 µPa) to the underwater 1 µPa
reference.

Adds $20 \log_{10}(20) \approx 26.02$ dB (a reference-pressure change
only; see [`underwater_to_in_air_spl`](https://docs.jmrp.io/phonometry/reference/api/underwater/acoustics/#underwater_to_in_air_spl)).

**Parameters**

| Name | Description |
| :--- | :--- |
| `level` | Level in dB re 20 µPa. |

**Returns:** The same pressure expressed in dB re 1 µPa.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | If the level is an array or not a number. |
| ValueError | If the level is not finite. |

## peak_sound_pressure_level

```python
peak_sound_pressure_level(
    pressure_pa: Signal | NumericArrayLike,
    *,
    reference: float = 1e-06,
) -> float
```

Zero-to-peak sound pressure level (ISO 18406 6.4.2.1.3).

$L_{p,\mathrm{pk}} = 20 \log_{10}(\max \lvert p \rvert / p_0)$ dB re
1 µPa.

**Parameters**

| Name | Description |
| :--- | :--- |
| `pressure_pa` | Sound-pressure time series (1-D), in Pa. Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal), whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in. |
| `reference` | Reference pressure $p_0$, in Pa (default 1 µPa). |

**Returns:** Peak sound pressure level, in dB re the reference.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the signal is invalid or is all zero. |
| TypeError | if `reference` is not a single number, or `pressure_pa` holds a text or a value that is not a real number. |

## sound_exposure_level

```python
sound_exposure_level(
    pressure_pa: Signal | NumericArrayLike,
    fs: float | None = None,
    *,
    reference: float = 1e-12,
) -> float
```

Sound exposure level (ISO 18405 / ISO 18406 Formulae 3-4).

$\mathrm{SEL} = 10 \log_{10}(E/E_0)$ dB re 1 µPa²·s, with the sound
exposure $E = \int p^2 \, dt \approx (1/f_\mathrm{s}) \sum p^2$ over the
record.

**Parameters**

| Name | Description |
| :--- | :--- |
| `pressure_pa` | Sound-pressure time series (1-D), in Pa. Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal), whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in. |
| `fs` | Sample rate, in Hz. Required for a bare array; a [`Signal`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal) brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
| `reference` | Reference exposure $E_0$, in Pa²·s (default 1 µPa²·s). |

**Returns:** Sound exposure level, in dB re the reference.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are invalid or the signal has no energy. |
| TypeError | if `fs` or `reference` is not a single number, or `pressure_pa` holds a text or a value that is not a real number. |

## sound_pressure_level

```python
sound_pressure_level(
    pressure_pa: Signal | NumericArrayLike,
    *,
    reference: float = 1e-06,
) -> float
```

Mean-square sound pressure level (ISO 18405 / ISO 18406 Formula 7).

$\mathrm{SPL} = 10 \log_{10}(\langle p^2 \rangle / p_0^2)$ dB, with `p`
in pascals and the underwater reference $p_0 = 1$ µPa by default.

**Parameters**

| Name | Description |
| :--- | :--- |
| `pressure_pa` | Sound-pressure time series (1-D), in Pa. Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal), whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in. |
| `reference` | Reference pressure $p_0$, in Pa (default 1 µPa). |

**Returns:** Sound pressure level, in dB re the reference.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the signal is invalid or has no energy. |
| TypeError | if `reference` is not a single number, or `pressure_pa` holds a text or a value that is not a real number. |

## UNDERWATER_REFERENCE_EXPOSURE_PA2_S

*Constant* (`float`).

```python
UNDERWATER_REFERENCE_EXPOSURE_PA2_S = 1e-12
```

## UNDERWATER_REFERENCE_PRESSURE_PA

*Constant* (`float`).

```python
UNDERWATER_REFERENCE_PRESSURE_PA = 1e-06
```

## underwater_to_in_air_spl

```python
underwater_to_in_air_spl(level: float) -> float
```

Re-reference an underwater SPL (re 1 µPa) to the in-air 20 µPa
reference.

Subtracts $20 \log_{10}(20) \approx 26.02$ dB. This is a
**reference-pressure change only**: it is not the in-water/in-air
intensity equivalence, which also involves the media characteristic
impedances.

**Parameters**

| Name | Description |
| :--- | :--- |
| `level` | Level in dB re 1 µPa. |

**Returns:** The same pressure expressed in dB re 20 µPa.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | If the level is an array or not a number. |
| ValueError | If the level is not finite. |
