Runrapporten

Elke run van de opdrachtregelinterface (CLI) schrijft naast zijn resultaat een rapport: een afdrukbare HyperText Markup Language (HTML)-pagina, <scenario>.report.html, en een machineleesbaar JavaScript Object Notation (JSON)-document, <scenario>.report.json, met dezelfde inhoud. Het rapport werkt voor elk scenariotype en voor campagnes.

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

Het resultaatdocument beantwoordt wat de engine heeft berekend. Het rapport voegt toe wat een lezer nodig heeft voordat hij erop handelt: wat erin ging, waarop de getallen berusten, wat is weggelaten en hoe dezelfde bytes opnieuw te verkrijgen zijn. Het verzint daarvan niets. Elke sectie wordt gelezen uit een bron die de engine al bijhoudt, en noemt de bron naast wat zij citeert.

De builder is kshana::advanced_report (src/advanced_report.rs). Het is een zuivere functie van de runuitvoer, de bytes van het scenariobestand en de opdrachtregel: hij leest geen klok, geen bestand en geen netwerk, en hij bouwt voor WebAssembly.

Secties#

#	Sectie	Wat het bevat	Gelezen uit
1	Managementsamenvatting	wat het soort doet, de samenvatting van de run in één regel, kerncijfers, het label voor eerlijkheid op runniveau, het aantal gebruikte capabilities VALIDATED / MODELLED / PARTNER	de catalogus van soorten (`kshana kinds --json`), het `label` van het resultaat, zijn `figure_tiers`-blok of blok met kwaliteitsmaten, de percentielen van een Monte Carlo-campagne
2	Invoer	elk veld dat het scenariobestand instelt, afgevlakt tot zijn pad, met zijn eenheid en waar de eenheid vandaan komt	het scenariobestand; eenheden uit het blok `units` van het resultaat (het eenhedenschema voor velden, `docs/field-units-schema.json`), anders het achtervoegsel van de veldnaam (`_s`, `_ns`, `_m`, `_deg`, `_dbw`, …); een eenheid die geen van beide vermeldt, wordt afgedrukt als niet opgegeven
3	Resultaten	de grafiek van de run, elke scalar van het resultaatdocument met zijn eenheid, en een samenvatting met aantal / minimum / maximum / eerste / laatste van elke numerieke kolom	het resultaatdocument en zijn `units`-blok
3a	Aggregatie (campagnes en sweeps)	de knooptabel van een sweep; het gemiddelde, de standaardafwijking, het 5e / 50e / 95e percentiel en het 95%-betrouwbaarheidsinterval op het gemiddelde van een Monte Carlo-run, met een histogram per maat; de fasetabel van een keten; de gedeelde voorwaarden, leden en gecombineerde samenvatting van een samenstelling	de sectie `sweep`, `monte_carlo`, `timeline` of `compose` van het campagneresultaat; het raster van een resultaat van `sweep` of `sweep-nd`
3b	Animatie en exports	de geanimeerde tekening van de run (de uitvoer van `--animate svg`), ingebed als inerte afbeelding, of waarom die er niet is; verwijzingen naar de animatie- en interoperabiliteitsbestanden die dezelfde opdracht naast het rapport schreef; elk exportformaat, met of het op het scenario van toepassing is, waarom niet, en zijn specificatie	de animatie-exporter (`src/animation.rs`), `interop::plan` en de bestanden die de opdrachtregel schreef (`--animate`, `--export`)
4	Gebeurtenistijdlijn	getimede vensters en puntgebeurtenissen, getekend en in een tabel gezet op de tijdas van de run	scenariotabellen met `t0`/`t1`, `on_s`/`off_s`, `start_s`/`end_s` of een begintijd; de runduur `time.duration_s`; elke `events`-array in het resultaat; de fasen en overdrachten van een campagne
5	Verificatielabels	elke rij van de verificatiematrix die de soorten van de run gebruiken, met haar label, onafhankelijke referentie en testbewijs, en de niveaus per kengetal die het resultaat vermeldt	de verificatiematrix (`src/verification.rs`, `docs/VERIFICATION-MATRIX.md`), via de kruisverwijzing van soort naar rij `advanced_report::KIND_CAPABILITIES`
6	Niet gemodelleerd, en aannames	elke beperking, geciteerd	de blokken `not_modelled`, `not_implemented` en `honesty` van het resultaat; de MODELLED-clausules van de soortencatalogus; scenario-opmerkingen en invoertekst die "not modelled" zeggen; de reden in de matrix waarom elke MODELLED-rij een model blijft (`docs/MODELLED-RATIONALE.md`)
7	Reproduceerbaarheidsverslag	engineversie, bron-commit, Secure Hash Algorithm 256-bit (SHA-256)-digests van het scenariobestand en van het resultaatdocument, seed, platform, de exacte opdracht, de regel voor de werkmap, de digest van elk verder invoerbestand	de build, de bestanden, de opdrachtregel

