Kshana — Arkitektur

Kshana är en motor organiserad i lager över en gemensam kärna: sensorpaketen (klocka, tröghet, tidsöverföring, hybrid); ett lager för astrodynamik och numerik (analytisk SGP4/SDP4 (SGP4: Simplified General Perturbations 4; SDP4: Simplified Deep-space Perturbations 4), en numerisk Cowell-propagator med sin kraftmodell med sju störningar, manöverutformning, banbestämning ur avstånd från markstationer och anpassning av kraftmodellen mot precisa efemerider från rymdorganisationer); ett lager för tid och referenssystem (IERS (International Earth Rotation and Reference Systems Service) tidsskalor, IAU (International Astronomical Union) 2006/2000A precession–nutation och reduktionen GCRS↔ITRS via CIO (Celestial Intermediate Origin) (GCRS: Geocentric Celestial Reference System; ITRS: International Terrestrial Reference System)); ett fusionslager (GNSS/INS-skattarna (GNSS: global navigation satellite system; INS: inertial navigation system)); samt lagren för integritet, resiliens, alt-PNT (PNT: positioning, navigation and timing) och lunar (RAIM/ARAIM/SBAS (RAIM: receiver autonomous integrity monitoring; ARAIM: advanced receiver autonomous integrity monitoring; SBAS: satellite-based augmentation system), jamming och spoofingdetektering i flera lager, kartmatchning av gravitation, terräng och magnetfält, samt cislunar PNT); och de nyare lagren LEO-PNT (PNT i låg omloppsbana), spektrum, solsystem och konstellationsutformning, nätverkstidssynkronisering och kampanj, med de rapport-, animerings- och interoperabilitetsskrivare som varje körning kan använda (§1d). Genom alla dessa vet motorn ingenting om "kvant" kontra "klassiskt": den driver sensorernas felmodeller genom ett GNSS-avbrottsscenario, kör en skattare och poängsätter utfallet. En kvantenhet och en klassisk enhet jämförs därför på samma scenario och skiljer sig endast åt i sina (publicerade, citerade) felparametrar och sina oberoende brusfrön.

Det här dokumentet samlar de strukturella och beteendemässiga diagrammen. §1 är sensorpaketens kärna; §1a kartlägger de lager för astrodynamik, fusion och alt-PNT som lagts till sedan dess; §1b–§1d lagren för studier, domäner och utdata. För användning se README; för vad som är och inte är validerat se VALIDATION; för tabellen över mognad per förmåga se CAPABILITY.

