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.

Quick start

Download the channel MAT-files from Zenodo 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")

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.

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; 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.

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

uwa_channels-0.6.7.tar.gz (23.8 kB view details)

Uploaded Aug 7, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

uwa_channels-0.6.7-py3-none-any.whl (11.4 kB view details)

Uploaded Aug 7, 2026 Python 3

File details

Details for the file uwa_channels-0.6.7.tar.gz.

File metadata

Download URL: uwa_channels-0.6.7.tar.gz
Upload date: Aug 7, 2026
Size: 23.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for uwa_channels-0.6.7.tar.gz
Algorithm	Hash digest
SHA256	`1d0c7bed498c6498ab55baef0d8f1cb128e32f0d2b4c8f78da8fca707e99e5ba`
MD5	`79eaedbc837cc87753813c427a3d927f`
BLAKE2b-256	`526800714eaa8ab89712c1571ed46e2fb98f208b31c3b212dd26bbb136c35a3a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for uwa_channels-0.6.7.tar.gz:

Publisher: ci.yaml on uwa-channels/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: uwa_channels-0.6.7.tar.gz
- Subject digest: 1d0c7bed498c6498ab55baef0d8f1cb128e32f0d2b4c8f78da8fca707e99e5ba
- Sigstore transparency entry: 2364849684
- Sigstore integration time: Aug 7, 2026
Source repository:
- Permalink: uwa-channels/python@c67d87c8855a9cbdf778dce7a8a166dbb34d6990
- Branch / Tag: refs/heads/main
- Owner: https://github.com/uwa-channels
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: ci.yaml@c67d87c8855a9cbdf778dce7a8a166dbb34d6990
- Trigger Event: push