feat(gps): split Doppler paths for ESKF and PPS

soc/software/gps_measurement_python/README.md

@@ -0,0 +1,226 @@
+# GPS code measurement ve DLL kalite modeli
+
+Bu dizin, mevcut firmware/RTL ölçüm yolunu değiştirmeden önce code-phase
+hassasiyeti, DLL jitter telemetrisi, dinamik WLS sigma ve carrier/Doppler
+smoothing seçeneklerini aynı sentetik veri üzerinde karşılaştırır.
+
+Bu genel amaçlı bir RF/GNSS simülatörü değildir. Projeye özgü executable
+tasarım modelidir.
+
+Dizin iki ayrı kararı inceler:
+
+1. Position WLS için C/N0'ın açıklamadığı DLL jitter/variance telemetrisi.
+2. Velocity WLS ve ESKF öncesindeki sabit Doppler IIR'in gürültü-gecikme
+   etkisi.
+
+## Modellenen mevcut mimari
+
+| Proje davranışı | Model |
+|---|---|
+| Normalized early-minus-late DLL discriminator | `rtl_dll_model.rtl_discriminator()` |
+| Signed Q2.13 discriminator quantization | `rtl_dll_model.py` |
+| `LF_code.sv` C1=`21.25`, C2=`0.05712890625` ve Q20 çıkış | `CodeLoopFilterRtl` |
+| 20 adet 1 ms DLL örneği/NAV bit | `synthesize_dll_window()` |
+| Firmware C/N0 IIR, alpha=`0.2` | `ChannelQuality.update()` |
+| URA/elevation/C/N0 position sigma | `firmware_sigma_m(CURRENT)` |
+| ECEF x/y/z + common clock-bias WLS | `firmware_wls()` |
+| 99% chi-square ve en az 7 uyduda leave-one-out FDE | `firmware_wls()` |
+| Position solve periyodu 200 ms | `measurement_scenarios.py` |
+| Doppler IIR alpha=`0.05`, 50 Hz | `doppler_eskf_model.py` |
+| ECEF velocity + common clock-drift WLS | `velocity_wls()` |
+| Velocity WLS periyodu 200 ms | `doppler_eskf_model.py` |
+| TDK 100 Hz IMU process-noise profili | `VelocityBiasEskf` |
+| Velocity 3-DOF `%99.9`, NIS=`16.266236` | `VelocityBiasEskf.update_velocity()` |
+
+Kaynak eşlemeleri:
+
+- `hardware/external/gps/rtl/trck_src/code_loop_discriminator.sv`
+- `hardware/external/gps/rtl/trck_src/LF_code.sv`
+- `hardware/external/gps/rtl/trck_src/NCO_code.sv`
+- `hardware/external/gps/rtl/trck_src/tracking_measurement.sv`
+- `hardware/external/gps/rtl/common/definitions.sv`
+- `soc/software/gps_system/src/gps/gps_tracking_measurement.c`
+- `soc/software/gps_system/src/gps/gps_interrupt_handlers.c`
+- `soc/software/gps_system/src/gps/NavEquations.c`
+
+`REM_CODE_PHASE`, DLL discriminator residual'ı olarak modellenmez. RTL'de bu
+değer code NCO'nun epoch taşma remainder'ıdır. Yeni kalite metriğinin girdisi
+RTL içindeki gerçek signed `dll_error` örnekleridir.
+
+## Karşılaştırılan sigma politikaları
+
+- `current_cn0`: mevcut URA + elevation + C/N0 modeli.
+- `naive_add_dll`: DLL variance'ı bağımsızmış gibi ekler. Nominal durumda aynı
+  thermal jitter'ı iki kere saydığı için negatif kontrol olarak bulunur.
+- `dll_excess`: yalnız ölçülen DLL variance'ın C/N0'dan beklenen variance'ı aşan
+  bölümünü code sigma'ya ekler.
+- `dll_excess_guard`: excess variance'a ek olarak sürekli discriminator mean
+  stress'inde ağırlığı azaltır.
+- `oracle_variance`: sentetik gerçek jitter çarpanını bilir. Ulaşılabilir üst
+  sınırı gösterir; firmware algoritması değildir.
+
+Dinamik model:
+
+```text
+sigma_base^2 = sigma_URA^2 + sigma_elevation^2 + sigma_CN0^2
+ratio = EWMA(measured_DLL_variance / expected_DLL_variance(C/N0))
+
+sigma_dynamic^2 =
+    sigma_URA^2
+  + sigma_elevation^2
+  + sigma_CN0^2 * max(1, ratio)
+```
+
+Bu form C/N0 ile DLL thermal jitter'ını iki kere toplamaz. Yalnızca C/N0
+modelinin açıklayamadığı kanal-bağımlı excess jitter'ı şişirir.
+
+## Senaryolar
+
+- Temiz açık gökyüzü
+- Bütün kanallarda düşük C/N0
+- C/N0'da görünmeyen tek-kanal DLL jitter
+- Bütün kanallarda ortak, C/N0'da görünmeyen DLL jitter
+- Gürültü burst ve recovery
+- Re-lock sırasında DLL mean/jitter stress
+- Düşük-variance stable multipath bias
+- Bias + excess jitter
+- Kötü geometri + gizli jitter
+- İlk başta düşük, sonra iyileşen C/N0
+
+Ayrı 1D model ham code, kör scalar IIR ve Doppler-predicted code smoothing'i
+range-rate adımları ve residual carrier CFO altında karşılaştırır. Carrier
+ölçümleri RTL cadence'i olan 50 Hz'de üretilir ve 200 ms WLS epoch'una kadar
+entegre edilir. Hem raw carrier-rate hem de mevcut firmware'deki
+`GPS_TRACK_DOPPLER_SMOOTH_ALPHA=0.05` çıkışı denenir. Bu ayrım önemlidir:
+PPS datum-drift predictor'u için yararlı olan yavaş Doppler filtresi, ESKF
+velocity veya hızlı code-aiding prediction'ında dinamik lag üretebilir.
+
+## Doppler pre-IIR ve ESKF modeli
+
+`doppler_eskf_model.py`, aynı truth, tracking gürültüsü ve IMU örnekleriyle şu
+dört yolu karşılaştırır:
+
+- Önceki: 50 Hz `alpha=0.05` IIR -> 5 Hz velocity WLS -> ESKF.
+- Ham Doppler -> 5 Hz velocity WLS -> ESKF.
+- C/N0 + düşük-geçiren navigation acceleration ile adaptif IIR -> WLS -> ESKF.
+- Ham Doppler -> RAIM-benzeri leave-one-out robust WLS -> ESKF.
+
+Mevcut `alpha=0.05` tek-kutuplu IIR için 50 Hz'de eşdeğer cutoff yaklaşık
+`0.408 Hz`, zaman sabiti `0.390 s`, DC group delay ise yaklaşık `380 ms`'dir.
+Bu gecikme constant velocity'de görünmez; acceleration sırasında velocity
+measurement innovation'ına doğrudan girer.
+
+ESKF modeli bu karar için gerekli `[velocity, accel-bias]` alt sistemidir.
+Firmware'deki TDK process acceleration noise density `0.025
+m/s2/sqrt(Hz)`, accelerometer bias random walk `0.0015 m/s2/sqrt(s)`, WLS'nin
+gerçek 3x3 covariance'ı, fusion adapter'ın `2/2/3 m/s` ENU velocity sigma
+tabanları ve velocity NIS kapısı kullanılır. Position, attitude, lever-arm ve
+tam 15-state cross-covariance bu modelin kapsamında değildir.
+
+Senaryo matrisi sabit uçuş, airliner/aggressive manevra, düşük C/N0, tek-kanal
+Doppler burst, common receiver clock-drift step, 15 saniye GPS kesintisi ve
+birleşik arıza koşullarını içerir.
+
+20-seed sentetik sonuçların özeti:
+
+- ESKF ham WLS gürültüsünü nominalde yaklaşık `0.416 m/s` 3D RMS'ten `0.190
+  m/s` seviyesine indirir; temporal filtreleme zaten ESKF'de gerçekleşir.
+- Sabit pre-IIR sakin uçuşta `0.182 m/s`, ham yol `0.190 m/s` verir. Airliner
+  manevrasında sabit IIR gecikmesi sonucu `0.416 m/s`, ham yol `0.190 m/s`;
+  aggressive manevrada sırasıyla `0.942 m/s` ve `0.190 m/s` oluşur. Adapter
+  sigma tabanları iki yolu da NIS içinde tutsa bile dinamik lag kalır.
+- Düşük C/N0 manevrasında adaptif taslak en iyi gürültü/gecikme uzlaşmasını
+  verir; eşikleri firmware'e taşımadan önce kart loguyla kalibre etmek gerekir.
+- ESKF yalnız aggregate 3D velocity gördüğünden tek uydu burst'ünün kaynağını
+  ayıramaz. Kanal outlier/FDE işlemi velocity WLS öncesinde yapılmalıdır.
+- Common receiver clock-frequency hatası WLS'nin dördüncü clock-drift state'i
+  tarafından hızdan ayrılır.
+
+Bu sonuçlarla firmware'de ESKF için ham Doppler -> kanal validity/FDE ->
+velocity WLS + covariance -> ESKF yolu uygulanmıştır. Ayrı yavaş-filtered
+Doppler velocity yalnız PPS position-WLS clock-bias datumunun drift predictor'u
+ve PPS kalite metriği için tutulur. Ayrıntılı tablo ve sınırlar
+`output/DOPPLER_ESKF_ANALYSIS.md` içindedir.
+
+## Kurulum ve çalıştırma
+
+Repo içindeki `soc/software` dizininden:
+
+```bash
+python3 -m venv gps_measurement_python/.venv
+gps_measurement_python/.venv/bin/pip install \
+  -r gps_measurement_python/requirements.txt
+gps_measurement_python/.venv/bin/python -m unittest \
+  gps_measurement_python/test_measurement_model.py \
+  gps_measurement_python/test_doppler_eskf_model.py
+gps_measurement_python/.venv/bin/python \
+  -m gps_measurement_python.analyze_measurement_scenarios \
+  --seeds 12 --jobs 4
+gps_measurement_python/.venv/bin/python \
+  -m gps_measurement_python.analyze_doppler_eskf \
+  --seeds 20 --jobs 4
+```
+
+Sistem Python'unda `venv` paketi yoksa bağımlılıklar izole bir target dizinine
+de kurulabilir:
+
+```bash
+python3 -m pip install --target /tmp/gps-measurement-deps \
+  -r gps_measurement_python/requirements.txt
+PYTHONPATH=/tmp/gps-measurement-deps:. python3 \
+  -m unittest gps_measurement_python/test_measurement_model.py
+PYTHONPATH=/tmp/gps-measurement-deps:. python3 \
+  -m gps_measurement_python.analyze_measurement_scenarios \
+  --seeds 12 --jobs 4
+```
+
+Çıktılar `gps_measurement_python/output/` altındadır:
+
+- `scenario_summary.csv`
+- `ANALYSIS.md`
+- `01_position_3d_rms.png`
+- `02_solution_availability.png`
+- `03_noise_burst_transition.png`
+- `04_code_smoothing_cfo.png`
+- `doppler_eskf_summary.csv`
+- `DOPPLER_ESKF_ANALYSIS.md`
+- `05_doppler_eskf_velocity_rms.png`
+- `06_airliner_maneuver_trace.png`
+- `07_outlier_wls_nis.png`
+- `08_low_cn0_wls_vs_eskf.png`
+
+## Kalibrasyon sınırı
+
+Modelde C/N0'dan beklenen normalized discriminator standard deviation'ı
+45 dB-Hz için `0.020` kabul edilir ve firmware ile aynı 20 dB amplitude yasası
+ile ölçeklenir. Bu sayı karttan alınmış bir kalibrasyon değildir.
+
+Karar vermeden önce karttan her kanal için en az şu 50 Hz kayıt alınmalıdır:
+
+```text
+sequence, PRN, C/N0,
+DLL mean, DLL variance, DLL sample count,
+code NCO correction, carrier frequency,
+ABS_SAMPLE, REM_CODE_PHASE, lock
+```
+
+Kayıtlarla `expected_DLL_variance(C/N0)` eğrisi çıkarılmalı; temperature,
+elevation ve lock yaşına göre ayrıştırılmalıdır. Stable multipath, DLL yeni
+denge noktasına oturduğunda düşük variance bırakabilir. Bu durum tek başına
+DLL variance ile çözülemez; ek correlator tap'leri veya correlation-shape
+metriği gerekir.
+
+RTL için en düşük maliyetli keşif arayüzü, her 20 ms NAV-bit penceresinde
+`dll_error` üzerinden aşağıdaki ham istatistikleri biriktirmektir:
+
+```text
+signed sum(error)       : 15 + ceil(log2(20)) = 20 bit
+unsigned sum(error^2)   : 30 + ceil(log2(20)) = 35 bit
+valid sample count      : 5 bit
+```
+
+35-bit kare toplamı APB'de iki 32-bit register ile taşınabilir. Ortalama,
+sample variance, C/N0 expectation ratio ve hysteresis yazılımda hesaplanır.
+Bölme ve square-root RTL'ye konmaz. Bu tuple mevcut measurement sequence,
+C/N0, carrier frequency, `ABS_SAMPLE` ve `REM_CODE_PHASE` ile aynı 20 ms
+snapshot'ta tutulmalıdır.