Vejledninger

Praktiske, gennemarbejdede eksempler, der fører dig fra “kør et medfølgende scenarie” til “kvantificér og forsvar et resultat.” Hvert tal i de tre tutorials er et rigtigt motoroutput, forankret i en ekstern (ikke-cirkulær) autoritativ uafhængig reference og fastlåst af en integrationstest (tests/tutorials.rs), så en tutorial aldrig i det skjulte kan glide væk fra det, motoren faktisk gør. Hvis en tutorial siger, at det optiske ur holder 6600 s, får testen buildet til at fejle den dag, det holder op med at være sandt.

Kshana er en simulator til positionering, navigation og tidssynkronisering (PNT). Tutorials bruger nogle få flere forkortelser, hver især skrevet ud, hvor den først optræder: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (kommandolinjegrænseflade) og TOML (Tom's Obvious Minimal Language, scenariernes filformat).

Ny i projektet? Læs først begrebsintroduktionen og ordlisten, og vend så tilbage hertil.

De tre gennemarbejdede eksempler#

Notebooks#

Kørbare Jupyter-notebooks på syntetiske data og offentlige elementsæt, som kun ligger i repositoriet, findes i notebooks/:

Sådan kører du en tutorial#

Hver tutorial kører det samme scenarie på tre måder; vælg den, der passer dig. De kalder alle den ene motor, så tallene er identiske (spejler afsnittet Brug i README).

Kommandolinje. CLI'en vælger efter scenariets felt kind og skriver <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html og <scenario>.report.json ved siden af inputtet (JSON er JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Nogle få kinds udgiver også en reproducerbarhedstabel som <scenario>.table.csv (kommaseparerede værdier): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing og moonlight-service-volume, når der er angivet et eksportsted. Ingen af de tre tutorials hører til dem, så du ser ikke den fil her.

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

cargo run -- bygger CLI'en fra dette checkout. Med en installeret binær (cargo install kshana) er den samme kommando kshana scenarios/orbit-sgp4-gps.toml. Uden et checkout er de fleste medfølgende scenarier indbygget i den binære: kshana example viser dem (og nævner de få, der ikke er indbygget, med begrundelsen), og kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml skriver ét ud: den kopi af scenarios/orbit-sgp4-gps.toml, som den binære blev bygget med.

Python. Byg udvidelsen fra dette checkout én gang med maturin i et aktivt virtuelt miljø, og kald derefter 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 installerer i stedet det udgivne wheel. Det kan hænge bagud i forhold til dette checkout: json.loads(kshana.list_kinds()) fortæller dig, hvilke scenarietyper dit build har.

Legeplads i browseren. Ingen installation: åbn Studio, vælg et scenarie, redigér parametrene og aflæs resultatet. Intet uploades; motoren kører hos klienten som WebAssembly.

Tutorials citerer CLI'en, men hver kommando har en tilsvarende Python- og legepladsvariant ovenfor. Hvert resultat kan gengives ud fra scenario + seed + engine version: kør det to gange, og du får bit-identisk output.

Kommenterede undervisningsscenarier#

For hvert funktionsområde er der én kraftigt kommenteret .toml under scenarios/: en undervisningskopi af et kanonisk scenarie, hvor hvert felt er forklaret i linjen, den anførte uafhængige reference er nævnt, og den forventede opsummering på én linje er optaget som en kommentar # expected:. Feltværdierne er identiske med forældrenes i repoets mappe scenarios/ på øverste niveau (tests/tutorials.rs sammenligner den parsede TOML), så det dokumenterede output forbliver sandt. De gyldne hashes er heller ikke rørt: en kommentar ændrer aldrig et scenaries hash.

Undervisningsfilen for sikkerhed bruger kind = "spoof" indeni: kvalitetsmålet for sikkerhed (1 − P_md, én minus sandsynligheden for en overset detektion) frembringes af spoof-pakken. Filnavnet følger funktionen (sikkerhed), mens kind følger pakken (spoof). Filens header gør opmærksom på det.

Det fulde katalog over scenarietyper#

Motoren vælger efter scenariets kind. Tabellen nedenfor viser de mest brugte kinds (de otte tutorial-områder ovenfor og deres nærmeste naboer). Den er ikke den komplette mængde: src/api.rs::list_scenario_kinds() returnerer alle 92 indbyggede kinds. Den funktion (tilgængelig som list_kinds() i bindingerne til Python og WebAssembly (WASM) og som kshana kinds --json på kommandolinjen) er det autoritative, altid opdaterede katalog, og SCENARIOS.md er dens genererede oversigt, ét afsnit pr. kind med de påkrævede og valgfrie TOML-felter. tests/tutorials.rs::tutorial_scenarios_use_real_kinds sikrer, at hver kind, en tutorial dokumenterer, er en rigtig dispatch-kind, så intet i denne tabel kan nævne en kind, der ikke findes.

Ud over tutorials: nyere funktioner#

De tre tutorials holder sig til de klassiske pakker for ur, bane og sikkerhed. Motoren er vokset langt ud over dem. Hver række nedenfor er et medfølgende scenarie, du kan køre, som det er (cargo run -- <file> eller kshana <file>); opsummeringen er den første linje, kshana 0.35.0 udskrev for det den 2026-10-10. I modsætning til tutorial-tallene er disse linjer en optegnelse af én kørsel og ikke fastlåst af tests/tutorials.rs: kør scenariet igen for at få den aktuelle værdi. Resultater angiver selv deres omfang (de fleste har en label), og verifikationsmatrixen angiver, hvilke funktioner der er VALIDATED mod en ekstern uafhængig reference, og hvilke der er MODELLED.

LEO er lav jordbane og MEO mellemhøj jordbane; PVT er position, hastighed og tid; PPP er præcis punktpositionering; 5G er femte generation af mobilstandarden; TDB er barycentrisk dynamisk tid; JD er juliansk dato; TE er tidsfejl.

CLI'en tilføjer tre outputs oven på enhver kørsel:

• Rapporter. Hver kørsel skriver <scenario>.report.html og <scenario>.report.json (se REPORTS.md). kshana --study <suite.toml> kører en suite af scenarier ind i én .study.json og .study.html, for eksempel kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> gengiver kørslens tidsserie, for eksempel skriver --animate html på scenarios/orbit-sgp4-gps.toml filen orbit-sgp4-gps.animation.html. En kind uden en samplet tidsakse (såsom solar-system) afvises med en fejl; se ANIMATION.md.
• Interop-eksporter. --export <czml|kml|geojson|stk|sigmf|all|list> skriver resultatet til andre værktøjer: CZML (Cesium Language), KML (Keyhole Markup Language, til Google Earth), GeoJSON (geographic JSON), en STK-efemeride (Systems Tool Kit) eller en SigMF-optagelse (Signal Metadata Format). --export list fortæller, hvilke formater der gælder for et scenarie; SigMF gælder kun for spectrum. Bane-pakken eksporterer også --export-sp3, --export-omm og --export-oem (CCSDS, Consultative Committee for Space Data Systems, banemeddelelser). Se INTEROP.md.

Graderede øvelser#

Arbejd dig igennem stigen. Hvert niveau er sværere og mere forsvarligt end det forrige; referenceløsninger findes i exercises/.

Referenceløsningerne bruger Python-udvidelsen (først maturin develop --features python). Kørt fra repositoriets rod udskriver tier2_sweep.py chipskala-atomurets holdover faldende fra 2610 s ved en specifikation på 20 ns til 1140 s ved 5 ns.

Vil du have friske data?#

Hovedtallene i disse tutorials kører helt og holdent fra scenarier, der allerede ligger i repoet. Intet hentes, og det er det, der gør dem reproducerbare og sikre at køre i continuous integration (CI). Til øvelserne “udvid det” kan du hente levende data:

• GPS two-line elements (TLE'er) (opdatér bane-konstellationen): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, elementsæt i ren tekst med 3 linjer (navn + linje 1 + linje 2). Hjælper: scripts/fetch_tles.sh. Åbne data (katalog fra US Space Force 18th Space Defense Squadron, videredistribueret af Celestrak, Dr T. S. Kelso).
• Uafhængig verifikationsreference for SGP4 (Simplified General Perturbations 4) (allerede medleveret, hent ikke igen): testvektorerne fra AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 “Revisiting Spacetrack Report #3”, https://celestrak.org/publications/AIAA/2006-6753/, brugt af tests/sgp4_verification.rs; se docs/SGP4-VALIDATION.md.
• Uafhængig reference for urstabilitetsrelationer: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, relationerne σ_y(τ)↔fase bag Tutorial 2.