Shuffle event training batches, and test the reader that landed without tests

SSC's training split is sorted by class -- 35 contiguous runs over 75,466
samples. The image path has always built its loader with shuffle=train;
event_batches read range(start, stop) in order and had no shuffle at all, so
every batch was a single class in class order and the network learned only
to name whichever class it was currently being shown. Held-out accuracy went
from 3.84% to 11.88% against 2.86% chance once the order was fixed.

No test could have caught it. The synthetic fixture labels samples
index % num_classes, so sixteen consecutive indices carry sixteen distinct
classes -- accidentally perfect interleaving, and the exact opposite of what
a real recording does. It took a real dataset to expose it, which is the
fourth time in this area that a fixture was better behaved than reality.

event_batches now takes shuffle and seed; the engine passes shuffle=train.
The default stays sequential, so the dashboard's demo pass is unchanged.

Also here: tests/test_hsd_reader.py, which belonged with the reader in
db0c338 and was left untracked when that commit swept the reader up under a
message about documentation links. The reader has had no tests in history
until now.

Its tripwire on tonic's arithmetic is gated on the promotion rule it depends
on. Asserting the multiply stays float16 only holds under NEP 50; NumPy 1.x
widens it to float32 and the timestamps survive, so on a legacy NumPy -- and
this project supports numpy>=1.26 -- the premise does not exist and the test
was failing for the wrong reason. It now skips there, naming the version,
and still fires on NumPy 2.

The SSC row is still not published. Three 3-epoch configurations reach
9-12%, all with loss barely under ln(35) = 3.555, so the stock defaults are
genuinely a poor fit for audio rather than still broken. Publishing that is
a judgement about what a catalog slot should mean, and separately the hub's
compatibility layer builds its comparison preset with no parameters, so it
rejects any checkpoint that is not 10-class.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: w4ffl35

CHANGELOG.md

@@ -13,6 +13,32 @@ that and describe the local source tree only.
 
 ### Added
 
+- **Heidelberg audio splits are read directly, bypassing tonic's decode.**
+  `spikeforge/events/hsd_reader.py` reads the SHD/SSC HDF5 itself and scales
+  seconds to microseconds in `float64`, which recovers every timestamp tonic
+  loses (see **Fixed**). It replaces exactly one thing — the per-sample decode.
+  Tonic still downloads the dataset, extracts it, owns the cache layout, and
+  supplies the sensor geometry; the reader is handed the constructed tonic
+  dataset and consults it for all of that. The emitted stream keeps tonic's own
+  `(t, x, p)` structured layout, so nothing downstream can tell the two paths
+  apart.
+
+  Routing is declared on the dataset, not hard-coded in the loader:
+  `DatasetSpec.native_reader` names the reader, and only `ssc` sets it — the
+  DVS datasets keep tonic's decode, which is correct for them. `h5py` arrives
+  with tonic itself and is imported defensively, so this module is to `h5py`
+  what `tonic_api` is to `tonic`: the only one that imports it.
+
+  Pinning `numpy<2` would also have worked and was rejected: a published number
+  whose reproduce command silently yields single-bin garbage on numpy 2 is not
+  reproducible. This fix is correct on any numpy, and
+  `tests/test_hsd_reader.py` asserts the broken promotion *is* still broken, so
+  the workaround cannot quietly outlive its reason.
+
+  It also opens the HDF5 once rather than per `__getitem__` as tonic does,
+  which is what lets the source's open-once caching actually pay off here:
+  0.50 ms/sample against 2.29 ms through tonic.
+
 - **Auditory event sensors load.** A cochlea has channels, not pixel rows:
   tonic's SHD and SSC declare `sensor_size = (700, 1, 1)` and their streams
   carry `(t, x, p)` with no `y` field at all, so `events_to_sample` raised
@@ -125,11 +151,33 @@ that and describe the local source tree only.
 
 ### Fixed
 
+- **Event training never shuffled, so a class-ordered dataset trained one class
+  per batch.** The image path builds its loader with `shuffle=train`; the event
+  path read `range(start, stop)` strictly in order and had no shuffle anywhere.
+  Real event datasets ship grouped by class — SSC's training split is exactly
+  **35 contiguous runs over 75,466 samples** — so every batch contained a
+  single class in class order, and the network learned only to name whichever
+  class it was currently being shown. Measured on SSC: **3.84%** unshuffled
+  against a 2.86% chance baseline on 35 classes, rising to **11.88%** once the
+  training split is visited in a seeded random order.
+
+  The synthetic fixture hid this completely. Its labels are
+  `index % num_classes`, so consecutive indices cycle through every class —
+  accidentally perfect interleaving, which is why no existing test caught it
+  and why it only surfaced against a real recording.
+
+  `event_batches` now takes `shuffle` and `seed`; the engine passes
+  `shuffle=train`, mirroring the image loader exactly, and the order is seeded
+  so a published row stays reproducible. The default is sequential, so the
+  dashboard and every existing caller are unchanged.
+
 - **Tonic destroys every SHD and SSC timestamp, and the pipeline would have
   trained on it silently.** The Heidelberg files store `spikes/times` as
   `float16`, whose maximum is 65504. Tonic's reader converts seconds to
