Körningsrapporter

Varje körning av kommandoradsgränssnittet (CLI) skriver en rapport bredvid sitt resultat: en utskrivbar HyperText Markup Language-sida (HTML), <scenario>.report.html, och ett maskinläsbart JavaScript Object Notation-dokument (JSON), <scenario>.report.json, med samma innehåll. Rapporten fungerar för alla scenariotyper och för kampanjer.

kshana scenarios/clock-holdover.toml
# wrote scenarios/clock-holdover.result.json, scenarios/clock-holdover.chart.svg,
#   scenarios/clock-holdover.report.html, and scenarios/clock-holdover.report.json

Resultatdokumentet svarar på vad motorn beräknade. Rapporten lägger till det en läsare behöver innan hen agerar på det: vad som gick in, vad siffrorna vilar på, vad som utelämnades och hur man får samma bytes igen. Den hittar inte på något av det. Varje avsnitt läses ur en källa som motorn redan håller, och namnger källan bredvid det den citerar.

Byggaren är kshana::advanced_report (src/advanced_report.rs). Den är en ren funktion av körningens utdata, scenariofilens bytes och kommandoraden: den läser ingen klocka, ingen fil och inget nätverk, och den bygger för WebAssembly.

Avsnitt#

Ett avsnitt utan något att lista anger skälet i en mening (till exempel "No timed event: the scenario scripts no window or onset time and the result reports no event"). Inget avsnitt är någonsin tomt och tyst.

Vad en etikett i rapporten betyder#

En verifieringsetikett graderar den förmåga som anges i en matrisrad, så som matrisen registrerar den. Den graderar inte scenariots konfiguration, och en VALIDATED-rad gör inte att en körnings indata blir uppmätta. En PARTNER-rad är en disciplin som körningen förlitar sig på och som Kshana inte tillhandahåller (antennhårdvara för radiofrekvenstyperna, kvantnyttolasten för kvanttyperna, satellitbussen för attitydbudgeten); rapporten visar den som förlitar sig på, tillhandahålls inte.

Korstabellen från typ till rader är en tabell med matrisens requirement-strängar. Etiketten, den oberoende referensen och beläggen läses tillbaka från matrisen när rapporten byggs, så när en rad flyttas mellan VALIDATED och MODELLED flyttas varje rapport med den. En kampanj bär raden för sitt läge (kedja, svep eller Monte Carlo, komposition) plus varje rad för varje medlemstyp den körde; sweep-nd bär raderna för den typ den svepte över. Varje körning bär också raden "Reproducibility & software assurance", som reproducerbarhetsuppgifterna vilar på.

En rad som bara graderar en indatasökväg för en typ listas endast när körningen tog den sökvägen (advanced_report::PATH_GATED_CAPABILITIES): orbit och ephemeris bär raden "Orbit propagation & determination" bara med en tle (sökvägen Simplified General Perturbations 4 (SGP4); en analytisk bana är en tvåkroppspropagering), och slot-timing bär raden för uppmätta register bara med en oscillator.record. Samma tabell styr raden för flera band i spectrum utifrån att körningen ritar [[panels]], och raderna för typerna för låg omloppsbana (LEO) utifrån vilken sökväg varje körning tog: en rad för regn, byggnadsinträde, låg energi eller spoofer för leo-pass eller leo-pnt-chain bara när scenariot sätter den termen, scintillationsraden om inte scenariot stänger av den, en rad för precise point positioning för leo-navmsg, leo-pvt eller kedja bara för den analys eller det läge som resultatet bär, och raden för LEO-systemförinställning bara när en namngiven förinställning används. Raden för Shuttle Radar Topography Mission (SRTM)-läsaren bärs av ingen typ: terrain-nav och terrain-slam körs på en syntetisk digital höjdmodell (DEM), och inget scenariofält läser en SRTM-ruta. En VALIDATED-rad som körningen aldrig berörde skulle annars göra anspråk på belägg som körningen inte har.

Reproducera en körning utifrån dess rapport#

report.json → reproducibility innehåller allt som behövs:

"command": "kshana clock-holdover.toml",
"argv": ["kshana", "clock-holdover.toml"],
"scenario_sha256": "430c364d…",
"result_sha256": "ee5ebb0a…",
"seed": 42,

1. Kontrollera scenariofilen mot scenario_sha256, och varje fil i input_files (en jordorienteringsfil av typen --eop) mot dess kontrollsumma.
2. Kör command från den katalog där den ursprungliga körningen startades. Scenariosökvägen, och varje relativ datasökväg i scenariot, löses upp mot den.
3. Den nya result.json har SHA-256 från result_sha256, och den nya report.json och report.html är byte för byte identiska med de gamla.

tests/advanced_report_cli.rs gör exakt detta för ett klockscenario, en kedjad kampanj, en svepkampanj och en banekörning med en --eop-fil: den läser kommandot ur rapporten, kör det i en ny katalog som bara innehåller de registrerade indatafilerna och jämför byte.

