Rust crate · Kshana docs

Kshana: a marca, uma retícula de bússola que marca o instante preciso, ao lado do logotipo kshana

Kshana · क्षण · o instante preciso
Um simulador de código aberto para a resiliência de PNT (posicionamento, navegação e temporização).

Versão v0.40.0 176 de 401 capacidades validadas em relação a referências independentes externas Cerca de 95% de cobertura de linhas, com mínimo exigido de 85% na integração contínua Licença: AGPL-3.0-only, ou uma licença comercial DOI 10.5281/zenodo.20528627

Ensaie o minuto em que o GNSS apaga#

O Kshana reproduz jamming, spoofing e holdover de relógio quando os sinais GNSS (Global Navigation Satellite System) falham, e informa por quanto tempo um sistema mantém tempo e posição dentro de seu orçamento, e qual relógio ou sensor compra mais margem. Este é o crate em Rust: o motor como biblioteca e o comando kshana. Toda execução é reprodutível bit a bit a partir do cenário, da semente e da versão do motor.

Experimente primeiro sem nada para instalar: o Kshana Studio executa o motor inteiro no seu navegador, compilado para WebAssembly, e não envia nada.

Evidências#

176 de 401 capacidades validadas em relação a referências independentes externas; 221 rotuladas com honestidade como modeladas, 4 pertencentes a parceiros. Cada capacidade traz um único rótulo em um registro verificado por máquina: VALIDATED (uma referência independente externa concorda: dados reais, uma implementação independente ou vetores de referência publicados), MODELLED (internamente consistente, e dito em voz alta) ou PARTNER (um parceiro de hardware é o responsável). Entre as verificações: todos os 666 vetores SGP4 (Simplified General Perturbations 4) do AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 até 4,12 mm, e o modelo de forças de Cowell até 0,08 m em relação ao Orekit 12,2.

Como uma capacidade obtém seu rótulo: capacidade, referência independente, teste, rótulo no registro. O estado de verificação das 401 capacidades: 176 validadas, 221 modeladas, 4 pertencentes a parceiros

Instalar#

cargo add kshana            # use the engine as a library
cargo install kshana        # or install the command-line interface (CLI)

Uso — biblioteca#

O exemplo é um programa completo: traz seu próprio cenário, escrito em TOML (Tom's Obvious, Minimal Language), de modo que roda como src/main.rs de um projeto cargo new novo após cargo add kshana, sem mais nada em disco.

use kshana::api;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A complete scenario, not a sketch: scenarios/clock-holdover.toml without its
    // comment lines. It runs 2 h, 10 min of GNSS then about 1.8 h with GNSS denied, and
    // asks how long a strontium optical clock and a chip-scale atomic clock (CSAC) each
    // hold time to within 20 ns. sigma_y(1s) is a clock's Allan deviation at an averaging
    // time of one second; q_wf, the white-frequency-noise intensity, is its square.
    let toml = r#"
seed = 42
threshold_ns = 20.0

[time]
step_s = 10.0
duration_s = 7200.0

[gnss]
windows = [
  { t0 = 0.0,    t1 = 600.0,  state = "nominal" },
  { t0 = 600.0,  t1 = 7200.0, state = "denied" },
]

[clock_quantum]
id = "optical-sr-lattice"
provenance = "Strontium optical lattice clock, space-oriented goal sigma_y(1s)=1e-15 (Origlia/Schiller/Bongs et al., arXiv:1503.08457); q_wf=sigma_y(1s)^2; ground-demonstrator maturity, not flown; flicker/aging not modeled"
y0   = 5.0e-17
q_wf = 1.0e-30
q_rw = 0.0

[clock_classical]
id = "csac-sa45s"
provenance = "Microchip SA65 / SA.45s CSAC datasheet sigma_y(1s)=3e-10; q_wf=sigma_y(1s)^2; flicker/aging not modeled"
y0   = 5.0e-10
q_wf = 9.0e-20
q_rw = 0.0
"#;
    let out = api::run_toml(toml)?; // RunOutput { json, svg, summary, csv }
    println!("{}", out.summary); // the one-line result string
    std::fs::write("clock-holdover.result.json", &out.json)?; // the full result document
    Ok(())
}

