Kshana — Architektura

Kshana je jeden engine organizovaný ve vrstvách nad společným jádrem: balíčky senzorů (hodiny, inerciální, přenos času, hybridní); vrstva astrodynamiky / numeriky (analytické SGP4/SDP4 (SGP4: Simplified General Perturbations 4; SDP4: Simplified Deep-space Perturbations 4), numerický Cowellův propagátor se sedmiporuchovým silovým modelem, návrh manévrů, určování oběžné dráhy z vzdáleností pozemních stanic a proložení silového modelu přesnými efemeridami agentur); vrstva času a referenčních soustav (časové stupnice IERS (International Earth Rotation and Reference Systems Service), precese–nutace IAU (International Astronomical Union) 2006/2000A a redukce GCRS↔ITRS přes CIO (Celestial Intermediate Origin) (GCRS: Geocentric Celestial Reference System; ITRS: International Terrestrial Reference System)); vrstva fúze (estimátory GNSS/INS (GNSS: globální družicový navigační systém; INS: inerciální navigační systém)); vrstvy integrity, odolnosti, alt-PNT (PNT: určování polohy, navigace a času) a lunární (RAIM/ARAIM/SBAS (RAIM: autonomní monitorování integrity v přijímači; ARAIM: pokročilé autonomní monitorování integrity v přijímači; SBAS: družicový rozšiřující systém), rušení a vícevrstvá detekce spoofingu, přiřazování podle gravitačních/terénních/magnetických map a cislunární PNT); a novější vrstvy LEO-PNT (PNT na nízké oběžné dráze Země), spektra, sluneční soustavy a návrhu konstelací, síťového časování a kampaní, se zapisovači zpráv, animací a interoperability, které může použít každý běh (§1d). Napříč všemi nic engine neví o „kvantovém“ proti „klasickému“: pohání chybové modely senzorů scénářem výpadku GNSS, spouští estimátor a hodnotí výsledek. Kvantové a klasické zařízení se proto porovnávají na tomtéž scénáři a liší se jen svými (zveřejněnými, citovanými) chybovými parametry a nezávislými seedy šumu.

Tento dokument shromažďuje strukturní a behaviorální diagramy. §1 je jádro balíčků senzorů; §1a mapuje vrstvy astrodynamiky, fúze a alt-PNT přidané od té doby; §1b–§1d vrstvy studií, domén a výstupů. K použití viz README; co je a co není validováno, viz VALIDATION; tabulku zralosti jednotlivých schopností viz CAPABILITY.

Zkratky použité v diagramech a nerozepsané tam, kde se objevují: ADEV, Allanova odchylka; BW, šířka pásma; CAI, interferometr se studenými atomy; CZML, Cesium Language; Δ-DOR, delta differential one-way ranging; DO-229E, norma přijímače SBAS RTCA (Radio Technical Commission for Aeronautics); EKF, rozšířený Kalmanův filtr; FM, frekvenční modulace; GSE, pozemní podpůrné zařízení; HPL/VPL, vodorovná/svislá ochranná úroveň; IMU, inerciální měřicí jednotka; IOAG, Interagency Operations Advisory Group; IQ, vzorky ve fázi a kvadratuře; ISL, mezidružicový spoj; ITU-T, Telekomunikační standardizační sektor Mezinárodní telekomunikační unie; J2–J6, zonální harmonické gravitace Země stupně 2 až 6; KIF, Kshana Interchange Format; KML, Keyhole Markup Language; KPI, klíčový ukazatel výkonnosti; L1/L5, nosná pásma GNSS (L2 halo drah CR3BP je naproti tomu Lagrangeův bod Země–Měsíc 2); LEO, nízká oběžná dráha Země; LOO, vynechání jednoho (leave-one-out); LTC, koordinovaný lunární čas; MEO, střední oběžná dráha Země; MTIE, maximální chyba časového intervalu; N2, Hillovo číslo diverzity řádu 2; NED, sever-východ-dolů; NTN, nepozemská síť; OD, určování oběžné dráhy; OPS-SAT, družice Evropské kosmické agentury jako softwarová laboratoř na oběžné dráze; PPP, přesné určování polohy bodu; PSD, spektrální hustota výkonu; PVT, poloha, rychlost a čas; RINEX, Receiver Independent Exchange Format; RK4 / RK5(4), integrátory Rungeho–Kutty čtvrtého řádu a vnořeného pátého (čtvrtého) řádu; SH, kulová harmonická; SigMF, Signal Metadata Format; SIR, vzorkování s významovým převzorkováním; SRIF, informační filtr s odmocninou; SRP, tlak slunečního záření; SSC, koeficient spektrálního oddělení; STK, Systems Tool Kit; SVG, Scalable Vector Graphics; TDEV, časová odchylka; TDM, Tracking Data Message CCSDS (Consultative Committee for Space Data Systems); TLE, dvouřádková sada prvků; TPL, časová ochranná úroveň (Timing Protection Level); UBX, binární protokol u-blox; UHF, velmi vysoká frekvence (ultra high frequency); VLBI, interferometrie s velmi dlouhou základnou; VRW / ARW, náhodná procházka rychlosti / úhlu; WASM, WebAssembly.

