Maskinoversættelse, ikke gennemgået af en modersmålstalende. Engelsk er referencen.

ScenarierRedigér på GitHubKilde: docs/SCHEMA.md

Resultatskema — læsning af en Kshana-*.result.json

Hver kørsel skriver en versioneret, selvbeskrivende JSON (JavaScript Object Notation)-artefakt ved siden af scenariet. Denne side er den håndskrevne læsers vejledning til udvekslingskonvolutten og til resultatformerne for ur og bane: hvert felts enhed, hvor det beregnes i kilden, og hvordan det læses. Den kanoniske type er RunResult i src/report.rs; kvalitetsmålene er FoMScores i src/fom.rs.

Den er ikke den komplette feltreference. Motoren afsender over langt flere typer end disse to, og hver udsender sin egen pakke. Den komplette reference — enhed, proveniensklasse og definition for hvert numerisk felt i hver indbygget type — er genereret, ikke håndskrevet: se Enheder og proveniens, for hvert felt, for hver type nedenfor.

Udvekslingskonvolut (KIF, Kshana Interchange Format) — genkendelse og versionskontrol af en artefakt#

Kshana-artefakter kan pakkes ind i en neutral, selvbeskrivende udvekslingskonvolut, så et tredjepartsværktøj kan genkende filen og afgøre, om det kan læse den, før det forpligter sig til et nyttelastskema. Den kanoniske type er Envelope i src/interchange.rs.

Nøgle Type Betydning
format streng Altid "kshana-interchange" (FORMAT_TAG) — sådan genkender et fremmed værktøj en Kshana-artefakt.
schema_version streng Skemaversionen MAJOR.MINOR (SCHEMA_VERSION, den eneste sandhedskilde for hele cratet).
kind streng Artefakttype, fx "scenario", "run-result", "trade-study" — lader en forbruger route uden at parse indholdet.
engine_version streng Crateversion (Cargo.toml), der frembragte nyttelasten.
payload objekt Den indpakkede artefakt som kanonisk JSON (en Scenario, en RunResult, …).

Kompatibilitetskontrakt. Versioner er MAJOR.MINOR. Nye felter tilføjes med #[serde(default)] (den additive disciplin), så en læser kan parse enhver artefakt med samme hovedversion og en lige så gammel eller ældre delversion (Compatible). En strengt nyere delversion (ForwardIncompatible) kan bære felter, som denne læser ikke kan honorere, og en anden hovedversion (MajorIncompatible) er et strukturelt brud — begge afvises af Envelope::parse, som kontrollerer formatmærket og versionen ved grænsen i stedet for i det skjulte at misparse fremmed input.

Determinisme. Konvolutten bærer intet tidsstempel — Kshanas løfte om reproducerbarhed (scenario + seed + engine_version reproducerer en kørsel) kræver det. Proveniens ligger i engine_version og i nyttelastens eget scenario_hash.

En typet tilbagelæsning (Envelope::payload_as::<T>()) virker for enhver nyttelast, der implementerer Deserialize (fx Scenario). Resultatartefakter kan efter udformningen kun serialiseres og læses som den rå JSON-værdi payload.

Øverste niveau (pakkerne for ur og bane)#