out.json é o documento de resultado em JSON (JavaScript Object Notation), out.svg o gráfico em SVG (Scalable Vector Graphics) e out.csv, para os tipos de cenário que publicam uma tabela, essa tabela em CSV (valores separados por vírgula).

Referência da API, gerada a partir de src/api.rs#

Toda função pública de kshana::api na versão v0.40.0 do motor, lida da fonte em tempo de compilação.

Função	Assinatura	O que faz
`kshana::api::without_figure_tiers`	`(json: &str) -> Option<String>`	json com seu bloco final figure_tiers removido, byte a byte como o documento era antes de esse bloco existir; None quando o documento não tem tal bloco, ou tem um que não é sua última chave (o que este crate nunca emite, de modo que um harness deve tratar isso como falha em vez de remover algo que não sabe explicar).
`kshana::api::list_scenario_kinds`	`() -> Vec<ScenarioMeta>`	Lista todo tipo de cenário incorporado com seus metadados.
`kshana::api::list_scenario_kinds_json`	`() -> String`	Os tipos de cenário incorporados e seus metadados como uma matriz JSON — a forma que os bindings de linguagem expõem para introspecção programática.
`kshana::api::kind_description_in`	`(lang: &crate::i18n::Lang, kind: &str) -> Option<String>`	A descrição do tipo de cenário incorporado kind em lang, a partir do catálogo (inglês quando o idioma não tem tradução dela); None para um nome que não é um tipo de cenário incorporado.
`kshana::api::kind_description`	`(kind: &str) -> Option<String>`	[kind_description_in] no idioma atual ([crate::i18n::current]).
`kshana::api::list_scenario_kinds_json_lang`	`(lang: &str) -> Result<String, String>`	[list_scenario_kinds_json] com cada descrição em lang (uma etiqueta como a que --lang aceita, como de ou zh-Hans); os nomes e as listas de campos são os mesmos em todos os idiomas e, para o inglês, o documento é idêntico byte a byte a [list_scenario_kinds_json].
`kshana::api::kind_modules_json`	`() -> String`	[KIND_MODULES] como um objeto JSON, tipo de cenário para matriz de nomes de módulos, na ordem da tabela.
`kshana::api::field_importance_json`	`() -> String`	[HEADLINE_FIELDS] como JSON: {kind: {"headline": [path, ...]}}, na ordem da tabela.
`kshana::api::scenarios_reference_md`	`() -> String`	Renderiza o catálogo de tipos de cenário incorporados como uma referência Markdown autônoma (docs/SCENARIOS.md): todo tipo de cenário despachável com sua descrição de uma linha e seus campos TOML obrigatórios / opcionais.
`kshana::api::validate_scenario`	`(src: &str) -> Vec<String>`	Verifica um cenário TOML em relação à introspecção do próprio crate e devolve uma lista de problemas — para que se possa dizer ao chamador o que está errado ANTES de uma execução (possivelmente longa), em vez de ele esbarrar em uma falha tardia em tempo de execução.
`kshana::api::export_sp3`	`(src: &str) -> Result<String, String>`	Exporta a constelação propagada de um cenário de órbita/constelação como texto SP3-c.
`kshana::api::auto_export_sp3`	`(src: &str) -> Result<Option<String>, String>`	Se src é um cenário de órbita com export_sp3 = true, devolve seu texto SP3-c; caso contrário, None.
`kshana::api::export_omm`	`(src: &str) -> Result<String, String>`	Exporta os elementos médios TLE de um cenário de órbita como um catálogo CCSDS OMM — uma OMM (Orbit Mean-Elements Message) por satélite definido por TLE, em formato KVN, com o número de catálogo NORAD real, o designador COSPAR e a época de cada TLE.
`kshana::api::auto_export_omm`	`(src: &str) -> Result<Option<String>, String>`	Se src é um cenário de órbita com export_omm = true, devolve seu texto de catálogo OMM; caso contrário, None.
`kshana::api::export_oem`	`(src: &str) -> Result<String, String>`	Exporta a constelação propagada de um cenário de órbita como texto CCSDS OEM — a série temporal de estados inerciais (TEME), posição E velocidade, no formato de intercâmbio de efemérides de espaçonaves que as ferramentas de dinâmica de voo (GMAT/Orekit/STK) leem.
`kshana::api::auto_export_oem`	`(src: &str) -> Result<Option<String>, String>`	Se src é um cenário de órbita com export_oem = true, devolve seu texto OEM; caso contrário, None.
`kshana::api::inject_eop`	`(src: &str, finals2000a_body: &str) -> Result<String, String>`	Incorpora um corpo IERS finals2000A real ao campo eop_finals2000a de um cenário (o caminho --eop <arquivo> da CLI), devolvendo o TOML mesclado.
`kshana::api::with_study_meta`	`(json: &str, meta: &crate::report::StudyMeta) -> String`	Insere um bloco de metadados de estudo em um documento JSON de resultado já renderizado, devolvendo o documento com uma chave "meta" de nível superior inserida logo após a chave de abertura.
`kshana::api::run_scenario`	`(src: &str) -> Result<RunOutput, KshanaError>`	Executa um cenário e devolve um resultado tipado com um erro estruturado — o ponto de entrada que os chamadores de bindings devem preferir ao [run_toml] com erro em string.
`kshana::api::run_toml`	`(src: &str) -> Result<RunOutput, String>`	Analisa, despacha e executa um cenário dado como string TOML.
`kshana::api::run_toml_lang`	`(src: &str, lang: &str) -> Result<RunOutput, String>`	[run_toml] para um usuário no idioma lang (uma etiqueta como de, pt-BR, zh-Hans, en-XA).
`kshana::api::run_toml_bilingual`	`(src: &str, lang: &str) -> Result<(RunOutput, Option<RunOutput>), String>`	As duas execuções de [run_toml_lang] mantidas separadas: a execução em inglês, cujos json e csv são os arquivos de máquina e, para outro idioma, a execução nesse idioma para tudo o que uma pessoa lê.
`kshana::api::run_toml_human`	`(src: &str, lang: &str) -> Result<HumanOutput, String>`	A segunda passagem de [run_toml_bilingual] isolada: executa o cenário uma vez em lang e devolve apenas o que uma pessoa lê.
`kshana::api::run_scenario_lang`	`(src: &str, lang: &str) -> Result<RunOutput, KshanaError>`	[run_scenario] para um usuário no idioma lang; veja [run_toml_lang].
`kshana::api::error_info_json`	`(src: &str, lang: &str) -> String`	Executa src no idioma lang e, se falhar, descreve a falha como um objeto JSON {"kind": <kind_tag>, "code": <stable code or null>, "message": <text in the language>}.
`kshana::api::without_evidence`	`(json: &str) -> String`	json sem o rótulo de evidência ([crate::evidence_label]); inalterado se não tiver nenhum.
`kshana::api::without_evidence_labels`	`(mut out: RunOutput) -> RunOutput`	out com o rótulo de evidência removido de seu JSON, SVG e CSV, byte a byte como a execução os produziu antes de o rótulo existir; uma saída sem rótulo permanece inalterada.
`kshana::api::run_toml_untiered`	`(src: &str) -> Result<RunOutput, String>`	[run_toml] sem o bloco figure_tiers por tipo de cenário que [run_toml_inner] acrescenta (RM-04): para uma execução cujo documento é incorporado ao resultado de outro tipo de cenário (um membro de campanha), de modo que o documento externo mantenha seus bytes.
`kshana::api::append_figure_tiers`	`(json: &str, block: &serde_json::Value) -> Result<String, String>`	json com block acrescentado como sua última chave, figure_tiers, byte a byte como o wrapper Documented o teria serializado: impressão formatada com dois espaços, o bloco aninhado um nível adentro.

