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.
Files changed (64) hide show
  1. {kanx-0.2.0/src/kanx.egg-info → kanx-0.2.2}/PKG-INFO +86 -49
  2. {kanx-0.2.0 → kanx-0.2.2}/README.md +84 -47
  3. {kanx-0.2.0 → kanx-0.2.2}/pyproject.toml +2 -2
  4. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/__init__.py +2 -2
  5. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/layers.py +4 -3
  6. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/prune.py +3 -2
  7. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/matrix_kan.py +23 -12
  8. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/utils.py +9 -7
  9. {kanx-0.2.0 → kanx-0.2.2/src/kanx.egg-info}/PKG-INFO +86 -49
  10. {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/SOURCES.txt +1 -0
  11. {kanx-0.2.0 → kanx-0.2.2}/tests/test_helm_chart.py +1 -1
  12. {kanx-0.2.0 → kanx-0.2.2}/tests/test_matrix_kan.py +12 -5
  13. kanx-0.2.2/tests/test_param_counts.py +66 -0
  14. {kanx-0.2.0 → kanx-0.2.2}/LICENSE +0 -0
  15. {kanx-0.2.0 → kanx-0.2.2}/setup.cfg +0 -0
  16. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/__main__.py +0 -0
  17. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/callbacks.py +0 -0
  18. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/config.py +0 -0
  19. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/__init__.py +0 -0
  20. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/feynman.py +0 -0
  21. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/datasets/tabular.py +0 -0
  22. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/inference.py +0 -0
  23. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/model.py +0 -0
  24. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/onnx_export.py +0 -0
  25. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/quickstart.py +0 -0
  26. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/__init__.py +0 -0
  27. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/layers.py +0 -0
  28. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/model.py +0 -0
  29. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/onnx_export.py +0 -0
  30. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/symbolic.py +0 -0
  31. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/torch/trainer.py +0 -0
  32. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/train.py +0 -0
  33. {kanx-0.2.0 → kanx-0.2.2}/src/kanx/viz.py +0 -0
  34. {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/dependency_links.txt +0 -0
  35. {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/entry_points.txt +0 -0
  36. {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/requires.txt +0 -0
  37. {kanx-0.2.0 → kanx-0.2.2}/src/kanx.egg-info/top_level.txt +0 -0
  38. {kanx-0.2.0 → kanx-0.2.2}/tests/test_api.py +0 -0
  39. {kanx-0.2.0 → kanx-0.2.2}/tests/test_api_hardening.py +0 -0
  40. {kanx-0.2.0 → kanx-0.2.2}/tests/test_api_metrics.py +0 -0
  41. {kanx-0.2.0 → kanx-0.2.2}/tests/test_benchmark_smoke.py +0 -0
  42. {kanx-0.2.0 → kanx-0.2.2}/tests/test_callbacks.py +0 -0
  43. {kanx-0.2.0 → kanx-0.2.2}/tests/test_cli.py +0 -0
  44. {kanx-0.2.0 → kanx-0.2.2}/tests/test_config.py +0 -0
  45. {kanx-0.2.0 → kanx-0.2.2}/tests/test_distributed_smoke.py +0 -0
  46. {kanx-0.2.0 → kanx-0.2.2}/tests/test_e2e_live.py +0 -0
  47. {kanx-0.2.0 → kanx-0.2.2}/tests/test_grid_range_guard.py +0 -0
  48. {kanx-0.2.0 → kanx-0.2.2}/tests/test_grid_update.py +0 -0
  49. {kanx-0.2.0 → kanx-0.2.2}/tests/test_hub.py +0 -0
  50. {kanx-0.2.0 → kanx-0.2.2}/tests/test_layers.py +0 -0
  51. {kanx-0.2.0 → kanx-0.2.2}/tests/test_model.py +0 -0
  52. {kanx-0.2.0 → kanx-0.2.2}/tests/test_onnx_tf.py +0 -0
  53. {kanx-0.2.0 → kanx-0.2.2}/tests/test_performance.py +0 -0
  54. {kanx-0.2.0 → kanx-0.2.2}/tests/test_precision.py +0 -0
  55. {kanx-0.2.0 → kanx-0.2.2}/tests/test_properties.py +0 -0
  56. {kanx-0.2.0 → kanx-0.2.2}/tests/test_prune.py +0 -0
  57. {kanx-0.2.0 → kanx-0.2.2}/tests/test_quickstart_api.py +0 -0
  58. {kanx-0.2.0 → kanx-0.2.2}/tests/test_simple_torch.py +0 -0
  59. {kanx-0.2.0 → kanx-0.2.2}/tests/test_symbolic.py +0 -0
  60. {kanx-0.2.0 → kanx-0.2.2}/tests/test_tf_torch.py +0 -0
  61. {kanx-0.2.0 → kanx-0.2.2}/tests/test_torch_backend.py +0 -0
  62. {kanx-0.2.0 → kanx-0.2.2}/tests/test_torch_kan.py +0 -0
  63. {kanx-0.2.0 → kanx-0.2.2}/tests/test_train_inference.py +0 -0
  64. {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.0
4
- Summary: Production-grade Kolmogorov-Arnold Networks — TensorFlow + PyTorch + ONNX.
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>Production-grade Kolmogorov-Arnold Networks</strong><br>
73
- <em>TensorFlow + PyTorch + ONNX — one library, four surfaces. </em><br>
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.20430883-7C3AED?style=for-the-badge&logo=zenodo&logoColor=white">
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`** &nbsp;·&nbsp; A small KAN beats a 10× larger MLP on smooth, separable targets — **honest, param-matched benchmark below.**
94
- > One library. Two backends. Real ONNX export. Docker + Kubernetes ready. Prometheus metrics, TensorBoard logging, Hub and symbolic extras are now implemented.
93
+ > **`pip install kanx`** &nbsp;·&nbsp; 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
- Every other KAN library stops at research. `kanx` goes the full distance:
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
- | Test coverage | research | research | research | **CI + Hypothesis** |
113
- | PyPI | ✅ | ✅ | ✅ | ✅ |
114
- | CI/CD release pipeline | ❌ | ❌ | ❌ | ✅ PyPI + GHCR + Pages |
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
- Most of the other KAN implementations are strictly academic. `KANX` bridges the gap between theory and reality by providing:
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. **High-Throughput Options:** Vectorized `MatrixKAN` to replace recursive B-splines with batched GEMMs for GPU acceleration.
122
- 4. **Grid Calibration:** Native adaptive and static grid fitting to prevent out-of-bounds input collapse.
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, CPU.
133
-
134
-
135
- | Model | Params | Train (s) | Infer 4k (ms) | **Test MSE** |
136
- |--------------------|------:|---------:|-------------:|-------------:|
137
- | **KAN[2,16,1]** | 432 | 12.50 | 68.64 | **2.14 × 10⁻⁵** |
138
- | KAN[2,32,1] | 864 | 16.62 | 25.52 | 4.44 × 10⁻⁴ |
139
- | MLP[2,32,1] | 129 | 5.07 | 6.17 | 4.61 × 10⁻¹ (undersized) |
140
- | MLP[2,16,16,1] | 337 | 5.46 | 4.08 | 1.60 × 10⁻³ |
141
- | MLP[2,64,64,1] | 4 417 | 6.00 | 5.74 | 5.51 × 10⁻⁴ |
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 smallest KAN (432 params) wins on this smooth separable
150
- target. The same KAN is ~10–15× *slower at inference* than a same-MSE MLP
151
- because each edge does a B-spline evaluation. On non-smooth or
152
- high-dimensional targets, this picture often reverses. We do not claim KANs
153
- are universally better than MLPs.
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
- > KANs use B-splines on a fixed input range (default `[-1, 1]`). If your inputs fall outside that range, the spline path **silently returns zero** and you only get the SiLU residual. Fix it one of two ways:
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)` will log a warning at inference if input exceeds the grid.
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
- Drop edges that barely contribute. `threshold` is an absolute cutoff on the edge score. `relative` drops 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`.
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) # keep edges above 1% of the peak
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 first edge carries the sine. The second carries the quadratic.
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-de Boor basis stays float32 as well: knot differences underflow in float16.
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
- ### ⚡ GPU-optimized MatrixKAN
263
+ ### ⚡ MatrixKAN
265
264
 
266
- For higher throughput on accelerators, use the vectorized `MatrixKAN` (replaces recursion with batched GEMM):
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([4, 32, 1]) # same interface as KAN
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
- ✔ Works with ONNX Runtime / TensorRT / OpenVINO
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: A Production-Grade Open-Source Library for Kolmogorov-Arnold Networks*
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/20430883
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: A Production-Grade Open-Source Library for Kolmogorov-Arnold Networks},
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>Production-grade Kolmogorov-Arnold Networks</strong><br>
5
- <em>TensorFlow + PyTorch + ONNX — one library, four surfaces. </em><br>
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.20430883-7C3AED?style=for-the-badge&logo=zenodo&logoColor=white">
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`** &nbsp;·&nbsp; A small KAN beats a 10× larger MLP on smooth, separable targets — **honest, param-matched benchmark below.**
26
- > One library. Two backends. Real ONNX export. Docker + Kubernetes ready. Prometheus metrics, TensorBoard logging, Hub and symbolic extras are now implemented.
25
+ > **`pip install kanx`** &nbsp;·&nbsp; 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
- Every other KAN library stops at research. `kanx` goes the full distance:
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
- | Test coverage | research | research | research | **CI + Hypothesis** |
45
- | PyPI | ✅ | ✅ | ✅ | ✅ |
46
- | CI/CD release pipeline | ❌ | ❌ | ❌ | ✅ PyPI + GHCR + Pages |
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
- Most of the other KAN implementations are strictly academic. `KANX` bridges the gap between theory and reality by providing:
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. **High-Throughput Options:** Vectorized `MatrixKAN` to replace recursive B-splines with batched GEMMs for GPU acceleration.
54
- 4. **Grid Calibration:** Native adaptive and static grid fitting to prevent out-of-bounds input collapse.
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, CPU.
65
-
66
-
67
- | Model | Params | Train (s) | Infer 4k (ms) | **Test MSE** |
68
- |--------------------|------:|---------:|-------------:|-------------:|
69
- | **KAN[2,16,1]** | 432 | 12.50 | 68.64 | **2.14 × 10⁻⁵** |
70
- | KAN[2,32,1] | 864 | 16.62 | 25.52 | 4.44 × 10⁻⁴ |
71
- | MLP[2,32,1] | 129 | 5.07 | 6.17 | 4.61 × 10⁻¹ (undersized) |
72
- | MLP[2,16,16,1] | 337 | 5.46 | 4.08 | 1.60 × 10⁻³ |
73
- | MLP[2,64,64,1] | 4 417 | 6.00 | 5.74 | 5.51 × 10⁻⁴ |
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 smallest KAN (432 params) wins on this smooth separable
82
- target. The same KAN is ~10–15× *slower at inference* than a same-MSE MLP
83
- because each edge does a B-spline evaluation. On non-smooth or
84
- high-dimensional targets, this picture often reverses. We do not claim KANs
85
- are universally better than MLPs.
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
- > KANs use B-splines on a fixed input range (default `[-1, 1]`). If your inputs fall outside that range, the spline path **silently returns zero** and you only get the SiLU residual. Fix it one of two ways:
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)` will log a warning at inference if input exceeds the grid.
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
- Drop edges that barely contribute. `threshold` is an absolute cutoff on the edge score. `relative` drops 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`.
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) # keep edges above 1% of the peak
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 first edge carries the sine. The second carries the quadratic.
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-de Boor basis stays float32 as well: knot differences underflow in float16.
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
- ### ⚡ GPU-optimized MatrixKAN
195
+ ### ⚡ MatrixKAN
197
196
 
198
- For higher throughput on accelerators, use the vectorized `MatrixKAN` (replaces recursion with batched GEMM):
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([4, 32, 1]) # same interface as KAN
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
- ✔ Works with ONNX Runtime / TensorRT / OpenVINO
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: A Production-Grade Open-Source Library for Kolmogorov-Arnold Networks*
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/20430883
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: A Production-Grade Open-Source Library for Kolmogorov-Arnold Networks},
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.0"
8
- description = "Production-grade Kolmogorov-Arnold Networks — TensorFlow + PyTorch + ONNX."
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 — Production-grade Kolmogorov-Arnold Networks in TensorFlow.
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.0"
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 is computed in float32
295
- so knot differences do not underflow.
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`` drops edges at or below that fraction
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`` — drop edges whose score is less than or equal to this value.
11
- * ``relative`` — drop edges whose score is less than or equal to
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.