bluepebble.models.environment

Environment models for bathymetry and sound-speed profile definition.

Environment models public API.

class bluepebble.models.environment.Arctan(surface_speed=1500.0, mid_depth=1000.0, steepness=0.005)[source]

Arctan sound speed profile model.

This model describes the sound speed profile using an arctangent function, which can represent a smooth transition in sound speed with depth.

Variables:

  • surface_speed (float) – The speed of sound at the surface in m/s. Defaults to 1500.0 m/s.

  • mid_depth (float) – The depth at which the sound speed transition occurs in meters. Defaults to 1000.0 m.

  • steepness (float) – The steepness of the transition. Higher values result in a sharper transition. Defaults to 0.005.

Parameters:

  • surface_speed (float)

  • mid_depth (float)

  • steepness (float)

surface_speed: float

Speed of sound at the surface in m/s

mid_depth: float

Depth at which sound speed transition occurs in meters

steepness: float

Steepness of the transition

calculate(depth)[source]

Calculate sound speed using the arctan profile.

Parameters:

depth (DepthInput) – Depth in meters. If negative (z-coordinate), converts to positive depth below surface for calculation.

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

class bluepebble.models.environment.Bathymetry(resolution=1000.0)[source]

Abstract base class for bathymetry models.

Parameters:

resolution (float)

resolution: float

Default grid resolution in meters for gridded outputs

abstractmethod get_depth(x, y)[source]

Get the seafloor depth at a given (x, y) position.

Parameters:

  • x (float) – X coordinate in meters.

  • y (float) – Y coordinate in meters.

Returns:

Depth in meters (positive value below surface).

Return type:

float

Notes

Implementations must override this abstract method.

abstractmethod get_grid(x_range, y_range)[source]

Get a gridded representation of the bathymetry.

Parameters:

  • x_range (Range1D) – Tuple of (x_min, x_max) in meters.

  • y_range (Range1D) – Tuple of (y_min, y_max) in meters.

  • resolution (float, optional) – Grid resolution in meters (defaults to resolution).

Returns:

(x_grid, y_grid, z_grid) where - x_grid : 1D array of x coordinates - y_grid : 1D array of y coordinates - z_grid : 2D array of depths (positive, below surface)

Return type:

GridResult

Notes

Implementations must override this abstract method.

class bluepebble.models.environment.Constant(speed=1500.0)[source]

Constant sound speed profile model.

This model assumes a uniform sound speed throughout the water column.

Variables:

speed (float) – Constant sound speed in m/s.

Parameters:

speed (float)

speed: float

Constant sound speed in m/s

calculate(depth)[source]

Return the constant sound speed.

Parameters:

depth (DepthInput) – Depth in meters (not used in this model).

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

class bluepebble.models.environment.FlatBathymetry(resolution=1000.0, depth=-5000.0)[source]

A flat seafloor bathymetry model.

Variables:

depth (float) – The constant depth of the seafloor in meters. Must be negative (below surface, Blue Pebble -z convention). Defaults to -5000.0 m.

Parameters:

  • resolution (float)

  • depth (float)

depth: float

Constant depth of the seafloor in meters

get_depth(x, y)[source]

Get the seafloor depth (constant everywhere).

Parameters:

  • x (float) – X coordinate in meters (ignored).

  • y (float) – Y coordinate in meters (ignored).

Returns:

Constant depth in meters.

Return type:

float

get_grid(x_range, y_range)[source]

Get a gridded representation of the flat bathymetry.

Parameters:

  • x_range (Range1D) – Tuple of (x_min, x_max) in meters.

  • y_range (Range1D) – Tuple of (y_min, y_max) in meters.

  • resolution (float, optional) – Grid resolution in meters (defaults to resolution).

Returns:

(x_grid, y_grid, z_grid) where z_grid is constant.

Return type:

GridResult

class bluepebble.models.environment.GEBCOBathymetry(file_path, resolution=1000.0, reference_lat_deg=None, reference_lon_deg=None)[source]

Bathymetry model backed by a GEBCO NetCDF dataset.

Notes

  • Coordinates are converted from lat/lon to local Cartesian meters.

  • Internally and at output, depth follows the convention -z underwater.

Parameters:

  • file_path (str)

  • resolution (float)

  • reference_lat_deg (float | None)

  • reference_lon_deg (float | None)

file_path: str

Path to GEBCO NetCDF file

reference_lat_deg: float | None

