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

APIs e integraçõesEditar no GitHubFonte: README.crates.md

Kshana: a marca, uma retícula de bússola que assinala o instante preciso, ao lado do logótipo kshanaKshana: a marca, uma retícula de bússola que assinala o instante preciso, ao lado do logótipo 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 face a referências independentes externas Cerca de 95% de cobertura de linhas, com um mínimo de 85% na integração contínua Licença: AGPL-3.0-only, ou uma licença comercial DOI 10.5281/zenodo.20528627

Ensaiar o minuto em que o GNSS fica às escuras: a consola de missão do Kshana, desenhada a partir de uma execução real do motor, uma campanha encadeada de jamming, spoofing, holdover e integridade sobre os 102 satélites do GPS, Galileo, BeiDou e GLONASSEnsaiar o minuto em que o GNSS fica às escuras: a consola de missão do Kshana, desenhada a partir de uma execução real do motor, uma campanha encadeada de jamming, spoofing, holdover e integridade sobre os 102 satélites do GPS, Galileo, BeiDou e GLONASS

Ensaiar o minuto em que o GNSS fica às escuras#

O Kshana reproduz jamming, spoofing e holdover do relógio quando os sinais GNSS (sistema global de navegação por satélite) falham, e diz durante quanto tempo um sistema mantém a hora e a posição dentro do seu orçamento, e que relógio ou sensor proporciona mais margem. Esta é a crate Rust: o motor como biblioteca, e o comando kshana. Cada 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 completo no seu navegador, compilado para WebAssembly, e não carrega nada.

Evidências#

176 de 401 capacidades validadas face a referências independentes externas; 221 etiquetadas com honestidade como modeladas, 4 pertencentes a parceiros. Cada capacidade traz uma única etiqueta num registo 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 face ao Orekit 12,2.

Como uma capacidade obtém a sua etiqueta: capacidade, referência independente, teste, etiqueta no registo. O estado de verificação das 401 capacidades: 176 validadas, 221 modeladas, 4 pertencentes a parceirosComo uma capacidade obtém a sua etiqueta: capacidade, referência independente, teste, etiqueta no registo. 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)

Utilização — biblioteca#

O exemplo é um programa completo: traz o seu próprio cenário, escrito em TOML (Tom's Obvious, Minimal Language), pelo que executa 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írgulas).

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

Todas as funções públicas de kshana::api na versão v0.40.0 do motor, lidas da origem no momento da compilação.

FunçãoAssinaturaO que faz
kshana::api::without_figure_tiers(json: &str) -> Option<String>json com o seu bloco figure_tiers final removido, byte a byte como o documento era antes de esse bloco existir; None quando o documento não tem esse bloco, ou tem um que não é a sua última chave (o que esta crate nunca emite, pelo que um sistema de testes deve tratar isso como falha em vez de retirar algo que não consegue explicar).
kshana::api::list_scenario_kinds() -> Vec<ScenarioMeta>Lista todos os tipos de cenário incorporados com os seus metadados.
kshana::api::list_scenario_kinds_json() -> StringOs tipos de cenário incorporados e os seus metadados como matriz JSON — a forma que as ligações de linguagem expõem para introspeçã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 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() -> StringProduz o catálogo de tipos de cenário incorporados como uma referência Markdown autónoma (docs/SCENARIOS.md): todos os tipos de cenário despacháveis com a sua descrição de uma linha e os seus campos TOML obrigatórios / opcionais.
kshana::api::validate_scenario(src: &str) -> Vec<String>Analisa um cenário TOML com a introspeção da própria 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 numa 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 for um cenário de órbita com export_sp3 = true, devolve o 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 catálogo CCSDS OMM — um OMM (Orbit Mean-Elements Message) por satélite definido por TLE, em forma 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 for um cenário de órbita com export_omm = true, devolve o texto do seu 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 veículos espaciais 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 for um cenário de órbita com export_oem = true, devolve o 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 no campo eop_finals2000a de um cenário (o caminho da CLI --eop <file>), devolvendo o TOML fundido.
kshana::api::with_study_meta(json: &str, meta: &crate::report::StudyMeta) -> StringInsere um bloco de metadados de estudo num documento JSON de resultado já produzido, devolvendo o documento com uma chave "meta" de nível superior inserida logo a seguir à 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 ligações devem preferir ao [run_toml] com erro em cadeia.
kshana::api::run_toml(src: &str) -> Result<RunOutput, String>Analisa, despacha e executa um cenário dado como cadeia TOML.
kshana::api::run_toml_lang(src: &str, lang: &str) -> Result<RunOutput, String>[run_toml] para um utilizador 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 ficheiros 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 utilizador no idioma lang; veja [run_toml_lang].
kshana::api::error_info_json(src: &str, lang: &str) -> StringExecuta 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) -> Stringjson sem a etiqueta de evidência ([crate::evidence_label]); inalterado se não tiver nenhum.
kshana::api::without_evidence_labels(mut out: RunOutput) -> RunOutputout com a etiqueta de evidência removida do seu JSON, SVG e CSV, byte a byte como a execução os produziu antes de a etiqueta existir; uma saída sem etiqueta 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 está incorporado no resultado de outro tipo de cenário (um membro de campanha), de modo que o documento exterior mantenha os seus bytes.
kshana::api::append_figure_tiers(json: &str, block: &serde_json::Value) -> Result<String, String>json com block acrescentado como a sua última chave, figure_tiers, byte a byte como o invólucro Documented o teria serializado: impressão formatada com dois espaços, o bloco aninhado um nível para dentro.

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

