Add Cyclic Group Representation (CGR) class (#182)

* Add BaseMCRTensor

Add a new base class to support future implementation of variations of
MCR proposals.

* Fix bug in BaseMCRTensor:__torch_function__()

There is a bug when args is a collection of collections instead of a
plain tuple. In this case, the old args parsing was unable to search for
block_size in nested structures containing BaseMCRTensor.

For instance, let `a` and `b` be BaseMCRTensor variables. Calling
`torch.stack((a, b))` results in error, as the `args` received in
`__torch_function__()` is a nested tuple.

* Add CGRTensor

Add a new VSA class named Cyclic Group Representation (CGR). This class
is similar to MCR, but differs in bundling.

* Add CGRTensor to functional embeddings

Allow its usage in level and circular embeddings as done with MCRTensor.

* Fix CGR bundle

Ensure both inputs are in the same shape.

* Add CGR into tests

The CGR should behave almost the same as MCR, but diverges in bundling.
Implement a custom bundling test for it.

* Use Tensor.dim() in CGRTensor

Shorter syntax and more readable.

* Remove asserts in CGR/MCR classes

No need to check block size in CGR/MCR functions as the
__torch_function__() in BaseMCRTensor already checks it.

* Improve exception in BaseMCRTensor if multiple block_sizes

- Raise ValueError instead of RuntimeError

* Add CGRTensor to docs

Include CGRTensor in the README and in the built docs.

* Add BaseMCRTensor to docs

* Fix typo in README.md

* Improve documentation for MCRTensor and CGRTensor

Replicate function signatures in inherited classes (MCRTensor and
CGRTensor) from their parent class (BaseMCRTensor) to let sphinx
print the documentation of each parent function.

Author: Zeldax64

README.md

@@ -95,6 +95,7 @@ Currently, the library supports the following HDC/VSA models:
 - [Holographic Reduced Representations (HRR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.HRRTensor.html)
 - [Fourier Holographic Reduced Representations (FHRR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.FHRRTensor.html)
 - [Binary Sparse Block Codes (B-SBC)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.BSBCTensor.html)
+- [Cyclic Group Representation (CGR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.CGRTensor.html)
 - [Modular Composite Representation (MCR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.MCRTensor.html)
 - [Vector-Derived Transformation Binding (VTB)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.VTBTensor.html)
 

docs/torchhd.rst

@@ -10,7 +10,7 @@ This module consists of the basic hypervector generation functions and operation
 Basis-hypervector sets
 ----------------------------------
 
-.. autosummary:: 
+.. autosummary::
     :toctree: generated/
     :template: function.rst
 
@@ -20,7 +20,7 @@ Basis-hypervector sets
     level
     thermometer
     circular
-    
+
 
 Operations
 --------------------
@@ -51,7 +51,7 @@ Similarities
 .. autosummary::
     :toctree: generated/
     :template: function.rst
-    
+
     cosine_similarity
     dot_similarity
     hamming_similarity
@@ -87,7 +87,9 @@ VSA Models
     HRRTensor
     FHRRTensor
     BSBCTensor
+    BaseMCRTensor
     MCRTensor
+    CGRTensor
     VTBTensor
 
 
@@ -97,7 +99,7 @@ Utilities
 .. autosummary::
     :toctree: generated/
     :template: function.rst
-    
+
     ensure_vsa_tensor
     map_range
     value_to_index

torchhd/__init__.py

@@ -37,7 +37,9 @@
 from torchhd.tensors.fhrr import FHRRTensor
 from torchhd.tensors.bsbc import BSBCTensor
 from torchhd.tensors.vtb import VTBTensor
+from torchhd.tensors.basemcr import BaseMCRTensor
 from torchhd.tensors.mcr import MCRTensor
+from torchhd.tensors.cgr import CGRTensor
 
 from torchhd.functional import (
     ensure_vsa_tensor,
@@ -91,7 +93,9 @@
     "FHRRTensor",
     "BSBCTensor",
     "VTBTensor",
+    "BaseMCRTensor",
     "MCRTensor",
+    "CGRTensor",
     "functional",
     "embeddings",
     "structures",

torchhd/functional.py

@@ -36,6 +36,7 @@
 from torchhd.tensors.bsbc import BSBCTensor
 from torchhd.tensors.vtb import VTBTensor
 from torchhd.tensors.mcr import MCRTensor
+from torchhd.tensors.cgr import CGRTensor
 from torchhd.types import VSAOptions
 
 
@@ -93,6 +94,8 @@ def get_vsa_tensor_class(vsa: VSAOptions) -> Type[VSATensor]:
         return VTBTensor
     elif vsa == "MCR":
         return MCRTensor
+    elif vsa == "CGR":
+        return CGRTensor
 
     raise ValueError(f"Provided VSA model is not supported, specified: {vsa}")
 
@@ -361,7 +364,7 @@ def level(
         device=span_hv.device,
     ).as_subclass(vsa_tensor)
 
-    if vsa == "BSBC" or vsa == "MCR":
+    if vsa == "BSBC" or vsa == "MCR" or vsa == "CGR":
         hv.block_size = span_hv.block_size
 
     for i in range(num_vectors):
@@ -588,7 +591,7 @@ def circular(
         device=span_hv.device,
     ).as_subclass(vsa_tensor)
 
-    if vsa == "BSBC" or vsa == "MCR":
+    if vsa == "BSBC" or vsa == "MCR" or vsa == "CGR":
         hv.block_size = span_hv.block_size
 
     mutation_history = deque()