Lab058: characterize symbol quality in controlled ABAB recording

docs/lab058_current_state.md

@@ -0,0 +1,82 @@
+# Lab058 — исходное состояние и заранее зафиксированный план
+
+## Назначение и границы
+
+Lab058 измеряет качество BPSK-символов в уже сохранённом единственном OTA ABAB-сеансе
+Lab056. Аппаратное оборудование не опрашивается, HackRF Plus не запускается, передача
+не выполняется. Исторические данные Lab054 и Lab056 не изменяются. Все новые результаты
+пишутся только в `data/processed/lab058/`.
+
+Исходный Git HEAD после отдельной фиксации Lab057:
+`5773136ebfa8bafdffc344462d0ce6b56838d3af`.
+
+## Проверяемые исходные данные
+
+- `data/raw/lab056/tx_abab.cs8`: ожидаемый SHA-256
+  `5b34bbe1a8e6d037d2d6d367a74e9eb84e8940db7da61600ffaa7f7497d4f600`;
+- `data/raw/lab056/rx_stream.cs8`: ожидаемый SHA-256
+  `e336dd653fa554058052fcf851e9f2462f66b8cf7c710815ca2b9a09ffc23ad4`;
+- Fs = 8 Мвыб/с, цифровая несущая +50 кГц, RRC roll-off 0,35, span 10 символов,
+  guard 16 символов;
+- A1/A2: 20 ксимв/с, 4096 полезных символов, 400 отсчётов/символ;
+- B1/B2: 500 ксимв/с, 102400 полезных символов, 16 отсчётов/символ;
+- границы burst и их уточнённые RX-start берутся из зафиксированного
+  `data/processed/lab056/rf_analysis.json`.
+
+Перед расчётом программа повторно проверяет существование, размер и SHA-256 обоих raw
+файлов. Она также проверяет, что первые 1280 символов каждого burst точно совпадают с
+действующей штатной PRBS7-преамбулой.
+
+## Два раздельных режима
+
+**Receiver-like.** Используется существующий RRC matched filter и действующие алгоритмы
+timing/CFO/комплексного gain. Их оценки получают только 1280 известных приёмнику символов
+преамбулы. Правильная полная TX-последовательность подключается после замораживания оценок
+и служит только для подсчёта ошибок и диагностических метрик. Переданные границы burst,
+унаследованные от Lab056, означают, что это анализ качества текущего приёмного тракта при
+известной сегментации, а не независимый поиск пакета в трёхсекундном потоке.
+
+**Oracle diagnostic.** Известная полная TX PRBS разрешена для физической диагностики.
+Timing выбирается на заранее фиксированной сетке из 33 точек от −0,5 до +0,5 символа.
+Сеанс делится на 64 последовательные временные плитки: чётные плитки оценивают timing,
+CFO и комплексный `h`, нечётные являются отложенной проверкой. По восемь символов у
+каждой границы плитки заранее исключаются из обеих выборок, чтобы опоры RRC и sinc не
+пересекали train/validation. Oracle matched filter оценивает постоянную составляющую
+только по сырым отсчётам защищённых чётных плиток; нечётные плитки не участвуют в этой
+nuisance-оценке.
+Первичные BER, EVM,
+matched/residual, decision margin и статистика облаков берутся с нечётных плиток.
+Oracle не считается результатом штатного receiver.
+
+## Формулы и фиксированные критерии
+
+- `EVM_RMS = sqrt(mean(|r - h*s|^2) / mean(|h*s|^2))` на отложенных символах.
+- `matched/residual = 10 log10(Pmatched / Presidual)`; это не объявляется Eb/N0.
+- Signed decision margin равен `s * Re(r/h)`; отрицательное значение означает ошибку.
+  Публикуются median, p10 и p01.
+- Eye opening — расстояние между средними действительной оси для `+1` и `−1` после
+  нормировки `h`. Временная ось задаётся в долях символа. Чувствительность — изменение
+  opening при offsets −0,10 и +0,10 символа относительно оптимального момента.
+- Диагностический ISI-отклик оценивается одним и тем же МНК-базисом taps −5…+5 для A и B;
+  публикуется `10 log10(sum(|h[k!=0]|^2)/|h[0]|^2)`. Эквалайзер не применяется.
+- `H(f)` получается как `Sxy/Sxx` из Hann-сегментов длиной 8192 с 50% overlap.
+  Используются только частоты внутри RRC-полосы и bins с TX PSD не ниже −20 dB от пика.
+  Публикуются p95−p05 ripple, max−min, линейный наклон, остаточная фаза после удаления
+  линейной задержки и variation group delay, только если число bins и coherence достаточны.
+- A1, B1, A2, B2 считаются независимо; средние A/B строятся только после этого.
+
+## Контроли
+
+1. Сохранённый TX проходит тот же RRC/oracle тракт; ожидается BER = 0 в обоих режимах.
+2. Воспроизводимый synthetic AWGN использует seed 5801 и комплексную дисперсию
+   400 код² на отсчёт при Fs = 8 Мвыб/с и одинаковую среднюю TX-мощность. Инвариант — одна и
+   та же sampled noise PSD; при росте скорости и падении энергии символа метрики должны
+   ухудшаться в ожидаемую сторону. Этот контроль не подгоняет реальную запись.
+3. Фоновое RX-окно до ABAB проверяется против BPSK-эталона и не должно выглядеть как
+   качественный BPSK-сигнал.
+
+Результат Lab056 `B/A energy per symbol = −13,870505 dB` используется только как известное
+энергетическое сравнение. Lab058 не предполагает заранее AWGN-канал и не объявляет
+частотно-зависимое искажение или многолучёвость доказанными без устойчивых оценок.
+
+RF TX = 0. Lab058 до результата не коммитируется. Push не выполняется.