svdynamics 0.0.0a0__py3-none-any.whl

svdynamics/__init__.py

@@ -0,0 +1,61 @@
+import builtins
+import sys
+from .logo import *
+from .kernels import CompositeKernel
+from .svm import SVDClassifier, SVDRegressor
+
+__all__ = [
+    "CompositeKernel",
+    "SVDClassifier",
+    "SVDRegressor",
+]
+
+
+# Detailed Documentation
+
+detailed_doc = """
+Welcome to svdynamics! Support Vector Dynamics is a lightweight, scikit-learn
+compatible Python library for building and using mixed (composite) kernels for
+support vector machines. It provides a simple and extensible interface for
+combining multiple kernel functions into a single weighted kernel, while
+remaining fully compatible with existing sklearn pipelines, cross-validation,
+and calibration workflows.
+
+svdynamics focuses on making kernel composition a first-class modeling primitive
+for both classification and regression, without requiring any changes to the
+underlying scikit-learn API.
+
+PyPI: https://pypi.org/project/svdynamics/
+Documentation: https://lshpaner.github.io/svdynamics/
+
+Version: 0.0.0a0
+"""
+
+# Assign only the detailed documentation to __doc__
+__doc__ = detailed_doc
+
+
+__version__ = "0.0.0a0"
+__author__ = "Leonid Shpaner"
+__email__ = "lshpaner@ucla.edu"
+
+
+# Define the custom help function
+def custom_help(obj=None):
+    """
+    Custom help function to dynamically include ASCII art in help() output.
+    """
+    if (
+        obj is None or obj is sys.modules[__name__]
+    ):  # When `help()` is called for this module
+        print(svdynamics_logo)  # Print ASCII art first
+        print(detailed_doc)  # Print the detailed documentation
+    else:
+        original_help(obj)  # Use the original help for other objects
+
+
+# Backup the original help function
+original_help = builtins.help
+
+# Override the global help function in builtins
+builtins.help = custom_help

