Tutoriály

Praktické pracovní příklady, které vás provedou od „spusťte dodaný scénář“ k „vyčíslete a obhajte výsledek“. Každé číslo uvedené ve třech tutoriálech je skutečným výstupem enginu, ukotveným k externímu (nekruhovému) směrodatnému orákulu a zafixovaným integračním testem (tests/tutorials.rs), takže tutoriál se nikdy nemůže tiše odchýlit od toho, co engine skutečně dělá. Pokud tutoriál říká, že optické hodiny drží 6600 s, test shodí sestavení v den, kdy to přestane platit.

Kshana je simulátor určování polohy, navigace a času (PNT). Tutoriály používají několik dalších zkratek, každá je rozepsána tam, kde se poprvé objeví: GNSS (globální družicový navigační systém), GPS (Global Positioning System), CLI (rozhraní příkazového řádku) a TOML (Tom's Obvious Minimal Language, formát souborů scénářů).

Jste v projektu noví? Přečtěte si nejprve úvodní přehled pojmů a slovník a pak se vraťte.

Tři pracovní příklady#

Notebooky#

Spustitelné notebooky Jupyter, na syntetických datech a veřejných sadách elementů uložených pouze v repozitáři, jsou v notebooks/:

Jak spustit tutoriál#

Každý tutoriál spouští stejný scénář třemi způsoby; vyberte si, který vám vyhovuje. Všechny volají jediný engine, takže čísla jsou shodná (odpovídá části Usage v README).

Příkazový řádek. CLI rozlišuje podle pole kind ve scénáři a zapisuje <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html a <scenario>.report.json vedle vstupu (JSON je JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Několik druhů publikuje také tabulku reprodukovatelnosti jako <scenario>.table.csv (hodnoty oddělené čárkami): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing a moonlight-service-volume, je-li nastaveno místo exportu. Žádný ze tří tutoriálů mezi ně nepatří, takže tento soubor zde neuvidíte.

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

cargo run -- sestaví CLI z tohoto checkoutu. S nainstalovanou binárkou (cargo install kshana) je stejný příkaz kshana scenarios/orbit-sgp4-gps.toml. Bez checkoutu je většina dodaných scénářů součástí binárky: kshana example je vypíše (a pojmenuje těch několik, které součástí nejsou, s důvodem) a kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml jeden zapíše: kopii scenarios/orbit-sgp4-gps.toml, se kterou byla binárka sestavena.

Python. Jednou sestavte rozšíření z tohoto checkoutu pomocí maturin v aktivním virtuálním prostředí a poté zavolejte 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 nainstaluje místo toho publikovaný wheel. Ten může zaostávat za tímto checkoutem: json.loads(kshana.list_kinds()) vám řekne, které druhy scénářů vaše sestavení má.

Playground v prohlížeči. Bez instalace: otevřete Studio, zvolte scénář, upravte parametry a přečtěte si výsledek. Nic se nenahrává; engine běží na straně klienta jako WebAssembly.

Tutoriály uvádějí CLI, ale každý příkaz má výše uvedený ekvivalent v Pythonu a playgroundu. Každý výsledek je reprodukovatelný z scenario + seed + engine version: spusťte jej dvakrát a dostanete bitově shodný výstup.

Okomentované výukové scénáře#

Pro každou schopnostní doménu existuje jeden silně okomentovaný soubor .toml v scenarios/: výuková kopie kanonického scénáře s každým polem vysvětleným přímo v něm, pojmenovaným citovaným orákulem a očekávaným jednořádkovým shrnutím zaznamenaným jako komentář # expected:. Hodnoty polí jsou shodné s nadřazeným scénářem v nejvyšším adresáři scenarios/ repozitáře (tests/tutorials.rs porovnává zpracovaný TOML), takže zdokumentovaný výstup zůstává pravdivý. Zlaté hashe zůstávají rovněž nedotčeny: komentář nikdy nezmění hash scénáře.

Výukový soubor pro bezpečnost uvnitř používá kind = "spoof": ukazatel kvality bezpečnosti (1 − P_md, jedna minus pravděpodobnost nezachycené události) vytváří balíček spoof. Název souboru se řídí schopností (bezpečnost), kind se řídí balíčkem (spoof). Hlavička tohoto souboru na to upozorňuje.

Úplný katalog druhů scénářů#

Engine rozlišuje podle kind scénáře. Tabulka níže uvádí nejčastěji používané druhy (osm výše uvedených tutoriálových domén a jejich nejbližší sousedy). Není to úplná množina: src/api.rs::list_scenario_kinds() vrací všech 92 vestavěných druhů. Tato funkce (zpřístupněná jako list_kinds() ve vazbách Pythonu a WebAssembly (WASM) a jako kshana kinds --json na příkazovém řádku) je směrodatným, vždy aktuálním katalogem a SCENARIOS.md je její generovaný výčet, jedna sekce na druh s povinnými a volitelnými poli TOML. tests/tutorials.rs::tutorial_scenarios_use_real_kinds vynucuje, aby každý druh, který tutoriál dokumentuje, byl skutečným druhem rozlišení, takže tato tabulka nemůže uvádět druh, který neexistuje.

Za hranicemi tutoriálů: novější schopnosti#

Tři tutoriály zůstávají u klasických balíčků hodin, oběžné dráhy a bezpečnosti. Engine od té doby výrazně vyrostl. Každý řádek níže je dodaný scénář, který můžete spustit tak, jak je (cargo run -- <file> nebo kshana <file>); shrnutí je první řádek, který kshana 0.35.0 pro něj vypsala dne 2026-10-10. Na rozdíl od údajů v tutoriálech jsou tyto řádky záznamem jednoho běhu a nejsou zafixovány tests/tutorials.rs: pro aktuální hodnotu scénář spusťte znovu. Výsledky uvádějí vlastní rozsah (většina nese label) a verifikační matice uvádí, které schopnosti jsou VALIDATED proti vnějšímu orákulu a které MODELLED.

LEO je nízká oběžná dráha Země a MEO střední oběžná dráha Země; PVT je poloha, rychlost a čas; PPP je přesné bodové určování polohy; 5G je pátá generace mobilního standardu; TDB je barycentrický dynamický čas; JD je juliánské datum; TE je časová chyba.

CLI přidává ke každému běhu tři výstupy:

• Zprávy. Každý běh zapisuje <scenario>.report.html a <scenario>.report.json (viz REPORTS.md). kshana --study <suite.toml> spustí sadu scénářů do jednoho .study.json a .study.html, například kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> vykreslí časové řady běhu, například --animate html na scenarios/orbit-sgp4-gps.toml zapíše orbit-sgp4-gps.animation.html. Druh bez vzorkované časové osy (například solar-system) je odmítnut s chybou; viz ANIMATION.md.
• Exporty pro interoperabilitu. --export <czml|kml|geojson|stk|sigmf|all|list> zapíše výsledek pro jiné nástroje: CZML (Cesium Language), KML (Keyhole Markup Language, pro Google Earth), GeoJSON (geografický JSON), efemeridy STK (Systems Tool Kit) nebo záznam SigMF (Signal Metadata Format). --export list říká, které formáty se na scénář vztahují; SigMF se vztahuje pouze na spectrum. Balíček oběžné dráhy také exportuje --export-sp3, --export-omm a --export-oem (zprávy o oběžné dráze CCSDS, Poradní výbor pro kosmické datové systémy). Viz INTEROP.md.

Odstupňovaná cvičení#

Projděte si žebříček. Každá úroveň je těžší a lépe obhajitelná než předchozí; referenční řešení jsou v exercises/.

Referenční řešení používají rozšíření Pythonu (nejprve maturin develop --features python). Spuštěno z kořene repozitáře, tier2_sweep.py vypíše pokles holdoveru čipových atomových hodin z 2610 s při specifikaci 20 ns na 1140 s při 5 ns.

Chcete čerstvá data?#

Úvodní čísla v těchto tutoriálech běží výhradně ze scénářů, které již jsou v repozitáři. Nic se nestahuje, a právě proto jsou reprodukovatelná a bezpečná ke spouštění v kontinuální integraci (CI). Pro cvičení „rozšiřte to“ můžete stáhnout živá data:

• Dvouřádkové elementy GPS (TLE) (obnovení konstelace oběžné dráhy): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, textové 3řádkové sady elementů (název + řádek 1 + řádek 2). Pomocník: scripts/fetch_tles.sh. Otevřená data (katalog 18. eskadry kosmické obrany Vesmírných sil USA, redistribuovaný Celestrakem, Dr T. S. Kelso).
• Ověřovací orákulum SGP4 (Simplified General Perturbations 4) (již součástí repozitáře, nestahujte znovu): testovací vektory AIAA (Americký institut pro letectví a kosmonautiku) 2006-6753 „Revisiting Spacetrack Report #3“, https://celestrak.org/publications/AIAA/2006-6753/, používané tests/sgp4_verification.rs; viz docs/SGP4-VALIDATION.md.
• Orákulum vztahů stability hodin: NIST (Národní institut standardů a technologie) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, vztahy σ_y(τ)↔fáze za Tutoriálem 2.