pytesdaqx 0.2.0__tar.gz → 0.2.2__tar.gz

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytesdaqx
-Version: 0.2.0
+Version: 0.2.2
 Summary: TES detector acquisition, instrument control, and raw-data recording
 Author: TESSERACT DAQ developers
 Classifier: Development Status :: 3 - Alpha

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/docs/developer/data_io.md

@@ -25,6 +25,7 @@ Important behavior:
 - Zarr v3 group and array metadata.
 - Continuous array shape `[channel, sample]`.
 - Finite array shape `[trace, channel, sample]`.
+- Finite `trace_time[trace]` array of float64 Unix acquisition timestamps.
 - Native zarr-python writing.
 - Optional compression and sharding configuration.
 - Stream metadata updated as read blocks or traces are appended.
@@ -32,6 +33,20 @@ Important behavior:
 
 Zarr does not use HDF5 file rotation. Recorder options such as `segments_per_file` are ignored for Zarr by the run controller.
 
+Finite-record timestamps are copied from `SegmentMetadata.segment_timestamp`
+to `trace_time`, preserving gaps between triggers. An absent timestamp is NaN;
+the recorder does not substitute its write time. `get_trace()` and
+`StreamReader` return the selected value as `trace_time`. Older stores without
+this array remain readable and omit the unavailable timestamp. The compact
+timestamp array is separate from waveform chunking/sharding and is not a JSONL
+sidecar.
+
+The NI run controller records `pretrigger_length_samples: 0` for finite
+acquisitions, whose digital/analog triggers start acquisition rather than
+referencing a pretrigger buffer. Historical pretrigger metadata is preserved
+by the readers; consumers must not assume that an arbitrary finite record is
+centered on its trigger.
+
 ## Compression and chunking defaults
 
 `ZarrRecorder` defaults to zstd compression (level 9) and to sharded arrays for

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytesdaqx"
-version = "0.2.0"
+version = "0.2.2"
 description = "TES detector acquisition, instrument control, and raw-data recording"
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx/io/zarr_reader.py

@@ -283,8 +283,7 @@ class ZarrReader:
         )
         info = self._native_info(
             record_type="trace",
-            trace_index=index,
-            n_samples=int(out.shape[1]),
+            **self._native_trace_info(index),
             selected_channels=selected_channels,
             units=units,
         )
@@ -505,10 +504,17 @@ class ZarrReader:
         return (out, info) if include_metadata else out
 
     def _native_trace_info(self, trace_index: int) -> dict[str, Any]:
-        return {
+        info = {
             "trace_index": int(trace_index),
             "n_samples": self.trace_length_samples,
         }
+        time_path = self.path / 'trace_time'
+        if is_array(time_path):
+            values = read_array_slice(time_path, (slice(trace_index, trace_index + 1),))
+            if np.asarray(values).size != 1:
+                raise ValueError('trace_time must contain one timestamp per finite trace')
+            info['trace_time'] = float(np.asarray(values).reshape(-1)[0])
+        return info
 
     def _native_read_block_info(self, read_block_index: int) -> dict[str, Any]:
         start, length = self._continuous_read_block_bounds(read_block_index)

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx/recorder/zarr.py

@@ -99,6 +99,7 @@ class ZarrRecorder:
         self._raw_path: Path | None = None
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
         self._native_raw_supports_shards = False
         self._raw_shape_model: str | None = None
         self._segment_length_samples: int | None = None
@@ -123,6 +124,7 @@ class ZarrRecorder:
         _require_zarr_python()
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
         self._native_raw_supports_shards = False
         try:
             self._open_stream_store()
@@ -182,6 +184,7 @@ class ZarrRecorder:
         self._raw_path = None
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
 
         if self.on_file_closed is not None:
             try:
@@ -209,6 +212,24 @@ class ZarrRecorder:
         self._native_raw.resize((n_traces, int(trace.shape[1]), int(trace.shape[2])))
         self._native_raw[int(trace_index), :, :] = np.ascontiguousarray(trace[0])
 
+    def _write_trace_time(self, trace_index: int, timestamp: float | None) -> None:
+        """Persist finite-record timestamps independently of waveform chunks.
+
+        Finite triggers need not be consecutive in time. Missing acquisition
+        timestamps remain NaN; write time is not an acquisition timestamp.
+        """
+        if self._native_trace_time is None:
+            self._native_trace_time = self._native_group.create_array(
+                'trace_time', shape=(0,), chunks=(1024,), dtype='float64',
+                fill_value=np.nan, dimension_names=('trace',),
+                attributes={'units': 's', 'time_reference': 'unix',
+                            'description': 'Acquisition timestamp for each finite trace'},
+            )
+        self._native_trace_time.resize((int(trace_index) + 1,))
+        self._native_trace_time[int(trace_index)] = (
+            np.nan if timestamp is None else float(timestamp)
+        )
+
     def write_segment(self, data, metadata: SegmentMetadata):
         if self._store is None:
             raise RuntimeError("ZarrRecorder is not open")
@@ -232,6 +253,7 @@ class ZarrRecorder:
         else:
             trace = data.reshape((1, int(data.shape[0]), int(data.shape[1])))
             self._write_native_trace(trace, segment_num - 1)
+            self._write_trace_time(segment_num - 1, metadata.segment_timestamp)
             self._chunk_shapes.append([1, int(data.shape[0]), int(data.shape[1])])
             self._n_samples_total = n_samples
 
@@ -244,8 +266,8 @@ class ZarrRecorder:
 
         # Zarr stores do not write per-block JSONL sidecars by default.
         # The stream/raw metadata carry n_samples, n_traces, chunking, and
-        # timing summaries; detailed per-write provenance can be added later
-        # behind an explicit debug/provenance option if needed.
+        # timing summaries. Finite acquisition timestamps live in the aligned
+        # trace_time array, because gaps cannot be recovered from trace indices.
 
         update_attrs(
             self._store,

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx/run/yaml_run.py

@@ -647,6 +647,10 @@ class YAMLRunController:
             "downsample_method": ds_method,
             "adc_physical_channels": [r.get("adc_physical_channel") for r in rows],
         }
+        # Finite NI tasks use start triggers (including analog threshold),
+        # not reference triggers with a pretrigger buffer.
+        if adc_mode.lower() == "finite":
+            adc_attrs["pretrigger_length_samples"] = 0
         return adc_attrs, rows
 
     def _build_detconfig_attrs(self, measurement_cfg: dict[str, Any], *, record_channels: list[str] | None = None) -> dict[str, Any]:

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx/services/tes_bias.py

@@ -819,7 +819,23 @@ class FEBPlusSignalGeneratorBiasPath(BaseBiasPath):
             self.feb_channel,
         )
         if source == "hardware" and value is not None:
