Distance metrics

Implementations of the pairwise metrics used to compare image embeddings. Each function takes two 2-D matrices, x of shape (N, D) and y of shape (M, D), and returns the full (N, M) pairwise result as float64:

  • cosine_similarity(x, y): higher means more similar. All-zero rows get a similarity of 0.

  • euclidean_distances(x, y): lower means more similar.

  • manhattan_distances(x, y, working_memory_bytes=...): lower means more similar. The optional keyword caps the size of the internal broadcast temporary (default 256 MiB).

These are the implementations behind the similarity_func names ("cosine", "euclidean", "l1", "manhattan") accepted by the embedders.

import numpy as np
from pyvisim.distance import cosine_similarity, euclidean_distances

x = np.random.rand(4, 128)   # 4 embeddings
y = np.random.rand(6, 128)   # 6 embeddings

cosine_similarity(x, y).shape      # (4, 6)
euclidean_distances(x, y).shape    # (4, 6)

Formula

  1. Cosine similarity:

    \[\text{cosine\_similarity}(x, y) = \frac{x \cdot y^T}{||x||_2 ||y||_2}\]

  2. Euclidean distance:

    \[\text{euclidean\_distances}(x, y) = ||x - y||_2\]

  3. Manhattan distance:

    \[\text{manhattan\_distances}(x, y) = ||x - y||_1\]

API reference

Pairwise distance and similarity metrics implemented in pure NumPy.

pyvisim.distance.cosine_similarity(x, y)[source]

Compute the pairwise cosine similarity between two matrices.

The raw inner products are computed with a single matrix product and the row norms are divided out of the (N, M) result in place.

Parameters:
Returns:

Cosine similarity matrix of shape (N, M).

Raises:

ValueError – If either input is not 2-D or the feature dimensions do not match.

Return type:

ndarray[tuple[int, …], dtype[float64]]

pyvisim.distance.euclidean_distances(x, y)[source]

Compute the pairwise Euclidean (L2) distance between two matrices.

Uses the expansion ||a - b||^2 = ||a||^2 - 2 a.b + ||b||^2 so the whole distance matrix reduces to one matrix product plus two rank-1 updates. Lower values mean more similar.

Parameters:
Returns:

Euclidean distance matrix of shape (N, M).

Raises:

ValueError – If either input is not 2-D or the feature dimensions do not match.

Return type:

ndarray[tuple[int, …], dtype[float64]]

pyvisim.distance.manhattan_distances(x, y, *, working_memory_bytes=None)[source]

Compute the pairwise Manhattan (L1) distance between two matrices.

The broadcast difference materializes a (chunk, M, D) temporary, so rows of x are processed in chunks that keep that temporary under the working-memory budget. Lower values mean more similar.

Parameters:
Returns:

Manhattan distance matrix of shape (N, M).

Raises:

ValueError – If either input is not 2-D, the feature dimensions do not match, or working_memory_bytes is not positive.

Return type:

ndarray[tuple[int, …], dtype[float64]]