BaseMCRTensor

class torchhd.BaseMCRTensor[source]

Base class for VSA Modular Composite Representations (MCR)

Proposed in Modular Composite Representation, this model works with modular integer vectors. The base class is used as template for the MCR and the Cyclic Group Representation (CGR), which is very similar to MCR but uses a different bundling operation.

classmethod __torch_function__(func, types, args=(), kwargs=None)[source]

This __torch_function__ implementation wraps subclasses such that methods called on subclasses return a subclass instance instead of a torch.Tensor instance.

One corollary to this is that you need coverage for torch.Tensor methods if implementing __torch_function__ for subclasses.

We recommend always calling super().__torch_function__ as the base case when doing the above.

While not mandatory, we recommend making __torch_function__ a classmethod.

bind(other: BaseMCRTensor) → BaseMCRTensor[source]

Bind the hypervector with other using circular convolution.

This produces a hypervector dissimilar to both.

Binding is used to associate information, for instance, to assign values to variables.

Parameters:

other (BaseMCRTensor) – other input hypervector

Shapes:

  • Self: \((*)\)

  • Other: \((*)\)

  • Output: \((*)\)

Examples:

>>> a, b = torchhd.BaseMCRTensor.random(2, 10, block_size=64)
>>> a
BaseMCRTensor([18, 55, 40, 62, 39, 26, 35, 24, 49, 41])
>>> b
BaseMCRTensor([46, 36, 21, 23, 25, 12, 29, 53, 54, 41])
>>> a.bind(b)
BaseMCRTensor([ 0, 27, 61, 21,  0, 38,  0, 13, 39, 18])
bundle(other: BaseMCRTensor) → BaseMCRTensor[source]

Bundle the hypervector with other

cosine_similarity(others: BaseMCRTensor, *, dtype=None) → Tensor[source]

Cosine similarity with other hypervectors

dot_similarity(others: BaseMCRTensor, *, dtype=None) → Tensor[source]

Based on ‘Manhattan Distance in a Modular Space’. Distance of two elements devided by the avearage distance of two random numbers.

classmethod empty(num_vectors: int, dimensions: int, *, block_size: int, generator=None, dtype=torch.int64, device=None, requires_grad=False) → BaseMCRTensor[source]

Creates a set of hypervectors representing empty sets.

When bundled with a hypervector \(x\), the result is \(x\). Because of the low precession of the MCR model an empty set cannot be explicitly represented, therefore the returned hypervectors are identical to random-hypervectors.

Parameters:

  • num_vectors (int) – the number of hypervectors to generate.

  • dimensions (int) – the dimensionality of the hypervectors.

  • block_size (int) – the number of elements per block which controls the angular granularity.

  • generator (torch.Generator, optional) – a pseudorandom number generator for sampling.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: int64.

  • 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.BaseMCRTensor.empty(3, 6, block_size=64)
BaseMCRTensor([[54,  3, 22, 27, 41, 21],
           [17, 31, 55,  3, 44, 52],
           [42, 37, 60, 54, 13, 41]])
classmethod identity(num_vectors: int, dimensions: int, *, block_size: int, dtype=torch.int64, device=None, requires_grad=False) → BaseMCRTensor[source]

Creates a set of identity hypervectors.

When bound with a random-hypervector \(x\), the result is \(x\).

Parameters:

  • num_vectors (int) – the number of hypervectors to generate.

  • dimensions (int) – the dimensionality of the hypervectors.

  • block_size (int) – the number of elements per block which controls the angular granularity.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if int64 depends on VSATensor.

  • 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.BaseMCRTensor.identity(3, 6, block_size=64)
BaseMCRTensor([[0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0]])
inverse() → BaseMCRTensor[source]

Invert the hypervector for binding.

Shapes:

  • Self: \((*)\)

  • Output: \((*)\)

Examples:

>>> a = torchhd.BaseMCRTensor.random(1, 10, block_size=64)
>>> a
BaseMCRTensor([[ 5, 30, 15, 43, 19, 36,  4, 14, 57, 34]])
>>> a.inverse()
BaseMCRTensor([[59, 34, 49, 21, 45, 28, 60, 50,  7, 30]])
multibind() → BaseMCRTensor[source]

Bind multiple hypervectors

multibundle() → BaseMCRTensor[source]

Bundle multiple hypervectors

normalize() → BaseMCRTensor[source]

Normalize the hypervector.

Each operation on MCR hypervectors ensures it remains normalized, so this returns a copy of self.

Shapes:

  • Self: \((*)\)

  • Output: \((*)\)

Examples:

>>> x = torchhd.BaseMCRTensor.random(4, 6, block_size=64).multibundle()
>>> x
BaseMCRTensor([28, 27, 20, 44, 57, 18])
>>> x.normalize()
BaseMCRTensor([28, 27, 20, 44, 57, 18])
permute(shifts: int = 1) → BaseMCRTensor[source]

Permute the hypervector.

The permutation operator is commonly used to assign an order to hypervectors.

Parameters:

shifts (int, optional) – The number of places by which the elements of the tensor are shifted.

Shapes:

  • Self: \((*)\)

  • Output: \((*)\)

Examples:

>>> a = torchhd.BaseMCRTensor.random(1, 10, block_size=64)
>>> a
BaseMCRTensor([[33, 24,  1, 36,  2, 57, 11, 59, 33,  3]])
>>> a.permute(4)
BaseMCRTensor([[11, 59, 33,  3, 33, 24,  1, 36,  2, 57]])
classmethod random(num_vectors: int, dimensions: int, *, block_size: int, generator=None, dtype=torch.int64, device=None, requires_grad=False) → BaseMCRTensor[source]

Creates a set of random independent hypervectors.

The resulting hypervectors sample uniformly random integers between 0 and block_size.

Parameters:

  • num_vectors (int) – the number of hypervectors to generate.

  • dimensions (int) – the dimensionality of the hypervectors.

  • block_size (int) – the number of elements per block which controls the angular granularity.

  • generator (torch.Generator, optional) – a pseudorandom number generator for sampling.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: int64.

  • 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.BaseMCRTensor.random(3, 6, block_size=64)
BaseMCRTensor([[ 7,  1, 39,  8, 55, 22],
           [51, 38, 59, 45, 13, 29],
           [19, 26, 30,  5, 15, 51]])
>>> torchhd.BaseMCRTensor.random(3, 6, block_size=128, dtype=torch.float32)
BaseMCRTensor([[116.,  25., 100.,  10.,  21.,  86.],
           [ 69.,  49.,   2.,  56.,  78.,  70.],
           [ 77.,  47.,  37., 106.,   8.,  30.]])