Kshana：架构

Kshana是一个引擎，在共享核心之上分层组织：传感器包（时钟、惯性、时间传递、混合）；天体动力学 / 数值层（解析SGP4/SDP4（SGP4：简化通用摄动4；SDP4：简化深空摄动4）、带七项摄动力模型的数值Cowell传播器、机动设计、基于地面站测距的定轨，以及对照机构精密星历的力模型拟合）；时间与坐标系层（IERS（国际地球自转与参考系服务）时间尺度、IAU（国际天文学联合会）2006/2000A岁差–章动，以及CIO（天球中间零点）GCRS↔ITRS（GCRS：地心天球参考系；ITRS：国际地球参考系）归算）；融合层（GNSS/INS（GNSS：全球导航卫星系统；INS：惯性导航系统）估计器）；完好性、韧性、alt-PNT（PNT：定位、导航与授时）和月球层（RAIM/ARAIM/SBAS（RAIM：接收机自主完好性监测；ARAIM：先进接收机自主完好性监测；SBAS：星基增强系统）、压制干扰与多层欺骗检测、重力/地形/磁场地图匹配，以及地月空间PNT）；以及较新的LEO-PNT（低地球轨道PNT）、频谱、太阳系与星座设计、网络授时和测评活动层，外加每次运行都可使用的报告、动画和互操作性写出器（§1d）。在所有这些层中，引擎对“量子”与“经典”一无所知：它通过GNSS中断场景驱动传感器误差模型，运行估计器，并对结果评分。因此，量子器件和经典器件是在同一场景上比较的，二者的区别仅在于其（已公布、有引用的）误差参数及各自独立的噪声随机种子。

本文档汇集结构图和行为图。§1是传感器包核心；§1a描绘此后新增的天体动力学、融合和alt-PNT层；§1b–§1d为研究、领域和输出层。用法见README；哪些已独立检查、哪些没有，见VALIDATION；各项能力的成熟度表见CAPABILITY。

图中使用、且在出现处未展开的缩写：ADEV，阿伦偏差；BW，带宽；CAI，冷原子干涉仪；CZML，Cesium语言；Δ-DOR，差分单向测距；DO-229E，RTCA（无线电技术委员会Radio Technical Commission for Aeronautics）SBAS接收机标准；EKF，扩展卡尔曼滤波器；FM，调频；GSE，地面保障设备；HPL/VPL，水平/垂直保护级；IMU，惯性测量单元；IOAG，机构间运行咨询组；IQ，同相/正交采样；ISL，星间链路；ITU-T，国际电信联盟电信标准化部门；J2–J6，地球2至6阶带谐重力系数；KIF，Kshana交换格式；KML，Keyhole标记语言；KPI，关键绩效指标；L1/L5，GNSS载波频段（CR3BP晕轨道的L2则是地月拉格朗日点2）；LEO，低地球轨道；LOO，留一法；LTC，协调月球时；MEO，中地球轨道；MTIE，最大时间间隔误差；N2，2阶Hill多样性数；NED，北东地；NTN，非地面网络；OD，定轨；OPS-SAT，欧洲航天局的在轨软件实验室卫星；PPP，精密单点定位；PSD，功率谱密度；PVT，位置、速度和时间；RINEX，接收机无关交换格式；RK4 / RK5(4)，四阶和嵌入式五（四）阶龙格–库塔积分器；SH，球谐；SigMF，信号元数据格式；SIR，采样重要性重采样；SRIF，平方根信息滤波器；SRP，太阳辐射压；SSC，频谱分离系数；STK，Systems Tool Kit；SVG，可缩放矢量图形；TDEV，时间偏差；TDM，CCSDS（空间数据系统咨询委员会）跟踪数据消息；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序列/Gold码）的设计权衡。

另有三个模块构成GNSS拒止下的韧性主干。holdover直接回答运行中的问题：这个时钟自由运行多久，其授时误差才会超出预算？它把van-Loan滑行误差闭式解表示为从守时（holdover）到阈值的反演，并与多步clock_state协方差递推交叉验证。其惯性对应物位于inertial::quantum_imu（QuantumNavBudget），它把冷原子干涉仪的白噪声漂移与偏置和比例因子误差组合成守时期间的位置漂移预算（偏置项已与独立的AccelModel积分器交叉验证）。verification呈现整个引擎从要求到模块、到测试、到参考基准（oracle）、到状态的矩阵，其经过单元测试的不变量禁止在没有独立外部参考基准（oracle）时使用“已独立检查”标签，因此保证性声明无法与代码相偏离。

