Kshana — Architectuur

Kshana is één engine, in lagen georganiseerd boven een gedeelde kern: de sensorpakketten (klok, inertiaal, tijdoverdracht, hybride); een laag voor astrodynamica / numeriek (analytische SGP4/SDP4 (SGP4: Simplified General Perturbations 4; SDP4: Simplified Deep-space Perturbations 4), een numerieke Cowell-propagator met zijn krachtmodel van zeven verstoringen, manoeuvreontwerp, baanbepaling uit afstanden van grondstations en de fit van het krachtmodel aan precieze efemeriden van instanties); een laag voor tijd en referentiestelsels (IERS-tijdschalen (International Earth Rotation and Reference Systems Service), IAU-precessie–nutatie (International Astronomical Union) 2006/2000A en de CIO-reductie (Celestial Intermediate Origin) GCRS↔ITRS (GCRS: Geocentric Celestial Reference System; ITRS: International Terrestrial Reference System)); een fusielaag (de GNSS/INS-schatters (GNSS: global navigation satellite system; INS: inertial navigation system)); en de lagen voor integriteit, veerkracht, alt-PNT (PNT: positiebepaling, navigatie en tijdsynchronisatie) en maan (RAIM/ARAIM/SBAS (RAIM: receiver autonomous integrity monitoring; ARAIM: advanced receiver autonomous integrity monitoring; SBAS: satellite-based augmentation system), jamming en spoofdetectie in meerdere lagen, map-matching op zwaartekracht/terrein/magnetisme en cislunaire PNT); en de nieuwere lagen LEO-PNT (PNT in een lage baan om de aarde), spectrum, zonnestelsel en constellatieontwerp, nettijdsynchronisatie en campagne, met de rapport-, animatie- en interoperabiliteitsschrijvers die elke run kan gebruiken (§1d). Over al deze lagen heen weet de engine niets van „kwantum” tegenover „klassiek”: hij stuurt foutmodellen van sensoren door een GNSS-uitvalscenario, voert een schatter uit en scoort de uitkomst. Een kwantumapparaat en een klassiek apparaat worden dus op hetzelfde scenario vergeleken, en verschillen alleen in hun (gepubliceerde, geciteerde) foutparameters en hun onafhankelijke ruisseeds.

Dit document verzamelt de structurele en gedragsdiagrammen. §1 is de kern met sensorpakketten; §1a brengt de sindsdien toegevoegde lagen voor astrodynamica, fusie en alt-PNT in kaart; §1b–§1d de studie-, domein- en uitvoerlagen. Voor gebruik zie de README; voor wat wel en niet is getoetst zie VALIDATION; voor de rijpheidstabel per mogelijkheid zie CAPABILITY.

Afkortingen die in de diagrammen worden gebruikt en niet worden uitgeschreven waar ze voorkomen: ADEV, Allan-deviatie; BW, bandbreedte; CAI, koudeatoom-interferometer; CZML, de Cesium Language; Δ-DOR, delta differential one-way ranging; DO-229E, de SBAS-ontvangerstandaard van de RTCA (Radio Technical Commission for Aeronautics); EKF, extended Kalman-filter; FM, frequentiemodulatie; GSE, grondondersteuningsapparatuur; HPL/VPL, horizontaal/verticaal beschermingsniveau; IMU, inertiële meeteenheid; IOAG, Interagency Operations Advisory Group; IQ, in-phase/quadrature-samples; ISL, inter-satellietverbinding; ITU-T, de Telecommunication Standardization Sector van de International Telecommunication Union; J2–J6, de zonale zwaartekrachtharmonischen van de aarde van graad 2 tot 6; KIF, het Kshana Interchange Format; KML, Keyhole Markup Language; KPI, kritieke prestatie-indicator; L1/L5, GNSS-draaggolfbanden (de L2 van de CR3BP-halobanen is in plaats daarvan het Lagrangepunt 2 van aarde–maan); LEO, lage baan om de aarde; LOO, leave-one-out; LTC, Coordinated Lunar Time; MEO, middelhoge baan om de aarde; MTIE, maximale tijdintervalfout; N2, het Hill-diversiteitsgetal van orde 2; NED, noord-oost-omlaag; NTN, niet-terrestrisch netwerk; OD, baanbepaling; OPS-SAT, de in-orbitsoftwarelaboratoriumsatelliet van de European Space Agency; PPP, precise point positioning; PSD, vermogensspectrale dichtheid; PVT, positie, snelheid en tijd; RINEX, Receiver Independent Exchange Format; RK4 / RK5(4), Runge–Kutta-integratoren van de vierde orde en ingebed vijfde(vierde) orde; SH, bolfunctieharmonische; SigMF, Signal Metadata Format; SIR, sampling importance resampling; SRIF, square-root information filter; SRP, zonnestralingsdruk; SSC, spectrale scheidingscoëfficiënt; STK, Systems Tool Kit; SVG, Scalable Vector Graphics; TDEV, tijdsdeviatie; TDM, het Tracking Data Message van de CCSDS (Consultative Committee for Space Data Systems); TLE, two-line element set; TPL, Timing Protection Level; UBX, het binaire protocol van u-blox; UHF, ultrahoge frequentie; VLBI, interferometrie met zeer lange basislijn; VRW / ARW, velocity / angle random walk; WASM, WebAssembly.

---

1. Modulestructuur#

