Metadata-Version: 2.4
Name: SonarKAN
Version: 1.1.0
Summary: Gauge-fixed KAN models for passive-sonar range-frequency fields.
License: Apache-2.0
Keywords: SonarKAN,Kolmogorov-Arnold network,passive sonar,range-frequency coupling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: PyYAML
Requires-Dist: torch
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

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

```bash
python -m pip install -e ./src
```

Or from this directory:

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

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

A minimal additive model can be constructed with:

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

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

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

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

It writes:

```text
outputs/figures/fig1_framework.pdf
outputs/figures/fig2_decomposition.pdf
```

## Package layout

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

