Functional Module
The jax_hdc.functional module provides core HDC operations implemented as pure functions.
Binary Spatter Code Operations
- jax_hdc.functional.bind_bsc(x: Array, y: Array) Array[source]
Bind two hypervectors using XOR for Binary Spatter Codes.
Binding creates a new hypervector that is dissimilar to both inputs.
- Parameters:
x – Binary hypervector of shape (…, d)
y – Binary hypervector of shape (…, d)
- Returns:
Bound hypervector of shape (…, d), dissimilar to both x and y
- jax_hdc.functional.bundle_bsc(vectors: Array, axis: int = 0) Array[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.
- Parameters:
vectors – Binary hypervectors of shape with axis containing vectors to bundle
axis – Axis along which to bundle (default: 0)
- Returns:
Bundled hypervector, similar to all inputs
- jax_hdc.functional.inverse_bsc(x: Array) Array[source]
Compute inverse for BSC (identity since XOR is self-inverse).
- jax_hdc.functional.hamming_similarity(x: Array, y: Array) Array[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 – 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
MAP Operations
- jax_hdc.functional.bind_map(x: Array, y: Array) Array[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 – Real-valued hypervector of shape (…, d)
y – Real-valued hypervector of shape (…, d)
- Returns:
Bound hypervector of shape (…, d)
- jax_hdc.functional.bundle_map(vectors: Array, axis: int = 0) Array[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 – Real-valued hypervectors with axis containing vectors to bundle
axis – Axis along which to bundle (default: 0)
- Returns:
Bundled and normalized hypervector
- jax_hdc.functional.inverse_map(x: Array, eps: float = 1e-08) Array[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 – Real-valued hypervector of shape (…, d)
eps – Small constant for numerical stability (default: EPS)
- Returns:
Inverse hypervector
- jax_hdc.functional.cosine_similarity(x: Array, y: Array) Array[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 – 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
HRR Operations
- jax_hdc.functional.bind_hrr(x: Array, y: Array) Array[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.
- Parameters:
x – Real-valued hypervector of shape (…, d)
y – Real-valued hypervector of shape (…, d)
- Returns:
Bound hypervector via circular convolution
- jax_hdc.functional.bundle_hrr(vectors: Array, axis: int = 0) Array
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 – Real-valued hypervectors with axis containing vectors to bundle
axis – Axis along which to bundle (default: 0)
- Returns:
Bundled and normalized hypervector
Universal Operations
- jax_hdc.functional.permute(x: Array, shifts: int = 1) Array[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 – Hypervector of shape (…, d)
shifts – Number of positions to shift (default: 1)
- Returns:
Permuted hypervector of shape (…, d)
- jax_hdc.functional.cleanup(query: ~jax.Array, memory: ~jax.Array, similarity_fn: ~typing.Callable[[~jax.Array, ~jax.Array], ~jax.Array] = <PjitFunction of <function cosine_similarity>>, return_similarity: bool = False) Array | tuple[Array, Array][source]
Find the most similar vector in memory to the query.
Cleanup (or resonator) is used to retrieve the closest known hypervector from memory, useful for error correction and symbol retrieval.
- Parameters:
query – Query hypervector of shape (…, d)
memory – Memory hypervectors of shape (n, d)
similarity_fn – Function to compute similarity (default: cosine_similarity)
return_similarity – Whether to return similarity scores (default: False)
- Returns:
Most similar vector from memory, or (vector, similarity) if return_similarity=True
Batch Operations
- jax_hdc.functional.batch_bind_bsc(x: Array, y: Array) Array
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.
- 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
- jax_hdc.functional.batch_bind_map(x: Array, y: Array) Array
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)
- jax_hdc.functional.batch_hamming_similarity(x: Array, y: Array) Array
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
- jax_hdc.functional.batch_cosine_similarity(x: Array, y: Array) Array
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
Example Usage
Basic binding and bundling:
import jax
import jax.numpy as jnp
from jax_hdc import functional as F
key = jax.random.PRNGKey(42)
# BSC operations
x = jax.random.bernoulli(key, 0.5, shape=(10000,))
y = jax.random.bernoulli(key, 0.5, shape=(10000,))
bound = F.bind_bsc(x, y)
sim = F.hamming_similarity(x, y)
# MAP operations
x = jax.random.normal(key, shape=(10000,))
y = jax.random.normal(key, shape=(10000,))
bound = F.bind_map(x, y)
sim = F.cosine_similarity(x, y)
Batch processing:
vectors = jax.random.normal(key, shape=(100, 10000))
bundled = F.bundle_map(vectors, axis=0)