flowchart TD
    main["main.rs<br/>CLI (thin wrapper)"]
    py["python.rs<br/>PyO3 (feature)"]
    wasm["wasm.rs<br/>wasm-bindgen (feature)"]
    api["api.rs<br/>run_toml: parse · dispatch by kind · json+svg+summary"]

    subgraph shared["Shared core"]
      types["types.rs<br/>Seconds · TimeGrid · ModelSpec"]
      scenario["scenario.rs<br/>GnssState · GnssTimeline · ClockCfg · Scenario"]
      allan["allan.rs<br/>overlapping Allan deviation"]
    end

    subgraph pack1["Pack 1 · Clock holdover"]
      models["models.rs<br/>ErrorModel · ClockModel (incl. flicker FM)"]
      estimator["estimator.rs<br/>HoldoverEstimator"]
      kalman["kalman.rs<br/>KalmanClock → Integrity bound"]
      security["security.rs<br/>clock-aided spoof detection → Security"]
      fom["fom.rs<br/>Sample · FoMScores · score · worst_case_holdover"]
      report["report.rs<br/>RunResult · hash · to_svg"]
      run["run.rs<br/>run / run_clock / run_orbit_clock"]
    end

    inertial["inertial/<br/>Pack 2 · AccelModel (accel + gyro + bias instability/RW) · run_inertial · quantum_imu CAI + QuantumNavBudget dead-reckoning-over-holdover"]
    timetransfer["timetransfer.rs<br/>Pack 3 · TimeTransferLink · run_timetransfer"]
    hybrid["hybrid.rs<br/>Pack 4 · run_suite · score_hybrid · run_hybrid (+ integrity/security)"]
    fusion["fusion/<br/>joint Kalman PNT estimator · run_fusion"]
    orbit["orbit.rs<br/>Propagator (Kepler | SGP4) · Walker / TLE / multi-constellation · visibility · DOP"]
    tle["tle.rs<br/>two-line element parsing (line 2 → Kepler, full TLE → SGP4)"]
    sgp4mod["sgp4.rs<br/>SGP4 / SDP4 propagator (deep-space + resonance)"]
    ensemble["ensemble.rs<br/>Monte Carlo confidence bands"]
    sweep["sweep.rs<br/>trade-study parameter sweeps"]
    spoof["spoof.rs<br/>active spoofing-attack demonstrator"]
    jamming["jamming.rs<br/>link-budget anti-jam C/N₀ (J/S · processing gain · Q)"]
    navsignal["navsignal.rs<br/>signal level: BPSK-R / BOC PSD · SSC κ · Gabor BW · DLL jitter · multipath · ranging-code (m-seq/Gold) design-trade"]
    holdover["holdover.rs<br/>GNSS-denied clock holdover: van-Loan coast → holdover-to-threshold · quantum-clock classes"]
    verification["verification.rs<br/>machine-checked requirement→module→test→oracle→status matrix"]

    main --> api
    py --> api
    wasm --> api
    api --> run
    api --> inertial
    api --> timetransfer
    api --> hybrid
    api --> ensemble
    api --> sweep
    api --> fusion
    api --> spoof
    spoof --> security
    api --> jamming
    api --> holdover
    api --> verification
    navsignal -. derives anti-jam Q (κ → Q=1/(R_c·κ)) .-> jamming
    jamming -. uses PSD / SSC .-> navsignal
    holdover -. coast-variance vs van-Loan recursion .-> kalman
    ensemble --> run
    sweep --> run
    orbit --> tle
    tle --> sgp4mod
    orbit -. SGP4 propagator .-> sgp4mod
    fusion -. composes .-> models
    fusion -. composes .-> inertial
    fusion --> kalman

    run --> models
    run --> estimator
    run --> kalman
    run --> security
    run --> fom
    run --> report
    run --> orbit
    models --> types
    scenario --> types
    inertial --> scenario
    timetransfer --> types
    orbit --> scenario
    hybrid -. composes .-> models
    hybrid -. composes .-> estimator
    hybrid -. composes .-> inertial
    hybrid -. composes .-> timetransfer
    pack1 --> shared
    inertial --> allan

De CLI (opdrachtregelinterface) en beide bindings lopen via één toegangspunt api::run_toml, zodat ze nooit uiteenlopen. De pakketten hergebruiken de gedeelde kern (types, scenario, allan); Pack 4 (hybrid) stelt de modellen en schatters van Packs 1–3 samen in plaats van ze opnieuw te implementeren; orbit leidt een GNSS-tijdlijn af uit geometrie die dan de run van Pack 1 voedt. De module navsignal zit op signaalniveau tussen het linkbudget en het meetdomein: zij leidt de spectrale scheidingscoëfficiënt κ af uit de werkelijke vermogensspectra van signaal en jammer, waaruit jamming nu zijn anti-jam-Q = 1/(R_c·κ) berekent in plaats van een representatieve constante te nemen (gecontroleerd in CI (continue integratie)); zij bevat ook de ontwerpafweging voor de rangeringscode (m-sequentie/Gold).

Drie verdere modules vormen de ruggengraat van veerkracht bij GNSS-uitval. holdover beantwoordt rechtstreeks de operationele vraag — hoe lang kan deze klok vrij lopen voordat zijn tijdfout het budget overschrijdt? — door de gesloten vorm van de van-Loan-coastfout beschikbaar te stellen als inversie van holdover naar drempel, gecontroleerd tegen de meerstaps-covariantierecursie van clock_state. Haar inertiële tegenhanger staat in inertial::quantum_imu (QuantumNavBudget), die de witte-ruisdrift van de koudeatoom-interferometer samenstelt met bias- en schaalfactorfout tot een budget voor positiedrift over holdover (de biasterm is gecontroleerd tegen de onafhankelijke AccelModel-integrator). verification toont de hele matrix van de engine, van eis naar module naar test naar onafhankelijke referentie naar status, met unit-geteste invarianten die een label getoetst zonder onafhankelijke externe referentie verbieden — zodat de zekerheidsbewering niet van de code kan afdrijven.

1a. Lagen voor astrodynamica, fusie en alt-PNT#

Naast de kern met sensorpakketten delen drie subsystemen dezelfde gedeelde kern en voeden ze orbit (of worden erdoor gevoed). De laag voor astrodynamica / numeriek voegt een niet-analytische Cowell-propagator toe naast het analytische pad SGP4/SDP4; de fusielaag bevat de GNSS/INS-schatters; en de alt-PNT-laag is matching van zwaartekrachtkaarten zonder GPS (GPS: Global Positioning System). Dit zijn bibliotheek-/scenariomogelijkheden (zie CAPABILITY voor welke aan een scenario-kind zijn gekoppeld en welke bereikbaar zijn als Rust-API (application programming interface)).

