class

MarginRankingLoss

extendsModule

MarginRankingLoss(margin: float = 0.0, reduction: str = 'mean')

source

Margin ranking loss for pairwise ranking problems.

Given two inputs $x_1$ , $x_2$ and a binary label $y \in \{-1, +1\}$ , the loss enforces that the correctly ranked input exceeds the other by at least margin:

\mathcal{L}(x_1, x_2, y) = \max\!\bigl(0,\; -y\,(x_1 - x_2) + \text{margin}\bigr)

When $y = +1$ , $x_1$ should be larger than $x_2$ (e.g. a more relevant document score). When $y = -1$ , $x_2$ should be larger.

Parameters

marginfloat= 0.0

Minimum required score gap between the two inputs. Default 0.0.

reductionstr= 'mean'

'none' | 'mean' (default) | 'sum'.

Attributes

marginfloat

The margin threshold.

reductionstr

The reduction mode.

Notes

x1 : $(N,)$ or $(N, D)$ .
x2 : $(N,)$ or $(N, D)$ .
y : $(N,)$ with values in $\{-1, +1\}$ .
Output : scalar for 'mean' / 'sum'; same shape as input for 'none'.

Commonly used in learning-to-rank tasks such as information retrieval and recommendation systems.
A positive margin $> 0$ requires a minimum gap between scores; setting it to 0 only penalises inversions.

Examples

Ranking pairs with a margin of 0.3:
>>> import lucid
>>> import lucid.nn as nn
>>> criterion = nn.MarginRankingLoss(margin=0.3)
>>> x1 = lucid.tensor([1.0,  0.5, 2.0])
>>> x2 = lucid.tensor([0.5,  1.0, 1.5])
>>> y  = lucid.tensor([1.0, -1.0, 1.0])
>>> loss = criterion(x1, x2, y)
Strict ranking (no margin):
>>> import lucid
>>> import lucid.nn as nn
>>> criterion = nn.MarginRankingLoss()
>>> x1 = lucid.tensor([3.0, 1.0])
>>> x2 = lucid.tensor([2.0, 2.0])
>>> y  = lucid.tensor([1.0, 1.0])
>>> loss = criterion(x1, x2, y)

Methods (3)

dunder

init

→None

__init__(margin: float = 0.0, reduction: str = 'mean')

source

Initialise the MarginRankingLoss module. See the class docstring for parameter semantics.

forward

→Tensor

forward(x1: Tensor, x2: Tensor, y: Tensor)

source

Compute the loss between predictions and targets.

Parameters

x1Tensor

Input tensor.

x2Tensor

Input tensor.

yTensor

Input tensor.

Returns

Tensor

Scalar loss (or unreduced tensor depending on reduction).

extra_repr

→str

extra_repr()

source

Return a string representation of the layer's configuration.