kasn 0.1.0__tar.gz

kasn-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+   __pycache__/
+   *.egg-info/
+   .pytest_cache/
+   dist/
+   build/
+   *.Rcheck/
+   *.tar.gz
+   .Rproj.user/
+   .Rhistory

kasn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sami Abdurahman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kasn-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: kasn
+Version: 0.1.0
+Summary: Kolmogorov-Arnold Sieve Networks for nonparametric estimation and semiparametric inference
+Project-URL: Repository, https://github.com/samiabd8/kasn
+Project-URL: Issues, https://github.com/samiabd8/kasn/issues
+Author: Sami Abdurahman
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Kolmogorov-Arnold networks,econometrics,group lasso,nonparametric regression,quantile regression,sieve estimation,time series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.22
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: scipy>=1.8
+Requires-Dist: torch>=2.3
+Provides-Extra: examples
+Requires-Dist: pandas>=1.5; extra == 'examples'
+Provides-Extra: test
+Requires-Dist: pandas>=1.5; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# kasn
+
+Kolmogorov-Arnold Sieve Networks. PyTorch backend, scikit-learn API.
+
+## Install
+
+```bash
+pip install kasn
+pip install -e "python[test]" && pytest python/tests   # development
+```
+
+## Usage
+
+```python
+from kasn import KASNRegressor, KASNClassifier, make_kasn_regression, load
+
+sim = make_kasn_regression(n=2000, d=50, s=10, target="compositional", random_state=0)
+X, y = sim.X, sim.y
+m = KASNRegressor(depth=3, random_state=0).fit(X[:1000], y[:1000], X[1000:1500], y[1000:1500])
+m.predict(X[1500:]); m.sparsity_report(); m.grid_coverage(X[1500:])
+m.save("fit.kasn"); m = load("fit.kasn")
+
+KASNRegressor(loss="quantile", quantile=0.9)
+KASNRegressor(loss="huber", huber_delta=1.0)
+KASNRegressor(loss="poisson")
+KASNClassifier()                       # binary logistic
+```
+
+`tune_kasn` runs the prune-aware greedy search. `examples/nonparametric_regression.py` reproduces the layout of Tables 1-4.
+
+## Parameters
+
+| Parameter | Definition | Default |
+|---|---|---|
+| `gamma`, `grid_size` | `G_n = max(5, floor(n^gamma))` | `gamma = 0.4` |
+| `depth` | `L_n` hidden layers, `L_n + 1` edge layers | `max(3, floor(log n))` |
+| `width`, `width_scale` | `W_n = C_W floor(log n)` | `C_W = 5` |
+| | `r_n = (d + 1) W_n + (L_n - 1) W_n^2` | |
+| `spline_order` | de Boor order `k` | 4 |
+| `grid_range` | `I_eps` | `(-0.05, 1.05)` |
+| `penalty` | `lambda_n` | `C_lambda sqrt(log(L_n W_n^2) / n)` |
+| `penalty_scale` | `C_lambda` | 0.05 |
+| `delta_mode` | `'penalty'`, `'project'`, `'dual'` | `'penalty'` |
+| `zeta_delta`, `delta_scale` | `Delta_n = max(5, delta_scale n^zeta_delta)` | 0.4, 1.0 |
+| `max_active_edges` | `s_n` cap | none |
+| `max_epochs`, `patience` | | 500, 50 |
+
+`n` is the training fold size.

kasn-0.1.0/README.md

