Feature Extraction
Safetensors
braindecode
eeg
foundation-model
ZUNA / convert_zuna11.py
bruAristimunha's picture
Re-host ZUNA1.1 encoder in braindecode parameter names (the ZUNA1 file did not load into braindecode.models.ZUNA)
daf5ccc verified
Raw History Blame Contribute Delete
6.52 kB
"""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()