pytesscope 0.2.1__py3-none-any.whl

pytesscope/__init__.py

@@ -0,0 +1,10 @@
+"""Live pulse viewer and dIdV scope for pytesdaqx."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pytesscope")
+except PackageNotFoundError:  # Source tree imported before installation.
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

pytesscope/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"]

pytesscope/acquisition/base.py

@@ -0,0 +1,71 @@
+"""Common data-source interface shared by live acquisition and file replay.
+
+Both :class:`~pytesscope.acquisition.live_source.LiveSource` and
+:class:`~pytesscope.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:`pytesscope.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,
+        active_channels: list[str] | None = None,
+    ) -> None:
+        """Begin producing frames for the given measurement.
+
+        ``active_channels``, when given, scopes any step-level hardware
+        control (notably a dIdV measurement's TES AC drive) to just those
+        detector channels rather than every channel configured in
+        run_setup.yaml - e.g. so only the channel(s) selected in the GUI's
+        channel panel actually get their AC waveform turned on. ``None``
+        means "every run channel", matching the underlying pytesdaqx
+        default.
+        """
+        ...
+
+    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."""
+        ...

pytesscope/acquisition/file_source.py

@@ -0,0 +1,180 @@
+"""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:`pytesscope.analysis` the same way as for
+    :class:`~pytesscope.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:`~pytesscope.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:`~pytesscope.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,
+        active_channels: list[str] | 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. active_channels
+        # is a live-acquisition concept (which channels get hardware control
+        # applied, e.g. dIdV AC drive) - meaningless for a recording that
+        # already exists, so it's accepted only for DataSource protocol
+        # compatibility.
+        del measurement, overrides, active_channels
+        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()

pytesscope/acquisition/live_source.py

@@ -0,0 +1,379 @@
+"""Live data source over pytesdaqx's DAQSession, with dIdV/PXI AC-drive sequencing."""
+
+from __future__ import annotations
+
+import queue
+import threading
+from typing import Any
+
+from pytesdaqx.acquisition.segment import Segment
+from pytesdaqx.acquisition.session import DAQSession
+from pytesdaqx.config.durations import parse_duration
+
+from .base import Frame
+
+try:
+    # nidaqmx is only actually installed on a machine with real NI hardware
+    # (pytesdaqx itself imports it lazily for the same reason - see
+    # NIDAQAIBackend); this module has to tolerate its absence too, since
+    # LiveSource is exercised against FakeAcquisitionBackend in tests/dev.
+    from nidaqmx.error_codes import DAQmxErrors
+
+    _SAMPLES_NOT_YET_AVAILABLE = DAQmxErrors.SAMPLES_NOT_YET_AVAILABLE
+except ImportError:
+    _SAMPLES_NOT_YET_AVAILABLE = None
+
+
+class LiveSource:
+    """Drives one measurement's live acquisition on a background thread.
+
+    A GUI polls :meth:`read_frame` (e.g. from a ``QTimer``) instead of
+    blocking its event loop; frames are dropped (not queued indefinitely)
+    if the consumer falls behind, matching a live-scope's "show the latest
+    trace" semantics rather than a recorder's "keep everything."
+
+    A dIdV measurement whose TES AC drive lives on a PXI AO device needs a
+    specific sequence (per pytesdaqx's ``ControlCoordinator`` docs): arm the
+    AI task *first*, then start the AO waveform, so the AI's
+    ``/ao/StartTrigger`` defines phase zero. Passing a ``control_coordinator``
+    gets this ordering; ``ControlCoordinator.start_measurement_tes_ac`` is
+    itself a no-op for measurements with no TES-AC waveform block, so it's
+    always safe to pass one even when most selected measurements are plain
+    background/threshold acquisitions.
+    """
+
+    def __init__(
+        self,
+        resolved_config: Any,
+        *,
+        backend: Any = None,
+        detector_channels: list[str] | None = None,
+        max_buffered_frames: int = 2,
+        control_coordinator: Any = None,
+    ) -> None:
+        self._session = DAQSession.from_resolved_config(
+            resolved_config, backend=backend, detector_channels=detector_channels
+        )
+        self._coordinator = control_coordinator
+        self._frame_queue: queue.Queue[Frame] = queue.Queue(maxsize=max_buffered_frames)
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._trace_length_ms: float | None = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    def trace_length_supported(self, measurement: str) -> bool:
+        """Whether :meth:`set_trace_length_ms` has any effect for this measurement.
+
+        Only true for a continuous-mode measurement. A finite/triggered
+        measurement (dIdV, threshold) has physical constraints on its trace
+        length - a PXI-locked dIdV trace needs an integer number of
+        signal-generator periods - that a plain "trace length in ms"
+        control could violate, so those stay fixed to whatever
+        acquisition.yaml specifies.
+        """
+        adc_cfg = (self._session.measurements.get(measurement, {}) or {}).get("adc", {}) or {}
+        mode = str(adc_cfg.get("mode", "continuous")).strip().lower()
+        return mode == "continuous"
+
+    def set_trace_length_ms(self, trace_length_ms: float | None) -> None:
+        """Override the read_block_duration used the next time :meth:`start` runs.
+
+        Only takes effect for a measurement where
+        :meth:`trace_length_supported` is true; silently has no effect
+        otherwise (rather than erroring, since the GUI already disables the
+        control in that case - this just guards against stale state).
+        """
+        self._trace_length_ms = trace_length_ms
+
+    def start(
+        self,
+        measurement: str,
+        *,
+        overrides: dict[str, Any] | None = None,
+        active_channels: list[str] | None = None,
+    ) -> None:
+        if self.is_running:
+            raise RuntimeError("LiveSource is already running; call stop() first")
+
+        effective_overrides = dict(overrides or {})
+        if self._trace_length_ms is not None and self.trace_length_supported(measurement):
+            adc_overrides = dict(effective_overrides.get("adc", {}))
+            adc_overrides.setdefault("read_block_duration", self._trace_length_ms * 1e-3)
+            effective_overrides["adc"] = adc_overrides
+
+        effective_overrides = self._expand_trace_periods(measurement, effective_overrides)
+
+        # Must be read before _force_continuous_pxi_ac rewrites adc.mode to
+        # "continuous" below - by then this measurement is indistinguishable
+        # from a plain continuous one, so discard-count has to be resolved
+        # against the pre-rewrite (declared) mode.
+        discard_initial_segments = self._discard_initial_segments(measurement, effective_overrides)
+
+        if self._uses_pxi_locked_ac(measurement, effective_overrides):
+            effective_overrides = self._force_continuous_pxi_ac(measurement, effective_overrides)
+
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            args=(measurement, effective_overrides, discard_initial_segments, active_channels),
+            daemon=True,
+        )
+        self._thread.start()
+
+    def _expand_trace_periods(self, measurement: str, overrides: dict[str, Any]) -> dict[str, Any]:
+        """Expand ``adc.trace_periods`` into a literal ``adc.trace_duration``.
+
+        NIDAQAIBackend only understands a literal trace_duration/n_samples
+        (see :meth:`trace_length_supported`'s docstring) - unlike a
+        pytesdaqx-run acquisition.yaml, nothing expands ``trace_periods``
+        before it reaches ``DAQSession.configure_measurement()`` here, so an
+        acquisition.yaml author would otherwise have to hand-compute
+        periods/frequency_hz themselves. A PXI-locked dIdV trace must hold
+        an exact whole number of waveform periods, hence the integer
+        requirement (matches pytesdaqx-run's own validation).
+        """
+        base_adc = dict((self._session.measurements.get(measurement, {}) or {}).get("adc", {}) or {})
+        override_adc = dict(overrides.get("adc", {}) or {})
+        merged_adc = {**base_adc, **override_adc}
+
+        periods = merged_adc.get("trace_periods")
+        if periods is None:
+            return overrides
+        if any(key in merged_adc for key in ("trace_duration", "samples_per_trace", "n_samples")):
+            # An explicit duration/sample-count already given wins;
+            # trace_periods is only a convenience when nothing more
+            # specific was provided.
+            return overrides
+
+        try:
+            periods_int = int(periods)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"measurement {measurement!r}: adc.trace_periods must be a positive integer "
+                f"(PXI phase-locked dIdV needs a whole number of waveform periods per trace); "
+                f"got {periods!r}. Use e.g. trace_periods: 2 or 4."
+            ) from exc
+        if periods_int != periods or periods_int <= 0:
+            raise ValueError(
+                f"measurement {measurement!r}: adc.trace_periods must be a positive integer; "
+                f"got {periods!r}. Use e.g. trace_periods: 2 or 4."
+            )
+
+        base_waveform = dict((self._session.measurements.get(measurement, {}) or {}).get("waveform", {}) or {})
+        override_waveform = dict(overrides.get("waveform", {}) or {})
+        frequency_hz = {**base_waveform, **override_waveform}.get("frequency_hz")
+        if not frequency_hz:
+            raise ValueError(
+                f"measurement {measurement!r}: adc.trace_periods requires waveform.frequency_hz "
+                "to compute a trace duration"
+            )
+
+        new_overrides = dict(overrides)
+        new_adc_overrides = dict(new_overrides.get("adc", {}))
+        new_adc_overrides["trace_duration"] = periods_int / float(frequency_hz)
+        new_overrides["adc"] = new_adc_overrides
+        return new_overrides
+
+    def _merged_adc(self, measurement: str, overrides: dict[str, Any] | None) -> dict[str, Any]:
+        base_adc = dict((self._session.measurements.get(measurement, {}) or {}).get("adc", {}) or {})
+        override_adc = dict((overrides or {}).get("adc", {}) or {})
+        return {**base_adc, **override_adc}
+
+    def _uses_pxi_locked_ac(self, measurement: str, overrides: dict[str, Any] | None) -> bool:
+        """Whether this is a PXI phase-locked TES-AC (dIdV-style) measurement
+        that should run as one continuous, never-rearmed AI task rather than
+        a genuinely one-shot finite DAQmx task.
+
+        Matches pytesdaqx's own "preferred, phase-locked, exact-period dIdV
+        path" (see the pxi_loopback example set): for TES AC drive with no
+        explicit hardware trigger, pytesdaqx-run keeps one continuous AI task
+        running for the whole measurement and slices fixed-length,
+        whole-period reads from it, rather than physically retriggering a
+        finite task per trace. `type: didv`/`mode: finite` is the
+        schema-correct way to *declare* this measurement's data as
+        trace-shaped, but literally executing it as a true DAQmx finite task
+        per read (what this class used to do) means recreating the AO
+        square-wave task on every read to keep it phase-locked - slow/racy
+        enough that some traces get captured before the newly restarted AO
+        output has actually begun, i.e. exactly "on for some traces, off for
+        others" instead of a clean, consistent square wave.
+        """
+        adc_cfg = self._merged_adc(measurement, overrides)
+        mode = str(adc_cfg.get("mode", "continuous")).strip().lower()
+        if mode != "finite":
+            return False
+        if adc_cfg.get("trigger"):
+            return False  # a genuine hardware trigger still needs a real retrigger per read
+        measurement_cfg = self._session.measurements.get(measurement, {}) or {}
+        override_waveform = (overrides or {}).get("waveform")
+        return bool(measurement_cfg.get("waveform")) or bool(override_waveform)
+
+    def _force_continuous_pxi_ac(self, measurement: str, overrides: dict[str, Any]) -> dict[str, Any]:
+        """Override adc.mode to continuous and translate the configured
+        trace length into read_block_duration, for a measurement
+        :meth:`_uses_pxi_locked_ac` selected.
+
+        The AC waveform then only needs to start once (see :meth:`_run`),
+        exactly like the already-working plain continuous/background path -
+        one continuous, PXI-reference-clock-coherent AI task, read repeatedly
+        without ever closing/reconfiguring it.
+        """
+        adc_cfg = self._merged_adc(measurement, overrides)
+        duration = adc_cfg.get("trace_duration", adc_cfg.get("read_block_duration", adc_cfg.get("segment_duration")))
+        parsed = parse_duration(duration) if duration is not None else None
+        if not isinstance(parsed, (int, float)):
+            # No literal duration to translate (e.g. only samples_per_trace
+            # was given, or duration is a pytesdaqx sentinel like "auto") -
+            # leave mode/rearm behavior alone rather than guess.
+            return overrides
+
+        new_overrides = dict(overrides)
+        new_adc_overrides = dict(new_overrides.get("adc", {}))
+        new_adc_overrides["mode"] = "continuous"
+        new_adc_overrides["read_block_duration"] = float(parsed)
+        new_overrides["adc"] = new_adc_overrides
+        return new_overrides
+
+    def _discard_initial_segments(self, measurement: str, overrides: dict[str, Any] | None) -> int:
+        """How many segments to silently drop right after starting a PXI
+        phase-locked AC measurement, before the first one reaches the GUI.
+
+        Matches pytesdaqx-run's own default (``discard_initial_segments: 1``,
+        see ``yaml_run.py``'s ``_run_pxi_phase_locked_stream``): the
+        PXIe-4322's AO task regenerates its waveform buffer starting from
+        whatever DC value was held before the wave task started, so the very
+        first segment after :meth:`start_measurement_tes_ac` can capture that
+        transition rather than a clean, settled period of the square wave -
+        a real hardware characteristic of the AO's regenerative buffer, not
+        a software startup race, so it doesn't go away by tightening
+        sequencing. Configurable via ``adc.discard_initial_segments`` or
+        ``waveform.discard_initial_segments``, like pytesdaqx-run.
+        """
+        if not self._uses_pxi_locked_ac(measurement, overrides):
+            return 0
+        adc_cfg = self._merged_adc(measurement, overrides)
+        base_waveform = dict((self._session.measurements.get(measurement, {}) or {}).get("waveform", {}) or {})
+        override_waveform = dict((overrides or {}).get("waveform", {}) or {})
+        waveform_cfg = {**base_waveform, **override_waveform}
+
+        value = adc_cfg.get("discard_initial_segments", waveform_cfg.get("discard_initial_segments", 1))
+        return max(0, int(value))
+
+    def _rearm_each_segment(self, measurement: str, overrides: dict[str, Any] | None) -> bool:
+        """Whether the DAQmx task must be closed and reconfigured before
+        every read, not just the first.
+
+        A `mode: continuous` task keeps running and can be read repeatedly
+        (read_segment() just pulls the next chunk). A `mode: finite` task is
+        genuinely one-shot: it stops for good after its first n_samples, and
+        a second read on it raises a DAQmx "read beyond final sample" error.
+        Matches pytesdaqx-run's own `rearm_each_segment` rule (yaml_run.py)
+        for the same reason. :meth:`_uses_pxi_locked_ac` measurements never
+        reach here in `finite` mode - :meth:`start` already rewrote their
+        overrides to `continuous` - so this only fires for a genuinely
+        one-shot/triggered acquisition with no PXI AC waveform involved.
+        """
+        mode = str(self._merged_adc(measurement, overrides).get("mode", "continuous")).strip().lower()
+        return mode in {"finite", "triggered"}
+
+    def _run(
+        self,
+        measurement: str,
+        overrides: dict[str, Any] | None,
+        discard_remaining: int = 0,
+        active_channels: list[str] | None = None,
+    ) -> None:
+        # active_channels scopes step controls/TES-AC drive to just these
+        # detector channels (e.g. the GUI's checked channel selection)
+        # instead of every channel configured in run_setup.yaml -
+        # ControlCoordinator.resolve_detector_channels(None) otherwise
+        # defaults to all of them.
+        step = {"measurement": measurement, "active_channels": active_channels}
+        rearm_each_segment = self._rearm_each_segment(measurement, overrides)
+        has_hardware_trigger = bool(self._merged_adc(measurement, overrides).get("trigger"))
+        try:
+            if self._coordinator is not None:
+                # Apply any step controls now, but defer TES AC drive until
+                # after the AI task is armed (see class docstring).
+                self._coordinator.prepare_measurement(step, start_tes_ac=False)
+
+            self._session.configure_measurement(measurement, overrides=overrides)
+
+            if self._coordinator is not None:
+                self._coordinator.start_measurement_tes_ac(step)
+
+            while not self._stop_event.is_set():
+                try:
+                    segment = self._session.backend.read_segment()
+                except Exception as exc:
+                    # A self-/hardware-triggered acquisition (e.g. a
+                    # threshold measurement) genuinely may not see its
+                    # trigger condition within one read's timeout - that's
+                    # normal, recurring, expected behavior while waiting for
+                    # an event, not a fault. DAQmx's own SAMPLES_NOT_YET_
+                    # AVAILABLE is precisely "the read's timeout elapsed
+                    # before enough samples existed" (as opposed to, say, a
+                    # buffer overrun or a disconnected device), so retry the
+                    # still-armed task's read rather than crashing the
+                    # acquisition thread outright. Anything else - or a
+                    # measurement with no trigger at all, where a read
+                    # timeout would mean something is actually wrong -
+                    # still propagates.
+                    if (
+                        has_hardware_trigger
+                        and _SAMPLES_NOT_YET_AVAILABLE is not None
+                        and getattr(exc, "error_code", None) == _SAMPLES_NOT_YET_AVAILABLE
+                    ):
+                        continue
+                    raise
+                if discard_remaining > 0:
+                    discard_remaining -= 1
+                else:
+                    self._on_segment(segment)
+                if rearm_each_segment and not self._stop_event.is_set():
+                    self._session.backend.close()
+                    self._session.configure_measurement(measurement, overrides=overrides)
+        finally:
+            if self._coordinator is not None:
+                self._coordinator.cleanup_measurement(step)
+
+    def _on_segment(self, segment: Segment) -> None:
+        frame = Frame(
+            data=segment.data,
+            detector_channels=segment.detector_channels,
+            sample_rate_hz=segment.sample_rate_hz or 0.0,
+            measurement=segment.measurement,
+            calibration_coeffs=segment.metadata.get("adc_conversion_coefficients"),
+            metadata=segment.metadata,
+        )
+        try:
+            self._frame_queue.put_nowait(frame)
+        except queue.Full:
+            try:
+                self._frame_queue.get_nowait()
+            except queue.Empty:
+                pass
+            self._frame_queue.put_nowait(frame)
+
+    def read_frame(self, timeout: float | None = 0.0) -> Frame | None:
+        try:
+            if timeout is None:
+                return self._frame_queue.get()
+            if timeout <= 0:
+                return self._frame_queue.get_nowait()
+            return self._frame_queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+
+    def close(self) -> None:
+        self.stop()
+        self._session.close()

pytesscope/analysis/__init__.py

@@ -0,0 +1,4 @@
+from .config import AnalysisConfig
+from .pipeline import AnalysisPipeline, AnalysisResult
+
+__all__ = ["AnalysisConfig", "AnalysisPipeline", "AnalysisResult"]