flowchart TD
    subgraph astro["Astrodynamics & numerical"]
      orbit2["orbit · sgp4 · tle · walker<br/>analytic SGP4/SDP4 · Walker design"]
      prop["propagator<br/>Cowell driver (accel_at / accel_rv)"]
      forces["forces<br/>two-body · J2–J6 · EGM2008 d/o-70 · 3rd-body · SRP · drag · Schwarzschild + Lense–Thirring · tides"]
      integ["integrator<br/>RK4 step-doubling · Dormand–Prince RK5(4)"]
      ephem["ephem<br/>low-precision Sun & Moon"]
      man["maneuver<br/>impulsive/finite burns · Izzo Lambert · porkchop"]
      od["orbit_determination<br/>Gauss–Newton batch (batch_ls) · sequential UKF"]
    end
    subgraph fusion["Fusion (GNSS/INS)"]
      ekf["fusion/gnss_ins_ekf · closed_loop · pack<br/>15-state loosely-coupled EKF"]
      tc["fusion/tightly_coupled (8-state)<br/>fusion/tightly_coupled17 (17-state, quantum-CAI)"]
      ukf["fusion/ukf — sigma-point core"]
      coup["fusion/coupled — clock+position cross-covariance"]
    end
    subgraph alt["Alt-PNT (GPS-denied)"]
      grav["gravimeter<br/>cold-atom model + SH anomaly field + mascons"]
      pf["particle_filter — SIR"]
      mm["mapmatch — field-match likelihood"]
    end
    prop --> forces
    prop --> integ
    forces --> ephem
    man --> integ
    od --> forces
    od --> integ
    od --> ukf
    tc --> ukf
    tc -. coasts on .-> forces
    grav --> pf
    mm --> pf
    grav --> mm
    ekf -. drives .-> strap["inertial/ strapdown (quaternion · NED · IMU errors)"]
    tc -. drives .-> strap
    grav -. CAI floor .-> strap

De krachttermen van de numerieke propagator staan standaard uit, zodat het inschakelen ervan de vrijgegeven golden-bestanden nooit verstoort. De strak gekoppelde UKF (unscented Kalman filter) met 17 toestanden overbrugt een GNSS-uitval op de afgeleide velocity-random-walk van de kwantum-CAI-versnellingsmeter; baanbepaling hergebruikt dezelfde forces/integrator om een kandidaattoestand over de trackingboog te propageren.

Dezelfde gedeelde kern bevat ook vier verdere subsystemen die hierboven niet zijn getekend (hun pakketten staan in de dispatch van §4): een laag voor tijd en referentiestelsels (timescales, jd2, precession, nutation, cio, frames, eop) die TEME↔GCRS↔ITRS (TEME: true equator, mean equinox) reduceert en het pakket ephemeris/grondspoor voedt; een laag voor integriteit (raim, sbas) voor RAIM/ARAIM/SBAS; een laag voor veerkracht (jamming, spoof, spoof_detect, spoof_monitors, detection) voor jamming en spoofdetectie in meerdere lagen, met een laag voor navigatiesignalen (navsignal) op signaalniveau — vermogensspectrale dichtheden van BPSK-R (BPSK: binary phase-shift keying) / sinus-BOC (BOC: binary offset carrier), de spectrale scheidingscoëfficiënt κ die nu de anti-jam-Q van jamming afleidt, de RMS-rangeringsbandbreedte (Gabor), de jitter van de coherente early–late-DLL (delay-locked loop) bij codetracking en de omhullende van de multipathfout (analyse van signaalprestaties, niet het ontwerp van RF-payload (RF: radiofrequent)/antennehardware — de rol van een payloadpartner); en een laag voor maan / cislunair (lunar, lunar_frame, lunar_od, cr3bp) voor CR3BP-dynamica (circular restricted three-body problem) — waaronder de toestandsovergangsmatrix van 6×6 en een differentiële corrector met single shooting (cr3bp_jacobian, propagate_state_stm, differential_correct_halo) die echt periodieke halo-/NRHO-banen (NRHO: near-rectilinear halo orbit) levert, en die de gepubliceerde zuidelijke L2-NRHO van 9:2 (de Gateway-baan) reproduceert met periode ≈ 6,57 d / perilune ≈ 3.250 km (gepubliceerd ≈ 6,56 d / ≈ 3.370 km); de selenocentrische MCI/MCMF-transformatie (MCI: Moon-centred inertial; MCMF: Moon-centred, Moon-fixed) van een gecorrigeerde baan en de voortzetting van families blijven vervolgwerk, en de NRHO is een CR3BP-oplossing (circulair, zonder zon), niet getoetst aan een echte LANS/Gateway-efemeride (LANS: Lunar Augmented Navigation Service) — en LunaNet-integriteit. De fit van het krachtmodel aan efemeriden van instanties (precise_od, lunar_od, tides, gravity_sh) en de volledige alt-PNT-veldenset (igrf, altpnt/terrain, gravimeter) completeren de modulelijst; zie CAPABILITY voor de rijpheid per module.

1b. Veerkrachtstudies, evaluatie van machine learning en reproduceerbare artefacten#

Vijf verdere modulegroepen vormen de open, reproduceerbare studielaag achter de onderzoekspapers van het project. Anders dan de scenario-kinds worden deze bereikt als generatoren cargo run --example / --bin die byte-deterministische artefacten schrijven (vaste seeds, vastgelegde engineversie + confighash). Alle zijn MODELLED (synthetische of publieke datasetkalibratie) en dragen eerlijke validatielabels — geen ervan is een certificering.

flowchart TD
    gen["study generators<br/>examples/ · bin/ (cargo run) → byte-deterministic artifacts"]

    subgraph timing["Timing integrity"]
      tplm["tpl<br/>conditional Timing Protection Level: k-σ floor · van-Loan coast · CUSUM"]
    end
    subgraph resilm["Resilience scoring & decision-instability"]
      arch["resilience/arch · score<br/>architecture model + RPCF-aligned scoring"]
      stats["resilience/stats<br/>Dirichlet · Kendall-τ · flip-rate · bootstrap"]
      div["resilience/diversity · timeline<br/>Hill-N2 common-mode collapse · KPIs"]
      study["resilience/study · report · panel<br/>instability study + integrity-hashed assurance report"]
    end
    subgraph aiml["RF-impairment optimism-gap (Machine learning)"]
      ie["impairment_eval<br/>labelled synthetic corpus · ROC/AUC harness"]
      is["impairment_study<br/>13-detector panel · scaling laws · LOO predictor"]
      ml["impairment_ml<br/>logistic-regression + one-hidden-layer MLP"]
      es["eval_stats<br/>bootstrap CI · DeLong · Spearman · ridge"]
      sdrm["sdr · realdata<br/>IQ/IF → E/P/L taps → SQM + ingest adapters"]
    end
    subgraph trade["Quantum-vs-classical"]
      cross["crossover<br/>resilience crossover map under parameter uncertainty"]
      qt["quantum_trade<br/>measured-ADEV holdover benefit vs classical"]
    end

    gen --> timing
    gen --> resilm
    gen --> aiml
    gen --> trade
    tplm -. cross-checked vs .-> recursion["holdover · clock_state · allan"]
    is --> ie
    is --> ml
    is --> es
    ie -. real recordings via .-> sdrm
    cross -. composes .-> packs2["clock · inertial packs"]