scenario_sha256 är kontrollsumman av filens exakta byte. Resultatets egen scenario_hash är något annat, typens fingeravtryck av scenariot (ofta av en kanonisk form), och rapporten skriver ut båda, med etiketter.

Frö. Fröet är scenariots seed, annars det som resultatet anger. För en typ som inte tar något frö säger rapporten det, och att enbart scenariofilen och motorbygget bestämmer resultatet.

Källkodscommit. Motorn registrerar commiten bara om den byggdes med miljövariabeln KSHANA_GIT_COMMIT satt, läst vid kompilering:

KSHANA_GIT_COMMIT=$(git rev-parse HEAD) cargo build --release

Ett bygge utan den rapporterar commiten som inte registrerad, och motorversionen identifierar utgåvan. Inget gissas.

Plattform. Operativsystem, arkitektur och familj för bygget. Resultaten är byte för byte identiska på en och samma plattform; mellan plattformar kan flyttalsresultat skilja sig i de sista siffrorna (se REPRODUCIBILITY.md).

Determinism och den enda tidsstämpeln#

Samma scenariobyte, frö och motorbygge ger en byte för byte identisk report.json och report.html. Rapporten bär ingen tidsstämpel. Den enda klockavläsningen i hela cratet är den som --study-name gör, och som stämplar meta.generated_utc i resultatdokumentet; rapporten visar sedan den stämpeln och anger att den är det enda fält som en reproduktion inte kommer att matcha. Undvik den genom att köra utan --study-name. tests/advanced_report.rs bygger rapporten för varje scenariofil under scenarios/ (utom sviten med manifest) två gånger, och kör om sex scenarier (bland dem en kampanj för vart och ett av lägena kedja, svep och komposition) för att kontrollera detta från början till slut.

Utskrift till PDF#

Motorn skriver inte Portable Document Format (PDF)-filer. En PDF-skrivare som ritar om diagrammen skulle innebära ett nytt, tungt beroende, så det finns inget alternativ --report pdf. Istället bär report.html en utskriftsstilmall: öppna den i en webbläsare, skriv ut och välj "Spara som PDF".

Stilmallen är skriven för både A4 och US Letter. Den anger ingen pappersstorlek (utskriftsdialogens val gäller), behåller marginaler på 15 mm / 14 mm som passar båda arken, byter till svart på vitt, upprepar tabellrubriker på varje sida, hindrar tabellrader, figurer och kort från att delas över sidor, håller ihop rubriker med den text som följer och startar avsnitten för indata, resultat, verifieringsetiketter och reproducerbarhet på en ny sida. Navigeringsfältet är dolt vid utskrift.

JSON-dokumentet#

report.json har report_schema = "kshana-report" och report_schema_version = "1.0", därefter kind och title samt en nyckel per avsnitt: executive_summary, inputs, results, aggregation (endast kampanjer och svep), events, capabilities, not_modelled, companions (avsnitt 3b: animation, exports och export_command) och reproducibility. Ett listavsnitt har items, omitted (de rader som sidgränsen lämnade utanför; resultatdokumentet bär varje värde) och, när items är tom, ett statement som anger varför. Ett värde behåller sin råa JSON-form i value och den text som sidan visar i display; ett saknat värde är null i value och "no value" i display.

Begränsningar, uttryckta rakt på sak#

• Enheter. Där varken schemat för fältenheter eller fältnamnet anger en enhet säger rapporten "not stated" istället för att gissa. Indata som ligger nästlade i en kampanjs medlemsscenarier löses upp enbart mot kampanjens eget enhetsblock och fältnamnets ändelse, så fler av dem står som "not stated" än i en fristående körning.
• Bedömning av korstabellen. Vilka matrisrader en typ utnyttjar är en kurerad tabell, som ett test kontrollerar anger exakt en befintlig rad per post och täcker varje inbyggd typ. Om varje koppling är den rätta är en mänsklig bedömning, liksom matrisens eget val av oberoende referens.
• Gränser. Sidan listar högst 400 indata, 150 skalära resultat, 60 numeriska kolumner och 200 händelser; omitted räknar resten. En tabell med fler än 24 rader i ett scenario (en inläst serie) sammanfattas per kolumn.
• Suites. kshana --study <suite.toml> behåller sin egen <suite>.study.json och <suite>.study.html; den skriver inte den här rapporten.
• Bindningar. Python- och WebAssembly-bindningarna behåller RunOutput::html_report(), resultatkortet på en sida; lekplatsens nedladdningsbara rapport är en egen sida (web/studio/lib/report.mjs). Den här rapporten skrivs av CLI:t, och Rust-anropare kan bygga den med kshana::advanced_report::build. Servern för Model Context Protocol (MCP) returnerar den från sitt verktyg report_scenario, som JSON eller som HTML-sida; scenariofilens namn i dess reproduktionskommando är det som anroparen anger (standard scenario.toml), och den listar ingen följefil, eftersom servern inte skriver någon.