Добавлена документация для трекинга комплексных и целочисленных фильтров IQ-потоков, включая цели, этапы и технические риски

Author: Infarh

docs/IQFiltersTracking.md

@@ -0,0 +1,217 @@
+# Трекинг: комплексные и целочисленные фильтры для IQ-потоков
+
+## Цель
+Реализовать полноценную линейку IQ-фильтров для:
+- комплексных потоков
+- целочисленных потоков формата HackRF One (interleaved int8 I/Q)
+- целочисленных потоков формата USRP B210 (interleaved int16 little-endian I/Q)
+
+С обязательным повторением существующей методики:
+- расчёт коэффициентов (как в текущих FIR/IIR/семействах Butterworth/Chebyshev/Elliptic)
+- структура API фильтров
+- система модульных тестов и проверок устойчивости
+
+## Ключевой принцип внедрения
+Каждый этап должен давать сразу используемый результат (не ждать окончания всей программы работ).
+
+## Область покрытия
+- FIR
+- IIR (включая SOS там, где применимо)
+- Билдеры/спецификации для расчёта коэффициентов
+- Потоковые API (Span/Stream + async)
+- Набор тестов (корректность, стабильность, совместимость форматов)
+
+## Соглашения по форматам
+- HackRF One: interleaved int8, порядок байт I,Q,I,Q...
+- USRP B210: interleaved int16 LE, порядок I,Q,I,Q...
+- Для целочисленных API обязательны:
+  - saturating clamp
+  - явно документированная политика округления
+  - контроль переполнений и формата входа
+
+## Этапы
+
+### Этап 0: Контракт и базовые типы данных (MVP foundation)
+Статус: Planned
+
+Результат этапа:
+- Общие контракты для IQ-фильтров (процессинг одного отсчёта, блока, потока)
+- Типы/адаптеры для complex/int8/int16 IQ-представления
+- Единая политика преобразований int <-> double/complex
+
+Задачи:
+- Ввести интерфейсы (например, IIqFilter<TSample>) без ломки текущего API
+- Зафиксировать соглашения по формату буферов HackRF/B210
+- Добавить вспомогательные конвертеры interleaved <-> sample/span
+
+Критерии готовности:
+- Есть минимальный API для обработки блока IQ-данных трёх типов
+- Есть тесты на конвертацию форматов и граничные случаи буферов
+
+Используемость после этапа:
+- Можно строить пайплайн с уже единым форматом входа/выхода
+
+---
+
+### Этап 1: Комплексный FIR для IQ (первый рабочий фильтр)
+Статус: Planned
+
+Результат этапа:
+- FIR для Complex IQ-потока
+- Поддержка IEnumerable/Span/Stream(опционально)
+
+Задачи:
+- Реализовать ComplexFIR с состоянием
+- Добавить FrequencyResponse и поведение Reset
+- Проверить совпадение с референсом (double FIR на I и Q по отдельности)
+
+Критерии готовности:
+- Точность тестов в рамках заданного eps
+- Нет аллокаций в hot path для Span API
+
+Используемость после этапа:
+- Можно сразу фильтровать комплексный IQ в реальных задачах
+
+---
+
+### Этап 2: Комплексный IIR для IQ + SOS
+Статус: Planned
+
+Результат этапа:
+- IIR для Complex IQ-потока
+- SOS-путь для высоких порядков (аналогично текущему IIR)
+
+Задачи:
+- Реализовать ComplexIIR (direct form + SOS)
+- Повторить методику валидации секций и коэффициентов
+- Сверить выход с референсом (раздельная фильтрация I/Q в double)
+
+Критерии готовности:
+- Устойчивость на длинных прогонах
+- Совпадение амплитудно-частотных и фазовых характеристик с допуском
+
+Используемость после этапа:
+- Комплексные IIR фильтры готовы для production-пайплайнов
+
+---
+
+### Этап 3: Целочисленные FIR/IIR для HackRF One (int8)
+Статус: In progress (частично)
+
+Результат этапа:
+- int8 interleaved IQ фильтрация FIR/IIR
+- in-place и out-of-place блоковые методы
+- stream/sync/async API
+
+Задачи:
+- Довести FIR-покрытие до паритета с IIR
+- Унифицировать состояние и поведение ошибок
+- Документировать политику квантования и клиппинга
+
+Критерии готовности:
+- Полный набор тестов для int8
+- Совпадение с complex/double референсом после квантования
+
+Используемость после этапа:
+- Готовый путь для HackRF RX/TX в raw-буферах
+
+---
+
+### Этап 4: Целочисленные FIR/IIR для USRP B210 (int16)
+Статус: Planned
+
+Результат этапа:
+- int16 LE interleaved IQ фильтрация FIR/IIR
+- API аналогичный HackRF ветке
+
+Задачи:
+- Реализовать обработку int16 LE без лишних копирований
+- Добавить in-place/out-of-place и stream/sync/async
+- Проверить корректность endian и знакового диапазона
+
+Критерии готовности:
+- Проход тестов совместимости формата B210
+- Совпадение с reференсом на эталонных наборах
+
+Используемость после этапа:
+- Готовая интеграция в пайплайн USRP B210
+
+---
+
+### Этап 5: Расчёт коэффициентов для IQ-линейки (паритет с текущими фильтрами)
+Статус: Planned
+
+Результат этапа:
+- Повторена вся методика расчёта коэффициентов для IQ-линейки
+- Билдеры/спецификации возвращают варианты для complex/int8/int16 обработки
+
+Задачи:
+- Переиспользовать текущие формулы и билдеры, не дублируя логику
+- Добавить фабрики/адаптеры для целевого типа потока
+- Ввести проверку соответствия коэффициентов между ветками
+
+Критерии готовности:
+- Для каждого семейства фильтров коэффициенты совпадают с базовой веткой
+- Тесты регрессии на коэффициенты стабильны
+
+Используемость после этапа:
+- Полноценный расчёт и создание нужного IQ-фильтра из одного DSL
+
+---
+
+### Этап 6: Полная тестовая матрица и регрессия
+Статус: Planned
+
+Результат этапа:
+- Единая система модульных тестов для всех представлений сигнала
+
+Подсистемы тестирования:
+- Unit: корректность Process/Reset/State
+- Golden vectors: фиксированные входы/выходы
+- Property-based: инварианты (линейность, нулевая реакция, boundedness)
+- Stability/long-run: длинные последовательности, дрейф и overflow
+- Format tests: interleaved/endianness/odd-length/partial-read
+- Cross-check: complex vs double(I/Q), int vs quantized reference
+
+Критерии готовности:
+- Покрытие критичных веток не ниже целевого порога
+- Отсутствие флаки-тестов
+- Отдельные профили тестов: fast/extended
+
+Используемость после этапа:
+- Надёжная база для дальнейшего развития и рефакторинга
+
+## Декомпозиция по релизам (предлагаемый порядок)
+1. R1: Этап 0 + Этап 1
+2. R2: Этап 2
+3. R3: Этап 3 (доведение до полного паритета)
+4. R4: Этап 4
+5. R5: Этап 5 + Этап 6
+
+## Технические риски и меры
+- Риск: расхождение результатов между complex и int ветками
+  - Мера: единый reference pipeline + golden vectors
+- Риск: нестабильность IIR высоких порядков
+  - Мера: обязательный SOS путь и long-run тесты
+- Риск: overhead от конвертаций
+  - Мера: Span/in-place API и профилирование hot path
+- Риск: ошибки формата USRP LE
+  - Мера: отдельный набор тестов на endian/знак/границы
+
+## Definition of Done (для каждого этапа)
+- Реализован API и минимум один рабочий сценарий использования
+- Добавлены и проходят модульные тесты этапа
+- Обновлена документация с примерами
+- Нет регрессий в уже реализованных этапах
+
+## Трекер задач (чеклист)
+- [ ] Этап 0: контракты и базовые адаптеры
+- [ ] Этап 1: Complex FIR
+- [ ] Этап 2: Complex IIR + SOS
+- [ ] Этап 3: HackRF int8 FIR/IIR (паритет)
+- [ ] Этап 4: USRP B210 int16 FIR/IIR
+- [ ] Этап 5: коэффициенты/билдеры IQ-линейки
+- [ ] Этап 6: полная тестовая матрица
+
+## Примечание по текущему состоянию
+Уже реализованы части этапа 3 для IIR (включая interleaved, stream sync/async). Нужно довести FIR-паритет и встроить в общий трек этапов 0/5/6.