Formatos de intercâmbio no crate: analisador e gravador CCSDS Tracking Data Message (TDM) (kshana::ccsds_tdm); Kshana Interchange Format (KIF) (kshana::interchange).

Uso — CLI#

Uma instalação pelo registro não tem o diretório scenarios/, de modo que a CLI leva consigo os cenários de referência; kshana example os lista e nomeia os poucos que deixa de fora, com o motivo (cada um lê apenas dados distribuídos com o repositório, ou segue uma predefinição que uma versão pode reter).

kshana example clock-holdover > clock-holdover.toml   # write a bundled scenario to a file
kshana clock-holdover.toml                            # run it
kshana --validate clock-holdover.toml                 # lint it without running
kshana example                                        # list every bundled scenario
kshana kinds                                          # list every scenario kind

kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml   # the GPS constellation, real orbital elements
kshana orbit-sgp4-gps.toml --export list              # which exchange formats apply
kshana orbit-sgp4-gps.toml --export all               # every exchange file that applies
kshana orbit-sgp4-gps.toml --animate html             # a self-contained animation page

Uma execução despacha pelo kind do cenário e grava <scenario>.result.json, .chart.svg, .report.html (uma página de relatório imprimível em HTML, HyperText Markup Language) e .report.json (o mesmo relatório, legível por máquina), além de .table.csv para os tipos de cenário que publicam uma tabela, ao lado do arquivo de cenário. --export acrescenta arquivos de intercâmbio: CZML (Cesium Language) e KML (Keyhole Markup Language) para visualizadores de globo, GeoJSON para mapas, arquivos de efemérides STK (Systems Tool Kit) e gravações SigMF (Signal Metadata Format) para o tipo de cenário spectrum. --animate acrescenta uma animação em SVG, HTML ou quadro a quadro.

