dethdc 0.1.0__tar.gz

dethdc-0.1.0/LICENSE

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

dethdc-0.1.0/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: dethdc
+Version: 0.1.0
+Summary: Deterministic Hyperdimensional Learning with Sobol projections and rank refinement
+Author: Abu Kaisar Mohammad Masum
+License: MIT
+Project-URL: Paper, https://ojs.aaai.org/index.php/AAAI/article/view/42253
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.0
+Provides-Extra: examples
+Requires-Dist: torchvision>=0.15; extra == "examples"
+Requires-Dist: scikit-learn>=1.2; extra == "examples"
+Requires-Dist: tqdm>=4.65; extra == "examples"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+
+# DetHDC
+
+### Deterministic Hyperdimensional Learning with Rank Refinement
+
+[![AAAI 2026](https://img.shields.io/badge/AAAI-2026-6A5ACD.svg)](https://ojs.aaai.org/index.php/AAAI/article/view/42253)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C.svg?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Official research implementation of the AAAI 2026 paper  
+“Deterministic Hyperdimensional Learning with Rank Refinement.”**
+
+[Paper](https://ojs.aaai.org/index.php/AAAI/article/view/42253) · [Quick Start](#-quick-start) · [Citation](#-citation)
+
+</div>
+
+---
+
+## ✨ Overview
+
+**DetHDC** is a lightweight PyTorch library for deterministic hyperdimensional learning using:
+
+- **Sobol quasi-random projections**
+- **position–value binding**
+- **prototype-based HDC classification**
+- **rank-based refinement**
+- **CPU and CUDA execution**
+- **reproducible training through explicit random seeds**
+
+The repository turns the method from our AAAI 2026 paper into a reusable Python API instead of a dataset-specific research script.
+
+---
+
+## 🧠 Method at a Glance
+
+Given an input vector \(x \in \mathbb{R}^{L}\), DetHDC builds two deterministic projection spaces:
+
+\[
+P, V \in \mathbb{R}^{D \times L},
+\]
+
+where \(P\) and \(V\) are generated from scrambled Sobol sequences.
+
+The projected representations are
+
+\[
+h_p = \frac{xP^\top}{\sqrt{L}},
+\qquad
+h_v = \frac{xV^\top}{\sqrt{L}},
+\]
+
+and the final hypervector is obtained through element-wise binding:
+
+\[
+h = \mathrm{norm}(h_p \odot h_v).
+\]
+
+Class prototypes are first constructed by bundling encoded samples. A rank-based refinement stage then updates prototypes when the true class is not sufficiently separated from the strongest competing class.
+
+---
+
+## 🚀 Quick Start
+
+### Install from source
+
+```bash
+git clone https://github.com/Abu-Kaisar-Mohammad-Masum/DetHDC.git
+cd DetHDC
+pip install -e .
+```
+
+### Minimal example
+
+```python
+from dethdc import DetHDC
+
+model = DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    seed=42,
+    device="auto",
+)
+
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+accuracy = model.score(X_test, y_test)
+
+print(f"Accuracy: {accuracy * 100:.2f}%")
+```
+
+---
+
+## 🔥 Why DetHDC?
+
+Traditional HDC implementations often rely on randomly generated hypervectors. That can introduce run-to-run variation and make reproducibility harder.
+
+DetHDC instead uses **Sobol-based deterministic projections**, giving a controlled projection space while retaining the efficiency and robustness properties of hyperdimensional learning.
+
+The library also exposes the refinement stage directly:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=True,
+    epochs=5,
+)
+```
+
+For a base model without rank refinement:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=False,
+)
+```
+
+---
+
+## 📦 Library API
+
+```python
+from dethdc import DetHDC, SobolEncoder
+```
+
+### `DetHDC`
+
+```python
+DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    refinement=True,
+    scramble=True,
+    seed=42,
+    device="auto",
+)
+```
+
+Main methods:
+
+```python
+model.fit(X, y)
+model.encode(X)
+model.predict(X)
+model.predict_similarity(X)
+model.score(X, y)
+model.get_config()
+model.save("model.pt")
+DetHDC.load("model.pt")
+```
+
+---
+
+## 🧪 MNIST Example
+
+Run:
+
+```bash
+python examples/mnist.py
+```
+
+The example:
+
+1. downloads MNIST,
+2. flattens native \(28 \times 28\) images,
+3. constructs Sobol projection matrices,
+4. encodes the training/test sets,
+5. builds class prototypes,
+6. performs rank-based refinement,
+7. reports classification accuracy.
+
+---
+
+## 🗂 Repository Structure
+
+```text
+DetHDC/
+├── README.md
+├── LICENSE
+├── CITATION.cff
+├── pyproject.toml
+├── src/
+│   └── dethdc/
+│       ├── __init__.py
+│       ├── classifier.py
+│       └── encoder.py
+├── examples/
+│   └── mnist.py
+├── benchmarks/
+│   └── reproduce_aaai2026.py
+└── tests/
+    ├── test_encoder.py
+    └── test_classifier.py
+```
+
+---
+
+## ⚡ GPU Support
+
+DetHDC automatically uses CUDA when available:
+
+```python
+model = DetHDC(device="auto")
+```
+
+You can also force a backend:
+
+```python
+model = DetHDC(device="cpu")
+model = DetHDC(device="cuda")
+```
+
+Classification stays in PyTorch and avoids unnecessary GPU → CPU → NumPy transfers.
+
+---
+
+## 🔬 Reproducibility
+
+DetHDC exposes the seed explicitly:
+
+```python
+model = DetHDC(seed=42)
+```
+
+You can inspect the complete configuration:
+
+```python
+print(model.get_config())
+```
+
+Example:
+
+```python
+{
+    "dimensions": 10000,
+    "epochs": 5,
+    "lr": 0.01,
+    "margin": 0.2,
+    "refinement": True,
+    "scramble": True,
+    "seed": 42,
+    "device": "cuda"
+}
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The test suite checks:
+
+- output dimensions,
+- deterministic Sobol generation,
+- fitting and prediction,
+- model save/load,
+- CPU execution,
+- CUDA execution when available.
+
+---
+
+## 🧪 Library Sanity Check
+
+Using the reproducible MNIST example included in this repository:
+
+| Configuration | Result |
+|---|---:|
+| Dimension | 10,000 |
+| Refinement iterations | 5 |
+| Seed | 42 |
+| Test split | 30% stratified |
+| Accuracy | **95.46%** |
+
+The packaged example uses a fixed deterministic split and seed and is
+intended as a reproducible usage example rather than an exact recreation
+of the paper's experimental split.
+
+## 📄 Paper
+
+**Deterministic Hyperdimensional Learning with Rank Refinement**  
+Abu Kaisar Mohammad Masum and Sercan Aygun  
+*Proceedings of the AAAI Conference on Artificial Intelligence*, 2026.
+
+Paper:
+
+https://ojs.aaai.org/index.php/AAAI/article/view/42253
+
+---
+
+## 📚 Citation
+
+If this repository helps your research, please cite our AAAI paper:
+
+```bibtex
+@inproceedings{masum2026deterministic,
+  title={Deterministic hyperdimensional learning with rank refinement (student abstract)},
+  author={Masum, Abu Kaisar Mohammad and Aygun, Sercan},
+  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
+  volume={40},
+  number={48},
+  pages={41313--41315},
+  year={2026}
+}
+```
+
+
+## 📜 License
+
+Released under the [MIT License](LICENSE).
+
+---
+
+**Deterministic projections. Lightweight learning. Reproducible HDC.**
+
+</div>

dethdc-0.1.0/README.md

@@ -0,0 +1,326 @@
+<div align="center">
+
+# DetHDC
+
+### Deterministic Hyperdimensional Learning with Rank Refinement
+
+[![AAAI 2026](https://img.shields.io/badge/AAAI-2026-6A5ACD.svg)](https://ojs.aaai.org/index.php/AAAI/article/view/42253)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C.svg?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Official research implementation of the AAAI 2026 paper  
+“Deterministic Hyperdimensional Learning with Rank Refinement.”**
+
+[Paper](https://ojs.aaai.org/index.php/AAAI/article/view/42253) · [Quick Start](#-quick-start) · [Citation](#-citation)
+
+</div>
+
+---
+
+## ✨ Overview
+
+**DetHDC** is a lightweight PyTorch library for deterministic hyperdimensional learning using:
+
+- **Sobol quasi-random projections**
+- **position–value binding**
+- **prototype-based HDC classification**
+- **rank-based refinement**
+- **CPU and CUDA execution**
+- **reproducible training through explicit random seeds**
+
+The repository turns the method from our AAAI 2026 paper into a reusable Python API instead of a dataset-specific research script.
+
+---
+
+## 🧠 Method at a Glance
+
+Given an input vector \(x \in \mathbb{R}^{L}\), DetHDC builds two deterministic projection spaces:
+
+\[
+P, V \in \mathbb{R}^{D \times L},
+\]
+
+where \(P\) and \(V\) are generated from scrambled Sobol sequences.
+
+The projected representations are
+
+\[
+h_p = \frac{xP^\top}{\sqrt{L}},
+\qquad
+h_v = \frac{xV^\top}{\sqrt{L}},
+\]
+
+and the final hypervector is obtained through element-wise binding:
+
+\[
+h = \mathrm{norm}(h_p \odot h_v).
+\]
+
+Class prototypes are first constructed by bundling encoded samples. A rank-based refinement stage then updates prototypes when the true class is not sufficiently separated from the strongest competing class.
+
+---
+
+## 🚀 Quick Start
+
+### Install from source
+
+```bash
+git clone https://github.com/Abu-Kaisar-Mohammad-Masum/DetHDC.git
+cd DetHDC
+pip install -e .
+```
+
+### Minimal example
+
+```python
+from dethdc import DetHDC
+
+model = DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    seed=42,
+    device="auto",
+)
+
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+accuracy = model.score(X_test, y_test)
+
+print(f"Accuracy: {accuracy * 100:.2f}%")
+```
+
+---
+
+## 🔥 Why DetHDC?
+
+Traditional HDC implementations often rely on randomly generated hypervectors. That can introduce run-to-run variation and make reproducibility harder.
+
+DetHDC instead uses **Sobol-based deterministic projections**, giving a controlled projection space while retaining the efficiency and robustness properties of hyperdimensional learning.
+
+The library also exposes the refinement stage directly:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=True,
+    epochs=5,
+)
+```
+
+For a base model without rank refinement:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=False,
+)
+```
+
+---
+
+## 📦 Library API
+
+```python
+from dethdc import DetHDC, SobolEncoder
+```
+
+### `DetHDC`
+
+```python
+DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    refinement=True,
+    scramble=True,
+    seed=42,
+    device="auto",
+)
+```
+
+Main methods:
+
+```python
+model.fit(X, y)
+model.encode(X)
+model.predict(X)
+model.predict_similarity(X)
+model.score(X, y)
+model.get_config()
+model.save("model.pt")
+DetHDC.load("model.pt")
+```
+
+---
+
+## 🧪 MNIST Example
+
+Run:
+
+```bash
+python examples/mnist.py
+```
+
+The example:
+
+1. downloads MNIST,
+2. flattens native \(28 \times 28\) images,
+3. constructs Sobol projection matrices,
+4. encodes the training/test sets,
+5. builds class prototypes,
+6. performs rank-based refinement,
+7. reports classification accuracy.
+
+---
+
+## 🗂 Repository Structure
+
+```text
+DetHDC/
+├── README.md
+├── LICENSE
+├── CITATION.cff
+├── pyproject.toml
+├── src/
+│   └── dethdc/
+│       ├── __init__.py
+│       ├── classifier.py
+│       └── encoder.py
+├── examples/
+│   └── mnist.py
+├── benchmarks/
+│   └── reproduce_aaai2026.py
+└── tests/
+    ├── test_encoder.py
+    └── test_classifier.py
+```
+
+---
+
+## ⚡ GPU Support
+
+DetHDC automatically uses CUDA when available:
+
+```python
+model = DetHDC(device="auto")
+```
+
+You can also force a backend:
+
+```python
+model = DetHDC(device="cpu")
+model = DetHDC(device="cuda")
+```
+
+Classification stays in PyTorch and avoids unnecessary GPU → CPU → NumPy transfers.
+
+---
+
+## 🔬 Reproducibility
+
+DetHDC exposes the seed explicitly:
+
+```python
+model = DetHDC(seed=42)
+```
+
+You can inspect the complete configuration:
+
+```python
+print(model.get_config())
+```
+
+Example:
+
+```python
+{
+    "dimensions": 10000,
+    "epochs": 5,
+    "lr": 0.01,
+    "margin": 0.2,
+    "refinement": True,
+    "scramble": True,
+    "seed": 42,
+    "device": "cuda"
+}
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The test suite checks:
+
+- output dimensions,
+- deterministic Sobol generation,
+- fitting and prediction,
+- model save/load,
+- CPU execution,
+- CUDA execution when available.
+
+---
+
+## 🧪 Library Sanity Check
+
+Using the reproducible MNIST example included in this repository:
+
+| Configuration | Result |
+|---|---:|
+| Dimension | 10,000 |
+| Refinement iterations | 5 |
+| Seed | 42 |
+| Test split | 30% stratified |
+| Accuracy | **95.46%** |
+
+The packaged example uses a fixed deterministic split and seed and is
+intended as a reproducible usage example rather than an exact recreation
+of the paper's experimental split.
+
+## 📄 Paper
+
+**Deterministic Hyperdimensional Learning with Rank Refinement**  
+Abu Kaisar Mohammad Masum and Sercan Aygun  
+*Proceedings of the AAAI Conference on Artificial Intelligence*, 2026.
+
+Paper:
+
+https://ojs.aaai.org/index.php/AAAI/article/view/42253
+
+---
+
+## 📚 Citation
+
+If this repository helps your research, please cite our AAAI paper:
+
+```bibtex
+@inproceedings{masum2026deterministic,
+  title={Deterministic hyperdimensional learning with rank refinement (student abstract)},
+  author={Masum, Abu Kaisar Mohammad and Aygun, Sercan},
+  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
+  volume={40},
+  number={48},
+  pages={41313--41315},
+  year={2026}
+}
+```
+
+
+## 📜 License
+
+Released under the [MIT License](LICENSE).
+
+---
+
+**Deterministic projections. Lightweight learning. Reproducible HDC.**
+
+</div>

