Metadata-Version: 2.4
Name: sonarkad
Version: 1.0.2
Summary: Physics-aligned Kolmogorov-Arnold decomposition for sonar range-frequency fields
Author: SonarKAD contributors
License: MIT
Keywords: sonar,signal-processing,kolmogorov-arnold,low-rank,diagnostics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Requires-Dist: matplotlib>=3.5
Requires-Dist: PyYAML>=6.0
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: tracking
Requires-Dist: wandb>=0.16; extra == "tracking"

# SonarKAD

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

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

```text
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

```bash
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:

```bash
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:

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

Then verify the layout:

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

## Reproduce assets

Full run:

```bash
bash run_all.sh
```

GPU / multi-GPU run:

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

Main generated files:

```text
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:

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

## Focused commands

Prepare one event:

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

Run selected-rank materialization:

```bash
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:

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

## Use a saved bundle

```python
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](https://huggingface.co/soundai2016/SonarKAD)


## Repository map

```text
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.
