Raporty z przebiegów

Każdy przebieg interfejsu wiersza poleceń (CLI) zapisuje obok wyniku raport: drukowalną stronę HyperText Markup Language (HTML), <scenario>.report.html, oraz czytelny maszynowo dokument JavaScript Object Notation (JSON), <scenario>.report.json, o tej samej treści. Raport działa dla każdego rodzaju scenariusza i dla kampanii.

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

Dokument wynikowy odpowiada na pytanie, co obliczył silnik. Raport dodaje to, czego czytelnik potrzebuje, zanim na tej podstawie zadziała: co wprowadzono, na czym opierają się liczby, co pominięto i jak uzyskać te same bajty ponownie. Niczego z tego nie wymyśla. Każda sekcja jest odczytywana ze źródła, które silnik już przechowuje, i podaje to źródło obok cytowanej treści.

Konstruktorem jest kshana::advanced_report (src/advanced_report.rs). Jest to czysta funkcja wyniku przebiegu, bajtów pliku scenariusza i wiersza poleceń: nie odczytuje zegara, pliku ani sieci i buduje się dla WebAssembly.

Sekcje#

Sekcja, w której nie ma nic do wymienienia, mówi dlaczego, jednym zdaniem (na przykład „No timed event: the scenario scripts no window or onset time and the result reports no event”). Żadna sekcja nigdy nie jest pusta i milcząca.

Co oznacza etykieta w raporcie#

Etykieta weryfikacji ocenia możliwość nazwaną w wierszu macierzy, tak jak zapisuje ją macierz. Nie ocenia konfiguracji scenariusza, a wiersz VALIDATED nie sprawia, że dane wejściowe przebiegu są zmierzone. Wiersz PARTNER to dyscyplina, na której przebieg polega, a której Kshana nie zapewnia (sprzęt antenowy dla rodzajów radiowych, ładunek kwantowy dla rodzajów kwantowych, magistrala statku kosmicznego dla budżetu orientacji); raport pokazuje ją jako wymaganą, lecz niezapewnianą.

Powiązanie rodzajów z wierszami jest tabelą ciągów requirement macierzy. Etykieta, wyrocznia i dowód są odczytywane z macierzy w chwili budowania raportu, więc przeniesienie wiersza między VALIDATED a MODELLED przenosi razem z nim każdy raport. Kampania niesie wiersz swojego trybu (łańcuch, przegląd lub Monte Carlo, kompozycja) oraz każdy wiersz każdego uruchomionego rodzaju składowego; sweep-nd niesie wiersze rodzaju, który przeglądał. Każdy przebieg niesie też wiersz „Reproducibility & software assurance”, na którym opiera się zapis odtwarzalności.

Wiersz oceniający tylko jedną ścieżkę wejściową rodzaju jest wymieniany tylko wtedy, gdy przebieg poszedł tą ścieżką (advanced_report::PATH_GATED_CAPABILITIES): orbit i ephemeris niosą wiersz „Orbit propagation & determination” tylko z blokiem tle (ścieżka Simplified General Perturbations 4 (SGP4); orbita analityczna to propagacja dwóch ciał), a slot-timing niesie wiersz zapisu pomiarowego tylko z oscillator.record. Ta sama tabela bramkuje wiersz wielopasmowy spectrum według tego, czy przebieg rysuje [[panels]], oraz wiersze rodzajów niskiej orbity okołoziemskiej (LEO) według ścieżki, którą poszedł każdy przebieg: wiersz deszczu, wejścia do budynku, niskiej energii lub spoofera dla leo-pass albo leo-pnt-chain tylko wtedy, gdy scenariusz ustawia ten człon, wiersz scyntylacji, chyba że scenariusz go wyłącza, wiersz leo-navmsg, leo-pvt lub łańcuchowego precyzyjnego pozycjonowania punktowego tylko dla analizy lub trybu, który niesie wynik, oraz wiersz gotowej konfiguracji systemu LEO tylko wtedy, gdy użyto nazwanej konfiguracji. Wiersz czytnika Shuttle Radar Topography Mission (SRTM) nie jest niesiony przez żaden rodzaj: terrain-nav i terrain-slam działają na syntetycznym cyfrowym modelu wysokościowym terenu (DEM), a żadne pole scenariusza nie odczytuje kafla SRTM. Wiersz VALIDATED, którego przebieg nigdy nie dotknął, rościłby sobie w przeciwnym razie dowody, których przebieg nie ma.

Odtworzenie przebiegu z jego raportu#

report.json → reproducibility zawiera wszystko, co jest potrzebne:

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

1. Należy sprawdzić plik scenariusza względem scenario_sha256 oraz każdy plik w input_files (plik orientacji Ziemi --eop) względem jego skrótu.
2. Należy uruchomić command z katalogu, w którym rozpoczęto pierwotny przebieg. Ścieżka scenariusza i każda względna ścieżka danych wewnątrz scenariusza są rozwiązywane względem niego.
3. Nowy result.json ma SHA-256 z result_sha256, a nowe report.json i report.html są identyczne co do bajta ze starymi.

tests/advanced_report_cli.rs robi dokładnie to dla scenariusza zegara, kampanii łańcuchowej, kampanii przeglądu i przebiegu orbity z plikiem --eop: odczytuje polecenie z raportu, uruchamia je w nowym katalogu zawierającym tylko zapisane wejścia i porównuje bajty.

scenario_sha256 to skrót dokładnych bajtów pliku. Własne scenario_hash wyniku jest czymś innym, odciskiem scenariusza ustalanym przez rodzaj (często z postaci kanonicznej), a raport wypisuje oba z etykietami.

