opforch 2.0.0__py3-none-any.whl

opforch/__init__.py

@@ -0,0 +1,7 @@
+"""OPForch: PyTorch-Inspired Optimum-Path Forest Classifier.
+
+This library provides GPU-accelerated OPF classifiers
+using PyTorch tensors as the universal data representation.
+"""
+
+__version__ = "2.0.0"

opforch/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core structures for OPForch implementations."""
+
+from opforch.core.heap import Heap
+from opforch.core.subgraph import Subgraph
+from opforch.core.opf import OPF

opforch/core/heap.py

@@ -0,0 +1,200 @@
+"""Tensor-backed Heap for the Optimum-Path Forest.
+
+A binary heap (priority queue) supporting min and max policies.
+Internal state is stored as tensors for consistency with the
+rest of OPForch, though heap operations remain sequential.
+"""
+
+from typing import Optional
+
+import torch
+
+import opforch.utils.constants as c
+from opforch.utils.device import DeviceManager
+
+
+class Heap:
+    """A binary heap with tensor-backed storage."""
+
+    def __init__(
+        self,
+        size: int = 1,
+        policy: str = "min",
+        device: Optional[str] = None,
+    ) -> None:
+        """Initialization method.
+
+        Args:
+            size: Maximum size of the heap.
+            policy: Heap's policy ('min' or 'max').
+            device: Target device string.
+
+        """
+
+        if size < 1:
+            raise builtins.ValueError("`size` should be > 0")
+        if policy not in ("min", "max"):
+            raise builtins.ValueError("`policy` should be 'min' or 'max'")
+
+        self.size = size
+        self.policy = policy
+        self.device = DeviceManager.resolve(device)
+
+        self.cost = torch.full(
+            (size,), c.FLOAT_MAX, dtype=torch.float64, device=self.device
+        )
+        self.color = torch.full(
+            (size,), c.WHITE, dtype=torch.int8, device=self.device
+        )
+        self.p = torch.full(
+            (size,), -1, dtype=torch.int64, device=self.device
+        )
+        self.pos = torch.full(
+            (size,), -1, dtype=torch.int64, device=self.device
+        )
+        self.last = -1
+
+    def is_full(self) -> bool:
+        """Checks if the heap is full."""
+
+        return self.last == (self.size - 1)
+
+    def is_empty(self) -> bool:
+        """Checks if the heap is empty."""
+
+        return self.last == -1
+
+    def dad(self, i: int) -> int:
+        """Returns the position of the node's parent."""
+
+        return (i - 1) // 2
+
+    def left_son(self, i: int) -> int:
+        """Returns the position of the node's left child."""
+
+        return 2 * i + 1
+
+    def right_son(self, i: int) -> int:
+        """Returns the position of the node's right child."""
+
+        return 2 * i + 2
+
+    def go_up(self, i: int) -> None:
+        """Sifts a node up to maintain heap property.
+
+        Args:
+            i: Position to sift up from.
+
+        """
+
+        j = self.dad(i)
+
+        if self.policy == "min":
+            while i > 0 and self.cost[self.p[j]] > self.cost[self.p[i]]:
+                self.p[j], self.p[i] = self.p[i].clone(), self.p[j].clone()
+                self.pos[self.p[i]] = i
+                self.pos[self.p[j]] = j
+                i = j
+                j = self.dad(i)
+        else:
+            while i > 0 and self.cost[self.p[j]] < self.cost[self.p[i]]:
+                self.p[j], self.p[i] = self.p[i].clone(), self.p[j].clone()
+                self.pos[self.p[i]] = i
+                self.pos[self.p[j]] = j
+                i = j
+                j = self.dad(i)
+
+    def go_down(self, i: int) -> None:
+        """Sifts a node down to maintain heap property.
+
+        Args:
+            i: Position to sift down from.
+
+        """
+
+        left = self.left_son(i)
+        right = self.right_son(i)
+        j = i
+
+        if self.policy == "min":
+            if left <= self.last and self.cost[self.p[left]] < self.cost[self.p[i]]:
+                j = left
+            if right <= self.last and self.cost[self.p[right]] < self.cost[self.p[j]]:
+                j = right
+        else:
+            if left <= self.last and self.cost[self.p[left]] > self.cost[self.p[i]]:
+                j = left
+            if right <= self.last and self.cost[self.p[right]] > self.cost[self.p[j]]:
+                j = right
+
+        if j != i:
+            self.p[j], self.p[i] = self.p[i].clone(), self.p[j].clone()
+            self.pos[self.p[i]] = i
+            self.pos[self.p[j]] = j
+            self.go_down(j)
+
+    def insert(self, p: int) -> bool:
+        """Inserts a new node into the heap.
+
+        Args:
+            p: Node index to insert.
+
+        Returns:
+            True if insertion succeeded, False if heap is full.
+
+        """
+
+        if not self.is_full():
+            self.last += 1
+            self.p[self.last] = p
+            self.color[p] = c.GRAY
+            self.pos[p] = self.last
+            self.go_up(self.last)
+            return True
+
+        return False
+
+    def remove(self) -> int:
+        """Removes and returns the root node from the heap.
+
+        Returns:
+            The removed node index, or -1 if heap is empty.
+
+        """
+
+        if not self.is_empty():
+            p = self.p[0].item()
+
+            self.pos[p] = -1
+            self.color[p] = c.BLACK
+
+            self.p[0] = self.p[self.last]
+            self.pos[self.p[0]] = 0
+            self.p[self.last] = -1
+
+            self.last -= 1
+
+            self.go_down(0)
+
+            return p
+
+        return -1
+
+    def update(self, p: int, cost: float) -> None:
+        """Updates a node's cost and adjusts its position.
+
+        Args:
+            p: Node index.
+            cost: New cost value.
+
+        """
+
+        self.cost[p] = cost
+
+        if self.color[p] == c.BLACK:
+            pass
+
+        if self.color[p] == c.WHITE:
+            self.insert(p)
+        else:
+            self.go_up(self.pos[p].item())

opforch/core/opf.py

@@ -0,0 +1,213 @@
+"""Optimum-Path Forest abstract base classifier."""
+
+import pickle
+from typing import List, Optional
+
+import torch
+
+import opforch.math.distance as d
+import opforch.utils.exception as e
+from opforch.core.subgraph import Subgraph
+from opforch.utils import logging
+from opforch.utils.device import DeviceManager
+
+logger = logging.get_logger(__name__)
+
+
+class OPF:
+    """Abstract base class defining all common OPF-related methods.
+
+    References:
+        J. P. Papa, A. X. Falcão and C. T. N. Suzuki.
+        LibOPF: A library for the design of optimum-path forest classifiers (2015).
+
+    """
+
+    def __init__(
+        self,
+        distance: str = "log_squared_euclidean",
+        pre_computed_distance: Optional[str] = None,
+        device: Optional[str] = None,
+    ) -> None:
+        """Initialization method.
+
+        Args:
+            distance: Name of the distance metric to use.
+            pre_computed_distance: Path to a pre-computed distance file.
+            device: Target device string ('cpu', 'cuda', 'cuda:0', etc.).
+
+        """
+
+        logger.info("Creating class: OPF.")
+
+        self.device = DeviceManager.resolve(device)
+
+        self.subgraph = None
+
+        if distance not in d.VALID_DISTANCES:
+            raise e.TypeError(
+                f"`distance` should be one of: {', '.join(sorted(d.VALID_DISTANCES))}"
+            )
+
+        self.distance = distance
+        self.distance_fn = d.DISTANCES[distance]
+
+        if pre_computed_distance:
+            self.pre_computed_distance = True
+            self._read_distances(pre_computed_distance)
+        else:
+            self.pre_computed_distance = False
+            self.pre_distances = None
+
+        logger.debug(
+            "Distance: %s | Pre-computed distance: %s | Device: %s.",
+            self.distance,
+            self.pre_computed_distance,
+            self.device,
+        )
+        logger.info("Class created.")
+
+    def _read_distances(self, file_name: str) -> None:
+        """Reads pre-computed distances from a file.
+
+        Args:
+            file_name: Path to the distance file (.csv, .txt, or .pt).
+
+        """
+
+        logger.debug("Running private method: read_distances().")
+
+        extension = file_name.split(".")[-1]
+
+        if extension in ("pt", "pth"):
+            distances = torch.load(file_name, map_location=self.device)
+        elif extension == "csv":
+            import numpy as np
+
+            data = np.loadtxt(file_name, delimiter=",")
+            distances = torch.from_numpy(data).to(
+                dtype=torch.float64, device=self.device
+            )
+        elif extension == "txt":
+            import numpy as np
+
+            data = np.loadtxt(file_name, delimiter=" ")
+            distances = torch.from_numpy(data).to(
+                dtype=torch.float64, device=self.device
+            )
+        else:
+            raise e.ArgumentError(
+                "File extension not recognized. "
+                "It should be `.csv`, `.txt`, `.pt` or `.pth`"
+            )
+
+        if distances is None:
+            raise e.ValueError(
+                "Pre-computed distances could not be properly loaded"
+            )
+
+        self.pre_distances = distances
+
+    def get_distances(self, normalize: bool = False) -> torch.Tensor:
+        """Computes the full distance matrix for the training subgraph.
+
+        Args:
+            normalize: Whether to min-max normalize the matrix.
+
+        Returns:
+            Distance matrix of shape (N, N).
+
+        """
+
+        distances = self.distance_fn(
+            self.subgraph.features, self.subgraph.features
+        )
+
+        if normalize:
+            d_min = distances.min()
+            d_max = distances.max()
+            return (distances - d_min) / (d_max - d_min)
+
+        return distances
+
+    def to(self, device) -> "OPF":
+        """Moves the entire model to a device.
+
+        Args:
+            device: Target device string or torch.device.
+
+        Returns:
+            Self, for chaining.
+
+        """
+
+        self.device = (
+            torch.device(device) if isinstance(device, str) else device
+        )
+
+        if self.subgraph is not None:
+            self.subgraph.to(self.device)
+
+        if self.pre_distances is not None:
+            self.pre_distances = self.pre_distances.to(self.device)
+
+        return self
+
+    def save(self, file_name: str) -> None:
+        """Saves the model using torch.save.
+
+        Args:
+            file_name: File path to save to.
+
+        """
+
+        logger.info("Saving model to file: %s ...", file_name)
+
+        # Move to CPU before saving for portability
+        cpu_model = self.to("cpu")
+        torch.save(cpu_model, file_name)
+
+        logger.info("Model saved.")
+
+    def load(self, file_name: str) -> None:
+        """Loads a model from a file.
+
+        Args:
+            file_name: File path to load from.
+
+        """
+
+        logger.info("Loading model from file: %s ...", file_name)
+
+        loaded = torch.load(file_name, map_location=self.device, weights_only=False)
+        self.__dict__.update(loaded.__dict__)
+
+        logger.info("Model loaded.")
+
+    def fit(self, X: torch.Tensor, Y: torch.Tensor, **kwargs) -> None:
+        """Fits data in the classifier.
+
+        Must be implemented by subclasses.
+
+        Args:
+            X: Feature tensor of shape (N, D).
+            Y: Label tensor of shape (N,).
+
+        """
+
+        raise NotImplementedError
+
+    def predict(self, X: torch.Tensor, **kwargs) -> List[int]:
+        """Predicts new data using the pre-trained classifier.
+
+        Must be implemented by subclasses.
+
+        Args:
+            X: Feature tensor of shape (M, D).
+
+        Returns:
+            A list of predicted labels.
+
+        """
+
+        raise NotImplementedError

