LeVJEPA-VideoMix-Large: ViT-L video encoder, EMA weights + modeling code

README.md

@@ -0,0 +1,107 @@
+---
+license: cc-by-nc-4.0
+library_name: transformers
+pipeline_tag: video-feature-extraction
+tags:
+  - video
+  - self-supervised
+  - jepa
+  - vision-transformer
+---
+
+# LeVJEPA-VideoMix-Large
+
+A ViT-L/16 video encoder trained with LeV-JEPA, a self-supervised objective combining
+a multi-crop prediction loss with SIGReg. No labels are used at any point.
+
+- **303.1M parameters**, 224px, patch 16, 16 frames, **tubelet 1** (one token per frame per patch)
+- **RoPE** position encoding, **block-causal** attention
+- Trained on **VideoMix**: 1,806,869 clips from Kinetics-710, Something-Something v2,
+  Walking Tours and PE-Video
+- 85 epochs at a flat 4e-4 followed by a 15-epoch cosine decay to 0
+
+## Usage
+
+```python
+import torch
+from transformers import AutoModel
+
+model = AutoModel.from_pretrained(
+    "galilai-group/LeVJEPA-VideoMix-Large", trust_remote_code=True
+).eval()
+
+# (B, C, T, H, W), ImageNet-normalised
+video = torch.randn(1, 3, 16, 224, 224)
+
+with torch.no_grad():
+    out = model(pixel_values=video)
+
+out.last_hidden_state   # (1, 3137, 1024) -- CLS + 16*14*14 patch tokens
+out["pooler_output"]    # (1, 1024)       -- the CLS token
+```
+
+`trust_remote_code=True` is required: this is a custom architecture (RoPE +
+block-causal attention) rather than a stock `transformers` model, so the modeling
+code ships with the weights.
+
+### Preprocessing
+
+Normalise with the ImageNet statistics used in training —
+`mean=[0.485, 0.456, 0.406]`, `std=[0.229, 0.224, 0.225]` — and resize/crop to 224.
+Frames are sampled at roughly 7.5 fps in training, so a 16-frame clip covers about
+two seconds.
+
+**For a single image**, repeat it along the temporal axis:
+
+```python
+image = torch.randn(1, 3, 224, 224)
+video = image.unsqueeze(2).repeat(1, 1, 16, 1, 1)
+```
+
+That is exactly how the model is evaluated on ImageNet.
+
+## Attention mode
+
+The weights were trained with **block-causal** attention: bidirectional within a
+temporal slot, causal across slots, with CLS as a read-only sink that sees the whole
+clip while no patch attends to it. `config.attn_mode` defaults to `"block_causal"`
+for this reason.
+
+> Running these weights under full attention will **not** raise an error — it will
+> quietly return worse features. Leave `attn_mode` alone unless you know why you are
+> changing it. An explicit attention mask also disqualifies SDPA's flash kernel, so
+> expect higher memory than a full-attention ViT-L at the same batch size.
+
+## Weights
+
+The released tensors are the **EMA** copy of the encoder (`decay=0.9999`,
+`update_every=32`), which is what we evaluate. There is no separate LR-decay artifact
+to apply — the cosine leg is already baked into these weights.
+
+## Training details
+
+| | |
+| --- | --- |
+| Objective | multi-crop prediction + SIGReg (weight 0.02) |
+| Crops | 1 global + 10 local |
+| Token drop | 95%, random, applied inside the encoder forward (training only) |
+| Optimizer | AdamW, lr 4e-4 flat then cosine → 0, weight decay 0.04 |
+| Batch | 3072 global |
+| Precision | bf16-mixed |
+
+Token dropping is a training-time regulariser and is inert under `eval()`, so the
+released model returns all 3137 tokens.
+
+## Intended use
+
+Frozen feature extraction for video and image understanding — attentive or linear
+probing, retrieval, and as a backbone for downstream heads. It is a self-supervised
+encoder with no classification head.
+
+## Limitations
+
+Trained at 224px on ~2-second clips, so it has not seen long-horizon temporal
+structure. Walking Tours substitutes for HowTo100M in the mixture, so the training
+distribution is not identical to V-JEPA's VideoMix2M despite the similar scale.
+Evaluation to date is ImageNet and Something-Something v2; behaviour on other domains
+is uncharacterised.

config.json

@@ -0,0 +1,27 @@
+{
+  "architectures": [
+    "LeVJEPAModel"
+  ],
+  "model_type": "levjepa",
+  "auto_map": {
+    "AutoConfig": "configuration_levjepa.LeVJEPAConfig",
+    "AutoModel": "modeling_levjepa.LeVJEPAModel"
+  },
+  "img_size": 224,
+  "patch_size": 16,
+  "num_frames": 16,
+  "tubelet_size": 1,
+  "in_chans": 3,
+  "embed_dim": 1024,
+  "depth": 24,
+  "num_heads": 16,
+  "mlp_ratio": 4.0,
+  "qkv_bias": true,
+  "uniform_power": false,
+  "use_rope": true,
+  "attn_mode": "block_causal",
+  "token_drop_rate": 0.0,
+  "token_drop_mode": "random",
+  "token_drop_k": 2,
+  "torch_dtype": "float32"
+}

configuration_levjepa.py