@@ -0,0 +1,48 @@
+# kasn
+
+Kolmogorov-Arnold Sieve Networks. PyTorch backend, scikit-learn API.
+
+## Install
+
+```bash
+pip install kasn
+pip install -e "python[test]" && pytest python/tests   # development
+```
+
+## Usage
+
+```python
+from kasn import KASNRegressor, KASNClassifier, make_kasn_regression, load
+
+sim = make_kasn_regression(n=2000, d=50, s=10, target="compositional", random_state=0)
+X, y = sim.X, sim.y
+m = KASNRegressor(depth=3, random_state=0).fit(X[:1000], y[:1000], X[1000:1500], y[1000:1500])
+m.predict(X[1500:]); m.sparsity_report(); m.grid_coverage(X[1500:])
+m.save("fit.kasn"); m = load("fit.kasn")
+
+KASNRegressor(loss="quantile", quantile=0.9)
+KASNRegressor(loss="huber", huber_delta=1.0)
+KASNRegressor(loss="poisson")
+KASNClassifier()                       # binary logistic
+```
+
+`tune_kasn` runs the prune-aware greedy search. `examples/nonparametric_regression.py` reproduces the layout of Tables 1-4.
+
+## Parameters
+
+| Parameter | Definition | Default |
+|---|---|---|
+| `gamma`, `grid_size` | `G_n = max(5, floor(n^gamma))` | `gamma = 0.4` |
+| `depth` | `L_n` hidden layers, `L_n + 1` edge layers | `max(3, floor(log n))` |
+| `width`, `width_scale` | `W_n = C_W floor(log n)` | `C_W = 5` |
+| | `r_n = (d + 1) W_n + (L_n - 1) W_n^2` | |
+| `spline_order` | de Boor order `k` | 4 |
+| `grid_range` | `I_eps` | `(-0.05, 1.05)` |
+| `penalty` | `lambda_n` | `C_lambda sqrt(log(L_n W_n^2) / n)` |
+| `penalty_scale` | `C_lambda` | 0.05 |
+| `delta_mode` | `'penalty'`, `'project'`, `'dual'` | `'penalty'` |
+| `zeta_delta`, `delta_scale` | `Delta_n = max(5, delta_scale n^zeta_delta)` | 0.4, 1.0 |
+| `max_active_edges` | `s_n` cap | none |
+| `max_epochs`, `patience` | | 500, 50 |
+
+`n` is the training fold size.

kasn-0.1.0/examples/nonparametric_regression.py

