pytesdaqx 0.2.2__tar.gz → 0.2.3__tar.gz

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

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

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

@@ -52,21 +52,41 @@ centered on its trigger.
 `ZarrRecorder` defaults to zstd compression (level 9) and to sharded arrays for
 both shapes:
 
-- **Continuous** (`channel_sample`): 1s chunks, sharded into 10s shards
-  (`continuous_sharding=True`, `continuous_shard_target_duration_s=10.0`).
-  Small chunks keep partial reads cheap (decompression cost is paid per
-  chunk touched, not per array), while sharding keeps the on-disk object
-  count low for filesystems like NERSC/CC-IN2P3 that penalize very large
-  numbers of small files.
+- **Continuous** (`channel_sample`): small chunks keep partial reads cheap
+  (decompression cost is paid per chunk touched, not per array), while
+  sharding keeps the on-disk object count low for filesystems like
+  NERSC/CC-IN2P3 that penalize very large numbers of small files.
 - **Finite/trace** (`trace_channel_sample`): one trace per chunk, sharded
   toward a 10s-equivalent target (`trace_sharding=True`,
   `trace_shard_target_duration_s=10.0`).
 
+The continuous geometry has two layers, because the useful sizes depend on
+the acquisition and only the run layer knows it:
+
+| | `ZarrRecorder` defaults | resolved by `pytesdaqx-run` from the YAML |
+|---|---|---|
+| chunk | `1s` | `0.25s`, grown towards 1 MiB at low data rates (capped 10s), then shortened to divide one read block |
+| shard | `10s` | one read block: the longest block up to 60s that divides the step duration |
+| shard bytes | 128 MiB | 8 GiB, so a whole block is never clamped |
+| chunks per shard | `max_chunks_per_shard=100` | `continuous_max_chunks_per_shard` (high): one block fills a shard in a single write |
+
+Constructing `ZarrRecorder` directly (including through `RawDataWriter`
+without recorder options) therefore keeps the older 1s/10s geometry; pass
+the options explicitly to match a run. See
+[acquisition configuration](../user/configuration/acquisition_config.md)
+for the user-facing rules.
+
+A shard is rewritten whenever part of it is written, so a read block shorter
+than the shard multiplies disk writes (measured: 5.5x for 1s blocks in 10s
+shards, 30x for 1s blocks in 60s shards, at 3 channels and 1.25 MHz). Keeping
+shard == read block writes each shard exactly once.
+
 Both shard-sizing paths (`_continuous_chunking_metadata` and
 `_trace_shard_traces` in `pytesdaqx/recorder/zarr.py`) apply a third
-constraint, `max_chunks_per_shard` (default 100), in addition to the
-duration and byte-size targets: `shard_chunk_count = min(by_duration,
-by_bytes, max_chunks_per_shard)`.
+constraint, `max_chunks_per_shard`, in addition to the duration and
+byte-size targets: `shard_chunk_count = min(by_duration, by_bytes,
+max_chunks_per_shard)`. A chunk or shard reduced by any of these limits
+emits a warning naming the binding one.
 
 This cap exists because of a measured defect in zarr-python 3.1.5: the
 per-write cost of an incremental `resize()` + append into a sharded array

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/docs/user/cli/data_inspection.md

@@ -110,6 +110,8 @@ pytesdaqx-view-traces acquisition_dir \
 
 The default display units are detector amps when the required readout-circuit metadata are available. Other supported choices include ADC volts or raw ADC values, depending on stored read mode and CLI options.
 
