Kshana — Архітектура

Kshana — це один рушій, організований шарами над спільним ядром: пакети датчиків (годинник, інерціальний, передавання часу, гібридний); шар астродинаміки / чисельних методів (аналітичні SGP4/SDP4 (SGP4: Simplified General Perturbations 4; SDP4: Simplified Deep-space Perturbations 4), чисельний пропагатор Коуелла з модельлю сил із семи збурень, проєктування маневрів, визначення орбіти за дальностями з наземних станцій і підгонка моделі сил до прецизійних ефемерид агентств); шар часу та систем відліку (шкали часу IERS (Міжнародна служба обертання Землі та систем відліку), прецесія–нутація IAU (Міжнародний астрономічний союз) 2006/2000A і редукція CIO (Celestial Intermediate Origin) GCRS↔ITRS (GCRS: Geocentric Celestial Reference System; ITRS: International Terrestrial Reference System)); шар злиття (оцінювачі GNSS/INS (GNSS: глобальна навігаційна супутникова система; INS: інерціальна навігаційна система)); а також шари цілісності, стійкості, альтернативного PNT (PNT: позиціонування, навігація та час) і місячний (RAIM/ARAIM/SBAS (RAIM: автономний контроль цілісності приймачем; ARAIM: розширений автономний контроль цілісності приймачем; SBAS: супутникова система функціонального доповнення), глушіння та багаторівневе виявлення спуфінгу, зіставлення з гравітаційними/рельєфними/магнітними картами та цисмісячний PNT); і новіші шари LEO-PNT (PNT на низькій навколоземній орбіті), спектра, Сонячної системи та проєктування орбітальних угруповань, мережевої синхронізації часу і кампаній, із засобами запису звітів, анімації та сумісності, які може використати кожен прогін (§1d). У всіх них рушій нічого не знає про «квантове» проти «класичного»: він проганяє моделі похибок датчиків через сценарій відмови GNSS, запускає оцінювач і оцінює результат. Тож квантовий і класичний пристрої порівнюються на одному сценарії, відрізняючись лише своїми (опублікованими, з цитуваннями) параметрами похибок і незалежними зернами шуму.

Цей документ збирає структурні та поведінкові діаграми. §1 — ядро пакетів датчиків; §1a відображає шари астродинаміки, злиття й альтернативного PNT, додані згодом; §1b–§1d — шари досліджень, доменів і виходів. Про використання див. README; про те, що валідовано, а що ні, див. VALIDATION; про таблицю зрілості кожної можливості див. CAPABILITY.

Скорочення, які використано на діаграмах і не розшифровано там, де вони трапляються: ADEV, девіація Аллана; BW, смуга пропускання; CAI, холодноатомний інтерферометр; CZML, Cesium Language; Δ-DOR, дельта-диференціальне односпрямоване вимірювання дальності; DO-229E, стандарт приймачів SBAS від RTCA (Radio Technical Commission for Aeronautics); EKF, розширений фільтр Калмана; FM, частотна модуляція; GSE, наземне допоміжне обладнання; HPL/VPL, горизонтальний/вертикальний рівень захисту; IMU, інерціальний вимірювальний блок; IOAG, Interagency Operations Advisory Group; IQ, відліки синфазної/квадратурної складових; ISL, міжсупутникова лінія; ITU-T, Сектор стандартизації електрозв'язку Міжнародного союзу електрозв'язку; J2–J6, зональні гармоніки гравітації Землі ступенів від 2 до 6; KIF, Kshana Interchange Format; KML, Keyhole Markup Language; KPI, ключовий показник ефективності; L1/L5, несівні діапазони GNSS (L2 гало-орбіт CR3BP — натомість точка Лагранжа 2 системи Земля–Місяць); LEO, низька навколоземна орбіта; LOO, виключення по одному; LTC, Координований місячний час; MEO, середня навколоземна орбіта; MTIE, максимальна похибка часового інтервалу; N2, число різноманітності Хілла порядку 2; NED, північ-схід-вниз; NTN, нетеррестріальна мережа; OD, визначення орбіти; OPS-SAT, супутник-лабораторія програмного забезпечення на орбіті Європейського космічного агентства; PPP, прецизійне точкове позиціонування; PSD, спектральна густина потужності; PVT, положення, швидкість і час; RINEX, Receiver Independent Exchange Format; RK4 / RK5(4), інтегратори Рунге–Кутти четвертого порядку та вкладений п'ятого(четвертого) порядку; SH, сферична гармоніка; SigMF, Signal Metadata Format; SIR, вибірка за важливістю з передискретизацією; SRIF, кореневий інформаційний фільтр; SRP, тиск сонячного випромінювання; SSC, коефіцієнт спектрального розділення; STK, Systems Tool Kit; SVG, Scalable Vector Graphics; TDEV, девіація часу; TDM, повідомлення з даними стеження CCSDS (Consultative Committee for Space Data Systems); TLE, двостроковий набір елементів; TPL, рівень захисту часу; UBX, двійковий протокол u-blox; UHF, ультрависока частота; VLBI, радіоінтерферометрія з наддовгою базою; VRW / ARW, випадкове блукання швидкості / кута; WASM, WebAssembly.

