bluepebble.models.propagation

Propagation models for analytical and rtrs-backed acoustic simulation workflows.

Propagation models public API.

class bluepebble.models.propagation.AcousticPropagationModel(ssp)[source]

An abstract base class for all acoustic propagation models.

It defines a common interface and implements shared functionality.

Parameters:

ssp (SoundSpeedProfile)

ssp: SoundSpeedProfile

Sound speed profile

abstractmethod propagate(platform, source)[source]

Propagate a signal from a source to a platform.

Notes

Subclasses must implement this method.

Parameters:

  • platform (Platform)

  • source (State)

Return type:

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

compute_sensor_delays(platform, source)[source]

Compute time delays for each sensor in an array.

The method calculates time-differences-of-arrival (TDOA) relative to the array reference sensor and accounts for sound speed at each sensor’s depth.

Parameters:

  • platform (Platform) – Platform object representing the sensor array.

  • source (State) – Source (State) object representing the acoustic point source.

Returns:

One-dimensional array of per-sensor delays in seconds.

Return type:

FloatArray

class bluepebble.models.propagation.CylindricalAcousticPropagationModel(ssp, attenuation_factor=0.5)[source]

A simple acoustic model based on cylindrical spreading and absorption loss.

This model provides a basic estimate of transmission loss without the computational overhead of more complex ray tracing methods.

Variables:

  • attenuation_factor (float) – The absorption loss factor in dB/km.

  • ssp (SoundSpeedProfile) – An instance of a sound speed profile.

Parameters:
attenuation_factor: float

The absorption loss factor in dB/km

propagate(platform, source)[source]

Propagate a signal using a cylindrical spreading loss model.

The model combines cylindrical spreading (10*log10(r)) with a frequency-independent absorption term.

Parameters:

  • platform (Platform) – Platform object representing the sensor array.

  • source (State) – Source (State) object representing the acoustic point source.

Returns:

  • tloss (float): Transmission loss in decibels (dB).

  • time (float): Direct-path travel time in seconds.

Return type:

PropagationResult

propagate_spectrum(platform, source, frequencies_hz)[source]

Propagate spectrum using cylindrical spreading.

Calculates complex transfer functions H(f) for each sensor and frequency, accounting for cylindrical spreading and frequency-dependent absorption.

Parameters:

  • platform (Platform) – Platform object representing the sensor array.

  • source (State) – Source (State) object representing the acoustic point source.

  • frequencies_hz (ArrayLike) – Array of frequencies in Hz for which to compute transfer functions.

Returns:

(H_sensors, propagation_time_s), where H_sensors is a complex transfer-function array with shape (num_sensors, num_frequencies) and propagation_time_s is the propagation time from the source to the reference sensor in seconds.

Return type:

SpectrumResult

class bluepebble.models.propagation.SpectrumPropagationModel[source]

Mixin ABC for propagation models that support frequency-domain transfer functions.

Inherit from this alongside AcousticPropagationModel to declare that a model implements propagate_spectrum(). Simulators use isinstance against this class to discover the capability at construction time rather than relying on hasattr.

abstractmethod propagate_spectrum(platform, source, frequencies_hz)[source]

Return per-sensor complex transfer functions and propagation time.

Parameters:

  • platform (Platform) – Platform state providing sensor array geometry.

  • source (State) – Source state providing position and metadata.

  • frequencies_hz (ArrayLike) – Frequency axis in Hz matching the desired FFT bins.

Returns:

Tuple (H_sensors, propagation_time_s) where H_sensors has shape (num_sensors, num_frequencies).

Return type:

SpectrumResult

class bluepebble.models.propagation.rtrsAcousticPropagationModel(ssp, bathymetry, step_m=15.0, ssp_resolution=(5000.0, 5000.0, 100.0), azimuth_search_width=1.0, azimuth_resolution=0.5, elevation_range=(-70.0, 70.0), elevation_resolution=1.0, use_all_frequencies=False, water_density_g_cm3=None, bottom_model=None, store_ray_paths=False, integration_method='euler')[source]

Representation of an rtrs acoustic propagation model.

Uses the rtrs Python bindings for 3D ray-tracing with support for 3D SSP and 2D bathymetry.

Variables:

  • ssp (SoundSpeedProfile) – An instance of a sound speed profile.

  • bathymetry (Bathymetry) – An instance of a bathymetry model.

  • step_m (float) – Ray tracing step size in meters (default 15.0).

  • ssp_resolution (tuple) – Resolution for SSP grid (x, y, z) in meters.

  • azimuth_search_width (float) – Angular width in degrees to search for azimuth angles that will hit the receiver.

  • azimuth_resolution (float) – Angular resolution for azimuth search in degrees.

  • elevation_range (tuple) – Minimum and maximum elevation angles in degrees.

  • elevation_resolution (float) – Angular resolution for elevation in degrees.

  • use_all_frequencies (bool) – If True, run rtrs for all tonal frequencies and return per-frequency TL values. If False, use only the loudest frequency.

  • water_density_g_cm3 (float | None) – Optional water density value passed to rtrs bathymetry config.

  • bottom_model (dict) – Bottom boundary model configuration for rtrs (e.g., rigid/acoustic/elastic).

  • store_ray_paths (bool) – Whether rtrs should store full ray paths.

  • integration_method (str) – Beam integration method for rtrs (“euler” or “rk2”).

