Rust crate · Kshana docs

Kshana: tunnus, kompassin ristikko, joka merkitsee täsmällisen hetken, sanamerkin kshana vieressä

Kshana · क्षण · tarkka hetki
Avoimen lähdekoodin PNT-kestävyyssimulaattori (paikannus, navigointi ja ajanmääritys).

Julkaisu v0.40.0 176 / 401 kyvykkyydestä validoitu riippumattomia ulkoisia oraakkeleita vasten Noin 95 %:n rivikattavuus, jatkuvassa integroinnissa kynnyksenä 85 % Lisenssi: AGPL-3.0-only tai kaupallinen lisenssi DOI 10.5281/zenodo.20528627

Harjoittele hetkeä, kun GNSS sammuu#

Kshana toistaa häirinnän, harhautuksen ja kellon holdoverin GNSS-signaalien (Global Navigation Satellite System) pettäessä ja kertoo, kuinka kauan järjestelmä pitää ajan ja paikan budjettinsa sisällä sekä mikä kello tai anturi tuo eniten marginaalia. Tämä on Rust-paketti (crate): moottori kirjastona ja komento kshana. Jokainen ajo on toistettavissa bitilleen skenaariosta, siemenluvusta ja moottorin versiosta.

Kokeile ensin ilman asennusta: Kshana Studio ajaa koko moottorin selaimessasi WebAssemblyksi käännettynä eikä lähetä mitään.

Todisteet#

176 / 401 kyvykkyydestä validoitu riippumattomia ulkoisia oraakkeleita vasten; 221 rehellisesti merkitty mallinnetuksi, 4 kumppanin omistamaa. Jokaisella kyvykkyydellä on yksi nimike koneellisesti tarkistetussa kirjanpidossa: VALIDATED (riippumaton ulkoinen oraakkeli on samaa mieltä: todellinen data, riippumaton toteutus tai julkaistut viitevektorit), MODELLED (sisäisesti johdonmukainen, ja se sanotaan ääneen) tai PARTNER (laitteistokumppani omistaa sen). Tarkistuksiin kuuluvat muun muassa kaikki 666 SGP4-vektoria (Simplified General Perturbations 4) julkaisusta AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 tarkkuudella 4,12 mm sekä Cowell-voimamalli tarkkuudella 0,08 m Orekit 12,2:aa vasten.

Miten kyvykkyys ansaitsee nimikkeensä: kyvykkyys, oraakkeli, testi, kirjanpidon nimike. Varmennustila kaikissa 401 kyvykkyydessä: 176 validoitua, 221 mallinnettua, 4 kumppanin omistamaa

Asennus#

cargo add kshana            # use the engine as a library
cargo install kshana        # or install the command-line interface (CLI)

Käyttö — kirjasto#

Esimerkki on täydellinen ohjelma: se kantaa oman skenaarionsa, kirjoitettuna TOML-kielellä (Tom's Obvious, Minimal Language), joten se toimii tiedostona src/main.rs projektissa, jonka on luonut cargo new, kun on ajettu cargo add kshana, eikä levyllä tarvita mitään muuta.

use kshana::api;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A complete scenario, not a sketch: scenarios/clock-holdover.toml without its
    // comment lines. It runs 2 h, 10 min of GNSS then about 1.8 h with GNSS denied, and
    // asks how long a strontium optical clock and a chip-scale atomic clock (CSAC) each
    // hold time to within 20 ns. sigma_y(1s) is a clock's Allan deviation at an averaging
    // time of one second; q_wf, the white-frequency-noise intensity, is its square.
    let toml = r#"
seed = 42
threshold_ns = 20.0

[time]
step_s = 10.0
duration_s = 7200.0

[gnss]
windows = [
  { t0 = 0.0,    t1 = 600.0,  state = "nominal" },
  { t0 = 600.0,  t1 = 7200.0, state = "denied" },
]

[clock_quantum]
id = "optical-sr-lattice"
provenance = "Strontium optical lattice clock, space-oriented goal sigma_y(1s)=1e-15 (Origlia/Schiller/Bongs et al., arXiv:1503.08457); q_wf=sigma_y(1s)^2; ground-demonstrator maturity, not flown; flicker/aging not modeled"
y0   = 5.0e-17
q_wf = 1.0e-30
q_rw = 0.0

[clock_classical]
id = "csac-sa45s"
provenance = "Microchip SA65 / SA.45s CSAC datasheet sigma_y(1s)=3e-10; q_wf=sigma_y(1s)^2; flicker/aging not modeled"
y0   = 5.0e-10
q_wf = 9.0e-20
q_rw = 0.0
"#;
    let out = api::run_toml(toml)?; // RunOutput { json, svg, summary, csv }
    println!("{}", out.summary); // the one-line result string
    std::fs::write("clock-holdover.result.json", &out.json)?; // the full result document
    Ok(())
}