@@ -0,0 +1,50 @@
+"""Config for LeV-JEPA video encoders."""
+
+from transformers import PretrainedConfig
+
+
+class LeVJEPAConfig(PretrainedConfig):
+    model_type = "levjepa"
+
+    def __init__(
+        self,
+        img_size=224,
+        patch_size=16,
+        num_frames=16,
+        tubelet_size=1,
+        in_chans=3,
+        embed_dim=1024,
+        depth=24,
+        num_heads=16,
+        mlp_ratio=4.0,
+        qkv_bias=True,
+        uniform_power=False,
+        use_rope=True,
+        # block_causal is NOT a cosmetic default: these weights were trained with
+        # it, and running them under full attention silently degrades results
+        # instead of raising.
+        attn_mode="block_causal",
+        # Token dropping is a training-time regulariser and is inert in eval();
+        # kept here so a training config round-trips through the class.
+        token_drop_rate=0.0,
+        token_drop_mode="random",
+        token_drop_k=2,
+        **kwargs,
+    ):
+        self.img_size = img_size
+        self.patch_size = patch_size
+        self.num_frames = num_frames
+        self.tubelet_size = tubelet_size
+        self.in_chans = in_chans
+        self.embed_dim = embed_dim
+        self.depth = depth
+        self.num_heads = num_heads
+        self.mlp_ratio = mlp_ratio
+        self.qkv_bias = qkv_bias
+        self.uniform_power = uniform_power
+        self.use_rope = use_rope
+        self.attn_mode = attn_mode
+        self.token_drop_rate = token_drop_rate
+        self.token_drop_mode = token_drop_mode
+        self.token_drop_k = token_drop_k
+        super().__init__(**kwargs)

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b6ce2813d8eb70f8e9a783d0783f1a5b992c5e01cf6bd788ed0a446c49554d63
+size 1212429888

modeling_levjepa.py

