Rust crate · Kshana docs

Kshana: märk, täpset hetke tähistav kompassi-ristik, sõnamärgi kshana kõrval

Kshana · क्षण · täpne hetk
Avatud lähtekoodiga simulaator PNT (positsioneerimine, navigatsioon ja aeg) vastupidavuse jaoks.

Väljalase v0.40.0 401 võimekusest 176 valideeritud sõltumatute väliste etalonide (oraaklite) vastu Ligikaudu 95 % reakatvus, pidevas integratsioonis nõutav 85 % Litsents: AGPL-3.0-only või kommertslitsents DOI 10.5281/zenodo.20528627

Harjuta minutit, mil GNSS vaikib#

Kshana kordab segamist, spuufimist ja kella holdover-it, kui GNSS-i (ülemaailmne satelliitnavigatsioonisüsteem) signaalid katkevad, ning ütleb, kui kaua süsteem hoiab aega ja asukohta oma eelarves ning milline kell või andur annab suurima varu. See on Rusti kast: mootor teegina ja käsk kshana. Iga jooks on bitist bitini reprodutseeritav stsenaariumist, algväärtusest ja mootori versioonist.

Esmalt saab proovida, ilma midagi paigaldamata: Kshana Studio käitab kogu mootorit brauseris, WebAssemblyks kompileeritult, ja ei lae midagi üles.

Tõendid#

401 võimekusest 176 on valideeritud sõltumatute väliste etalonide (oraaklite) vastu; 221 on ausalt märgistatud modelleeritud, 4 on partneri omad. Iga võimekus kannab masinkontrollitud registris (ledger) ühte silti: VALIDATED (sõltumatu väline etalon nõustub: tegelikud andmed, sõltumatu teostus või avaldatud etalonvektorid), MODELLED (sisemiselt kooskõlas ja see on öeldud välja) või PARTNER (selle eest vastutab riistvarapartner). Kontrollide hulgas: kõik 666 SGP4 (Simplified General Perturbations 4) vektorit AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 täpsusega 4,12 mm ja Cowelli jõumudel täpsusega 0,08 m Orekit 12,2 suhtes.

Kuidas võimekus oma sildi teenib: võimekus, etalon (oraakel), test, registri (ledger) silt. Kontrollistaatus kõigi 401 võimekuse lõikes: 176 valideeritud, 221 modelleeritud, 4 partneri omad

Paigaldamine#

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

Kasutamine — teek#

