uwa-channels 0.5.0

Replay, noise generation, and unpacking for measured underwater acoustic channels.

Underwater Acoustic Channel Toolbox — Python

Python toolbox for replaying signals through measured underwater acoustic channels, generating realistic ocean noise, and unpacking stored impulse responses. To learn more about the channels, check out the documentation.

Please report bugs and suggest enhancements by creating a new issue. We welcome your feedback. See CONTRIBUTING.md for more information.

Installation

pip install -i https://test.pypi.org/simple/ uwa-channels

Functions

Function	Description
replay	Pass a passband signal through a measured underwater acoustic channel.
noisegen	Generate realistic ocean noise: pink Gaussian (17 dB/decade), spatially-correlated Gaussian, or impulsive (symmetric α-stable).
unpack	Reconstruct the full time-varying impulse response from the compressed representation.

Quick start

Download the channel MAT-files from here and place them in your working directory.

Replay and noise generation

import h5py
from uwa_channels import replay, noisegen

channel = h5py.File("blue_1.mat", "r")
noise = h5py.File("blue_1_noise.mat", "r")

y = replay(input, fs, array_index, channel)
w = noisegen(y.shape, fs, array_index, noise)
r = y + 0.05 * w

See examples/example_replay.py for a complete example that generates a BPSK signal, replays it through the blue_1 channel, adds noise, and plots the received signal, cross-correlation, and spectrum.

Unpack

import h5py
from uwa_channels import unpack

channel = h5py.File("blue_1.mat", "r")
unpacked = unpack(fs_time, array_index, channel)

See examples/example_unpack.py for details.

Channel format

Each channel MAT-file contains:

Variable	Description
h_hat	Estimated impulse response, shape (K, M, T)
theta_hat or phi_hat	Phase or delay-phase trajectory, shape (M, N)
params	Group with fs_delay, fs_time, fc
meta	Estimation metadata (see estimate repo)
version	File format version

Each noise MAT-file contains:

Field	Description
Fs	Sampling rate at which noise statistics were measured [Hz]
R	Signal bandwidth [Hz]
alpha	Stability index (2 = Gaussian, < 2 = impulsive)
beta	Mixing coefficients, shape (M, M, K)
fc	Center frequency [Hz]
rms_power	Per-channel RMS power scaling, shape (M, 1)
version	Noise struct version

Tests

This repository includes automated testing via GitHub Actions. The tests folder contains three test suites:

Test	What it verifies
test_replay	Generates random mobile channels ({static, mobile} × {theta_hat, phi_hat}), transmits a signal, and checks that cross-correlation peaks match the true multipath structure.
test_noisegen	Verifies output size, spectral shape (17 dB/decade), spatial correlation (theoretical vs. sample), bandpass filtering, rms_power scaling, Gaussianity (α = 2), and heavy-tail behavior (α < 2).
test_unpack	Tests all tracking modes (none, theta_hat, phi_hat, f_resamp, and combinations) for correct impulse response reconstruction.

Tests run automatically on every push, ensuring continued correctness of the core functions.

Related repositories

Repository	Description
uwa-channels/matlab	MATLAB/Octave implementation of the replay toolbox.
uwa-channels/estimate	Channel estimation from single-carrier signals, with visualization.

License

The license is available in the LICENSE file within this repository.

© 2025–2026, Underwater Acoustic Channels Group.