Tutoriales

Ejemplos prácticos que le llevan de “ejecutar un escenario incluido” a “cuantificar y defender un resultado”. Cada número citado en los tres tutoriales es una salida real del motor, anclada a una referencia independiente externa de autoridad reconocida (no circular), y fijada por una prueba de integración (tests/tutorials.rs), de modo que un tutorial nunca puede desviarse en silencio de lo que el motor hace realmente. Si un tutorial dice que el reloj óptico mantiene 6600 s, la prueba hace fallar la compilación el día en que eso deje de ser cierto.

Kshana es un simulador de posicionamiento, navegación y temporización (PNT). Los tutoriales usan algunas abreviaturas más, cada una desarrollada donde aparece por primera vez: GNSS (Sistema Global de Navegación por Satélite), GPS (Sistema de Posicionamiento Global), CLI (interfaz de línea de comandos) y TOML (Tom's Obvious Minimal Language, el formato de archivo de escenario).

¿Es nuevo en el proyecto? Lea primero la introducción a los conceptos y el glosario, y luego vuelva aquí.

Los tres ejemplos prácticos#

Cuadernos#

Los notebooks de Jupyter ejecutables, con datos sintéticos y conjuntos de elementos públicos conservados solo en el repositorio, están en notebooks/:

Cómo ejecutar un tutorial#

Cada tutorial ejecuta el mismo escenario de tres maneras; elija la que le convenga. Todas llaman al único motor, de modo que los números son idénticos (refleja la sección Uso del README).

Línea de comandos. La CLI despacha según el campo kind del escenario y escribe <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html y <scenario>.report.json junto a la entrada (JSON es JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). Algunos tipos de escenario publican además una tabla de reproducibilidad como <scenario>.table.csv (valores separados por comas): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing y moonlight-service-volume cuando se fija un sitio de exportación. Ninguno de los tres tutoriales es uno de ellos, de modo que no verá ese archivo aquí.

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

cargo run -- compila la CLI a partir de esta copia de trabajo. Con un binario instalado (cargo install kshana), el mismo comando es kshana scenarios/orbit-sgp4-gps.toml. Sin una copia de trabajo, la mayoría de los escenarios incluidos vienen en el binario: kshana example los enumera (y nombra los pocos que no vienen incluidos, con el motivo), y kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml escribe uno: la copia de scenarios/orbit-sgp4-gps.toml con la que se compiló el binario.

Python. Compile la extensión a partir de esta copia de trabajo una vez con maturin, dentro de un entorno virtual activo, y luego llame a 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 en su lugar la rueda publicada. Puede ir por detrás de esta copia de trabajo: json.loads(kshana.list_kinds()) le indica qué tipos de escenario tiene su compilación.

Playground del navegador. Sin instalación: abra el Studio, elija un escenario, edite los parámetros y lea el resultado. No se sube nada; el motor se ejecuta en el cliente como WebAssembly.

Los tutoriales citan la CLI, pero cada comando tiene el equivalente de Python y del playground indicado arriba. Cada resultado es reproducible a partir de scenario + seed + engine version: ejecútelo dos veces y obtendrá una salida idéntica bit a bit.

Escenarios didácticos anotados#

Para cada dominio de capacidad hay un .toml muy comentado en scenarios/: una copia didáctica de un escenario canónico con cada campo explicado en línea, la referencia independiente citada indicada por nombre y el resumen esperado de una línea registrado como un comentario # expected:. Los valores de los campos son idénticos a los del original en el directorio scenarios/ de nivel superior del repositorio (tests/tutorials.rs compara el TOML analizado), de modo que la salida documentada sigue siendo cierta. Los hashes de referencia tampoco se tocan: un comentario nunca cambia el hash de un escenario.

El archivo didáctico de seguridad usa kind = "spoof" en su interior: la cifra de mérito de seguridad (1 − P_md, uno menos la probabilidad de detección fallida) la produce el paquete spoof. El nombre del archivo sigue a la capacidad (seguridad), mientras que el kind sigue al paquete (spoof). La cabecera de ese archivo lo señala.

El catálogo completo de tipos de escenario#

El motor despacha según el kind del escenario. La tabla siguiente enumera los tipos de escenario de uso más habitual (los ocho dominios de los tutoriales anteriores y sus vecinos más próximos). No es el conjunto completo: src/api.rs::list_scenario_kinds() devuelve los 92 tipos de escenario integrados. Esa función (expuesta como list_kinds() en los enlaces de Python y de WebAssembly (WASM), y como kshana kinds --json en la línea de comandos) es el catálogo de referencia, siempre actualizado, y SCENARIOS.md es su enumeración generada, con una sección por tipo y los campos TOML obligatorios y opcionales. tests/tutorials.rs::tutorial_scenarios_use_real_kinds exige que todo tipo de escenario que documenta un tutorial sea un tipo de despacho real, de modo que nada de esta tabla puede nombrar un tipo de escenario que no exista.

Más allá de los tutoriales: capacidades más recientes#

Los tres tutoriales se quedan en los paquetes clásicos de reloj, órbita y seguridad. El motor ha crecido mucho más allá de ellos. Cada fila siguiente es un escenario incluido que puede ejecutar tal cual (cargo run -- <file> o kshana <file>); el resumen es la primera línea que kshana 0.35.0 imprimió para él el 2026-10-10. A diferencia de las cifras de los tutoriales, estas líneas son el registro de una ejecución, no están fijadas por tests/tutorials.rs: vuelva a ejecutar el escenario para obtener el valor actual. Los resultados declaran su propio alcance (la mayoría llevan un label), y la matriz de verificación indica qué capacidades están VALIDATED frente a una referencia independiente externa y cuáles están MODELLED.

LEO es órbita terrestre baja y MEO órbita terrestre media; PVT es posición, velocidad y tiempo; PPP es posicionamiento preciso de punto; 5G es el estándar móvil de quinta generación; TDB es el Tiempo Dinámico Baricéntrico; JD es la Fecha Juliana; TE es error de tiempo.

La CLI añade tres salidas a cualquier ejecución:

• Informes. Cada ejecución escribe <scenario>.report.html y <scenario>.report.json (véase REPORTS.md). kshana --study <suite.toml> ejecuta una suite de escenarios en un único .study.json y .study.html, por ejemplo kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> representa las series temporales de la ejecución; por ejemplo, --animate html sobre scenarios/orbit-sgp4-gps.toml escribe orbit-sgp4-gps.animation.html. Un tipo de escenario sin eje de tiempo muestreado (como solar-system) se rechaza con un error; véase ANIMATION.md.
• Exportaciones de interoperabilidad. --export <czml|kml|geojson|stk|sigmf|all|list> escribe el resultado para otras herramientas: CZML (Cesium Language), KML (Keyhole Markup Language, para Google Earth), GeoJSON (JSON geográfico), unas efemérides STK (Systems Tool Kit) o una grabación SigMF (Signal Metadata Format). --export list indica qué formatos se aplican a un escenario; SigMF se aplica solo a spectrum. El paquete de órbita también exporta --export-sp3, --export-omm y --export-oem (mensajes de órbita de CCSDS, el Comité Consultivo para Sistemas de Datos Espaciales). Véase INTEROP.md.

Ejercicios graduados#

Recorra la escalera. Cada nivel es más difícil y más defendible que el anterior; las soluciones de referencia están en exercises/.

Las soluciones de referencia usan la extensión de Python (antes, maturin develop --features python). Ejecutado desde la raíz del repositorio, tier2_sweep.py imprime el holdover del reloj atómico a escala de chip cayendo de 2610 s con una especificación de 20 ns a 1140 s con 5 ns.

¿Quiere datos nuevos?#

Las cifras principales de estos tutoriales se ejecutan por completo a partir de escenarios que ya están en el repositorio. No se descarga nada, lo que las mantiene reproducibles y seguras de ejecutar en integración continua (CI). Para los ejercicios de “ampliación” puede obtener datos en vivo:

• Elementos de dos líneas (TLE) de GPS (actualizan la constelación de órbita): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, conjuntos de elementos de 3 líneas en texto plano (nombre + línea 1 + línea 2). Auxiliar: scripts/fetch_tles.sh. Datos abiertos (catálogo del 18.º Escuadrón de Defensa Espacial de la Fuerza Espacial de EE. UU., redistribuido por Celestrak, Dr. T. S. Kelso).
• Referencia independiente de verificación de SGP4 (Simplified General Perturbations 4) (ya incorporada, no la vuelva a descargar): vectores de prueba de 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; véase docs/SGP4-VALIDATION.md.
• Referencia independiente de las relaciones de estabilidad de reloj: Publicación Especial 1065 del NIST (National Institute of Standards and Technology) (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, las relaciones entre σ_y(τ) y la fase en que se basa el Tutorial 2.