CaltechExperimentalGravity / CaltechExperimentalGravity/system_ident
Pre-flight channel validation: existence, retrievability class, per-channel rate, liveness, injectability
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
**Spin-out of #32 · Stage D (#13) · spec §4.3.5, §4.3.1.**
Covers #32 items **2, 6, 7** and part of **9**.
**Nothing here has been observed.** Every run to date has been a closely supervised single-operator
session where a human noticed anything wrong. This is architecture for the multi-user, unattended
case, filed now because the seam is far cheaper to install than to retrofit.
## Why here, and why it is free
`CDSBackend.from_config` already probes the hardware rate once with a one-second read (spec §4.2).
Extending **that same probe** costs no extra hardware time and still happens strictly before any
injection.
That matters more than it looks, because of the constraint in spec §4.3.1: **many front-end channels
are not recorded to disk.** They must be captured live from the framebuilder or they are
unretrievable — and that includes the `:-_..._EXC` excitation readback that §2.1
makes mandatory (`read()` must never synthesise X). So a channel-name mistake discovered *after* an
injection costs an injection, an operator approval under Rule 2, and data that cannot be re-fetched.
Discovered before, it costs nothing.
## What to establish, per channel, for every channel the campaign will touch
- [ ] **Existence** — #32 item 7 (invalid readback channel name).
- [ ] **Retrievability class** — recorded (frame-backed) vs test point (live only). Fast non-EPICS
channels normally carry a **`_DQ`** suffix, so `_DQ` is a good *prior* for "has look-back" — but
it is a heuristic, not a contract, and the class must be **confirmed by probing**.
- [ ] **Rate, per channel**, and §4.2's integer-ratio conditions checked against it. `_DQ` channels are
normally served at a **lower rate** than the corresponding full-rate channel (properly
decimated), so `fs_hw` can no longer be one global number — #32 item 9.
- [ ] **Liveness** — finite, and variance above a floor. This is the check #18 already specifies for
`Pyy`, generalised to every channel; it is what catches a readback test point that has been
cleared by another user before an injection is spent — #32 item 2.
- [ ] **Injectability**, for excitation channels — structurally, an excitation channel must be a fast
front-end test point, never a slow read-only EPICS record — #32 item 6.
## Scope boundary
Component 1 ships the **structural** injectability check. The site-specific channel-naming tables are
site-profile data and belong to #26. Nothing site-specific is hard-coded here.
## Known consequence to carry, not solve here
An **X/Y rate mismatch** (full-rate excitation readback for X, lower-rate `_DQ` for Y) breaks the
exact filter cancellation spec §7 relies on: `H_meas = H · D_Y/D_X`, a systematic magnitude *and*
phase error growing toward Nyquist. Agreed default is **warn and proceed**, not refuse. Dividing
`D_Y` out needs site-supplied filter data (#26), and the filters' type is itself unknown — plausibly
IIR rather than FIR, unconfirmed.
## Verification
All on the #5 fake harness, no hardware: a missing channel, a wrong-rate channel, a dead (zero
variance) channel and a non-injectable channel each fail pre-flight **with the excitation never
constructed** — not merely never started.
---
**Campaign:** CDS hardware backend · branch [`feat/cds-hardware-backend`](https://github.com/CaltechExperimentalGravity/system_ident/tree/feat/cds-hardware-backend)
· [spec](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/superpowers/specs/2026-08-03-cds-hardware-backend-design.md) · [plan](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/superpowers/plans/2026-08-03-cds-hardware-backend.md) · [handoff](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/notes/cds-hardware-bringup-2026-08.md)
*Code is deferred until the plan and issues have been reviewed.*
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with CDSBackend.from_config and the existing one-second hardware-rate probe, then read the linked spec §4.3.5 and §4.3.1 and the #5 fake harness. Done means missing, wrong-rate, zero-variance, and non-injectable channels fail pre-flight before the excitation is constructed, with no hardware required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100