Burst acquisition: many whole rows per FastFrame acquisition

Per-row acquisition pays a full arm/stop/transfer round trip for every row,
and the transfer is one IEEE-488.2 block read per frame (~16k frames a row).
Burst mode runs one FastFrame acquisition across as many complete rows as the
scope's frame memory holds and pulls each burst in a single CURVe?
transaction, amortising the round trip over the whole burst.

It is opt-in (ScanEngine(burst_mode=...), default False) and writes
byte-identical files to the per-row path — test_burst_and_serial_produce_
identical_files runs the same plan both ways and compares the bytes, which is
the property the whole feature rests on.

core/scope_burst.py — the new policy module. Everything that computes rather
than talks to hardware is a free function, so sizing and row-splitting are
testable without a rig: rows_per_burst() (rounds down, since a partial row
can't be written, and clamps to a transfer-buffer budget), split_row_counts(),
normalize_row(), frame_means_block().

The hard part is that a burst carries no row markers — the scope returns one
flat run of frames. Boundaries come from ACQuire:NUMFRAMESACQuired? sampled
after each acquiring pass while the stage gate is already low, rebased on a
baseline read back at RUN rather than assuming the counter resets. A counter
that goes backwards means the acquisition restarted mid-burst and is now a
hard error instead of silently misattributing every later row.

core/scan_engine.py — the row loop splits into _scan_rows_serial and
_scan_rows_burst. The wire is channel-major and the file is row-major with
channels inner, so _write_burst deinterleaves by writing one channel at a
time to strided offsets; peak memory stays at a single channel's burst
instead of the whole thing.

_gate_off_preflight is what makes this trustworthy on real hardware. The BBD
value that idles the trigger output low is not settled by the protocol docs
(see TRIGOUT_GATE_OFF), and getting it wrong fills every burst with flyback
frames that silently shift the file. The scope already measures the gate on
CH3, so the check needs no bench probe: one gated-off flyback must acquire
nothing, and one gated pass must acquire something — the second half is what
stops a dark laser from making the first half pass vacuously. It runs once
per scan and costs two row-times.

Two fixes fall out of this work and apply to both paths:
- Rows are now squared up to the declared n_frames (short rows zero-padded,
  long rows truncated, both warned). v6 commits to n_frames per row in the
  header and has no per-row length field, so an over- or under-triggered row
  used to shift every later row in the file.
- The X trigger output is returned to idle in the run() finally block. The
  per-row path left TRIGOUT_MAXV armed for the rest of the session, so the
  gate line kept being driven on every later jog.

core/scope_sras.py — pins DATa:ENCdg RIBinary and DATa:WIDth 1 during setup
instead of inheriting front-panel state. The file header hardcodes
bytes_per_sample=1; a scope left on 2 bytes would have corrupted every frame
written. frames_acquired/frame_means move to scope_burst, where the offset-
based variants serve both paths.

tests/fakes.py — FakeStage and FakeScope are now wired together the way the
rig is: a gated X move at scan velocity feeds frames into a running
acquisition at the real 20 kHz / 100 mm/s rate, direction-agnostic. Both
paths therefore derive frame counts from one model, which is what makes the
byte-identity comparison meaningful, and a gate the engine forgets to drop
shows up as extra frames instead of passing silently. Frame content is a
function of (channel, index) alone, so the same frame sequence yields the
same bytes however it is chopped into transfers.

87 tests passing, ruff clean.

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

core/scope_burst.py

@@ -0,0 +1,149 @@
+"""Burst-mode FastFrame acquisition policy.
+
+Per-row acquisition pays a full arm/stop/transfer round trip for every row,
+and the transfer alone is one IEEE-488.2 block read per frame (~16k frames a
+row).  A burst instead runs one FastFrame acquisition across as many complete
+rows as the scope's frame memory holds, then pulls the whole thing in a single
+transaction — amortising the round trip over `rows_per_burst` rows.
+
+The scope reports its capacity with ``HORizontal:FASTframe:MAXFRames?`` once
+the horizontal settings are fixed; ``rows_per_burst`` turns that into a row
+count.  Everything here that computes rather than talks to hardware is a free
+function, so the row-splitting logic is testable without a rig.
+
+The catch is that the burst contains no row markers: the scope hands back one
+flat run of frames.  Boundaries come from polling ``ACQuire:NUMFRAMESACQuired?``
+after each row's acquiring pass, while the stage gate is already low — see
+``split_row_counts``.
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# Peak transfer buffer, per channel.  The writer holds one channel at a time
+# (see ScanEngine._scan_rows_burst), so this is the real high-water mark.
+BURST_MEMORY_BUDGET_BYTES = 512 * 1024 * 1024
+
+# Extra frames budgeted per row on top of n_frames.  0 gives the plain
+# floor(max_frames / n_frames) row count; raise it if the acquiring pass
+# routinely over-triggers (watch the pad/truncate warnings).
+BURST_FRAME_HEADROOM = 0
+
+BURST_ARM_SETTLE_S = 0.05   # after ACQuire:STATE RUN, before the first move
+BURST_ROW_SETTLE_S = 0.05   # after the gate drops, before reading the counter
+
+
+# ── Pure helpers ─────────────────────────────────────────────────────────────
+
+def rows_per_burst(max_frames: int, n_frames: int, samples_per_frame: int,
+                   rows_remaining: int,
+                   memory_budget: int = BURST_MEMORY_BUDGET_BYTES,
+                   headroom: int = BURST_FRAME_HEADROOM) -> int:
+    """How many complete rows fit in one acquisition.
+
+    Rounds down — a partial row is worthless, since a row must be transferred
+    whole to be written.  Clamped by the transfer buffer budget and by the rows
+    actually left in the angle, and never below 1 (a single row always goes,
+    even if it exceeds the budget, so the scan can still make progress).
+    """
+    if n_frames < 1 or samples_per_frame < 1:
+        raise ValueError(f"n_frames={n_frames} samples_per_frame={samples_per_frame}")
+
+    by_scope = max_frames // (n_frames + headroom)
+    by_memory = memory_budget // (n_frames * samples_per_frame)
+    return max(1, min(by_scope, by_memory, rows_remaining))
+
+
+def split_row_counts(cumulative: list[int]) -> list[int]:
+    """Per-row frame counts from the cumulative counter sampled after each row.
+
+    ``cumulative`` is ``ACQuire:NUMFRAMESACQuired?`` read once per row, already
+    rebased on the value at burst start.
+    """
+    counts = []
+    prev = 0
+    for i, c in enumerate(cumulative):
+        if c < prev:
+            raise RuntimeError(
+                f"FastFrame counter went backwards at row {i} ({prev} → {c}) — "
+                "the acquisition was restarted mid-burst"
+            )
+        counts.append(c - prev)
+        prev = c
+    return counts
+
+
+def normalize_row(buf, offset: int, count: int, n_frames: int,
+                  samples_per_frame: int):
+    """Coerce one row's frames to exactly ``n_frames``.
+
+    The v6 format commits to n_frames per row in the header and has no per-row
+    length field, so a row that over- or under-triggers must be squared up or
+    every later row in the file shifts.  Short rows are zero-padded, long rows
+    lose their trailing frames.  Returns something writable directly.
+    """
+    want = n_frames * samples_per_frame
+    end = min(offset + count * samples_per_frame, offset + want, len(buf))
+    chunk = memoryview(buf)[offset:end]
+    if len(chunk) == want:
+        return chunk
+    return bytes(chunk) + bytes(want - len(chunk))
+
+
+def frame_means_block(buf, offset: int, n_frames: int,
+                      samples_per_frame: int) -> list[float]:
+    """Per-frame DC mean over one row's slice of a burst buffer."""
+    n = n_frames * samples_per_frame
+    block = np.frombuffer(buf, dtype=np.int8, count=n, offset=offset)
+    return block.reshape(n_frames, samples_per_frame).mean(
+        axis=1, dtype=np.float32).tolist()
+
+
+# ── Instrument control ───────────────────────────────────────────────────────
+
+def max_frames(scope) -> int:
+    """Frames the scope can hold under the current horizontal settings."""
+    try:
+        m = scope.get_fastframe_max_frames()
+    except Exception as exc:
+        raise RuntimeError(
+            "Scope did not answer HORizontal:FASTframe:MAXFRames? — burst mode "
+            "cannot size a burst without it.  Use per-row acquisition on this "
+            f"firmware. ({exc})"
+        ) from exc
+    if m < 1:
+        raise RuntimeError(f"Scope reports a FastFrame capacity of {m} frames")
+    return m
+
+
+def start_burst(scope, frame_count: int) -> int:
+    """Arm one burst; returns the counter baseline to subtract from later reads.
+
+    Reading the baseline back beats assuming the counter resets to 0 on RUN —
+    any residual is simply subtracted out instead of being misattributed to the
+    first row.
+    """
+    scope.set_fastframe_count(frame_count)
+    scope.write("ACQuire:STATE RUN")
+    time.sleep(BURST_ARM_SETTLE_S)
+    return frames_acquired(scope)
+
+
+def stop_burst(scope) -> None:
+    time.sleep(BURST_ROW_SETTLE_S)
+    scope.write("ACQuire:STATE STOP")
+
+
+def frames_acquired(scope) -> int:
+    return int(scope.query("ACQuire:NUMFRAMESACQuired?"))
+
+
+def transfer_burst(scope, ch: int, frame_count: int, samples_per_frame: int):
+    """Pull a whole burst for one channel in a single CURVe? transaction."""
+    scope.set_data_source(ch)
+    return scope.transfer_fastframe_bulk(frame_count, samples_per_frame)