Opetusohjelmat

Käytännönläheisiä, läpikäytyjä esimerkkejä, jotka vievät sinut vaiheesta ”aja toimitettu skenaario” vaiheeseen ”kvantifioi ja puolusta tulosta”. Jokainen kolmessa opetusohjelmassa mainittu luku on todellinen moottorin tuloste, ankkuroitu ulkoiseen (kehäpäättelystä vapaaseen) auktoritatiiviseen oraakkeliin ja lukittu integraatiotestillä (tests/tutorials.rs), joten opetusohjelma ei voi huomaamatta ajautua erilleen siitä, mitä moottori todella tekee. Jos opetusohjelma sanoo, että optinen kello pitää 6600 s, testi kaataa koonnin sinä päivänä, kun se lakkaa pitämästä paikkansa.

Kshana on paikannuksen, navigoinnin ja ajanmäärityksen (PNT) simulaattori. Opetusohjelmissa käytetään muutamia muita lyhenteitä, jotka kukin avataan ensimmäisellä esiintymiskerralla: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (komentorivikäyttöliittymä) ja TOML (Tom's Obvious Minimal Language, skenaariotiedostojen muoto).

Oletko uusi projektissa? Lue ensin peruskäsitteiden johdanto ja sanasto ja palaa sitten tänne.

Kolme läpikäytyä esimerkkiä#

Muistikirjat#

Ajettavia Jupyter-muistikirjoja, jotka käyttävät synteettistä dataa ja vain repositoriossa säilytettäviä julkisia elementtijoukkoja, on hakemistossa notebooks/:

Kuinka opetusohjelma ajetaan#

Jokainen opetusohjelma ajaa saman skenaarion kolmella tavalla; valitse sinulle sopiva. Ne kaikki kutsuvat yhtä moottoria, joten luvut ovat identtiset (vastaa README-tiedoston Käyttö-osiota).

Komentorivi. CLI valitsee toiminnon skenaarion kentän kind mukaan ja kirjoittaa tiedostot <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html ja <scenario>.report.json syötteen viereen (JSON on JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Muutama tyyppi julkaisee myös toistettavuustaulukon tiedostona <scenario>.table.csv (pilkuilla erotetut arvot): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing ja moonlight-service-volume, kun vientipaikka on asetettu. Mikään kolmesta opetusohjelmasta ei ole niitä, joten et näe tätä tiedostoa tässä.

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

cargo run -- rakentaa CLI:n tästä paikallisesta kopiosta. Asennetulla binäärillä (cargo install kshana) sama komento on kshana scenarios/orbit-sgp4-gps.toml. Ilman paikallista kopiota useimmat toimitetut skenaariot on niputettu binääriin: kshana example luettelee ne (ja nimeää ne harvat, joita ei ole niputettu, syineen), ja kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml kirjoittaa yhden ulos: tiedoston scenarios/orbit-sgp4-gps.toml kopion, jolla binääri rakennettiin.

Python. Rakenna laajennus tästä paikallisesta kopiosta kerran maturinilla aktiivisessa virtuaaliympäristössä ja kutsu sitten 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 asentaa sen sijaan julkaistun wheel-paketin. Se voi olla tätä kopiota jäljessä: json.loads(kshana.list_kinds()) kertoo, mitä skenaariotyyppejä versiossasi on.

Selaimen leikkikenttä. Ei asennusta: avaa Studio, valitse skenaario, muokkaa parametreja ja lue tulos. Mitään ei lähetetä; moottori toimii asiakaspuolella WebAssemblynä.

Opetusohjelmat esittävät CLI-komennot, mutta jokaisella komennolla on yllä oleva Python- ja leikkikenttävastine. Jokainen tulos on toistettavissa tiedoista scenario + seed + engine version: aja se kahdesti, niin saat bitilleen identtisen tulosteen.

Kommentoidut opetusskenaariot#

Jokaista ominaisuusaluetta varten on yksi runsaasti kommentoitu tiedosto (.toml) hakemistossa scenarios/: kanonisen skenaarion opetuskopio, jossa jokainen kenttä on selitetty rivillä, siteerattu oraakkeli on nimetty ja odotettu yhden rivin yhteenveto on kirjattu kommenttina # expected:. Kenttien arvot ovat identtiset vanhemman arvojen kanssa repositorion ylätason hakemistossa scenarios/ (tests/tutorials.rs vertaa jäsennettyä TOML-sisältöä), joten dokumentoitu tuloste pysyy todenmukaisena. Myös golden-tiivisteet ovat koskemattomia: kommentti ei koskaan muuta skenaarion tiivistettä.

Tietoturvan opetustiedosto sisältää rivin kind = "spoof": tietoturvan laatumittarin (1 − P_md, yksi miinus havaitsematta jäämisen todennäköisyys) tuottaa harhautuspaketti. Tiedoston nimi seuraa ominaisuutta (tietoturva), kenttä kind seuraa pakettia (spoof). Tiedoston otsikko tuo tämän esiin.

Täydellinen skenaariotyyppien luettelo#

Moottori valitsee toiminnon skenaarion kentän kind mukaan. Alla oleva taulukko luettelee yleisimmin käytetyt tyypit (yllä olevat kahdeksan opetusaluetta sekä niiden lähimmät naapurit). Se ei ole täydellinen joukko: src/api.rs::list_scenario_kinds() palauttaa kaikki 92 sisäänrakennettua tyyppiä. Tämä funktio (Python- ja WebAssembly (WASM) -sidonnoissa nimellä list_kinds() ja komentorivillä komennolla kshana kinds --json) on auktoritatiivinen, aina ajan tasalla oleva luettelo, ja SCENARIOS.md on sen generoitu luettelointi, yksi osio tyyppiä kohti, pakollisine ja valinnaisine TOML-kenttineen. tests/tutorials.rs::tutorial_scenarios_use_real_kinds pakottaa, että jokainen opetusohjelmassa dokumentoitu tyyppi on todellinen toiminnon valintatyyppi, joten tämän taulukon mikään rivi ei voi nimetä olematonta tyyppiä.

Opetusohjelmien jälkeen: uudemmat ominaisuudet#

Kolme opetusohjelmaa pysyvät klassisissa kello-, kiertorata- ja tietoturvapaketeissa. Moottori on kasvanut niitä paljon pidemmälle. Jokainen alla oleva rivi on toimitettu skenaario, jonka voit ajaa sellaisenaan (cargo run -- <file> tai kshana <file>); yhteenveto on ensimmäinen rivi, jonka kshana 0.35.0 tulosti siitä 2026-10-10. Toisin kuin opetusohjelmien luvut, nämä rivit ovat yhden ajon tallenne, eikä niitä ole lukittu tiedostolla tests/tutorials.rs: aja skenaario uudelleen saadaksesi nykyisen arvon. Tulokset kertovat oman rajauksensa (useimmissa on label), ja varmennusmatriisi kertoo, mitkä ominaisuudet on VALIDATED ulkoista oraakkelia vasten ja mitkä MODELLED.

LEO on matala Maan kiertorata ja MEO keskikorkea Maan kiertorata; PVT on sijainti, nopeus ja aika; PPP on tarkka pistepaikannus; 5G on viidennen sukupolven mobiilistandardi; TDB on barysentrinen dynaaminen aika (Barycentric Dynamical Time); JD on juliaaninen päivämäärä; TE on aikavirhe.

CLI lisää minkä tahansa ajon päälle kolme tulostetta:

• Raportit. Jokainen ajo kirjoittaa tiedostot <scenario>.report.html ja <scenario>.report.json (katso REPORTS.md). Komento kshana --study <suite.toml> ajaa skenaariojoukon ja tuottaa tiedostot .study.json ja .study.html, esimerkiksi kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. Komento kshana <scenario.toml> --animate <svg|html|frames|all> piirtää ajon aikasarjan, esimerkiksi komento --animate html skenaariolle scenarios/orbit-sgp4-gps.toml kirjoittaa tiedoston orbit-sgp4-gps.animation.html. Tyyppi, jolla ei ole näytteistettyä aika-akselia (kuten solar-system), hylätään virheellä; katso ANIMATION.md.
• Yhteentoimivuusviennit. Komento --export <czml|kml|geojson|stk|sigmf|all|list> kirjoittaa tuloksen muita työkaluja varten: CZML (Cesium Language), KML (Keyhole Markup Language, Google Earthia varten), GeoJSON (geographic JSON), STK:n (Systems Tool Kit) efemeridi tai SigMF-tallenne (Signal Metadata Format). Komento --export list kertoo, mitkä formaatit sopivat skenaarioon; SigMF sopii vain tyyppiin spectrum. Kiertoratapaketti vie myös --export-sp3, --export-omm ja --export-oem (CCSDS, Consultative Committee for Space Data Systems, -ratasanomat). Katso INTEROP.md.

Arvioitavat harjoitukset#

Käy tikkaat läpi. Jokainen taso on edellistä vaikeampi ja puolustettavampi; esimerkkiratkaisut ovat hakemistossa exercises/.

Esimerkkiratkaisut käyttävät Python-laajennusta (ensin maturin develop --features python). Kun komento ajetaan repositorion juuresta, tiedosto tier2_sweep.py tulostaa sirutason atomikellon holdoverin putoavan arvosta 2610 s 20 ns:n määrittelyllä arvoon 1140 s 5 ns:n määrittelyllä.

Haluatko tuoretta dataa?#

Näiden opetusohjelmien pääluvut ajetaan kokonaan repositoriossa jo olevista skenaarioista. Mitään ei haeta, minkä ansiosta ne ovat toistettavia ja turvallisia ajaa jatkuvassa integroinnissa (CI). ”Laajenna sitä” -harjoituksiin voit hakea live-dataa:

• GPS:n kaksirivisiä elementtijoukkoja (TLE) (päivitä kiertoratatähdistö): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, pelkkää tekstiä olevia 3-rivisiä elementtijoukkoja (nimi + rivi 1 + rivi 2). Apuri: scripts/fetch_tles.sh. Avoin data (US Space Forcen 18th Space Defense Squadronin luettelo, Celestrakin jakelema, Dr T. S. Kelso).
• SGP4:n (Simplified General Perturbations 4) varmennusoraakkeli (jo mukana, älä hae uudelleen): AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 ”Revisiting Spacetrack Report #3” -testivektorit, https://celestrak.org/publications/AIAA/2006-6753/, tiedoston tests/sgp4_verification.rs käyttämät; katso docs/SGP4-VALIDATION.md.
• Kellon vakauden relaatioiden oraakkeli: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, σ_y(τ)↔vaihe-relaatiot, joihin opetusohjelma 2 perustuu.