Tradução automática, não revista por um falante nativo. O inglês é a referência.

CenáriosEditar no GitHubFonte: docs/SCHEMA.md

Esquema de resultados — como ler um *.result.json do Kshana

Toda execução grava, ao lado do cenário, um artefato JSON (JavaScript Object Notation) versionado e autodescritivo. Esta página é o guia de leitura, escrito à mão, do envelope de intercâmbio e das formas de resultado de relógio e órbita: a unidade de cada campo, onde ele é calculado na fonte e como lê-lo. O tipo canônico é RunResult em src/report.rs; as figuras de mérito são FoMScores em src/fom.rs.

Esta não é a referência completa de campos. O motor despacha sobre muito mais tipos de cenário do que esses dois, e cada um emite seu próprio pacote. A referência completa — unidade, classe de procedência e definição de todo campo numérico de todo tipo de cenário incorporado — é gerada, não escrita à mão: veja Unidades e procedência, por campo, para todo tipo de cenário abaixo.

Envelope de intercâmbio (KIF, o Kshana Interchange Format) — reconhecimento e verificação de versão de um artefato#

Os artefatos do Kshana podem ser envolvidos em um envelope de intercâmbio neutro e autodescritivo, para que uma ferramenta de terceiros reconheça o arquivo e decida se consegue lê-lo antes de se comprometer com um esquema de carga útil. O tipo canônico é Envelope em src/interchange.rs.

Chave Tipo Significado
format string Sempre "kshana-interchange" (FORMAT_TAG) — como uma ferramenta externa reconhece um artefato do Kshana.
schema_version string A versão de esquema MAJOR.MINOR (SCHEMA_VERSION, a única fonte de verdade de todo o crate).
kind string O tipo de artefato, p. ex., "scenario", "run-result", "trade-study" — permite que um consumidor encaminhe sem analisar o corpo.
engine_version string Versão do crate (Cargo.toml) que produziu a carga útil.
payload objeto O artefato envolvido como JSON canônico (um Scenario, um RunResult, …).

Contrato de compatibilidade. As versões são MAJOR.MINOR. Novos campos são acrescentados com #[serde(default)] (a disciplina aditiva), de modo que um leitor pode analisar qualquer artefato da mesma versão maior e de versão menor igual ou mais antiga (Compatible). Uma versão menor estritamente mais nova (ForwardIncompatible) pode trazer campos que este leitor não consegue atender, e uma versão maior diferente (MajorIncompatible) é uma ruptura estrutural — ambas são recusadas por Envelope::parse, que valida a etiqueta de formato e a versão na fronteira, em vez de interpretar mal, em silêncio, uma entrada externa.

Determinismo. O envelope não traz carimbo de tempo — a promessa de reprodutibilidade do Kshana (scenario + seed + engine_version reproduz uma execução) exige isso. A procedência fica em engine_version e no próprio scenario_hash da carga útil.

Uma leitura tipada (Envelope::payload_as::<T>()) funciona para qualquer carga útil que implemente Deserialize (p. ex., Scenario). Os artefatos de resultado são apenas serializáveis por projeto e são lidos como o valor JSON bruto payload.

Nível superior (pacotes de relógio e órbita)#

