3.0.0rc5

This is the fifth release candidate for version 3.0.0. The 3.0.0rc1 notes describe version 3 as a whole, and the migration guide covers version 2 names.

New features

• Compatible losses and miners accept a precomputed distance matrix through the keyword-only mat argument. One matrix can serve a miner and several losses, and a matrix can depend on per-batch metadata that a distance does not receive, without changing the distance object. Losses reject a matrix with no autograd graph, nothing is cached, and unsupported modules raise. See precomputed distance matrices (#211, #697).
• Every miner accepts tuples_per_anchor, which keeps a random subset of each anchor's mined tuples, without replacement. See bounding the output (#193).
• losses.anchor_batched_backward computes the gradient of a tuple loss in chunks of anchors. Its result equals a full-batch backward(), and losses whose objective does not split by anchor are rejected. See anchor_batched_backward (#586).
• losses.DecoupledContrastiveLoss implements DCL and DCLW from Decoupled Contrastive Learning by Yeh et al. See DecoupledContrastiveLoss (#375).
• losses.SelectivelyContrastiveTripletLoss implements the loss from Hard Negative Examples are Hard, but Useful by Xuan et al. See SelectivelyContrastiveTripletLoss (#287).
• regularizers.SphericalEmbeddingRegularizer implements the spherical embedding constraint from Deep Metric Learning with Spherical Embedding by Zhang et al. It differs from CenterInvariantRegularizer, which compares squared norms. See SphericalEmbeddingRegularizer (#346).
• losses.CentroidTripletLoss returns, rewritten for version 3. It implements On the Unreasonable Effectiveness of Centroids in Image Retrieval by Wieczorek et al. Classes of different sizes now work, a class with one embedding provides a negative centroid instead of raising, and swap and triplets_per_anchor are gone. The default distance is now the paper's squared Euclidean distance. Thanks to cwkeam, who contributed the original implementation, and pgrosjean, who diagnosed the failure. See CentroidTripletLoss (#451).
• losses.GE2ELoss implements both variants of Generalized End-to-End Loss for Speaker Verification by Wan et al., with the anchor left out of its own class's centroid. See GE2ELoss (#603).
• losses.CenterLoss implements the center loss from A Discriminative Feature Learning Approach for Deep Face Recognition by Wen et al. Centers are a buffer that moves only through an explicit update_centers(embeddings, labels) call, which applies the paper's update rule. See CenterLoss (#108).
• DistributedLossWrapper supports CrossBatchMemory with objective="local_anchor". Each rank uses its own rows as anchors while enqueuing the complete gathered batch, so queues stay identical across ranks. See distributed (#448).
• losses.RankNContrastLoss implements supervised contrastive regression from Rank-N-Contrast by Zha et al., for continuous targets. See RankNContrastLoss (#557).
• The ProxyNCA++ recipe maps the six enhancements of ProxyNCA++ by Teh et al. to library settings and model code. Its objective is ProxyNCALoss(softmax_scale=9) (#103).
• The class mining recipe implements hard negative class mining from the N-pairs paper by Sohn, with an executable NPairsLoss example (#109).

Fixes

• DynamicSoftMarginLoss keeps its histogram detached from autograd, so training across optimizer steps does not retain a previous batch's graph. Multi-step regressions cover this behavior (#731).
• Unnormalized distances no longer overflow float16. With float16 or bfloat16 inputs and normalize_embeddings=False, a distance is computed and returned in float32, so its losses, anchor_batched_backward, and CustomKNN return float32 too. Squared distances and dot products could previously become inf. See calling a distance.
• ManifoldLoss no longer returns NaN for large unnormalized similarities, and it now raises TypeError for a distance that is not a similarity. LpDistance previously made distant rows count as more similar.

Validation

• MultiSimilarityMiner now has regressions using the matrix reported in #723. They validate label-correct pairs on CPU and current MPS hardware. The original macOS 14.4 report was not reproduced, so this establishes current behavior rather than a confirmed fix for that historical environment.