Add DIVER-1 any-variate iEEG foundation model - #1170

Adds the architecture-only DIVER1 any-variate iEEG foundation model and integrates it into Braindecode.

Changes:

• Implements DIVER1 embeddings, metadata handling, transformer encoder, and classification head.
• Registers and publicly exports the model; updates documentation, licensing, and catalog metadata.
• Adds integration and return-feature test coverage.

Suppressed comments (6)

braindecode/models/diver1.py:574

• This unconditional check prevents the advertised any-variate path from accepting a different channel count: with pooling="mean" and use_position_emb=False, the remaining operations derive their shapes/IDs from x and the head has no channel dimension, but this raises before reaching them. Gate this validation on fixed metadata or flatten pooling (or revise the any-variate API claim).

        if x.shape[1] != self.n_chans:

braindecode/models/diver1.py:458

• chs_info["loc"][:3] is an MNE head-frame position, not an MNI coordinate (see braindecode/models/util.py:811-813). Multiplying it by 1e3 and treating it as MNI silently feeds the wrong coordinate system into this positional encoder for the documented fallback; require an explicit MNI chan_pos or apply and document the appropriate transform.

                # MNE stores channel positions in metres; DIVER-1 encodes MNI
                # coordinates in millimetres.
                rows.append([float(v) * 1e3 for v in list(loc)[:3]])

braindecode/models/diver1.py:499

• When chs_info is omitted, every kind is None and this maps every channel to the learned EEG embedding. Since DIVER1 is an iEEG model and the metadata-optional constructor is exercised by the registry/integration tests, missing metadata silently selects the scalp-EEG modality instead of a defined unknown/neutral value or the model's iEEG default.

            modality = ["iEEG" if _is_intracranial(k) else "EEG" for k in kinds]

braindecode/models/diver1.py:424

• Directly assigning _n_outputs bypasses EEGModuleMixin._set_n_outputs, so serialized configs can still report the old class count after reset_head; the replacement Linear is also always CPU/float32, which breaks a reset on a moved or half-precision model. Preserve the old head's metadata, device, and dtype when rebuilding it.

        self._n_outputs = n_outputs
        self.final_layer = nn.Linear(self.final_layer.in_features, n_outputs)

braindecode/models/diver1.py:439

• chan_pos is documented as array-like and is accepted here from NumPy/Torch arrays, but the base build_model_config skips non-JSON-serializable init arguments and these coordinates only live in non-persistent buffers. Consequently, get_config()/from_config() silently drops explicit array coordinates and reloads a different montage. Store a JSON-serializable copy when explicit positions are supplied.

        if chan_pos is not None:
            pos = torch.as_tensor(chan_pos, dtype=torch.float32)

braindecode/models/diver1.py:697

• The constructor accepts any positive patch_size, but this default formula produces stride=0 for padded patch sizes below 16, so valid inputs such as patch_size=1 fail in the stride validation. Clamp the default to at least 1 or reject those patch sizes explicitly.

            stride = padded // (8 if patch_size >= 100 else 16)

• Files reviewed: 9/10 changed files
• Comments generated: 2
• Review effort level: Lite

Suppressed comments (4)

braindecode/models/diver1.py:136

• With the default pooling="flatten", this is not true for the model's logits: the final linear layer consumes channel-ordered tokens, so permuting channels changes the output even when the encoder is equivariant. This setting makes the encoder representation equivariant; only pooling="mean" makes the readout invariant to channel order.

    coordinate term contributes little). Set ``use_position_emb=False`` to drop
    the coordinate and type terms entirely, which makes the whole model exactly
    channel-permutation equivariant.

braindecode/models/diver1.py:925

