Support explicit VSA models enabling customization of operations (#91)

* Implement VSA Model class

* Update README

* Add tests for hypervector creation

* test operations

* Update tests

* Create documentation outline

* Fix short circuit tests

* Update examples

* Add automatic model conversion

* WIP documentation

* Refactor as_vsa_model function for automatic conversion

* Update model references

* Use backward supported typing

* WIP BSC documentation

* add documentation for the MAP VSA model

* doc fhrr

* Fix pytorch version install and empty BSC

* Lower minimum torch version

* Update examples

* Increment version

* Update examples

* Deterministic tests

Co-authored-by: pereverges <[email protected]>
Co-authored-by: igordeoliveiranunes <[email protected]>

Author: 3 people

README.md

@@ -65,19 +65,19 @@ usd, mxn = torchhd.random_hv(2, d)  # US Dollar and Mexican Peso
 
 # create country representations
 us_values = torch.stack([usa, wdc, usd])
-us = torchhd.functional.hash_table(keys, us_values)
+us = torchhd.hash_table(keys, us_values)
 
 mx_values = torch.stack([mex, mxc, mxn])
-mx = torchhd.functional.hash_table(keys, mx_values)
+mx = torchhd.hash_table(keys, mx_values)
 
 # combine all the associated information
-mx_us = torchhd.bind(us, mx)
+mx_us = torchhd.bind(torchhd.inverse(us), mx)
 
 # query for the dollar of mexico
 usd_of_mex = torchhd.bind(mx_us, usd)
 
 memory = torch.cat([keys, us_values, mx_values], dim=0)
-torchhd.functional.cosine_similarity(usd_of_mex, memory)
+torchhd.cos_similarity(usd_of_mex, memory)
 # tensor([-0.0062,  0.0123, -0.0057, -0.0019, -0.0084, -0.0078,  0.0102,  0.0057,  0.3292])
 # The hypervector for the Mexican Peso is the most similar.
 ```

dev-requirements.txt

@@ -1,4 +1,4 @@
-torch
+torch>=1.9.0
 torchvision
 pandas
 requests

docs/_static/css/custom.css

@@ -242,4 +242,34 @@ body,
 
 .wy-nav-content-wrap {
     background: none;
+}
+
+.body,
+.rst-content .toctree-wrapper>p.caption,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+legend {
+    font-family: -apple-system, BlinkMacSystemFont, arial, sans-serif !important;
+}
+
+.body {
+    font-synthesis: none;
+    text-rendering: optimizeLegibility;
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: "liga", "case", "calt";
+}
+
+.btn {
+    border: None;
+    box-shadow: None;
+    padding: 8px 12px;
+}
+
+.btn:active {
+    box-shadow: None;
+    padding: 8px 12px;
 }

docs/index.rst

@@ -1,7 +1,7 @@
 Welcome to the Torchhd documentation!
 =====================================
 
-Torchhd is a Python library dedicated to *Hyperdimensional Computing* (also knwon as *Vector Symbolic Architectures*).
+Torchhd is a Python library dedicated to *Hyperdimensional Computing* (also known as *Vector Symbolic Architectures*).
 
 .. toctree::
    :glob:
@@ -15,7 +15,7 @@ Torchhd is a Python library dedicated to *Hyperdimensional Computing* (also knwo
    :maxdepth: 2
    :caption: Package Reference:
 
-   functional
+   torchhd
    embeddings
    structures
    datasets

docs/functional.rst renamed to docs/torchhd.rst

@@ -1,9 +1,9 @@
 .. _functional:
 
-torchhd.functional
+torchhd
 =========================
 
-.. currentmodule:: torchhd.functional 
+.. currentmodule:: torchhd
 
 This module consists of the basic hypervector generation functions and operations used on hypervectors.
 
@@ -14,6 +14,7 @@ Basis-hypervector sets
     :toctree: generated/
     :template: function.rst
 
+    empty_hv
     identity_hv
     random_hv
     level_hv
@@ -28,9 +29,10 @@ Operations
     :template: function.rst
 
     bind
-    unbind
     bundle
     permute
+    inverse
+    negative
     cleanup
     randsel
     multirandsel
@@ -44,9 +46,8 @@ Similarities
 .. autosummary::
     :toctree: generated/
     :template: function.rst
-
 
-    cosine_similarity
+    cos_similarity
     dot_similarity
     hamming_similarity
 
@@ -68,14 +69,28 @@ Encodings
     graph
 
 
+VSA Models
+------------------------
+
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    VSA_Model
+    BSC
+    MAP
+    .. HRR
+    FHRR
+
+
 Utilities
 ------------------------
 
 .. autosummary::
     :toctree: generated/
     :template: function.rst
-
 
+    as_vsa_model
     map_range
     value_to_index
     index_to_value

examples/emg_hand_gestures.py

@@ -7,7 +7,7 @@
 import torchmetrics
 from tqdm import tqdm
 
-from torchhd import functional
+import torchhd
 from torchhd import embeddings
 from torchhd.datasets import EMGHandGestures
 
@@ -40,12 +40,12 @@ def __init__(self, num_classes, timestamps, channels):
 
     def encode(self, x: torch.Tensor) -> torch.Tensor:
         signal = self.signals(x)
-        samples = functional.bind(signal, self.channels.weight.unsqueeze(0))
-        samples = functional.bind(signal, self.timestamps.weight.unsqueeze(1))
+        samples = torchhd.bind(signal, self.channels.weight.unsqueeze(0))
+        samples = torchhd.bind(signal, self.timestamps.weight.unsqueeze(1))
 
-        samples = functional.multiset(samples)
-        sample_hv = functional.ngrams(samples, n=N_GRAM_SIZE)
-        return functional.hard_quantize(sample_hv)
+        samples = torchhd.multiset(samples)
+        sample_hv = torchhd.ngrams(samples, n=N_GRAM_SIZE)
+        return torchhd.hard_quantize(sample_hv)
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         enc = self.encode(x)

examples/graphhd.py

@@ -4,12 +4,12 @@
 from tqdm import tqdm
 
 # Note: this example requires the torch_geometric library: https://pytorch-geometric.readthedocs.io
-import torch_geometric
+from torch_geometric.datasets import TUDataset
 
 # Note: this example requires the torchmetrics library: https://torchmetrics.readthedocs.io
 import torchmetrics
 
-from torchhd import functional
+import torchhd
 from torchhd import embeddings
 
 device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
@@ -20,7 +20,7 @@
 # for other available datasets see: https://pytorch-geometric.readthedocs.io/en/latest/notes/data_cheatsheet.html?highlight=tudatasets
 dataset = "MUTAG"
 
-graphs = torch_geometric.datasets.TUDataset("data", dataset)
+graphs = TUDataset("../data", dataset)
 train_size = int(0.7 * len(graphs))
 test_size = len(graphs) - train_size
 train_ld, test_ld = torch.utils.data.random_split(graphs, [train_size, test_size])
@@ -98,8 +98,8 @@ def encode(self, x):
 
         row, col = to_undirected(x.edge_index)
 
-        hvs = functional.bind(node_id_hvs[row], node_id_hvs[col])
-        return functional.multiset(hvs)
+        hvs = torchhd.bind(node_id_hvs[row], node_id_hvs[col])
+        return torchhd.multiset(hvs)
 
     def forward(self, x):
         enc = self.encode(x)

examples/hd_hashing.py

@@ -3,7 +3,7 @@
 # Note: this example requires the mmh3 library: https://github.com/hajimes/mmh3
 import mmh3
 
-from torchhd import functional
+import torchhd
 
 
 class HDHashing:
@@ -14,7 +14,7 @@ def __init__(self, levels: int, dimensions: int, device=None):
         self.dimensions = dimensions
         self.device = device
 
-        self.hvs = functional.circular_hv(levels, dimensions, device=device)
+        self.hvs = torchhd.circular_hv(levels, dimensions, device=device)
         self.servers = []
         self.server_hvs = []
         self.weight_by_server = {}
@@ -35,7 +35,7 @@ def request(self, value: str):
         # The next three lines simulate associative memory in HDC
         # It returns the value at the memory location (server)
         # that is most similar to the requested location (request).
-        similarity = functional.dot_similarity(hv, server_hvs)
+        similarity = torchhd.dot_similarity(hv, server_hvs)
         server_idx = torch.argmax(similarity).item()
         return self.servers[server_idx]
 

examples/language_recognition.py

@@ -7,7 +7,7 @@
 import torchmetrics
 from tqdm import tqdm
 
-from torchhd import functional
+import torchhd
 from torchhd import embeddings
 from torchhd.datasets import EuropeanLanguages as Languages
 
@@ -65,8 +65,8 @@ def __init__(self, num_classes, size):
 
     def encode(self, x):
         symbols = self.symbol(x)
-        sample_hv = functional.ngrams(symbols, n=3)
-        return functional.hard_quantize(sample_hv)
+        sample_hv = torchhd.ngrams(symbols, n=3)
+        return torchhd.hard_quantize(sample_hv)
 
     def forward(self, x):
         enc = self.encode(x)

examples/mnist.py

@@ -8,7 +8,7 @@
 import torchmetrics
 from tqdm import tqdm
 
-from torchhd import functional
+import torchhd
 from torchhd import embeddings
 
 
@@ -43,9 +43,9 @@ def __init__(self, num_classes, size):
 
     def encode(self, x):
         x = self.flatten(x)
-        sample_hv = functional.bind(self.position.weight, self.value(x))
-        sample_hv = functional.multiset(sample_hv)
-        return functional.hard_quantize(sample_hv)
+        sample_hv = torchhd.bind(self.position.weight, self.value(x))
+        sample_hv = torchhd.multiset(sample_hv)
+        return torchhd.hard_quantize(sample_hv)
 
     def forward(self, x):
         enc = self.encode(x)