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 uwa-channels

Functions

Quick start

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

Replay and noise generation

from uwa_channels import replay, noisegen, load_channel, load_noise

channel = load_channel("blue_1.mat")
noise = load_noise("blue_noise.mat")

array_index = [0, 1, 2]
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.

Use load_channel / load_noise rather than h5py.File directly. The file-format specification asks for -v7.3 (HDF5), and h5py reads only that; MATLAB's save writes MAT v5 unless told otherwise. The loaders accept either flavour and return something replay, noisegen and unpack take unchanged — for a -v7.3 file they return the same open h5py.File as before.

Unpack

from uwa_channels import unpack, load_channel

channel = load_channel("blue_1.mat")
unpacked = unpack(fs_time, array_index, channel)

See examples/example_unpack.py for details.

Channel format

Each channel MAT-file contains:

Each noise MAT-file contains:

beta is normalized over the whole array: the expected noise powers of all M elements sum to M, and each element keeps its measured power relative to the others. A subset selected with array_index keeps the powers of its elements, so its sum need not equal the size of the subset.

Tests

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

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

Testing against the released files

The first four suites build their channels in memory, so they cannot catch a disagreement between the package and the files you actually download. test_zenodo starts from the files: it fetches black.mat and black_noise.mat (162 MB, checked against the MD5 digests Zenodo publishes), replays a BPSK probe through the channel, and checks that

• the arrival lands within two samples of fs_delay of where h_hat and the delay drift phi_hat / (2π f_c) say it should,
• the measured power-delay profile matches the one stored in h_hat,
• the generated noise has the spatial covariance beta prescribes, and
• both load_channel and load_noise read the released data identically from a -v7.3 and a MAT v5 copy.

Because of the download it is opt-in:

PYTHONPATH=src pytest tests/test_zenodo.py --zenodo

Files land in ~/.cache/uwa-channels, or in $UWA_CHANNELS_CACHE if you set it; point that at a directory where you already keep the library and nothing is downloaded. Once the files are there the suite runs as part of a plain pytest. UWA_CHANNELS_ZENODO=1 is equivalent to --zenodo.

Related repositories

License

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

© 2025–2026, Underwater Acoustic Channels Group.