Parameters:

  • ssp (SoundSpeedProfile)

  • bathymetry (Bathymetry)

  • step_m (float)

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

  • azimuth_search_width (float)

  • azimuth_resolution (float)

  • elevation_range (tuple[float, float])

  • elevation_resolution (float)

  • use_all_frequencies (bool)

  • water_density_g_cm3 (float | None)

  • bottom_model (dict[str, object] | None)

  • store_ray_paths (bool)

  • integration_method (str)

bathymetry: Bathymetry

Bathymetry model

step_m: float

Ray tracing step size in meters

ssp_resolution: tuple[float, float, float]

Resolution for SSP grid (x, y, z) in meters

azimuth_search_width: float

Angular width in degrees to search for azimuth angles

azimuth_resolution: float

Angular resolution for azimuth search in degrees

elevation_range: tuple[float, float]

Min and max elevation angles in degrees

elevation_resolution: float

Angular resolution for elevation in degrees

use_all_frequencies: bool

If True, run rtrs for all tonal frequencies. If False, use only the loudest frequency. Not used for propagated spectrum method.

water_density_g_cm3: float | None

Optional water density passed to rtrs bathymetry config (g/cm^3)

bottom_model: dict[str, object] | None

Bottom boundary model dictionary for rtrs

store_ray_paths: bool

If True, store full ray paths in rtrs output, not needed for Blue Pebble

integration_method: str

Beam integration method for rtrs (“euler” or “rk2”)

propagate(platform, source)[source]

Run an rtrs simulation for a single source and receiver.

The method prepares the rtrs environment, runs the ray-tracing simulation and returns transmission loss and travel time.

Parameters:

  • platform (Platform) – Object representing the sensor platform.

  • source (State) – Object representing the acoustic source.

Returns:

  • tloss (float or FloatArray): Transmission loss in dB. If use_all_frequencies is True, returns one value per frequency.

  • time (float): Direct-path travel time in seconds.

Return type:

PropagationResult

propagate_spectrum(platform, source, frequencies_hz)[source]

Run rtrs simulation for broadband spectrum propagation.

Computes complex transfer functions H(f) for each frequency bin and sensor. Suitable for STFT-based broadband processing where H(f) is applied to each STFT frame.

Parameters:

  • platform (Platform) – Sensor platform with array geometry.

  • source (State) – Acoustic source position.

  • frequencies_hz (ArrayLike) – Array of frequencies in Hz (from STFT bins).

Returns:

  • transfer_functionsComplex array of shape (num_sensors, num_frequencies)

    containing H(f).

  • propagation_time_s : Mean travel time in seconds.

Return type:

SpectrumResult

class bluepebble.models.propagation.SphericalAcousticPropagationModel(ssp, attenuation_factor=0.001)[source]

A simple acoustic model based on spherical spreading and absorption loss.

This model provides a basic estimate of transmission loss without the computational overhead of more complex ray tracing methods.

Variables:

  • attenuation_factor (float) – The absorption loss factor in dB/km.

  • ssp (SoundSpeedProfile) – An instance of a sound speed profile.

Parameters:
attenuation_factor: float

The absorption loss factor in dB/km

propagate(platform, source)[source]

Propagate a signal using a spherical spreading loss model.

The model combines spherical spreading (20*log10(r)) with a frequency-independent absorption term.

Parameters:

  • platform (Platform) – Platform object representing the sensor array.

  • source (State) – Source (State) object representing the acoustic point source.

Returns:

  • tloss (float): Transmission loss in decibels (dB).

  • time (float): Direct-path travel time in seconds.

Return type:

PropagationResult

propagate_spectrum(platform, source, frequencies_hz)[source]

Propagate spectrum using spherical spreading.

This method calculates transfer functions H(f) for each sensor and frequency, accounting for spherical spreading and frequency-dependent absorption.

Parameters:

  • platform (Platform) – Platform object representing the sensor array.

  • source (State) – Source (State) object representing the acoustic point source.

  • frequencies_hz (ArrayLike) – Array of frequencies in Hz for which to compute transfer functions.

Returns:

(H_sensors, propagation_time_s), where H_sensors is a complex transfer-function array with shape (num_sensors, num_frequencies) and propagation_time_s is the propagation time from the source to the reference sensor in seconds.

Return type:

SpectrumResult