pytesdaqx-scope 0.1.0__tar.gz

pytesdaqx_scope-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: pytesdaqx-scope
+Version: 0.1.0
+Summary: Live pulse viewer and dIdV scope for pytesdaqx
+Author: TESSERACT DAQ developers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pytesdaqx
+Requires-Dist: numpy<2.0,>=1.26
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: qetpy
+Requires-Dist: astropy
+Requires-Dist: PySide6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-qt; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# pytesdaqx-scope
+
+Live pulse viewer / dIdV scope for [pytesdaqx](../pytesdaqx), migrated and
+refactored from the pulse viewer in `pytesdaq-obsolete`.
+
+## A Qt styling gotcha worth knowing about
+
+A "bare declaration" stylesheet - `widget.setStyleSheet(f"background-color:
+{color};")` with no selector - silently breaks QComboBox popup styling for
+*any* descendant combobox, anywhere in that widget's subtree, even if the
+popup styling itself lives in a completely separate stylesheet (app-level or
+on the combobox directly). Reproduced with a minimal repro outside this
+codebase before fixing it here. Always use `theme.scoped_background(name,
+color)` / `theme.scoped_text_color(name, color)` (with
+`widget.setObjectName(name)` first) instead of a bare declaration - see
+`gui/theme.py` and its usages in `main_window.py`/`display_panel.py`/
+`tools_window.py`/`channel_panel.py` for the pattern.
+
+## Status
+
+Under active development. Current layout:
+
+```
+pytesdaqx_scope/
+  analysis/       Qt-free analysis pipeline (normalization, PSD, running
+                   average, pileup rejection, dIdV pole fitting)
+
+                   normalize() requires norm_list whenever norm_type != NoNorm
+                   was actually requested; it used to silently skip the
+                   volts-to-amps division when norm_list was missing (e.g. a
+                   failed board/file read) and fall straight through to the
+                   display unit's scale factor - producing a plausible but
+                   wrong number (raw volts read as if it were current,
+                   inflated further by uAmps' 1e6) instead of an error.
+                   Controller.process_frame() catches this (and any other
+                   per-frame analysis error) and reports it via on_status
+                   instead of letting it recur silently on every poll tick.
+
+                   didv_fit()'s data_array_truncated/fit_array add the
+                   trace's baseline back after qetpy's fit (which works on
+                   an AC-only, baseline-subtracted trace internally) -
+                   without this they were zero-centered, which only matched
+                   the *live* running-average trace (never baseline-
+                   subtracted) on the exact frame the fit ran on. Since the
+                   fit overlay is kept and redrawn on later frames too (see
+                   MainWindow._fit_overlay), the overlay would visibly drift
+                   away from the live trace's true DC level afterward.
+
+                   A completed dIdV fit now also pauses the display (like
+                   the old GUI): ControlPanel becomes a 3-state Start/Stop/
+                   Resume button (yellow while paused), the poll timer stops
+                   so the frame holding the fit result stays on screen for
+                   inspection/zooming, and clicking Resume drops the overlay
+                   and continues - without re-arming the data source, since
+                   pausing never told it to stop in the first place.
+  file_board_reader.py  FileBoardReader: BoardReader backed by a recording's
+                   stored per-channel settings (close_loop_norm, preamp_gain,
+                   signal-gen, TES bias) instead of a live board read - the
+                   file-replay equivalent of board_reader.py, wired into
+                   launcher.py's --file path. Without this, Amps/uAmps
+                   selection during file replay had no normalization source
+                   at all (NullBoardReader raised, but normalize()'s old
+                   silent-skip bug masked that as bad numbers rather than a
+                   visible error).
+  acquisition/     Data source adapters over pytesdaqx: LiveSource (NI-DAQ,
+                   via DAQSession/StreamingAcquisitionLoop) and FileSource
+                   (zarr/hdf5 replay, via StreamReader). Both produce a
+                   common Frame (raw ADC codes + calibration coefficients).
+
+                   read_frame() returning None is ambiguous by itself: for
+                   LiveSource it means "nothing new yet, poll again"; for
+                   FileSource it means "recording is over". FileSource
+                   exposes is_exhausted to disambiguate - MainWindow checks
+                   it after every poll and auto-stops with a clear status
+                   message instead of silently going quiet forever (which
+                   read exactly like a freeze). FileSource.start() rewinds
+                   automatically only when already exhausted, so Stop-then-
+                   Start still resumes mid-file rather than always
+                   restarting from the top.
+
+                   Both sources support an optional trace_length_ms knob
+                   (ControlPanel's "Trace Length [ms]" field), but only where
+                   it's physically meaningful: LiveSource.trace_length_supported()
+                   is true only for a continuous-mode measurement, since a
+                   finite/triggered one (dIdV, threshold) has a fixed record
+                   shape - a PXI-locked dIdV trace needs an integer number of
+                   signal-generator periods, which a plain "ms" knob could
+                   violate. FileSource.trace_length_supported() is true only
+                   for a native continuous Zarr stream (raw_shape_model ==
+                   "channel_sample"); HDF5 recordings and finite/trace Zarr
+                   streams have a fixed length baked into the file itself, so
+                   there's nothing to adjust. When supported, FileSource reads
+                   fixed-size partitions via read_partition() instead of
+                   read_next(); LiveSource folds it into adc.read_block_duration
+                   for the next start(). MainWindow re-checks support on every
+                   measurement change and disables the control accordingly.
+  gui/             PySide6 GUI shell: MainWindow composition root plus
+                   ControlPanel (measurement select + start/stop),
+                   ChannelPanel, DisplayPanel (waveform/PSD toggle,
+                   unit/norm controls, matplotlib canvas, dIdV fit overlay),
+                   ToolsPanel (running avg / LP filter / read-from-board /
+                   opens ToolsWindow), and ToolsWindow (dIdV pole-model fit
+                   + pileup-rejection cuts, in a separate top-level window
+                   like the old design). Widgets only emit signals; all
+                   wiring to the Controller lives in MainWindow.
+
+                   ChannelPanel is a vertical list (color swatch + checkbox)
+                   for the first 8 channels, with a "More Channels..."
+                   button opening a scrollable picker dialog for the rest
+                   (channel count isn't hardcoded to 24 - it's however many
+                   channels are passed in). Long names are middle-elided
+                   ("Mv6BandG...insRight", not right-elided, since detector
+                   names often differ only in a suffix) with the full name
+                   in a tooltip; a fixed-cell button grid (the old AI0-AI7
+                   style) doesn't work once names run 20+ characters.
+  controller.py    Qt-free orchestrator wiring a DataSource into the
+                   analysis pipeline. Board reads (normalization, signal
+                   generator, TES bias) go through a BoardReader Protocol,
+                   cached and refreshed only on explicit triggers (channel
+                   change / norm-type change / user action) since they can
+                   be slow.
+  board_reader.py  PytesdaqxBoardReader: concrete BoardReader over
+                   SQUIDService/TESBiasService. Supports "Open Loop" and
+                   "Close Loop" normalization only (OpenLoop PreAmp+FB was
+                   dropped - see module docstring); output_fix_gain/
+                   preamp_fix_gain are assumed 1.0 until pytesdaqx's config
+                   schema grows a place for them (StarCryo SQUID electronics).
+  launcher.py      CLI entry point: `pytesdaqx-scope --hardware ... --run-setup
+                   ... --acquisition-config ... [--backend nidaq|fake]` for
+                   live acquisition, or `pytesdaqx-scope --file <acquisition>`
+                   to replay a recorded zarr/hdf5 acquisition. Live vs. file
+                   is chosen once at launch (a CLI arg), not a runtime GUI
+                   toggle - a deliberate simplification now that the
+                   config-driven design resolves channels/measurements from
+                   YAML rather than a device combobox.
+
+                   For live acquisition, also builds a
+                   `pytesdaqx.control.coordinator.ControlCoordinator` (shared
+                   HardwareRegistry with the board reader) and passes it to
+                   `LiveSource`. `LiveSource` sequences a dIdV measurement's
+                   PXI AC drive correctly: arm the AI task first, *then*
+                   start the AO waveform, so the AI's `/ao/StartTrigger`
+                   defines phase zero. `start_measurement_tes_ac` is a no-op
+                   for measurements without a TES-AC waveform block, so this
+                   is always safe to wire up even for background/threshold
+                   runs.
+```
+
+Qt runs headless via `QT_QPA_PLATFORM=offscreen` in tests and in this
+(display-less) dev environment; `pytest-qt`'s `qtbot` fixture drives widget
+interaction in tests without a real display.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Try the GUI shell against the fake backend (no hardware required), using
+pytesdaqx's example configs:
+
+```bash
+QT_QPA_PLATFORM=offscreen pytesdaqx-scope \
+  --hardware ../pytesdaqx/examples/configuration/basic/hardware_fake.yaml \
+  --run-setup ../pytesdaqx/examples/configuration/basic/run_setup.yaml \
+  --acquisition-config ../pytesdaqx/examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+(Drop `QT_QPA_PLATFORM=offscreen` on a machine with a real display.)

pytesdaqx_scope-0.1.0/README.md

@@ -0,0 +1,171 @@
+# pytesdaqx-scope
+
+Live pulse viewer / dIdV scope for [pytesdaqx](../pytesdaqx), migrated and
+refactored from the pulse viewer in `pytesdaq-obsolete`.
+
+## A Qt styling gotcha worth knowing about
+
+A "bare declaration" stylesheet - `widget.setStyleSheet(f"background-color:
+{color};")` with no selector - silently breaks QComboBox popup styling for
+*any* descendant combobox, anywhere in that widget's subtree, even if the
+popup styling itself lives in a completely separate stylesheet (app-level or
+on the combobox directly). Reproduced with a minimal repro outside this
+codebase before fixing it here. Always use `theme.scoped_background(name,
+color)` / `theme.scoped_text_color(name, color)` (with
+`widget.setObjectName(name)` first) instead of a bare declaration - see
+`gui/theme.py` and its usages in `main_window.py`/`display_panel.py`/
+`tools_window.py`/`channel_panel.py` for the pattern.
+
+## Status
+
+Under active development. Current layout:
+
+```
+pytesdaqx_scope/
+  analysis/       Qt-free analysis pipeline (normalization, PSD, running
+                   average, pileup rejection, dIdV pole fitting)
+
+                   normalize() requires norm_list whenever norm_type != NoNorm
+                   was actually requested; it used to silently skip the
+                   volts-to-amps division when norm_list was missing (e.g. a
+                   failed board/file read) and fall straight through to the
+                   display unit's scale factor - producing a plausible but
+                   wrong number (raw volts read as if it were current,
+                   inflated further by uAmps' 1e6) instead of an error.
+                   Controller.process_frame() catches this (and any other
+                   per-frame analysis error) and reports it via on_status
+                   instead of letting it recur silently on every poll tick.
+
+                   didv_fit()'s data_array_truncated/fit_array add the
+                   trace's baseline back after qetpy's fit (which works on
+                   an AC-only, baseline-subtracted trace internally) -
+                   without this they were zero-centered, which only matched
+                   the *live* running-average trace (never baseline-
+                   subtracted) on the exact frame the fit ran on. Since the
+                   fit overlay is kept and redrawn on later frames too (see
+                   MainWindow._fit_overlay), the overlay would visibly drift
+                   away from the live trace's true DC level afterward.
+
+                   A completed dIdV fit now also pauses the display (like
+                   the old GUI): ControlPanel becomes a 3-state Start/Stop/
+                   Resume button (yellow while paused), the poll timer stops
+                   so the frame holding the fit result stays on screen for
+                   inspection/zooming, and clicking Resume drops the overlay
+                   and continues - without re-arming the data source, since
+                   pausing never told it to stop in the first place.
+  file_board_reader.py  FileBoardReader: BoardReader backed by a recording's
+                   stored per-channel settings (close_loop_norm, preamp_gain,
+                   signal-gen, TES bias) instead of a live board read - the
+                   file-replay equivalent of board_reader.py, wired into
+                   launcher.py's --file path. Without this, Amps/uAmps
+                   selection during file replay had no normalization source
+                   at all (NullBoardReader raised, but normalize()'s old
+                   silent-skip bug masked that as bad numbers rather than a
+                   visible error).
+  acquisition/     Data source adapters over pytesdaqx: LiveSource (NI-DAQ,
+                   via DAQSession/StreamingAcquisitionLoop) and FileSource
+                   (zarr/hdf5 replay, via StreamReader). Both produce a
+                   common Frame (raw ADC codes + calibration coefficients).
+
+                   read_frame() returning None is ambiguous by itself: for
+                   LiveSource it means "nothing new yet, poll again"; for
+                   FileSource it means "recording is over". FileSource
+                   exposes is_exhausted to disambiguate - MainWindow checks
+                   it after every poll and auto-stops with a clear status
+                   message instead of silently going quiet forever (which
+                   read exactly like a freeze). FileSource.start() rewinds
+                   automatically only when already exhausted, so Stop-then-
+                   Start still resumes mid-file rather than always
+                   restarting from the top.
+
+                   Both sources support an optional trace_length_ms knob
+                   (ControlPanel's "Trace Length [ms]" field), but only where
+                   it's physically meaningful: LiveSource.trace_length_supported()
+                   is true only for a continuous-mode measurement, since a
+                   finite/triggered one (dIdV, threshold) has a fixed record
+                   shape - a PXI-locked dIdV trace needs an integer number of
+                   signal-generator periods, which a plain "ms" knob could
+                   violate. FileSource.trace_length_supported() is true only
+                   for a native continuous Zarr stream (raw_shape_model ==
+                   "channel_sample"); HDF5 recordings and finite/trace Zarr
+                   streams have a fixed length baked into the file itself, so
+                   there's nothing to adjust. When supported, FileSource reads
+                   fixed-size partitions via read_partition() instead of
+                   read_next(); LiveSource folds it into adc.read_block_duration
+                   for the next start(). MainWindow re-checks support on every
+                   measurement change and disables the control accordingly.
+  gui/             PySide6 GUI shell: MainWindow composition root plus
+                   ControlPanel (measurement select + start/stop),
+                   ChannelPanel, DisplayPanel (waveform/PSD toggle,
+                   unit/norm controls, matplotlib canvas, dIdV fit overlay),
+                   ToolsPanel (running avg / LP filter / read-from-board /
+                   opens ToolsWindow), and ToolsWindow (dIdV pole-model fit
+                   + pileup-rejection cuts, in a separate top-level window
+                   like the old design). Widgets only emit signals; all
+                   wiring to the Controller lives in MainWindow.
+
+                   ChannelPanel is a vertical list (color swatch + checkbox)
+                   for the first 8 channels, with a "More Channels..."
+                   button opening a scrollable picker dialog for the rest
+                   (channel count isn't hardcoded to 24 - it's however many
+                   channels are passed in). Long names are middle-elided
+                   ("Mv6BandG...insRight", not right-elided, since detector
+                   names often differ only in a suffix) with the full name
+                   in a tooltip; a fixed-cell button grid (the old AI0-AI7
+                   style) doesn't work once names run 20+ characters.
+  controller.py    Qt-free orchestrator wiring a DataSource into the
+                   analysis pipeline. Board reads (normalization, signal
+                   generator, TES bias) go through a BoardReader Protocol,
+                   cached and refreshed only on explicit triggers (channel
+                   change / norm-type change / user action) since they can
+                   be slow.
+  board_reader.py  PytesdaqxBoardReader: concrete BoardReader over
+                   SQUIDService/TESBiasService. Supports "Open Loop" and
+                   "Close Loop" normalization only (OpenLoop PreAmp+FB was
+                   dropped - see module docstring); output_fix_gain/
+                   preamp_fix_gain are assumed 1.0 until pytesdaqx's config
+                   schema grows a place for them (StarCryo SQUID electronics).
+  launcher.py      CLI entry point: `pytesdaqx-scope --hardware ... --run-setup
+                   ... --acquisition-config ... [--backend nidaq|fake]` for
+                   live acquisition, or `pytesdaqx-scope --file <acquisition>`
+                   to replay a recorded zarr/hdf5 acquisition. Live vs. file
+                   is chosen once at launch (a CLI arg), not a runtime GUI
+                   toggle - a deliberate simplification now that the
+                   config-driven design resolves channels/measurements from
+                   YAML rather than a device combobox.
+
+                   For live acquisition, also builds a
+                   `pytesdaqx.control.coordinator.ControlCoordinator` (shared
+                   HardwareRegistry with the board reader) and passes it to
+                   `LiveSource`. `LiveSource` sequences a dIdV measurement's
+                   PXI AC drive correctly: arm the AI task first, *then*
+                   start the AO waveform, so the AI's `/ao/StartTrigger`
+                   defines phase zero. `start_measurement_tes_ac` is a no-op
+                   for measurements without a TES-AC waveform block, so this
+                   is always safe to wire up even for background/threshold
+                   runs.
+```
+
+Qt runs headless via `QT_QPA_PLATFORM=offscreen` in tests and in this
+(display-less) dev environment; `pytest-qt`'s `qtbot` fixture drives widget
+interaction in tests without a real display.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Try the GUI shell against the fake backend (no hardware required), using
+pytesdaqx's example configs:
+
+```bash
+QT_QPA_PLATFORM=offscreen pytesdaqx-scope \
+  --hardware ../pytesdaqx/examples/configuration/basic/hardware_fake.yaml \
+  --run-setup ../pytesdaqx/examples/configuration/basic/run_setup.yaml \
+  --acquisition-config ../pytesdaqx/examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+(Drop `QT_QPA_PLATFORM=offscreen` on a machine with a real display.)

pytesdaqx_scope-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytesdaqx-scope"
+version = "0.1.0"
+description = "Live pulse viewer and dIdV scope for pytesdaqx"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+authors = [
+  {name = "TESSERACT DAQ developers"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "pytesdaqx",
+  "numpy>=1.26,<2.0",
+  "scipy",
+  "matplotlib",
+  "qetpy",
+  "astropy",
+  "PySide6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-qt",
+  "ruff",
+]
+
+[project.scripts]
+pytesdaqx-scope = "pytesdaqx_scope.launcher:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pytesdaqx_scope*"]
+
+[tool.setuptools.package-data]
+pytesdaqx_scope = ["gui/assets/*.png"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E9", "F", "I"]

pytesdaqx_scope-0.1.0/pytesdaqx_scope/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pytesdaqx_scope-0.1.0/pytesdaqx_scope/acquisition/__init__.py

@@ -0,0 +1,5 @@
+from .base import DataSource, Frame
+from .file_source import FileSource
+from .live_source import LiveSource
+
+__all__ = ["DataSource", "Frame", "FileSource", "LiveSource"]

pytesdaqx_scope-0.1.0/pytesdaqx_scope/acquisition/base.py

@@ -0,0 +1,56 @@
+"""Common data-source interface shared by live acquisition and file replay.
+
+Both :class:`~pytesdaqx_scope.acquisition.live_source.LiveSource` and
+:class:`~pytesdaqx_scope.acquisition.file_source.FileSource` produce
+:class:`Frame` objects, so the controller and analysis pipeline never need
+to know which one produced a given frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+import numpy as np
+
+
+@dataclass
+class Frame:
+    """One event/read-block of raw ADC-code traces, ready for analysis.
+
+    ``data`` is always in raw ADC codes (never pre-calibrated), so
+    :meth:`pytesdaqx_scope.analysis.pipeline.AnalysisPipeline.process` can
+    treat live and file-replay frames identically via ``calibration_coeffs``.
+    """
+
+    data: np.ndarray  # [nb_channels, nb_samples]
+    detector_channels: list[str]
+    sample_rate_hz: float
+    measurement: str
+    calibration_coeffs: list[list[float] | None] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class DataSource(Protocol):
+    """Common interface for live and file-replay data sources."""
+
+    def start(self, measurement: str, *, overrides: dict[str, Any] | None = None) -> None:
+        """Begin producing frames for the given measurement."""
+        ...
+
+    def read_frame(self, timeout: float | None = 0.0) -> Frame | None:
+        """Return the next available frame.
+
+        ``None`` means "nothing available right now" for a live source
+        (safe to poll again later) or "exhausted" for a file source
+        (nothing more will ever come).
+        """
+        ...
+
+    def stop(self) -> None:
+        """Stop producing frames; safe to call again with :meth:`start`."""
+        ...
+
+    def close(self) -> None:
+        """Release underlying resources; the source cannot be reused after this."""
+        ...

pytesdaqx_scope-0.1.0/pytesdaqx_scope/acquisition/file_source.py

@@ -0,0 +1,170 @@
+"""File-replay data source over pytesdaqx's StreamReader (zarr/hdf5)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pytesdaqx.io import StreamReader
+
+from .base import Frame
+
+
+class FileSource:
+    """Steps sequentially through a recorded acquisition, one record at a time.
+
+    Wraps :class:`pytesdaqx.io.StreamReader`, always requesting raw ADC
+    codes (``units="adc"``) so calibration flows through
+    :mod:`pytesdaqx_scope.analysis` the same way as for
+    :class:`~pytesdaqx_scope.acquisition.live_source.LiveSource` frames.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        streams: str | int | list[str | int] | None = None,
+        measurement_types: str | list[str] | None = None,
+        channels: list[str] | None = None,
+    ) -> None:
+        self._reader = StreamReader(
+            path,
+            streams=streams,
+            measurement_types=measurement_types,
+            restricted="all",
+        )
+        self._channels = channels
+        self._exhausted = False
+        #: Samples per read when in partition mode; None means "use the
+        #: file's own read-block/trace boundaries via read_next()" (default).
+        self._partition_length_samples: int | None = None
+        self._partition_cursor = 0
+
+    @property
+    def is_exhausted(self) -> bool:
+        """True once :meth:`read_frame` has hit the end of the recording.
+
+        ``read_frame`` returning ``None`` is ambiguous on its own - for
+        :class:`~pytesdaqx_scope.acquisition.live_source.LiveSource` it just
+        means "nothing new yet, poll again"; for a file it means "nothing
+        more will ever come". Callers (e.g. the GUI's poll loop) should check
+        this after a ``None`` read to tell the two apart, rather than
+        silently polling forever with no feedback.
+        """
+        return self._exhausted
+
+    def peek_metadata(self) -> dict[str, Any]:
+        """Static resource metadata (detector_channels, measurement, ...).
+
+        Uses a separate, throwaway reader under the hood, so calling this
+        does not disturb :meth:`read_frame`'s sequential position.
+        """
+        return self._reader.get_metadata()
+
+    def trace_length_supported(self, measurement: str | None = None) -> bool:
+        """Whether :meth:`set_trace_length_ms` has any effect on this file.
+
+        Only true for a native continuous Zarr stream (``raw_shape_model ==
+        "channel_sample"``): HDF5 recordings and finite/trace Zarr streams
+        (dIdV, threshold) have a fixed record length baked into the file
+        itself, so there is nothing to adjust. ``measurement`` is accepted
+        (and ignored) only so callers can treat this and
+        ``LiveSource.trace_length_supported`` the same way - a single file
+        source is fixed to whichever stream(s) it was opened with.
+        """
+        del measurement
+        return self._reader.raw_shape_model == "channel_sample"
+
+    def set_trace_length_ms(self, trace_length_ms: float | None) -> None:
+        """Set the partition length read per :meth:`read_frame` call, in ms.
+
+        Only meaningful when :meth:`trace_length_supported` is true;
+        otherwise this is a no-op. ``None`` reverts to the file's own
+        read-block boundaries (:meth:`read_next`). Resets the partition
+        read position to the start.
+        """
+        if not self.trace_length_supported():
+            return
+        if trace_length_ms is None:
+            self._partition_length_samples = None
+        else:
+            samples = round(trace_length_ms * 1e-3 * self._reader.sample_rate_hz)
+            self._partition_length_samples = max(1, samples)
+        self._partition_cursor = 0
+
+    def get_detector_settings(self) -> dict[str, dict[str, Any]]:
+        """Per-channel stored settings: close_loop_norm, preamp_gain,
+        signal_gen_current/frequency, tes_bias, etc. - used by
+        :class:`~pytesdaqx_scope.file_board_reader.FileBoardReader` in place
+        of a live board read. Like :meth:`peek_metadata`, this doesn't
+        disturb :meth:`read_frame`'s sequential position.
+        """
+        return self._reader.get_detector_settings()
+
+    def start(self, measurement: str, *, overrides: dict[str, Any] | None = None) -> None:
+        # File replay has no separate "arm" step; read_frame() drives the
+        # reader. Stop-then-Start resumes from the current position (pause/
+        # resume), but Start after running off the end has nothing to resume
+        # from, so it means "replay from the top" instead.
+        del measurement, overrides
+        if self._exhausted:
+            self.rewind()
+
+    def read_frame(self, timeout: float | None = 0.0) -> Frame | None:
+        del timeout  # file reads are effectively instantaneous
+        if self._partition_length_samples is not None:
+            return self._read_partition_frame()
+
+        try:
+            data, info = self._reader.read_next(channels=self._channels, units="adc")
+        except StopIteration:
+            self._exhausted = True
+            return None
+        return self._frame_from_read(data, info)
+
+    def _read_partition_frame(self) -> Frame | None:
+        try:
+            data, info = self._reader.read_partition(
+                partition_start_index=self._partition_cursor,
+                partition_length_samples=self._partition_length_samples,
+                channels=self._channels,
+                units="adc",
+            )
+        except ValueError:
+            # read_partition() raises when a request runs past the end of
+            # the stream, rather than the StopIteration read_next() uses -
+            # both mean the same thing here: nothing more to read.
+            self._exhausted = True
+            return None
+        self._partition_cursor += self._partition_length_samples
+        return self._frame_from_read(data, info)
+
+    def _frame_from_read(self, data, info: dict[str, Any]) -> Frame:
+        detector_channels = list(info.get("detector_channels") or [])
+        calibration_by_name = {
+            row["detector_channel"]: row.get("adc_conversion_coefficients")
+            for row in info.get("channel_map") or []
+            if "detector_channel" in row
+        }
+        calibration_coeffs = [calibration_by_name.get(name) for name in detector_channels]
+
+        return Frame(
+            data=data,
+            detector_channels=detector_channels,
+            sample_rate_hz=float(info.get("sample_rate_hz") or self._reader.sample_rate_hz),
+            measurement=str(info.get("measurement") or info.get("measurement_type") or ""),
+            calibration_coeffs=calibration_coeffs,
+            metadata=info,
+        )
+
+    def rewind(self) -> None:
+        self._reader.rewind()
+        self._exhausted = False
+        self._partition_cursor = 0
+
+    def stop(self) -> None:
+        # Nothing to stop mid-stream; rewind() is the explicit reset.
+        pass
+
+    def close(self) -> None:
+        self._reader.close()