Ajoraportit

Jokainen komentorivin (CLI) ajo kirjoittaa tuloksensa viereen raportin: tulostettavan HyperText Markup Language (HTML) -sivun <scenario>.report.html ja koneluettavan JavaScript Object Notation (JSON) -asiakirjan <scenario>.report.json, joilla on sama sisältö. Raportti toimii mille tahansa skenaariotyypille ja kampanjoille.

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

Tulosasiakirja vastaa kysymykseen mitä moottori laski. Raportti lisää sen, mitä lukija tarvitsee ennen kuin toimii sen perusteella: mitä meni sisään, mihin luvut nojaavat, mitä jätettiin pois ja miten saman tavusisällön saa uudelleen. Se ei keksi mitään tästä. Jokainen osio luetaan lähteestä, jonka moottori jo säilyttää, ja nimeää lähteen siteeraamansa vierelle.

Rakentaja on kshana::advanced_report (src/advanced_report.rs). Se on puhdas funktio ajon tulosteesta, skenaariotiedoston tavuista ja komentoriviltä: se ei lue kelloa, tiedostoa eikä verkkoa, ja se rakentuu WebAssemblylle.

Osiot#

Osio, jossa ei ole mitään lueteltavaa, kertoo syyn yhdellä lauseella (esimerkiksi ”Ei ajoitettua tapahtumaa: skenaario ei määrittele ikkunaa tai alkamisaikaa, eikä tulos ilmoita tapahtumaa”). Yksikään osio ei ole koskaan tyhjä ja hiljainen.

Mitä raportin merkintä tarkoittaa#

Varmennusmerkintä arvioi matriisin rivillä nimetyn ominaisuuden sellaisena kuin matriisi sen kirjaa. Se ei arvioi skenaarion kokoonpanoa, eikä VALIDATED-rivi tee ajon syötteistä mitattuja. PARTNER-rivi on osa-alue, johon ajo luottaa ja jota Kshana ei tarjoa (antennilaitteisto radiotaajuustyypeille, kvanttikuorma kvanttityypeille, avaruusalusväylä asennonhallinnan budjetille); raportti esittää sen merkinnällä luotettu, ei tarjottu.

Vastaavuustaulukko tyypeistä riveihin on taulukko matriisin merkkijonoista requirement. Merkintä, oraakkeli ja todisteet luetaan takaisin matriisista raporttia rakennettaessa, joten rivin siirtäminen tasolta VALIDATED tasolle MODELLED siirtää mukanaan jokaisen raportin. Kampanja kantaa moodinsa rivin (ketju, pyyhkäisy tai Monte Carlo, koostaminen) sekä jokaisen ajamansa jäsentyypin kaikki rivit; sweep-nd kantaa pyyhkäisemänsä tyypin rivit. Jokaisessa ajossa on myös rivi ”Reproducibility & software assurance”, johon toistettavuustiedot perustuvat.

Rivi, joka arvioi vain yhtä tyypin syötepolkua, luetellaan vain, jos ajo kulki sitä polkua (advanced_report::PATH_GATED_CAPABILITIES): orbit ja ephemeris kantavat rivin ”Orbit propagation & determination” vain, kun mukana on tle (Simplified General Perturbations 4 (SGP4) -polku; analyyttinen rata on kahden kappaleen propagointi), ja slot-timing kantaa mitatun tallenteen rivin vain, kun mukana on oscillator.record. Sama taulukko rajaa monikaistarivin spectrum vain ajoihin, jotka piirtävät [[panels]], sekä matalan Maan kiertoradan (LEO) tyyppien rivit sen mukaan, minkä polun kukin ajo kulki: tyypin leo-pass tai leo-pnt-chain sade-, rakennukseen tulo-, matalaenergia- tai harhauttajarivi vain, kun skenaario asettaa kyseisen termin, tuikintarivi, ellei skenaario kytke sitä pois, tyypin leo-navmsg, leo-pvt tai ketjun tarkan pistepaikannuksen rivi vain tuloksen kantaman analyysin tai moodin osalta, ja LEO-järjestelmän esiasetusrivi vain, kun käytetään nimettyä esiasetusta. Shuttle Radar Topography Mission (SRTM) -lukijan rivi ei kuulu millekään tyypille: terrain-nav ja terrain-slam toimivat synteettisellä korkeusmallilla (DEM), eikä mikään skenaariokenttä lue SRTM-ruutua. VALIDATED-rivi, jota ajo ei koskaan käyttänyt, väittäisi muuten todisteita, joita ajolla ei ole.

