class

TripletMarginWithDistanceLoss

extendsModule

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

source edit

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 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)

Used by 1

lucid.nn.modules

Constructors

dunder

init

→None

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

source edit

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

Instance methods

extra_repr

→str

extra_repr()

source edit

Return a string representation of the layer's configuration.

forward

→Tensor

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

source edit

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).

Default L2 distance (equivalent to 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)