Add BaRISTA iEEG model - #1173

- Turn the MAPA_DKT_REGIONS string into Sphinx #: comments (the bare
  string failed check-docstring-first) and keep the api.rst entry on one
  line (docstrfmt).
- License header is Apache-2.0, matching the upstream code it transcribes.
- Changelog cites this PR (braindecode#1178), not braindecode#1173.
- Docstring: window normalization is one of two numerical departures from
  the reference (the per-window STFT with reflect padding is the other);
  normalization="none" feeds the raw STFT magnitude, not the reference's
  inputs; pooling="flatten" reads the normed four-tap concatenation, not
  the paper's pre-norm block-12 read-out.

Resolve models/__init__.py and docs/whats_new.rst conflicts against master's newly-merged MIRepNet (braindecode#1146) and BaRISTA (braindecode#1173): keep both registry entries, restore alphabetical import/__all__ order, keep both changelog entries.

* onboard MAPA

* fix: make MAPA pass pre-commit and correct its fidelity notes

- Turn the MAPA_DKT_REGIONS string into Sphinx #: comments (the bare
  string failed check-docstring-first) and keep the api.rst entry on one
  line (docstrfmt).
- License header is Apache-2.0, matching the upstream code it transcribes.
- Changelog cites this PR (#1178), not #1173.
- Docstring: window normalization is one of two numerical departures from
  the reference (the per-window STFT with reflect padding is the other);
  normalization="none" feeds the raw STFT magnitude, not the reference's
  inputs; pooling="flatten" reads the normed four-tap concatenation, not
  the paper's pre-norm block-12 read-out.

* enable single init and forward with different subjects

* MAPA: normalization='session' takes a session-normalized spectrogram

Co-authored-by: Cursor <[email protected]>

* allow to receive spectrogram bands directly

* fix: MAPA layout cache owns its indices; reuse functional.rotate_pairs

- _token_layout cached the caller's sensor-indices tensor by reference,
  so an in-place edit of that tensor compared equal to the cached copy and
  returned a stale layout. Store a clone; covered by
  test_mapa_metadata_cache_owns_its_snapshot.
- Replace the private _rotate_half with braindecode.functional.rotate_pairs,
  which master added for the shared rotary code (bitwise identical).
- Header: link the upstream repository next to the Apache-2.0 notice, as
  LUNA/ZUNA do.

* fix: MAPA.reset_head keeps get_config() in sync

Master's generic test_reset_head_updates_config /
test_reset_head_model_reloads_after_saving require every model with a
custom reset_head to call _update_init_kwargs, otherwise from_config and
from_pretrained rebuild the old head size.

* test: MAPA's released checkpoint reproduces the authors' features

A network-marked test downloads mapa_vits384.pt from the authors' Hub
repository at a pinned commit (sha256 equal to their GitHub release v0.1.0),
loads it with only the classification head missing, and compares the pooled
features of two deterministic raw windows, frontend included, with values
computed by the authors' code (bentang18/MAPA at bf2b49e).

* test: say where MAPA's checkpoint test fits its z-score and how to run it

The reference values fit the authors' robust z-score on each window, as
the default normalization="window" does; the docstring now says so and
notes that CI's unit-test jobs do not pass --run-network.

* refactor: trim MAPA docstrings and reuse braindecode blocks

Rewrite the class docstring in the layout of the other foundation models,
shorten the private helpers' docstrings, merge duplicated input checks, and
reuse rescale_parameter and FeedForwardBlock. FeedForwardBlock names its
layers 0-3, so a mapping renames the released checkpoint's mlp.fc1/fc2 keys
on load. Outputs and initialization are unchanged.

Co-authored-by: Cursor <[email protected]>

* MAINT simplify MAPA: inline constants, fold layout/parse/stft helpers, strict sfreq, fix reset_head device/dtype and rotary device

* MAINT move MAPA DKT region vocabulary into a shared models/util helper

* MAINT derive MAPA DKT region table from MNE's FreeSurfer LUT

util.dkt_region_slots() now derives the 74-slot DKT region table from
mne.read_freesurfer_lut() ids at call time instead of typing out the
parcel/structure names: the 62 cortical parcels come from excluding five
DK ids (unknown, corpuscallosum, bankssts, frontalpole, temporalpole)
out of the contiguous 1000-1035 block and sorting what remains
alphabetically per hemisphere; the 12 subcortical slots come from the
six aseg ids in 10-18 that have a bilateral Right- counterpart. The one
piece that cannot be derived from MNE -- the released slot order of
those six aseg structures, which is neither ascending-id nor
alphabetical order -- is kept as a tiny position permutation, not a
name list, documented as sourced from the released checkpoint. A test
freezes the exact previously-hard-coded 74-name tuple and asserts the
new helper reproduces it exactly.

---------

Co-authored-by: Bru <[email protected]>
Co-authored-by: Cursor <[email protected]>