# examples/moco.py
"""Seeded CPU MoCo v1 mechanics with vectors and a tiny linear encoder.

Follows the original queue/EMA/InfoNCE mechanism and the historical builder's
EMA-before-key-forward timing. No images, BatchNorm, checkpoints,
distributed collectives, pretrained representations, or benchmark results
are reproduced.
The wrapped queue supports 1 <= batch <= capacity, even without divisibility.

Source: https://arxiv.org/html/1911.05722v3 (Sections 3.1-3.3, Equations 1-2).
Builder: facebookresearch/moco, revision
3631be074a0a14ab85c206631729fe035e54b525, moco/builder.py.
"""

import argparse
import hashlib
import json
import math
from pathlib import Path

import torch
from torch import nn
from torch.nn import functional as F


class TinyMoCo(nn.Module):
    """Maintain copied encoders and a normalized FIFO dictionary on CPU.

    Args:
        input_dim: Number of coordinates in each synthetic input vector.
        dim: Encoded feature width.
        capacity: Number of stored negative keys.
        momentum: EMA coefficient in [0, 1).
        temperature: Positive finite logit temperature.
    """

    def __init__(
        self, input_dim=6, dim=4, capacity=5, momentum=0.999, temperature=0.07
    ):
        super().__init__()
        if any(
            type(value) is not int or value < 1
            for value in (input_dim, dim, capacity)
        ):
            raise ValueError(
                "Dimensions and capacity must be positive integers."
            )
        if not math.isfinite(momentum) or not 0 <= momentum < 1:
            raise ValueError("Momentum must be finite and in [0, 1).")
        if not math.isfinite(temperature) or temperature <= 0:
            raise ValueError("Temperature must be positive and finite.")
        self.input_dim = input_dim
        self.dim = dim
        self.capacity = capacity
        self.momentum = momentum
        self.temperature = temperature
        # region: initialize
        self.encoder_q = nn.Linear(input_dim, dim, bias=False)
        self.encoder_k = nn.Linear(input_dim, dim, bias=False)
        self.encoder_k.load_state_dict(self.encoder_q.state_dict())
        self.encoder_k.requires_grad_(False)
        # Columns are normalized keys; the pointer marks the oldest slot.
        self.register_buffer(
            "queue", F.normalize(torch.randn(dim, capacity), dim=0)
        )
        self.register_buffer("queue_ptr", torch.zeros(1, dtype=torch.long))
        # endregion: initialize

    def validate_views(self, query_view, key_view):
        """Reject malformed views before changing any encoder or queue state."""
        weight = self.encoder_q.weight
        for view in (query_view, key_view):
            if (
                view.ndim != 2
                or view.shape[1] != self.input_dim
                or not 1 <= view.shape[0] <= self.capacity
                or view.dtype != weight.dtype
                or view.device != weight.device
                or view.device.type != "cpu"
                or not torch.isfinite(view).all()
            ):
                raise ValueError(
                    "Views must be finite CPU [B, input_dim] tensors "
                    "with the encoder dtype and 1 <= B <= capacity."
                )
        if query_view.shape != key_view.shape:
            raise ValueError("Query and key views must have matching shapes.")

    @staticmethod
    def normalized_features(features):
        """Reject nonfinite or unusable projections before any state commit."""
        normalized = F.normalize(features, dim=1)
        if (
            not torch.isfinite(features).all()
            or not torch.isfinite(normalized).all()
            or not torch.allclose(
                normalized.norm(dim=1),
                torch.ones_like(normalized[:, 0]),
                atol=1e-5,
                rtol=1e-5,
            )
        ):
            raise ValueError("Encoded features must have finite unit norms.")
        return normalized

    # region: queries
    def encode_queries(self, query_view):
        """Encode each query and normalize across feature coordinates."""
        return self.normalized_features(self.encoder_q(query_view))  # [B, D]

    # endregion: queries

    # region: momentum_key
    @torch.no_grad()
    def prospective_keys(self, key_view):
        """Encode with prospective EMA weights without changing live state."""
        weight = self.encoder_k.weight * self.momentum
        weight.add_(self.encoder_q.weight, alpha=1.0 - self.momentum)
        # EMA precedes the key forward; staging makes rejection atomic.
        keys = self.normalized_features(F.linear(key_view, weight))
        # This tiny linear encoder has no BN or distributed shuffling.
        return keys, weight  # [B, D] and [D, input_dim], neither has a graph

    @torch.no_grad()
    def encode_keys(self, key_view):
        """Apply validated EMA and encode the current keys, without gradients."""
        keys, weight = self.prospective_keys(key_view)
        self.encoder_k.weight.copy_(weight)
        return keys

    # endregion: momentum_key

    # region: logits
    def make_logits(self, queries, keys):
        """Put the positive at column zero, using only the OLD dictionary."""
        old_queue = self.queue.clone().detach()  # [D, K]
        positive = (queries * keys.detach()).sum(dim=1, keepdim=True)  # [B, 1]
        negative = queries @ old_queue  # [B, K]
        logits = torch.cat((positive, negative), dim=1) / self.temperature
        # Clone protects backward even when enqueue mutates the live buffer.
        return logits, old_queue

    # endregion: logits

    # region: enqueue
    @torch.no_grad()
    def enqueue(self, keys):
        """Insert one finite normalized batch in order, wrapping at capacity.

        Real DDP gathers detached keys before this step. Here one CPU process
        supplies the entire batch. Unlike the historical contiguous updater,
        this ring allows non-divisible capacity; batches larger than K fail.
        """
        if (
            keys.ndim != 2
            or keys.shape[1] != self.dim
            or not 1 <= keys.shape[0] <= self.capacity
            or keys.dtype != self.queue.dtype
            or keys.device != self.queue.device
            or not torch.isfinite(keys).all()
            or not torch.allclose(
                keys.norm(dim=1),
                torch.ones_like(keys[:, 0]),
                atol=1e-5,
                rtol=1e-5,
            )
        ):
            raise ValueError(
                "Keys must be finite normalized [B, D], 1 <= B <= K."
            )
        pointer = int(self.queue_ptr.item())
        slots = (torch.arange(keys.shape[0]) + pointer) % self.capacity
        self.queue[:, slots] = keys.detach().T
        self.queue_ptr[0] = (pointer + keys.shape[0]) % self.capacity

    # endregion: enqueue

    def forward(self, query_view, key_view):
        """Score old keys, then advance the dictionary."""
        self.validate_views(query_view, key_view)
        queries = self.encode_queries(query_view)
        keys, key_weight = self.prospective_keys(key_view)
        logits, old_queue = self.make_logits(queries, keys)
        loss, labels = contrastive_loss(logits)
        # No live state changes until projections, logits, and loss validate.
        self.enqueue(keys)
        with torch.no_grad():
            self.encoder_k.weight.copy_(key_weight)
        return {
            "queries": queries,
            "keys": keys,
            "logits": logits,
            "labels": labels,
            "loss": loss,
            "old_queue": old_queue,
        }


