relucent 0.2.1__tar.gz

relucent-0.2.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: relucent
+Version: 0.2.1
+Summary: Explore polyhedral complexes associated with the activation states of ReLU neural networks.
+Author: Blake B. Gaines
+License-Expression: AGPL-3.0-or-later
+Requires-Dist: pandas>=2.3
+Requires-Dist: gurobipy>=12.0
+Requires-Dist: networkx>=3.6
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: numpy>=2.4
+Requires-Dist: pillow>=12.1
+Requires-Dist: plotly>=6.3
+Requires-Dist: scikit-learn>=1.8
+Requires-Dist: scipy>=1.17
+Requires-Dist: tqdm>=4.67
+Requires-Dist: torch>=2.13 ; extra == 'cli'
+Requires-Dist: torchvision ; extra == 'cli'
+Requires-Dist: pyvis>=0.3 ; extra == 'cli'
+Requires-Dist: kaleido ; extra == 'cli'
+Requires-Python: >=3.13, <3.14
+Project-URL: Repository, https://github.com/bl-ake/relucent
+Project-URL: Documentation, https://bl-ake.github.io/relucent/
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+[![Usable](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml/badge.svg)](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml)
+[![Latest Release](https://img.shields.io/github/v/tag/bl-ake/relucent?label=Latest%20Release)](https://github.com/bl-ake/relucent/releases)
+
+# Relucent
+Explore polyhedral complexes associated with the activation states of ReLU neural networks
+
+## Environment Setup 
+1. Install Python 3.13
+2. Install [PyTorch >= 2.3.0](https://pytorch.org/get-started/locally/)
+3. Run `pip install relucent`
+
+## Getting Started
+To see if the installation has been successful, try plotting the complex of a randomly initialized network in 2 dimensions like this:
+```
+from relucent import Complex, get_mlp_model
+
+network = get_mlp_model(widths=[2, 10, 5, 1])
+cplx = Complex(network)
+cplx.bfs()
+fig = cplx.plot(bound=10000)
+fig.show()
+```
+
+The "NN" object returned by get_mlp_model inherits from torch.nn.Module, so you can train and manipulate it just like you're used to :)
+
+Given some input point, you could get a minimal H-representation of the polyhedron containing it like this:
+```
+import numpy as np
+
+input_point = np.random.random(network.input_shape)
+p = cplx.point2poly(input_point)
+print(p.halfspaces[p.shis, :])
+```
+
+You could also check the average number of faces of all polyhedrons with:
+```
+sum(len(p.shis) for p in cplx) / len(cplx)
+```
+Or, get the adjacency graph of top-dimensional cells in the complex as a [NetworkX Graph](https://networkx.org/documentation/stable/tutorial.html) with:
+```
+print(cplx.get_dual_graph())
+```
+
+View the documentation for this library at https://bl-ake.github.io/relucent/
+
+## Source Code Structure
+* [model.py](src/relucent/model.py): PyTorch Module that acts as an interface between the model and the rest of the code
+* [poly.py](src/relucent/poly.py): Class for calculations involving individual polyhedrons (e.g. computing boundaries, neighbors, volume)
+* [complex.py](src/relucent/complex.py): Class for calculations involving the polyhedral cplx (e.g. polyhedron search, connectivity graph calculation)
+* [convert_model.py](src/relucent/convert_model.py): Utilities for converting various PyTorch.nn layers to Linear layers
+* [bvs.py](src/relucent/bvs.py): Data structures for storing large numbers of sign vectors
+
+## Obtaining a Gurobi License
+Without a [license](https://support.gurobi.com/hc/en-us/articles/12872879801105-How-do-I-retrieve-and-set-up-a-Gurobi-license), Gurobi will only work with a limited feature set. This includes a limit on the number of decision variables in the models it can solve, which limits the size of the networks this code is able to analyze. There are multiple ways to install the software, but we recommend the following steps to those eligible for an academic license:
+1. Install the [Gurobi Python library](https://pypi.org/project/gurobipy/), for example using `pip install gurobipy`
+2. [Obtain a Gurobi license](https://support.gurobi.com/hc/en-us/articles/360040541251-How-do-I-obtain-a-free-academic-license) (Note: a WLS license will limit the number of concurrent sessions across multiple devices, which can result in slowdowns when using this library on different machines simultaneously.)
+3. In your Conda environment, run `grbgetkey` followed by your license key

relucent-0.2.1/README.md

@@ -0,0 +1,57 @@
+[![Usable](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml/badge.svg)](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml)
+[![Latest Release](https://img.shields.io/github/v/tag/bl-ake/relucent?label=Latest%20Release)](https://github.com/bl-ake/relucent/releases)
+
+# Relucent
+Explore polyhedral complexes associated with the activation states of ReLU neural networks
+
+## Environment Setup 
+1. Install Python 3.13
+2. Install [PyTorch >= 2.3.0](https://pytorch.org/get-started/locally/)
+3. Run `pip install relucent`
+
+## Getting Started
+To see if the installation has been successful, try plotting the complex of a randomly initialized network in 2 dimensions like this:
+```
+from relucent import Complex, get_mlp_model
+
+network = get_mlp_model(widths=[2, 10, 5, 1])
+cplx = Complex(network)
+cplx.bfs()
+fig = cplx.plot(bound=10000)
+fig.show()
+```
+
+The "NN" object returned by get_mlp_model inherits from torch.nn.Module, so you can train and manipulate it just like you're used to :)
+
+Given some input point, you could get a minimal H-representation of the polyhedron containing it like this:
+```
+import numpy as np
+
+input_point = np.random.random(network.input_shape)
+p = cplx.point2poly(input_point)
+print(p.halfspaces[p.shis, :])
+```
+
+You could also check the average number of faces of all polyhedrons with:
+```
+sum(len(p.shis) for p in cplx) / len(cplx)
+```
+Or, get the adjacency graph of top-dimensional cells in the complex as a [NetworkX Graph](https://networkx.org/documentation/stable/tutorial.html) with:
+```
+print(cplx.get_dual_graph())
+```
+
+View the documentation for this library at https://bl-ake.github.io/relucent/
+
+## Source Code Structure
+* [model.py](src/relucent/model.py): PyTorch Module that acts as an interface between the model and the rest of the code
+* [poly.py](src/relucent/poly.py): Class for calculations involving individual polyhedrons (e.g. computing boundaries, neighbors, volume)
+* [complex.py](src/relucent/complex.py): Class for calculations involving the polyhedral cplx (e.g. polyhedron search, connectivity graph calculation)
+* [convert_model.py](src/relucent/convert_model.py): Utilities for converting various PyTorch.nn layers to Linear layers
+* [bvs.py](src/relucent/bvs.py): Data structures for storing large numbers of sign vectors
+
+## Obtaining a Gurobi License
+Without a [license](https://support.gurobi.com/hc/en-us/articles/12872879801105-How-do-I-retrieve-and-set-up-a-Gurobi-license), Gurobi will only work with a limited feature set. This includes a limit on the number of decision variables in the models it can solve, which limits the size of the networks this code is able to analyze. There are multiple ways to install the software, but we recommend the following steps to those eligible for an academic license:
+1. Install the [Gurobi Python library](https://pypi.org/project/gurobipy/), for example using `pip install gurobipy`
+2. [Obtain a Gurobi license](https://support.gurobi.com/hc/en-us/articles/360040541251-How-do-I-obtain-a-free-academic-license) (Note: a WLS license will limit the number of concurrent sessions across multiple devices, which can result in slowdowns when using this library on different machines simultaneously.)
+3. In your Conda environment, run `grbgetkey` followed by your license key

relucent-0.2.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = [
+    "uv_build >= 0.9.5, <0.10.0",
+]
+build-backend = "uv_build"
+
+[project]
+name = "relucent"
+description = "Explore polyhedral complexes associated with the activation states of ReLU neural networks."
+version = "0.2.1"
+requires-python = ">= 3.13, <3.14"
+dependencies = [
+    "pandas>=2.3",
+    "gurobipy>=12.0",
+    "networkx>=3.6",
+    "matplotlib>=3.10",
+    "numpy>=2.4",
+    "Pillow>=12.1",
+    "plotly>=6.3",
+    "scikit_learn>=1.8",
+    "scipy>=1.17",
+    "tqdm>=4.67",
+]
+authors = [
+    { name = "Blake B. Gaines" },
+]
+license = "AGPL-3.0-or-later"
+readme = "README.md"
+
+[project.optional-dependencies]
+cli = [
+    "torch>=2.13",
+    "torchvision",
+    "pyvis>=0.3",
+    "kaleido",
+]
+
+[project.urls]
+Repository = "https://github.com/bl-ake/relucent"
+Documentation = "https://bl-ake.github.io/relucent/"

relucent-0.2.1/src/relucent/__init__.py

@@ -0,0 +1,18 @@
+try:
+    from torch import __version__
+    from torchvision import __version__  # noqa
+except ImportError:
+    raise ImportError(
+        "Relucent requires PyTorch to be installed manually. "
+        "Please install the version compatible with your system from: "
+        "https://pytorch.org/get-started/previous-versions/#:~:text=org/whl/cpu-,v2.3.0"
+    )
+
+from .bvs import BVManager
+from .complex import Complex
+from .poly import Polyhedron
+from .model import NN, get_mlp_model
+from .convert_model import convert
+from .utils import get_env, split_sequential, set_seeds
+
+__all__ = [Complex, Polyhedron, NN, get_mlp_model, BVManager, convert, get_env, split_sequential, set_seeds]

relucent-0.2.1/src/relucent/bvs.py

@@ -0,0 +1,257 @@
+from heapq import heappop, heappush
+
+from torch import Tensor
+
+from relucent.poly import encode_bv
+
+
+class BVManager:
+    """Manages storage and lookup of sign sequences.
+
+    This class provides a dictionary-like interface for storing and retrieving
+    sign sequences (arrays with values in {-1, 0, 1}). It maintains an index
+    mapping and allows efficient membership testing and retrieval.
+
+    Sign sequences are encoded as hashable tags for efficient storage and lookup.
+    """
+
+    def __init__(self):
+        self.index2bv = list()
+        self.tag2index = dict()  ## Tags are just hashable versions of bvs, should be unique
+        self._len = 0
+
+    def _get_tag(self, bv):
+        if isinstance(bv, Tensor):
+            bv = bv.detach().cpu().numpy()
+        return encode_bv(bv)
+
+    def add(self, bv):
+        """Add a sign sequence to the manager.
+
+        Args:
+            bv: A sign sequence as torch.Tensor or np.ndarray.
+        """
+        tag = self._get_tag(bv)
+        if tag not in self.tag2index:
+            self.tag2index[tag] = len(self.index2bv)
+            self.index2bv.append(bv)
+            self._len += 1
+
+    def __getitem__(self, bv):
+        tag = self._get_tag(bv)
+        index = self.tag2index[tag]
+        if self.index2bv[index] is None:
+            raise KeyError
+        return index
+
+    def __contains__(self, bv):
+        tag = self._get_tag(bv)
+        if tag not in self.tag2index:
+            return False
+        return self.index2bv[self.tag2index[tag]] is not None
+
+    def __delitem__(self, bv):
+        tag = self._get_tag(bv)
+        index = self.tag2index[tag]
+        self.index2bv[index] = None
+        self._len -= 1
+
+    def __iter__(self):
+        return iter((bv for bv in self.index2bv if bv is not None))
+
+    def __len__(self):
+        return self._len
+
+
+# TODO: Move to utils as general priority queue
+class BVPriorityQueue:
+    """Priority queue for tasks with sign sequences.
+
+    A priority queue implementation that supports updating task priorities and
+    removing tasks. Tasks are tuples starting with a sign sequence (BV) followed
+    by additional data. Based on the heapq implementation from Python docs.
+
+    Reference: https://docs.python.org/3/library/heapq.html
+    """
+
+    REMOVED = "<removed-task>"  # placeholder for a removed task
+
+    def __init__(self):
+        self.pq = []  # list of entries arranged in a heap
+        self.entry_finder = {}  # mapping of tasks to entries
+        self.counter = 0  # unique sequence count
+
+    def push(self, task, priority=0):
+        """Add a new task or update the priority of an existing task.
+
+        Args:
+            task: A tuple starting with a sign sequence followed by
+                additional task data.
+            priority: The priority value (lower = higher priority). Defaults to 0.
+        """
+        bv, *task = task
+        task = tuple(task)
+        if task in self.entry_finder:
+            self.remove_task(task)
+        entry = [priority, self.counter, bv, task]
+        self.entry_finder[task] = entry
+        heappush(self.pq, entry)
+        self.counter += 1
+
+    def remove_task(self, task):
+        "Mark an existing task as REMOVED.  Raise KeyError if not found."
+        entry = self.entry_finder.pop(task)
+        entry[-1] = self.REMOVED
+
+    def pop(self):
+        """Remove and return the lowest priority task.
+
+        Returns:
+            tuple: A tuple starting with the sign sequence (BV) followed by
+                the task data.
+
+        Raises:
+            KeyError: If the queue is empty.
+        """
+        while self.pq:
+            _, _, bv, task = heappop(self.pq)
+            if task is not self.REMOVED:
+                del self.entry_finder[task]
+                return bv, *task
+        raise KeyError("pop from an empty priority queue")
+
+    def __len__(self):
+        return len(self.entry_finder)
+
+
+# class BVPriorityQueue:
+#     """Simpler, less efficient version of the one above for debugging"""
+#     def __init__(self):
+#         self.pq = []  # list of entries arranged in a heap
+
+#     def push(self, task, priority=0):
+#         "Add a new task or update the priority of an existing task"
+#         # bv, *task = task
+#         self.pq.append((priority, task))
+#         self.pq.sort(reverse=True, key=lambda x: x[0])
+
+#     def remove_task(self, task):
+#         "Mark an existing task as REMOVED.  Raise KeyError if not found."
+#         self.pq = [(p, t) for p, t in self.pq if t != task]
+
+#     def pop(self):
+#         "Remove and return the lowest priority task. Raise KeyError if empty."
+#         return self.pq.pop(-1)[1]
+
+#     def __len__(self):
+#         return len(self.pq)
+
+
+# class BVNode:
+#     def __init__(self, key):
+#         self.key = key  ## Key of bv being set
+#         self.left = None  ## for all nodes in subtree, bv[0, key] = -1
+#         self.middle = None  ## ...bv[0, key] = 0
+#         self.right = None  ## ...bv[0, key] = 1
+
+#     def get_child(self, bv):
+#         # return either BVNode or int
+#         if bv[0, self.key] == -1:
+#             next_node = self.left
+#         elif bv[0, self.key] == 0:
+#             next_node = self.middle
+#         elif bv[0, self.key] == 1:
+#             next_node = self.right
+#         return next_node
+
+#     def set_child(self, bv, node):
+#         if bv[0, self.key] == -1:
+#             self.left = node
+#         elif bv[0, self.key] == 0:
+#             self.middle = node
+#         elif bv[0, self.key] == 1:
+#             self.right = node
+
+#     def print(self, level=0):
+#         print(" " * level + str(self.key) + ":")
+#         for name, k in zip(("L", "M", "R"), (self.left, self.middle, self.right)):
+#             if isinstance(k, BVNode):
+#                 print(" " * (level + 2) + name)
+#                 k.print(level=level + 4)
+#             elif isinstance(k, int):
+#                 print(" " * (level + 2) + name + ": leaf " + str(k))
+
+# # Trie
+# # Each edge in the tree sets a dimension to a value
+# # Leaf nodes are just indices of bvs in index2bv
+# class BVManager:
+#     def __init__(self):
+#         self.root = BVNode(0)
+#         self.index2bv = list()
+
+#     def add(self, bv):
+#         assert bv.ndim == 2
+#         node = self.root
+#         child = self.root.get_child(bv)
+#         while isinstance(child, BVNode):
+#             node = child
+#             child = node.get_child(bv)
+#         if child is None:
+#             node.set_child(bv, len(self.index2bv))
+#             self.index2bv.append(bv)
+#         elif isinstance(child, int):  ## TODO: This check should be redundant
+#             child_bv = self.index2bv[child]
+#             if not isinstance(child_bv, type(bv)):
+#                 if isinstance(bv, Tensor):
+#                     bv = bv.detach().cpu().numpy()
+#                 else:
+#                     child_bv = child_bv.detach().cpu().numpy()
+#             if not (child_bv == bv).all():
+#                 if child_bv[0, node.key] == bv[0, node.key]:  ## TODO: This check should be redundant
+#                     for i in range(bv.shape[1]):
+#                         if child_bv[0, i] != bv[0, i]:
+#                             break
+
+#                     ## Replace the existing child of the node with a new node
+#                     new_bvnode = BVNode(i)
+#                     node.set_child(bv, new_bvnode)
+
+#                     ## Set the new node's children
+#                     new_bvnode.set_child(child_bv, child)
+#                     new_bvnode.set_child(bv, len(self.index2bv))
+#                     self.index2bv.append(bv)
+#                 else:
+#                     raise ValueError("Something went wrong")
+
+#     def __getitem__(self, bv):
+#         assert bv.ndim == 2
+#         node = self.root
+#         while isinstance(node, BVNode):
+#             node = node.get_child(bv)
+#         if isinstance(node, int):
+#             found_bv = self.index2bv[node]
+#             if not isinstance(bv, type(found_bv)):
+#                 if isinstance(bv, Tensor):
+#                     bv = bv.detach().cpu().numpy()
+#                 else:
+#                     found_bv = found_bv.detach().cpu().numpy()
+#             if (found_bv == bv).all():
+#                 return node
+#         raise KeyError
+
+#     def __contains__(self, bv):
+#         try:
+#             self[bv]
+#             return True
+#         except KeyError:
+#             return False
+
+#     def __iter__(self):
+#         return iter(self.index2bv)
+
+#     def __len__(self):
+#         return len(self.index2bv)
+
+#     def print(self):
+#         print("Number of BVs:", len(self))
+#         self.root.print()