Tutoriais

Exercícios práticos resolvidos que levam você de “executar um cenário fornecido” a “quantificar e defender um resultado”. Todo número citado nos três tutoriais é uma saída real do mecanismo, ancorada em uma referência independente externa (não circular) de autoridade reconhecida, e fixado por um teste de integração (tests/tutorials.rs), de modo que um tutorial nunca pode se afastar em silêncio do que o mecanismo realmente faz. Se um tutorial diz que o relógio óptico mantém 6600 s, o teste derruba o build no dia em que isso deixar de ser verdade.

O Kshana é um simulador de posicionamento, navegação e temporização (PNT). Os tutoriais usam algumas outras abreviações, cada uma explicada onde aparece pela primeira vez: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (interface de linha de comando) e TOML (Tom's Obvious Minimal Language, o formato de arquivo de cenário).

Novo no projeto? Leia antes o guia de conceitos e o glossário e depois volte aqui.

Os três exemplos práticos#

Notebooks#

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

Como executar um tutorial#

Todo tutorial executa o mesmo cenário de três maneiras; escolha a que lhe convier. Todas chamam o mesmo mecanismo, portanto os números são idênticos (espelha a seção Uso do README).

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

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

cargo run -- compila a CLI a partir deste checkout. Com um binário instalado (cargo install kshana), o mesmo comando é kshana scenarios/orbit-sgp4-gps.toml. Sem um checkout, a maioria dos cenários fornecidos está embutida no binário: kshana example os lista (e nomeia os poucos que não estão embutidos, com o motivo), e kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml grava um: a cópia de scenarios/orbit-sgp4-gps.toml com que o binário foi compilado.

Python. Compile a extensão a partir deste checkout uma vez com maturin, dentro de um ambiente virtual ativo, e então 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 o wheel publicado. Ele pode estar defasado em relação a este checkout: json.loads(kshana.list_kinds()) informa quais tipos de cenário 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 mecanismo roda no cliente como WebAssembly.

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

Cenários didáticos anotados#

Para cada domínio de capacidade há um .toml bastante 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 nomeada e o resumo esperado de uma linha registrado como comentário # expected:. Os valores dos campos são idênticos aos do original no diretório scenarios/ de nível superior do repositório (tests/tutorials.rs compara o TOML interpretado), de modo que a saída documentada continua verdadeira. Os hashes de referência (golden) também ficam intocados: um comentário nunca altera o hash de um cenário.

O arquivo didático de segurança usa kind = "spoof" internamente: a figura de mérito de Segurança (1 − P_md, um menos a probabilidade de detecção perdida) é produzida pelo pacote spoof. O nome do arquivo segue a capacidade (segurança); o kind segue o pacote (spoof). O cabeçalho desse arquivo destaca isso.

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

O mecanismo despacha pelo kind do cenário. A tabela abaixo lista os tipos de cenário mais usados (os oito domínios de tutorial acima mais seus vizinhos mais próximos). Ela não é o conjunto completo: src/api.rs::list_scenario_kinds() devolve todos os 92 tipos de cenário embutidos. Essa função (exposta como list_kinds() nos bindings Python e WebAssembly (WASM), e como kshana kinds --json na linha de comando) é o catálogo autoritativo e sempre atual, e SCENARIOS.md é sua enumeração gerada, uma seção por tipo de cenário com os campos TOML obrigatórios e opcionais. tests/tutorials.rs::tutorial_scenarios_use_real_kinds garante que todo tipo de cenário que um tutorial documenta é um tipo de despacho real, de modo que nada nesta tabela pode nomear um tipo de cenário que não existe.

Além dos tutoriais: capacidades mais novas#

Os três tutoriais ficam nos pacotes clássicos de relógio, órbita e segurança. O mecanismo cresceu muito além deles. Cada linha abaixo é um cenário fornecido que você pode executar 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 das figuras dos tutoriais, essas linhas são o registro de uma execução, não fixadas por tests/tutorials.rs: execute o cenário de novo para obter o valor atual. Os resultados declaram seu próprio escopo (a maioria traz um label), e a matriz de verificação declara quais capacidades são VALIDATED contra 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 é o padrão 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. Toda execução grava <scenario>.report.html e <scenario>.report.json (veja REPORTS.md). kshana --study <suite.toml> executa uma suíte de cenários em um .study.json e .study.html, por exemplo kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> renderiza as séries temporais da execução, por exemplo --animate html em scenarios/orbit-sgp4-gps.toml grava orbit-sgp4-gps.animation.html. Um tipo de cenário sem eixo de tempo amostrado (como solar-system) é recusado com um erro; veja ANIMATION.md.
• Exportações de interoperabilidade. --export <czml|kml|geojson|stk|sigmf|all|list> grava 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 informa quais formatos se aplicam a um cenário; o SigMF se aplica somente a spectrum. O pacote de órbita também exporta --export-sp3, --export-omm e --export-oem (mensagens de órbita do CCSDS, Consultative Committee for Space Data Systems). Veja INTEROP.md.

Exercícios graduados#

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

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

Quer dados novos?#

Os números de destaque nestes tutoriais rodam inteiramente a partir de cenários já presentes no repositório. Nada é baixado, o que os mantém reprodutíveis e seguros para rodar em integração contínua (CI). Para os exercícios de “estenda”, você pode puxar dados ao vivo:

• Elementos de duas linhas (TLEs) do GPS (atualizar a constelação de órbita): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, conjuntos de elementos de 3 linhas em texto simples (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á incluída, não baixe 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; veja docs/SGP4-VALIDATION.md.
• Referência independente das relações de estabilidade de relógio: Publicação Especial 1065 do NIST (National Institute of Standards and Technology) (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.