Näide on täielik programm: see kannab oma stsenaariumi, mis on kirjutatud TOML-is (Tom's Obvious, Minimal Language), nii et see käivitub värske cargo new projekti src/main.rs pärast cargo add kshana, ilma et kettal oleks midagi muud.

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 tulemusdokument JSON-is (JavaScript Object Notation), out.svg diagramm SVG-na (Scalable Vector Graphics) ja out.csv, tabelit avaldavate liikide puhul, see tabel CSV-na (komaga eraldatud väärtused).

API viide, genereeritud failist src/api.rs#

Iga kasti kshana::api avalik funktsioon mootori versioonil v0.40.0, loetud lähtekoodist ehitamise ajal.

Funktsioon	Signatuur	Mida see teeb
`kshana::api::without_figure_tiers`	`(json: &str) -> Option<String>`	json koos selle lõpus oleva figure_tiers plokiga eemaldatuna, bait-baidilt nagu dokument oli enne selle ploki olemasolu; None, kui dokumendil sellist plokki ei ole või on see, mis ei ole selle viimane võti (mida see kast kunagi ei väljasta, seega peab kasutaja seda käsitlema veana, mitte eemaldama midagi, mida ta ei saa seletada).
`kshana::api::list_scenario_kinds`	`() -> Vec<ScenarioMeta>`	Loetle iga sisseehitatud stsenaariumi liik koos selle metaandmetega.
`kshana::api::list_scenario_kinds_json`	`() -> String`	Sisseehitatud stsenaariumi liigid ja nende metaandmed JSON-massiivina — vorm, mida keelesidumised programmeerimiseks introspektsiooniks pakuvad.
`kshana::api::kind_description_in`	`(lang: &crate::i18n::Lang, kind: &str) -> Option<String>`	Sisseehitatud stsenaariumi liigi kind kirjeldus keeles lang kataloogist (inglise keeles, kui keeles selle tõlget pole); None nime puhul, mis ei ole sisseehitatud liik.
`kshana::api::kind_description`	`(kind: &str) -> Option<String>`	[kind_description_in] praeguses keeles ([crate::i18n::current]).
`kshana::api::list_scenario_kinds_json_lang`	`(lang: &str) -> Result<String, String>`	[list_scenario_kinds_json], kus iga kirjeldus on keeles lang (silt, mida --lang aktsepteerib, näiteks de või zh-Hans); nimed ja väljaloendid on igas keeles samad ning inglise keele puhul on dokument baidi-baidilt identne dokumendiga [list_scenario_kinds_json].
`kshana::api::kind_modules_json`	`() -> String`	[KIND_MODULES] JSON-objektina, liik moodulinimede massiivi, tabeli järjekorras.
`kshana::api::field_importance_json`	`() -> String`	[HEADLINE_FIELDS] JSON-ina: {kind: {"headline": [path, ...]}}, tabeli järjekorras.
`kshana::api::scenarios_reference_md`	`() -> String`	Renderda sisseehitatud stsenaariumi liikide kataloog eraldiseisva Markdown-viitena (docs/SCENARIOS.md): iga väljasaadetav liik koos selle ühe rea kirjelduse ja nõutud / valikuliste TOML-väljadega.
`kshana::api::validate_scenario`	`(src: &str) -> Vec<String>`	Kontrolli stsenaariumi TOML-i kasti enda introspektsiooni vastu ja tagasta probleemide loend — et kutsujale saaks öelda, mis on valesti ENNE (võimalikult pikka) jooksu, selle asemel et jõuda hilise käitusaja veani.
`kshana::api::export_sp3`	`(src: &str) -> Result<String, String>`	Ekspordi orbiidi/konstellatsiooni stsenaariumi propageeritud konstellatsioon SP3-c tekstina.
`kshana::api::auto_export_sp3`	`(src: &str) -> Result<Option<String>, String>`	Kui src on orbiidistsenaarium, kus export_sp3 = true, tagasta selle SP3-c tekst; muidu None.
`kshana::api::export_omm`	`(src: &str) -> Result<String, String>`	Ekspordi orbiidistsenaariumi TLE keskmised elemendid CCSDS OMM kataloogina — üks OMM (Orbit Mean-Elements Message) iga TLE-ga määratud satelliidi kohta, KVN-kujul, kandes igast TLE-st tegelikku NORAD kataloogi numbrit, COSPAR tähist ja epohhi.
`kshana::api::auto_export_omm`	`(src: &str) -> Result<Option<String>, String>`	Kui src on orbiidistsenaarium, kus export_omm = true, tagasta selle OMM kataloogi tekst; muidu None.
`kshana::api::export_oem`	`(src: &str) -> Result<String, String>`	Ekspordi orbiidistsenaariumi propageeritud konstellatsioon CCSDS OEM tekstina — inertsiaalne (TEME) olekute ajarida, asukoht JA kiirus, kosmoseaparaadi efemeriidi vahetusvormingus, mida lendudünaamika tööriistad (GMAT/Orekit/STK) loevad.
`kshana::api::auto_export_oem`	`(src: &str) -> Result<Option<String>, String>`	Kui src on orbiidistsenaarium, kus export_oem = true, tagasta selle OEM tekst; muidu None.
`kshana::api::inject_eop`	`(src: &str, finals2000a_body: &str) -> Result<String, String>`	Lisa reaalne IERS finals2000A sisu stsenaariumi välja eop_finals2000a (CLI tee --eop <file>), tagastades liidetud TOML-i.
`kshana::api::with_study_meta`	`(json: &str, meta: &crate::report::StudyMeta) -> String`	Lisa uuringu metaandmete plokk juba renderdatud tulemuse JSON-dokumenti, tagastades dokumendi, kus ülemise taseme „meta“ võti on sisestatud kohe avava loogelise sulu järele.
`kshana::api::run_scenario`	`(src: &str) -> Result<RunOutput, KshanaError>`	Käivita stsenaarium ja tagasta tüüpitud tulemus struktureeritud veaga — sisenemispunkt, mida sidumiskutsujad peaksid eelistama stringiveaga [run_toml].
`kshana::api::run_toml`	`(src: &str) -> Result<RunOutput, String>`	Parsi, edasta ja käivita stsenaarium, mis on antud TOML-stringina.
`kshana::api::run_toml_lang`	`(src: &str, lang: &str) -> Result<RunOutput, String>`	[run_toml] kasutajale keeles lang (silt, näiteks de, pt-BR, zh-Hans, en-XA).
`kshana::api::run_toml_bilingual`	`(src: &str, lang: &str) -> Result<(RunOutput, Option<RunOutput>), String>`	Kaks [run_toml_lang] jooksu hoitud lahus: inglise keele jooks, mille json ja csv on masinafailid, ning teise keele puhul jooks selles keeles kõige jaoks, mida inimene loeb.
`kshana::api::run_toml_human`	`(src: &str, lang: &str) -> Result<HumanOutput, String>`	[run_toml_bilingual] teine läbimine eraldi: käivita stsenaarium üks kord keeles lang ja tagasta ainult see, mida inimene loeb.
`kshana::api::run_scenario_lang`	`(src: &str, lang: &str) -> Result<RunOutput, KshanaError>`	[run_scenario] kasutajale keeles lang; vt [run_toml_lang].
`kshana::api::error_info_json`	`(src: &str, lang: &str) -> String`	Käivita src keeles lang ja kui see ebaõnnestub, kirjelda tõrget JSON-objektina {"kind": <kind_tag>, "code": <stabiilne kood või null>, "message": <tekst selles keeles>}.
`kshana::api::without_evidence`	`(json: &str) -> String`	json ilma tõendussildita ([crate::evidence_label]); muutmata, kui sellel silti pole.
`kshana::api::without_evidence_labels`	`(mut out: RunOutput) -> RunOutput`	out koos tõendussildi eemaldamisega selle JSON-ist, SVG-st ja CSV-st, bait-baidilt nii, nagu jooks need tootis enne sildi olemasolu; sildita väljund jääb muutmata.
`kshana::api::run_toml_untiered`	`(src: &str) -> Result<RunOutput, String>`	[run_toml] ilma liigipõhise figure_tiers plokita, mille [run_toml_inner] lisab (RM-04): jooksu jaoks, mille dokument on manustatud teise liigi tulemusse (kampaania liige), nii et välimine dokument säilitab oma baidid.
`kshana::api::append_figure_tiers`	`(json: &str, block: &serde_json::Value) -> Result<String, String>`	json koos plokiga block lisatuna selle viimase võtmena, figure_tiers, bait-baidilt nii, nagu Documented ümbris oleks selle serialiseerinud: kahe tühikuga ilus printimine, plokk pesastatud ühe taseme võrra.

Vahetusvormingud kastis: CCSDS Tracking Data Message (TDM) parser ja kirjutaja (kshana::ccsds_tdm); Kshana Interchange Format (KIF) (kshana::interchange).

Kasutamine — CLI#

Registrist paigaldamisel ei ole kataloogi scenarios/, seega kannab CLI etalonstsenaariume endaga kaasas; kshana example loetleb need ja nimetab vähesed, mille see välja jätab, koos põhjusega (iga neist loeb ainult hoidlaga tarnitud andmeid või järgib eelseadet, mille väljalase võib kinni hoida).

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

Jooks edastatakse stsenaariumi kind järgi ja kirjutab stsenaariumifaili kõrvale <scenario>.result.json, .chart.svg, .report.html (prinditav aruandeleht HTML-is, HyperText Markup Language) ja .report.json (sama aruanne, masinloetav), pluss .table.csv tabelit avaldavate liikide jaoks. --export lisab vahetusfailid: CZML (Cesium Language) ja KML (Keyhole Markup Language) gloobusevaaturitele, GeoJSON kaartidele, STK (Systems Tool Kit) efemeriidifailid ja SigMF (Signal Metadata Format) salvestised liigi spectrum jaoks. --animate lisab SVG-, HTML- või kaader-kaadrilt animatsiooni.

Hoidla kloonist võtavad samad käsud faile otse kataloogist scenarios/, sealhulgas mitmestsenaariumilise uuringu (kshana --study scenarios/quantum-pnt-demonstrator.suite.toml) ja lunar-llr-datum, ainsa stsenaariumi, mis loeb ainult hoidlaga tarnitud reaalseid laservahemõõtmise andmeid.

Iga võimekus kontrollimaatriksis on märgistatud kui valideeritud (kontrollitud sõltumatu välise etaloni vastu), modelleeritud või partneri omad; optiliste kellade arvud on kosmoseesmärgid maapealsel riistvaral (ükski strontsiumi optiline kell ei ole lennanud). Küpsus ei ole valdkonniti ühtlane — Maa PNT on valideeritud tegelike andmete vastu; kaugkosmose ja Marsi navigatsioon on modelleeritud, ainult selle ehituskivid (valguse levi aeg, planeetide asukohad) on valideeritud väliste sõltumatute etalonide vastu; tegeliku missiooni kaugkosmose OD (orbiidi määramine) on teekaardil.

Võimekused#

Mootoril on 92 stsenaariumi liiki; kshana kinds loetleb need koos nende väljadega. Uus versioonis 0.38.0: gnss-ssv (GNSS-signaalid kosmoselaevadele GNSS-orbiitidest kõrgemal, nende ümber ja kaugemal) ja lunar-infrastructure (Kuu orbiit ja pind navigatsiooni- ja geodeetilise infrastruktuurina), mõlemad MODELLED, ning holdover-test (ajavea kirje ITU-T maskide vastu).

Spekter: kuidas segaja võtab GNSS-i L-riba, riba kaupa.
Kellad ja ajastus: holdover läve vastu, aja edastamine ning telekommunikatsiooni holdover Rahvusvahelise Telekommunikatsiooniliidu standardimissektori (ITU-T) maskide vastu.
Konstellatsioonid mis tahes keha ümber: katvus, täpsuse halvenemise tegur ja kättesaadavus Maa, Kuu või Marsi ümber ning päikesesüsteem ühel epohhil.
Madala Maa orbiidi navigatsioon: signaal, läbilend ja side, navigatsioonisõnum ning liidetud fiks, etapp etapi haaval.
Kampaaniad: aheldatud missioon, parameetriskaneerimine või Monte Carlo ansambel ühes stsenaariumis.
Aruanded, animatsioon ja eksport: iga arv koos oma ühiku ja sildiga; käitamise animeeritud joonis; SP3 (Standard Product 3), CCSDS (Consultative Committee for Space Data Systems) orbiidisõnumid, CZML (Cesium Language), KML (Keyhole Markup Language), GeoJSON, STK (Systems Tool Kit) ja SigMF (Signal Metadata Format) failid.
Laeva GNSS-i usaldus (receiver_trust, sealhulgas receiver_trust::live): 0–100 skoor koos põhjustega vastuvõtja NMEA-st, reaalajas või logist; nõuandev, mitte tüübikinnitust omav navigatsiooniseade.
Tõendipaketid (evidence): allkirjastatud tehniline kirje logiaknast, kontrollitav võrguühenduseta.
Usalduse telemeetria (telemetry): usaldusvoog Prometheuse mõõdikutena, SIEM-i sündmustena ja valikulise OpenTelemetry'na.
Koolitusvood (nmea_synth): sünteetiline sillal kasutatav NMEA stsenaariumipõhise segamise ja spuufimisega ning juhendaja logi. Ainult tekst; mitte kunagi laeva reaalajas navigatsioonisüsteemidele.
Häirekaart (interference_map): koondatud halvenenud navigatsiooni kaardid ja marsruudi eksponeeritus.
Katsestend (bench) ja compliance-kaardistus (interop::testbench, compliance): stsenaariumi sõiduki liikumine ja sündmused laboratoorse GNSS-simulaatori jaoks ning avaliku raamistiku kaardistus, mis on täidetud tulemusdokumentidest.
GNSS-i IQ labor (iq): stseenid, püüe, jälgimine, monitorid ja kampaaniad salvestatud ja sünteetilisel IQ-l.

Arhitektuur#

Üks avatud mootor keskel, kshana 0.40.0, tüübitud suunamisega 75 liiki hõlmavale; selle ümber käsurida, Rusti teek, Python, WebAssembly ja Kshana Studio, MCP server, Dockeri tõmmis ja JetBrainsi plugin; selle all Kshana Pro, patenteeritud kiht, mis sõltub avatud mootorist ja ei hargne sellest kunagi

Sama stsenaariumifail annab igal liidesel samad baidid. MCP on Model Context Protocol: kshana-mcp laseb tehisintellekti (AI) assistendil mootorit käitada.

Uuringud#

Kuus arXivi artiklit tuginevad avatud mootorile, igaühel koos selle taga oleva käsuga: arXiv:2606,22054 (häiretuvastajate optimismilõhe), arXiv:2606,24210 (tingimuslik ajastuse kaitsetase), arXiv:2607,05415 (kui stabiilne on PNT vastupidavuse skoor), arXiv:2607,02566 (Kuu pinnajaamade jälgitavus väga pika baasjoonega interferomeetria abil), arXiv:2607,06212 (Kuu lõunapoolse polaarala geomeetria ja pinnamajakad) ja arXiv:2610,23871 (tsislunaarne navigatsioon jälgitavusprobleemina: kaare pikkus, Grami maatriksi tingimuslikkus ja Doppleri kangi efekt). Vt Uuringud.

Väljaanded#

Kogu mootor on vaba AGPL-3.0 all. Kshana Pro, patenteeritud kiht, mis sõltub avatud mootorist ja ei hargne sellest kunagi, ning kohandatud uuringud on lepingu alusel saadaval Ashforde® OÜ-lt: contact@ashforde.org. Hindu ei ole; vt docs/PRO.md.

Loe lähemalt#

Täielik README → https://github.com/AshfordeOU/kshana
Kshana Studio (mootor brauseris, WebAssemblyna) → https://kshana.dev
Võimekused → docs/CAPABILITY.md
Valideerimine ja päritolu → docs/VALIDATION.md · docs/PROVENANCE.md
Kontrollimaatriks → docs/VERIFICATION-MATRIX.md
Viita → CITATION.cff · DOI 10.5281/zenodo.20528627

Litsents#

Vaba ja avatud lähtekoodiga GNU AGPL-3.0-only all (GNU Affero üldine avalik litsents, ainult versioon 3). Kommertslitsents on suletud integratsiooniks saadaval Ashforde® OÜ-lt (Eesti osaühing; OÜ = osaühing); vt LICENSING.md. Professionaalselt arendanud ja hooldanud Ashforde® OÜ.