Ajon toistaminen sen raportista#

report.json → reproducibility sisältää kaiken tarvittavan:

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

1. Tarkista skenaariotiedosto tiivistettä scenario_sha256 vasten ja jokainen kohdassa input_files oleva tiedosto (Maan orientaatiotiedosto --eop) oman tiivisteensä vasten.
2. Suorita command siitä hakemistosta, jossa alkuperäinen ajo käynnistettiin. Skenaarion polku ja kaikki skenaarion sisäiset suhteelliset datapolut ratkeavat sen suhteen.
3. Uuden tulostiedoston result.json SHA-256 vastaa kohdassa result_sha256 olevaa arvoa, ja uudet report.json ja report.html ovat tavu tavulta samat kuin vanhat.

tests/advanced_report_cli.rs tekee täsmälleen tämän kellon skenaariolle, ketjutetulle kampanjalle, pyyhkäisykampanjalle ja ratalaskennalle, jossa on tiedosto --eop: se lukee komennon raportista, ajaa sen tuoreessa hakemistossa, jossa on vain tallennetut syötteet, ja vertaa tavuja.

scenario_sha256 on tiedoston tarkkojen tavujen tiiviste. Tuloksen oma scenario_hash on eri asia: tyypin oma sormenjälki skenaariosta (usein sen kanonisesta muodosta), ja raportti tulostaa molemmat nimettyinä.

Siemenluku. Siemenluku on skenaarion arvo seed tai muuten se, jonka tulos ilmoittaa. Tyypille, joka ei käytä siemenlukua, raportti sanoo niin ja sen, että skenaariotiedosto ja moottorin käännös yksin määräävät tuloksen.

Lähdekoodin commit. Moottori tallentaa commitin vain, jos se on käännetty ympäristömuuttujan KSHANA_GIT_COMMIT ollessa asetettuna, luettuna käännösaikana:

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

Käännös ilman sitä ilmoittaa commitin tallentamattomaksi, ja moottorin versio tunnistaa julkaisun. Mitään ei arvata.

Alusta. Käännöksen käyttöjärjestelmä, arkkitehtuuri ja perhe. Tulokset ovat tavu tavulta samat yhdellä alustalla; alustojen välillä liukulukutulokset voivat poiketa viimeisissä numeroissa (katso REPRODUCIBILITY.md).

Determinismi ja ainoa aikaleima#

Samat skenaariotavut, siemenluku ja moottorin käännös tuottavat tavu tavulta saman tiedoston report.json ja report.html. Raportti ei sisällä aikaleimaa. Ainoa kellonluku koko paketissa (crate) on se, jonka tekee --study-name ja joka leimaa kentän meta.generated_utc tulosasiakirjaan; raportti näyttää sen leiman ja kertoo sen olevan ainoa kenttä, jota toisto ei vastaa. Sen välttämiseksi aja ilman --study-name. tests/advanced_report.rs rakentaa jokaisen hakemiston scenarios/ skenaariotiedoston raportin (sarjan manifestia lukuun ottamatta) kahdesti ja ajaa kuusi skenaariota uudelleen (niiden joukossa yksi kampanja kustakin ketju-, pyyhkäisy- ja koostamismoodista) tämän tarkistamiseksi päästä päähän.

Tulostus PDF-muotoon#

