"""Convert the Zyphra/ZUNA1.1 checkpoint to braindecode's ZUNA class. The upstream file holds the full ZUNA1.1 pretraining model (encoder and rectified-flow decoder, 639 tensors named ``model.*``). Braindecode's :class:`braindecode.models.ZUNA` is the ZUNA1.1 encoder followed by a classification head, so this script 1. downloads ``model-00001-of-00001.safetensors`` from Zyphra/ZUNA1.1 at a pinned revision and checks its sha256; 2. keeps the 213 encoder tensors, renamed to the class's parameter names (``model.encoder.X`` -> ``encoder.X``; the upstream RMSNorm wraps a ``torch.nn.RMSNorm`` as ``.norm``, so ``*.norm.weight`` -> ``*.weight``), and drops the 426 decoder tensors; 3. loads them into ``ZUNA`` with ``strict=False`` and requires that the only missing keys are the classification head and nothing is unexpected, and that every loaded tensor equals its source bit for bit; 4. saves the encoder (no head) with ``save_pretrained``, with a config.json that leaves the input geometry (channels, window, outputs) to the user. Usage:: python convert_zuna11.py --out ./export [--weights local.safetensors] Then:: from braindecode.models import ZUNA model = ZUNA.from_pretrained("braindecode/ZUNA", chs_info=raw.info["chs"], n_times=1280, n_outputs=4) Upstream code: github.com/Zyphra/zuna @ c7b0195252e197bf0d1f9a0cebbb602ed0b69284 (``EncoderTransformer`` in ``src/zuna/inference/AY2l/lingua/apps/AY2latent_bci/transformer.py``). """ from __future__ import annotations import argparse import hashlib import json from pathlib import Path import torch REPO_ID = "Zyphra/ZUNA1.1" REVISION = "10b9d6c8285ab808685f079f586bdafe3ad2c9a3" FILENAME = "model-00001-of-00001.safetensors" SHA256 = "295fcddb42ab4623dc1346fba12176798d97ab95389c666907e32cbce23f7f33" # ZUNA1.1 buckets each scalp coordinate into 100 bins over +/-0.12 m # (upstream configs/config_bci.yaml and config_infer_fif.yaml: # num_bins_discretize_xyz_chan_pos: 100, chan_pos_xyz_extremes_type: "twelves"). # ZUNA1 used 50 bins. All other ZUNA1.1 hyperparameters are the class defaults. RELEASE_KWARGS = dict(pos_bins=100) SFREQ = 256 HEAD_KEYS = {"final_layer.1.weight", "final_layer.1.bias"} GEOMETRY_KEYS = ("n_outputs", "n_chans", "chs_info", "n_times", "input_window_seconds") def sha256sum(path, chunk=1 << 24): digest = hashlib.sha256() with open(path, "rb") as f: for block in iter(lambda: f.read(chunk), b""): digest.update(block) return digest.hexdigest() def convert_key(key: str) -> str | None: """Upstream key -> braindecode ZUNA key; None for tensors not in the class.""" if not key.startswith("model.encoder."): return None # decoder key = key[len("model.") :] if key.endswith(".norm.weight"): # upstream RMSNorm(...).norm = nn.RMSNorm key = key[: -len(".norm.weight")] + ".weight" return key def convert_state_dict(upstream: dict) -> dict: converted, dropped = {}, [] for key, value in upstream.items(): new = convert_key(key) if new is None: dropped.append(key) continue if new in converted: raise ValueError(f"two upstream tensors map to {new}") converted[new] = value.to(torch.float32) if not all(k.startswith("model.decoder.") for k in dropped): raise ValueError(f"unexpected upstream tensors: {dropped}") return converted def standard_chs_info(names=None, montage="standard_1005"): import mne names = names or ( "Fp1 Fp2 F7 F3 Fz F4 F8 T7 C3 Cz C4 T8 P7 P3 Pz P4 P8 O1 O2".split() ) info = mne.create_info(names, SFREQ, "eeg") info.set_montage(montage) return info["chs"] def build_model(converted: dict, chs_info=None, n_times=1280, n_outputs=4): """ZUNA with the converted encoder; strict on every non-head key.""" from braindecode.models import ZUNA model = ZUNA( n_outputs=n_outputs, chs_info=chs_info if chs_info is not None else standard_chs_info(), n_times=n_times, sfreq=SFREQ, **RELEASE_KWARGS, ) result = model.load_state_dict(converted, strict=False) if set(result.missing_keys) != HEAD_KEYS or result.unexpected_keys: raise RuntimeError( f"strict load failed: missing={result.missing_keys} " f"unexpected={result.unexpected_keys}" ) own = model.state_dict() for key, value in converted.items(): if not torch.equal(own[key], value): raise RuntimeError(f"{key} differs after loading") return model.eval() def load_upstream(weights=None, cache_dir=None): from safetensors.torch import load_file if weights is None: from huggingface_hub import hf_hub_download weights = hf_hub_download( REPO_ID, FILENAME, revision=REVISION, cache_dir=cache_dir ) digest = sha256sum(weights) if digest != SHA256: raise ValueError(f"{weights}: sha256 {digest}, expected {SHA256}") return load_file(weights) def export(converted: dict, out: Path): """``save_pretrained`` of the encoder (no head) with a geometry-free config.""" model = build_model(converted) model.final_layer = torch.nn.Identity() # the head is task-specific: not saved out.mkdir(parents=True, exist_ok=True) model.save_pretrained(out) config_path = out / "config.json" config = json.loads(config_path.read_text()) for key in GEOMETRY_KEYS: config[key] = None config["sfreq"] = SFREQ config_path.write_text(json.dumps(config, indent=2) + "\n") for extra in ("pytorch_model.bin", "README.md"): # safetensors + config only (out / extra).unlink(missing_ok=True) return {p.name: sha256sum(p) for p in sorted(out.iterdir()) if p.is_file()} def main(): parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument("--out", type=Path, required=True) parser.add_argument("--weights", help="local copy of the upstream file") parser.add_argument("--cache-dir") args = parser.parse_args() upstream = load_upstream(args.weights, args.cache_dir) converted = convert_state_dict(upstream) print( f"upstream tensors {len(upstream)}: encoder {len(converted)} kept, " f"decoder {len(upstream) - len(converted)} dropped" ) for name, digest in export(converted, args.out).items(): print(f"{digest} {name}") if __name__ == "__main__": main()