Kørselsrapporter

Hver kørsel af kommandolinjegrænsefladen (CLI) skriver en rapport ved siden af sit resultat: en udskrivbar HyperText Markup Language-side (HTML), <scenario>.report.html, og et maskinlæsbart JavaScript Object Notation-dokument (JSON), <scenario>.report.json, med det samme indhold. Rapporten virker for enhver scenarietype og for kampagner.

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 svarer på, hvad motoren beregnede. Rapporten tilføjer det, en læser har brug for, før der handles på det: hvad der gik ind, hvad tallene hviler på, hvad der blev udeladt, og hvordan man får de samme bytes igen. Den opfinder intet af det. Hvert afsnit læses fra en kilde, motoren allerede fører, og nævner kilden ved siden af det, den citerer.

Bygningen sker med kshana::advanced_report (src/advanced_report.rs). Det er en ren funktion af kørslens output, scenariefilens bytes og kommandolinjen: den læser intet ur, ingen fil og intet netværk, og den bygges til WebAssembly.

Afsnit#

En sektion uden noget at opregne angiver årsagen i én sætning (for eksempel "No timed event: the scenario scripts no window or onset time and the result reports no event"). Ingen sektion er nogensinde tom og tavs.

Hvad en mærkat i rapporten betyder#

En verifikationsmærkat bedømmer den funktion, der er nævnt i en matrixrække, sådan som matrixen registrerer den. Den bedømmer ikke scenariets konfiguration, og en VALIDATED-række gør ikke en kørsels input til målte data. En PARTNER-række er en disciplin, som kørslen bygger på, og som Kshana ikke leverer (antennehardware til radiofrekvenstyperne, den kvantemæssige nyttelast til kvantetyperne, rumfartøjets bus til attitudebudgettet); rapporten viser den som relied on, not provided.

Krydsreferencen fra type til rækker er en tabel af matrixens requirement-strenge. Mærkaten, den uafhængige reference og beviset læses tilbage fra matrixen, når rapporten bygges, så når en række flyttes mellem VALIDATED og MODELLED, flytter hver rapport med. En kampagne bærer rækken for sin tilstand (kæde, sweep eller Monte Carlo, sammensætning) samt hver række for hver medlemstype, den har kørt; sweep-nd bærer rækkerne for den type, den har sweepet. Hver kørsel bærer også rækken "Reproducibility & software assurance", som reproducerbarhedsoptegnelsen hviler på.

En række, der kun bedømmer én inputsti for en type, opregnes kun, når kørslen har fulgt den sti (advanced_report::PATH_GATED_CAPABILITIES): orbit og ephemeris bærer rækken "Orbit propagation & determination" kun med en tle (stien med Simplified General Perturbations 4 (SGP4); en analytisk bane er en to-legemers propagering), og slot-timing bærer rækken for målt optegnelse kun med en oscillator.record. Den samme tabel styrer rækken for flere bånd under spectrum efter, om kørslen tegner [[panels]], og rækkerne for typerne med lav jordbane (LEO) efter den sti, hver kørsel har fulgt: en række for regn, indtrængen i bygning, lav energi eller spoofer for leo-pass eller leo-pnt-chain kun når scenariet sætter det led, rækken for scintillation medmindre scenariet slår den fra, en række for leo-navmsg, leo-pvt eller kædens præcise punktpositionering kun for den analyse eller tilstand, resultatet bærer, og rækken for LEO-systemforudindstilling kun når en navngiven forudindstilling bruges. Læserrækken for Shuttle Radar Topography Mission (SRTM) bæres af ingen type: terrain-nav og terrain-slam kører på en syntetisk digital højdemodel (DEM), og intet scenariefelt læser en SRTM-flise. En VALIDATED-række, som kørslen aldrig har berørt, ville ellers hævde et belæg, som kørslen ikke har.

Gengivelse af en kørsel ud fra dens rapport#

report.json → reproducibility indeholder alt, hvad der skal bruges:

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

1. Kontrollér scenariefilen mod scenario_sha256 og enhver fil i input_files (en --eop-fil om jordens orientering) mod dens digest.
2. Kør command fra den mappe, som den oprindelige kørsel blev startet i. Scenariets sti og enhver relativ datasti i scenariet opløses i forhold til den.
3. Den nye result.json har den SHA-256, der står i result_sha256, og den nye report.json og report.html er byte-identiske med de gamle.

tests/advanced_report_cli.rs gør præcis dette for et urscenarie, en kædet kampagne, en sweep-kampagne og en banekørsel med en --eop-fil: den læser kommandoen ud af rapporten, kører den i en ny mappe med kun de registrerede input og sammenligner bytes.

scenario_sha256 er digest af filens præcise bytes. Resultatets eget scenario_hash er noget andet, nemlig typens fingeraftryk af scenariet (ofte af en kanonisk form), og rapporten udskriver begge med mærkater.