---

1. Структура модулів#

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 (інтерфейс командного рядка) і обидві прив'язки сходяться в одній точці входу api::run_toml, тож ніколи не розходяться. Пакети повторно використовують спільне ядро (types, scenario, allan); Пакет 4 (hybrid) компонує моделі та оцінювачі Пакетів 1–3, а не реалізує їх наново; orbit виводить часову лінію GNSS із геометрії, що далі живить прогін Пакета 1. Модуль navsignal міститься на рівні сигналу між бюджетом лінії зв'язку та областю вимірювань: він виводить коефіцієнт спектрального розділення κ із фактичних спектрів потужності сигналу та глушника, з якого jamming тепер обчислює свій захист від глушіння Q = 1/(R_c·κ), а не бере репрезентативну сталу (перехресно перевіряється в CI (безперервна інтеграція)); він також містить компроміс проєктування кодів дальності (m-послідовності/Голда).

Ще три модулі утворюють хребет стійкості за відсутності GNSS. holdover безпосередньо відповідає на операційне запитання — як довго цей годинник може працювати вільно, доки його похибка часу не перевищить бюджет? — надаючи замкнену форму похибки вибігу за ван Лоаном як обернення «holdover до порога», перехресно перевірену за багатокроковою рекурсією коваріації clock_state. Його інерційний двійник живе в inertial::quantum_imu (QuantumNavBudget), що поєднує дрейф білого шуму холодноатомного інтерферометра зі зміщенням і похибкою масштабного коефіцієнта в бюджет дрейфу положення за holdover (складову зміщення перехресно перевірено за незалежним інтегратором AccelModel). verification відтворює матрицю «вимога → модуль → тест → оракул → стан» усього рушія з перевіреними модульними тестами інваріантами, що забороняють мітку validated без незалежного зовнішнього оракула, тож твердження про гарантії не може розійтися з кодом.

1a. Шари астродинаміки, злиття та альтернативного PNT#