@@ -0,0 +1,128 @@
+"""Local nonparametric regression example (Section 4.1 of the KASN paper, scaled down).
+
+Simulates the additive or compositional design, splits it chronologically
+into train / validation / test (0.5 / 0.25 / 0.25), fits the KASN and a
+validation-tuned Lasso, and reports the columns of Tables 1-4: RMSE and R^2
+on each fold, the held-out L2 error against f_0, and the active edge count.
+
+Runs on a laptop CPU in under a minute. ``--tune`` runs the prune-aware
+hyperparameter search. Paper scale: ``--n 5000 --d 100 --s 30``.
+
+    python examples/nonparametric_regression.py --target compositional
+"""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+import numpy as np
+from sklearn.linear_model import Lasso
+from sklearn.metrics import mean_squared_error, r2_score
+
+from kasn import (EmpiricalCDFTransformer, KASNRegressor, check_conditions,
+                  make_kasn_regression, target_function, tune_kasn)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--target", default="compositional",
+                   choices=["additive", "compositional", "deep"])
+    p.add_argument("--n", type=int, default=2000)
+    p.add_argument("--d", type=int, default=50)
+    p.add_argument("--s", type=int, default=10)
+    p.add_argument("--rho", type=float, default=0.7)
+    p.add_argument("--gamma", type=float, default=0.4)
+    p.add_argument("--depth", type=int, default=3)
+    p.add_argument("--epochs", type=int, default=500)
+    p.add_argument("--patience", type=int, default=50)
+    p.add_argument("--tune", action="store_true")
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--device", default="auto")
+    args, _ = p.parse_known_args()          # Jupyter-safe
+    return args
+
+
+def metrics(name, pred, y, f0, idx, extra):
+    row = {"method": name}
+    for fold in ("train", "val", "test"):
+        i = idx[fold]
+        row[f"{fold}_rmse"] = float(np.sqrt(mean_squared_error(y[i], pred[i])))
+        row[f"{fold}_r2"] = float(r2_score(y[i], pred[i]))
+    i = idx["test"]
+    row["l2_error"] = float(np.sqrt(np.mean((pred[i] - f0[i]) ** 2)))
+    row.update(extra)
+    return row
+
+
+def main() -> None:
+    a = parse_args()
+    check_conditions(a.gamma, m=2)
+    data = make_kasn_regression(n=a.n, d=a.d, s=a.s, target=a.target,
+                                rho=a.rho, random_state=a.seed)
+    X, y, f0 = data.X, data.y, data.f0
+    n_tr, n_va = int(0.5 * a.n), int(0.25 * a.n)
+    idx = {"train": np.arange(n_tr), "val": np.arange(n_tr, n_tr + n_va),
+           "test": np.arange(n_tr + n_va, a.n)}
+    Xtr, ytr = X[idx["train"]], y[idx["train"]]
+    Xva, yva = X[idx["val"]], y[idx["val"]]
+    print(f"Design: target={a.target} n={a.n} d={a.d} S={a.s} rho_X={a.rho} "
+          f"(chronological split {n_tr}/{n_va}/{a.n - n_tr - n_va})")
+
+    params = dict(gamma=a.gamma, depth=a.depth, max_epochs=a.epochs,
+                  patience=a.patience, device=a.device, random_state=a.seed)
+    if a.tune:
+        res = tune_kasn(Xtr, ytr, Xva, yva, base_params=params,
+                        penalty_scale_grid=(0.05, 0.1, 1.0),
+                        gamma_grid=(0.3, 0.4), width_scale_grid=(3, 5),
+                        batch_size_grid=(32,), tuning_epochs=40,
+                        random_state=a.seed)
+        params = res.best_params
+        print(f"Tuned in {res.selection_time:.0f}s: gamma={params['gamma']} "
+              f"penalty_scale={params['penalty_scale']} "
+              f"width_scale={params['width_scale']}")
+
+    rows = []
+    t0 = time.time()
+    kasn = KASNRegressor(**params, verbose=1).fit(Xtr, ytr, Xva, yva)
+    rep = kasn.sparsity_report()
+    rows.append(metrics("KASN", kasn.predict(X), y, f0, idx, {
+        "parameters": f"{rep['active_edges']:,}/{rep['r_n']:,}",
+        "fit_s": time.time() - t0}))
+
+    t0 = time.time()
+    cdf = EmpiricalCDFTransformer().fit(Xtr)
+    best = min((Lasso(alpha=al, max_iter=10_000).fit(cdf.transform(Xtr), ytr)
+                for al in (1e-5, 1e-3, 1e-2, 5e-2, 1e-1, 1.0)),
+               key=lambda m: mean_squared_error(yva, m.predict(cdf.transform(Xva))))
+    nz = int(np.sum(np.abs(best.coef_) > 1e-6))
+    rows.append(metrics("LASSO", best.predict(cdf.transform(X)), y, f0, idx,
+                        {"parameters": f"{nz}/{a.d}", "fit_s": time.time() - t0}))
+
+    oracle = target_function(X, a.s, a.target)
+    rows.append(metrics("Oracle", oracle, y, f0, idx,
+                        {"parameters": "-", "fit_s": 0.0}))
+
+    print(f"\n{'method':8s} {'trRMSE':>7s} {'trR2':>6s} {'vaRMSE':>7s} "
+          f"{'vaR2':>6s} {'teRMSE':>7s} {'teR2':>6s} {'||f-f0||':>8s} "
+          f"{'parameters':>14s} {'fit(s)':>7s}")
+    for r in rows:
+        print(f"{r['method']:8s} {r['train_rmse']:7.4f} {r['train_r2']:6.4f} "
+              f"{r['val_rmse']:7.4f} {r['val_r2']:6.4f} {r['test_rmse']:7.4f} "
+              f"{r['test_r2']:6.4f} {r['l2_error']:8.4f} {r['parameters']:>14s} "
+              f"{r['fit_s']:7.1f}")
+
+    print(f"\nKASN: sparsity ratio {rep['sparsity_ratio']:.3f}, "
+          f"output-connected edges {rep['output_connected_edges']:,}, "
+          f"Delta_n {rep['delta_n']:.2f} ({rep['delta_mode']}), "
+          f"lambda_n {rep['lambda_n']:.2e}, "
+          f"L_n={rep['L_n']} W_n={rep['W_n']} G_n={rep['G_n']}")
+    print("Grid coverage on the test fold (share of layer inputs outside I_eps):")
+    for c in kasn.grid_coverage(X[idx["test"]]):
+        print(f"  layer {c['layer']}: range [{c['min']:+.3f}, {c['max']:+.3f}]"
+              f"  outside grid {c['frac_outside_grid_range']:.4f}"
+              f"  outside support {c['frac_outside_support']:.4f}")
+
+
+if __name__ == "__main__":
+    main()

