Functional Module¶

The bayes_hdc.functional module provides core HDC operations as pure functions.

BSC Operations¶

bayes_hdc.functional.bind_bsc(x, y)[source]¶

Bind two hypervectors using XOR for Binary Spatter Codes.

Binding creates a new hypervector that is dissimilar to both inputs. XOR is its own inverse, so unbinding is identical to binding.

Parameters:

x (Array) – Binary hypervector of shape (…, d)
y (Array) – Binary hypervector of shape (…, d)

Returns:

Bound hypervector of shape (…, d), dissimilar to both x and y

Return type:

Array

References: Kanerva, P. (1997). Fully Distributed Representation. In Proc. RWC ‘97, pp. 358-365.

bayes_hdc.functional.bundle_bsc(vectors, axis=0, key=None)[source]¶

Bundle hypervectors using majority rule for Binary Spatter Codes.

Bundling creates a new hypervector similar to all inputs by taking the majority vote at each dimension.

For an even number of input vectors, ties at exactly half the count are broken according to key:

key is None (default) — deterministic: ties map to False. This is fast, JIT-friendly, and matches the historical behaviour of this library.
key is a jax.random.PRNGKey — stochastic: ties are broken by independent fair coin flips per component, matching Kanerva (1997)’s prescription for an unbiased majority rule under even input counts.

For an odd number of input vectors there is no tie and key has no effect.

Parameters:

vectors (Array) – Binary hypervectors of shape with axis containing vectors to bundle
axis (int) – Axis along which to bundle (default: 0)
key (Array | None) – Optional jax.random.PRNGKey. When provided, ties are broken by stochastic coin flip; when None, ties map deterministically to False.

Returns:

Bundled hypervector, similar to all inputs

Return type:

Array

References: Kanerva, P. (1997). Fully Distributed Representation. In Proc. RWC ‘97, pp. 358-365.

bayes_hdc.functional.inverse_bsc(x)[source]¶

Compute inverse for BSC (identity since XOR is self-inverse).

Parameters:: x (Array)
Return type:: Array

bayes_hdc.functional.hamming_similarity(x, y)[source]¶

Compute normalized Hamming similarity between binary hypervectors.

Returns the fraction of matching bits between two binary vectors. Random vectors have similarity ≈ 0.5.

Parameters:

x (Array) – Binary hypervector of shape (…, d)
y (Array) – Binary hypervector of shape (…, d)

Returns:

Similarity score in [0, 1], where 1 is identical and 0.5 is random

Return type:

Array

MAP Operations¶

bayes_hdc.functional.bind_map(x, y)[source]¶

Bind two hypervectors using element-wise multiplication for MAP.

For real-valued vectors (MAP model), binding is element-wise multiplication. The result is dissimilar to both inputs.

Parameters:

x (Array) – Real-valued hypervector of shape (…, d)
y (Array) – Real-valued hypervector of shape (…, d)

Returns:

Bound hypervector of shape (…, d)

Return type:

Array

bayes_hdc.functional.bundle_map(vectors, axis=0)[source]¶

Bundle hypervectors using normalized sum for MAP.

For real-valued vectors, bundling is the normalized sum. The result is similar to all inputs (high cosine similarity).

Parameters:

vectors (Array) – Real-valued hypervectors with axis containing vectors to bundle
axis (int) – Axis along which to bundle (default: 0)

Returns:

Bundled and normalized hypervector

Return type:

Array

bayes_hdc.functional.inverse_map(x, eps=1e-08)[source]¶

Compute inverse for MAP using element-wise reciprocal.

For MAP binding (element-wise multiplication), the inverse is element-wise reciprocal: bind(bind(x, y), inverse(y)) = x. Near-zero elements return 0 (no inverse; bind with 0 destroys information).

Parameters:

x (Array) – Real-valued hypervector of shape (…, d)
eps (float) – Small constant for numerical stability (default: EPS)

Returns:

Inverse hypervector

