simplex-tree-classifier 0.1.0__tar.gz

simplex_tree_classifier-0.1.0/LICENSE

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

simplex_tree_classifier-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: simplex-tree-classifier
+Version: 0.1.0
+Summary: Hierarchical simplex-tree classifier with barycentric embedding, GPU-accelerated transform, and non-convex boundary pruning.
+Author: Yasmin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yasmin/SimplexTreeClassifier
+Project-URL: Repository, https://github.com/yasmin/SimplexTreeClassifier
+Keywords: machine-learning,classifier,simplex,barycentric,interpretability,surrogate-model
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: torch>=1.12
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.4; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# simplex-tree-classifier
+
+A hierarchical **simplex-tree classifier**. It embeds points into the barycentric
+coordinates of a subdivided simplex, then trains any scikit-learn estimator on
+that sparse, geometry-aware feature space. The barycentric `transform` is
+accelerated with **PyTorch** and runs on the GPU when one is available.
+
+It works in two ways:
+
+- **Dataset mode** - train directly on your data `(X, y)`.
+- **Surrogate mode** - imitate an existing `model` (e.g. a neural network) to
+produce an interpretable, piecewise-linear geometric surrogate.
+
+Everything is **N-dimensional**.
+
+## Installation
+
+```bash
+pip install simplex-tree-classifier          # core (numpy, scipy, scikit-learn, torch)
+pip install simplex-tree-classifier[viz]      # + matplotlib for 2-D plots
+```
+
+From source:
+
+```bash
+cd simplex_tree_package
+pip install -e .
+```
+
+
+
+## Quickstart
+
+
+
+### Dataset mode
+
+```python
+import numpy as np
+from simplex_tree_classifier import SimplexTreeClassifier
+
+X = np.random.uniform(0, 1, size=(500, 4))
+y = (X.sum(axis=1) > 2.0).astype(int)
+
+clf = SimplexTreeClassifier(subdivision_levels=2)   # default classifier: LinearSVC
+clf.fit(X, y)
+print(clf.predict(X[:5]))
+```
+
+
+
+### Surrogate mode (imitate a model)
+
+Pass any object with `.predict(X)` or any callable `X -> labels`, plus the input
+dimensionality. Fill points are sampled in `[0, 1]^d` and labeled by the model.
+
+```python
+def black_box(X):                      # e.g. a wrapped PyTorch model
+    X = np.atleast_2d(X)
+    return (X[:, 0] + X[:, 1] > 1.0).astype(int)
+
+surrogate = SimplexTreeClassifier(
+    model=black_box,
+    n_features=2,
+    subdivision_levels=4,
+    n_fill=5000,
+)
+surrogate.fit()                        # samples + labels internally
+```
+
+
+
+### Data-driven subdivision
+
+Instead of uniform (barycentric) subdivision, split only where the classifier is
+still wrong:
+
+```python
+clf = SimplexTreeClassifier(
+    subdivision_strategy="data_driven",
+    subdivision_levels=6,     # here: maximum tree depth
+    max_leaves=500,
+)
+clf.fit(X, y)
+```
+
+
+
+## API overview
+
+Constructor: `SimplexTreeClassifier(classifier=None, model=None, n_features=None, subdivision_levels=1, subdivision_strategy="barycentric", n_fill=5000, max_leaves=None, normalize=None, margin=0.05, device=None, tolerance=1e-10, random_state=None, data_driven_max_iter=50)`
+
+Core methods:
+
+- `transform(X)` - sparse barycentric embedding (GPU-accelerated); rows sum to 1.
+- `fit(X=None, y=None)` - trains the classifier. In surrogate mode `X`/`y` are
+optional. Automatically records same-side simplices afterward (linear only).
+- `predict(X)` - predicted labels.
+
+Geometry queries:
+
+- `find_containing_simplex(point)` - the leaf simplex a point falls in.
+- `find_adjacent_simplexes(simplex)` - leaves sharing a `(d-1)`-face.
+- `get_simplex_vertices()` - vertices of every leaf simplex (renamed from
+`get_simplex_boundaries`).
+- `is_in_simplex(point, simplex)` - boolean containment test.
+
+Decision-boundary analysis (linear classifiers, multiclass-aware):
+
+- `identify_crossing_simplices()` - leaves crossed by the decision boundary.
+- `remove_nonconvex_leaves(criterion="distance"|"convexity_sign", removal_factor=0.15, epsilon=None, keep_frac=None, min_depth=0.0, max_remove_frac=0.25, max_iter=10, refit=True)` - iteratively prune leaves whose
+boundary bends non-convexly.
+- `find_same_side_simplices()` - subdivisions that don't touch the boundary (also
+run automatically at the end of `fit`, stored in `same_side_keys_`).
+- `compute_plane_equations()` - the boundary hyperplane within each crossing leaf.
+
+Helpers: `SimplexTree`, `Simplex`, `VertexRegistry`, `make_enclosing_simplex(d)`,
+`get_device()`.
+
+## GPU acceleration
+
+`transform` stacks each leaf's inverse edge matrix into tensors and embeds an
+entire batch of points against all leaves at once. The device is auto-detected
+(CUDA if present); override with `device="cpu"` / `device="cuda"`. Points outside
+every leaf (or inside a degenerate one) fall back to an exact per-point search.
+
+## TODO
+
+- [ ] **Overleaf cross-check.** Reconcile this package's operations against the
+  list of supported operations in the paper (Overleaf) and add anything missing.
+