@@ -0,0 +1,1104 @@
+"""LeV-JEPA video encoder — ViT with RoPE and optional block-causal attention.
+
+The transformer below is vendored verbatim from the training codebase so the
+released weights load into exactly the module that produced them. Only the
+training-time loss (SIGReg) and projection head were removed; they are not
+needed to compute features.
+"""
+
+import math
+from functools import partial
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from transformers import PreTrainedModel
+from transformers.modeling_outputs import BaseModelOutput
+
+from .configuration_levjepa import LeVJEPAConfig
+
+
+def _no_grad_trunc_normal_(tensor, mean, std, a, b):
+    # Cut & paste from PyTorch official master until it's in a few official releases - RW
+    # Method based on https://people.sc.fsu.edu/~jburkardt/presentations/truncated_normal.pdf
+    def norm_cdf(x):
+        # Computes standard normal cumulative distribution function
+        return (1.0 + math.erf(x / math.sqrt(2.0))) / 2.0
+
+    with torch.no_grad():
+        # Values are generated by using a truncated uniform distribution and
+        # then using the inverse CDF for the normal distribution.
+        l = norm_cdf((a - mean) / std)
+        u = norm_cdf((b - mean) / std)
+
+        # Uniformly fill tensor with values from [l, u], then translate to
+        # [2l-1, 2u-1].
+        tensor.uniform_(2 * l - 1, 2 * u - 1)
+
+        # Use inverse cdf transform for normal distribution to get truncated
+        # standard normal.
+        tensor.erfinv_()
+
+        # Transform to proper mean, std.
+        tensor.mul_(std * math.sqrt(2.0))
+        tensor.add_(mean)
+
+        # Clamp to ensure it's in the proper range.
+        tensor.clamp_(min=a, max=b)
+        return tensor
+
+
+def trunc_normal_(tensor, mean=0.0, std=1.0, a=-2.0, b=2.0):
+    # type: (Tensor, float, float, float, float) -> Tensor
+    return _no_grad_trunc_normal_(tensor, mean, std, a, b)
+
+
+def get_3d_sincos_pos_embed(
+    embed_dim,
+    grid_size,
+    grid_depth,
+    cls_token=False,
+    uniform_power=False,
+):
+    """
+    grid_size: int of the grid height and width
+    grid_depth: int of the grid depth
+    returns:
+        pos_embed: [grid_depth*grid_size*grid_size, embed_dim] (w/o cls_token)
+                or [1+grid_depth*grid_size*grid_size, embed_dim] (w/ cls_token)
+    """
+    grid_d = np.arange(grid_depth, dtype=float)
+    grid_h = np.arange(grid_size, dtype=float)
+    grid_w = np.arange(grid_size, dtype=float)
+    # order of meshgrid is very important for indexing as [d,h,w]
+    grid_h, grid_d, grid_w = np.meshgrid(grid_h, grid_d, grid_w)
+
+    if not uniform_power:
+        h_embed_dim = embed_dim // 4
+        w_embed_dim = embed_dim // 4
+        d_embed_dim = embed_dim // 2
+    else:
+        h_embed_dim = w_embed_dim = d_embed_dim = int(np.ceil(embed_dim / 6) * 2)
+
+    emb_h = get_1d_sincos_pos_embed_from_grid(h_embed_dim, grid_h)
+    emb_w = get_1d_sincos_pos_embed_from_grid(w_embed_dim, grid_w)
+    emb_d = get_1d_sincos_pos_embed_from_grid(d_embed_dim, grid_d)
+    pos_embed = np.concatenate([emb_d, emb_h, emb_w], axis=1)
+    pos_embed = pos_embed[:, :embed_dim]
+    if cls_token:
+        pos_embed = np.concatenate([np.zeros([1, embed_dim]), pos_embed], axis=0)
+    return pos_embed
+
+
+def get_2d_sincos_pos_embed(embed_dim, grid_size, cls_token=False):
+    """
+    grid_size: int of the grid height and width
+    returns:
+        pos_embed: [grid_size*grid_size, embed_dim] (w/o cls_token)
+                or [1+grid_size*grid_size, embed_dim] (w/ cls_token)
+    """
+    grid_h = np.arange(grid_size, dtype=float)
+    grid_w = np.arange(grid_size, dtype=float)
+    # order of meshgrid is very important for indexing as [h, w]
+    grid_w, grid_h = np.meshgrid(grid_w, grid_h)
+
+    emb_h = get_1d_sincos_pos_embed_from_grid(embed_dim // 2, grid_h)
+    emb_w = get_1d_sincos_pos_embed_from_grid(embed_dim // 2, grid_w)
+    pos_embed = np.concatenate([emb_h, emb_w], axis=1)
+    if cls_token:
+        pos_embed = np.concatenate([np.zeros([1, embed_dim]), pos_embed], axis=0)
+    return pos_embed
+
+
+def get_1d_sincos_pos_embed(embed_dim, grid_size, cls_token=False):
+    """
+    embed_dim: output dimension for each position
+    grid_size: int of the grid length
+    returns:
+        pos_embed: [grid_size, embed_dim] (w/o cls_token)
+                or [1+grid_size, embed_dim] (w/ cls_token)
+    """
+    grid = np.arange(grid_size, dtype=float)
+    pos_embed = get_1d_sincos_pos_embed_from_grid(embed_dim, grid)
+    if cls_token:
+        pos_embed = np.concatenate([np.zeros([1, embed_dim]), pos_embed], axis=0)
+    return pos_embed
+
+
+def get_1d_sincos_pos_embed_from_grid(embed_dim, pos):
+    """
+    embed_dim: output dimension for each position
+    pos: a list of positions to be encoded: size (M,)
+    returns: (M, D)
+    """
+    assert embed_dim % 2 == 0
+    omega = np.arange(embed_dim // 2, dtype=float)
+    omega /= embed_dim / 2.0
+    omega = 1.0 / 10000**omega
+
+    pos = pos.reshape(-1)
+    out = np.einsum("m,d->md", pos, omega)
+
+    emb_sin = np.sin(out)
+    emb_cos = np.cos(out)
+
+    emb = np.concatenate([emb_sin, emb_cos], axis=1)
+    return emb
+
+
+class PatchEmbed(nn.Module):
+    """
+    Image to Patch Embedding
+    """
+
+    def __init__(
+        self,
+        patch_size=16,
+        in_chans=3,
+        embed_dim=768,
+    ):
+        super().__init__()
+        self.patch_size = patch_size
+        self.proj = nn.Conv2d(
+            in_chans,
+            embed_dim,
+            kernel_size=patch_size,
+            stride=patch_size,
+        )
+
+    def forward(self, x):
+        B, C, H, W = x.shape
+        x = self.proj(x).flatten(2).transpose(1, 2)
+        return x
+
+
+class PatchEmbed3D(nn.Module):
+    """
+    Image to Patch Embedding
+    """
+
+    def __init__(
+        self,
+        patch_size=16,
+        tubelet_size=2,
+        in_chans=3,
+        embed_dim=768,
+    ):
+        super().__init__()
+        self.patch_size = patch_size
+        self.tubelet_size = tubelet_size
+
+        self.proj = nn.Conv3d(
+            in_channels=in_chans,
+            out_channels=embed_dim,
+            kernel_size=(tubelet_size, patch_size, patch_size),
+            stride=(tubelet_size, patch_size, patch_size),
+        )
+
+    def forward(self, x, **kwargs):
+        B, C, T, H, W = x.shape
+        x = self.proj(x).flatten(2).transpose(1, 2)
+        return x
+
+
+class MLP(nn.Module):
+    def __init__(
+        self,
+        in_features,
+        hidden_features=None,
+        out_features=None,
+        act_layer=nn.GELU,
+        drop=0.0,
+    ):
+        super().__init__()
+        out_features = out_features or in_features
+        hidden_features = hidden_features or in_features
+        self.fc1 = nn.Linear(in_features, hidden_features)
+        self.act = act_layer()
+        self.fc2 = nn.Linear(hidden_features, out_features)
+        self.drop = nn.Dropout(drop)
+
+    def forward(self, x):
+        x = self.fc1(x)
+        x = self.act(x)
+        x = self.drop(x)
+        x = self.fc2(x)
+        x = self.drop(x)
+        return x
+
+
+class Attention(nn.Module):
+    def __init__(
+        self,
+        dim,
+        num_heads=8,
+        qkv_bias=False,
+        qk_scale=None,
+        attn_drop=0.0,
+        proj_drop=0.0,
+        use_sdpa=True,
+    ):
+        super().__init__()
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim**-0.5
+        self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias)
+        self.attn_drop = nn.Dropout(attn_drop)
+        self.proj = nn.Linear(dim, dim)
+        self.proj_drop_prob = proj_drop
+        self.proj_drop = nn.Dropout(proj_drop)
+        self.use_sdpa = use_sdpa
+
+    def forward(self, x, attn_mask=None):
+        B, N, C = x.shape
+        qkv = (
+            self.qkv(x)
+            .reshape(B, N, 3, self.num_heads, C // self.num_heads)
+            .permute(2, 0, 3, 1, 4)
+        )
+        q, k, v = qkv[0], qkv[1], qkv[2]
+
+        if self.use_sdpa:
+            with torch.backends.cuda.sdp_kernel():
+                x = F.scaled_dot_product_attention(
+                    q,
+                    k,
+                    v,
+                    attn_mask=attn_mask,
+                    dropout_p=self.proj_drop_prob,
+                )
+                attn = None
+        else:
+            attn = (q @ k.transpose(-2, -1)) * self.scale
+            if attn_mask is not None:
+                attn = attn.masked_fill(~attn_mask, float("-inf"))
+            attn = attn.softmax(dim=-1)
+            attn = self.attn_drop(attn)
+            x = attn @ v
+        x = x.transpose(1, 2).reshape(B, N, C)
+        x = self.proj(x)
+        x = self.proj_drop(x)
+        return x, attn
+
+
+def rotate_queries_or_keys(x, pos):
+    B, num_heads, N, D = x.size()
+    assert D % 2 == 0, "Embedding dimension must be a multiple of 2 for RoPE"
+
+    omega = torch.arange(D // 2, dtype=x.dtype, device=x.device)
+    omega /= D / 2.0
+    omega = 1.0 / 10000**omega
+    freq = torch.einsum("..., f -> ... f", pos, omega)
+
+    emb_sin = freq.sin()
+    emb_cos = freq.cos()
+    # Match V-JEPA2's pretrained-compatible frequency expansion.
+    if pos.dim() == 1:
+        # Position ids shared across the batch: (N, D/2) -> (1, 1, N, D).
+        emb_sin = emb_sin.unsqueeze(0).unsqueeze(0).repeat(1, 1, 1, 2)
+        emb_cos = emb_cos.unsqueeze(0).unsqueeze(0).repeat(1, 1, 1, 2)
+    else:
+        # Per-sample position ids: (B, N, D/2) -> (B, 1, N, D).
+        emb_sin = emb_sin.unsqueeze(1).repeat(1, 1, 1, 2)
+        emb_cos = emb_cos.unsqueeze(1).repeat(1, 1, 1, 2)
+
+    y = x.unflatten(-1, (-1, 2))
+    y1, y2 = y.unbind(dim=-1)
+    y = torch.stack((-y2, y1), dim=-1)
+    y = y.flatten(-2)
+    return (x * emb_cos) + (y * emb_sin)
+
+# Yoinked from https://github.com/facebookresearch/vjepa2/blob/main/src/models/utils/modules.py
+class RoPEAttention(nn.Module):
+    def __init__(
+        self,
+        dim,
+        num_heads=8,
+        qkv_bias=False,
+        qk_scale=None,
+        attn_drop=0.0,
+        proj_drop=0.0,
+        use_sdpa=True,
+        grid_size=14,
+        has_cls_token=True,
+    ):
+        super().__init__()
+        self.num_heads = num_heads
+        self.head_dim = head_dim = dim // num_heads
+        self.scale = qk_scale or head_dim**-0.5
+        self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias)
+        self.attn_drop = nn.Dropout(attn_drop)
+        self.proj = nn.Linear(dim, dim)
+        self.proj_drop_prob = proj_drop
+        self.proj_drop = nn.Dropout(proj_drop)
+        self.use_sdpa = use_sdpa
+        self.grid_size = grid_size
+        self.has_cls_token = has_cls_token
+
+        self.d_dim = int(2 * ((head_dim // 3) // 2))
+        self.h_dim = int(2 * ((head_dim // 3) // 2))
+        self.w_dim = int(2 * ((head_dim // 3) // 2))
+
+    def _get_frame_pos(self, ids, H_patches=None, W_patches=None):
+        if H_patches is None or W_patches is None:
+            tokens_per_frame = int(self.grid_size * self.grid_size)
+        else:
+            tokens_per_frame = int(H_patches * W_patches)
+        return ids // tokens_per_frame
+
+    def _get_height_pos(self, ids, H_patches=None, W_patches=None):
+        if H_patches is None or W_patches is None:
+            tokens_per_frame = int(self.grid_size * self.grid_size)
+            tokens_per_row = self.grid_size
+        else:
+            tokens_per_frame = int(H_patches * W_patches)
+            tokens_per_row = W_patches
+        frame_ids = self._get_frame_pos(ids, H_patches, W_patches)
+        ids = ids - tokens_per_frame * frame_ids
+        return ids // tokens_per_row
+
+    def separate_positions(self, ids, H_patches=None, W_patches=None):
+        if H_patches is None or W_patches is None:
+            tokens_per_frame = int(self.grid_size * self.grid_size)
+            tokens_per_row = self.grid_size
+        else:
+            tokens_per_frame = int(H_patches * W_patches)
+            tokens_per_row = W_patches
+        frame_ids = self._get_frame_pos(ids, H_patches, W_patches)
+        height_ids = self._get_height_pos(ids, H_patches, W_patches)
+        width_ids = (ids - tokens_per_frame * frame_ids) - tokens_per_row * height_ids
+        return frame_ids, height_ids, width_ids
+
+    def _apply_rope(self, q, k, pos):
+        d_pos, h_pos, w_pos = pos
+        s = 0
+        qd = rotate_queries_or_keys(q[..., s : s + self.d_dim], pos=d_pos)
+        kd = rotate_queries_or_keys(k[..., s : s + self.d_dim], pos=d_pos)
+        s += self.d_dim
+
+        qh = rotate_queries_or_keys(q[..., s : s + self.h_dim], pos=h_pos)
+        kh = rotate_queries_or_keys(k[..., s : s + self.h_dim], pos=h_pos)
+        s += self.h_dim
+
+        qw = rotate_queries_or_keys(q[..., s : s + self.w_dim], pos=w_pos)
+        kw = rotate_queries_or_keys(k[..., s : s + self.w_dim], pos=w_pos)
+        s += self.w_dim
+
+        if s < self.head_dim:
+            q = torch.cat([qd, qh, qw, q[..., s:]], dim=-1)
+            k = torch.cat([kd, kh, kw, k[..., s:]], dim=-1)
+        else:
+            q = torch.cat([qd, qh, qw], dim=-1)
+            k = torch.cat([kd, kh, kw], dim=-1)
+        return q, k
+
+    def forward(
+        self,
+        x,
+        T=None,
+        H_patches=None,
+        W_patches=None,
+        token_ids=None,
+        attn_mask=None,
+    ):
+        B, N, C = x.shape
+        qkv = (
+            self.qkv(x)
+            .reshape(B, N, 3, self.num_heads, C // self.num_heads)
+            .permute(2, 0, 3, 1, 4)
+        )
+        q, k, v = qkv[0], qkv[1], qkv[2]
+
+        cls_tokens = 1 if self.has_cls_token else 0
+        patch_N = N - cls_tokens
+        if T is None or H_patches is None or W_patches is None:
+            T = int(patch_N // (self.grid_size * self.grid_size))
+            H_patches = W_patches = self.grid_size
+
+        if token_ids is not None:
+            mask = token_ids
+        else:
+            mask = torch.arange(int(T * H_patches * W_patches), device=x.device)
+        d_mask, h_mask, w_mask = self.separate_positions(mask, H_patches, W_patches)
+
+        if cls_tokens:
+            q_patch, k_patch = self._apply_rope(
+                q[..., cls_tokens:, :],
+                k[..., cls_tokens:, :],
+                (d_mask, h_mask, w_mask),
+            )
+            q = torch.cat([q[..., :cls_tokens, :], q_patch], dim=-2)
+            k = torch.cat([k[..., :cls_tokens, :], k_patch], dim=-2)
+        else:
+            q, k = self._apply_rope(q, k, (d_mask, h_mask, w_mask))
+
+        if self.use_sdpa:
+            with torch.backends.cuda.sdp_kernel():
+                x = F.scaled_dot_product_attention(
+                    q,
+                    k,
+                    v,
+                    attn_mask=attn_mask,
+                    dropout_p=self.proj_drop_prob,
+                )
+                attn = None
+        else:
+            attn = (q @ k.transpose(-2, -1)) * self.scale
+            if attn_mask is not None:
+                attn = attn.masked_fill(~attn_mask, float("-inf"))
+            attn = attn.softmax(dim=-1)
+            attn = self.attn_drop(attn)
+            x = attn @ v
+
+        x = x.transpose(1, 2).reshape(B, N, C)
+        x = self.proj(x)
+        x = self.proj_drop(x)
+        return x, attn
+
+
+def build_block_causal_mask(
+    T,
+    H_patches,
+    W_patches,
+    token_ids=None,
+    num_prefix_tokens=1,
+    device=None,
+):
+    """Bidirectional inside a temporal slot, causal across slots.
+
+    Patch tokens are grouped into blocks by their temporal slot (a tubelet of
+    `tubelet_size` frames) and a query may attend to every key in its own block
+    and in all earlier ones, so spatial context is unrestricted while nothing
+    ever reads from the future. Token positions come from `token_ids` -- the
+    keep-set token dropping produced -- so the mask describes the true grid
+    positions of the surviving tokens rather than their order in the sequence.
+
+    The CLS prefix is the readout register: its row is all-True so it sees the
+    whole clip, but its column is False for patches. Letting patches attend to
+    it would route layer-l information about the last frame into a first-frame
+    token at layer l+1, which is exactly the leak the mask exists to prevent.
+
+    Returns a bool mask of shape (B or 1, 1, N, N), True meaning "attend".
+    """
+    tokens_per_frame = int(H_patches * W_patches)
+    if token_ids is None:
+        ids = torch.arange(int(T * tokens_per_frame), device=device).unsqueeze(0)
+    else:
+        ids = token_ids
+    frame_ids = ids // tokens_per_frame
+    mask = frame_ids.unsqueeze(-1) >= frame_ids.unsqueeze(-2)
+    if num_prefix_tokens:
+        B, N_patches, _ = mask.shape
+        p = int(num_prefix_tokens)
+        full = mask.new_zeros((B, N_patches + p, N_patches + p))
+        full[:, :p, :] = True
+        full[:, p:, p:] = mask
+        mask = full
+    return mask.unsqueeze(1)
+
+
+class Block(nn.Module):
+    def __init__(
+        self,
+        dim,
+        num_heads,
+        mlp_ratio=4.0,
+        qkv_bias=False,
+        qk_scale=None,
+        drop=0.0,
+        attn_drop=0.0,
+        act_layer=nn.GELU,
+        norm_layer=nn.LayerNorm,
+        grid_size=None,
+        grid_depth=None,
+        use_rope=False,
+    ):
+        super().__init__()
+        self.norm1 = norm_layer(dim)
+        if use_rope:
+            self.attn = RoPEAttention(
+                dim,
+                num_heads=num_heads,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                attn_drop=attn_drop,
+                proj_drop=drop,
+                grid_size=grid_size,
+            )
+        else:
+            self.attn = Attention(
+                dim,
+                num_heads=num_heads,
+                qkv_bias=qkv_bias,
+                qk_scale=qk_scale,
+                attn_drop=attn_drop,
+                proj_drop=drop,
+            )
+
+        self.norm2 = norm_layer(dim)
+        mlp_hidden_dim = int(dim * mlp_ratio)
+        self.mlp = MLP(
+            in_features=dim,
+            hidden_features=mlp_hidden_dim,
+            act_layer=act_layer,
+            drop=drop,
+        )
+
+    def forward(
+        self,
+        x,
+        return_attention=False,
+        T=None,
+        H_patches=None,
+        W_patches=None,
+        token_ids=None,
+        attn_mask=None,
+    ):
+        if isinstance(self.attn, RoPEAttention):
+            y, attn = self.attn(
+                self.norm1(x),
+                T=T,
+                H_patches=H_patches,
+                W_patches=W_patches,
+                token_ids=token_ids,
+                attn_mask=attn_mask,
+            )
+        else:
+            y, attn = self.attn(self.norm1(x), attn_mask=attn_mask)
+        if return_attention:
+            return attn
+        x = x + y
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class VisionTransformer(nn.Module):
+    """Vision Transformer"""
+
+    def __init__(
+        self,
+        img_size=224,
+        patch_size=16,
+        num_frames=1,
+        tubelet_size=2,
+        in_chans=3,
+        embed_dim=768,
+        depth=12,
+        num_heads=12,
+        mlp_ratio=4.0,
+        qkv_bias=True,
+        qk_scale=None,
+        drop_rate=0.0,
+        attn_drop_rate=0.0,
+        norm_layer=nn.LayerNorm,
+        init_std=0.02,
+        out_layers=None,
+        uniform_power=False,
+        use_rope=False,
+        token_drop_rate=0.0,
+        token_drop_mode="random",
+        token_drop_k=2,
+        attn_mode="full",
+        **kwargs,
+    ):
+        super().__init__()
+        self.num_features = self.embed_dim = embed_dim
+        self.num_heads = num_heads
+        self.out_layers = out_layers
+        self.token_drop_rate = token_drop_rate
+        self.token_drop_mode = token_drop_mode
+        self.token_drop_k = int(token_drop_k)
+        if attn_mode not in ("full", "block_causal"):
+            raise ValueError(f"Unknown attn_mode {attn_mode!r}")
+        self.attn_mode = attn_mode
+
+        self.input_size = img_size
+        self.patch_size = patch_size
+
+        self.num_frames = num_frames
+        self.tubelet_size = tubelet_size
+        self.is_video = num_frames > 1
+
+        grid_size = self.input_size // self.patch_size
+        grid_depth = self.num_frames // self.tubelet_size
+
+        # Tokenize pixels with convolution
+        if self.is_video:
+            self.patch_embed = PatchEmbed3D(
+                patch_size=patch_size,
+                tubelet_size=tubelet_size,
+                in_chans=in_chans,
+                embed_dim=embed_dim,
+            )
+            self.num_patches = (
+                (num_frames // tubelet_size)
+                * (img_size // patch_size)
+                * (img_size // patch_size)
+            )
+        else:
+            self.patch_embed = PatchEmbed(
+                patch_size=patch_size,
+                in_chans=in_chans,
+                embed_dim=embed_dim,
+            )
+            self.num_patches = (img_size // patch_size) * (img_size // patch_size)
+
+        # Position embedding
+        self.uniform_power = uniform_power
+        self.use_rope = use_rope
+        self.cls_token = nn.Parameter(torch.zeros(1, 1, embed_dim))
+        if self.use_rope:
+            self.pos_embed = None
+        else:
+            self.pos_embed = nn.Parameter(
+                torch.zeros(1, self.num_patches + 1, embed_dim),
+                requires_grad=False,
+            )
+
+        # Attention Blocks
+        self.blocks = nn.ModuleList(
+            [
+                Block(
+                    dim=embed_dim,
+                    num_heads=num_heads,
+                    mlp_ratio=mlp_ratio,
+                    qkv_bias=qkv_bias,
+                    qk_scale=qk_scale,
+                    drop=drop_rate,
+                    act_layer=nn.GELU,
+                    grid_size=grid_size,
+                    grid_depth=grid_depth,
+                    attn_drop=attn_drop_rate,
+                    norm_layer=norm_layer,
+                    use_rope=use_rope,
+                )
+                for i in range(depth)
+            ]
+        )
+        self.norm = norm_layer(embed_dim)
+
+        # ------ initialize weights
+        if self.pos_embed is not None:
+            self._init_pos_embed(self.pos_embed.data)  # sincos pos-embed
+        self.init_std = init_std
+        self.apply(self._init_weights)
+        trunc_normal_(self.cls_token, std=self.init_std)
+        self._rescale_blocks()
+
+    def _init_pos_embed(self, pos_embed):
+        embed_dim = pos_embed.size(-1)
+        grid_size = self.input_size // self.patch_size
+        if self.is_video:
+            grid_depth = self.num_frames // self.tubelet_size
+            sincos = get_3d_sincos_pos_embed(
+                embed_dim,
+                grid_size,
+                grid_depth,
+                cls_token=True,
+                uniform_power=self.uniform_power,
+            )
+        else:
+            sincos = get_2d_sincos_pos_embed(embed_dim, grid_size, cls_token=True)
+        pos_embed.copy_(torch.from_numpy(sincos).float().unsqueeze(0))
+
+    def _init_weights(self, m):
+        if isinstance(m, nn.Linear):
+            trunc_normal_(m.weight, std=self.init_std)
+            if isinstance(m, nn.Linear) and m.bias is not None:
+                nn.init.constant_(m.bias, 0)
+        elif isinstance(m, nn.LayerNorm):
+            nn.init.constant_(m.bias, 0)
+            nn.init.constant_(m.weight, 1.0)
+        elif isinstance(m, nn.Conv2d):
+            trunc_normal_(m.weight, std=self.init_std)
+            if m.bias is not None:
+                nn.init.constant_(m.bias, 0)
+        elif isinstance(m, nn.Conv3d):
+            trunc_normal_(m.weight, std=self.init_std)
+            if m.bias is not None:
+                nn.init.constant_(m.bias, 0)
+
+    def _rescale_blocks(self):
+        def rescale(param, layer_id):
+            param.div_(math.sqrt(2.0 * layer_id))
+
+        for layer_id, layer in enumerate(self.blocks):
+            rescale(layer.attn.proj.weight.data, layer_id + 1)
+            rescale(layer.mlp.fc2.weight.data, layer_id + 1)
+
+    def get_num_layers(self):
+        return len(self.blocks)
+
+    def no_weight_decay(self):
+        return {}
+
+    def forward(self, x):
+        """
+        :param x: input image/video
+        """
+
+        # Tokenize input
+        if x.ndim == 4:
+            _, _, H, W = x.shape
+            T = 1
+        elif x.ndim == 5:
+            _, _, T, H, W = x.shape
+            T = T // self.tubelet_size
+        else:
+            raise ValueError(f"Expected image or video tensor, got {x.ndim} dimensions")
+        H_patches = H // self.patch_size
+        W_patches = W // self.patch_size
+
+        pos_embed = self.pos_embed
+        if pos_embed is not None:
+            pos_embed = self.interpolate_pos_encoding(x, pos_embed)
+        x = self.patch_embed(x)
+        if pos_embed is not None:
+            cls_pos_embed = pos_embed[:, :1]
+            patch_pos_embed = pos_embed[:, 1:]
+            x += patch_pos_embed
+
+        token_ids = None
+        if self.training and self.token_drop_rate > 0:
+            B, N_patches, C = x.shape
+            if self.token_drop_mode == "tube":
+                # Keep the same random spatial locations in every temporal slot.
+                HW = H_patches * W_patches
+                keep_s = max(1, int(round(HW * (1 - self.token_drop_rate))))
+                noise = torch.rand(B, HW, device=x.device)
+                spatial_ids = noise.argsort(dim=1)[:, :keep_s]
+                temporal_offsets = torch.arange(T, device=x.device) * HW
+                token_ids = (
+                    spatial_ids[:, None, :] + temporal_offsets[None, :, None]
+                ).reshape(B, T * keep_s)
+                token_ids, _ = token_ids.sort(dim=1)
+            elif self.token_drop_mode == "tube_k":
+                # Keep short tubes: a spatial location survives for k consecutive
+                # temporal slots. The temporal axis is cut into T//k aligned blocks
+                # of length k, and we sample whole (block, location) pairs, so every
+                # kept run is contiguous and runs never overlap. k=1 degenerates to
+                # `random`, k=T to `tube`.
+                HW = H_patches * W_patches
+                k = max(1, min(self.token_drop_k, T))
+                if T % k != 0:
+                    raise ValueError(
+                        f"token_drop_mode='tube_k' needs k to divide the temporal "
+                        f"grid, got k={k} and T={T} slots"
+                    )
+                n_blocks = T // k
+                keep_len = max(1, int(round(N_patches * (1 - self.token_drop_rate))))
+                # Same token budget as the other modes (hence same FLOPs), up to the
+                # <k/2 tokens lost to rounding keep_len onto a multiple of k.
+                n_seg = min(max(1, int(round(keep_len / k))), HW * n_blocks)
+                noise = torch.rand(B, HW * n_blocks, device=x.device)
+                seg_ids = noise.argsort(dim=1)[:, :n_seg]
+                block_ids, spatial_ids = seg_ids // HW, seg_ids % HW
+                offsets = torch.arange(k, device=x.device)
+                token_ids = (
+                    (block_ids[:, :, None] * k + offsets[None, None, :]) * HW
+                    + spatial_ids[:, :, None]
+                ).reshape(B, n_seg * k)
+                token_ids, _ = token_ids.sort(dim=1)
+            else:
+                # Draw an independent keep-set over the full temporal-spatial grid.
+                keep_len = max(
+                    1, int(round(N_patches * (1 - self.token_drop_rate)))
+                )
+                noise = torch.rand(B, N_patches, device=x.device)
+                token_ids = noise.argsort(dim=1)[:, :keep_len]
+
+            x = torch.gather(
+                x,
+                dim=1,
+                index=token_ids.unsqueeze(-1).expand(-1, -1, C),
+            )
+
+        cls_token = self.cls_token.expand(x.shape[0], -1, -1)
+        if pos_embed is not None:
+            cls_token = cls_token + cls_pos_embed
+        x = torch.cat((cls_token, x), dim=1)
+
+        attn_mask = None
+        if self.attn_mode == "block_causal":
+            attn_mask = build_block_causal_mask(
+                T,
+                H_patches,
+                W_patches,
+                token_ids=token_ids,
+                num_prefix_tokens=1,
+                device=x.device,
+            )
+
+        # Fwd prop
+        outs = []
+        for i, blk in enumerate(self.blocks):
+            x = blk(
+                x,
+                T=T,
+                H_patches=H_patches,
+                W_patches=W_patches,
+                token_ids=token_ids,
+                attn_mask=attn_mask,
+            )
+            if self.out_layers is not None and i in self.out_layers:
+                outs.append(self.norm(x))
+
+        if self.out_layers is not None:
+            return outs
+
+        if self.norm is not None:
+            x = self.norm(x)
+
+        return x
+
+    def interpolate_pos_encoding(self, x, pos_embed):
+        _, N, dim = pos_embed.shape
+        cls_pos_embed = pos_embed[:, :1]
+        patch_pos_embed = pos_embed[:, 1:]
+        N = patch_pos_embed.shape[1]
+
+        if self.is_video:
+            # If pos_embed already correct size, just return.
+            _, _, T, H, W = x.shape
+            if H == self.input_size and W == self.input_size and T == self.num_frames:
+                return pos_embed
+
+            # Convert depth, height, width of input to be measured in patches
+            # instead of pixels/frames.
+            T = T // self.tubelet_size
+            H = H // self.patch_size
+            W = W // self.patch_size
+
+            # Compute the initialized shape of the positional embedding measured
+            # in patches.
+            N_t = self.num_frames // self.tubelet_size
+            N_h = N_w = self.input_size // self.patch_size
+            assert (
+                N_h * N_w * N_t == N
+            ), "Positional embedding initialized incorrectly"
+
+            # Compute scale factor for spatio-temporal interpolation.
+            scale_factor = (T / N_t, H / N_h, W / N_w)
+
+            pos_embed = nn.functional.interpolate(
+                patch_pos_embed.reshape(1, N_t, N_h, N_w, dim).permute(0, 4, 1, 2, 3),
+                scale_factor=scale_factor,
+                mode="trilinear",
+            )
+            patch_pos_embed = pos_embed.permute(0, 2, 3, 4, 1).view(1, -1, dim)
+            return torch.cat((cls_pos_embed, patch_pos_embed), dim=1)
+
+        # If pos_embed already correct size, just return.
+        _, _, H, W = x.shape
+        if H == self.input_size and W == self.input_size:
+            return pos_embed
+
+        # Compute scale factor for spatial interpolation.
+        npatch = (H // self.patch_size) * (W // self.patch_size)
+        scale_factor = math.sqrt(npatch / N)
+
+        pos_embed = nn.functional.interpolate(
+            patch_pos_embed.reshape(1, int(math.sqrt(N)), int(math.sqrt(N)), dim).permute(
+                0,
+                3,
+                1,
+                2,
+            ),
+            scale_factor=scale_factor,
+            mode="bicubic",
+        )
+        patch_pos_embed = pos_embed.permute(0, 2, 3, 1).view(1, -1, dim)
+        return torch.cat((cls_pos_embed, patch_pos_embed), dim=1)
+
+
+def vit_tiny(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=192,
+        depth=12,
+        num_heads=3,
+        mlp_ratio=4,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_small(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=384,
+        depth=12,
+        num_heads=6,
+        mlp_ratio=4,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_base(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=768,
+        depth=12,
+        num_heads=12,
+        mlp_ratio=4,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_large(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=1024,
+        depth=24,
+        num_heads=16,
+        mlp_ratio=4,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_huge(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=1280,
+        depth=32,
+        num_heads=16,
+        mlp_ratio=4,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_giant(patch_size=16, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=1408,
+        depth=40,
+        num_heads=16,
+        mlp_ratio=48 / 11,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+def vit_gigantic(patch_size=14, **kwargs):
+    model = VisionTransformer(
+        patch_size=patch_size,
+        embed_dim=1664,
+        depth=48,
+        num_heads=16,
+        mpl_ratio=64 / 13,
+        qkv_bias=True,
+        norm_layer=partial(nn.LayerNorm, eps=1e-6),
+        **kwargs,
+    )
+    return model
+
+
+VIT_EMBED_DIMS = {
+    "vit_tiny": 192,
+    "vit_small": 384,
+    "vit_base": 768,
+    "vit_large": 1024,
+    "vit_huge": 1280,
+    "vit_giant": 1408,
+    "vit_gigantic": 1664,
+}
+
+
+__all__ = [
+    "SIGReg",
+    "Attention",
+    "Block",
+    "MLP",
+    "PatchEmbed",
+    "PatchEmbed3D",
+    "Projector",
+    "RoPEAttention",
+    "VIT_EMBED_DIMS",
+    "VisionTransformer",
+    "get_1d_sincos_pos_embed",
+    "get_1d_sincos_pos_embed_from_grid",
+    "get_2d_sincos_pos_embed",
+    "get_3d_sincos_pos_embed",
+    "rotate_queries_or_keys",
+    "trunc_normal_",
+    "vit_base",
+    "vit_giant",
+    "vit_gigantic",
+    "vit_huge",
+    "vit_large",
+    "vit_small",
+    "vit_tiny",
+]
+
+
+class LeVJEPAModel(PreTrainedModel):
+    """Frozen-feature video encoder.
+
+    forward(pixel_values) -> BaseModelOutput with
+      last_hidden_state : (B, 1 + N, D)  CLS followed by patch tokens
+      pooler_output     : (B, D)         the CLS token
+
+    pixel_values is (B, C, T, H, W), already normalised. For a still image,
+    repeat it along T -- that is how the ImageNet probe feeds this model.
+    """
+
+    config_class = LeVJEPAConfig
+    base_model_prefix = "encoder"
+    main_input_name = "pixel_values"
+    supports_gradient_checkpointing = False
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.encoder = VisionTransformer(
+            img_size=config.img_size,
+            patch_size=config.patch_size,
+            num_frames=config.num_frames,
+            tubelet_size=config.tubelet_size,
+            in_chans=config.in_chans,
+            embed_dim=config.embed_dim,
+            depth=config.depth,
+            num_heads=config.num_heads,
+            mlp_ratio=config.mlp_ratio,
+            qkv_bias=config.qkv_bias,
+            norm_layer=partial(nn.LayerNorm, eps=1e-6),
+            uniform_power=config.uniform_power,
+            use_rope=config.use_rope,
+            token_drop_rate=config.token_drop_rate,
+            token_drop_mode=config.token_drop_mode,
+            token_drop_k=config.token_drop_k,
+            attn_mode=config.attn_mode,
+        )
+        self.post_init()
+
+    def _init_weights(self, module):
+        # Weights always arrive from a checkpoint; the vendored VisionTransformer
+        # already ran its own init at construction time.
+        return
+
+    def forward(self, pixel_values, return_dict=True, **kwargs):
+        hidden = self.encoder(pixel_values)
+        if isinstance(hidden, (list, tuple)):
+            hidden = hidden[-1]
+        pooled = hidden[:, 0]
+        if not return_dict:
+            return (hidden, pooled)
+        out = BaseModelOutput(last_hidden_state=hidden)
+        out["pooler_output"] = pooled
+        return out