braindecode.models.SAMBA#

class braindecode.models.SAMBA(n_outputs=None, n_chans=None, chs_info=None, n_times=None, input_window_seconds=None, sfreq=None, *, target_positions=None, base_channels=64, bottleneck_channels=128, d_state=16, d_conv=2, expand=8, head_dim=16, cdse_hidden_dim=32, branch_kernel_sizes=(1, 3, 7), pool_size=2, stage_kernel_size=3, encoder1_head_dim=64, chunk_size=64, dt_min=0.001, dt_max=0.1, dt_init_floor=0.0001, a_init_range=(1.0, 16.0), norm_eps=1e-05, channel_strategy='native', channel_strategy_kwargs=None)[source]#

SAMBA from Hong et al. (2026) [samba].

Convolution Recurrent Channel Foundation Model

Added in version 2.1.

Architecture Overview

The encoder of SAMBA, a U-shaped Mamba autoencoder pretrained to rebuild masked EEG; the reconstruction decoder is not part of this class. A coordinate-driven spatial embedding (CDSE) first projects the electrodes onto a fixed target montage from their 3D positions, so the layers behind it never see the recording montage. Mamba-2 state space blocks [mamba2], with max-pooling and convolutions in between, then read the time axis in linear time (p is pool_size, 2 by default):

