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 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file uwa_channels-0.6.4.tar.gz.
File metadata
- Download URL: uwa_channels-0.6.4.tar.gz
- Upload date:
- Size: 22.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
466f80d8570e1d2401b87ff1deb7c3d9bd8cc14536c18d0990f517f400ef8d12
|
|
| MD5 |
faffc8f3912d6366241c80ae96bc570b
|
|
| BLAKE2b-256 |
a639e14bf4a68751984ac04dd5a78657c0d21580cf1c7424649aadbb3ee79d54
|
Provenance
The following attestation bundles were made for uwa_channels-0.6.4.tar.gz:
Publisher:
ci.yaml on uwa-channels/python
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
uwa_channels-0.6.4.tar.gz -
Subject digest:
466f80d8570e1d2401b87ff1deb7c3d9bd8cc14536c18d0990f517f400ef8d12 - Sigstore transparency entry: 2124519834
- Sigstore integration time:
-
Permalink:
uwa-channels/python@5c6687f1c9b1541ccec768e8c6eb6191120866f6 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/uwa-channels
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yaml@5c6687f1c9b1541ccec768e8c6eb6191120866f6 -
Trigger Event:
push
-
Statement type:
File details
Details for the file uwa_channels-0.6.4-py3-none-any.whl.
File metadata
- Download URL: uwa_channels-0.6.4-py3-none-any.whl
- Upload date:
- Size: 11.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a93a303feea4dfb3ba8f70d4c38066264d53071635d2c724e298b81d19cc9160
|
|
| MD5 |
5127be6a3097108e85d5570a6b48e0bf
|
|
| BLAKE2b-256 |
ac964c8719e727a5023870ac81e4750f38a5013cd9ae1ed9c67f1ff3e795e9d1
|
Provenance
The following attestation bundles were made for uwa_channels-0.6.4-py3-none-any.whl:
Publisher:
ci.yaml on uwa-channels/python
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
uwa_channels-0.6.4-py3-none-any.whl -
Subject digest:
a93a303feea4dfb3ba8f70d4c38066264d53071635d2c724e298b81d19cc9160 - Sigstore transparency entry: 2124519877
- Sigstore integration time:
-
Permalink:
uwa-channels/python@5c6687f1c9b1541ccec768e8c6eb6191120866f6 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/uwa-channels
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yaml@5c6687f1c9b1541ccec768e8c6eb6191120866f6 -
Trigger Event:
push
-
Statement type:
