# examples/dino.py
"""Seeded offline CPU DINO mechanics, without pretrained features or benchmarks.

Conventions: facebookresearch/dino revision
7c446df5b9f45747937fb0d72314eb9f7b66930a, main_dino.py and DINOHead in
vision_transformer.py. This authored reduction uses synthetic square crops, a
small convolutional encoder and SGD. It omits ViT, full photometric augmentation,
distributed all-reduce, last-layer epoch freezing and production schedules.
"""

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

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

UPSTREAM_REVISION = "7c446df5b9f45747937fb0d72314eb9f7b66930a"


def _tensor(value, name, ndim):
    """Reject empty, nonfinite, nonfloating or non-CPU tensors."""
    if (
        not isinstance(value, torch.Tensor)
        or value.ndim != ndim
        or value.numel() == 0
        or not value.is_floating_point()
        or value.device.type != "cpu"
        or not torch.isfinite(value).all()
    ):
        raise ValueError(
            f"{name} must be a finite nonempty CPU float tensor of rank {ndim}"
        )


def _positive(value, name):
    """Validate a finite positive temperature."""
    if not math.isfinite(value) or value <= 0:
        raise ValueError(f"{name} must be finite and positive")


def _momentum(value):
    """Validate an EMA coefficient, including both endpoints."""
    if not math.isfinite(value) or not 0 <= value <= 1:
        raise ValueError("momentum must be finite and in [0, 1]")


# region: crops
def make_crops(images, local_count, generator):
    """Make two global crops followed by L local crops, preserving batch identity.

    Args:
        images: Synthetic images [B, 3, H, W] with H and W at least 12.
        local_count: Nonnegative integer number of local views.
        generator: Local CPU torch.Generator controlling offsets and flips.

    Returns:
        List with two [B, 3, 8, 8] globals and L [B, 3, 4, 4] locals.
    """
    _tensor(images, "images", 4)
    if images.shape[1] != 3 or min(images.shape[2:]) < 12:
        raise ValueError(
            "images require three channels and spatial dimensions >= 12"
        )
    if type(local_count) is not int or local_count < 0:
        raise ValueError("local_count must be a nonnegative integer")
    views = []
    for side, output_size in [(10, 8), (8, 8)] + [(4, 4)] * local_count:
        top = int(
            torch.randint(images.shape[2] - side + 1, (), generator=generator)
        )
        left = int(
            torch.randint(images.shape[3] - side + 1, (), generator=generator)
        )
        crop = images[:, :, top : top + side, left : left + side]
        if bool(torch.randint(2, (), generator=generator)):
            crop = crop.flip(-1)
        views.append(
            F.interpolate(
                crop,
                (output_size, output_size),
                mode="bilinear",
                align_corners=False,
            )
        )
    return views


# endregion: crops


# region: head
class TinyDINO(nn.Module):
    """BN-free reduced encoder and three-layer DINO projection head."""

    def __init__(self, output_dim=7):
        super().__init__()
        if type(output_dim) is not int or output_dim < 2:
            raise ValueError("output_dim must be an integer >= 2")
        self.encoder = nn.Conv2d(3, 6, kernel_size=3, padding=1)
        self.mlp = nn.Sequential(
            nn.Linear(6, 12),
            nn.GELU(),
            nn.Linear(12, 12),
            nn.GELU(),
            nn.Linear(12, 4),
        )
        self.direction = nn.Parameter(torch.randn(output_dim, 4))

    def forward(self, view):
        """Map any positive crop resolution to logits [B, K]."""
        _tensor(view, "view", 4)
        if view.shape[1] != 3:
            raise ValueError("view must have three channels")
        features = F.gelu(self.encoder(view)).mean(dim=(-2, -1))
        bottleneck = F.normalize(self.mlp(features), dim=-1)
        # Weight normalization with fixed gain 1, like norm_last_layer=True.
        weights = F.normalize(self.direction, dim=-1)
        return F.linear(bottleneck, weights)


# endregion: head


# region: teacher_probs
def teacher_probabilities(logits, old_center, temperature):
    """Center raw teacher logits using the previous state, sharpen, then detach."""
    _tensor(logits, "teacher logits", 3)
    _tensor(old_center, "center", 2)
    _positive(temperature, "teacher temperature")
    if (
        logits.shape[0] != 2
        or logits.shape[2] < 2
        or old_center.shape != (1, logits.shape[2])
        or old_center.dtype != logits.dtype
    ):
        raise ValueError(
            "teacher requires [2, B, K] logits and matching [1, K] center"
        )
    return F.softmax((logits - old_center) / temperature, dim=-1).detach()


