Handledningar

Praktiska, genomgångna exempel som tar dig från ”kör ett medföljande scenario” till ”kvantifiera och försvara ett resultat”. Varje tal som citeras i de tre handledningarna är ett verkligt motorresultat, förankrat i en extern (icke-cirkulär) auktoritativ oberoende referens och fastlåst av ett integrationstest (tests/tutorials.rs), så en handledning kan aldrig i det tysta avvika från vad motorn faktiskt gör. Om en handledning säger att den optiska klockan klarar 6600 s, fäller testet bygget den dag det slutar vara sant.

Kshana är en simulator för positionering, navigering och tidssynkronisering (PNT). Handledningarna använder några fler förkortningar, var och en utskriven där den först förekommer: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (command-line interface, kommandoradsgränssnitt) och TOML (Tom's Obvious Minimal Language, scenariofilens format).

Är du ny i projektet? Läs först begreppsintroduktionen och ordlistan och kom sedan tillbaka hit.

De tre genomgångna exemplen#

Notebooks#

Körbara Jupyter-anteckningsböcker, på syntetiska data och offentliga elementmängder som bara finns i förrådet, finns i notebooks/:

Så kör du en handledning#

Varje handledning kör samma scenario på tre sätt; välj det som passar dig. Alla anropar en motor, så talen är identiska (motsvarar avsnittet Användning i README).

Kommandorad. CLI:t väljer väg utifrån scenariots fält kind och skriver <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html och <scenario>.report.json bredvid indatafilen (JSON är JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Några typer publicerar också en reproducerbarhetstabell som <scenario>.table.csv (kommaseparerade värden): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing och moonlight-service-volume när en exportplats är angiven. Ingen av de tre handledningarna är någon av dem, så du ser inte den filen här.

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

cargo run -- bygger CLI:t från den här utcheckningen. Med en installerad binär (cargo install kshana) är samma kommando kshana scenarios/orbit-sgp4-gps.toml. Utan utcheckning är de flesta medföljande scenarier inbyggda i binären: kshana example listar dem (och nämner de få som inte är inbyggda, med skälet), och kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml skriver ut ett: den kopia av scenarios/orbit-sgp4-gps.toml som binären byggdes med.

Python. Bygg tillägget från den här utcheckningen en gång med maturin, i en aktiv virtuell miljö, och anropa sedan 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 installerar i stället det publicerade wheel-paketet. Det kan ligga efter den här utcheckningen: json.loads(kshana.list_kinds()) visar vilka scenariotyper ditt bygge har.

Lekplats i webbläsaren. Ingen installation: öppna Studio, välj ett scenario, redigera parametrarna och läs resultatet. Ingenting laddas upp; motorn körs hos klienten som WebAssembly.

Handledningarna citerar CLI:t, men varje kommando har motsvarigheten i Python och lekplatsen ovan. Varje resultat går att reproducera från scenario + seed + engine version: kör det två gånger så får du bitidentiska utdata.

Kommenterade undervisningsscenarier#

För varje förmågeområde finns en rikt kommenterad .toml under scenarios/: en undervisningskopia av ett kanoniskt scenario där varje fält förklaras på plats, den åberopade oberoende referensen namnges och den förväntade sammanfattningen på en rad finns registrerad som en # expected:-kommentar. Fältvärdena är identiska med förlagans i förrådets översta katalog scenarios/ (tests/tutorials.rs jämför den tolkade TOML-filen), så den dokumenterade utdatan förblir sann. De gyllene hasharna är också orörda: en kommentar ändrar aldrig ett scenarios hash.

Undervisningsfilen för säkerhet använder kind = "spoof" internt: måttet för säkerhet (1 − P_md, ett minus sannolikheten för missad detektion) produceras av spoof-paketet. Filnamnet följer förmågan (säkerhet), medan kind följer paketet (spoof). Filens huvud pekar ut detta.

Hela katalogen över scenariotyper#

Motorn väljer väg utifrån scenariots kind. Tabellen nedan listar de vanligaste typerna (de åtta handledningsområdena ovan samt deras närmaste grannar). Den är inte den fullständiga uppsättningen: src/api.rs::list_scenario_kinds() returnerar alla 92 inbyggda typer. Den funktionen (tillgänglig som list_kinds() i bindningarna för Python och WebAssembly (WASM), och som kshana kinds --json på kommandoraden) är den auktoritativa, alltid aktuella katalogen, och SCENARIOS.md är dess genererade uppräkning, ett avsnitt per typ med de obligatoriska och valfria TOML-fälten. tests/tutorials.rs::tutorial_scenarios_use_real_kinds säkerställer att varje typ som en handledning dokumenterar är en verklig typ att välja väg efter, så ingenting i den här tabellen kan nämna en typ som inte finns.

Bortom handledningarna: nyare förmågor#

De tre handledningarna håller sig till de klassiska paketen för klocka, bana och säkerhet. Motorn har vuxit långt bortom dem. Varje rad nedan är ett medföljande scenario som du kan köra som det är (cargo run -- <file> eller kshana <file>); sammanfattningen är den första raden som kshana 0.35.0 skrev ut för det den 2026-10-10. Till skillnad från handledningarnas värden är dessa rader en registrering av en körning och inte fastlåsta av tests/tutorials.rs: kör scenariot igen för att få aktuellt värde. Resultaten anger sin egen omfattning (de flesta har en label), och verifieringsmatrisen anger vilka förmågor som är VALIDATED mot en extern oberoende referens och vilka som är MODELLED.

LEO är låg jordbana och MEO medelhög jordbana; PVT är position, hastighet och tid; PPP är precis punktpositionering; 5G är den femte generationens mobilstandard; TDB är barycentrisk dynamisk tid; JD är juliansk dag; TE är tidsfel.

CLI:t lägger till tre utdata ovanpå varje körning:

• Rapporter. Varje körning skriver <scenario>.report.html och <scenario>.report.json (se REPORTS.md). kshana --study <suite.toml> kör en svit av scenarier till en .study.json och en .study.html, till exempel kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> renderar körningens tidsserie, till exempel skriver --animate html på scenarios/orbit-sgp4-gps.toml filen orbit-sgp4-gps.animation.html. En typ utan samplad tidsaxel (som solar-system) avvisas med ett fel; se ANIMATION.md.
• Export för samverkan. --export <czml|kml|geojson|stk|sigmf|all|list> skriver resultatet för andra verktyg: CZML (Cesium Language), KML (Keyhole Markup Language, för Google Earth), GeoJSON (geografisk JSON), en STK-efemerid (Systems Tool Kit) eller en SigMF-inspelning (Signal Metadata Format). --export list anger vilka format som gäller för ett scenario; SigMF gäller bara spectrum. Omloppspaketet exporterar också --export-sp3, --export-omm och --export-oem (CCSDS, Consultative Committee for Space Data Systems, banmeddelanden). Se INTEROP.md.

Graderade övningar#

Arbeta dig uppför stegen. Varje nivå är svårare och mer försvarbar än den förra; referenslösningar finns i exercises/.

Referenslösningarna använder Python-tillägget (maturin develop --features python först). Körd från förrådets rot skriver tier2_sweep.py ut hur den chipskaliga atomklockans holdover faller från 2610 s vid en specifikation på 20 ns till 1140 s vid 5 ns.

Vill du ha färska data?#

Huvudvärdena i de här handledningarna körs helt från scenarier som redan finns i förrådet. Ingenting hämtas, vilket är det som håller dem reproducerbara och säkra att köra i kontinuerlig integration (CI). För övningarna ”bygg vidare” kan du hämta levande data:

• Tvåradiga elementmängder (TLE) för GPS (uppdatera omloppskonstellationen): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, elementmängder i klartext med 3 rader (namn + rad 1 + rad 2). Hjälpskript: scripts/fetch_tles.sh. Öppna data (katalogen från US Space Force 18th Space Defense Squadron, vidaredistribuerad av Celestrak, Dr T. S. Kelso).
• Oberoende referens för verifiering av SGP4 (Simplified General Perturbations 4) (redan inkluderad, hämta inte igen): testvektorerna i AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 ”Revisiting Spacetrack Report #3”, https://celestrak.org/publications/AIAA/2006-6753/, som används av tests/sgp4_verification.rs; se docs/SGP4-VALIDATION.md.
• Oberoende referens för klockstabilitetens samband: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, sambanden mellan σ_y(τ) och fas bakom handledning 2.