simplex_tree_classifier-0.1.0/README.md

@@ -0,0 +1,131 @@
+# simplex-tree-classifier
+
+A hierarchical **simplex-tree classifier**. It embeds points into the barycentric
+coordinates of a subdivided simplex, then trains any scikit-learn estimator on
+that sparse, geometry-aware feature space. The barycentric `transform` is
+accelerated with **PyTorch** and runs on the GPU when one is available.
+
+It works in two ways:
+
+- **Dataset mode** - train directly on your data `(X, y)`.
+- **Surrogate mode** - imitate an existing `model` (e.g. a neural network) to
+produce an interpretable, piecewise-linear geometric surrogate.
+
+Everything is **N-dimensional**.
+
+## Installation
+
+```bash
+pip install simplex-tree-classifier          # core (numpy, scipy, scikit-learn, torch)
+pip install simplex-tree-classifier[viz]      # + matplotlib for 2-D plots
+```
+
+From source:
+
+```bash
+cd simplex_tree_package
+pip install -e .
+```
+
+
+
+## Quickstart
+
+
+
+### Dataset mode
+
+```python
+import numpy as np
+from simplex_tree_classifier import SimplexTreeClassifier
+
+X = np.random.uniform(0, 1, size=(500, 4))
+y = (X.sum(axis=1) > 2.0).astype(int)
+
+clf = SimplexTreeClassifier(subdivision_levels=2)   # default classifier: LinearSVC
+clf.fit(X, y)
+print(clf.predict(X[:5]))
+```
+
+
+
+### Surrogate mode (imitate a model)
+
+Pass any object with `.predict(X)` or any callable `X -> labels`, plus the input
+dimensionality. Fill points are sampled in `[0, 1]^d` and labeled by the model.
+
+```python
+def black_box(X):                      # e.g. a wrapped PyTorch model
+    X = np.atleast_2d(X)
+    return (X[:, 0] + X[:, 1] > 1.0).astype(int)
+
+surrogate = SimplexTreeClassifier(
+    model=black_box,
+    n_features=2,
+    subdivision_levels=4,
+    n_fill=5000,
+)
+surrogate.fit()                        # samples + labels internally
+```
+
+
+
+### Data-driven subdivision
+
+Instead of uniform (barycentric) subdivision, split only where the classifier is
+still wrong:
+
+```python
+clf = SimplexTreeClassifier(
+    subdivision_strategy="data_driven",
+    subdivision_levels=6,     # here: maximum tree depth
+    max_leaves=500,
+)
+clf.fit(X, y)
+```
+
+
+
+## API overview
+
+Constructor: `SimplexTreeClassifier(classifier=None, model=None, n_features=None, subdivision_levels=1, subdivision_strategy="barycentric", n_fill=5000, max_leaves=None, normalize=None, margin=0.05, device=None, tolerance=1e-10, random_state=None, data_driven_max_iter=50)`
+
+Core methods:
+
+- `transform(X)` - sparse barycentric embedding (GPU-accelerated); rows sum to 1.
+- `fit(X=None, y=None)` - trains the classifier. In surrogate mode `X`/`y` are
+optional. Automatically records same-side simplices afterward (linear only).
+- `predict(X)` - predicted labels.
+
+Geometry queries:
+
+- `find_containing_simplex(point)` - the leaf simplex a point falls in.
+- `find_adjacent_simplexes(simplex)` - leaves sharing a `(d-1)`-face.
+- `get_simplex_vertices()` - vertices of every leaf simplex (renamed from
+`get_simplex_boundaries`).
+- `is_in_simplex(point, simplex)` - boolean containment test.
+
+Decision-boundary analysis (linear classifiers, multiclass-aware):
+
+- `identify_crossing_simplices()` - leaves crossed by the decision boundary.
+- `remove_nonconvex_leaves(criterion="distance"|"convexity_sign", removal_factor=0.15, epsilon=None, keep_frac=None, min_depth=0.0, max_remove_frac=0.25, max_iter=10, refit=True)` - iteratively prune leaves whose
+boundary bends non-convexly.
+- `find_same_side_simplices()` - subdivisions that don't touch the boundary (also
+run automatically at the end of `fit`, stored in `same_side_keys_`).
+- `compute_plane_equations()` - the boundary hyperplane within each crossing leaf.
+
+Helpers: `SimplexTree`, `Simplex`, `VertexRegistry`, `make_enclosing_simplex(d)`,
+`get_device()`.
+
+## GPU acceleration
+
+`transform` stacks each leaf's inverse edge matrix into tensors and embeds an
+entire batch of points against all leaves at once. The device is auto-detected
+(CUDA if present); override with `device="cpu"` / `device="cuda"`. Points outside
+every leaf (or inside a degenerate one) fall back to an exact per-point search.
+
+## TODO
+
+- [ ] **Overleaf cross-check.** Reconcile this package's operations against the
+  list of supported operations in the paper (Overleaf) and add anything missing.
+

