Add methods to form thermometer codes (#93)

* Add methods to form thermometer codes

* Add revisions after review

* Formatting and micro optimizations

* Modify code to allow flexible number of hypervectors

* [github-action] formatting fixes

* Modify Thermometer embedding to accept HD/VSA model type

* Remove model option from embeddings

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

Author: 3 people

docs/embeddings.rst

@@ -12,6 +12,7 @@ torchhd.embeddings
     Identity
     Random
     Level
+    Thermometer
     Circular
     Projection
     Sinusoid

docs/torchhd.rst

@@ -18,6 +18,7 @@ Basis-hypervector sets
     identity_hv
     random_hv
     level_hv
+    thermometer_hv
     circular_hv
 
 

torchhd/__init__.py

@@ -16,6 +16,7 @@
     identity_hv,
     random_hv,
     level_hv,
+    thermometer_hv,
     circular_hv,
     bind,
     bundle,
@@ -62,6 +63,7 @@
     "identity_hv",
     "random_hv",
     "level_hv",
+    "thermometer_hv",
     "circular_hv",
     "bind",
     "bundle",

torchhd/embeddings.py

@@ -1,16 +1,19 @@
 import math
+from typing import Type, Union
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
 from torch import Tensor
 
 import torchhd.functional as functional
+from torchhd.base import VSA_Model
 from torchhd.map import MAP
 
 __all__ = [
     "Identity",
     "Random",
     "Level",
+    "Thermometer",
     "Circular",
     "Projection",
     "Sinusoid",
@@ -169,6 +172,66 @@ def forward(self, input: torch.Tensor) -> torch.Tensor:
         return super(Level, self).forward(indices).as_subclass(MAP)
 
 
+class Thermometer(nn.Embedding):
+    """Embedding wrapper around :func:`~torchhd.functional.thermometer_hv`.
+
+    Class inherits from `Embedding <https://pytorch.org/docs/stable/generated/torch.nn.Embedding.html>`_ and supports the same keyword arguments.
+
+    Args:
+        num_embeddings (int): the number of hypervectors to generate.
+        embedding_dim (int): the dimensionality of the hypervectors.
+        low (float, optional): The lower bound of the real number range that the levels represent. Default: ``0.0``
+        high (float, optional): The upper bound of the real number range that the levels represent. Default: ``1.0``
+        requires_grad (bool, optional): If autograd should record operations on the returned tensor. Default: ``False``.
+
+    Examples::
+
+        >>> emb = embeddings.Thermometer(11, 10, low=-1, high=2)
+        >>> x = torch.FloatTensor([0.3, 1.9, -0.8])
+        >>> emb(x)
+        tensor([[ 1.,  1.,  1.,  1., -1., -1., -1., -1., -1., -1.],
+                [ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.],
+                [ 1., -1., -1., -1., -1., -1., -1., -1., -1., -1.]])
+
+    """
+
+    def __init__(
+        self,
+        num_embeddings,
+        embedding_dim,
+        low=0.0,
+        high=1.0,
+        requires_grad=False,
+        **kwargs
+    ):
+        self.low_value = low
+        self.high_value = high
+
+        super(Thermometer, self).__init__(num_embeddings, embedding_dim, **kwargs)
+        self.weight.requires_grad = requires_grad
+
+    def reset_parameters(self):
+        factory_kwargs = {
+            "device": self.weight.data.device,
+            "dtype": self.weight.data.dtype,
+        }
+
+        self.weight.data.copy_(
+            functional.thermometer_hv(
+                self.num_embeddings, self.embedding_dim, **factory_kwargs
+            )
+        )
+
+        self._fill_padding_idx_with_zero()
+
+    def forward(self, input: torch.Tensor) -> torch.Tensor:
+        indices = functional.value_to_index(
+            input, self.low_value, self.high_value, self.num_embeddings
+        ).clamp(0, self.num_embeddings - 1)
+
+        return super(Thermometer, self).forward(indices).as_subclass(MAP)
+
+
 class Circular(nn.Embedding):
     """Embedding wrapper around :func:`~torchhd.functional.circular_hv`.
 

torchhd/functional.py

@@ -16,6 +16,7 @@
     "identity_hv",
     "random_hv",
     "level_hv",
+    "thermometer_hv",
     "circular_hv",
     "bind",
     "bundle",
@@ -326,6 +327,100 @@ def level_hv(
     return hv.as_subclass(model)
 
 
+def thermometer_hv(
+    num_vectors: int,
+    dimensions: int,
+    model: Type[VSA_Model] = MAP,
+    *,
+    requires_grad=False,
+    **kwargs,
+) -> VSA_Model:
+    """Creates a thermometer code for given dimensionality.
+
+    Implements similarity-preserving hypervectors as described in `Sparse Binary Distributed Encoding of Scalars <https://doi.org/10.1615/J%20Automat%20Inf%20Scien.v37.i6.20>`_.
+
+    Args:
+        num_vectors (int): the number of hypervectors to generate.
+        dimensions (int): the dimensionality of the hypervectors.
+        model: (``Type[VSA_Model]``, optional): specifies the hypervector type to be instantiated. Default: ``torchhd.MAP``.
+        dtype (``torch.dtype``, optional): the desired data type of returned tensor. Default: if ``None`` depends on VSA_Model.
+        device (``torch.device``, optional):  the desired device of returned tensor. Default: if ``None``, uses the current device for the default tensor type (see torch.set_default_tensor_type()). ``device`` will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
+        requires_grad (bool, optional): If autograd should record operations on the returned tensor. Default: ``False``.
+
+    Examples::
+
+        >>> torchhd.thermometer_hv(7, 6, torchhd.BSC)
+        tensor([[False, False, False, False, False, False],
+                [ True, False, False, False, False, False],
+                [ True,  True, False, False, False, False],
+                [ True,  True,  True, False, False, False],
+                [ True,  True,  True,  True, False, False],
+                [ True,  True,  True,  True,  True, False],
+                [ True,  True,  True,  True,  True,  True]])
+
+        >>> torchhd.thermometer_hv(4, 6, torchhd.MAP)
+        tensor([[-1., -1., -1., -1., -1., -1.],
+                [ 1.,  1., -1., -1., -1., -1.],
+                [ 1.,  1.,  1.,  1., -1., -1.],
+                [ 1.,  1.,  1.,  1.,  1.,  1.]])
+
+        >>> torchhd.thermometer_hv(6, 6, torchhd.FHRR)
+        tensor([[-1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j],
+                [ 1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j],
+                [ 1.+0.j,  1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j],
+                [ 1.+0.j,  1.+0.j,  1.+0.j, -1.+0.j, -1.+0.j, -1.+0.j],
+                [ 1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j, -1.+0.j, -1.+0.j],
+                [ 1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j, -1.+-0.j]])
+
+    """
+    # Check if the requested number of vectors can be accommodated
+    if num_vectors > dimensions + 1:
+        raise ValueError(
+            f"For the given dimensionality: {dimensions}, the thermometer code cannot create more than {dimensions+1} hypervectors."
+        )
+    else:
+        # Based on num_vectors and dimensions compute step between neighboring hypervectors
+        step = 0
+        if num_vectors > 1:
+            step = (dimensions) // (num_vectors - 1)
+
+    # generate a random vector as a placeholder to get dtype and device
+    rand_hv = model.random_hv(
+        1,
+        dimensions,
+        **kwargs,
+    )
+
+    if model == BSC:
+        # Use binary vectors
+        hv = torch.zeros(
+            num_vectors,
+            dimensions,
+            dtype=rand_hv.dtype,
+            device=rand_hv.device,
+        )
+    elif (model == MAP) | (model == FHRR):
+        # Use bipolar vectors
+        hv = torch.full(
+            (
+                num_vectors,
+                dimensions,
+            ),
+            -1,
+            dtype=rand_hv.dtype,
+            device=rand_hv.device,
+        )
+    else:
+        raise ValueError(f"{model} HD/VSA model is not defined.")
+
+    # Create hypervectors using the obtained step
+    for i in range(1, num_vectors):
+        hv[i, 0 : i * step] = 1
+
+    hv.requires_grad = requires_grad
+    return hv.as_subclass(model)
+
+
 def circular_hv(
     num_vectors: int,
     dimensions: int,