pytesdaqx 0.1.0__tar.gz

pytesdaqx-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include mkdocs.yml
+recursive-include docs *.md
+recursive-include examples *.md *.yaml *.py
+prune site

pytesdaqx-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: pytesdaqx
+Version: 0.1.0
+Summary: TES detector acquisition, instrument control, and raw-data recording
+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: numpy<2.0,>=1.26
+Requires-Dist: PyYAML
+Requires-Dist: h5py>=3.10
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: zarr<4,>=3
+Requires-Dist: numcodecs
+Requires-Dist: zstandard
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: ni
+Requires-Dist: nidaqmx; extra == "ni"
+Provides-Extra: visa
+Requires-Dist: pyvisa; extra == "visa"
+Provides-Extra: magnicon
+Requires-Dist: paramiko; extra == "magnicon"
+Provides-Extra: notebook
+Requires-Dist: jupyter; extra == "notebook"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+
+# pytesdaqx
+
+`pytesdaqx` is the Python acquisition and instrument-control framework used for TES detector readout. It supports continuous and finite NI-DAQmx acquisition, TES and SQUID control, YAML-defined sequences, and raw-data recording in Zarr or legacy HDF5. Zarr is the default for new
+acquisition configuration files when `run.file_format` is omitted. **Supported Python versions
+are 3.11 and 3.12.** Python 3.10 is not supported: the required `zarr>=3` has no published
+wheel/sdist for 3.10.
+
+## Documentation
+
+The user manual is in [`docs/`](docs/index.md). Start with:
+
+- [Installation](docs/installation/index.md)
+- [Quick start](docs/user/quickstart.md)
+- [Configuration files](docs/user/configuration/index.md)
+- [Command-line tools](docs/user/cli/index.md)
+- [Terminology](docs/user/terminology.md)
+- [Data format](docs/user/data_format.md)
+- [Developer guide](docs/developer/index.md)
+
+To build the documentation website locally:
+
+```bash
+python -m pip install -e '.[docs]'
+mkdocs serve
+```
+
+## Minimal local test
+
+```bash
+python -m pip install -e '.[dev]'
+
+pytesdaqx-validate-config \
+  --hardware examples/configuration/basic/hardware_fake.yaml \
+  --run-setup examples/configuration/basic/run_setup.yaml \
+  --acquisition-config examples/configuration/basic/acquisition_background.yaml
+
+pytesdaqx-run \
+  --hardware examples/configuration/basic/hardware_fake.yaml \
+  --run-setup examples/configuration/basic/run_setup.yaml \
+  --acquisition-config examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+The fake backend exercises configuration resolution and acquisition orchestration without contacting hardware.
+
+## Development
+
+Run the repository tests with:
+
+```bash
+pytest -q
+```
+
+Architecture, extension points, hardware support, testing, and release practices are documented in the [developer guide](docs/developer/index.md). The maintained example configurations are described in [`examples/README.md`](examples/README.md).

pytesdaqx-0.1.0/README.md

@@ -0,0 +1,54 @@
+# pytesdaqx
+
+`pytesdaqx` is the Python acquisition and instrument-control framework used for TES detector readout. It supports continuous and finite NI-DAQmx acquisition, TES and SQUID control, YAML-defined sequences, and raw-data recording in Zarr or legacy HDF5. Zarr is the default for new
+acquisition configuration files when `run.file_format` is omitted. **Supported Python versions
+are 3.11 and 3.12.** Python 3.10 is not supported: the required `zarr>=3` has no published
+wheel/sdist for 3.10.
+
+## Documentation
+
+The user manual is in [`docs/`](docs/index.md). Start with:
+
+- [Installation](docs/installation/index.md)
+- [Quick start](docs/user/quickstart.md)
+- [Configuration files](docs/user/configuration/index.md)
+- [Command-line tools](docs/user/cli/index.md)
+- [Terminology](docs/user/terminology.md)
+- [Data format](docs/user/data_format.md)
+- [Developer guide](docs/developer/index.md)
+
+To build the documentation website locally:
+
+```bash
+python -m pip install -e '.[docs]'
+mkdocs serve
+```
+
+## Minimal local test
+
+```bash
+python -m pip install -e '.[dev]'
+
+pytesdaqx-validate-config \
+  --hardware examples/configuration/basic/hardware_fake.yaml \
+  --run-setup examples/configuration/basic/run_setup.yaml \
+  --acquisition-config examples/configuration/basic/acquisition_background.yaml
+
+pytesdaqx-run \
+  --hardware examples/configuration/basic/hardware_fake.yaml \
+  --run-setup examples/configuration/basic/run_setup.yaml \
+  --acquisition-config examples/configuration/basic/acquisition_background.yaml \
+  --backend fake
+```
+
+The fake backend exercises configuration resolution and acquisition orchestration without contacting hardware.
+
+## Development
+
+Run the repository tests with:
+
+```bash
+pytest -q
+```
+
+Architecture, extension points, hardware support, testing, and release practices are documented in the [developer guide](docs/developer/index.md). The maintained example configurations are described in [`examples/README.md`](examples/README.md).

pytesdaqx-0.1.0/docs/developer/acquisition_pipeline.md

@@ -0,0 +1,118 @@
+# Acquisition pipeline
+
+## Backend contract
+
+There is not yet a formal abstract base class, but acquisition backends follow this minimal protocol:
+
+```python
+backend.configure(
+    measurement_name=...,
+    measurement_config=...,
+    detector_channels=...,
+)
+segment = backend.read_segment()
+backend.close()
+```
+
+`read_segment()` returns a `Segment` with a two-dimensional array shaped `[channel, sample]`.
+
+## DAQSession
+
+`DAQSession` owns the selected measurement dictionary and backend. For every configuration call it:
+
+1. copies the measurement configuration;
+2. deep-merges temporary overrides;
+3. selects detector channels;
+4. calls `backend.configure()`.
+
+This copy is important: scan- or step-specific overrides must not mutate the original resolved measurement dictionary.
+
+## Run-controller acquisition modes
+
+`YAMLRunController._run_step()` chooses one of three paths.
+
+### Threaded continuous
+
+Used when:
+
+```text
+adc.mode == continuous
+and threaded_continuous is enabled
+```
+
+```text
+NIDAQAIBackend.read_segment()
+  -> bounded SegmentRingBuffer
+  -> consumer callback
+  -> processors/callbacks/recorder
+```
+
+The queue blocks by default when full. `drop_when_full: true` is suitable only when losing blocks is acceptable, such as some live-display workflows. Raw-data acquisition should normally preserve the blocking behavior.
+
+### Serial or serial rearm
+
+Finite or triggered measurements use the serial path. If the measurement is finite or has an explicit trigger, the backend is configured and closed for every trace so the NI task rearms cleanly.
+
+A non-threaded continuous-mode measurement can also use the serial path without rearming between blocks.
+
+### PXI phase-locked dIdV
+
+A dIdV measurement using PXIe-4322 AC without an explicit trigger can use the dedicated phase-locked stream path:
+
+1. Configure and arm AI.
+2. Configure AI to wait on the AO StartTrigger.
+3. Start the multi-channel PXI AO waveform task.
+4. Read contiguous integer-period records from one AI task.
+5. Optionally discard initial transition records.
+6. Keep the AI sample clock referenced to the configured PXI reference clock.
+
+Explicit digital or analog triggers retain the finite-rearm diagnostic path.
+
+## NI analog-input backend
+
+`NIDAQAIBackend` currently supports:
+
+- one single DAQmx task for the selected AI channels;
+- continuous and finite sample modes;
+- digital-edge/external start triggers;
+- analog-edge/threshold start triggers;
+- scaled floating-point reads;
+- unscaled `int16` reads with device calibration coefficients;
+- optional input-buffer and read-chunk sizing;
+- optional reference-clock configuration;
+- logical `pfi0` resolution when selected channels use one ADC device.
+
+Selected channels must fit in one DAQmx task. Explicit multi-device synchronized AI is not implemented in this backend.
+
+For long continuous saved blocks, the backend may perform several shorter DAQmx reads into temporary contiguous arrays. This limits DAQmx buffer allocation while preserving the requested saved write-block length.
+
+## Processing and callbacks
+
+Every acquired `Segment` passes through:
+
+```text
+processor 1 -> processor 2 -> ... -> callback 1 -> callback 2 -> recorder
+```
+
+Processors may replace the `Segment`; callbacks receive the processed result. The current built-in processor is `DownsampleProcessor`.
+
+`collect_records=True` retains records in memory and should be limited to tests, notebooks, and short runs.
+
+## Metadata propagation
+
+Before recording, the run controller adds:
+
+- measurement label;
+- sequence-step index;
+- compact stream-level scan metadata;
+- an opt-in stream-level temperature snapshot;
+- backend metadata such as DAQmx read mode;
+- ADC conversion coefficients when available.
+
+The temperature snapshot is taken once per stream after scan and sequence controls are applied. It contains only sensor device/channel, temperature, resistance, and units; read errors are nonfatal and represented compactly. Recorders translate nested dictionaries to native Zarr attributes or JSON-encoded HDF5 attributes. Readers normalize both forms back to dictionaries.
+
+## Resource lifecycle
+
+A backend must make `close()` idempotent. Configuration failures must close partially created tasks. Instrument outputs that can remain active require explicit service/coordinator cleanup semantics; do not rely on object destruction.
+
+Temperature scan cleanup is executed by the outer run-controller `finally` block before `HardwareRegistry.close_all()`, including on Ctrl-C. The narrow shutdown path is `set_setpoint(0)` followed by `disable_heater()`; it does not call general PID/topology configuration. If the run already has an exception, cleanup or close failures are logged while the original exception is preserved.

pytesdaqx-0.1.0/docs/developer/adding_hardware.md

@@ -0,0 +1,113 @@
+# Adding hardware
+
+Choose the smallest extension point that matches the device.
+
+## 1. New acquisition backend
+
+Use this path for a device that produces sampled detector data.
+
+Implement the backend protocol:
+
+```python
+class MyBackend:
+    def configure(self, *, measurement_name, measurement_config, detector_channels): ...
+    def read_segment(self) -> Segment: ...
+    def close(self) -> None: ...
+```
+
+Requirements:
+
+- Return data shaped `[channel, sample]`.
+- Preserve the requested detector-channel order.
+- Include sample rate and useful backend metadata.
+- Make `close()` safe after partial configuration and safe to call more than once.
+- Avoid importing vendor libraries at module import time when possible.
+
+Then add backend construction in `pytesdaqx.run.yaml_run._make_backend()` and expose a CLI choice if it is user-selectable. Add fake/unit tests and a real-hardware diagnostic command.
+
+## 2. New built-in controllable instrument
+
+Use this path for a device that sets bias, waveform, SQUID, laser, or temperature state.
+
+1. Add a wrapper in `pytesdaqx.instruments`.
+2. Prefer lazy vendor-driver construction in `open()`.
+3. Implement generic capability methods used by the relevant service.
+4. Add the canonical driver name to `BUILTIN_DRIVER_NAMES`.
+5. Add a branch in `build_builtin_instrument()`.
+6. Add hardware YAML documentation and tests using a fake underlying instance.
+7. Add the path to the hardware support matrix after validation.
+
+Keep communication details in the instrument wrapper, not in services or sequence code.
+
+## 3. Out-of-tree/private instrument
+
+For site-specific code, use:
+
+```yaml
+instruments:
+  private_device:
+    driver: external
+    class_path: package.module:DeviceClass
+    constructor_args: []
+    constructor_kwargs: {}
+    connection:
+      address: ...
+```
+
+`ExternalInstrument` imports the class lazily and delegates unknown methods to the instance. The external class still needs to expose methods expected by the selected service.
+
+This route is preferable when a driver cannot be distributed with `pytesdaqx`.
+
+## 4. Custom factory registration
+
+Applications embedding `pytesdaqx` can register a builder:
+
+```python
+factory = DriverFactory.with_default_fake_builders(allow_fake=False)
+factory.register("my_driver", lambda name, cfg: MyInstrument(name=name, config=cfg))
+registry = HardwareRegistry(hardware_config, factory=factory)
+```
+
+Use `allow_fake=False` in production validation when an unknown driver must be an error rather than silently becoming `FakeHardwareDevice`.
+
+## 5. New service path
+
+Add a service path only when the same logical operation needs genuinely different behavior, conversion, grouping, or state handling.
+
+Examples already present in `TESBiasService` are PXI AO, direct signal generator, and FEB-plus-signal-generator paths.
+
+A new path should define:
+
+- accepted physical units and conversion rules;
+- set and readback behavior;
+- cached-state policy when readback is absent;
+- grouped-channel behavior if synchronization matters;
+- startup and cleanup behavior;
+- metadata state source and error reporting.
+
+## 6. New scan/control target
+
+A new scan target is a cross-cutting feature. Update:
+
+1. scan/config schema validation;
+2. `ControlCoordinator` target dispatch;
+3. channel-selection logic;
+4. service call and unit conversion;
+5. settling behavior;
+6. metadata persistence;
+7. fake and target-specific tests;
+8. user scan documentation.
+
+## Required tests
+
+At minimum, test:
+
+- hardware YAML resolution;
+- registry construction;
+- service path selection;
+- the generic set/get methods;
+- failure cleanup;
+- a fake full-stack measurement or scan;
+- import behavior without the vendor library installed.
+
+Real-hardware validation should record the OS, kernel, driver version, model, physical wiring, command, and observed result.

pytesdaqx-0.1.0/docs/developer/architecture.md

@@ -0,0 +1,142 @@
+# Architecture
+
+## End-to-end flow
+
+A normal `pytesdaqx-run` invocation follows this path:
+
+```text
+pytesdaqx-run
+  |
+  v
+YAMLRunController.from_yaml()
+  |
+  +--> ConfigResolver
+  |      hardware.yaml + run_setup.yaml + acquisition.yaml
+  |      -> ResolvedConfig
+  |
+  +--> HardwareRegistry
+  |      -> controllable instrument objects
+  |
+  +--> detector-oriented services
+  |      TESBiasService
+  |      SQUIDService
+  |      LaserService
+  |      TemperatureService
+  |
+  +--> acquisition backend
+  |      NIDAQAIBackend or FakeAcquisitionBackend
+  |
+  v
+YAMLRunController.run()
+  |
+  +--> ScanEngine: build scan points
+  +--> ControlCoordinator: apply controls and manage measurement state
+  +--> DAQSession: configure the selected measurement
+  +--> acquisition loop: produce Segment objects
+  +--> optional processors and callbacks
+  +--> ZarrRecorder or HDF5Recorder
+  +--> acquisition manifest
+```
+
+The run controller owns orchestration. It should not contain low-level instrument protocol details, and a recorder should never operate hardware.
+
+## Control plane and data plane
+
+It is useful to view the system as two connected planes.
+
+### Control plane
+
+```text
+ResolvedConfig
+  -> HardwareRegistry
+  -> services
+  -> ControlCoordinator
+  -> scan point / sequence-step actions
+```
+
+The control plane sets TES bias, SQUID state, laser output, and temperature setpoints. It also performs cleanup after every sequence step, including failed steps.
+
+### Data plane
+
+```text
+ResolvedConfig.channel_map()
+  -> acquisition backend
+  -> Segment(data[channel, sample])
+  -> processor(s)
+  -> callback(s)
+  -> recorder
+  -> raw-data reader
+```
+
+The data plane uses detector-channel order from the resolved configuration. Storage metadata preserves that order and the physical ADC mapping.
+
+## Why services exist
+
+Run setup is detector-oriented: a user asks to set the TES bias for `TES_A`, not to invoke a particular driver method on AO channel 0. Services convert that detector-oriented request into a device-specific path.
+
+For example, `TESBiasService` can construct one of three paths:
+
+```text
+same device, PXI-like AO
+  -> PXI4322BiasPath
+
+same device, signal-generator-like
+  -> SignalGeneratorBiasPath
+
+FEB for DC + signal generator for AC
+  -> FEBPlusSignalGeneratorBiasPath
+```
+
+The split FEB path has different waveform-center semantics from the other two:
+the FEB carries TES DC, while the signal generator remains zero-centered and
+provides only the AC perturbation. If several detector channels share one
+generator output, the service resolves their physical waveform settings first,
+requires them to match, configures the generator once, and then connects the
+individual FEB inputs.
+
+This keeps sequence and scan code independent of the physical implementation.
+
+## NI ADC ownership
+
+The NI analog-input device is intentionally different from controllable instruments:
+
+- `ConfigResolver` produces the ADC channel map.
+- `NIDAQAIBackend` creates and owns the NI-DAQmx AI task.
+- The default `HardwareRegistry` does **not** create the ADC task.
+
+A `hardware.yaml` entry with `driver: nidaqmx` is therefore used for inventory and channel resolution. The actual AI task is created by `NIDAQAIBackend` from `ResolvedConfig.channel_map()`.
+
+## Run hierarchy
+
+The main orchestration hierarchy is:
+
+```text
+acquisition
+  -> sequence repeat
+     -> scan point
+        -> sequence step / stream
+           -> acquired in-memory record
+```
+
+For each sequence step, the run controller opens one stream recorder, executes the acquisition path, and closes the stream recorder. Zarr therefore has one stream group per executed step. Repeated steps create distinct full stream names. Stream IDs are the bare `I#_D#_T#` timestamp identifiers.
+
+## Internal `Segment` name
+
+The in-memory acquisition object is currently named `Segment` for historical reasons. It is always a two-dimensional array:
+
+```text
+data[channel, sample]
+```
+
+Its external meaning depends on the measurement and recorder:
+
+- Continuous acquisition: one internal acquisition read block appended to a continuous stream.
+- Finite or triggered acquisition: one trace.
+
+Do not expose the internal `Segment` class name as Zarr storage terminology. In user-facing documentation, use **read block**, **trace**, or **partition** as appropriate.
+
+## Failure and cleanup model
+
+The run controller uses nested `try/finally` blocks around measurement setup, acquisition, recorder closure, and hardware cleanup. This is especially important for NI AO tasks: a partially configured PXI waveform task must be closed so the next run does not fail because the NI resource remains reserved.
+
+Manifest updates are intentionally rebuildable. A manifest callback failure is logged but must not corrupt or stop raw-data writing.

