exponet 0.1.0__tar.gz

exponet-0.1.0/LICENSE

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

exponet-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: exponet
+Version: 0.1.0
+Summary: Trainable blend of ReLU and squared ReLU activations for PyTorch
+Author: ExpoNet Contributors
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# ExpoNet
+
+ExpoNet is a compact PyTorch library for dense numeric models with a trainable
+blend of ReLU and squared ReLU:
+
+```text
+u = max(x, 0)
+f(x; a) = (1 - a) * u + a * u * u
+0 <= a <= 1
+```
+
+The primary activation uses one learned coefficient per hidden neuron. It uses
+multiplication and addition on activation values, not a general power. ExpoNet
+also provides scikit-learn-compatible dense regression and classification
+estimators with CPU or a single CUDA device.
+
+## Install
+
+ExpoNet requires Python 3.11 or later, PyTorch, NumPy, and scikit-learn.
+Install the PyTorch build appropriate for your platform and GPU first, using
+the [official PyTorch selector](https://pytorch.org/get-started/locally/), then
+install this checkout:
+
+```powershell
+python -m pip install .
+```
+
+For a checkout, install the project and its development tools with:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Package publication is not part of this release-readiness milestone; install a
+built wheel locally with `python -m pip install dist/exponet-0.1.0-py3-none-any.whl`.
+
+`device="auto"` uses CUDA when `torch.cuda.is_available()` is true, otherwise
+CPU. `device="cuda"` or `device="cuda:N"` requires that device and raises if
+it is unavailable; ExpoNet never silently falls back to CPU. A CUDA toolkit
+compiler (`nvcc`) is not required for the prebuilt-PyTorch path.
+
+Verified release-candidate coverage is Windows 11 CPU and CUDA on an NVIDIA
+GeForce RTX 5060 (PyTorch 2.11.0+cu128, CUDA runtime 12.8, Python 3.12.10,
+NumPy 2.5.2, scikit-learn 1.9.0). Linux has not yet been validated, so it is
+not claimed as supported coverage.
+
+## Quick start
+
+```python
+import numpy as np
+from exponet import ExpoRegressor
+
+rng = np.random.default_rng(0)
+X = rng.normal(size=(80, 2)).astype(np.float32)
+y = (1.5 * X[:, 0] - 0.75 * X[:, 1] + 0.2).astype(np.float32)
+
+model = ExpoRegressor(
+    hidden_dims=(8,),
+    normalization="none",
+    trainable_blend=False,
+    blend_init=0.0,  # ReLU control
+    epochs=80,
+    lr=0.03,
+    device="auto",
+    random_state=0,
+).fit(X, y)
+
+predictions = model.predict(X[:3])  # shape: (3,)
+print(model.device_, predictions)
+```
+
+The same verified examples are available for [direct PyTorch use](examples/direct_torch.py),
+[regression](examples/regression.py), and [multiclass classification](examples/classification.py).
+
+## Public API
+
+| Export | Purpose | Output shape |
+| --- | --- | --- |
+| `ExpoActivation` | Reusable PyTorch activation. | Same as input tensor. |
+| `ExpoMLP` | Dense `Linear -> optional LayerNorm -> ExpoActivation` blocks and a linear readout. | `(batch, out_features)` |
+| `ExpoRegressor` | Dense numeric regression estimator. | `predict`: `(N,)` for 1-D targets, otherwise `(N, K)` |
+| `ExpoClassifier` | Binary/multiclass integer or string-label estimator. | `predict`: `(N,)`; `predict_proba`: `(N, K)` in `classes_` order |
+
+Both estimators accept dense finite numeric features shaped `(N, F)`, train in
+float32, provide `fit`, `predict`, `score`, `get_blend_weights`, and restricted
+inference `save`/`load` methods. See the [API contract](docs/API_CONTRACT.md)
+for constructor parameters, validation, scaling, early stopping, persistence,
+and reproducibility semantics.
+
+## Scope and limitations
+
+- This is a dense numeric-data library. Sparse inputs, missing values,
+  categorical encoding, image/sequence architectures, sample/class weights,
+  streaming, warm starts, AMP, compilation, distributed execution, and custom
+  training hooks are outside this release.
+- Classification accepts homogeneous integer or string labels only; continuous,
+  mixed, multilabel, and multioutput labels are rejected.
+- Float32 is the primary runtime dtype. CPU float64 is supported for low-level
+  activation mathematics tests. Very large positive activations can overflow,
+  particularly toward the squared-ReLU endpoint.
+- Saved snapshots restore inference state only, not optimizer or RNG state; do
+  not treat a loaded estimator as an exact training-resume checkpoint.
+- The initial controlled evaluation did not show a consistent predictive
+  advantage over native ReLU, so no superiority or universal-normalization
+  claim is made. See the [initial evaluation](docs/INITIAL_EVALUATION.md).
+
+## Development validation
+
+```powershell
+python -B -m ruff format --check --no-cache --no-respect-gitignore src tests benchmarks examples
+python -B -m ruff check --no-cache --no-respect-gitignore src tests benchmarks examples
+python -B -m pytest -q -p no:cacheprovider
+```
+
+The [roadmap](docs/ROADMAP.md) records exact validation evidence and release
+scope. ExpoNet is available under the [MIT License](LICENSE).
+
+## Design and evidence
+
+| Document | Purpose |
+| --- | --- |
+| [API contract](docs/API_CONTRACT.md) | Implemented interfaces and exact behavior. |
+| [Design](docs/DESIGN.md) | Mathematics, numerical behavior, normalization, and architecture. |
+| [Decisions](docs/DECISIONS.md) | Accepted scope and defaults. |
+| [Validation](docs/VALIDATION.md) | Correctness checks and experimental criteria. |
+| [Initial evaluation](docs/INITIAL_EVALUATION.md) | P6 five-seed activation comparison. |
+| [Activation timing](docs/ACTIVATION_BENCHMARK.md) | P1.04 CPU timing evidence and limitations. |
+| [PSANN reuse assessment](docs/PSANN_REUSE.md) | Selective adaptation provenance; no PSANN runtime dependency. |
+| [Roadmap](docs/ROADMAP.md) | Completed work, release evidence, and deferred scope. |

exponet-0.1.0/README.md

@@ -0,0 +1,129 @@
+# ExpoNet
+
+ExpoNet is a compact PyTorch library for dense numeric models with a trainable
+blend of ReLU and squared ReLU:
+
+```text
+u = max(x, 0)
+f(x; a) = (1 - a) * u + a * u * u
+0 <= a <= 1
+```
+
+The primary activation uses one learned coefficient per hidden neuron. It uses
+multiplication and addition on activation values, not a general power. ExpoNet
+also provides scikit-learn-compatible dense regression and classification
+estimators with CPU or a single CUDA device.
+
+## Install
+
+ExpoNet requires Python 3.11 or later, PyTorch, NumPy, and scikit-learn.
+Install the PyTorch build appropriate for your platform and GPU first, using
+the [official PyTorch selector](https://pytorch.org/get-started/locally/), then
+install this checkout:
+
+```powershell
+python -m pip install .
+```
+
+For a checkout, install the project and its development tools with:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Package publication is not part of this release-readiness milestone; install a
+built wheel locally with `python -m pip install dist/exponet-0.1.0-py3-none-any.whl`.
+
+`device="auto"` uses CUDA when `torch.cuda.is_available()` is true, otherwise
+CPU. `device="cuda"` or `device="cuda:N"` requires that device and raises if
+it is unavailable; ExpoNet never silently falls back to CPU. A CUDA toolkit
+compiler (`nvcc`) is not required for the prebuilt-PyTorch path.
+
+Verified release-candidate coverage is Windows 11 CPU and CUDA on an NVIDIA
+GeForce RTX 5060 (PyTorch 2.11.0+cu128, CUDA runtime 12.8, Python 3.12.10,
+NumPy 2.5.2, scikit-learn 1.9.0). Linux has not yet been validated, so it is
+not claimed as supported coverage.
+
+## Quick start
+
+```python
+import numpy as np
+from exponet import ExpoRegressor
+
+rng = np.random.default_rng(0)
+X = rng.normal(size=(80, 2)).astype(np.float32)
+y = (1.5 * X[:, 0] - 0.75 * X[:, 1] + 0.2).astype(np.float32)
+
+model = ExpoRegressor(
+    hidden_dims=(8,),
+    normalization="none",
+    trainable_blend=False,
+    blend_init=0.0,  # ReLU control
+    epochs=80,
+    lr=0.03,
+    device="auto",
+    random_state=0,
+).fit(X, y)
+
+predictions = model.predict(X[:3])  # shape: (3,)
+print(model.device_, predictions)
+```
+
+The same verified examples are available for [direct PyTorch use](examples/direct_torch.py),
+[regression](examples/regression.py), and [multiclass classification](examples/classification.py).
+
+## Public API
+
+| Export | Purpose | Output shape |
+| --- | --- | --- |
+| `ExpoActivation` | Reusable PyTorch activation. | Same as input tensor. |
+| `ExpoMLP` | Dense `Linear -> optional LayerNorm -> ExpoActivation` blocks and a linear readout. | `(batch, out_features)` |
+| `ExpoRegressor` | Dense numeric regression estimator. | `predict`: `(N,)` for 1-D targets, otherwise `(N, K)` |
+| `ExpoClassifier` | Binary/multiclass integer or string-label estimator. | `predict`: `(N,)`; `predict_proba`: `(N, K)` in `classes_` order |
+
+Both estimators accept dense finite numeric features shaped `(N, F)`, train in
+float32, provide `fit`, `predict`, `score`, `get_blend_weights`, and restricted
+inference `save`/`load` methods. See the [API contract](docs/API_CONTRACT.md)
+for constructor parameters, validation, scaling, early stopping, persistence,
+and reproducibility semantics.
+
+## Scope and limitations
+
+- This is a dense numeric-data library. Sparse inputs, missing values,
+  categorical encoding, image/sequence architectures, sample/class weights,
+  streaming, warm starts, AMP, compilation, distributed execution, and custom
+  training hooks are outside this release.
+- Classification accepts homogeneous integer or string labels only; continuous,
+  mixed, multilabel, and multioutput labels are rejected.
+- Float32 is the primary runtime dtype. CPU float64 is supported for low-level
+  activation mathematics tests. Very large positive activations can overflow,
+  particularly toward the squared-ReLU endpoint.
+- Saved snapshots restore inference state only, not optimizer or RNG state; do
+  not treat a loaded estimator as an exact training-resume checkpoint.
+- The initial controlled evaluation did not show a consistent predictive
+  advantage over native ReLU, so no superiority or universal-normalization
+  claim is made. See the [initial evaluation](docs/INITIAL_EVALUATION.md).
+
+## Development validation
+
+```powershell
+python -B -m ruff format --check --no-cache --no-respect-gitignore src tests benchmarks examples
+python -B -m ruff check --no-cache --no-respect-gitignore src tests benchmarks examples
+python -B -m pytest -q -p no:cacheprovider
+```
+
+The [roadmap](docs/ROADMAP.md) records exact validation evidence and release
+scope. ExpoNet is available under the [MIT License](LICENSE).
+
+## Design and evidence
+
+| Document | Purpose |
+| --- | --- |
+| [API contract](docs/API_CONTRACT.md) | Implemented interfaces and exact behavior. |
+| [Design](docs/DESIGN.md) | Mathematics, numerical behavior, normalization, and architecture. |
+| [Decisions](docs/DECISIONS.md) | Accepted scope and defaults. |
+| [Validation](docs/VALIDATION.md) | Correctness checks and experimental criteria. |
+| [Initial evaluation](docs/INITIAL_EVALUATION.md) | P6 five-seed activation comparison. |
+| [Activation timing](docs/ACTIVATION_BENCHMARK.md) | P1.04 CPU timing evidence and limitations. |
+| [PSANN reuse assessment](docs/PSANN_REUSE.md) | Selective adaptation provenance; no PSANN runtime dependency. |
+| [Roadmap](docs/ROADMAP.md) | Completed work, release evidence, and deferred scope. |

exponet-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exponet"
+version = "0.1.0"
+description = "Trainable blend of ReLU and squared ReLU activations for PyTorch"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "ExpoNet Contributors"}]
+requires-python = ">=3.11"
+dependencies = ["torch>=2.0.0", "numpy>=1.24.0", "scikit-learn>=1.3.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "ruff>=0.1.0"]
+
+[tool.setuptools]
+packages = ["exponet"]
+package-dir = {"" = "src"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

exponet-0.1.0/setup.cfg

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

exponet-0.1.0/src/exponet/__init__.py

@@ -0,0 +1,8 @@
+"""ExpoNet: Trainable blend of ReLU and squared ReLU activations."""
+
+from exponet.activations import ExpoActivation as ExpoActivation
+from exponet.estimators import ExpoClassifier as ExpoClassifier
+from exponet.estimators import ExpoRegressor as ExpoRegressor
+from exponet.nn import ExpoMLP as ExpoMLP
+
+__version__ = "0.1.0"

exponet-0.1.0/src/exponet/_persistence.py

@@ -0,0 +1,172 @@
+"""Restricted, versioned inference snapshots for ExpoNet estimators."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import sklearn
+import torch
+from sklearn.preprocessing import StandardScaler
+
+FORMAT_VERSION = 1
+
+
+def _cpu_state_dict(model: torch.nn.Module) -> dict[str, torch.Tensor]:
+    """Copy state tensors to CPU without changing the live model's device."""
+    return {
+        name: value.detach().cpu().clone() for name, value in model.state_dict().items()
+    }
+
+
+def _scaler_payload(scaler: StandardScaler | None) -> dict[str, object] | None:
+    if scaler is None:
+        return None
+    return {
+        "mean": torch.as_tensor(scaler.mean_, dtype=torch.float64).clone(),
+        "scale": torch.as_tensor(scaler.scale_, dtype=torch.float64).clone(),
+        "var": torch.as_tensor(scaler.var_, dtype=torch.float64).clone(),
+        "n_features_in": int(scaler.n_features_in_),
+        "n_samples_seen": int(np.asarray(scaler.n_samples_seen_).item()),
+    }
+
+
+def _primitive_constructor(params: dict[str, object]) -> dict[str, object]:
+    result = dict(params)
+    result["hidden_dims"] = list(result["hidden_dims"])
+    return result
+
+
+def save_snapshot(estimator: Any, *, kind: str, path: str | Path) -> None:
+    """Atomically write a restricted inference snapshot for a fitted estimator."""
+    destination = Path(path)
+    if not destination.parent.exists():
+        raise ValueError(f"snapshot directory does not exist: {destination.parent}")
+    if not destination.parent.is_dir():
+        raise ValueError(f"snapshot parent is not a directory: {destination.parent}")
+    payload: dict[str, object] = {
+        "format_version": FORMAT_VERSION,
+        "estimator_kind": kind,
+        "constructor": _primitive_constructor(estimator.get_params(deep=False)),
+        "model_state": _cpu_state_dict(estimator.model_),
+        "fitted": {
+            "n_features_in": int(estimator.n_features_in_),
+            "n_iter": int(estimator.n_iter_),
+            "best_epoch": estimator.best_epoch_,
+            "history": estimator.history_,
+            "feature_scaler": _scaler_payload(estimator.feature_scaler_),
+        },
+        "producer": {
+            "exponet": "0.1.0",
+            "torch": str(torch.__version__),
+            "numpy": np.__version__,
+            "scikit_learn": sklearn.__version__,
+        },
+    }
+    fitted = payload["fitted"]
+    assert isinstance(fitted, dict)
+    if kind == "regressor":
+        fitted.update(
+            {
+                "n_outputs": int(estimator.n_outputs_),
+                "target_was_1d": bool(estimator._target_was_1d),
+                "target_scaler": _scaler_payload(estimator.target_scaler_),
+            }
+        )
+    elif kind == "classifier":
+        fitted.update(
+            {
+                "n_classes": int(estimator.n_classes_),
+                "classes": estimator.classes_.tolist(),
+            }
+        )
+    else:
+        raise ValueError(f"unsupported estimator kind: {kind!r}")
+
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=destination.parent,
+            prefix=f".{destination.name}.",
+            delete=False,
+        ) as temporary:
+            temporary_name = temporary.name
+        torch.save(payload, temporary_name)
+        os.replace(temporary_name, destination)
+        temporary_name = None
+    finally:
+        if temporary_name is not None:
+            Path(temporary_name).unlink(missing_ok=True)
+
+
+def load_snapshot(path: str | Path, *, expected_kind: str) -> dict[str, object]:
+    """Read and validate only the outer restricted snapshot envelope."""
+    try:
+        payload = torch.load(path, map_location="cpu", weights_only=True)
+    except Exception as error:
+        raise ValueError("invalid or unreadable ExpoNet snapshot") from error
+    if not isinstance(payload, dict):
+        raise ValueError("snapshot must contain a dictionary payload")
+    if payload.get("format_version") != FORMAT_VERSION:
+        raise ValueError("unsupported ExpoNet snapshot format version")
+    if payload.get("estimator_kind") != expected_kind:
+        raise ValueError(
+            f"snapshot is for {payload.get('estimator_kind')!r}, not {expected_kind!r}"
+        )
+    if not isinstance(payload.get("constructor"), dict):
+        raise ValueError("snapshot constructor metadata is invalid")
+    if not isinstance(payload.get("fitted"), dict):
+        raise ValueError("snapshot fitted metadata is invalid")
+    if not isinstance(payload.get("model_state"), dict) or not all(
+        isinstance(name, str) and isinstance(value, torch.Tensor)
+        for name, value in payload["model_state"].items()
+    ):
+        raise ValueError("snapshot model state is invalid")
+    return payload
+
+
+def restore_scaler(
+    payload: object, *, expected_features: int, name: str
+) -> StandardScaler | None:
+    """Rebuild a fitted StandardScaler from finite tensor-only metadata."""
+    if payload is None:
+        return None
+    if not isinstance(payload, dict):
+        raise ValueError(f"snapshot {name} metadata is invalid")
+    try:
+        count = payload["n_features_in"]
+        seen = payload["n_samples_seen"]
+        mean = payload["mean"]
+        scale = payload["scale"]
+        var = payload["var"]
+    except KeyError as error:
+        raise ValueError(f"snapshot {name} metadata is incomplete") from error
+    if (
+        not isinstance(count, int)
+        or isinstance(count, bool)
+        or count != expected_features
+        or not isinstance(seen, int)
+        or isinstance(seen, bool)
+        or seen <= 0
+        or not all(isinstance(value, torch.Tensor) for value in (mean, scale, var))
+    ):
+        raise ValueError(f"snapshot {name} metadata is invalid")
+    arrays = [
+        value.detach().cpu().numpy().astype(np.float64, copy=True)
+        for value in (mean, scale, var)
+    ]
+    if any(array.shape != (expected_features,) for array in arrays) or not all(
+        np.isfinite(array).all() for array in arrays
+    ):
+        raise ValueError(f"snapshot {name} arrays are invalid")
+    if np.any(arrays[1] <= 0) or np.any(arrays[2] < 0):
+        raise ValueError(f"snapshot {name} arrays are invalid")
+    scaler = StandardScaler()
+    scaler.mean_, scaler.scale_, scaler.var_ = arrays
+    scaler.n_features_in_ = expected_features
+    scaler.n_samples_seen_ = seen
+    return scaler