Tutoriais

Exemplos práticos que o levam de “executar um cenário fornecido” a “quantificar e defender um resultado”. Cada número citado nos três tutoriais é uma saída real do motor, ancorada numa referência independente externa (não circular) de autoridade reconhecida, e fixado por um teste de integração (tests/tutorials.rs), pelo que um tutorial nunca pode afastar-se silenciosamente do que o motor realmente faz. Se um tutorial disser que o relógio ótico aguenta 6600 s, o teste faz falhar a compilação no dia em que isso deixar de ser verdade.

O Kshana é um simulador de posicionamento, navegação e temporização (PNT). Os tutoriais usam mais algumas abreviaturas, cada uma por extenso onde aparece pela primeira vez: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (command-line interface) e TOML (Tom's Obvious Minimal Language, o formato dos ficheiros de cenário).

É novo no projeto? Leia primeiro o guia de conceitos e o glossário e depois volte aqui.

Os três exemplos práticos#

Cadernos interativos#

Os notebooks Jupyter executáveis, sobre dados sintéticos e conjuntos de elementos públicos mantidos apenas no repositório, estão em notebooks/:

Como executar um tutorial#

Todos os tutoriais executam o mesmo cenário de três formas; escolha a que lhe convier. Todas chamam o mesmo motor, pelo que os números são idênticos (espelha a secção Utilização do README).

Linha de comandos. A CLI despacha com base no campo kind do cenário e escreve <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html e <scenario>.report.json junto da entrada (JSON é JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Alguns tipos de cenário publicam também uma tabela de reprodutibilidade como <scenario>.table.csv (valores separados por vírgulas): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing e moonlight-service-volume quando está definido um local de exportação. Nenhum dos três tutoriais é um deles, pelo que não verá esse ficheiro aqui.

cargo run -- scenarios/orbit-sgp4-gps.toml

cargo run -- compila a CLI a partir desta cópia de trabalho. Com um binário instalado (cargo install kshana), o mesmo comando é kshana scenarios/orbit-sgp4-gps.toml. Sem uma cópia de trabalho, a maioria dos cenários fornecidos está incluída no binário: kshana example lista-os (e indica os poucos que não estão incluídos, com o motivo), e kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml escreve um: a cópia de scenarios/orbit-sgp4-gps.toml com que o binário foi compilado.

Python. Compile a extensão a partir desta cópia de trabalho uma vez com o maturin, dentro de um ambiente virtual ativo, e depois chame kshana.run:

pip install maturin
maturin develop --features python

import json, kshana
result = json.loads(kshana.run(open("scenarios/orbit-sgp4-gps.toml").read()))
print(result["geometry"]["best_pdop"])

pip install kshana instala antes o wheel publicado. Pode ficar atrás desta cópia de trabalho: json.loads(kshana.list_kinds()) indica-lhe que tipos de cenário a sua compilação tem.

Playground no navegador. Sem instalação: abra o Studio, escolha um cenário, edite os parâmetros e leia o resultado. Nada é enviado; o motor corre no cliente como WebAssembly.

Os tutoriais citam a CLI, mas cada comando tem o equivalente em Python e no playground acima. Cada resultado é reproduzível a partir de scenario + seed + engine version: execute-o duas vezes e obtém uma saída idêntica bit a bit.

Cenários didáticos anotados#

Para cada domínio de capacidade existe um .toml muito comentado em scenarios/: uma cópia didática de um cenário canónico com cada campo explicado em linha, a referência independente citada indicada e o resumo esperado de uma linha registado como comentário # expected:. Os valores dos campos são idênticos aos do cenário de origem no diretório scenarios/ de topo do repositório (tests/tutorials.rs compara o TOML analisado), pelo que a saída documentada continua verdadeira. Os hashes de referência também ficam intactos: um comentário nunca altera o hash de um cenário.

O ficheiro didático de segurança usa kind = "spoof" no interior: a figura de mérito de Segurança (1 − P_md, um menos a probabilidade de falha de deteção) é produzida pelo pacote spoof. O nome do ficheiro segue a capacidade (segurança), o kind segue o pacote (spoof). O cabeçalho desse ficheiro chama a atenção para isto.

O catálogo completo de tipos de cenário#

O motor despacha com base no kind do cenário. A tabela abaixo lista os tipos de cenário mais usados (os oito domínios dos tutoriais acima mais os vizinhos mais próximos). Não é o conjunto completo: src/api.rs::list_scenario_kinds() devolve todos os 92 tipos de cenário incorporados. Essa função (exposta como list_kinds() nas ligações Python e WebAssembly (WASM), e como kshana kinds --json na linha de comandos) é o catálogo de referência, sempre atual, e SCENARIOS.md é a sua enumeração gerada, com uma secção por tipo de cenário e os campos TOML obrigatórios e opcionais. tests/tutorials.rs::tutorial_scenarios_use_real_kinds garante que todos os tipos de cenário que um tutorial documenta são tipos de despacho reais, pelo que nada nesta tabela pode nomear um tipo de cenário que não existe.

Para além dos tutoriais: capacidades mais recentes#

Os três tutoriais ficam pelos pacotes clássicos de relógio, órbita e segurança. O motor cresceu muito para além deles. Cada linha abaixo é um cenário fornecido que pode executar tal como está (cargo run -- <file> ou kshana <file>); o resumo é a primeira linha que o kshana 0.35.0 imprimiu para ele em 2026-10-10. Ao contrário dos valores dos tutoriais, estas linhas são o registo de uma execução, não fixadas por tests/tutorials.rs: execute novamente o cenário para obter o valor atual. Os resultados indicam o seu próprio âmbito (a maioria traz um label), e a matriz de verificação indica que capacidades são VALIDATED face a uma referência independente externa e quais são MODELLED.

LEO é órbita terrestre baixa e MEO órbita terrestre média; PVT é posição, velocidade e tempo; PPP é posicionamento preciso de ponto; 5G é a norma móvel de quinta geração; TDB é o Tempo Dinâmico Baricêntrico; JD é a Data Juliana; TE é o erro de tempo.

A CLI acrescenta três saídas a qualquer execução:

• Relatórios. Cada execução escreve <scenario>.report.html e <scenario>.report.json (ver REPORTS.md). kshana --study <suite.toml> executa um conjunto de cenários num único .study.json e .study.html, por exemplo kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> desenha as séries temporais da execução, por exemplo --animate html em scenarios/orbit-sgp4-gps.toml escreve orbit-sgp4-gps.animation.html. Um tipo de cenário sem eixo temporal amostrado (como solar-system) é recusado com um erro; ver ANIMATION.md.
• Exportações de interoperabilidade. --export <czml|kml|geojson|stk|sigmf|all|list> escreve o resultado para outras ferramentas: CZML (Cesium Language), KML (Keyhole Markup Language, para o Google Earth), GeoJSON (JSON geográfico), efemérides STK (Systems Tool Kit) ou uma gravação SigMF (Signal Metadata Format). --export list indica que formatos se aplicam a um cenário; o SigMF aplica-se apenas a spectrum. O pacote de órbita também exporta --export-sp3, --export-omm e --export-oem (mensagens de órbita CCSDS, do Consultative Committee for Space Data Systems). Ver INTEROP.md.

Exercícios graduados#

Percorra a escada. Cada nível é mais difícil e mais defensável do que o anterior; as soluções de referência encontram-se em exercises/.

As soluções de referência usam a extensão Python (primeiro maturin develop --features python). Executado a partir da raiz do repositório, tier2_sweep.py imprime o holdover do relógio atómico à escala de chip a descer de 2610 s com uma especificação de 20 ns para 1140 s a 5 ns.

Quer dados novos?#

Os números de destaque destes tutoriais correm inteiramente a partir de cenários que já estão no repositório. Nada é descarregado, o que os mantém reproduzíveis e seguros para executar em integração contínua (CI). Para os exercícios de “alargar” pode obter dados em direto:

• Elementos de duas linhas (TLE) do GPS (atualizar a constelação de órbita): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, conjuntos de elementos em texto simples de 3 linhas (nome + linha 1 + linha 2). Auxiliar: scripts/fetch_tles.sh. Dados abertos (catálogo do 18th Space Defense Squadron da US Space Force, redistribuído pelo Celestrak, Dr. T. S. Kelso).
• Referência independente de verificação do SGP4 (Simplified General Perturbations 4) (já incorporada, não descarregar de novo): vetores de teste AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 “Revisiting Spacetrack Report #3”, https://celestrak.org/publications/AIAA/2006-6753/, usados por tests/sgp4_verification.rs; ver docs/SGP4-VALIDATION.md.
• Referência independente das relações de estabilidade de relógio: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, as relações σ_y(τ)↔fase por trás do Tutorial 2.