torch.nn.PairwiseDistance

class PairwiseDistance extends Module

new PairwiseDistance(options?: PairwiseDistanceOptions)

readonlyp(number)
readonlyeps(number)
readonlykeepdim(boolean)

Pairwise distance: computes Lp norm distance between vector pairs.

Computes the distance between pairs of vectors using any Lp norm (L1, L2, Chebyshev, or general Lp). Default is L2 (Euclidean) distance, the most common choice for measuring dissimilarity. Useful for metric learning, similarity calculations, and distance-based clustering. Essential for:

Triplet loss and metric learning
Similarity-based retrieval
Distance-based clustering (k-NN, k-means)
Anomaly detection (distance from normal samples)
Contrastive learning (pushing similar/dissimilar pairs apart/together)

Unlike cosine similarity which measures angle, pairwise distance measures actual magnitude differences. L2 distance is the Euclidean distance; L1 is Manhattan/taxi-cab distance; higher p emphasizes larger differences more. Chebyshev (p=∞) takes maximum absolute difference.

When to use PairwiseDistance:

Computing distances between feature vectors
Triplet loss training (positive/negative pair distances)
Contrastive loss (similarity-based losses)
Finding nearest neighbors
Clustering algorithms
Distance-based anomaly detection

Distance metrics (different p values):

p=1 (L1/Manhattan): Sum of absolute differences, robust to outliers
p=2 (L2/Euclidean): Straight-line distance, standard choice, sensitive to outliers
p=∞ (Chebyshev): Maximum absolute difference in any dimension
Other p: General Lp norm, p=1.5 provides middle ground

Trade-offs:

L1 vs L2: L1 more robust but less smooth gradients; L2 smoother but outlier-sensitive
vs Cosine: Distance is magnitude-sensitive; cosine is scale-invariant
vs Euclidean: PairwiseDistance is more general, supports any Lp norm
Computational cost: L1/L2 fast; general Lp slightly slower (power operation)

Input shape expectations:

x1 and x2 must have same shape
Typically: (batch_size, feature_dim) for batch processing
Distance computed along last dimension, result has shape (batch_size,)

PairwiseDistance computation: For vectors x1, x2 of shape (N, D):

Compute difference: diff = x1 - x2 (shape: N, D)
For L2: distance = sqrt(sum(diff²)) per row
For L1: distance = sum(|diff|) per row
For Lp: distance = (sum(|diff|^p))^(1/p) per row
Result shape: (N,) - distance for each pair

\begin{aligned} d_1(\mathbf{x}_1, \mathbf{x}_2) = \sum_i |x_{1,i} - x_{2,i}| \\ d_2(\mathbf{x}_1, \mathbf{x}_2) = \sqrt{\sum_i (x_{1,i} - x_{2,i})^2} \\ d_p(\mathbf{x}_1, \mathbf{x}_2) = \left(\sum_i |x_{1,i} - x_{2,i}|^p\right)^{1/p} \\ d_{\infty}(\mathbf{x}_1, \mathbf{x}_2) = \max_i |x_{1,i} - x_{2,i}| \end{aligned}

L2 default: L2 (Euclidean) is most commonly used distance metric
Symmetric: Distance symmetric: d(x, y) = d(y, x)
Non-negative: Distance always ≥ 0
Triangle inequality: L1, L2, Chebyshev satisfy triangle inequality (true metrics)
General Lp: Can use any p, but L1, L2, ∞ are most common
Magnitude sensitive: Depends on actual vector values, unlike cosine similarity

Output shape: Dimension reduced to remove feature dimension
Same input shape: x1 and x2 must have identical shapes
Last dimension: Distance always computed along last dimension
Numerical stability: Very large vectors may overflow, very small may underflow
p=∞ behavior: Returns single max value, not element-wise maximum

Examples

// Basic L2 distance (Euclidean)
const pairwise = new torch.nn.PairwiseDistance(2);
const x1 = torch.tensor([[0, 0], [1, 1]]);
const x2 = torch.tensor([[3, 4], [4, 3]]);
const distances = pairwise.forward(x1, x2);
// distances ≈ [5, 4.24] (Euclidean distances)

// Triplet loss: push similar pairs close, dissimilar pairs far
const distance = new torch.nn.PairwiseDistance(2);

// Anchor and positive should be close
const anchor = torch.randn([32, 128]);
const positive = torch.randn([32, 128]);
const pos_dist = distance.forward(anchor, positive);

// Anchor and negative should be far
const negative = torch.randn([32, 128]);
const neg_dist = distance.forward(anchor, negative);

// Triplet loss: max(0, pos_dist - neg_dist + margin)
const margin = 1.0;
const triplet_loss = torch.relu(pos_dist.sub(neg_dist).add(margin)).mean();

// Find closest match from database
const distance = new torch.nn.PairwiseDistance(2);
const query = torch.randn([1, 256]);        // Single query embedding
const database = torch.randn([10000, 256]); // 10K database vectors

// Expand query to match database
const query_expanded = query.expand([10000, 256]);
const distances = distance.forward(query_expanded, database);

// Find closest match
const min_idx = distances.argmin().item();
console.log(`Closest match at index: ${min_idx}`);

// Metric learning with different norms
const l1_distance = new torch.nn.PairwiseDistance(1);   // Manhattan
const l2_distance = new torch.nn.PairwiseDistance(2);   // Euclidean
const chebyshev = new torch.nn.PairwiseDistance(Infinity); // Max

const x1 = torch.randn([100, 64]);
const x2 = torch.randn([100, 64]);

const d_l1 = l1_distance.forward(x1, x2);
const d_l2 = l2_distance.forward(x1, x2);
const d_chebyshev = chebyshev.forward(x1, x2);
// Different norms give different distance characteristics

// Contrastive loss: penalize dissimilar positive pairs
const pairwise = new torch.nn.PairwiseDistance(2);

function contrastive_loss(
  x1: torch.Tensor,
  x2: torch.Tensor,
  label: torch.Tensor,  // 1 if similar, 0 if dissimilar
  margin: number = 1.0
): torch.Tensor {
  const distance = pairwise.forward(x1, x2);
  // Similar pairs: minimize distance
  // Dissimilar pairs: maximize distance (push > margin apart)
  const loss = label.mul(distance.pow(2)).add(
    torch.sub(1, label).mul(torch.relu(torch.sub(margin, distance)).pow(2))
  );
  return loss.mean();
}

torch.nn.PairwiseDistance

Examples

See Also

torch.nn.PairwiseDistance

Examples

See Also