CaltechExperimentalGravity / CaltechExperimentalGravity/system_ident

Pre-flight channel validation: existence, retrievability class, per-channel rate, liveness, injectability

Open
#34 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.