Ziarno. Ziarnem jest seed scenariusza, a w przeciwnym razie to, które podaje wynik. Dla rodzaju, który nie przyjmuje ziarna, raport mówi o tym oraz że wynik ustalają wyłącznie plik scenariusza i kompilacja silnika.

Commit źródłowy. Silnik zapisuje commit tylko wtedy, gdy został zbudowany z ustawioną zmienną środowiskową KSHANA_GIT_COMMIT, odczytywaną w czasie kompilacji:

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

Kompilacja bez niej podaje commit jako niezapisany, a wersja silnika identyfikuje wydanie. Nic nie jest zgadywane.

Platforma. System operacyjny, architektura i rodzina kompilacji. Wyniki są identyczne co do bajta na jednej platformie; między platformami wyniki zmiennoprzecinkowe mogą się różnić na ostatnich cyfrach (zob. REPRODUCIBILITY.md).

Determinizm i jeden znacznik czasu#

Te same bajty scenariusza, to samo ziarno i ta sama kompilacja silnika dają identyczne co do bajta report.json i report.html. Raport nie zawiera znacznika czasu. Jedyny odczyt zegara w całym pakiecie robi --study-name, który wstawia meta.generated_utc do dokumentu wynikowego; raport pokazuje wtedy ten znacznik i mówi, że jest to jedyne pole, którego odtworzenie nie powtórzy. Aby tego uniknąć, należy uruchomić bez --study-name. tests/advanced_report.rs buduje raport każdego pliku scenariusza w scenarios/ (poza manifestem zestawu) dwukrotnie i ponownie uruchamia sześć scenariuszy (wśród nich po jednej kampanii w trybie łańcucha, przeglądu i kompozycji), aby sprawdzić to od końca do końca.

Drukowanie do PDF#

Silnik nie zapisuje plików Portable Document Format (PDF). Zapisywanie PDF z renderowanymi wykresami oznaczałoby nową, ciężką zależność, więc nie ma opcji --report pdf. Zamiast tego report.html zawiera arkusz stylów do druku: należy otworzyć go w przeglądarce, wydrukować i wybrać „Zapisz jako PDF”.

Arkusz stylów jest napisany zarówno dla A4, jak i US Letter. Nie ustawia rozmiaru papieru (obowiązuje wybór z okna druku), zachowuje marginesy 15 mm / 14 mm pasujące do obu arkuszy, przełącza na czerń na bieli, powtarza nagłówki tabel na każdej stronie, nie dzieli wierszy tabel, rysunków i kart między strony, trzyma nagłówki z tekstem, który po nich następuje, i zaczyna sekcje wejść, wyników, etykiet weryfikacji i odtwarzalności od nowej strony. Pasek nawigacji jest ukryty w druku.

Dokument JSON#

report.json ma report_schema = "kshana-report" i report_schema_version = "1.0", następnie kind i title oraz po jednym kluczu na sekcję: executive_summary, inputs, results, aggregation (tylko kampanie i przeglądy), events, capabilities, not_modelled, companions (sekcja 3b: animation, exports i export_command) oraz reproducibility. Sekcja listowa ma items, omitted (wiersze, które pominął limit strony; dokument wynikowy zawiera każdą wartość) i, gdy items jest puste, statement mówiące dlaczego. Wartość zachowuje swoją surową postać JSON w value, a tekst pokazywany na stronie w display; brakująca wartość to null w value i „no value” w display.

Ograniczenia, podane wprost#

• Jednostki. Gdy ani schemat jednostek pól, ani nazwa pola nie podaje jednostki, raport mówi „not stated” zamiast zgadywać. Wejścia zagnieżdżone w scenariuszach składowych kampanii są rozwiązywane wyłącznie względem własnego bloku jednostek kampanii i przyrostka nazwy pola, więc więcej z nich odczytuje się jako „not stated” niż w przebiegu samodzielnym.
• Ocena powiązania. To, które wiersze macierzy wykorzystuje dany rodzaj, jest kuratorowaną tabelą, sprawdzaną testem pod kątem tego, że każdy wpis wskazuje dokładnie jeden istniejący wiersz i że pokryty jest każdy wbudowany rodzaj. To, czy każde odwzorowanie jest właściwe, jest oceną człowieka, tak jak sam wybór wyroczni w macierzy.
• Limity. Strona wymienia co najwyżej 400 wejść, 150 wyników skalarnych, 60 kolumn liczbowych i 200 zdarzeń; omitted zlicza resztę. Tabela z więcej niż 24 wierszami wewnątrz scenariusza (wczytany szereg) jest podsumowywana dla każdej kolumny.
• Suites. kshana --study <suite.toml> zachowuje własne <suite>.study.json i <suite>.study.html; nie zapisuje tego raportu.
• Powiązania. Powiązania Pythona i WebAssembly zachowują RunOutput::html_report(), jednostronicową kartę wyników; pobieralny raport placu zabaw to jego własna strona (web/studio/lib/report.mjs). Ten raport jest zapisywany przez CLI, a wywołujący z Rusta mogą go zbudować za pomocą kshana::advanced_report::build. Serwer Model Context Protocol (MCP) zwraca go ze swojego narzędzia report_scenario, jako JSON albo stronę HTML; nazwa pliku scenariusza w jego poleceniu odtworzenia to ta, którą poda wywołujący (domyślnie scenario.toml), i nie wymienia on żadnego pliku towarzyszącego, ponieważ serwer żadnego nie zapisuje.