Components

---
name: components
description: "Routes PyTorch Metric Learning questions about losses, miners,
  distances, reducers, regularizers, self-supervised wrappers, and custom
  component implementations."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# Components

Use this sub-skill when the user needs to choose, combine, or customize the metric-learning primitives that sit below training and evaluation.

## Typical triggers

- "Which loss should I use for triplets, pairs, proxies, or self-supervision?"
- "How do I pick a miner for this batch?"
- "How do I swap the distance, reducer, or regularizer?"
- "Why does this loss need labels, a miner output, or `indices_tuple`?"
- "How do I write a custom loss or miner?"
- "Why am I getting no valid triplets, a distance-compatibility error, or a shape error?"

## In scope

- Distances: `LpDistance`, `CosineSimilarity`, `DotProductSimilarity`, `SNRDistance`, and `BatchedDistance`.
- Reducers: `MeanReducer`, `AvgNonZeroReducer`, `ThresholdReducer`, `DivisorReducer`, `PerAnchorReducer`, `MultipleReducers`, `DoNothingReducer`, `SumReducer`, `ClassWeightedReducer`.
- Regularizers: `LpRegularizer`, `CenterInvariantRegularizer`, `RegularFaceRegularizer`, `SparseCentersRegularizer`, `ZeroMeanRegularizer`.
- Miners: `TripletMarginMiner`, `MultiSimilarityMiner`, `BatchHardMiner`, `BatchEasyHardMiner`, `DistanceWeightedMiner`, `PairMarginMiner`, `AngularMiner`, `HDCMiner`, `UniformHistogramMiner`, `EmbeddingsAlreadyPackagedAsTriplets`.
- Loss families and wrappers: `TripletMarginLoss`, `ContrastiveLoss`, `MultiSimilarityLoss`, `NTXentLoss`, `AngularLoss`, `ArcFaceLoss`, `CosFaceLoss`, `NormalizedSoftmaxLoss`, `ProxyAnchorLoss`, `ProxyNCALoss`, `SelfSupervisedLoss`, `CrossBatchMemory`, `MultipleLosses`, `SmoothAPLoss`, `VICRegLoss`, and related metric/classification losses.
- Custom component authoring with `BaseMetricLossFunction`, `BaseMiner`, `loss_and_miner_utils`, and `TorchInitWrapper`.

## Out of scope

- Trainer setup, hooks, logging, and checkpointing belong in `training`.
- Accuracy calculators, testers, and nearest-neighbor inference belong in `evaluation`.
- Dataset download and sampler configuration belong in `data`.

## How to use this sub-skill

1. Start with `references/losses-miners-and-customization.md` for the compact component catalog and compatibility rules.
2. Run `scripts/smoke_components.py` on toy tensors when you need a quick sanity check for a component stack or a custom extension.
3. Read `references/troubleshooting.md` when the failure mentions labels, `indices_tuple`, no valid tuples, or an incompatible distance/reducer/regularizer.
4. For custom loss/miner implementations, follow the distilled extension patterns and use the bundled `loss_and_miner_utils` helpers instead of re-deriving tuple conversion logic.

## Common routing decisions

- If the user asks which loss or miner to use, stay here.
- If the user asks why a component rejects labels, margins, or tuple shapes, stay here.
- If the user asks how to wire the chosen component into a trainer or tester, route to `training` or `evaluation` after the component choice is settled.

## Useful public facts

- Most metric losses and miners accept a `distance` object.
- Some losses can be called with `indices_tuple` instead of labels when the tuple has already been mined.
- Classification-style losses typically need `num_classes` and `embedding_size`, and some require an optimizer for their class weights.
- `CrossBatchMemory` wraps another loss and adds queue behavior; `SelfSupervisedLoss` adapts a pair or tuple loss to two views.
- `MultipleLosses` and `MultipleReducers` require matching keys or parallel lists.

## Read next

- `references/losses-miners-and-customization.md` for the component catalog and extension notes.
- `references/troubleshooting.md` for predictable component-level failures.
- `scripts/smoke_components.py` for a tiny direct smoke check.