Moottori ei kirjoita Portable Document Format (PDF) -tiedostoja. PDF-kirjoittaja, joka piirtäisi kaaviot, toisi mukanaan uuden, raskaan riippuvuuden, joten vaihtoehtoa --report pdf ei ole. Sen sijaan report.html sisältää tulostustyylitiedoston: avaa se selaimessa, tulosta ja valitse ”Tallenna PDF-tiedostona”.

Tyylitiedosto on kirjoitettu sekä A4- että US Letter -koolle. Se ei aseta paperikokoa (tulostusikkunan valinta pätee), pitää 15 mm / 14 mm marginaalit, jotka sopivat kumpaankin arkkiin, vaihtaa mustaan valkoisella, toistaa taulukon otsikot joka sivulla, estää taulukon rivejä, kuvia ja kortteja katkeamasta sivujen välillä, pitää otsikot seuraavan tekstin kanssa ja aloittaa syötteiden, tulosten, varmennusmerkintöjen ja toistettavuuden osiot uudelta sivulta. Siirtymispalkki piilotetaan tulostuksessa.

JSON-asiakirja#

Tiedostossa report.json ovat report_schema = "kshana-report" ja report_schema_version = "1.0", sitten kind ja title sekä yksi avain kutakin osiota kohti: executive_summary, inputs, results, aggregation (vain kampanjat ja pyyhkäisyt), events, capabilities, not_modelled, companions (osio 3b: animation, exports ja export_command) ja reproducibility. Luetteloosiossa on items, omitted (rivit, jotka sivun yläraja jätti pois; tulosasiakirja sisältää kaikki arvot) ja, kun items on tyhjä, statement, joka kertoo syyn. Arvo säilyttää raa'an JSON-muotonsa kentässä value ja sivun näyttämän tekstin kentässä display; puuttuva arvo on null kentässä value ja ”no value” kentässä display.

Rajoitukset, ilmaistuna selvästi#

• Yksiköt. Kun kenttäyksikköskeema tai kentän nimi ei anna yksikköä, raportti sanoo ”not stated” eikä arvaa. Kampanjan jäsenskenaarioiden sisäiset syötteet ratkaistaan vain kampanjan oman yksikkölohkon ja kentän nimen päätteen perusteella, joten useammat niistä saavat arvon ”not stated” kuin erillisessä ajossa.
• Vastaavuustaulukon harkinta. Mitä matriisin rivejä tyyppi käyttää, on kuratoitu taulukko, jonka testi tarkistaa nimeävän täsmälleen yhden olemassa olevan rivin kutakin merkintää kohti ja kattavan jokaisen sisäänrakennetun tyypin. Se, onko kukin vastaavuus oikea, on ihmisen harkinta, kuten matriisin oma oraakkelin valinta.
• Ylärajat. Sivu luettelee enintään 400 syötettä, 150 skalaaritulosta, 60 numeerista saraketta ja 200 tapahtumaa; omitted laskee loput. Yli 24 rivin taulukko skenaarion sisällä (sisään luettu sarja) tiivistetään sarakkeittain.
• Suites. kshana --study <suite.toml> pitää yllä omia tiedostojaan <suite>.study.json ja <suite>.study.html; se ei kirjoita tätä raporttia.
• Sidokset. Python- ja WebAssembly-sidokset säilyttävät kohdan RunOutput::html_report(), yhden sivun tuloskortin; leikkikentän ladattava raportti on oma sivunsa (web/studio/lib/report.mjs). Tämän raportin kirjoittaa komentorivi, ja Rust-kutsujat voivat rakentaa sen kutsulla kshana::advanced_report::build. Model Context Protocol (MCP) -palvelin palauttaa sen työkalustaan report_scenario JSON-muodossa tai HTML-sivuna; skenaariotiedoston nimi sen toistokomennossa on se, jonka kutsuja antaa (oletus scenario.toml), eikä se luettele liitetiedostoa, koska palvelin ei kirjoita sellaista.