NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #2901 most downloaded on PyPI
Composable metric learning losses, miners, distances, samplers, and retrieval metrics for PyTorch.
Latest stable
3.0.3
Last release 9 days ago
13 Nov 2026
Release timing varies
gaps range from 8 days to 1.2 years
Nearly every release is documented
notes for 56 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
221 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
Version 3.0.3 fixes numerical precision and retrieval edge cases, and speeds up fixed pair and triplet construction. Public signatures and minimum sup
Version 3.0.3 fixes numerical precision and retrieval edge cases, and speeds up
fixed pair and triplet construction. Public signatures and minimum supported
Python, PyTorch, and NumPy versions are unchanged.
MultiSupConLoss preserves label intersections under autocast. JaccardCrossBatchMemory trainingManifoldLoss preserves float64 in its graph inverse, correcting values andGE2ELoss uses stable cross entropy and cancels the common bias beforePerAnchorReducer retains float32 aggregates through its inner reducer forUniformHistogramMiner preserves tiny distance ranges and computesVICRegLoss computes low-precision statistics and returns its scalar inFixedSetOfPairs and FixedSetOfTriplets select distinct classes without
permuting every class for each tuple. Their class-uniform distribution, tuple
relationships, and seeded reproducibility are preserved. Exact tuples for an
existing seed change with the new algorithm. The
construction measurements
cover datasets with many classes; they do not measure training throughput
(#786).
FaissKNN.train and FaissKNN.add accept non-contiguous tensor views when(0, k) results from CustomKNN and FaissKNN, includingCustomKNN preserves the distance's output dtypeThanks to @Afloat16 for all nine contributions.
The original contribution commits are preserved in this release.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Version 3.0.2 fixes low-precision reductions and regularization, small-batch regularization, and NumPy sampler inputs. Public signatures and minimum s
Version 3.0.2 fixes low-precision reductions and regularization, small-batch
regularization, and NumPy sampler inputs. Public signatures and minimum
supported Python, PyTorch, and NumPy versions are unchanged.
ClassWeightedReducer multiplies and averages float16 and bfloat16 lossesCenterInvariantRegularizer widens float16 and bfloat16 inputs beforeRegularFaceRegularizer returns differentiable zero for empty and singletonSamplers preserve categorical and hashable NumPy label values and accept
views with negative strides or non-native byte order. Invalid label
dimensions and hierarchy columns produce descriptive errors at construction
(#778).
Capacity searches report a batch size only after successful confirmation.
They return no verified capacity when every probe or a confirmation fails,
preserve the confirmation failure status, and correctly refine brackets
whose starting batch is not aligned to the search granularity. Invalid
search settings are rejected before launching a probe
(#779).
Previously published benchmark measurements are unchanged.
Thanks to @Afloat16 for all five fixes. The
original contribution commits are preserved in this release.
Version 3.0.1 fixes a large time and memory regression in low-precision Euclidean distances, including the default distance used by Contrastive and Tr
Version 3.0.1 fixes a large time and memory regression in low-precision
Euclidean distances, including the default distance used by Contrastive and
TripletMargin losses. Public signatures and minimum supported Python, PyTorch,
and NumPy versions are unchanged. No migration is required.
In v3.0.0, float16 and BF16 matrices always used the direct torch.cdist
kernel to preserve nearby-point accuracy. Its CUDA backward pass can allocate
memory proportional to queries × references × embedding dimensions.
Large eager Euclidean calls now use float32 matrix evaluation when a numerical
screen shows that it is safe. Self comparisons reuse prepared inputs and keep
their diagonal exactly zero. Nearby or duplicate points, other norms, small
matrices, compiled execution, CUDA graph capture, and reduced float32 matmul
precision retain the accurate direct calculation. Global precision settings
are unchanged.
The improvement is measured on standard-normal inputs; clustered training
embeddings can still take the slower direct path. Values and gradients are
checked for random, nearby, duplicate, and mixed-scale float16/BF16 inputs.
The fix was measured at commit 32bcfa8, whose numerical code is included
unchanged in this release. Each successful timing configuration averages
900 forward/backward pairs across three fresh processes after warmup.
At BF16 batch 2,048, 128 dimensions, and four samples per class:
| GPU | Loss | v3.0.0 → fix time per pair (ms) | v3.0.0 → fix peak allocation (MiB) |
|---|---|---|---|
| RTX 5090 | Contrastive | 13.3 → 2.23 | 2,118 → 356 |
| RTX 5090 | Batch-hard + Triplet | 16.4 → 1.38 | 2,118 → 151 |
| A100 | Contrastive | 23.4 → 6.32 | 2,118 → 308 |
| A100 | Batch-hard + Triplet | 30.0 → 5.47 | 2,118 → 103 |
These are loss/miner measurements, excluding an encoder, optimizer, and data
loading. Peak allocation is total PyTorch tensor allocation, not total device
usage. The fix does not beat v2.9.0 in every case: RTX 5090 batch-hard triplet
still takes 25.6% longer in this configuration. See the
complete comparison and limitations
for process ranges, controls, numerical checks, and reproduction instructions.
The new five-GPU benchmark report compares
released v3.0.0 with v2.9.0 on RTX 4090, RTX 5090, L40S, A100, and H100 systems.
It covers seven common losses plus batch-hard triplet mining, absolute forward
and backward time, total and incremental peak memory, and verified batch limits.
CSV tables, SVG scaling charts, raw measurements, and hardware/source provenance
are included. Those original release results remain separate from the
two-GPU fix measurements.
Version 3 focuses the library on composable metric-learning components used from ordinary PyTorch code. It removes training and evaluation orchestrati
Version 3 focuses the library on composable metric-learning components used from
ordinary PyTorch code. It removes training and evaluation orchestration, makes tensor
and extension contracts explicit and typed, and corrects numerical, distributed, and
retrieval behavior. It adds losses, evaluation tools, and memory controls.
It is a clean break from version 2, with no compatibility aliases. Look up any version 2
name in the migration guide. This page summarizes the changes
since 2.9.0, and each release candidate's notes hold the complete list:
rc1, rc2, rc3, rc4, and
rc5.
faiss for the Faiss retrieval backends, and clustering for NMIwith-hooks, with-hooks-cpu, docs, and dev extras are removed.py.typed. pytorch_metric_learning.__version__ isimportlib.metadata.version("pytorch-metric-learning").InferenceModel, the datasetsevaluation, distributed wrappers indistributed, and utils.indexing replaces utils.loss_and_miner_utils. Every otherutils is private. See the public API.ref_emb=None means a query set compared with itself, andref_emb describes a separate set. Miners return named tuples, labels must beforward.torch.nn.Module directly andcompute_loss, custom reducerselement_reduction, and classification losses derive from BaseProxyLoss.MPerClassSampler yields whole batches, so pass it asDataLoader(dataset, batch_sampler=sampler). It takes batch_size and num_batches.DotProductSimilarity() computes a plain dot product. Passnormalize_embeddings=True for the previous behavior.TripletMarginLoss defaults to margin=0.2. Pass margin=0.05 for the previousAccuracyCalculator searches with exact PyTorch squared Euclidean distance on theProxyAnchorLoss andProxyNCALoss, and the rc1 notes give the details.Losses:
Everything else:
regularizers.SphericalEmbeddingRegularizerlosses.anchor_batched_backward computes amat.tuples_per_anchor.SelfSupervisedLoss accepts more than two views.CrossBatchMemory accepts label sets,DistributedLossWrapper supports it withobjective="local_anchor".evaluation.select_threshold chooses aevaluation.ndcg_metric addssamplers.FixedSetOfPairs draws a fixed, balancedFaissKNN passes CUDA tensors directly to a GPU index on the same device, extractedNCALoss, ProxyNCALoss, NTXentLoss, ManifoldLoss, and RankedListLoss computeManifoldLoss raises TypeError for a distance that is not aNTXentLoss preserves small losses under large score offsets (contributed byTupletMarginLoss uses exact endpoint angles (adapted from a contributionCrossBatchMemory validates inputs before changing its queue, and DynamicSoftMarginLossAccuracyCalculator keeps label dtypes, so large identifiers no longer collideRegression tests from @kocean9-freedom and @Afloat16 cover DistanceWeightedMiner, PNPLoss,
and HistogramLoss.
NTXentLoss, TupletMarginLoss, and LiftedStructureLoss reduce negatives per anchorAccuracyCalculator retrieves only the neighbors the selected metrics need.See measuring performance for workloads and commands.
anchor_batched_backward keeps what the input dtype selects in a full loss. Float16 andeps and torch.cdist kernel, sobackward(). Chunks alsoinf.Thank you to @Afloat16, @akshitkhokhani, @AryanRG, @chingisooinar,
@domenicoMuscill0, @kocean9-freedom, and @QibinLiang for the contributions
incorporated into v3.0.0, including PRs adapted to its new architecture.
Thanks also to @cwkeam for the original CentroidTripletLoss implementation and
@pgrosjean for diagnosing its failure, and to everyone who reported issues,
suggested features, and helped test the release.
See the full project acknowledgements
for earlier contributions, upstream projects, and supporters.
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 name
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.
mat argument. One matrix can serve a miner and several losses, andtuples_per_anchor, which keeps a random subset of eachlosses.anchor_batched_backward computes the gradient of a tuple loss in chunksbackward(), and losses whoseanchor_batched_backwardlosses.DecoupledContrastiveLoss implements DCL and DCLW fromlosses.SelectivelyContrastiveTripletLoss implements the loss fromregularizers.SphericalEmbeddingRegularizer implements the spherical embeddingCenterInvariantRegularizer, which compares squaredlosses.CentroidTripletLoss returns, rewritten for version 3. It implementsswap and triplets_per_anchorlosses.GE2ELoss implements both variants oflosses.CenterLoss implements the center loss fromupdate_centers(embeddings, labels) call, which applies the paper's update rule. SeeDistributedLossWrapper supports CrossBatchMemory with objective="local_anchor".losses.RankNContrastLoss implements supervised contrastive regression fromProxyNCALoss(softmax_scale=9)NPairsLoss exampleDynamicSoftMarginLoss keeps its histogram detached from autograd, so trainingnormalize_embeddings=False, a distance is computed and returned in float32, so itsanchor_batched_backward, and CustomKNN return float32 too. Squared distancesinf. SeeManifoldLoss no longer returns NaN for large unnormalized similarities, and it nowTypeError for a distance that is not a similarity. LpDistance previouslyMultiSimilarityMiner now has regressions using the matrix reported inThis is the fourth release candidate for version 3.0.0. It adds evaluation utilities and fixed-pair sampling. The 3.0.0rc1 notes describe version 3 as
This is the fourth release candidate for version 3.0.0. It adds evaluation
utilities and fixed-pair sampling. The 3.0.0rc1 notes describe
version 3 as a whole, and the migration guide covers
version 2 names.
evaluation.select_threshold chooses a match/no-match threshold from validationMatchFinder. Built-in metrics are match_accuracy,match_balanced_accuracy, and match_f1. Seesamplers.FixedSetOfPairs draws a fixed, balanced set of positive and negativeDataLoader-to-loss loopevaluation.ndcg_metric registers NDCG from a graded relevance function,RetrievalInputs gains the required fields reference_labels andref_includes_query. Only code that constructs RetrievalInputs directlyRetrievalMetric gains exclude_lone_queries, default True. A metric thatFalse decides through NaN which queries count.AccuracyCalculator no longer raises TypeError with MPS inputs. The searchAccuracyCalculatorThis is the third release candidate for version 3.0.0. It changes defaults and sampler behavior that are easier to change before the final release. Th
This is the third release candidate for version 3.0.0. It changes defaults and
sampler behavior that are easier to change before the final release. The
3.0.0rc1 notes describe version 3 as a whole, and the
migration guide covers version 2 names.
DotProductSimilarity() now computes a plain dot product. Passnormalize_embeddings=True for the previous behavior. NPairsLoss andNormalizedSoftmaxLoss request normalization explicitly, so their defaultTripletMarginLoss now defaults to margin=0.2, matchingTripletMarginMiner and FaceNet. Pass margin=0.05 for the previous defaultSelfSupervisedLoss accepts more than two views:loss_func(view_1, view_2, view_3). All views of a sample are positives ofsymmetric=False, only the first view provides anchorsMPerClassSampler now yields whole batches. Pass it asDataLoader(dataset, batch_sampler=sampler) and remove the DataLoaderbatch_size. batch_size is a required sampler argument, and num_batchesnum_samplesMPerClassSampler rotates through shuffled passes of classes and of eachThe macOS OpenMP section now covers
using Faiss and UMAP in one process. Importing this package loads neither
Faiss nor UMAP, so the conflict arises only when an application uses Faiss
with PyTorch
(#617).
Recipe pages link to readable source on GitHub for the matching release
instead of Python files that browsers download.
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 describe vers
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 describe version 3 as a whole, and the
migration guide covers version 2 names.
threshold. Adapted from a contribution by Qibin LiangCrossBatchMemory4MultiLabel class is replaced byCrossBatchMemory withlabel_shape and pair_function, and pair tuples stay standard instead ofSubCenterArcFaceLoss instead of wrapping a loss and changinga and b.FaissKNN passes CUDA tensors directly to a GPU index on the same device.NTXentLoss subtracts each anchor's maximum negative score before temperatureTupletMarginLoss uses exact endpoint angles with a zero angular gradient at[-1, 1]. Adapted from a contribution by AryanRGDistanceWeightedMiner 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).
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).
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).
modify_cosine_of_target_classes in subclasses of ArcFaceLoss, CosFaceLoss,LargeMarginSoftmaxLoss now receives labels as a second argument.BaseMetricLossFunction subclass can set the class attribute label_ndim(batch, classes) labels.This is the first release candidate for version 3.0.0.
This is the first release candidate for version 3.0.0.
Version 3 focuses the library on composable metric-learning components used
from ordinary PyTorch code. It removes training and evaluation orchestration,
makes tensor and extension contracts explicit and typed, and corrects numerical,
distributed, and retrieval behavior. It is a clean break: there are no
compatibility aliases. Look up any version 2 name in the
migration guide.
faiss (Faiss 1.15.1 or newer) for the Faiss retrievalclustering (scikit-learn 1.9.1 or newer) for NMI and AMI.with-hooks, with-hooks-cpu, docs, and dev extras are removed, soclustering extra.py.typed. Read the installed version withimportlib.metadata.version("pytorch-metric-learning");pytorch_metric_learning.__version__ is removed.pytorch_metric_learning.evaluationAccuracyCalculator, CustomKNN, FaissKNN, FaissKMeans,MatchFinder), replacing utils.accuracy_calculator, utils.inference,utils.retrieval.pytorch_metric_learning.distributed.utils.loss_and_miner_utils is replaced by utils.indexing. Everything elseutils, including the former common functions, is private.__all__ of distances, losses, miners,reducers, regularizers, samplers, evaluation, distributed, types,utils.indexing; see versioning.losses.pnp_loss orevaluation.retrieval, are not public import paths, and their helpers areremove_self_comparisons, add_to_index_and_search, andreturn_results.types exports the aliases and result tuples used in public signatures:PNPVariant, AnchorAggregation, DistributedObjective,SubCenterOutliers, ArrayLike, NeighborLimit, MetricNeighbors, andDatasetLabels.evaluation exports the built-in retrieval metric functionsprecision_at_k, precision_at_1, r_precision, mean_average_precision,mean_average_precision_at_r, and mean_reciprocal_rank for reuse in customref_emb=None means the query set is its own reference set, andref_emb, even the same tensor,ref_emb, supply both labels andref_labels or neither.ValueError.forward; place modules with .to(device, dtype).types.PairIndices or types.TripletIndices named tuples.utils.indexing accept these or plain 3- or 4-tuples.utils.indexing.pairs_to_triplets validates its input like indices_tuple;ValueError.{"losses": tensor, "indices": ..., "divisor": optional}.indices: None for an already reduced value, one(anchor, other) pair, or a triplet. Thereduction_type key is removed.indices_tuple, miner output, and loss terms must beint64 or int32; other dtypes raise TypeError. A loss term's indicesNone, one tensor, a pair, or a triplet; 1-tuples are rejected.indices_tuple with no indices selects nothing. Miner-weightedNone for no restriction.TypeError for the wrong type and ValueError for anpython -O. HistogramLoss(num_bins=...),LargeMarginSoftmaxLoss and SphereFaceLoss margins, and SoftTripleLossRegularFaceRegularizer with a distance that is not a similarity nowTypeError.DynamicSoftMarginLoss,HistogramLoss, ManifoldLoss, P2SGradLoss, PNPLoss,ThresholdConsistentMarginLoss) take no reducer, and P2SGradLoss takes nodistance; both were ignored and now raise TypeError. LpRegularizer andZeroMeanRegularizer likewise take no distance.VICRegLoss requires at least two rows; a one-row batch raises ValueErrorBaseMetricLossFunction, BaseMiner, and BaseRegularizer extendtorch.nn.Module directly and take keyword-only options typed bytypes.LossOptions and types.RegularizerOptions. The mixins andweight. Except for P2SGradLoss, they derive from the newlosses.BaseProxyLoss and take keyword-only weight_regularizer,weight_reg_weight, and weight_init_func.compute_loss(embeddings, labels, indices_tuple, ref_emb, ref_labels). A custom loss may return {} when nothing is valid;sub_loss_names andzero_losses are removed. GenericPairLoss subclasses implementpair_loss(mat, pairs).element_reduction(losses, anchors, embeddings, labels); the pair and triplet hooks are removed. Terms with a divisorProxyAnchorLoss, MarginLoss, SparseCentersRegularizer) requireDivisorReducer, alone or inside MultipleReducers; other reducers raiseValueError instead of ignoring the divisor.loss_terms(...) returnsforward(embeddings, labels, indices_tuple=None, ref_emb=None, ref_labels=None) and restrict their search to optional candidate tuples.HDCMiner.set_idx_externally and reset_idx. TheDistributedMinerWrapper is nowindices_tuple, so pass references by keyword.BaseDistance.is_inverted is a classBaseDistance.pairwise(query, ref) computes normalized, poweredsmallest_dist and largest_dist are removed.DistributedLossWrapper and DistributedMinerWrapper takeobjective="global" or "local_anchor" instead of efficient.ArcFaceLoss and SubCenterArcFaceLoss margins are in radians (defaultLargeMarginSoftmaxLoss requires an integer margin.CircleLoss(margin=...) replaces m; HistogramLoss(num_bins=...) replacesn_bins and delta; RankedListLoss(neg_temperature=..., pos_temperature=...)Tn and Tp; AngularMiner(alpha=...) replaces angle;PerAnchorReducer(aggregation="mean") or aggregation="sum" replacesaggregation_func.ManifoldLoss(embedding_size, num_proxies, lambda_c, ...) replaces l, K,lambdaC; proxy assignments are passed as labels.P2SGradLoss(num_classes, embedding_size) matches the other classificationMultipleLosses takes mappings for losses, miners, and weights,BaseMetricLossFunction or MultipleLosses values, and has theforward signature as a loss, including ref_emb and ref_labels.CrossBatchMemory, SelfSupervisedLoss, and DistributedLossWrapper accepttypes.MetricLoss). Its per-loss miners select from a suppliedindices_tuple as candidates.CosineSimilarity() takes no options; useDotProductSimilarity(normalize_embeddings=True, ...) for other norms orLiftedStructureLoss and GeneralizedLiftedStructureLoss take(pos_margin, neg_margin) positionally, like ContrastiveLoss.MarginLoss names its main term "loss"; DynamicSoftMarginLoss.hist_ ishist.SubCenterArcFaceLoss.get_outliers(embeddings, labels, threshold_radians=...)SubCenterOutliers(outliers, dominant_centers).MPerClassSampler(num_samples=...) replaces length_before_new_iter.MatchFinder.get_matching_pairs is replaced by get_match_matrix (a booleanget_match_indices (an (num_matches, 2) index tensor).AccuracyCalculator no longer takes return_per_class.get_accuracy returns dict[str, float]; get_accuracy_per_class returnscustom_metrics={name: RetrievalMetric(function, neighbors=...)} orClusteringMetric(function); a retrieval metric returns one value per querymetric_functions(),requires_knn(), requires_clustering(), aggregate(), and thecalculate_* methods are removed. Naming a clustering metric inget_accuracy_per_class(include=...) raises ValueError.generator;InferenceModel, run_pca, and thedatasets package. The training andcollect_stats, COLLECT_STATS, and attributes such asminer.pos_pair_dist). Compute diagnostics from returned tensors or withforward.DoNothingReducer (use loss_terms), EmbeddingsAlreadyPackagedAsTriplets,TuplesToWeightsSampler, BaseLossWrapper, the common_functions logging,AccuracyCalculator searches with exact PyTorch squared Euclidean distanceCustomKNN) on the input device instead of Faiss, and selects a device onlykmeans_func.k is capped at the neighbors available in each call.k below a query's relevant count divides by thek. That configuration still logs a warning;k="max_bin_count".utils.indexing.convert_to_triplets defaults to all triplets.ProxyAnchorLoss applies miner weights as multiplicative weights on thew - 1 to the exponent. Results withoutProxyNCALoss miner weights count every position in the mined tuples, likePerAnchorReducer(aggregation="mean") averages over anchors that haveCircleLoss, GeneralizedLiftedStructureLoss, MultiSimilarityLoss,SupConLoss, SmoothAPLoss, and PNPLoss exclude anchors that lack theNCALoss and FastAPLoss already did.SupConLoss follows the paper when a batch has positives but no negatives,NCALoss and ProxyNCALoss compute the objective in log space. A singlesoftmax_scale values no longer underflow hard examples to zero loss andNTXentLoss computes per-anchor log-sum-exp directly; float16 hard positivesAccuracyCalculator relevance counts, lone-query detection, andk="max_bin_count" honor custom label comparators, so a comparator thatCrossBatchMemory rejects labels that change value when converted tolabel_dtype, and validates inputs and runs the wrapped miner and lossPerAnchorReducer aggregates the supplied losses by anchor, supportsAngularMiner measures angles on normalized embeddings, matchingAngularLoss.LiftedStructureLoss positive pairs without negatives contribute zero, as inref_emb, which it mishandled.SmoothAPLoss derives positives from labels instead of positional blocks.ThresholdConsistentMarginLoss uses ref_emb and its configured similarity.TupletMarginLoss no longer returns NaN for identical anchors andAngularLoss normalizes negatives.RankedListLoss computes exact weighted means without a 1e-5 offset andTripletMarginLoss(swap=True) measures positive-negative distances on theFaissKNN uses a GPU only with a GPU build of Faiss.BatchHardMiner, BatchEasyHardMiner, DistanceWeightedMiner, andMultiSimilarityMiner return empty tuples for an empty query or referenceIndexError.AccuracyCalculator runs under torch.no_grad() and builds no autogradknn_func returning indices outside the reference set, such as aFaissKNN(reset_before=False) whose index has grown, raises ValueErrorIndexError, and so do indices not shaped (len(query), k).P2SGradLoss, so zero and tiny rows no longer give NaN values or gradients.ThresholdConsistentMarginLoss sums its penalties and DynamicSoftMarginLossLpDistance.pairwise no longer adds1e-6, so identical rows give 0, matching the distance matrix.AngularLoss takes negatives from labels even when a miner supplies onlyGeneralizedLiftedStructureLoss no longer adds a hinge for anchors missingPNPLoss, labeled ManifoldLoss, and P2SGradLoss give a differentiableDistanceWeightedMiner normalizes weights per anchor over eligible negatives,LpDistance preserves small float16 and bfloat16 distances and theirforward; one float64AccuracyCalculator keeps label dtypes, so large integer identifiers noMPerClassSampler yields exactly len(sampler) indices.MatchFinder.is_match applies the configured normalization and power.NTXentLoss, TupletMarginLoss, and LiftedStructureLoss reduce negativesAccuracyCalculator retrieves only the neighbors the selected metrics need,precision_at_1 and k=None, 2000 queries againstLpDistance computes half-precision matrices with torch.cdist in float32See performance measurements for the measured workloads.
Added SmoothAPLoss . Thanks @ir2718 !
Fixed some module import issues.
Fixed some module import issues.
Added the Datasets module for easy downloading of common datasets:
Added ThresholdConsistentMarginLoss.
Changed the emb argument of DistributedLossWrapper.forward to embeddings to be consistent with the rest of the library.
DistributedLossWrapperemb argument of DistributedLossWrapper.forward to embeddings to be consistent with the rest of the library.DistributedLossWrapper is being used in a non-distributed setting.Allow scaling up the memory and batch size when using TripletMarginMiner
Thanks @mkmenta !
This is identical to v2.4.0, but includes the LICENSE file which was missing from v2.4.0.
This is identical to v2.4.0, but includes the LICENSE file which was missing from v2.4.0.
Added DynamicSoftMarginLoss. See PR #659. Thanks @domenicoMuscill0!
Added HistogramLoss. See pull request #651. Thanks @domenicoMuscill0!
Added ManifoldLoss. See pull request #635. Thanks @domenicoMuscill0!
symmetric flag to SelfSupervisedLoss. If True, then the embeddings in both embeddings and ref_emb are used as anchors. If False, then only the embeddings in embeddings are used as anchors. The previous behavior was equivalent to symmetric=False. Now the default is symmetric=True, because this is usually what is done in self supervised papers (e.g. SimCLR).Fixed bug where set_stats was not being called in TripletMarginMiner
set_stats was not being called in TripletMarginMiner (#628)HierarchicalSampler extend torch.utils.data.Sampler instead of torch.utils.data.BatchSampler (#613)Fixes bug where BaseDistance.initial_avg_query_norm was not actually being set
BaseDistance.initial_avg_query_norm was not actually being set (#620)New loss function: PNPLoss. Thanks @interestingzhuo!
New loss function: PNPLoss. Thanks @interestingzhuo!
### Bug Fixes - Fixed #591. Thanks @HSinger04!
…in the future without causing more breaking changes.
You don't have to create labels for self-supervised learning anymore:
from pytorch_metric_learning.losses import SelfSupervisedLoss
loss_func = SelfSupervisedLoss(TripletMarginLoss())
embeddings = model(data)
augmented = model(augmented_data)
loss = loss_func(embeddings, augmented)
Thanks @cwkeam!
The order and naming of arguments has changed.
get_accuracy(
query,
reference,
query_labels,
reference_labels,
embeddings_come_from_same_source=False
)
get_accuracy(
query,
query_labels,
reference=None,
reference_labels=None
ref_includes_query=False
)
The benefits of this change are:
query is reference, then you only need to pass in query, query_labelsref_includes_query is shorter and clearer in meaning than embeddings_come_from_same_sourceSome example usage of the new format:
# Accuracy of a query set, where the query set is also the reference set:
get_accuracy(query, query_labels)
# Accuracy of a query set with a separate reference set:
get_accuracy(query, query_labels, ref, ref_labels)
# Accuracy of a query set with a reference set that includes the query set:
get_accuracy(query, query_labels, ref, ref_labels, ref_includes_query=True)
BaseMiner instead of BaseTupleMinerMiners must extend BaseMiner because BaseTupleMiner no longer exists
enqueue_idx is now enqueue_maskBefore, enqueue_idx specified the indices of embeddings that should be added to the memory bank.
Now, enqueue_mask[i] should be True if embeddings[i] should be added to the memory bank.
The benefit of this change is that it fixed an issue in distributed training.
Here's an example of the new usage:
# enqueue the second half of a batch
enqueue_mask = torch.zeros(batch_size).bool()
enqueue_mask[batch_size/2:] = True
Before:
loss_fn = VICRegLoss()
loss_fn(emb, ref_emb)
Now:
loss_fn = VICRegLoss()
loss_fn(emb, ref_emb=ref_emb)
The reason is that VICRegLoss now uses the forward method of BaseMetricLossFunction, to allow for possible generalizations in the future without causing more breaking changes.
mining_funcs and dataset have swapped orderThis is to allow mining_funcs to be optional.
Before if you didn't want to use miners:
MetricLossOnly(
models,
optimizers,
batch_size,
loss_funcs,
mining_funcs = {},
dataset = dataset,
)
Now:
MetricLossOnly(
models,
optimizers,
batch_size,
loss_funcs,
dataset,
)
The following classes/functions were removed
losses.CentroidTripletLoss (it contained a bug that I don't have time to figure out)miners.BaseTupleMiner (use miners.BaseMiner instead)miners.BaseSubsetBatchMiner (rarely used)miners.MaximumLossMiner (rarely used)trainers.UnsupervisedEmbeddingsUsingAugmentations (rarely used)utils.common_functions.Identity (use torch.nn.Identity instead)Nothing published for this version
Nothing published for this version
Fixed #472, in which enqueue_idx for CrossBatchMemory could not be passed into DistributedLossWrapper
enqueue_idx for CrossBatchMemory could not be passed into DistributedLossWrapperembedding_memory and label_memory to buffers, so they can be saved and loaded as state dicts and transferred to devices use .to(device).Resolved https://github.com/KevinMusgrave/pytorch-metric-learning/issues/565
Resolved https://github.com/KevinMusgrave/pytorch-metric-learning/issues/565
Fixed bug where labels were always required for DistributedLossWrapper
Fixes an edge case in ArcFaceLoss. Thanks @ElisonSherton!
Fixes an edge case in ArcFaceLoss. Thanks @ElisonSherton!
Relevant links:
Fixed bug where DistributedMinerWrapper would crash when world_size == 1
DistributedMinerWrapper would crash when world_size == 1 (#542)To be consistent with the common definition of mean average precision, the divisor has been changed again:
To be consistent with the common definition of mean average precision, the divisor has been changed again:
min(k, num_relevant)num_relevantAgain, this has no effect on mean_average_precision_at_r
Fixed a bug in mean_average_precision in AccuracyCalculator. Previously, the divisor for each sample was the number of correctly retrieved samples. In
Fixed a bug in mean_average_precision in AccuracyCalculator. Previously, the divisor for each sample was the number of correctly retrieved samples. In the new version, the divisor for each sample is min(k, num_relevant).
For example, if class "A" has 11 samples, then num_relevant is 11 for every sample with the label "A".
k = 5, meaning that 5 nearest neighbors are retrieved for each sample, then the divisor will be 5.k = 100, meaning that 100 nearest neighbors are retrieved for each sample, then the divisor will be 11.The bug in previous versions did not affect mean_average_precision_at_r.
Added additional shape checks to AccuracyCalculator.get_accuracy.
DistributedLossWrapper and DistributedMinerWrapper now support ref_emb and ref_labels:
DistributedLossWrapper and DistributedMinerWrapper now support ref_emb and ref_labels:
from pytorch_metric_learning import losses
from pytorch_metric_learning.utils import distributed as pml_dist
loss_func = losses.ContrastiveLoss()
loss_func = pml_dist.DistributedLossWrapper(loss_func)
loss = loss_func(embeddings, labels, ref_emb=ref_emb, ref_labels=ref_labels)
Thanks @NoTody for PR #503
In previous versions, when embeddings_come_from_same_source == True, the first nearest-neighbor of each query embedding was discarded, with the assump
In previous versions, when embeddings_come_from_same_source == True, the first nearest-neighbor of each query embedding was discarded, with the assumption that it must be the query embedding itself.
While this is usually the case, it's not always the case. It is possible for two different embeddings to be exactly equal to each other, and discarding the first nearest-neighbor in this case can be incorrect.
This release fixes this bug by excluding each embedding's index from the k-nn results.
In order for the above bug fix to work, AccuracyCalculator now requires that reference[:len(query)] == query when embeddings_come_from_same_source == True. For example, the following will raise an error:
query = torch.randn(100, 10)
ref = torch.randn(100, 10)
ref = torch.cat([ref, query], dim=0)
AC.get_accuracy(query, ref, labels1, labels2, True)
# ValueError
To fix this, move query to the beginning of ref:
query = torch.randn(100, 10)
ref = torch.randn(100, 10)
ref = torch.cat([query, ref], dim=0)
AC.get_accuracy(query, ref, labels1, labels2, True)
Note that this change doesn't affect the case where query is ref.
Bumped the record-keeper version to fix issue #497
Bumped the record-keeper version to fix issue #497
For some loss functions, labels are now optional if indices_tuple is provided: `python loss = loss_func(embeddings, indices_tuple=pairs) `
For some loss functions, labels are now optional if indices_tuple is provided:
loss = loss_func(embeddings, indices_tuple=pairs)
The losses for which you can do this are:
This issue has come up several times:
#412 #490 #482 #473 #179 #263
Added InstanceLoss. See #410 by @layumi
Fixed a bug in BatchEasyHardMiner where get_max_per_row was not always returning correct values, resulting in invalid pairs and triplets. #476
get_max_per_row was not always returning correct values, resulting in invalid pairs and triplets. #476Fixed ThresholdReducer being incompatible with older versions of PyTorch
torch.cat call.Nothing published for this version
Added a `batch_size` parameter to CustomKNN. This computes k-nn per batch of query embeddings (using BatchedDistance), which requires less memory than
batch_size parameter to CustomKNN. This computes k-nn per batch of query embeddings (using BatchedDistance), which requires less memory than computing the entire distance matrix at once.Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
## New Loss Function: SubCenterArcFace - Documentation - Example notebook - Paper - Issue - Pull Request Thanks @chingisooinar!
Thanks @chingisooinar!
## Bug fixes - #427 - #428
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Implementation of On the Unreasonable Effectiveness of Centroids in Image Retrieval
Implementation of On the Unreasonable Effectiveness of Centroids in Image Retrieval
Implementation of VICReg: Variance-Invariance-Covariance Regularization for Self-Supervised Learning
"mean_reciprocal_rank".return_per_class argument for AccuracyCalculator. This is like avg_of_avgs but returns the accuracy per class, instead of averaging them for you.#369 #372 #374 #394
Thanks to @cwkeam and @mlw214!
Nothing published for this version
Nothing published for this version
You can separate the source of anchors and positive/negatives. In the example below, anchors will be selected from `embeddings and positives/negatives
You can separate the source of anchors and positive/negatives. In the example below, anchors will be selected from embeddings and positives/negatives will be selected from ref_emb.
loss_fn = TripletMarginLoss()
loss = loss_fn(embeddings, labels, ref_emb=ref_emb, ref_labels=ref_labels)
efficient=True: each process uses its own embeddings for anchors, and the gathered embeddings for positives/negatives. Gradients will not be equal to those in non-distributed code, but the benefit is reduced memory and faster training.efficient=False: each process uses gathered embeddings for both anchors and positives/negatives. Gradients will be equal to those in non-distributed code, but at the cost of doing unnecessary operations (i.e. doing computations where both anchors and positives/negatives have no gradient).The default is False. You can set it to True like this:
from pytorch_metric_learning import losses
from pytorch_metric_learning.utils import distributed as pml_dist
loss_func = losses.ContrastiveLoss()
loss_func = pml_dist.DistributedLossWrapper(loss_func, efficient=True)
Documentation: https://kevinmusgrave.github.io/pytorch-metric-learning/distributed/
You can use a different type of faiss index:
import faiss
from pytorch_metric_learning.utils.accuracy_calculator import AccuracyCalculator
from pytorch_metric_learning.utils.inference import FaissKNN
knn_func = FaissKNN(index_init_fn=faiss.IndexFlatIP, gpus=[0,1,2])
ac = AccuracyCalculator(knn_func=knn_func)
You can also use a custom distance function:
from pytorch_metric_learning.distances import SNRDistance
from pytorch_metric_learning.utils.inference import CustomKNN
knn_func = CustomKNN(SNRDistance())
ac = AccuracyCalculator(knn_func=knn_func)
Relevant docs:
https://github.com/KevinMusgrave/pytorch-metric-learning/issues/204 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/251 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/256 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/292 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/330 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/337 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/345 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/347 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/349 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/353 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/359 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/361 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/362 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/363 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/368 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/376 https://github.com/KevinMusgrave/pytorch-metric-learning/issues/380
Thanks to @yutanakamura-tky and @KinglittleQ for pull requests, and @mensaochun for providing helpful code in #380
Nothing published for this version
One column per quarter.