braindecode 1.8.1.dev181847394__tar.gz → 1.8.1.dev183849953__tar.gz

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/NOTICE.txt

@@ -52,6 +52,7 @@ The following components are licensed under the Apache License 2.0:
 - `braindecode/models/zuna.py`
 - `braindecode/models/luna.py`
 - `braindecode/models/brant.py`
+- `braindecode/models/mscformer.py`
 
 ### USC Academic License Files
 

{braindecode-1.8.1.dev181847394/braindecode.egg-info → braindecode-1.8.1.dev183849953}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1.dev181847394
+Version: 1.8.1.dev183849953
 Summary: Deep learning software to decode EEG, ECG or MEG signals
 Author-email: Robin Tibor Schirrmeister <robintibor@gmail.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Alexandre Gramfort <agramfort@meta.com>
 Maintainer-email: Alexandre Gramfort <agramfort@meta.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Robin Tibor Schirrmeister <robintibor@gmail.com>

braindecode-1.8.1.dev183849953/braindecode/functional/_real_dft.py

@@ -0,0 +1,138 @@
+"""Real-valued DFT helpers for accelerators without complex tensors.
+
+Intel Gaudi (HPU) has no complex dtype, so ``torch.fft`` with complex outputs
+cannot run there. These helpers express the one-sided DFT, and the inverse
+transforms built on top of it, as matmuls against a cosine/sine basis. Under
+bfloat16 autocast those matmuls would run in bfloat16, whereas ``torch.fft`` is
+never downcast, so callers wrap the numerically sensitive parts with
+:func:`fp32_island`.
+"""
+
+# Authors: Bruno Aristimunha <b.aristimunha@gmail.com>
+#
+# License: BSD (3-clause)
+import functools
+
+import torch
+
+
+def needs_real_dft(x: torch.Tensor) -> bool:
+    """Whether ``x`` lives on a device without complex-tensor FFT support."""
+    return x.device.type == "hpu"
+
+
+def fp32_island(fn):
+    """Run ``fn`` with autocast disabled, in at least float32 precision.
+
+    Any bfloat16/float16 tensor argument is upcast to float32 before ``fn``
+    runs; float32 and float64 arguments are left untouched, so the same code
+    path can also be checked against a float64 ``torch.fft`` reference.
+    """
+
+    @functools.wraps(fn)
+    def wrapped(*args, **kwargs):
+        ref = next(a for a in args if isinstance(a, torch.Tensor))
+        with torch.autocast(device_type=ref.device.type, enabled=False):
+            args = tuple(
+                a.float()
+                if isinstance(a, torch.Tensor)
+                and a.is_floating_point()
+                and torch.finfo(a.dtype).bits < 32
+                else a
+                for a in args
+            )
+            return fn(*args, **kwargs)
+
+    return wrapped
+
+
+def real_dft_basis(n, *, device, dtype):
+    """One-sided cosine/sine basis of an ``n``-point DFT, shape ``(n // 2 + 1, n)``.
+
+    The phase index is reduced modulo ``n`` in integers before scaling, so the
+    DC row is exact (``sin`` is exactly zero there); the Nyquist row (present
+    for even ``n``) is exact to floating-point precision.
+    """
+    if n <= 0:
+        raise ValueError("n must be positive")
+    if (n // 2) * (n - 1) >= 2**31:
+        # The int32 phase index below would overflow and give wrong phases.
+        raise ValueError(f"n={n} exceeds the 65536 samples of the real-valued DFT")
+    freqs = torch.arange(n // 2 + 1, device=device, dtype=torch.int32)
+    samples = torch.arange(n, device=device, dtype=torch.int32)
+    phase_index = (freqs[:, None] * samples[None, :]) % n
+    angles = 2 * torch.pi * phase_index.to(dtype) / n
+    return angles.cos(), angles.sin()
+
+
+def real_rfft(x):
+    """Real and imaginary parts of ``torch.fft.rfft(x, dim=-1)`` without complex tensors."""
+    n = x.shape[-1]
+    cosine, sine = real_dft_basis(n, device=x.device, dtype=x.dtype)
+    return x @ cosine.transpose(0, 1), -(x @ sine.transpose(0, 1))
+
+
+def real_irfft(real, imag, *, n):
+    """``torch.fft.irfft(torch.complex(real, imag), n=n, dim=-1)`` without complex tensors."""
+    if real.shape[-1] != n // 2 + 1:
+        raise ValueError(
+            f"expected {n // 2 + 1} one-sided bins for n={n}, got {real.shape[-1]}"
+        )
+    cosine, sine = real_dft_basis(n, device=real.device, dtype=real.dtype)
+    output = real[..., :1] @ cosine[:1, :]
+    if n % 2 == 0:
+        interior = slice(1, -1)
+        output = output + real[..., -1:] @ cosine[-1:, :]
+    else:
+        interior = slice(1, None)
+    if real.shape[-1] > (2 if n % 2 == 0 else 1):
+        output = output + 2 * (
+            real[..., interior] @ cosine[interior, :]
+            - imag[..., interior] @ sine[interior, :]
+        )
+    return output / n
+
+
+def real_analytic_ifft(real, imag, *, n):
+    """Inverse ``n``-point FFT of a one-sided spectrum, without complex tensors.
+
+    ``real``/``imag`` hold the bins ``0 .. n // 2`` of a length-``n`` spectrum
+    whose remaining (negative-frequency) bins are zero, so this is a plain
+    (non-Hermitian) inverse DFT, not :func:`real_irfft`. Returns the real and
+    imaginary parts of the generally complex time-domain signal, each of shape
+    ``(..., n)``. This is the last step of :func:`hilbert_freq_real`.
+    """
+    if real.shape[-1] != n // 2 + 1:
+        raise ValueError(
+            f"expected {n // 2 + 1} one-sided bins for n={n}, got {real.shape[-1]}"
+        )
+    cosine, sine = real_dft_basis(n, device=real.device, dtype=real.dtype)
+    out_real = (real @ cosine - imag @ sine) / n
+    out_imag = (real @ sine + imag @ cosine) / n
+    return out_real, out_imag
+
+
+@torch.jit.unused
+def hilbert_freq_real(x: torch.Tensor, forward_fourier: bool) -> torch.Tensor:
+    """Real-valued equivalent of :func:`braindecode.functional.hilbert_freq`.
+
+    Lives here rather than in ``functions.py`` because ``torch.jit.unused`` needs
+    real annotations, and ``functions.py`` uses ``from __future__ import annotations``.
+    """
+
+    @fp32_island
+    def compute(x):
+        if forward_fourier:
+            seq_len = x.shape[-1]
+            real, imag = real_rfft(x)
+        else:
+            seq_len = 2 * (x.shape[-2] - 1)
+            real, imag = x[..., 0], x[..., 1]
+        scale = torch.full((real.shape[-1],), 2.0, dtype=real.dtype, device=real.device)
+        scale[0] = 1.0  # Don't multiply the DC-term by 2
+        if forward_fourier and seq_len % 2 == 0:
+            scale[-1] = 1.0  # Nor the Nyquist term, which only exists for even lengths
+        out_real, out_imag = real_analytic_ifft(real * scale, imag * scale, n=seq_len)
+        return torch.stack((out_real, out_imag), dim=-1)
+
+    return compute(x)

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/functional/functions.py

@@ -12,6 +12,8 @@ import numpy as np
 import torch
 import torch.nn.functional as F
 
+from . import _real_dft
+
 
 def square(x):
     return x * x
@@ -165,6 +167,9 @@ def hilbert_freq(x: torch.Tensor, forward_fourier: bool = True) -> torch.Tensor:
     https://github.com/scipy/scipy/blob/v1.14.1/scipy/signal/_signaltools.py#L2287-L2394
 
     """
+    if _real_dft.needs_real_dft(x):
+        return _real_dft.hilbert_freq_real(x, forward_fourier).to(x.dtype)
+
     input_dtype = x.dtype
     # ``view_as_complex`` does not accept bfloat16 real/imaginary pairs.  The
     # HPU path can produce bfloat16 Fourier coefficients under autocast, so do
@@ -175,12 +180,20 @@ def hilbert_freq(x: torch.Tensor, forward_fourier: bool = True) -> torch.Tensor:
         x = x.float()
 
     if forward_fourier:
+        seq_len = x.shape[-1]
         x = torch.fft.rfft(x, norm=None, dim=-1)
         x = torch.view_as_real(x)
+    else:
+        # The one-sided spectrum does not record whether the signal length
+        # was odd or even, so assume an even length here.
+        seq_len = 2 * (x.shape[-2] - 1)
     x = x * 2.0
     x[..., 0, :] = x[..., 0, :] / 2.0  # Don't multiply the DC-term by 2
+    if forward_fourier and seq_len % 2 == 0:
+        # Nor the Nyquist term, which only exists for even lengths
+        x[..., -1, :] = x[..., -1, :] / 2.0
     x = F.pad(
-        x, [0, 0, 0, x.shape[-2] - 2]
+        x, [0, 0, 0, seq_len - x.shape[-2]]
     )  # Fill Fourier coefficients to retain shape
     x = torch.view_as_complex(x)
     x = torch.fft.ifft(x, norm=None, dim=-1)  # returns complex signal

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/__init__.py

@@ -42,6 +42,7 @@ from .luna import LUNA
 from .medformer import MEDFormer
 from .meta_neuromotor import MetaNeuromotorHand
 from .mirepnet import MIRepNet
+from .mscformer import MSCFormer
 from .msvtnet import MSVTNet
 from .mvpformer import MVPFormer
 from .neuropose import NeuroPose
@@ -137,6 +138,7 @@ __all__ = [
     "positions_from_chs_info",
     "MEDFormer",
     "MIRepNet",
+    "MSCFormer",
     "MSVTNet",
     "MVPFormer",
     "PBT",

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/base.py

@@ -537,12 +537,31 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         if n_outputs <= 0:
             raise ValueError(f"n_outputs must be positive; got {n_outputs}.")
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
+
+    def _update_init_kwargs(self, **init_kwargs) -> None:
+        """Record constructor arguments that change after construction.
+
+        Helper for :meth:`reset_head` implementations that also change a
+        constructor argument, for example turning a feature extractor into a
+        classifier. Keeps the braindecode init kwargs and the Hugging Face hub
+        config in sync, so :meth:`get_config` and ``save_pretrained`` rebuild
+        the architecture the model actually has.
+
+        Parameters
+        ----------
+        **init_kwargs
+            Constructor argument names mapped to their new values.
+        """
         for config in (
             getattr(self, "_braindecode_init_kwargs", None),
             getattr(self, "_hub_mixin_config", None),
         ):
-            if config is not None and "n_outputs" in config:
-                config["n_outputs"] = n_outputs
+            if config is None:
+                continue
+            for name, value in init_kwargs.items():
+                if name in config:
+                    config[name] = value
 
     def reset_head(self, n_outputs):
         """Replace the classification head for a new number of outputs.
@@ -550,6 +569,10 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         This is called automatically by :meth:`from_pretrained` when the
         user passes an ``n_outputs`` that differs from the saved config.
         Override in subclasses that need a model-specific head structure.
+        Implementations keep changed constructor arguments in sync with
+        ``self._update_init_kwargs``, so that a saved model can be loaded
+        back. Implementations requiring positive outputs can also use
+        ``self._set_n_outputs`` to validate and record the new value.
 
         Parameters
         ----------

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/bendr.py

@@ -355,7 +355,9 @@ class BENDR(EEGModuleMixin, nn.Module):
 
     def reset_head(self, n_outputs):
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
         self.include_final_layer = True
+        self._update_init_kwargs(final_layer=True)
         self._build_head(n_outputs)
 
     def forward(self, x, return_features=False):

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/biot.py

@@ -237,6 +237,7 @@ class BIOT(EEGModuleMixin, nn.Module):
 
     def reset_head(self, n_outputs):
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
         self.final_layer = _ClassificationHead(
             emb_size=self.embed_dim,
             n_outputs=n_outputs,

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/cbramod.py

@@ -224,6 +224,9 @@ class CBraMod(EEGModuleMixin, nn.Module):
 
     def reset_head(self, n_outputs):
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
+        # A head implies a classifier, also when built with return_encoder_output.
+        self._update_init_kwargs(return_encoder_output=False)
         if self._n_times is not None and self._n_chans is not None:
             n_patch = self._n_times // self._patch_size
             flat_dim = self._n_chans * n_patch * self._emb_dim

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/eegdino.py

@@ -260,7 +260,9 @@ class EEGDINO(EEGModuleMixin, nn.Module):
         mirroring :meth:`braindecode.models.CBraMod.reset_head`.
         """
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
         self.return_encoder_output = False
+        self._update_init_kwargs(return_encoder_output=False)
         self.final_layer = self._make_head()
 
     def forward(self, x, return_features: bool | None = None):

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/eegpt.py

@@ -371,6 +371,7 @@ class EEGPT(EEGModuleMixin, nn.Module):
 
     def reset_head(self, n_outputs):
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
         self.final_layer = _LinearConstraintProbe(
             **self.get_probe_params(),
             n_outputs=n_outputs,

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/labram.py

@@ -823,6 +823,7 @@ class Labram(EEGModuleMixin, nn.Module):
 
     def reset_head(self, n_outputs):
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
         self.reset_classifier(n_outputs)
 
     def _adj_temporal_embedding(self, num_ch, batch_size, dim_embed=None):

{braindecode-1.8.1.dev181847394 → braindecode-1.8.1.dev183849953}/braindecode/models/meta_neuromotor.py

@@ -486,6 +486,7 @@ class MetaNeuromotorHand(EEGModuleMixin, nn.Module, license="cc-by-nc-4.0"):
         """Replace the classification head for a new number of outputs."""
         self.final_layer = nn.Linear(self.final_layer.in_features, n_outputs)
         self._n_outputs = n_outputs
+        self._update_init_kwargs(n_outputs=n_outputs)
 
     def compute_output_lengths(self, input_lengths: torch.Tensor) -> torch.Tensor:
         """Compute the valid emission length for each input sequence.