-            return {"value": value, "units": self.last_dc_units, "source": "hardware"}
+            # last_dc_units is only populated by a set_dc() call made this
+            # session - if the FEB was already biased beforehand (the usual
+            # case: bias set once, then a viewer/reader process attaches
+            # later), it's still None here. Unlike PXI4322BiasPath (whose
+            # get_dc() falls back to "V", correctly paired with returning a
+            # raw voltage in that same branch), this class's `value` is the
+            # FEB's own already-calibrated current reading - falling back to
+            # None left callers with no unit at all, which a units-string
+            # lookup (e.g. PytesdaqxBoardReader.read_tes_bias) can silently
+            # misread as "not a recognized current unit, must be volts" and
+            # divide by a bias resistor instead of doing nothing - turning a
+            # ~uA reading into a value several orders of magnitude off.
+            return {
+                "value": value,
+                "units": self.last_dc_units or self.dc_default_units or "uA",
+                "source": "hardware",
+            }
         return super().get_dc()
 
     def configure_ac(

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytesdaqx
-Version: 0.2.0
+Version: 0.2.2
 Summary: TES detector acquisition, instrument control, and raw-data recording
 Author: TESSERACT DAQ developers
 Classifier: Development Status :: 3 - Alpha

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/pytesdaqx.egg-info/SOURCES.txt

@@ -172,6 +172,7 @@ tests/test_distribution_readiness.py
 tests/test_facility_catalog_metadata.py
 tests/test_feb_driver.py
 tests/test_feb_signal_generator_didv.py
+tests/test_finite_record_metadata.py
 tests/test_io_coordinate_cleanup.py
 tests/test_lakeshore372_driver.py
 tests/test_laser_configuration_ownership.py

{pytesdaqx-0.2.0 → pytesdaqx-0.2.2}/tests/test_feb_signal_generator_didv.py

@@ -225,3 +225,24 @@ def test_preflight_fails_on_generator_clipping_and_leaves_feb_disconnected():
     assert ("output_off", 1) in sg.calls
     assert ("connect_tes_ac", "A", False) in feb.calls
     assert ("connect_tes_ac", "B", False) in feb.calls
+
+
+def test_get_dc_falls_back_to_configured_units_when_never_set_this_session():
+    # Regression test: the FEB is normally already biased before a viewer
+    # process ever attaches (bias set once, kept for the whole run) - so
+    # set_dc() (the only thing that used to populate last_dc_units) is often
+    # never called this session at all. get_dc() used to return units=None
+    # in that case, unlike PXI4322BiasPath.get_dc() (which falls back to
+    # "V", correctly paired with the raw voltage it returns in that same
+    # branch). A caller that maps a units *string* to a conversion factor
+    # (e.g. pytesscope's PytesdaqxBoardReader.read_tes_bias) can silently
+    # read units=None as "not a recognized current unit, must be volts" and
+    # divide the FEB's already-in-uA reading by a bias resistor instead -
+    # producing a value several orders of magnitude off, with no error
+    # raised anywhere.
+    service, feb, _sg = _service()
+
+    state = service.get_dc("TES_A")
+
+    assert state["value"] == feb.bias_by_channel["A"]
+    assert state["units"] == "uA"  # from dc_default_units, not left as None

pytesdaqx-0.2.2/tests/test_finite_record_metadata.py

@@ -0,0 +1,89 @@
+"""Finite acquisition timing must survive recording and reader selection."""
+
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+import zarr
+
+from pytesdaqx.io import StreamReader
+from pytesdaqx.io.zarr_utils import read_array, read_attrs
+from pytesdaqx.recorder import HDF5Recorder, RunMetadata, SegmentMetadata, ZarrRecorder
+from pytesdaqx.run.yaml_run import YAMLRunController
+
+
+def run_metadata(tmp_path):
+    return RunMetadata(
+        run_name='threshold_I2_D20260914_T120001', output_dir=tmp_path,
+        detector_channels=['TES_A'], sample_rate_hz=1000.,
+        root_attrs={'measurement': 'threshold', 'measurement_type': 'threshold',
+                    'stream_start': 1000., 'facility': 2},
+        adc_attrs={'adc_mode': 'finite', 'sample_rate_hz': 1000.,
+                   'pretrigger_length_samples': 0},
+    )
+
+
+@pytest.mark.parametrize('storage', ['hdf5', 'zarr'])
+def test_finite_timestamps_and_pretrigger_survive_recording(tmp_path, storage):
+    recorder = HDF5Recorder() if storage == 'hdf5' else ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    timestamps = [1000.125, 1007.75, 1018.3125]
+    for index, timestamp in enumerate(timestamps):
+        recorder.write_segment(np.full((1, 32), index, dtype=np.int16), SegmentMetadata(
+            measurement='threshold', sample_rate_hz=1000., segment_timestamp=timestamp))
+    recorder.close()
+
+    with StreamReader(tmp_path) as reader:
+        records = list(reader.iter_records())
+        assert len(records) == 3
+        for index, (trace, info) in enumerate(records):
+            np.testing.assert_array_equal(trace, np.full((1, 32), index))
+            key = 'segment_time' if storage == 'hdf5' else 'trace_time'
+            assert info[key] == timestamps[index]
+            assert info['pretrigger_length_samples'] == 0
+        if storage == 'zarr':
+            _, info = reader.read_record({'trace_index': 1})
+            assert info['trace_time'] == timestamps[1]
+    if storage == 'zarr':
+        time_path = next(tmp_path.glob('*.zarr')) / 'trace_time'
+        np.testing.assert_array_equal(read_array(time_path), timestamps)
+        assert read_attrs(time_path)['time_reference'] == 'unix'
+
+
+def test_missing_finite_timestamp_is_not_replaced_with_write_time(tmp_path):
+    recorder = ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    recorder.write_segment(np.zeros((1, 32)), SegmentMetadata(measurement='threshold', sample_rate_hz=1000.))
+    recorder.close()
+    with StreamReader(tmp_path) as reader:
+        _, info = reader.read_next()
+        assert np.isnan(info['trace_time'])
+
+
+def test_older_finite_zarr_without_timestamp_array_still_reads(tmp_path):
+    recorder = ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    recorder.write_segment(np.zeros((1, 32)), SegmentMetadata(measurement='threshold', sample_rate_hz=1000.))
+    recorder.close()
+    group = zarr.open_group(str(next(tmp_path.glob('*.zarr'))), mode='a')
+    del group['trace_time']
+    with StreamReader(tmp_path) as reader:
+        _, info = reader.read_next()
+        assert info['trace_index'] == 0
+        assert 'trace_time' not in info
+
+
+@pytest.mark.parametrize('trigger', ['none', 'analog_threshold', 'digital_edge'])
+@pytest.mark.parametrize('mode', ['finite', 'continuous'])
+def test_acquisition_builder_records_zero_pretrigger_for_finite_start_triggers(mode, trigger):
+    # Metadata building is hardware independent; the configured NI finite
+    # implementation uses start triggers, not reference-trigger buffers.
+    controller = SimpleNamespace(processors=[], _channel_map_for=lambda channels: [
+        {'detector_channel': channels[0], 'array_index': 0, 'adc_physical_channel': 'Dev1/ai0'}])
+    attrs, _ = YAMLRunController._build_adc_metadata(controller, {
+        'adc': {'mode': mode, 'sample_rate': 1000.}, 'trigger': {'type': trigger},
+    }, record_channels=['TES_A'])
+    if mode == 'finite':
+        assert attrs['pretrigger_length_samples'] == 0
+    else:
+        assert 'pretrigger_length_samples' not in attrs