Add aliasing for basic function (#52)

Author: mikeheddes

README.md

@@ -45,18 +45,18 @@ import torch, torchhd
 d = 10000  # number of dimensions
 
 # create the hypervectors for each symbol
-country = torchhd.functional.random_hv(1, d)
-capital = torchhd.functional.random_hv(1, d)
-currency = torchhd.functional.random_hv(1, d)
+country = torchhd.random_hv(1, d)
+capital = torchhd.random_hv(1, d)
+currency = torchhd.random_hv(1, d)
 
-usa = torchhd.functional.random_hv(1, d)  # United States
-mex = torchhd.functional.random_hv(1, d)  # Mexico
+usa = torchhd.random_hv(1, d)  # United States
+mex = torchhd.random_hv(1, d)  # Mexico
 
-wdc = torchhd.functional.random_hv(1, d)  # Washington D.C.
-mxc = torchhd.functional.random_hv(1, d)  # Mexico City
+wdc = torchhd.random_hv(1, d)  # Washington D.C.
+mxc = torchhd.random_hv(1, d)  # Mexico City
 
-usd = torchhd.functional.random_hv(1, d)  # US Dollar
-mxn = torchhd.functional.random_hv(1, d)  # Mexican Peso
+usd = torchhd.random_hv(1, d)  # US Dollar
+mxn = torchhd.random_hv(1, d)  # Mexican Peso
 
 # create country representations
 keys = torch.cat([country, capital, currency], dim=0)
@@ -67,10 +67,10 @@ US = torchhd.functional.hash_table(keys, us_values)
 mx_values = torch.cat([mex, mxc, mxn])
 MX = torchhd.functional.hash_table(keys, mx_values)
 
-MX_US = torchhd.functional.bind(US, MX)
+MX_US = torchhd.bind(US, MX)
 
 # query for the dollar of mexico
-usd_of_mex = torchhd.functional.bind(MX_US, usd)
+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/__init__.py

@@ -3,9 +3,26 @@
 import torchhd.structures as structures
 import torchhd.datasets as datasets
 
+from torchhd.functional import (
+    identity_hv,
+    random_hv,
+    level_hv,
+    circular_hv,
+    bind,
+    bundle,
+    permute,
+)
+
 __all__ = [
     "functional",
     "embeddings",
     "structures",
     "datasets",
+    "identity_hv",
+    "random_hv",
+    "level_hv",
+    "circular_hv",
+    "bind",
+    "bundle",
+    "permute",
 ]

torchhd/functional.py

@@ -44,6 +44,8 @@ def identity_hv(
     """Creates a set of identity hypervector.
 
     When bound with a random-hypervector :math:`x`, the result is :math:`x`.
+    
+    Aliased as ``torchhd.identity_hv``.
 
     Args:
         num_embeddings (int): the number of hypervectors to generate.
@@ -93,6 +95,8 @@ def random_hv(
 
     The resulting hypervectors are sampled uniformly at random from the ``embedding_dim``-dimensional hyperspace.
 
+    Aliased as ``torchhd.random_hv``.
+
     Args:
         num_embeddings (int): the number of hypervectors to generate.
         embedding_dim (int): the dimensionality of the hypervectors.
@@ -153,6 +157,8 @@ def level_hv(
     Implements level-hypervectors as an interpolation between random-hypervectors as described in `An Extension to Basis-Hypervectors for Learning from Circular Data in Hyperdimensional Computing <https://arxiv.org/abs/2205.07920>`_.
     The first and last hypervector in the generated set are quasi-orthogonal.
 
+    Aliased as ``torchhd.level_hv``.
+
     Args:
         num_embeddings (int): the number of hypervectors to generate.
         embedding_dim (int): the dimensionality of the hypervectors.
@@ -249,6 +255,8 @@ def circular_hv(
     Implements circular-hypervectors based on level-hypervectors as described in `An Extension to Basis-Hypervectors for Learning from Circular Data in Hyperdimensional Computing <https://arxiv.org/abs/2205.07920>`_.
     Any hypervector is quasi-orthogonal to the hypervector opposite site of the circle.
 
+    Aliased as ``torchhd.circular_hv``.
+
     Args:
         num_embeddings (int): the number of hypervectors to generate.
         embedding_dim (int): the dimensionality of the hypervectors.
@@ -366,6 +374,8 @@ def bind(input: Tensor, other: Tensor, *, out=None) -> Tensor:
 
         \otimes: \mathcal{H} \times \mathcal{H} \to \mathcal{H}
 
+    Aliased as ``torchhd.bind``.
+
     Args:
         input (Tensor): input hypervector
         other (Tensor): other input hypervector
@@ -406,6 +416,8 @@ def bundle(input: Tensor, other: Tensor, *, out=None) -> Tensor:
 
         \oplus: \mathcal{H} \times \mathcal{H} \to \mathcal{H}
 
+    Aliased as ``torchhd.bundle``.
+
     Args:
         input (Tensor): input hypervector
         other (Tensor): other input hypervector
@@ -446,6 +458,8 @@ def permute(input: Tensor, *, shifts=1, dims=-1) -> Tensor:
 
         \Pi: \mathcal{H} \to \mathcal{H}
 
+    Aliased as ``torchhd.permute``.
+
     Args:
         input (Tensor): input hypervector
         shifts (int or tuple of ints, optional): The number of places by which the elements of the tensor are shifted. If shifts is a tuple, dims must be a tuple of the same size, and each dimension will be rolled by the corresponding value.