docs: note proposed interferometer signal-strength trend on webpage
CI for csaxs_bec / test (push) Successful in 2m14s

Design note only -- not implemented. Captures the idea (low-rate/~hourly
trend, not per-projection), plus a 2026-09-19 survey finding that flomni/
lamni/omny each have incompatible interferometer-read primitives (different
axis counts/semantics, no shared RT-controller base), and that omny has no
working webpage generator to hook into yet (its existing file is dead code,
never imported by the real factory).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132KBoxsovfcMNRGJhS1Pbw
This commit is contained in:
x01dcandClaude Sonnet 5 committed 2026-09-19 09:56:01 +02:00
1 parent 7d21c0e43e
commit 22a882fafa
2 files changed
+121

No files matched your search

@@ -0,0 +1,114 @@
# TODO: interferometer signal-strength trend on the webpage
Status: **proposed, not implemented.** Discussed 2026-09-19. This is a design
note to capture the idea before it's lost -- no code changes yet.
## Goal
A new section on the flomni/lamni/omny status webpage showing the trend of
interferometer signal strength over time (a sparkline/chart, not a live
readout), so drift/degradation is visible at a glance across a session or
beamtime, not just from an interactive `show_signal_strength_interferometer()`
call in the moment.
## Sampling design
- **Very low rate on purpose**: roughly one data point per hour, or less --
explicitly *not* per-projection. A tomo scan already calls a signal-strength
check regularly (flomni: every projection, see below), but sampling that
often would produce far too many points for a trend view (tens of points
per hour per axis) for no benefit -- this is about long-term drift, not
per-projection diagnostics.
- **Timestamped, so per-axis cadence can differ freely.** Each data point is
`(timestamp, value)`; there's no requirement that every axis be sampled at
the same time or the same rate. An axis that's cheap to read opportunistically
(e.g. already fetched as a side effect of something else) can be sampled
more often than one that costs a dedicated round-trip, and the trend for
each axis is still valid independently. Staleness/eventual-consistency
between axes, or between this and the live scan, is fine -- the goal is a
general trend, not point-in-time precision.
- **Retention**: apply the lesson from `eps_alarm_history.json`'s HTTP 413
bug (see `docs/developer/...` -- fixed 2026-09-18 in `eps_status_generator.py`,
`_MAX_UPLOAD_BYTES`/`_shrink_to_fit`): cap this ring buffer by *both* count
and a hard byte budget from the start, reusing that same pattern, not just
a count cap discovered insufficient after the fact.
## Per-setup reality check (2026-09-19 survey -- see below for what's actually there)
The three setups' interferometer-read primitives are **not interchangeable**
-- this can't be one generic helper at the RT-controller layer:
| Setup | Read primitive | Axes/channels | Threshold/check helper |
|---|---|---|---|
| flomni | `RtFlomniController.read_ssi_interferometer(axis_number)` (`rt_flomni_ophyd.py:462`), generic `j{n}` socket read | 0-3 | `laser_tracker_check_signalstrength()` (`rt_flomni_ophyd.py:466`) -- reads axis 1, warns only, does not act |
| LamNI | **no equivalent single-axis reader.** `RtLamniController.show_signal_strength_interferometer()` (`rt_lamni_ophyd.py:268`) reads 3 channels (ST FZP horizontal/vertical, angle) via distinct `J2`/`J3`/`J7` commands | 3 (different meaning than flomni's 0-3) | none -- no `min_signal`/`low_signal` threshold logic exists in this file at all |
| omny | `RtOMNYController.laser_tracker_check_and_wait_for_signalstrength()` (`rt_omny_ophyd.py:270`) -- different behavior class: polls and *auto-triggers* `omny_interferometer_align_tracking()` if below `low_signal`, not just a warning. `show_signal_strength_interferometer()` (`rt_omny_ophyd.py:736`) reads 5 channels via a `self.ssi` dict from `feedback_get_status_and_ssi()` | 5 (OSA FZP Y/X, ST OSA Y/X, Angle) | yes, but actively corrective, not passive |
There is no shared `csaxs_bec`-level RT-controller base across the three
(`RtFlomniController`/`RtLamniController`/`RtOMNYController` each subclass the
generic external `ophyd_devices.utils.controller.Controller` directly). LamNI
also doesn't reuse the one shared local module that does exist
(`csaxs_bec/devices/omny/rt/rt_ophyd.py`'s `RtSignalRO`/etc., used by flomni
and omny) -- it redefines its own parallel Signal classes.
**Conclusion**: the shared piece of this feature should be the trend
storage/rendering (a common global-var shape + webpage section), not the
signal read itself. Each setup needs its own small adapter that knows its own
axis semantics and feeds the shared throttled-stash helper.
## Where the throttled read would hook in, per setup
- **flomni**: `laser_tracker_check_signalstrength()` is already called once
per projection during `tomo_scan()` (`flomni.py:3624`) -- cheapest option is
to throttle *at that call site* (check "have I stashed a data point in the
last hour?" before writing one), reusing an already-happening RT round-trip
rather than adding a new one.
- **LamNI**: confirmed (2026-09-19 survey) there is **no** scan-time
signal-strength call anywhere in the LamNI plugin -- `show_signal_strength`
(`lamni.py:724`) is a manual/interactive-only helper, never called from
`tomo_scan_projection` or `tomo_scan`. There's no existing per-projection
hook to throttle against, so this would need a separate low-rate timer
instead -- the natural fit is `WebpageGeneratorBase`'s own `_cycle()` loop
(`OMNY_shared/webpage_generator_base.py`, default 15s cadence, already runs
continuously including when idle), which already has a documented
subclass-override hook for instrument-specific data
(`_collect_setup_data()`, used today by `FlomniWebpageGenerator`/
`LamniWebpageGenerator` for temperatures/sample name/etc.) -- add the
throttle check there instead of in the scan loop.
- **omny**: blocked on a prerequisite -- **omny has no working webpage
generator at all right now.** `omny_webpage_generator.py` looks like one
(defines `WebpageGeneratorBase`, `FlomniWebpageGenerator`, a
`make_webpage_generator()`, etc.) but is confirmed dead/orphaned: nothing
in `omny.py`/`omny/__init__.py` imports it, and the real factory
(`OMNY_shared/webpage_generator_base.py` ~line 1409) explicitly falls
through to the plain base class for the omny session with a comment noting
this file is "an unwired, stale duplicate." Building a real
`OmnyWebpageGenerator` subclass is a prerequisite for this feature on omny,
not just an extra per-setup adapter -- do not revive the stale duplicate
as-is.
## Suggested shape (for whenever this is implemented)
- A global var, e.g. `interferometer_signal_trend`, holding a small
ring-buffer list of `{timestamp, axis, value}` (or per-axis sub-lists),
written via a proxy class mirroring `_ProgressProxy`/`_TomoQueueProxy`
(`OMNY_shared/tomo_queue_mixin.py`) -- the established pattern in this
codebase for cross-process/cross-thread state via
`client.get_global_var`/`set_global_var`.
- A shared rendering piece (webpage HTML/JS section, sparkline or simple line
chart) that reads this same global var shape regardless of which setup
wrote it, so the display code doesn't need to know about per-setup axis
differences -- only each setup's adapter does.
- Byte-budget-capped storage per the eps history lesson above.
## Open questions (not yet decided)
- Exact axis(es) worth trending per setup -- flomni's axis 1 is free (already
read every projection); trending flomni's other 3 axes, or any of LamNI's/
omny's channels, means new dedicated round-trips on whatever cadence is
chosen for those.
- Whether sampling should continue during idle time between scans (needs a
timer-based approach for all three setups, not just LamNI/omny) or only
while a scan is actively running (cheaper, but leaves gaps covering the
most interesting idle-drift periods).
- Exact webpage layout/placement of the new section -- not designed yet.
@@ -198,6 +198,13 @@ cannot drift.
- **Consider**: the PSI **EPICS archiver REST interface** to sidestep CA firewall
concerns.
### Interferometer signal-strength trend (proposed, not implemented)
- See `OMNY_shared/AI_docs/TODO_interferometer_signal_trend.md` for the full
design note (2026-09-19) — a new webpage section trending interferometer
signal strength over time, sampled at ~1 point/hour or less (not
per-projection). Blocked on omny specifically needing a real
`OmnyWebpageGenerator` built first (its current file is dead/unwired code).
### Deferred
- **LamNI**: fill in `LamniWebpageGenerator` — real `tomo_type` key values in
`TOMO_TYPES`, device paths / `_collect_setup_data()`, `LamNI.png`. Add a