CaltechExperimentalGravity / CaltechExperimentalGravity/system_ident
Stage I: documentation — register CDSBackend, correct its docstring, record the non-defects
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
**Stage I (spec §7, plan Stage I).** Rolling; each item lands with its code.
Already done in the plan commit: the [`CLAUDE.md`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/CLAUDE.md) **Hardware safety** hard-rule section, the two dated
notes on the trunk-based and Phase-1 rules, and the "Human authorization comes first" section in
[`docs/tutorial/safety-and-ops.qmd`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/tutorial/safety-and-ops.qmd).
Remaining:
- **[`docs/_quarto.yml:143`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/_quarto.yml#L143)** — register `backends.cds.CDSBackend` in the "Plant & backends" section
once it stops being a stub. The API reference is **hand-curated**, so a new public symbol is invisible
until listed. `backends.rtsfreerun_adapter.RTSfreerunBackend` is missing too and should be added at the
same time.
- **[`docs/index.qmd:125`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/index.qmd#L125)** — currently says the CDS backend "is currently a **stub**". Update when it
is not, and keep it explicit that hardware validation is a separate gate from a green twin suite.
- **[`src/system_ident/backends/cds.py:18`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/src/system_ident/backends/cds.py#L18)** — correct the docstring. "A constant integer-sample offset
*cancels* in the ratio-of-averages FRF, but a fractional-sample clock drift would re-introduce leakage"
is only half right: a constant *fractional* offset **also** cancels when X is a readback; only
time-*varying* drift bites. As written it pushes an implementer toward the GPS-alignment code the spec
rules out as unnecessary and dangerous.
- **Extend [`docs/tutorial/safety-and-ops.qmd`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/docs/tutorial/safety-and-ops.qmd)** with the per-injection token mechanics and the
mandatory-STOP requirement, once Stage E lands.
- **Record the non-defects** (spec §7) somewhere durable, so nobody "fixes" working code:
- the sibling project's `normalise_rms` overshoot of `sqrt(Δf_full/Δf_dec)` ≈ 22.6× is **not latent
here** — measured realised `var/px_total` = **1.033**;
- its unbanded first excitation with a −17.35-count residual DC offset is **not latent here** —
[`src/system_ident/excitation.py:170`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/src/system_ident/excitation.py#L170) keeps only `k >= 1`, measured `mean(drive)` = −1.4e-17;
- its `effective_coherence` bug (the function algebraically ignores its `u_signal` argument, so
denominator readback noise never enters any reported uncertainty) is **not present here** — this repo
derives coherence from `var_b` at [`src/system_ident/loop.py:462`](https://github.com/CaltechExperimentalGravity/system_ident/blob/feat/cds-hardware-backend/src/system_ident/loop.py#L462).
Note `git lfs` is **not installed** on the dev machine — **touch no images** in this campaign.
---
**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 by reading the linked Stage I plan and spec, then inspect docs/_quarto.yml:143, docs/index.qmd:125, src/system_ident/backends/cds.py:18, and docs/tutorial/safety-and-ops.qmd. Confirm the existing references at src/system_ident/excitation.py:170 and src/system_ident/loop.py:462 before recording the non-defects. Done means the backend references, status wording, docstring, safety mechanics, and durable non-defect notes are updated without touching images.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100