torchsonn 0.1.0__tar.gz

torchsonn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Konstantin Kolokolov
+
+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.

torchsonn-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: torchsonn
+Version: 0.1.0
+Summary: Self-organizing polynomial neural network on PyTorch.
+Author: Konstantin Kolokolov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kvoyager/torchsonn
+Project-URL: Repository, https://github.com/kvoyager/torchsonn
+Project-URL: Issues, https://github.com/kvoyager/torchsonn/issues
+Keywords: gmdh,group-method-of-data-handling,polynomial-neural-network,pytorch,self-organizing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hydra-core>=1.3
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: scikit-learn
+Requires-Dist: tqdm
+Requires-Dist: omegaconf
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Requires-Dist: torchsonn[viz]; extra == "test"
+Provides-Extra: viz
+Requires-Dist: graphviz; extra == "viz"
+Requires-Dist: matplotlib; extra == "viz"
+Dynamic: license-file
+
+# TorchSONN
+
+TorchSONN is a Python library implementing a self-organizing polynomial
+neural network built on PyTorch. Layers of polynomial neurons are grown one
+at a time; each layer tries every pair of the previous layer's outputs
+against a small set of reference polynomials (`linear`, `linear_cov`,
+`quadratic`, `cubic`, multi-input `polyquad`) and keeps the top-k that
+minimize a validation criterion. Training stops automatically when adding a
+layer no longer reduces the criterion error.
+
+It is a GPU-accelerated extension of
+[GmdhPy](https://github.com/kvoyager/GmdhPy), an earlier scikit-learn-style
+library implementing the iterative Group Method of Data Handling (GMDH).
+TorchSONN reimplements the same self-organizing algorithm on PyTorch,
+bringing GPU acceleration to model training and inference.
+
+## Install
+
+```bash
+pip install torchsonn
+```
+
+Plotting is opt-in via the `viz` extra, which adds `graphviz` (for the
+`torchsonn.plot_model` network diagrams) and `matplotlib` (for
+`SONN.plot_layer_error`):
+
+```bash
+pip install "torchsonn[viz]"
+```
+
+`graphviz` additionally requires the system Graphviz binaries — `dot` must be
+on your `PATH` (see [graphviz.org/download](https://graphviz.org/download/)).
+Training and inference work without any of this.
+
+For development, clone the repo and install editably:
+
+```bash
+git clone https://github.com/kvoyager/torchsonn.git
+cd torchsonn
+pip install -e ".[test]"
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import numpy as np
+from omegaconf import OmegaConf
+from sklearn.datasets import fetch_california_housing
+from sklearn.preprocessing import StandardScaler
+from torch.utils.data import DataLoader
+
+from torchsonn import SONN, SONNDataset, Trainer
+
+# California housing regression — 8 features, target in units of $100k.
+housing = fetch_california_housing()
+x = housing.data.astype(np.float32)
+y = housing.target.astype(np.float32)
+feature_names = list(housing.feature_names)
+
+# 50/25/25 train/dev/test split; z-score features on the train split only.
+n = x.shape[0]
+i_train, i_dev = int(0.50 * n), int(0.75 * n)
+scaler = StandardScaler().fit(x[:i_train])
+
+train_ds = SONNDataset(scaler.transform(x[:i_train]),      y[:i_train])
+dev_ds   = SONNDataset(scaler.transform(x[i_train:i_dev]), y[i_train:i_dev])
+test_ds  = SONNDataset(scaler.transform(x[i_dev:]),        y[i_dev:])
+
+train_dl = DataLoader(train_ds, batch_size=8192, shuffle=True)
+dev_dl   = DataLoader(dev_ds,   batch_size=8192)
+test_dl  = DataLoader(test_ds,  batch_size=8192)
+
+# Override only what differs from the schema defaults — everything else
+# comes from torchsonn.config.SONNConfig.
+config = OmegaConf.merge(
+    SONN.default_config(),
+    OmegaConf.create({
+        "model": {
+            "type": "regressor",
+            "ref_functions": ["linear_cov"],
+            "nbest_neurons": 8,
+            "max_neuron_models": 28,
+            "shortcut": True,
+            "output_clamp_value": 1e6,
+        },
+        "train": {
+            "criterion_type": "validate",
+            "max_layer_count": 10,
+            "optimizer": {"name": "lbfgs",
+                          "optimizer_params": {"lr": 0.1, "history_size": 10}},
+            "steps": 500,
+            "batch_size": 8192,
+        },
+    }),
+)
+
+model = SONN(config, d_model=x.shape[1], feature_names=feature_names)
+trainer = Trainer(config, feature_names=feature_names)
+trainer.set_seed(config.train.seed)
+trainer.train(model, train_dl, dev_dl, test_dl)
+
+trainer.load_model_checkpoint(model, "cpu")
+
+# Collapse the ensemble to its single best-error path so inference returns
+# one prediction per sample.
+trainer.prune(model)
+
+preds, targets = trainer.infer(model, test_dl)
+preds = preds.reshape(-1)
+mse = ((preds - targets) ** 2).mean().item()
+mae = (preds - targets).abs().mean().item()
+print(f"test MSE: {mse:.4f}  MAE: {mae:.4f}")
+print(f"features used: {model.get_selected_features()}")
+```
+
+## Tutorials
+
+Four end-to-end examples live under `tutorials/`, each with every config
+key overridable on the command line:
+
+```bash
+# Iris classification — multi-class with soft binner, polyquad neurons.
+python -m tutorials.iris.iris_recognition
+
+# California housing regression — gmdhpy-equivalent setup with LBFGS.
+python -m tutorials.california_housing.california_housing
+
+# UCI Concrete compressive-strength regression — reports MSE / MAE / R².
+python -m tutorials.concrete.concrete
+
+# Otto Group product classification — multi-class log loss, out_proj fine-tune.
+python tutorials/otto/otto_classification.py
+```
+
+Hydra overrides work on any field in the schema. A few useful ones:
+
+```bash
+# Resume from the last checkpoint
+python -m tutorials.iris.iris_recognition resume=true
+
+# Swap optimizer + tune its kwargs
+python -m tutorials.california_housing.california_housing \
+    train.optimizer.name=adam \
+    train.optimizer.optimizer_params.lr=5e-3
+
+# Redirect Hydra's per-run output directory
+python -m tutorials.iris.iris_recognition hydra.run.dir=/tmp/sonn_run
+```
+
+The iris and otto tutorials also ship notebook versions
+(`tutorials/iris/iris_recognition.ipynb` and `tutorials/otto/otto.ipynb`)
+that render the layer-error curve, the confusion matrix, and the graphviz
+network diagrams inline.
+
+Every tutorial except `tutorials/otto/otto_classification.py` plots its
+results, so they need the `[viz]` extra — iris, california_housing, and
+concrete render network diagrams (graphviz), and iris plus both notebooks
+call `SONN.plot_layer_error` (matplotlib). The otto script runs on a base
+install.
+
+## Configuration
+
+Defaults are defined as a typed dataclass at
+`torchsonn.config.SONNConfig` (registered with Hydra's `ConfigStore`
+under the name `default`). Tutorial YAMLs use the
+`defaults: [default, _self_]` pattern, so each tutorial's YAML is just
+the diff against the schema. Override hierarchy at compose time:
+
+```
+SONNConfig defaults  →  tutorial YAML  →  CLI overrides
+```
+
+Type-checked at compose time: unknown keys and wrong-typed values are
+rejected before any training starts.
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE) for the full text.
+
+## Citation
+
+If you use TorchSONN in your research, please cite it as:
+
+```bibtex
+@software{kolokolov_torchsonn_2026,
+  author    = {Kolokolov, Konstantin},
+  title     = {{TorchSONN}: A {PyTorch} Implementation of the self-organizing polynomial neural network},
+  year      = {2026},
+  version   = {0.1.0},
+  url       = {https://github.com/kvoyager/torchsonn},
+  note      = {GitHub repository}
+}
+```
+

torchsonn-0.1.0/README.md

@@ -0,0 +1,196 @@
+# TorchSONN
+
+TorchSONN is a Python library implementing a self-organizing polynomial
+neural network built on PyTorch. Layers of polynomial neurons are grown one
+at a time; each layer tries every pair of the previous layer's outputs
+against a small set of reference polynomials (`linear`, `linear_cov`,
+`quadratic`, `cubic`, multi-input `polyquad`) and keeps the top-k that
+minimize a validation criterion. Training stops automatically when adding a
+layer no longer reduces the criterion error.
+
+It is a GPU-accelerated extension of
+[GmdhPy](https://github.com/kvoyager/GmdhPy), an earlier scikit-learn-style
+library implementing the iterative Group Method of Data Handling (GMDH).
+TorchSONN reimplements the same self-organizing algorithm on PyTorch,
+bringing GPU acceleration to model training and inference.
+
+## Install
+
+```bash
+pip install torchsonn
+```
+
+Plotting is opt-in via the `viz` extra, which adds `graphviz` (for the
+`torchsonn.plot_model` network diagrams) and `matplotlib` (for
+`SONN.plot_layer_error`):
+
+```bash
+pip install "torchsonn[viz]"
+```
+
+`graphviz` additionally requires the system Graphviz binaries — `dot` must be
+on your `PATH` (see [graphviz.org/download](https://graphviz.org/download/)).
+Training and inference work without any of this.
+
+For development, clone the repo and install editably:
+
+```bash
+git clone https://github.com/kvoyager/torchsonn.git
+cd torchsonn
+pip install -e ".[test]"
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import numpy as np
+from omegaconf import OmegaConf
+from sklearn.datasets import fetch_california_housing
+from sklearn.preprocessing import StandardScaler
+from torch.utils.data import DataLoader
+
+from torchsonn import SONN, SONNDataset, Trainer
+
+# California housing regression — 8 features, target in units of $100k.
+housing = fetch_california_housing()
+x = housing.data.astype(np.float32)
+y = housing.target.astype(np.float32)
+feature_names = list(housing.feature_names)
+
+# 50/25/25 train/dev/test split; z-score features on the train split only.
+n = x.shape[0]
+i_train, i_dev = int(0.50 * n), int(0.75 * n)
+scaler = StandardScaler().fit(x[:i_train])
+
+train_ds = SONNDataset(scaler.transform(x[:i_train]),      y[:i_train])
+dev_ds   = SONNDataset(scaler.transform(x[i_train:i_dev]), y[i_train:i_dev])
+test_ds  = SONNDataset(scaler.transform(x[i_dev:]),        y[i_dev:])
+
+train_dl = DataLoader(train_ds, batch_size=8192, shuffle=True)
+dev_dl   = DataLoader(dev_ds,   batch_size=8192)
+test_dl  = DataLoader(test_ds,  batch_size=8192)
+
+# Override only what differs from the schema defaults — everything else
+# comes from torchsonn.config.SONNConfig.
+config = OmegaConf.merge(
+    SONN.default_config(),
+    OmegaConf.create({
+        "model": {
+            "type": "regressor",
+            "ref_functions": ["linear_cov"],
+            "nbest_neurons": 8,
+            "max_neuron_models": 28,
+            "shortcut": True,
+            "output_clamp_value": 1e6,
+        },
+        "train": {
+            "criterion_type": "validate",
+            "max_layer_count": 10,
+            "optimizer": {"name": "lbfgs",
+                          "optimizer_params": {"lr": 0.1, "history_size": 10}},
+            "steps": 500,
+            "batch_size": 8192,
+        },
+    }),
+)
+
+model = SONN(config, d_model=x.shape[1], feature_names=feature_names)
+trainer = Trainer(config, feature_names=feature_names)
+trainer.set_seed(config.train.seed)
+trainer.train(model, train_dl, dev_dl, test_dl)
+
+trainer.load_model_checkpoint(model, "cpu")
+
+# Collapse the ensemble to its single best-error path so inference returns
+# one prediction per sample.
+trainer.prune(model)
+
+preds, targets = trainer.infer(model, test_dl)
+preds = preds.reshape(-1)
+mse = ((preds - targets) ** 2).mean().item()
+mae = (preds - targets).abs().mean().item()
+print(f"test MSE: {mse:.4f}  MAE: {mae:.4f}")
+print(f"features used: {model.get_selected_features()}")
+```
+
+## Tutorials
+
+Four end-to-end examples live under `tutorials/`, each with every config
+key overridable on the command line:
+
+```bash
+# Iris classification — multi-class with soft binner, polyquad neurons.
+python -m tutorials.iris.iris_recognition
+
+# California housing regression — gmdhpy-equivalent setup with LBFGS.
+python -m tutorials.california_housing.california_housing
+
+# UCI Concrete compressive-strength regression — reports MSE / MAE / R².
+python -m tutorials.concrete.concrete
+
+# Otto Group product classification — multi-class log loss, out_proj fine-tune.
+python tutorials/otto/otto_classification.py
+```
+
+Hydra overrides work on any field in the schema. A few useful ones:
+
+```bash
+# Resume from the last checkpoint
+python -m tutorials.iris.iris_recognition resume=true
+
+# Swap optimizer + tune its kwargs
+python -m tutorials.california_housing.california_housing \
+    train.optimizer.name=adam \
+    train.optimizer.optimizer_params.lr=5e-3
+
+# Redirect Hydra's per-run output directory
+python -m tutorials.iris.iris_recognition hydra.run.dir=/tmp/sonn_run
+```
+
+The iris and otto tutorials also ship notebook versions
+(`tutorials/iris/iris_recognition.ipynb` and `tutorials/otto/otto.ipynb`)
+that render the layer-error curve, the confusion matrix, and the graphviz
+network diagrams inline.
+
+Every tutorial except `tutorials/otto/otto_classification.py` plots its
+results, so they need the `[viz]` extra — iris, california_housing, and
+concrete render network diagrams (graphviz), and iris plus both notebooks
+call `SONN.plot_layer_error` (matplotlib). The otto script runs on a base
+install.
+
+## Configuration
+
+Defaults are defined as a typed dataclass at
+`torchsonn.config.SONNConfig` (registered with Hydra's `ConfigStore`
+under the name `default`). Tutorial YAMLs use the
+`defaults: [default, _self_]` pattern, so each tutorial's YAML is just
+the diff against the schema. Override hierarchy at compose time:
+
+```
+SONNConfig defaults  →  tutorial YAML  →  CLI overrides
+```
+
+Type-checked at compose time: unknown keys and wrong-typed values are
+rejected before any training starts.
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE) for the full text.
+
+## Citation
+
+If you use TorchSONN in your research, please cite it as:
+
+```bibtex
+@software{kolokolov_torchsonn_2026,
+  author    = {Kolokolov, Konstantin},
+  title     = {{TorchSONN}: A {PyTorch} Implementation of the self-organizing polynomial neural network},
+  year      = {2026},
+  version   = {0.1.0},
+  url       = {https://github.com/kvoyager/torchsonn},
+  note      = {GitHub repository}
+}
+```
+

torchsonn-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torchsonn"
+version = "0.1.0"
+description = "Self-organizing polynomial neural network on PyTorch."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Konstantin Kolokolov" },
+]
+requires-python = ">=3.12"
+keywords = [
+    "gmdh",
+    "group-method-of-data-handling",
+    "polynomial-neural-network",
+    "pytorch",
+    "self-organizing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "hydra-core>=1.3",
+    "torch",
+    "numpy",
+    "scikit-learn",
+    "tqdm",
+    "omegaconf",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pandas",
+    # test_plot_model.py imports torchsonn.plot_model; test_model.py exercises
+    # SONN.plot_layer_error.
+    "torchsonn[viz]",
+]
+# Plotting-only, and each reached from exactly one call site: `graphviz` from
+# torchsonn.plot_model (an opt-in module), `matplotlib` from
+# SONN.plot_layer_error (imported inside the method so the base install stays
+# importable). graphviz is also inert without the system Graphviz binaries
+# (`dot` on PATH) — a common install snag. Keeping both out of the base
+# dependency set means a plain `pip install torchsonn` can't fail on them.
+viz = [
+    "graphviz",
+    "matplotlib",
+]
+
+[project.urls]
+Homepage = "https://github.com/kvoyager/torchsonn"
+Repository = "https://github.com/kvoyager/torchsonn"
+Issues = "https://github.com/kvoyager/torchsonn/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+# `where=["src"]` makes setuptools scan inside src/ instead of the project
+# root, picking up `torchsonn` + every subpackage (config, data, loss,
+# modules, neurons, optimizers, schedulers). Without this hint, auto-
+# discovery falls back to flat-layout rules and errors out because tests/
+# and tutorials/ also have __init__.py.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::UserWarning",
+]
+
+[tool.coverage.run]
+source = ["torchsonn"]
+omit = [
+    "*/tutorials/*",
+    "*/tests/*",
+]
+branch = false
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]

torchsonn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

torchsonn-0.1.0/src/torchsonn/__init__.py

@@ -0,0 +1,23 @@
+"""TorchSONN — self-organizing polynomial neural network on PyTorch.
+
+Everything needed for a full train / infer loop is re-exported here:
+
+    from torchsonn import SONN, SONNConfig, SONNDataset, Trainer
+
+`PlotModel` is deliberately *not* re-exported: it pulls in the optional
+`graphviz` dependency (``pip install "torchsonn[viz]"``), which would make a
+bare `import torchsonn` fail on a base install. It stays reachable as
+`from torchsonn.plot_model import PlotModel`.
+"""
+from torchsonn.config import SONNConfig
+from torchsonn.data.dataset import SONNDataset
+from torchsonn.model import SONN
+from torchsonn.trainer import Trainer
+
+
+__all__ = [
+    "SONN",
+    "SONNConfig",
+    "SONNDataset",
+    "Trainer",
+]

torchsonn-0.1.0/src/torchsonn/config/__init__.py

@@ -0,0 +1,22 @@
+"""Hydra-structured config schemas for SONN.
+
+Importing this package triggers `ConfigStore.store(name="default", node=SONNConfig)`,
+so any subsequent `@hydra.main` / `hydra.compose` call that references
+`- default` in its `defaults:` list resolves to the typed dataclass below.
+"""
+from torchsonn.config.schemas import (
+    ModelConfig,
+    OptimizerConfig,
+    SchedulerConfig,
+    SONNConfig,
+    TrainConfig,
+)
+
+
+__all__ = [
+    "ModelConfig",
+    "OptimizerConfig",
+    "SchedulerConfig",
+    "SONNConfig",
+    "TrainConfig",
+]