kasn-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kasn"
+dynamic = ["version"]
+description = "Kolmogorov-Arnold Sieve Networks for nonparametric estimation and semiparametric inference"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Sami Abdurahman" }]
+keywords = ["sieve estimation", "Kolmogorov-Arnold networks", "group lasso",
+            "nonparametric regression", "quantile regression", "econometrics",
+            "time series"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "numpy>=1.22",
+  "scipy>=1.8",
+  "scikit-learn>=1.2",
+  "torch>=2.3",
+]
+
+[project.optional-dependencies]
+examples = ["pandas>=1.5"]
+test = ["pytest>=7", "pandas>=1.5"]
+
+[project.urls]
+Repository = "https://github.com/samiabd8/kasn"
+Issues = "https://github.com/samiabd8/kasn/issues"
+
+[tool.hatch.version]
+path = "src/kasn/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kasn"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kasn-0.1.0/src/kasn/__init__.py

@@ -0,0 +1,49 @@
+"""Kolmogorov-Arnold Sieve Networks (KASN).
+
+Sieve extremum estimation with deep Kolmogorov-Arnold networks, learned
+B-spline edges and Group Lasso regularisation.
+
+KASNRegressor
+    Squared, Huber, quantile and Poisson criteria.
+KASNClassifier
+    Binary logistic criterion.
+tune_kasn
+    Prune-aware greedy hyperparameter search on a validation fold.
+make_kasn_regression
+    Monte Carlo designs of Section 4.
+load
+    Restore any estimator written by ``.save()``.
+"""
+
+from typing import Optional
+
+from .base import _read_payload
+from .classifier import KASNClassifier
+from .datasets import make_kasn_regression, target_function
+from .losses import make_loss
+from .network import KASNLayer, KASNNetwork
+from .preprocessing import EmpiricalCDFTransformer
+from .regressor import KASNRegressor
+from .splines import BSplineBasis
+from .theory import architecture, check_conditions
+from .tuning import TuningResult, tune_kasn
+
+__version__ = "0.1.0"
+
+
+def load(path, device: Optional[str] = None):
+    """Load a ``KASNRegressor`` or ``KASNClassifier`` written by ``.save()``."""
+    payload = _read_payload(path)
+    classes = {"KASNRegressor": KASNRegressor,
+               "KASNClassifier": KASNClassifier}
+    if payload["class"] not in classes:
+        raise ValueError(f"unknown estimator class {payload['class']!r}")
+    return classes[payload["class"]]._from_payload(payload, device)
+
+
+__all__ = [
+    "KASNRegressor", "KASNClassifier", "load", "tune_kasn", "TuningResult",
+    "make_kasn_regression", "target_function", "make_loss",
+    "EmpiricalCDFTransformer", "BSplineBasis", "KASNLayer", "KASNNetwork",
+    "architecture", "check_conditions", "__version__",
+]

kasn-0.1.0/src/kasn/_utils.py

@@ -0,0 +1,55 @@
+"""Small internal helpers: devices, seeding and serialisation hygiene."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Iterator, Optional, Union
+
+import numpy as np
+import torch
+
+
+def resolve_device(device: Union[str, torch.device, None]) -> torch.device:
+    """``'auto'`` (or ``None``) picks CUDA when available, otherwise CPU."""
+    if device is None or device == "auto":
+        return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    return torch.device(device)
+
+
+@contextlib.contextmanager
+def seeded(random_state: Optional[int],
+           device: torch.device) -> Iterator[None]:
+    """Seed torch inside a forked RNG so the caller's global state is untouched.
+
+    Every candidate in a hyperparameter search therefore starts from the same
+    initialisation, and repeated fits do not consume each other's draws.
+    """
+    if random_state is None:
+        yield
+        return
+    devices = []
+    if device.type == "cuda":
+        devices = [device.index if device.index is not None
+                   else torch.cuda.current_device()]
+    with torch.random.fork_rng(devices=devices):
+        torch.manual_seed(int(random_state))
+        yield
+
+
+def plain(obj: Any) -> Any:
+    """Recursively convert numpy scalars and arrays to built-in Python types.
+
+    ``torch.load(weights_only=True)`` accepts only built-in containers and
+    tensors, so everything saved alongside the state dict passes through here.
+    """
+    if isinstance(obj, dict):
+        return {str(k): plain(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return type(obj)(plain(v) for v in obj)
+    if isinstance(obj, np.generic):
+        return obj.item()
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, torch.device):
+        return str(obj)
+    return obj