out.json on tulosasiakirja JSON-muodossa (JavaScript Object Notation), out.svg kaavio SVG-muodossa (Scalable Vector Graphics) ja out.csv niille tyypeille, jotka julkaisevat taulukon, kyseinen taulukko CSV-muodossa (pilkuin erotetut arvot).

API-viite, generoitu tiedostosta src/api.rs#

Jokainen moduulin kshana::api julkinen funktio moottorin versiossa v0.40.0, luettuna lähteestä käännösaikana.

Funktio	Allekirjoitus	Mitä se tekee
`kshana::api::without_figure_tiers`	`(json: &str) -> Option<String>`	json, josta loppuun sijoitettu lohko figure_tiers on poistettu, tavu tavulta sellaisena kuin asiakirja oli ennen kuin lohko oli olemassa; None, kun asiakirjassa ei ole sellaista lohkoa tai lohko ei ole sen viimeinen avain (jota tämä paketti ei koskaan tuota, joten testauskehyksen on käsiteltävä se virheenä sen sijaan, että se poistaisi jotain, mitä se ei voi selittää).
`kshana::api::list_scenario_kinds`	`() -> Vec<ScenarioMeta>`	Luettele jokainen sisäänrakennettu skenaariotyyppi metatietoineen.
`kshana::api::list_scenario_kinds_json`	`() -> String`	Sisäänrakennetut skenaariotyypit ja niiden metatiedot JSON-taulukkona — muoto, jonka kielisidokset paljastavat ohjelmalliseen introspektioon.
`kshana::api::kind_description_in`	`(lang: &crate::i18n::Lang, kind: &str) -> Option<String>`	Sisäänrakennetun skenaariotyypin kind kuvaus kielellä lang katalogista (englanniksi, kun kielellä ei ole sen käännöstä); None nimelle, joka ei ole sisäänrakennettu tyyppi.
`kshana::api::kind_description`	`(kind: &str) -> Option<String>`	[kind_description_in] nykyisellä kielellä ([crate::i18n::current]).
`kshana::api::list_scenario_kinds_json_lang`	`(lang: &str) -> Result<String, String>`	[list_scenario_kinds_json], jossa jokainen kuvaus on kielellä lang (tunniste, jonka --lang hyväksyy, kuten de tai zh-Hans); nimet ja kenttäluettelot ovat samat jokaisella kielellä, ja englanniksi asiakirja on tavu tavulta identtinen luettelon [list_scenario_kinds_json] kanssa.
`kshana::api::kind_modules_json`	`() -> String`	[KIND_MODULES] JSON-objektina, tyyppi → moduulinimien taulukko, taulukon järjestyksessä.
`kshana::api::field_importance_json`	`() -> String`	[HEADLINE_FIELDS] JSON-muodossa: {kind: {"headline": [path, ...]}}, taulukon järjestyksessä.
`kshana::api::scenarios_reference_md`	`() -> String`	Tuota sisäänrakennettu skenaariotyyppiluettelo erillisenä Markdown-viitteenä (docs/SCENARIOS.md): jokainen kutsuttavissa oleva tyyppi yhden rivin kuvauksineen sekä vaadittuine / valinnaisine TOML-kenttineen.
`kshana::api::validate_scenario`	`(src: &str) -> Vec<String>`	Tarkista skenaarion TOML paketin oman introspektion avulla ja palauta ongelmaluettelo — jotta kutsujalle voidaan kertoa, mikä on pielessä ENNEN (mahdollisesti pitkää) ajoa, sen sijaan että se törmäisi myöhäiseen ajonaikaiseen virheeseen.
`kshana::api::export_sp3`	`(src: &str) -> Result<String, String>`	Vie rata-/tähdistöskenaarion propagoitu tähdistö SP3-c-tekstinä.
`kshana::api::auto_export_sp3`	`(src: &str) -> Result<Option<String>, String>`	Jos src on rataskenaario, jossa export_sp3 = true, palauta sen SP3-c-teksti; muuten None.
`kshana::api::export_omm`	`(src: &str) -> Result<String, String>`	Vie rataskenaarion TLE-keskielementit CCSDS OMM -luettelona — yksi OMM (Orbit Mean-Elements Message) jokaista TLE-määriteltyä satelliittia kohti, KVN-muodossa, kantaen todellisen NORAD-katalogiluvun, COSPAR-tunnuksen ja epookin kustakin TLE:stä.
`kshana::api::auto_export_omm`	`(src: &str) -> Result<Option<String>, String>`	Jos src on rataskenaario, jossa export_omm = true, palauta sen OMM-luettelon teksti; muuten None.
`kshana::api::export_oem`	`(src: &str) -> Result<String, String>`	Vie rataskenaarion propagoitu tähdistö CCSDS OEM -tekstinä — inertiaalinen (TEME) tilojen aikasarja, sekä paikka ETTÄ nopeus, avaruusalusten efemeridien vaihtomuodossa, jota lentodynamiikkatyökalut (GMAT/Orekit/STK) lukevat.
`kshana::api::auto_export_oem`	`(src: &str) -> Result<Option<String>, String>`	Jos src on rataskenaario, jossa export_oem = true, palauta sen OEM-teksti; muuten None.
`kshana::api::inject_eop`	`(src: &str, finals2000a_body: &str) -> Result<String, String>`	Upota todellinen IERS finals2000A -runko skenaarion kenttään eop_finals2000a (CLI-polku --eop <file>) ja palauta yhdistetty TOML.
`kshana::api::with_study_meta`	`(json: &str, meta: &crate::report::StudyMeta) -> String`	Liitä tutkimuksen metatietolohko jo muodostettuun tulos-JSON-asiakirjaan ja palauta asiakirja, johon on lisätty ylätason avain ”meta” heti aloittavan aaltosulkeen perään.
`kshana::api::run_scenario`	`(src: &str) -> Result<RunOutput, KshanaError>`	Aja skenaario ja palauta tyypitetty tulos jäsennellyllä virheellä — sisääntulopiste, jota sidoskutsujien tulee suosia merkkijonovirheisen [run_toml]-funktion sijaan.
`kshana::api::run_toml`	`(src: &str) -> Result<RunOutput, String>`	Jäsennä, välitä ja aja TOML-merkkijonona annettu skenaario.
`kshana::api::run_toml_lang`	`(src: &str, lang: &str) -> Result<RunOutput, String>`	[run_toml] käyttäjälle kielellä lang (tunniste kuten de, pt-BR, zh-Hans, en-XA).
`kshana::api::run_toml_bilingual`	`(src: &str, lang: &str) -> Result<(RunOutput, Option<RunOutput>), String>`	Kaksi funktion [run_toml_lang] ajoa erillään: englanninkielinen ajo, jonka json ja csv ovat konetiedostot, ja toiselle kielelle ajo sillä kielellä kaikelle, minkä ihminen lukee.
`kshana::api::run_toml_human`	`(src: &str, lang: &str) -> Result<HumanOutput, String>`	Funktion [run_toml_bilingual] toinen vaihe yksinään: aja skenaario kerran kielellä lang ja palauta vain se, minkä ihminen lukee.
`kshana::api::run_scenario_lang`	`(src: &str, lang: &str) -> Result<RunOutput, KshanaError>`	[run_scenario] käyttäjälle kielellä lang; ks. [run_toml_lang].
`kshana::api::error_info_json`	`(src: &str, lang: &str) -> String`	Aja src kielellä lang ja, jos se epäonnistuu, kuvaa virhe JSON-oliona {"kind": <kind_tag>, "code": <stable code or null>, "message": <text in the language>}.
`kshana::api::without_evidence`	`(json: &str) -> String`	json ilman todistemerkintää ([crate::evidence_label]); muuttumaton, jos siinä ei ole sellaista.
`kshana::api::without_evidence_labels`	`(mut out: RunOutput) -> RunOutput`	out ilman todistemerkintää JSON-, SVG- ja CSV-tulosteestaan, tavu tavulta sellaisena kuin ajo ne tuotti ennen merkinnän olemassaoloa; tuloste, jossa ei ole merkintää, on muuttumaton.
`kshana::api::run_toml_untiered`	`(src: &str) -> Result<RunOutput, String>`	[run_toml] ilman tyyppikohtaista figure_tiers-lohkoa, jonka [run_toml_inner] liittää (RM-04): ajolle, jonka asiakirja on upotettu toisen tyypin tulokseen (kampanjan jäsen), jotta ulompi asiakirja säilyttää tavunsa.
`kshana::api::append_figure_tiers`	`(json: &str, block: &serde_json::Value) -> Result<String, String>`	json, johon block on liitetty viimeiseksi avaimeksi, figure_tiers, tavu tavulta sellaisena kuin Documented-kääre olisi sen serialisoinut: kahden välilyönnin sisennys, lohko sisennettynä yhden tason.