Return type:

Array

bayes_hdc.functional.cosine_similarity(x, y)[source]¶

Compute cosine similarity between real-valued hypervectors.

Returns the cosine of the angle between two vectors. Random unit vectors have similarity ≈ 0.

Parameters:

x (Array) – Real-valued hypervector of shape (…, d)
y (Array) – Real-valued hypervector of shape (…, d)

Returns:

Similarity score in [-1, 1], where 1 is identical, -1 is opposite, and 0 is orthogonal

Return type:

Array

HRR Operations¶

bayes_hdc.functional.bind_hrr(x, y)[source]¶

Bind two hypervectors using circular convolution for HRR.

Circular convolution in the spatial domain is equivalent to element-wise multiplication in the Fourier domain, making it efficient to compute via the FFT. This is the canonical HRR binding of Plate (1995, 1994/2003); Jones & Mewhort (2007) is the canonical cognitive-science application (the BEAGLE composite holographic lexicon).

Parameters:

x (Array) – Real-valued hypervector of shape (…, d)
y (Array) – Real-valued hypervector of shape (…, d)

Returns:

Bound hypervector via circular convolution

Return type:

Array

References: Plate, T. A. (1995). Holographic Reduced Representations. IEEE Transactions on Neural Networks 6(3): 623-641. Plate, T. A. (2003). Holographic Reduced Representation: Distributed Representation for Cognitive Structures. CSLI Publications. Jones, M. N., Mewhort, D. J. K. (2007). Representing Word Meaning and Order Information in a Composite Holographic Lexicon. Psychological Review 114(1): 1-37.

bayes_hdc.functional.bundle_hrr(vectors, axis=0)¶

Bundle hypervectors using normalized sum for MAP.

For real-valued vectors, bundling is the normalized sum. The result is similar to all inputs (high cosine similarity).

Parameters:

vectors (Array) – Real-valued hypervectors with axis containing vectors to bundle
axis (int) – Axis along which to bundle (default: 0)

Returns:

Bundled and normalized hypervector

Return type:

Array

bayes_hdc.functional.inverse_hrr(x)[source]¶

Approximate inverse for HRR — Plate’s involution x*.

The involution is the vector x* with (x*)_i = x_{(-i) mod d} — i.e. the first element is preserved and the remaining d - 1 elements are reversed. For a length-4 example [c_0, c_1, c_2, c_3] this returns [c_0, c_3, c_2, c_1], matching Plate (1995, §II.F) verbatim.

The involution is an approximate inverse: bind_hrr(x, inverse_hrr(x)) is approximately the unit impulse, with the approximation tightening as the dimension grows. It differs from the exact inverse F^{-1}(1 / F(x)), which exists only when no Fourier coefficient of x vanishes; the library uses the involution because it is cheap, always defined, and the standard choice in HRR libraries.

Parameters:: x (Array) – Real-valued hypervector of shape (…, d)
Returns:: The involution x*, shape (…, d).
Return type:: Array

References: Plate, T. A. (1995). Holographic Reduced Representations. IEEE Transactions on Neural Networks 6(3): 623-641. (See §II.F for the involution definition.)

CGR Operations¶

bayes_hdc.functional.bind_cgr(x, y, q)[source]¶

Bind using modular addition for Cyclic Group Representation.

Parameters:

x (Array) – Integer hypervector with values in {0, …, q-1}, shape (…, d)
y (Array) – Integer hypervector with values in {0, …, q-1}, shape (…, d)
q (int) – Size of the cyclic group

Returns:

(x + y) mod q

Return type:

Bound hypervector

bayes_hdc.functional.bundle_cgr(vectors, q, axis=0)[source]¶

Bundle using component-wise mode for CGR.

Selects the most frequent value at each dimension.

Parameters:

vectors (Array) – Integer hypervectors with values in {0, …, q-1}
q (int) – Size of the cyclic group
axis (int) – Axis along which to bundle (default: 0)

