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 — ler um *.result.json do Kshana

Cada execução escreve, junto ao cenário, um artefacto JSON (JavaScript Object Notation) versionado e autodescritivo. Esta página é o guia do leitor, escrito à mão, para o envelope de intercâmbio e para as formas de resultado de relógio e órbita: a unidade de cada campo, onde é calculado na origem e como o ler. O tipo canónico é RunResult em src/report.rs; as figuras de mérito são FoMScores em src/fom.rs.

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

Envelope de intercâmbio (KIF, o Kshana Interchange Format) — reconhecer e verificar a versão de um artefacto#

Os artefactos do Kshana podem ser envolvidos num envelope de intercâmbio neutro e autodescritivo, para que uma ferramenta de terceiros possa reconhecer o ficheiro e decidir se o consegue ler antes de se comprometer com um esquema de carga útil. O tipo canónico é Envelope em src/interchange.rs.

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

Contrato de compatibilidade. As versões são MAJOR.MINOR. Os novos campos são acrescentados com #[serde(default)] (a disciplina aditiva), pelo que um leitor consegue analisar qualquer artefacto da mesma versão principal e de uma secundária igual ou mais antiga (Compatible). Uma versão secundária estritamente mais recente (ForwardIncompatible) pode trazer campos que este leitor não consegue honrar, e uma versão principal diferente (MajorIncompatible) é uma rutura estrutural — ambas são recusadas por Envelope::parse, que valida a etiqueta de formato e a versão na fronteira em vez de analisar mal, em silêncio, uma entrada externa.

Determinismo. O envelope não traz nenhuma marca temporal — a promessa de reprodutibilidade do Kshana (scenario + seed + engine_version reproduz uma execução) exige-o. A proveniência está em engine_version e no scenario_hash da própria carga útil.

Uma leitura tipada (Envelope::payload_as::<T>()) funciona para qualquer carga útil que implemente Deserialize (por exemplo Scenario). Os artefactos de resultado são apenas de serialização por conceção e são lidos como o valor JSON em bruto de payload.

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