simplex_tree_classifier-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simplex-tree-classifier"
+version = "0.1.0"
+description = "Hierarchical simplex-tree classifier with barycentric embedding, GPU-accelerated transform, and non-convex boundary pruning."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yasmin" }]
+keywords = [
+    "machine-learning",
+    "classifier",
+    "simplex",
+    "barycentric",
+    "interpretability",
+    "surrogate-model",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.21",
+    "scipy>=1.7",
+    "scikit-learn>=1.0",
+    "torch>=1.12",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.4"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/yasmin/SimplexTreeClassifier"
+Repository = "https://github.com/yasmin/SimplexTreeClassifier"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

simplex_tree_classifier-0.1.0/setup.cfg

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

simplex_tree_classifier-0.1.0/src/simplex_tree_classifier/__init__.py

@@ -0,0 +1,28 @@
+"""simplex_tree_classifier - hierarchical simplex-tree classifier.
+
+Public API:
+    - ``SimplexTreeClassifier``: the main estimator (dataset or surrogate mode).
+    - ``SimplexTree`` / ``Simplex`` / ``VertexRegistry``: the geometric core.
+    - ``make_enclosing_simplex``: build an N-D simplex enclosing ``[0, 1]^d``.
+    - ``get_device``: resolve the torch device used for the transform.
+"""
+
+from .vertex_registry import VertexRegistry
+from .simplex import Simplex
+from .simplex_tree import SimplexTree, make_enclosing_simplex
+from .plane_equation import PlaneEquation
+from .classifier import SimplexTreeClassifier
+from .backend import get_device
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SimplexTreeClassifier",
+    "SimplexTree",
+    "Simplex",
+    "VertexRegistry",
+    "PlaneEquation",
+    "make_enclosing_simplex",
+    "get_device",
+    "__version__",
+]

