class

TripletMarginWithDistanceLoss

extendsModule

TripletMarginWithDistanceLoss(distance_function: Callable[[Tensor, Tensor], Tensor] | None = None, margin: float = 1.0, swap: bool = False, reduction: str = 'mean')

source

Triplet margin loss with a user-supplied distance function.

A generalisation of TripletMarginLoss that replaces the fixed $L_p$ norm with an arbitrary differentiable distance function. Given anchor $a$ , positive $p$ , and negative $n$ embeddings and a callable $d$ :

\mathcal{L}(a, p, n) = \max\!\bigl(d(a, p) - d(a, n) + \text{margin},\; 0\bigr)

When distance_function is None, the default falls back to the Euclidean (L2) distance, making this equivalent to TripletMarginLoss with $p = 2$ .

The swap option: if True, the loss also considers $d(p, n)$ as an alternative negative distance and replaces $d(a, n)$ with $\max(d(a, n), d(p, n))$ , exploiting the triangle inequality.

Parameters

distance_functioncallable= None

A function (Tensor, Tensor) -> Tensor that computes pairwise distances along the batch dimension. Defaults to the L2 (Euclidean) distance when None.

marginfloat= 1.0

Minimum required distance gap. Default 1.0.

swapbool= False

If True, uses the triangle-inequality-based swap. Default False.

reductionstr= 'mean'

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

Attributes

distance_functioncallable

The distance function in use.

marginfloat

The margin threshold.

swapbool

Whether the swap heuristic is active.

reductionstr

The reduction mode.

Notes

anchor : $(N, D)$ .
positive : $(N, D)$ .
negative : $(N, D)$ .
Output : scalar for 'mean' / 'sum'; $(N,)$ for 'none'.

Custom distance functions allow cosine distance, Mahalanobis distance, or any learned distance to be used as the training objective without changing the loss formulation.
The distance_function must return a 1-D tensor of shape $(N,)$ — one scalar distance per sample in the batch.

Examples

Default L2 distance (equivalent to :class:`TripletMarginLoss`):
>>> import lucid
>>> import lucid.nn as nn
>>> criterion = nn.TripletMarginWithDistanceLoss(margin=1.0)
>>> anchor   = lucid.tensor([[1.0, 0.0, 0.0]])
>>> positive = lucid.tensor([[1.1, 0.0, 0.0]])
>>> negative = lucid.tensor([[5.0, 0.0, 0.0]])
>>> loss = criterion(anchor, positive, negative)
Custom cosine distance:
>>> import lucid
>>> import lucid.nn as nn
>>> import lucid.nn.functional as F
>>> def cosine_dist(a: lucid.Tensor, b: lucid.Tensor) -> lucid.Tensor:
...     cos_sim = F.cosine_similarity(a, b, dim=1)
...     return 1.0 - cos_sim
>>> criterion = nn.TripletMarginWithDistanceLoss(
...     distance_function=cosine_dist, margin=0.5
... )
>>> anchor   = lucid.tensor([[1.0, 0.0]])
>>> positive = lucid.tensor([[0.9, 0.1]])
>>> negative = lucid.tensor([[0.0, 1.0]])
>>> loss = criterion(anchor, positive, negative)

Methods (3)

dunder

init

→None

__init__(distance_function: Callable[[Tensor, Tensor], Tensor] | None = None, margin: float = 1.0, swap: bool = False, reduction: str = 'mean')

source

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

forward

→Tensor

forward(anchor: Tensor, positive: Tensor, negative: Tensor)

source

Compute the loss between predictions and targets.

Parameters

anchorTensor

Input tensor.

positiveTensor

Input tensor.

negativeTensor

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.