-lightgrey.svg){kind=icon}
For decades, underwater acoustic propagation models have been implemented in highly optimized Fortran/C code. For many years, wrapping these models in MATLAB was the natural solution adopted by the scientific community. As Python has become a dominant language in scientific computing, a noticeable gap has emerged. Despite multiple efforts to wrap or re-implement these models, Python users still lack a unified, comprehensive, and up-to-date solution.
UACPY is an attempt to close that gap.
It was created for researchers, engineers, oceanographers, and acousticians
who need underwater acoustic modeling to be more open, consistent,
transparent, and reproducible. It builds on decades of pioneering work in
the field and aims to provide a shared foundation for comparing models,
validating results, running experiments, and developing new ideas.
This project began as an AI-assisted (Claude Code with Sonnet 4.5, Opus 4.6 and 4.7) initiative to reduce early development time, but starting with the first release, it will be maintained manually by its author—without autonomous AI-driven modifications.
Community feedback, verification, and contributions are warmly encouraged. The project’s success depends on collective effort; the codebase is far too large and complex for one person to maintain alone in their spare time. The goal is for this module to be truly community-driven.
⚠️ Note: UACPY is not production‑ready. Expect missing features, inconsistencies, and the need for validation.
A unified Python API over the classical underwater‑acoustic propagation
models — consistent Environment / Source / Receiver construction and
Result objects — plus first‑class toolkits for everything around them.
Propagation models
| Model | Kind |
|---|---|
| Bellhop | Ray / beam tracing |
| Kraken | Normal modes |
| Scooter | Finite elements for range independant env |
| SPARC | Experimental time-marched FFP for pulses in range independant env |
| RAM | Parabolic equation |
| OASES | OAST (TL) · OASN (covariance / MFP replicas) · OASR (reflection) · OASP (broadband TRF) |
| Bounce | Reflection coefficients |
Toolkits — first‑class modules, not just glue around the models:
- Signal processing (
uacpy.acoustic_signal) — waveforms, matched filtering / pulse compression, conventional & adaptive beamforming, time‑frequency & invertible transforms (f‑k, τ‑p/Radon, wavelet, Wigner–Ville, cepstrum), channel simulation, modal warping, spectra. - Sonar performance (
uacpy.sonar) — sonar equation, scattering laws, reverberation, detection theory & range. - Communications (
uacpy.comms) — PSK/QAM/DPSK/FSK, adaptive DFE/LMS/RLS + carrier PLL, Doppler, OFDM, Viterbi FEC, DSSS, end‑to‑end real‑data.wavmodems, and the open NATO JANUS standard (STANAG 4748). - Ambient noise (
uacpy.noise) — Wenz curves (wind / shipping / rain / thermal). - Standards & metrics — UNESCO/Del Grosso sound speed, ISO 18405 decidecade bands, ISO 17208 ship source level, Southall 2019 marine‑mammal weighting.
- Visualization — TL maps, rays, modes, fields, cross‑model comparisons.
Linux is the primary supported platform. macOS works with Homebrew. Windows is supported via WSL2 (Windows Subsystem for Linux) — see the Windows section below for why and how.
What install.sh builds:
| Tool | Required for |
|---|---|
python3 |
Driving install.sh and importing uacpy (always) |
gfortran, make |
OALIB, mpiramS, ramsurf (rams0.5 elastic + ramsurf1.5 rough surface), OASES (Fortran models — always) |
git |
Cloning uacpy + submodules (always) |
tar |
Submodule unpacking + OASES archive (always) |
cmake, g++/clang++ |
C++ Bellhop variant (--bellhop cxx) |
CUDA toolkit (nvcc) |
GPU Bellhop variant (--bellhop cuda) — required when --bellhop cuda is passed; the installer hard-errors if nvcc is absent (no silent downgrade to cxx) |
curl |
OASES archive download (--oases yes) |
install.sh verifies these are present and aborts with a clear
message if anything is missing — it does not install system packages
itself. Provision the toolchain once for your platform, then run the
build.
1. Install dependencies
# Debian / Ubuntu
sudo apt-get update
sudo apt-get install -y gfortran make git \
cmake g++ curl tar python3-venv python3-pip
# Fedora / RHEL
sudo dnf install -y gcc-gfortran make git \
cmake gcc-c++ curl tar python3-virtualenv python3-pip
# Arch / Manjaro
sudo pacman -S --needed gcc-fortran make git \
cmake gcc curl tar python python-pipFor GPU Bellhop, additionally install the CUDA toolkit from your distribution or NVIDIA's site.
2. Clone, create venv, install
git clone --recurse-submodules https://github.com/ErVuL/uacpy.git
cd uacpy
python3 -m venv uacpy_venv
source uacpy_venv/bin/activate
pip install -e .
./install.sh./install.sh runs interactively by default. Useful flags:
| Flag | Effect |
|---|---|
-y / --yes |
Non-interactive — auto-detect everything |
--bellhop fortran |
Skip the C++ build (Fortran Bellhop is always built) |
--bellhop cxx |
Also build C++ Bellhop (CPU) |
--bellhop cuda |
Also build CUDA Bellhop (GPU, requires nvcc) |
--oases yes / no |
Download + build OASES (or skip the prompt) |
--force |
Skip incremental builds; do a full clean rebuild of every selected component |
1. Install dependencies
# Install Homebrew (skip if 'brew' is already on PATH). See https://brew.sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Xcode Command Line Tools (provides make, clang, git, tar)
xcode-select --install
# Build dependencies. The 'gcc' formula provides gfortran on macOS.
brew install gcc cmake curl pythonCUDA Bellhop is not available on macOS (no NVIDIA toolkit). The C++
Bellhop variant (--bellhop cxx) builds fine with Apple's clang.
2. Clone, create venv, install
git clone --recurse-submodules https://github.com/ErVuL/uacpy.git
cd uacpy
python3 -m venv uacpy_venv
source uacpy_venv/bin/activate
pip install -e .
./install.sh(See the Linux section above for install.sh flags — they're identical
on macOS.)
uacpy on Windows runs inside WSL2 (Windows Subsystem for Linux), following the Linux instructions above.
WSL2 needs CPU virtualization extensions. Some computer ship with this disabled by default, so first of all enable hardware virtualization in your BIOS/UEFI.
In an elevated PowerShell (Run as Administrator):
wsl --install -d UbuntuReboot when prompted. Open Ubuntu (Start menu → "Ubuntu") and follow the Linux / Debian recipe from above:
sudo apt-get update
sudo apt-get install -y gfortran make git \
cmake g++ curl tar python3-venv python3-pip
cd ~
git clone --recurse-submodules https://github.com/ErVuL/uacpy.git
cd uacpy
python3 -m venv uacpy_venv
source uacpy_venv/bin/activate
pip install -e .
./install.sh -yTip: clone into the WSL filesystem (
~/uacpy), not into/mnt/c/.... Cross-filesystem I/O is 10–20× slower and the Acoustics-Toolbox build does a lot of small file writes.
pip uninstall uacpy
rm -rf uacpyA Pekeris waveguide — isovelocity water over a fluid half-space — at 1 kHz, plotted as a transmission-loss field.
import numpy as np
import matplotlib.pyplot as plt
import uacpy
from uacpy.models import Bellhop, RunMode
from uacpy.visualization import plot_field
# 1. Environment — isovelocity water over a fluid half-space bottom
env = uacpy.Environment(
name="Pekeris Waveguide",
bathymetry=100.0,
ssp=1500.0,
bottom=uacpy.BoundaryProperties(
acoustic_type='half-space',
sound_speed=1600.0,
density=1.5,
attenuation=0.5,
),
)
# 2. Source — 1000 Hz, mid water column
source = uacpy.Source(depths=50.0, frequencies=1000.0)
# 3. Receiver grid — 200 depths × 500 ranges out to 5 km
# Start ranges at the step size; r=0 has no ray data (Bellhop sentinel).
receiver = uacpy.Receiver(
depths=np.linspace(0, 100, 200),
ranges=np.linspace(10, 5000, 500),
)
# 4. Run Bellhop in coherent-TL mode
result = Bellhop(beam_type='B', n_beams=300, alpha=(-80, 80)).run(
env, source, receiver, run_mode=RunMode.COHERENT_TL,
)
# 5. Plot the TL field
fig, ax = plt.subplots(figsize=(8, 4))
plot_field(result, env=env, ax=ax)
plt.tight_layout()
plt.show()
The full API reference lives in a single file:
DOCUMENTATION.md — quick start, environment setup,
per-model signatures, visualization, signal processing, noise, units, and
troubleshooting.
Inside uacpy/uacpy/examples/ you will find 36 example scripts numbered
sequentially (example_01_*.py through example_36_*.py) — from a first
TL field to communications modems and a standards-based noise-impact
assessment. See the
examples index for a description
of each one.
UACPY uses pytest with custom markers for categorizing tests.
pytest and pytest-xdist are no longer pulled in by the runtime
dependency set — install the test extra to get them, or the dev extra
for the additional formatting / linting / coverage tooling:
# For running the test suite
pip install -e ".[test]"
# For development (test deps + black, flake8, pytest-cov)
pip install -e ".[dev]"Note: With macOS you may need to use pip install -e .\[xxx\].
cd uacpy
pytest uacpy/tests/
Tests use custom markers to allow selective execution:
slow-- Long-running tests (broadband, large grids, slow examples)requires_binary-- Tests that need compiled native binaries (Fortran/C)requires_oases-- Tests that need compiled OASES binaries
# Skip slow tests
pytest uacpy/tests/ -m "not slow"
# Run only tests that don't need compiled binaries
pytest uacpy/tests/ -m "not requires_binary"
# Skip OASES tests (if OASES is not installed)
pytest uacpy/tests/ -m "not requires_oases"
Because the initial codebase was LLM‑bootstrapped, auditing comes before new features. Both lists are contributor checklists — open an issue or PR for anything you investigate. Full diffs of in‑tree native‑model changes live in MODIFICATIONS.md.
- 🧱 API audit
- 🔬 Native model re‑validation
- 🐍 Python‑side review
- 📊 Visualization review
- 🧪 Test suite audit
- 📦 Build, install, packaging
- 🔁 CI / CD
If you are evaluating UACPY for a project: do not trust any specific number it produces until the re‑validation items above have been verified for the model and regime you care about.
- Model features — coverage of every native model option, GPU acceleration for more models, full 3‑D propagation.
- Environmental data — global bathymetry (GEBCO, SRTM), NOAA / IOOS / CMEMS oceanographic fields, on‑the‑fly extraction / caching / mesh generation.
- Framework — scenario‑based batch simulations, reproducible experiment containers, interactive TL / mode dashboards.
UACPY would not exist without decades of prior work by the underwater acoustics community. Every propagation model shipped here was designed, implemented, and validated elsewhere --- UACPY only provides a unified Python interface around them. Which codebases are vendored vs modified is summarised in the licensing table; full diffs for modified sources live in MODIFICATIONS.md.
Michael B. Porter --- http://oalib.hlsresearch.com/AcousticsToolbox/
- Porter, The BELLHOP Manual and User's Guide, 2011
- Porter, The KRAKEN Normal Mode Program, 1992
C. S. Schmid, D. F. Schmidt, A. E. Hodgson --- https://github.com/A-New-BellHope/bellhopcuda
- BellhopCUDA: High-Performance Acoustical Ray Tracing on GPUs, 2020
Michael D. Collins (Naval Research Laboratory)
- Collins, "A split-step Padé solution for the parabolic equation method," JASA, 1993
Brian D. Dushaw --- https://zenodo.org/records/10818570
Vendored from the Quiet Oceans repackaging of David C. Calvo's NRL distribution --- https://github.com/quiet-oceans/ramsurf
- Collins, A split-step Padé solution for the parabolic equation method, JASA, 1993
- Collins, Higher-order parabolic approximations for accurate and stable elastic parabolic equations with application to interface wave propagation, JASA, 1991 (RAMS / elastic)
- Collins, Generalization of the split-step Padé solution (variable surface / ramsurf), JASA 97, 2767–2770, 1995
Henrik Schmidt (Massachusetts Institute of Technology) --- https://acoustics.mit.edu/faculty/henrik/oases.html
Mandar Chitre (Acoustic Research Lab, National University of Singapore) --- https://github.com/org-arl/arlpy
Utility functions adapted into uacpy/core/acoustics.py preserve Mandar
Chitre's 2016 copyright header and cite arlpy as the source.
UACPY aggregates code from multiple projects, each under its own license. Downstream users are responsible for respecting each license when redistributing or modifying UACPY or its outputs.
| Component | Location | How it ships | License |
|---|---|---|---|
| UACPY wrapper | this repository | source + Python package | GPL-3.0 |
| Acoustics Toolbox (Porter) | third_party/Acoustics-Toolbox/ |
vendored Fortran sources, modified | GPL-3.0 |
| bellhopcuda (Schmid et al.) | third_party/bellhopcuda/ |
git submodule pinned to upstream v1.5, unmodified |
GPL-3.0 |
| mpiramS (Dushaw) | third_party/mpiramS/ |
vendored Fortran sources, modified | Creative Commons Attribution 4.0 International |
| ramsurf (Calvo / Quiet Oceans) | third_party/ramsurf/ |
vendored Fortran sources, modified | BSD-3-Clause |
| arlpy utilities (Chitre) | uacpy/core/ |
adapted (ported into UACPY sources, unmodified scientifically) | BSD-3-Clause |
| OASES (Schmidt, MIT) | third_party/oases/ (gitignored) |
optional download at install time, not redistributed | Academic license --- see Henrik Schmidt's terms |
Questions, bug reports, and contributions are welcome. For matters not suited to a GitHub issue (collaboration proposals, private questions, etc.), the maintainer can be reached at:
@software{uacpy2026,
title = {UACPY: Underwater ACoustics for PYthon},
author = {ErVuL and UACPY Contributors},
year = {2026},
url = {https://github.com/ErVuL/uacpy}
}