relucent 0.1.0__tar.gz

relucent-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: relucent
+Version: 0.1.0
+Author: Blake B. Gaines
+License-Expression: AGPL-3.0-or-later
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: pandas
+Requires-Dist: gurobipy
+Requires-Dist: networkx
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: plotly
+Requires-Dist: pillow
+Requires-Dist: pyvis ; extra == 'cli'
+Requires-Dist: kaleido ; extra == 'cli'
+Requires-Python: >=3.13, <3.14
+Project-URL: Homepage, https://github.com/bl-ake/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)
+
+# Relucent
+Explore polyhedral complexes associated with ReLU networks
+
+## Environment Setup 
+1. Install Python 3.13
+2. Install [PyTorch 2.3.0](https://pytorch.org/get-started/previous-versions/#:~:text=org/whl/cpu-,v2.3.0)
+3. Install the remaining dependencies with `pip install -r requirements.txt`
+
+## 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
+
+**The following steps are not necessary when replicating the experiments from the paper.** 
+
+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.1.0/README.md

@@ -0,0 +1,25 @@
+[![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)
+
+# Relucent
+Explore polyhedral complexes associated with ReLU networks
+
+## Environment Setup 
+1. Install Python 3.13
+2. Install [PyTorch 2.3.0](https://pytorch.org/get-started/previous-versions/#:~:text=org/whl/cpu-,v2.3.0)
+3. Install the remaining dependencies with `pip install -r requirements.txt`
+
+## 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
+
+**The following steps are not necessary when replicating the experiments from the paper.** 
+
+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.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["uv_build >= 0.9.5, <0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "relucent"
+version = "0.1.0"
+requires-python = ">= 3.13, <3.14"
+dependencies = [ ## TODO: Constrain Versions
+    "torch",
+    "torchvision",
+    "pandas",
+    "gurobipy",
+    "networkx",
+    "numpy",
+    "scipy",
+    "tqdm",
+    "matplotlib",
+    "plotly",
+    "Pillow",
+]
+authors = [{ name = "Blake B. Gaines" }]
+license = "AGPL-3.0-or-later"
+readme = "README.md"
+
+[project.optional-dependencies]
+cli = ["pyvis", "kaleido"]
+
+[project.urls]
+Homepage = "https://github.com/bl-ake/relucent"

relucent-0.1.0/src/relucent/__init__.py

@@ -0,0 +1,7 @@
+from .bvs import BVManager
+from .complex import Complex
+from .model import NN, get_mlp_model
+from .convert_model import convert
+from .utils import get_env, split_sequential, data_graph, set_seeds
+
+__all__ = [Complex, NN, get_mlp_model, BVManager, convert, get_env, split_sequential, data_graph, set_seeds]

relucent-0.1.0/src/relucent/bvs.py

@@ -0,0 +1,221 @@
+from heapq import heappop, heappush
+
+from torch import Tensor
+
+from .poly import encode_bv
+
+
+class BVManager:
+    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):
+        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:
+    ## From 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"
+        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. Raise KeyError if 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:
+#     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
+# # TODO: Replace hashmaps in Complex class with this
+# 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()