pytesdaqx-0.1.0/docs/developer/configuration_pipeline.md

@@ -0,0 +1,136 @@
+# Configuration pipeline
+
+The user edits three YAML files, but runtime code consumes one `ResolvedConfig`.
+
+## Resolution stages
+
+```text
+hardware.yaml
+run_setup.yaml
+acquisition.yaml
+      |
+      v
+ConfigResolver._load_yaml()
+      |
+      v
+hardware entries -> HardwareDevice
+      |
+      v
+schema validation and cross-reference checks
+      |
+      v
+selected detector channels -> ResolvedChannel[]
+      |
+      v
+logical temperatures -> ResolvedTemperaturePath[]
+      |
+      v
+measurements + sequence -> SequenceStep[]
+      |
+      v
+scan -> ScanParameter[]
+      |
+      v
+ResolvedConfig
+```
+
+`ConfigResolver.resolve()` is the canonical entry point.
+
+## Resolved channel order
+
+Detector channels are sorted by:
+
+```text
+ADC device name, ADC channel number, detector-channel name
+```
+
+The resulting `array_index` defines row order in acquired arrays and recorded channel maps. Code must not assume that YAML insertion order is the storage order.
+
+## Validation layers
+
+Configuration checking has several layers:
+
+1. YAML must parse to a top-level mapping.
+2. `validate_full_configuration()` checks schemas and cross-file relationships.
+3. The resolver verifies referenced devices and physical channels.
+4. Duplicate ADC assignments are rejected.
+5. Sequence and scan blocks are normalized into dataclasses.
+6. In strict mode, active channels must be part of the available detector-channel set.
+7. Backends and services perform hardware-specific validation when configured.
+
+The validator can return warnings in `ResolvedConfig.warnings`; callers should display or log them rather than silently discard them.
+
+## Precedence
+
+The main precedence rule is:
+
+```text
+explicit Python/CLI argument
+  > acquisition-config YAML run option
+  > internal default
+```
+
+Channel selection follows:
+
+```text
+CLI channels
+  > run.channels
+  > every channel in run_setup.yaml
+```
+
+Measurement-specific temporary overrides are deep-merged by `DAQSession.configure_measurement()` before the backend is configured. This is used, for example, to resolve `read_block_duration`, `trace_duration`, or exact period counts into a backend sample count.
+
+See the [user precedence guide](../user/configuration/resolution.md) for the user-facing rules.
+
+## Temperature-path resolution
+
+`resolve_temperature_paths()` converts canonical `run_setup.temperatures` entries into `ResolvedTemperaturePath` objects. Each path contains one required sensor endpoint and one optional control endpoint. Endpoint references are checked against the controller's explicit `sensors` or `heaters` inventory, including MACRT module aliases. Singular/flat temperature syntax and endpoint `controller` aliases are rejected.
+
+A control endpoint also carries its heater-level `setpoint_limits` normalized to kelvin. The service layer attaches registry device instances and enforces those limits centrally before calling a driver, so CLI, controls, scans, and cleanup have identical safety behavior. Drivers implement one fixed Kelvin-based interface (`read_temperature_k`, `read_resistance_ohm`, `read_setpoint_k`, `set_setpoint_k`, `get_control_state`, and `disable_heater`) instead of relying on legacy method-name alternatives.
+
+## Laser configuration ownership
+
+Laser configuration is intentionally split across two layers:
+
+- `run_setup.yaml` owns stable topology: logical laser name, physical device, control channel, and TTL/reference channel.
+- the acquisition configuration owns operational pulse settings: voltage levels, offset, pulse width, repetition frequency, waveform shape, phase, and output cleanup behavior.
+
+`LaserService` is constructed from run setup and therefore owns the physical output channels. `ControlCoordinator` applies measurement-level pulse settings without passing a channel override. Metadata assembly combines the run-setup topology with the acquisition pulse settings so the stored stream describes both what was wired and what was requested. Schema validation rejects operational fields in run setup and device/channel overrides in acquisition laser sections.
+
+## Scan representation
+
+The resolver produces `ScanParameter` objects. `ScanEngine` converts them into ordered `ScanPoint` values using either Cartesian product or zipped axes. A temperature parameter may also carry normalized `wait_for_stable` configuration. The run controller applies each scan point, performs any required temperature-stability wait, then executes the full sequence. Only `temperature.setpoint` is accepted for temperature scans.
+
+`scan.cleanup.temperature` remains raw acquisition configuration because it runs once after the whole scan rather than generating scan points. `YAMLRunController` invokes it from the outer run `finally` block before closing the registry. The coordinator sets an optional cleanup setpoint first, then calls the narrow service `disable_heater()` method and verifies the reported off state when requested. Original acquisition exceptions take precedence over cleanup errors.
+
+Developers adding a scan target normally need to update all of:
+
+- `config/schema.py` validation;
+- `ControlCoordinator.apply_target()` or a target-specific helper;
+- metadata capture when the value must be persisted;
+- user scan documentation;
+- fake-path and target-specific tests.
+
+## Adding a configuration field
+
+Before adding a YAML key, decide which domain owns it:
+
+- Inventory or connection property: `hardware.yaml`.
+- Detector wiring or calibration constant: `run_setup.yaml`.
+- Acquisition behavior or sequence policy: `acquisition.yaml`.
+
+Then update, as applicable:
+
+1. schema validation;
+2. resolver normalization or dataclasses;
+3. the consumer backend/service/recorder;
+4. resolved metadata snapshots;
+5. an example YAML file;
+6. user documentation;
+7. unit and regression tests.
+
+Prefer one canonical name. Compatibility aliases should be translated at the configuration boundary and clearly documented as aliases rather than propagated throughout the code.
+
+## Source and resolved configuration in data
+
+For Zarr acquisitions, the top-level acquisition attributes contain source YAML snapshots and a resolved summary. HDF5 acquisitions use a `config/` directory beside the data files. This metadata is part of reproducibility; changes to resolution behavior should be considered data-format changes even when array layout is unchanged.