dethdc-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dethdc"
+version = "0.1.0"
+description = "Deterministic Hyperdimensional Learning with Sobol projections and rank refinement"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Abu Kaisar Mohammad Masum"}
+]
+dependencies = [
+  "numpy>=1.24",
+  "torch>=2.0"
+]
+
+[project.optional-dependencies]
+examples = [
+  "torchvision>=0.15",
+  "scikit-learn>=1.2",
+  "tqdm>=4.65"
+]
+test = [
+  "pytest>=7.0"
+]
+
+[project.urls]
+Paper = "https://ojs.aaai.org/index.php/AAAI/article/view/42253"
+
+[tool.setuptools.packages.find]
+where = ["src"]

dethdc-0.1.0/setup.cfg

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

dethdc-0.1.0/src/dethdc/__init__.py

@@ -0,0 +1,5 @@
+from .classifier import DetHDC
+from .encoder import SobolEncoder
+
+__all__ = ["DetHDC", "SobolEncoder"]
+__version__ = "0.1.0"

dethdc-0.1.0/src/dethdc/classifier.py

@@ -0,0 +1,171 @@
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+
+from .encoder import SobolEncoder
+
+
+class DetHDC:
+    """Deterministic HDC classifier with optional rank-based refinement."""
+
+    def __init__(
+        self,
+        dimensions=10000,
+        epochs=5,
+        lr=0.01,
+        margin=0.2,
+        refinement=True,
+        scramble=True,
+        seed=42,
+        device="auto",
+    ):
+        self.dimensions = int(dimensions)
+        self.epochs = int(epochs)
+        self.lr = float(lr)
+        self.margin = float(margin)
+        self.refinement = bool(refinement)
+        self.scramble = bool(scramble)
+        self.seed = int(seed)
+
+        self.encoder = SobolEncoder(
+            dimensions=self.dimensions,
+            scramble=self.scramble,
+            seed=self.seed,
+            device=device,
+        )
+        self.device = self.encoder.device
+
+        self.class_hypervectors_ = None
+        self.classes_ = None
+
+    def encode(self, X):
+        return self.encoder.transform(X)
+
+    def _initialize_prototypes(self, encoded, y):
+        y = torch.as_tensor(y, dtype=torch.long, device=self.device)
+        self.classes_ = torch.unique(y, sorted=True)
+
+        if not torch.equal(
+            self.classes_,
+            torch.arange(len(self.classes_), device=self.device),
+        ):
+            raise ValueError(
+                "Current implementation expects integer class labels 0..C-1."
+            )
+
+        prototypes = torch.zeros(
+            (len(self.classes_), self.dimensions),
+            dtype=torch.float32,
+            device=self.device,
+        )
+
+        prototypes.index_add_(0, y, encoded)
+        return F.normalize(prototypes, p=2, dim=1, eps=1e-12)
+
+    def _rank_refine(self, encoded, y):
+        y = torch.as_tensor(y, dtype=torch.long, device=self.device)
+
+        prototypes = self.class_hypervectors_.clone().detach().requires_grad_(True)
+        optimizer = torch.optim.SGD([prototypes], lr=self.lr)
+
+        for _ in range(self.epochs):
+            order = torch.randperm(
+                len(encoded),
+                generator=torch.Generator(device="cpu").manual_seed(self.seed),
+            )
+
+            for idx in order.tolist():
+                optimizer.zero_grad()
+
+                x = encoded[idx : idx + 1]
+                target = int(y[idx].item())
+
+                sims = F.cosine_similarity(x, prototypes)
+                pred = int(torch.argmax(sims).item())
+
+                if pred == target:
+                    continue
+
+                loss = torch.clamp(
+                    self.margin - (sims[target] - sims[pred]),
+                    min=0.0,
+                )
+
+                if loss.item() > 0:
+                    loss.backward()
+                    optimizer.step()
+
+                    with torch.no_grad():
+                        prototypes[:] = F.normalize(
+                            prototypes, p=2, dim=1, eps=1e-12
+                        )
+
+        self.class_hypervectors_ = prototypes.detach()
+
+    def fit(self, X, y):
+        encoded = self.encoder.fit_transform(X)
+        self.class_hypervectors_ = self._initialize_prototypes(encoded, y)
+
+        if self.refinement and self.epochs > 0:
+            self._rank_refine(encoded, y)
+
+        return self
+
+    def predict_similarity(self, X):
+        self._check_fitted()
+        encoded = self.encode(X)
+        encoded = F.normalize(encoded, p=2, dim=1, eps=1e-12)
+        prototypes = F.normalize(
+            self.class_hypervectors_, p=2, dim=1, eps=1e-12
+        )
+        return encoded @ prototypes.T
+
+    def predict(self, X):
+        similarities = self.predict_similarity(X)
+        return torch.argmax(similarities, dim=1).detach().cpu().numpy()
+
+    def score(self, X, y):
+        pred = torch.as_tensor(self.predict(X))
+        target = torch.as_tensor(y).cpu()
+        return float((pred == target).float().mean().item())
+
+    def get_config(self):
+        return {
+            "dimensions": self.dimensions,
+            "epochs": self.epochs,
+            "lr": self.lr,
+            "margin": self.margin,
+            "refinement": self.refinement,
+            "scramble": self.scramble,
+            "seed": self.seed,
+            "device": str(self.device),
+        }
+
+    def save(self, path):
+        self._check_fitted()
+        payload = {
+            "config": self.get_config(),
+            "classes": self.classes_.detach().cpu(),
+            "class_hypervectors": self.class_hypervectors_.detach().cpu(),
+            "projection": self.encoder.projection_.detach().cpu(),
+            "input_dim": self.encoder.input_dim_,
+        }
+        torch.save(payload, Path(path))
+
+    @classmethod
+    def load(cls, path, device="auto"):
+        payload = torch.load(Path(path), map_location="cpu")
+        cfg = dict(payload["config"])
+        cfg["device"] = device
+
+        model = cls(**cfg)
+        model.classes_ = payload["classes"].to(model.device)
+        model.class_hypervectors_ = payload["class_hypervectors"].to(model.device)
+        model.encoder.projection_ = payload["projection"].to(model.device)
+        model.encoder.input_dim_ = payload["input_dim"]
+        return model
+
+    def _check_fitted(self):
+        if self.class_hypervectors_ is None:
+            raise RuntimeError("Call fit() before prediction.")