A partir de um clone do repositório, os mesmos comandos aceitam diretamente os arquivos em scenarios/, inclusive o estudo com vários cenários (kshana --study scenarios/quantum-pnt-demonstrator.suite.toml) e lunar-llr-datum, o único cenário que lê dados reais de telemetria a laser distribuídos apenas com o repositório.

Toda capacidade na matriz de verificação é rotulada como validada (verificada contra uma referência independente externa), modelada ou de propriedade de parceiro; as cifras de relógios ópticos são metas espaciais em hardware de solo (nenhum relógio óptico de estrôncio voou). A maturidade não é uniforme entre os domínios — o PNT terrestre é validado contra dados reais; a navegação de espaço profundo e de Marte é modelada, com apenas os seus blocos de construção (tempo de luz, posições de planetas) validados contra referências independentes externas; a OD (determinação de órbita) de espaço profundo em missões reais está no roteiro.

Capacidades#

O motor tem 92 tipos de cenário; kshana kinds os lista com seus campos. Novos na 0.38.0: gnss-ssv (sinais GNSS para espaçonaves acima, ao redor e além das órbitas GNSS) e lunar-infrastructure (órbita e superfície lunares como infraestrutura de navegação e geodésica), ambos MODELLED, e holdover-test (um registro de erro de tempo em relação às máscaras da ITU-T).

