Implement Vector-Derived Transformation Binding (#149)

* WIP implementing VTB model

* [github-action] formatting fixes

* Implement efficient binding method and add tests

* [github-action] formatting fixes

* Update documentation

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: mikeheddes

docs/torchhd.rst

@@ -85,6 +85,7 @@ VSA Models
     MAPTensor
     HRRTensor
     FHRRTensor
+    VTBTensor
 
 
 Utilities

torchhd/__init__.py

@@ -34,6 +34,7 @@
 from torchhd.tensors.map import MAPTensor
 from torchhd.tensors.hrr import HRRTensor
 from torchhd.tensors.fhrr import FHRRTensor
+from torchhd.tensors.vtb import VTBTensor
 
 from torchhd.functional import (
     ensure_vsa_tensor,
@@ -84,6 +85,7 @@
     "MAPTensor",
     "HRRTensor",
     "FHRRTensor",
+    "VTBTensor",
     "functional",
     "embeddings",
     "structures",

torchhd/embeddings.py

@@ -806,9 +806,9 @@ def __init__(
         self.out_features = out_features
         self.vsa = vsa
 
-        if vsa not in {"MAP", "HRR"}:
+        if vsa not in {"MAP", "HRR", "VTB"}:
             raise ValueError(
-                f"Projection embedding only supports MAP and HRR but provided: {vsa}"
+                f"Projection embedding supports MAP, HRR, VTB but provided: {vsa}"
             )
 
         self.weight = nn.parameter.Parameter(
@@ -877,9 +877,9 @@ def __init__(
         self.out_features = out_features
         self.vsa = vsa
 
-        if vsa not in {"MAP", "HRR"}:
+        if vsa not in {"MAP", "HRR", "VTB"}:
             raise ValueError(
-                f"Sinusoid embedding only supports MAP and HRR but provided: {vsa}"
+                f"Sinusoid embedding supports MAP, HRR, VTB but provided: {vsa}"
             )
 
         self.weight = nn.parameter.Parameter(

torchhd/functional.py

@@ -32,6 +32,7 @@
 from torchhd.tensors.map import MAPTensor
 from torchhd.tensors.hrr import HRRTensor
 from torchhd.tensors.fhrr import FHRRTensor
+from torchhd.tensors.vtb import VTBTensor
 from torchhd.types import VSAOptions
 
 
@@ -82,6 +83,8 @@ def get_vsa_tensor_class(vsa: VSAOptions) -> Type[VSATensor]:
         return HRRTensor
     elif vsa == "FHRR":
         return FHRRTensor
+    elif vsa == "VTB":
+        return VTBTensor
 
     raise ValueError(f"Provided VSA model is not supported, specified: {vsa}")
 
@@ -540,9 +543,9 @@ def circular(
     """
     vsa_tensor = get_vsa_tensor_class(vsa)
 
-    if vsa_tensor == HRRTensor:
+    if vsa == "HRR" or vsa == "VTB":
         raise ValueError(
-            "The circular hypervectors don't currently work with the HRR model. We are not sure why, if you have any insight that could help please share it at: https://github.com/hyperdimensional-computing/torchhd/issues/108."
+            "The circular hypervectors do currently not work with the HRR and VTB models. We are not sure why, if you have any insight that could help please share it at: https://github.com/hyperdimensional-computing/torchhd/issues/108."
         )
 
     # convert from normalized "randomness" variable r to