augmentation: add BandRotation for surface-EMG wristband layouts - #1013

Per-band circular roll along the channel axis plus inter-band temporal
jitter, for inputs laid out as ``(B, num_bands * electrodes_per_band, T)``.
Models small wristband rotation between sessions and relative timing
noise between two arms; introduced in the emg2qwerty paper (Sivakumar
et al., NeurIPS 2024).

* New ``braindecode.augmentation.functional.band_rotation`` (low-level
  function on (X, y) tensors).
* New ``braindecode.augmentation.BandRotation`` Transform wrapping it
  for use with ``AugmentedDataLoader``.
* 4 functional unit tests (shape, seed reproducibility, no-op path,
  channel-count validation, circular-roll value preservation) plus a
  ``test_set_params`` parametrize entry to verify Skorch round-trip.
* Bench-checked: a vectorized ``torch.gather`` collapsing the per-band
  loop is ~16% slower for the typical num_bands=2 case on CPU (gather
  index tensor exceeds what two contiguous rolls touch); the loop only
  loses past num_bands>=8.  Loop kept with a comment recording the
  benchmark.

* Tighten the channel-count error message (drop redundant middle-term
  expansion).
* Compress the gather-benchmark comment from 7 lines to 3.
* Add a Transform-level seed-reproducibility test; the existing tests
  only covered the functional.
* Trim a few word-of-filler patterns from docstrings + changelog
  ("Originally introduced" → "Introduced", "additionally gets" →
  "also gets", "the underlying" → drop).

* Validate ``band_offsets`` is non-empty and ``max_temporal_jitter >= 0``
  with explicit ValueError messages, instead of letting numpy raise its
  less actionable internal errors.
* Clarify that the temporal jitter applies to band 1 only regardless of
  ``num_bands`` (functional + Transform docstrings).
* Note in the Transform docstring that one set of parameters applies to
  the whole transformed sub-batch — a property users typically expect to
  read at the Transform level, not the functional one.
* Add unit tests for the two new error paths plus a comment on the
  value-set comparison test cautioning against scaling it up.

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* Validate that ``band_offsets`` contains integers in
  ``BandRotation.__init__`` so misconfigurations fail at Transform
  construction time instead of on the first batch (matches the
  functional ``band_rotation`` check).
* Make ``test_band_rotation_circular_jitter_wraps_vs_zero_pads``
  conditional on the observed ``n_diff``: when the RNG happens to draw
  ``shift == 0`` both modes are no-ops, so we assert outputs equal ``X``
  and return; otherwise we keep the boundary-region invariants.  This
  decouples the test from the sampler's exact draw sequence.
* Replace the misleading "use a ``set``-based equality check" comment
  in ``test_band_rotation_circular_roll_preserves_values`` with a
  pointer to a multiset-aware alternative (``torch.unique(...,
  return_counts=True)`` / histograms) — sets silently drop duplicates
  and would miss value-multiplicity bugs.