svdynamics/kernels.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+from sklearn.metrics.pairwise import linear_kernel, polynomial_kernel, rbf_kernel, sigmoid_kernel
+
+from .utils import ParsedKernel, KernelSpec, _validate_weights
+
+
+SUPPORTED_KERNELS = {"linear", "rbf", "poly", "sigmoid"}
+
+
+def _parse_kernel_spec(spec: KernelSpec) -> ParsedKernel:
+    # Callable kernel
+    if callable(spec):
+        return ParsedKernel(kind="callable", params={}, fn=spec)
+
+    # String kernel
+    if isinstance(spec, str):
+        k = spec.lower().strip()
+        if k not in SUPPORTED_KERNELS:
+            raise ValueError(f"Unsupported kernel '{spec}'. Supported: {sorted(SUPPORTED_KERNELS)}")
+        return ParsedKernel(kind=k, params={}, fn=None)
+
+    # Tuple kernel ("rbf", {...})
+    if isinstance(spec, tuple) and len(spec) == 2 and isinstance(spec[0], str) and isinstance(spec[1], dict):
+        k = spec[0].lower().strip()
+        if k not in SUPPORTED_KERNELS:
+            raise ValueError(f"Unsupported kernel '{spec[0]}'. Supported: {sorted(SUPPORTED_KERNELS)}")
+        return ParsedKernel(kind=k, params=dict(spec[1]), fn=None)
+
+    raise TypeError(
+        "Kernel spec must be one of: "
+        "a string ('rbf', 'linear', 'poly', 'sigmoid'), "
+        "a tuple like ('rbf', {'gamma': 0.1}), "
+        "or a callable kernel(X, Y)->ndarray."
+    )
+
+
+def _compute_kernel(parsed: ParsedKernel, X: np.ndarray, Y: np.ndarray) -> np.ndarray:
+    if parsed.kind == "callable":
+        assert parsed.fn is not None
+        K = parsed.fn(X, Y)
+        return np.asarray(K)
+
+    if parsed.kind == "linear":
+        return linear_kernel(X, Y)
+
+    if parsed.kind == "rbf":
+        return rbf_kernel(X, Y, **parsed.params)
+
+    if parsed.kind == "poly":
+        return polynomial_kernel(X, Y, **parsed.params)
+
+    if parsed.kind == "sigmoid":
+        return sigmoid_kernel(X, Y, **parsed.params)
+
+    raise RuntimeError(f"Unexpected kernel kind: {parsed.kind}")
+
+
+def _kernel_scale_from_diag(Kxx: np.ndarray, eps: float = 1e-12) -> float:
+    # Kxx is square kernel matrix
+    d = np.diag(Kxx)
+    # Use mean of diagonal as a stable scalar, avoid zeros
+    s = float(np.sqrt(max(float(np.mean(d * d)), eps)))
+    if not np.isfinite(s) or s <= 0.0:
+        return 1.0
+    return s
+
+
+@dataclass
+class CompositeKernel:
+    """
+    CompositeKernel builds a callable kernel that is a weighted sum of base kernels.
+
+    K(X, Y) = sum_m w_m * K_m(X, Y)
+
+    Parameters
+    ----------
+    kernels:
+        List of kernel specs. Each element can be:
+        - "rbf" | "linear" | "poly" | "sigmoid"
+        - ("rbf", {"gamma": 0.1}) etc.
+        - callable kernel(X, Y) -> ndarray
+    weights:
+        Optional weights for kernels. If None, uniform weights are used.
+        Weights are normalized to sum to 1.
+    normalize:
+        If True, each base kernel is rescaled by a scalar derived from K(X, X)
+        to reduce dominance due to scale.
+    eps:
+        Small constant used for numerical stability.
+    """
+
+    kernels: Sequence[KernelSpec]
+    weights: Optional[Sequence[float]] = None
+    normalize: bool = True
+    eps: float = 1e-12
+
+    def __post_init__(self) -> None:
+        if self.kernels is None or len(self.kernels) == 0:
+            raise ValueError("kernels must be a non-empty sequence")
+
+        self._parsed: List[ParsedKernel] = [_parse_kernel_spec(s) for s in self.kernels]
+        self._weights: np.ndarray = _validate_weights(len(self._parsed), self.weights)
+
+    @property
+    def parsed_kernels(self) -> List[ParsedKernel]:
+        return list(self._parsed)
+
+    @property
+    def normalized_weights(self) -> np.ndarray:
+        return self._weights.copy()
+
+    def as_callable(self) -> Callable[[np.ndarray, np.ndarray], np.ndarray]:
+        def _k(X: np.ndarray, Y: np.ndarray) -> np.ndarray:
+            return self(X, Y)
+
+        return _k
+
+    def __call__(self, X: np.ndarray, Y: np.ndarray) -> np.ndarray:
+        X = np.asarray(X)
+        Y = np.asarray(Y)
+
+        # Compute normalization scalars using K(X, X) for each kernel if requested
+        scales: List[float] = []
+        if self.normalize:
+            for pk in self._parsed:
+                Kxx = _compute_kernel(pk, X, X)
+                if Kxx.shape[0] != Kxx.shape[1]:
+                    raise ValueError("Expected square K(X, X) during normalization")
+                scales.append(_kernel_scale_from_diag(Kxx, eps=self.eps))
+        else:
+            scales = [1.0] * len(self._parsed)
+
+        # Combine kernels
+        K_total = None
+        for w, s, pk in zip(self._weights, scales, self._parsed):
+            K = _compute_kernel(pk, X, Y)
+            if K_total is None:
+                K_total = (w / s) * K
+            else:
+                K_total += (w / s) * K
+
+        assert K_total is not None
+        return np.asarray(K_total, dtype=float)

svdynamics/logo.py