(batch, n_chans, n_times)
-> CDSE                       (batch, n_targets, n_times)
-> multi-branch convolution   (batch, base_channels, n_times)
-> Linear, residual Mamba-2   (batch, n_times, base_channels)
-> pool, convolution          (batch, base_channels, n_times // p)
-> pool, convolution          (batch, bottleneck_channels, n_times // p**2)
-> pool                       (batch, bottleneck_channels, n_times // p**3)
-> Linear, differential Mamba-2, Linear
                              (batch, n_times // p**3, bottleneck_channels)
-> mean and std over time     (batch, 2 * bottleneck_channels)
-> final_layer                (batch, n_outputs)

Macro Components

SAMBA.encoder.cdse

Operations. An MLP Linear(3, cdse_hidden_dim) -> ReLU -> Linear(cdse_hidden_dim, 1) scores the offset from each electrode to each target position; a softmax over the electrodes turns the scores into weights, and each target channel is the weighted sum of the electrodes. Role. Montage-agnostic input: any layout with 3D positions reaches the same layers.

SAMBA.encoder.input_embedding

Operations. One Conv1d per entry of branch_kernel_sizes (1, 3 and 7 by default) over the target channels, concatenated and fused by a pointwise convolution. Role. Temporal features at several scales on the target montage.

SAMBA.encoder.encoder1_mamba

Operations. After a Linear, a residual Mamba-2 block: input-dependent step sizes, a causal depthwise convolution, a scan over the time axis in chunks of chunk_size steps and a gated RMS norm. The scan is a pure PyTorch recurrence, with no CUDA dependency; its results need not be bitwise identical to the authors’ fused CUDA kernels. Role. Models the signal at the input rate.

SAMBA.encoder.encoder2, SAMBA.encoder.encoder3

Operations. Conv1d of kernel size stage_kernel_size behind a max-pooling by pool_size each, with no activation in between, as in the authors’ code. Role. Divide the time axis by pool_size at each stage and widen the features to bottleneck_channels.

SAMBA.encoder.bottleneck_mamba

Operations. The channels are split into heads of head_dim. Two Mamba-2 blocks read each head, and first - lam * second followed by a GroupNorm cancels what the two readings share, with lam a learned scale per channel. A Linear mixes the heads, with a residual connection. Role. The multi-head differential Mamba of the paper, at 1 / pool_size ** 3 of the input rate (one eighth by default).

SAMBA.final_layer

Operations. Linear on the mean and the population standard deviation (correction=0) of the encoder output over time. Not pretrained. Role. The task head; reset_head() replaces it.

Temporal, Spatial, and Spectral Encoding

  • Temporal: Mamba-2 state space blocks at the input rate and at the rate left by three max-poolings by pool_size; the output has n_times // pool_size ** 3 steps (n_times // 8 by default).

  • Spatial: electrodes enter only through their 3D positions, so any montage with positions can be read.

  • Spectral: no explicit spectral transform; the convolutions and the state space blocks learn it.

Additional Mechanisms

  • Coordinates. Positions are read from chs_info[i]["loc"][:3], in metres, and must be in the frame of target_positions. The target montage of the authors’ released weights is in the frame of the colin27_1005 template of MNE (mne.channels.make_standard_montage; standard_1005 in older versions, deprecated in MNE 1.13), not in the head frame that raw.set_montage writes into chs_info, which is a few centimetres away.

  • Input scale. The model does not normalise its input. The authors’ recipe uses EEG at 128 Hz and divides each channel of each window by the 95th percentile of its absolute value.

  • Not causal. The convolutions and the GroupNorm look at the whole window, so the encoder is not a streaming model. The Mamba-2 blocks alone are causal.

  • Mamba-2 defaults. encoder1_head_dim, dt_min, dt_max, dt_init_floor, a_init_range and norm_eps default to the values of the reference Mamba2 of state-spaces/mamba.

Pretrained Weights

The encoders of the authors’ SAMBA-2s and SAMBA-100s are on the Hugging Face Hub at braindecode/samba-2s-pretrained and braindecode/samba-100s-pretrained, with the authors’ values (their files are Dcode-AI/SAMBA-2s at e553287 and Dcode-AI/SAMBA-100s at 3a235a1). The authors retrained both after the checkpoints of the paper were lost, so they are not the paper’s SAMBA-E and SAMBA-T. SAMBA-2s was pretrained on 2 s windows (256 samples) of Emotiv, HBN, Muse and DICE recordings, SAMBA-100s on 100 s windows (12,800 samples) of TUAB, so a TUAB task does not test transfer for it. Both expect EEG at 128 Hz, each channel of each window divided by the 95th percentile of its absolute value, with positions in metres in the frame of the colin27_1005 template (see Coordinates and Input scale). The head is not pretrained: from_pretrained builds it for your n_outputs and takes the 94 target electrodes of the weights as chs_info unless you pass yours. On a fixed input, the first and last five features of both encoders match those of the authors’ files, loaded with the port of #1689, to within 1e-5 (#1739); they were not compared with the authors’ fused CUDA kernels.

from braindecode.models import SAMBA

model = SAMBA.from_pretrained("braindecode/samba-2s-pretrained", n_outputs=2)
# x: (batch, 94, n_times) -> features: (batch, 256)
features = model(x, return_features=True)["features"]
Parameters:
  • n_outputs (int | None) – Number of outputs of the model. This is the number of classes in the case of classification.

  • n_chans (int | None) – Number of EEG channels.

  • chs_info (list[dict] | None) – Information about each individual EEG channel. This should be filled with info["chs"]. Refer to mne.Info for more details.

  • n_times (int | None) – Number of time samples of the input window.

  • input_window_seconds (float | None) – Length of the input window in seconds.

  • sfreq (float | None) – Sampling frequency of the EEG recordings.

  • target_positions (list[list[float]] | None) – Positions (n_targets, 3), in metres, of the montage onto which the CDSE projects the electrodes. None takes the positions of chs_info; the saved config records them, so the trained model loads on another montage.

  • base_channels (int) – Width of the multi-branch embedding and of the first Mamba-2 stage.

  • bottleneck_channels (int) – Width of the differential Mamba-2 bottleneck; the head reads twice this many features.

  • d_state (int) – State size of every Mamba-2 block.

  • d_conv (int) – Kernel size of the causal depthwise convolution of every Mamba-2 block.

  • expand (int) – Inner width of every Mamba-2 block, as a multiple of its input width; it is split into heads. base_channels * expand must be divisible by encoder1_head_dim.

  • head_dim (int) – Channels per head of the differential bottleneck; divides bottleneck_channels.

  • cdse_hidden_dim (int) – Hidden width of the MLP of the CDSE.

  • branch_kernel_sizes (tuple[int, ...]) – Kernel size of each branch of the multi-branch embedding, as in the authors’ code. Odd, so that the padding of k // 2 keeps the steps.

  • pool_size (int) – Kernel size and stride of the three max-poolings: each divides the number of steps by pool_size, so n_times >= pool_size ** 3.

  • stage_kernel_size (int) – Kernel size of the two convolutions behind the first two poolings. Odd, so that the padding of k // 2 keeps the steps.

  • encoder1_head_dim (int) – Channels per head of the Mamba-2 of the first stage (headdim in the reference Mamba2). head_dim is that of the bottleneck.

  • chunk_size (int) – Steps per chunk of the Mamba-2 scan; bounds the size of its quadratic form.

  • dt_min (float) – Lower end of the log-uniform range of the initial step sizes of the Mamba-2 blocks.

  • dt_max (float) – Upper end of that range.

  • dt_init_floor (float) – Floor of the initial step sizes.

  • a_init_range (tuple[float, float]) – (low, high) of the uniform draw of the initial decay rates A of the Mamba-2 blocks (A_init_range in the reference Mamba2).

  • norm_eps (float) – Epsilon of the RMS norm that follows the gate of every Mamba-2 block.

  • channel_strategy (str) – How another montage reaches the encoder; see EEGModuleMixin. The model reads the montage of chs_info natively, so the default "native" is usually what you want.

  • channel_strategy_kwargs (dict | None) – Options of channel_strategy.

Raises:

ValueError – If some input signal-related parameters are not specified: and can not be inferred.

Notes

If some input signal-related parameters are not specified, there will be an attempt to infer them from the other parameters.

References

[samba]

Hong, J., Mackellar, G., Ghane, S. (2026). SAMBA: Toward an EEG Foundation Model via Differential Mamba and Coordinate-Driven Spatial Embedding. NeurReps 2026 (Proceedings Track). arXiv:2511.18571. https://github.com/Jiazhen-Hong/SAMBA

[mamba2]

Dao, T., Gu, A. (2024). Transformers are SSMs: Generalized Models and Efficient Algorithms Through Structured State Space Duality. ICML. arXiv:2405.21060.

Hugging Face Hub integration

When the optional huggingface_hub package is installed, all models automatically gain the ability to be pushed to and loaded from the Hugging Face Hub. Install with:

pip install braindecode[hub]

Pushing a model to the Hub:

from braindecode.models import SAMBA

# Train your model
model = SAMBA(n_chans=22, n_outputs=4, n_times=1000)
# ... training code ...

# Push to the Hub; ``datasets`` and ``base_model`` go to the card
model.push_to_hub(
    repo_id="username/my-samba-model",
    commit_message="Initial model upload",
    model_card_kwargs={"datasets": ["BNCI2014_001"]},
)

Loading a model from the Hub:

from braindecode.models import SAMBA

# Load pretrained model
model = SAMBA.from_pretrained("username/my-samba-model")
# Data the weights were trained on, from the Hub model card
print(model.card_data.datasets if model.card_data else None)

# Load with a different number of outputs (head is rebuilt automatically)
model = SAMBA.from_pretrained("username/my-samba-model", n_outputs=4)

Extracting features and replacing the head:

import torch

x = torch.randn(1, model.n_chans, model.n_times)
# Extract encoder features (consistent dict across all models)
out = model(x, return_features=True)
features = out["features"]

# Replace the classification head
model.reset_head(n_outputs=10)

Saving and restoring full configuration:

import json

config = model.get_config()            # all __init__ params
with open("config.json", "w") as f:
    json.dump(config, f)

model2 = SAMBA.from_config(config)    # reconstruct (no weights)

All model parameters (both EEG-specific and model-specific such as dropout rates, activation functions, number of filters) are automatically saved to the Hub and restored when loading.

See Loading and Adapting Pretrained Foundation Models for a complete tutorial.

Methods

forward(x, return_features=False)[source]#

Encode EEG windows and score them.

Parameters:
  • x (Tensor) – EEG of shape (batch, n_chans, n_times), in the channel order of chs_info, with n_times >= pool_size ** 3 (8 by default).

  • return_features (bool) – Return the features that final_layer reads instead of its outputs.

Returns:

Outputs of shape (batch, n_outputs). With return_features=True, {"features": Tensor, "cls_token": None} with the (batch, 2 * bottleneck_channels) input of final_layer.

Return type:

Tensor | dict[str, Tensor | None]

reset_head(n_outputs)[source]#

Replace final_layer by a new one with n_outputs outputs.

Parameters:

n_outputs (int) – New number of outputs.

Return type:

None

Examples

>>> from braindecode.models import BENDR
>>> model = BENDR(n_chans=22, n_times=1000, n_outputs=4)
>>> model.reset_head(10)
>>> model.n_outputs
10

Added in version 1.4.