# underwater: seabed reflection

> 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/seabed-reflection/
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:27Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Plane-wave reflection at the seabed (fluid-fluid Rayleigh model).

---

Every name on this page is published by `phonometry.underwater`: `from phonometry import underwater`, then `underwater.<name>`.

Plane-wave reflection at the seabed (fluid-fluid Rayleigh model).

A plane wave in the water column (density $\rho_1$, sound speed
`c1`) striking a fluid sediment half-space ($\rho_2$, `c2`)
reflects with the Rayleigh pressure reflection coefficient (Medwin & Clay,
Eq. 2.6.11a). Using the grazing angle $\varphi$ (measured from the
interface), the angle of incidence from the normal is
$\theta_1 = 90^\circ - \varphi$, Snell's law gives
$\sin\theta_2 = (c_2/c_1) \cos\varphi$ and

$$
R = \frac{\rho_2 c_2 \sin\varphi - \rho_1 c_1 \cos\theta_2} {\rho_2 c_2 \sin\varphi + \rho_1 c_1 \cos\theta_2}
$$

* [`critical_angle`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#critical_angle): the critical grazing angle
  $\varphi_\mathrm{c} = \arccos(c_1/c_2)$ (only when `c2 > c1`); below it the
  wave is totally reflected ($\lvert R \rvert = 1$).
* [`reflection_coefficient`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#reflection_coefficient): the complex `R` per grazing angle.
* [`seabed_reflection`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#seabed_reflection): the complex `R`, its magnitude `|R|` and the
  bottom loss bundled with the interface parameters into a
  [`SeabedReflection`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#seabedreflection) whose `.plot()` draws `|R|` versus grazing angle.
* [`bottom_reflection_loss`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#bottom_reflection_loss): the bottom loss
  $\mathrm{BL} = -20 \log_{10} \lvert R \rvert$ (dB), returned as a
  [`BottomLossResult`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#bottomlossresult) with a `.plot()`.

Lossless fluid-fluid model (real $\rho$/`c`); sediment attenuation is
out of scope. Densities enter only through the impedance ratio, so any
consistent unit works (kg/m³ by convention).

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

## bottom_reflection_loss

```python
bottom_reflection_loss(
    grazing_angle_deg: NumericArrayLike,
    *,
    rho1: float = 1000.0,
    c1: float = 1500.0,
    rho2: float,
    c2: float,
) -> BottomLossResult
```

Bottom reflection loss $\mathrm{BL} = -20 \log_{10} \lvert R \rvert$
versus grazing angle (dB).

At an angle of intromission $R = 0$ and the loss is `inf` (total
transmission into the sediment); that is a legitimate bottom-loss value,
returned without warning.

**Parameters**

| Name | Description |
| :--- | :--- |
| `grazing_angle_deg` | Grazing angle(s) $\varphi$ from the interface, in degrees. |
| `rho1` | Water density $\rho_1$ (default 1000 kg/m³). |
| `c1` | Sound speed in the water `c1`, in m/s (default 1500). |
| `rho2` | Sediment density $\rho_2$. |
| `c2` | Sound speed in the sediment `c2`, in m/s. |

**Returns:** A [`BottomLossResult`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#bottomlossresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are invalid. |
| TypeError | if `grazing_angle_deg` holds a text or a value that is not a real number. |

## BottomLossResult

```python
BottomLossResult(
    grazing_angle_deg: NDArray[np.float64],
    reflection_loss: NDArray[np.float64],
    reflection_coefficient: NDArray[np.complex128],
    critical_angle_deg: float | None,
)
```

Bottom reflection loss versus grazing angle (fluid-fluid Rayleigh
model).

**Attributes**

| Name | Description |
| :--- | :--- |
| `grazing_angle_deg` | Grazing angles, in degrees. |
| `reflection_loss` | Bottom loss $\mathrm{BL} = -20 \log_{10} \lvert R \rvert$ per angle, in dB. |
| `reflection_coefficient` | Complex reflection coefficient per angle. |
| `critical_angle_deg` | The critical grazing angle, in degrees, or `None` if the sediment is not faster than the water. |

### BottomLossResult.plot()

```python
BottomLossResult.plot(
    ax: Axes | None = None,
    *,
    language: Literal['en', 'es'] = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the bottom loss versus grazing angle with the critical angle.

**Parameters**

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

## critical_angle

```python
critical_angle(c1: float, c2: float) -> float
```

Critical grazing angle $\varphi_\mathrm{c} = \arccos(c_1/c_2)$, in
degrees.

Defined only when the sediment is faster than the water (`c2 > c1`); at and
below this grazing angle the wave is totally reflected.

**Parameters**

| Name | Description |
| :--- | :--- |
| `c1` | Sound speed in the water, in m/s. |
| `c2` | Sound speed in the sediment, in m/s. |

**Returns:** The critical grazing angle, in degrees.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `c2 <= c1` (no critical angle exists). |
| TypeError | if `c1` or `c2` is not a single number. |

## reflection_coefficient

```python
reflection_coefficient(
    grazing_angle_deg: float | np.floating[Any] | np.integer[Any],
    *,
    rho1: float,
    c1: float,
    rho2: float,
    c2: float,
) -> complex

reflection_coefficient(
    grazing_angle_deg: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    *,
    rho1: float,
    c1: float,
    rho2: float,
    c2: float,
) -> NDArray[np.complex128]

reflection_coefficient(
    grazing_angle_deg: NumericArrayLike,
    *,
    rho1: float,
    c1: float,
    rho2: float,
    c2: float,
) -> complex | NDArray[np.complex128]
```

Complex plane-wave pressure reflection coefficient at the seabed.

**Parameters**

| Name | Description |
| :--- | :--- |
| `grazing_angle_deg` | Grazing angle(s) $\varphi$ from the interface, in degrees (`0` grazing to `90` normal incidence). |
| `rho1` | Water density $\rho_1$ (any consistent unit; kg/m³ by convention). |
| `c1` | Sound speed in the water `c1`, in m/s. |
| `rho2` | Sediment density $\rho_2$. |
| `c2` | Sound speed in the sediment `c2`, in m/s. |

**Returns:** The complex reflection coefficient per grazing angle. A `complex` 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 `c1`, `c2`, `rho1` or `rho2` is not a single number, or `grazing_angle_deg` holds a text or a value that is not a real number. |

## seabed_reflection

```python
seabed_reflection(
    grazing_angle_deg: NumericArrayLike,
    *,
    rho1: float = 1000.0,
    c1: float = 1500.0,
    rho2: float,
    c2: float,
) -> SeabedReflection
```

Build a plottable seabed reflection-coefficient result (Rayleigh
model).

Evaluates [`reflection_coefficient`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#reflection_coefficient) at `grazing_angle_deg` for the given
fluid-fluid interface and bundles the complex `R`, its magnitude `|R|`,
the bottom loss $\mathrm{BL} = -20 \log_{10} \lvert R \rvert$ and the
interface parameters into a [`SeabedReflection`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#seabedreflection) that exposes
`.plot()`. The maths is unchanged; this is a thin, plottable wrapper
around the existing function (the same `ValueError` cases apply). At an
angle of intromission $R = 0$ and the bottom loss is `inf` (total
transmission), returned without warning.

**Parameters**

| Name | Description |
| :--- | :--- |
| `grazing_angle_deg` | Grazing angle(s) $\varphi$ from the interface, in degrees (`0` grazing to `90` normal incidence). |
| `rho1` | Water density $\rho_1$ (default 1000 kg/m³). |
| `c1` | Sound speed in the water `c1`, in m/s (default 1500). |
| `rho2` | Sediment density $\rho_2$. |
| `c2` | Sound speed in the sediment `c2`, in m/s. |

**Returns:** A frozen [`SeabedReflection`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#seabedreflection).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are invalid. |
| TypeError | if `grazing_angle_deg` holds a text or a value that is not a real number. |

## SeabedReflection

```python
SeabedReflection(
    grazing_angle_deg: NDArray[np.float64],
    reflection_coefficient: NDArray[np.complex128],
    magnitude: NDArray[np.float64],
    bottom_loss: NDArray[np.float64],
    critical_angle_deg: float | None,
    rho1: float,
    c1: float,
    rho2: float,
    c2: float,
)
```

Plane-wave seabed reflection coefficient versus grazing angle.

Bundles the complex Rayleigh reflection coefficient `R` over a
grazing-angle grid with its magnitude `|R|`, the bottom loss
$\mathrm{BL} = -20 \log_{10} \lvert R \rvert$ and the fluid-fluid
interface parameters, so the classic `|R|` versus grazing-angle curve
can be drawn with `plot`. Build it with [`seabed_reflection`](https://docs.jmrp.io/phonometry/reference/api/underwater/seabed-reflection/#seabed_reflection);
the frozen instance is a thin, plottable wrapper and re-runs none of the
maths.

**Attributes**

| Name | Description |
| :--- | :--- |
| `grazing_angle_deg` | Grazing angles $\varphi$ from the interface, in degrees. |
| `reflection_coefficient` | Complex pressure reflection coefficient `R` per grazing angle. |
| `magnitude` | Reflection-coefficient magnitude `\|R\|` per grazing angle (`1` below the critical angle for a faster sediment). |
| `bottom_loss` | Bottom loss $\mathrm{BL} = -20 \log_{10} \lvert R \rvert$ per grazing angle, in dB. |
| `critical_angle_deg` | The critical grazing angle, in degrees, or `None` if the sediment is not faster than the water. |
| `rho1` | Water density $\rho_1$. |
| `c1` | Sound speed in the water `c1`, in m/s. |
| `rho2` | Sediment density $\rho_2$. |
| `c2` | Sound speed in the sediment `c2`, in m/s. |

### SeabedReflection.plot()

```python
SeabedReflection.plot(
    ax: Axes | None = None,
    *,
    language: Literal['en', 'es'] = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the reflection-coefficient magnitude `|R|` versus grazing angle.

Draws `|R|` on a linear grazing-angle axis (0..90°), marking the
critical angle when the sediment is faster than the water. Requires
matplotlib (the `[plot]` extra); returns the
`Axes` and never calls `plt.show`.

**Parameters**

| Name | Description |
| :--- | :--- |
| `ax` | Existing axes, or `None` to create a figure. |
| `language` | `"en"` (default) or `"es"`. |
| `kwargs` | Forwarded to the `\|R\|` curve `plot` call. |

**Returns:** The axes.