# endregion: teacher_probs


# region: student_log_probs
def student_log_probabilities(logits, temperature=0.1):
    """Use stable log-softmax for all student crops [2 + L, B, K]."""
    _tensor(logits, "student logits", 3)
    _positive(temperature, "student temperature")
    if logits.shape[0] < 2 or logits.shape[2] < 2:
        raise ValueError(
            "student requires at least two crops and two output dimensions"
        )
    return F.log_softmax(logits / temperature, dim=-1)


# endregion: student_log_probs


# region: cross_view_loss
def cross_view_loss(
    student_logits,
    teacher_logits,
    old_center,
    teacher_temperature,
    student_temperature=0.1,
):
    """Average cross-entropy over batch and exactly 2*(L+1) valid view pairs.

    The first two student crop identities match the teacher global identities.
    This function is pure: the caller updates the center after this objective.
    """
    targets = teacher_probabilities(
        teacher_logits, old_center, teacher_temperature
    )
    predictions = student_log_probabilities(student_logits, student_temperature)
    if (
        predictions.shape[1:] != targets.shape[1:]
        or predictions.dtype != targets.dtype
    ):
        raise ValueError(
            "teacher and student must share batch size, K and dtype"
        )
    terms, pairs = [], []
    for teacher_view in range(2):
        for student_view in range(predictions.shape[0]):
            if student_view == teacher_view:
                continue
            terms.append(
                -(targets[teacher_view] * predictions[student_view])
                .sum(dim=-1)
                .mean()
            )
            pairs.append((teacher_view, student_view))
    return torch.stack(terms).mean(), pairs


# endregion: cross_view_loss


# region: center_update
@torch.no_grad()
def update_center(center, raw_teacher_logits, momentum=0.9):
    """EMA the raw-logit mean over both globals and B samples, after the loss."""
    teacher_probabilities(
        raw_teacher_logits, center, 1.0
    )  # Shape/finite checks.
    _momentum(momentum)
    batch_center = raw_teacher_logits.mean(dim=(0, 1)).unsqueeze(0)
    center.mul_(momentum).add_(batch_center, alpha=1 - momentum)


# endregion: center_update


# region: teacher_ema
@torch.no_grad()
def update_teacher(teacher, student, momentum):
    """Update matching teacher parameters after the student's optimizer step."""
    _momentum(momentum)
    teacher_parameters = dict(teacher.named_parameters())
    student_parameters = dict(student.named_parameters())
    if teacher_parameters.keys() != student_parameters.keys():
        raise ValueError("teacher and student parameter names must match")
    for name, parameter in teacher_parameters.items():
        other = student_parameters[name]
        if parameter.shape != other.shape or parameter.dtype != other.dtype:
            raise ValueError(
                "teacher and student parameter shapes/dtypes must match"
            )
        _tensor(parameter, name, parameter.ndim)
        _tensor(other, name, other.ndim)
    for name, parameter in teacher_parameters.items():
        parameter.mul_(momentum).add_(
            student_parameters[name], alpha=1 - momentum
        )


# endregion: teacher_ema


def temperature_schedule(epochs, warmup_epochs=0, start=0.04, final=0.04):
    """Match the release's endpoint-inclusive linear warmup, then constant tail."""
    if (
        type(epochs) is not int
        or type(warmup_epochs) is not int
        or epochs < 1
        or not 0 <= warmup_epochs <= epochs
    ):
        raise ValueError("require epochs >= 1 and 0 <= warmup_epochs <= epochs")
    _positive(start, "start temperature")
    _positive(final, "final temperature")
    warmup = (
        [start]
        if warmup_epochs == 1
        else [
            start + (final - start) * i / (warmup_epochs - 1)
            for i in range(warmup_epochs)
        ]
    )
    return warmup + [final] * (epochs - warmup_epochs)


def teacher_momentum(step, total_steps, base=0.996):
    """Match the release cosine denominator N: the last used step is below 1."""
    _momentum(base)
    if (
        type(step) is not int
        or type(total_steps) is not int
        or total_steps < 1
        or not 0 <= step < total_steps
    ):
        raise ValueError("require 0 <= step < total_steps and total_steps >= 1")
    return 1 + 0.5 * (base - 1) * (1 + math.cos(math.pi * step / total_steps))