Paketin vaihtoformaatit: CCSDS Tracking Data Message (TDM) -jäsennin ja -kirjoitin (kshana::ccsds_tdm); Kshana Interchange Format (KIF) (kshana::interchange).

Käyttö — CLI#

Rekisteriasennuksessa ei ole hakemistoa scenarios/, joten CLI kantaa vertailuskenaariot mukanaan; kshana example luettelee ne ja nimeää ne harvat, jotka se jättää pois, syineen (jokainen lukee vain repositorion mukana toimitettua dataa tai seuraa esiasetusta, jonka julkaisu voi pidättää).

kshana example clock-holdover > clock-holdover.toml   # write a bundled scenario to a file
kshana clock-holdover.toml                            # run it
kshana --validate clock-holdover.toml                 # lint it without running
kshana example                                        # list every bundled scenario
kshana kinds                                          # list every scenario kind

kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml   # the GPS constellation, real orbital elements
kshana orbit-sgp4-gps.toml --export list              # which exchange formats apply
kshana orbit-sgp4-gps.toml --export all               # every exchange file that applies
kshana orbit-sgp4-gps.toml --animate html             # a self-contained animation page

Ajo välittää skenaarion kentän kind mukaan ja kirjoittaa <scenario>.result.json, .chart.svg, .report.html (tulostettava raporttisivu HTML-muodossa, HyperText Markup Language) ja .report.json (sama raportti koneluettavana), sekä .table.csv niille tyypeille, jotka julkaisevat taulukon, skenaariotiedoston viereen. --export lisää vaihtotiedostot: CZML (Cesium Language) ja KML (Keyhole Markup Language) maapallonäkymiin, GeoJSON kartoille, STK (Systems Tool Kit) -efemeriditiedostot ja SigMF (Signal Metadata Format) -tallenteet tyypille spectrum. --animate lisää SVG-, HTML- tai kuva kuvalta -animaation.