Окрім ядра пакетів датчиків, три підсистеми ділять те саме спільне ядро й живлять orbit (або живляться від нього). Шар астродинаміки / чисельних методів додає неаналітичний пропагатор Коуелла поряд з аналітичним шляхом SGP4/SDP4; шар злиття несе оцінювачі GNSS/INS; а шар альтернативного PNT — це зіставлення з гравітаційною картою за відсутності GPS (GPS: Global Positioning System). Це можливості бібліотеки/сценарію (див. CAPABILITY, які з них під'єднано до виду сценарію kind, а які доступні як API (інтерфейс програмування застосунків) Rust).

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

Силові члени чисельного пропагатора типово вимкнені, тож їхнє ввімкнення ніколи не збурює випущені еталонні результати. 17-станний тісно зв'язаний UKF (unscented Kalman filter, фільтр Калмана без запаху) долає відмову GNSS на виведеному випадковому блуканні швидкості акселерометра квантового CAI; визначення орбіти повторно використовує ті самі forces/integrator, щоб пропагувати стан-кандидат уздовж дуги стеження.

Те саме спільне ядро несе ще чотири підсистеми, не зображені вище (їхні пакети з'являються в диспетчеризації §4): шар часу та систем відліку (timescales, jd2, precession, nutation, cio, frames, eop), що редукує TEME↔GCRS↔ITRS (TEME: істинний екватор, середнє рівнодення) і живить пакет ephemeris/траси на поверхні; шар цілісності (raim, sbas) для RAIM/ARAIM/SBAS; шар стійкості (jamming, spoof, spoof_detect, spoof_monitors, detection) для глушіння та багаторівневого виявлення спуфінгу, з шаром навігаційного сигналу (navsignal) на рівні сигналу — спектральні густини потужності BPSK-R (BPSK: двопозиційна фазова маніпуляція) / sine-BOC (BOC: двійкова зміщена несівна), коефіцієнт спектрального розділення κ, з якого тепер виводиться захист jamming від глушіння Q, середньоквадратична (за Габором) смуга дальнометрії, флуктуація стеження за кодом когерентним DLL (контур стеження за затримкою) «рано–пізно» й обвідна похибки багатопроменевості (аналіз характеристик сигналу, не проєктування радіочастотного (РЧ) корисного навантаження / антенної апаратури — роль партнера з корисного навантаження); і місячний / цисмісячний шар (lunar, lunar_frame, lunar_od, cr3bp) для динаміки CR3BP (обмежена кругова задача трьох тіл), зокрема матриці переходу стану 6×6 і диференційного коректора одиночної стрільби (cr3bp_jacobian, propagate_state_stm, differential_correct_halo), що дає справді періодичні гало-орбіти/NRHO (NRHO: майже прямолінійна гало-орбіта), відтворюючи опубліковану південну NRHO L2 9:2 (орбіту Gateway) з періодом ≈ 6,57 доби / періселенієм ≈ 3 250 км (опубліковано ≈ 6,56 доби / ≈ 3 370 км); селеноцентричне перетворення MCI/MCMF (MCI: місяцецентрична інерційна; MCMF: місяцецентрична, фіксована відносно Місяця) скоригованої орбіти та продовження за родиною залишаються подальшими кроками, а NRHO є розв'язком CR3BP (кругова, без Сонця), не валідованим за справжніми ефемеридами LANS/Gateway (LANS: Lunar Augmented Navigation Service), — і цілісність LunaNet. Підгонка моделі сил до ефемерид агентств (precise_od, lunar_od, tides, gravity_sh) і повний набір полів альтернативного PNT (igrf, altpnt/terrain, gravimeter) завершують список модулів; про зрілість кожного модуля див. CAPABILITY.

1b. Дослідження стійкості, оцінювання машинного навчання та відтворювані артефакти#

П'ять додаткових груп модулів утворюють відкритий шар відтворюваних досліджень за науковими статтями проєкту. На відміну від kind сценаріїв, до них звертаються як до генераторів cargo run --example / --bin, що записують побайтово детерміновані артефакти (фіксовані зерна, записана версія рушія + хеш конфігурації). Усі вони MODELLED (синтетичне або калібрування за публічним набором даних) і мають чесні мітки валідації — жодна не є сертифікацією.

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 — умовний рівень захисту часу (Timing Protection Level): обмежена holdover межа невиявленої похибки часу за спуфінгу, що поєднує нижню межу монітора k-σ, дисперсію вибігу за ван Лоаном за затримку виявлення та час до тривоги CUSUM (кумулятивна сума); відкалібровано за справжнім записаним спуфінгом (JammerTest 2024). Скінченної безумовної межі немає — TPL умовний щодо того, що незалежна перехресна перевірка виявляє атаку.
• resilience/ — рушій оцінювання стійкості PNT, узгоджений із рамками (категорії DHS (Міністерство внутрішньої безпеки США) RPCF (Resilient PNT Conformance Framework)), а також дослідження нестабільності рішень: симплекс вагових коефіцієнтів Діріхле, нестабільність рангів за τ Кендалла, частота зміни переможця top-1 і колапс різноманітності загального режиму (Hill-N2), зі звітом про гарантії із захищеним хешем цілісності та 35 вручну виведеними тестами за оракулом. Див. RESILIENCE-CROSSWALK. Синтетичні архітектури, узгоджені з RPCF v2.0 — самооцінка, а не сертифікація.
• impairment_eval / impairment_study / impairment_ml / eval_stats — дослідження розриву оптимізму для РЧ-ушкоджень: розмічений синтетичний корпус і незалежний від детектора інструментарій ROC/AUC (ROC: робоча характеристика приймача; AUC: площа під кривою), панель із 13 детекторів (енергія/AGC/SQM/парність (AGC: автоматичне регулювання підсилення; SQM: моніторинг якості сигналу) плюс детектори логістичної регресії із зерном і MLP з одним прихованим шаром (MLP: багатошаровий перцептрон)), закони масштабування в розподілі й поза ним із перестановочною нульовою гіпотезою та предиктор погіршення поза розподілом за схемою виключення по одному. Метрики оцінювання валідовано біт у біт за scikit-learn.
• sdr / realdata — вхідний тракт програмного приймача (необроблений IQ/IF (IQ: синфазна/квадратурна складові; IF: проміжна частота) → відводи кореляторів early/prompt/late → SQM) та адаптери введення (RINEX, u-blox UBX, GnssLogger, JammerTest, Yunnan, SatGrid), що дають змогу тим самим детекторам працювати із записами, наданими локально; жодних наборів даних у репозиторій не закомічено.
• crossover / quantum_trade — карта перетину стійкості «квантові проти класичних» за невизначеності параметрів і компроміс виграшу holdover за виміряною ADEV; чисельні ядра цього компромісу валідовано за scipy.

1c. Шари цілісності, GNSS, далекого космосу, Місяця та місій#

Решта доменів підключаються до тієї самої диспетчеризації api і повторно використовують спільне ядро, системи відліку та геометрію. Усе тут — MODELLED, якщо рядок матриці verification не посилається на зовнішній оракул (ядро RAIM проти SciPy, SBAS проти форку RTKLIB (відкрита бібліотека кінематичного позиціонування в реальному часі), ядро DOP (погіршення точності) gnss_lib_py, оцінювання OPS-SAT, ядро рівня захисту місячного ARAIM, міжпостачальницька узгодженість місячних ефемерид) — решта місячного набору й квантовий демонстратор змодельовані, ілюстративні, на публічних джерелах і не несуть жодного твердження про TRL (рівень технологічної готовності) / досвід польотів / схвалення агентствами.

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. PNT на LEO, спектр, Сонячна система, мережева синхронізація часу, кампанії та виходи#

Найновіші шари дотримуються того самого шаблону: кожен — це один чи кілька kind сценаріїв, що диспетчеризуються з api, побудованих на спільному ядрі, і MODELLED, якщо рядок матриці не називає зовнішній оракул.

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

Подробиці за кожним видом див. у LEO-PNT, LEO-SIGNAL, LEO-PASS, LEO-NAVMSG, LEO-PNT-FUSION, SPECTRUM, CONSTELLATION-DESIGN, TELECOM-TIMING, SLOT-TIMING, CAMPAIGNS, REPORTS, ANIMATION і INTEROP.

1e. Шари довіри до приймача, доказів, телеметрії, навчання та compliance (0,35)#

Ці шари читають власний журнал приймача або записують файли для інших інструментів; жоден із них не синтезує й не передає радіочастотний сигнал. Вони розташовані поряд із api, а не під видами сценаріїв, окрім самого receiver-trust, який є видом сценарію. Усі вони MODELLED, якщо рядок матриці не називає зовнішній оракул, а морські виходи є консультативними, не навігаційним обладнанням із затвердженням типу.

Інтеграції для суден (плагін Signal K, режим шлюзу OpenCPN та еталонна збірка) викликають інструмент командного рядка; див. MARINE-INTEGRATIONS.

2. Конвеєр рушія (на один прогін)#

Кожен прогін проводить одну модель сенсора крізь сітку часу, синхронізуючи її, поки GNSS номінальний, і даючи їй працювати вільно (holdover / навігація за лічильником шляху) під час відмови.

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

Сценарій двічі проходить цей конвеєр — один раз для квантового сенсора, один раз для класичного — з незалежними зернами (classical_seed = seed + 0x9e3779b97f4a7c15), щоб дві реалізації шуму були некорельованими.

3. Інтерфейс моделі похибок (точка розширення)#

Кожен сенсор реалізує одну й ту саму ідею: об'єкт зі станом, чий step() просуває його внутрішню стохастичну похибку, а накопичений стан зчитується на кожному такті. Годинники подають накопичену фазу; акселерометри — двічі проінтегроване положення; лінії зв'язку — джитер для кожного вимірювання.

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 } передається до результату, тож кожен показник у виході можна простежити до опублікованого джерела, названого в provenance.

Поряд з аналітичним HoldoverEstimator пакет годинника запускає двостановий (фаза, частота) фільтр Калмана (KalmanClock), шум процесу якого відповідає істинній моделі. Під час вибігу крізь відмову дисперсія його похибки фази зростає точно до q_wf·T + q_rw·T³/3 — аналітичного співвідношення holdover, — а його поточна межа 1-σ використовується для заповнення показника якості Цілісність (частка відліків відмови, у яких похибка залишається в межі k-σ).

4. Диспетчеризація (CLI та прив'язки)#

api::run_toml(src) — єдина точка входу: вона зазирає у верхньорівневе kind, десеріалізує відповідний сценарій, запускає пакет і повертає { json, svg, summary, csv } (csv присутній лише для тих видів, що публікують таблицю відтворюваності). CLI записує це у файли разом зі звітом (report.html, report.json) і будь-яким виходом --export / --animate; прив'язки Python і WebAssembly повертають це хосту. Одна диспетчеризація, без розбіжностей.

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

Диспетчеризація відбувається за типізованим переліком ScenarioKind з вичерпним зіставленням (див. наступний підрозділ), тому додавання пакета — це зміна, яку перевіряє компілятор. Відсутнє kind повертається до пакета clock, тож наявні сценарії одного виду десеріалізуються без змін (serde ігнорує поле kind у кожній структурі сценарію). Нерозпізнане kind відхиляється з KshanaError::InvalidInput, що називає найближчий вбудований вид, якщо назва схожа на описку.

Типізована диспетчеризація та структурований API#

Диспетчеризація відбувається за типізованим переліком ScenarioKind, а не за зіставленням сирого рядка: ScenarioKind::classify(src) зіставляє поле kind з варіантом, а диспетчер зіставляє його вичерпно — додавання пакета є зміною, яку перевіряє компілятор, а не друкарською помилкою в рядку. Поряд зі строковим run_toml (залишеним для CLI та наявних прив'язок) є дві типізовані поверхні:

• run_scenario(src) -> Result<RunOutput, KshanaError> — типізований вхід зі структурованою таксономією помилок (InvalidInput, NonConvergence, Unsupported, IoError). Кожна помилка несе стабільний kind_tag(), щоб викликач міг розгалужуватися за категорією збою, а не розбирати повідомлення. Прив'язки відкривають це як error_kind(toml).
• list_scenario_kinds() -> Vec<ScenarioMeta> (і list_scenario_kinds_json(), відкрите в прив'язках як list_kinds()) — програмна інтроспекція: назва кожного виду, опис та обов'язкові/необов'язкові поля, для автодоповнення в UI (інтерфейс користувача) і в блокнотах.

Розширення Kshana зовнішнім пакетом#

Сторонній пакет реалізує два невеликі трейти зі стабільним semver із 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 також має типовий метод register_into(&mut PackRegistry), який нічого не робить, якщо пакет не вибирає шов диспетчеризації реєстру в src/registry.rs. Вбудований пакет jamming підключено через Scenario як робочий приклад; пакети поза деревом дотримуються того самого контракту без форка ядра (за аналогією з точкою розширення ErrorModel у §3, яку використовує приватне накладення стійкості).

Тож Kshana має два стабільні шви розширення — додати сенсор, реалізувавши ErrorModel (§3), або додати цілий вид сценарію, реалізувавши Scenario + ExternalPack — обидва зі стабільним semver, жоден не потребує форка ядра:

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. Гібридний підсумковий пакет#

Гібридний пакет запускає набір (один годинник + один інерціальний сенсор) і вимагає, щоб і час, і положення залишалися в межах специфікації; pnt_holdover — це час до першого порушення будь-якого з них. За потреби оптична міжсупутникова лінія повторно синхронізує годинник під час відмови — лише підтримка за часом; положення не синхронізується повторно, бо передавання часу дає час, а не положення. Саме це виокремлює інерціальний сенсор як обмежувальний чинник.

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, виведена з геометрії#

orbit.rs — детермінований шар геометрії без залежностей. Propagator — це або аналітична кеплерова Orbit (двотільна, за потреби з вековим J2), або повний пропагатор Sgp4, побудований із повного двострокового набору елементів; генератор Walker-delta створює синтетичні орбітальні угруповання, а пряма видимість = затуляння Землею + маска висоти. Кількість видимих супутників відображається на стан GNSS (≥4 = номінальний, 1–3 = погіршений, 0 = відмовлений), а build_timeline перетворює це на часову шкалу доступності, що керує стандартним прогоном holdover годинника. Отже, доступність виводиться з геометрії, а не задається вручну, тоді як прогін, оцінювач і оцінювання лишаються незмінними.

Орбітальне угруповання, задане повними TLE, пропагується моделлю SGP4/SDP4 у sgp4.rs (перевіреною за векторами AIAA (American Institute of Aeronautics and Astronautics) 2006-6753); елементи лише з рядка 2 зберігають аналітичний двотільний шлях. Обидва способи можна змішувати в одному блоці угруповання.

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. Прив'язки#

Ядро без змін компілюється в нативний код, у розширення Python і в WebAssembly. Модулі Python (python.rs, PyO3 abi3) і WebAssembly (wasm.rs, wasm-bindgen) — необов'язкові залежності, що вмикаються функціями (--features python / --features wasm): типова збірка й набір тестів їх ніколи не компілюють, тоді як перевірка аудиту залежностей (cargo deny --all-features) таки перевіряє їхні дерева залежностей, адже ці крейти постачаються всередині wheel і пакета npm. Обидва викликають api::run_toml, тож усі поверхні повертають однакові результати. Модуль WebAssembly підтримує браузерний майданчик у web/ і експортує тринадцять функцій: run, run_all (один прогін рушія, що повертає результат, діаграму, підсумок і таблицю разом), chart_svg, summary, table_csv, list_kinds, error_kind, version, кодек encode_permalink / decode_permalink для посилань, якими можна ділитися (URL: вебадреса), і три експортери export_sp3 / export_omm / export_oem, що підтримують меню експорту майданчика. Ще два входи ведуть до того самого api: сервер MCP (Model Context Protocol) (mcp/kshana-mcp, крейт rmcp, виключений з робочого простору, що відкриває п'ятнадцять інструментів — 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; два інструменти прикладів читають вбудовані сценарії через типово вимкнену функцію бібліотеки bundled-scenarios, яку вмикає лише цей сервер) і плагін для JetBrains IDE (інтегроване середовище розробки) (ide/jetbrains, проєкт на Kotlin, що викликає CLI kshana в оболонці, а не компонує бібліотеку).

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

Керування функціями: Python і WASM вмикаються через --features python / --features wasm; вбудована таблиця сценаріїв — через --features bundled-scenarios (єдине використання її сервером MCP); сервер MCP і перехресні перевірки xval/* — крейти, ВИКЛЮЧЕНІ з робочого простору; плагін IDE нічого не компонує — він запускає CLI.

8. Детермінізм і відтворюваність#

• Уся випадковість проходить через один засіяний ChaCha8Rng на прогін; порядок кроків фіксований, тож (scenario, seed, engine version) → identical bits.
• Результат містить scenario_hash SHA-256 (SHA: Secure Hash Algorithm); scripts/check-reproducible.sh двічі запускає еталонний сценарій і перевіряє побайтово ідентичний вихід.
• Той самий рушій компілюється в нативний код, у розширення Python і в wasm32-unknown-unknown для прогонів у браузері, що дають ті самі числа.

9. Відкладена / майбутня структура#

Шари астродинаміки, злиття даних і alt-PNT з §1a — повний пропагатор SGP4/SDP4, числовий пропагатор Cowell із силовою моделлю з семи збурень і двома адаптивними інтеграторами, проєктування маневрів/траєкторій, визначення орбіти, оцінювачі GNSS/INS з 15, 8 і 17 станами, зв'язаний фільтр годинника й положення та зіставлення гравітаційних карт — усі вже реалізовані, поряд з показником якості безпеки з активним демонстратором спуфінгу, реальною геометрією TLE/кількох орбітальних угруповань, смугами Монте-Карло, торговими дослідженнями з перебором параметрів, друкованим звітом HTML (HyperText Markup Language) з його машинночитним двійником та робочими процесами випуску/публікації/wheels/pages.

Кілька можливостей, що колись значилися тут як майбутня робота, відтоді реалізовані і описані вище або в VALIDATION: повна нутація IAU 2000A і редукція CIO GCRS↔ITRS / ITRF (International Terrestrial Reference Frame) без рівнодення (перевірена побітово за SOFA/ERFA (SOFA: Standards of Fundamental Astronomy; ERFA: Essential Routines for Fundamental Astronomy)), геопотенціал EGM2008 (Earth Gravitational Model 2008) до ступеня/порядку 70, доданок Лензе–Тіррінга (захоплення інерціальних систем), твердоплинні/океанічні/атмосферні припливи, перехресна перевірка ефемерид рівня DE (DE440/ANISE (DE440: Development Ephemeris 440; ANISE: Attitude, Navigation, Instrument, Spacecraft, Ephemeris — інструментарій планетарної геометрії на чистому Rust)), зовнішня перехресна перевірка за Orekit 12,2 числового пропагатора Cowell (0,08 м за 24 год) і пакетного та послідовного визначення орбіти, а також 17-станний щільно зв'язаний навігатор, представлений як вид сценарію hybrid-ukf.

Решта подальших робіт відстежується в CHANGELOG [Unreleased] і в покапабіліті-дорожній карті в CAPABILITY: зовнішнє оракульне значення для оцінювача EGM (Earth Gravitational Model) високого ступеня точно на полярній осі та чисте щодо pyshtools порівняння поблизу полюса (оцінювач до ступеня 2190 і його завантажувач .gfc під час виконання постачаються, MODELLED; див. xval/high-degree-gravity/), змінний у часі драйвер космічної погоди для необов'язкового рівня густини опору NRLMSISE-00 (NRLMSISE: Naval Research Laboratory Mass Spectrometer and Incoherent Scatter Radar Extended atmosphere model) (типова густина опору — статична експоненційна модель, а густина Jacchia-71 для виду space-weather схарактеризована відносно NRLMSISE-00, але не замінена нею), зовнішня перевірка необов'язкової тіні з потемнінням до краю сонячного диска, щільне зв'язування GNSS/INS за фазою несівної та реальна гравітаційна карта EGM2008/EIGEN (EIGEN: European Improved Gravity model of the Earth by New techniques) для зіставляча alt-PNT.

Приватний репозиторій-накладення містить глибину стійкості з експортними обмеженнями; він підключається через той самий інтерфейс ErrorModel (і контракт ExternalPack у §4) без змін у публічному рушії.