kshana 0.36.0

Kshana · क्षण · the precise instant
An open-source simulator for PNT (positioning, navigation and timing) resilience.

Rehearse the minute GNSS goes dark

Kshana replays jamming, spoofing and clock holdover when GNSS (Global Navigation Satellite System) signals fail, and tells you how long a system keeps time and position inside its budget, and which clock or sensor buys the most margin. This is the Python package: the engine in a notebook or a script. Every run is reproducible bit for bit from the scenario, the seed and the engine version.

Try it first with nothing to install: Kshana Studio runs the whole engine in your browser, compiled to WebAssembly, and uploads nothing.

Evidence

175 of 361 capabilities validated against independent external oracles; 182 honestly labelled Modelled, 4 partner-owned. Each capability carries one label in a machine-checked ledger: VALIDATED (an independent external oracle agrees: real data, an independent implementation or published reference vectors), MODELLED (internally consistent, and said out loud) or PARTNER (a hardware partner owns it). Among the checks: all 666 SGP4 (Simplified General Perturbations 4) vectors of AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 to 4.12 mm, and the Cowell force model to 0.08 m against Orekit 12.2.

Install

pip install kshana

Wheels are built on each release tag for Linux, macOS and Windows, each for x86-64 and 64-bit ARM, and one abi3 wheel per platform covers CPython 3.9 and newer. To build from source instead, use maturin: pip install maturin && maturin develop --features python.

Usage

The example is complete: it carries its own scenario, so it runs as written with nothing else on disk.

import json, kshana

# 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.
toml = """
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
"""

result = json.loads(kshana.run(toml))       # the full result document
print(result["quantum"]["fom"]["integrity"])

# The JSON result, the chart as SVG (Scalable Vector Graphics) and a one-line summary,
# all from one engine run:
result_json, chart_svg, summary = kshana.run_full(toml)
print(kshana.version(), summary)

Every other reference scenario is a file under scenarios/ in the repository; pass its text to kshana.run the same way. With the Rust command-line interface (CLI) installed, kshana example <name> prints each scenario bundled in the binary, and kshana example lists them.

Beyond run / run_full / version, the module exposes run_typed (a structured result object), validate_toml (lint → list of error strings), scenario_kinds (the dispatchable kinds as a Python list of dictionaries), list_kinds (the same metadata as one JSON string — kept as a string so existing callers do not break; call json.loads(kshana.list_kinds()), or use scenario_kinds() for the parsed list), and error_kind (the KshanaError tag for a rejected scenario) — see docs/PYTHON_API.md.

Every capability in the verification matrix is labelled validated (checked against an independent external oracle), modelled or partner-owned; optical-clock figures are space goals on ground hardware (no strontium optical clock has flown). Maturity is not uniform across domains — Earth PNT is validated against real data; deep-space and Mars navigation is modelled, with only its building blocks (light time, planet positions) validated against external oracles; real-mission deep-space OD (orbit determination) is on the roadmap.

Capabilities

The engine has 83 scenario kinds; kshana kinds lists them with their fields.