Reference latitude for local x/y conversion. Defaults to dataset midpoint.

reference_lon_deg: float | None

Reference longitude for local x/y conversion. Defaults to dataset midpoint.

get_depth(x, y)[source]

Get nearest-neighbour GEBCO depth at (x, y) in meters (-z).

Parameters:

  • x (float)

  • y (float)

Return type:

float

get_grid(x_range, y_range)[source]

Get a regular GEBCO bathymetry grid for the requested x/y extent.

Parameters:

  • x_range (tuple[float, float])

  • y_range (tuple[float, float])

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

class bluepebble.models.environment.LeroyCopernicusSoundSpeedProfile(temperature_file_path, salinity_file_path, reference_lat_deg=None, reference_lon_deg=None, fill_speed_m_s=1480.0)[source]

SSP model built from Copernicus temperature/salinity using the Leroy equation.

Notes

  • Copernicus depth is expected in oceanographic convention (+z downward).

  • calculate accepts -z depth inputs and internally uses abs(depth).

  • get_3d_grid returns z_grid in RTRS convention (+z downward).

Parameters:

  • temperature_file_path (str)

  • salinity_file_path (str)

  • reference_lat_deg (float | None)

  • reference_lon_deg (float | None)

  • fill_speed_m_s (float)

temperature_file_path: str

Path to Copernicus temperature NetCDF file

salinity_file_path: str

Path to Copernicus salinity NetCDF file

reference_lat_deg: float | None

Reference latitude for local x/y conversion. Defaults to dataset midpoint.

reference_lon_deg: float | None

Reference longitude for local x/y conversion. Defaults to dataset midpoint.

fill_speed_m_s: float

Fallback fill value for columns with no finite Copernicus values.

calculate(depth)[source]

Calculate representative sound speed at depth using a domain-mean profile.

Parameters:

depth (float | ArrayLike)

Return type:

float | ndarray[tuple[Any, …], dtype[float64]]

get_3d_grid(x_range, y_range, z_range, x_res=5000.0, y_res=5000.0, z_res=100.0)[source]

Get a regular SSP cube resampled from Copernicus data for RTRS.

Parameters:

  • x_range (tuple[float, float])

  • y_range (tuple[float, float])

  • z_range (tuple[float, float])

  • x_res (float)

  • y_res (float)

  • z_res (float)

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

class bluepebble.models.environment.Linear(surface_speed=1500.0, gradient=0.017)[source]

Linear sound speed profile model.

This model assumes that the sound speed varies linearly with depth.

Variables:

  • surface_speed (float) – Sound speed at the surface in m/s.

  • gradient (float) – Sound speed gradient in s^-1 (change per meter).

Parameters:

  • surface_speed (float)

  • gradient (float)

surface_speed: float

Sound speed at the surface in m/s

gradient: float

Sound speed gradient in s^-1 (change per meter)

calculate(depth)[source]

Calculate sound speed using a linear profile.

Parameters:

depth (DepthInput) – Depth in meters. If negative (z-coordinate), converts to positive depth below surface for calculation.

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

class bluepebble.models.environment.Mackenzie[source]

Mackenzie sound speed profile model.

This model calculates the sound speed using the nine-term Mackenzie equation, which is an empirical formula based on temperature, salinity, and depth. This implementation uses internal models for temperature and salinity as a function of depth.

calculate(depth)[source]

Calculate sound speed using the Mackenzie nine-term equation.

Parameters:

depth (DepthInput) – Depth in meters. If negative (z-coordinate), converts to positive depth below surface for calculation.

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

class bluepebble.models.environment.Munk(surface_speed=1500.0)[source]

Munk sound speed profile model.

This model describes the sound speed profile using an analytical equation proposed by Walter Munk. It is characterised by a deep sound channel axis and is widely used in ocean acoustics.

Variables:

surface_speed (float) – The speed of sound at the surface in m/s. Defaults to 1500.0 m/s.

Parameters:

surface_speed (float)

surface_speed: float

Speed of sound at the surface in m/s

calculate(depth)[source]

Calculate sound speed using the Munk equation.

Parameters:

depth (DepthInput) – Depth in meters. If negative (z-coordinate), converts to positive depth below surface for calculation.

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

class bluepebble.models.environment.SeamountBathymetry(resolution=1000.0, summit_position=(25000.0, 25000.0, -1000.0), radius=15000.0, plateau_depth=-5000.0)[source]