---

1. Struktura modulů#

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 (rozhraní příkazového řádku) a obě vazby ústí do jednoho vstupního bodu api::run_toml, takže se nikdy nerozejdou. Balíčky znovu používají společné jádro (types, scenario, allan); Balíček 4 (hybrid) skládá modely a estimátory Balíčků 1–3, místo aby je implementoval znovu; orbit odvozuje z geometrie časovou osu GNSS, která pak živí běh Balíčku 1. Modul navsignal sedí na úrovni signálu mezi rozpočtem spoje a doménou měření: z vlastních výkonových spekter signálu a rušiče odvozuje koeficient spektrálního oddělení κ, z něhož jamming nyní počítá svůj protirušicí Q = 1/(R_c·κ), místo aby bral reprezentativní konstantu (zkontrolováno v CI (průběžná integrace)); nese také kompromis návrhu rozptylových kódů (m-posloupnost/Gold).

Tři další moduly tvoří páteř odolnosti bez GNSS. holdover odpovídá přímo na provozní otázku — jak dlouho mohou tyto hodiny běžet volně, než jejich časová chyba překročí rozpočet? — tím, že uzavřený tvar chyby doběhu podle van Loana zpřístupňuje jako inverzi od holdoveru k prahu, zkontrolovanou proti vícekrokové rekurzi kovariance clock_state. Jeho inerciální dvojče žije v inertial::quantum_imu (QuantumNavBudget), které skládá bílý šum driftu interferometru se studenými atomy se zkreslením a chybou měřítkového faktoru do rozpočtu driftu polohy během holdoveru (člen zkreslení zkontrolován proti nezávislému integrátoru AccelModel). verification vykresluje matici požadavek → modul → test → orákulum → stav celého enginu, s jednotkově testovanými invarianty, které zakazují štítek ověřeno bez nezávislého vnějšího orákula — takže tvrzení o jistotě se nemůže od kódu odchýlit.

1a. Vrstvy astrodynamiky, fúze a alt-PNT#

Kromě jádra balíčků senzorů sdílejí tři podsystémy totéž společné jádro a živí orbit (nebo jsou jím živeny). Vrstva astrodynamiky / numeriky přidává neanalytický Cowellův propagátor vedle analytické cesty SGP4/SDP4; vrstva fúze nese estimátory GNSS/INS; a vrstva alt-PNT je přiřazování podle gravitační mapy bez GPS (GPS: Global Positioning System). Jsou to schopnosti knihovny/scénáře (viz CAPABILITY, které jsou zapojeny do scénáře kind a které dostupné jako API (rozhraní pro programování aplikací) Rustu).

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

Členy sil numerického propagátoru jsou ve výchozím stavu vypnuty, takže jejich zapnutí nikdy neruší vydané zlaté reference. 17stavový těsně vázaný UKF (unscented Kalman filter) přečká výpadek GNSS na odvozené náhodné procházce rychlosti kvantového akcelerometru CAI; určování oběžné dráhy znovu používá tytéž forces/integrator k propagaci kandidátního stavu přes sledovací oblouk.