+Accelerometer channels can be displayed in g with `--units g`; this requires `readout_circuit.amplifier_gain` (and optionally `sensitivity_v_per_g`) in the run setup. See [Accelerometer readout](../configuration/run_setup_yaml.md#accelerometer-readout).
+
 If amp conversion fails, inspect the channel `readout_circuit` values in stored metadata, especially output gain and resistance/turn-ratio fields.
 
 ### Plot decimation

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/docs/user/configuration/acquisition_config.md

@@ -53,9 +53,36 @@ sequence:
     duration: 15m
 ```
 
+### A step records whole read blocks
+
+Acquisition always records complete read blocks, so `sequence[].duration` is
+rounded **up** to a whole number of them. With a 60-second read block a
+20-second step records 60 seconds of data, not 20. Keep the step duration a
+multiple of the read-block duration; pytesdaqx warns when it is not, naming
+the amount of data that will actually be taken.
+
 ### Automatic read-block duration
 
-`read_block_duration` is optional. When omitted, pytesdaqx derives it from the effective Zarr chunk duration after applying the configured chunk-duration target and chunk-size cap. This preserves aligned writes without requiring normal users to tune acquisition buffering.
+`read_block_duration` is optional. When omitted, pytesdaqx uses the longest
+block up to 60 seconds that divides the step duration exactly, so that a step
+never takes more data than requested:
+
+| Step duration | Automatic read block | Blocks recorded |
+|---|---|---|
+| 3 min | 60 s | 3 |
+| 100 s | 50 s | 2 |
+| 20 s | 20 s | 1 |
+| 1 s (scan point) | 1 s | 1 |
+
+One read block is written as one shard, so this also sets the file count: a
+three-minute stream becomes three data objects instead of eighteen at the old
+ten-second default. The cost is buffering: one block is held in memory before
+it is written, which is `channels x sample_rate x 2 bytes x block` (1.2 GB for
+8 channels at 1.25 MHz with a 60-second block), and an interrupted acquisition
+loses the block in flight.
+
+Steps driven by `n_read_blocks` rather than `duration` keep the historical
+chunk-aligned block.
 
 For example:
 
@@ -88,10 +115,29 @@ A **chunk** is a physical Zarr storage-layout unit. It is independent of a read
 
 | Key | Default | Meaning |
 |---|---:|---|
-| `chunk_duration` | `10s` | Continuous chunk-duration target |
+| `chunk_duration` | `0.25s`, grown at low data rates | Continuous chunk-duration target |
 | `chunk_target_mb` | `128` | Maximum target chunk size |
-
-The resolved chunk may be shorter than `chunk_duration` when the byte-size cap is reached.
+| `shard_duration` | one read block | Continuous shard-duration target |
+| `shard_target_mb` | `8192` (continuous), `128` (traces) | Maximum target shard size |
+| `max_chunks_per_shard` | `100` (traces) | Chunks per trace shard |
+
+A chunk is the unit a reader must decompress, so the default keeps it short
+(about 5-8 MB at 20-32 MB/s) to make short random reads such as feature
+windows cheap; at low data rates it grows towards 1 MiB so it stays worth
+compressing, up to 10 seconds. A shard is one file and defaults to one read
+block, which writes each shard exactly once.
+
+The resolved chunk may be shorter than `chunk_duration`, and the resolved
+shard shorter than `shard_duration`, when a byte cap or `max_chunks_per_shard`
+is reached. Both cases emit a warning naming the binding limit.
+
+### Shards, blocks and write cost
+
+A shard is rewritten every time part of it is written, so a read block shorter
+than the shard multiplies disk writes: at 3 channels and 1.25 MHz, one-second
+blocks with 10-second shards write 4.2 GB for 764 MB of data (5.5x), and with
+60-second shards 23 GB (30x). Leaving both at their defaults, or setting
+`read_block_duration` equal to `shard_duration`, writes each shard once.
 
 ## Finite acquisition: traces
 

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/docs/user/configuration/run_setup_yaml.md

@@ -108,6 +108,33 @@ readout_circuit:
 
 The correct constants depend on the installed readout circuit.
 
+### Accelerometer readout
+
+Auxiliary sensors such as accelerometers use the same `readout_circuit`
+mapping. The conversion from ADC voltage to acceleration depends on the
+sensor specification and its signal-conditioner gain:
+
+```yaml
+channels:
+  AccelerometerX:
+    adc:
+      device: adc1
+      channel: 0
+    readout_circuit:
+      sensor_type: accelerometer
+      amplifier_gain: 100         # signal conditioner gain (typically 1, 10 or 100)
+      sensitivity_v_per_g: 1.0    # sensor sensitivity in V/g (default 1)
+```
+
+Acceleration in g is `volts / (amplifier_gain * sensitivity_v_per_g)`.
+`amplifier_gain` is required when `sensor_type: accelerometer`; both values
+must be positive. The constants are saved with the stream metadata, exposed
+by `get_detector_settings()` as `amplifier_gain`, `sensitivity_v_per_g`, and
+`acceleration_norm_v_per_g`, and used when reading data with `units="g"`.
+
+A complete example with three accelerometers and a vibration transducer is
+in `examples/configuration/vibration/`.
+
 ## Other run-level mappings
 
 A run setup may also define:

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/docs/user/configuration/scans.md

@@ -430,6 +430,8 @@ Cleanup is not implicit. Without `scan.cleanup.temperature`, the final scan setp
 
 A vibration transducer is driven by a signal generator; `channels` names logical transducers from `run_setup.transducers`, not detector channels.
 
+Accelerometer channels recorded during the scan should define their volts-to-g conversion in `run_setup.yaml` (see [Accelerometer readout](run_setup_yaml.md#accelerometer-readout)); `examples/configuration/vibration/run_setup.yaml` pairs with the vibration scan example below.
+
 | Target | Values and units | Behavior |
 |---|---|---|
 | `transducer.frequency_hz` | Numeric drive frequency in Hz | Sets the transducer signal generator's frequency |

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/examples/README.md

@@ -42,6 +42,10 @@ configuration/
     README.md
     acquisition_didv.yaml
     acquisition_iv_restore.yaml
+
+  vibration/
+    hardware_fake.yaml
+    run_setup.yaml
 ```
 
 The files under `basic/` form the common configuration foundation:
@@ -57,6 +61,17 @@ The files under `basic/` form the common configuration foundation:
 
 The basic hardware and run-setup examples also include a fake temperature controller using separate `sensors` and `heaters` inventory mappings. The logical `mc` path is suitable for testing `pytesdaqx-temperature`, canonical `temperature.setpoint` scans, stability waiting, and opt-in stream snapshots with `acquisition_temperature_fake.yaml`.
 
+The `vibration/` directory maps three accelerometers (`AccelerometerX`, `AccelerometerY`, `AccelerometerZ`) to `adc1` channels 0-2, with their volts-to-g conversion (`readout_circuit.amplifier_gain` and `sensitivity_v_per_g`), plus a vibration transducer. Use it with `scans/acquisition_transducer_vibration_scan.yaml`:
+
+```bash
+pytesdaqx-run \
+  --hardware examples/configuration/vibration/hardware_fake.yaml \
+  --run-setup examples/configuration/vibration/run_setup.yaml \
+  --acquisition-config examples/configuration/scans/acquisition_transducer_vibration_scan.yaml \
+  --backend fake \
+  --no-save-data
+```
+
 The `temperature/` directory contains the native MACRT inventory and logical temperature mappings used for real-controller CLI tests.
 
 The scan examples cover the currently maintained scan patterns. Less common

pytesdaqx-0.2.3/examples/configuration/blinded/acquisition_blinded_75_25.yaml

@@ -0,0 +1,117 @@
+# Blinded physics running: 75% restricted / 25% open, with a grouped
+# IV+dIdV calibration block at the start and end of every cycle.
+#
+# One cycle (repeated by run.n_sequence_repeats):
+#
+#   [ IV -> dIdV ]  ->  4 data slots  ->  [ dIdV ]
+#    opening calib      3 restricted        closing calib
+#                       + 1 open
+#
+# Why the data block is split into slots instead of one restricted block
+# followed by one open block: with a fixed "restricted then open" order the
+# open sample always sits further from the calibration than the restricted
+# sample does, so bias-point drift biases exactly the 25% used to develop
+# cuts and efficiencies. Splitting into slots and moving the open slot
+# around makes the time-since-dIdV distribution the same for both samples.
+#
+# The open slot's position is rotated by hand here (see the four cycle
+# variants below). For real running, generate this file with a seeded RNG
+# so the position is randomized rather than a fixed rotation, and record the
+# seed -- a fixed rotation can alias with periodic systematics (diurnal
+# temperature, cryocooler, fridge fills).
+#
+# Slot length (5m here) must be short compared to the drift timescale. The
+# two bracketing dIdVs measure that drift directly: if the opening and
+# closing dIdV disagree beyond tolerance, shorten the slots.
+
+run:
+  file_format: zarr
+  save_data: true
+  channels: [TES_A, TES_B]
+  output_dir: /data/pytesdaqx
+  acquisition_label: blinded_physics
+  stop_policy: finish_current_step
+  # One cycle = 1 IV + 2 dIdV + 4 x 5m data = ~20m of physics data.
+  # 72 repeats ~= 24h of running.
+  n_sequence_repeats: 72
+
+sequence:
+  # ---- opening calibration block (IV and dIdV grouped together) ----
+  - measurement: iv
+    label: iv
+    duration: 2m
+
+  - measurement: didv
+    label: didv_open
+    duration: 1m
+
+  # ---- settling window, discarded, applied equally to both samples ----
+  # The dIdV square wave injects heat. Taking this as its own labeled step
+  # means the transient lands in a stream both samples see identically,
+  # instead of being absorbed by whichever slot happens to run first.
+  - measurement: background
+    label: settle
+    duration: 30s
+    restricted: 0
+
+  # ---- data block: 4 slots, 3 restricted + 1 open ----
+  # This cycle places the open slot 2nd. Rotate/randomize per cycle.
+  - measurement: background
+    label: physics
+    duration: 5m
+    restricted: 1
+
+  - measurement: background
+    label: physics
+    duration: 5m
+    restricted: 0
+
+  - measurement: background
+    label: physics
+    duration: 5m
+    restricted: 1
+
+  - measurement: background
+    label: physics
+    duration: 5m
+    restricted: 1
+
+  # ---- closing calibration: brackets the block for interpolation ----
+  - measurement: didv
+    label: didv_close
+    duration: 1m
+
+measurements:
+  iv:
+    type: iv
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      read_block_duration: 2s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+
+  didv:
+    type: didv
+    waveform:
+      shape: square
+      frequency_hz: 50
+      amplitude_vpp: 0.01
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      trace_duration: 2s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+
+  background:
+    type: background
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      read_block_duration: 1s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+    recorder:
+      chunk_duration: 1s
+      shard_duration: 10s

pytesdaqx-0.2.3/examples/configuration/blinded/generate_blinded_sequence.py

@@ -0,0 +1,165 @@
+"""Generate a blinded physics acquisition YAML with a randomized open slot.
+
+Each cycle is:
+
+    IV -> dIdV -> settle -> [4 data slots: 3 restricted + 1 open] -> dIdV
+
+The open slot's position inside the 4-slot unit is drawn with *stratified*
+randomization (permuted blocks): every group of 4 consecutive cycles uses
+each of the 4 positions exactly once, in random order. That gives exactly
+25% open data AND an open/restricted "time since dIdV" distribution that is
+balanced by construction, not just on average -- while staying random, so
+it cannot alias with a periodic systematic the way a fixed rotation can.
+
+The seed is recorded in the generated file so the layout is reproducible
+and auditable after unblinding.
+
+Usage:
+    python generate_blinded_sequence.py --cycles 72 --seed 20260918 \
+        --output acquisition_blinded_generated.yaml
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+from pathlib import Path
+
+SLOTS_PER_CYCLE = 4  # 3 restricted + 1 open -> 25% open
+
+
+def open_slot_positions(n_cycles: int, seed: int, slots: int = SLOTS_PER_CYCLE) -> list[int]:
+    """Open-slot position per cycle, stratified over every block of `slots`."""
+    rng = random.Random(seed)
+    positions: list[int] = []
+    while len(positions) < n_cycles:
+        block = list(range(slots))
+        rng.shuffle(block)
+        positions.extend(block)
+    return positions[:n_cycles]
+
+
+def render_cycle(cycle: int, open_slot: int, slot_duration: str) -> str:
+    lines = [
+        f"  # ---- cycle {cycle}: open slot in position {open_slot + 1} of {SLOTS_PER_CYCLE} ----",
+        "  - measurement: iv",
+        "    label: iv",
+        "    duration: 2m",
+        "",
+        "  - measurement: didv",
+        "    label: didv_open",
+        "    duration: 1m",
+        "",
+        "  - measurement: background",
+        "    label: settle",
+        "    duration: 30s",
+        "    restricted: 0",
+        "",
+    ]
+    for slot in range(SLOTS_PER_CYCLE):
+        restricted = 0 if slot == open_slot else 1
+        lines += [
+            "  - measurement: background",
+            "    label: physics",
+            f"    duration: {slot_duration}",
+            f"    restricted: {restricted}",
+            "",
+        ]
+    lines += [
+        "  - measurement: didv",
+        "    label: didv_close",
+        "    duration: 1m",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+HEADER = """# GENERATED FILE -- do not edit by hand.
+# Regenerate with:
+#   python generate_blinded_sequence.py --cycles {cycles} --seed {seed}
+#
+# Blinded physics running, {open_pct}% open / {restricted_pct}% restricted.
+# Open-slot positions (1-based, one per cycle), stratified random with the
+# seed below:
+#   {positions}
+#
+# blinding_seed: {seed}
+
+run:
+  file_format: zarr
+  save_data: true
+  channels: [TES_A, TES_B]
+  output_dir: /data/pytesdaqx
+  acquisition_label: blinded_physics
+  stop_policy: finish_current_step
+  # Cycles are unrolled below, so the sequence runs once.
+  n_sequence_repeats: 1
+
+sequence:
+"""
+
+FOOTER = """measurements:
+  iv:
+    type: iv
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      read_block_duration: 2s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+
+  didv:
+    type: didv
+    waveform:
+      shape: square
+      frequency_hz: 50
+      amplitude_vpp: 0.01
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      trace_duration: 2s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+
+  background:
+    type: background
+    adc:
+      mode: continuous
+      sample_rate: 1250000
+      read_block_duration: 1s
+      adc_input_range_v: [-10, 10]
+      read_mode: unscaled_int16
+    recorder:
+      chunk_duration: 1s
+      shard_duration: 10s
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--cycles", type=int, default=72)
+    parser.add_argument("--seed", type=int, required=True)
+    parser.add_argument("--slot-duration", default="5m")
+    parser.add_argument("--output", type=Path, default=Path("acquisition_blinded_generated.yaml"))
+    args = parser.parse_args()
+
+    positions = open_slot_positions(args.cycles, args.seed)
+    body = "\n".join(
+        render_cycle(cycle, slot, args.slot_duration) for cycle, slot in enumerate(positions)
+    )
+    header = HEADER.format(
+        cycles=args.cycles,
+        seed=args.seed,
+        open_pct=int(100 / SLOTS_PER_CYCLE),
+        restricted_pct=int(100 - 100 / SLOTS_PER_CYCLE),
+        positions=", ".join(str(p + 1) for p in positions),
+    )
+    args.output.write_text(header + body + FOOTER, encoding="utf-8")
+
+    counts = {slot + 1: positions.count(slot) for slot in range(SLOTS_PER_CYCLE)}
+    print(f"wrote {args.output}: {args.cycles} cycles, seed {args.seed}")
+    print(f"open-slot position counts: {counts}")
+
+
+if __name__ == "__main__":
+    main()

pytesdaqx-0.2.3/examples/configuration/vibration/hardware_fake.yaml

@@ -0,0 +1,15 @@
+# Fake hardware inventory for vibration studies: one ADC reading three
+# accelerometers and one signal generator driving a vibration transducer.
+
+instruments:
+  adc1:
+    driver: fake
+    type: pci_adc
+    device_alias: Dev1
+    model: fake_adc
+    channels: [0, 1, 2, 3, 4, 5, 6, 7]
+
+  agilent1:
+    driver: fake
+    type: signal_generator
+    channels: [1, 2]

pytesdaqx-0.2.3/examples/configuration/vibration/run_setup.yaml

@@ -0,0 +1,45 @@
+facility: 2
+fridge_run: 123
+fridge_run_start: "2026-04-12 19:00:00"
+
+# Example run setup for vibration studies: three accelerometer axes on adc1
+# channels 0-2 and one vibration transducer.
+#
+# Acceleration in g = volts / (amplifier_gain * sensitivity_v_per_g).
+# amplifier_gain is the signal-conditioner gain (typically 1, 10 or 100);
+# sensitivity_v_per_g is the accelerometer sensitivity (default 1 V/g).
+
+channels:
+  AccelerometerX:
+    adc:
+      device: adc1
+      channel: 0
+    readout_circuit:
+      sensor_type: accelerometer
+      amplifier_gain: 100
+      sensitivity_v_per_g: 1.0
+
+  AccelerometerY:
+    adc:
+      device: adc1
+      channel: 1
+    readout_circuit:
+      sensor_type: accelerometer
+      amplifier_gain: 100
+      sensitivity_v_per_g: 1.0
+
+  AccelerometerZ:
+    adc:
+      device: adc1
+      channel: 2
+    readout_circuit:
+      sensor_type: accelerometer
+      amplifier_gain: 100
+      sensitivity_v_per_g: 1.0
+
+# Topology only; drive frequency/amplitude are scan.parameters targets
+# (see examples/configuration/scans/acquisition_transducer_vibration_scan.yaml).
+transducers:
+  transducer1:
+    device: agilent1
+    channel: 2

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

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

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/pytesdaqx/cli/view_traces.py

@@ -168,7 +168,7 @@ def parse_args(argv: list[str] | None = None):
     parser.add_argument(
         "--units",
         default="amps",
-        choices=["adc", "volts", "amps"],
+        choices=["adc", "volts", "amps", "g"],
         help="Vertical-axis units; default: amps",
     )
     parser.add_argument(
@@ -736,6 +736,7 @@ def _units_label(units: str) -> str:
         "amps": "Current [A]",
         "volts": "Voltage [V]",
         "adc": "ADC counts",
+        "g": "Acceleration [g]",
     }.get(key, str(units))
 
 

{pytesdaqx-0.2.2 → pytesdaqx-0.2.3}/pytesdaqx/config/resolver.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings as _warnings
 from pathlib import Path
 from typing import Any
 
@@ -68,6 +69,13 @@ class ConfigResolver:
         )
         resolved_temperatures = resolve_temperature_paths(run_setup, hardware)
 
