Relatórios de execução

Cada execução da interface de linha de comandos (CLI) escreve um relatório ao lado do seu resultado: uma página HyperText Markup Language (HTML) imprimível, <scenario>.report.html, e um documento JavaScript Object Notation (JSON) legível por máquina, <scenario>.report.json, com o mesmo conteúdo. O relatório funciona para qualquer tipo de cenário e para campanhas.

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

O documento de resultado responde a o que o motor calculou. O relatório acrescenta o que um leitor precisa antes de agir com base nele: o que entrou, em que assentam os números, o que ficou de fora, e como obter novamente os mesmos bytes. Não inventa nada disso. Cada secção é lida de uma fonte que o motor já mantém, e nomeia a fonte junto ao que cita.

O construtor é kshana::advanced_report (src/advanced_report.rs). É uma função pura da saída da execução, dos bytes do ficheiro de cenário e da linha de comandos: não lê nenhum relógio, nenhum ficheiro e nenhuma rede, e compila para WebAssembly.

Secções#

Uma secção sem nada para listar diz porquê numa frase (por exemplo, "No timed event: the scenario scripts no window or onset time and the result reports no event"). Nenhuma secção fica alguma vez vazia e muda.

O que significa uma etiqueta no relatório#

Uma etiqueta de verificação classifica a capacidade indicada numa linha da matriz, tal como a matriz a regista. Não classifica a configuração do cenário, e uma linha VALIDATED não torna medidas as entradas de uma execução. Uma linha PARTNER é uma disciplina em que a execução se apoia e que o Kshana não fornece (hardware de antena para os tipos de cenário de radiofrequência, a carga útil quântica para os tipos de cenário quânticos, a plataforma da nave para o orçamento de atitude); o relatório mostra-a como assumida, não fornecida.

A correspondência de tipo de cenário para linhas é uma tabela de cadeias requirement da matriz. A etiqueta, a referência independente e a evidência são lidas de novo da matriz quando o relatório é construído, pelo que mover uma linha entre VALIDATED e MODELLED move com ela todos os relatórios. Uma campanha traz a linha do seu modo (cadeia, varrimento ou Monte Carlo, composição) mais todas as linhas de todos os tipos de cenário membros que executou; sweep-nd traz as linhas do tipo de cenário que varreu. Cada execução traz também a linha "Reproducibility & software assurance", em que assenta o registo de reprodutibilidade.

Uma linha que classifica apenas um caminho de entrada de um tipo de cenário só é listada quando a execução seguiu esse caminho (advanced_report::PATH_GATED_CAPABILITIES): orbit e ephemeris trazem a linha "Orbit propagation & determination" apenas com um tle (o caminho Simplified General Perturbations 4 (SGP4); uma órbita analítica é uma propagação de dois corpos), e slot-timing traz a linha do registo medido apenas com um oscillator.record. A mesma tabela condiciona a linha multibanda de spectrum à execução que desenha [[panels]], e as linhas dos tipos de cenário de órbita terrestre baixa (LEO) ao caminho que cada execução seguiu: uma linha de chuva, entrada em edifícios, baixa energia ou spoofer de leo-pass ou leo-pnt-chain só quando o cenário define esse termo, a linha de cintilação a menos que o cenário a desligue, uma linha de leo-navmsg, leo-pvt ou de posicionamento de ponto preciso em cadeia só para a análise ou o modo que o resultado traz, e a linha de predefinição de sistema LEO só quando é usada uma predefinição com nome. A linha do leitor da Shuttle Radar Topography Mission (SRTM) não é trazida por nenhum tipo de cenário: terrain-nav e terrain-slam executam-se sobre um modelo digital de elevação (DEM) sintético, e nenhum campo de cenário lê um mosaico SRTM. Uma linha VALIDATED em que a execução nunca tocou reivindicaria, de outro modo, evidência que a execução não tem.

Reproduzir uma execução a partir do seu relatório#

report.json → reproducibility contém tudo o que é necessário:

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

1. Verifique o ficheiro de cenário face a scenario_sha256, e qualquer ficheiro em input_files (um ficheiro de orientação da Terra --eop) face ao seu resumo.
2. Execute command a partir do diretório em que a execução original foi iniciada. O caminho do cenário, e qualquer caminho de dados relativo dentro do cenário, são resolvidos a partir dele.
3. O novo result.json tem o SHA-256 de result_sha256, e o novo report.json e o novo report.html são idênticos ao byte aos antigos.

tests/advanced_report_cli.rs faz exatamente isto para um cenário de relógio, uma campanha encadeada, uma campanha de varrimento e uma execução de órbita com um ficheiro --eop: lê o comando do relatório, executa-o num diretório novo que contém apenas as entradas registadas, e compara bytes.

scenario_sha256 é o resumo dos bytes exatos do ficheiro. O scenario_hash do próprio resultado é outra coisa, a impressão digital do cenário feita pelo tipo de cenário (muitas vezes de uma forma canónica), e o relatório imprime ambos, etiquetados.