• Spectrum: how a jammer takes the GNSS L band, band by band.
• Clocks and timing: holdover against a threshold, time transfer, and telecom holdover against the masks of the International Telecommunication Union's standardization sector (ITU-T).
• Constellations around any body: coverage, dilution of precision and availability around the Earth, the Moon or Mars, and the solar system at one epoch.
• Low-Earth-orbit navigation: signal, pass and link, navigation message, and a fused fix, stage by stage.
• Campaigns: a chained mission, a sweep or a Monte Carlo ensemble in one scenario.
• Reports, animation and exports: every figure with its unit and label; an animated drawing of a run; SP3 (Standard Product 3), CCSDS (Consultative Committee for Space Data Systems) orbit messages, CZML (Cesium Language), KML (Keyhole Markup Language), GeoJSON, STK (Systems Tool Kit) and SigMF (Signal Metadata Format) files.
• Vessel GNSS trust (advisory, not type-approved navigation equipment): receiver_trust scores a receiver log described by a scenario; receiver_trust_replay scores a bounded NMEA excerpt the way the live command does; assess_vessel_log scores a vessel's NMEA log as a batch run. A 0-100 score with its reasons.
• Evidence packs: evidence_create and evidence_verify make and check a signed technical record of a log window; evidence_keygen makes a signing key (Python only, so the private key stays out of a page or an agent conversation); evidence_attach_timestamp binds an RFC 3161 timestamp token. A record, not a legal opinion.
• OSNMA: osnma_verify reports which satellites' Galileo navigation data an I/NAV page file or a UBX stream authenticates, given a trusted Merkle root or public keys and an optional independent reference time. It authenticates data; it is not a navigation integrity service and makes no anti-spoofing performance claim.
• Trust telemetry: trust_telemetry renders a trust stream or result as Prometheus text, CEF or LEEF syslog lines or an OTLP payload; nothing is sent.
• Training streams: nmea_training writes synthetic bridge NMEA and an instructor log for crew training. Text only; never for a vessel's live navigation systems; advisory, not type-approved navigation equipment.
• Interference map: interference_map builds aggregate degraded-navigation maps from public reports; route_exposure measures how much of a route falls inside them.
• Test bench and compliance mapping: bench_export writes a scenario's vehicle motion and events for a laboratory GNSS simulator (no signal is written); compliance_report fills the public-framework mapping from result documents and compliance_mapping returns the static tables.
• Examples, exports, animation and routes: list_examples and get_example (the bundled scenarios), export_formats, export_scenario, export_sp3, export_omm and export_oem, animate_scenario (an animated drawing, a player or frames) and import_route (a GeoJSON route into a terrain, gravity or combined scenario).
• GNSS IQ lab: iq_signals, iq_scene, iq_scene_broadcast, iq_acquire, iq_acq_surface, iq_info, iq_inventory, iq_sweep, iq_track, iq_loop_designs, iq_read_epochs, iq_monitor, iq_frontend, iq_test_conditions, iq_campaign, iq_campaign_report and iq_labfit for recorded and synthetic GNSS IQ.
• Core calls: run, run_full, run_typed, validate_toml, scenario_kinds, list_kinds, error_kind and version.

Architecture

The same scenario file gives the same bytes on every surface. MCP is the Model Context Protocol: kshana-mcp lets an AI (artificial intelligence) assistant run the engine.

Research

Five papers on arXiv are built on the open engine, each with the command behind it: arXiv:2606.22054 (the optimism gap of interference detectors), arXiv:2606.24210 (a conditional timing protection level), arXiv:2607.05415 (how stable a PNT resilience score is), arXiv:2607.02566 (lunar surface station observability with very-long-baseline interferometry) and arXiv:2607.06212 (lunar south-polar geometry and surface beacons). See Research.

Editions

The whole engine is free under the AGPL-3.0. Kshana Pro, a proprietary overlay that depends on the open engine and never forks it, and custom studies are available under contract from Ashforde® OÜ: contact@ashforde.org. There are no prices; see docs/PRO.md.

Learn more

• The full README → https://github.com/AshfordeOU/kshana
• Kshana Studio (the engine in your browser, as WebAssembly) → https://kshana.dev
• Capabilities → docs/CAPABILITY.md
• Validation and provenance → docs/VALIDATION.md · docs/PROVENANCE.md
• Verification matrix → docs/VERIFICATION-MATRIX.md
• Cite → CITATION.cff · DOI 10.5281/zenodo.20528627

Licence

Free and open source under the GNU AGPL-3.0-only (the GNU Affero General Public License, version 3 only). A commercial licence is available from Ashforde® OÜ (an Estonian private limited company; OÜ = osaühing) for closed integration; see LICENSING.md. Professionally developed and maintained by Ashforde® OÜ.