BellhopJL
Model AcousticsToolbox.BellhopJL
Description Native Julia port of the Bellhop ray/beam tracer
Language Julia
Advantages Differentiable (forward mode), no file I/O, drop-in alternative to AcousticsToolbox.Bellhop
Limitations 2D only, no 3D or range-dependent sound speed support
Differentiability ForwardDiff 
BellhopJL(env; kwargs...)

Native-Julia port of the 2D Bellhop Gaussian-beam/ray tracer — a drop-in alternative to the Fortran-wrapping Bellhop model in this package, differentiable with ForwardDiff.

Supported keyword arguments:

  • nbeams: number of beams to use (default: 0, auto)
  • min_angle: minimum beam angle (default: -80°)
  • max_angle: maximum beam angle (default: 80°)
  • beam_type: :geometric (default) or :gaussian

BellhopJL is a native Julia port of the 2D Bellhop Gaussian beam / ray tracer, based on the A-New-BellHope bug-fixed mirror of Bellhop 2022_4 and updated with the relevant corrections from the OALIB 2024_12_25 release (full provenance and deviations are documented in the package’s PORTING_NOTES.md). It implements Bellhop’s exact stepping algorithm, boundary reflections, and geometric hat/Gaussian beam influence in Cartesian coordinates, and reads environments directly from UnderwaterAcoustics.jl (no env/shd/arr file I/O). Since the port is pure Julia, it is compatible with automatic differentiation (AD) tools such as ForwardDiff (prefer beam_type=:gaussian for optimization work, as hat beams have kinks at beam edges).

A good overview of the Bellhop model can be found at:

Example

using UnderwaterAcoustics
using AcousticsToolbox
using Plots

env = UnderwaterEnvironment(
  bathymetry = SampledField([200, 150]; x=[0, 1000], interp=Linear()),
  soundspeed = SampledField([1500, 1480, 1495, 1510, 1520]; z=0:-50:-200, interp=CubicSpline()),
  seabed = SandyClay
)
pm = BellhopJL(env)

tx = AcousticSource(0, -50, 300)
rx = AcousticReceiver(1000, -100)
rays = arrivals(pm, tx, rx)

plot(env; xlims=(-10, 1010))
plot!(tx)
plot!(rx)
plot!(rays)
rxs = AcousticReceiverGrid2D(1:1000, -200:0)
x = transmission_loss(pm, tx, rxs; mode=:coherent)

plot(rxs, x; crange=70)
plot!(env; xlims=(0,1000), linewidth=3)

Notes

The BellhopJL propagation model requires that the transmitter is located at \((x=0, y=0)\) and all receivers are located in the right half-plane (i.e., \(x>0\) and \(y=0\)). This limitation can be worked around by wrapping the model with Reframe2D, which automatically transforms 2D scenarios specified in world coordinates into the coordinate system required by the model (see the quickstart guide for an example).

Like the Fortran wrapper, the port implements the subset of Bellhop features reachable through the UnderwaterAcoustics.jl API. It does NOT support:

  • 3D environments (i.e., Bellhop 3D)
  • Range-dependent sound speed
  • Directional or line sources
  • Cerveny (Cartesian or ray-centered) and simple Gaussian bundle beams

Licensing: the BellhopJL solver is GPL-3.0-or-later (a derivative work of Bellhop), unlike the rest of AcousticsToolbox.jl (MIT) — see the package’s licensing notes for details.