Repositorion kloonista samat komennot ottavat tiedostot suoraan hakemistosta scenarios/, myös usean skenaarion tutkimuksen (kshana --study scenarios/quantum-pnt-demonstrator.suite.toml) ja skenaarion lunar-llr-datum, ainoan, joka lukee vain repositorion mukana toimitettua todellista laseretäisyysmittausdataa.

Jokainen varmennusmatriisin ominaisuus on merkitty tilaan validoitu (tarkistettu riippumatonta ulkoista oraakkelia vastaan), mallinnettu tai kumppanin omistama; optisten kellojen luvut ovat avaruustavoitteita maanpäällisellä laitteistolla (strontium-optista kelloa ei ole lennetty). Kypsyys ei ole tasaista eri aloilla: Maan PNT on validoitu oikeaa dataa vastaan; syväavaruuden ja Marsin navigointi on mallinnettua, ja vain sen rakennuspalikat (valon kulkuaika, planeettojen paikat) on validoitu ulkoisia oraakkeleita vastaan; oikean tehtävän syväavaruuden radanmääritys (OD, orbit determination) on tiekartalla.

Ominaisuudet#

Moottorissa on 92 skenaariolajia; kshana kinds luettelee ne kenttineen. Uutta versiossa 0.38.0: gnss-ssv (GNSS-signaalit avaruusaluksille GNSS-kiertoratojen yläpuolella, ympärillä ja ohi) ja lunar-infrastructure (Kuun kiertorata ja pinta navigointi- ja geodeettisena infrastruktuurina), molemmat MODELLED, sekä holdover-test (aikavirhetallenne ITU-T-maskeja vasten).

