cosine_embedding_loss

→Tensor

cosine_embedding_loss(x1: Tensor, x2: Tensor, y: Tensor, margin: float = 0.0, reduction: str = 'mean')

source

Cosine embedding loss for pairwise similarity learning.

Encourages "similar" pairs (label $y = 1$ ) to align in direction and "dissimilar" pairs ( $y = -1$ ) to be at least margin cosine-units apart. Operates purely on angular (direction) information — magnitudes are normalised away, which is useful when the relevant signal is the direction of embeddings (e.g., word vectors, learned representations).

Parameters

x1Tensor

First embedding of shape

(N, D)

x2Tensor

Second embedding of the same shape.

yTensor

Label tensor of shape

(N,)

with values

\pm 1

marginfloat= 0.0

Minimum desired cosine gap for dissimilar pairs, typically in

[-1, 1]

(default 0.0).

reductionstr= 'mean'

"mean" (default), "sum", or "none".

Returns

Tensor

Scalar or per-pair tensor of shape $(N,)$ .

Notes

Per-pair loss:

L_i = \begin{cases} 1 - \cos(x_1^{(i)}, x_2^{(i)}) & y_i = +1 \\ \max\!\big(0,\; \cos(x_1^{(i)}, x_2^{(i)}) - \text{margin}\big) & y_i = -1 \end{cases}

With margin = 0, dissimilar pairs are only penalised when they have positive cosine similarity — i.e., the loss is satisfied as long as the angle between them exceeds $90°$ . Increasing margin toward 1 demands more separation.

Examples

>>> import lucid
>>> from lucid.nn.functional import cosine_embedding_loss
>>> x1 = lucid.tensor([[1.0, 0.0]])
>>> x2 = lucid.tensor([[0.5, 0.5]])
>>> y = lucid.tensor([1.0])
>>> cosine_embedding_loss(x1, x2, y)
Tensor(0.2928...)