Add architecture-only model card

README.md

@@ -0,0 +1,230 @@
+---
+license: bsd-3-clause
+library_name: braindecode
+pipeline_tag: feature-extraction
+tags:
+  - eeg
+  - biosignal
+  - pytorch
+  - neuroscience
+  - braindecode
+  - foundation-model
+  - convolutional
+---
+
+# LUNA
+
+LUNA from Döner et al .
+
+> **Architecture-only repository.** This repo documents the
+> `braindecode.models.LUNA` class. **No pretrained weights are
+> distributed here** — instantiate the model and train it on your own
+> data, or fine-tune from a published foundation-model checkpoint
+> separately.
+
+## Quick start
+
+```bash
+pip install braindecode
+```
+
+```python
+from braindecode.models import LUNA
+
+model = LUNA(
+    n_chans=22,
+    sfreq=250,
+    input_window_seconds=4.0,
+    n_outputs=4,
+)
+```
+
+The signal-shape arguments above are example defaults — adjust them
+to match your recording.
+
+## Documentation
+
+- Full API reference (parameters, references, architecture figure):
+  <https://braindecode.org/stable/generated/braindecode.models.LUNA.html>
+- Interactive browser with live instantiation:
+  <https://huggingface.co/spaces/braindecode/model-explorer>
+- Source on GitHub: <https://github.com/braindecode/braindecode/blob/master/braindecode/models/luna.py#L30>
+
+## Architecture description
+
+The block below is the rendered class docstring (parameters,
+references, architecture figure where available).
+
+<div class='bd-doc'><main>
+<p>LUNA from Döner et al [LUNA]_.</p>
+<span style="display:inline-block;padding:2px 8px;border-radius:4px;background:#5cb85c;color:white;font-size:11px;font-weight:600;margin-right:4px;">Convolution</span>  <span style="display:inline-block;padding:2px 8px;border-radius:4px;background:#d9534f;color:white;font-size:11px;font-weight:600;margin-right:4px;">Foundation Model</span>
+
+:bdg-dark-line:`Channel`
+
+   .. figure:: https://arxiv.org/html/2510.22257v1/x1.png
+       :align: center
+       :alt: LUNA Architecture.
+
+   LUNA is a topology-invariant EEG model that processes signals from varying
+   numbers of channels using a channel-unification mechanism with learned queries.
+
+   The architecture consists of:
+   1. Patch Feature Extraction (temporal CNN + FFT-based features)
+   2. Channel-Unification Module (cross-attention with learned queries)
+   3. Patch-wise Temporal Encoder (RoPE-based transformer)
+   4. Decoder Heads (classification or reconstruction)
+
+   .. important::
+      **Pre-trained Weights Available**
+
+      This model has pre-trained weights available on the Hugging Face Hub
+      at `PulpBio/LUNA <https://huggingface.co/PulpBio/LUNA>`_.
+
+      Available model variants:
+
+      - **LUNA_base.safetensors** - Base model (embed_dim=64, num_queries=4, depth=8)
+      - **LUNA_large.safetensors** - Large model (embed_dim=96, num_queries=6, depth=10)
+      - **LUNA_huge.safetensors** - Huge model (embed_dim=128, num_queries=8, depth=24)
+
+      Example loading for fine-tuning:
+
+      .. code:: python
+          from braindecode.models import LUNA
+
+          # Load pre-trained base model from Hugging Face Hub
+          model = LUNA.from_pretrained(
+              "PulpBio/LUNA",
+              filename="LUNA_base.safetensors",
+              n_outputs=2,
+              n_chans=22,
+              n_times=1000,
+              embed_dim=64,
+              num_queries=4,
+              depth=8,
+          )
+
+      To push your own trained model to the Hub:
+
+      .. code:: python
+          # After training your model
+          model.push_to_hub(
+              repo_id="username/my-luna-model", commit_message="Upload trained LUNA model"
+          )
+
+      Requires installing ``braindecode[hug]`` for Hub integration.
+
+   Parameters
+   ----------
+   patch_size : int
+       Number of time samples per patch. Default: 40.
+   num_queries : int
+       Number of learned queries for channel unification.
+       Paper uses: 4 (Base), 6 (Large), 8 (Huge). Default: 4.
+   embed_dim : int
+       Embedding dimension for patch features.
+       Paper uses: 64 (Base), 96 (Large), 128 (Huge). Default: 64.
+   depth : int
+       Number of transformer encoder blocks.
+       Paper uses: 8 (Base), 10 (Large), 24 (Huge). Default: 8.
+   num_heads : int
+       Number of attention heads in channel unification.
+       Default: 2.
+   mlp_ratio : float
+       Ratio of MLP hidden dimension to embedding dimension. Default: 4.0.
+   norm_layer : nn.Module
+       Normalization layer class. Default: nn.LayerNorm.
+   drop_path : float
+       Stochastic depth rate. Default: 0.0.
+
+   References
+   ----------
+   .. [LUNA] Döner, B., Ingolfsson, T. M., Benini, L., & Li, Y. (2025).
+       LUNA: Efficient and Topology-Agnostic Foundation Model for EEG Signal Analysis.
+       The Thirty-Ninth Annual Conference on Neural Information Processing Systems - NeurIPS.
+       Retrieved from https://openreview.net/forum?id=uazfjnFL0G
+
+   .. rubric:: 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:**
+
+   .. code::
+       from braindecode.models import LUNA
+
+       # Train your model
+       model = LUNA(n_chans=22, n_outputs=4, n_times=1000)
+       # ... training code ...
+
+       # Push to the Hub
+       model.push_to_hub(
+           repo_id="username/my-luna-model",
+           commit_message="Initial model upload",
+       )
+
+   **Loading a model from the Hub:**
+
+   .. code::
+       from braindecode.models import LUNA
+
+       # Load pretrained model
+       model = LUNA.from_pretrained("username/my-luna-model")
+
+       # Load with a different number of outputs (head is rebuilt automatically)
+       model = LUNA.from_pretrained("username/my-luna-model", n_outputs=4)
+
+   **Extracting features and replacing the head:**
+
+   .. code::
+       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:**
+
+   .. code::
+       import json
+
+       config = model.get_config()            # all __init__ params
+       with open("config.json", "w") as f:
+           json.dump(config, f)
+
+       model2 = LUNA.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 :ref:`load-pretrained-models` for a complete tutorial.</main>
+</div>
+
+## Citation
+
+Please cite both the original paper for this architecture (see the
+*References* section above) and braindecode:
+
+```bibtex
+@article{aristimunha2025braindecode,
+  title   = {Braindecode: a deep learning library for raw electrophysiological data},
+  author  = {Aristimunha, Bruno and others},
+  journal = {Zenodo},
+  year    = {2025},
+  doi     = {10.5281/zenodo.17699192},
+}
+```
+
+## License
+
+BSD-3-Clause for the model code (matching braindecode).
+Pretraining-derived weights, if you fine-tune from a checkpoint,
+inherit the licence of that checkpoint and its training corpus.