# region: shuffle
def permutation_roundtrip(samples, permutation):
    """Demonstrate shuffle/unshuffle identity, without distributed BatchNorm.

    The release globally gathers, shuffles, splits across ranks, encodes,
    gathers again, then inverts. Random shuffling changes co-batch membership
    statistically; it does not guarantee every positive moves to another GPU.
    """
    if (
        samples.ndim < 1
        or samples.shape[0] < 1
        or permutation.ndim != 1
        or permutation.dtype != torch.long
        or permutation.device != samples.device
        or permutation.shape[0] != samples.shape[0]
        or not torch.equal(
            permutation.sort().values,
            torch.arange(samples.shape[0], device=samples.device),
        )
    ):
        raise ValueError("Expected a permutation of all batch indices.")
    shuffled = samples[permutation]
    inverse = permutation.argsort()
    restored = shuffled[inverse]
    return shuffled, restored, inverse


# endregion: shuffle


# region: contrastive
def contrastive_loss(logits):
    """Compute Equation 1 as mean cross entropy, with positives at zero."""
    if (
        logits.ndim != 2
        or logits.shape[0] < 1
        or logits.shape[1] < 2
        or not logits.is_floating_point()
        or not torch.isfinite(logits).all()
    ):
        raise ValueError(
            "Logits must be finite floating [B, 1 + K] with B, K >= 1."
        )
    labels = torch.zeros(
        logits.shape[0], dtype=torch.long, device=logits.device
    )
    loss = F.cross_entropy(logits, labels)
    if not torch.isfinite(loss):
        raise ValueError("Contrastive loss must be finite.")
    return loss, labels