Seed. Seed er scenariets seed, ellers det, som resultatet angiver. For en type, der ikke tager noget seed, siger rapporten det, og at scenariefilen og motorbuildet alene fastlægger resultatet.

Kildecommit. Motoren registrerer kun commit, hvis den er bygget med miljøvariablen KSHANA_GIT_COMMIT sat, læst ved kompilering:

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

Et build uden den rapporterer commit som ikke registreret, og motorversionen identificerer udgivelsen. Intet gættes.

Platform. Buildets operativsystem, arkitektur og familie. Resultaterne er byte-identiske på én platform; på tværs af platforme kan flydende-komma-resultater afvige i de sidste cifre (se REPRODUCIBILITY.md).

Determinisme og det ene tidsstempel#

Samme scenariebytes, seed og motorbuild giver en byte-identisk report.json og report.html. Rapporten bærer intet tidsstempel. Den eneste urlæsning i hele cratet er den, som --study-name foretager, og som stempler meta.generated_utc ind i resultatdokumentet; rapporten viser derefter dette stempel og siger, at det er det ene felt, som en reproduktion ikke vil matche. For at undgå det køres uden --study-name. tests/advanced_report.rs bygger rapporten for hver scenariefil under scenarios/ (suitemanifestet undtaget) to gange og genkører seks scenarier (blandt dem én kampagne i hver af tilstandene kæde, sweep og sammensætning) for at kontrollere dette fra ende til anden.

Udskrivning til PDF#

Motoren skriver ikke Portable Document Format (PDF)-filer. En PDF-skriver, der gengiver diagrammerne, ville betyde en ny, tung afhængighed, så der er ingen --report pdf-indstilling. I stedet bærer report.html et udskriftsformatark: åbn den i en browser, udskriv, og vælg "Gem som PDF".

Formatarket er skrevet til både A4 og US Letter. Det fastsætter ingen papirstørrelse (udskriftsdialogens valg gælder), bruger marginer på 15 mm / 14 mm, som passer til begge ark, skifter til sort på hvid, gentager tabeloverskrifter på hver side, forhindrer, at tabelrækker, figurer og kort deles over flere sider, holder overskrifter sammen med den tekst, der følger, og starter sektionerne input, resultater, verifikationsmærkater og reproducerbarhed på en ny side. Navigationslinjen er skjult ved udskrift.

JSON-dokumentet#

report.json har report_schema = "kshana-report" og report_schema_version = "1.0", derefter kind og title og én nøgle for hver sektion: executive_summary, inputs, results, aggregation (kun kampagner og sweeps), events, capabilities, not_modelled, companions (afsnit 3b: animation, exports og export_command) og reproducibility. En listesektion har items, omitted (de rækker, som sidens loft udelod; resultatdokumentet bærer hver værdi) og, når items er tom, en statement, der siger hvorfor. En værdi beholder sin rå JSON-form i value og den tekst, siden viser, i display; en manglende værdi er null i value og "no value" i display.

Begrænsninger, åbent angivet#

• Enheder. Hvor hverken skemaet for feltenheder eller feltnavnet angiver en enhed, siger rapporten "not stated" i stedet for at gætte. Input, der er indlejret i en kampagnes medlemsscenarier, opløses kun mod kampagnens egen units-blok og feltnavnets endelse, så flere af dem lyder "not stated" end i en selvstændig kørsel.
• Skøn i krydsreferencen. Hvilke matrixrækker en type berører, er en kurateret tabel, som en test kontrollerer, så den nævner præcis én eksisterende række for hver post og dækker hver indbygget type. Om hver tilknytning er den rigtige, er et menneskeligt skøn, ligesom matrixens eget valg af uafhængig reference.
• Lofter. Siden opregner højst 400 input, 150 skalare resultater, 60 numeriske kolonner og 200 hændelser; omitted tæller resten. En tabel med mere end 24 rækker inde i et scenarie (en indlæst serie) opsummeres for hver kolonne.
• Suites. kshana --study <suite.toml> beholder sin egen <suite>.study.json og <suite>.study.html; den skriver ikke denne rapport.
• Bindinger. Python- og WebAssembly-bindingerne beholder RunOutput::html_report(), resultatkortet på én side; legepladsens rapport, der kan hentes, er en side for sig (web/studio/lib/report.mjs). Denne rapport skrives af CLI'en, og Rust-kaldere kan bygge den med kshana::advanced_report::build. Model Context Protocol (MCP)-serveren returnerer den fra sit værktøj report_scenario, som JSON eller som HTML-siden; scenariefilens navn i dens reproduktionskommando er det, kalderen angiver (standard scenario.toml), og den opregner ingen ledsagefil, da serveren ikke skriver nogen.