Semente. A semente é a seed do cenário, ou então a que o resultado indica. Para um tipo de cenário que não usa semente, o relatório di-lo, e diz que só o ficheiro de cenário e a compilação do motor fixam o resultado.

Commit de origem. O motor só regista o commit se tiver sido compilado com a variável de ambiente KSHANA_GIT_COMMIT definida, lida em tempo de compilação:

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

Uma compilação sem ela comunica o commit como não registado, e a versão do motor identifica a edição. Nada é adivinhado.

Plataforma. Sistema operativo, arquitetura e família da compilação. Os resultados são idênticos ao byte numa mesma plataforma; entre plataformas, os resultados de vírgula flutuante podem diferir nos últimos algarismos (ver REPRODUCIBILITY.md).

Determinismo e a única marca temporal#

O mesmo conjunto de bytes de cenário, semente e compilação do motor dá um report.json e um report.html idênticos ao byte. O relatório não traz nenhuma marca temporal. A única leitura de relógio em toda a crate é a que --study-name faz, que carimba meta.generated_utc no documento de resultado; o relatório mostra então esse carimbo e diz que é o único campo que uma reprodução não irá igualar. Para o evitar, execute sem --study-name. tests/advanced_report.rs constrói duas vezes o relatório de cada ficheiro de cenário em scenarios/ (exceto o manifesto da suite), e volta a executar seis cenários (entre eles uma campanha de cada um dos modos cadeia, varrimento e composição) para verificar isto de ponta a ponta.

Imprimir para PDF#

O motor não escreve ficheiros Portable Document Format (PDF). Um escritor de PDF que desenhasse os gráficos significaria uma dependência nova e pesada, pelo que não existe a opção --report pdf. Em vez disso, report.html traz uma folha de estilos de impressão: abra-o num navegador, imprima e escolha "Guardar como PDF".

A folha de estilos é escrita tanto para A4 como para US Letter. Não define nenhum tamanho de papel (aplica-se a escolha da caixa de diálogo de impressão), mantém margens de 15 mm / 14 mm que servem em qualquer das folhas, passa a preto sobre branco, repete os cabeçalhos das tabelas em todas as páginas, impede que linhas de tabela, figuras e cartões se dividam entre páginas, mantém os títulos com o texto que se segue, e inicia as secções de entradas, resultados, etiquetas de verificação e reprodutibilidade numa página nova. A barra de navegação fica oculta na impressão.

O documento JSON#

report.json tem report_schema = "kshana-report" e report_schema_version = "1.0", depois kind e title e uma chave por secção: executive_summary, inputs, results, aggregation (apenas campanhas e varrimentos), events, capabilities, not_modelled, companions (secção 3b: animation, exports e export_command) e reproducibility. Uma secção de lista tem items, omitted (as linhas que o limite da página deixou de fora; o documento de resultado traz todos os valores) e, quando items está vazio, uma statement que diz porquê. Um valor mantém a sua forma JSON em bruto em value e o texto que a página mostra em display; um valor em falta é null em value e "no value" em display.

Limites, indicados com clareza#

• Unidades. Quando nem o esquema de unidades de campo nem o nome do campo dão uma unidade, o relatório diz "not stated" em vez de adivinhar. As entradas aninhadas nos cenários membros de uma campanha são resolvidas apenas face ao bloco de unidades da própria campanha e ao sufixo do nome do campo, pelo que mais delas surgem como "not stated" do que numa execução autónoma.
• Juízo sobre a correspondência. As linhas da matriz que um tipo de cenário exercita são uma tabela curada, verificada por um teste para nomear exatamente uma linha existente por entrada e para cobrir todos os tipos de cenário incorporados. Se cada correspondência é a certa é um juízo humano, como a escolha da própria matriz quanto à referência independente.
• Limites. A página lista no máximo 400 entradas, 150 resultados escalares, 60 colunas numéricas e 200 eventos; omitted conta os restantes. Uma tabela com mais de 24 linhas dentro de um cenário (uma série ingerida) é resumida por coluna.
• Suites. kshana --study <suite.toml> mantém os seus próprios <suite>.study.json e <suite>.study.html; não escreve este relatório.
• Ligações. As ligações (bindings) de Python e WebAssembly mantêm RunOutput::html_report(), o painel de resultados de uma página; o relatório descarregável do espaço de experimentação é uma página própria (web/studio/lib/report.mjs). Este relatório é escrito pela CLI, e os chamadores em Rust podem construí-lo com kshana::advanced_report::build. O servidor Model Context Protocol (MCP) devolve-o a partir da sua ferramenta report_scenario, como JSON ou como página HTML; o nome do ficheiro de cenário no seu comando de reprodução é o que o chamador passa (predefinição scenario.toml), e não lista nenhum ficheiro acompanhante, porque o servidor não escreve nenhum.