Totéž společné jádro nese také čtyři další podsystémy, které nejsou nakresleny výše (jejich balíčky se objevují v rozdělení v §4): vrstvu času a referenčních soustav (timescales, jd2, precession, nutation, cio, frames, eop) redukující TEME↔GCRS↔ITRS (TEME: true equator, mean equinox) a živící balíček ephemeris/pozemní stopy; vrstvu integrity (raim, sbas) pro RAIM/ARAIM/SBAS; vrstvu odolnosti (jamming, spoof, spoof_detect, spoof_monitors, detection) pro rušení a vícevrstvou detekci spoofingu, s vrstvou navigačního signálu (navsignal) na úrovni signálu — spektrální hustoty výkonu BPSK-R (BPSK: binární fázová modulace) / sine-BOC (BOC: binární offsetová nosná), koeficient spektrálního oddělení κ, který nyní odvozuje protirušicí Q modulu jamming, RMS (Gaborovu) šířku pásma měření vzdálenosti, jitter koherentního sledování kódu časně–pozdě smyčkou DLL (smyčka s uzamčeným zpožděním) a obálku chyby vícecestného šíření (analýza výkonu signálu, nikoli návrh RF (radiofrekvenčního) nákladu / antény, což je role partnera pro náklad); a vrstvu lunární / cislunární (lunar, lunar_frame, lunar_od, cr3bp) pro dynamiku CR3BP (omezený kruhový problém tří těles) — včetně matice přechodu stavu 6×6 a jednostřelového diferenciálního korektoru (cr3bp_jacobian, propagate_state_stm, differential_correct_halo), který vytváří skutečně periodické dráhy halo/NRHO (NRHO: téměř přímočará halo dráha), reprodukující zveřejněnou jižní NRHO L2 9:2 (dráha Gateway) s periodou ≈ 6,57 d / perilunem ≈ 3 250 km (zveřejněno ≈ 6,56 d / ≈ 3 370 km); selenocentrická transformace MCI/MCMF (MCI: inerciální soustava se středem v Měsíci; MCMF: soustava se středem v Měsíci pevná k Měsíci) korigované dráhy a pokračování rodiny zůstávají následnými úkoly a NRHO je řešení CR3BP (kruhové, bez Slunce), neověřené proti skutečné efemeridě LANS/Gateway (LANS: Lunar Augmented Navigation Service) — a integritu LunaNet. Proložení silového modelu agenturními efemeridami (precise_od, lunar_od, tides, gravity_sh) a úplná sada polí alt-PNT (igrf, altpnt/terrain, gravimeter) doplňují seznam modulů; zralost jednotlivých modulů viz CAPABILITY.

1b. Studie odolnosti, hodnocení strojového učení a reprodukovatelné artefakty#

