Lab058: characterize symbol quality in controlled ABAB recording

docs/LABS_INDEX.md

@@ -476,3 +476,22 @@
   [график](../data/processed/lab057/comparison.png), [проверки](../data/processed/lab057/acceptance.json).
 - **STOP:** исторический Lab054 NOT_A, 0/16 сохранён. Lab057 не коммитилась,
   push не выполнялся; следующий OFFLINE-анализ Lab056 требует отдельного согласования.
+
+## Lab058 — качество символов сохранённого ABAB Lab056
+
+- **Запись 052; только сохранённые файлы, RF TX=0.** Lab057 зафиксирована коммитом
+  `5773136ebfa8bafdffc344462d0ce6b56838d3af`; Lab058 не закоммичена.
+- **Oracle A/B:** BER 0%/3,4959%, EVM 0,3174/0,8453, matched/residual
+  9,9685/1,4648 дБ. Энергия символа B/A из Lab056 −13,870505 дБ.
+- **Receiver-like A/B:** BER 0,0178%/52,4169%; B оценивает CFO примерно +4,7 Гц,
+  тогда как oracle получает значение около нуля. Carrier synchronization — отдельный
+  подтверждённый практический предел текущего receiver.
+- **Диагностика тракта:** eye opening 1,9979/1,9935; ISI ratio −33,3195/−30,1006 дБ;
+  H(f) ripple p95−p05 0,4067/5,4714 дБ. OTA не разделяет TX, канал и RX; group-delay
+  variation не объявлена устойчивой.
+- **Контроли:** TX BER 0/0; synthetic AWGN движет EVM в ожидаемую сторону при одинаковой
+  noise PSD; background BER около 50%. Итог `MIXED`; Lab054 остаётся NOT_A, 0/16.
+- [Постановка](lab058_current_state.md), [отчёт](lab058_offline_result.md),
+  [JSON](../data/processed/lab058/summary.json),
+  [CSV](../data/processed/lab058/segment_metrics.csv),
+  [H(f)](../data/processed/lab058/channel_transfer.png). STOP; push не выполнялся.

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 не выполняется.

docs/lab058_offline_result.md

