Similarity Metrics API

Similarity metrics for comparing hypervectors.

Functions

vsax.similarity.cosine_similarity(a, b)

Compute cosine similarity between two hypervectors.

Cosine similarity measures the cosine of the angle between two vectors, ranging from -1 (opposite) to 1 (identical direction). For complex vectors, uses the real part of the complex dot product.

Works with all hypervector types: - Complex hypervectors (FHRR): Uses conjugate dot product - Real hypervectors (MAP): Standard cosine similarity - Binary hypervectors: Normalized dot product

Parameters:

Name	Type	Description	Default
a	Union[AbstractHypervector, ndarray]	First hypervector (AbstractHypervector or jnp.ndarray).	required
b	Union[AbstractHypervector, ndarray]	Second hypervector (AbstractHypervector or jnp.ndarray).	required

Returns:

Type	Description
float	Cosine similarity as a float in range [-1, 1].

Raises:

Type	Description
ValueError	If vectors have different shapes.

Example

from vsax import create_fhrr_model, VSAMemory from vsax.similarity import cosine_similarity model = create_fhrr_model(dim=512) memory = VSAMemory(model) memory.add_many(["dog", "cat", "animal"]) similarity = cosine_similarity(memory["dog"], memory["cat"]) print(f"Similarity: {similarity:.3f}")

vsax.similarity.dot_similarity(a, b)

Compute dot product similarity between two hypervectors.

The dot product provides an unnormalized similarity measure. Higher values indicate more similarity. For complex vectors, uses the real part of the complex dot product (conjugate dot product).

Works with all hypervector types: - Complex hypervectors (FHRR): Real part of a* · b - Real hypervectors (MAP): Standard dot product a · b - Binary hypervectors: Dot product (count of matching bits)

Parameters:

Name	Type	Description	Default
a	Union[AbstractHypervector, ndarray]	First hypervector (AbstractHypervector or jnp.ndarray).	required
b	Union[AbstractHypervector, ndarray]	Second hypervector (AbstractHypervector or jnp.ndarray).	required

Returns:

Type	Description
float	Dot product similarity as a float.

Raises:

Type	Description
ValueError	If vectors have different shapes.

Example

from vsax import create_map_model, VSAMemory from vsax.similarity import dot_similarity model = create_map_model(dim=512) memory = VSAMemory(model) memory.add_many(["apple", "orange", "fruit"]) similarity = dot_similarity(memory["apple"], memory["orange"]) print(f"Dot product: {similarity:.3f}")

vsax.similarity.hamming_similarity(a, b)

Compute Hamming similarity between two binary hypervectors.

Hamming similarity measures the proportion of matching bits between two binary vectors. It ranges from 0 (completely different) to 1 (identical).

Primarily designed for binary hypervectors but works with any vector type by comparing element equality. For best results, use with bipolar {-1, +1} or binary {0, 1} vectors.

Parameters:

Name	Type	Description	Default
a	Union[AbstractHypervector, ndarray]	First hypervector (AbstractHypervector or jnp.ndarray).	required
b	Union[AbstractHypervector, ndarray]	Second hypervector (AbstractHypervector or jnp.ndarray).	required

Returns:

Type	Description
float	Hamming similarity as a float in range [0, 1].
float	1.0 means all bits match, 0.0 means no bits match.

Raises:

Type	Description
ValueError	If vectors have different shapes.

Example

from vsax import create_binary_model, VSAMemory from vsax.similarity import hamming_similarity model = create_binary_model(dim=10000, bipolar=True) memory = VSAMemory(model) memory.add_many(["cat", "dog", "bird"]) similarity = hamming_similarity(memory["cat"], memory["dog"]) print(f"Hamming similarity: {similarity:.3f}")