dethdc-0.1.0/src/dethdc/encoder.py

@@ -0,0 +1,85 @@
+import math
+import torch
+import torch.nn.functional as F
+from torch.quasirandom import SobolEngine
+
+
+class SobolEncoder:
+    """Sobol-based deterministic position/value hypervector encoder."""
+
+    def __init__(
+        self,
+        dimensions=10000,
+        scramble=True,
+        seed=42,
+        device="auto",
+    ):
+        self.dimensions = int(dimensions)
+        self.scramble = bool(scramble)
+        self.seed = int(seed)
+        self.device = self._resolve_device(device)
+        self.projection_ = None
+        self.input_dim_ = None
+
+    @staticmethod
+    def _resolve_device(device):
+        if device == "auto":
+            return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        return torch.device(device)
+
+    def _build_projection(self, input_dim):
+        pos_engine = SobolEngine(
+            dimension=input_dim,
+            scramble=self.scramble,
+            seed=self.seed,
+        )
+        val_engine = SobolEngine(
+            dimension=input_dim,
+            scramble=self.scramble,
+            seed=self.seed + 1,
+        )
+
+        position = 2.0 * pos_engine.draw(self.dimensions) - 1.0
+        value = 2.0 * val_engine.draw(self.dimensions) - 1.0
+
+        self.projection_ = torch.stack(
+            [position, value], dim=0
+        ).to(self.device, dtype=torch.float32)
+
+        self.input_dim_ = input_dim
+
+    def fit(self, X):
+        X = torch.as_tensor(X)
+        input_dim = int(X[0].numel()) if X.ndim > 1 else int(X.numel())
+        self._build_projection(input_dim)
+        return self
+
+    def transform(self, X):
+        X = torch.as_tensor(X, dtype=torch.float32, device=self.device)
+        X = X.reshape(X.shape[0], -1)
+
+        if self.projection_ is None:
+            self._build_projection(X.shape[1])
+
+        if X.shape[1] != self.input_dim_:
+            raise ValueError(
+                f"Expected input dimension {self.input_dim_}, got {X.shape[1]}."
+            )
+
+        # Match the original image preprocessing behavior when inputs are [0,1].
+        if torch.min(X) >= 0 and torch.max(X) <= 1:
+            X = X * 2.0 - 1.0
+
+        position = self.projection_[0]
+        value = self.projection_[1]
+
+        inv_sqrt_l = 1.0 / math.sqrt(float(self.input_dim_))
+
+        pos = torch.einsum("bi,di->bd", X, position) * inv_sqrt_l
+        val = torch.einsum("bi,di->bd", X, value) * inv_sqrt_l
+
+        hv = pos * val
+        return F.normalize(hv, p=2, dim=1, eps=1e-12)
+
+    def fit_transform(self, X):
+        return self.fit(X).transform(X)

