cosine_similarity

cosine_similarity#

class braintools.metric.cosine_similarity(predictions, targets, epsilon=1e-08)#

Compute cosine similarity between predicted and target vectors.

Calculates the cosine of the angle between vectors, providing a measure of similarity that is independent of vector magnitude. This metric is particularly useful for comparing direction or orientation of high-dimensional vectors, commonly used in natural language processing, computer vision, and recommendation systems.

The cosine similarity is defined as:

\[\text{cosine\_similarity}(\mathbf{u}, \mathbf{v}) = \frac{\mathbf{u} \cdot \mathbf{v}}{||\mathbf{u}|| ||\mathbf{v}||}\]

where \(\mathbf{u}\) and \(\mathbf{v}\) are vectors, and \(||\cdot||\) denotes the L2 (Euclidean) norm.

Parameters:

  • predictions (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Predicted vectors with shape (..., dim) where dim is the vector dimension. Must be floating-point type.

  • targets (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Ground truth target vectors with shape (..., dim) matching the shape of predictions. Must be floating-point type.

  • epsilon (float) – Minimum norm used as a floor in the denominator to prevent division by zero when computing norms (via safe_norm()). This provides numerical stability for zero or near-zero vectors and keeps both the value and the gradient finite for zero-vector inputs. The default of 1e-8 (rather than 0) ensures the zero-vector safety actually takes effect.

Returns:

Cosine similarity values with shape (...,) where the last dimension has been reduced. Values range from -1 (opposite directions) to 1 (same direction), with 0 indicating orthogonal vectors.

Return type:

Array | ndarray | bool | number | bool | int | float | complex | Quantity

Notes

Properties of cosine similarity:

  • Scale invariant: Only depends on vector direction, not magnitude

  • Bounded: Values always in [-1, 1] range

  • Symmetric: sim(u, v) = sim(v, u)

  • Geometric interpretation: Cosine of angle between vectors

Common use cases:

  • Text similarity: Comparing document embeddings

  • Image features: Comparing visual feature vectors

  • Recommendation: Finding similar user/item profiles

  • Clustering: Measuring vector similarity in high dimensions

The function handles zero vectors gracefully using the epsilon parameter to floor the denominator, which keeps both the value and the gradient finite for zero-vector inputs. Note that because each vector is normalized independently, the gradient – while finite – can be large in magnitude for near-zero inputs (it scales like 1 / epsilon).

Examples

Basic cosine similarity:

>>> import jax.numpy as jnp
>>> import braintools
>>> # Two 3D vectors, same direction, different magnitude
>>> pred = jnp.array([1.0, 2.0, 3.0])
>>> target = jnp.array([2.0, 4.0, 6.0])
>>> braintools.metric.cosine_similarity(pred, target)
Array(0.9999999, dtype=float32)

Batch computation (all orthogonal pairs):

>>> pred_batch = jnp.array([[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
>>> target_batch = jnp.array([[0.0, 1.0], [1.0, 0.0], [1.0, -1.0]])
>>> braintools.metric.cosine_similarity(pred_batch, target_batch)
Array([0., 0., 0.], dtype=float32)

Handling zero vectors (finite result):

>>> zero_vec = jnp.array([0.0, 0.0, 0.0])
>>> normal_vec = jnp.array([1.0, 2.0, 3.0])
>>> braintools.metric.cosine_similarity(zero_vec, normal_vec)
Array(0., dtype=float32)

See also

braintools.metric.cosine_distance

1 - cosine_similarity

jax.numpy.dot

Dot product computation

jax.numpy.linalg.norm

Vector norm computation

References