# endregion: contrastive


def smoke(seed=7):
    """Execute three CPU updates and measure state and gradients."""
    with torch.random.fork_rng(devices=[]):
        torch.manual_seed(seed)
        model = TinyMoCo()
        optimizer = torch.optim.SGD(model.encoder_q.parameters(), lr=0.03)
        history = []
        for _ in range(3):
            base = torch.randn(3, 6)
            query_view = base + 0.05 * torch.randn_like(base)
            key_view = base + 0.05 * torch.randn_like(base)
            before_key = model.encoder_k.weight.detach().clone()
            expected_key = (
                before_key * model.momentum
                + model.encoder_q.weight.detach() * (1 - model.momentum)
            )
            optimizer.zero_grad()
            output = model(query_view, key_view)
            output["loss"].backward()  # Live queue has already changed.
            grad = model.encoder_q.weight.grad
            oracle = torch.tensor(
                [
                    [
                        sum(
                            float(q[d]) * float(k[d]) for d in range(model.dim)
                        )
                        / model.temperature
                    ]
                    + [
                        sum(
                            float(q[d]) * float(output["old_queue"][d, j])
                            for d in range(model.dim)
                        )
                        / model.temperature
                        for j in range(model.capacity)
                    ]
                    for q, k in zip(output["queries"].detach(), output["keys"])
                ]
            )
            history.append(
                {
                    "loss": float(output["loss"].detach()),
                    "pointer": int(model.queue_ptr.item()),
                    "logit_oracle_max_error": float(
                        (output["logits"].detach() - oracle).abs().max()
                    ),
                    "ema_max_error": float(
                        (model.encoder_k.weight - expected_key).abs().max()
                    ),
                    "query_gradient_norm": float(grad.norm()),
                    "key_has_gradient": any(
                        p.grad is not None
                        for p in model.encoder_k.parameters()
                    ),
                    "queue_has_gradient": model.queue.grad is not None,
                    "labels": output["labels"].tolist(),
                }
            )
            if not torch.isfinite(grad).all() or grad.norm() <= 0:
                raise RuntimeError("Expected finite, nonzero query gradients.")
            optimizer.step()
        shuffled, restored, inverse = permutation_roundtrip(
            base, torch.tensor([2, 0, 1])
        )
        result = {
            "source_sha256": hashlib.sha256(
                Path(__file__).read_bytes()
            ).hexdigest(),
            "upstream_revision": "3631be074a0a14ab85c206631729fe035e54b525",
            "seed": seed,
            "boundary": (
                "Offline CPU synthetic mechanics; no pretrained "
                "or distributed BN behavior."
            ),
            "reductions": {
                "encoder": "linear 6 -> 4, no BN",
                "batch": 3,
                "queue_capacity": 5,
                "steps": 3,
                "momentum": model.momentum,
                "temperature": model.temperature,
                "distributed_gather": "omitted",
            },
            "shapes": {
                name: list(output[name].shape)
                for name in (
                    "queries",
                    "keys",
                    "logits",
                    "old_queue",
                    "labels",
                )
            },
            "steps": history,
            "queue_column_norms": model.queue.norm(dim=0).tolist(),
            "shuffle_identity": bool(torch.equal(restored, base)),
            "shuffle_changed_order": bool(not torch.equal(shuffled, base)),
            "inverse_permutation": inverse.tolist(),
        }
        json.dumps(result, allow_nan=False)
        return result


def main():
    """Print actual finite smoke JSON without fetching data or weights."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--smoke", action="store_true", required=True)
    parser.add_argument("--seed", type=int, default=7)
    arguments = parser.parse_args()
    print(json.dumps(smoke(arguments.seed), indent=2, allow_nan=False))


if __name__ == "__main__":
    main()