Een sectie zonder iets om op te sommen zegt in één zin waarom (bijvoorbeeld: "No timed event: the scenario scripts no window or onset time and the result reports no event"). Geen enkele sectie is ooit leeg en zwijgzaam.

Wat een label in het rapport betekent#

Een verificatielabel beoordeelt de capability die in een matrixrij wordt genoemd, zoals de matrix die vastlegt. Het beoordeelt niet de configuratie van het scenario, en een rij VALIDATED maakt de invoer van een run niet tot gemeten invoer. Een rij PARTNER is een discipline waarop de run steunt en die Kshana niet levert (antennehardware voor de radiofrequente soorten, de quantumpayload voor de quantumsoorten, de ruimtevaartuigbus voor het standhoudingsbudget); het rapport toont haar als waarop wordt gesteund, niet geleverd.

De kruisverwijzing van soort naar rijen is een tabel met requirement-strings van de matrix. Het label, de onafhankelijke referentie en het bewijs worden uit de matrix teruggelezen wanneer het rapport wordt gebouwd, dus wie een rij tussen VALIDATED en MODELLED verplaatst, verplaatst elk rapport mee. Een campagne draagt de rij voor haar modus (keten, sweep of Monte Carlo, samenstelling) plus elke rij van elke ledensoort die zij heeft uitgevoerd; sweep-nd draagt de rijen van de soort die zij heeft gesweept. Elke run draagt ook de rij "Reproducibility & software assurance", waarop het reproduceerbaarheidsverslag berust.

Een rij die slechts één invoerpad van een soort beoordeelt, wordt alleen vermeld wanneer de run dat pad nam (advanced_report::PATH_GATED_CAPABILITIES): orbit en ephemeris dragen de rij "Orbit propagation & determination" alleen met een tle (het pad Simplified General Perturbations 4 (SGP4); een analytische baan is een tweelichamenpropagatie), en slot-timing draagt de rij met het gemeten record alleen met een oscillator.record. Dezelfde tabel bepaalt ook de rij voor meerdere banden van spectrum naar gelang de run [[panels]] tekent, en de rijen van de soorten voor lage aardbanen (LEO) naar het pad dat elke run nam: een rij voor regen, gebouwpenetratie, laag vermogen of spoofer bij leo-pass of leo-pnt-chain alleen wanneer het scenario die term instelt, de scintillatierij tenzij het scenario die uitschakelt, een rij voor leo-navmsg, leo-pvt of precise point positioning in een keten alleen voor de analyse of modus die het resultaat draagt, en de rij voor het LEO-systeemvoorinstelling alleen wanneer een benoemde voorinstelling wordt gebruikt. De rij voor de Shuttle Radar Topography Mission (SRTM)-lezer wordt door geen enkele soort gedragen: terrain-nav en terrain-slam draaien op een synthetisch digitaal hoogtemodel (DEM), en geen enkel scenarioveld leest een SRTM-tegel. Een rij VALIDATED die de run nooit raakte, zou anders bewijs claimen dat de run niet heeft.

Een run reproduceren uit zijn rapport#

report.json → reproducibility bevat alles wat nodig is:

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

Controleer het scenariobestand aan scenario_sha256, en elk bestand in input_files (een Earth-orientation-bestand van --eop) aan zijn digest.
Voer command uit vanuit de map waarin de oorspronkelijke run is gestart. Het scenariopad, en elk relatief gegevenspad in het scenario, wordt daaraan gerelateerd.
Het nieuwe result.json heeft de SHA-256 uit result_sha256, en het nieuwe report.json en report.html zijn byte-identiek aan de oude.

tests/advanced_report_cli.rs doet precies dit voor een klokscenario, een gekoppelde campagne, een sweepcampagne en een baanrun met een --eop-bestand: de test leest de opdracht uit het rapport, voert die uit in een verse map met alleen de vastgelegde invoer, en vergelijkt bytes.

scenario_sha256 is de digest van de exacte bytes van het bestand. De eigen scenario_hash van het resultaat is iets anders, de vingerafdruk van het scenario door de soort (vaak van een canonieke vorm), en het rapport drukt beide af, met label.

Seed. De seed is de seed van het scenario, anders die welke het resultaat vermeldt. Voor een soort die geen seed neemt, zegt het rapport dat, en dat het scenariobestand en de enginebuild alleen het resultaat vastleggen.

Bron-commit. De engine legt de commit alleen vast als hij is gebouwd met de omgevingsvariabele KSHANA_GIT_COMMIT ingesteld, gelezen tijdens het compileren:

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