1a. 天体动力学、融合与alt-PNT层#

在传感器包核心之外，另有三个子系统共用同一个共享核心，并向orbit提供输入（或由其提供输入）。天体动力学 / 数值层在解析SGP4/SDP4路径之外增加了非解析的Cowell传播器；融合层承载GNSS/INS估计器；alt-PNT层是GPS拒止（GPS：全球定位系统）下的重力地图匹配。这些是库/场景层面的能力（哪些接入场景kind、哪些只能作为Rust API（应用程序接口）使用，见CAPABILITY）。

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（无迹卡尔曼滤波器）在GNSS中断期间依靠量子CAI加速度计推导出的速度随机游走滑行；定轨复用同一套forces/integrator，在跟踪弧段上传播候选状态。

同一个共享核心还承载另外四个上图未绘出的子系统（其包出现在 §4的分派中）：时间与坐标系层（timescales、jd2、precession、nutation、cio、frames、eop），归算TEME↔GCRS↔ITRS（TEME：真赤道平春分点），并为ephemeris/星下点轨迹包提供输入；用于RAIM/ARAIM/SBAS的完好性层（raim、sbas）；用于压制干扰和多层欺骗检测的韧性层（jamming、spoof、spoof_detect、spoof_monitors、detection），以及位于信号层的导航信号层（navsignal）：BPSK-R（BPSK：二进制相移键控）/ 正弦BOC（BOC：二进制偏移载波）功率谱密度、现用于推导jamming抗干扰Q的频谱分离系数κ、RMS（Gabor）测距带宽、相干超前–滞后DLL（延迟锁定环）码跟踪抖动，以及多路径误差包络（信号性能分析，不是射频（RF）有效载荷 / 天线的硬件设计，那是有效载荷合作方的角色）；还有月球 / 地月空间层（lunar、lunar_frame、lunar_od、cr3bp），用于CR3BP（圆形限制性三体问题）动力学，包括6×6状态转移矩阵和单次打靶微分修正器（cr3bp_jacobian、propagate_state_stm、differential_correct_halo），可产生真正周期性的晕轨道/NRHO（NRHO：近直线晕轨道），复现已公布的L2南向9:2 NRHO（Gateway轨道），周期 ≈ 6.57 d / 近月点 ≈ 3,250 km（已公布 ≈ 6.56 d / ≈ 3,370 km）；修正后轨道的月心MCI/MCMF（MCI：月心惯性；MCMF：月心月固）变换和族延拓仍有待后续完成，且该NRHO是CR3BP（圆形、无太阳）的解，并未对照真实的LANS/Gateway（LANS：月球增强导航服务）星历验证；以及LunaNet完好性。机构星历力模型拟合（precise_od、lunar_od、tides、gravity_sh）和完整的alt-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：条件授时保护级，即对欺骗下未检出的时间误差的受守时（holdover）限制的界限，它由k-σ 监测下限、检测延迟内的van-Loan滑行方差和CUSUM（累积和）报警时间组合而成；以一次真实记录的欺骗（JammerTest 2024）校准。不存在有限的无条件界限：TPL以独立的交叉检查能检测到攻击为条件。
• resilience/：与框架对齐的PNT韧性评分引擎（DHS（美国国土安全部）RPCF（韧性PNT一致性框架）类别），外加决策不稳定性研究：Dirichlet权重单纯形、Kendall-τ 排名不稳定性、top-1胜出者翻转率和共模多样性坍缩（Hill-N2），并带有完整性哈希的保证报告和35个手工推导的参考基准（oracle）测试。见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：中频）→ 相关器超前/即时/滞后抽头 → SQM）以及摄取适配器（RINEX、u-blox UBX、GnssLogger、JammerTest、Yunnan、SatGrid），使同样的检测器能在本地提供的记录上运行；仓库中不提交任何数据集。
• crossover / quantum_trade：参数不确定性下的量子与经典韧性交叉图，以及实测ADEV的守时（holdover）收益权衡；该权衡的数值内核已对照scipy验证。

1c. 完好性、GNSS、深空、月球与任务层#

其余领域接入同一个api分派，复用共享核心、坐标系和几何。此处一切均为MODELLED，除非某个verification矩阵行引用了外部参考基准（oracle）（RAIM内核对照SciPy、SBAS对照RTKLIB（一个开源实时动态定位库）分支、gnss_lib_py的DOP（精度因子）内核、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. LEO PNT、频谱、太阳系、网络授时、测评活动与输出#

