kanx 0.2.0__tar.gz → 0.2.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {kanx-0.2.0/src/kanx.egg-info → kanx-0.2.2}/PKG-INFO +86 -49
- {kanx-0.2.0 → kanx-0.2.2}/README.md +84 -47
- {kanx-0.2.0 → kanx-0.2.2}/pyproject.toml +2 -2
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/__init__.py +2 -2
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/layers.py +4 -3
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/prune.py +3 -2
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/matrix_kan.py +23 -12
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/utils.py +9 -7
- {kanx-0.2.0 → kanx-0.2.2/src/kanx.egg-info}/PKG-INFO +86 -49
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/SOURCES.txt +1 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_helm_chart.py +1 -1
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_matrix_kan.py +12 -5
- kanx-0.2.2/tests/test_param_counts.py +66 -0
- {kanx-0.2.0 → kanx-0.2.2}/LICENSE +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/setup.cfg +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/__main__.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/callbacks.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/config.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/__init__.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/feynman.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/tabular.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/inference.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/model.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/onnx_export.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/quickstart.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/__init__.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/layers.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/model.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/onnx_export.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/symbolic.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/trainer.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/train.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx/viz.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/dependency_links.txt +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/entry_points.txt +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/requires.txt +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/top_level.txt +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_api.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_api_hardening.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_api_metrics.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_benchmark_smoke.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_callbacks.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_cli.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_config.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_distributed_smoke.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_e2e_live.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_grid_range_guard.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_grid_update.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_hub.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_layers.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_model.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_onnx_tf.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_performance.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_precision.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_properties.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_prune.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_quickstart_api.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_simple_torch.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_symbolic.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_tf_torch.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_torch_backend.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_torch_kan.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_train_inference.py +0 -0
- {kanx-0.2.0 → kanx-0.2.2}/tests/test_viz.py +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: kanx
|
|
3
|
-
Version: 0.2.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 0.2.2
|
|
4
|
+
Summary: Kolmogorov-Arnold Networks for TensorFlow and PyTorch, with ONNX export.
|
|
5
5
|
Author: kanx contributors
|
|
6
6
|
License: Apache-2.0
|
|
7
7
|
Project-URL: Homepage, https://github.com/Mattral/KANX
|
|
@@ -69,9 +69,8 @@ Dynamic: license-file
|
|
|
69
69
|
<h1 align="center">🚀 kanx</h1>
|
|
70
70
|
|
|
71
71
|
<p align="center">
|
|
72
|
-
<strong>
|
|
73
|
-
<em>
|
|
74
|
-
<em> > `kanx` is the only Kolmogorov-Arnold Network (KAN) library purpose-built for production deployment.</em>
|
|
72
|
+
<strong>Kolmogorov-Arnold Networks for TensorFlow and PyTorch</strong><br>
|
|
73
|
+
<em>A Python library with ONNX export, a FastAPI service, a CLI, and Docker and Kubernetes configs.</em>
|
|
75
74
|
</p>
|
|
76
75
|
|
|
77
76
|
<p align="center">
|
|
@@ -79,19 +78,20 @@ Dynamic: license-file
|
|
|
79
78
|
<a href="https://pypi.org/project/kanx/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/kanx?style=for-the-badge&color=A78BFA"></a>
|
|
80
79
|
<a href="https://pepy.tech/project/kanx"> <img alt="Total Downloads" src="https://img.shields.io/pepy/dt/kanx?style=for-the-badge&color=F87171"></a>
|
|
81
80
|
<a href="./CITATION.cff"><img alt="Cite" src="https://img.shields.io/badge/cite-CITATION.cff-brightgreen?style=for-the-badge"></a>
|
|
81
|
+
<a href="https://github.com/Mattral/KANX/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Mattral/KANX/ci.yml?branch=main&label=CI&style=for-the-badge&logo=github"></a>
|
|
82
82
|
|
|
83
83
|
<img alt="Python" src="https://img.shields.io/pypi/pyversions/kanx?style=for-the-badge&logo=python&logoColor=white">
|
|
84
84
|
<a href="https://mattral.github.io/KANX/"><img alt="Docs" src="https://img.shields.io/badge/docs-mkdocs--material-22C55E?style=for-the-badge&logo=readthedocs&logoColor=white"></a>
|
|
85
85
|
<a href="https://colab.research.google.com/github/Mattral/KANX/blob/main/notebooks/quickstart.ipynb"><img alt="Colab" src="https://img.shields.io/badge/Colab-train_in_2_to_5_min-F9AB00?style=for-the-badge&logo=googlecolab&logoColor=white"></a>
|
|
86
86
|
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-A78BFA?style=for-the-badge"></a>
|
|
87
87
|
<a href="https://doi.org/10.5281/zenodo.20615396">
|
|
88
|
-
<img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.
|
|
88
|
+
<img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20615396-7C3AED?style=for-the-badge&logo=zenodo&logoColor=white">
|
|
89
89
|
</a>
|
|
90
90
|
|
|
91
91
|
</p>
|
|
92
92
|
|
|
93
|
-
> **`pip install kanx`** ·
|
|
94
|
-
> One library. Two backends.
|
|
93
|
+
> **`pip install kanx`** · On one smooth 2-D target, `sin(πx₁) + cos(2πx₂)`, KAN[2,32,1] (864 parameters) reaches a mean test MSE of 1.09×10⁻⁴. MLP[2,64,64,1] (4,417 parameters, 5.1× more) reaches 6.43×10⁻⁴. That is three init seeds on one dataset, on one CPU. The same KAN is 8.3× slower at inference (29.15 ms against 3.53 ms for 4,096 rows) and 1.6× slower to train. On UCI diabetes (one 5-fold CV run in the quickstart notebook) the TensorFlow KAN does not beat ridge regression: mean R² 0.456 against 0.490. Tables and caveats are in the benchmark section.
|
|
94
|
+
> One library. Two backends. ONNX export. Docker and Kubernetes configs. Prometheus metrics, TensorBoard logging, Hub and symbolic extras.
|
|
95
95
|
|
|
96
96
|
---
|
|
97
97
|
|
|
@@ -99,7 +99,7 @@ Dynamic: license-file
|
|
|
99
99
|
## ⭐ Why kanx?
|
|
100
100
|
<div align="center">
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
Feature comparison with three other KAN libraries:
|
|
103
103
|
|
|
104
104
|
| | [pykan](https://github.com/KindXiaoming/pykan) | [efficient-kan](https://github.com/Blealtan/efficient-kan) | [mlx-kan](https://github.com/Goekdeniz-Guelmez/mlx-kan) | **kanx** |
|
|
105
105
|
|---|:---:|:---:|:---:|:---:|
|
|
@@ -109,48 +109,46 @@ Every other KAN library stops at research. `kanx` goes the full distance:
|
|
|
109
109
|
| REST API service | ❌ | ❌ | ❌ | ✅ FastAPI |
|
|
110
110
|
| Docker + K8s | ❌ | ❌ | ❌ | ✅ |
|
|
111
111
|
| Property-based tests | ❌ | ❌ | ❌ | ✅ Hypothesis |
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
112
|
+
| PyPI | ✅ | ❌ | ✅ | ✅ |
|
|
113
|
+
| CI/CD release pipeline | ✅ PyPI on release | ❌ | ✅ PyPI on release | ✅ PyPI + GHCR + Pages |
|
|
114
|
+
|
|
115
|
+
Other columns checked on 21 November 2026 against each project's README, docs, and source: pykan v0.2.8 (master `ecde4ec`, 19 January 2025), efficient-kan master `7b6ce1c` (3 July 2024, no tagged release), and mlx-kan v0.2.5 (main `252ba79`, 18 June 2025). ❌ means the feature was not found there. The vectorized B-spline row was not re-checked.
|
|
115
116
|
|
|
116
117
|
</div>
|
|
117
118
|
|
|
118
|
-
|
|
119
|
+
What kanx provides:
|
|
119
120
|
1. **Multi-Backend Support:** Native TensorFlow and PyTorch (`MatrixKAN`) implementations.
|
|
120
121
|
2. **Real Deployment:** True ONNX export, FastAPI (`/api/predict`), Docker, and Kubernetes configs out-of-the-box.
|
|
121
|
-
3. **
|
|
122
|
-
4. **Grid
|
|
122
|
+
3. **MatrixKAN:** Experimental. The forward pass is the same Cox–de Boor recursion as `KAN`, written as a Python loop over each basis index. It does not run a batched GEMM. On a Tesla T4 that loop stays slower from width 32 to 512.
|
|
123
|
+
4. **Grid calibration:** `fit_grid_to_data` places the stored knots on the training inputs. The basis is exactly zero only past the outermost extended knot.
|
|
123
124
|
|
|
124
125
|
|
|
125
126
|
---
|
|
126
127
|
|
|
127
128
|
## 📊 Benchmarks (reproducible, fair, multi-baseline)
|
|
128
129
|
|
|
129
|
-
<div align="center">
|
|
130
|
-
|
|
131
130
|
Synthetic 2-D regression target `y = sin(π·x₁) + cos(2π·x₂)`,
|
|
132
|
-
100 epochs, Adam(lr=1e-2), batch=128
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
| KAN[2,
|
|
139
|
-
|
|
|
140
|
-
| MLP[2,
|
|
141
|
-
| MLP[2,
|
|
142
|
-
|
|
143
|
-
</div>
|
|
131
|
+
100 epochs, Adam(lr=1e-2), batch=128.
|
|
132
|
+
Intel Core i9-9900 at 3.10 GHz, Windows, Python 3.11.17, TensorFlow 2.21.0.
|
|
133
|
+
Init seeds 0, 1, and 2 share one dataset. Inference is ten warmup forwards of 4,096 rows, then the median of twenty. The ± is the population standard deviation across seeds.
|
|
134
|
+
|
|
135
|
+
| Model | Params | Train (s) | Infer 4k (ms) | **Test MSE** |
|
|
136
|
+
|---|---:|---:|---:|---:|
|
|
137
|
+
| KAN[2,16,1] | 432 | 9.42 ± 0.12 | 26.72 ± 0.31 | 2.58×10⁻⁴ ± 1.71×10⁻⁴ |
|
|
138
|
+
| KAN[2,32,1] | 864 | 11.12 ± 0.18 | 29.15 ± 0.46 | **1.09×10⁻⁴ ± 6.34×10⁻⁵** |
|
|
139
|
+
| MLP[2,32,1] | 129 | 6.09 ± 0.07 | 2.06 ± 0.03 | 4.62×10⁻¹ ± 1.40×10⁻³ |
|
|
140
|
+
| MLP[2,16,16,1] | 337 | 6.78 ± 0.23 | 2.90 ± 0.05 | 1.44×10⁻³ ± 3.83×10⁻⁴ |
|
|
141
|
+
| MLP[2,64,64,1] | 4417 | 7.00 ± 0.07 | 3.53 ± 0.05 | 6.43×10⁻⁴ ± 4.02×10⁻⁴ |
|
|
144
142
|
|
|
145
143
|
<p align="center">
|
|
146
144
|
<img src="docs/assets/benchmark.png" alt="Test MSE for the published KAN and MLP runs" width="720"/>
|
|
147
145
|
</p>
|
|
148
146
|
|
|
149
|
-
**Honest read.** The
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
147
|
+
**Honest read.** The wider KAN has the lower mean test MSE. The smaller KAN's test MSE moves by about as much as its mean across the three seeds. Inference increases with width, 26.7 ms then 29.2 ms. Both are several times the MLPs on this CPU: KAN[2,16,1] is 7.57× MLP[2,64,64,1]. The 0.2.0 tables each timed one unwarmed forward and are not averaged into these cells. On non-smooth or high-dimensional targets, this accuracy picture often reverses. We do not claim KANs are universally better than MLPs.
|
|
148
|
+
|
|
149
|
+
KAN[2,16,1] has 10.2× fewer parameters than MLP[2,64,64,1] and a lower mean test MSE (2.58×10⁻⁴ against 6.43×10⁻⁴). The mean ± one standard deviation ranges of the two overlap across the three seeds, so this run does not show it ahead of the 10× larger MLP. KAN[2,32,1] against the same MLP is 5.1× fewer parameters, 5.9× lower mean test MSE, and 8.3× the inference time.
|
|
150
|
+
|
|
151
|
+
On UCI diabetes (442 rows, 10 features, `KFold(5, shuffle=True, random_state=0)`, 100 epochs, kanx 0.2.0, section 13 of `notebooks/quickstart.ipynb`), KAN-TF[10,32,1] scores mean R² 0.456 ± 0.114 and ridge regression 0.490 ± 0.091. The KAN is below ridge on three of the five folds. The PyTorch KAN in the same cell scores −0.006. This is one run with an unseeded KAN initialization.
|
|
154
152
|
|
|
155
153
|
Reproduce with `python benchmarks/compare_mlp.py` (quick, 100 epochs) or
|
|
156
154
|
`python benchmarks/compare_mlp.py --long` (1000 epochs + early-stopping).
|
|
@@ -178,12 +176,13 @@ model.predict([[0.5, 0.2]]) # → array([[1.04…]])
|
|
|
178
176
|
|
|
179
177
|
> **⚠️ Grid calibration — two methods**
|
|
180
178
|
>
|
|
181
|
-
>
|
|
179
|
+
> The stored knots default to `[-1, 1]` (`grid_size=5` is six knots, spacing 0.4). `extend_grid` adds `spline_order` knots of that spacing on each side, so the default cubic basis runs out to about ±2.2. The basis sums to 1 on the stored interval, is still nonzero at 1.7 (the sum is about 0.32), and is exactly zero at and beyond the outermost knot. Past that knot the layer is only the SiLU residual. Put the stored interval on the data one of two ways:
|
|
182
180
|
>
|
|
183
181
|
> **Static approach** (pre-training):
|
|
184
182
|
> ```python
|
|
185
183
|
> from kanx import KAN, fit_grid_to_data
|
|
186
184
|
> model = KAN([n_features, 64, 1])
|
|
185
|
+
> model.build((None, n_features)) # weights exist only after build
|
|
187
186
|
> fit_grid_to_data(model, X_train) # one-time grid fit
|
|
188
187
|
> model.fit(X_train, y_train, epochs=30)
|
|
189
188
|
> ```
|
|
@@ -196,13 +195,13 @@ model.predict([[0.5, 0.2]]) # → array([[1.04…]])
|
|
|
196
195
|
> model.fit(X_train, y_train, epochs=15) # continue training
|
|
197
196
|
> ```
|
|
198
197
|
>
|
|
199
|
-
> `kanx.check_input_range(model, X)`
|
|
198
|
+
> `kanx.check_input_range(model, X)` logs a warning when a row leaves the stored grid. That boundary is the interval you fit, which is stricter than the hard zero at the outermost knot.
|
|
200
199
|
|
|
201
|
-
|
|
200
|
+
Zero out edges that barely contribute. `prune` sets the spline coefficients and the base weight to zero. It does not remove the slot, and the contraction still visits it. `threshold` is an absolute cutoff on the edge score. `relative` zeros edges at or below that fraction of the strongest edge in the same layer. Pass `samples` to score each edge by its RMS on real inputs. The same method is on the PyTorch `KAN` and on `MatrixKAN`.
|
|
202
201
|
|
|
203
202
|
```python
|
|
204
|
-
model.prune(relative=0.01)
|
|
205
|
-
model.prune(threshold=1e-3, samples=X_train)
|
|
203
|
+
model.prune(relative=0.01) # zero edges at or below 1% of the peak
|
|
204
|
+
model.prune(threshold=1e-3, samples=X_train) # coefficients become zero; shapes stay
|
|
206
205
|
```
|
|
207
206
|
|
|
208
207
|
Plot what is left. Each edge is a learned 1-D function (SiLU residual plus B-spline). `plot_edges` needs matplotlib (`pip install "kanx[viz]"`). `write_edge_viewer` writes a single HTML file with a layer picker and a hover readout.
|
|
@@ -218,9 +217,9 @@ write_edge_viewer(model, "edges.html")
|
|
|
218
217
|
<img src="docs/assets/edge_functions.png" alt="Learned edge functions on a two-input KAN" width="640"/>
|
|
219
218
|
</p>
|
|
220
219
|
|
|
221
|
-
Layer 0 of a `KAN([2, 1])` fit to `sin(π x₁) + 0.6 x₂²`. The
|
|
220
|
+
Layer 0 of a `KAN([2, 1])` fit to `sin(π x₁) + 0.6 x₂²`. The left edge follows the sine. The right edge follows a bowl. That is a reading of this plot. It is not a proof that each edge owns one term, and a shorter fit of the same target can leave the right side of the bowl unfinished.
|
|
222
221
|
|
|
223
|
-
The TensorFlow spline contraction can run in reduced precision, and the forward pass can be XLA-compiled. Weights and the returned tensor stay float32. The Cox
|
|
222
|
+
The TensorFlow spline contraction can run in reduced precision, and the forward pass can be XLA-compiled. Weights and the returned tensor stay float32. The Cox–de Boor basis stays float32 because `(x − tᵢ)` cancels near a knot and the divided differences amplify the error. bfloat16 has fewer mantissa bits than float16 (8 versus 11), so it is the worse choice for the basis. Float16's largest finite value is 65504. That is a property of the format, not an overflow measured in this contraction: on these knots the cubic basis peaks at 2/3, and the coefficients start small. bfloat16 is the practical training dtype because float16 gradients underflow when training does not use loss scaling. Knot spacing does not underflow in float16 at grid size 5 (spacing 0.4) or at grid size 1000 (spacing 0.002). Against a float64 `b_spline_basis` on the same extended knots, the max absolute error is 1.9×10⁻⁷ in float32 and 1.5×10⁻³ in float16 at grid size 5 (1.2×10⁻² in bfloat16). At grid size 1000 it is 2.5×10⁻⁵, 0.16, and 0.67. The grid-size-1000 gap is mostly the input rounding onto a step comparable to the 0.002 knot spacing.
|
|
224
223
|
|
|
225
224
|
```python
|
|
226
225
|
model = KAN([8, 16, 1], precision="bfloat16", jit_compile=True)
|
|
@@ -261,17 +260,30 @@ model.predict([[0.5, 0.2]])
|
|
|
261
260
|
---
|
|
262
261
|
|
|
263
262
|
|
|
264
|
-
### ⚡
|
|
263
|
+
### ⚡ MatrixKAN
|
|
265
264
|
|
|
266
|
-
|
|
265
|
+
`MatrixKAN` is experimental. It evaluates the same Cox–de Boor basis as `KAN`, with a Python loop over each basis index. `build_recurrence_matrix_batch` is not used, and a constant matrix cannot represent the recursion because the weights depend on `x`. The 0.2.0 docstring called this a batched GEMM. That description was wrong.
|
|
267
266
|
|
|
268
267
|
```python
|
|
269
268
|
from kanx.torch import MatrixKAN
|
|
270
269
|
|
|
271
|
-
model = MatrixKAN([
|
|
272
|
-
model.fit(X, y, epochs=30) # ~1.5–2× faster on GPU vs standard KAN
|
|
270
|
+
model = MatrixKAN([2, 32, 1], grid_size=5, spline_order=3)
|
|
273
271
|
```
|
|
274
272
|
|
|
273
|
+
The table below times that loop, not a matrix algorithm. Tesla T4, torch 2.11.0+cu130, kanx 0.2.0, float32, grid size 5, spline order 3, shape `[2, width, 1]`. Ten warmup calls, then the mean of 50, with `torch.cuda.synchronize` around the loop. Cells are MatrixKAN milliseconds divided by KAN milliseconds. The JSON is `benchmarks/results/matrixkan_t4_0.2.0.json`.
|
|
274
|
+
|
|
275
|
+
| width \ batch | 1,024 | 4,096 | 8,192 | 16,384 |
|
|
276
|
+
|---:|---:|---:|---:|---:|
|
|
277
|
+
| 32 | 6.41 | 6.37 | 5.53 | 3.24 |
|
|
278
|
+
| 64 | 6.58 | 5.88 | 3.59 | 3.32 |
|
|
279
|
+
| 128 | 6.72 | 3.32 | 3.35 | 3.30 |
|
|
280
|
+
| 256 | 5.74 | 3.37 | 3.32 | 3.29 |
|
|
281
|
+
| 512 | 3.33 | 3.32 | 3.29 | 3.27 |
|
|
282
|
+
|
|
283
|
+
At width 32 and batch 4,096 the calls are 2.10 ms and 13.37 ms. At width 512 and batch 16,384 they are 67.0 ms and 219 ms. The ratio falls from 6.4× to 3.3× and stays there. At the small end the extra cost is kernel launches: on CPU, one `MatrixKANLinear(32, 1)` forward at batch 1,024 recorded 1,394 ATen ops against 205 for `KANLinear` (torch 2.14.1+cpu). The ~2 ms KAN floor at width 32 is mostly launch overhead as well. A uniform-grid cubic basis can be one small multiply on `[1, u, u², u³]`. That path is not this class, and grids from `update_grid_from_samples` are not uniform.
|
|
284
|
+
|
|
285
|
+
A second T4 run copies the weights, checks that the outputs match, and times one training step. It sweeps spline orders 3, 5, and 7. The JSON is `benchmarks/results/matrixkan_t4_sweep_0.2.0.json`. Every row matched, with max absolute error 0. At batch 16,384 the forward ratio is about 3.3×, 4.0×, and 4.6× to 4.9× for orders 3, 5, and 7. The backward ratio on those rows is about 4.6×, 6.2×, and 7.3×. The Python loop does more iterations as the order rises, and the ratio rises with it. One order-3 cell does not match the table above: width 512, batch 1,024, MatrixKAN forward 34.9 ms here and 14.9 ms in the earlier run. The other order-3 forward cells agree. This run does not replace that table.
|
|
286
|
+
|
|
275
287
|
TensorBoard logging and symbolic edge fitting are included:
|
|
276
288
|
|
|
277
289
|
```bash
|
|
@@ -386,7 +398,7 @@ export_onnx_tf(model, "kan.onnx")
|
|
|
386
398
|
|
|
387
399
|
✔ Dynamic batch
|
|
388
400
|
✔ Verified numerical consistency (1e-5)
|
|
389
|
-
✔
|
|
401
|
+
✔ Runs in ONNX Runtime (tested in CI). TensorRT and OpenVINO are not tested.
|
|
390
402
|
|
|
391
403
|
---
|
|
392
404
|
|
|
@@ -415,6 +427,31 @@ python -m kanx predict --checkpoint model.keras --input X.json
|
|
|
415
427
|
|
|
416
428
|
---
|
|
417
429
|
|
|
430
|
+
## Status and scope
|
|
431
|
+
|
|
432
|
+
kanx is at 0.2.2. Its package metadata marks it Beta.
|
|
433
|
+
|
|
434
|
+
**Tested in CI** ([`ci.yml`](https://github.com/Mattral/KANX/blob/main/.github/workflows/ci.yml), every push and pull request to `main`):
|
|
435
|
+
|
|
436
|
+
- `ruff` on `src`, `tests`, `api`, `benchmarks`, and `examples`.
|
|
437
|
+
- `pytest tests/` on Python 3.10, 3.11, and 3.12, Ubuntu, CPU only. This covers the TensorFlow backend, the CPU PyTorch backend, ONNX export checked in ONNX Runtime, the FastAPI service against a live `uvicorn`, Hypothesis property tests, Helm chart rendering, and the CPU distributed smoke tests. The last `main` run before this section was written reported 181 passed and 2 skipped on each Python version, with 77% coverage of `src/kanx`. The two skips are the MatrixKAN CUDA tests.
|
|
438
|
+
- A Docker build, with `/api/health`, `/api/info`, and `/api/predict` called on the running container.
|
|
439
|
+
- An MkDocs build, and `--smoke` runs of both benchmark scripts.
|
|
440
|
+
|
|
441
|
+
**Not tested in CI:**
|
|
442
|
+
|
|
443
|
+
- GPU code paths. The CUDA tests are skipped, and the Tesla T4 MatrixKAN tables are manual runs.
|
|
444
|
+
- Windows and macOS. The published CPU benchmark is a manual run on Windows.
|
|
445
|
+
- TensorRT and OpenVINO. Only ONNX Runtime runs the exported models.
|
|
446
|
+
- Installing the Kubernetes manifests or the Helm chart on a cluster. The chart is only rendered.
|
|
447
|
+
- The published benchmark numbers. `--smoke` checks that the scripts run and produce finite metrics. It does not reproduce the tables.
|
|
448
|
+
- The notebooks.
|
|
449
|
+
- `black` runs with `|| true`, so formatting cannot fail the job. `mypy` is configured in `pyproject.toml` but is not run.
|
|
450
|
+
|
|
451
|
+
**What 1.0 means.** Until 1.0, a minor release can change the public API, and the changelog lists each change. From 1.0, the documented API follows Semantic Versioning: `kanx.KAN`, `KANLinear`, `fit_grid_to_data`, `export_onnx_tf`, `kanx.torch.KAN`, `kanx.torch.export_onnx`, the `python -m kanx` commands, and the REST endpoints change incompatibly only in a new major version. Anything marked experimental, currently `MatrixKAN`, is outside that promise. No 1.0 date is set.
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
418
455
|
## ⭐ Quality
|
|
419
456
|
|
|
420
457
|
- Unit, integration, live API, property-based, and performance tests in [`tests/`](tests/)
|
|
@@ -457,9 +494,9 @@ the library.
|
|
|
457
494
|
|
|
458
495
|
Our work is formally documented and available as a preprint:
|
|
459
496
|
|
|
460
|
-
- 📘 Title: *KANX:
|
|
497
|
+
- 📘 Title: *KANX: An Open-Source Library for Kolmogorov-Arnold Networks*
|
|
461
498
|
- 📍 DOI: https://doi.org/10.5281/zenodo.20615396
|
|
462
|
-
- 📂 Zenodo: https://zenodo.org/records/
|
|
499
|
+
- 📂 Zenodo: https://zenodo.org/records/20615396
|
|
463
500
|
- 📄 [Read Paper (preprint)](docs/preprint.pdf)
|
|
464
501
|
- 📄 [Read Paper (ArXiv)](docs/KANX_ArXiv_Paper.pdf)
|
|
465
502
|
|
|
@@ -469,7 +506,7 @@ Our work is formally documented and available as a preprint:
|
|
|
469
506
|
|
|
470
507
|
```bibtex
|
|
471
508
|
@article{mattral2026kanx,
|
|
472
|
-
title={KANX:
|
|
509
|
+
title={KANX: An Open-Source Library for Kolmogorov-Arnold Networks},
|
|
473
510
|
author={Myet, Min Htet},
|
|
474
511
|
year={2026},
|
|
475
512
|
doi={10.5281/zenodo.20615396},
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
<h1 align="center">🚀 kanx</h1>
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<strong>
|
|
5
|
-
<em>
|
|
6
|
-
<em> > `kanx` is the only Kolmogorov-Arnold Network (KAN) library purpose-built for production deployment.</em>
|
|
4
|
+
<strong>Kolmogorov-Arnold Networks for TensorFlow and PyTorch</strong><br>
|
|
5
|
+
<em>A Python library with ONNX export, a FastAPI service, a CLI, and Docker and Kubernetes configs.</em>
|
|
7
6
|
</p>
|
|
8
7
|
|
|
9
8
|
<p align="center">
|
|
@@ -11,19 +10,20 @@
|
|
|
11
10
|
<a href="https://pypi.org/project/kanx/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/kanx?style=for-the-badge&color=A78BFA"></a>
|
|
12
11
|
<a href="https://pepy.tech/project/kanx"> <img alt="Total Downloads" src="https://img.shields.io/pepy/dt/kanx?style=for-the-badge&color=F87171"></a>
|
|
13
12
|
<a href="./CITATION.cff"><img alt="Cite" src="https://img.shields.io/badge/cite-CITATION.cff-brightgreen?style=for-the-badge"></a>
|
|
13
|
+
<a href="https://github.com/Mattral/KANX/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Mattral/KANX/ci.yml?branch=main&label=CI&style=for-the-badge&logo=github"></a>
|
|
14
14
|
|
|
15
15
|
<img alt="Python" src="https://img.shields.io/pypi/pyversions/kanx?style=for-the-badge&logo=python&logoColor=white">
|
|
16
16
|
<a href="https://mattral.github.io/KANX/"><img alt="Docs" src="https://img.shields.io/badge/docs-mkdocs--material-22C55E?style=for-the-badge&logo=readthedocs&logoColor=white"></a>
|
|
17
17
|
<a href="https://colab.research.google.com/github/Mattral/KANX/blob/main/notebooks/quickstart.ipynb"><img alt="Colab" src="https://img.shields.io/badge/Colab-train_in_2_to_5_min-F9AB00?style=for-the-badge&logo=googlecolab&logoColor=white"></a>
|
|
18
18
|
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-A78BFA?style=for-the-badge"></a>
|
|
19
19
|
<a href="https://doi.org/10.5281/zenodo.20615396">
|
|
20
|
-
<img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.
|
|
20
|
+
<img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20615396-7C3AED?style=for-the-badge&logo=zenodo&logoColor=white">
|
|
21
21
|
</a>
|
|
22
22
|
|
|
23
23
|
</p>
|
|
24
24
|
|
|
25
|
-
> **`pip install kanx`** ·
|
|
26
|
-
> One library. Two backends.
|
|
25
|
+
> **`pip install kanx`** · On one smooth 2-D target, `sin(πx₁) + cos(2πx₂)`, KAN[2,32,1] (864 parameters) reaches a mean test MSE of 1.09×10⁻⁴. MLP[2,64,64,1] (4,417 parameters, 5.1× more) reaches 6.43×10⁻⁴. That is three init seeds on one dataset, on one CPU. The same KAN is 8.3× slower at inference (29.15 ms against 3.53 ms for 4,096 rows) and 1.6× slower to train. On UCI diabetes (one 5-fold CV run in the quickstart notebook) the TensorFlow KAN does not beat ridge regression: mean R² 0.456 against 0.490. Tables and caveats are in the benchmark section.
|
|
26
|
+
> One library. Two backends. ONNX export. Docker and Kubernetes configs. Prometheus metrics, TensorBoard logging, Hub and symbolic extras.
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
## ⭐ Why kanx?
|
|
32
32
|
<div align="center">
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Feature comparison with three other KAN libraries:
|
|
35
35
|
|
|
36
36
|
| | [pykan](https://github.com/KindXiaoming/pykan) | [efficient-kan](https://github.com/Blealtan/efficient-kan) | [mlx-kan](https://github.com/Goekdeniz-Guelmez/mlx-kan) | **kanx** |
|
|
37
37
|
|---|:---:|:---:|:---:|:---:|
|
|
@@ -41,48 +41,46 @@ Every other KAN library stops at research. `kanx` goes the full distance:
|
|
|
41
41
|
| REST API service | ❌ | ❌ | ❌ | ✅ FastAPI |
|
|
42
42
|
| Docker + K8s | ❌ | ❌ | ❌ | ✅ |
|
|
43
43
|
| Property-based tests | ❌ | ❌ | ❌ | ✅ Hypothesis |
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
44
|
+
| PyPI | ✅ | ❌ | ✅ | ✅ |
|
|
45
|
+
| CI/CD release pipeline | ✅ PyPI on release | ❌ | ✅ PyPI on release | ✅ PyPI + GHCR + Pages |
|
|
46
|
+
|
|
47
|
+
Other columns checked on 21 November 2026 against each project's README, docs, and source: pykan v0.2.8 (master `ecde4ec`, 19 January 2025), efficient-kan master `7b6ce1c` (3 July 2024, no tagged release), and mlx-kan v0.2.5 (main `252ba79`, 18 June 2025). ❌ means the feature was not found there. The vectorized B-spline row was not re-checked.
|
|
47
48
|
|
|
48
49
|
</div>
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
What kanx provides:
|
|
51
52
|
1. **Multi-Backend Support:** Native TensorFlow and PyTorch (`MatrixKAN`) implementations.
|
|
52
53
|
2. **Real Deployment:** True ONNX export, FastAPI (`/api/predict`), Docker, and Kubernetes configs out-of-the-box.
|
|
53
|
-
3. **
|
|
54
|
-
4. **Grid
|
|
54
|
+
3. **MatrixKAN:** Experimental. The forward pass is the same Cox–de Boor recursion as `KAN`, written as a Python loop over each basis index. It does not run a batched GEMM. On a Tesla T4 that loop stays slower from width 32 to 512.
|
|
55
|
+
4. **Grid calibration:** `fit_grid_to_data` places the stored knots on the training inputs. The basis is exactly zero only past the outermost extended knot.
|
|
55
56
|
|
|
56
57
|
|
|
57
58
|
---
|
|
58
59
|
|
|
59
60
|
## 📊 Benchmarks (reproducible, fair, multi-baseline)
|
|
60
61
|
|
|
61
|
-
<div align="center">
|
|
62
|
-
|
|
63
62
|
Synthetic 2-D regression target `y = sin(π·x₁) + cos(2π·x₂)`,
|
|
64
|
-
100 epochs, Adam(lr=1e-2), batch=128
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
| KAN[2,
|
|
71
|
-
|
|
|
72
|
-
| MLP[2,
|
|
73
|
-
| MLP[2,
|
|
74
|
-
|
|
75
|
-
</div>
|
|
63
|
+
100 epochs, Adam(lr=1e-2), batch=128.
|
|
64
|
+
Intel Core i9-9900 at 3.10 GHz, Windows, Python 3.11.17, TensorFlow 2.21.0.
|
|
65
|
+
Init seeds 0, 1, and 2 share one dataset. Inference is ten warmup forwards of 4,096 rows, then the median of twenty. The ± is the population standard deviation across seeds.
|
|
66
|
+
|
|
67
|
+
| Model | Params | Train (s) | Infer 4k (ms) | **Test MSE** |
|
|
68
|
+
|---|---:|---:|---:|---:|
|
|
69
|
+
| KAN[2,16,1] | 432 | 9.42 ± 0.12 | 26.72 ± 0.31 | 2.58×10⁻⁴ ± 1.71×10⁻⁴ |
|
|
70
|
+
| KAN[2,32,1] | 864 | 11.12 ± 0.18 | 29.15 ± 0.46 | **1.09×10⁻⁴ ± 6.34×10⁻⁵** |
|
|
71
|
+
| MLP[2,32,1] | 129 | 6.09 ± 0.07 | 2.06 ± 0.03 | 4.62×10⁻¹ ± 1.40×10⁻³ |
|
|
72
|
+
| MLP[2,16,16,1] | 337 | 6.78 ± 0.23 | 2.90 ± 0.05 | 1.44×10⁻³ ± 3.83×10⁻⁴ |
|
|
73
|
+
| MLP[2,64,64,1] | 4417 | 7.00 ± 0.07 | 3.53 ± 0.05 | 6.43×10⁻⁴ ± 4.02×10⁻⁴ |
|
|
76
74
|
|
|
77
75
|
<p align="center">
|
|
78
76
|
<img src="docs/assets/benchmark.png" alt="Test MSE for the published KAN and MLP runs" width="720"/>
|
|
79
77
|
</p>
|
|
80
78
|
|
|
81
|
-
**Honest read.** The
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
79
|
+
**Honest read.** The wider KAN has the lower mean test MSE. The smaller KAN's test MSE moves by about as much as its mean across the three seeds. Inference increases with width, 26.7 ms then 29.2 ms. Both are several times the MLPs on this CPU: KAN[2,16,1] is 7.57× MLP[2,64,64,1]. The 0.2.0 tables each timed one unwarmed forward and are not averaged into these cells. On non-smooth or high-dimensional targets, this accuracy picture often reverses. We do not claim KANs are universally better than MLPs.
|
|
80
|
+
|
|
81
|
+
KAN[2,16,1] has 10.2× fewer parameters than MLP[2,64,64,1] and a lower mean test MSE (2.58×10⁻⁴ against 6.43×10⁻⁴). The mean ± one standard deviation ranges of the two overlap across the three seeds, so this run does not show it ahead of the 10× larger MLP. KAN[2,32,1] against the same MLP is 5.1× fewer parameters, 5.9× lower mean test MSE, and 8.3× the inference time.
|
|
82
|
+
|
|
83
|
+
On UCI diabetes (442 rows, 10 features, `KFold(5, shuffle=True, random_state=0)`, 100 epochs, kanx 0.2.0, section 13 of `notebooks/quickstart.ipynb`), KAN-TF[10,32,1] scores mean R² 0.456 ± 0.114 and ridge regression 0.490 ± 0.091. The KAN is below ridge on three of the five folds. The PyTorch KAN in the same cell scores −0.006. This is one run with an unseeded KAN initialization.
|
|
86
84
|
|
|
87
85
|
Reproduce with `python benchmarks/compare_mlp.py` (quick, 100 epochs) or
|
|
88
86
|
`python benchmarks/compare_mlp.py --long` (1000 epochs + early-stopping).
|
|
@@ -110,12 +108,13 @@ model.predict([[0.5, 0.2]]) # → array([[1.04…]])
|
|
|
110
108
|
|
|
111
109
|
> **⚠️ Grid calibration — two methods**
|
|
112
110
|
>
|
|
113
|
-
>
|
|
111
|
+
> The stored knots default to `[-1, 1]` (`grid_size=5` is six knots, spacing 0.4). `extend_grid` adds `spline_order` knots of that spacing on each side, so the default cubic basis runs out to about ±2.2. The basis sums to 1 on the stored interval, is still nonzero at 1.7 (the sum is about 0.32), and is exactly zero at and beyond the outermost knot. Past that knot the layer is only the SiLU residual. Put the stored interval on the data one of two ways:
|
|
114
112
|
>
|
|
115
113
|
> **Static approach** (pre-training):
|
|
116
114
|
> ```python
|
|
117
115
|
> from kanx import KAN, fit_grid_to_data
|
|
118
116
|
> model = KAN([n_features, 64, 1])
|
|
117
|
+
> model.build((None, n_features)) # weights exist only after build
|
|
119
118
|
> fit_grid_to_data(model, X_train) # one-time grid fit
|
|
120
119
|
> model.fit(X_train, y_train, epochs=30)
|
|
121
120
|
> ```
|
|
@@ -128,13 +127,13 @@ model.predict([[0.5, 0.2]]) # → array([[1.04…]])
|
|
|
128
127
|
> model.fit(X_train, y_train, epochs=15) # continue training
|
|
129
128
|
> ```
|
|
130
129
|
>
|
|
131
|
-
> `kanx.check_input_range(model, X)`
|
|
130
|
+
> `kanx.check_input_range(model, X)` logs a warning when a row leaves the stored grid. That boundary is the interval you fit, which is stricter than the hard zero at the outermost knot.
|
|
132
131
|
|
|
133
|
-
|
|
132
|
+
Zero out edges that barely contribute. `prune` sets the spline coefficients and the base weight to zero. It does not remove the slot, and the contraction still visits it. `threshold` is an absolute cutoff on the edge score. `relative` zeros edges at or below that fraction of the strongest edge in the same layer. Pass `samples` to score each edge by its RMS on real inputs. The same method is on the PyTorch `KAN` and on `MatrixKAN`.
|
|
134
133
|
|
|
135
134
|
```python
|
|
136
|
-
model.prune(relative=0.01)
|
|
137
|
-
model.prune(threshold=1e-3, samples=X_train)
|
|
135
|
+
model.prune(relative=0.01) # zero edges at or below 1% of the peak
|
|
136
|
+
model.prune(threshold=1e-3, samples=X_train) # coefficients become zero; shapes stay
|
|
138
137
|
```
|
|
139
138
|
|
|
140
139
|
Plot what is left. Each edge is a learned 1-D function (SiLU residual plus B-spline). `plot_edges` needs matplotlib (`pip install "kanx[viz]"`). `write_edge_viewer` writes a single HTML file with a layer picker and a hover readout.
|
|
@@ -150,9 +149,9 @@ write_edge_viewer(model, "edges.html")
|
|
|
150
149
|
<img src="docs/assets/edge_functions.png" alt="Learned edge functions on a two-input KAN" width="640"/>
|
|
151
150
|
</p>
|
|
152
151
|
|
|
153
|
-
Layer 0 of a `KAN([2, 1])` fit to `sin(π x₁) + 0.6 x₂²`. The
|
|
152
|
+
Layer 0 of a `KAN([2, 1])` fit to `sin(π x₁) + 0.6 x₂²`. The left edge follows the sine. The right edge follows a bowl. That is a reading of this plot. It is not a proof that each edge owns one term, and a shorter fit of the same target can leave the right side of the bowl unfinished.
|
|
154
153
|
|
|
155
|
-
The TensorFlow spline contraction can run in reduced precision, and the forward pass can be XLA-compiled. Weights and the returned tensor stay float32. The Cox
|
|
154
|
+
The TensorFlow spline contraction can run in reduced precision, and the forward pass can be XLA-compiled. Weights and the returned tensor stay float32. The Cox–de Boor basis stays float32 because `(x − tᵢ)` cancels near a knot and the divided differences amplify the error. bfloat16 has fewer mantissa bits than float16 (8 versus 11), so it is the worse choice for the basis. Float16's largest finite value is 65504. That is a property of the format, not an overflow measured in this contraction: on these knots the cubic basis peaks at 2/3, and the coefficients start small. bfloat16 is the practical training dtype because float16 gradients underflow when training does not use loss scaling. Knot spacing does not underflow in float16 at grid size 5 (spacing 0.4) or at grid size 1000 (spacing 0.002). Against a float64 `b_spline_basis` on the same extended knots, the max absolute error is 1.9×10⁻⁷ in float32 and 1.5×10⁻³ in float16 at grid size 5 (1.2×10⁻² in bfloat16). At grid size 1000 it is 2.5×10⁻⁵, 0.16, and 0.67. The grid-size-1000 gap is mostly the input rounding onto a step comparable to the 0.002 knot spacing.
|
|
156
155
|
|
|
157
156
|
```python
|
|
158
157
|
model = KAN([8, 16, 1], precision="bfloat16", jit_compile=True)
|
|
@@ -193,17 +192,30 @@ model.predict([[0.5, 0.2]])
|
|
|
193
192
|
---
|
|
194
193
|
|
|
195
194
|
|
|
196
|
-
### ⚡
|
|
195
|
+
### ⚡ MatrixKAN
|
|
197
196
|
|
|
198
|
-
|
|
197
|
+
`MatrixKAN` is experimental. It evaluates the same Cox–de Boor basis as `KAN`, with a Python loop over each basis index. `build_recurrence_matrix_batch` is not used, and a constant matrix cannot represent the recursion because the weights depend on `x`. The 0.2.0 docstring called this a batched GEMM. That description was wrong.
|
|
199
198
|
|
|
200
199
|
```python
|
|
201
200
|
from kanx.torch import MatrixKAN
|
|
202
201
|
|
|
203
|
-
model = MatrixKAN([
|
|
204
|
-
model.fit(X, y, epochs=30) # ~1.5–2× faster on GPU vs standard KAN
|
|
202
|
+
model = MatrixKAN([2, 32, 1], grid_size=5, spline_order=3)
|
|
205
203
|
```
|
|
206
204
|
|
|
205
|
+
The table below times that loop, not a matrix algorithm. Tesla T4, torch 2.11.0+cu130, kanx 0.2.0, float32, grid size 5, spline order 3, shape `[2, width, 1]`. Ten warmup calls, then the mean of 50, with `torch.cuda.synchronize` around the loop. Cells are MatrixKAN milliseconds divided by KAN milliseconds. The JSON is `benchmarks/results/matrixkan_t4_0.2.0.json`.
|
|
206
|
+
|
|
207
|
+
| width \ batch | 1,024 | 4,096 | 8,192 | 16,384 |
|
|
208
|
+
|---:|---:|---:|---:|---:|
|
|
209
|
+
| 32 | 6.41 | 6.37 | 5.53 | 3.24 |
|
|
210
|
+
| 64 | 6.58 | 5.88 | 3.59 | 3.32 |
|
|
211
|
+
| 128 | 6.72 | 3.32 | 3.35 | 3.30 |
|
|
212
|
+
| 256 | 5.74 | 3.37 | 3.32 | 3.29 |
|
|
213
|
+
| 512 | 3.33 | 3.32 | 3.29 | 3.27 |
|
|
214
|
+
|
|
215
|
+
At width 32 and batch 4,096 the calls are 2.10 ms and 13.37 ms. At width 512 and batch 16,384 they are 67.0 ms and 219 ms. The ratio falls from 6.4× to 3.3× and stays there. At the small end the extra cost is kernel launches: on CPU, one `MatrixKANLinear(32, 1)` forward at batch 1,024 recorded 1,394 ATen ops against 205 for `KANLinear` (torch 2.14.1+cpu). The ~2 ms KAN floor at width 32 is mostly launch overhead as well. A uniform-grid cubic basis can be one small multiply on `[1, u, u², u³]`. That path is not this class, and grids from `update_grid_from_samples` are not uniform.
|
|
216
|
+
|
|
217
|
+
A second T4 run copies the weights, checks that the outputs match, and times one training step. It sweeps spline orders 3, 5, and 7. The JSON is `benchmarks/results/matrixkan_t4_sweep_0.2.0.json`. Every row matched, with max absolute error 0. At batch 16,384 the forward ratio is about 3.3×, 4.0×, and 4.6× to 4.9× for orders 3, 5, and 7. The backward ratio on those rows is about 4.6×, 6.2×, and 7.3×. The Python loop does more iterations as the order rises, and the ratio rises with it. One order-3 cell does not match the table above: width 512, batch 1,024, MatrixKAN forward 34.9 ms here and 14.9 ms in the earlier run. The other order-3 forward cells agree. This run does not replace that table.
|
|
218
|
+
|
|
207
219
|
TensorBoard logging and symbolic edge fitting are included:
|
|
208
220
|
|
|
209
221
|
```bash
|
|
@@ -318,7 +330,7 @@ export_onnx_tf(model, "kan.onnx")
|
|
|
318
330
|
|
|
319
331
|
✔ Dynamic batch
|
|
320
332
|
✔ Verified numerical consistency (1e-5)
|
|
321
|
-
✔
|
|
333
|
+
✔ Runs in ONNX Runtime (tested in CI). TensorRT and OpenVINO are not tested.
|
|
322
334
|
|
|
323
335
|
---
|
|
324
336
|
|
|
@@ -347,6 +359,31 @@ python -m kanx predict --checkpoint model.keras --input X.json
|
|
|
347
359
|
|
|
348
360
|
---
|
|
349
361
|
|
|
362
|
+
## Status and scope
|
|
363
|
+
|
|
364
|
+
kanx is at 0.2.2. Its package metadata marks it Beta.
|
|
365
|
+
|
|
366
|
+
**Tested in CI** ([`ci.yml`](https://github.com/Mattral/KANX/blob/main/.github/workflows/ci.yml), every push and pull request to `main`):
|
|
367
|
+
|
|
368
|
+
- `ruff` on `src`, `tests`, `api`, `benchmarks`, and `examples`.
|
|
369
|
+
- `pytest tests/` on Python 3.10, 3.11, and 3.12, Ubuntu, CPU only. This covers the TensorFlow backend, the CPU PyTorch backend, ONNX export checked in ONNX Runtime, the FastAPI service against a live `uvicorn`, Hypothesis property tests, Helm chart rendering, and the CPU distributed smoke tests. The last `main` run before this section was written reported 181 passed and 2 skipped on each Python version, with 77% coverage of `src/kanx`. The two skips are the MatrixKAN CUDA tests.
|
|
370
|
+
- A Docker build, with `/api/health`, `/api/info`, and `/api/predict` called on the running container.
|
|
371
|
+
- An MkDocs build, and `--smoke` runs of both benchmark scripts.
|
|
372
|
+
|
|
373
|
+
**Not tested in CI:**
|
|
374
|
+
|
|
375
|
+
- GPU code paths. The CUDA tests are skipped, and the Tesla T4 MatrixKAN tables are manual runs.
|
|
376
|
+
- Windows and macOS. The published CPU benchmark is a manual run on Windows.
|
|
377
|
+
- TensorRT and OpenVINO. Only ONNX Runtime runs the exported models.
|
|
378
|
+
- Installing the Kubernetes manifests or the Helm chart on a cluster. The chart is only rendered.
|
|
379
|
+
- The published benchmark numbers. `--smoke` checks that the scripts run and produce finite metrics. It does not reproduce the tables.
|
|
380
|
+
- The notebooks.
|
|
381
|
+
- `black` runs with `|| true`, so formatting cannot fail the job. `mypy` is configured in `pyproject.toml` but is not run.
|
|
382
|
+
|
|
383
|
+
**What 1.0 means.** Until 1.0, a minor release can change the public API, and the changelog lists each change. From 1.0, the documented API follows Semantic Versioning: `kanx.KAN`, `KANLinear`, `fit_grid_to_data`, `export_onnx_tf`, `kanx.torch.KAN`, `kanx.torch.export_onnx`, the `python -m kanx` commands, and the REST endpoints change incompatibly only in a new major version. Anything marked experimental, currently `MatrixKAN`, is outside that promise. No 1.0 date is set.
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
350
387
|
## ⭐ Quality
|
|
351
388
|
|
|
352
389
|
- Unit, integration, live API, property-based, and performance tests in [`tests/`](tests/)
|
|
@@ -389,9 +426,9 @@ the library.
|
|
|
389
426
|
|
|
390
427
|
Our work is formally documented and available as a preprint:
|
|
391
428
|
|
|
392
|
-
- 📘 Title: *KANX:
|
|
429
|
+
- 📘 Title: *KANX: An Open-Source Library for Kolmogorov-Arnold Networks*
|
|
393
430
|
- 📍 DOI: https://doi.org/10.5281/zenodo.20615396
|
|
394
|
-
- 📂 Zenodo: https://zenodo.org/records/
|
|
431
|
+
- 📂 Zenodo: https://zenodo.org/records/20615396
|
|
395
432
|
- 📄 [Read Paper (preprint)](docs/preprint.pdf)
|
|
396
433
|
- 📄 [Read Paper (ArXiv)](docs/KANX_ArXiv_Paper.pdf)
|
|
397
434
|
|
|
@@ -401,7 +438,7 @@ Our work is formally documented and available as a preprint:
|
|
|
401
438
|
|
|
402
439
|
```bibtex
|
|
403
440
|
@article{mattral2026kanx,
|
|
404
|
-
title={KANX:
|
|
441
|
+
title={KANX: An Open-Source Library for Kolmogorov-Arnold Networks},
|
|
405
442
|
author={Myet, Min Htet},
|
|
406
443
|
year={2026},
|
|
407
444
|
doi={10.5281/zenodo.20615396},
|
|
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "kanx"
|
|
7
|
-
version = "0.2.
|
|
8
|
-
description = "
|
|
7
|
+
version = "0.2.2"
|
|
8
|
+
description = "Kolmogorov-Arnold Networks for TensorFlow and PyTorch, with ONNX export."
|
|
9
9
|
authors = [{ name = "kanx contributors" }]
|
|
10
10
|
license = { text = "Apache-2.0" }
|
|
11
11
|
readme = "README.md"
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""kanx —
|
|
1
|
+
"""kanx — Kolmogorov-Arnold Networks in TensorFlow.
|
|
2
2
|
|
|
3
3
|
Public API:
|
|
4
4
|
from kanx import KAN, KANLinear, load_config, train, predict
|
|
@@ -52,4 +52,4 @@ __all__ = [
|
|
|
52
52
|
"datasets",
|
|
53
53
|
]
|
|
54
54
|
|
|
55
|
-
__version__ = "0.2.
|
|
55
|
+
__version__ = "0.2.2"
|
|
@@ -291,8 +291,9 @@ class KANLinear(Layer):
|
|
|
291
291
|
"""SiLU residual plus spline einsum.
|
|
292
292
|
|
|
293
293
|
Float32 uses the inputs' dtype end to end. Reduced precision casts
|
|
294
|
-
only the two dense contractions. The basis
|
|
295
|
-
|
|
294
|
+
only the two dense contractions. The basis stays in float32 because
|
|
295
|
+
(x - t_i) cancels near a knot and the divided differences amplify
|
|
296
|
+
that error. Knot spacing at grid size 5 or 1000 does not underflow.
|
|
296
297
|
"""
|
|
297
298
|
compute = _PRECISION_DTYPES[self.precision]
|
|
298
299
|
if compute == tf.float32:
|
|
@@ -360,7 +361,7 @@ class KANLinear(Layer):
|
|
|
360
361
|
|
|
361
362
|
An edge is one ``(input feature, output feature)`` pair: its spline
|
|
362
363
|
coefficients and its base weight. ``threshold`` is an absolute cutoff
|
|
363
|
-
on the edge score. ``relative``
|
|
364
|
+
on the edge score. ``relative`` zeros edges at or below that fraction
|
|
364
365
|
of the strongest edge in this layer. Pass either argument, or both
|
|
365
366
|
(the higher cutoff wins).
|
|
366
367
|
|
|
@@ -7,8 +7,9 @@ The score is either the L2 norm of that edge's parameters, or the RMS of the
|
|
|
7
7
|
edge function on a batch of inputs. Both cutoffs below apply to whichever
|
|
8
8
|
score the caller computed:
|
|
9
9
|
|
|
10
|
-
* ``threshold`` —
|
|
11
|
-
|
|
10
|
+
* ``threshold`` — zero edges whose score is less than or equal to this value.
|
|
11
|
+
The slot stays, and the contraction still visits it.
|
|
12
|
+
* ``relative`` — zero edges whose score is less than or equal to
|
|
12
13
|
``relative`` times the strongest edge in the same layer.
|
|
13
14
|
|
|
14
15
|
When both are set, the higher cutoff is used.
|