gps/soc/software/gps_measurement_python/README.md

# 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.