BSCTensor

class torchhd.BSCTensor[source]

Binary Spatter Codes

Proposed in Binary spatter-coding of ordered K-tuples, this model works with binary valued hypervectors.

bind(other: BSCTensor) → BSCTensor[source]

Bind the hypervector with other using XOR.

This produces a hypervector dissimilar to both.

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

Parameters:

other (BSC) – other input hypervector

Shapes:

  • Self: \((*)\)

  • Other: \((*)\)

  • Output: \((*)\)

Examples:

>>> a, b = torchhd.BSCTensor.random(2, 10)
>>> a
tensor([ True, False,  True,  True, False,  True, False, False,  True, False])
>>> b
tensor([ True, False, False, False, False,  True, False, False, False, False])
>>> a.bind(b)
tensor([False, False,  True,  True, False, False, False, False,  True, False])

>>> a, b = torchhd.BSCTensor.random(2, 10, dtype=torch.long)
>>> a
tensor([1, 0, 0, 1, 0, 1, 0, 0, 0, 0])
>>> b
tensor([0, 0, 0, 1, 0, 0, 1, 0, 1, 0])
>>> a.bind(b)
tensor([1, 0, 0, 0, 0, 1, 1, 0, 1, 0])
bundle(other: BSCTensor, *, generator: Generator | None = None) → BSCTensor[source]

Bundle the hypervector with other using majority voting.

This produces a hypervector maximally similar to both.

The bundling operation is used to aggregate information into a single hypervector.

Ties in the majority vote are broken at random. For a deterministic result provide a random number generator.

Parameters:

  • other (BSC) – other input hypervector

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

Shapes:

  • Self: \((*)\)

  • Other: \((*)\)

  • Output: \((*)\)

Examples:

>>> a, b = torchhd.BSCTensor.random(2, 10)
>>> a
tensor([ True, False,  True, False, False,  True,  True, False,  True, False])
>>> b
tensor([ True, False, False,  True,  True, False, False,  True, False,  True])
>>> a.bundle(b)
tensor([ True, False,  True,  True, False,  True,  True, False, False, False])

>>> a, b = torchhd.BSCTensor.random(2, 10, dtype=torch.long)
>>> a
tensor([1, 0, 1, 1, 1, 0, 1, 1, 1, 1])
>>> b
tensor([1, 1, 1, 0, 0, 0, 1, 1, 0, 0])
>>> a.bundle(b)
tensor([1, 0, 1, 0, 0, 0, 1, 1, 0, 1])
cosine_similarity(others: BSCTensor, *, dtype=None) → Tensor[source]

Cosine similarity with other hypervectors.

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

Inner product with other hypervectors.

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

Creates a set of hypervectors representing empty sets.

When bundled with a random-hypervector \(x\), the result is \(\sim x\). Because of the low precession of the BSC 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.

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

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None 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.BSCTensor.empty(3, 6)
tensor([[False, False, False, False,  True,  True],
        [False,  True, False, False,  True,  True],
        [ True, False,  True,  True, False, False]])

>>> torchhd.BSCTensor.empty(3, 6, dtype=torch.long)
tensor([[0, 1, 0, 1, 0, 1],
        [0, 0, 1, 1, 0, 1],
        [0, 1, 1, 0, 1, 1]])
classmethod identity(num_vectors: int, dimensions: int, *, dtype=torch.bool, device=None, requires_grad=False) → BSCTensor[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.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None 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.BSCTensor.identity(3, 6)
tensor([[False, False, False, False, False, False],
        [False, False, False, False, False, False],
        [False, False, False, False, False, False]])

>>> torchhd.BSCTensor.identity(3, 6, dtype=torch.long)
tensor([[0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0]])
inverse() → BSCTensor[source]

Invert the hypervector for binding.

Each hypervector in BSC is its own inverse, so this returns a copy of self.

Shapes:

  • Self: \((*)\)

  • Output: \((*)\)

Examples:

>>> a = torchhd.BSCTensor.random(1, 10)
>>> a
tensor([[False, False, False,  True,  True, False, False,  True,  True, False]])
>>> a.inverse()
tensor([[False, False, False,  True,  True, False, False,  True,  True, False]])

>>> a = torchhd.BSCTensor.random(1, 10, dtype=torch.long)
>>> a
tensor([[0, 1, 0, 1, 1, 1, 1, 0, 1, 1]])
>>> a.inverse()
tensor([[0, 1, 0, 1, 1, 1, 1, 0, 1, 1]])
multibind() → BSCTensor[source]

Bind multiple hypervectors.

multibundle(*, generator: Generator | None = None) → BSCTensor[source]

Bundle multiple hypervectors.

negative() → BSCTensor[source]

Negate the hypervector for the bundling inverse.

Shapes:

  • Self: \((*)\)

  • Output: \((*)\)

Examples:

>>> a = torchhd.BSCTensor.random(1, 10)
>>> a
tensor([[ True,  True,  True,  True, False, False, False,  True,  True,  True]])
>>> a.negative()
tensor([[False, False, False, False,  True,  True,  True, False, False, False]])

>>> a = torchhd.BSCTensor.random(1, 10, dtype=torch.long)
>>> a
tensor([[0, 1, 0, 1, 0, 0, 1, 1, 0, 1]])
>>> a.negative()
tensor([[1, 0, 1, 0, 1, 1, 0, 0, 1, 0]])
permute(shifts: int = 1) → BSCTensor[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.BSCTensor.random(1, 10)
>>> a
tensor([[ True, False, False, False, False, False, False, False, False, False]])
>>> a.permute()
tensor([[False,  True, False, False, False, False, False, False, False, False]])

>>> a = torchhd.BSCTensor.random(1, 10, dtype=torch.long)
>>> a
tensor([[1, 1, 0, 0, 1, 1, 0, 0, 1, 1]])
>>> a.permute()
tensor([[1, 1, 1, 0, 0, 1, 1, 0, 0, 1]])
classmethod random(num_vectors: int, dimensions: int, *, sparsity=0.5, generator=None, dtype=torch.bool, device=None, requires_grad=False) → BSCTensor[source]

Creates a set of random independent hypervectors.

The resulting hypervectors are sampled uniformly at random from the dimensions-dimensional hyperspace.

Parameters:

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

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

  • sparsity (float, optional) – the expected fraction of elements to be in-active. Has no effect on complex hypervectors. Default: 0.5.

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

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None 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.BSCTensor.random(3, 6)
tensor([[ True, False, False, False,  True,  True],
        [False, False,  True, False, False, False],
        [False, False,  True,  True, False, False]])

>>> torchhd.BSCTensor.random(3, 6, sparsity=0.1)
tensor([[ True,  True,  True,  True,  True,  True],
        [False,  True,  True,  True,  True,  True],
        [ True,  True,  True,  True,  True,  True]])

>>> torchhd.BSCTensor.random(3, 6, dtype=torch.long)
tensor([[1, 1, 0, 0, 0, 1],
        [0, 1, 0, 0, 1, 1],
        [0, 1, 1, 0, 0, 0]])