Pět dalších skupin modulů tvoří otevřenou, reprodukovatelnou studijní vrstvu za výzkumnými články projektu. Na rozdíl od scénářů kind se k nim přistupuje jako ke generátorům cargo run --example / --bin, které zapisují byte-deterministické artefakty (pevné seedy, zaznamenaná verze enginu + hash konfigurace). Všechny jsou MODELLED (syntetická kalibrace nebo kalibrace na veřejné datové sadě) a nesou otevřené štítky validace — žádná není certifikace.

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 — podmíněná časová ochranná úroveň (Timing Protection Level): holdoverem omezená mez nezjištěné časové chyby při spoofingu, skládající práh monitoru k-σ, van Loanův rozptyl doběhu přes latenci detekce a čas do poplachu CUSUM (kumulativní součet); kalibrovaná na skutečném zaznamenaném spoofingu (JammerTest 2024). Neexistuje konečná nepodmíněná mez — TPL je podmíněná tím, že útok zjistí nezávislá křížová kontrola.
• resilience/ — engine pro hodnocení odolnosti PNT v souladu s rámcem (kategorie RPCF (Resilient PNT Conformance Framework) amerického ministerstva vnitřní bezpečnosti DHS) plus studie nestability rozhodnutí: Dirichletův vážicí simplex, nestabilita pořadí podle Kendallova τ, četnost změny vítěze top-1 a kolaps diverzity společného režimu (Hill-N2), se zprávou o zajištění chráněnou integritním hashem a 35 ručně odvozenými testy orákula. Viz RESILIENCE-CROSSWALK. Syntetické architektury sladěné s RPCF v2.0 — vlastní posouzení, nikoli certifikace.
• impairment_eval / impairment_study / impairment_ml / eval_stats — studie mezery optimismu při RF zhoršení: označený syntetický korpus a nástroj ROC/AUC (ROC: provozní charakteristika přijímače; AUC: plocha pod křivkou) nezávislý na detektoru, panel 13 detektorů (energie/AGC/SQM/parita (AGC: automatické řízení zesílení; SQM: monitorování kvality signálu) plus detektory logistické regrese s pevným seedem a MLP (MLP: vícevrstvý perceptron) s jednou skrytou vrstvou), zákony škálování uvnitř a mimo rozdělení trénovacích dat s permutační nulou a prediktor vynechání jednoho (leave-one-out) degradace mimo rozdělení. Metriky vyhodnocení jsou validovány bit po bitu proti scikit-learn.
• sdr / realdata — přijímací část softwarově definovaného přijímače (surové IQ/IF (IQ: ve fázi/kvadratura; IF: mezifrekvence) → odbočky korelátoru časně/okamžitě/pozdě → SQM) a adaptéry pro načítání (RINEX, u-blox UBX, GnssLogger, JammerTest, Yunnan, SatGrid), které umožňují týmž detektorům běžet nad záznamy dodanými lokálně; do repozitáře nejsou zapsány žádné datové sady.
• crossover / quantum_trade — mapa křížení odolnosti kvantového a klasického řešení při nejistotě parametrů a kompromis přínosu holdoveru podle naměřené ADEV; numerická jádra kompromisu jsou validována proti scipy.

1c. Vrstvy integrity, GNSS, hlubokého vesmíru, Měsíce a misí#

Zbývající domény se zapojují do téhož rozdělení api a znovu používají společné jádro, soustavy a geometrii. Vše zde je MODELLED, pokud řádek matice verification necituje vnější orákulum (jádro RAIM proti SciPy, SBAS proti forku RTKLIB (open-source knihovna pro kinematické určování polohy v reálném čase), jádro DOP (faktor zhoršení přesnosti) gnss_lib_py, hodnocení OPS-SAT, jádro ochranné úrovně lunárního ARAIM, konzistence lunárních efemerid mezi poskytovateli) — zbytek lunární sady a kvantový demonstrátor jsou modelované, ilustrativní, z veřejných zdrojů a nenesou žádné tvrzení o TRL (úroveň technologické připravenosti) / odkazu na dřívější nasazení / podpoře agentury.

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, sluneční soustava, síťové časování, kampaně a výstupy#

Nejnovější vrstvy sledují stejný vzor: každá je jeden či více scénářů kind rozdělovaných z api, postavených na společném jádru a MODELLED, pokud řádek matice nepojmenovává vnější orákulum.

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

Podrobnosti podle druhů jsou v LEO-PNT, LEO-SIGNAL, LEO-PASS, LEO-NAVMSG, LEO-PNT-FUSION, SPECTRUM, CONSTELLATION-DESIGN, TELECOM-TIMING, SLOT-TIMING, CAMPAIGNS, REPORTS, ANIMATION a INTEROP.

1e. Vrstvy důvěry v přijímač, důkazů, telemetrie, tréninku a compliance (0,35)#

Tyto vrstvy čtou vlastní záznam přijímače nebo zapisují soubory pro jiné nástroje; žádná z nich nesyntetizuje ani nevysílá radiofrekvenční signál. Stojí vedle api, nikoli pod druhy scénářů, kromě samotného receiver-trust, které je druhem scénáře. Všechny jsou MODELLED, pokud řádek matice nepojmenovává vnější orákulum, a námořní výstupy mají pouze poradní charakter, nejde o typově schválené navigační zařízení.

Integrace pro lodě (zásuvný modul Signal K, režim brány OpenCPN a referenční sestavení) volají nástroj příkazového řádku; viz MARINE-INTEGRATIONS.

2. Řetězec zpracování enginu (na jeden běh)#