def run_smoke(seed=7, local_count=8, batch_size=3):
    """Execute two deterministic CPU updates and return measured JSON values."""
    if type(batch_size) is not int or batch_size < 1:
        raise ValueError("batch_size must be a positive integer")
    with torch.random.fork_rng(devices=[]):
        torch.manual_seed(seed)
        generator = torch.Generator().manual_seed(seed)
        student = TinyDINO().double()
        teacher = copy.deepcopy(student).requires_grad_(False)
        optimizer = torch.optim.SGD(student.parameters(), lr=0.01)
        center = torch.zeros(1, 7, dtype=torch.float64)
        images = torch.randn(
            batch_size, 3, 12, 12, generator=generator, dtype=torch.float64
        )
        temperatures = temperature_schedule(4, 3, start=0.04, final=0.07)
        receipts = []
        for step in range(2):
            views = make_crops(images, local_count, generator)
            student_logits = torch.stack([student(view) for view in views])
            with torch.no_grad():
                teacher_logits = torch.stack(
                    [teacher(view) for view in views[:2]]
                )
            old_center = center.clone()
            loss, pairs = cross_view_loss(
                student_logits, teacher_logits, old_center, temperatures[step]
            )
            expected_center = (
                0.9 * old_center + 0.1 * teacher_logits.mean((0, 1))[None]
            )
            update_center(center, teacher_logits)
            next_center_loss, _ = cross_view_loss(
                student_logits, teacher_logits, center, temperatures[step]
            )
            optimizer.zero_grad()
            loss.backward()
            gradient_norm = math.sqrt(
                sum(
                    float(p.grad.square().sum())
                    for p in student.parameters()
                    if p.grad is not None
                )
            )
            old_teacher = [p.detach().clone() for p in teacher.parameters()]
            old_student = [p.detach().clone() for p in student.parameters()]
            optimizer.step()
            momentum = teacher_momentum(step, 2)
            expected_teacher = [
                momentum * old + (1 - momentum) * new.detach()
                for old, new in zip(old_teacher, student.parameters())
            ]
            update_teacher(teacher, student, momentum)
            receipts.append(
                {
                    "step": step,
                    "loss": float(loss.detach()),
                    "pair_count": len(pairs),
                    "teacher_temperature": temperatures[step],
                    "teacher_momentum": momentum,
                    "student_gradient_norm": gradient_norm,
                    "teacher_gradient_count": sum(
                        p.grad is not None for p in teacher.parameters()
                    ),
                    "old_center": old_center.tolist(),
                    "new_center": center.tolist(),
                    "center_max_error": float(
                        (center - expected_center).abs().max()
                    ),
                    "next_center_loss_difference": float(
                        (next_center_loss - loss).detach()
                    ),
                    "student_update_max": max(
                        float((p.detach() - old).abs().max())
                        for p, old in zip(student.parameters(), old_student)
                    ),
                    "teacher_ema_max_error": max(
                        float((p - expected).abs().max())
                        for p, expected in zip(
                            teacher.parameters(), expected_teacher
                        )
                    ),
                }
            )
        return {
            "source_sha256": hashlib.sha256(
                Path(__file__).read_bytes()
            ).hexdigest(),
            "upstream_revision": UPSTREAM_REVISION,
            "seed": seed,
            "boundary": "Tiny random-weight CPU mechanics; no pretrained semantics or benchmarks",
            "reductions": {
                "encoder": "3->6 conv + spatial mean",
                "mlp": [6, 12, 12, 4],
                "K": 7,
                "optimizer": "SGD",
                "dtype": "float64",
                "crop_sides": {"global": [10, 8], "local": 4},
                "omitted": [
                    "ViT",
                    "photometric augmentation",
                    "distributed all-reduce",
                    "last-layer epoch freezing",
                    "benchmark training",
                ],
            },
            "shapes": {
                "images": list(images.shape),
                "crops": [list(v.shape) for v in views],
                "student_logits": list(student_logits.shape),
                "teacher_logits": list(teacher_logits.shape),
                "center": list(center.shape),
            },
            "temperature_schedule": temperatures,
            "steps": receipts,
        }


def main():
    """Print actual finite measurements; never download data or checkpoints."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--smoke", action="store_true", required=True)
    parser.add_argument("--seed", type=int, default=7)
    parser.add_argument("--local-count", type=int, default=8)
    parser.add_argument("--batch-size", type=int, default=3)
    args = parser.parse_args()
    torch.set_num_threads(1)
    print(
        json.dumps(
            run_smoke(args.seed, args.local_count, args.batch_size),
            indent=2,
            allow_nan=False,
        )
    )


if __name__ == "__main__":
    main()