+        # A channel selected for specific measurements is easy to leave out of
+        # run.channels by accident, and then it is silently never recorded.
+        excluded_warnings = self._record_for_exclusion_warnings(run_setup, selected_channels)
+        for message in excluded_warnings:
+            _warnings.warn(message, stacklevel=2)
+        validation_warnings = list(validation_warnings) + excluded_warnings
+
         resolved_channels = self._resolve_channels(run_setup=run_setup, hardware=hardware, selected_channels=selected_channels)
         measurements = require_mapping(acquisition_config.get("measurements", {}), name="measurements")
         sequence = self._resolve_sequence(
@@ -125,6 +133,35 @@ class ConfigResolver:
             if isinstance(cfg, dict)
         }
 
+    @staticmethod
+    def _record_for_exclusion_warnings(
+        run_setup: dict[str, Any], selected_channels: list[str] | None
+    ) -> list[str]:
+        """Warn about channels reserved for a measurement but left out of the run.
+
+        ``record_for`` only narrows the channels of ``run.channels`` (or
+        ``--channels``) to the measurements that should record them; it cannot
+        add a channel that the run never selected.
+        """
+
+        if not selected_channels:
+            return []
+        selected = {str(name) for name in selected_channels}
+        messages = []
+        for name, cfg in (run_setup.get("channels", {}) or {}).items():
+            if str(name) in selected or not isinstance(cfg, dict):
+                continue
+            allowed = cfg.get("record_for", cfg.get("measurements", cfg.get("record_measurements")))
+            if allowed is None:
+                continue
+            allowed_list = [allowed] if isinstance(allowed, str) else list(allowed)
+            messages.append(
+                f"run_setup.channels.{name} has record_for {allowed_list} but is not "
+                f"in run.channels, so it is never recorded. Add {name} to "
+                f"run.channels: record_for then limits it to those measurements."
+            )
+        return messages
+
     @staticmethod
     def _resolve_record_channels(acquisition_config: dict[str, Any], cli_channels: list[str] | None) -> list[str] | None:
         if cli_channels is not None: