Kshana — Arkitektur

Kshana er én motor organiseret i lag over en fælles kerne: sensorpakkerne (ur, inerti, tidsoverførsel, hybrid); et astrodynamisk / numerisk lag (analytisk SGP4/SDP4 (SGP4: Simplified General Perturbations 4; SDP4: Simplified Deep-space Perturbations 4), en numerisk Cowell-propagator med dens kraftmodel med syv perturbationer, manøvredesign, banebestemmelse ud fra afstande fra jordstationer og tilpasningen af kraftmodellen til agenturers præcise efemerider); et lag for tid og referencesystem (IERS (International Earth Rotation and Reference Systems Service) tidsskalaer, IAU (International Astronomical Union) 2006/2000A præcession–nutation og CIO (Celestial Intermediate Origin) GCRS↔ITRS-reduktionen (GCRS: Geocentric Celestial Reference System; ITRS: International Terrestrial Reference System)); et fusionslag (GNSS/INS-estimatorerne (GNSS: global navigation satellite system; INS: inertial navigation system)); og lagene for integritet, robusthed, alt-PNT (PNT: positionering, navigation og tidssynkronisering) og måne (RAIM/ARAIM/SBAS (RAIM: receiver autonomous integrity monitoring; ARAIM: advanced receiver autonomous integrity monitoring; SBAS: satellite-based augmentation system), jamming og spoof-detektion i flere lag, map-matching mod tyngdekraft/terræn/magnetfelt og cislunar PNT); og de nyere lag for LEO-PNT (PNT fra lav jordbane), spektrum, solsystem og konstellationsdesign, nettidssynkronisering og kampagner med de skrivere til rapporter, animation og interoperabilitet, som enhver kørsel kan bruge (§1d). På tværs af dem alle kender motoren intet til "quantum" mod "klassisk": den driver sensorernes fejlmodeller gennem et GNSS-udfaldsscenarie, kører en estimator og scorer udfaldet. En kvanteenhed og en klassisk enhed sammenlignes derfor på det samme scenarie og adskiller sig kun i deres (offentliggjorte, citerede) fejlparametre og deres uafhængige støj-seeds.

Dette dokument samler de strukturelle og adfærdsmæssige diagrammer. §1 er sensorpakkernes kerne; §1a kortlægger de astrodynamiske lag, fusionslagene og alt-PNT-lagene, der er tilføjet siden; §1b–§1d lagene for studier, domæner og output. Se README for brug; se VALIDATION for, hvad der er og ikke er valideret; se CAPABILITY for modenhedstabellen pr. funktion.

Forkortelser brugt i diagrammerne og ikke skrevet ud, hvor de optræder: ADEV, Allan-deviation; BW, båndbredde; CAI, koldatom-interferometer; CZML, Cesium Language; Δ-DOR, delta differential one-way ranging; DO-229E, RTCA's (Radio Technical Commission for Aeronautics) modtagerstandard for SBAS; EKF, udvidet Kalman-filter; FM, frekvensmodulation; GSE, ground support equipment; HPL/VPL, vandret/lodret beskyttelsesniveau; IMU, inertial måleenhed; IOAG, Interagency Operations Advisory Group; IQ, in-phase/quadrature-sampel; ISL, link mellem satellitter; ITU-T, telekommunikationssektoren i International Telecommunication Union; J2–J6, Jordens zonale tyngdeharmoniske af grad 2 til 6; KIF, Kshana Interchange Format; KML, Keyhole Markup Language; KPI, nøgletal for ydeevne; L1/L5, GNSS-bærebølgebånd (L2 for CR3BP-halobaner er i stedet Jord–Måne-Lagrange-punktet 2); LEO, lav jordbane; LOO, leave-one-out; LTC, Coordinated Lunar Time; MEO, mellemhøj jordbane; MTIE, maksimal tidsintervalfejl; N2, Hill-diversitetstallet af orden 2; NED, nord-øst-ned; NTN, ikke-terrestrisk net; OD, banebestemmelse; OPS-SAT, Den Europæiske Rumorganisations satellit til softwareforsøg i kredsløb; PPP, præcis punktpositionering; PSD, effekttæthedsspektrum; PVT, position, hastighed og tid; RINEX, Receiver Independent Exchange Format; RK4 / RK5(4), Runge–Kutta-integratorer af fjerde orden og indlejret femte(fjerde) orden; SH, kugleflade-harmonisk; SigMF, Signal Metadata Format; SIR, sampling importance resampling; SRIF, kvadratrods-informationsfilter; SRP, solstrålingstryk; SSC, spektral separationskoefficient; STK, Systems Tool Kit; SVG, Scalable Vector Graphics; TDEV, tidsdeviation; TDM, CCSDS' (Consultative Committee for Space Data Systems) Tracking Data Message; TLE, two-line element-sæt; TPL, Timing Protection Level; UBX, u-blox' binære protokol; UHF, ultrahøj frekvens; VLBI, interferometri med meget lang baseline; VRW / ARW, tilfældig gang i hastighed / vinkel; WASM, WebAssembly.

---

1. Modulstruktur#

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

CLI'en (kommandolinjegrænsefladen) og begge bindinger løber gennem ét indgangspunkt api::run_toml, så de aldrig glider fra hinanden. Pakkerne genbruger den fælles kerne (types, scenario, allan); Pakke 4 (hybrid) sammensætter modellerne og estimatorerne fra pakkerne 1–3 frem for at genimplementere dem; orbit udleder en GNSS-tidslinje ud fra geometri, som så fodrer kørslen af Pakke 1. Modulet navsignal ligger på signalniveau mellem linkbudgettet og måledomænet: det udleder den spektrale separationskoefficient κ ud fra de faktiske spektre for signal og jammer, hvoraf jamming nu beregner sin anti-jam-Q = 1/(R_c·κ) frem for at tage en repræsentativ konstant (krydskontrolleret i CI (kontinuerlig integration)); det rummer også designafvejningen for rækkeviddekoden (m-sekvens/Gold).

Tre yderligere moduler udgør rygraden i robusthed uden GNSS. holdover besvarer det operative spørgsmål direkte — hvor længe kan dette ur køre frit, før dets tidsfejl overskrider budgettet? — ved at udstille van-Loan-udtrykket i lukket form for fejl under frit forløb som en inversion fra holdover til tærskel, krydskontrolleret mod den flertrins clock_state-kovariansrekursion. Dets inertielle tvilling findes i inertial::quantum_imu (QuantumNavBudget), som sammensætter koldatom-interferometrets hvide-støjdrift med bias og skalafaktorfejl til et budget for positionsdrift over holdover (bias-leddet krydskontrolleret mod den uafhængige AccelModel-integrator). verification gengiver hele motorens matrix fra krav til modul til test til uafhængig reference til status, med enhedstestede invarianter, der forbyder en valideret-mærkat uden en uafhængig ekstern reference — så påstanden om sikkerhed i beviserne ikke kan glide fra koden.

1a. Lag for astrodynamik, fusion og alt-PNT#

Ud over sensorpakkernes kerne deler tre delsystemer den samme fælles kerne og fodrer (eller fodres af) orbit. Det astrodynamiske / numeriske lag tilføjer en ikke-analytisk Cowell-propagator ved siden af den analytiske SGP4/SDP4-vej; fusionslaget rummer GNSS/INS-estimatorerne; og alt-PNT-laget er map-matching mod tyngdekraften uden GPS (GPS: Global Positioning System). Det er funktioner i biblioteket/scenarierne (se CAPABILITY for, hvilke der er koblet til en scenarietype kind, og hvilke der kan nås som en Rust-API (programmeringsgrænseflade)).

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

Den numeriske propagators kraftled er slået fra som standard, så aktivering aldrig forstyrrer de udgivne golden-filer. Det 17-tilstands tæt koblede UKF (unscented Kalman filter) driver gennem et GNSS-udfald på den afledte tilfældige gang i hastighed fra kvante-CAI-accelerometret; banebestemmelsen genbruger de samme forces/integrator til at propagere en kandidattilstand over sporingsbuen.

Den samme fælles kerne bærer også fire yderligere delsystemer, der ikke er tegnet ovenfor (deres pakker optræder i fordelingen i §4): et lag for tid og referencesystem (timescales, jd2, precession, nutation, cio, frames, eop), der reducerer TEME↔GCRS↔ITRS (TEME: true equator, mean equinox) og fodrer pakken ephemeris/jordspor; et integritetslag (raim, sbas) for RAIM/ARAIM/SBAS; et robusthedslag (jamming, spoof, spoof_detect, spoof_monitors, detection) for jamming og spoof-detektion i flere lag, med et navigationssignallag (navsignal) på signalniveau — effekttæthedsspektre for BPSK-R (BPSK: binary phase-shift keying) / sinus-BOC (BOC: binary offset carrier), den spektrale separationskoefficient κ, der nu udleder anti-jam-Q for jamming,RMS-båndbredden (Gabor) for afstandsmåling, den koherente early–late DLL's (delay-locked loop) jitter i kodesporing og envelopen for multipath-fejl (analyse af signalydelse, ikke design af RF-nyttelast (RF: radiofrekvens) / antennehardware — en nyttelastpartners rolle); og et måne- / cislunarlag (lunar, lunar_frame, lunar_od, cr3bp) for CR3BP-dynamik (circular restricted three-body problem) — herunder 6×6 tilstandsovergangsmatricen og en differentialkorrektor med enkelt skydning (cr3bp_jacobian, propagate_state_stm, differential_correct_halo), der frembringer ægte periodiske halo-/NRHO-baner (NRHO: near-rectilinear halo orbit), som gengiver den offentliggjorte L2-sydlige 9:2 NRHO (Gateway-banen) med periode ≈ 6,57 d / perilun ≈ 3.250 km (offentliggjort ≈ 6,56 d / ≈ 3.370 km); den selenocentriske MCI/MCMF-transformation (MCI: Moon-centred inertial; MCMF: Moon-centred, Moon-fixed) af en korrigeret bane og fortsættelse af familier er fortsat opfølgende arbejde, og NRHO'en er en CR3BP-løsning (cirkulær, uden Solen), ikke valideret mod en reel LANS/Gateway-efemeride (LANS: Lunar Augmented Navigation Service) — og LunaNet-integritet. Tilpasningen af kraftmodellen til agenturers efemerider (precise_od, lunar_od, tides, gravity_sh) og det fulde alt-PNT-feltsæt (igrf, altpnt/terrain, gravimeter) runder modullisten af; se CAPABILITY for modenhed pr. modul.

1b. Robusthedsstudier, evaluering af maskinlæring og reproducerbare artefakter#

Fem yderligere modulgrupper udgør laget for åbne, reproducerbare studier bag projektets forskningsartikler. I modsætning til scenarie-kind-typerne nås disse som cargo run --example / --bin-generatorer, der skriver byte-deterministiske artefakter (faste seeds, registreret motorversion + konfigurations-hash). Alle er MODELLED (syntetisk eller kalibrering til offentligt datasæt) og bærer ærlige valideringsmærkater — ingen af dem er en 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 — det betingede Timing Protection Level: en grænse begrænset af holdover for den uopdagede tidsfejl under spoofing, der sammensætter et k-σ-gulv for monitoren, van-Loan-variansen for frit forløb over detektionsforsinkelsen og en CUSUM-tid til alarm (cumulative sum); kalibreret på en reel optaget spoof (JammerTest 2024). Der findes ingen endelig ubetinget grænse — TPL er betinget af, at en uafhængig krydskontrol opdager angrebet.
• resilience/ — en scoringsmotor for PNT-robusthed afstemt efter rammeværker (DHS (Department of Homeland Security) RPCF (Resilient PNT Conformance Framework) kategorier) plus et studie af beslutningsustabilitet: et Dirichlet-vægtsimpleks, Kendall-τ-rangustabilitet, hyppighed af skift af nr. 1, og fælles diversitetskollaps (Hill-N2), med en integritets-hashet rapport om sikkerhed i beviserne og 35 håndudledte tests mod en uafhængig reference. Se RESILIENCE-CROSSWALK. Syntetiske arkitekturer afstemt efter RPCF v2.0 — en selvvurdering, ikke en certificering.
• impairment_eval / impairment_study / impairment_ml / eval_stats — studiet af optimismegabet ved RF-forringelser: et mærket syntetisk korpus og en detektoragnostisk ROC/AUC-ramme (ROC: receiver operating characteristic; AUC: area under the curve), et panel med 13 detektorer (energi/AGC/SQM/paritet (AGC: automatic gain control; SQM: signal-quality monitoring) plus detektorer med seedet logistisk regression og MLP med ét skjult lag (MLP: multi-layer perceptron)), skaleringslove inden for og uden for fordelingen med en permutationsnulhypotese og en leave-one-out-prædiktor for forringelse uden for fordelingen. Evalueringsmålene er valideret bit for bit mod scikit-learn.
• sdr / realdata — en front end til softwaredefineret modtager (rå IQ/IF (IQ: in-phase/quadrature; IF: mellemfrekvens) → korrelatorens early/prompt/late-aftapninger → SQM) og indlæsningsadaptere (RINEX, u-blox UBX, GnssLogger, JammerTest, Yunnan, SatGrid), der lader de samme detektorer køre over optagelser leveret lokalt; ingen datasæt er committet til repositoriet.
• crossover / quantum_trade — krydsningskortet for robusthed, kvante mod klassisk, under parameterusikkerhed og afvejningen af holdover-fordelen ud fra målt ADEV; afvejningens numeriske kerner er valideret mod scipy.

1c. Lag for integritet, GNSS, dybt rum, måne og mission#

De øvrige domæner kobles til den samme api-fordeling og genbruger den fælles kerne, referencesystemerne og geometrien. Alt her er MODELLED, medmindre en række i verification-matricen henviser til en ekstern uafhængig reference (RAIM-kerne mod SciPy, SBAS mod RTKLIB-forken (et open source-bibliotek til kinematisk positionering i realtid), gnss_lib_py's DOP-kerne (dilution of precision), OPS-SAT-evalueringen, ARAIM-kernen for beskyttelsesniveau på månen, konsistensen mellem leverandørers månefemerider) — resten af månepakken og kvantedemonstratoren er modelleret, illustrativ, baseret på offentlige kilder og bærer ingen påstand om TRL (technology readiness level) / heritage / tilslutning fra et agentur.

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, spektrum, solsystem, nettidssynkronisering, kampagner og output#

De nyeste lag følger samme mønster: hvert er en eller flere scenarie-kind-typer, fordelt fra api, bygget på den fælles kerne og MODELLED, medmindre en matrixrække navngiver en ekstern uafhængig reference.

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

Detaljerne pr. type findes i LEO-PNT, LEO-SIGNAL, LEO-PASS, LEO-NAVMSG, LEO-PNT-FUSION, SPECTRUM, CONSTELLATION-DESIGN, TELECOM-TIMING, SLOT-TIMING, CAMPAIGNS, REPORTS, ANIMATION og INTEROP.

1e. Lag for modtagertillid, evidens, telemetri, træning og compliance (0,35)#

Disse lag læser en modtagers egen log eller skriver filer til andre værktøjer; ingen af dem syntetiserer eller udsender et radiofrekvenssignal. De ligger ved siden af api frem for under scenarietyperne, bortset fra receiver-trust selv, som er en scenarietype. Alle er MODELLED, medmindre en matrixrække navngiver en ekstern uafhængig reference, og de maritime output er vejledende, ikke typegodkendt navigationsudstyr.

Integrationer til både (Signal K-pluginet, OpenCPN i gate-tilstand og referencebygget) kalder kommandolinjeværktøjet; se MARINE-INTEGRATIONS.

2. Motorens pipeline (pr. kørsel)#

Hver kørsel stepper en enkelt sensormodel gennem tidsgitteret, styrer den, så længe GNSS er nominelt, og lader den løbe frit (holdover / dead-reckoning) under udfaldet.

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)"]

Et scenarie kører denne pipeline to gange, én gang for kvantesensoren og én gang for den klassiske sensor, med uafhængige seeds (classical_seed = seed + 0x9e3779b97f4a7c15), så de to støjrealiseringer er ukorrelerede.

3. Fejlmodelgrænsefladen (udvidelsespunktet)#

Enhver sensor implementerer den samme idé: et tilstandsfuldt objekt, hvis step() fremfører dets interne stokastiske fejl, og hvis akkumulerede tilstand aflæses i hvert tick. Ure udstiller akkumuleret fase; accelerometre udstiller dobbeltintegreret position; forbindelser udstiller jitter pr. måling.

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 } følger med ind i resultatet, så hvert tal i outputtet kan spores til den publicerede kilde, som er angivet i provenance.

Ved siden af den analytiske HoldoverEstimator kører urpakken et Kalman-filter med to tilstande (fase, frekvens) (KalmanClock), hvis processtøj svarer til sandhedsmodellen. Under frit løb gennem et udfald vokser dets fasefejlvarians til præcis q_wf·T + q_rw·T³/3, den analytiske holdover-relation, og dets online 1-σ-grænse bruges til at udfylde kvalitetsmålet Integritet (andelen af udfaldets sampler, hvor fejlen holder sig inden for k-σ-grænsen).

4. Dispatch (CLI og bindinger)#

api::run_toml(src) er det eneste indgangspunkt: den kigger på det øverste kind, deserialiserer det tilsvarende scenarie, kører pakken og returnerer { json, svg, summary, csv } (csv er kun med for de typer, der udgiver en reproducerbarhedstabel). CLI'en skriver dem til filer, plus rapporten (report.html, report.json) og eventuelt output fra --export / --animate; Python- og WebAssembly-bindingerne returnerer dem til værten. Én dispatch, ingen afdrift.

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"]

Dispatch sker på en typet enum ScenarioKind, som matches udtømmende (se næste underafsnit), så tilføjelse af en pakke er en ændring, der kontrolleres af compileren. Et manglende kind falder tilbage på pakken clock, så eksisterende scenarier med én type deserialiseres uændret (serde ignorerer feltet kind på hver scenariestruktur). En ukendt kind afvises med KshanaError::InvalidInput, som nævner den nærmeste indbyggede type, når navnet ligner en tastefejl.

Typet dispatch og det strukturerede API#

