v8: multi-airport + airport-ID token + LOAO support

train_v8_finetune.py

@@ -0,0 +1,1209 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["torch>=2.1","numpy","pandas","scikit-learn","huggingface-hub","trackio"]
+# ///
+"""
+Flight-JEPA v2 — bundled training script for HF Jobs.
+
+Self-contained: downloads the dataset from HF, trains either the supervised
+baseline (`--lambda-jepa 0`) or the JEPA-augmented model, runs blindspot
+scoring + extrapolation eval, and pushes the result to a hub repo.
+
+Usage (HF Jobs):
+    python train_v2_prod.py --tag baseline --lambda-jepa 0.0 \
+        --hub-model-id guychuk/flight-jepa-v2 --push-to-hub
+
+    python train_v2_prod.py --tag jepa --lambda-jepa 0.5 \
+        --hub-model-id guychuk/flight-jepa-v2 --push-to-hub
+"""
+from __future__ import annotations
+import argparse
+import copy
+import json
+import math
+import os
+import shutil
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import Dataset, DataLoader
+
+try:
+    import trackio
+    HAS_TRACKIO = True
+except ImportError:
+    HAS_TRACKIO = False
+
+
+# ============================================================================
+# DATA UTILITIES (inlined from flight_jepa.data)
+# ============================================================================
+
+def load_atfm(dset_name, mode, path):
+    variables = ["X", "Y", "Z"]
+    data, labels = [], None
+    for var in variables:
+        df = pd.read_csv(os.path.join(path, f"{dset_name}_{mode}_{var}.tsv"),
+                          sep="\t", header=None, na_values="NaN")
+        if labels is None:
+            labels = df.values[:, 0]
+        data.append(df.values[:, 1:])
+    return np.stack(data, axis=-1), labels.astype(int)
+
+
+def compute_features(traj_xyz: np.ndarray) -> np.ndarray:
+    if traj_xyz.shape[0] < 2:
+        T = traj_xyz.shape[0]
+        return np.concatenate([
+            traj_xyz, np.zeros((T, 3), dtype=traj_xyz.dtype),
+            np.zeros((T, 3), dtype=traj_xyz.dtype)
+        ], axis=1)
+    x, y, z = traj_xyz[:, 0], traj_xyz[:, 1], traj_xyz[:, 2]
+    diff = np.diff(traj_xyz, axis=0)
+    norms = np.maximum(np.linalg.norm(diff, axis=1, keepdims=True), 1e-8)
+    u = diff / norms
+    u = np.vstack([u, u[-1:]])
+    r = np.sqrt(x ** 2 + y ** 2)
+    theta = np.arctan2(y, x)
+    return np.column_stack([
+        traj_xyz, u,
+        r[:, None], np.sin(theta)[:, None], np.cos(theta)[:, None]
+    ]).astype(np.float32)
+
+
+def ensure_data(airport: str, data_dir: str = "data"):
+    target = os.path.join(data_dir, airport)
+    if os.path.isdir(target) and any(f.endswith(".tsv") for f in os.listdir(target)):
+        return target
+    print(f"[data] downloading {airport} from HF ...")
+    from huggingface_hub import snapshot_download
+    snap = snapshot_download(
+        "petchthwr/ATFMTraj",
+        repo_type="dataset",
+        allow_patterns=[f"{airport}/*"],
+    )
+    os.makedirs(data_dir, exist_ok=True)
+    src = os.path.join(snap, airport)
+    if not os.path.isdir(target):
+        shutil.copytree(src, target)
+    return target
+
+
+# ============================================================================
+# DATASET — variable-length blindspot
+# ============================================================================
+
+PAD_VALUE = 0.0
+
+# Multi-airport (v8) — global registry. Order is the airport-ID embedding index.
+# r_max from the ATFMTraj README; used to convert normalized ENU [-1,1] -> meters.
+AIRPORTS = ["RKSIa", "RKSId", "ESSA", "LSZH"]
+RMAX_KM_PER_AIRPORT = {
+    "RKSIa": 120.0,
+    "RKSId": 120.0,  # same airport, departures
+    "ESSA": 100.0,
+    "LSZH": 40.0 * 1.852,  # 40 NM -> km
+}
+AIRPORT_TO_ID = {a: i for i, a in enumerate(AIRPORTS)}
+
+
+class BlindspotDataset(Dataset):
+    def __init__(self, airport, mode, data_dir,
+                 past_max=256, past_min=60,
+                 delta_min=30, delta_max=120,
+                 seed=0, epoch_multiplier=4,
+                 held_out_classes=None,  # None = no filter; list = exclude these classes
+                 keep_only_classes=None,  # None = no filter; list = keep ONLY these classes (overrides held_out)
+                 ):
+        ensure_data(airport, data_dir)
+        airport_dir = os.path.join(data_dir, airport)
+        raw, labels = load_atfm(airport, mode, airport_dir)
+
+        self.past_max = past_max
+        self.past_min = past_min
+        self.delta_min = delta_min
+        self.delta_max = delta_max
+        self.epoch_multiplier = epoch_multiplier
+        self.rng_seed = seed
+
+        lengths = np.array(
+            [int(np.sum(~np.isnan(raw[i, :, 0]))) for i in range(raw.shape[0])],
+            dtype=np.int64,
+        )
+        min_required = past_min + delta_max + 1
+        keep = lengths >= min_required
+        if keep.sum() == 0:
+            raise RuntimeError(
+                f"No trajectories of length >= {min_required} in {airport}/{mode}"
+            )
+
+        # Class-based filtering (held-out generalization eval)
+        if keep_only_classes is not None:
+            keep_set = set(int(c) for c in keep_only_classes)
+            class_keep = np.array([int(c) in keep_set for c in labels])
+            keep = keep & class_keep
+        elif held_out_classes is not None:
+            held = set(int(c) for c in held_out_classes)
+            class_keep = np.array([int(c) not in held for c in labels])
+            keep = keep & class_keep
+
+        raw = raw[keep]
+        lengths = lengths[keep]
+        self.labels = labels[keep].astype(np.int64)
+
+        self.positions = []
+        for i in range(raw.shape[0]):
+            L = int(lengths[i])
+            self.positions.append(np.nan_to_num(raw[i, :L], nan=0.0).astype(np.float32))
+        del raw
+
+        self.n_traj = len(self.positions)
+        self.airport = airport
+        # Airport ID for multi-airport conditioning. Single-airport runs
+        # default to ID 0 (which is RKSIa); multi-airport runs read this.
+        self.airport_id = AIRPORT_TO_ID.get(airport, 0)
+        print(f"[data] {airport}/{mode}: {self.n_traj} trajectories "
+              f"(after filtering for L >= {min_required})")
+
+    def __len__(self):
+        return self.n_traj * self.epoch_multiplier
+
+    def __getitem__(self, idx):
+        traj_idx = idx % self.n_traj
+        rng = np.random.default_rng(self.rng_seed + idx * 9173)
+        positions = self.positions[traj_idx]
+        L = positions.shape[0]
+        delta = int(rng.integers(self.delta_min, self.delta_max + 1))
+        t_in_max = L - delta - 1
+        t_in_min = self.past_min
+        t_in = int(rng.integers(t_in_min, t_in_max + 1))
+
+        past_start = max(0, t_in - self.past_max)
+        past_pos = positions[past_start:t_in]
+        target_pos = positions[t_in:t_in + delta]
+
+        past_features = compute_features(past_pos)
+        T_past = past_features.shape[0]
+        feat_pad = np.full((self.past_max, 9), PAD_VALUE, dtype=np.float32)
+        feat_pad[:T_past] = past_features
+        tgt_pad = np.zeros((self.delta_max, 3), dtype=np.float32)
+        tgt_pad[:delta] = target_pos
+        return {
+            "past_features": torch.from_numpy(feat_pad),
+            "past_length": torch.tensor(T_past, dtype=torch.long),
+            "target_pos": torch.from_numpy(tgt_pad),
+            "delta": torch.tensor(delta, dtype=torch.long),
+            "label": torch.tensor(int(self.labels[traj_idx]), dtype=torch.long),
+            "airport_id": torch.tensor(self.airport_id, dtype=torch.long),
+        }
+
+
+class MultiAirportBlindspotDataset(Dataset):
+    """
+    Concatenates several BlindspotDatasets (one per airport) and yields samples
+    tagged with `airport_id`. Used for v8 LOAO training: instantiate this with
+    {RKSIa, RKSId, ESSA, LSZH} minus the held-out airport.
+    """
+
+    def __init__(self, airports, mode, data_dir,
+                 past_max=256, past_min=60,
+                 delta_min=30, delta_max=120,
+                 seed=0, epoch_multiplier=4):
+        self.subsets = []
+        for ap in airports:
+            ds = BlindspotDataset(
+                airport=ap, mode=mode, data_dir=data_dir,
+                past_max=past_max, past_min=past_min,
+                delta_min=delta_min, delta_max=delta_max,
+                seed=seed, epoch_multiplier=1,  # we handle multiplier ourselves
+            )
+            self.subsets.append(ds)
+        self.epoch_multiplier = epoch_multiplier
+        self.delta_min = delta_min
+        self.delta_max = delta_max
+        self.past_max = past_max
+        # Index map: for each global idx (without multiplier), which subset + local idx
+        self._cum = np.cumsum([s.n_traj for s in self.subsets])
+        self.n_traj = int(self._cum[-1])
+        print(f"[multi-data] union of {[s.airport for s in self.subsets]} "
+              f"-> {self.n_traj} trajectories total")
+
+    def __len__(self):
+        return self.n_traj * self.epoch_multiplier
+
+    def _route(self, global_idx):
+        i = global_idx % self.n_traj
+        sub = int(np.searchsorted(self._cum, i, side="right"))
+        local = i - (self._cum[sub - 1] if sub > 0 else 0)
+        return sub, local
+
+    def __getitem__(self, idx):
+        sub, local = self._route(idx)
+        ds = self.subsets[sub]
+        # Reproducibility: use idx so reshuffling DataLoader still gives stable samples.
+        # We bypass ds.__getitem__'s seeding (which is index-relative) by replicating
+        # its logic with our own RNG.
+        rng = np.random.default_rng(ds.rng_seed + idx * 9173)
+        positions = ds.positions[local]
+        L = positions.shape[0]
+        delta = int(rng.integers(self.delta_min, self.delta_max + 1))
+        t_in_max = L - delta - 1
+        t_in_min = ds.past_min
+        t_in = int(rng.integers(t_in_min, t_in_max + 1))
+        past_start = max(0, t_in - self.past_max)
+        past_pos = positions[past_start:t_in]
+        target_pos = positions[t_in:t_in + delta]
+        past_features = compute_features(past_pos)
+        T_past = past_features.shape[0]
+        feat_pad = np.full((self.past_max, 9), PAD_VALUE, dtype=np.float32)
+        feat_pad[:T_past] = past_features
+        tgt_pad = np.zeros((self.delta_max, 3), dtype=np.float32)
+        tgt_pad[:delta] = target_pos
+        return {
+            "past_features": torch.from_numpy(feat_pad),
+            "past_length": torch.tensor(T_past, dtype=torch.long),
+            "target_pos": torch.from_numpy(tgt_pad),
+            "delta": torch.tensor(delta, dtype=torch.long),
+            "label": torch.tensor(int(ds.labels[local]), dtype=torch.long),
+            "airport_id": torch.tensor(ds.airport_id, dtype=torch.long),
+        }
+
+
+# ============================================================================
+# MODEL
+# ============================================================================
+
+def sinusoidal_embedding(values, dim):
+    half = dim // 2
+    device = values.device
+    freqs = torch.exp(-math.log(10000.0)
+                      * torch.arange(half, device=device) / half)
+    angles = values.float().unsqueeze(-1) * freqs
+    emb = torch.cat([torch.sin(angles), torch.cos(angles)], dim=-1)
+    if dim % 2 == 1:
+        emb = F.pad(emb, (0, 1))
+    return emb
+
+
+class LearnablePosEnc(nn.Module):
+    def __init__(self, max_len, d_model):
+        super().__init__()
+        self.pe = nn.Parameter(torch.randn(1, max_len, d_model) * 0.02)
+    def forward(self, x):
+        return x + self.pe[:, :x.size(1)]
+
+
+class PatchTokenizer(nn.Module):
+    def __init__(self, in_channels=9, d_model=256, patch_size=8, max_patches=64):
+        super().__init__()
+        self.patch_size = patch_size
+        self.d_model = d_model
+        self.embed = nn.Sequential(
+            nn.Conv1d(in_channels, d_model // 2, 5, padding=2),
+            nn.GELU(),
+            nn.Conv1d(d_model // 2, d_model, 3, padding=1),
+            nn.GELU(),
+        )
+        self.pos_enc = LearnablePosEnc(max_patches, d_model)
+        self.norm = nn.LayerNorm(d_model)
+
+    def forward(self, features, lengths):
+        B, T, C = features.shape
+        h = self.embed(features.transpose(1, 2))
+        N = max(1, T // self.patch_size)
+        h = h[:, :, :N * self.patch_size]
+        h = h.reshape(B, self.d_model, N, self.patch_size).mean(-1)
+        h = h.transpose(1, 2)
+        h = self.norm(self.pos_enc(h))
+        patch_lengths = (lengths.float() / self.patch_size).clamp(min=1).long()
+        patch_lengths = patch_lengths.clamp(max=N)
+        return h, patch_lengths
+
+
+class CausalEncoder(nn.Module):
+    def __init__(self, d_model=256, n_heads=8, n_layers=4, d_ff=1024, dropout=0.1):
+        super().__init__()
+        layer = nn.TransformerEncoderLayer(
+            d_model=d_model, nhead=n_heads, dim_feedforward=d_ff,
+            dropout=dropout, activation="gelu", batch_first=True,
+            norm_first=True,
+        )
+        self.tf = nn.TransformerEncoder(layer, num_layers=n_layers)
+        self.norm = nn.LayerNorm(d_model)
+
+    def forward(self, x, key_padding_mask):
+        N = x.size(1)
+        causal_mask = torch.triu(
+            torch.ones(N, N, dtype=torch.bool, device=x.device), diagonal=1
+        )
+        return self.norm(
+            self.tf(x, mask=causal_mask, src_key_padding_mask=key_padding_mask)
+        )
+
+
+def last_valid_token(encoded, patch_lengths):
+    B, N, D = encoded.shape
+    idx = (patch_lengths - 1).clamp(min=0).view(B, 1, 1).expand(-1, 1, D)
+    return encoded.gather(1, idx).squeeze(1)
+
+
+class DeltaEmbedding(nn.Module):
+    def __init__(self, d_model=256, d_freq=64):
+        super().__init__()
+        self.d_freq = d_freq
+        self.proj = nn.Sequential(
+            nn.Linear(d_freq * 2, d_model),
+            nn.GELU(),
+            nn.Linear(d_model, d_model),
+        )
+    def forward(self, delta, t_past):
+        d_emb = sinusoidal_embedding(delta.float(), self.d_freq)
+        rel = delta.float() / t_past.float().clamp(min=1.0)
+        rel_emb = sinusoidal_embedding(rel * 100.0, self.d_freq)
+        return self.proj(torch.cat([d_emb, rel_emb], dim=-1))
+
+
+class GaussianHead(nn.Module):
+    def __init__(self, d_model=256, d_hidden=256):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(d_model, d_hidden), nn.GELU(),
+            nn.Linear(d_hidden, d_hidden), nn.GELU(),
+        )
+        self.mu_head = nn.Linear(d_hidden, 3)
+        self.log_sigma_head = nn.Linear(d_hidden, 3)
+        self.rho_head = nn.Linear(d_hidden, 1)
+
+    def forward(self, h):
+        z = self.net(h)
+        delta_mu = self.mu_head(z)
+        log_sigma = self.log_sigma_head(z).clamp(min=-7.0, max=2.0)
+        rho = torch.tanh(self.rho_head(z)).squeeze(-1) * 0.99
+        return delta_mu, log_sigma, rho
+
+
+def gaussian_nll_xyz(true_delta, mu, log_sigma, rho, beta: float = 0.5):
+    """
+    β-NLL Gaussian for (x, y, z) — bivariate on xy + independent z.
+
+    Standard NLL has a degenerate minimum where σ→0 ("σ-collapse",
+    Detlefsen 2019). β-NLL (Seitzer et al., arxiv:2203.09168) reweights
+    each sample's NLL by ��^{2β} (detached) so points with large σ get
+    proportionally more gradient on the mean term, preventing collapse.
+
+    β = 0   → standard NLL (collapse-prone, what v2 used)
+    β = 0.5 → recommended; preserves uncertainty learning
+    β = 1   → pure squared-error scaling (loses σ learning)
+    """
+    sx = log_sigma[:, 0].exp()
+    sy = log_sigma[:, 1].exp()
+    sz = log_sigma[:, 2].exp()
+    dx = true_delta[:, 0] - mu[:, 0]
+    dy = true_delta[:, 1] - mu[:, 1]
+    dz = true_delta[:, 2] - mu[:, 2]
+    omr2 = (1.0 - rho * rho).clamp(min=1e-6)
+    z2 = (((dx / sx) ** 2)
+          - 2.0 * rho * (dx / sx) * (dy / sy)
+          + ((dy / sy) ** 2)) / omr2
+    log_det = 2.0 * (log_sigma[:, 0] + log_sigma[:, 1]) + torch.log(omr2)
+    nll_xy = 0.5 * (z2 + log_det + 2.0 * math.log(2.0 * math.pi))
+    nll_z = 0.5 * ((dz / sz) ** 2 + 2.0 * log_sigma[:, 2]
+                    + math.log(2.0 * math.pi))
+
+    if beta > 0.0:
+        # Detached per-sample weights: σ^{2β}. Weight is treated as constant
+        # during backward, so it rescales the gradient without participating
+        # in optimization.
+        # For xy use geometric-mean σ; for z use σz directly.
+        sxy = (sx * sy).sqrt().detach()
+        wxy = sxy.pow(2.0 * beta)
+        wz = sz.detach().pow(2.0 * beta)
+        return wxy * nll_xy + wz * nll_z
+    return nll_xy + nll_z
+
+
+class ParallelDecoder(nn.Module):
+    """
+    HiVT-style parallel decoder (arxiv:2207.09588).
+
+    Takes a single context vector h ∈ R^d (fused z_in + Δ_emb) and emits
+    a full [T_max, 7] tensor of (μ_x, μ_y, μ_z, log σ_x, log σ_y, log σ_z, ρ)
+    in one forward pass. Each row is the prediction for one future timestep
+    (relative to the start of the blindspot).
+
+    Coherence comes from the shared MLP backbone + per-step positional embed
+    (every step is a function of the same context, with smoothly-varying
+    positional inputs). Variable Δ is handled by masking unused steps in the
+    loss.
+
+    Output represents *absolute positions* at each step, not deltas. The
+    NLL loss is applied per-step against target_pos[:, t].
+    """
+
+    def __init__(self, d_model: int = 256, t_max: int = 120, mlp_hidden: int = 512,
+                 dropout: float = 0.1):
+        super().__init__()
+        self.t_max = t_max
+        self.d_model = d_model
+        self.step_pe = LearnablePosEnc(t_max, d_model)
+        self.mlp = nn.Sequential(
+            nn.Linear(d_model, mlp_hidden),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(mlp_hidden, mlp_hidden),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(mlp_hidden, 7),
+        )
+        # T-Fixup-flavor init: small last-layer std reduces transformer instability
+        # (arxiv:2004.08249). For an MLP this matters less but doesn't hurt.
+        nn.init.trunc_normal_(self.mlp[-1].weight, std=0.02)
+        nn.init.zeros_(self.mlp[-1].bias)
+
+    def forward(self, h: torch.Tensor) -> torch.Tensor:
+        """
+        h: (B, D) context vector
+        returns: (B, T_max, 7) — (μ_x, μ_y, μ_z, log σ_x, log σ_y, log σ_z, rho_pre)
+        """
+        B = h.size(0)
+        # Broadcast h across all steps, then add per-step positional embedding.
+        h_expand = h.unsqueeze(1).expand(B, self.t_max, self.d_model)
+        h_step = self.step_pe(h_expand)  # adds learnable per-step PE
+        out = self.mlp(h_step)  # (B, T_max, 7)
+        return out
+
+
+def split_parallel_output(raw: torch.Tensor):
+    """raw (B, T, 7) -> (mu, log_sigma, rho).
+    mu: (B, T, 3); log_sigma: (B, T, 3); rho: (B, T)."""
+    mu = raw[..., :3]
+    log_sigma = raw[..., 3:6].clamp(min=-7.0, max=2.0)
+    rho = torch.tanh(raw[..., 6]) * 0.99
+    return mu, log_sigma, rho
+
+
+def parallel_nll_xyz(true_pos: torch.Tensor, mu: torch.Tensor,
+                      log_sigma: torch.Tensor, rho: torch.Tensor,
+                      mask: torch.Tensor, beta: float = 0.5) -> torch.Tensor:
+    """
+    Per-batch β-NLL over a (B, T, ·) tensor. mask: (B, T) float, 1 for valid.
+    Returns scalar mean NLL across (sample, valid steps).
+    """
+    sx = log_sigma[..., 0].exp()
+    sy = log_sigma[..., 1].exp()
+    sz = log_sigma[..., 2].exp()
+    dx = true_pos[..., 0] - mu[..., 0]
+    dy = true_pos[..., 1] - mu[..., 1]
+    dz = true_pos[..., 2] - mu[..., 2]
+    omr2 = (1.0 - rho * rho).clamp(min=1e-6)
+    z2 = (((dx / sx) ** 2)
+          - 2.0 * rho * (dx / sx) * (dy / sy)
+          + ((dy / sy) ** 2)) / omr2
+    log_det = 2.0 * (log_sigma[..., 0] + log_sigma[..., 1]) + torch.log(omr2)
+    nll_xy = 0.5 * (z2 + log_det + 2.0 * math.log(2.0 * math.pi))
+    nll_z = 0.5 * ((dz / sz) ** 2 + 2.0 * log_sigma[..., 2]
+                    + math.log(2.0 * math.pi))
+    nll = nll_xy + nll_z  # (B, T)
+
+    if beta > 0.0:
+        sxy = (sx * sy).sqrt().detach()
+        wxy = sxy.pow(2.0 * beta)
+        wz = sz.detach().pow(2.0 * beta)
+        nll = wxy * nll_xy + wz * nll_z
+
+    nll = nll * mask
+    valid = mask.sum(-1).clamp(min=1.0)
+    return (nll.sum(-1) / valid).mean()
+
+
+class FuturePredictor(nn.Module):
+    def __init__(self, d_model=256, pred_dim=128, dropout=0.1):
+        super().__init__()
+        self.proj_in = nn.Linear(d_model * 2, pred_dim)
+        layer = nn.TransformerEncoderLayer(
+            d_model=pred_dim, nhead=4, dim_feedforward=pred_dim * 2,
+            dropout=dropout, activation="gelu", batch_first=True, norm_first=True,
+        )
+        self.tf = nn.TransformerEncoder(layer, num_layers=2)
+        self.proj_out = nn.Linear(pred_dim, d_model)
+        self.norm = nn.LayerNorm(d_model)
+
+    def forward(self, z_in, delta_emb):
+        h = self.proj_in(torch.cat([z_in, delta_emb], dim=-1)).unsqueeze(1)
+        h = self.tf(h)
+        return self.norm(self.proj_out(h.squeeze(1)))
+
+
+class FlightJEPAv2(nn.Module):
+    def __init__(self, cfg):
+        super().__init__()
+        self.cfg = cfg
+        d = cfg.get("d_model", 256)
+        h_ = cfg.get("n_heads", 8)
+        n_l = cfg.get("n_layers", 4)
+        d_ff = cfg.get("d_ff", 1024)
+        dr = cfg.get("dropout", 0.1)
+        ps = cfg.get("patch_size", 8)
+        past_max = cfg.get("past_max", 256)
+        max_patches = past_max // ps
+        self.lambda_jepa = cfg.get("lambda_jepa", 0.0)
+        self.ema_decay = cfg.get("ema_decay", 0.998)
+        self.beta_nll = cfg.get("beta_nll", 0.5)
+        self.decoder_mode = cfg.get("decoder_mode", "ar")  # "ar" or "parallel"
+        self.t_max = cfg.get("delta_max", 120)
+        # v8: airport-ID conditioning. n_airports=4 = max we currently support
+        # (RKSIa, RKSId, ESSA, LSZH). Single-airport runs always pass airport_id=0
+        # and the embedding for that index acts as a no-op constant offset.
+        self.n_airports = cfg.get("n_airports", 4)
+        self.use_airport_token = cfg.get("use_airport_token", False)
+
+        self.tokenizer = PatchTokenizer(9, d, ps, max_patches)
+        self.encoder = CausalEncoder(d, h_, n_l, d_ff, dr)
+        self.delta_emb = DeltaEmbedding(d, 64)
+        # If airport conditioning is enabled, fuse a (d-dim) airport embed
+        # alongside z_in + delta_e via a wider linear projection.
+        # This module exists in both single-airport and multi-airport configs;
+        # for single-airport we just pass a fixed embedding for airport 0.
+        self.airport_emb = nn.Embedding(self.n_airports, d)
+        nn.init.trunc_normal_(self.airport_emb.weight, std=0.02)
+        if self.use_airport_token:
+            self.fuse_in = nn.Sequential(
+                nn.Linear(d * 3, d), nn.GELU(),
+                nn.Linear(d, d),
+            )
+        else:
+            self.fuse_in = nn.Sequential(
+                nn.Linear(d * 2, d), nn.GELU(),
+                nn.Linear(d, d),
+            )
+        # Both heads exist to keep checkpoint structure stable across modes,
+        # but only one is used per run.
+        self.head = GaussianHead(d, d)  # AR head
+        self.step_cell = nn.GRUCell(input_size=3, hidden_size=d)
+        self.parallel_decoder = ParallelDecoder(
+            d_model=d, t_max=self.t_max,
+            mlp_hidden=d * 2, dropout=dr,
+        )
+
+        self.target_tokenizer = copy.deepcopy(self.tokenizer)
+        self.target_encoder = copy.deepcopy(self.encoder)
+        for p in self.target_tokenizer.parameters():
+            p.requires_grad = False
+        for p in self.target_encoder.parameters():
+            p.requires_grad = False
+        self.predictor = FuturePredictor(d, d // 2, dr)
+
+    @torch.no_grad()
+    def update_ema(self):
+        m = self.ema_decay
+        for online, target in [(self.tokenizer, self.target_tokenizer),
+                                (self.encoder, self.target_encoder)]:
+            for po, pt in zip(online.parameters(), target.parameters()):
+                pt.data.mul_(m).add_(po.data, alpha=1.0 - m)
+
+    def encode_past(self, past_features, past_length):
+        patches, patch_lens = self.tokenizer(past_features, past_length)
+        N = patches.size(1)
+        pad_mask = (torch.arange(N, device=patches.device).unsqueeze(0)
+                    >= patch_lens.unsqueeze(1))
+        encoded = self.encoder(patches, key_padding_mask=pad_mask)
+        z_in = last_valid_token(encoded, patch_lens)
+        return z_in, encoded, patch_lens
+
+    @torch.no_grad()
+    def encode_future_target(self, target_features, target_length):
+        patches, patch_lens = self.target_tokenizer(target_features, target_length)
+        N = patches.size(1)
+        pad_mask = (torch.arange(N, device=patches.device).unsqueeze(0)
+                    >= patch_lens.unsqueeze(1))
+        encoded = self.target_encoder(patches, key_padding_mask=pad_mask)
+        return last_valid_token(encoded, patch_lens)
+
+    def forward(self, past_features, past_length, target_pos, delta, last_pos,
+                ss_prob: float = 0.0, airport_id=None):
+        """
+        ss_prob: scheduled-sampling probability ∈ [0, 1]. AR mode only —
+                  parallel mode predicts all timesteps in one shot, no SS needed.
+        airport_id: (B,) long tensor for v8 multi-airport conditioning. Required
+                  if cfg.use_airport_token is True; ignored otherwise.
+        """
+        B = past_features.size(0)
+        device = past_features.device
+        delta_max = target_pos.size(1)
+
+        z_in, _, _ = self.encode_past(past_features, past_length)
+        delta_e = self.delta_emb(delta, past_length)
+        if self.use_airport_token:
+            if airport_id is None:
+                airport_id = torch.zeros(B, dtype=torch.long, device=device)
+            ap_e = self.airport_emb(airport_id)
+            h = self.fuse_in(torch.cat([z_in, delta_e, ap_e], dim=-1))
+        else:
+            h = self.fuse_in(torch.cat([z_in, delta_e], dim=-1))
+
+        # ---------------- PARALLEL DECODER (v6) ----------------
+        if self.decoder_mode == "parallel":
+            raw = self.parallel_decoder(h)  # (B, t_max, 7)
+            # Truncate to current batch's delta_max if smaller (target padding).
+            raw = raw[:, :delta_max]
+            mu, log_sigma, rho = split_parallel_output(raw)
+            arange = torch.arange(delta_max, device=device).unsqueeze(0)  # (1, T)
+            mask = (arange < delta.unsqueeze(1)).float()  # (B, T)
+
+            nll_loss = parallel_nll_xyz(target_pos, mu, log_sigma, rho, mask,
+                                         beta=self.beta_nll)
+            with torch.no_grad():
+                step_l2 = (target_pos - mu).pow(2).sum(-1).sqrt()  # (B, T)
+                ade_train = (step_l2 * mask).sum(-1) / mask.sum(-1).clamp(min=1.0)
+                ade_train = ade_train.mean()
+
+            losses = {"nll": nll_loss, "ade_train": ade_train, "total": nll_loss}
+
+            if self.lambda_jepa > 0.0:
+                tgt_feat = torch.zeros(B, delta_max, 9, device=device)
+                tgt_feat[..., :3] = target_pos
+                z_target = self.encode_future_target(tgt_feat, delta)
+                z_pred = self.predictor(z_in, delta_e)
+                jepa_loss = F.l1_loss(z_pred, z_target.detach())
+                losses["jepa"] = jepa_loss
+                losses["total"] = nll_loss + self.lambda_jepa * jepa_loss
+
+            return losses
+
+        # ---------------- AR DECODER (v5, default) ----------------
+        prev_pos = last_pos
+        nll_total = torch.zeros(B, device=device)
+        valid_steps = torch.zeros(B, device=device)
+        ade_total = torch.zeros(B, device=device)
+
+        for t in range(delta_max):
+            delta_mu, log_sigma, rho = self.head(h)
+            true_pos_t = target_pos[:, t]
+            true_delta = true_pos_t - prev_pos
+
+            # NLL computed always vs truth.
+            nll = gaussian_nll_xyz(true_delta, delta_mu, log_sigma, rho,
+                                    beta=self.beta_nll)
+            mask = (t < delta).float()
+            nll_total = nll_total + nll * mask
+            ade_total = (ade_total
+                         + (true_delta - delta_mu).pow(2).sum(-1).sqrt() * mask)
+            valid_steps = valid_steps + mask
+
+            # Scheduled-sampling: with prob ss_prob, feed predicted delta instead
+            # of true delta into the recurrence. Sampled per (batch, step).
+            if ss_prob > 0.0 and self.training:
+                use_pred = (torch.rand(B, device=device) < ss_prob).float().unsqueeze(-1)
+                # Use predicted mean as "what we would do at inference time".
+                # Detach so the prev_pos accumulator gradient doesn't recurse.
+                fed_delta = use_pred * delta_mu.detach() + (1 - use_pred) * true_delta
+                fed_pos = use_pred * (prev_pos + delta_mu.detach()) + (1 - use_pred) * true_pos_t
+            else:
+                fed_delta = true_delta
+                fed_pos = true_pos_t
+
+            h = self.step_cell(fed_delta, h)
+            prev_pos = fed_pos
+
+        nll_loss = (nll_total / valid_steps.clamp(min=1.0)).mean()
+        ade_train = (ade_total / valid_steps.clamp(min=1.0)).mean().detach()
+
+        losses = {"nll": nll_loss, "ade_train": ade_train, "total": nll_loss}
+
+        if self.lambda_jepa > 0.0:
+            tgt_feat = torch.zeros(B, delta_max, 9, device=device)
+            tgt_feat[..., :3] = target_pos
+            z_target = self.encode_future_target(tgt_feat, delta)
+            z_pred = self.predictor(z_in, delta_e)
+            jepa_loss = F.l1_loss(z_pred, z_target.detach())
+            losses["jepa"] = jepa_loss
+            losses["total"] = nll_loss + self.lambda_jepa * jepa_loss
+
+        return losses
+
+    @torch.no_grad()
+    def rollout(self, past_features, past_length, delta, last_pos, delta_max,
+                airport_id=None):
+        B = past_features.size(0)
+        device = past_features.device
+        z_in, _, _ = self.encode_past(past_features, past_length)
+        delta_e = self.delta_emb(delta, past_length)
+        if self.use_airport_token:
+            if airport_id is None:
+                airport_id = torch.zeros(B, dtype=torch.long, device=device)
+            ap_e = self.airport_emb(airport_id)
+            h = self.fuse_in(torch.cat([z_in, delta_e, ap_e], dim=-1))
+        else:
+            h = self.fuse_in(torch.cat([z_in, delta_e], dim=-1))
+
+        if self.decoder_mode == "parallel":
+            # Need t_max queries. If extrapolating beyond train t_max, the
+            # learnable PE doesn't extend — pad by clamping at t_max.
+            req = max(delta_max, 1)
+            n_emit = min(req, self.t_max)
+            raw = self.parallel_decoder(h)  # (B, t_max, 7)
+            raw = raw[:, :n_emit]
+            mu_abs, log_sigma, rho = split_parallel_output(raw)
+            sigma = log_sigma.exp()
+            mu_pos = torch.zeros(B, delta_max, 3, device=device)
+            sg = torch.zeros(B, delta_max, 3, device=device)
+            ro = torch.zeros(B, delta_max, device=device)
+            mu_pos[:, :n_emit] = mu_abs
+            sg[:, :n_emit] = sigma
+            ro[:, :n_emit] = rho
+            # If extrapolating beyond t_max, repeat the last predicted step
+            # (a deliberate choice — better than zero-fill which would alias
+            # to the airport origin).
+            if delta_max > n_emit:
+                mu_pos[:, n_emit:] = mu_abs[:, -1:]
+                sg[:, n_emit:] = sigma[:, -1:]
+                ro[:, n_emit:] = rho[:, -1:]
+            return mu_pos, sg, ro
+
+        # ----- AR rollout (v5) -----
+        prev_pos = last_pos
+        mu_pos = torch.zeros(B, delta_max, 3, device=device)
+        sigma = torch.zeros(B, delta_max, 3, device=device)
+        rho_out = torch.zeros(B, delta_max, device=device)
+        for t in range(delta_max):
+            delta_mu, log_sigma, rho = self.head(h)
+            cur_pos = prev_pos + delta_mu
+            mu_pos[:, t] = cur_pos
+            sigma[:, t] = log_sigma.exp()
+            rho_out[:, t] = rho
+            h = self.step_cell(delta_mu, h)
+            prev_pos = cur_pos
+        return mu_pos, sigma, rho_out
+
+
+# ============================================================================
+# TRAIN + SCORE
+# ============================================================================
+
+RMAX_KM = 120.0
+DELTA_BUCKETS = [(30, 60), (60, 90), (90, 120)]
+EXTRAP_DELTAS = [180, 300]
+THRESH_M = [500.0, 1000.0, 2000.0]
+
+
+def get_last_pos(past_features, past_length):
+    B = past_features.size(0)
+    idx = (past_length - 1).clamp(min=0)
+    return past_features[torch.arange(B, device=past_features.device), idx, :3]
+
+
+def train_one_epoch(model, loader, optimizer, device, grad_clip=1.0,
+                     log_every: int = 50, ss_prob: float = 0.0):
+    model.train()
+    sums = {"nll": 0.0, "ade": 0.0, "jepa": 0.0, "total": 0.0, "n": 0}
+    t0 = time.time()
+    n_batches = len(loader) if hasattr(loader, "__len__") else 0
+    for bi, batch in enumerate(loader):
+        past_f = batch["past_features"].to(device)
+        past_l = batch["past_length"].to(device)
+        target = batch["target_pos"].to(device)
+        delta = batch["delta"].to(device)
+        airport_id = batch.get("airport_id")
+        if airport_id is not None:
+            airport_id = airport_id.to(device)
+        last_pos = get_last_pos(past_f, past_l)
+        losses = model(past_f, past_l, target, delta, last_pos,
+                        ss_prob=ss_prob, airport_id=airport_id)
+        optimizer.zero_grad()
+        losses["total"].backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip)
+        optimizer.step()
+        if model.lambda_jepa > 0.0:
+            model.update_ema()
+        bs = past_f.size(0)
+        sums["nll"] += losses["nll"].item() * bs
+        sums["ade"] += losses["ade_train"].item() * bs
+        if "jepa" in losses:
+            sums["jepa"] += losses["jepa"].item() * bs
+        sums["total"] += losses["total"].item() * bs
+        sums["n"] += bs
+
+        if (bi + 1) % log_every == 0 or bi == 0:
+            dt = time.time() - t0
+            rate = (bi + 1) / max(dt, 0.001)
+            print(f"  [batch {bi+1}/{n_batches}] {dt:.1f}s elapsed, "
+                  f"{rate:.1f} batch/s, loss={losses['total'].item():.4f}",
+                  flush=True)
+    n = max(sums["n"], 1)
+    return {k: v / n for k, v in sums.items() if k != "n"} | {
+        "ade_train": sums["ade"] / n
+    }
+
+
+@torch.no_grad()
+def score_loader(model, loader, device, extrap_delta=None):
+    model.train(False)
+    delta_max_dataset = loader.dataset.delta_max
+    per_sample = []
+    for batch in loader:
+        past_f = batch["past_features"].to(device)
+        past_l = batch["past_length"].to(device)
+        target = batch["target_pos"].to(device)
+        delta = batch["delta"].to(device)
+        airport_id = batch.get("airport_id")
+        if airport_id is not None:
+            airport_id = airport_id.to(device)
+        last_pos = get_last_pos(past_f, past_l)
+        if extrap_delta is not None:
+            forced = torch.full_like(delta, extrap_delta)
+            roll_len = extrap_delta
+        else:
+            forced = delta
+            roll_len = int(delta.max().item())
+        if roll_len > delta_max_dataset:
+            continue
+        mu_pos, sigma, rho = model.rollout(past_f, past_l, forced, last_pos, roll_len,
+                                            airport_id=airport_id)
+        active_len = torch.minimum(forced, delta).clamp(min=1)
+        for i in range(past_f.size(0)):
+            L = int(active_len[i].item())
+            per_sample.append({
+                "mu": mu_pos[i, :L].cpu().numpy(),
+                "sigma": sigma[i, :L].cpu().numpy(),
+                "rho": rho[i, :L].cpu().numpy(),
+                "target": target[i, :L].cpu().numpy(),
+                "delta_orig": int(delta[i].item()),
+            })
+
+    if not per_sample:
+        return {}
+    ades, fdes = [], []
+    in_circle = {t: [] for t in THRESH_M}
+    nlls, coverage95, delta_orig = [], [], []
+    for s in per_sample:
+        diff = s["target"] - s["mu"]
+        per_step_l2 = np.linalg.norm(diff, axis=1) * RMAX_KM * 1000.0
+        ades.append(per_step_l2.mean())
+        fdes.append(per_step_l2[-1])
+        for t in THRESH_M:
+            in_circle[t].append(per_step_l2[-1] <= t)
+        sx = max(s["sigma"][-1, 0], 1e-9)
+        sy = max(s["sigma"][-1, 1], 1e-9)
+        sz = max(s["sigma"][-1, 2], 1e-9)
+        rho_xy = s["rho"][-1]
+        dx = diff[-1, 0]; dy = diff[-1, 1]; dz = diff[-1, 2]
+        omr2 = max(1.0 - rho_xy * rho_xy, 1e-6)
+        z2 = ((dx / sx) ** 2 - 2 * rho_xy * (dx / sx) * (dy / sy)
+              + (dy / sy) ** 2) / omr2
+        coverage95.append(z2 <= 5.991)
+        log_det = 2 * (math.log(sx) + math.log(sy)) + math.log(omr2)
+        nll_xy = 0.5 * (z2 + log_det + 2 * math.log(2 * math.pi))
+        nll_z = 0.5 * ((dz / sz) ** 2 + 2 * math.log(sz) + math.log(2 * math.pi))
+        nlls.append(nll_xy + nll_z)
+        delta_orig.append(s["delta_orig"])
+    ades = np.array(ades); fdes = np.array(fdes)
+    nlls = np.array(nlls); coverage95 = np.array(coverage95, dtype=float)
+    delta_orig = np.array(delta_orig)
+    out = {
+        "ade_m": float(ades.mean()),
+        "fde_m": float(fdes.mean()),
+        "fde_median_m": float(np.median(fdes)),
+        "nll_xy_z": float(nlls.mean()),
+        "coverage_95": float(coverage95.mean()),
+        "n": len(ades),
+    }
+    for t in THRESH_M:
+        out[f"miss_rate_{int(t)}m"] = float(1.0 - np.mean(in_circle[t]))
+    if extrap_delta is None:
+        per_bucket = {}
+        for lo, hi in DELTA_BUCKETS:
+            mask = (delta_orig >= lo) & (delta_orig <= hi)
+            if mask.sum() == 0:
+                continue
+            per_bucket[f"delta_{lo}_{hi}"] = {
+                "ade_m": float(ades[mask].mean()),
+                "fde_m": float(fdes[mask].mean()),
+                "coverage_95": float(coverage95[mask].mean()),
+                "n": int(mask.sum()),
+            }
+        out["per_bucket"] = per_bucket
+    return out
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--airport", default="RKSIa",
+                   help="Single-airport training (legacy). Ignored if --multi-airport is set.")
+    p.add_argument("--multi-airport", default=None,
+                   help="Comma-separated TRAINING airports for v8 multi-airport runs, "
+                        "e.g. 'RKSId,ESSA,LSZH'. Pairs with --eval-airport.")
+    p.add_argument("--eval-airport", default=None,
+                   help="HELD-OUT airport for LOAO eval. If unset and --multi-airport is set, "
+                        "evaluates on the union (no held-out).")
+    p.add_argument("--use-airport-token", action="store_true",
+                   help="v8: enable airport-ID conditioning (UniTraj recipe).")
+    p.add_argument("--data-dir", default="data")
+    p.add_argument("--tag", default="run")
+    p.add_argument("--out-dir", default="runs")
+    p.add_argument("--epochs", type=int, default=30)
+    p.add_argument("--batch-size", type=int, default=64)
+    p.add_argument("--lr", type=float, default=1e-4)
+    p.add_argument("--weight-decay", type=float, default=1e-4)
+    p.add_argument("--past-max", type=int, default=256)
+    p.add_argument("--past-min", type=int, default=60)
+    p.add_argument("--delta-min", type=int, default=30)
+    p.add_argument("--delta-max", type=int, default=120)
+    p.add_argument("--extrap-delta-max", type=int, default=300)
+    p.add_argument("--epoch-multiplier", type=int, default=4)
+    p.add_argument("--lambda-jepa", type=float, default=0.0)
+    p.add_argument("--ema-decay", type=float, default=0.998)
+    p.add_argument("--beta-nll", type=float, default=0.5,
+                   help="β-NLL exponent (Seitzer 2022). 0=plain NLL, 0.5=recommended.")
+    p.add_argument("--ss-max", type=float, default=0.0,
+                   help="Max scheduled-sampling probability (0=teacher-forcing only, 0.5=Bengio recommended).")
+    p.add_argument("--ss-warmup-frac", type=float, default=0.5,
+                   help="Fraction of training over which ss_prob ramps from 0 to ss_max linearly.")
+    p.add_argument("--decoder-mode", choices=["ar", "parallel"], default="ar",
+                   help="ar = v5 GRU autoregressive; parallel = v6 HiVT-style MLP decoder.")
+    p.add_argument("--d-model", type=int, default=256)
+    p.add_argument("--n-layers", type=int, default=4)
+    p.add_argument("--n-heads", type=int, default=8)
+    p.add_argument("--patch-size", type=int, default=8)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--num-workers", type=int, default=2)
+    p.add_argument("--push-to-hub", action="store_true")
+    p.add_argument("--hub-model-id", default=None)
+    p.add_argument("--pretrained-encoder", default=None,
+                   help="Path or HF repo id to a pretrained encoder checkpoint "
+                        "(loaded into tokenizer + encoder weights before training).")
+    p.add_argument("--pretrained-encoder-file", default=None,
+                   help="If --pretrained-encoder is a HF repo, name of the file in it.")
+    p.add_argument("--freeze-encoder", action="store_true",
+                   help="Freeze tokenizer + encoder weights after loading pretrained.")
+    p.add_argument("--held-out-classes", default=None,
+                   help="Comma-separated class IDs to EXCLUDE from training (e.g., '6,18,28').")
+    p.add_argument("--keep-only-classes", default=None,
+                   help="Comma-separated class IDs to KEEP for evaluation (eval on these only).")
+    p.add_argument("--trackio-name", default=None)
+    args = p.parse_args()
+
+    torch.manual_seed(args.seed)
+    np.random.seed(args.seed)
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"[v2] device={device} tag={args.tag} "
+          f"decoder_mode={args.decoder_mode} "
+          f"lambda_jepa={args.lambda_jepa} beta_nll={args.beta_nll} "
+          f"ss_max={args.ss_max} ss_warmup_frac={args.ss_warmup_frac}",
+          flush=True)
+    if device == "cuda":
+        print(f"[v2] cuda device: {torch.cuda.get_device_name(0)} "
+              f"vram={torch.cuda.get_device_properties(0).total_memory/1e9:.1f}GB",
+              flush=True)
+    else:
+        print("[v2] WARNING: CUDA not available, training on CPU. "
+              "This will be very slow.", flush=True)
+
+    if HAS_TRACKIO and args.trackio_name:
+        trackio.init(project="flight-jepa-v2", name=args.trackio_name,
+                      config=vars(args))
+
+    held_out = (
+        [int(c) for c in args.held_out_classes.split(",")]
+        if args.held_out_classes else None
+    )
+    keep_only = (
+        [int(c) for c in args.keep_only_classes.split(",")]
+        if args.keep_only_classes else None
+    )
+    if args.multi_airport:
+        train_airports = [a.strip() for a in args.multi_airport.split(",")]
+        train_ds = MultiAirportBlindspotDataset(
+            airports=train_airports, mode="TRAIN", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.delta_max,
+            seed=args.seed, epoch_multiplier=args.epoch_multiplier,
+        )
+        eval_ap = args.eval_airport if args.eval_airport else train_airports[0]
+        test_ds = BlindspotDataset(
+            airport=eval_ap, mode="TEST", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.delta_max,
+            seed=args.seed + 1, epoch_multiplier=1,
+        )
+        extrap_ds = BlindspotDataset(
+            airport=eval_ap, mode="TEST", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.extrap_delta_max,
+            seed=args.seed + 99, epoch_multiplier=1,
+        )
+        print(f"[v8] LOAO: train={train_airports} eval={eval_ap}")
+    else:
+        train_ds = BlindspotDataset(
+            airport=args.airport, mode="TRAIN", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.delta_max,
+            seed=args.seed, epoch_multiplier=args.epoch_multiplier,
+            held_out_classes=held_out, keep_only_classes=keep_only,
+        )
+        test_ds = BlindspotDataset(
+            airport=args.airport, mode="TEST", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.delta_max,
+            seed=args.seed + 1, epoch_multiplier=1,
+            held_out_classes=held_out, keep_only_classes=keep_only,
+        )
+        extrap_ds = BlindspotDataset(
+            airport=args.airport, mode="TEST", data_dir=args.data_dir,
+            past_max=args.past_max, past_min=args.past_min,
+            delta_min=args.delta_min, delta_max=args.extrap_delta_max,
+            seed=args.seed + 99, epoch_multiplier=1,
+            held_out_classes=held_out, keep_only_classes=keep_only,
+        )
+
+    train_dl = DataLoader(train_ds, batch_size=args.batch_size, shuffle=True,
+                           num_workers=args.num_workers, pin_memory=True,
+                           drop_last=True)
+    test_dl = DataLoader(test_ds, batch_size=args.batch_size, shuffle=False,
+                          num_workers=args.num_workers, pin_memory=True)
+    extrap_dl = DataLoader(extrap_ds, batch_size=args.batch_size, shuffle=False,
+                            num_workers=args.num_workers, pin_memory=True)
+
+    cfg = {
+        "d_model": args.d_model, "n_heads": args.n_heads,
+        "n_layers": args.n_layers, "d_ff": args.d_model * 4,
+        "dropout": 0.1, "patch_size": args.patch_size,
+        "past_max": args.past_max, "lambda_jepa": args.lambda_jepa,
+        "ema_decay": args.ema_decay, "beta_nll": args.beta_nll,
+        "decoder_mode": args.decoder_mode,
+        "delta_max": args.delta_max,
+        "use_airport_token": args.use_airport_token,
+        "n_airports": len(AIRPORTS),
+    }
+    model = FlightJEPAv2(cfg).to(device)
+    n_params = sum(p.numel() for p in model.parameters())
+    print(f"[v2] params={n_params/1e6:.2f}M")
+
+    # Optionally load pretrained encoder + tokenizer from a v7 pretrain run.
+    if args.pretrained_encoder:
+        path = args.pretrained_encoder
+        if not os.path.exists(path):
+            # Treat as HF repo id; download the named file.
+            from huggingface_hub import hf_hub_download
+            file_name = args.pretrained_encoder_file or "v7-pretrain.pt"
+            path = hf_hub_download(args.pretrained_encoder, file_name)
+        ck = torch.load(path, map_location=device, weights_only=False)
+        miss_t, unx_t = model.tokenizer.load_state_dict(
+            ck["tokenizer_state_dict"], strict=False
+        )
+        miss_e, unx_e = model.encoder.load_state_dict(
+            ck["encoder_state_dict"], strict=False
+        )
+        print(f"[v2] loaded pretrained encoder from {path}")
+        print(f"     tokenizer missing={len(miss_t)} unexpected={len(unx_t)}")
+        print(f"     encoder   missing={len(miss_e)} unexpected={len(unx_e)}")
+        # Also seed the EMA copies with the same weights.
+        model.target_tokenizer.load_state_dict(model.tokenizer.state_dict())
+        model.target_encoder.load_state_dict(model.encoder.state_dict())
+        if args.freeze_encoder:
+            for p_ in model.tokenizer.parameters():
+                p_.requires_grad = False
+            for p_ in model.encoder.parameters():
+                p_.requires_grad = False
+            print("[v2] tokenizer + encoder FROZEN")
+
+    optimizer = torch.optim.AdamW(model.parameters(), lr=args.lr,
+                                   weight_decay=args.weight_decay)
+    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=args.epochs)
+
+    os.makedirs(args.out_dir, exist_ok=True)
+    history = []
+    best_fde = float("inf")
+    best_state = None
+
+    for epoch in range(args.epochs):
+        t0 = time.time()
+        # Linear ramp ss_prob: 0 → ss_max over args.ss_warmup_frac of training,
+        # then hold at ss_max.
+        warmup_epochs = max(1, int(args.epochs * args.ss_warmup_frac))
+        ss_prob = min(args.ss_max,
+                      args.ss_max * (epoch + 1) / warmup_epochs)
+        train_stats = train_one_epoch(model, train_dl, optimizer, device,
+                                       ss_prob=ss_prob)
+        scheduler.step()
+
+        score_stats = None
+        if (epoch + 1) % 5 == 0 or epoch == args.epochs - 1:
+            score_stats = score_loader(model, test_dl, device)
+            if score_stats and score_stats["fde_m"] < best_fde:
+                best_fde = score_stats["fde_m"]
+                best_state = {k: v.detach().cpu().clone()
+                              for k, v in model.state_dict().items()}
+
+        elapsed = time.time() - t0
+        log = {
+            "epoch": epoch + 1, "elapsed_s": elapsed,
+            "lr": optimizer.param_groups[0]["lr"],
+            "train": train_stats, "score": score_stats,
+        }
+        history.append(log)
+        msg = (f"[v2] ep {epoch+1:03d} | loss={train_stats['total']:.4f} "
+               f"nll={train_stats['nll']:.4f} ade_t={train_stats['ade_train']:.4f} "
+               f"jepa={train_stats['jepa']:.4f} ss={ss_prob:.2f}")
+        if score_stats:
+            msg += f" | fde={score_stats['fde_m']:.0f}m ade={score_stats['ade_m']:.0f}m"
+        msg += f" | {elapsed:.0f}s"
+        print(msg, flush=True)
+
+        if HAS_TRACKIO and args.trackio_name:
+            tlog = {f"train/{k}": v for k, v in train_stats.items()}
+            if score_stats:
+                tlog.update({f"test/{k}": v for k, v in score_stats.items()
+                             if isinstance(v, (int, float))})
+            trackio.log(tlog, step=epoch + 1)
+
+    final = {"in_distribution": score_loader(model, test_dl, device)}
+    for d in EXTRAP_DELTAS:
+        final[f"extrap_delta_{d}"] = score_loader(model, extrap_dl, device, extrap_delta=d)
+
+    if best_state is not None:
+        model.load_state_dict(best_state)
+
+    out_path = os.path.join(args.out_dir, f"{args.tag}.pt")
+    torch.save({
+        "state_dict": model.state_dict(),
+        "config": cfg, "args": vars(args),
+        "history": history, "final": final,
+        "best_fde_m": best_fde,
+    }, out_path)
+    print(f"[v2] saved {out_path}")
+
+    summary_path = os.path.join(args.out_dir, f"{args.tag}_summary.json")
+    with open(summary_path, "w") as f:
+        json.dump({
+            "tag": args.tag, "lambda_jepa": args.lambda_jepa,
+            "beta_nll": args.beta_nll,
+            "n_params": n_params, "best_fde_m": best_fde,
+            "final": final, "args": vars(args),
+        }, f, indent=2, default=float)
+    print(f"[v2] summary -> {summary_path}", flush=True)
+
+    if args.push_to_hub and args.hub_model_id:
+        try:
+            from huggingface_hub import HfApi
+            api = HfApi()
+            api.create_repo(args.hub_model_id, exist_ok=True)
+            for path, fname in [(out_path, f"{args.tag}.pt"),
+                                 (summary_path, f"{args.tag}_summary.json")]:
+                api.upload_file(path_or_fileobj=path, path_in_repo=fname,
+                                 repo_id=args.hub_model_id)
+            print(f"[v2] uploaded to {args.hub_model_id}")
+        except Exception as e:
+            print(f"[v2] hub upload failed: {e}")
+
+    if HAS_TRACKIO and args.trackio_name:
+        trackio.finish()
+
+
+if __name__ == "__main__":
+    main()