Förkortningar som används i diagrammen och inte skrivs ut där de förekommer: ADEV, Allan-avvikelse; BW, bandbredd; CAI, kallatominterferometer; CZML, Cesium Language; Δ-DOR, delta differential one-way ranging; DO-229E, RTCA:s (Radio Technical Commission for Aeronautics) mottagarstandard för SBAS; EKF, utökat Kalmanfilter; FM, frekvensmodulering; GSE, markstödsutrustning; HPL/VPL, horisontell/vertikal protektionsnivå; IMU, tröghetsmätenhet; IOAG, Interagency Operations Advisory Group; IQ, sampel i fas och kvadratur; ISL, länk mellan satelliter; ITU-T, standardiseringssektorn för telekommunikation inom Internationella teleunionen; J2–J6, jordens zonala gravitationsharmoniker av grad 2 till 6; KIF, Kshana Interchange Format; KML, Keyhole Markup Language; KPI, nyckeltal för prestanda; L1/L5, GNSS-bärvågsband (L2 för CR3BP-haloomloppsbanorna är i stället Jord–Måne-Lagrangepunkten 2); LEO, låg omloppsbana; LOO, leave-one-out; LTC, koordinerad månatid; MEO, medelhög jordbana; MTIE, maximalt tidsintervallfel; N2, Hill-mångfaldstalet av ordning 2; NED, nord-ost-ned; NTN, icke-jordbundet nätverk; OD, banbestämning; OPS-SAT, Europeiska rymdorganisationens satellit för programvarulaboratorium i omloppsbana; PPP, precis punktpositionering; PSD, effekttäthetsspektrum; PVT, position, hastighet och tid; RINEX, Receiver Independent Exchange Format; RK4 / RK5(4), Runge–Kutta-integratorer av fjärde ordningen respektive inbäddad femte(fjärde) ordningen; SH, sfärisk harmonik; SigMF, Signal Metadata Format; SIR, sampling importance resampling; SRIF, kvadratrotsinformationsfilter; SRP, solstrålningstryck; SSC, spektral separationskoefficient; STK, Systems Tool Kit; SVG, Scalable Vector Graphics; TDEV, tidsavvikelse; TDM, CCSDS:s (Consultative Committee for Space Data Systems) Tracking Data Message; TLE, tvåradig elementsats; TPL, Timing Protection Level; UBX, u-blox binära protokoll; UHF, ultrahög frekvens; VLBI, interferometri med mycket lång baslinje; VRW / ARW, slumpvandring i hastighet / 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 (kommandoradsgränssnittet) och båda bindningarna leds genom en enda ingångspunkt api::run_toml, så att de aldrig glider isär. Paketen återanvänder den gemensamma kärnan (types, scenario, allan); paket 4 (hybrid) sätter samman modellerna och skattarna från paketen 1–3 i stället för att implementera dem på nytt; orbit härleder en GNSS-tidslinje ur geometri som sedan matar körningen av paket 1. Modulen navsignal ligger på signalnivå mellan länkbudgeten och mätdomänen: den härleder den spektrala separationskoefficienten κ ur de faktiska spektra för signal och jammer, utifrån vilken jamming nu beräknar sin anti-jam-Q = 1/(R_c·κ) i stället för att ta en representativ konstant (korskontrollerat i CI (kontinuerlig integration)); den bär också avvägningen för utformning av avståndskoder (m-sekvens/Gold).

Tre ytterligare moduler utgör ryggraden för resiliens vid GNSS-nekning. holdover besvarar den operativa frågan direkt — hur länge kan den här klockan gå fritt innan tidsfelet överskrider budgeten? — genom att exponera van-Loans slutna form för felet vid fritt lopp som en inversion från holdover till tröskel, korskontrollerad mot den flerstegiga kovariansrekursionen i clock_state. Dess tröghetsmotsvarighet finns i inertial::quantum_imu (QuantumNavBudget), som sätter samman vitbrusdriften hos kallatominterferometern med bias- och skalfaktorfel till en budget för positionsdrift under holdover (biastermen korskontrollerad mot den oberoende integratorn AccelModel). verification renderar hela motorns matris från krav till modul till test till oberoende referens till status, med enhetstestade invarianter som förbjuder en etikett validated utan en oberoende extern referens — så att påståendet om säkerställande inte kan glida ifrån koden.

1a. Lager för astrodynamik, fusion och alt-PNT#