• F.unfold and F.fold interpret the padding value on both sides of the temporal axis. With window=7, this produces n_patches + 6 windows and gives each output patch a 13-patch effective receptive field, rather than the centered 7-patch window described above. Use half-padding (self.window // 2) here (or otherwise document and test the intended wider receptive field).

            "padding": (0, self.window - 1),

braindecode/models/summary.csv:57

• The parameter count in this catalog row does not match the implementation. For the displayed defaults (22 channels, 1000 samples, 4 outputs, hence 2 patches), summing the parameters created by DIVER1 gives 12,716,742, not 12,711,366, so the model-zoo metadata underreports the model size. Please regenerate or update this row.

DIVER1,General,"Prediction, Embedding",500,"n_chans, n_outputs, n_times",12711366,"DIVER1(n_chans=22, n_outputs=4, n_times=1000, sfreq=500)","Attention/Transformer,Foundation Model,Channel",iEEG

test/unit_tests/models/test_return_features.py:89

• The added DIVER1 coverage only smoke-tests the default no-metadata, exact-window path. It does not exercise the chs_info/explicit metadata resolution, pooling="mean", non-divisible patch padding, or the STCPE/attention ID packing, so substantial regressions in this new encoder could pass the suite; add focused tests for these branches and shape/invariance contracts.

    pytest.param(
        DIVER1,
        N_CHANS,
        {"patch_size": 100, "d_model": 64, "n_layers": 2},
        True,
        id="DIVER1",

• Files reviewed: 8/9 changed files
• Comments generated: 3
• Review effort level: Lite

Suppressed comments (5)

Previously missed (2) — in code that hasn't changed since the last review.

braindecode/models/diver1.py:423

• reset_head bypasses EEGModuleMixin._set_n_outputs, so invalid output sizes are not validated and get_config()/Hub config retain the old n_outputs. It also recreates the head on CPU/float32, so calling it after .double() or .to(device) makes the next forward fail. Use the shared helper and preserve the old head's device and dtype.
  braindecode/models/diver1.py:577
• This guard fixes the channel count to the montage used at construction, and the channel metadata buffers are fixed to the same size. Consequently even pooling="mean" cannot accept an arbitrary-channel recording; callers must rebuild the model, which contradicts the PR's any-variate/variable-input contract. Either make per-recording metadata part of forward and derive these tensors dynamically, or narrow the public claim to a model rebuilt per montage.

braindecode/models/diver1.py:376

• chan_pos is documented as an array-like, but this code only keeps the resolved coordinates in non-persistent buffers. EEGModuleMixin.build_model_config drops non-JSONable constructor values such as NumPy arrays, so get_config() and Hub save/load silently lose explicitly supplied positions and reload from chs_info or unknown coordinates. Preserve a JSON-safe copy of the explicit positions in the serialized config (or restore these buffers through another defined mechanism).

        coords, coords_known = self._resolve_chan_pos(chan_pos)
        self.register_buffer("chan_coords", coords, persistent=False)
        self.register_buffer("chan_coords_known", coords_known, persistent=False)

braindecode/models/diver1.py:457

• chs_info[i]["loc"][:3] is an MNE head-frame location, not an MNI coordinate (see braindecode/models/util.py:729-731). This fallback therefore silently feeds the wrong coordinate system into an embedding documented as MNI; require/transform an explicit MNI chan_pos, or document and use the actual frame instead.

                # MNE stores channel positions in metres; DIVER-1 encodes MNI
                # coordinates in millimetres.
                rows.append([float(v) * 1e3 for v in list(loc)[:3]])

braindecode/models/diver1.py:135

• This overstates the invariance guarantee: with the default pooling="flatten", the fixed-position linear head assigns different weights to channel slots, so permuting channels changes the logits even when the encoder is equivariant. Qualify the statement to the encoder, or limit the logits claim to mean pooling.

    coordinate term contributes little). Set ``use_position_emb=False`` to drop
    the coordinate and type terms entirely, which makes the whole model exactly
    channel-permutation equivariant.

• Files reviewed: 8/9 changed files
• Comments generated: 0 new
• Review effort level: Lite