bluepebble.simulator

Stone Soup-compatible simulator entrypoints for passive sonar array data generation.

Current primary simulator entrypoints are:

  • ContinuousSTFTPassiveSonarArraySimulator for broadband STFT-domain propagation and reconstruction.

  • DiscretePassiveSonarArraySimulator for discrete timestep broadband workflows.

  • ContinuousFractionalDelayPassiveSonarArraySimulator for continuous fractional-delay synthesis.

For compatibility with older notebooks, DeprecatedDiscretePassiveSonarArraySimulator remains available but is deprecated for new work. It emits a DeprecationWarning on instantiation.

PassiveSonarSensorData now lives in bluepebble.types and is documented with the types API surface.

Simulator package public API.

class bluepebble.simulator.PassiveSonarArraySimulatorBase(platform, propagation_model, noise_model=None, beamformer=None, steering_calculator=None, ground_truth_paths=None)[source]

Common base class for passive-sonar array simulators.

This class centralises properties and utility methods shared by discrete-time and continuous broadband simulator implementations.

Parameters:
platform: TowedArrayPlatform

Towed array platform

propagation_model: AcousticPropagationModel

Acoustic propagation model

noise_model: RandomSignal | None

Stochastic signal model (optional)

beamformer: Beamformer | None

Beamforming algorithm (optional)

steering_calculator: SteeringCalculator | None

Steering calculator (optional)

ground_truth_paths: list[GroundTruthPath]

List of GroundTruthPath objects

abstractmethod sensor_data_gen()[source]

Yield timestamped passive-sonar sensor snapshots.

Yields:

tuple of (datetime, set of PassiveSonarSensorData) – Timestamp and one-element sensor-data set for that timestamp.

Return type:

Iterator[tuple[datetime, set[PassiveSonarSensorData]]]

class bluepebble.simulator.ContinuousSTFTPassiveSonarArraySimulator(platform, propagation_model, signal_models, noise_model=None, beamformer=None, steering_calculator=None, ground_truth_paths=None, mode='stft_interp', fade_in_ms=100.0, fade_out_ms=100.0, norm_floor_ratio=0.001)[source]

Continuous broadband passive-sonar simulator with selectable STFT synthesis mode.

Use mode for channel update method. All three modes use the same propagation history, then differ in reconstruction method:

  • stft_interp and wola_interp common interpolation steps:

    1. De-rotate channel phase using per-sensor delay history (remove delay phase).

    2. Interpolate residual channel magnitude and unwrapped phase at frame-center times.

    3. Re-apply interpolated delay phase and form per-target frame spectra.

  • stft_interp

    1. Sum target spectra in the frequency domain.

    2. Reconstruct sensor time series with inverse_stft.

  • wola_interp

    1. IFFT each frame and accumulate with weighted overlap-add (WOLA).

    2. Normalize overlap energy to produce output sensor signals.

  • cola

    1. Select the nearest previous knot transfer function for each frame.

    2. Apply knot transfer function to each target source spectrum.

    3. IFFT and overlap-add frame signals.

    4. Apply COLA-style overlap normalization.

All modes share fades, noise addition, beamforming, and timestamp chunk output. In practice, each method produces largely similar results. The default stft_interp and wola_interp methods are recommended. The cola method can produce interference artefacts, but is good as a fast baseline.

Parameters:
signal_models: list[AnthropogenicSignal]

List of broadband signal models (one per target, or single-element list for all)

mode: str

Synthesis mode: stft_interp, wola_interp, or cola

fade_in_ms: float

Fade-in duration at arrival (ms)

fade_out_ms: float

Fade-out duration at end (ms)

norm_floor_ratio: float

Relative floor (fraction of max overlap weight) below which COLA/WOLA normalization is not applied to avoid edge gain blow-up

sensor_data_gen()[source]

Yield continuous broadband sensor snapshots using selected STFT mode.

Yields:

tuple of (datetime, set of PassiveSonarSensorData) – Timestamp and simulated sensor-data set for that timestep.

Raises:

ValueError – If fewer than two timesteps are available or the synthesis mode is unsupported.

Return type:

Iterator[tuple[datetime, set[PassiveSonarSensorData]]]

class bluepebble.simulator.DiscretePassiveSonarArraySimulator(platform, propagation_model, signal_models, noise_model=None, beamformer=None, steering_calculator=None, ground_truth_paths=None)[source]

Discrete broadband simulator with per-timestamp spectrum rendering.

This simulator synthesises one independent snapshot per platform timestamp. It is intended for broadband scenarios where each timestep can be processed as a standalone frame, without enforcing waveform continuity across adjacent timestamps.

Processing stages

  1. Resolve one signal model per target (or broadcast a single shared model).

  2. Build one full source waveform per target via get_source_waveform.

  3. Partition source waveforms into timestamp-aligned chunks using platform time spacing and sampling rate.

  4. For each timestamp, evaluate H(f) from propagate_spectrum at the chunk FFT bins for each active target.

  5. Apply H(f) in the frequency domain and IFFT per sensor, summing contributions from all targets.

  6. Add optional ambient noise, run optional beamforming, and emit one PassiveSonarSensorData payload.

Notes

  • This method does not interpolate transfer functions across timesteps.

  • No overlap-add or continuity smoothing is applied between emitted chunks.

  • Timestamp boundaries that produce zero-length chunks are clamped to a minimum one-sample snapshot to keep FFT processing valid.

Tradeoffs

  • Lower complexity and simpler reasoning than continuous STFT/WOLA methods.

  • Best suited to analyses where per-timestep independence is acceptable.

signal_models: list[BiologicalSignal]

List of broadband signal models (one per target, or single-element list for all)

sensor_data_gen()[source]

Yield one independent broadband snapshot per platform timestamp.

Yields:

tuple of (datetime, set of PassiveSonarSensorData) – Timestamp and simulated sensor-data set for that timestamp.

Raises:

  • AttributeError – If the configured propagation model does not implement propagate_spectrum.

  • ValueError – If signal model configuration is invalid.

Return type:

Iterator[tuple[datetime, set[PassiveSonarSensorData]]]

Parameters:
class bluepebble.simulator.ContinuousFractionalDelayPassiveSonarArraySimulator(platform, propagation_model, signal_models, noise_model=None, beamformer=None, steering_calculator=None, ground_truth_paths=None, fade_in_ms=100.0, fade_out_ms=100.0)[source]

Broadband simulator with sample-domain fractional-delay rendering.

This method avoids frame-wise channel interpolation and renders each sensor using time-varying fractional delay plus gain envelope:

y_s[n] = a_s[n] * x(n - tau_s[n] * fs)

Here tau_s[n] is interpolated absolute delay and a_s[n] is interpolated broadband gain. Broadband gain is estimated from propagate_spectrum using RMS magnitude across frequency bins.

Algorithm overview

  1. Build per-target source signals with matched lengths.

  2. Compute per-knot transfer functions and sensor delay history.

  3. Derive broadband gain history from |H_s(f)|.

  4. Interpolate gain and delay to per-sample trajectories.

  5. Fractionally resample and accumulate target contributions.

  6. Apply fades, noise, beamforming, and timestamp slicing.

(A knot is a tie point between simulation steps)

Tradeoffs

  • Strong arrival-time fidelity under fast geometry changes.

  • Lower spectral-detail fidelity than full complex frame-wise synthesis.

signal_models: list[AnthropogenicSignal]

List of broadband signal models (one per target, or single-element list for all)

fade_in_ms: float

Fade-in duration at arrival (ms)

fade_out_ms: float

Fade-out duration at end (ms)

sensor_data_gen()[source]

Yield broadband sensor snapshots via fractional-delay rendering.

Yields:

tuple of (datetime, set of PassiveSonarSensorData) – Timestamp and simulated sensor-data set for that timestep.

Raises:

  • ValueError – If fewer than two timesteps are available.

  • TypeError – If targets are present and the propagation model does not implement propagate_spectrum.

  • RuntimeError – If target source-signal lengths are inconsistent.

Return type:

Iterator[tuple[datetime, set[PassiveSonarSensorData]]]

Parameters: