tracking-loop (scenario kind)

Scenario kind of the engine v0.38.0, family Jamming, spoofing and the spectrum. Advisory: analysis output from a research and engineering tool, not type-approved navigation equipment and not a safety-of-life service. Every label here is the engine's or the verification matrix's; a kind is MODELLED unless the matrix says otherwise (how a label is earned: the README's Evidence section).

What it does#

Tracking-loop loss of lock: C/N0 -> lock/unlock WITH HYSTERESIS, the time it takes to lose lock, and spoof pull-in as a function of code and carrier offset RATE. The engine's existing denial and capture criteria are ratios on received power (a jammer denies at J/S = 30 dB, a spoofer captures at 3 dB); real loss of lock is not a power ratio, it is where a loop's jitter plus dynamic stress leaves its tracking-threshold budget. Reports (1) carrier (Costas) and code (non-coherent early/late) 1-sigma thermal jitter versus C/N0, squaring loss included, against the stated rules 3sigma_PLL + theta_e <= 45 deg (the 15-degree rule in three-sigma form) and 3sigma_DLL + ramp lag <= d/2 chips; (2) the drop and re-lock C/N0 thresholds with the binding loop named, the re-lock threshold DERIVED from the wider bandwidth a receiver re-pulls-in at rather than asserted, so the hysteresis width must fall between 5log10(ratio) and 10log10(ratio) dB; (3) the declared time to lose lock from a two-threshold lock detector with confirmation dwells driven over a C/N0 ramp, reported separately from the physical phase-escape time (the Viterbi mean time between cycle slips, in log10 s because it spans hundreds of decades); (4) spoof pull-in limits — the largest code slew and carrier Doppler rate a victim's loops can follow, with a map over both axes, because a spoofer that slews faster than these does not capture the loop, it outruns it; and (5) the DENIAL RADIUS the loop dynamics imply reported ALONGSIDE the existing power-ratio radius, never in place of it, with their signed difference as its own named field (denial_radius_delta_km) and a definition beside it. Every emitted numeric field carries a unit and a provenance class. VALIDATED closed forms: the carrier and code jitter expressions, the loop-filter reduction sqrt(2B_nT) and the first-order ramp lag are cross-checked against the engine's own sdr correlator stepped forward on seeded synthetic IF — a different route to the same numbers — to 0.6 %, 3.7 % and 0.17 % respectively, and the modified Bessel I0 behind the cycle-slip time against standard tabulated values to 1e-7. The lower validity limit is asserted, not merely stated: below ~32 dB-Hz at 1 ms the real atan discriminator saturates against its +-pi/2 range and measures less jitter than any linear theory. MODELLED: the loop bandwidths, integration time, correlator spacing, pull-in bandwidth ratio, confirmation dwells, jammer power and antenna gains are representative band figures, not a datasheet. NOT modelled: oscillator (Allan-deviation) and vibration jitter, front-end bandwidth limiting, multipath, AGC dynamics, data-bit-transition loss, external aiding, and any half-cycle correction to the Costas cycle-slip formula. Under loop dynamics spoof capture has no radius at all — the binding constraint is offset rate, not power — so that field is null with a reason rather than a fabricated number. Not a certified receiver-performance product.

One run of scenarios/tracking-loop.toml summarises as: tracking-loop: B_pll 10.0 Hz / B_dll 1.0 Hz, T 1 ms, d 0.50 chip -> drop 25.4744 dB-Hz (carrier binds), relock 27.4413 dB-Hz, hysteresis 1.9669 dB | loss of lock declared 39.101 s into the ramp | denial radius threshold(J/S 30 dB) 127.413 km vs loop dynamics 53.1694 km, delta -74.2438 km | spoof pull-in <= 0.966 chip/s code and 41.45 Hz/s carrier (MODELLED loop, VALIDATED closed forms)

Inputs#

From the schema (kshana kinds --json):

• Required fields: none
• Optional fields: pll_bandwidth_hz, dll_bandwidth_hz, predetection_integration_s, correlator_spacing_chips, carrier_allowance_deg, code_allowance_chips, pullin_bandwidth_ratio, drop_confirm_epochs, relock_confirm_epochs, doppler_rate_hz_per_s, code_slew_chips_per_s, cn0_high_dbhz, cn0_low_dbhz, ramp_duration_s, jitter_table_cn0_dbhz, jammer_power_dbw, jammer_gain_dbi, rx_gain_toward_jammer_db, rx_gain_toward_sat_db, signal_power_dbw, temp_k, freq_hz, chip_rate_hz, jammer_type, q_override, denial_js_threshold_db, capture_js_threshold_db, spoof_code_slew_chips_per_s, spoof_doppler_rate_hz_per_s

The example scenarios/tracking-loop.toml sets, among others:

Run it#

kshana scenarios/tracking-loop.toml

What it gives#

The scalar results of that run, with the units the engine states:

Result label (the engine's): MIXED — VALIDATED loop closed forms, MODELLED loop configuration. The carrier and code thermal-jitter expressions, the loop-filter reduction sqrt(2B_nT) and the first-order ramp lag are cross-checked against the engine's own sdr correlator stepped forward on seeded synthetic IF (a different route

Evidence#

MODELLED: the verification matrix rows that name this kind.

• MODELLED The lunar-jamming report no longer rests its denial contour on one scalar.
• MODELLED Loss of lock computed from loop dynamics instead of a power ratio: carrier (Costas) and code (non-coherent early/late) 1σ thermal jitter against C/N₀ with the squaring loss, against the stated rules 3σ_PLL + θ_e ≤ 45° and 3σ_DLL + ramp lag

The rows the run itself exercised, with the oracle the matrix gives each (the public sources are named there):

• MODELLED Deterministic, scenario-hashed, SBOM + cross-platform golden gates. Oracle (ExternalDataset): SBOM conformance to the official CycloneDX 1.5 JSON Schema (+ valid SPDX identifiers) — an external published standard, zero validation errors over the full dependency graph; the FoM-determinism / byte-reproducibility part remains a pinned self-consistency check, so the row stays MODELLED
• PARTNER Not provided — Kshana models signal performance, not payload/antenna hardware. Oracle (NoneKind): none: a partner-owned discipline, with no module and no test by design
• MODELLED Loss of lock computed from loop dynamics instead of a power ratio: carrier (Costas) and code (non-coherent early/late) 1σ thermal jitter against C/N₀ with the s. Oracle (ReferenceImpl): The engine's own sdr correlator (sdr::correlate / synth_if / CaCode) stepped forward on seeded synthetic IF at a calibrated C/N₀ — a separate code path reaching the same numbers by numerical correlation of sampled IQ rather than by an algebraic jitter expression, so it is a different route and not a restatement — plus standard tabulated modified-Bessel I₀ values for the cycle-slip term. Loop theory per Kaplan & Hegar

Limitations#

What the run's own report says is not modelled or not validated:

• MIXED — VALIDATED loop closed forms, MODELLED loop configuration. The carrier and code thermal-jitter expressions, the loop-filter reduction sqrt(2B_nT) and the first-order ramp lag are cross-checked against the engine's own sdr correlator stepped forward on seeded synthetic IF (a different route to the same numbers), and the modified Bessel I0 against standard tabulated values. MODELLED: the loop bandwidths, integ (result label)
• MODELLED: the loop bandwidths, integration time, correlator spacing, pull-in bandwidth ratio, confirmation dwells, jammer power and antenna gains are representative band figures, not a datasheet. (kind catalogue (kshana kinds --json))
• NOT modelled: oscillator (Allan-deviation) and vibration jitter, front-end bandwidth limiting, multipath, AGC dynamics, data-bit-transition loss, external aiding, and any half-cycle correction to the Costas cycle-slip formula. (kind catalogue (kshana kinds --json))
• Every loop parameter below is a MODELLED representative band figure, not a datasheet. (scenario file comment, line 22)
• --- loop geometry ----------------------------------------------------------------- A 10 Hz Costas carrier loop and a 1 Hz carrier-aided code loop, 1 ms coherent integration (one C/A code period, so no data-bit synchronisation is assumed), narrow 0.5 chip correlator. (scenario file comment, lines 25 to 28)
• Reproducibility & software assurance is MODELLED, not validated: a sub-claim is externally checked, but the whole capability composes modelled pieces, so the capability stays Modelled. (verification matrix (docs/MODELLED-RATIONALE.md))
• Tracking-loop loss of lock and spoof pull-in under interference is MODELLED, not validated: checked against a separate implementation in this same codebase — independent of the unit under test, but not externally authoritative. (verification matrix (docs/MODELLED-RATIONALE.md))

See also#

• Family page: Jamming, spoofing and the spectrum
• All kinds: KINDS.md