Utilização — CLI#

Uma instalação a partir do registo de pacotes não tem diretório scenarios/, pelo que a CLI traz consigo os cenários de referência; kshana example lista-os, e nomeia os poucos que deixa de fora com a razão (cada um lê dados fornecidos apenas com o repositório, ou segue uma predefinição que uma ediçã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 segundo o kind do cenário e escreve <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), mais .table.csv para os tipos de cenário que publicam uma tabela, junto ao ficheiro de cenário. --export acrescenta ficheiros de troca: CZML (Cesium Language) e KML (Keyhole Markup Language) para visualizadores de globo, GeoJSON para mapas, ficheiros 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 SVG, HTML ou fotograma a fotograma.

A partir de um clone do repositório, os mesmos comandos aceitam diretamente os ficheiros em scenarios/, incluindo o estudo de 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 medição de distâncias por laser fornecidos apenas com o repositório.

Cada capacidade da matriz de verificação é etiquetada como validada (verificada face a uma referência independente externa), modelada ou da responsabilidade de parceiros; os valores dos relógios óticos são objetivos espaciais em hardware de solo (nenhum relógio ótico de estrôncio voou). A maturidade não é uniforme entre domínios — o PNT terrestre é validado face a dados reais; a navegação no espaço profundo e em Marte é modelada, com apenas os seus blocos de construção (tempo de luz, posições dos planetas) validados face a referências independentes externas; a determinação de órbita (OD) em espaço profundo de missões reais consta do roteiro.

Capacidades#

O motor tem 92 tipos de cenário; kshana kinds os lista com os respetivos campos. Novos na 0.38.0: gnss-ssv (sinais GNSS para veículos espaciais acima, em torno 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 registo de erro de tempo face às máscaras da ITU-T).

  • Espetro: como um emissor de jamming ocupa a banda L do GNSS, banda a banda.
  • Relógios e temporização: holdover face a um limiar, transferência de tempo e holdover de telecomunicações face às máscaras do setor de normalização da União Internacional das Telecomunicações (ITU-T).
  • Constelações em torno de qualquer corpo: cobertura, diluição da precisão e disponibilidade em torno da Terra, da Lua ou de Marte, e do sistema solar numa época.
  • Navegação em órbita terrestre baixa: sinal, passagem e ligação, mensagem de navegação e uma solução de posição fundida, fase a fase.
  • Campanhas: uma missão encadeada, uma varredura ou um conjunto de Monte Carlo num só cenário.
  • Relatórios, animação e exportações: cada valor com a sua unidade e etiqueta; um desenho animado de uma execução; ficheiros 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 em embarcações (receiver_trust, incluindo receiver_trust::live): uma pontuação de 0-100 com razões a partir do NMEA de um recetor, em direto ou a partir de um registo; consultivo, não é um equipamento de navegação homologado.
  • Pacotes de evidências (evidence): um registo técnico assinado de uma janela de registo, verificável offline.
  • Telemetria de confiança (telemetry): o fluxo de confiança como métricas Prometheus, eventos SIEM e OpenTelemetry opcional.
  • Fluxos de formação (nmea_synth): NMEA de ponte sintético com jamming e spoofing programados e um registo do instrutor. Apenas texto; nunca para os sistemas de navegação em direto de uma embarcação.
  • Mapa de interferência (interference_map): mapas agregados de navegação degradada e exposição de rotas.
  • 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 quadros públicos preenchido a partir de documentos de resultado.
  • Laboratório de IQ GNSS (iq): cenas, aquisição, seguimento, monitores e campanhas sobre IQ gravado e sintético.

Arquitetura#

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

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

Investigação#

Seis artigos no arXiv assentam no motor aberto, cada um com o comando que está por trás: arXiv:2606,22054 (a lacuna de otimismo dos detetores 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 à superfície lunar com interferometria de base muito longa), arXiv:2607,06212 (geometria polar sul lunar e faróis de superfície) e arXiv:2610,23871 (navegação cisluar como um problema de observabilidade: comprimento do arco, condicionamento do Gramiano e a alavanca do Doppler). Ver Investigação.

Edições#

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

Saber mais#

Licença#

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