@@ -0,0 +1,29 @@
+##################################################################################
+# ASCII/ ANSI Logo
+##################################################################################
+
+import os
+
+svdynamics_logo = """
+
+███████╗██╗   ██╗██████╗ ██████╗  ██████╗ ██████╗ ████████╗      
+██╔════╝██║   ██║██╔══██╗██╔══██╗██╔═══██╗██╔══██╗╚══██╔══╝      
+███████╗██║   ██║██████╔╝██████╔╝██║   ██║██████╔╝   ██║         
+╚════██║██║   ██║██╔═══╝ ██╔═══╝ ██║   ██║██╔══██╗   ██║         
+███████║╚██████╔╝██║     ██║     ╚██████╔╝██║  ██║   ██║         
+╚══════╝ ╚═════╝ ╚═╝     ╚═╝      ╚═════╝ ╚═╝  ╚═╝   ╚═╝         
+██╗   ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗               
+██║   ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗              
+██║   ██║█████╗  ██║        ██║   ██║   ██║██████╔╝              
+╚██╗ ██╔╝██╔══╝  ██║        ██║   ██║   ██║██╔══██╗              
+ ╚████╔╝ ███████╗╚██████╗   ██║   ╚██████╔╝██║  ██║              
+  ╚═══╝  ╚══════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝              
+██████╗ ██╗   ██╗███╗   ██╗ █████╗ ███╗   ███╗██╗ ██████╗███████╗
+██╔══██╗╚██╗ ██╔╝████╗  ██║██╔══██╗████╗ ████║██║██╔════╝██╔════╝
+██║  ██║ ╚████╔╝ ██╔██╗ ██║███████║██╔████╔██║██║██║     ███████╗
+██║  ██║  ╚██╔╝  ██║╚██╗██║██╔══██║██║╚██╔╝██║██║██║     ╚════██║
+██████╔╝   ██║   ██║ ╚████║██║  ██║██║ ╚═╝ ██║██║╚██████╗███████║
+╚═════╝    ╚═╝   ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝ ╚═════╝╚══════╝
+                                                                
+"""
+

svdynamics/svm.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Union
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin, RegressorMixin
+from sklearn.svm import SVC, SVR
+
+from .kernels import CompositeKernel
+
+
+KernelArg = Union[str, CompositeKernel, Any]  # string for sklearn kernels, CompositeKernel, or callable
+
+
+@dataclass
+class SVDClassifier(BaseEstimator, ClassifierMixin):
+    """
+    SVDClassifier is a thin wrapper around sklearn.svm.SVC that supports CompositeKernel.
+
+    If kernel is a CompositeKernel, the estimator uses a callable kernel.
+    Otherwise it passes through to sklearn SVC.
+    """
+
+    C: float = 1.0
+    kernel: KernelArg = "rbf"
+    degree: int = 3
+    gamma: Union[str, float] = "scale"
+    coef0: float = 0.0
+    shrinking: bool = True
+    probability: bool = False
+    tol: float = 1e-3
+    cache_size: float = 200.0
+    class_weight: Optional[Dict[Any, float]] = None
+    verbose: bool = False
+    max_iter: int = -1
+    decision_function_shape: str = "ovr"
+    break_ties: bool = False
+    random_state: Optional[int] = None
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> "SVDClassifier":
+        k = self.kernel.as_callable() if isinstance(self.kernel, CompositeKernel) else self.kernel
+
+        self._model = SVC(
+            C=self.C,
+            kernel=k,
+            degree=self.degree,
+            gamma=self.gamma,
+            coef0=self.coef0,
+            shrinking=self.shrinking,
+            probability=self.probability,
+            tol=self.tol,
+            cache_size=self.cache_size,
+            class_weight=self.class_weight,
+            verbose=self.verbose,
+            max_iter=self.max_iter,
+            decision_function_shape=self.decision_function_shape,
+            break_ties=self.break_ties,
+            random_state=self.random_state,
+        )
+        self._model.fit(X, y)
+
+        # ---- expose sklearn-required fitted attributes ----
+        self.classes_ = self._model.classes_
+
+        # optional but good hygiene for sklearn tooling
+        if hasattr(self._model, "n_features_in_"):
+            self.n_features_in_ = self._model.n_features_in_
+
+        return self
+
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        return self._model.predict(X)
+
+    def decision_function(self, X: np.ndarray) -> np.ndarray:
+        return self._model.decision_function(X)
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        if not getattr(self._model, "probability", False):
+            raise AttributeError("predict_proba is only available when probability=True")
+        return self._model.predict_proba(X)
+
+    @property
+    def support_vectors_(self) -> np.ndarray:
+        return self._model.support_vectors_
+
+    @property
+    def n_support_(self) -> np.ndarray:
+        return self._model.n_support_
+
+
+@dataclass
+class SVDRegressor(BaseEstimator, RegressorMixin):
+    """
+    SVDRegressor is a thin wrapper around sklearn.svm.SVR that supports CompositeKernel.
+    """
+
+    C: float = 1.0
+    kernel: KernelArg = "rbf"
+    degree: int = 3
+    gamma: Union[str, float] = "scale"
+    coef0: float = 0.0
+    tol: float = 1e-3
+    epsilon: float = 0.1
+    shrinking: bool = True
+    cache_size: float = 200.0
+    verbose: bool = False
+    max_iter: int = -1
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> "SVDRegressor":
+        k = self.kernel.as_callable() if isinstance(self.kernel, CompositeKernel) else self.kernel
+
+        self._model = SVR(
+            C=self.C,
+            kernel=k,
+            degree=self.degree,
+            gamma=self.gamma,
+            coef0=self.coef0,
+            tol=self.tol,
+            epsilon=self.epsilon,
+            shrinking=self.shrinking,
+            cache_size=self.cache_size,
+            verbose=self.verbose,
+            max_iter=self.max_iter,
+        )
+        self._model.fit(X, y)
+        return self
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        return self._model.predict(X)
+
+    @property
+    def support_(self) -> np.ndarray:
+        return self._model.support_

