Add sparsity parameter to level and circular hypervectors (#56)

* Add sparsity parameter to level and circular-hv sets

* Add sparsity parameter to level and circular-hv sets

* Add to documentation

* Add tests

Co-authored-by: mikeheddes <mikeheddes@gmail.com>

Author: igordeoliveiranunes

torchhd/functional.py

@@ -146,6 +146,7 @@ def level_hv(
     num_embeddings: int,
     embedding_dim: int,
     *,
+    sparsity=0.5,
     randomness=0.0,
     generator=None,
     dtype=None,
@@ -162,6 +163,7 @@ def level_hv(
     Args:
         num_embeddings (int): the number of hypervectors to generate.
         embedding_dim (int): the dimensionality of the hypervectors.
+        sparsity (float, optional): the expected fraction of elements to be +1. Default: ``0.5``.
         randomness (float, optional): r-value to interpolate between level at ``0.0`` and random-hypervectors at ``1.0``. Default: ``0.0``.
         generator (``torch.Generator``, optional): a pseudorandom number generator for sampling.
         dtype (``torch.dtype``, optional): the desired data type of returned tensor. Default: if ``None``, uses a global default (see ``torch.set_default_tensor_type()``).
@@ -204,6 +206,7 @@ def level_hv(
         int(math.ceil(span + 1)),
         embedding_dim,
         generator=generator,
+        sparsity=sparsity,
         dtype=dtype,
         device=device,
     )
@@ -244,6 +247,7 @@ def circular_hv(
     num_embeddings: int,
     embedding_dim: int,
     *,
+    sparsity=0.5,
     randomness=0.0,
     generator=None,
     dtype=None,
@@ -260,6 +264,7 @@ def circular_hv(
     Args:
         num_embeddings (int): the number of hypervectors to generate.
         embedding_dim (int): the dimensionality of the hypervectors.
+        sparsity (float, optional): the expected fraction of elements to be +1. Default: ``0.5``.
         randomness (float, optional): r-value to interpolate between circular at ``0.0`` and random-hypervectors at ``1.0``. Default: ``0.0``.
         generator (``torch.Generator``, optional): a pseudorandom number generator for sampling.
         dtype (``torch.dtype``, optional): the desired data type of returned tensor. Default: if ``None``, uses a global default (see ``torch.set_default_tensor_type()``).
@@ -307,6 +312,7 @@ def circular_hv(
         int(math.ceil(span + 1)),
         embedding_dim,
         generator=generator,
+        sparsity=sparsity,
         dtype=dtype,
         device=device,
     )

torchhd/tests/test_basis_hv.py

@@ -117,14 +117,14 @@ def test_sparsity(self):
         generator = torch.Generator()
         generator.manual_seed(2147483644)
 
-        hv = functional.random_hv(100, 10000, generator=generator, sparsity=1)
+        hv = functional.random_hv(1000, 10000, generator=generator, sparsity=1)
         assert torch.all(hv == 1).item()
 
-        hv = functional.random_hv(100, 10000, generator=generator, sparsity=0)
+        hv = functional.random_hv(1000, 10000, generator=generator, sparsity=0)
         assert torch.all(hv == -1).item()
 
-        hv = functional.random_hv(100, 10000, generator=generator, sparsity=0.5)
-        assert between(torch.sum(hv == -1).div(10000 * 100).item(), 0.499, 0.501)
+        hv = functional.random_hv(1000, 10000, generator=generator, sparsity=0.5)
+        assert between(torch.sum(hv == -1).div(10000 * 1000).item(), 0.499, 0.501)
 
     def test_orthogonality(self):
         generator = torch.Generator()
@@ -257,6 +257,23 @@ def test_value(self):
             (0.249 < sims_diff) & (sims_diff < 0.251)
         ).item(), "similarity decreases linearly"
 
+    def test_sparsity(self):
+        generator = torch.Generator()
+        generator.manual_seed(2147287646)
+
+        hv = functional.level_hv(1000, 10000, generator=generator, sparsity=1)
+        assert torch.all(hv == 1).item()
+
+        hv = functional.level_hv(1000, 10000, generator=generator, sparsity=0)
+        assert torch.all(hv == -1).item()
+
+        sparsity = [None] * 100
+        for i in range(100):
+            hv = functional.level_hv(100, 10000, generator=generator, sparsity=0.5)
+            sparsity[i] = torch.sum(hv == -1).div(10000 * 100)
+        assert between(torch.vstack(sparsity).mean().item(), 0.499, 0.501)
+
+
     def test_device(self):
         device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
         hv = functional.level_hv(3, 52, device=device)
@@ -368,6 +385,22 @@ def test_value(self):
             (0.249 < abs_sims_diff) & (abs_sims_diff < 0.251)
         ).item(), "similarity decreases linearly"
 
+    def test_sparsity(self):
+        generator = torch.Generator()
+        generator.manual_seed(2147487649)
+
+        hv = functional.circular_hv(100, 10000, generator=generator, sparsity=1)
+        assert torch.all(hv == 1).item()
+
+        hv = functional.circular_hv(100, 10000, generator=generator, sparsity=0)
+        assert torch.all(hv == -1).item()
+
+        sparsity = [None] * 100
+        for i in range(100):
+            hv = functional.circular_hv(100, 10000, generator=generator, sparsity=0.5)
+            sparsity[i] = torch.sum(hv == -1).div(10000 * 100)
+        assert between(torch.vstack(sparsity).mean().item(), 0.499, 0.501)
+
     def test_device(self):
         device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
         hv = functional.circular_hv(3, 52, device=device)