Každý běh provádí krok za krokem jeden model senzoru po časové mřížce; kdykoli je GNSS nominální, senzor se disciplinuje, a během výpadku ho nechá běžet volně (holdover / dead-reckoning).

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

Scénář tento řetězec spustí dvakrát, jednou pro kvantový senzor a jednou pro klasický senzor, a to s nezávislými hodnotami seed (classical_seed = seed + 0x9e3779b97f4a7c15), takže obě realizace šumu jsou nekorelované.

3. Rozhraní chybového modelu (bod rozšíření)#

Každý senzor implementuje stejnou myšlenku: stavový objekt, jehož step() posouvá jeho vnitřní stochastickou chybu a jehož nashromážděný stav se čte v každém taktu. Hodiny zpřístupňují nashromážděnou fázi; akcelerometry dvojitě integrovanou polohu; spoje jitter jednotlivých měření.

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 } se přenáší do výsledku, takže každou hodnotu ve výstupu lze dohledat k publikovanému zdroji uvedenému v provenance.

Vedle analytického HoldoverEstimator spouští balíček hodin dvoustavový (fáze, frekvence) Kalmanův filtr (KalmanClock), jehož procesní šum odpovídá skutečnému modelu. Při setrvání ve výpadku roste rozptyl jeho fázové chyby přesně na q_wf·T + q_rw·T³/3, tedy analytický vztah pro holdover, a jeho online mez 1-σ slouží k naplnění ukazatele kvality Integrita (podíl vzorků výpadku, jejichž chyba zůstane uvnitř meze k-σ).

4. Rozdělování (CLI a vazby)#

api::run_toml(src) je jediný vstupní bod: nahlédne do kind na nejvyšší úrovni, deserializuje odpovídající scénář, spustí balíček a vrátí { json, svg, summary, csv } (csv je přítomno pouze u druhů, které publikují tabulku reprodukovatelnosti). CLI je zapíše do souborů spolu se zprávou (report.html, report.json) a s výstupem --export / --animate, pokud je požadován; vazby pro Python a WebAssembly je vracejí hostiteli. Jedno rozdělování, žádný rozpor.

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

Rozdělování probíhá podle typovaného výčtu ScenarioKind, který se vyhodnocuje vyčerpávajícím porovnáním (viz další podkapitola), takže přidání balíčku je změna kontrolovaná při kompilaci. Chybějící kind se vrací k balíčku clock, takže existující scénáře jednoho druhu se deserializují beze změny (serde ignoruje pole kind v každé struktuře scénáře). Nerozpoznaný kind je odmítnut chybou KshanaError::InvalidInput, která pojmenuje nejbližší vestavěný druh, pokud název vypadá jako překlep.

Typované rozdělování a strukturované API#

Rozdělování probíhá podle typovaného výčtu ScenarioKind, nikoli podle porovnání surového řetězce: ScenarioKind::classify(src) převede pole kind na variantu a rozdělovač ji vyhodnotí vyčerpávajícím porovnáním; přidání balíčku je změna kontrolovaná při kompilaci, nikoli překlep v řetězci. Vedle run_toml, které vrací řetězec (ponecháno pro CLI a stávající vazby), existují dvě typované rozhraní:

• run_scenario(src) -> Result<RunOutput, KshanaError>: typovaný vstup se strukturovanou taxonomií chyb (InvalidInput, NonConvergence, Unsupported, IoError). Každá chyba nese stabilní kind_tag(), aby volající mohl větvit podle kategorie selhání, místo aby analyzoval zprávu. Vazby to zpřístupňují jako error_kind(toml).
• list_scenario_kinds() -> Vec<ScenarioMeta> (a list_scenario_kinds_json(), ve vazbách zpřístupněné jako list_kinds()): programová introspekce, tedy název, popis a povinná/volitelná pole každého druhu, pro automatické doplňování v uživatelském rozhraní (UI) a v noteboocích.

Rozšíření Kshana o externí balíček#

Balíček třetí strany implementuje dva malé rysy (traits) stabilní z hlediska semver z 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 má také výchozí metodu register_into(&mut PackRegistry), která nic nedělá, pokud se balíček nepřihlásí k rozdělování přes registr v src/registry.rs. Vestavěný balíček jamming je zapojen přes Scenario jako vzorový příklad; balíčky mimo strom (out-of-tree) se řídí stejnou smlouvou bez forku jádra (obdobně jako bod rozšíření ErrorModel v §3, který používá soukromá nadstavba odolnosti).

