SonarKAN 1.1.0

Gauge-fixed KAN models for passive-sonar range-frequency fields.

SonarKAN Python package

sonarkan implements the gauge-fixed additive-plus-low-rank model. The package provides the model, B-spline edge functions, SWellEx-96 data utilities, acoustic/statistical baselines, experiment runners, checkpoint loading, reporting, and the two submitted figure generators.

The canonical spelling is SonarKAN for the project and model class, and sonarkan for the Python package.

Official resources

GitHub https://github.com/soundai2016/SonarKAN

Outputs https://huggingface.co/soundai2016/SonarKAN

Model

For range r and frequency f, SonarKAN represents the received-level field as

y_hat(r, f) = b + phi_r(r) + phi_f(f) + phi_abs(r, f)
              + sum_k u_k(r) v_k(f)

• phi_r and phi_f are learned one-dimensional B-spline edge functions.
• phi_abs is an optional prescribed or parameterized absorption contribution.
• The final term is a rank-K interaction branch.
• K = 0 is the additive member of the same model family.
• Gauge fixing centers the learned marginals and removes lower-order row/column means from the aggregate interaction, so coupling diagnostics are attached to the centered interaction rather than leaked main effects.

Individual low-rank factors are not uniquely interpretable under rotations and rescalings; use the aggregate interaction field exported in components.pt for interpretation.

Installation

From the source-repository root:

python -m pip install -e ./src

Or from this directory:

python -m pip install -e .

The package requires Python 3.10 or newer and installs NumPy, PyTorch, Matplotlib, and PyYAML as runtime dependencies.

Public API

from sonarkan import (
    SonarKAN,
    SonarKANConfig,
    SmallMLP,
    load_sonarkan_model_bundle,
    predict_from_bundle,
    predict_rl,
)

A minimal additive model can be constructed with:

from sonarkan import SonarKAN, SonarKANConfig

config = SonarKANConfig(interaction_rank=0)
model = SonarKAN(r_min_m=900.0, r_max_m=8700.0, cfg=config)

Training in the submitted experiments is configured through ../configs/config.yaml and run through ../scripts/run.py; the package does not install a separate console entry point.

Load a retained checkpoint

sonarkan_model.pt is a dictionary bundle with format identifier SonarKAN_model_bundle. It stores the state dictionary, model configuration, physical normalization bounds, and training metadata.

From the source-repository root:

from sonarkan import load_sonarkan_model_bundle, predict_rl

checkpoint = (
    "outputs/results/selected_models/"
    "swellex96_s5_vla/selected_K00/run/sonarkan_model.pt"
)
model, metadata = load_sonarkan_model_bundle(checkpoint, device="cpu")

prediction_db = predict_rl(
    model,
    r_m=[1000.0, 2000.0],
    f_hz=[49.0, 388.0],
    normalization=metadata["normalization"],
    progress_bar=False,
)
print(prediction_db)

The convenience wrapper predict_from_bundle(...) loads the bundle and performs the same normalization automatically.

PyTorch .pt files use Python serialization. Load checkpoints and component files only from a trusted source.

Checkpoints versus component exports

File	Purpose
sonarkan_model.pt	Loadable model bundle for inference or continued analysis
components.pt	Precomputed marginal curves, interaction grid, held-out predictions, and diagnostic metadata used for interpretation and Figure 2
results.json	Single-run metrics, baseline details, and training history
results_cv.json	Blocked-CV aggregate metrics, fold assignments, and fold summaries

components.pt is not a model checkpoint and does not contain everything required to reconstruct the network.

Plotting API

The package exports:

from sonarkan.plots import plot_figure1, plot_figure2

plot_figure1 is self-contained. plot_figure2 requires the two processed event files and their fixed-K = 16 components.pt artifacts. Most users should call the repository-level wrapper instead:

python scripts/plot.py --config configs/config.yaml --force

It writes:

outputs/figures/fig1_framework.pdf
outputs/figures/fig2_decomposition.pdf

Package layout

sonarkan/models.py                    SonarKAN, spline edges, absorption, and MLP baseline
sonarkan/deploy.py                    checkpoint loading and batched prediction
sonarkan/baselines.py                 parametric TL, GAM, WGI, and modal baselines
sonarkan/data/                        SIO, SWellEx-96, range, VLA, and CTD utilities
sonarkan/experiments/                 preprocessing, training, CV, rank, and transfer studies
sonarkan/plots/figure1.py             manuscript Figure 1
sonarkan/plots/figure2.py             manuscript Figure 2
sonarkan/reporting.py                 manuscript CSV tables
sonarkan/utils/                       configuration, paths, seeds, and PyTorch compatibility