教程
动手实践的实例演练，带你从“运行一个自带场景”走到“量化并为一个结果辩护”。三个教程中引用的每个数字都是引擎的真实输出，锚定于外部（非循环）的权威参考基准（oracle），并由一项集成测试固定（tests/tutorials.rs），因此教程绝不会悄悄偏离引擎的实际行为。如果教程说光钟守时6600 s，那么这一点哪天不再成立，测试就会使构建失败。
Kshana是一款定位、导航与授时（PNT）仿真器。教程还用到几个缩写，各自在首次出现处给出全称：GNSS（全球导航卫星系统）、GPS（全球定位系统）、CLI（命令行界面）和TOML（Tom's Obvious Minimal Language，场景文件格式）。
三个实例演练#
| # | 教程 | 你将学到 | 场景类型 | 难度 | 约需时间 |
|---|---|---|---|---|---|
| 1 | 我的第一条轨道：GPS卫星在哪里 | 外推一个真实的GPS星座，读取可用性、位置精度因子（PDOP）和位置精度，并导出卫星的实际位置（SP3精密轨道格式） | orbit |
入门 | 15分钟 |
| 2 | 时钟守时：能滑行多久 | 运行一次GNSS拒止下的时钟守时，读取授时性能指标，并理解其背后的 √(q_wf·T) 增长规律 | clock |
入门 | 20分钟 |
| 3 | 量子与经典GNSS韧性对比 | 压轴篇：欺骗干扰检测器（spoof）和完整的融合PNT套件（hybrid），以及如何把安全性、完好性与航位推算放在一起解读 |
spoof + hybrid |
中级 | 35分钟 |
Notebook#
可运行的Jupyter笔记本，使用合成数据和仅保存在仓库中的公开星历根数集，位于notebooks/：
| 笔记本 | 你将学到 |
|---|---|
| 船舶信任度与训练 | 生成带有脚本化事件的合成桥楼NMEA数据流，再用船舶信任度监测器对其评分（咨询性，不是经型式认可的导航设备） |
| 干扰地图与航线暴露 | 导航数据在何处显得劣化，以及它波及航线的多大部分 |
| compliance映射与test bench导出 | 一组运行为哪些公开框架条目提供证据支持（绝不表示某个框架已达到要求），以及把场景的运动和事件导出为文本，供实验室GNSS模拟器使用（不写出任何信号） |
| 量子与经典GDOP对比 | 同一星座几何构型下，分别搭配量子与经典传感器，按精度因子比较 |
| 天际线下的天空几何 | 某站点在街道或码头天际线下看到的卫星、其DOP与误差椭圆、由星历根数集得到的带日期的天空，以及对照协方差的带随机种子蒙特卡罗（MODELLED） |
如何运行教程#
每个教程都以三种方式运行同一个场景；选择适合你的即可。它们调用的都是同一个引擎，因此数字完全一致（对应README的用法一节）。
命令行。CLI根据场景的kind字段分派，并在输入文件旁写出<scenario>.result.json、<scenario>.chart.svg、<scenario>.report.html和<scenario>.report.json（JSON即JavaScript Object Notation，SVG即Scalable Vector Graphics，HTML即HyperText Markup Language）。少数类型还会把可复现性表发布为<scenario>.table.csv（逗号分隔值）：realtime-frame-eop、lunar-time-budget、lunar-jamming、leo-navmsg、telecom-timing，以及设置了导出站点时的moonlight-service-volume。这三个教程都不属于其中，因此你在这里不会看到该文件。
cargo run -- scenarios/orbit-sgp4-gps.tomlcargo run --从当前检出的代码构建CLI。使用已安装的二进制文件（cargo install kshana）时，同一命令为kshana scenarios/orbit-sgp4-gps.toml。没有检出代码时，大多数自带场景都打包在二进制文件中：kshana example会列出它们（并说明少数未打包的场景及原因），kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml则写出其中一个：即该二进制文件构建时所用的scenarios/orbit-sgp4-gps.toml副本。
Python。在已激活的虚拟环境中，用maturin从当前检出的代码构建一次扩展，然后调用kshana.run：
pip install maturin
maturin develop --features pythonimport json, kshana
result = json.loads(kshana.run(open("scenarios/orbit-sgp4-gps.toml").read()))
print(result["geometry"]["best_pdop"])pip install kshana则改为安装已发布的wheel。它可能落后于当前检出的代码：json.loads(kshana.list_kinds())会告诉你你的构建包含哪些场景类型。
浏览器playground。零安装：打开Studio，选择一个场景，编辑参数，查看结果。不会上传任何内容；引擎以WebAssembly形式在客户端运行。
教程引用的是CLI，但每条命令在上述Python和playground中都有等价形式。每个结果都可由scenario + seed + engine version复现：运行两次，得到逐位相同的输出。
带注释的教学场景#
每个能力领域都有一个注释详尽的.toml，位于scenarios/之下：它是某个规范场景的教学副本，每个字段都有行内说明，点明所引用的参考基准（oracle），并把预期的单行摘要记录为一条# expected:注释。字段取值与仓库顶层scenarios/目录中的原场景完全相同（tests/tutorials.rs会比较解析后的TOML），因此文档中的输出始终成立。黄金哈希也不受影响：注释绝不会改变场景哈希。
| 领域 | 教学文件 | 类别 | 派生自 |
|---|---|---|---|
| 时钟守时（holdover） | scenarios/clock.toml | clock |
scenarios/clock-holdover.toml |
| 轨道与几何 | scenarios/orbit.toml | orbit |
scenarios/orbit-sgp4-gps.toml |
| 完好性（RAIM，接收机自主完好性监测） | scenarios/integrity.toml | integrity |
scenarios/integrity-raim.toml |
| 安全性（欺骗干扰） | scenarios/security.toml | spoof |
scenarios/spoof-attack.toml |
| 混合PNT | scenarios/hybrid.toml | hybrid |
scenarios/hybrid-pnt.toml |
| 惯性航位推算 | scenarios/inertial.toml | inertial |
scenarios/imu-deadreckoning.toml |
| 时间传递 | scenarios/timetransfer.toml | timetransfer |
scenarios/timetransfer.toml |
| GNSS测量域 | scenarios/gnss-sim.toml | gnss-sim |
scenarios/gnss-sim-raim.toml |
安全性的教学文件内部使用
kind = "spoof"：安全性性能指标（1 − P_md，即1减去漏检概率）由欺骗干扰包产生。文件名遵循能力（安全性），而kind遵循包（spoof）。该文件的头部对此有说明。
完整的场景类型目录#
引擎根据场景的kind分派。下表列出最常用的类型（上述八个教程领域及其最相近的类型）。它不是完整集合：src/api.rs::list_scenario_kinds()返回全部92种内置类型。该函数（在Python和WebAssembly（WASM）绑定中以list_kinds()提供，在命令行中以kshana kinds --json提供）是权威且始终最新的目录，而SCENARIOS.md是其生成的枚举，每种类型一节，列出必需和可选的TOML字段。tests/tutorials.rs::tutorial_scenarios_use_real_kinds强制要求教程中记载的每个类型都是真实的分派类型，因此本表不会列出不存在的类型。
| 类别 | 作用 |
|---|---|
clock |
时钟守时与规格对比；可选的蒙特卡罗集合（runs > 1）。 |
inertial |
GNSS中断期间的1-DOF（一个自由度）惯性航位推算。 |
orbit |
由星座（Walker / 两行根数 / RINEX，即与接收机无关的交换格式）得出的GNSS可用性与精度因子（DOP）。 |
integrity |
快照 / 解分离 / ARAIM（先进RAIM），含水平与垂直保护级（HPL/VPL）及Stanford图。 |
lunar-integrity |
月球南极ARAIM保护级过境，对照一组LunaNet中继。 |
timetransfer |
光学与射频（RF）双向时间/频率传递的对比。 |
hybrid |
混合PNT压轴篇：时钟 + 惯性测量单元（IMU）+ 时间传递辅助。 |
fusion |
基于同一组混合输入的联合卡尔曼传感器融合PNT。 |
gnss-ins |
松耦合与紧耦合GNSS/INS（惯性导航系统）误差状态扩展卡尔曼滤波器。 |
gnss-sim |
测量域伪距仿真（Klobuchar电离层、Saastamoinen/Niell对流层）+ RAIM。 |
jamming |
链路预算压制干扰（jamming）：干信比（J/S）→ 有效载噪比（C/N₀）→ 失锁。 |
spoof |
随机时间欺骗干扰检测器（Neyman–Pearson / χ²₁），含蒙特卡罗虚警与漏检概率（P_fa/P_md）。 |
sweep |
针对时钟包参数的1-D权衡研究扫描。 |
sweep-nd |
通过点分TOML键/JSON指标路径，对任意包进行的通用N维扫描。 |
超越教程：较新的能力#
三个教程停留在经典的时钟、轨道和安全性包上。引擎已远远超出这些范围。下表每一行都是一个自带场景，可按原样运行（cargo run -- <file>或kshana <file>）；摘要是kshana 0.35.0于2026-10-10为其输出的第一行。与教程中的数字不同，这些行只是某一次运行的记录，不由tests/tutorials.rs固定：请重新运行场景以获得当前值。结果会说明各自的适用范围（大多数带有label），而验证矩阵则说明哪些能力是VALIDATED（对照外部参考基准（oracle））、哪些是MODELLED。
| 能力 | 场景 | 类别 | 摘要的第一行 | 阅读更多 |
|---|---|---|---|---|
| L波段频谱与压制干扰（jamming）瀑布图 | scenarios/l-band-waterfall-jamming.toml |
spectrum |
scenario spectrum | 5 bands | 3 jammers | noise floor -202.0 dBW/Hz | worst band gps-l1ca min C/N0 3.2 dB-Hz (J/S 60.2 dB) |
SPECTRUM.md |
| 某一历元的太阳系 | scenarios/solar-system-tour.toml |
solar-system |
Solar system at 2026-09-28T00:00:00 (JD 2461311.50080 TDB), 18 bodies, observer Earth |
SCENARIOS.md |
| 绕另一天体的定位 | scenarios/europa-surface-pnt.toml |
body-pnt |
Positioning around Europa — surface user, 12 relays at 4500 km, 171 epochs |
SCENARIOS.md |
| 大规模星座设计 | scenarios/constellation-multi-gnss-coverage.toml |
constellation-design |
constellation-design: 102 satellites (GPS, Galileo, BeiDou, GLONASS) around the Earth; availability 100.00% (PDOP <= 6 at 10 deg mask), … |
CONSTELLATION-DESIGN.md |
| 活动：在同一条时间线上串联的各类型 | scenarios/campaign-jam-spoof-holdover-integrity.toml |
campaign |
campaign f87a4a0e0bab | Jamming, spoofing, holdover and integrity: a chained mission | chain: 6 phases over 4570 s, … |
CAMPAIGNS.md |
| 端到端的一套LEO-PNT系统 | scenarios/leo-pnt-end-to-end.toml |
leo-pnt-chain |
LEO-PNT end to end, generic 1080 km constellation |
LEO-PNT.md |
| MEO与LEO融合定位 | scenarios/meo-leo-fused-pvt.toml |
leo-pvt |
LEO PVT (joint) at 40.42, -3.70 over 1800 s |
LEO-PNT-FUSION.md |
| LEO信号、过境与导航电文 | scenarios/leo-band-trade.toml, scenarios/leo-pass-iridium.toml, scenarios/leo-navmsg-encode-decode.toml |
leo-signal, leo-pass, leo-navmsg |
LEO pass link budget, air user at 50.00, -30.00; 1 LEO satellite(s), 900 s window（过境） |
LEO-SIGNAL.md、LEO-PASS.md、LEO-NAVMSG.md |
| 带LEO层的PPP收敛；5G定位 | scenarios/leo-ppp-convergence.toml, scenarios/ntn-5g-positioning.toml |
leo-ppp, ntn-positioning |
PPP convergence to 0.10 m horizontal / 0.10 m vertical, 12 runs per case, 96 GNSS satellites |
SCENARIOS.md |
| 韧性：GNSS被压制，LEO带领用户度过 | scenarios/leo-resilience-gnss-jammed-leo-carries.toml |
campaign |
campaign 248395b851cc | GNSS jammed, LEO-PNT carries the user, integrity maintained | chain: 3 phases over 2100 s, … |
RESILIENCE-CROSSWALK.md |
| 垂直行业：铁路、海事、电信、车辆、北极 | scenarios/leo-vertical-rail-maritime.toml（以及其他leo-vertical-*文件） |
campaign |
campaign 49575d27b696 | Railway and maritime with a LEO layer | chain: 3 phases over 2520 s, … |
CAMPAIGNS.md |
| 对照ITU-T（国际电信联盟电信标准化部门）G.8272时钟限值的电信守时（holdover） | scenarios/telecom-prtc-holdover-24h.toml |
telecom-timing |
telecom-timing: max|TE| 603.2 ns over 90000 s; eprtc-a-holdover FAIL, prtc-a FAIL; 100 ns budget exceeded after 8206 s (MODELLED) |
TELECOM-TIMING.md |
LEO指低地球轨道，MEO指中地球轨道；PVT指位置、速度与时间；PPP指精密单点定位；5G指第五代移动通信标准；TDB指质心力学时；JD指儒略日；TE指钟差（时间误差）。
CLI在任何一次运行之上还增加三种输出：
- 报告。每次运行都会写出
<scenario>.report.html和<scenario>.report.json（见REPORTS.md）。kshana --study <suite.toml>把一套场景运行为一份.study.json和.study.html，例如kshana --study scenarios/quantum-pnt-demonstrator.suite.toml。 - Animation.
kshana <scenario.toml> --animate <svg|html|frames|all>渲染该次运行的时间序列，例如在scenarios/orbit-sgp4-gps.toml上使用--animate html会写出orbit-sgp4-gps.animation.html。没有采样时间轴的类型（如solar-system）会被拒绝并报错；见ANIMATION.md。 - 互操作导出。
--export <czml|kml|geojson|stk|sigmf|all|list>把结果写出，供其他工具使用：CZML（Cesium Language）、KML（Keyhole Markup Language，用于Google Earth）、GeoJSON（地理JSON）、STK（Systems Tool Kit）星历，或SigMF（Signal Metadata Format）录制文件。--export list会说明哪些格式适用于某个场景；SigMF仅适用于spectrum。轨道包还可导出--export-sp3、--export-omm和--export-oem（CCSDS，即空间数据系统咨询委员会，轨道电文）。见INTEROP.md。
分级练习#
沿着这条阶梯逐级练习。每一级都比上一级更难、更站得住脚；参考解答位于exercises/。
| 层级 | 目标 | 你要做什么 | 参考解答 |
|---|---|---|---|
| 第1级——运行并解读 | 原样运行一个自带场景，并读取一个性能指标 | 运行scenarios/clock-holdover.toml；输出量子与经典的holdover_s。可用CLI、playground，或一行Python调用。 |
exercises/tier1_run.py |
| 第2级——修改并扫描 | 改变一个参数，观察单调的影响 | 收紧时钟规格（threshold_ns）或延长中断时间，观察守时下降；也可以用kind = "sweep"/"sweep-nd"把结果列成表。 |
exercises/tier2_sweep.py |
| 第3级——量化并为结论辩护 | 蒙特卡罗、置信区间、可复现性，以及保护级 | 运行一个时钟集合（runs = N），读取 [p05–p95] 区间，确认两次运行给出相同的scenario_hash，并解读一个完好性 / Stanford图结果。 |
exercises/tier3_montecarlo.py |
参考解答使用Python扩展（先运行maturin develop --features python）。在仓库根目录运行tier2_sweep.py，会输出芯片级原子钟的守时从20 ns规格下的2610 s下降到5 ns规格下的1140 s。
想要最新数据？#
这些教程中的核心数字完全由仓库中已有的场景运行得出。不会获取任何外部数据，这正是它们可复现、并且可以安全地在持续集成（CI）中运行的原因。对于“扩展练习”，你可以拉取实时数据：
- GPS两行根数（TLE）（刷新轨道星座）：https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle，纯文本的3行根数集（名称 + 第1行 + 第2行）。辅助脚本：
scripts/fetch_tles.sh。开放数据（美国太空军第18太空防御中队目录，由Celestrak再分发，Dr T. S. Kelso）。 - SGP4（Simplified General Perturbations 4）验证参考基准（oracle）（已内置，无需重新获取）：AIAA（美国航空航天学会）2006-6753“Revisiting Spacetrack Report #3”测试向量，https://celestrak.org/publications/AIAA/2006-6753/，由
tests/sgp4_verification.rs使用；见docs/SGP4-VALIDATION.md。 - 时钟稳定度关系的参考基准（oracle）：NIST（美国国家标准与技术研究院）特别出版物1065（Riley，Handbook of Frequency Stability Analysis），https://tf.nist.gov/general/pdf/2220.pdf，即教程2背后的 σ_y(τ)↔相位关系。