simplex-tree-classifier 0.1.0__py3-none-any.whl

simplex_tree_classifier/convexity.py

@@ -0,0 +1,237 @@
+"""Geometry helpers to test whether the decision boundary between two adjacent
+simplices bends in a convex or non-convex way.
+
+The idea: two adjacent boundary-crossing simplices share a face. The linear
+boundary crosses that shared face at a "meeting point" and exits each simplex at
+an "external crossing". Sampling test points a fraction ``epsilon`` of the way
+toward each external crossing and checking which side of the hyperplane their
+average lands on tells us whether the boundary is locally convex.
+"""
+
+import numpy as np
+
+from .plane_equation import PlaneEquation
+
+
+def _ensure_dense_weights(weights):
+    """Convert sparse matrix to dense array if needed (OneClassSVM returns sparse)."""
+    if hasattr(weights, 'toarray'):
+        return weights.toarray().flatten()
+    elif hasattr(weights, 'A'):
+        return np.asarray(weights).flatten()
+    return weights
+
+
+def get_shared_vertices(simplex1_node, simplex2_node):
+    set1 = set(tuple(v) for v in simplex1_node.vertices)
+    set2 = set(tuple(v) for v in simplex2_node.vertices)
+    shared_tuples = set1.intersection(set2)
+    return [np.array(v) for v in shared_tuples]
+
+
+def shared_face_length(simplex1_node, simplex2_node):
+    """Longest edge of the shared face between two adjacent simplices."""
+    shared = get_shared_vertices(simplex1_node, simplex2_node)
+    if len(shared) < 2:
+        return None
+    return max(np.linalg.norm(shared[i] - shared[j])
+               for i in range(len(shared))
+               for j in range(i + 1, len(shared)))
+
+
+def find_crossing_on_edge(line_coeffs, point_a, point_b):
+    w = line_coeffs[:-1]
+    b = line_coeffs[-1]
+
+    val_a = np.dot(w, point_a) + b
+    val_b = np.dot(w, point_b) + b
+
+    if abs(val_a - val_b) < 1e-10:
+        return None
+
+    t = val_a / (val_a - val_b)
+    if t < 0 or t > 1:
+        return None
+
+    return point_a + t * (point_b - point_a)
+
+
+def find_crossing_on_shared_face(shared_vertices, line_coeffs):
+    for i in range(len(shared_vertices)):
+        for j in range(i + 1, len(shared_vertices)):
+            point_a = np.array(shared_vertices[i])
+            point_b = np.array(shared_vertices[j])
+            crossing = find_crossing_on_edge(line_coeffs, point_a, point_b)
+            if crossing is not None:
+                return crossing
+    return None
+
+
+def find_svm_meeting_point(simplex1_node, simplex2_node, weights, intercept):
+    shared_vertices = get_shared_vertices(simplex1_node, simplex2_node)
+
+    if len(shared_vertices) < 2:
+        return None
+
+    svm_plane1 = PlaneEquation(simplex1_node)
+    line_coeffs1 = svm_plane1.compute_plane_from_weights(weights, intercept)
+
+    meeting_point = find_crossing_on_shared_face(shared_vertices, line_coeffs1)
+
+    return meeting_point
+
+
+def find_external_crossing(simplex_node, line_coeffs, shared_vertices):
+    vertices = [np.array(v) for v in simplex_node.vertices]
+    shared_set = set(tuple(v) for v in shared_vertices)
+
+    for i in range(len(vertices)):
+        for j in range(i + 1, len(vertices)):
+            vi_shared = tuple(vertices[i]) in shared_set
+            vj_shared = tuple(vertices[j]) in shared_set
+
+            if vi_shared and vj_shared:
+                continue
+
+            crossing = find_crossing_on_edge(line_coeffs, vertices[i], vertices[j])
+            if crossing is not None:
+                return crossing
+
+    return None
+
+
+def find_epsilon_points(simplex1_node, simplex2_node, weights, intercept, epsilon):
+    """Find test points along the decision boundary for convexity checking.
+
+    Args:
+        simplex1_node: First adjacent simplex
+        simplex2_node: Second adjacent simplex
+        weights: Hyperplane weights
+        intercept: Hyperplane intercept
+        epsilon: Fraction (0-1) of distance from meeting point to external crossing.
+
+    Returns:
+        ``(meeting_point, point1, point2)``.
+    """
+    shared_vertices = get_shared_vertices(simplex1_node, simplex2_node)
+
+    if len(shared_vertices) < 2:
+        return None, None, None
+
+    svm_plane1 = PlaneEquation(simplex1_node)
+    svm_plane2 = PlaneEquation(simplex2_node)
+
+    line_coeffs1 = svm_plane1.compute_plane_from_weights(weights, intercept)
+    line_coeffs2 = svm_plane2.compute_plane_from_weights(weights, intercept)
+
+    meeting_point = find_crossing_on_shared_face(shared_vertices, line_coeffs1)
+
+    if meeting_point is None:
+        return None, None, None
+
+    external1 = find_external_crossing(simplex1_node, line_coeffs1, shared_vertices)
+    external2 = find_external_crossing(simplex2_node, line_coeffs2, shared_vertices)
+
+    if external1 is None or external2 is None:
+        return meeting_point, None, None
+
+    dir1 = external1 - meeting_point
+    dir2 = external2 - meeting_point
+
+    norm1 = np.linalg.norm(dir1)
+    norm2 = np.linalg.norm(dir2)
+
+    if norm1 < 1e-10 or norm2 < 1e-10:
+        return meeting_point, None, None
+
+    point1 = meeting_point + epsilon * dir1
+    point2 = meeting_point + epsilon * dir2
+
+    return meeting_point, point1, point2
+
+
+def find_average_point(simplex1_node, simplex2_node, weights, intercept, epsilon):
+    meeting_point, point1, point2 = find_epsilon_points(
+        simplex1_node, simplex2_node, weights, intercept, epsilon
+    )
+
+    if meeting_point is None or point1 is None or point2 is None:
+        return None, meeting_point, point1, point2
+
+    average_point = (meeting_point + point1 + point2) / 3
+
+    return average_point, meeting_point, point1, point2
+
+
+def meeting_to_average_distance(simplex1_node, simplex2_node, weights, intercept, epsilon):
+    """Distance from the shared-face meeting point to the average test point.
+
+    Returns ``(distance, average_point, meeting_point, point1, point2)`` where
+    ``distance`` is ``None`` when the geometry could not be resolved.
+    """
+    average_point, meeting, pt1, pt2 = find_average_point(
+        simplex1_node, simplex2_node, weights, intercept, epsilon
+    )
+    if average_point is None or meeting is None:
+        return None, average_point, meeting, pt1, pt2
+    distance = float(np.linalg.norm(np.asarray(average_point) - np.asarray(meeting)))
+    return distance, average_point, meeting, pt1, pt2
+
+
+def is_point_in_red_area(point, containing_simplex, weights, intercept):
+    barycentric = containing_simplex._embed_point(tuple(point))
+    if barycentric is None:
+        return None
+
+    weights = _ensure_dense_weights(weights)
+    vertex_decisions = [weights[idx] + intercept for idx in containing_simplex.vertex_indices]
+
+    decision_value = np.dot(vertex_decisions, barycentric)
+
+    return decision_value >= 0
+
+
+def check_convexity(simplex1_node, simplex2_node, weights, intercept,
+                    global_tree=None, epsilon=0.3):
+    """Check if the boundary between two adjacent simplices is convex.
+
+    Creates test points along the boundary and checks if the average point falls
+    on the expected side of the hyperplane.
+
+    Args:
+        simplex1_node: First adjacent simplex
+        simplex2_node: Second adjacent simplex
+        weights: Hyperplane weights
+        intercept: Hyperplane intercept
+        global_tree: Optional tree to search for the containing simplex if the
+            average point falls outside both input simplices
+        epsilon: Fraction (0-1) of distance from meeting point to external crossing.
+
+    Returns:
+        ``(is_convex, average_point, meeting, pt1, pt2)``.
+    """
+    average_point, meeting, pt1, pt2 = find_average_point(
+        simplex1_node, simplex2_node, weights, intercept, epsilon
+    )
+
+    if average_point is None:
+        return True, None, meeting, pt1, pt2
+
+    containing_simplex = None
+
+    if simplex1_node._point_inside_simplex(tuple(average_point)):
+        containing_simplex = simplex1_node
+    elif simplex2_node._point_inside_simplex(tuple(average_point)):
+        containing_simplex = simplex2_node
+    elif global_tree is not None:
+        containing_simplex = global_tree.find_containing_simplex(tuple(average_point))
+
+    if containing_simplex is None:
+        return True, average_point, meeting, pt1, pt2
+
+    in_red = is_point_in_red_area(average_point, containing_simplex, weights, intercept)
+
+    if in_red is None:
+        return True, average_point, meeting, pt1, pt2
+
+    return in_red, average_point, meeting, pt1, pt2