Returns:

Bundled hypervector with mode value at each dimension

Return type:

Array

bayes_hdc.functional.inverse_cgr(x, q)[source]¶

Inverse via modular negation for CGR.

Parameters:

x (Array) – Integer hypervector with values in {0, …, q-1}
q (int) – Size of the cyclic group

Returns:

(q - x) mod q

Return type:

Inverse

bayes_hdc.functional.matching_similarity(x, y)[source]¶

Fraction of matching elements between integer hypervectors.

Random vectors with q levels have expected similarity 1/q.

Parameters:

x (Array) – Integer hypervector of shape (…, d)
y (Array) – Integer hypervector of shape (…, d)

Returns:

Similarity in [0, 1]

Return type:

Array

MCR Operations¶

bayes_hdc.functional.bind_mcr(x, y, q)¶

Bind using modular addition for Cyclic Group Representation.

Parameters:

x (Array) – Integer hypervector with values in {0, …, q-1}, shape (…, d)
y (Array) – Integer hypervector with values in {0, …, q-1}, shape (…, d)
q (int) – Size of the cyclic group

Returns:

(x + y) mod q

Return type:

Bound hypervector

bayes_hdc.functional.bundle_mcr(vectors, q, axis=0)[source]¶

Bundle using phasor sum and snap-to-grid for MCR.

Converts indices to complex phasors (q-th roots of unity), sums them, and snaps back to the nearest discrete phase level.

Parameters:

vectors (Array) – Integer hypervectors with values in {0, …, q-1}
q (int) – Number of phase levels
axis (int) – Axis along which to bundle (default: 0)

Returns:

Bundled hypervector with values snapped to nearest phase index

Return type:

Array

bayes_hdc.functional.inverse_mcr(x, q)¶

Inverse via modular negation for CGR.

Parameters:

x (Array) – Integer hypervector with values in {0, …, q-1}
q (int) – Size of the cyclic group

Returns:

(q - x) mod q

Return type:

Inverse

bayes_hdc.functional.phasor_similarity(x, y, q)[source]¶

Similarity via phasor inner product for MCR.

Converts to phasors and computes the real part of the normalized inner product. Random vectors have expected similarity ~0.

Parameters:

x (Array) – Integer hypervector with values in {0, …, q-1}
y (Array) – Integer hypervector with values in {0, …, q-1}
q (int) – Number of phase levels

Returns:

Similarity in [-1, 1]

Return type:

Array

VTB Operations¶

bayes_hdc.functional.bind_vtb(x, y)[source]¶

Bind using matrix multiplication for VTB.

Reshapes d-dimensional vectors into sqrt(d) x sqrt(d) matrices and multiplies them. Requires d to be a perfect square.

Parameters:

x (Array) – Real-valued hypervector of shape (…, d)
y (Array) – Real-valued hypervector of shape (…, d)

Returns:

Bound hypervector of shape (…, d)

Return type:

Array

bayes_hdc.functional.bundle_vtb(vectors, axis=0)¶

Bundle hypervectors using normalized sum for MAP.

For real-valued vectors, bundling is the normalized sum. The result is similar to all inputs (high cosine similarity).

Parameters:

vectors (Array) – Real-valued hypervectors with axis containing vectors to bundle
axis (int) – Axis along which to bundle (default: 0)

Returns:

Bundled and normalized hypervector

Return type:

Array

bayes_hdc.functional.inverse_vtb(x)[source]¶

Inverse via matrix pseudoinverse for VTB.

Parameters:: x (Array)
Return type:: Array

Universal Operations¶

bayes_hdc.functional.permute(x, shifts=1)[source]¶

Cyclically permute a hypervector to encode sequence information.

Permutation reorders elements to represent positional or sequential information. Cyclic shifts preserve the distribution of values.

Parameters:

x (Array) – Hypervector of shape (…, d)
shifts (int) – Number of positions to shift (default: 1)

Returns:

Permuted hypervector of shape (…, d)

Return type:

Array

bayes_hdc.functional.cleanup(query, memory, similarity_fn=<PjitFunction of <function cosine_similarity>>, return_similarity=False)[source]¶

Find the most similar vector in memory to the query.

Cleanup is used to retrieve the closest known hypervector from memory, useful for error correction and symbol retrieval after a bind / unbind sequence has introduced approximation noise. This is the abstract-vector cleanup operation of Kanerva (2009); for the spiking-neuron implementation see Stewart, Tang & Eliasmith (2010, Cognitive Systems Research 12: 84-92), which is out of scope here. Resonator networks (Frady et al. 2020) are a related but distinct factorisation algorithm built on top of cleanup.

Parameters:

query (Array) – Query hypervector of shape (…, d)
memory (Array) – Memory hypervectors of shape (n, d)
similarity_fn (Callable[[Array, Array], Array]) – Function to compute similarity (default: cosine_similarity)
return_similarity (bool) – Whether to return similarity scores (default: False)

Returns:

Most similar vector from memory, or (vector, similarity) if return_similarity=True

Return type:

Array | tuple[Array, Array]

References: Kanerva, P. (2009). Hyperdimensional Computing: An Introduction. Cognitive Computation 1(2): 139-159.

Batch Operations¶

bayes_hdc.functional.batch_bind_bsc(x, y)¶

Vectorized version of bind_bsc. Takes similar arguments as bind_bsc but with additional array axes over which bind_bsc is mapped.

Original documentation:

Bind two hypervectors using XOR for Binary Spatter Codes.

Binding creates a new hypervector that is dissimilar to both inputs. XOR is its own inverse, so unbinding is identical to binding.

Args:
x: Binary hypervector of shape (…, d) y: Binary hypervector of shape (…, d)

Returns:
Bound hypervector of shape (…, d), dissimilar to both x and y

References: Kanerva, P. (1997). Fully Distributed Representation. In Proc. RWC ‘97, pp. 358-365.

Parameters:

x (Array)
y (Array)

Return type:

Array

bayes_hdc.functional.batch_bind_map(x, y)¶

Vectorized version of bind_map. Takes similar arguments as bind_map but with additional array axes over which bind_map is mapped.

Original documentation:

Bind two hypervectors using element-wise multiplication for MAP.

For real-valued vectors (MAP model), binding is element-wise multiplication. The result is dissimilar to both inputs.

Args:
x: Real-valued hypervector of shape (…, d) y: Real-valued hypervector of shape (…, d)

Returns:
Bound hypervector of shape (…, d)

Parameters:

x (Array)
y (Array)

Return type:

Array

bayes_hdc.functional.batch_hamming_similarity(x, y)¶

Vectorized version of hamming_similarity. Takes similar arguments as hamming_similarity but with additional array axes over which hamming_similarity is mapped.

Original documentation:

Compute normalized Hamming similarity between binary hypervectors.

Returns the fraction of matching bits between two binary vectors. Random vectors have similarity ≈ 0.5.

Args:
x: Binary hypervector of shape (…, d) y: Binary hypervector of shape (…, d)

Returns:
Similarity score in [0, 1], where 1 is identical and 0.5 is random

Parameters:

x (Array)
y (Array)

Return type:

Array

bayes_hdc.functional.batch_cosine_similarity(x, y)¶

Vectorized version of cosine_similarity. Takes similar arguments as cosine_similarity but with additional array axes over which cosine_similarity is mapped.

Original documentation:

Compute cosine similarity between real-valued hypervectors.

Returns the cosine of the angle between two vectors. Random unit vectors have similarity ≈ 0.

Args:
x: Real-valued hypervector of shape (…, d) y: Real-valued hypervector of shape (…, d)

Returns:
Similarity score in [-1, 1], where 1 is identical, -1 is opposite, and 0 is orthogonal

Parameters:

x (Array)
y (Array)

Return type:

Array