• tpl — het conditionele Timing Protection Level: een door holdover beperkte grens voor de niet-gedetecteerde tijdfout onder spoofing, die een k-σ-monitorondergrens, de van-Loan-coastvariantie over de detectielatentie en een CUSUM-tijd tot alarm (cumulative sum) samenstelt; gekalibreerd op een echte opgenomen spoof (JammerTest 2024). Er is geen eindige onvoorwaardelijke grens — de TPL is voorwaardelijk aan het feit dat een onafhankelijke kruiscontrole de aanval detecteert.
• resilience/ — een scoringsengine voor PNT-veerkracht in lijn met raamwerken (categorieën van DHS (Department of Homeland Security) RPCF (Resilient PNT Conformance Framework)) plus een studie naar beslissingsinstabiliteit: een Dirichlet-wegingssimplex, Kendall-τ-rangorde-instabiliteit, de omslagfrequentie van de top-1-winnaar en diversiteitscollaps door common mode (Hill-N2), met een rapport van zekerheid met integriteitshash en 35 met de hand afgeleide oracletests. Zie RESILIENCE-CROSSWALK. Synthetische architecturen in lijn met RPCF v2.0 — een zelfbeoordeling, geen certificering.
• impairment_eval / impairment_study / impairment_ml / eval_stats — de studie naar de optimismekloof bij RF-verstoringen: een gelabeld synthetisch corpus en een detectoronafhankelijk ROC/AUC-harnas (ROC: receiver operating characteristic; AUC: area under the curve), een panel van 13 detectoren (energie/AGC/SQM/pariteit (AGC: automatic gain control; SQM: signal-quality monitoring) plus geseede logistische-regressiedetectoren en detectoren met een MLP van één verborgen laag (MLP: multi-layer perceptron)), schaalwetten binnen en buiten de verdeling met een permutatienulmodel, en een leave-one-out-voorspeller van de achteruitgang buiten de verdeling. De evaluatiemaatstaven zijn bit voor bit getoetst aan scikit-learn.
• sdr / realdata — een front end voor een software-defined receiver (ruwe IQ/IF (IQ: in-phase/quadrature; IF: intermediate frequency) → early/prompt/late-aftakkingen van de correlator → SQM) en inleesadapters (RINEX, u-blox UBX, GnssLogger, JammerTest, Yunnan, SatGrid) waarmee dezelfde detectoren over lokaal aangeleverde opnamen kunnen lopen; er worden geen datasets in de repository vastgelegd.
• crossover / quantum_trade — de kaart van het kruispunt in veerkracht tussen kwantum en klassiek bij parameteronzekerheid, en de afweging van het holdover-voordeel op basis van gemeten ADEV; de numerieke kernels van de afweging zijn getoetst aan scipy.

1c. Lagen voor integriteit, GNSS, diepe ruimte, maan en missies#

De overige domeinen sluiten aan op dezelfde dispatch api en hergebruiken de gedeelde kern, de stelsels en de geometrie. Alles hier is MODELLED tenzij een rij van de verification-matrix een externe onafhankelijke referentie noemt (RAIM-kernel tegen SciPy, SBAS tegen de fork van RTKLIB (een opensourcebibliotheek voor real-time kinematische positiebepaling), de DOP-kernel (dilution of precision) van gnss_lib_py, de OPS-SAT-evaluatie, de ARAIM-beschermingsniveaukernel voor de maan, de consistentie van maanefemeriden tussen aanbieders) — de rest van de maansuite en de kwantumdemonstrator zijn gemodelleerd, illustratief, uit publieke bronnen en dragen geen bewering over TRL (technology readiness level) / heritage / onderschrijving door een instantie.

flowchart TD
    api["api.rs — run_toml / run_scenario · 92 kinds"]

    subgraph gnss["Integrity & GNSS measurement"]
      raim["raim — RAIM/ARAIM · HPL/VPL (kernel vs SciPy)"]
      sbas["sbas — DO-229E PL · L1/L5 (vs RTKLIB fork)"]
      meas["gnss_sim · ionex · pvt · glonass — pseudorange · iono maps · single-point PVT"]
      imp["integrity_impact · frugal — miss→integrity · cost-per-coverage"]
    end

    subgraph deep["Deep-space & Mars"]
      core2["body · ephem_provider · clock_state — multi-body · ephemeris seam · onboard clock"]
      radio["radiometric · ccsds_tdm — light-time · Doppler/range · Δ-DOR · TDM"]
      mars["deepspace_od · mars_frame · mars_atmos · mars_pnt · linkbudget · gse_sim — SRIF OD · Mars frame · relay-PNT · GSE sim"]
    end

    subgraph lunar["Lunar PNT suite (evidence tier per piece in the matrix · illustrative public-source)"]
      cis["cr3bp · lunar · lunar_frame · lunar_od — CR3BP · halo/NRHO · cislunar ARAIM · MCI↔MCMF"]
      suite["lunar_time · lunar_vlbi · lunar_combination · lunar_frame_realise — LTC time · VLBI · joint OD+clock · frame realisation"]
      suite2["lunar_service · lunar_dpnt · lunar_interop — Moonlight service-volume · differential PNT · LunaNet/IOAG interop"]
    end

    subgraph quantum["Quantum-Enabled PNT demonstrator (MODELLED)"]
      qd["quantum_devices · quantum_faults · quantum_nav_od — device error models · fault catalogue · GNSS-free OD"]
      qt["qtrade · timetransfer_chain · representativeness — unified trade · time-transfer chain · gaps-to-flight ledger"]
    end

    subgraph mission["Mission analysis, environment & interop"]
      ma["launch · reentry · eo_payload · attitude_budget · passes · linkbudget — first-order budgets"]
      env["space_weather — Jacchia-71 density"]
      iop["rinex · rinex_obs · sp3 · oem · omm · ccsds_tdm · space_packet · interchange · permalink — interop formats + KIF"]
      ver["verification — requirement→module→test→oracle→status matrix"]
    end

    api --> gnss & deep & lunar & quantum & mission
    raim -. reuses .-> meas
    suite -. reuses validated DOP / SBAS kernels .-> gnss
    qt -. rides validated kernels (scipy / sklearn) .-> quantum

