SonarKAN paper reproduction outputs

This repository is the output-only artifact bundle for the anonymized submission “SonarKAN: Testing Range–Frequency Coupling in Passive Sonar.” It contains processed SWellEx-96 S5/S59 tonal received-level fields, blocked-validation results, selected and diagnostic SonarKAN checkpoints, component exports, transfer-study artifacts, manuscript tables, and the two submitted figures.

The complete training and preprocessing code is available on GitHub

https://github.com/soundai2016/SonarKAN

This repository only stores generated outputs.

Pre-upload check

From the complete SonarKAN source repository, regenerate and normalize the manuscript assets before uploading this directory:

python scripts/run.py paper-assets --config configs/config.yaml --force

After this command, figures/ should contain exactly:

figures/fig1_framework.pdf
figures/fig2_decomposition.pdf

The plotting code removes legacy manuscript renders such as fig2.png and any unrelated .pdf, .png, or .svg files from figures/.

Manuscript artifact index

Figures

• Figure 1 — SonarKAN framework
• Figure 2 — SWellEx-96 decomposition

Figure 1 is a self-contained schematic of the range, frequency, optional absorption, low-rank interaction, gauge-projection, and diagnostic branches. Figure 2 uses the retained fixed-K = 16 component exports for S5 and S59.

Tables and summaries

• Table 1 — blocked cross-validation
• Table 2 — coupling and acoustic diagnostics
• Table 3 — cross-event transfer
• Selected-model summary

The submitted results select K = 0 for both S5 and S59 under the one-standard-error rule. The fixed K = 16 runs are separate stress-diagnostic fits used for the residual-interaction energy and Figure 2.

Submitted result	S5	S59
Selected SonarKAN rank	K = 0	K = 0
Fixed-K = 16 RMSE, mean ± std (dB)	3.500 ± 0.472	3.419 ± 0.242
Fixed-K = 16 centered interaction energy	5.130 ± 1.741%	1.805 ± 1.657%

The submitted S5-to-S59 frequency-marginal transfer changes target RMSE from 4.302 to 4.112 dB and explained variance from 0.353 to 0.407; see results/table3_transfer.csv.

Directory layout

README.md
figures/
  fig1_framework.pdf
  fig2_decomposition.pdf

results/
  table1_blocked_cv.csv
  table2_diagnostics.csv
  table3_transfer.csv
  selected_models_summary.json
  selected_models/                 validation-selected K=0 artifacts for S5 and S59
  rank_ablation/                   retained rank-study results and fold artifacts
  transfer_study/                  transfer artifacts used by paper-assets

swellex96_s5_vla/
  processed/swellex96_tonal_rl_high.npz
  run/                             fixed K=16 run, blocked CV, and retained studies

swellex96_s59_vla/
  processed/swellex96_tonal_rl_high.npz
  run/                             fixed K=16 run, blocked CV, and retained studies

transfer_swellex96_s5_vla_to_swellex96_s59_vla/
  ...                              direct swellex96-transfer command output

Some study artifacts are materialized in more than one path because manifests and command-specific output trees retain stable source-repository references. Do not delete a tree solely because another directory appears to contain similar files.

Artifact formats

Artifact	Contents and use
processed/*.npz	Arrays t_sec, r_m, f_hz, rl_db, and object metadata meta; these are derived tonal fields, not raw audio
sonarkan_model.pt	Loadable dictionary bundle with format SonarKAN_model_bundle, state dictionary, model configuration, normalization, and training metadata
components.pt	Precomputed range/frequency marginals, optional absorption field, centered interaction grid, held-out predictions, and diagnostic metadata
results.json	Single-run evaluation, baseline details, and training history
results_cv.json	Blocked-CV aggregate metrics, exact block/fold assignments, and fold summaries
rank_ablation.csv / rank_ablation_summary.json	Candidate-rank comparison and selected-rank information
selected_model_manifest.json	Stable pointers to the selected rank, checkpoint, components, and CV result
manuscript CSV files	Compact data used to reproduce Tables 1–3

The submitted processed array shapes are:

Event	t_sec / r_m	f_hz	rl_db
S5	(2133,)	(13,)	(2133, 13)
S59	(2811,)	(13,)	(2811, 13)

Download into the source repository

Paths inside the JSON manifests are stored relative to the complete source repository and begin with outputs/. For exact compatibility, download this Hub repository into the source repository's outputs/ directory.

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="<namespace>/<sonarkan-output-repository>",
    repo_type="dataset",
    local_dir="outputs",
)

Run this from the SonarKAN source-repository root. If the Hub snapshot is downloaded elsewhere, either move it to outputs/ or resolve manifest paths by stripping their leading outputs/ component.

Reproduce the manuscript assets

After the output snapshot is placed at <source-repository>/outputs/ and the local package is installed:

python -m pip install -e ./src

# Figures 1 and 2 only; no training
python scripts/plot.py --config configs/config.yaml --force

# Figures 1–2, Tables 1–3, selected-rank summary, and transfer summary
python scripts/run.py paper-assets --config configs/config.yaml --force

The figure-only command reads the processed .npz files and fixed-K = 16 components.pt files. The paper-assets command reuses retained numerical artifacts and computes only artifacts that are missing.

Load a selected checkpoint

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,
)

Use results/selected_models_summary.json as the canonical entry point for validation-selected checkpoints. The top-level event runs under swellex96_*_vla/run/ are the fixed-K = 16 diagnostic runs used by Figure 2, not the selected K = 0 models.

Security and integrity notes

• PyTorch .pt files use Python serialization. Load them only from a trusted and integrity-checked snapshot.
• components.pt is an interpretation/plotting export, not a complete model checkpoint.
• Keep checkpoint and component files paired with their adjacent results.json, results_cv.json, and manifest files.
• Do not interchange validation-selected K = 0 checkpoints with fixed-K = 16 diagnostic checkpoints.
• NumPy meta arrays require allow_pickle=True; use that option only with trusted files.

Scope, provenance, and responsible use

The processed fields are derived from the public SWellEx-96 vertical-line-array events S5 and S59. They are controlled-source, non-human acoustic measurements. S5 has no reported loud interferer; S59 contains a moving loud interferer and a late tow-ship maneuver.

These two event-specific case studies do not establish universal range–frequency separability. The artifacts support reproduction of the submitted blocked-validation and diagnostic analyses only. Operational passive-sonar use requires independent validation in the target environment.

License and upstream terms

No license value is declared in the Hub metadata for this mixed artifact bundle. Source-code licensing, generated manuscript artifacts, trained parameters, and data derived from SWellEx-96 may have different applicable terms. Uploaders should confirm redistribution requirements and then add a valid Hugging Face license field if appropriate. This README does not relicense the upstream recordings or documentation.