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

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.
`load_channel`, `load_noise`	Open a channel or noise MAT-file saved either with or without `-v7.3`.

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. red_noise.mat in the v1.0 Zenodo release is a MAT v5 file, so h5py.File("red_noise.mat", "r") fails with OSError: file signature not found. The loaders open either flavour and return something replay, noisegen and unpack accept unchanged — for a -v7.3 file they return the same open h5py.File as before. The same applies to a channel you estimate yourself, since MATLAB's save writes v5 unless told otherwise.

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:

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; also checks that `array_index` isolates individual hydrophones and that the output power scaling is O(1).
`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.

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.

Metadata

Release files for uwa-channels 0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uwa-channels 0.7
File	Size	Uploaded
uwa_channels-0.7.tar.gz	29.9 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for uwa-channels 0.7
File	Interpreter	ABI	Platform	Reset
uwa_channels-0.7-py3-none-any.whl 14.9 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 44.8 kB

Release files / uwa_channels-0.7.tar.gz

Download URL	uwa_channels-0.7.tar.gz
Size	29.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`f653c67151e614a9777a31187900add447bdcd62b367ad3d1f38f8c1ffaf2458`
BLAKE2b-256 checksum How to use checksums	`e5f5808f554b8263ca85a2ad6b4dad122d4cae266a1b3d3a8e7567435c142175`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/uwa-channels/python
Publishing commit: github.com/uwa-channels/python/tree/908c4a0b38c03b2edfc8db52d990c5ba2afb4904

Workflow

Publishing configuration: github.com/uwa-channels/python/blob/908c4a0b38c03b2edfc8db52d990c5ba2afb4904/.github/workflows/ci.yaml
Publishing logs: github.com/uwa-channels/python/actions/runs/35001989834/attempts/1

Artifact

Subject: uwa_channels-0.7.tar.gz
SHA-256 checksum: f653c67151e614a9777a31187900add447bdcd62b367ad3d1f38f8c1ffaf2458 Verifying attestations

Release files / uwa_channels-0.7-py3-none-any.whl

Download URL	uwa_channels-0.7-py3-none-any.whl
Size	14.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`67d5eb7bfb7957586b361790773446fc14a05d888aa16713c8d845ba2f71fbb3`
BLAKE2b-256 checksum How to use checksums	`d2fc1a1cbec97d83f7c8200aece53880f2fd26d75d0f925def8bc4706fc4f403`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/uwa-channels/python
Publishing commit: github.com/uwa-channels/python/tree/908c4a0b38c03b2edfc8db52d990c5ba2afb4904

Workflow

Publishing configuration: github.com/uwa-channels/python/blob/908c4a0b38c03b2edfc8db52d990c5ba2afb4904/.github/workflows/ci.yaml
Publishing logs: github.com/uwa-channels/python/actions/runs/35001989834/attempts/1

Artifact

Subject: uwa_channels-0.7-py3-none-any.whl
SHA-256 checksum: 67d5eb7bfb7957586b361790773446fc14a05d888aa16713c8d845ba2f71fbb3 Verifying attestations