Maschinelle Übersetzung, nicht von einem Muttersprachler geprüft. Englisch ist die maßgebliche Fassung.

SzenarienAuf GitHub bearbeitenQuelle: docs/SCHEMA.md

Ergebnisschema — ein *.result.json von Kshana lesen

Jeder Lauf schreibt neben das Szenario ein versioniertes, selbstbeschreibendes JSON-Artefakt (JavaScript Object Notation). Diese Seite ist der von Hand geschriebene Leserleitfaden zur Austauschhülle und zu den Ergebnisformen von Uhr und Orbit: die Einheit jedes Feldes, wo es in der Quelle berechnet wird und wie es zu lesen ist. Der kanonische Typ ist RunResult in src/report.rs; die Gütemaße sind FoMScores in src/fom.rs.

Sie ist nicht die vollständige Feldreferenz. Die Engine verteilt über weit mehr Arten als diese beiden, und jede gibt ihr eigenes Paket aus. Die vollständige Referenz — Einheit, Herkunftsklasse und Definition für jedes numerische Feld jeder eingebauten Art — wird erzeugt, nicht von Hand geschrieben: siehe unten Einheiten und Herkunft, je Feld, für jede Art.

Austauschhülle (KIF, das Kshana Interchange Format) — ein Artefakt erkennen und seine Version prüfen#

Artefakte von Kshana können in eine neutrale, selbstbeschreibende Austauschhülle verpackt werden, damit ein Werkzeug eines Dritten die Datei erkennen und entscheiden kann, ob es sie lesen kann, bevor es sich auf ein Nutzdatenschema festlegt. Der kanonische Typ ist Envelope in src/interchange.rs.

Schlüssel Typ Bedeutung
format Zeichenfolge Immer "kshana-interchange" (FORMAT_TAG) — wie ein fremdes Werkzeug ein Artefakt von Kshana erkennt.
schema_version Zeichenfolge Die Schemaversion MAJOR.MINOR (SCHEMA_VERSION, die einzige Quelle der Wahrheit für das gesamte Crate).
kind Zeichenfolge Artefaktart, z. B. "scenario", "run-result", "trade-study" — lässt einen Konsumenten routen, ohne den Rumpf zu parsen.
engine_version Zeichenfolge Crate-Version (Cargo.toml), die die Nutzdaten erzeugt hat.
payload Objekt Das verpackte Artefakt als kanonisches JSON (ein Scenario, ein RunResult, …).

Kompatibilitätsvertrag. Versionen sind MAJOR.MINOR. Neue Felder werden mit #[serde(default)] hinzugefügt (die additive Disziplin), sodass ein Leser jedes Artefakt mit derselben Hauptversion und einer gleichen oder älteren Nebenversion parsen kann (Compatible). Eine streng neuere Nebenversion (ForwardIncompatible) kann Felder tragen, die dieser Leser nicht berücksichtigen kann, und eine andere Hauptversion (MajorIncompatible) ist ein struktureller Bruch — beide werden von Envelope::parse zurückgewiesen, das das Formatkennzeichen und die Version an der Grenze prüft, statt fremde Eingaben stillschweigend falsch zu parsen.

Determinismus. Die Hülle trägt keinen Zeitstempel — das Reproduzierbarkeitsversprechen von Kshana (scenario + seed + engine_version reproduziert einen Lauf) verlangt es. Die Herkunft steht in engine_version und im eigenen scenario_hash der Nutzdaten.

Ein typisiertes Zurücklesen (Envelope::payload_as::<T>()) funktioniert für jede Nutzlast, die Deserialize implementiert (z. B. Scenario). Ergebnisartefakte sind absichtlich nur serialisierbar und werden als roher JSON-Wert payload gelesen.

Oberste Ebene (Pakete Uhr und Orbit)#

