Pelagic v0.4.1

Pelagic v0.4.1

A documentation and examples release, with one fix to the arlpy backend. The solvers, the input and output formats, and the pinned Acoustics Toolbox v2023.5 reference are unchanged.

Highlights

• 24 ready-to-run example cases in examples/. Each one ships as Acoustics Toolbox files and as self-contained JSON.

  • BELLHOP: rays, eigenrays, arrivals and TL in the Munk channel; a Gulf of Mexico .ssp; a seamount .bty; curved .ati/.bty boundaries; a range-dependent bottom; an elastic bottom; a .brc reflection table; an .sbp beam pattern.
  • KRAKEN/KRAKENC: Munk modes; a surface duct; a layered seabed; an elastic sediment with an interface wave; Arctic ice; a rough surface; leaky modes; a .brc table; a 101-frequency broadband case; Gulf adiabatic and coupled modes.

• Scripts for every interface:

  • Python (16): quickstart; rays, eigenrays and arrivals, with a received pulse; editing a case, and building one from scratch; parallel sweeps; modes and seabeds; leaky and range-dependent modes; broadband pulse synthesis; saving results; error handling; the arlpy backend.
  • MATLAB (8).
  • Command line: bash and PowerShell scripts, a stdin and diagnostics pipeline, and an h5py reader.
  • HTTP: a standard-library client.

  CI runs every case and script on all five platforms, so they stay current.

• Reorganized documentation:

  • For users: getting started, plus separate Python, MATLAB/Octave and command-line guides, and troubleshooting with an error-code table.
  • For maintainers: CONTRIBUTING, an interface contract (what is public, version rules, diagnostic codes), a release checklist and a CHANGELOG.

Fixed

