KrakenJL


Model	`AcousticsToolbox.KrakenJL`
Description	Native Julia port of the Kraken and KrakenC normal mode models
Language	Julia
Advantages	Differentiable (forward mode), no file I/O, multithreaded, drop-in alternative to `AcousticsToolbox.Kraken`
Limitations	2D only, range-independent only
Differentiability	`ForwardDiff`

KrakenJL(env; kwargs...)

Native-Julia port of the KRAKEN / KRAKENC normal-mode models — a drop-in alternative to the Fortran-wrapping Kraken model in this package.

Supported keyword arguments:

nmodes: number of modes to use (default: 9999)
mesh_density: number of mesh points per wavelength (default: 0, 0=auto)
clow: lower limit of phase speed (default: 1300, 0=auto)
chigh: upper limit of phase speed (default: 2500)
rmax: largest range (in m) of interest (default: Inf, meaning 1% more than the furthest receiver)
complex_solver: use the KRAKENC complex solver (default: true)
robust: use robust (but slow) root finder restarts (default: false)
threads: number of threads for mode/field computation (default: Threads.nthreads(); 1 runs the serial code path)

KrakenJL is a native Julia port of the Kraken and KrakenC normal mode models, based on the OALIB Acoustics Toolbox 2024_12_25 release — the same sources the wrapped Fortran binaries are compiled from (full provenance and deviations are documented in the package’s PORTING_NOTES.md). It implements both the KrakenC complex eigenvalue solver (default) and the Kraken real solver, fluid/elastic/multilayer-elastic seabeds, Richardson mesh extrapolation, perturbational attenuation and group speeds, and performs the coherent/incoherent mode summation natively (no env/mod/shd file I/O). Mode finding and field evaluation are multithreaded (threads keyword argument), with results identical to the serial computation. Since the port is pure Julia, it is compatible with automatic differentiation (AD) tools such as ForwardDiff.

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

M. B. Porter, “The KRAKEN normal mode program”, Technical report NRL/MR/5120-92-6920, Naval Research Laboratory, 1992 (original report pdf) (updated draft pdf).

Tip

The theory of modal models is summarized in a brief note “On modal models”. It provides an overview of key concepts and relevant mathematical formulations.

Examples

Range-independent scenario

Here’s an example showing results for the PEKERIS test problem from the Kraken technical report:

using UnderwaterAcoustics
using AcousticsToolbox
using Plots

env = UnderwaterEnvironment(
  bathymetry = 5000,
  soundspeed = 1500,
  density = 1000,
  seabed = FluidBoundary(2000, 2000)
)
pm = KrakenJL(env)

tx = AcousticSource(0, -500, 10)
rx = AcousticReceiver(200000, -2500)
modes = arrivals(pm, tx, rx)[1:7]     # first 7 modes

7 element Vector{ModeArrival}:
  mode 1: kᵣ = 0.041883 - 0.0im rad/m, v = 1499.84 m/s, vₚ = 1500.16 m/s
  mode 2: kᵣ = 0.04187 - 0.0im rad/m, v = 1499.36 m/s, vₚ = 1500.66 m/s
  mode 3: kᵣ = 0.041847 - 0.0im rad/m, v = 1498.56 m/s, vₚ = 1501.48 m/s
  mode 4: kᵣ = 0.041815 - 0.0im rad/m, v = 1497.45 m/s, vₚ = 1502.63 m/s
  mode 5: kᵣ = 0.041773 - 0.0im rad/m, v = 1496.01 m/s, vₚ = 1504.12 m/s
  mode 6: kᵣ = 0.041723 - 0.0im rad/m, v = 1494.24 m/s, vₚ = 1505.94 m/s
  mode 7: kᵣ = 0.041663 - 0.0im rad/m, v = 1492.15 m/s, vₚ = 1508.10 m/s

# plot the modes
plot(modes)

rxs = AcousticReceiverGrid2D(200000:10:220000, -2500)
x = transmission_loss(pm, tx, rxs)

plot(200:0.01:220, x; ylims=(70,110), yflip=true, legend=false,
  xlabel="Range (km)", ylabel="Transmission loss (dB)")

Range-dependent scenario with multilayered seabed

While the Kraken model is range-independent by itself, it can be made range-dependent by using AdiabaticExt as shown below:

using UnderwaterAcoustics
using Plots

env = UnderwaterEnvironment(
  bathymetry = SampledField([200, 150, 200]; x=[0, 2000, 5000]),
  soundspeed = 1500,
  density = 1000,
  seabed = MultilayerElasticBoundary([
    (40, 1374, 1520, 0, dBperλ(0.1124), 0),           # 40m thick fluid sediment
    (Inf, 2200, 1730, 800, dBperλ(0.5), dBperλ(0.5))  # hard half-space substrate
  ])
)

# use an adiabatic extension to the KrakenJL for range-dependence
pm = AdiabaticExt(KrakenJL, env)

tx = AcousticSource(0, -50, 250)
rx = AcousticReceiver(7000, -25)
rxs = AcousticReceiverGrid2D(10:10:7000, -200:-1)
x = transmission_loss(pm, tx, rxs)

plot(rxs, x; crange=50)
plot!(env)

Differentiability

Since KrakenJL is a pure Julia model, we can differentiate through it. For example, we can compute the sensitivity of the transmission loss to the water depth, seabed sound speed and frequency:

using ForwardDiff

function ℳ(x)
  D, cb, f = x
  env = UnderwaterEnvironment(
    bathymetry = D,
    soundspeed = 1500,
    density = 1000,
    seabed = FluidBoundary(2000, cb)
  )
  pm = KrakenJL(env)
  transmission_loss(pm, AcousticSource(0, -500, f), AcousticReceiver(200000, -2500))
end

ForwardDiff.gradient(ℳ, [5000.0, 2000.0, 10.0])

3-element Vector{Float64}:
   -2.7961233409223345
    0.15771604095385153
 -692.3278510911277

Notes

The KrakenJL 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 Kraken features reachable through the UnderwaterAcoustics.jl API. It does NOT support:

N2-linear, analytic or quadratic interpolation for sound speed
Arbitrary (tabulated) reflection coefficients
Twersky scattering
Broadband mode files, coupled modes and 3D field computation

Group velocities follow the behavior of the Fortran models: the KrakenC solver (complex_solver=true, default) computes them, but the values are incorrect for multilayer seabeds with elastic sediment layers (reported as missing); the Kraken real solver (complex_solver=false) does not compute them and reports zeros.

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