Chave Tipo / unidade Significado Fonte
schema_version cadeia de caracteres Versão do esquema de resultados (independente da versão do motor). report.rs
engine_version cadeia de caracteres Versão da crate (Cargo.toml) que produziu o ficheiro. report.rs
scenario_hash cadeia 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) para a 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 (ver abaixo). report.rs
classical objeto (ClockRun) A execução do sensor clássico, para comparação. report.rs
units objeto Mapa de unidade/proveniência por campo para este documento, indexado pelo caminho do campo. Ver §Unidades e proveniência abaixo. field_schema.rs:units_block
evidence objeto (0,40) A etiqueta 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 a 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 o 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 escrito à mão. 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 a ser 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 a mesma etiqueta (<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 nenhuma: o documento externo traz-a. Não contém números. evidence_label.rs
figure_tiers objeto O nível de verificação de cada figura de mérito comunicada, e sempre a última chave do documento. figures lista uma entrada por figura presente: path (por exemplo quantum.fom.timing_p95_ns), tier (VALIDATED = verificado face a uma referência independente externa, MODELLED = a partir 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 todos os cenários sem ataque configurado: o limite mantém-se 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 detém (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 da sua execução, e (0,36, RM-04) por todos os outros tipos de cenário para as 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 repõe-o ao documento sem níveis, byte a byte. Não é emitido por lunar-station-coverage, cujo resultado é uma previsão congelada e fixada antecipadamente (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 razão), nem pelos documentos membros incorporados numa 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 de erro de distância por satélite modelado), 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). Apenas no pacote de órbita. orbit.rs
eci_track matriz de [x, y, z] km, opcional Trajetória inercial centrada na Terra propagada da nave do utilizador, uma entrada por instante amostrado. Apenas no pacote de órbita; omitida nos restantes. Apenas de saída — não entra no 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, pelo que uma execução sem metadados é idêntica ao byte à saída anterior. Apenas de saída — não entra no hash. report.rs

ClockRun (cada um de quantum / classical)#

Chave Tipo / unidade Significado
spec.id cadeia de caracteres Identificador do sensor (por exemplo optical-sr-lattice).
spec.kind cadeia de caracteres Tipo de modelo (por exemplo clock).
spec.provenance cadeia de caracteres Citação/fonte dos parâmetros do sensor.
spec.params objeto Os parâmetros do modelo usados, em bruto.
series matriz de {t, error_ns, gnss} Série temporal por passo: t segundos, error_ns o erro de temporização 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 adimensional da frequência fracionária σ_y(τ), n_samples a contagem de sobreposição por trás desse ponto, noise o tipo de lei de potência identificado a partir da inclinação do MDEV (desvio de Allan modificado) (por exemplo WhiteFm), edf os graus de liberdade efetivos específicos do tipo de ruído, e ci_lo/ci_hi a banda de confiança de 95% baseada em χ² de adev nesse τ. Calculado em allan.rs:overlapping_adev_curve.
filter_health objeto, opcional Avaliação da consistência do filtro de Kalman (NIS/NEES (NIS: inovação normalizada ao quadrado; NEES: erro de estimação normalizado ao quadrado) face às suas bandas χ²), 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 (raiz do 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 do percentil 95 durante a interrupção. fom.rs:score
holdover_s s Pior caso (o mais curto) de trecho em inércia dentro da especificação entre os segmentos de interrupção. fom.rs:worst_case_holdover limitado pela grelha — um limite inferior à resolução do passo de tempo
resilience_slope_ns_per_s ns/s Taxa de crescimento por mínimos quadrados de |erro| 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 se mantém dentro do limite de k-σ de Kalman. run.rs NÃO é integridade HPL/VPL/RAIM (HPL: nível de proteção horizontal; VPL: nível de proteção vertical; RAIM: monitorização autónoma da integridade pelo recetor) — ver INTEGRITY.md
security fração [0 1] ou nulo Limite analítico de detetabilidade de spoofing a partir da estabilidade do relógio. run.rs + security.rs só tem significado com um ataque configurado, pelo 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 detetor RAIM de vários satélites

Como é o "bom"#

  • Um relógio mais silencioso (adev_curve mais baixo) dá um holdover_s mais longo e um limite de detetabilidade security mais alto — esse é o contraste quântico-versus-clássico.
  • availability próximo de 1,0 significa que o sistema se manteve dentro da especificação durante quase toda a execução; numa interrupção longa, desce 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#

Todos os outros tipos de cenário emitem a 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) — de eixo único (1-DOF (DOF: grau de liberdade)), de semente única (ver CAPABILITY.md).
  • hybrid / fusion: timing_spec_ns e position_spec_m ao nível superior, e por lado as figuras de temporização e de posição de um conjunto de sensores (position_p95_m, position_holdover_s e pnt_holdover_s, o tempo até uma das especificações ser violada), com um bloco figure_tiers como o do pacote de relógio, em que as figuras de posição constam como untiered.
  • spoof: desvio de spoofing por passo face ao limite de deteção do relógio, mais se o spoofing atingiu a especificação antes da deteçã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 secção [skyline], pelo que um cenário sem ela fica inalterado): um objeto skyline de nível superior com source (cadeia: 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 (cadeia); 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). As suas unidades e classes de proveniência estão no bloco units (src/skyline.rs UNITS; SKYLINE.md).

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

Outros ficheiros que uma execução escreve#

Junto a <scenario>.result.json, a CLI (interface de linha de comandos) escreve <scenario>.chart.svg, um <scenario>.report.html imprimível e o mesmo relatório como <scenario>.report.json, cujo bloco reproducibility regista a versão do motor, o SHA-256 do ficheiro de cenário, a semente, a plataforma e o comando exato (ver REPORTS.md e REPRODUCIBILITY.md). Os tipos de cenário que publicam uma tabela de reprodutibilidade escrevem também <scenario>.table.csv (CSV: valores separados por vírgulas). --export escreve ficheiros de troca (ver INTEROP.md) e --animate uma animação (ver ANIMATION.md).

Unidades e proveniência, por campo, para cada tipo de cenário#

Esta página é escrita à mão e abrange os pacotes de relógio e de órbita. A contraparte legível por máquina abrange todos os tipos de cenário incorporados:

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

Ambos são impostos por tests/field_units_global.rs, que executa todos os tipos de cenário registados e falha se um campo numérico emitido não tiver unidade e classe de proveniência. Os tipos de cenário ainda não cobertos são nomeados individualmente em UNCOVERED_KINDS desse ficheiro com a razão de cada um estar em aberto, e a contagem está fixada para que a lista só possa diminuir.

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

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