Een build zonder die variabele meldt de commit als niet vastgelegd, en de engineversie identificeert de release. Er wordt niets geraden.

Platform. Besturingssysteem, architectuur en familie van de build. Resultaten zijn byte-identiek op één platform; tussen platforms kunnen resultaten met drijvende komma in de laatste cijfers verschillen (zie REPRODUCIBILITY.md).

Determinisme en de ene tijdstempel#

Dezelfde scenariobytes, seed en enginebuild geven een byte-identiek report.json en report.html. Het rapport draagt geen tijdstempel. De enige klokaflezing in de hele crate is die welke --study-name maakt en die meta.generated_utc in het resultaatdocument stempelt; het rapport toont die stempel en zegt dat het het ene veld is dat een reproductie niet zal evenaren. Voer de run uit zonder --study-name om dit te vermijden. tests/advanced_report.rs bouwt tweemaal het rapport van elk scenariobestand onder scenarios/ (het suitemanifest daargelaten), en voert zes scenario's opnieuw uit (onder andere één campagne van elk van de modi keten, sweep en samenstelling) om dit van begin tot eind te controleren.

Afdrukken naar PDF#

De engine schrijft geen Portable Document Format (PDF)-bestanden. Een PDF-schrijver die de grafieken rendert zou een nieuwe, zware afhankelijkheid betekenen, dus er is geen optie --report pdf. In plaats daarvan bevat report.html een afdrukstijlblad: open het in een browser, druk af en kies "Opslaan als PDF".

Het stijlblad is geschreven voor zowel A4 als US Letter. Het stelt geen papierformaat in (de keuze van het afdrukdialoogvenster geldt), houdt marges van 15 mm / 14 mm aan die op beide vellen passen, schakelt over op zwart op wit, herhaalt tabelkoppen op elke pagina, voorkomt dat tabelrijen, figuren en kaarten over pagina's worden gesplitst, houdt koppen bij de tekst die volgt, en laat de secties met invoer, resultaten, verificatielabels en reproduceerbaarheid op een nieuwe pagina beginnen. De navigatiebalk is verborgen bij het afdrukken.

Het JSON-document#

report.json heeft report_schema = "kshana-report" en report_schema_version = "1.0", dan kind en title en één sleutel per sectie: executive_summary, inputs, results, aggregation (alleen campagnes en sweeps), events, capabilities, not_modelled, companions (sectie 3b: animation, exports en export_command) en reproducibility. Een lijstsectie heeft items, omitted (de rijen die de paginalimiet wegliet; het resultaatdocument bevat elke waarde) en, wanneer items leeg is, een statement die zegt waarom. Een waarde behoudt haar ruwe JSON-vorm in value en de tekst die de pagina toont in display; een ontbrekende waarde is null in value en "no value" in display.

Beperkingen, duidelijk vermeld#

Eenheden. Waar noch het eenhedenschema voor velden noch de veldnaam een eenheid geeft, zegt het rapport "not stated" in plaats van te raden. Invoer binnen de ledenscenario's van een campagne wordt alleen opgelost aan het eigen eenhedenblok van de campagne en het achtervoegsel van de veldnaam, zodat meer ervan "not stated" tonen dan in een op zichzelf staande run.
Oordeel over de kruisverwijzing. Welke matrixrijen een soort gebruikt is een samengestelde tabel, die een test controleert op precies één bestaande rij per item en op dekking van elke ingebouwde soort. Of elke toewijzing de juiste is, is een menselijk oordeel, zoals de keuze van de onafhankelijke referentie in de matrix zelf.
Limieten. De pagina vermeldt hoogstens 400 invoeren, 150 scalaire resultaten, 60 numerieke kolommen en 200 gebeurtenissen; omitted telt de rest. Een tabel van meer dan 24 rijen in een scenario (een ingelezen reeks) wordt per kolom samengevat.
Suites. kshana --study <suite.toml> houdt zijn eigen <suite>.study.json en <suite>.study.html; het schrijft dit rapport niet.
Bindings. De Python- en WebAssembly-bindings houden RunOutput::html_report() aan, de scorekaart van één pagina; het downloadbare rapport van de playground is zijn eigen pagina (web/studio/lib/report.mjs). Dit rapport wordt door de CLI geschreven, en Rust-aanroepers kunnen het bouwen met kshana::advanced_report::build. De Model Context Protocol (MCP)-server geeft het terug vanuit zijn tool report_scenario, als JSON of als HTML-pagina; de bestandsnaam van het scenario in zijn reproductieopdracht is die welke de aanroeper doorgeeft (standaard scenario.toml), en hij vermeldt geen begeleidend bestand, omdat de server er geen schrijft.