Espectro: como um jammer toma a banda L do GNSS, banda a banda.
Relógios e temporização: holdover contra um limiar, transferência de tempo e holdover de telecomunicações contra as máscaras do setor de normalização da União Internacional de Telecomunicações (ITU-T).
Constelações em torno de qualquer corpo: cobertura, diluição de precisão e disponibilidade em torno da Terra, da Lua ou de Marte, e o sistema solar numa época.
Navegação em órbita terrestre baixa: sinal, passagem e enlace, mensagem de navegação e uma solução fundida, etapa por etapa.
Campanhas: uma missão encadeada, uma varredura ou um ensemble de Monte Carlo num único cenário.
Relatórios, animação e exportações: toda cifra com a sua unidade e o seu rótulo; um desenho animado de uma execução; arquivos SP3 (Standard Product 3), mensagens de órbita CCSDS (Consultative Committee for Space Data Systems), CZML (Cesium Language), KML (Keyhole Markup Language), GeoJSON, STK (Systems Tool Kit) e SigMF (Signal Metadata Format).
Confiança GNSS de embarcação (receiver_trust, inclusive receiver_trust::live): uma pontuação de 0 a 100 com motivos, a partir do NMEA de um receptor, ao vivo ou de um log; consultivo, não um equipamento de navegação homologado.
Pacotes de evidências (evidence): um registro técnico assinado de uma janela de log, verificável offline.
Telemetria de confiança (telemetry): o fluxo de confiança como métricas Prometheus, eventos SIEM e OpenTelemetry opcional.
Fluxos de treinamento (nmea_synth): NMEA sintético de ponte com jamming e spoofing roteirizados e um log de instrutor. Somente texto; nunca para os sistemas de navegação ao vivo de uma embarcação.
Mapa de interferência (interference_map): mapas agregados de navegação degradada e exposição de rota.
Test bench e mapeamento de compliance (interop::testbench, compliance): o movimento do veículo e os eventos de um cenário para um simulador GNSS de laboratório, e o mapeamento para frameworks públicos preenchido a partir de documentos de resultado.
Laboratório de IQ GNSS (iq): cenas, aquisição, rastreamento, monitores e campanhas sobre IQ gravado e sintético.

Arquitetura#

Um motor aberto no centro, kshana 0.40.0, com um despacho tipado sobre 75 tipos de cenário; ao redor, a linha de comando, a biblioteca Rust, o Python, o WebAssembly e o Kshana Studio, o servidor MCP, a imagem Docker e o plugin JetBrains; abaixo, o Kshana Pro, uma camada proprietária que depende do motor aberto e nunca o bifurca

O mesmo arquivo de cenário dá os mesmos bytes em todas as superfícies. MCP é o Model Context Protocol: kshana-mcp permite que um assistente de IA (inteligência artificial) execute o motor.

Pesquisa#

Seis artigos no arXiv são construídos sobre o motor aberto, cada um com o comando por trás dele: arXiv:2606,22054 (a lacuna de otimismo dos detectores de interferência), arXiv:2606,24210 (um nível de proteção de temporização condicional), arXiv:2607,05415 (quão estável é uma pontuação de resiliência de PNT), arXiv:2607,02566 (observabilidade de estações de superfície lunar com interferometria de linha de base muito longa), arXiv:2607,06212 (geometria polar sul lunar e faróis de superfície) e arXiv:2610,23871 (navegação cislunar como problema de observabilidade: comprimento de arco, condicionamento do Gramiano e a alavanca Doppler). Veja Pesquisa.

Edições#

O motor inteiro é livre sob a AGPL-3.0. O Kshana Pro, uma camada proprietária que depende do motor aberto e nunca o bifurca, e estudos personalizados estão disponíveis sob contrato com a Ashforde® OÜ: contact@ashforde.org. Não há preços; veja docs/PRO.md.

Saiba mais#

O README completo → https://github.com/AshfordeOU/kshana
Kshana Studio (o motor no seu navegador, como WebAssembly) → https://kshana.dev
Capacidades → docs/CAPABILITY.md
Validação e proveniência → docs/VALIDATION.md · docs/PROVENANCE.md
Matriz de verificação → docs/VERIFICATION-MATRIX.md
Citar → CITATION.cff · DOI 10.5281/zenodo.20528627

Licença#

Software livre e de código aberto sob a GNU AGPL-3.0-only (a GNU Affero General Public License, versão 3 apenas). Uma licença comercial está disponível junto à Ashforde® OÜ (uma sociedade privada de responsabilidade limitada da Estônia; OÜ = osaühing) para integração fechada; veja LICENSING.md. Desenvolvido e mantido profissionalmente pela Ashforde® OÜ.