torch.nn.functional.pairwise_distance

function pairwise_distance(x1: Tensor, x2: Tensor, options?: PairwiseDistanceFunctionalOptions): Tensor

function pairwise_distance(x1: Tensor, x2: Tensor, p: number, eps: number, keepdim: boolean, options?: PairwiseDistanceFunctionalOptions): Tensor

Pairwise Distance: computes Lp distance between corresponding vector pairs.

Computes element-wise Lp distance between two batches of vectors. For inputs of shape (N, M) representing N vector pairs of dimension M, returns distances of shape (N,) or (N, 1) containing the distance for each pair. Supports various distance metrics (L1, L2/Euclidean, L∞, etc.) via the p parameter. Essential for:

Metric learning and distance-based losses (contrastive, triplet loss)
Siamese networks comparing pairs of inputs
Similarity-based neural networks (matching networks, prototypical networks)
Computing distances between matched features
Pairwise comparisons in ranking and retrieval tasks
Distance-based regularization in neural networks
Verification and authentication networks (face verification, etc.)

Key difference from pdist:

pairwise_distance: compares x1[i] with x2[i] for each i (pair-wise, shape (N,))
pdist: all-pairs distances within one batch (shape (N*(N-1)/2,))
Use pairwise_distance for Siamese networks; pdist for clustering/metric learning matrices

When to use Pairwise Distance:

Siamese/Triplet networks with paired inputs
Contrastive learning between matched pairs
Metric learning comparing anchor to positive/negative
Similarity verification tasks
Computing losses that compare pair distances
Matching network outputs (comparing embeddings point-wise)

Comparison with alternatives:

pdist: All-pairs distances for single batch; pairwise for matched pairs
cosine_similarity: Angular distance (scale-invariant); pairwise uses magnitude
norm: Distance between single vectors; pairwise for batch comparisons
Manual subtraction + norm: Less efficient than optimized pairwise_distance

\begin{aligned} d_p(x_1, x_2) = \|x_1 - x_2\|_p = \left(\sum_k |x_{1,k} - x_{2,k}|^p\right)^{1/p} \\ \text{L1 (Manhattan): } d_1(x, y) = \sum_k |x_k - y_k| \\ \text{L2 (Euclidean): } d_2(x, y) = \sqrt{\sum_k (x_k - y_k)^2} \\text{ (default)} \\ \text{L∞ (Chebyshev): } d_\infty(x, y) = \max_k |x_k - y_k| \end{aligned}

Pair-wise comparison: Each element compared with its corresponding element in other batch
Efficient computation: Optimized for batch operations; faster than manual implementation
Magnitude-sensitive: Unlike cosine_similarity, depends on vector magnitudes
Symmetric: pairwise_distance(x1, x2) = pairwise_distance(x2, x1)
Non-negative: All distances ≥ 0 (satisfies non-negativity property of metrics)
Reduces to zero for identical vectors: pairwise_distance(x, x) = 0
Numerical stability: eps parameter prevents sqrt/division by zero

Same shape required: x1 and x2 must have identical shapes (N, M)
Not a full distance matrix: Computes only diagonal comparisons, not all pairs
p must be positive: p = 0 is invalid; use p 0 for well-defined Lp norm
Large p values: For very large p, numerical issues can arise (use Infinity instead)
Magnitude matters: If vectors have wildly different scales, normalize first

Parameters

x1Tensor: First batch of vectors, shape (N, M) where N is batch size, M is feature dim Example: anchor embeddings [batch, embedding_dim]
x2Tensor: Second batch of vectors, shape (N, M) matching x1 Example: positive/negative embeddings [batch, embedding_dim]
optionsPairwiseDistanceFunctionalOptionsoptional

Returns

Tensor– Tensor of distances, shape (N,) or (N, 1) depending on keepdim Each element contains distance between corresponding pair in x1 and x2

Examples

// Basic pairwise distance between pairs
const x1 = torch.tensor([[1, 0], [0, 1], [1, 1]]);  // 3 vectors
const x2 = torch.tensor([[1, 1], [0, 0], [2, 0]]);  // 3 vectors
const distances = torch.nn.functional.pairwise_distance(x1, x2, 2);
// distances shape: [3] - distance between each pair (x1[i], x2[i])

// Siamese Network: compute distance between query and candidate embeddings
const query_embeddings = model.encode(query_images);      // [batch, 128]
const candidate_embeddings = model.encode(candidate_images);  // [batch, 128]
const distances = torch.nn.functional.pairwise_distance(
  query_embeddings, candidate_embeddings, 2
);  // [batch] - distance for each query-candidate pair

// Loss: minimize distances for positive pairs
const loss = distances.mean();

// Contrastive Loss: anchor vs positive (should be similar), anchor vs negative (should be dissimilar)
const anchor = model(anchor_input);        // [batch, 64]
const positive = model(positive_input);    // [batch, 64]
const negative = model(negative_input);    // [batch, 64]

const pos_dist = torch.nn.functional.pairwise_distance(anchor, positive, 2);
const neg_dist = torch.nn.functional.pairwise_distance(anchor, negative, 2);

const margin = 1.0;
const loss = torch.nn.functional.relu(pos_dist - neg_dist + margin).mean();
// Loss pushes positive closer and negative farther

// Metric Learning: face verification with different distance metrics
const face1_embedding = face_model(face1);
const face2_embedding = face_model(face2);

// L2 (Euclidean) distance - standard
const euclidean_dist = torch.nn.functional.pairwise_distance(
  face1_embedding, face2_embedding, 2
);

// L1 (Manhattan) distance - robust to outliers
const l1_dist = torch.nn.functional.pairwise_distance(
  face1_embedding, face2_embedding, 1
);

// Chebyshev distance - maximum coordinate difference
const chebyshev_dist = torch.nn.functional.pairwise_distance(
  face1_embedding, face2_embedding, Infinity
);

// Verification: if distance < threshold, same person
const threshold = 0.6;
const is_same = euclidean_dist.lt(threshold);

// Triplet Loss with pairwise distances
const anchor = model(anchor_img);
const positive = model(positive_img);  // Same person
const negative = model(negative_img);  // Different person

const ap_dist = torch.nn.functional.pairwise_distance(anchor, positive, 2, 1e-6, true);
const an_dist = torch.nn.functional.pairwise_distance(anchor, negative, 2, 1e-6, true);

const margin = 0.5;
const triplet_loss = torch.nn.functional.relu(ap_dist - an_dist + margin).mean();

// Different distance metrics comparison
const x = torch.randn([32, 100]);  // 32 sample embeddings, 100-dim
const y = torch.randn([32, 100]);  // 32 sample embeddings, 100-dim

// Manhattan (L1) - sum of absolute differences, robust to outliers
const l1_distances = torch.nn.functional.pairwise_distance(x, y, 1);

// Euclidean (L2) - standard, default, most common
const l2_distances = torch.nn.functional.pairwise_distance(x, y, 2);

// Chebyshev (L∞) - maximum difference, robust to dimension scaling
const l_inf_distances = torch.nn.functional.pairwise_distance(x, y, Infinity);

torch.nn.functional.pairwise_distance

Parameters

Returns

Examples

See Also

torch.nn.functional.pairwise_distance

Parameters

Returns

Examples

See Also