Kshana má proto dvě stabilní rozšiřující rozhraní: senzor se přidá implementací ErrorModel (§3), celý druh scénáře implementací Scenario + ExternalPack; obě jsou stabilní z hlediska semver a žádné nevyžaduje fork jádra:

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. Hybridní vrcholný balíček#

Hybridní balíček spouští sadu (jedny hodiny a jeden inerciální senzor) a vyžaduje, aby čas i poloha zůstaly ve specifikaci; pnt_holdover je doba do prvního porušení kteréhokoli z nich. Volitelně optický meziodružicový spoj během výpadku znovu synchronizuje hodiny, a to pouze podporou času; poloha se znovu nesynchronizuje, protože přenos času dává čas, nikoli polohu. Právě to izoluje inerciální senzor jako limitující 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. Dostupnost GNSS odvozená z geometrie#

orbit.rs je deterministická geometrická vrstva bez závislostí. Propagator je buď analytická keplerovská Orbit (dvoutělesová, volitelně se sekulárním J2), nebo plný propagátor Sgp4 sestavený z úplné dvouřádkové sady prvků; generátor Walker-delta vytváří syntetické konstelace a přímá viditelnost = zákryt Zemí + elevační maska. Počet viditelných družic se mapuje na stav GNSS (≥4 = nominální, 1–3 = zhoršený, 0 = odepřený) a build_timeline z toho vytvoří časovou osu dostupnosti, která řídí standardní běh holdoveru hodin. Dostupnost je tedy odvozena z geometrie, a nikoli psána ručně, zatímco běh, estimátor a hodnocení zůstávají beze změny.

Konstelace zadaná jako úplné TLE se propaguje modelem SGP4/SDP4 v sgp4.rs (ověřeno proti vektorům AIAA (American Institute of Aeronautics and Astronautics) 2006-6753); prvky pouze z řádku 2 zůstávají na analytické dvoutělesové cestě. Obojí lze v jednom bloku konstelace míchat.

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

Jádro se beze změny kompiluje do nativního kódu, do rozšíření pro Python a do WebAssembly. Moduly pro Python (python.rs, PyO3 abi3) a WebAssembly (wasm.rs, wasm-bindgen) jsou volitelné závislosti řízené příznaky funkcí (--features python / --features wasm): výchozí sestavení a testovací sada je nikdy nekompilují, zatímco brána auditu závislostí (cargo deny --all-features) jejich stromy závislostí kontroluje, protože tyto crates jsou součástí balíčku wheel a balíčku npm. Oba volají api::run_toml, takže každé rozhraní vrací shodné výsledky. Modul WebAssembly pohání prohlížečové hřiště v web/ a exportuje třináct funkcí: run, run_all (jeden běh enginu vracející výsledek, graf, shrnutí a tabulku dohromady), chart_svg, summary, table_csv, list_kinds, error_kind, version, kodek sdílitelných URL (URL: webová adresa) encode_permalink / decode_permalink a tři exportéry export_sp3 / export_omm / export_oem, které pohánějí exportní nabídku hřiště. Dvě další vstupní brány vedou ke stejnému api: server MCP (Model Context Protocol) (mcp/kshana-mcp, crate rmcp vyňatý z pracovního prostoru, který zpřístupňuje patnáct nástrojů: 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; dva nástroje s příklady čtou přibalené scénáře přes funkci knihovny bundled-scenarios, ve výchozím stavu vypnutou, kterou zapíná jen tento server) a zásuvný modul pro JetBrains IDE (integrované vývojové prostředí) (ide/jetbrains, projekt v Kotlinu, který volá CLI kshana přes shell, místo aby knihovnu linkoval).

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