simplex_tree_classifier/plane_equation.py

@@ -0,0 +1,65 @@
+"""Recover the linear decision boundary inside a single simplex.
+
+Given a linear classifier's per-vertex weights, ``PlaneEquation`` turns them
+into the hyperplane (in the original feature space) where the decision function
+is zero within one simplex. Used by the convexity checks.
+"""
+
+import numpy as np
+
+from .simplex import Simplex
+
+
+class PlaneEquation:
+    def __init__(self, simplex: Simplex):
+        self.simplex = simplex
+        self.plane_coefficients = None
+        self.normalized_coefficients = None
+
+    def compute_plane_from_weights(self, weight_vector: np.ndarray,
+                                   intercept: float = 0.0) -> np.ndarray:
+        # Convert sparse matrix to dense array if needed (OneClassSVM returns sparse).
+        if hasattr(weight_vector, 'toarray'):
+            weight_vector = weight_vector.toarray().flatten()
+        elif hasattr(weight_vector, 'A'):
+            weight_vector = np.asarray(weight_vector).flatten()
+        simplex_weights = np.asarray(weight_vector)[self.simplex.vertex_indices]
+        plane_eq = self.simplex.A_inv.T @ (simplex_weights[1:] - simplex_weights[0])
+        constant = (simplex_weights[0] + intercept) - plane_eq @ self.simplex.vertices[0]
+        self.plane_coefficients = np.append(plane_eq, constant)
+        return self.plane_coefficients
+
+    def get_cartesian_form(self) -> str:
+        if self.plane_coefficients is None:
+            raise ValueError(
+                "Plane equation not computed yet. Call compute_plane_from_weights first."
+            )
+
+        coeffs = self.plane_coefficients
+        var_names = [f"x{i+1}" for i in range(len(coeffs) - 1)]
+        constant = coeffs[-1]
+
+        equation_parts = []
+        for coeff, var in zip(coeffs[:-1], var_names):
+            if abs(coeff) < 1e-10:
+                continue
+            if coeff == 1.0:
+                term = var
+            elif coeff == -1.0:
+                term = f"-{var}"
+            else:
+                term = f"{coeff:.4f}{var}"
+
+            if equation_parts and coeff > 0:
+                equation_parts.append("+")
+            equation_parts.append(term)
+
+        if abs(constant) > 1e-10:
+            if constant > 0 and equation_parts:
+                equation_parts.append("+")
+            equation_parts.append(f"{constant:.4f}")
+
+        if not equation_parts:
+            return "0 = 0"
+
+        return " ".join(equation_parts) + " = 0"