svdynamics/utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+
+KernelSpec = Union[
+    str,  # "rbf", "linear", "poly", "sigmoid"
+    Tuple[str, Dict[str, Any]],  # ("rbf", {"gamma": 0.1})
+    Any,  # callable kernel(X, Y) -> ndarray
+]
+
+
+@dataclass(frozen=True)
+class ParsedKernel:
+    kind: str  # "rbf", "linear", "poly", "sigmoid", or "callable"
+    params: Dict[str, Any]
+    fn: Optional[Any] = None  # for callable kernels
+
+
+def _as_list(x: Optional[Sequence[Any]]) -> List[Any]:
+    if x is None:
+        return []
+    return list(x)
+
+
+def _validate_weights(num_kernels: int, weights: Optional[Sequence[float]]) -> np.ndarray:
+    if weights is None:
+        w = np.ones(num_kernels, dtype=float)
+        return w / w.sum()
+
+    w = np.asarray(weights, dtype=float)
+    if w.ndim != 1 or w.shape[0] != num_kernels:
+        raise ValueError(f"weights must be length {num_kernels}, got shape {w.shape}")
+
+    if np.any(~np.isfinite(w)):
+        raise ValueError("weights must be finite")
+
+    if np.allclose(w.sum(), 0.0):
+        raise ValueError("weights sum to 0")
+
+    return w / w.sum()
+
+
+def _validate_square_kernel_matrix(K: np.ndarray, name: str = "K") -> None:
+    if not isinstance(K, np.ndarray):
+        raise TypeError(f"{name} must be a numpy array")
+    if K.ndim != 2:
+        raise ValueError(f"{name} must be 2D, got {K.ndim}D")
+    if K.shape[0] == 0 or K.shape[1] == 0:
+        raise ValueError(f"{name} must be non-empty, got shape {K.shape}")

