Re-host ZUNA1.1 encoder in braindecode parameter names (the ZUNA1 file did not load into braindecode.models.ZUNA)
daf5ccc verified Download convert_zuna11.py from braindecode/ZUNA: direct link, hf CLI and curl.
- Browser
- Download file 6.52 kB
-
https://huggingface.co/braindecode/ZUNA/resolve/main/convert_zuna11.py
- Command line
-
hf download hf://braindecode/ZUNA/convert_zuna11.py
-
curl -L -o convert_zuna11.py https://huggingface.co/braindecode/ZUNA/resolve/main/convert_zuna11.py
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() | |