opforch/core/subgraph.py

@@ -0,0 +1,238 @@
+"""Tensor-first Subgraph for the Optimum-Path Forest.
+
+Replaces the OPFython Node + Subgraph pair with dense tensors.
+All per-node state lives as columns in this class, enabling
+batch operations and seamless GPU transfer.
+"""
+
+from typing import Optional, Tuple
+
+import numpy as np
+import torch
+
+import opforch.stream.parser as p
+import opforch.utils.constants as c
+import opforch.utils.exception as e
+from opforch.stream import loader
+from opforch.utils import logging
+from opforch.utils.device import DeviceManager
+
+logger = logging.get_logger(__name__)
+
+
+class Subgraph:
+    """A tensor-based collection of nodes forming the OPF subgraph.
+
+    All per-node attributes are stored as dense 1-D or 2-D tensors,
+    enabling vectorized operations and device transfer.
+    """
+
+    def __init__(
+        self,
+        X: Optional[torch.Tensor] = None,
+        Y: Optional[torch.Tensor] = None,
+        I: Optional[torch.Tensor] = None,
+        from_file: Optional[str] = None,
+        device: Optional[str] = None,
+    ) -> None:
+        """Initialization method.
+
+        Args:
+            X: Feature array/tensor of shape (N, D).
+            Y: Label array/tensor of shape (N,).
+            I: Index array/tensor of shape (N,).
+            from_file: Path to load data from (.csv, .txt, or .json).
+            device: Target device string (e.g. 'cpu', 'cuda').
+
+        """
+
+        self.device = DeviceManager.resolve(device)
+        self.trained = False
+
+        if from_file:
+            X, Y = self._load(from_file)
+
+        if X is not None:
+            self._build(X, Y, I)
+        else:
+            # Empty subgraph — tensors will be initialized later
+            self.features = torch.empty(0, device=self.device)
+            self.labels = torch.empty(0, dtype=torch.int64, device=self.device)
+            self._n_features = 0
+            self._init_state_tensors(0)
+            logger.error("Subgraph has not been properly created.")
+
+    def _to_tensor(self, arr, dtype=torch.float32) -> torch.Tensor:
+        """Converts numpy arrays, lists, or existing tensors to the target device."""
+
+        if arr is None:
+            return None
+
+        if isinstance(arr, np.ndarray):
+            t = torch.from_numpy(arr)
+        elif isinstance(arr, torch.Tensor):
+            t = arr
+        else:
+            t = torch.tensor(arr)
+
+        return t.to(dtype=dtype, device=self.device)
+
+    def _load(self, file_path: str) -> Tuple[torch.Tensor, torch.Tensor]:
+        """Loads and parses a dataframe from a file.
+
+        Args:
+            file_path: File to be loaded.
+
+        Returns:
+            Tuple of (features, labels) tensors.
+
+        """
+
+        extension = file_path.split(".")[-1]
+
+        if extension == "csv":
+            data = loader.load_csv(file_path)
+        elif extension == "txt":
+            data = loader.load_txt(file_path)
+        elif extension == "json":
+            data = loader.load_json(file_path)
+        else:
+            raise e.ArgumentError(
+                "File extension not recognized. It should be `.csv`, `.json` or `.txt`"
+            )
+
+        X, Y = p.parse_loader(data)
+
+        return X, Y
+
+    def _init_state_tensors(self, n: int) -> None:
+        """Initializes all per-node state tensors to default values.
+
+        Args:
+            n: Number of nodes.
+
+        """
+
+        dev = self.device
+
+        self.pred_labels = torch.zeros(n, dtype=torch.int64, device=dev)
+        self.cluster_labels = torch.zeros(n, dtype=torch.int64, device=dev)
+        self.costs = torch.zeros(n, dtype=torch.float64, device=dev)
+        self.densities = torch.zeros(n, dtype=torch.float64, device=dev)
+        self.radii = torch.zeros(n, dtype=torch.float64, device=dev)
+        self.n_plateaus = torch.zeros(n, dtype=torch.int64, device=dev)
+        self.preds = torch.full((n,), c.NIL, dtype=torch.int64, device=dev)
+        self.roots = torch.arange(n, dtype=torch.int64, device=dev)
+        self.status = torch.full((n,), c.STANDARD, dtype=torch.int8, device=dev)
+        self.relevant = torch.full((n,), c.IRRELEVANT, dtype=torch.int8, device=dev)
+
+        # Ordered node indices (filled during training)
+        self.idx_nodes = []
+
+        # Adjacency (set by KNNSubgraph or during plateau expansion)
+        self.adjacency = None
+
+    def _build(
+        self,
+        X: torch.Tensor,
+        Y: Optional[torch.Tensor],
+        I: Optional[torch.Tensor],
+    ) -> None:
+        """Builds the subgraph from feature/label/index data.
+
+        Args:
+            X: Features of shape (N, D).
+            Y: Labels of shape (N,). Defaults to zeros if None.
+            I: Original indices of shape (N,). Defaults to 0..N-1 if None.
+
+        """
+
+        self.features = self._to_tensor(X, dtype=torch.float32)
+
+        n = self.features.shape[0]
+
+        if Y is not None:
+            self.labels = self._to_tensor(Y, dtype=torch.int64)
+        else:
+            self.labels = torch.zeros(n, dtype=torch.int64, device=self.device)
+
+        if I is not None:
+            self.indices = self._to_tensor(I, dtype=torch.int64)
+        else:
+            self.indices = torch.arange(n, dtype=torch.int64, device=self.device)
+
+        self._n_features = self.features.shape[1] if self.features.dim() > 1 else 0
+
+        self._init_state_tensors(n)
+
+    @property
+    def n_nodes(self) -> int:
+        """Number of nodes in the subgraph."""
+
+        return self.features.shape[0]
+
+    @property
+    def n_features(self) -> int:
+        """Dimensionality of the feature space."""
+
+        return self._n_features
+
+    def to(self, device) -> "Subgraph":
+        """Moves all tensors to the specified device.
+
+        Args:
+            device: Target torch device or string.
+
+        Returns:
+            Self, for chaining.
+
+        """
+
+        device = torch.device(device) if isinstance(device, str) else device
+        self.device = device
+
+        self.features = self.features.to(device)
+        self.labels = self.labels.to(device)
+        self.indices = self.indices.to(device)
+        self.pred_labels = self.pred_labels.to(device)
+        self.cluster_labels = self.cluster_labels.to(device)
+        self.costs = self.costs.to(device)
+        self.densities = self.densities.to(device)
+        self.radii = self.radii.to(device)
+        self.n_plateaus = self.n_plateaus.to(device)
+        self.preds = self.preds.to(device)
+        self.roots = self.roots.to(device)
+        self.status = self.status.to(device)
+        self.relevant = self.relevant.to(device)
+
+        if self.adjacency is not None:
+            self.adjacency = self.adjacency.to(device)
+
+        return self
+
+    def destroy_arcs(self) -> None:
+        """Destroys all adjacency arcs in the subgraph."""
+
+        self.n_plateaus.zero_()
+        self.adjacency = None
+
+    def mark_nodes(self, i: int) -> None:
+        """Marks a node and its entire predecessor chain as relevant.
+
+        Args:
+            i: Starting node index.
+
+        """
+
+        while self.preds[i].item() != c.NIL:
+            self.relevant[i] = c.RELEVANT
+            i = self.preds[i].item()
+
+        self.relevant[i] = c.RELEVANT
+
+    def reset(self) -> None:
+        """Resets predecessors, relevance flags, and arcs."""
+
+        self.preds.fill_(c.NIL)
+        self.relevant.fill_(c.IRRELEVANT)
+        self.destroy_arcs()

opforch/math/__init__.py

@@ -0,0 +1 @@
+"""Mathematical package for OPForch."""