underwater: seabed reflection
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.
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 , sound speed
c1) striking a fluid sediment half-space (, c2)
reflects with the Rayleigh pressure reflection coefficient (Medwin & Clay,
Eq. 2.6.11a). Using the grazing angle (measured from the
interface), the angle of incidence from the normal is
, Snell’s law gives
and
critical_angle: the critical grazing angle (only whenc2 > c1); below it the wave is totally reflected ().reflection_coefficient: the complexRper grazing angle.seabed_reflection: the complexR, its magnitude|R|and the bottom loss bundled with the interface parameters into aSeabedReflectionwhose.plot()draws|R|versus grazing angle.bottom_reflection_loss: the bottom loss (dB), returned as aBottomLossResultwith a.plot().
Lossless fluid-fluid model (real /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
Section titled “bottom_reflection_loss”bottom_reflection_loss( grazing_angle_deg: NumericArrayLike, *, rho1: float = 1000.0, c1: float = 1500.0, rho2: float, c2: float,) -> BottomLossResultBottom reflection loss versus grazing angle (dB).
At an angle of intromission 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) from the interface, in degrees. |
rho1 |
Water density (default 1000 kg/m³). |
c1 |
Sound speed in the water c1, in m/s (default 1500). |
rho2 |
Sediment density . |
c2 |
Sound speed in the sediment c2, in m/s. |
Returns: A 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
Section titled “BottomLossResult”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 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()
Section titled “BottomLossResult.plot()”BottomLossResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the bottom loss versus grazing angle with the critical angle.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
critical_angle
Section titled “critical_angle”critical_angle(c1: float, c2: float) -> floatCritical grazing angle , 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
Section titled “reflection_coefficient”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) from the interface, in degrees (0 grazing to 90 normal incidence). |
rho1 |
Water density (any consistent unit; kg/m³ by convention). |
c1 |
Sound speed in the water c1, in m/s. |
rho2 |
Sediment density . |
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
Section titled “seabed_reflection”seabed_reflection( grazing_angle_deg: NumericArrayLike, *, rho1: float = 1000.0, c1: float = 1500.0, rho2: float, c2: float,) -> SeabedReflectionBuild a plottable seabed reflection-coefficient result (Rayleigh model).
Evaluates reflection_coefficient at grazing_angle_deg for the given
fluid-fluid interface and bundles the complex R, its magnitude |R|,
the bottom loss and the
interface parameters into a 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 and the bottom loss is inf (total
transmission), returned without warning.
Parameters
| Name | Description |
|---|---|
grazing_angle_deg |
Grazing angle(s) from the interface, in degrees (0 grazing to 90 normal incidence). |
rho1 |
Water density (default 1000 kg/m³). |
c1 |
Sound speed in the water c1, in m/s (default 1500). |
rho2 |
Sediment density . |
c2 |
Sound speed in the sediment c2, in m/s. |
Returns: A frozen 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
Section titled “SeabedReflection”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
and the fluid-fluid
interface parameters, so the classic |R| versus grazing-angle curve
can be drawn with plot. Build it with 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 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 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 . |
c1 |
Sound speed in the water c1, in m/s. |
rho2 |
Sediment density . |
c2 |
Sound speed in the sediment c2, in m/s. |
SeabedReflection.plot()
Section titled “SeabedReflection.plot()”SeabedReflection.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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.