• arlpy backend: compute_transmission_loss returned wrong range coordinates (the DataFrame's columns). arlpy 1.9 reads .shd receiver ranges as float32, but Toolbox v2023.5 stores them as float64. Pressure values were always correct.

Compatibility

• Case JSON v1, BELLHOP HDF5 v3, KRAKEN HDF5 v1 and diagnostics protocol v1 are unchanged. So are the CLI, Python and MATLAB APIs, and their outputs.
• examples/field-g.json moved to examples/cases/bellhop/field-g/field-g.json, and examples/kraken-pekeris.json to examples/cases/kraken/pekeris/pekeris.json.

Verification

Release commit: f0ed60c80eba7ead033696cd87f56d94f7eb3fc9 (merged PRs #56 and #57).

• Clean-commit full numerical acceptance: 27/27 stages PASS in 474 seconds, exit 0. The initial and final SHA both match this commit, and the tree stayed clean. The host was macOS ARM64, using the pinned Linux amd64 Fortran oracle; the host C toolchain was the Command Line Tools.
• Workspace: fmt, Clippy -D warnings and 250 tests passed.
• Python: 404–405 tests on each of the five wheel platforms, including every example case and script, and the CLI example scripts (bash, or PowerShell on Windows). Also tested on Python 3.9 with NumPy 1.26, and on Python 3.14 with NumPy 2.3.
• MATLAB R2025b and Octave: the bindings and curated tests passed in both. The MATLAB example scripts passed on Linux and Windows.
• The solver code is unchanged from v0.4.0, so the v0.4.0 numerical coverage statements still apply.

Downloads

• Python: python -m pip install pelagic==0.4.1
• MATLAB/Octave: pelagic-v0.4.1.mltbx
• CLI: pelagic-v0.4.1-windows-x64.zip, and pelagic-v0.4.1-<platform>.tar.gz for macOS and Linux. The macOS binaries are not notarized. If Gatekeeper blocks a downloaded copy, run xattr -d com.apple.quarantine pelagic.

Every asset has a .sha256 checksum file. Start with Getting started.

Pelagic v0.4.0

Pelagic v0.4.0

This release makes Pelagic usable directly from Python and MATLAB/Octave, and ships prebuilt CLIs for macOS and Linux alongside Windows. The numerical solvers and the pinned Acoustics Toolbox v2023.5 reference are unchanged.

Highlights

• Python package — python -m pip install pelagic. Runs BELLHOP and KRAKEN/KRAKENC in-process (no CLI, no HDF5 dependency) and returns immutable NumPy results with labelled [source, depth, range] axes, rays, eigenrays, arrivals and per-profile modes; optional pandas/xarray conversion; run_many() for parallel sweeps with Ctrl-C cancellation; structured exceptions carrying stable diagnostic codes; provenance (version, reference, input/case SHA-256); native file output without HDF5. abi3 wheels for CPython 3.9+ on Linux x86-64/aarch64, macOS x86-64/ARM64 and Windows x64. An opt-in arlpy 1.9 backend (model="pelagic") is included.
• MATLAB/Octave toolbox — pelagic-v0.4.0.mltbx bundles the matching CLI for all five platforms. pelagic.bellhop.load/run and pelagic.kraken.load/run return plain structs; numeric fields are ordinary vectors, and scalars assigned to array fields are encoded correctly. Works in MATLAB R2023a+ and GNU Octave 7+ (Java enabled).
• macOS and Linux CLIs — pelagic-v0.4.0-{macos-arm64,macos-x64,linux-x64,linux-arm64}.tar.gz, in addition to the Windows ZIP.
• Machine protocol for tools and adapters — validate/export/run accept - for JSON on stdin; global --diagnostics json emits NDJSON diagnostics with stable code, severity, field and source; pelagic version --json reports schema, protocol and reference versions; new pelagic kraken validate.
• Cooperative cancellation — thread-scoped cancellation checks in ray tracing, influence, modal searches and FIELD (BH0304/KR0304). Without a token, behaviour is unchanged.
• Citation — CITATION.cff describes how to cite an exact release.

Compatibility

• JSON case schemas remain v1; BELLHOP HDF5 remains schema v3 and KRAKEN HDF5 schema v1. CLI defaults, protected result directories and the BELLHOP-only HTTP contract are unchanged.
• Diagnostic field names now match the JSON schema: frequency → frequency_hz, run_options.beam_family → run.beam_family, trace.launch_count → trace.launch_angles_degrees. Malformed JSON now reports the offending field path (e.g. frequencies[0].propagation) instead of json. Update any scripts that matched the old names; codes and exit codes are unchanged.
• KRAKEN run errors are structured reports internally; human-readable CLI output is unchanged.
• Rust: native writers and directory publication moved to the new HDF5-free native-output crate; output re-exports the directory API for existing callers.

Verification and known limits

Release commit: 2761dab31c1f16c9af41750f06059ed651721a82 (merged PR #55).

• Clean-commit full numerical acceptance: 27/27 stages PASS, 439 seconds, exit 0; the initial/final SHA both match this release commit and the tree stayed clean (macOS ARM64 host with the pinned Linux amd64 Fortran oracle; host C toolchain: Command Line Tools).
• Workspace: fmt, Clippy -D warnings, 250 tests passed (macOS ARM64); CI green on Linux and Windows.
• Python: 365 tests, every curated fixture compared with CLI HDF5 and native output (identical on each platform), on all five wheel platforms plus Python 3.9/NumPy 1.26 and Python 3.14/NumPy 2.3.
• MATLAB R2025b (Linux, Windows, macOS) and Octave: adapter tests and 311 curated fixtures identical through the MATLAB JSON transport, 35 matching rejections.

Solver arithmetic is unchanged in this release apart from the cancellation checks, so the v0.3.0 business inventories still describe numerical coverage: KRAKEN 306 PASS / 4 strict reference differences of 345 paths, BELLHOP 205 PASS / 9 FAIL / 4 nonfinite references / 1 3D exclusion. They were not re-run for this release. This release does not claim universal Toolbox parity.

Downloads

• Python: python -m pip install pelagic==0.4.0
• MATLAB/Octave: pelagic-v0.4.0.mltbx
• CLI: pelagic-v0.4.0-windows-x64.zip and pelagic-v0.4.0-<platform>.tar.gz for macOS/Linux. macOS binaries are not notarized; if Gatekeeper blocks a downloaded copy, run xattr -d com.apple.quarantine pelagic.

Every asset has a .sha256 checksum file. See the bindings guide for Python/MATLAB usage.

Pelagic v0.3.0

Pelagic v0.3.0

This release adds rough-fluid-interface scattering, corrects KRAKENC mode discovery and strengthens numerical verification while retaining the pinned Acoustics Toolbox v2023.5 reference.

Highlights

• Rough fluid interfaces: surface, internal and bottom RMS roughness through both KRAKEN engines, legacy inputs, self-contained JSON and HDF5 metadata. Complete complex first-mesh scattering perturbations survive refinement.
• More reliable KRAKENC spectra: corrected separated-duct and rigid-top initial guesses, plus complex-eigenvector polishing. Search bounds, resource ceilings and count-increase protection remain intact.
• Independent numerical controls: complete lossy Pekeris spectra, normalized modes and fields; roughness formulas and scaling; Sturm/refinement checks; actual ENV/JSON CLI native/HDF5 round-trips.
• BELLHOP fixes since v0.2.0: five beam-normalization/precision corrections and rejection of nonfinite scaled fields before publication, including HDF5-only output. Boundary-repair experiments remain deferred, not shipped.
• Clearer documentation: current capabilities/results, comparison criteria, reproduction workflows and historical investigations have distinct homes. Exact acceptance case lists remain in executable scripts.

Compatibility

Existing JSON v1 inputs remain valid and default to smooth interfaces. Rust code constructing CaseDefinition literals must add interface_roughness_m: Vec::new() for smooth behavior, or provide one RMS-height value per fluid interface. Rough elastic/table interfaces remain rejected.

KRAKEN HDF5 remains schema v1 with additive roughness attributes; BELLHOP remains schema v3. CLI format defaults, protected result-directory behavior and the BELLHOP-only HTTP contract are unchanged.

The comparator now accepts ordinary-decimal printed attenuation and machine-scale imaginary-k residuals against an exact reference zero (1e-12 m⁻¹ floor). Production roots are not clamped. Physical-loss, mode-count, shape and pressure criteria are unchanged.

Verification and known limits

Release commit: 0f07b15506f6aa0fc699a440144048badb63d9fb (merged PR #47).

• Clean-commit full numerical acceptance: 27/27 stages PASS, 547 seconds, exit 0; the initial/final SHA both match this release commit.
• macOS and same-container Linux workspace suites: 242 passed / 0 failed / 12 ignored each; external-reference entry points ran separately.
• CI, build/package checks, Clippy, formatting, documentation and reference-integrity guards passed. The fresh business rerun retained all outcomes below, with 612 common official MOD/SHD products byte-identical to the preceding diagnostic.

The full 345-path KRAKEN business inventory retains 306 PASS / 4 strict reference differences, plus 23 unsupported, 4 nonfinite references, 2 failed references, 4 unconverged references and 2 missing originals. The four strict differences are PekerisDense, PekerisFiltered, PekerisRigidPlane and PekerisDenseLoss; independent/real-reference controls support the Rust results without relabeling the original comparisons as passes. Weak-field relative/TL/phase limitations remain explicit.

BELLHOP retains its recorded 205 PASS / 9 FAIL / 4 nonfinite references / 1 3D exclusion and acceptance with documented exceptions. This release does not claim universal Toolbox parity or full physical validation of arbitrary inputs.

Downloads and documentation

The release workflow attaches pelagic-v0.3.0-windows-x64.zip and its .sha256 checksum. The ZIP contains the CLI, license notices and exact source/build information; HDF5 and the MSVC runtime are statically linked. The optional HTTP server is built separately.

For source builds, use the repository-pinned Rust toolchain, CMake and a C/C++ toolchain, then run cargo install --locked --path crates/cli. The declared Rust 1.88 MSRV is unchanged.

• Documentation index
• Rough-interface input/model contract
• KRAKEN results and limitations
• BELLHOP results and accepted exceptions
• Full changelog

Pelagic v0.2.0

Pelagic v0.2.0

BELLHOP ray/beam modelling and KRAKEN/KRAKENC normal-mode modelling now share one CLI: pelagic.

Highlights

• Independent BELLHOP and KRAKEN/KRAKENC solvers, accepting legacy inputs or their own self-contained JSON documents.
• Native RAY/eigenray, ASCII/binary ARR, SHD and MOD outputs, alongside the existing HDF5 schemas. Use --format legacy|hdf5|both; native output is the default and both calculates once.
• Protected result directories: update verified owned outputs while preserving unrelated files and protecting inputs. Modified files and unrecognized conflicts are not silently overwritten.
• A separate pelagic-server keeps the BELLHOP-only HTTP API.
• Windows x64 CLI download, built natively with MSVC. HDF5 and the MSVC runtime are statically linked; no separate HDF5/VC runtime installation is needed.

Downloads

The Windows release workflow attaches pelagic-v0.2.0-windows-x64.zip and its .sha256 checksum after verification. The ZIP includes pelagic.exe, license notices and exact source/build information; it does not include the HTTP server or an installer and is not code-signed.

GitHub's source archives are also available. To build the CLI from this release, use Rust 1.88+, CMake and a C/C++ toolchain, then run cargo install --locked --path crates/cli.

CLI migration

Use pelagic bellhop ... or pelagic kraken ... instead of the old solver-specific executables. --output now names a result directory, and --overwrite has been removed. To retain HDF5 output, select --format hdf5 or --format both.

The HDF5 schemas and existing Rust single-file output APIs are retained. The HTTP protocol is unchanged. .prt files contain Pelagic's own reports, not original Fortran print formatting.

Verification and scope

The release is based on merged PRs #39, #40 and #41. Acoustics Toolbox v2023.5 remains the fixed numerical reference; supported cases, tolerances and reference bytes were not relaxed for this release. Linux CI executes the complete reference matrix; Windows CI runs the workspace tests plus actual extracted-package native/HDF5 readbacks for BELLHOP, KRAKEN and KRAKENC.

See the CLI guide, native output and directory contract, and model-specific BELLHOP / KRAKEN capabilities before using a new model configuration. This release is not a claim of full Toolbox option parity.

bellhop-rs v0.1.0

First public release of bellhop-rs, a deterministic Rust implementation of the two-dimensional BELLHOP underwater-acoustics model, compatible with Acoustics Toolbox v2023.5.

Highlights

• Loads complete legacy 2D cases and .ssp, .ati, .bty, .brc, .trc, .irc, and .sbp auxiliary inputs.
• Provides a strict, self-contained JSON case format with validation and legacy-case export.
• Implements ray traces, eigenrays, arrivals, and coherent, semi-coherent, and incoherent pressure fields.
• Supports all N/C/P/S/Q/A sound-speed models and supported 2D boundary/reflection modes.
• Includes the bellhop CLI for validation, conversion, and HDF5 simulation output.
• Includes bellhop-server with bounded execution, authentication, OpenAPI/Swagger documentation, HDF5 output, and versioned JSON arrival output.
• Uses versioned HDF5 schema v2 and JSON arrival schema v1.
• Verifies numerical compatibility through committed goldens and pinned Linux differential tests against Acoustics Toolbox v2023.5.

Requirements

• Rust 1.88 or newer.
• This release provides source archives; build the CLI or server with Cargo.

Known limits

• Two-dimensional cases only; three-dimensional options are rejected.
• Reference-incomplete W reflection-table generation and reference-unimplemented influence paths remain unavailable.

See the README, input compatibility, and HTTP guide for details.