# 3.0.0rc2

This is the second release candidate for version 3.0.0. It adds contributed
losses and corrects two numerical issues. The
[3.0.0rc1 notes](3.0.0rc1.md) describe version 3 as a whole, and the
[migration guide](../migration-2-to-3.md) covers version 2 names.

## New features

- [MultiSupConLoss](../losses/multi_supcon_loss.md) adds supervised contrastive
  learning for boolean label sets, with Jaccard-weighted positives and an
  inclusive `threshold`. Adapted from a contribution by Qibin Liang
  ([#667](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/667)):
  the separate `CrossBatchMemory4MultiLabel` class is replaced by
  [`CrossBatchMemory`](../losses/cross_batch_memory.md#label-sets) with
  `label_shape` and `pair_function`, and pair tuples stay standard instead of
  carrying a similarity matrix. The threshold is inclusive as in the paper, and
  two empty label sets have similarity 1.
- [DynamicArcFaceLoss](../losses/dynamic_arcface_loss.md) adds class-size margins
  for long-tailed data. Adapted from a contribution by chingis
  ([#452](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/452)):
  it derives from `SubCenterArcFaceLoss` instead of wrapping a loss and changing
  its margin on each forward, and takes the paper's margin bounds instead of
  `a` and `b`.
- `FaissKNN` passes CUDA tensors directly to a GPU index on the same device.
  Sharded multi-GPU indices and tensors on another GPU keep CPU copies. Extracted
  from a contribution by Domenico Muscillo
  ([#643](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/643)).

## Numerical corrections

- `NTXentLoss` subtracts each anchor's maximum negative score before temperature
  scaling and uses softplus, which preserves small losses under large common
  score offsets. Contributed by Afloat
  ([#758](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/758)).
- `TupletMarginLoss` uses exact endpoint angles with a zero angular gradient at
  nonzero margin, uses the cosine directly at zero margin, and clamps only values
  outside `[-1, 1]`. Adapted from a contribution by AryanRG
  ([#765](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/765)).

## Regression coverage

- `DistanceWeightedMiner` tests now cover 65,536 eligible negatives,
  high-dimensional anchors, nearly antipodal negatives above
  `nonzero_loss_cutoff`, and the strict cutoff boundary. Adapted from
  contributions by kocean9-freedom
  ([#764](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/764)).

- `PNPLoss` tests now check all five variants against independent scalar values
  and analytic embedding gradients, half-precision exponent overflow, masked
  comparisons, and float32 negative tails with zero absolute tolerance. Adapted
  from a contribution by Afloat
  ([#759](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/759)).

- `HistogramLoss` tests now check endpoint probability mass, interior
  interpolation values and slopes, and collapsed and opposite embeddings in each
  dtype. Adapted from a contribution by Afloat
  ([#756](https://github.com/KevinMusgrave/pytorch-metric-learning/pull/756)).

## Extension changes

- `modify_cosine_of_target_classes` in subclasses of `ArcFaceLoss`, `CosFaceLoss`,
  and `LargeMarginSoftmaxLoss` now receives `labels` as a second argument.
- A `BaseMetricLossFunction` subclass can set the class attribute `label_ndim`
  to 2 to accept `(batch, classes)` labels.