Handleidingen

Praktische, uitgewerkte voorbeelden die u meenemen van “draai een meegeleverd scenario” naar “kwantificeer en verdedig een resultaat.” Elk getal in de drie tutorials is een echte uitvoer van de engine, verankerd aan een externe (niet-circulaire) gezaghebbende onafhankelijke referentie, en vastgelegd door een integratietest (tests/tutorials.rs), zodat een tutorial nooit ongemerkt kan afwijken van wat de engine werkelijk doet. Als een tutorial zegt dat de optische klok 6600 s volhoudt, laat de test de build falen op de dag dat dat niet langer waar is.

Kshana is een simulator voor positiebepaling, navigatie en tijdsynchronisatie (PNT). De tutorials gebruiken nog een paar afkortingen, elk uitgeschreven waar ze voor het eerst voorkomen: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (command-line interface) en TOML (Tom's Obvious Minimal Language, het formaat van scenariobestanden).

Nieuw bij het project? Lees eerst de conceptenintroductie en de verklarende woordenlijst en kom dan hier terug.

De drie uitgewerkte voorbeelden#

Notebooks#

Uitvoerbare Jupyter-notebooks, op synthetische gegevens en openbare elementensets die alleen in de repository worden bewaard, staan in notebooks/:

Een tutorial draaien#

Elke tutorial draait hetzelfde scenario op drie manieren; kies wat bij u past. Ze roepen allemaal dezelfde engine aan, dus de getallen zijn identiek (volgt de sectie Usage van de README).

Opdrachtregel. De CLI schakelt op het veld kind van het scenario en schrijft <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html en <scenario>.report.json naast de invoer (JSON is JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Enkele soorten publiceren ook een reproduceerbaarheidstabel als <scenario>.table.csv (door komma's gescheiden waarden): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing, en moonlight-service-volume wanneer een exportlocatie is ingesteld. Geen van de drie tutorials is er een van, dus u ziet dat bestand hier niet.

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

cargo run -- bouwt de CLI uit deze checkout. Met een geïnstalleerd binair bestand (cargo install kshana) is dezelfde opdracht kshana scenarios/orbit-sgp4-gps.toml. Zonder checkout zijn de meeste meegeleverde scenario's in het binaire bestand opgenomen: kshana example somt ze op (en noemt de enkele die niet zijn opgenomen, met de reden), en kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml schrijft er één uit: de kopie van scenarios/orbit-sgp4-gps.toml waarmee het binaire bestand is gebouwd.

Python. Bouw de extensie eenmalig uit deze checkout met maturin, binnen een actieve virtuele omgeving, en roep dan kshana.run aan:

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 installeert in plaats daarvan het gepubliceerde wheel. Dat kan achterlopen op deze checkout: json.loads(kshana.list_kinds()) vertelt u welke scenariosoorten uw build heeft.

Playground in de browser. Zonder installatie: open de Studio, kies een scenario, pas de parameters aan en lees het resultaat. Er wordt niets geüpload; de engine draait aan de clientzijde als WebAssembly.

De tutorials noemen de CLI, maar elke opdracht heeft hierboven het equivalent in Python en in de playground. Elk resultaat is reproduceerbaar uit scenario + seed + engine version: draai het twee keer en u krijgt bitidentieke uitvoer.

Geannoteerde leerscenario's#

Voor elk mogelijkhedendomein is er één rijkelijk becommentarieerd .toml onder scenarios/: een leerversie van een canoniek scenario met elk veld inline toegelicht, de aangehaalde onafhankelijke referentie genoemd en de verwachte samenvatting van één regel vastgelegd als commentaar # expected:. De veldwaarden zijn identiek aan die van het origineel in de map scenarios/ op het hoogste niveau van de repo (tests/tutorials.rs vergelijkt de geparseerde TOML), zodat de gedocumenteerde uitvoer klopt. De golden hashes blijven ook ongewijzigd: commentaar verandert nooit een scenariohash.

Het leerbestand voor beveiliging gebruikt kind = "spoof" binnenin: de kwaliteitsmaat voor beveiliging (1 − P_md, één min de kans op gemiste detectie) wordt geproduceerd door het spoofpakket. De bestandsnaam volgt de mogelijkheid (beveiliging), de kind volgt het pakket (spoof). De kop van dat bestand wijst hierop.

De volledige catalogus van scenariosoorten#

De engine schakelt op de kind van het scenario. De tabel hieronder somt de meestgebruikte soorten op (de acht tutorialdomeinen hierboven plus hun naaste buren). Het is niet de complete verzameling: src/api.rs::list_scenario_kinds() geeft alle 92 ingebouwde soorten terug. Die functie (beschikbaar als list_kinds() in de Python- en WebAssembly-bindings (WASM), en als kshana kinds --json op de opdrachtregel) is de gezaghebbende, altijd actuele catalogus, en SCENARIOS.md is de gegenereerde opsomming ervan, één sectie per soort met de verplichte en optionele TOML-velden. tests/tutorials.rs::tutorial_scenarios_use_real_kinds dwingt af dat elke soort die een tutorial beschrijft een echte dispatchsoort is, zodat niets in deze tabel een soort kan noemen die niet bestaat.

Voorbij de tutorials: nieuwere mogelijkheden#

De drie tutorials blijven bij de klassieke pakketten voor klok, baan en beveiliging. De engine is daar ver bovenuit gegroeid. Elke rij hieronder is een meegeleverd scenario dat u ongewijzigd kunt draaien (cargo run -- <file> of kshana <file>); de samenvatting is de eerste regel die kshana 0.35.0 er op 2026-10-10 voor afdrukte. Anders dan de cijfers uit de tutorials zijn deze regels de vastlegging van één run en niet vastgelegd door tests/tutorials.rs: draai het scenario opnieuw voor de actuele waarde. Resultaten vermelden hun eigen reikwijdte (de meeste hebben een label), en de verificatiematrix vermeldt welke mogelijkheden VALIDATED zijn aan een externe onafhankelijke referentie en welke MODELLED.

LEO is lage baan om de aarde (low Earth orbit) en MEO middelhoge baan om de aarde (medium Earth orbit); PVT is positie, snelheid en tijd; PPP is precise point positioning; 5G is de vijfde generatie mobiele standaard; TDB is Barycentric Dynamical Time; JD is Juliaanse datum; TE is tijdfout.

De CLI voegt drie uitvoeren toe aan elke run:

• Rapporten. Elke run schrijft <scenario>.report.html en <scenario>.report.json (zie REPORTS.md). kshana --study <suite.toml> draait een suite van scenario's naar één .study.json en .study.html, bijvoorbeeld kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> geeft de tijdreeks van de run weer, bijvoorbeeld --animate html op scenarios/orbit-sgp4-gps.toml schrijft orbit-sgp4-gps.animation.html. Een soort zonder bemonsterde tijdas (zoals solar-system) wordt met een foutmelding geweigerd; zie ANIMATION.md.
• Interop-exports. --export <czml|kml|geojson|stk|sigmf|all|list> schrijft het resultaat voor andere hulpmiddelen: CZML (Cesium Language), KML (Keyhole Markup Language, voor Google Earth), GeoJSON (geografische JSON), een efemeride voor STK (Systems Tool Kit) of een opname in SigMF (Signal Metadata Format). --export list zegt welke formaten voor een scenario gelden; SigMF geldt alleen voor spectrum. Het baanpakket exporteert ook --export-sp3, --export-omm en --export-oem (CCSDS, het Consultative Committee for Space Data Systems, baanberichten). Zie INTEROP.md.

Oefeningen met oplopende moeilijkheid#

Werk de ladder door. Elke tier is moeilijker en beter verdedigbaar dan de vorige; referentie-oplossingen staan in exercises/.

De referentie-oplossingen gebruiken de Python-extensie (eerst maturin develop --features python). Vanuit de root van de repository gedraaid drukt tier2_sweep.py af dat de holdover van de atoomklok op chipschaal daalt van 2610 s bij een specificatie van 20 ns naar 1140 s bij 5 ns.

Verse gegevens nodig?#

De kerngetallen in deze tutorials draaien volledig uit scenario's die al in de repo staan. Er wordt niets opgehaald, en dat houdt ze reproduceerbaar en veilig om in continuous integration (CI) te draaien. Voor de oefeningen “breid het uit” kunt u live gegevens ophalen:

• GPS two-line elements (TLE's) (ververs de baanconstellatie): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, elementensets van 3 regels in platte tekst (naam + regel 1 + regel 2). Hulpmiddel: scripts/fetch_tles.sh. Open gegevens (catalogus van het 18th Space Defense Squadron van de US Space Force, herverspreid door Celestrak, Dr T. S. Kelso).
• Verificatiereferentie voor SGP4 (Simplified General Perturbations 4) (al opgenomen, haal niet opnieuw op): de testvectoren uit AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 “Revisiting Spacetrack Report #3”, https://celestrak.org/publications/AIAA/2006-6753/, gebruikt door tests/sgp4_verification.rs; zie docs/SGP4-VALIDATION.md.
• Onafhankelijke referentie voor klokstabiliteitsrelaties: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, de relaties tussen σ_y(τ) en fase achter Tutorial 2.