Utöver sensorpaketens kärna delar tre delsystem samma gemensamma kärna och matar (eller matas av) orbit. Lagret för astrodynamik och numerik lägger till en icke-analytisk Cowell-propagator bredvid den analytiska SGP4/SDP4-vägen; fusionslagret bär GNSS/INS-skattarna; och lagret för alt-PNT är kartmatchning av gravitation vid GPS-nekning (GPS: Global Positioning System). Det här är bibliotek- och scenarioförmågor (se CAPABILITY för vilka som är kopplade till en scenariotyp kind kontra nåbara som ett 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

Den numeriska propagatorns kraftermer är avstängda som standard, så att aktivera dem stör aldrig de utgivna facitfilerna. Den tätt kopplade UKF:en (unscented Kalman filter) med 17 tillstånd låter ett GNSS-avbrott löpa på den härledda hastighetsslumpvandringen hos den kvantbaserade CAI-accelerometern; banbestämning återanvänder samma forces/integrator för att propagera ett kandidattillstånd över spårningsbågen.

Samma gemensamma kärna bär också fyra ytterligare delsystem som inte ritats ovan (deras paket förekommer i dispatchen i §4): ett lager för tid och referenssystem (timescales, jd2, precession, nutation, cio, frames, eop) som reducerar TEME↔GCRS↔ITRS (TEME: true equator, mean equinox) och matar paketet ephemeris/markspår; ett lager för integritet (raim, sbas) för RAIM/ARAIM/SBAS; ett lager för resiliens (jamming, spoof, spoof_detect, spoof_monitors, detection) för jamming och spoofingdetektering i flera lager, med ett lager för navigeringssignal (navsignal) på signalnivå — effekttäthetsspektra för BPSK-R (BPSK: binary phase-shift keying) / sinus-BOC (BOC: binary offset carrier), den spektrala separationskoefficienten κ som nu härleder jamming:s anti-jam-Q, RMS-bandbredden (Gabor) för avståndsmätning, den koherenta kodföljningsjittern i early–late-DLL (delay-locked loop) och flervägsfelets hölje (analys av signalprestanda, inte utformning av hårdvara för RF-nyttolast (RF: radiofrekvens) eller antenn — en nyttolastpartners roll); och ett lager för lunar / cislunar (lunar, lunar_frame, lunar_od, cr3bp) för CR3BP-dynamik (circular restricted three-body problem) — inklusive tillståndsövergångsmatrisen 6×6 och en differentiell korrigerare med enkel skjutning (cr3bp_jacobian, propagate_state_stm, differential_correct_halo) som ger genuint periodiska halo-/NRHO-banor (NRHO: near-rectilinear halo orbit), och återger den publicerade södra L2-NRHO 9:2 (Gateway-banan) vid period ≈ 6,57 d / perilun ≈ 3 250 km (publicerat ≈ 6,56 d / ≈ 3 370 km); den selenocentriska transformen MCI/MCMF (MCI: Moon-centred inertial; MCMF: Moon-centred, Moon-fixed) av en korrigerad bana och familjekontinuering återstår som uppföljning, och NRHO är en CR3BP-lösning (cirkulär, utan Solen), inte validerad mot en verklig efemerid för LANS/Gateway (LANS: Lunar Augmented Navigation Service) — och LunaNet-integritet. Anpassningen av kraftmodellen mot efemerider från rymdorganisationer (precise_od, lunar_od, tides, gravity_sh) och hela fältuppsättningen för alt-PNT (igrf, altpnt/terrain, gravimeter) fullbordar modullistan; se CAPABILITY för mognad per modul.

1b. Resiliensstudier, utvärdering av maskininlärning och reproducerbara artefakter#

Fem ytterligare modulgrupper utgör det öppna, reproducerbara studielagret bakom projektets forskningsartiklar. Till skillnad från scenariots kind nås de som generatorer av typen cargo run --example / --bin som skriver bytedeterministiska artefakter (fasta frön, registrerad motorversion + konfigurationshash). Alla är MODELLED (syntetisk eller kalibrering mot offentlig datamängd) och bär ärliga valideringsetiketter — ingen av dem är en certifiering.

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 — den villkorliga Timing Protection Level: en holdover-begränsad gräns för det oupptäckta tidsfelet under spoofing, som sätter samman ett k-σ-golv för övervakaren, van-Loan-variansen vid fritt lopp över detektionsfördröjningen och en CUSUM (cumulative sum) för tid till larm; kalibrerad på en verklig inspelad spoofing (JammerTest 2024). Det finns ingen ändlig ovillkorlig gräns — TPL är villkorlig av att en oberoende korskontroll upptäcker angreppet.
• resilience/ — en poängmotor för PNT-resiliens i linje med ramverk (kategorierna i DHS (Department of Homeland Security) RPCF (Resilient PNT Conformance Framework)) plus en studie av beslutsinstabilitet: en Dirichlet-viktningssimplex, Kendall-τ-rankinginstabilitet, frekvens för byte av topp-1-vinnare, och mångfaldskollaps i gemensam mod (Hill-N2), med en integritetshashad säkerställanderapport och 35 för hand härledda tester mot oberoende referens. Se RESILIENCE-CROSSWALK. Syntetiska arkitekturer i linje med RPCF v2.0 — en självbedömning, inte en certifiering.
• impairment_eval / impairment_study / impairment_ml / eval_stats — studien av optimismglappet vid RF-störningar: ett märkt syntetiskt korpus och en detektoragnostisk ROC/AUC-ram (ROC: receiver operating characteristic; AUC: area under the curve), en panel med 13 detektorer (energi/AGC/SQM/paritet (AGC: automatic gain control; SQM: signal-quality monitoring) plus detektorer med seedad logistisk regression och MLP med ett dolt lager (MLP: multi-layer perceptron)), skalningslagar inom och utanför fördelningen med en permutationsnollhypotes, samt en leave-one-out-prediktor för försämring utanför fördelningen. Utvärderingsmåtten är validerade bit för bit mot scikit-learn.
• sdr / realdata — en front end för mjukvarudefinierad mottagare (rå IQ/IF (IQ: i fas och kvadratur; IF: mellanfrekvens) → korrelatorns early/prompt/late-uttag → SQM) och inläsningsadaptrar (RINEX, u-blox UBX, GnssLogger, JammerTest, Yunnan, SatGrid) som låter samma detektorer köras över inspelningar som tillhandahålls lokalt; inga datamängder checkas in i förrådet.
• crossover / quantum_trade — korsningskartan för resiliens mellan kvant och klassiskt under parameterosäkerhet, och avvägningen för holdover-nytta med uppmätt ADEV; de numeriska kärnorna i avvägningen är validerade mot scipy.

1c. Lager för integritet, GNSS, djup rymd, lunar och uppdrag#

De återstående domänerna kopplas in i samma api-dispatch och återanvänder den gemensamma kärnan, referenssystemen och geometrin. Allt här är MODELLED om inte en rad i verification-matrisen hänvisar till en extern oberoende referens (RAIM-kärnan mot SciPy, SBAS mot RTKLIB-grenen (ett öppet bibliotek för kinematisk positionering i realtid), DOP-kärnan (dilution of precision) i gnss_lib_py, OPS-SAT-utvärderingen, protektionsnivåkärnan för lunar ARAIM, konsistensen mellan leverantörers lunar efemerid) — resten av lunar-sviten och kvantdemonstratorn är modellerade, illustrativa, bygger på offentliga källor och bär inget påstående om TRL (technology readiness level), arv eller stöd från någon rymdorganisation.

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, nätverkstidssynkronisering, kampanjer och utdata#

De nyaste lagren följer samma mönster: var och en är en eller flera scenariotyper kind som dispatchas från api, byggda på den gemensamma kärnan, och MODELLED om inte en matrisrad anger en extern oberoende referens.

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

Detaljerna per typ finns i LEO-PNT, LEO-SIGNAL, LEO-PASS, LEO-NAVMSG, LEO-PNT-FUSION, SPECTRUM, CONSTELLATION-DESIGN, TELECOM-TIMING, SLOT-TIMING, CAMPAIGNS, REPORTS, ANIMATION och INTEROP.

1e. Lager för mottagarförtroende, evidens, telemetri, träning och compliance (0,35)#

Dessa lager läser en mottagares egen logg eller skriver filer för andra verktyg; inget av dem syntetiserar eller sänder en radiofrekvenssignal. De ligger vid sidan av api snarare än under scenariotyperna, bortsett från receiver-trust självt, som är en scenariotyp. Alla är MODELLED om inte en matrisrad anger en extern oberoende referens, och de maritima utdata är rådgivande, inte typgodkänd navigationsutrustning.

Integrationer för båtar (Signal K-pluginet, OpenCPN i gate-läge och referensbygget) anropar kommandoradsverktyget; se MARINE-INTEGRATIONS.

2. Motorns pipeline (per körning)#

Varje körning stegar en enskild sensormodell genom tidsrastret. Den styrs så länge GNSS är nominellt och får gå fritt (holdover / dödräkning) under avbrottet.

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

Ett scenario kör den här pipelinen två gånger, en gång för kvantsensorn och en gång för den klassiska sensorn, med oberoende frön (classical_seed = seed + 0x9e3779b97f4a7c15) så att de två brusrealiseringarna är okorrelerade.

3. Felmodellens gränssnitt (förlängningspunkten)#

Varje sensor implementerar samma idé: ett objekt med tillstånd vars step() för sitt inre stokastiska fel framåt och vars ackumulerade tillstånd läses ut vid varje tick. Klockor visar ackumulerad fas, accelerometrar visar dubbelintegrerad position och länkar visar jitter per mätning.

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öljer med in i resultatet så att varje siffra i utdata kan spåras till den publicerade källa som anges i provenance.

Vid sidan av den analytiska HoldoverEstimator kör klockpaketet ett Kalman-filter med två tillstånd (fas, frekvens) (KalmanClock) vars processbrus motsvarar referensmodellen. När filtret glider genom ett avbrott växer dess fasfelsvarians till exakt q_wf·T + q_rw·T³/3, den analytiska holdover-relationen, och dess 1-σ-gräns online används för att fylla måttet integritet (andelen avbrottsprov vars fel håller sig inom k-σ-gränsen).

4. Dispatch (CLI och bindningar)#

api::run_toml(src) är den enda ingången: den kikar på kind på översta nivån, deserialiserar det matchande scenariot, kör paketet och returnerar { json, svg, summary, csv } (csv finns bara för de typer som publicerar en reproducerbarhetstabell). CLI:t skriver dessa till filer, tillsammans med rapporten (report.html, report.json) och eventuell utdata från --export / --animate. Python- och WebAssembly-bindningarna returnerar dem till värden. En dispatch, ingen avvikelse.

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 typad enum ScenarioKind som matchas uttömmande (se nästa underavsnitt), så att tillägg av ett paket är en ändring som kontrolleras vid kompilering. Ett saknat kind faller tillbaka på paketet clock, så att befintliga scenarier av en enda typ deserialiseras oförändrade (serde ignorerar fältet kind i varje scenariostruct). Ett okänt kind avvisas med KshanaError::InvalidInput, som anger den närmaste inbyggda typen när namnet ser ut som ett skrivfel.

Typad dispatch och det strukturerade API:et#

Dispatch sker på en typad enum ScenarioKind, inte på en rå strängmatchning: ScenarioKind::classify(src) översätter fältet kind till en variant, och dispatchern matchar på den uttömmande. Tillägg av ett paket är en ändring som kontrolleras vid kompilering, inte ett strängfel. Två typade gränssnitt finns vid sidan av run_toml, som returnerar en sträng (kvar för CLI:t och befintliga bindningar):

• run_scenario(src) -> Result<RunOutput, KshanaError>: den typade ingången, med en strukturerad felindelning (InvalidInput, NonConvergence, Unsupported, IoError). Varje fel har en stabil kind_tag() så att en anropare kan grena på felkategorin i stället för att tolka meddelandet. Bindningarna exponerar detta som error_kind(toml).
• list_scenario_kinds() -> Vec<ScenarioMeta> (och list_scenario_kinds_json(), som i bindningarna exponeras som list_kinds()): programmatisk introspektion med varje typs namn, beskrivning samt obligatoriska och valfria fält, för automatisk komplettering i användargränssnitt (UI) och notebooks.

Att utöka Kshana med ett externt paket#

Ett tredjepartspaket implementerar två små, semver-stabila traits från 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 också en standardmetod register_into(&mut PackRegistry), som inte gör något om inte ett paket väljer registrets dispatch-söm i src/registry.rs. Det inbyggda paketet jamming kopplas in via Scenario som genomgånget exempel. Paket utanför trädet följer samma kontrakt utan att forka kärnan (efter förebild från förlängningspunkten ErrorModel i §3, som den privata resiliens-overlayen använder).

Kshana har därför två stabila förlängningssömmar: lägg till en sensor genom att implementera ErrorModel (§3), eller lägg till en hel scenariotyp genom att implementera Scenario + ExternalPack. Båda är semver-stabila och ingen kräver en fork av kärnan:

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 hybrida slutprodukten#

Det hybrida paketet kör en svit (en klocka + en tröghetssensor) och kräver att både tidssynkronisering och position håller sig inom specifikation. pnt_holdover är tiden tills någon av dem överskrids. Eventuellt synkar en optisk länk mellan satelliter om klockan under avbrottet, men bara som tidsstöd: positionen synkas inte om, eftersom tidsöverföring ger tid, inte position. Det är detta som gör tröghetssensorn till den begränsande faktorn.

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-tillgänglighet härledd ur geometri#

orbit.rs är ett deterministiskt geometrilager utan beroenden. En Propagator är antingen den analytiska keplerska Orbit (tvåkropps, valfritt med sekulär J2) eller en fullständig Sgp4-propagator byggd från en komplett tvåradig elementmängd. En Walker-delta-generator skapar syntetiska konstellationer, och siktlinjens synlighet = jordens ockultation + elevationsmask. Antalet synliga satelliter avbildas på ett GNSS-tillstånd (≥4 = nominellt, 1–3 = försämrat, 0 = nekat), och build_timeline gör om detta till den tillgänglighetstidslinje som driver den vanliga körningen av klockans holdover. Tillgängligheten är alltså härledd ur geometri i stället för handskriven, medan körningen, estimatorn och poängsättningen förblir oförändrade.

En konstellation som anges som fullständiga TLE:er propageras med SGP4/SDP4-modellen i sgp4.rs (validerad mot AIAA (American Institute of Aeronautics and Astronautics) 2006-6753-vektorerna). Element med endast rad 2 behåller den analytiska tvåkroppsvägen. De två kan blandas inom ett och samma konstellationsblock.

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

Kärnan kompileras oförändrad till inbyggd kod, till ett Python-tillägg och till WebAssembly. Modulerna för Python (python.rs, PyO3 abi3) och WebAssembly (wasm.rs, wasm-bindgen) är valfria beroenden som styrs av funktionsflaggor (--features python / --features wasm): standardbygget och testsviten kompilerar dem aldrig, medan beroendegranskningen (cargo deny --all-features) däremot inspekterar deras beroendeträd, eftersom dessa crates levereras inuti wheel-paketet och npm-paketet. Båda anropar api::run_toml, så varje yta returnerar identiska resultat. WebAssembly-modulen ligger bakom webbläsarens lekplats i web/ och exporterar tretton funktioner: run, run_all (en motorkörning som returnerar resultat, diagram, sammanfattning och tabell tillsammans), chart_svg, summary, table_csv, list_kinds, error_kind, version, kodeken encode_permalink / decode_permalink för delbara webbadresser (URL: webbadress) och de tre exportfunktionerna export_sp3 / export_omm / export_oem som ligger bakom lekplatsens exportmeny. Två ytterligare ingångar når samma api: MCP-servern (Model Context Protocol) (mcp/kshana-mcp, en rmcp-crate utanför workspace som exponerar femton verktyg: 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 två exempelverktygen läser de medföljande scenarierna via bibliotekets funktion bundled-scenarios, som är avstängd som standard och som bara den här servern slår på) och JetBrains IDE-pluginet (integrerad utvecklingsmiljö) (ide/jetbrains, ett Kotlin-projekt som anropar CLI:t kshana i stället för att länka 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"]

Funktionsstyrning: Python och WASM är --features python / --features wasm. Tabellen med medföljande scenarier är --features bundled-scenarios (MCP-serverns enda användning av den). MCP-servern och korskontrollerna i xval/* är crates som är UTESLUTNA ur workspace. IDE-pluginet länkar ingenting, det kör CLI:t.

8. Determinism och reproducerbarhet#

• All slumpmässighet går genom en enda seedad ChaCha8Rng per körning. Stegordningen är fast, så (scenario, seed, engine version) → identical bits.
• Resultatet bär en SHA-256 (SHA: Secure Hash Algorithm) scenario_hash. scripts/check-reproducible.sh kör ett referensscenario två gånger och kontrollerar att utdata är identisk byte för byte.
• Samma motor kompileras till inbyggd kod, till ett Python-tillägg och till wasm32-unknown-unknown för körningar i webbläsaren som ger samma tal.

9. Uppskjuten / framtida struktur#

Astrodynamik-, fusions- och alt-PNT-lagren i §1a (den fullständiga SGP4/SDP4-propagatorn, den numeriska Cowell-propagatorn med sin kraftmodell med sju störningar och två adaptiva integratorer, manöver- och banutformning, banbestämning, GNSS/INS-estimatorerna med 15, 8 och 17 tillstånd, det kopplade filtret för klocka och position samt gravitationskartmatchning) har alla levererats, tillsammans med säkerhetsmåttet (Security FoM) med en aktiv spoofing-demonstrator, verklig TLE- och multikonstellationsgeometri, Monte Carlo-band, svep för avvägningsstudier, den utskrivbara HTML-rapporten (HyperText Markup Language) med sin maskinläsbara tvilling samt arbetsflödena för release, publicering, wheels och sidor.

Flera förmågor som tidigare angavs här som framtida arbete har sedan dess levererats och beskrivs ovan eller i VALIDATION: den fullständiga IAU 2000A-nutationen och den ekvinoxfria CIO-reduktionen GCRS↔ITRS / ITRF (International Terrestrial Reference Frame) (validerad bit för bit mot SOFA/ERFA (SOFA: Standards of Fundamental Astronomy; ERFA: Essential Routines for Fundamental Astronomy)), geopotentialen EGM2008 (Earth Gravitational Model 2008) till grad och ordning 70, termen för rampdragning Lense–Thirring, fasta, havs- och atmosfäriska tidvatten, en korsvalidering av efemerider av DE-klass (DE440/ANISE (DE440: Development Ephemeris 440; ANISE: Attitude, Navigation, Instrument, Spacecraft, Ephemeris, ett rent Rust-verktyg för planetgeometri)), den externa korsvalideringen mot Orekit 12,2 av den numeriska Cowell-propagatorn (0,08 m över 24 h) och av batch- och sekventiell banbestämning samt den tätt kopplade navigatorn med 17 tillstånd som görs tillgänglig som scenariotypen hybrid-ukf.

De återstående uppföljningarna spåras i CHANGELOG [Unreleased] och i färdplanen per förmåga i CAPABILITY: ett externt oraklevärde för EGM-evaluatorn (Earth Gravitational Model) av hög grad exakt på polaxeln och en pyshtools-ren jämförelse nära polen (evaluatorn till grad 2190 och dess körtidsladdare för .gfc levereras, MODELLED, se xval/high-degree-gravity/), en tidsvarierande rymdväderdrivare för den valfria nivån med NRLMSISE-00 (NRLMSISE: Naval Research Laboratory Mass Spectrometer and Incoherent Scatter Radar Extended, en atmosfärmodell) för luftmotståndets täthet (standardtätheten är den statiska exponentialmodellen, och Jacchia-71-tätheten i typen space-weather är karakteriserad mot NRLMSISE-00 men ersätts inte av den), en extern kontroll av den valfria skuggan med solskivans kantmörkning, tät koppling av GNSS/INS med bärvågsfas samt en verklig EGM2008/EIGEN-gravitationskarta (EIGEN: European Improved Gravity model of the Earth by New techniques) för alt-PNT-matcharen.

Ett privat overlay-repo innehåller exportkänslig resiliensdjup. Det kopplas in via samma gränssnitt ErrorModel (och kontraktet ExternalPack i §4) utan att ändra den publika motorn.