sonarkad 1.0.2

Physics-aligned Kolmogorov-Arnold decomposition for sonar range-frequency fields

SonarKAD

SonarKAD is a compact PyTorch implementation of the masked additive--low-rank test.

The model decomposes a passive-sonar range--frequency field as

y(r, f) = b + phi_r(r) + phi_f(f) + psi_K(r, f)

where the range and frequency marginals are spline additive terms and psi_K is a gauge-fixed low-rank residual. Candidate ranks are compared by blocked validation, and the smallest rank within the one-standard-error rule is selected.

Version 1.0.2

This release is aligned with the public SPL submission package:

• masked additive projection and low-rank interaction diagnostics;
• SWellEx-96 S5/S59 VLA preprocessing, blocked CV, rank ablation, transfer study, and paper figures;
• selected-rank workflow with K*=1 for S5 and K*=0 for S59 under the default configuration;
• checkpoint/resume support, JSONL/CSV logs, optional Weights & Biases logging, and DataParallel multi-GPU training;
• deployable sonarkad_model.pt bundles plus components.pt, validation traces, manifests, and figure-generation records.

Install

git clone https://github.com/soundai2016/SonarKAD.git
cd SonarKAD
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e ".[tracking]"

For a minimal install without W&B:

python -m pip install -e .

Data layout

SWellEx-96 raw data are not redistributed in this repository. Put the files under data/ as referenced by configs/config.yaml, for example:

data/J1312315.vla.21els.sio
data/J1341145.vla.21els.sio
data/RangeEventS5/
data/RangeEventS59/
data/positions_vla.txt
data/ctds/

Then verify the layout:

python scripts/run.py check --config configs/config.yaml
python scripts/run.py data-validate --config configs/config.yaml

Reproduce assets

Full run:

bash run_all.sh

GPU / multi-GPU run:

DEVICE=cuda GPUS=0,1 FORCE=1 RANKS=0,1,2,4,8,16 bash run_all.sh

Main generated files:

outputs/results/figure_method_overview.png
outputs/results/figure_swellex96_data_overview.png
outputs/results/figure_swellex96_summary.png
outputs/results/figure_swellex96_decomposition.png
outputs/results/table_metrics_two_events.csv
outputs/results/table_diagnostics_two_events.csv
outputs/results/selected_models_summary.json
outputs/results/selected_models/*/selected_model_manifest.json
outputs/results/selected_models/*/selected_K*/run/sonarkad_model.pt
outputs/results/selected_models/*/selected_K*/run/results_cv.json
outputs/results/selected_models/*/rank_ablation/rank_ablation.csv
outputs/results/transfer_study/transfer_summary.json

Render publication figures from existing outputs only:

python scripts/plot.py --results-dir outputs --out-dir outputs/figures

Focused commands

Prepare one event:

python scripts/run.py swellex96-prepare --config configs/config.yaml --exp swellex96_s5_vla

Run selected-rank materialization:

python scripts/run.py swellex96-select-rank --config configs/config.yaml --exp swellex96_s5_vla --ranks 0,1,2,4,8,16 --selection-rule 1se
python scripts/run.py swellex96-select-rank --config configs/config.yaml --exp swellex96_s59_vla --ranks 0,1,2,4,8,16 --selection-rule 1se

Run transfer audit:

python scripts/run.py swellex96-transfer-audit --config configs/config.yaml --source swellex96_s5_vla --target swellex96_s59_vla

Use a saved bundle

import numpy as np
from sonarkad import load_sonarkad_model_bundle, predict_rl

model, meta = load_sonarkad_model_bundle(
    "outputs/results/selected_models/swellex96_s5_vla/selected_K01/run/sonarkad_model.pt",
    device="auto",
)

r_m = np.linspace(meta["normalization"]["r_min_m"], meta["normalization"]["r_max_m"], 128)
f_hz = np.linspace(meta["normalization"]["f_min_hz"], meta["normalization"]["f_max_hz"], 64)
rr, ff = np.meshgrid(r_m, f_hz, indexing="ij")
rl_db = predict_rl(model, r_m=rr, f_hz=ff, normalization=meta["normalization"])

Models & results

We have officially released the pre-trained SonarKAD models on Hugging Face. You can access the model repository, download weights, and check detailed configurations directly via the link below:

📌 Hugging Face Model Hub: soundai2016/SonarKAD

Repository map

configs/config.yaml           Default SWellEx-96 and paper configuration
scripts/run.py                Source-checkout wrapper around the SonarKAD CLI
scripts/plot.py               Figure-only rendering wrapper
src/sonarkad/models.py        Additive spline + low-rank interaction model
src/sonarkad/training.py      Device, checkpoint, resume, and logging helpers
src/sonarkad/experiments/     SWellEx-96, rank, transfer, and validation workflows
src/sonarkad/plots/           Manuscript figure renderers
src/sonarkad/deploy.py        Load/predict helpers for saved model bundles

License

MIT. SWellEx-96 data remain governed by the terms of the original data provider and are not bundled here.