チュートリアル

「同梱のシナリオを実行する」から「結果を定量化し擁護する」までを導く、実践的な実例です。三つのチュートリアルで引用されている数値はすべて、実際のエンジンの出力であり、外部の（循環しない）権威あるオラクルを拠り所とし、統合試験によって固定されています（tests/tutorials.rs）。そのため、チュートリアルがエンジンの実際の動作から黙ってずれることはありません。チュートリアルが光時計は 6600 秒保持すると述べていれば、それが成り立たなくなった日に、試験がビルドを失敗させます。

Kshana は、測位・航法・時刻（PNT）のシミュレーターです。チュートリアルでは、初出の箇所で正式名称を示しながら、さらにいくつかの略語を使います。GNSS（全球測位衛星システム）、GPS（全地球測位システム）、CLI（コマンドラインインターフェース）、TOML（Tom's Obvious Minimal Language、シナリオファイルの形式）です。

このプロジェクトが初めてですか。まずコンセプトの入門と用語集を読んでから、ここに戻ってください。

三つの実例#

ノートブック#

合成データと、リポジトリ内にのみ保持された公開の要素セットを使う、実行可能な Jupyter ノートブックが notebooks/ にあります。

チュートリアルの実行方法#

どのチュートリアルも同じシナリオを三通りの方法で実行します。ご自身に合うものを選んでください。いずれも一つのエンジンを呼び出すため、数値は同一です（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.toml

cargo 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 python

import json, kshana
result = json.loads(kshana.run(open("scenarios/orbit-sgp4-gps.toml").read()))
print(result["geometry"]["best_pdop"])

pip install kshana は、代わりに公開済みのホイールをインストールします。これはこのチェックアウトより遅れていることがあります。お使いのビルドにどのシナリオのカインドがあるかは、json.loads(kshana.list_kinds()) で分かります。

ブラウザーのプレイグラウンド。インストール不要です。Studio を開いてシナリオを選び、パラメーターを編集して、結果を読みます。何もアップロードされず、エンジンは WebAssembly としてクライアント側で動作します。

チュートリアルが引用するのは CLI ですが、どのコマンドにも上記の Python とプレイグラウンドでの対応するものがあります。各結果は scenario + seed + engine version から再現できます。二度実行すれば、ビット単位で同一の出力が得られます。

注釈付きの教材用シナリオ#

各機能領域には、scenarios/ の下に、コメントを豊富に付けた .toml が一つあります。これは正典となるシナリオの教材用のコピーで、すべてのフィールドがインラインで説明され、引用されたオラクルが名指しされ、期待される一行の要約が # expected: のコメントとして記録されています。フィールドの値は、リポジトリのトップレベルの scenarios/ ディレクトリにある親のシナリオと同一であり（tests/tutorials.rs が解析済みの TOML を比較します）、記載された出力は正しいまま保たれます。ゴールデンハッシュも変わりません。コメントがシナリオのハッシュを変えることはないためです。

セキュリティの教材用ファイルは、内部で kind = "spoof" を使っています。セキュリティの性能指標（1 − P_md、一から見逃し確率を引いたもの）は、spoof パックが生成します。ファイル名は機能（セキュリティ）に従い、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 は、チュートリアルが記載するすべてのカインドが実在するディスパッチ対象のカインドであることを強制するため、この表が存在しないカインドを名指すことはありません。

チュートリアルを超えて：より新しい機能#

三つのチュートリアルは、従来のクロック、軌道、セキュリティのパックにとどまっています。エンジンはそれらをはるかに超えて成長しました。下の各行は、そのまま実行できる同梱のシナリオです（cargo run -- <file> または kshana <file>）。要約は、kshana 0.35.0 が 2026-10-10 にそのシナリオについて最初に出力した行です。チュートリアルの数値とは異なり、これらの行は一回の実行の記録であり、tests/tutorials.rs によって固定されてはいません。現在の値は、シナリオを再実行して確認してください。結果はそれぞれ自身の範囲を示しており（多くは label を持ちます）、検証マトリクスには、どの機能が外部のオラクルに照らして VALIDATED で、どれが MODELLED かが示されています。

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、Consultative Committee for Space Data Systems の軌道メッセージ）もエクスポートします。INTEROP.md を参照してください。

段階別の演習#

段階を順に進めてください。各ティアは前のものより難しく、より擁護しやすくなっています。模範解答は exercises/ にあります。

模範解答は Python 拡張を使います（最初に maturin develop --features python）。リポジトリのルートから実行すると、tier2_sweep.py は、チップスケール原子時計のホールドオーバーが、20 ns の仕様での 2610 秒から、5 ns での 1140 秒へ低下する様子を出力します。

新しいデータが必要ですか。#

これらのチュートリアルの代表的な数値は、すべてリポジトリにすでにあるシナリオだけから実行されます。何も取得しないため、再現性が保たれ、継続的インテグレーション（CI）でも安全に実行できます。「拡張」演習では、ライブのデータを取得できます。

• GPS の two-line elements（TLE）（軌道コンステレーションの更新用）：https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle、プレーンテキストの 3-line の要素セット（名前 + 行 1 + 行 2）。補助スクリプト：scripts/fetch_tles.sh。オープンデータ（米国宇宙軍第 18 宇宙防衛隊のカタログを、Celestrak の Dr T. S. Kelso が再配布）。
• SGP4（Simplified General Perturbations 4）の検証オラクル（すでにベンダリング済みで、再取得は不要）：AIAA（American Institute of Aeronautics and Astronautics）2006-6753「Revisiting Spacetrack Report #3」の試験ベクトル、https://celestrak.org/publications/AIAA/2006-6753/、tests/sgp4_verification.rs が使用します。docs/SGP4-VALIDATION.md を参照してください。
• クロック安定度の関係のオラクル：NIST（National Institute of Standards and Technology）Special Publication 1065（Riley, Handbook of Frequency Stability Analysis）、https://tf.nist.gov/general/pdf/2220.pdf、チュートリアル 2 の背後にある σ_y(τ) と位相の関係。