1d. LEO-PNT, spectrum, zonnestelsel, nettijdsynchronisatie, campagnes en uitvoer#

De nieuwste lagen volgen hetzelfde patroon: elk is een of meer scenario-kinds die vanuit api worden verzonden, op de gedeelde kern zijn gebouwd en MODELLED zijn tenzij een matrixrij een externe onafhankelijke referentie noemt.

flowchart TD
    api["api.rs — run_toml / run_scenario"]

    subgraph leo["LEO PNT (low Earth orbit positioning, navigation and timing)"]
      lsig["leo_signal — signal design: acquisition, code tracking, GNSS compatibility, band trade"]
      lpass["leo_pass · leo_link (geometry · antenna · itu · iono · energy · spoof · presets) — pass and per-band link budget"]
      lnav["leo_navmsg (elements · fit · codec · sisre · services · text) — broadcast ephemeris and clock message"]
      lfus["leo_fusion (doppler · joint_pvt · ppp · ntn · timing · polar · presets) — fused MEO+LEO PVT · PPP · 5G NTN"]
      lchain["leo_pnt_chain — one system end to end, each stage handing its output to the next"]
    end

    subgraph rf["Spectrum"]
      spec["spectrum · navsignal — L-band (and UHF/S/C) PSD waterfall under a jammer timeline"]
      sig["sigmf — SigMF recording read/write · Welch PSD of complex IQ"]
    end

    subgraph sky["Solar system & constellations"]
      ss["solar_system · body · ephem · ephem_provider — bodies, constants, light time at one epoch"]
      bp["body_pnt — positioning around any body with a local constellation"]
      cd["constellation · walker — Walker delta/star, multi-shell, published GNSS slots, coverage/DOP maps"]
    end

    subgraph net["Network timing"]
      tel["telecom_timing — time error, MTIE, TDEV vs ITU-T masks"]
      slot["slot_timing — seconds until a free-running clock leaves a slot guard"]
    end

    subgraph comp["Composition & outputs"]
      camp["campaign · study · suite — chained phases, sweeps, Monte Carlo, shared conditions"]
      rep["advanced_report — report.html + report.json with a reproducibility record"]
      anim["animation — SVG / HTML / frame animations"]
      iop["interop (czml · kml · geojson · stk) · sigmf — exchange files for --export"]
    end

    api --> leo & rf & sky & net & comp
    lchain -. composes .-> lsig & lpass & lnav & lfus
    lsig -. SSC chain .-> spec
    lfus -. GNSS presets .-> cd
    bp -. reuses .-> ss
    camp -. runs other kinds through .-> api

Het detail per soort staat in LEO-PNT, LEO-SIGNAL, LEO-PASS, LEO-NAVMSG, LEO-PNT-FUSION, SPECTRUM, CONSTELLATION-DESIGN, TELECOM-TIMING, SLOT-TIMING, CAMPAIGNS, REPORTS, ANIMATION en INTEROP.

1e. Lagen voor ontvangervertrouwen, bewijs, telemetrie, training en compliance (0,35)#

Deze lagen lezen het eigen log van een ontvanger of schrijven bestanden voor andere hulpmiddelen; geen ervan synthetiseert of zendt een radiofrequent signaal uit. Ze staan naast api in plaats van onder de scenariosoorten, behalve receiver-trust zelf, dat een scenariosoort is. Alle zijn MODELLED tenzij een matrixrij een externe onafhankelijke referentie noemt, en de maritieme uitvoer is adviserend, geen typegoedgekeurde navigatieapparatuur.

Integraties voor boten (de Signal K-plugin, de gatemodus van OpenCPN en de referentiebuild) roepen het opdrachtregelprogramma aan; zie MARINE-INTEGRATIONS.

2. Enginepijplijn (per run)#

Elke run laat één sensormodel stap voor stap door het tijdraster lopen: het wordt gedisciplineerd zolang GNSS nominaal is en loopt vrij (holdover / dead-reckoning) tijdens de onderbreking.

flowchart TD
    A["for each time step t"] --> B{"i > 0 ?"}
    B -- yes --> C["model.step(dt, rng)<br/>evolve noise state"]
    B -- no --> D
    C --> D{"GNSS state at t ?"}
    D -- "Nominal" --> E["discipline to truth<br/>(estimator sync / dead-reckoning reset)<br/>error = 0"]
    D -- "Denied/Degraded" --> F["estimator predicts;<br/>error = truth − prediction"]
    E --> G["record Sample(t, error, gnss)"]
    F --> G
    G --> A
    A -. after loop .-> H["score(series, spec)<br/>→ figures of merit"]
    H --> I["assemble Result<br/>(specs · series · FoM · scenario hash)"]

Een scenario doorloopt deze pijplijn twee keer, een keer voor de kwantumsensor en een keer voor de klassieke sensor, met onafhankelijke seeds (classical_seed = seed + 0x9e3779b97f4a7c15), zodat de twee ruisrealisaties ongecorreleerd zijn.

3. De interface van het foutmodel (het uitbreidingspunt)#

Elke sensor implementeert hetzelfde idee: een object met toestand waarvan step() zijn interne stochastische fout laat doorlopen en waarvan de opgebouwde toestand elke tik wordt uitgelezen. Klokken geven de opgebouwde fase vrij; versnellingsmeters geven de dubbel geïntegreerde positie vrij; verbindingen geven jitter per meting vrij.