simplex_tree_classifier-0.1.0/src/simplex_tree_classifier/backend.py

@@ -0,0 +1,181 @@
+"""PyTorch backend that accelerates the barycentric ``transform``.
+
+Leaves produced by barycentric subdivision are full ``d``-simplices (``d + 1``
+vertices), so each non-degenerate leaf has an invertible edge matrix ``A`` with a
+precomputed inverse. This backend stacks those per-leaf inverses into tensors and
+embeds an entire batch of points against every leaf at once, on the GPU when one
+is available. For each point it selects the leaf whose barycentric coordinates
+are all non-negative and most interior.
+
+Points that are not resolved on the GPU (outside every leaf, or inside a
+degenerate leaf excluded from the tensor stack) are reported back so the caller
+can fall back to the exact per-point CPU search.
+"""
+
+from typing import List, Optional
+
+import numpy as np
+
+try:
+    import torch
+    _TORCH_AVAILABLE = True
+except ImportError:  # pragma: no cover - torch is a hard dependency, guard anyway
+    torch = None
+    _TORCH_AVAILABLE = False
+
+
+def get_device(device=None):
+    """Resolve a torch device, defaulting to CUDA when available, else CPU.
+
+    Args:
+        device: An explicit ``torch.device``/str, or ``None`` to auto-detect.
+
+    Returns:
+        A ``torch.device``.
+    """
+    if not _TORCH_AVAILABLE:
+        raise ImportError(
+            "PyTorch is required for simplex_tree_classifier. Install it with "
+            "`pip install torch`."
+        )
+    if device is not None:
+        return torch.device(device)
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    return torch.device("cpu")
+
+
+class TransformBackend:
+    """Precomputes per-leaf tensors and batch-embeds points into barycentric coords."""
+
+    def __init__(self, device=None, tolerance: float = 1e-10,
+                 element_budget: int = 40_000_000):
+        self.device = get_device(device)
+        self.tolerance = tolerance
+        # Caps the number of (chunk x leaves x dim) elements held at once.
+        self.element_budget = int(element_budget)
+        self.dtype = torch.float64
+        self._built = False
+
+        self.leaves: List = []
+        self.n_leaves = 0
+        self.dimension = 0
+        # Global vertex indices per leaf, in the order alphas are produced.
+        self.leaf_vertex_indices: Optional[np.ndarray] = None
+        self._V0 = None      # (L, d)
+        self._A_inv = None   # (L, d, d)
+
+    @property
+    def is_built(self) -> bool:
+        return self._built and self.n_leaves > 0
+
+    def build(self, leaves: List) -> None:
+        """Stack tensors for all full, non-degenerate leaves.
+
+        Args:
+            leaves: Iterable of leaf ``SimplexTree`` nodes.
+        """
+        self._built = False
+        self.leaves = []
+        v0_list = []
+        a_inv_list = []
+        vidx_list = []
+
+        dimension = None
+        for leaf in leaves:
+            d = leaf.dimension
+            # Only stack full simplices with a usable inverse.
+            if leaf.n_vertices != d + 1:
+                continue
+            if getattr(leaf, "is_degenerate", False) or getattr(leaf, "A_inv", None) is None:
+                continue
+            if dimension is None:
+                dimension = d
+            elif d != dimension:
+                # Mixed dimensions should not happen within one tree; skip oddities.
+                continue
+            self.leaves.append(leaf)
+            v0_list.append(np.asarray(leaf.vertices[0], dtype=np.float64))
+            a_inv_list.append(np.asarray(leaf.A_inv, dtype=np.float64))
+            vidx_list.append(np.asarray(leaf.vertex_indices, dtype=np.int64))
+
+        self.n_leaves = len(self.leaves)
+        self.dimension = dimension or 0
+
+        if self.n_leaves == 0:
+            self.leaf_vertex_indices = None
+            self._V0 = None
+            self._A_inv = None
+            self._built = True
+            return
+
+        self.leaf_vertex_indices = np.stack(vidx_list, axis=0)  # (L, d+1)
+        self._V0 = torch.as_tensor(np.stack(v0_list, axis=0),
+                                   dtype=self.dtype, device=self.device)   # (L, d)
+        self._A_inv = torch.as_tensor(np.stack(a_inv_list, axis=0),
+                                      dtype=self.dtype, device=self.device)  # (L, d, d)
+        self._built = True
+
+    def _chunk_size(self) -> int:
+        per_point = max(self.n_leaves * max(self.dimension, 1), 1)
+        return max(1, self.element_budget // per_point)
+
+    def embed(self, points: np.ndarray):
+        """Embed a batch of points against every stacked leaf.
+
+        Args:
+            points: Array of shape ``(m, d)``.
+
+        Returns:
+            Tuple ``(leaf_index, found, alphas)`` where:
+              * ``leaf_index`` (m,) int array indexes into ``self.leaves`` / rows of
+                ``self.leaf_vertex_indices`` (``-1`` when unresolved),
+              * ``found`` (m,) bool array marks GPU-resolved points,
+              * ``alphas`` (m, d+1) float array holds the barycentric coordinates
+                for the chosen leaf (rows for unresolved points are meaningless).
+        """
+        points = np.asarray(points, dtype=np.float64)
+        if points.ndim == 1:
+            points = points.reshape(1, -1)
+        m = points.shape[0]
+
+        leaf_index = np.full(m, -1, dtype=np.int64)
+        found = np.zeros(m, dtype=bool)
+        alphas_out = np.zeros((m, self.dimension + 1), dtype=np.float64)
+
+        if not self.is_built:
+            return leaf_index, found, alphas_out
+
+        tol = self.tolerance
+        chunk = self._chunk_size()
+        P_all = torch.as_tensor(points, dtype=self.dtype, device=self.device)
+
+        for start in range(0, m, chunk):
+            end = min(start + chunk, m)
+            P = P_all[start:end]                                   # (c, d)
+            b = P[:, None, :] - self._V0[None, :, :]               # (c, L, d)
+            alpha_r = torch.einsum("lij,clj->cli", self._A_inv, b)  # (c, L, d)
+            alpha0 = 1.0 - alpha_r.sum(dim=-1)                     # (c, L)
+            alphas = torch.cat([alpha0[..., None], alpha_r], dim=-1)  # (c, L, d+1)
+
+            inside = (alphas >= -tol).all(dim=-1)                  # (c, L)
+            min_alpha = alphas.amin(dim=-1)                        # (c, L)
+            neg_inf = torch.full_like(min_alpha, float("-inf"))
+            scored = torch.where(inside, min_alpha, neg_inf)       # (c, L)
+
+            best_val, best_leaf = scored.max(dim=1)                # (c,), (c,)
+            chunk_found = torch.isfinite(best_val)                 # (c,)
+
+            rows = torch.arange(end - start, device=self.device)
+            best_alphas = alphas[rows, best_leaf]                  # (c, d+1)
+
+            cf = chunk_found.cpu().numpy()
+            bl = best_leaf.cpu().numpy()
+            ba = best_alphas.cpu().numpy()
+
+            sl = slice(start, end)
+            found[sl] = cf
+            leaf_index[sl] = np.where(cf, bl, -1)
+            alphas_out[sl] = ba
+
+        return leaf_index, found, alphas_out