svdynamics-0.0.0a0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: svdynamics
+Version: 0.0.0a0
+Summary: Support Vector Dynamics: mixed (composite) kernels for scikit-learn SVMs.
+Author: Leonid Shpaner
+License: MIT License
+        
+        Copyright (c) 2026 Leon Shpaner
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/lshpaner/svdynamics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Dynamic: license-file
+
+<img src="https://raw.githubusercontent.com/lshpaner/svdynamics/refs/heads/main/assets/svd_logo.svg" height="250" style="border: none; outline: none; box-shadow: none;" oncontextmenu="return false;">
+
+Welcome to `svdynamics`! Support Vector Dynamics is a lightweight, scikit-learn
+compatible Python library for building and using mixed (composite) kernels for
+support vector machines. It provides a simple and extensible interface for
+combining multiple kernel functions into a single weighted kernel, while
+remaining fully compatible with existing sklearn pipelines, cross-validation,
+and calibration workflows.
+
+`svdynamics` focuses on making kernel composition a first-class modeling primitive
+for both classification and regression, without requiring any changes to the
+underlying scikit-learn API.
+
+## Prerequisites
+
+Before you install `svdynamics`, ensure your system meets the following requirements:
+
+- `Python`: Version `3.8` or higher.
+
+
+Additionally, `svdynamics` depends on the following packages, which will be automatically installed:
+
+- `numpy`: version `1.21` or higher
+- `scikit-learn`: version `1.0` or higher
+
+
+## 💾 Installation
+
+To install `svdynamics`, simply run the following command in your terminal:
+
+
+```bash
+pip install svdynamics
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from sklearn.datasets import make_classification
+from svdynamics import CompositeKernel, SVDClassifier
+
+X, y = make_classification(n_samples=300, n_features=10, random_state=0)
+
+kernel = CompositeKernel(
+    kernels=[
+        ("rbf", {"gamma": 0.2}),
+        ("linear", {}),
+        ("poly", {"degree": 2, "coef0": 1.0}),
+    ],
+    weights=[0.6, 0.3, 0.1],
+    normalize=True,
+)
+
+clf = SVDClassifier(C=1.0, kernel=kernel, probability=True, random_state=0)
+clf.fit(X, y)
+proba = clf.predict_proba(X[:5])
+pred = clf.predict(X[:5])
+
+print(proba)
+print(pred)
+```
+
+## 📄 Official Documentation
+
+https://lshpaner.github.io/svdynamics
+
+
+## 🌐 Authors' Website
+
+1. [Leon Shpaner](https://www.leonshpaner.com)
+
+## ⚖️ License
+
+`svdynamics` is distributed under the MIT License. See [LICENSE](https://github.com/lshpaner/svdynamics/blob/main/LICENSE.md) for more information.

svdynamics-0.0.0a0.dist-info/RECORD

@@ -0,0 +1,10 @@
+svdynamics/__init__.py,sha256=lGoDzb38myqFmzTyiw83JXULgROJqpATdHoRdzEfwB8,1747
+svdynamics/kernels.py,sha256=qZD_WhMD4sW8685o3t-czS7patdwsPSPrP7h18q_ork,4949
+svdynamics/logo.py,sha256=rgNBeoHVgkS5toHGgd03N5a5YNS9EnxrXPrsfgwUIO0,3150
+svdynamics/svm.py,sha256=w1-Z6t6Sznx7qEtuvuMPftZ3bYSA0vwBjn8HeUOpljI,4098
+svdynamics/utils.py,sha256=nJ_1Fg1y0dzK0ldBm_z6AVYYJZkCM0fM9k3H6rNpmjw,1578
+svdynamics-0.0.0a0.dist-info/licenses/LICENSE,sha256=EgB5za7q_O_ot4diuV-MKV5dGsAY1g5VDBX1mSrSG14,1069
+svdynamics-0.0.0a0.dist-info/METADATA,sha256=mMiX1rpw1Xh75-tAG5UegPNbxS9pHC_5dCISB_tJVyg,3824
+svdynamics-0.0.0a0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+svdynamics-0.0.0a0.dist-info/top_level.txt,sha256=S_2tKPzvnhIcuViHPIZKkbV_NpzmCisBBy8UWWmPB3E,11
+svdynamics-0.0.0a0.dist-info/RECORD,,

svdynamics-0.0.0a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

svdynamics-0.0.0a0.dist-info/licenses/LICENSE

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

svdynamics-0.0.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+svdynamics