classDiagram
    class ErrorModel {
      <<trait>>
      +step(dt, rng)
      +spec() ModelSpec
    }
    class ClockModel {
      +y0, q_wf, q_rw, drift, flicker
      +phase() s
      +det_freq()  +drift_rate()
    }
    class AccelModel {
      +bias, q_va, gyro_bias, q_arw
      +pos() m  +theta() rad
      +reset()
    }
    class TimeTransferLink {
      +sigma_j
      +sample(rng) s
    }
    ErrorModel <|.. ClockModel
    ClockModel : white FM + random-walk FM + flicker FM + aging
    AccelModel : accel bias + VRW + gyro bias + ARW (gravity-tilt)
    TimeTransferLink : white timing jitter

ModelSpec { id, kind, provenance, params } gaat mee in het resultaat, zodat elk cijfer in de uitvoer herleidbaar is tot de gepubliceerde bron die in provenance is genoemd.

Naast de analytische HoldoverEstimator draait het klokpakket een Kalman-filter met twee toestanden (fase, frequentie) (KalmanClock) waarvan de procesruis overeenkomt met het referentiemodel. Tijdens het uitlopen door een onderbreking groeit de variantie van de fasefout tot precies q_wf·T + q_rw·T³/3, de analytische holdover-relatie, en de online 1-σ-grens ervan wordt gebruikt om de kwaliteitsmaat Integriteit te vullen (het deel van de samples tijdens de onderbreking waarvan de fout binnen de k-σ-grens blijft).

4. Dispatch (CLI en bindings)#

api::run_toml(src) is het enige ingangspunt: het kijkt naar de kind op het hoogste niveau, deserialiseert het bijbehorende scenario, draait het pakket en geeft { json, svg, summary, csv } terug (csv is alleen aanwezig voor de soorten die een reproduceerbaarheidstabel publiceren). De CLI schrijft die naar bestanden, plus het rapport (report.html, report.json) en eventuele --export- / --animate-uitvoer; de Python- en WebAssembly-bindings geven ze terug aan de host. Eén dispatch, geen afwijking.

flowchart TD
    F["api::run_toml(src) · run_scenario(src)"] --> K{"ScenarioKind::classify<br/>typed · exhaustive · 92 kinds<br/>(absent kind → clock; unknown kind → InvalidInput)"}
    K --> G1["Timing<br/>clock · timetransfer · quantum-time-transfer · telecom-timing · slot-timing"]
    K --> G2["Inertial & fusion<br/>inertial · hybrid · hybrid-ukf · fusion · gnss-ins · quantum-gnss-free-nav · ins-trn-coast · hybrid-optical-rf"]
    K --> G3["Orbit, geometry & positioning<br/>orbit · ephemeris · constellation-design · gnss-sim · pvt"]
    K --> G4["Integrity<br/>integrity · lunar-integrity · araim-reference-check"]
    K --> G5["Resilience & spectrum<br/>jamming · spoof · spoof-detect · quantum-anomaly-detect · tracking-loop · spectrum · conflict-resilience"]
    K --> G6["Alt-PNT (GPS-denied)<br/>gravity-map · terrain-nav · terrain-slam · combined-altpnt"]
    K --> G7["LEO PNT<br/>leo-signal · leo-pass · leo-navmsg · leo-pvt · leo-ppp · ntn-positioning · leo-pnt-chain"]
    K --> G8["Lunar / cislunar suite (MODELLED)<br/>lunar-time-offset · lunar-time-budget · lunar-vlbi · lunar-vlbi-fim · lunar-joint-od-clock<br/>lunar-frame-realisation · lunar-frame-campaign · lunar-llr-datum · realtime-frame-eop<br/>moonlight-service-volume · lunar-differential-pnt · lunar-interop-export · lunar-beacon<br/>lunar-jamming · lunar-attack-surface · earth-gnss-lunar · cislunar-observability · cislunar-arc-recovery"]
    K --> G9["Deep space & solar system<br/>mars-pnt · solar-system · body-pnt"]
    K --> G10["Machine learning & trade<br/>impairment-eval · quantum-trade"]
    K --> G11["Mission analysis & environment<br/>launch-window · reentry · eo-coverage · attitude-budget · aperture-duty-cycle<br/>passes · link-budget · space-packet · space-weather"]
    K --> G12["Trade studies, campaigns & interop<br/>sweep · sweep-nd · campaign · oem-interop"]
    G1 & G2 & G3 & G4 & G5 & G6 & G7 & G8 & G9 & G10 & G11 & G12 --> W["RunOutput { json, svg, summary, csv }<br/>+ SHA-256 scenario_hash"]

De dispatch gebeurt op een getypeerde enum ScenarioKind, uitputtend gematcht (zie de volgende paragraaf), zodat het toevoegen van een pakket een door de compiler gecontroleerde wijziging is. Een ontbrekende kind valt terug op het pakket clock, zodat bestaande scenario's van één soort ongewijzigd worden gedeserialiseerd (serde negeert het veld kind op elke scenariostruct). Een onbekende kind wordt geweigerd met KshanaError::InvalidInput, die de dichtstbijzijnde ingebouwde soort noemt als de naam op een typfout lijkt.

Getypeerde dispatch en de gestructureerde API#

De dispatch gebeurt op een getypeerde enum ScenarioKind, niet op een ruwe stringmatch: ScenarioKind::classify(src) zet het veld kind om in een variant en de dispatcher matcht die uitputtend, zodat het toevoegen van een pakket een door de compiler gecontroleerde wijziging is en geen typefout in een string. Twee getypeerde oppervlakken staan naast de stringteruggevende run_toml (behouden voor de CLI en bestaande bindings):

• run_scenario(src) -> Result<RunOutput, KshanaError>: de getypeerde ingang, met een gestructureerde foutentaxonomie (InvalidInput, NonConvergence, Unsupported, IoError). Elke fout draagt een stabiele kind_tag(), zodat een aanroeper kan vertakken op de foutcategorie in plaats van het bericht te ontleden. De bindings bieden dit aan als error_kind(toml).
• list_scenario_kinds() -> Vec<ScenarioMeta> (en list_scenario_kinds_json(), in de bindings beschikbaar als list_kinds()): programmatische introspectie: naam, beschrijving en verplichte/optionele velden van elke soort, voor automatisch aanvullen in de UI (gebruikersinterface) en in notebooks.

Kshana uitbreiden met een extern pakket#

Een pakket van een derde partij implementeert twee kleine, semver-stabiele traits uit api:

use kshana::api::{ExternalPack, KshanaError, RunOutput, Scenario, ScenarioMeta};

struct MyPack {
    threshold: f64, // the deserialized scenario fields
}

impl Scenario for MyPack {
    fn run(&self) -> Result<RunOutput, KshanaError> {
        // Run the model, then build the unified output envelope.
        Ok(RunOutput {
            json: format!("{{\"threshold\": {}}}", self.threshold),
            svg: String::from("<svg xmlns=\"http://www.w3.org/2000/svg\"/>"),
            summary: format!("my-pack | threshold {}", self.threshold),
            csv: None,
        })
    }
}

impl ExternalPack for MyPack {
    fn kind_name(&self) -> &'static str {
        "my-pack"
    }
    fn meta(&self) -> ScenarioMeta {
        ScenarioMeta {
            name: "my-pack",
            description: "An out-of-tree example pack.",
            required_fields: &["threshold"],
            optional_fields: &[],
        }
    }
}

ExternalPack heeft ook een standaardmethode register_into(&mut PackRegistry), die niets doet tenzij een pakket kiest voor de registry-dispatchaansluiting in src/registry.rs. Het ingebouwde pakket jamming is via Scenario aangesloten als uitgewerkt voorbeeld; pakketten buiten de boom volgen hetzelfde contract zonder de kern te forken (naar het voorbeeld van het uitbreidingspunt ErrorModel in §3, dat de privé-veerkrachtoverlay gebruikt).

Kshana heeft daarom twee stabiele uitbreidingsaansluitingen: voeg een sensor toe door ErrorModel te implementeren (§3), of een heel scenariosoort door Scenario + ExternalPack te implementeren; beide zijn semver-stabiel en geen van beide vereist een fork van de kern:

classDiagram
    class ErrorModel {
      <<trait — sensor seam>>
      +step(dt, rng)
      +spec() ModelSpec
    }
    class Scenario {
      <<trait — pack seam>>
      +run() RunOutput
    }
    class ExternalPack {
      <<trait : Scenario>>
      +kind_name() str
      +meta() ScenarioMeta
    }
    ErrorModel <|.. ClockModel
    ErrorModel <|.. AccelModel
    ErrorModel <|.. TimeTransferLink
    Scenario <|.. ExternalPack
    Scenario <|.. JammingPack : worked example
    ExternalPack <|.. ThirdPartyPack : out-of-tree, no core fork

5. De hybride afsluiter#

Het hybride pakket draait een suite (één klok + één traagheidssensor) en vereist dat zowel tijdsynchronisatie als positie binnen de specificatie blijven; pnt_holdover is de tijd tot een van beide die overschrijdt. Optioneel synchroniseert een optische intersatellietverbinding de klok tijdens de onderbreking opnieuw: alleen tijdondersteuning; de positie wordt niet opnieuw gesynchroniseerd, omdat tijdoverdracht tijd geeft en geen positie. Hierdoor springt de traagheidssensor eruit als beperkende factor.

flowchart LR
    subgraph suite["PNT suite (per technology)"]
      clk["clock → timing error"]
      acc["inertial sensor → position error"]
      isl["optical ISL<br/>re-sync clock at interval"] -. aids .-> clk
    end
    clk --> J["both within spec ?"]
    acc --> J
    J --> P["pnt_holdover = first breach<br/>(timing OR position)"]

6. Uit geometrie afgeleide GNSS-beschikbaarheid#

orbit.rs is een deterministische geometrielaag zonder afhankelijkheden. Een Propagator is ofwel de analytische Kepler-Orbit (twee-lichamen, optioneel met seculiere J2) ofwel een volledige Sgp4-propagator die is opgebouwd uit een complete two-line-elementenset; een Walker-delta-generator maakt synthetische constellaties, en zichtbaarheid in rechte lijn = aardbedekking + elevatiemasker. Het aantal zichtbare satellieten wordt afgebeeld op een GNSS-toestand (≥4 = nominaal, 1–3 = gedegradeerd, 0 = geweigerd), en build_timeline zet dat om in de beschikbaarheidstijdlijn die de standaard klok-holdoverrun aanstuurt. Beschikbaarheid is dus afgeleid uit geometrie in plaats van met de hand opgesteld, terwijl de run, de schatter en de scoring ongewijzigd blijven.

Een constellatie die als volledige TLE's wordt aangeleverd, wordt gepropageerd met het SGP4/SDP4-model in sgp4.rs (getoetst aan de vectoren van AIAA (American Institute of Aeronautics and Astronautics) 2006-6753); elementen met alleen regel 2 blijven het analytische tweelichamenpad volgen. De twee kunnen binnen één constellatieblok worden gemengd.

flowchart LR
    U["user orbit"] --> V
    C["Walker constellation"] --> V["visible_count(t)<br/>occultation + mask"]
    V --> S["gnss_state: ≥4 / 1–3 / 0"]
    S --> T["build_timeline → GnssTimeline"]
    T --> R["run_orbit_clock → clock holdover"]

7. Bindings#

De kern compileert ongewijzigd naar native, naar een Python-extensie en naar WebAssembly. De Python-module (python.rs, PyO3 abi3) en de WebAssembly-module (wasm.rs, wasm-bindgen) zijn optionele, feature-gated afhankelijkheden (--features python / --features wasm): de standaardbuild en de testsuite compileren ze nooit, terwijl de poort voor de audit van afhankelijkheden (cargo deny --all-features) wel hun afhankelijkheidsbomen inspecteert, omdat die crates in het wheel en in het npm-pakket worden meegeleverd. Beide roepen api::run_toml aan, zodat elk oppervlak identieke resultaten geeft. De WebAssembly-module ondersteunt de browser-playground in web/ en exporteert dertien functies: run, run_all (één enginerun die resultaat, grafiek, samenvatting en tabel samen teruggeeft), chart_svg, summary, table_csv, list_kinds, error_kind, version, de codec encode_permalink / decode_permalink voor deelbare URL's (URL: webadres), en de drie exporteurs export_sp3 / export_omm / export_oem achter het exportmenu van de playground. Twee verdere toegangspoorten bereiken dezelfde api: de MCP-server (Model Context Protocol) (mcp/kshana-mcp, een van de workspace uitgesloten rmcp-crate die vijftien tools aanbiedt: run_scenario, list_scenario_kinds, validate_scenario, list_example_scenarios, get_example_scenario, report_scenario, animate_scenario, list_export_formats, export_interop, import_route, export_sp3, export_omm, export_oem, export_table_csv, assess_receiver_log; de twee voorbeeldtools lezen de meegeleverde scenario's via de standaard uitgeschakelde feature bundled-scenarios van de bibliotheek, die alleen deze server inschakelt) en de JetBrains-IDE-plugin (integrated development environment) (ide/jetbrains, een Kotlin-project dat de CLI kshana aanroept in plaats van de bibliotheek te linken).

