torch.nn.MarginRankingLossOptions

Margin Ranking Loss: for ranking tasks where you want to rank one input higher than another.

Measures relative ranking between two inputs with a margin. Given two inputs and a target (1 or -1), pushes input1 to be higher ranked than input2 (target=1) or lower (target=-1) by at least margin. Common in:

Learning to rank (information retrieval)
Preference learning (which item is better)
Recommender systems (ranking items)
Relative importance ranking

When to use MarginRankingLoss:

Pair-wise ranking (comparing two items)
Learning relative preferences
Information retrieval (ranking search results)
When you have pairs to rank, not triplets
Simpler than triplet loss (2 instead of 3 samples)

Trade-offs:

vs TripletMarginLoss: Ranking uses 2 samples (relative), triplet uses 3 (relative to anchor)
vs Triplet: Simpler but less powerful (doesn't anchor to reference)
Flexibility: Works with any scalar outputs, not just embeddings
Use case: Ranking/preference learning, not embedding learning

Algorithm: For each pair (input1, input2) with target y ∈ {1, -1}:

If y == 1: loss = max(0, margin - input1 + input2)
If y == -1: loss = max(0, margin + input1 - input2)

The loss encourages input1 > input2 + margin when target=1.

Definition

export interface MarginRankingLossOptions {
  /** Margin for ranking loss (default: 0) */
  margin?: number;
  /** How to reduce loss across batch (default: 'mean') */
  reduction?: Reduction;
}

margin(number)optional: – Margin for ranking loss (default: 0)
reduction(Reduction)optional: – How to reduce loss across batch (default: 'mean')

Examples

// Learning to rank: document A should rank above document B
const margin_loss = new torch.nn.MarginRankingLoss(0.5);

// Relevance scores from model for query
const doc_a_score = torch.tensor([0.9, 0.7, 0.5]);
const doc_b_score = torch.tensor([0.6, 0.8, 0.4]);

// Target: 1 means doc_a should rank higher, -1 means doc_b should rank higher
const target = torch.tensor([1, -1, 1]);

const loss = margin_loss.forward(doc_a_score, doc_b_score, target);
// Loss encourages: doc_a_score > doc_b_score + margin when target=1

// Recommender system: prefer liked items over disliked
class PreferenceScorer extends torch.nn.Module {
  fc1: torch.nn.Linear;
  fc2: torch.nn.Linear;

  constructor() {
    super();
    this.fc1 = new torch.nn.Linear(128, 64);
    this.fc2 = new torch.nn.Linear(64, 1);
  }

  forward(x: torch.Tensor): torch.Tensor {
    let h = torch.nn.functional.relu(this.fc1.forward(x));
    return this.fc2.forward(h);
  }
}

const scorer = new PreferenceScorer();
const margin_loss = new torch.nn.MarginRankingLoss(0.2);

// For each user, score items they liked vs disliked
const liked_item = torch.randn([32, 128]);
const disliked_item = torch.randn([32, 128]);

const liked_score = scorer.forward(liked_item);
const disliked_score = scorer.forward(disliked_item);

const target = torch.ones([32]);  // User prefers liked over disliked
const loss = margin_loss.forward(liked_score, disliked_score, target);