最新的各层遵循同一模式：每层是一个或多个由api分派的场景kind，建立在共享核心之上，并且为MODELLED，除非某个矩阵行指明了外部参考基准（oracle）。

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）#

这些层读取接收机自己的日志，或为其他工具写出文件；它们都不合成或发射射频信号。除receiver-trust本身是场景类型外，它们位于api旁边，而不在各场景类型之下。除非某个矩阵行指明了外部参考基准（oracle），一切均为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（用户界面）和notebook自动补全使用。

用外部包扩展Kshana#

第三方包需要实现api中两个小型且遵循语义化版本稳定性的trait：

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接入，作为示例；树外的包遵循同一约定，无需复刻核心代码（与 §3中的ErrorModel扩展点相对应，私有的韧性叠加层即使用该扩展点）。

因此Kshana有两个稳定的扩展接缝：通过实现ErrorModel（§3）添加一种传感器，或通过实现Scenario + ExternalPack添加整类场景类型；两者都遵循语义化版本稳定性，都无需复刻核心代码：

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.rs中的SGP4/SDP4模型传播（已对照AIAA（美国航空航天学会）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）会检查它们的依赖树，因为这些crate随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（模型上下文协议）服务器（mcp/kshana-mcp，一个排除在工作区之外的rmcp crate，提供十五个工具：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项目，通过调用kshana CLI工作，而不是链接该库）。

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/*交叉检查是被工作区排除的crate；IDE插件不链接任何内容，只运行CLI。

8. 确定性与可复现性#

• 所有随机性都来自每次运行中单一的带种子ChaCha8Rng；步骤顺序固定，因此(scenario, seed, engine version) → identical bits。
• 结果带有SHA-256（SHA：安全散列算法）scenario_hash；scripts/check-reproducible.sh将一个参考场景运行两次，并断言输出逐字节一致。
• 同一个引擎可编译为原生程序、Python扩展，以及用于浏览器内运行的wasm32-unknown-unknown，并产生相同的数值。

9. 已推迟 / 未来的结构#

§1a中的天体动力学、融合和alt-PNT层，包括完整的SGP4/SDP4传播器、带七项摄动力模型和两种自适应积分器的数值Cowell传播器、机动/轨迹设计、定轨、15/8/17状态的GNSS/INS估计器、时钟与位置耦合滤波器以及重力图匹配，均已发布；同时发布的还有带主动欺骗干扰（spoofing）演示器的安全性能指标、真实TLE/多星座几何、蒙特卡罗置信带、权衡研究扫描、带机器可读副本的可打印HTML（超文本标记语言）报告，以及发布/发版/wheels/pages工作流。

此前列为未来工作的若干能力现已发布，见上文或VALIDATION：完整的IAU 2000A章动和无春分点的CIO GCRS↔ITRS / ITRF（国际地球参考框架）归算（已对照SOFA/ERFA（SOFA：基础天文学标准；ERFA：基本天文例程）逐位验证），EGM2008（地球重力场模型2008）位势至70阶次，Lense–Thirring参考系拖曳项，固体潮/海潮/大气潮，DE级（DE440/ANISE（DE440：星历表440；ANISE：姿态、导航、仪器、航天器、星历，一个纯Rust的行星几何工具包））星历交叉验证，对数值Cowell传播器（24 h内0.08 m）以及批处理和序贯定轨所做的外部Orekit 12.2交叉验证，以及作为hybrid-ukf场景类型提供的17状态紧耦合导航器。

其余后续工作记录在CHANGELOG [Unreleased]中，各项能力的路线图见CAPABILITY：针对EGM（地球重力场模型）高阶评估器恰好位于极轴上的外部参考基准（oracle）数值，以及无pyshtools干扰的近极点对比（评估器至2190阶，其运行时.gfc加载器已提供，MODELLED；见xval/high-degree-gravity/）；为可选的NRLMSISE-00（NRLMSISE：美国海军研究实验室质谱仪与非相干散射雷达扩展大气模型）阻力密度层提供随时间变化的空间天气驱动（默认阻力密度为静态指数模型，space-weather类型的Jacchia-71密度已对照NRLMSISE-00进行了特性分析，但并未被其取代）；对可选的太阳临边昏暗阴影做外部核查；载波相位GNSS/INS紧耦合；以及为alt-PNT匹配器提供真实的EGM2008/EIGEN（EIGEN：新技术欧洲改进地球重力模型）重力图。

一个私有叠加仓库承载受出口管制的韧性深度能力；它通过同一个ErrorModel接口（以及 §4中的ExternalPack约定）接入，不改变公开引擎。