@@ -0,0 +1,105 @@
+# Lab058 — качество BPSK-символов в сохранённом ABAB-сеансе Lab056
+
+## Что произошло простыми словами
+
+Передатчик в Lab056 держал почти одинаковую среднюю цифровую мощность для 20 и 500 ксимв/с. При 500 ксимв/с за ту же секунду передавалось в 25 раз больше символов, поэтому на один символ пришлось примерно на 13,87 дБ меньше измеренной энергии. Полная принятая мощность при этом практически не изменилась.
+
+В сохранённой записи отдельные символы 500 ксимв/с действительно различаются хуже: после точного диагностического согласования BER вырос с 0% до 3,4959%, RMS EVM — с 0,317 до 0,845, а matched/residual снизился с 9,97 до 1,46 дБ. Но штатный приёмный тракт ухудшает B намного сильнее — до 52,42% BER. Он оценил остаточный CFO примерно как +4,7 Гц вместо близкого к нулю значения. За burst 0,2048 с эта ошибка поворачивает фазу почти на полный оборот и перемешивает решения.
+
+Установлены два разных эффекта. Физическое качество широкополосного B хуже и совместимо с меньшей энергией символа; кроме того, штатная синхронизация B в этой записи явно не удерживает фазу. Оценка H(f) показывает большее широкополосное изменение амплитуды, но OTA-тракт включает обе платы, кабели, антенны и распространение. По нему нельзя приписать эффект одному HackRF Plus. Абсолютная RF-мощность в dBm, шумовая фигура и истинный Eb/N0 требуют калиброванного измерительного тракта; приведённые значения — цифровые диагностические метрики сохранённых IQ.
+
+## Целостность и границы
+
+| Файл | Размер | SHA-256 | Результат |
+|---|---:|---|---|
+| `tx_abab.cs8` | 21 177 088 байт | `5b34bbe1a8e6d037d2d6d367a74e9eb84e8940db7da61600ffaa7f7497d4f600` | совпал |
+| `rx_stream.cs8` | 48 000 000 байт | `e336dd653fa554058052fcf851e9f2462f66b8cf7c710815ca2b9a09ffc23ad4` | совпал |
+
+Использованы сохранённые RX-start A1/B1/A2/B2: 5 254 791 / 7 709 991 / 10 149 062 / 12 604 263. Исторические файлы Lab054/Lab056 не изменялись. Оборудование не опрашивалось, RF TX = 0.
+
+## Receiver-like и oracle
+
+Receiver-like применяет существующие RRC, timing и carrier estimates. Для оценки ему доступны только 1280 символов штатной преамбулы. Полный TX truth подключается затем лишь для подсчёта ошибок. Границы burst унаследованы от Lab056, поэтому независимый поиск пакета здесь не проверяется.
+
+Oracle использует известный TX для диагностического согласования. 64 временные плитки разделены заранее: чётные оценивают timing/CFO/h, нечётные проверяют результат. По восемь символов с каждой стороны каждой плитки исключены, чтобы опоры RRC и sinc не пересекали train/validation. Постоянная составляющая оценивается только по защищённым чётным участкам raw. Timing выбирается на фиксированной сетке −0,5…+0,5 символа с шагом 1/32. Основные физические метрики относятся к защищённым нечётным плиткам.
+
+| Сегмент | Режим | Ошибки / символы | BER | CFO, Гц | Timing, символа | RMS EVM | Matched/residual, дБ |
+|---|---|---:|---:|---:|---:|---:|---:|
+| A1 | receiver-like | 1 / 2816 | 0,0355% | +0,0558 | +0,0050 | 0,3164 | +9,9946 |
+| A1 | oracle | 0 / 1536 | 0% | −0,0175 | 0 | 0,3146 | +10,0454 |
+| B1 | receiver-like | 53110 / 101120 | 52,5218% | +4,6690 | 0 | 1,6279 | −4,2326 |
+| B1 | oracle | 1625 / 50688 | 3,2059% | −0,0617 | −0,03125 | 0,8151 | +1,7761 |
+| A2 | receiver-like | 0 / 2816 | 0% | −0,1387 | 0 | 0,3321 | +9,5741 |
+| A2 | oracle | 0 / 1536 | 0% | +0,0072 | 0 | 0,3202 | +9,8916 |
+| B2 | receiver-like | 52898 / 101120 | 52,3121% | +4,7422 | −0,0625 | 1,6786 | −4,4991 |
+| B2 | oracle | 1919 / 50688 | 3,7859% | −0,0187 | −0,03125 | 0,8756 | +1,1536 |
+
+Средний receiver-like BER A/B равен 0,0178% / 52,4169%; средний oracle BER — 0% / 3,4959%. Разрыв receiver-like–oracle у B около 48,92 процентного пункта. Oracle не является packet PASS и не меняет исторический результат Lab054.
+
+## Решения, EVM и margin
+
+Использована модель `r = h*s + e` и формула `EVM_RMS = sqrt(mean(|e|²) / mean(|h*s|²))`. Matched/residual — отношение мощности модельной компоненты к остатку, содержащему шум, ISI и ошибки модели; это не Eb/N0.
+
+| Метрика oracle | A1 | A2 | A mean | B1 | B2 | B mean | B−A |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| BER | 0% | 0% | 0% | 3,2059% | 3,7859% | 3,4959% | +3,4959 п.п. |
+| RMS EVM | 0,3146 | 0,3202 | 0,3174 | 0,8151 | 0,8756 | 0,8453 | +0,5280 |
+| Matched/residual, дБ | 10,0454 | 9,8916 | 9,9685 | 1,7761 | 1,1536 | 1,4648 | −8,5036 |
+| Margin median | 1,0278 | 1,0233 | 1,0256 | 1,0383 | 1,0295 | 1,0339 | +0,0084 |
+| Margin p10 | 0,8134 | 0,7810 | 0,7972 | 0,4456 | 0,4080 | 0,4268 | −0,3704 |
+| Margin p01 | 0,4432 | 0,4030 | 0,4231 | −0,7474 | −0,8916 | −0,8195 | −1,2426 |
+| Eye opening | 2,0110 | 1,9848 | 1,9979 | 2,0221 | 1,9648 | 1,9935 | −0,0044 |
+| ISI ratio, дБ | −34,4848 | −32,1542 | −33,3195 | −30,2664 | −29,9349 | −30,1006 | +3,2189 |
+| H(f) ripple p95−p05, дБ | 0,4274 | 0,3860 | 0,4067 | 4,5321 | 6,4107 | 5,4714 | +5,0647 |
+
+Центры облаков остаются около ±1, поэтому median margin и среднее eye opening почти одинаковы. У B намного шире хвосты: p01 становится отрицательным, что непосредственно соответствует ошибочным решениям. Разделение центров относительно pooled standard deviation снижается с 12,07σ в среднем у A до 3,65σ у B.
+
+![Созвездия A/B](../data/processed/lab058/constellation_a_vs_b.png)
+
+![BER, EVM и matched/residual](../data/processed/lab058/symbol_quality_comparison.png)
+
+## Eye и чувствительность timing
+
+Время нормировано в долях символа, поэтому 400 и 16 отсчётов/символ сравниваются в общей шкале. Среднее падение opening при −0,1/+0,1 символа составляет около 1,98%/1,87% у A и 1,72%/1,78% у B. Сильного дополнительного закрытия eye именно от малого timing offset не видно. У B основная проблема проявляется в разбросе точек и фазе, а не в среднем расстоянии между центрами.
+
+![Eye A](../data/processed/lab058/eye_a.png)
+
+![Eye B](../data/processed/lab058/eye_b.png)
+
+## H(f) и диагностический ISI
+
+H(f) рассчитана как усреднённое `Sxy/Sxx` по Hann-окнам 8192 отсчёта с 50% overlap. Сохранены только bins внутри RRC-полосы и не ниже −20 дБ по TX PSD. У A осталось 27 bins с median coherence 0,903; у B — 516 bins с median coherence 0,551. Робастный p95−p05 amplitude ripple равен 0,407 дБ для A и 5,471 дБ для B. Полный max−min равен 0,791 и 22,962 дБ, но эта крайняя величина чувствительна к отдельным bins, поэтому основным показателем выбран p95−p05. Остаточная phase ripple p95−p05 составляет 0,042 и 0,306 rad. Производная фазы оказалась недостаточно устойчивой по заранее заданному критерию, поэтому variation group delay не объявляется результатом.
+
+Эти данные показывают широкополосную неравномерность всего OTA-тракта B, но средняя coherence B умеренная и тракт не разделён на TX, propagation и RX. Это свидетельство дополнительного частотно-зависимого эффекта, а не доказательство многолучёвости или аппаратной потери HackRF.
+
+Фиксированный МНК-отклик −5…+5 символов дал adjacent/main −33,32 дБ у A и −30,10 дБ у B. ISI у B выше на 3,22 дБ, но абсолютная сумма соседних taps остаётся примерно на 30 дБ ниже главного. Большой адаптивный equalizer не применялся.
+
+![Диагностическая H(f)](../data/processed/lab058/channel_transfer.png)
+
+![Диагностические ISI taps](../data/processed/lab058/diagnostic_isi.png)
+
+## Контроли и энергетическое сравнение
+
+- Сохранённый TX после того же RRC/oracle тракта дал BER 0 для A и B. Остаток цифрового TX-контроля RMS EVM равен 0,01105 / 0,00998; он включает конечные RRC/transient/model effects и не приписывается исключительно int8-квантованию.
+- Synthetic AWGN использовал seed 5801, одинаковые Fs, TX RMS и комплексную дисперсию шума 400 код²/отсчёт. BER остался 0, но EVM ухудшился от 0,02503 до 0,11406, то есть на 13,17 дБ; matched/residual снизился с 32,03 до 18,86 дБ. Направление и масштаб совместимы с падением энергии символа −13,870505 дБ. Это контроль формул, не модель, подогнанная к OTA, и не доказательство AWGN-природы реального канала.
+- Фоновое окно до ABAB дало receiver-like/oracle BER 50,31% / 50,35% и oracle training coherence `4,50e−5`: оно не выглядит как качественный BPSK.
+
+В реальной записи ухудшение EVM B/A равно 8,51 дБ, меньше энергетических 13,87 дБ, поскольку A уже имеет собственный остаточный floor. По одной OTA-записи нельзя разложить остаток на шум и искажения единственным способом.
+
+## Повторяемость и вывод
+
+A1/A2 устойчивы по главным метрикам: BER 0/0, EVM различается на 0,0056 (0,15 дБ), matched/residual — на 0,15 дБ, eye opening — на 0,114 дБ. Диагностический ISI ratio расходится на 2,33 дБ при малом абсолютном уровне соседних taps.
+
+B1/B2 повторяют основной эффект: oracle BER 3,2059% / 3,7859%, EVM отличается на 0,0606 (0,62 дБ), matched/residual — на 0,62 дБ, eye opening — на 0,25 дБ, ISI ratio — на 0,331 дБ. Ripple H(f) расходится на 1,88 дБ, что ограничивает точность его единственной OTA-оценки, но оба повтора намного менее плоские, чем A.
+
+Основная классификация — **MIXED**:
+
+1. Уменьшение энергии символа совместимо с ухудшением EVM и matched/residual B.
+2. В широком B-диапазоне видна дополнительная неравномерность всего OTA-тракта, однако её источник и точная доля не локализованы.
+3. Самая большая практическая потеря возникает в текущей carrier synchronization: receiver-like B почти случаен, тогда как oracle B сохраняет BER 3,5%.
+
+Следующий один этап рекомендуется сделать полностью офлайн: проверить исправленный preamble-only CFO/carrier estimator на сохранённых Lab056 A1/B1/A2/B2, Lab054 и TX/AWGN/background controls, требуя приблизить receiver-like B к oracle без регрессии A и без использования payload truth в оценивателе. Lab059 в этой работе не создаётся.
+
+Машинные данные: [summary.json](../data/processed/lab058/summary.json), [segment_metrics.csv](../data/processed/lab058/segment_metrics.csv), [channel_response.csv](../data/processed/lab058/channel_response.csv).
+
+Исторический Lab054 остаётся `NOT_A, 0/16`. RF TX = 0. Lab058 не закоммичена, push не выполнялся.