Spektri: miten häirintälähde valtaa GNSS:n L-kaistan, kaista kerrallaan.
Kellot ja ajoitus: holdover kynnystä vastaan, ajansiirto ja telealan holdover Kansainvälisen televiestintäliiton standardointisektorin (ITU-T) maskeja vastaan.
Satelliittitähdistöt minkä tahansa kappaleen ympärillä: kattavuus, DOP (tarkkuuden heikkenemiskerroin) ja saatavuus Maan, Kuun tai Marsin ympärillä sekä aurinkokunta yhdellä epookilla.
Matalan Maan kiertoradan navigointi: signaali, ylitys ja yhteys, navigointiviesti sekä yhdistetty paikkaratkaisu vaihe vaiheelta.
Kampanjat: ketjutettu tehtävä, pyyhkäisy tai Monte Carlo -joukko yhdessä skenaariossa.
Raportit, animaatio ja viennit: jokainen luku yksikköineen ja tunnisteineen; ajon animoitu piirros; SP3- (Standard Product 3), CCSDS:n (Consultative Committee for Space Data Systems) rataviestit sekä CZML- (Cesium Language), KML- (Keyhole Markup Language), GeoJSON-, STK- (Systems Tool Kit) ja SigMF-tiedostot (Signal Metadata Format).
Aluksen GNSS-luottamus (receiver_trust, mukaan lukien receiver_trust::live): 0-100 pisteen luku perusteluineen vastaanottimen NMEA:sta, livenä tai lokista; ohjeellinen, ei tyyppihyväksytty navigointilaite.
Todistepaketit (evidence): allekirjoitettu tekninen tallenne lokijaksosta, todennettavissa offline-tilassa.
Luottamustelemetria (telemetry): luottamusvirta Prometheus-mittareina, SIEM-tapahtumina ja valinnaisesti OpenTelemetry-muodossa.
Harjoitusvirrat (nmea_synth): synteettinen sillan NMEA, jossa on käsikirjoitettua häirintää ja harhautusta sekä ohjaajan loki. Vain tekstiä; ei koskaan aluksen live-navigointijärjestelmiin.
Häiriökartta (interference_map): koostetut heikentyneen navigoinnin kartat ja reittialtistus.
Testipenkki (bench) ja compliance-kartoitus (interop::testbench, compliance): skenaarion ajoneuvon liike ja tapahtumat laboratorion GNSS-simulaattorille sekä tulosasiakirjoista täytetty julkisen kehyksen vastaavuustaulukko.
GNSS IQ -laboratorio (iq): kohtaukset, hankinta, seuranta, monitorit ja kampanjat tallennetulla ja synteettisellä IQ-datalla.

Arkkitehtuuri#

Yksi avoin moottori keskellä, kshana 0.40.0, tyypitetyllä lähetyksellä 75 lajiin; sen ympärillä komentorivi, Rust-kirjasto, Python, WebAssembly ja Kshana Studio, MCP-palvelin, Docker-image ja JetBrains-liitännäinen; sen alla Kshana Pro, suljettu kerros, joka riippuu avoimesta moottorista eikä koskaan haarauta sitä

Sama skenaariotiedosto antaa samat tavut jokaisella pinnalla. MCP on Model Context Protocol: kshana-mcp antaa tekoälyavustajan (AI) ajaa moottoria.

Tutkimus#

Kuusi arXiv-artikkelia perustuu avoimeen moottoriin, kukin komentoineen: arXiv:2606,22054 (häiriöilmaisimien optimismikuilu), arXiv:2606,24210 (ehdollinen ajoituksen suojaustaso), arXiv:2607,05415 (kuinka vakaa PNT-kestävyyspistemäärä on), arXiv:2607,02566 (Kuun pinta-aseman havaittavuus pitkän kantaman interferometrialla), arXiv:2607,06212 (Kuun etelänapaisen alueen geometria ja pintamajakat) ja arXiv:2610,23871 (kuunläheinen navigointi havaittavuusongelmana: kaaren pituus, Gramin matriisin ehtoluku ja Dopplerin vipuvarsi). Ks. Tutkimus.

Versiot#

Koko moottori on vapaa AGPL-3.0-lisenssillä. Kshana Pro, suljettu kerros, joka riippuu avoimesta moottorista eikä koskaan haarauta sitä, sekä räätälöidyt tutkimukset ovat saatavilla sopimuksella Ashforde® OÜ:ltä: contact@ashforde.org. Hintoja ei ole; ks. docs/PRO.md.

Lue lisää#

Koko README → https://github.com/AshfordeOU/kshana
Kshana Studio (moottori selaimessasi WebAssemblynä) → https://kshana.dev
Ominaisuudet → docs/CAPABILITY.md
Validointi ja alkuperä → docs/VALIDATION.md · docs/PROVENANCE.md
Varmennusmatriisi → docs/VERIFICATION-MATRIX.md
Viittaa → CITATION.cff · DOI 10.5281/zenodo.20528627

Lisenssi#

Vapaa ja avoimen lähdekoodin ohjelmisto lisenssillä GNU AGPL-3.0-only (GNU Affero General Public License, vain versio 3). Kaupallinen lisenssi on saatavilla yritykseltä Ashforde® OÜ (virolainen osakeyhtiö; OÜ = osaühing) suljettua integrointia varten; ks. LICENSING.md. Ashforde® OÜ kehittää ja ylläpitää ohjelmistoa ammattimaisesti.