simplex_tree_classifier/simplex.py

@@ -0,0 +1,156 @@
+"""N-dimensional simplex with barycentric-coordinate embedding.
+
+A ``Simplex`` is defined by ``d + 1`` (or more) vertices in ``d``-dimensional
+space. It knows how to embed an arbitrary point into barycentric coordinates
+and to test whether a point lies inside it. The math here is dimension-agnostic
+and unchanged from the original research implementation.
+"""
+
+import numpy as np
+from typing import List, Tuple, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .vertex_registry import VertexRegistry
+
+
+class Simplex:
+    def __init__(self, vertex_indices: List[int], registry: "VertexRegistry",
+                 tolerance: float = 1e-10):
+        if len(vertex_indices) < 2:
+            raise ValueError("Simplex must have at least 2 vertices")
+
+        self.vertex_indices = vertex_indices
+        self.registry = registry
+        self.n_vertices = len(vertex_indices)
+        self.tolerance = tolerance
+
+        first_vertex = self.registry._get_vertex(vertex_indices[0])
+        self.dimension = len(first_vertex)
+
+        for idx in vertex_indices:
+            v = self.registry._get_vertex(idx)
+            if len(v) != self.dimension:
+                raise ValueError("All vertices must have the same dimension")
+
+        if self.n_vertices < self.dimension + 1:
+            raise ValueError(
+                f"For {self.dimension}D space, need at least "
+                f"{self.dimension + 1} vertices, got {self.n_vertices}"
+            )
+
+        self._build_transformation_matrix()
+
+    @property
+    def vertices(self) -> List[np.ndarray]:
+        """Returns list of vertex coordinates as numpy arrays."""
+        return self.registry._get_vertices(self.vertex_indices)
+
+    def _build_transformation_matrix(self):
+        vertices = self.vertices
+        v0 = vertices[0]
+
+        if self.n_vertices == self.dimension + 1:
+            self.A = np.column_stack([v - v0 for v in vertices[1:]])
+            self.det_A = np.linalg.det(self.A)
+            self.is_degenerate = abs(self.det_A) < self.tolerance
+            if not self.is_degenerate:
+                self.A_inv = np.linalg.inv(self.A)
+            else:
+                self.A_inv = None
+        else:
+            edge_vectors = np.array([v - v0 for v in vertices[1:]])
+            self.A = edge_vectors.T
+
+            try:
+                self.A_pseudo_inv = np.linalg.pinv(self.A)
+                self.is_degenerate = False
+                self.det_A = 1.0
+            except np.linalg.LinAlgError:
+                self.is_degenerate = True
+                self.A_pseudo_inv = None
+                self.det_A = 0.0
+
+    def _embed_point(self, point: Tuple[float, ...]) -> Optional[Tuple[float, ...]]:
+        if self.is_degenerate:
+            return None
+        P = np.array(point)
+        if len(P) != self.dimension:
+            raise ValueError(
+                f"Point dimension {len(P)} doesn't match simplex "
+                f"dimension {self.dimension}"
+            )
+
+        vertices = self.vertices
+
+        if self.n_vertices == self.dimension + 1:
+            v0 = vertices[0]
+            b = P - v0
+            alpha_rest = self.A_inv @ b
+            alpha_0 = 1 - np.sum(alpha_rest)
+            embeddings = tuple([float(alpha_0)] + [float(x) for x in alpha_rest])
+        else:
+            from itertools import combinations
+            required_vertices = self.dimension + 1
+
+            best_simplex = None
+            best_coords = None
+            best_indices = None
+
+            for local_indices in combinations(range(self.n_vertices), required_vertices):
+                sub_vertex_indices = [self.vertex_indices[i] for i in local_indices]
+
+                try:
+                    temp_simplex = Simplex(sub_vertex_indices, self.registry, self.tolerance)
+
+                    if temp_simplex._point_inside_simplex(tuple(P)):
+                        coords = temp_simplex._embed_point(tuple(P))
+                        if coords is not None and all(c >= -self.tolerance for c in coords):
+                            min_coord = min(coords)
+                            if best_simplex is None or min_coord > best_simplex:
+                                best_simplex = min_coord
+                                best_coords = coords
+                                best_indices = local_indices
+                except (ValueError, np.linalg.LinAlgError):
+                    continue
+
+            if best_coords is not None:
+                sparse_coords = [0.0] * self.n_vertices
+                for i, local_idx in enumerate(best_indices):
+                    sparse_coords[local_idx] = best_coords[i]
+                embeddings = tuple(sparse_coords)
+            else:
+                vertex_matrix = np.array(vertices).T
+                constraint_matrix = np.vstack([vertex_matrix, np.ones(self.n_vertices)])
+                constraint_vector = np.append(P, 1.0)
+
+                try:
+                    weights = np.linalg.lstsq(constraint_matrix, constraint_vector, rcond=None)[0]
+                    embeddings = tuple(float(w) for w in weights)
+                except np.linalg.LinAlgError:
+                    return None
+        return embeddings
+
+    def _point_inside_simplex(self, point) -> bool:
+        coords = self._embed_point(point)
+        if coords is None:
+            return False
+
+        if not all(0 <= alpha <= 1 for alpha in coords):
+            return False
+
+        if abs(sum(coords) - 1.0) > self.tolerance:
+            return False
+
+        return True
+
+    def contains_point(self, point) -> bool:
+        """Public predicate: True if ``point`` lies inside this simplex."""
+        return self._point_inside_simplex(point)
+
+    def get_vertices_as_tuples(self) -> List[Tuple[float, ...]]:
+        """Returns list of vertex coordinates as tuples for easy iteration/display."""
+        return self.registry.get_vertices_as_tuples(self.vertex_indices)
+
+    def __repr__(self):
+        return (f"Simplex(vertex_indices={self.vertex_indices}, "
+                f"dim={self.dimension}, degenerate={self.is_degenerate})")