Řízení funkcí: Python a WASM jsou --features python / --features wasm; tabulka přibalených scénářů je --features bundled-scenarios (server MCP ji používá jako jediný); server MCP a křížové kontroly xval/* jsou crates z pracovního prostoru VYŇATÉ; zásuvný modul IDE nic nelinkuje, spouští CLI.

8. Determinismus a reprodukovatelnost#

• Veškerá náhodnost prochází jediným ChaCha8Rng se seedem pro každý běh; pořadí kroků je pevné, takže platí (scenario, seed, engine version) → identical bits.
• Výsledek nese SHA-256 (SHA: Secure Hash Algorithm) scenario_hash; scripts/check-reproducible.sh spustí referenční scénář dvakrát a ověří, že výstup je bajt po bajtu shodný.
• Stejný engine se kompiluje do nativního kódu, do rozšíření pro Python a do wasm32-unknown-unknown pro běhy v prohlížeči, které dávají stejná čísla.

9. Odložená / budoucí struktura#

Astrodynamické, fúzní a alt-PNT vrstvy v §1a, tedy plný propagátor SGP4/SDP4, numerický Cowellův propagátor se sedmi poruchami v silovém modelu a dvěma adaptivními integrátory, návrh manévrů a trajektorií, určování oběžné dráhy, 15-/8-/17stavové estimátory GNSS/INS, spřažený filtr hodin a polohy a párování s gravitačními mapami, jsou všechny dodány, spolu s ukazatelem kvality Bezpečnost s aktivním demonstrátorem spoofingu, skutečnou geometrií TLE / více konstelací, pásmy Monte Carlo, studiemi kompromisů formou průchodů parametrů, tisknutelnou zprávou HTML (HyperText Markup Language) s jejím strojově čitelným dvojčetem a pracovními postupy pro vydání, publikaci, wheels a pages.

Několik schopností, které zde byly dříve uvedeny jako budoucí práce, bylo od té doby dodáno a je popsáno výše nebo ve VALIDATION: plná nutace IAU 2000A a redukce GCRS↔ITRS / ITRF (International Terrestrial Reference Frame) bez rovnodennosti přes CIO (ověřeno bit po bitu proti SOFA/ERFA (SOFA: Standards of Fundamental Astronomy; ERFA: Essential Routines for Fundamental Astronomy)), geopotenciál EGM2008 (Earth Gravitational Model 2008) do stupně/řádu 70, člen Lense–Thirring (strhávání rámce), slapy pevné země, oceánské a atmosférické, křížová validace efemerid třídy DE (DE440/ANISE (DE440: Development Ephemeris 440; ANISE: Attitude, Navigation, Instrument, Spacecraft, Ephemeris, čistě Rustový nástroj pro planetární geometrii)), externí křížová validace numerického Cowellova propagátoru pomocí Orekit 12,2 (0,08 m za 24 h) i dávkového a sekvenčního určování oběžné dráhy a 17stavový těsně vázaný navigátor zpřístupněný jako druh scénáře hybrid-ukf.

Zbývající navazující práce jsou sledovány v CHANGELOG [Unreleased] a v plánu jednotlivých schopností v CAPABILITY: externí hodnota orákula pro vysokostupňový vyhodnocovač EGM (Earth Gravitational Model) přesně na polární ose a porovnání v těsné blízkosti pólu čisté vůči pyshtools (vyhodnocovač do stupně 2190 a jeho zavaděč .gfc za běhu jsou dodány, MODELLED; viz xval/high-degree-gravity/), časově proměnný ovladač kosmického počasí pro volitelnou úroveň hustoty odporu NRLMSISE-00 (NRLMSISE: Naval Research Laboratory Mass Spectrometer and Incoherent Scatter Radar Extended atmosphere model) (výchozí hustota odporu je statický exponenciální model a hustota Jacchia-71 druhu space-weather je charakterizována vůči NRLMSISE-00, ale není jím nahrazena), externí kontrola volitelného stínu s okrajovým ztmavením slunečního disku, těsné spřažení GNSS/INS s fází nosné a skutečná gravitační mapa EGM2008/EIGEN (EIGEN: European Improved Gravity model of the Earth by New techniques) pro alt-PNT párovač.

Soukromý překryvný repozitář obsahuje hloubku odolnosti citlivou z hlediska exportu; zapojuje se přes totéž rozhraní ErrorModel (a smlouvu ExternalPack v §4) bez změny veřejného enginu.