flowchart LR
    cli["CLI · main.rs<br/>native binary"] --> api
    py["Python · python.rs (PyO3 abi3)<br/>RunOutput class + run · run_full · run_typed · scenario_kinds · list_kinds · validate_toml · error_kind · version"] --> api
    wasm["WebAssembly · wasm.rs (wasm-bindgen)<br/>run · run_all · chart_svg · summary · table_csv · list_kinds · error_kind · version · encode/decode_permalink<br/>export_sp3 · export_omm · export_oem"] --> api
    mcp["MCP server · mcp/kshana-mcp (rmcp)<br/>tools: run_scenario · list_scenario_kinds · validate_scenario<br/>list_example_scenarios · get_example_scenario<br/>report_scenario · animate_scenario<br/>list_export_formats · export_interop · import_route<br/>export_sp3 · export_omm · export_oem · export_table_csv"] --> api
    ide["JetBrains plugin · ide/jetbrains (Kotlin)"] -- spawns process --> cli
    api["api::run_toml / run_scenario / list_scenario_kinds"] --> out["identical { json, svg, summary } on every surface"]

Feature-gating: Python en WASM zijn --features python / --features wasm; de meegeleverde scenariotabel is --features bundled-scenarios (het enige gebruik ervan door de MCP-server); de MCP-server en de kruiscontroles xval/* zijn crates die van de workspace zijn UITGESLOTEN; de IDE-plugin linkt niets: hij draait de CLI.

8. Determinisme en reproduceerbaarheid#

• Alle willekeur loopt per run via één geseede ChaCha8Rng; de volgorde van de stappen ligt vast, dus (scenario, seed, engine version) → identical bits.
• Het resultaat draagt een SHA-256 (SHA: Secure Hash Algorithm) scenario_hash; scripts/check-reproducible.sh draait een referentiescenario twee keer en controleert dat de uitvoer byte-identiek is.
• Dezelfde engine compileert naar native, naar een Python-extensie en naar wasm32-unknown-unknown voor runs in de browser die dezelfde getallen opleveren.

9. Uitgestelde / toekomstige structuur#

De lagen voor astrodynamica, fusie en alt-PNT in §1a (de volledige SGP4/SDP4-propagator, de numerieke Cowell-propagator met zijn krachtenmodel van zeven verstoringen en twee adaptieve integratoren, manoeuvre-/trajectontwerp, baanbepaling, de GNSS/INS-schatters met 15, 8 en 17 toestanden, het gekoppelde klok+positiefilter en matching van zwaartekrachtkaarten) zijn allemaal opgeleverd, samen met de Security-kwaliteitsmaat met een actieve spoof-demonstrator, echte TLE-/multiconstellatiegeometrie, Monte Carlo-banden, afwegingsstudies met sweeps, het afdrukbare HTML-rapport (HyperText Markup Language) met zijn machineleesbare tegenhanger, en de release-/publish-/wheels-/pages-workflows.

Verschillende mogelijkheden die hier eerder als toekomstig werk stonden, zijn inmiddels opgeleverd en worden hierboven of in VALIDATION behandeld: de volledige IAU 2000A-nutatie en de equinoxvrije CIO-reductie GCRS↔ITRS / ITRF (International Terrestrial Reference Frame) (bit voor bit getoetst aan SOFA/ERFA (SOFA: Standards of Fundamental Astronomy; ERFA: Essential Routines for Fundamental Astronomy)), het EGM2008-geopotentiaal (Earth Gravitational Model 2008) tot graad/orde 70, de Lense–Thirring-term voor frame-dragging, vaste-aarde-, oceaan- en atmosferische getijden, een kruisvalidatie van de efemeride op DE-niveau (DE440/ANISE (DE440: Development Ephemeris 440; ANISE: Attitude, Navigation, Instrument, Spacecraft, Ephemeris, een zuivere Rust-toolkit voor planeetgeometrie)), de externe kruisvalidatie met Orekit 12,2 van de numerieke Cowell-propagator (0,08 m over 24 h) en van batch- en sequentiële baanbepaling, en de strak gekoppelde navigator met 17 toestanden, beschikbaar als scenariosoort hybrid-ukf.

De resterende vervolgstappen worden bijgehouden in CHANGELOG [Unreleased] en in de roadmap per mogelijkheid in CAPABILITY: een externe referentiewaarde voor de EGM-evaluator (Earth Gravitational Model) van hoge graad precies op de poolas en een pyshtools-zuivere vergelijking nabij de pool (de evaluator tot graad 2190 en zijn runtime-lader voor .gfc worden opgeleverd, MODELLED; zie xval/high-degree-gravity/), een tijdsvariërende ruimteweerdriver voor het opt-in-niveau van de luchtweerstandsdichtheid van NRLMSISE-00 (NRLMSISE: Naval Research Laboratory Mass Spectrometer and Incoherent Scatter Radar Extended atmosphere model) (de standaarddichtheid is het statische exponentiële model, en de Jacchia-71-dichtheid van de soort space-weather is gekarakteriseerd ten opzichte van NRLMSISE-00 maar niet erdoor vervangen), een externe controle van de opt-in-schaduw met zonneschijfverduistering, strakke koppeling van GNSS/INS met draaggolffase, en een echte EGM2008/EIGEN-zwaartekrachtkaart (EIGEN: European Improved Gravity model of the Earth by New techniques) voor de alt-PNT-matcher.

Een privé-overlayrepo bevat veerkrachtdiepgang die onder exportbeperkingen valt; die sluit aan via dezelfde interface ErrorModel (en het contract ExternalPack in §4) zonder de publieke engine te wijzigen.