Tutorials

Praxisnahe, durchgespielte Beispiele, die Sie von „ein mitgeliefertes Szenario ausführen“ zu „ein Ergebnis quantifizieren und verteidigen“ führen. Jede in den drei Tutorials genannte Zahl ist eine reale Ausgabe der Engine, verankert an einer externen (nicht zirkulären) maßgeblichen unabhängigen Referenz und durch einen Integrationstest festgeschrieben (tests/tutorials.rs), sodass ein Tutorial nie unbemerkt von dem abweichen kann, was die Engine tatsächlich tut. Sagt ein Tutorial, dass die optische Uhr 6600 s hält, lässt der Test den Build an dem Tag scheitern, an dem das nicht mehr stimmt.

Kshana ist ein Simulator für Positionierung, Navigation und Zeitgebung (PNT). Die Tutorials verwenden einige weitere Abkürzungen, die jeweils an der ersten Stelle ausgeschrieben sind: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (Befehlszeilenschnittstelle) und TOML (Tom's Obvious Minimal Language, das Format der Szenariodatei).

Neu im Projekt? Lesen Sie zuerst die Einführung in die Konzepte und das Glossar und kehren Sie dann hierher zurück.

Die drei durchgespielten Beispiele#

Notebooks#

Ausführbare Jupyter-Notebooks, nur mit synthetischen Daten und öffentlichen Elementsätzen im Repository, liegen in notebooks/:

So führen Sie ein Tutorial aus#

Jedes Tutorial führt dasselbe Szenario auf drei Arten aus; wählen Sie, was zu Ihnen passt. Alle rufen die eine Engine auf, daher sind die Zahlen identisch (entspricht dem Abschnitt Verwendung der README).

Befehlszeile. Die CLI verzweigt nach dem Feld kind des Szenarios und schreibt <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html und <scenario>.report.json neben die Eingabe (JSON ist JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Einige Arten veröffentlichen außerdem eine Reproduzierbarkeitstabelle als <scenario>.table.csv (durch Komma getrennte Werte): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing und moonlight-service-volume, wenn ein Exportstandort gesetzt ist. Keines der drei Tutorials gehört dazu, daher sehen Sie diese Datei hier nicht.

cargo run -- scenarios/orbit-sgp4-gps.toml

cargo run -- baut die CLI aus diesem Checkout. Mit einer installierten Binärdatei (cargo install kshana) lautet derselbe Befehl kshana scenarios/orbit-sgp4-gps.toml. Ohne Checkout sind die meisten mitgelieferten Szenarien in der Binärdatei enthalten: kshana example listet sie auf (und nennt die wenigen, die nicht enthalten sind, mit Begründung), und kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml schreibt eines aus: die Kopie von scenarios/orbit-sgp4-gps.toml, mit der die Binärdatei gebaut wurde.

Python. Bauen Sie die Erweiterung einmal aus diesem Checkout mit maturin in einer aktiven virtuellen Umgebung und rufen Sie dann kshana.run auf:

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 installiert stattdessen das veröffentlichte Wheel. Es kann hinter diesem Checkout zurückliegen: json.loads(kshana.list_kinds()) zeigt Ihnen, welche Szenarioarten Ihr Build hat.

Playground im Browser. Ohne Installation: Öffnen Sie das Studio, wählen Sie ein Szenario, bearbeiten Sie die Parameter und lesen Sie das Ergebnis. Nichts wird hochgeladen; die Engine läuft clientseitig als WebAssembly.

Die Tutorials zitieren die CLI, aber jeder Befehl hat oben das Äquivalent in Python und im Playground. Jedes Ergebnis ist aus scenario + seed + engine version reproduzierbar: Führen Sie es zweimal aus, und Sie erhalten bitidentische Ausgaben.

Kommentierte Lehrszenarien#

Für jeden Fähigkeitsbereich gibt es eine stark kommentierte Datei .toml unter scenarios/: eine Lehrkopie eines kanonischen Szenarios, in der jedes Feld inline erklärt ist, die zitierte unabhängige Referenz genannt wird und die erwartete einzeilige Zusammenfassung als Kommentar # expected: festgehalten ist. Die Feldwerte sind identisch mit denen des Ursprungs im obersten Verzeichnis scenarios/ des Repositorys (tests/tutorials.rs vergleicht das geparste TOML), sodass die dokumentierte Ausgabe stimmt. Auch die Golden-Hashes bleiben unberührt: Ein Kommentar ändert nie einen Szenario-Hash.

Die Lehrdatei für Sicherheit verwendet innen kind = "spoof": Die Sicherheitskennzahl (1 − P_md, eins minus der Wahrscheinlichkeit einer verpassten Erkennung) wird vom Spoof-Paket erzeugt. Der Dateiname folgt der Fähigkeit (Sicherheit), die kind folgt dem Paket (Spoof). Der Kopf dieser Datei weist darauf hin.

Der vollständige Katalog der Szenarioarten#

Die Engine verzweigt nach dem Feld kind des Szenarios. Die Tabelle unten listet die am häufigsten verwendeten Arten (die acht Tutorial-Bereiche oben plus ihre nächsten Nachbarn). Sie ist nicht die vollständige Menge: src/api.rs::list_scenario_kinds() gibt alle 92 eingebauten Arten zurück. Diese Funktion (als list_kinds() in den Bindungen für Python und WebAssembly (WASM) und als kshana kinds --json in der Befehlszeile verfügbar) ist der maßgebliche, stets aktuelle Katalog, und SCENARIOS.md ist ihre erzeugte Aufzählung, ein Abschnitt je Art mit den erforderlichen und optionalen TOML-Feldern. tests/tutorials.rs::tutorial_scenarios_use_real_kinds stellt sicher, dass jede in einem Tutorial dokumentierte Art eine reale Dispatch-Art ist, sodass nichts in dieser Tabelle eine nicht existierende Art nennen kann.

Über die Tutorials hinaus: neuere Fähigkeiten#

Die drei Tutorials bleiben bei den klassischen Paketen für Uhr, Orbit und Sicherheit. Die Engine ist weit darüber hinausgewachsen. Jede Zeile unten ist ein mitgeliefertes Szenario, das Sie unverändert ausführen können (cargo run -- <file> oder kshana <file>); die Zusammenfassung ist die erste Zeile, die kshana 0.35.0 dafür am 2026-10-10 ausgegeben hat. Anders als die Zahlen der Tutorials sind diese Zeilen die Aufzeichnung eines einzelnen Laufs und nicht durch tests/tutorials.rs festgeschrieben: Führen Sie das Szenario erneut aus, um den aktuellen Wert zu erhalten. Die Ergebnisse geben ihren eigenen Geltungsbereich an (die meisten tragen ein label), und die Verifikationsmatrix gibt an, welche Fähigkeiten gegen eine externe unabhängige Referenz VALIDATED und welche MODELLED sind.

LEO ist die niedrige Erdumlaufbahn und MEO die mittlere Erdumlaufbahn; PVT ist Position, Geschwindigkeit und Zeit; PPP ist die präzise Punktpositionierung; 5G ist der Mobilfunkstandard der fünften Generation; TDB ist die baryzentrische dynamische Zeit; JD ist das Julianische Datum; TE ist der Zeitfehler.

Die CLI fügt zu jedem Lauf drei Ausgaben hinzu:

• Berichte. Jeder Lauf schreibt <scenario>.report.html und <scenario>.report.json (siehe REPORTS.md). kshana --study <suite.toml> führt eine Suite von Szenarien in ein .study.json und ein .study.html zusammen, zum Beispiel kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> stellt die Zeitreihen des Laufs dar, zum Beispiel schreibt --animate html auf scenarios/orbit-sgp4-gps.toml die Datei orbit-sgp4-gps.animation.html. Eine Art ohne abgetastete Zeitachse (wie solar-system) wird mit einem Fehler abgelehnt; siehe ANIMATION.md.
• Interop-Exporte. --export <czml|kml|geojson|stk|sigmf|all|list> schreibt das Ergebnis für andere Werkzeuge: CZML (Cesium Language), KML (Keyhole Markup Language, für Google Earth), GeoJSON (geografisches JSON), eine STK-Ephemeride (Systems Tool Kit) oder eine SigMF-Aufzeichnung (Signal Metadata Format). --export list nennt, welche Formate für ein Szenario gelten; SigMF gilt nur für spectrum. Das Orbit-Paket exportiert außerdem --export-sp3, --export-omm und --export-oem (CCSDS, das Consultative Committee for Space Data Systems, Bahnnachrichten). Siehe INTEROP.md.

Abgestufte Übungen#

Arbeiten Sie die Leiter durch. Jede Stufe ist schwerer und belastbarer als die vorige; Referenzlösungen liegen in exercises/.

Die Referenzlösungen verwenden die Python-Erweiterung (zuerst maturin develop --features python). Aus dem Wurzelverzeichnis des Repositorys ausgeführt, gibt tier2_sweep.py aus, wie der Holdover der Chip-Scale-Atomuhr von 2610 s bei einer Vorgabe von 20 ns auf 1140 s bei 5 ns fällt.

Frische Daten gewünscht?#

Die Titelzahlen dieser Tutorials laufen vollständig aus Szenarien, die bereits im Repository liegen. Nichts wird abgerufen, wodurch sie reproduzierbar bleiben und sich gefahrlos in der kontinuierlichen Integration (CI) ausführen lassen. Für die „Erweitern Sie es“-Übungen können Sie Live-Daten ziehen:

• GPS-Zweizeilen-Bahnelemente (TLEs) (die Orbit-Konstellation auffrischen): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, Klartext-Elementsätze mit 3 Zeilen (Name + Zeile 1 + Zeile 2). Hilfsskript: scripts/fetch_tles.sh. Offene Daten (Katalog der 18th Space Defense Squadron der US Space Force, weiterverbreitet von Celestrak, Dr. T. S. Kelso).
• Verifikationsreferenz für SGP4 (Simplified General Perturbations 4) (bereits eingebunden, nicht erneut abrufen): die Testvektoren „Revisiting Spacetrack Report #3“ von AIAA (American Institute of Aeronautics and Astronautics) 2006-6753, https://celestrak.org/publications/AIAA/2006-6753/, verwendet von tests/sgp4_verification.rs; siehe docs/SGP4-VALIDATION.md.
• Referenz für Uhrenstabilitätsbeziehungen: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, die Beziehungen σ_y(τ)↔Phase hinter Tutorial 2.