Real-Time Performance
A realtime pipeline has two budgets. Latency is how long a sample takes to come out the other end; load is whether every frame is processed before the next one arrives. Most of the latency is chosen rather than suffered: the frame size, the event margin, OSCAR and your own filters each add a known amount. What was measured on each amplifier, on Windows, macOS and Linux, is on Benchmarks.
What real-time means in g.Pype
A live source emits a frame of a few samples as soon as it is full, every node runs once per frame on the source’s thread, an event is placed on the sample whose period contained the instant it arrived, and a pipeline that could only produce a wrong answer is refused before it starts. That is what is guaranteed by construction, and Benchmarks is what was measured.
What is not guaranteed: this is soft real time on a general-purpose operating system and a Python interpreter. No deadline is enforced by the system; a pipeline that cannot keep up is stopped and says so rather than left to fall behind. A device’s own latency, Bluetooth, USB or a driver’s buffer, is not subtracted from a stamp, which marks the instant a block reached the host. And a scope redraws at its own rate on the GUI thread, so what you see lags what was computed by up to one refresh.
Where latency comes from
Frames. A block leaves a source only once its frame is full, so a frame’s
length is latency every sample pays. A Generator, a BCI Core or a
Unicorn picks a frame of about 16 ms of signal unless told otherwise:
Sampling rate |
Default frame |
Frame length |
|---|---|---|
125 Hz |
2 samples |
16 ms |
250 Hz |
4 samples |
16 ms |
1000 Hz |
16 samples |
16 ms |
4800 Hz |
64 samples |
13.3 ms |
The GDS amplifiers take their driver’s choice instead: a g.Nautilus sends each
sample on its own, a frame of 1 (4 ms at 250 Hz), and a g.HIamp or a g.USBamp
the size the device recommends for its rate. frame_size= on the source
changes it. A smaller frame lowers latency and raises the overhead per sample,
because every node runs once per frame. A device may also limit it: a
g.Nautilus accepts only 1, or the size it recommends for the rate – 8 at
250 Hz, 15 at 500 Hz.
Processing is rarely the part that matters: a bandpass filter’s worst cycle at 250 Hz was 0.4 ms.
The event margin. Nodes that place events on a signal hold every frame back
by 40 ms, so a late event still finds its sample
(Time and Synchronisation). A marker emitted into a
Router came out after 51.8 ms, the median of 20 – the margin plus part
of a frame. p.event_margin_ms lowers it, down to 0, at the cost of more
events placed late.
OSCAR, g.tec’s artifact removal. enable_oscar=True on an amplifier adds
OSCAR’s own delay, which the source reports as oscar_delay_samples once
start() has run:
83 samples, 332 ms, on a g.Nautilus at 250 Hz. It is None before the start
and on an amplifier without OSCAR. With OSCAR on, the event margin drops to 0,
since OSCAR’s delay already gives events time to arrive.
Your own filters. A moving average of N samples lags by about half its
window; a Decimator’s default anti-alias filter delayed the alpha power
of Season 2 by
400 ms. Filters with phase="zero" have no delay at all, but only offline
(Offline Processing).
Load
p.get_load() reports, as a dict, how much of the time the pipeline spends
working. Each call covers the time since the previous one, and the first after
start() includes the setup, so discard it:
p.start()
p.get_load() # includes the setup: discard
time.sleep(5)
load = p.get_load() # the last five seconds
print(load["headroom"], load["busiest"], load["short_of_headroom"])
for node in load["nodes"]:
print(node["name"], node["worst_cycle_ms"])
headroom is 1.0 when idle and 0.0 when saturated; busiest names the
node doing the most; short_of_headroom lists every node over
Pipeline.LOAD_WARNING_DUTY, 0.70 – deliberately below 1.0, so the warning
comes before frames are late. The rows also list the nodes the pipeline builds
around each source, such as the Sync that places its samples on the master
timeline. On a laptop, one bandpass at 250 Hz left a headroom of 0.975;
256 channels at 1000 Hz through twelve bandpass filters left 0.877.
For a deadline, compare each node’s worst_cycle_ms with the frame length: at
250 Hz in frames of 4 a frame is 16 ms, so a worst cycle near that is already
late, however comfortable the average. Season 6, Episode 3 reads
a report line by line.
The clock
Every stamp is read from time.perf_counter(): 100 ns steps on Windows, and
41.7 ns on the Mac it was measured on. That was not always so. g.Pype once
stamped from time.monotonic(), which on Windows with Python 3.10 to 3.12 ticks
only every 15.6 ms – nearly four samples at 250 Hz. perf_counter has no such
limit on any supported Python, and if a machine’s clock were ever coarser than a
sample period, start() would log a warning naming its resolution.
Measured
What was measured on each amplifier, on Windows, macOS and Linux, is on Latency and Performance Benchmarks: how far markers scatter, how many triggers land on their own sample, how evenly frames arrive, how true each clock runs, how fast a lost device is reported, and how two machines agree, every number defined.