-  microseconds with `times * 1e6`, which overflows float16 to `inf`, becomes
-  `NaN`, and casts to `INT64_MIN` — for **every timestamp in every sample**,
+  microseconds with `times * 1e6`; under NumPy 2's NEP 50 promotion that stays
+  in `float16`, where `1e6` itself does not fit — so the scale factor becomes
+  `inf`, every product is `inf` (or `NaN` where the timestamp is 0), and the
+  cast to `int64` yields `INT64_MIN` for **every timestamp in every sample**,
   in both SHD and SSC, on tonic 1.4.3. Our binning then saw a zero-width span
   and collapsed all events into the first time step: a spiking network trained
   on that has had all of its timing removed, and would still report a

documentation/event-datasets.md

@@ -158,11 +158,15 @@ of decoding a missing image.
   is still an error.
 - **🔴 SHD and SSC cannot currently be trained on.** The Heidelberg files
   store timestamps as `float16`, and tonic's reader scales them by `1e6` —
-  which overflows float16 to `inf`, then `NaN`, then `INT64_MIN` for every
-  timestamp in every sample. All timing is gone before the data reaches us.
-  `EventTimestampError` refuses such a stream rather than binning every event
-  into the first time step and reporting a number measured on it. Verified
-  against tonic 1.4.3 on both datasets; it needs an upstream fix.
+  which under NumPy 2 stays in `float16`, where `1e6` does not fit, so every
+  timestamp becomes `inf`/`NaN` and casts to `INT64_MIN`. All timing is gone
+  before the data reaches us. `EventTimestampError` refuses such a stream
+  rather than binning every event into the first time step and reporting a
+  number measured on it. **`ssc` routes around it**: the registry's
+  `native_reader` field sends it to `spikeforge.events.hsd_reader`, which
+  reads the HDF5 itself and scales in `float64`. Tonic still downloads the
+  dataset and still owns the cache layout; only the per-sample decode is
+  replaced, and only for the datasets tonic decodes wrongly.
 - **The DVS datasets cannot currently be downloaded.** `dvs128_gesture` and
   `cifar10_dvs` are served from figshare, which answers tonic's downloader
   with `HTTP 202` and an empty body (tonic then reports "File not found or

scripts/train_reference_models.py

@@ -169,7 +169,7 @@ def engine_kwargs(self) -> Dict[str, Any]:
         name="ssc-fc-legacy",
         dataset="ssc",
         topology="fc_legacy",
-        epochs=1,
+        epochs=3,
         num_steps=25,
         batch_size=128,
         # A cochlea has 700 channels and no second spatial axis, so the flat

spikeforge/data/event_errors.py

@@ -55,11 +55,12 @@ class EventTimestampError(ValueError):
     This is not hypothetical. Tonic's SHD/SSC reader scales the file's
     timestamps by ``1e6`` to convert seconds to microseconds, but the
     Heidelberg files store them as ``float16``, whose maximum is 65504 -- so
-    the multiply overflows to ``inf``, becomes ``NaN``, and every timestamp
-    in the sample casts to ``INT64_MIN``. Binning then sees a zero-width
-    time span and collapses every event into the first time step, which
-    trains and scores perfectly happily while having destroyed all timing.
-    A named failure is the only honest outcome.
+    under NumPy 2 the scale factor itself becomes ``inf`` and every product
+    is ``inf`` (or ``NaN`` where the timestamp is 0), which casts to
+    ``INT64_MIN``. Binning then sees a zero-width time span and collapses
+    every event into the first time step, which trains and scores perfectly
+    happily while having destroyed all timing. A named failure is the only
+    honest outcome. :mod:`spikeforge.events.hsd_reader` is the way around it.
     """
 
     def __init__(self, detail: str = "") -> None:
@@ -68,8 +69,8 @@ def __init__(self, detail: str = "") -> None:
             "event timestamps are negative, so they are not recording times "
             f"{detail}; this is what a non-finite timestamp cast to an "
             "integer looks like. Tonic's SHD/SSC reader produces it by "
-            "scaling float16 seconds by 1e6 (the multiply overflows to inf, "
-            "then NaN, then INT64_MIN), which would silently collapse every "
-            "event into one time bin. Refusing rather than reporting a "
-            "number measured on destroyed timing."
+            "scaling float16 seconds by 1e6, which does not fit in float16 "
+            "and so becomes inf, then INT64_MIN on cast; that would "
+            "silently collapse every event into one time bin. Refusing "
+            "rather than reporting a number measured on destroyed timing."
         )

spikeforge/events/hsd_reader.py

@@ -2,12 +2,14 @@
 
 Tonic downloads these datasets correctly and then decodes them wrongly. Its
 reader converts the file's timestamps from seconds to microseconds with
-``times * 1e6``, but the Heidelberg files store them as ``float16`` (maximum
-65504). Under NumPy 2's NEP 50 promotion a ``float16`` array times a Python
-float stays ``float16``, so the multiply overflows to ``inf``, becomes ``NaN``,
-and casts to ``INT64_MIN`` -- for every timestamp in every sample. Binning then
-sees a zero-width span and collapses the whole recording into one time step, so
-a 25-step spiking network trains on a single static frame and still reports a
+``times * 1e6``, but the Heidelberg files store them as ``float16``, whose
+maximum is 65504. Under NumPy 2's NEP 50 promotion a ``float16`` array times a
+Python float stays ``float16``, and ``1e6`` does not fit: the scale factor
+itself becomes ``inf``. Every product is then ``inf`` -- or ``NaN`` wherever
+the timestamp is exactly 0 -- and casting either to ``int64`` yields
+``INT64_MIN``, for every timestamp in every sample. Binning then sees a
+zero-width span and collapses the whole recording into one time step, so a
+25-step spiking network trains on a single static frame and still reports a
 plausible accuracy.
 
 So this module replaces that one conversion. It does **not** replace tonic:

spikeforge/training/event_batches.py

@@ -53,12 +53,34 @@ def batch_event_samples(
     return spikes, labels
 
 
+def visit_order(
+    total: int, shuffle: bool, seed: Optional[int] = None
+) -> List[int]:
+    """Return the sample indices one epoch visits, in visiting order.
+
+    Sequential unless ``shuffle``. Shuffling is not cosmetic here: real event
+    datasets arrive grouped by class -- SSC's training split is 35 contiguous
+    runs over 75,466 samples -- so reading them in order makes every batch a
+    single class and training collapses to predicting whichever class it is
+    currently being shown. ``seed`` makes the permutation reproducible, which a
+    published row needs.
+    """
+    if not shuffle:
+        return list(range(total))
+    generator = None
+    if seed is not None:
+        generator = torch.Generator().manual_seed(int(seed))
+    return [int(i) for i in torch.randperm(total, generator=generator)]
+
+
 def event_batches(
     source: EventSampleSource,
     spec: TopologySpec,
     subset: int,
     batch_size: int,
     samples: Optional[int] = None,
+    shuffle: bool = False,
+    seed: Optional[int] = None,
 ) -> List[Batch]:
     """Return the epoch's ``(spikes, labels)`` batches in bridge layout.
 
@@ -73,16 +95,19 @@ def event_batches(
     checkpoint claiming the full training split requires. ``subset`` is
     bypassed when ``samples`` is given, since the two would otherwise both be
     trying to set the same thing.
+
+    ``shuffle`` visits the samples in a seeded random order, which a training
+    epoch over a class-ordered dataset requires; see :func:`visit_order`. It
+    matches the image path, whose loader is built with ``shuffle=train``.
     """
     size = max(1, int(batch_size))
     total = (
         max(1, int(samples))
         if samples is not None
         else batch_count(subset) * size
     )
+    order = visit_order(total, shuffle, seed)
     return [
-        batch_event_samples(
-            source, spec, range(start, min(start + size, total))
-        )
+        batch_event_samples(source, spec, order[start:start + size])
         for start in range(0, total, size)
     ]

spikeforge/training/event_engine.py

@@ -130,11 +130,18 @@ def _epoch_batches(
         ``train`` selects which source is read. The two sources opened
         different dataset splits, so the batches are different data, not the
         same stream under a different name.
+
+        The training split is visited in a seeded random order and the
+        held-out split sequentially, exactly as the image path's loader is
+        built with ``shuffle=train``. That is load-bearing rather than tidy:
+        real event datasets ship grouped by class, so reading a training epoch
+        in order makes every batch a single class.
         """
         source = self._event_source if train else self._test_source
         return event_batches.event_batches(
             source, self._spec, self._subset, self._batch_size,
             self._epoch_samples if train else None,
+            shuffle=train, seed=self._seed,
         )
 
     def _load_test_batches(