Nøgle Type / enhed Betydning Kilde
schema_version streng Version af resultatskemaet (uafhængig af motorversionen). report.rs
engine_version streng Crateversion (Cargo.toml), der frembragte filen. report.rs
scenario_hash hex-streng SHA-256 (SHA: Secure Hash Algorithm) over det kanoniske scenarie-JSON — kørslen kan reproduceres ud fra scenario + seed + engine_version. report.rs:hash_scenario
seed u64 RNG (random-number generator)-seed til kvantekørslen (den klassiske bruger seed + 0x9e3779b97f4a7c15). run.rs
threshold_ns nanosekunder Tidssynkroniseringens specifikation: en fejl inden for ±threshold_ns er "in spec". scenarie
quantum objekt (ClockRun) Kvantesensorens kørsel (se nedenfor). report.rs
classical objekt (ClockRun) Den klassiske sensors kørsel, til sammenligning. report.rs
units objekt Kort over enhed/proveniens for hvert felt i dette dokument, nøglet efter feltsti. Se §Enheder og proveniens nedenfor. field_schema.rs:units_block
evidence objekt (0,40) Kørslens evidensetiket: tier (VALIDATED, MODELLED eller PARTNER: den svageste status blandt rækkerne, så den aldrig hævder mere end sin svageste række), matrix (docs/VERIFICATION-MATRIX.md), id_rule og rows, én pr. verifikationsmatrixrække, kørslen brugte (de rækker, dens avancerede rapport opfører, fra advanced_report::KIND_CAPABILITIES): id (VM- og de første 8 hex-cifre af SHA-256 for rækkens kravtekst), requirement og status, alle læst fra matricen, ingen skrevet ind. Tilføjet af api::run_toml til hver types resultat, før den afsluttende blok figure_tiers, når der er en (den blok forbliver den sidste nøgle); evidence_label::strip_json fjerner den byte for byte. Diagram-SVG og CSV-tabellen fra den samme kørsel bærer den samme etiket (<metadata id="kshana-evidence"> og en synlig linje under diagrammet; kommentarlinjer # evidence: foran CSV'en). Kampagnemedlemmer, der er indlejret i en anden types resultat, bærer ingen: det ydre dokument gør. Bærer ingen tal. evidence_label.rs
figure_tiers objekt Verifikationsniveauet for hvert rapporteret kvalitetsmål, og altid dokumentets sidste nøgle. figures opregner én post for hvert tal, der er til stede: path (fx quantum.fom.timing_p95_ns), tier (VALIDATED = kontrolleret mod en uafhængig ekstern reference, MODELLED = ud fra grundprincipper, internt testet), requirement (den række i verifikationsmatrixen, som niveauet læses fra) og applicable. applicable er false, med en reason, for security i hvert scenarie uden konfigureret angreb: grænsen bliver i fom.security, men den besvarer ikke et spørgsmål, scenariet stiller. untiered opregner ethvert tal, som ingen matrixrække ejer (positionstallene for hybrid og fusion), i stedet for at give det et niveau. Udsendt af typerne clock (enkeltkørsel og Monte Carlo-ensemble), orbit, hybrid og fusion, som bygger den inde i deres kørsel, og (0,36, RM-04) af hver anden type for dens hovedtal, tilføjet efter kørslen fra tabellen for hver type fom_label::kind_figures; api::without_figure_tiers fjerner den igen til dokumentet uden niveauer byte for byte. Udsendes ikke af lunar-station-coverage, hvis resultat er en frosset, på forhånd registreret forudsigelse (docs/predictions/lunar-reference-station.md): den type har ingen figure_tiers, før en ny dateret forudsigelse erstatter den. Udsendes heller ikke af leo-ppp, solar-system, optical-atmosphere (0,37; arrays for hvert sted), sweep og sweep-nd, som ikke har noget skalart hovedtal, eller af lunar-attack-surface, hvis dokument er kompakt JSON (fom_label::KINDS_EXCLUDED_FROM_FIGURE_TIERS giver hver årsag), eller af en kampagnes indlejrede medlemsdokumenter. Bærer ingen tal. fom_label.rs:figure_tiers, fom_label.rs:kind_figure_tiers
geometry objekt, valgfrit Opsummering af geometri i bane-pakken: samples_total, samples_with_fix, sigma_uere_m (m, det modellerede budget for afstandsfejl for hver satellit), best_pdop / median_pdop (dimensionsløse) og best_position_sigma_m / median_position_sigma_m (m, PDOP (positionens dilution of precision) × sigma_uere_m). Kun bane-pakken. orbit.rs
eci_track array af [x, y, z] km, valgfrit Propageret spor i jordcentreret inertialsystem for brugerens rumfartøj, én post for hvert samplet tidspunkt. Kun bane-pakken; ellers udeladt. Kun output — ikke hashet. report.rs
meta objekt (StudyMeta), valgfrit Additiv rapportmetadata (studiets titel, genereringsstempel, forfatter, ansvarsfraskrivelse). Udeladt, når den ikke er der, så en kørsel uden meta er byte-identisk med ældre output. Kun output — ikke hashet. report.rs

ClockRun (hver af quantum / classical)#

Nøgle Type / enhed Betydning
spec.id streng Sensoridentifikator (fx optical-sr-lattice).
spec.kind streng Modeltype (fx clock).
spec.provenance streng Henvisning/kilde til sensorens parametre.
spec.params objekt De rå modelparametre, der er brugt.
series array af {t, error_ns, gnss} Tidsserie for hvert trin: t sekunder, error_ns tidsfejlen i nanosekunder, gnss en af nominal/degraded/denied.
fom objekt (FoMScores) De bedømte kvalitetsmål (nedenfor).
adev_curve array af {tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi} Overlappende Allan-deviation: tau_s middeltiden (s), adev den dimensionsløse fraktionelle frekvensstabilitet σ_y(τ), n_samples antallet af overlap bag det punkt, noise den potenslovstype, der er identificeret ud fra MDEV (modificeret Allan-deviation)-hældningen (fx WhiteFm), edf de støjtypespecifikke effektive frihedsgrader, og ci_lo/ci_hi det χ²-baserede 95%-konfidensbånd for adev ved det τ. Beregnet i allan.rs:overlapping_adev_curve.
filter_health objekt, valgfrit Vurdering af Kalman-filterets konsistens (NIS/NEES (NIS: normaliseret innovation i anden; NEES: normaliseret estimeringsfejl i anden) mod deres χ²-bånd), beregnet i filter_health.rs; udeladt for kørsler, der ikke vurderer den.

FoMScores (objektet fom)#

Felt Enhed Betydning Kilde Forbehold
timing_rms_ns ns RMS (root mean square) for urfasefejl (tidssynkronisering) over udfaldet. fom.rs:score en metrik for tidssynkronisering, ikke position
timing_p95_ns ns 95. percentil af tidsfejlen over udfaldet. fom.rs:score
holdover_s s Værste (korteste) glidning inden for specifikationen på tværs af udfaldssegmenter. fom.rs:worst_case_holdover begrænset af gitteret — en nedre grænse ved tidstrinnets opløsning
resilience_slope_ns_per_s ns/s Vækstrate for |fejl| efter mindste kvadrater under udfaldet. fom.rs:score
availability andel [0.1] Andelen af hele kørslen med en løsning inden for specifikationen. fom.rs:score
integrity andel [0.1] eller null Filterets selvkonsistens: andelen af udfaldssamples, hvis sande fejl bliver inden for Kalman-grænsen k-σ. run.rs IKKE integritet efter HPL/VPL/RAIM (HPL: horisontalt beskyttelsesniveau; VPL: vertikalt beskyttelsesniveau; RAIM: receiver autonomous integrity monitoring) — se INTEGRITY.md
security andel [0.1] eller null Analytisk grænse for detekterbarhed af spoofing ud fra urets stabilitet. run.rs + security.rs kun meningsfuldt med et konfigureret angreb, så pakkerne for ur og bane (som ikke konfigurerer nogen) markerer det applicable: false i figure_tiers og udskriver det som n/a (no attack) i oversigten; ikke en RAIM-detektor for flere satellitter

Hvordan "godt" ser ud#

  • Et roligere ur (lavere adev_curve) giver et længere holdover_s og en højere grænse for detekterbarhed i security — det er kontrasten mellem kvante og klassisk.
  • availability nær 1,0 betyder, at systemet blev inden for specifikationen næsten hele kørslen; under et langt udfald falder den for det mere støjede ur.
  • integrity nær 1,0 betyder, at filterets egen usikkerhedsgrænse var ærlig om sin fejl — en udtalelse om selvkonsistens, ikke en garanti for sikkerhed for liv.

Andre scenarietyper#

Hver anden type udsender sin egen resultatform. Nogle af de almindelige:

  • inertial: kvalitetsmål i positionsdomænet i meter (pos_rms_m, pos_p95_m) — enkelt akse (1-DOF (DOF: frihedsgrad)), enkelt seed (se CAPABILITY.md).
  • hybrid / fusion: timing_spec_ns og position_spec_m på øverste niveau og, for hver side, tids- og positionstallene for én sensorsuite (position_p95_m, position_holdover_s og pnt_holdover_s, tiden indtil en af specifikationerne brydes), med en blok figure_tiers som i urpakken, hvor positionstallene er opregnet som untiered.
  • spoof: spoofer-forskydning for hvert trin mod urets detektionsgrænse samt om spoofingen nåede specifikationen før detektion (src/spoof.rs).
  • skyline (orbit og integrity med user_site, gnss-sim, jamming, leo-pvt, leo-pass; kun til stede, når scenariet har en sektion [skyline], så et scenarie uden en er uændret): et objekt skyline på øverste niveau med source (streng: preset:<name>, preset:<name>+overrides eller custom), open_fraction (andel [0.1] af den øvre halvkugles rumvinkel over max(mask_deg, skyline)) og provenance (streng); for hver sample masked_by_skyline (antal satellitter over masken, men bag skylinen: epochs[] for integrity og jamming, gnss_measurements[] for gnss-sim, joint.epochs[] for leo-pvt); og for leo-pass satellites[].pass.epochs_masked_by_skyline (antal epoker). Deres enheder og proveniensklasser står i blokken units (src/skyline.rs UNITS; SKYLINE.md).

For det præcise feltsæt for en vilkårlig type, læs dens post i field-units-schema.json (nedenfor), typens sektion i SCENARIOS.md eller den tilsvarende struct *Result i src/.

Andre filer, en kørsel skriver#

Ved siden af <scenario>.result.json skriver CLI'en (kommandolinjegrænsefladen) <scenario>.chart.svg, en udskrivbar <scenario>.report.html og den samme rapport som <scenario>.report.json, hvis blok reproducibility registrerer motorversionen, SHA-256 af scenariefilen, seed, platformen og den præcise kommando (se REPORTS.md og REPRODUCIBILITY.md). Typer, der udgiver en reproducerbarhedstabel, skriver også <scenario>.table.csv (CSV: comma-separated values). --export skriver udvekslingsfiler (se INTEROP.md) og --animate en animation (se ANIMATION.md).

Enheder og proveniens, for hvert felt, for hver type#

Denne side er håndskrevet og dækker pakkerne for ur og bane. Den maskinlæsbare modpart dækker hver indbygget type:

  • I selve resultatet. Hvert scenaries resultatdokument bærer et objekt units på øverste niveau, der kobler et udsendt felts sti til {"unit", "provenance", "note"}. Stigrammatikken (et array bidrager med ét segment med suffikset [], som deles af dets rækker; * er et jokertegn for ét segment for objekter med datanøgler) og det lukkede proveniensvokabular er defineret i src/field_schema.rs.
  • Som én fil. field-units-schema.json er den høstede foreningsmængde: for hver type hvert numerisk felt, den udsender ved en angivet kilde, med dets enhed, proveniensklasse, evidensniveau og definition — og, nævnt frem for udeladt, hvert felt, der endnu ikke har nogen. Dens blok coverage bærer antallene.

Begge håndhæves af tests/field_units_global.rs, som kører hver registreret type og fejler, hvis et udsendt numerisk felt mangler en enhed og en proveniensklasse. Typer, der endnu ikke er dækket, er nævnt enkeltvis i filens UNCOVERED_KINDS med årsagen til, at hver er åben, og antallet er fastlåst, så listen kun kan blive kortere.

Regenerér JSON'en efter enhver ændring af en rapports form eller af en units-blok:

cargo test --test field_units_global zzz_emit_field_units_schema -- --ignored