Adding ZUNA to Braindecode - #1020

…ntions

ZUNA worked CUDA-only because flex_attention is unstable for autograd on
CPU; this collapses the whole API onto SDPA and trims the inference
port to a maintainable size.

Model (braindecode/models/zuna.py, 861 -> 400 lines):
- Drop flex_attention path, BlockMask, _create_document_mask, packed
  multi-document layout, and the use_flex / attention_impl plumbing.
  SDPA per-batch is mathematically equivalent (each sample is its own
  document) and supports CPU + fp16 + autograd.
- Replace custom _RMSNorm with torch.nn.RMSNorm.
- Drop _ZUNAEncoderArgs dataclass, _build_zuna_encoder_args validation,
  InitStdFactor enum, and the six zero-arg config helpers in favour of
  module constants plus one patchable _encoder_config().
- Drop unused dataclass knobs: init_base_std, init_std_factor,
  encoder_hidden_dim, n_kv_heads, ffn_dim_multiplier, multiple_of,
  dropout_type / dropout_vec, encoder_latent_downsample_factor,
  tok_idx_type.
- Drop _apply_channel_mask + dropped_channels API (caller-side concern).
- Drop _discretize_channel_positions string extremes_type; inline the
  constant ZUNA_POS_HALF_RANGE = 0.12.
- Drop _repeat_kv / GQA plumbing (never used: n_kv_heads always equals
  n_heads in the published config).
- Cache positions from chs_info at construction; resolve once.
- Replace 4-lookup + cat RoPE gather with one indexed read + flatten.
- Bucket positions in fp32 so fp16 inference doesn't shift bucket edges.
- Distinguish 'no coords' vs 'names without montage' errors.
- Split forward shape validation so ndim / n_chans / n_times mismatches
  get targeted messages.

Param count matches Zyphra/ZUNA published checkpoint exactly
(172,069,668 params for n_chans=22, n_outputs=4).

Tests (test/unit_tests/models/test_models.py, 290 -> 151 lines):
- Drop _zuna_forward inference_mode wrapper - no longer needed.
- Drop @pytest.mark.skipif(not zuna.HAS_FLEX) on every test.
- Drop redundant channel_mask / dropped_channels tests with the API.
- Drop _zuna_published_config snapshot test (superseded by inline
  constants).
- Parametrize n_times rejection over (1279, 1281).
- Add test_zuna_requires_montage_when_names_only.
- Drop CUDA-only skips in test_integration.py for ZUNA.

…ndecode style

Follow the BrainOmni/REVE convention where every architecture knob is a
documented __init__ argument instead of frozen module constants.

- ZUNA.__init__ now takes dim, n_layers, n_heads, head_dim, fine_time_pts,
  latent_dim, max_seqlen, rope_theta, rope_dim, pos_bins, pos_half_range,
  norm_eps, drop_prob and activation (defaults reproduce the published
  Zyphra/ZUNA config); drop the _encoder_config() indirection.
- Remove the ZUNA_* module constants; values are now literal defaults.
- Apache-2.0 header (upstream is Apache-2.0, not BSD-3) + adaptation credit.
- Ship a torch>=2.0-compatible _RMSNorm (nn.RMSNorm needs torch>=2.4).
- reset_head keeps get_config()/hub config in sync.
- Tests configure a small model via constructor kwargs; un-skip the
  activation/drop_prob/export checks; fix stale flex_attention comments.

The changelog-check CI was red: a new user-visible model needs a
whats_new entry and ZUNA had none. Add the entry plus the missing
'Jon Huml' contributor link target.

Re-host the upstream Zyphra/ZUNA encoder checkpoint at braindecode/ZUNA
(a bit-identical mirror, apache-2.0) so the library has a stable, permanent
location instead of depending on the third-party repo.

- ZUNA.from_pretrained now defaults pretrained_model_name_or_path to
  'braindecode/ZUNA' (weights normalised to the standard model.safetensors,
  so no filename argument is needed)
- Only the encoder is pretrained; the classification head stays randomly
  initialised and must be fine-tuned (documented)
- Add TestZUNAPretrained to the pretrained-hub integration suite
- Update the changelog entry

Avoids the signature divergence from the parent from_pretrained (Codacy /
pylint arguments-differ) while keeping identical behaviour: with no path
given, it defaults to the braindecode/ZUNA re-host; any explicit repo id or
local path (positional or keyword) is passed straight through.

- Collapse duplicate window/shape validations into single checks,
  keeping the error messages the tests pin.
- Replace the manual _repeat_kv expand+reshape with SDPA's native
  enable_gqa (torch>=2.5 needed only for GQA configs; the published
  ZUNA1.1 config has n_kv_heads == n_heads and is unaffected).
- Compress reset_head config sync into a loop and shorten comments.

Replace raw view/reshape/transpose/repeat_interleave chains with named
einops rearrange/repeat patterns (head split/merge, register-token
interleave, 4D RoPE table gather, patch tokenisation), and use the
einops Rearrange layer instead of nn.Flatten in final_layer, matching
the rest of the model zoo. No parameter or state-dict key changes.

Model:
- Reject rope_dim != 4 at construction instead of crashing in forward.
- Drop partial/non-finite chs_info positions so forward falls back to
  channel_names instead of silently corrupting RoPE buckets.
- Guard torch.compiler.is_compiling behind a helper (torch 2.0 floor).
- Forward **kwargs and raise when no upstream key matches in
  load_state_dict; remove the dead _apply_upstream_config machinery.
- RMSNorm casts to the weight dtype so model.half() works.
- Bound the tok_idx cache and key it by montage source.
- Replace the matrix rotary table with native torch.polar /
  view_as_complex (numerics verified identical).
- Inline the module-level constants into the code that uses them.

Tests: move the ZUNA block from test_models.py into a dedicated
test_zuna.py, dropping signature/import tautologies covered by the
shared parametrized suites, and add coverage for the fixes above.

…to zuna