A bathymetry model with an idealized seamount feature.

Variables:

  • summit_position (tuple) – (x, y, z) coordinates of the summit in meters. Defaults to (25000.0, 25000.0, -1000.0).

  • radius (float) – Radius of the seamount in meters. Defaults to 15000.0 m.

  • plateau_depth (float) – Depth at the surrounding plateau in meters. Defaults to -5000.0 m.

Parameters:

  • resolution (float)

  • summit_position (tuple[float, float, float])

  • radius (float)

  • plateau_depth (float)

summit_position: tuple[float, float, float]

(x, y, z) coordinates of the summit in meters

radius: float

Radius of the seamount in meters

plateau_depth: float

Depth at the surrounding plateau in meters

get_depth(x, y)[source]

Get the seafloor depth at a given position.

Parameters:

  • x (float) – X coordinate in meters.

  • y (float) – Y coordinate in meters.

Returns:

Depth in meters at (x, y).

Return type:

float

get_grid(x_range, y_range)[source]

Get a gridded representation of the seamount bathymetry.

Parameters:

  • x_range (Range1D) – Tuple of (x_min, x_max) in meters.

  • y_range (Range1D) – Tuple of (y_min, y_max) in meters.

  • resolution (float, optional) – Grid resolution in meters (defaults to resolution).

Returns:

(x_grid, y_grid, z_grid) with seamount topography.

Return type:

GridResult

class bluepebble.models.environment.SoundSpeedProfile[source]

Abstract base class for sound speed profile models.

abstractmethod calculate(depth)[source]

Calculate the sound speed at a given depth.

Parameters:

depth (DepthInput) – Depth in meters. Can be positive (oceanographic convention, measured downward from surface) or negative (3D coordinate system where surface == 0 and underwater is negative z).

Returns:

Sound speed in m/s.

Return type:

SpeedOutput

get_3d_grid(x_range, y_range, z_range, x_res=5000.0, y_res=5000.0, z_res=100.0)[source]

Get a 3D grid representation of the sound speed profile.

Parameters:

  • x_range (Range1D) – Tuple of (x_min, x_max) in meters.

  • y_range (Range1D) – Tuple of (y_min, y_max) in meters.

  • z_range (Range1D) – Tuple of (z_min, z_max) in meters (negative depths).

  • x_res (float, optional) – Grid resolution in x direction in meters (default 5000.0).

  • y_res (float, optional) – Grid resolution in y direction in meters (default 5000.0).

  • z_res (float, optional) – Grid resolution in z direction in meters (default 100.0).

Returns:

(x_grid, y_grid, z_grid, c_grid) where - x_grid : 1D array of x coordinates - y_grid : 1D array of y coordinates - z_grid : 1D array of z coordinates (negative depths) - c_grid : 3D array of sound speeds, flattened in C order

Return type:

Grid3DResult

class bluepebble.models.environment.WedgeBathymetry(resolution=1000.0, depth_at_origin=-1000.0, x_gradient=0.0, y_gradient=0.001)[source]

A linearly sloping seafloor bathymetry model.

Variables:

  • depth_at_origin (float) – Depth at the origin (0, 0) in meters. Defaults to -1000.0 m.

  • x_gradient (float) – Depth gradient in the x direction (m/m). Defaults to 0.0 (no slope in x).

  • y_gradient (float) – Depth gradient in the y direction (m/m). Defaults to 0.001 (1 m increase per 1000 m in y).

Parameters:

  • resolution (float)

  • depth_at_origin (float)

  • x_gradient (float)

  • y_gradient (float)

depth_at_origin: float

Depth at the origin (0, 0) in meters

x_gradient: float

Depth gradient in the x direction (m/m)

y_gradient: float

Depth gradient in the y direction (m/m)

get_depth(x, y)[source]

Get the seafloor depth at a given position.

Parameters:

  • x (float) – X coordinate in meters.

  • y (float) – Y coordinate in meters.

Returns:

Depth in meters at (x, y).

Return type:

float

get_grid(x_range, y_range)[source]

Get a gridded representation of the sloping bathymetry.

Parameters:

  • x_range (Range1D) – Tuple of (x_min, x_max) in meters.

  • y_range (Range1D) – Tuple of (y_min, y_max) in meters.

  • resolution (float, optional) – Grid resolution in meters (defaults to resolution).

Returns:

(x_grid, y_grid, z_grid) with linearly varying depths.

Return type:

GridResult