Pelagic

Pelagic runs the classic two-dimensional underwater acoustics models from Python, MATLAB/Octave or the command line, without building the Fortran Acoustics Toolbox:

• BELLHOP: ray traces, eigenrays, arrivals and pressure fields.
• KRAKEN / KRAKENC: real and complex normal modes, plus FIELD pressure.

It reads your existing .env/.flp files or a self-contained JSON case. It writes the familiar .ray/.arr/.shd/.mod files, structured HDF5, or both. Results are checked against the official Acoustics Toolbox v2023.5 release.

Install

Prebuilt packages cover Windows x64, macOS (Apple silicon and Intel) and Linux (x86-64 and ARM64). Nothing else needs to be installed: HDF5 is built in. To build from source, see CONTRIBUTING.

Quick start

These use munk-tl.json, deep-water transmission loss. examples/ has 24 cases, from rays and arrivals to elastic seabeds, range-dependent modes and broadband pulses, each with Python, MATLAB and command-line scripts.

Python

import pelagic as pg

result = pg.bellhop.load("munk-tl.json").run()
pressure = result.field.pressure            # complex64, [source, depth, range]
loss_db = result.field.transmission_loss()
result.write_native("results/munk-tl")      # .shd and friends, no re-solve

MATLAB / Octave

c = pelagic.bellhop.load('munk-tl.json');
c.frequency_hz = 200;
r = pelagic.bellhop.run(c);
imagesc(r.ranges_m, r.depths_m, 20*log10(abs(squeeze(r.pressure(1,:,:)))));

Command line

pelagic bellhop run munk-tl.json --format both --output results/munk-tl
pelagic kraken run case.env --solver krakenc --output results/case

What it can and cannot do

Pelagic covers a large, tested part of 2D BELLHOP and KRAKEN/KRAKENC, but not every option combination in the Toolbox. Three-dimensional programs (BELLHOP3D, FIELD3D) and BOUNCE table generation are not included. Unsupported input is rejected with a clear error rather than approximated. Before starting a study, check your options against:

• BELLHOP capabilities and limits
• KRAKEN/KRAKENC capabilities and limits

Documentation

• Getting started: install, first run and choosing an interface
• Guides: Python · MATLAB/Octave · Command line · HTTP service
• Examples: 24 cases with Python, MATLAB, command-line and HTTP scripts
• Troubleshooting and error codes
• Full documentation index, including file formats and JSON schemas
• Changelog

Questions and bug reports are welcome in Issues. To contribute, start with CONTRIBUTING.

Citing Pelagic

If Pelagic contributes to published work, cite the exact release you used. See CITATION.cff, or use "Cite this repository" on GitHub. Each result also records its Pelagic version and an input hash for reproducibility.

License

GPL-3.0-or-later. See LICENSE and NOTICE.