SonarKAD

SonarKAD v1.0.2

This repository stores the public output bundle for SonarKAD, a masked additive--low-rank diagnostic model for passive-sonar range--frequency fields.

SonarKAD first fits smooth range and frequency marginals, projects candidate low-rank residuals away from the observed additive subspace, and then selects the smallest interaction rank that improves blocked validation within a one-standard-error rule.

What is included

The expected uploaded tree is:

results/selected_models_summary.json
results/selected_models/swellex96_s5_vla/selected_model_manifest.json
results/selected_models/swellex96_s5_vla/selected_K01/run/sonarkad_model.pt
results/selected_models/swellex96_s5_vla/selected_K01/run/components.pt
results/selected_models/swellex96_s5_vla/selected_K01/run/results_cv.json
results/selected_models/swellex96_s5_vla/rank_ablation/rank_ablation.csv
results/selected_models/swellex96_s59_vla/selected_model_manifest.json
results/selected_models/swellex96_s59_vla/selected_K00/run/sonarkad_model.pt
results/selected_models/swellex96_s59_vla/selected_K00/run/components.pt
results/selected_models/swellex96_s59_vla/selected_K00/run/results_cv.json
results/selected_models/swellex96_s59_vla/rank_ablation/rank_ablation.csv
results/figure_method_overview.png
results/figure_swellex96_data_overview.png
results/figure_swellex96_summary.png
results/figure_swellex96_decomposition.png
results/table_metrics_two_events.csv
results/table_diagnostics_two_events.csv
results/transfer_study/transfer_summary.json
validation/**

Checkpoint files are PyTorch dictionaries produced by the GitHub code release. Logs, manifests, rank traces, transfer outputs, and figure records are included so that the selected-rank decisions can be audited without rerunning training.

Results reported by the SPL manuscript

S5 is treated as the cleaner tow; S59 is interference-stressed. Under the same protocol, SonarKAD keeps a compact rank-one residual for S5 and rejects residual coupling for S59.

Data

The experiments use SWellEx-96 vertical-line-array tonal data. Raw SWellEx-96 files are not redistributed in this model repository. The GitHub repository contains the preprocessing code and expects users to place the raw .sio, range, VLA-position, and CTD files under data/ according to configs/config.yaml.

Default preprocessing uses:

• sampling rate: 1500 Hz;
• 4096-point Hann STFT;
• 2.7307 s window and 1.3653 s hop;
• median pooling over 21 VLA channels after array-order correction;
• high T-49-13 tones from 49 Hz to 388 Hz;
• five blocked folds with 30 frames per block.

How to load a bundle

Install from GitHub:

git clone https://github.com/soundai2016/SonarKAD.git
cd SonarKAD
python -m pip install -e .

Load the S5 selected model from this Hugging Face repository:

import numpy as np
from huggingface_hub import hf_hub_download
from sonarkad import load_sonarkad_model_bundle, predict_rl

bundle_path = hf_hub_download(
    repo_id="soundai2016/SonarKAD",
    filename="results/selected_models/swellex96_s5_vla/selected_K01/run/sonarkad_model.pt",
    repo_type="model",
)

model, meta = load_sonarkad_model_bundle(bundle_path, device="auto")

r_m = np.linspace(meta["normalization"]["r_min_m"], meta["normalization"]["r_max_m"], 100)
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"])
print(rl_db.shape)

Reproduce outputs

From the GitHub checkout:

python -m pip install -e ".[tracking]"
bash run_all.sh

For multi-GPU training:

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

Intended use

SonarKAD is intended for research diagnostics on passive-sonar range--frequency fields. The output bundle supports:

• reproducing manuscript figures and tables;
• auditing blocked-CV rank selection;
• inspecting additive range/frequency components and the retained residual interaction;
• running inference inside the normalized range/frequency support saved in each bundle.

Limitations

• The saved bundles are event-specific diagnostics, not a universal ocean-acoustics predictor.
• Predictions outside the stored normalization range are clipped by the inference helper and should not be interpreted physically.
• Rank selection depends on the configured mask, block partition, preprocessing, and validation rule.
• SWellEx-96 raw data must be obtained from the original data source.