Schlüssel Typ / Einheit Bedeutung Quelle
schema_version Zeichenfolge Version des Ergebnisschemas (unabhängig von der Engine-Version). report.rs
engine_version Zeichenfolge Crate-Version (Cargo.toml), die die Datei erzeugt hat. report.rs
scenario_hash Hex-Zeichenkette SHA-256 (SHA: Secure Hash Algorithm) über das kanonische Szenario-JSON — der Lauf ist aus scenario + seed + engine_version reproduzierbar. report.rs:hash_scenario
seed u64 Seed des Zufallszahlengenerators (RNG) für den Quantenlauf (klassisch verwendet seed + 0x9e3779b97f4a7c15). run.rs
threshold_ns Nanosekunden Die Zeitspezifikation: Ein Fehler innerhalb von ±threshold_ns ist „in Spezifikation“. Szenario
quantum Objekt (ClockRun) Der Lauf des Quantensensors (siehe unten). report.rs
classical Objekt (ClockRun) Der Lauf des klassischen Sensors, zum Vergleich. report.rs
units Objekt Karte von Einheit/Herkunft je Feld für dieses Dokument, nach Feldpfad geschlüsselt. Siehe §Einheiten und Herkunft unten. field_schema.rs:units_block
evidence Objekt (0,40) Die Nachweiskennzeichnung des Laufs: tier (VALIDATED, MODELLED oder PARTNER: der schwächste Status unter den Zeilen, sodass sie nie mehr behauptet als ihre schwächste Zeile), matrix (docs/VERIFICATION-MATRIX.md), id_rule und rows, eine je Zeile der Verifikationsmatrix, die der Lauf beansprucht hat (die Zeilen, die sein erweiterter Bericht aus advanced_report::KIND_CAPABILITIES auflistet): id (VM- und die ersten 8 Hexadezimalziffern des SHA-256 des Anforderungstexts der Zeile), requirement und status, alle aus der Matrix gelesen, keine getippt. Von api::run_toml zum Ergebnis jeder Art hinzugefügt, vor dem nachgestellten Block figure_tiers, wenn es einen gibt (dieser Block bleibt der letzte Schlüssel); evidence_label::strip_json entfernt sie Byte für Byte. Die Diagramm-SVG und die CSV-Tabelle desselben Laufs tragen dieselbe Kennzeichnung (<metadata id="kshana-evidence"> und eine sichtbare Zeile unter dem Diagramm; Kommentarzeilen # evidence: vor der CSV). In das Ergebnis einer anderen Art eingebettete Kampagnenmitglieder tragen keine: Das äußere Dokument trägt sie. Enthält keine Zahlen. evidence_label.rs
figure_tiers Objekt Die Verifikationsstufe jedes gemeldeten Gütemaßes, und immer der letzte Schlüssel des Dokuments. figures listet je vorhandener Kennzahl einen Eintrag auf: path (z. B. quantum.fom.timing_p95_ns), tier (VALIDATED = gegen eine unabhängige externe Referenz geprüft, MODELLED = aus ersten Prinzipien, intern getestet), requirement (die Zeile der Verifikationsmatrix, aus der die Stufe gelesen wird) und applicable. applicable ist false, mit einem reason, für security in jedem Szenario ohne konfigurierten Angriff: Die Schranke bleibt in fom.security, beantwortet aber keine Frage, die das Szenario stellt. untiered listet jede Kennzahl auf, die keine Matrixzeile besitzt (die Positionskennzahlen von hybrid und fusion), statt ihr eine Stufe zu geben. Ausgegeben von den Arten clock (Einzellauf und Monte-Carlo-Ensemble), orbit, hybrid und fusion, die sie in ihrem Lauf aufbauen, und (0,36, RM-04) von jeder anderen Art für ihre Kopfkennzahlen, nach dem Lauf angehängt aus der Tabelle je Art fom_label::kind_figures; api::without_figure_tiers streift sie Byte für Byte zurück zum nicht gestuften Dokument. Nicht ausgegeben von lunar-station-coverage, dessen Ergebnis eine eingefrorene, vorregistrierte Vorhersage ist (docs/predictions/lunar-reference-station.md): Diese Art hat kein figure_tiers, bis eine neue datierte Vorhersage sie ersetzt. Ebenfalls nicht ausgegeben von leo-ppp, solar-system, optical-atmosphere (0,37; Arrays je Standort), sweep und sweep-nd, die keine skalare Kopfkennzahl haben, oder von lunar-attack-surface, dessen Dokument kompaktes JSON ist (fom_label::KINDS_EXCLUDED_FROM_FIGURE_TIERS gibt jeden Grund an), oder von den eingebetteten Mitgliedsdokumenten einer Kampagne. Trägt keine Zahlen. fom_label.rs:figure_tiers, fom_label.rs:kind_figure_tiers
geometry Objekt, optional Geometriezusammenfassung des Orbit-Pakets: samples_total, samples_with_fix, sigma_uere_m (m, das modellierte Entfernungsfehlerbudget je Satellit), best_pdop / median_pdop (dimensionslos) und best_position_sigma_m / median_position_sigma_m (m, PDOP (Positions-Dilution-of-Precision) × sigma_uere_m). Nur Orbit-Paket. orbit.rs
eci_track Array aus [x, y, z] km, optional Propagierte erdzentrierte inertiale Spur des Nutzer-Raumfahrzeugs, ein Eintrag je abgetasteter Zeit. Nur Orbit-Paket; sonst weggelassen. Nur Ausgabe — nicht gehasht. report.rs
meta Objekt (StudyMeta), optional Additive Berichtsmetadaten (Studientitel, Erzeugungsstempel, Autor, Haftungsausschluss). Weggelassen, wenn nicht vorhanden, sodass ein Lauf ohne Metadaten byteidentisch zur alten Ausgabe ist. Nur Ausgabe — nicht gehasht. report.rs

ClockRun (jeweils quantum / classical)#

Schlüssel Typ / Einheit Bedeutung
spec.id Zeichenfolge Sensorkennung (z. B. optical-sr-lattice).
spec.kind Zeichenfolge Modellart (z. B. clock).
spec.provenance Zeichenfolge Zitat/Quelle für die Parameter des Sensors.
spec.params Objekt Die verwendeten rohen Modellparameter.
series Array aus {t, error_ns, gnss} Zeitreihe je Schritt: t Sekunden, error_ns der Zeitfehler in Nanosekunden, gnss eines von nominal/degraded/denied.
fom Objekt (FoMScores) Die bewerteten Gütemaße (unten).
adev_curve Array aus {tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi} Überlappende Allan-Abweichung: tau_s die Mittelungszeit (s), adev die dimensionslose relative Frequenzstabilität σ_y(τ), n_samples die Überlappungszahl hinter diesem Punkt, noise der aus der Steigung der MDEV (modifizierte Allan-Abweichung) erkannte Potenzgesetztyp (z. B. WhiteFm), edf die rauschtypspezifischen effektiven Freiheitsgrade und ci_lo/ci_hi das auf χ² beruhende 95-%-Konfidenzband auf adev bei diesem τ. Berechnet in allan.rs:overlapping_adev_curve.
filter_health Objekt, optional Bewertung der Kalman-Filter-Konsistenz (NIS/NEES (NIS: normiertes Innovationsquadrat; NEES: normiertes Schätzfehlerquadrat) gegen ihre χ²-Bänder), berechnet in filter_health.rs; weggelassen für Läufe, die sie nicht bewerten.

FoMScores (das Objekt fom)#

Feld Einheit Bedeutung Quelle Vorbehalt
timing_rms_ns ns RMS (quadratischer Mittelwert) des Uhrenphasenfehlers (Zeitfehlers) über den Ausfall. fom.rs:score eine Zeitgebungs-Metrik, keine Position
timing_p95_ns ns 95.-Perzentil des Zeitfehlers über den Ausfall. fom.rs:score
holdover_s s Ungünstigste (kürzeste) Überbrückung in Spezifikation über die Ausfallabschnitte. fom.rs:worst_case_holdover gitterbegrenzt — eine Untergrenze bei der Auflösung des Zeitschritts
resilience_slope_ns_per_s ns/s Wachstumsrate von |Fehler| nach kleinsten Quadraten während des Ausfalls. fom.rs:score
availability Anteil [0.1] Anteil des gesamten Laufs mit einer Lösung in Spezifikation. fom.rs:score
integrity Anteil [0.1] oder null Selbstkonsistenz des Filters: Anteil der Ausfallproben, deren wahrer Fehler innerhalb der Kalman-k-σ-Schranke bleibt. run.rs NICHT Integrität nach HPL/VPL/RAIM (HPL: horizontales Schutzniveau; VPL: vertikales Schutzniveau; RAIM: empfängerautonome Integritätsüberwachung) — siehe INTEGRITY.md
security Anteil [0.1] oder null Analytische Schranke der Spoof-Erkennbarkeit aus der Uhrenstabilität. run.rs + security.rs nur mit einem konfigurierten Angriff aussagekräftig, daher kennzeichnen die Pakete Uhr und Orbit (die keinen konfigurieren) sie in figure_tiers mit applicable: false und drucken sie in der Zusammenfassung als n/a (no attack); kein RAIM-Detektor mit mehreren Satelliten

Wie „gut“ aussieht#

  • Eine ruhigere Uhr (niedrigeres adev_curve) ergibt ein längeres holdover_s und eine höhere Schranke der Erkennbarkeit security — das ist der Kontrast zwischen Quanten und klassisch.
  • availability nahe 1,0 bedeutet, dass das System fast den ganzen Lauf in Spezifikation blieb; bei einem langen Ausfall fällt es für die rauschere Uhr ab.
  • integrity nahe 1,0 bedeutet, dass die eigene Unsicherheitsschranke des Filters ehrlich zu seinem Fehler war — eine Aussage zur Selbstkonsistenz, keine Garantie für Leib und Leben.

Andere Szenarioarten#

Jede andere Art gibt ihre eigene Ergebnisform aus. Einige der gängigen:

  • inertial: Gütemaße im Positionsbereich in Metern (pos_rms_m, pos_p95_m) — einachsig (1-DOF (DOF: Freiheitsgrad)), mit einem Seed (siehe CAPABILITY.md).
  • hybrid / fusion: timing_spec_ns und position_spec_m auf oberster Ebene und je Seite die Zeitgebungs- und Positionskennzahlen einer Sensor-Suite (position_p95_m, position_holdover_s und pnt_holdover_s, die Zeit, bis eine der beiden Spezifikationen verletzt wird), mit einem Block figure_tiers wie dem des Uhrenpakets, in dem die Positionskennzahlen als untiered aufgeführt sind.
  • spoof: Spoof-Versatz je Schritt gegenüber der Erkennungsschranke der Uhr, plus ob der Spoof die Spezifikation vor der Erkennung erreichte (src/spoof.rs).
  • Horizontprofil (orbit und integrity mit user_site, gnss-sim, jamming, leo-pvt, leo-pass; nur vorhanden, wenn das Szenario einen Abschnitt [skyline] hat, sodass ein Szenario ohne ihn unverändert ist): ein Objekt skyline auf oberster Ebene mit source (Zeichenkette: preset:<name>, preset:<name>+overrides oder custom), open_fraction (Anteil [0.1] des Raumwinkels der oberen Hemisphäre über max(mask_deg, skyline)) und provenance (Zeichenkette); je Probe masked_by_skyline (Zahl der Satelliten über der Maske, aber hinter dem Horizontprofil: epochs[] von integrity und jamming, gnss_measurements[] von gnss-sim, joint.epochs[] von leo-pvt); und für leo-pass satellites[].pass.epochs_masked_by_skyline (Zahl der Epochen). Ihre Einheiten und Herkunftsklassen stehen im Block units (src/skyline.rs UNITS; SKYLINE.md).

Den genauen Feldsatz einer Art finden Sie in deren Eintrag in field-units-schema.json (unten), im Abschnitt der Art in SCENARIOS.md oder in der entsprechenden *Result-Struktur in src/.

Weitere Dateien, die ein Lauf schreibt#

Neben <scenario>.result.json schreibt die CLI (Kommandozeilenschnittstelle) <scenario>.chart.svg, ein druckbares <scenario>.report.html und denselben Bericht als <scenario>.report.json, dessen reproducibility-Block die Engine-Version, den SHA-256 der Szenariodatei, den Seed, die Plattform und den genauen Befehl festhält (siehe REPORTS.md und REPRODUCIBILITY.md). Arten, die eine Reproduzierbarkeitstabelle veröffentlichen, schreiben außerdem <scenario>.table.csv (CSV: kommagetrennte Werte). --export schreibt Austauschdateien (siehe INTEROP.md) und --animate eine Animation (siehe ANIMATION.md).

Einheiten und Herkunft, je Feld, für jede Art#

Diese Seite ist von Hand geschrieben und deckt die Uhren- und Bahnpakete ab. Das maschinenlesbare Gegenstück deckt jede eingebaute Art ab:

  • Im Ergebnis selbst. Das Ergebnisdokument jedes Szenarios enthält ein units-Objekt auf oberster Ebene, das den Pfad eines ausgegebenen Feldes auf {"unit", "provenance", "note"} abbildet. Die Pfadgrammatik (ein Array trägt ein mit [] endendes Segment bei, das seine Zeilen gemeinsam nutzen; * ist ein Platzhalter für ein einzelnes Segment bei datenbasierten Objekten) und das geschlossene Vokabular der Herkunftsklassen sind in src/field_schema.rs definiert.
  • Als eine Datei. field-units-schema.json ist die zusammengeführte Vereinigung: für jede Art jedes numerische Feld, das sie an einer benannten Quelle ausgibt, mit Einheit, Herkunftsklasse, Evidenzstufe und Definition – und, benannt statt weggelassen, jedes Feld, das noch keine hat. Der coverage-Block enthält die Zählwerte.

Beides wird von tests/field_units_global.rs durchgesetzt, das jede registrierte Art ausführt und fehlschlägt, wenn einem ausgegebenen numerischen Feld eine Einheit oder eine Herkunftsklasse fehlt. Noch nicht abgedeckte Arten sind in UNCOVERED_KINDS dieser Datei einzeln mit dem Grund genannt, warum sie offen sind, und die Anzahl ist festgeschrieben, sodass die Liste nur kürzer werden kann.

Erzeugen Sie das JSON nach jeder Änderung an der Form eines Berichts oder an einem units-Block neu:

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