dethdc-0.1.0/src/dethdc.egg-info/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: dethdc
+Version: 0.1.0
+Summary: Deterministic Hyperdimensional Learning with Sobol projections and rank refinement
+Author: Abu Kaisar Mohammad Masum
+License: MIT
+Project-URL: Paper, https://ojs.aaai.org/index.php/AAAI/article/view/42253
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.0
+Provides-Extra: examples
+Requires-Dist: torchvision>=0.15; extra == "examples"
+Requires-Dist: scikit-learn>=1.2; extra == "examples"
+Requires-Dist: tqdm>=4.65; extra == "examples"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+
+# DetHDC
+
+### Deterministic Hyperdimensional Learning with Rank Refinement
+
+[![AAAI 2026](https://img.shields.io/badge/AAAI-2026-6A5ACD.svg)](https://ojs.aaai.org/index.php/AAAI/article/view/42253)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C.svg?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Official research implementation of the AAAI 2026 paper  
+“Deterministic Hyperdimensional Learning with Rank Refinement.”**
+
+[Paper](https://ojs.aaai.org/index.php/AAAI/article/view/42253) · [Quick Start](#-quick-start) · [Citation](#-citation)
+
+</div>
+
+---
+
+## ✨ Overview
+
+**DetHDC** is a lightweight PyTorch library for deterministic hyperdimensional learning using:
+
+- **Sobol quasi-random projections**
+- **position–value binding**
+- **prototype-based HDC classification**
+- **rank-based refinement**
+- **CPU and CUDA execution**
+- **reproducible training through explicit random seeds**
+
+The repository turns the method from our AAAI 2026 paper into a reusable Python API instead of a dataset-specific research script.
+
+---
+
+## 🧠 Method at a Glance
+
+Given an input vector \(x \in \mathbb{R}^{L}\), DetHDC builds two deterministic projection spaces:
+
+\[
+P, V \in \mathbb{R}^{D \times L},
+\]
+
+where \(P\) and \(V\) are generated from scrambled Sobol sequences.
+
+The projected representations are
+
+\[
+h_p = \frac{xP^\top}{\sqrt{L}},
+\qquad
+h_v = \frac{xV^\top}{\sqrt{L}},
+\]
+
+and the final hypervector is obtained through element-wise binding:
+
+\[
+h = \mathrm{norm}(h_p \odot h_v).
+\]
+
+Class prototypes are first constructed by bundling encoded samples. A rank-based refinement stage then updates prototypes when the true class is not sufficiently separated from the strongest competing class.
+
+---
+
+## 🚀 Quick Start
+
+### Install from source
+
+```bash
+git clone https://github.com/Abu-Kaisar-Mohammad-Masum/DetHDC.git
+cd DetHDC
+pip install -e .
+```
+
+### Minimal example
+
+```python
+from dethdc import DetHDC
+
+model = DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    seed=42,
+    device="auto",
+)
+
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+accuracy = model.score(X_test, y_test)
+
+print(f"Accuracy: {accuracy * 100:.2f}%")
+```
+
+---
+
+## 🔥 Why DetHDC?
+
+Traditional HDC implementations often rely on randomly generated hypervectors. That can introduce run-to-run variation and make reproducibility harder.
+
+DetHDC instead uses **Sobol-based deterministic projections**, giving a controlled projection space while retaining the efficiency and robustness properties of hyperdimensional learning.
+
+The library also exposes the refinement stage directly:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=True,
+    epochs=5,
+)
+```
+
+For a base model without rank refinement:
+
+```python
+model = DetHDC(
+    dimensions=10000,
+    refinement=False,
+)
+```
+
+---
+
+## 📦 Library API
+
+```python
+from dethdc import DetHDC, SobolEncoder
+```
+
+### `DetHDC`
+
+```python
+DetHDC(
+    dimensions=10000,
+    epochs=5,
+    lr=0.01,
+    margin=0.2,
+    refinement=True,
+    scramble=True,
+    seed=42,
+    device="auto",
+)
+```
+
+Main methods:
+
+```python
+model.fit(X, y)
+model.encode(X)
+model.predict(X)
+model.predict_similarity(X)
+model.score(X, y)
+model.get_config()
+model.save("model.pt")
+DetHDC.load("model.pt")
+```
+
+---
+
+## 🧪 MNIST Example
+
+Run:
+
+```bash
+python examples/mnist.py
+```
+
+The example:
+
+1. downloads MNIST,
+2. flattens native \(28 \times 28\) images,
+3. constructs Sobol projection matrices,
+4. encodes the training/test sets,
+5. builds class prototypes,
+6. performs rank-based refinement,
+7. reports classification accuracy.
+
+---
+
+## 🗂 Repository Structure
+
+```text
+DetHDC/
+├── README.md
+├── LICENSE
+├── CITATION.cff
+├── pyproject.toml
+├── src/
+│   └── dethdc/
+│       ├── __init__.py
+│       ├── classifier.py
+│       └── encoder.py
+├── examples/
+│   └── mnist.py
+├── benchmarks/
+│   └── reproduce_aaai2026.py
+└── tests/
+    ├── test_encoder.py
+    └── test_classifier.py
+```
+
+---
+
+## ⚡ GPU Support
+
+DetHDC automatically uses CUDA when available:
+
+```python
+model = DetHDC(device="auto")
+```
+
+You can also force a backend:
+
+```python
+model = DetHDC(device="cpu")
+model = DetHDC(device="cuda")
+```
+
+Classification stays in PyTorch and avoids unnecessary GPU → CPU → NumPy transfers.
+
+---
+
+## 🔬 Reproducibility
+
+DetHDC exposes the seed explicitly:
+
+```python
+model = DetHDC(seed=42)
+```
+
+You can inspect the complete configuration:
+
+```python
+print(model.get_config())
+```
+
+Example:
+
+```python
+{
+    "dimensions": 10000,
+    "epochs": 5,
+    "lr": 0.01,
+    "margin": 0.2,
+    "refinement": True,
+    "scramble": True,
+    "seed": 42,
+    "device": "cuda"
+}
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The test suite checks:
+
+- output dimensions,
+- deterministic Sobol generation,
+- fitting and prediction,
+- model save/load,
+- CPU execution,
+- CUDA execution when available.
+
+---
+
+## 🧪 Library Sanity Check
+
+Using the reproducible MNIST example included in this repository:
+
+| Configuration | Result |
+|---|---:|
+| Dimension | 10,000 |
+| Refinement iterations | 5 |
+| Seed | 42 |
+| Test split | 30% stratified |
+| Accuracy | **95.46%** |
+
+The packaged example uses a fixed deterministic split and seed and is
+intended as a reproducible usage example rather than an exact recreation
+of the paper's experimental split.
+
+## 📄 Paper
+
+**Deterministic Hyperdimensional Learning with Rank Refinement**  
+Abu Kaisar Mohammad Masum and Sercan Aygun  
+*Proceedings of the AAAI Conference on Artificial Intelligence*, 2026.
+
+Paper:
+
+https://ojs.aaai.org/index.php/AAAI/article/view/42253
+
+---
+
+## 📚 Citation
+
+If this repository helps your research, please cite our AAAI paper:
+
+```bibtex
+@inproceedings{masum2026deterministic,
+  title={Deterministic hyperdimensional learning with rank refinement (student abstract)},
+  author={Masum, Abu Kaisar Mohammad and Aygun, Sercan},
+  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
+  volume={40},
+  number={48},
+  pages={41313--41315},
+  year={2026}
+}
+```
+
+
+## 📜 License
+
+Released under the [MIT License](LICENSE).
+
+---
+
+**Deterministic projections. Lightweight learning. Reproducible HDC.**
+
+</div>

dethdc-0.1.0/src/dethdc.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/dethdc/__init__.py
+src/dethdc/classifier.py
+src/dethdc/encoder.py
+src/dethdc.egg-info/PKG-INFO
+src/dethdc.egg-info/SOURCES.txt
+src/dethdc.egg-info/dependency_links.txt
+src/dethdc.egg-info/requires.txt
+src/dethdc.egg-info/top_level.txt
+tests/test_classifier.py
+tests/test_encoder.py

dethdc-0.1.0/src/dethdc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dethdc-0.1.0/src/dethdc.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy>=1.24
+torch>=2.0
+
+[examples]
+torchvision>=0.15
+scikit-learn>=1.2
+tqdm>=4.65
+
+[test]
+pytest>=7.0

dethdc-0.1.0/src/dethdc.egg-info/top_level.txt

@@ -0,0 +1 @@
+dethdc

dethdc-0.1.0/tests/test_classifier.py

@@ -0,0 +1,27 @@
+import numpy as np
+
+from dethdc import DetHDC
+
+
+def test_fit_predict():
+    rng = np.random.RandomState(42)
+
+    X0 = rng.normal(0.2, 0.05, size=(20, 8)).astype("float32")
+    X1 = rng.normal(0.8, 0.05, size=(20, 8)).astype("float32")
+
+    X = np.vstack([X0, X1])
+    y = np.array([0] * 20 + [1] * 20)
+
+    model = DetHDC(
+        dimensions=256,
+        epochs=1,
+        refinement=True,
+        seed=42,
+        device="cpu",
+    )
+
+    model.fit(X, y)
+    pred = model.predict(X)
+
+    assert pred.shape == y.shape
+    assert model.score(X, y) >= 0.5

dethdc-0.1.0/tests/test_encoder.py

@@ -0,0 +1,20 @@
+import numpy as np
+import torch
+
+from dethdc import SobolEncoder
+
+
+def test_encoder_shape():
+    X = np.random.RandomState(0).rand(8, 16).astype("float32")
+    encoder = SobolEncoder(dimensions=128, seed=42, device="cpu")
+    H = encoder.fit_transform(X)
+    assert H.shape == (8, 128)
+
+
+def test_same_seed_same_projection():
+    X = np.random.RandomState(1).rand(4, 8).astype("float32")
+
+    a = SobolEncoder(dimensions=64, seed=7, device="cpu").fit_transform(X)
+    b = SobolEncoder(dimensions=64, seed=7, device="cpu").fit_transform(X)
+
+    assert torch.allclose(a, b)