Dispatch sker på en typet enum ScenarioKind, ikke på et råt strengmatch: ScenarioKind::classify(src) afgør feltet kind til en variant, og dispatcheren matcher på den udtømmende, så tilføjelse af en pakke er en ændring, der kontrolleres af compileren, ikke en tastefejl i en streng. To typede flader ligger ved siden af den strengreturnerende run_toml (bevaret til CLI'en og eksisterende bindinger):

• run_scenario(src) -> Result<RunOutput, KshanaError> — den typede indgang med en struktureret fejltaksonomi (InvalidInput, NonConvergence, Unsupported, IoError). Hver fejl bærer en stabil kind_tag(), så en kalder kan forgrene sig på fejlkategorien i stedet for at parse meddelelsen. Bindingerne udstiller den som error_kind(toml).
• list_scenario_kinds() -> Vec<ScenarioMeta> (og list_scenario_kinds_json(), udstillet i bindingerne som list_kinds()) — programmatisk introspektion: hver types navn, beskrivelse og påkrævede/valgfrie felter, til autofuldførelse i brugerflader og notebooks.

Udvidelse af Kshana med en ekstern pakke#

En tredjepartspakke implementerer to små, semver-stabile traits fra 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 har også en standardmetode register_into(&mut PackRegistry), som ikke gør noget, medmindre en pakke vælger at bruge registrets dispatch-søm i src/registry.rs. Den indbyggede pakke jamming er koblet ind gennem Scenario som gennemarbejdet eksempel; pakker uden for træet følger den samme kontrakt uden at forke kernen (efter samme mønster som udvidelsespunktet ErrorModel i §3, som det private robusthedsoverlay bruger).

Kshana har derfor to stabile udvidelsessømme — tilføj en sensor ved at implementere ErrorModel (§3), eller tilføj en hel scenarietype ved at implementere Scenario + ExternalPack — begge semver-stabile, og ingen kræver en fork af kernen:

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. Den hybride slutsten#

Den hybride pakke kører en suite (ét ur + én inertisensor) og kræver, at både tidssynkronisering og position holder sig inden for specifikationen; pnt_holdover er tiden, indtil en af dem brydes. Eventuelt resynkroniserer et optisk inter-satellitlink uret under udfaldet — kun tidsstøtte; positionen resynkroniseres ikke, fordi tidsoverførsel giver tid, ikke position. Det er det, der isolerer inertisensoren som den begrænsende faktor.

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. GNSS-tilgængelighed udledt af geometri#

orbit.rs er et deterministisk geometrilag uden afhængigheder. En Propagator er enten den analytiske Kepler-Orbit (to-legeme, eventuelt sekulær J2) eller en fuld Sgp4-propagator bygget ud fra et komplet two-line element-sæt; en Walker-delta-generator producerer syntetiske konstellationer, og sigtelinjesynlighed = jordens okkultation + elevationsmaske. Antallet af synlige satellitter afbildes til en GNSS-tilstand (≥4 = nominel, 1–3 = forringet, 0 = nægtet), og build_timeline omsætter det til den tilgængelighedstidslinje, der driver den almindelige ur-holdover-kørsel. Tilgængelighed er altså udledt af geometri frem for håndskrevet, mens kørslen, estimatoren og scoringen er uændrede.

En konstellation, der leveres som fulde TLE'er, propageres med SGP4/SDP4-modellen i sgp4.rs (valideret mod AIAA (American Institute of Aeronautics and Astronautics) 2006-6753-vektorerne); elementer med kun linje 2 følger den analytiske to-legeme-vej. De to kan blandes i én konstellationsblok.

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

Kernen kompilerer uændret til native, til en Python-udvidelse og til WebAssembly. Python-modulerne (python.rs, PyO3 abi3) og WebAssembly-modulerne (wasm.rs, wasm-bindgen) er valgfrie afhængigheder bag feature-flag (--features python / --features wasm): standardbygget og testsuiten kompilerer dem aldrig, mens afhængighedsrevisionens gate (cargo deny --all-features) inspicerer deres afhængighedstræer, fordi disse crates leveres inde i wheel-filen og npm-pakken. Begge kalder api::run_toml, så alle flader returnerer identiske resultater. WebAssembly-modulet bærer browser-legepladsen i web/ og eksporterer tretten funktioner: run, run_all (én motorkørsel, der returnerer resultat, diagram, oversigt og tabel samlet), chart_svg, summary, table_csv, list_kinds, error_kind, version, kodeken encode_permalink / decode_permalink til delbare URL'er (URL: webadresse) og de tre eksportører export_sp3 / export_omm / export_oem, som bærer legepladsens eksportmenu. To yderligere indgange når det samme api: MCP-serveren (Model Context Protocol) (mcp/kshana-mcp, en rmcp-crate uden for workspace, der udstiller femten værktøjer — 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 to eksempelværktøjer læser de medfølgende scenarier gennem bibliotekets funktion bundled-scenarios, som er slået fra som standard, og som kun denne server slår til) og JetBrains IDE-pluginet (integrated development environment) (ide/jetbrains, et Kotlin-projekt, der kalder CLI'en kshana i stedet for at linke biblioteket).

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 og WASM er --features python / --features wasm; tabellen med medfølgende scenarier er --features bundled-scenarios (MCP-serverens eneste brug af den); MCP-serveren og krydskontrollerne i xval/* er crates, der er UDELADT fra workspace; IDE-pluginet linker ingenting — det kører CLI'en.

8. Determinisme og reproducerbarhed#

• Al tilfældighed løber gennem én seedet ChaCha8Rng pr. kørsel; rækkefølgen af trin er fast, så (scenario, seed, engine version) → identical bits.
• Resultatet bærer en SHA-256 (SHA: Secure Hash Algorithm) scenario_hash; scripts/check-reproducible.sh kører et referencescenarie to gange og kontrollerer, at outputtet er identisk byte for byte.
• Den samme motor kompilerer til native, til en Python-udvidelse og til wasm32-unknown-unknown til kørsler i browseren, der giver de samme tal.

9. Udskudt / fremtidig struktur#

Astrodynamik-, fusions- og alt-PNT-lagene i §1a — den fulde SGP4/SDP4-propagator, den numeriske Cowell-propagator med en kraftmodel med syv perturbationer og to adaptive integratorer, manøvre- og banedesign, banebestemmelse, GNSS/INS-estimatorerne med 15, 8 og 17 tilstande, det koblede ur+positionsfilter og gravitationskortmatchning — er alle leveret, sammen med Security FoM med en aktiv spoof-demonstrator, ægte TLE-/multikonstellationsgeometri, Monte Carlo-bånd, trade-study-sweeps, den udskrivbare HTML-rapport (HyperText Markup Language) med dens maskinlæsbare tvilling og workflows til release, publish, wheels og pages.

Flere funktioner, der engang stod her som fremtidigt arbejde, er siden leveret og er beskrevet ovenfor eller i VALIDATION: den fulde IAU 2000A-nutation og den ækvinoksfrie CIO GCRS↔ITRS / ITRF-reduktion (International Terrestrial Reference Frame) (valideret bit for bit mod SOFA/ERFA (SOFA: Standards of Fundamental Astronomy; ERFA: Essential Routines for Fundamental Astronomy)), EGM2008-geopotentialet (Earth Gravitational Model 2008) til grad/orden 70, leddet Lense–Thirring (frame-dragging), tidevand i fast jord, hav og atmosfære, en krydsvalidering af efemeriden på DE-niveau (DE440/ANISE (DE440: Development Ephemeris 440; ANISE: Attitude, Navigation, Instrument, Spacecraft, Ephemeris — et rent Rust-værktøjssæt til planetgeometri)), den eksterne krydsvalidering mod Orekit 12,2 af den numeriske Cowell-propagator (0,08 m over 24 h) og af batch- og sekventiel banebestemmelse samt den tæt koblede navigator med 17 tilstande, der er gjort tilgængelig som scenarietypen hybrid-ukf.

De resterende opfølgninger spores i CHANGELOG [Unreleased] og i køreplanen pr. funktion i CAPABILITY: en ekstern orakelværdi til EGM-evaluatoren (Earth Gravitational Model) af høj grad netop på polaksen og en pyshtools-ren sammenligning nær polen (evaluatoren til grad 2190 og dens indlæser .gfc til kørselstid er leveret, MODELLED; se xval/high-degree-gravity/), en tidsvarierende rumvejrsdriver til den valgfrie densitetsmodel NRLMSISE-00 for atmosfærisk modstand (NRLMSISE: Naval Research Laboratory Mass Spectrometer and Incoherent Scatter Radar Extended atmosfæremodel) (standardtætheden for modstand er den statiske eksponentielle model, og tætheden Jacchia-71 for typen space-weather er karakteriseret mod NRLMSISE-00, men ikke erstattet af den), en ekstern kontrol af den valgfrie skygge med solens randformørkelse, bærebølgefase-GNSS/INS-tætkobling og et ægte EGM2008/EIGEN-gravitationskort (EIGEN: European Improved Gravity model of the Earth by New techniques) til alt-PNT-matcheren.

Et privat overlay-repo rummer eksportfølsom robusthedsdybde; det kobles ind gennem den samme grænseflade ErrorModel (og kontrakten ExternalPack i §4) uden at ændre den offentlige motor.