Chave Tipo / unidade Significado Fonte
schema_version string Versão do esquema de resultados (independente da versão do motor). report.rs
engine_version string Versão do crate (Cargo.toml) que produziu o arquivo. report.rs
scenario_hash string hexadecimal SHA-256 (SHA: Secure Hash Algorithm) sobre o JSON canônico do cenário — a execução é reprodutível a partir de scenario + seed + engine_version. report.rs:hash_scenario
seed u64 Semente do RNG (gerador de números aleatórios) da execução quântica (a clássica usa seed + 0x9e3779b97f4a7c15). run.rs
threshold_ns nanossegundos A especificação de temporização: um erro dentro de ±threshold_ns está "dentro da especificação". cenário
quantum objeto (ClockRun) A execução do sensor quântico (veja abaixo). report.rs
classical objeto (ClockRun) A execução do sensor clássico, para comparação. report.rs
units objeto Mapa de unidade/procedência por campo deste documento, indexado pelo caminho do campo. Veja §Unidades e procedência abaixo. field_schema.rs:units_block
evidence objeto (0,40) O rótulo de evidência da execução: tier (VALIDATED, MODELLED ou PARTNER: o estado mais fraco entre as linhas, de modo que nunca afirma mais que sua linha mais fraca), matrix (docs/VERIFICATION-MATRIX.md), id_rule e rows, um por linha da matriz de verificação que a execução exercitou (as linhas que seu relatório avançado lista, a partir de advanced_report::KIND_CAPABILITIES): id (VM- e os primeiros 8 dígitos hexadecimais do SHA-256 do texto do requisito da linha), requirement e status, todos lidos da matriz, nenhum digitado. Acrescentado por api::run_toml ao resultado de todo tipo de cenário, antes do bloco figure_tiers final quando há um (esse bloco continua sendo a última chave); evidence_label::strip_json o remove byte a byte. O SVG do gráfico e a tabela CSV da mesma execução trazem o mesmo rótulo (<metadata id="kshana-evidence"> e uma linha visível sob o gráfico; linhas de comentário # evidence: na frente do CSV). Os membros de campanha embutidos no resultado de outro tipo de cenário não trazem nenhum: o documento externo o traz. Não contém números. evidence_label.rs
figure_tiers objeto O nível de verificação de cada figura de mérito informada, e sempre a última chave do documento. figures lista uma entrada por figura presente: path (p. ex., quantum.fom.timing_p95_ns), tier (VALIDATED = verificado em relação a uma referência independente externa, MODELLED = de primeiros princípios, testado internamente), requirement (a linha da matriz de verificação de onde o nível é lido) e applicable. applicable é false, com um reason, para security em todo cenário sem ataque configurado: o limite permanece em fom.security, mas não responde a uma pergunta que o cenário faça. untiered lista qualquer figura que nenhuma linha da matriz possui (as figuras de posição de hybrid e fusion), em vez de lhe dar um nível. Emitido pelos tipos de cenário clock (execução única e conjunto Monte Carlo), orbit, hybrid e fusion, que o constroem dentro de sua execução, e (0,36, RM-04) por todos os demais tipos de cenário para suas figuras principais, acrescentado após a execução a partir da tabela por tipo de cenário fom_label::kind_figures; api::without_figure_tiers o remove de volta ao documento sem níveis, byte a byte. Não emitido por lunar-station-coverage, cujo resultado é uma previsão pré-registrada congelada (docs/predictions/lunar-reference-station.md): esse tipo de cenário não tem figure_tiers até que uma nova previsão datada a substitua. Também não emitido por leo-ppp, solar-system, optical-atmosphere (0,37; matrizes por local), sweep e sweep-nd, que não têm figura principal escalar, nem por lunar-attack-surface, cujo documento é JSON compacto (fom_label::KINDS_EXCLUDED_FROM_FIGURE_TIERS dá cada motivo), nem pelos documentos de membros incorporados de uma campanha. Não traz números. fom_label.rs:figure_tiers, fom_label.rs:kind_figure_tiers
geometry objeto, opcional Resumo de geometria do pacote de órbita: samples_total, samples_with_fix, sigma_uere_m (m, o orçamento modelado de erro de distância por satélite), best_pdop / median_pdop (adimensionais) e best_position_sigma_m / median_position_sigma_m (m, PDOP (diluição da precisão de posição) × sigma_uere_m). Somente no pacote de órbita. orbit.rs
eci_track matriz de [x, y, z] km, opcional Trajetória inercial centrada na Terra propagada da espaçonave do usuário, uma entrada por instante amostrado. Somente no pacote de órbita; omitida nos demais. Apenas de saída — sem hash. report.rs
meta objeto (StudyMeta), opcional Metadados aditivos do relatório (título do estudo, carimbo de geração, autor, aviso legal). Omitidos quando ausentes, de modo que uma execução sem metadados é idêntica byte a byte à saída legada. Apenas de saída — sem hash. report.rs

ClockRun (cada um de quantum / classical)#

Chave Tipo / unidade Significado
spec.id string Identificador do sensor (p. ex., optical-sr-lattice).
spec.kind string Tipo de modelo (p. ex., clock).
spec.provenance string Citação/fonte dos parâmetros do sensor.
spec.params objeto Os parâmetros brutos do modelo usados.
series matriz de {t, error_ns, gnss} Série temporal por passo: t segundos, error_ns o erro de tempo em nanossegundos, gnss um de nominal/degraded/denied.
fom objeto (FoMScores) As figuras de mérito pontuadas (abaixo).
adev_curve matriz de {tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi} Desvio de Allan sobreposto: tau_s o tempo de média (s), adev a estabilidade fracionária de frequência adimensional σ_y(τ), n_samples a contagem de sobreposição por trás desse ponto, noise o tipo de lei de potência identificado pela inclinação do MDEV (desvio de Allan modificado) (p. ex., WhiteFm), edf os graus de liberdade efetivos específicos do tipo de ruído, e ci_lo/ci_hi a faixa de confiança de 95% baseada em χ² sobre adev naquele τ. Calculado em allan.rs:overlapping_adev_curve.
filter_health objeto, opcional Avaliação de consistência do filtro de Kalman (NIS/NEES (NIS: inovação normalizada ao quadrado; NEES: erro de estimação normalizado ao quadrado) contra suas faixas χ²), calculada em filter_health.rs; omitida nas execuções que não a avaliam.

FoMScores (o objeto fom)#

Campo Unidade Significado Fonte Ressalva
timing_rms_ns ns Erro RMS (valor quadrático médio) de fase do relógio (temporização) durante a interrupção. fom.rs:score uma métrica de temporização, não de posição
timing_p95_ns ns Erro de temporização no percentil 95 durante a interrupção. fom.rs:score
holdover_s s Pior caso (o mais curto) de trecho por inércia dentro da especificação entre os segmentos de interrupção. fom.rs:worst_case_holdover limitado pela grade — um limite inferior na resolução do passo de tempo
resilience_slope_ns_per_s ns/s Taxa de crescimento de |erro| por mínimos quadrados durante a interrupção. fom.rs:score
availability fração [0.1] Fração da execução inteira com uma solução dentro da especificação. fom.rs:score
integrity fração [0.1] ou nulo Autoconsistência do filtro: fração das amostras da interrupção cujo erro verdadeiro permanece dentro do limite k-σ do Kalman. run.rs NÃO é integridade HPL/VPL/RAIM (HPL: nível de proteção horizontal; VPL: nível de proteção vertical; RAIM: monitoramento de integridade autônomo pelo receptor) — veja INTEGRITY.md
security fração [0.1] ou nulo Limite analítico de detectabilidade de spoofing a partir da estabilidade do relógio. run.rs + security.rs significativo apenas com um ataque configurado, de modo que os pacotes de relógio e de órbita (que não configuram nenhum) o marcam como applicable: false em figure_tiers e o imprimem como n/a (no attack) no resumo; não é um detector RAIM de vários satélites

Como é um valor "bom"#

  • Um relógio mais silencioso (adev_curve menor) dá um holdover_s mais longo e um limite de detectabilidade security maior — esse é o contraste quântico versus clássico.
  • availability próximo de 1,0 significa que o sistema ficou dentro da especificação quase toda a execução; durante uma interrupção longa, cai para o relógio mais ruidoso.
  • integrity próximo de 1,0 significa que o limite de incerteza do próprio filtro foi honesto quanto ao seu erro — uma afirmação de autoconsistência, não uma garantia de segurança da vida humana.

Outros tipos de cenário#

Todo outro tipo de cenário emite sua própria forma de resultado. Alguns dos mais comuns:

  • inertial: figuras de mérito no domínio da posição em metros (pos_rms_m, pos_p95_m) — eixo único (1-DOF (DOF: grau de liberdade)), semente única (veja CAPABILITY.md).
  • hybrid / fusion: timing_spec_ns e position_spec_m no nível superior e, por lado, as figuras de temporização e de posição de uma suíte de sensores (position_p95_m, position_holdover_s e pnt_holdover_s, o tempo até que qualquer das especificações seja violada), com um bloco figure_tiers como o do pacote de relógio, em que as figuras de posição são listadas como untiered.
  • spoof: deslocamento de spoofing por passo contra o limite de detecção do relógio, mais se o spoofing atingiu a especificação antes da detecção (src/spoof.rs).
  • skyline (orbit e integrity com user_site, gnss-sim, jamming, leo-pvt, leo-pass; presente apenas quando o cenário tem uma seção [skyline], de modo que um cenário sem ela permanece inalterado): um objeto skyline de nível superior com source (string: preset:<name>, preset:<name>+overrides ou custom), open_fraction (fração [0.1] do ângulo sólido do hemisfério superior acima de max(mask_deg, skyline)) e provenance (string); por amostra masked_by_skyline (contagem de satélites acima da máscara mas atrás da linha de horizonte: epochs[] de integrity e jamming, gnss_measurements[] de gnss-sim, joint.epochs[] de leo-pvt); e, para leo-pass, satellites[].pass.epochs_masked_by_skyline (contagem de épocas). Suas unidades e classes de procedência estão no bloco units (src/skyline.rs UNITS; SKYLINE.md).

Para o conjunto preciso de campos de qualquer tipo de cenário, leia sua entrada em field-units-schema.json (abaixo), a seção do tipo de cenário em SCENARIOS.md ou a struct *Result correspondente em src/.

Outros arquivos que uma execução grava#

Além de <scenario>.result.json, a CLI (interface de linha de comando) grava <scenario>.chart.svg, um <scenario>.report.html imprimível e o mesmo relatório como <scenario>.report.json, cujo bloco reproducibility registra a versão do motor, o SHA-256 do arquivo de cenário, a semente, a plataforma e o comando exato (veja REPORTS.md e REPRODUCIBILITY.md). Os tipos de cenário que publicam uma tabela de reprodutibilidade também gravam <scenario>.table.csv (CSV: valores separados por vírgula). --export grava arquivos de intercâmbio (veja INTEROP.md) e --animate uma animação (veja ANIMATION.md).

Unidades e procedência, por campo, para todo tipo de cenário#

Esta página é escrita à mão e cobre os pacotes de relógio e de órbita. A contrapartida legível por máquina cobre todo tipo de cenário incorporado:

  • No próprio resultado. O documento de resultado de cada cenário traz um objeto units de nível superior que mapeia o caminho de um campo emitido para {"unit", "provenance", "note"}. A gramática de caminhos (uma matriz contribui com um segmento com sufixo [] compartilhado por suas linhas; * é um curinga de um único segmento para objetos indexados por dados) e o vocabulário fechado de procedência estão definidos em src/field_schema.rs.
  • Como um único arquivo. field-units-schema.json é a união colhida: para cada tipo de cenário, todo campo numérico que ele emite em uma fonte declarada, com sua unidade, classe de procedência, nível de evidência e definição — e, nomeado em vez de omitido, todo campo que ainda não tem uma. Seu bloco coverage traz as contagens.

Ambos são impostos por tests/field_units_global.rs, que executa todo tipo de cenário registrado e falha se um campo numérico emitido não tem unidade e classe de procedência. Os tipos de cenário ainda não cobertos são nomeados individualmente em UNCOVERED_KINDS desse arquivo, com o motivo de cada um estar em aberto, e a contagem é fixada para que a lista só possa diminuir.

Regenere o JSON após qualquer alteração na forma de um relatório ou em um bloco units:

cargo test --test field_units_global zzz_emit_field_units_schema -- --ignored