Add BOC-aware lock detection and E1C-aided tracking

tests/unit/test_boc_lock_calibration.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import numpy as np
+
+from galileo_rx.diagnostics.boc_lock_validation import (
+    boc11_autocorrelation,
+    boc11_five_tap_shape,
+)
+from galileo_rx.signal_profiles import galileo_e1_profile
+from galileo_rx.signals.code_provider import SyntheticCodeProvider
+
+
+def test_ideal_boc11_shoulder_and_negative_sidelobe_metrics() -> None:
+    profile = galileo_e1_profile()
+    code = SyntheticCodeProvider().primary_code(profile, "E1B", 1)
+    shape = boc11_autocorrelation(code, samples_per_chip=32)
+    taps = boc11_five_tap_shape(shape, np.asarray([0.0, 0.25, 0.5], dtype=np.float64))
+    # Finite-code adjacent-chip cross terms perturb the ideal 0.1/0.84/1/3
+    # values slightly; the classification must remain unchanged.
+    assert 0.08 < taps["legacy_prompt_el_ratio"][1] < 0.12
+    assert 0.80 < taps["main_peak_fraction"][1] < 0.88
+    assert 0.28 < taps["main_peak_coherence"][1] < 0.38
+    assert -0.55 < taps["prompt_amplitude"][2] < -0.45
+    assert abs(taps["main_peak_coherence"][2]) < 1e-12

tests/unit/test_lock_detector.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import numpy as np
 
-from galileo_rx.tracking.lock_detector import LockDetector
+from galileo_rx.tracking.lock_detector import BocLockDetectorConfig, LockDetector
 from galileo_rx.types import CorrelatorOutputs
 
 
@@ -16,3 +16,89 @@ def test_data_lock_detector_ignores_bpsk_transition_but_detects_quadrature_jump(
     detector.update(_correlators(0.0))
     assert detector.update(_correlators(np.pi)).cycle_slip is False
     assert detector.update(_correlators(np.pi + 0.49 * np.pi)).cycle_slip is True
+
+
+def _detector() -> LockDetector:
+    return LockDetector(
+        data_sign_insensitive=True,
+        config=BocLockDetectorConfig(
+            smoothing_epochs=4,
+            confirmation_epochs=2,
+            failure_epochs=3,
+        ),
+    )
+
+
+def _repeat(detector: LockDetector, values: CorrelatorOutputs, count: int):
+    return [detector.update(values) for _ in range(count)]
+
+
+def test_boc_lock_metric_validity_is_separate_from_lock_state() -> None:
+    detector = _detector()
+    statuses = _repeat(detector, _correlators(0.0), 5)
+    assert [status.metric_valid for status in statuses] == [False, False, False, True, True]
+    assert statuses[3].code_locked is False
+    assert statuses[4].code_locked is True
+
+
+def test_boc_quarter_chip_shoulder_does_not_cause_false_unlock() -> None:
+    detector = _detector()
+    centered = CorrelatorOutputs(0.25 + 0j, 0.25 + 0j, 1.0 + 0j, 0.25 + 0j, 0.25 + 0j)
+    _repeat(detector, centered, 8)
+    # Ideal BOC(1,1) at +0.25 chip: one E/L tap is at the main peak,
+    # while P is only 0.25 in amplitude.  The legacy P/E/L ratio is 0.1.
+    shoulder = CorrelatorOutputs(-0.5 + 0j, 1.0 + 0j, 0.25 + 0j, -0.5 + 0j, 0j)
+    statuses = _repeat(detector, shoulder, 12)
+    assert min(status.code_metric for status in statuses) < 0.11
+    assert all(status.code_locked for status in statuses)
+    assert not any(status.side_peak_suspected for status in statuses)
+
+
+def test_boc_outer_tap_side_peak_and_signal_loss_are_detected_after_debounce() -> None:
+    detector = _detector()
+    centered = CorrelatorOutputs(0.25 + 0j, 0.25 + 0j, 1.0 + 0j, 0.25 + 0j, 0.25 + 0j)
+    _repeat(detector, centered, 8)
+    side_peak = CorrelatorOutputs(1.0 + 0j, 0.5 + 0j, 0.25 + 0j, 0j, 0j)
+    side_status = _repeat(detector, side_peak, 8)
+    assert any(status.side_peak_suspected for status in side_status)
+    assert side_status[-1].code_locked is False
+
+    detector = _detector()
+    _repeat(detector, centered, 8)
+    lost = _repeat(detector, CorrelatorOutputs(), 8)
+    assert lost[-1].signal_present is False
+    assert lost[-1].code_locked is False
+
+
+def test_boc_negative_half_chip_prompt_side_peak_is_detected_by_tap_coherence() -> None:
+    detector = _detector()
+    centered = CorrelatorOutputs(-0.25 + 0j, 0.25 + 0j, 1.0 + 0j, 0.25 + 0j, -0.25 + 0j)
+    _repeat(detector, centered, 8)
+    # At +0.5 chip the Prompt is the negative BOC sidelobe. E and L have
+    # opposing signs, so powers alone are ambiguous but Re{(E+L)P*} is zero.
+    half_chip_side = CorrelatorOutputs(0.25 + 0j, 0.25 + 0j, -0.5 + 0j, -0.25 + 0j, 0j)
+    statuses = _repeat(detector, half_chip_side, 8)
+    assert statuses[-1].boc_main_peak_coherence <= 0.15
+    assert statuses[-1].side_peak_suspected is True
+    assert statuses[-1].code_locked is False
+
+
+def test_single_bad_boc_epoch_is_debounced() -> None:
+    detector = _detector()
+    centered = CorrelatorOutputs(0.25 + 0j, 0.25 + 0j, 1.0 + 0j, 0.25 + 0j, 0.25 + 0j)
+    _repeat(detector, centered, 8)
+    side_peak = CorrelatorOutputs(1.0 + 0j, 0.5 + 0j, 0.25 + 0j, 0j, 0j)
+    assert detector.update(side_peak).code_locked is True
+    assert detector.update(centered).code_locked is True
+
+
+def test_invalid_integration_does_not_enter_power_smoother() -> None:
+    detector = _detector()
+    centered = CorrelatorOutputs(0.25 + 0j, 0.25 + 0j, 1.0 + 0j, 0.25 + 0j, 0.25 + 0j)
+    for _ in range(10):
+        status = detector.update(centered, metric_input_valid=False)
+        assert status.metric_valid is False
+        assert status.code_locked is False
+    statuses = _repeat(detector, centered, 5)
+    assert statuses[-1].metric_valid is True
+    assert statuses[-1].code_locked is True