---
title: Cosine Similarity
description: Calculate pairwise cosine similarity.
canonical: 'https://lightning.ai/docs/torchmetrics/stable/pairwise/cosine_similarity'
---
# Cosine Similarity {#cosine-similarity}

## Functional Interface {#functional-interface}

### `torchmetrics.functional.pairwise_cosine_similarity(x, y=None, reduction=None, zero_diagonal=None)` {#torchmetrics.functional.pairwise_cosine_similarity}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/functional/pairwise/cosine.py#L48-L91)

Calculate pairwise cosine similarity.

```math
s_{cos}(x,y) = \frac{<x,y>}{||x|| \cdot ||y||} = \frac{\sum_{d=1}^D x_d \cdot y_d }{\sqrt{\sum_{d=1}^D x_i^2} \cdot \sqrt{\sum_{d=1}^D y_i^2}}
```

If both $`x`$ and $`y`$ are passed in, the calculation will be performed pairwise between the rows of $`x`$ and $`y`$. If only $`x`$ is passed in, the calculation will be performed between the rows of $`x`$.

Parameters:

*   **x** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – Tensor with shape `[N, d]`
    
*   **y** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\]) – Tensor with shape `[M, d]`, optional
    
*   **reduction** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")\[`'mean'`, `'sum'`, `'none'`, `None`\]\]) – reduction to apply along the last dimension. Choose between ‘mean’, ‘sum’ (applied along column dimension) or ‘none’, None for no reduction
    
*   **zero\_diagonal** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")\]) – if the diagonal of the distance matrix should be set to 0. If only $`x`$ is given this defaults to `True` else if $`y`$ is also given it defaults to `False`
    

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

Returns:

A `[N,N]` matrix of distances if only `x` is given, else a `[N,M]` matrix

Example

```python
>>> import torch
>>> from torchmetrics.functional.pairwise import pairwise_cosine_similarity
>>> x = torch.tensor([[2, 3], [3, 5], [5, 8]], dtype=torch.float32)
>>> y = torch.tensor([[1, 0], [2, 1]], dtype=torch.float32)
>>> pairwise_cosine_similarity(x, y)
tensor([[0.5547, 0.8682],
        [0.5145, 0.8437],
        [0.5300, 0.8533]])
>>> pairwise_cosine_similarity(x)
tensor([[0.0000, 0.9989, 0.9996],
        [0.9989, 0.0000, 0.9998],
        [0.9996, 0.9998, 0.0000]])
```

---

**Navigation**

- Parent: [Pairwise](/docs/torchmetrics/1.9.0/pairwise.md)