Kshana PNT-resilience simulator

Kshana · क्षण · the precise instant

An open-source simulator for PNT (positioning, navigation and timing) resilience.

Open Kshana Studio · Install · Capabilities · Evidence · Research · Documentation · Cite

Contents

• Rehearse the minute GNSS goes dark
• What's new in 0.39, What's new in 0.38, and 0.38 in depth: jammertest scoring, the receiver's own flags, machine inputs, timing and holdover, standards packs, LunaNet AFS, the lab round trip, kshana-bench, the observatory, exporters, optical, space-user navigation and lunar infrastructure
• Kshana Studio and every Studio page
• Capabilities: the table of areas, every scenario kind by family, every command, every surface
• How a run works, Missions
• Evidence: the ledger, capability domains
• Install, Architecture (and the diagrams), AI assistant
• Editions, Research, Cite, Licence
• Reference: usage, scenario format, output, repository layout, FAQ, troubleshooting, versioning, roadmap, contributing, documentation

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. It is one Rust engine. It runs in a terminal, a notebook, an IDE (integrated development environment), an AI (artificial intelligence) assistant, or in your browser.

Every run is reproducible bit for bit from the scenario, the seed and the engine version. Every capability carries one of three labels in a machine-checked ledger: VALIDATED (an independent external oracle agrees), MODELLED (internally consistent, and said out loud) or PARTNER (a hardware partner owns it).

Status: v0.39.0. A validated, reproducible simulation substrate for PNT resilience. Timing and holdover come first, because that domain is the best validated. Kshana is a study and trade-off instrument: not radio-frequency (RF) signal-generator hardware (it drives no radio and transmits nothing; its signal-level output is baseband IQ sample files for software receivers), not a hardware or certified GNSS receiver (its software receiver is an analysis tool) and not a flight product. New to the field? Start with the plain-language primer and the glossary.

What's new in 0.39

0.39 adds no feature and changes no result; the engine's output is the 0.38 output. It fixes one thing on the command line, updates dependencies of the cross-validation tooling, and states the benchmark verdicts in full.

• Command line. kshana kinds | head (any closed standard output) no longer panics: the program exits quietly with status 141, as other tools do for a closed pipe. Other write errors still report themselves.
• Dependencies. memmap2 0.9.11 in the two ANISE cross-check locks and pillow 13.0.0 and certifi 2026.10.19 in the oracle environment pins, all under xval/: nothing that ships changed.
• kshana-bench, all verdicts. Against the pre-registered bars, three are NOT MET, each pinned by a test: A2 (agc_k_sigma AUC 0.766 against at least 0.80), D1 (largest gap 0.0301) and task (b) R1 (carried, not re-run). No bar was loosened (Bench).

What's new in 0.38

0.38 makes the neutral referee measurable: it scores receiver logs against a published test schedule, reads more receivers and sensors, tests timing systems, and ships a benchmark and an interference observatory. It stays advisory: nothing here is certified, no result is a type approval, and nothing transmits. Each row states what the ledger holds for it (how a label is earned); a status names only what was checked, and the ledger row and the linked page say what was not.

0.37's highlights: changelog. The full 0.38 list is in the changelog.

0.38 in depth

Each capability from the table above, in a few lines: what it does, one command to run it, one picture drawn from a real run of the engine, and what the ledger holds for it. The pictures are written by tools/gen_figures_038.py into docs/figures/0.38/ (never drawn by hand): python3 tools/gen_figures_038.py rewrites them from a built engine, and --check fails if one is stale or its caption here differs. Where an input is a log, it is a made-up one the script writes, because the real third-party logs are never vendored, and the caption says so. Everything below is advisory: not certified, not a type approval, and nothing transmits. A status names what was checked and nothing more; how a label is earned.

Jammertest scoring

kshana jammertest import turns the published NPRA test catalogue and transmission plan into scheduled truth, and kshana jammertest score scores a receiver log against it: for each scheduled test, whether it was detected, how late, and how long the receiver took to recover, plus false alarms outside every slot. The catalogue is fetched, never vendored.

xval/jammertest-plan/fetch.sh ../jammertest-plan
kshana jammertest score session.toml --catalog ../jammertest-plan/testcatalog2025.json \
    --plan ../jammertest-plan/plan-tuesday-2025-09-16.json --location 1 --json

Ledger status: MODELLED. The bars were fixed before any scored run; on the JammerTest 2024 data the minimum-data rule failed in both runs, so no bar is assessable and nothing is claimed. Jammertest.

The receiver's own flags

UBX-NAV-STATUS spoofDetState, UBX-SEC-SIG and NovAtel RXSTATUS are read into a per-epoch self_report and set beside Kshana's alarms: both, receiver only, Kshana only, or neither. A Septentrio SBF reader and a read-only --serial input feed the same comparison. Neither side is ground truth.

kshana receiver-trust session.toml     # [log] format = "ubx", path = "receiver.ubx"

Ledger status: MODELLED. Agreement between a receiver's detector and Kshana's is not validation. Receiver trust.

More receivers and sensors

RTKLIB .pos, NovAtel OEM7, RTCM 3 MSM4/MSM7 C/N0, GNSS-SDR monitor streams, an IMU log as a second sensor, a ROS 2 package and a gnss_lib_py bridge all end in the same receiver-trust timeline. imu-fit reads the sensor parameters the hybrid and fusion scenarios need off a stationary IMU log, so a scenario can be run with the sensor you actually have.

kshana imu-fit still.csv --format csv --axis x --expected-mean 0 --id bench-imu

Ledger status: MODELLED. Self-written fixtures only; no capture from a real receiver, IMU, GNSS-SDR run or ROS graph was read. Machine inputs.

Timing and holdover tests

The holdover-test kind scores a holdover test (GNSS removed by the operator, holdover, recovery) from a measured time-error record against ITU-T masks, and says so in those words: measured against the mask. linuxptp and chrony log readers feed it; the hardware stages and the lab-attestation field say who stated what.

kshana scenarios/holdover-test-example.toml

Ledger status: MODELLED. The times GNSS was removed and restored are the operator's statement, not verified. Timing HIL, Hardware safety.

Standards packs

Scored packs for the DHS Resilient PNT test profiles, IMO MSC.1/Circ.1575 and ICAO Doc 9849 Appendix F, plus a NIST IR 8323r1 crosswalk in compliance-report. Each test runs a bundled scenario and compares a result field with a bar stated before the run; a test that needs a receiver log is listed as needing an input, not scored. The wording is "supports evidence for".

kshana standards-pack list
kshana standards-pack run imo-circ-1575

Ledger status: MODELLED. A met bar says a modelled scenario met a stated bar, nothing about a product; every miss is kept and pinned by a test. Standards.

LunaNet AFS

The LunaNet Augmented Forward Signal code generator (Gold, Weil and tertiary codes, the message frame and its error coding) and a checker for a recorded or generated symbol stream, pinned to one edition of the specification.

kshana lunanet-afs-check spec
kshana lunanet-afs-check generate --frames 2 --out afs.sym
kshana lunanet-afs-check symbols afs.sym

Ledger status: VALIDATED for the code and synchronisation checks, against the values the specification prints (which it marks TBC); one check is NOT MET, kept and pinned (one printed tertiary-code column differs: the document prints the same value for two PRNs). The LDPC and CRC words of subframes 2 to 4 are not checked. The ledger rows say exactly which. LunaNet AFS.

Lab round trip

kshana.test-conditions/1 is a published description of what a laboratory did (events, times, powers). kshana evidence round-trip links the scenario hash, the conditions hash, the receiver log hash and the score into one signed pack, and refuses a pack whose conditions and scoring scenario disagree about the events. Kshana never produces or replays a signal: how a scenario reached a receiver is the operator's responsibility.

kshana evidence --help

The picture is the layout of a pack. Ledger status: MODELLED. Test conditions, Test bench.

kshana-bench

Fixed tasks, splits and metrics for interference detection, IQ detection, holdover prediction and the optimism gap, with a sealed holdout and a static leaderboard. It scores submissions; it is not a ranking of receivers.

kshana bench baseline --task d --split test --out results/

Ledger status: no ledger row of its own; the baselines are labelled MODELLED in the result files. Against the pre-registered bars the scorer, C1 to C3 and D2 are met and three bars are NOT MET, each pinned by a test: A2 (agc_k_sigma AUC 0.766 against at least 0.80 on the test split), D1 (largest gap 0.0301) and task (b) R1 (carried from the earlier campaign, not re-run). The figures are in xval/bench/RESULTS-v2.md. Bench.

Interference observatory

One product per UTC day and region from an open aircraft-position archive, on a fixed coarse grid: each cell is degraded, not degraded, or not observed (which is not "clear"). Released no earlier than 24 h after the day ends, with small cells suppressed and no attribution of cause.

kshana interference-map daily /path/to/extracted/2026-09-15 \
    --dataset adsb-lol --day 2026-09-15 --bbox 53.5,9.0,66.0,31.0 --out products/

The picture is the committed sample days, not an observatory product. Ledger status: MODELLED: no external oracle, no ground truth and no cause attribution; a cell that is not observed was not assessed, which is not the same as clear. Observatory method.

Exporters

Trust telemetry as Prometheus text, CEF, LEEF, OTLP and Home Assistant MQTT discovery and state messages. The command publishes only to a destination you give it and holds no credentials.

kshana trust-telemetry --result session.result.json --print-metrics
kshana trust-telemetry --result session.result.json --print-syslog --format cef

Ledger status: MODELLED. Trust telemetry.

Optical link margin against time

The optical-atmosphere kind can write one seeded realisation of a site's weather as a link-margin series: cloud episodes, a liquid-water column for each, one scintillation sample per step. The Studio's Optical PNT page opens the optical-atmosphere scenarios.

kshana scenarios/optical-atmosphere-network.toml

Ledger status: MODELLED. One draw from the model, not the climate. Optical atmosphere.

New Studio views

kshana.dev/studio gains a Bridge replay (two runs side by side on one mission clock, at /studio/replay/), an Optical PNT page (/studio/optical/), a Holdover test page (/studio/holdover/) and an observatory viewer (/studio/observatory/). They run the same engine in the browser, nothing is uploaded, and they carry the same advisory statement. The pictures above are drawn from the engine's own output by a script; they are not screenshots of these pages.

Space-user navigation (gnss-ssv)

For a spacecraft above, around or far past the GNSS orbits: how many GNSS signals it can use, how strong they are, how good the geometry is, and what an onboard filter can do with them. One kind, four modes, chosen by the scenario's tables: a shell of users (the share of time with one and four signals, per constellation), a trajectory (signals, C/N0, dilution of precision and the limb-ray medium along an orbit), a navigation run (a nine-state filter on pseudoranges, to the Moon) and a formation (relative navigation of deputies about a chief). The public source for the availability comparison is the interoperable GNSS Space Service Volume booklet (UN OOSA ST/SPACE/75, from the International Committee on GNSS), which is itself a simulation; it is fetched, never vendored. Full page: docs/SSV.md.

kshana scenarios/gnss-ssv-shell.toml            # shell: the upper space service volume, reduced size
kshana scenarios/gnss-ssv-heo.toml              # trajectory: a high Earth orbit, limb medium
kshana scenarios/gnss-ssv-nav-lunar.toml        # navigation: an onboard filter toward the Moon
kshana scenarios/gnss-ssv-formation-heo.toml    # formation: relative navigation

Ledger status: MODELLED, and the comparison with the booklet mostly misses. The bars were fixed before the run. Of eight, only S0 (the inverse link budget, 13 of 13 values) and S6 (the lunar mission) are met. S1 to S5 and S7 are NOT MET: the upper and lower service volume geometry (43 of 52 and 48 of 52 cells), the 15/20/25 dB-Hz upper service volume, the six GEO missions, the HEO mission, and the parametric sidelobe pattern against measured GPS panel patterns. Almost every miss in S1 to S5 involves GLONASS, and the booklet prints two different reference angles for it; a diagnostic variant that uses the other pair brings S1, S2 and S4 to every cell, but it does not replace the run of record and no row is VALIDATED. The formation run's absolute filter is also overconfident (mean normalised error squared well above the value of about 3 that a consistent filter gives).

Space-user navigation, what the comparison shows.

Lunar infrastructure (lunar-infrastructure)

The Moon's orbit and surface as navigation and geodetic infrastructure, in five studies chosen by study: od-consistency (an onboard Earth-GNSS orbit determination in a halo orbit against an independent ground one), carrier-phase (integer ambiguity fixing between surface stations and an orbiter), frame-coestimation (the lunar datum from Earth-station ranging with and without orbiter links), space-tie (laser, VLBI and GNSS offsets on one spacecraft against the local-tie error) and geodesy-sensitivity (which observable family sees the Love numbers h2, k2 and l2). The model is a restricted three-body one with stated simplifications and illustrative inputs. Full page: docs/LUNAR-INFRASTRUCTURE.md.

kshana scenarios/lunar-infrastructure-od-consistency.toml
kshana scenarios/lunar-infrastructure-carrier-phase.toml            # quick; the scored run takes about eight minutes
kshana scenarios/lunar-infrastructure-frame-coestimation.toml
kshana scenarios/lunar-infrastructure-space-tie.toml
kshana scenarios/lunar-infrastructure-geodesy-sensitivity.toml

Ledger status: MODELLED, and three bars are NOT MET. The numerics are checked against independent numpy and scipy programs; nothing is compared with a measurement of a lunar quantity, and nothing is VALIDATED. Met: the two orbit solutions are consistent (mean q 5.81 against 6 expected), and orbiter links raise the smallest datum eigenvalue about 111-fold, assuming a known orbit. Not met: the injected 3e-10 m/s2 model error is not detected (C3: the onboard solution is known to about 350 m, so about ten metres hides in its covariance); integer fixing is not achieved (1 to 3 % success at 25 dBi, and at the registered 12 dBi the problem cannot be formed); and the trace half of G3 for adding an observable family (the trace rose in 12 of 28 additions, each time because the family raised the rank). Each miss is pinned by a test. Lunar infrastructure.

Kshana Studio

Open kshana.dev/studio and the whole engine runs in your browser, compiled to WebAssembly. Nothing to install, and nothing is uploaded. The Studio has two views of the same engine, and a switch in the header moves between them, keeping the scenario, the view and any settings you changed.

The Simple view is where the Studio opens. It starts from questions (how many satellites can I see, can I trust my position fix, how long can a clock keep time, what does a jammer do to my receiver) and from a map of everything the engine can do, each area with its share of validated methods. Open a scenario and the answer comes first: one plain sentence, written for what that scenario measures, then its key figures and a chart. At most five settings are on show, the ones that change the answer most; the rest wait under Advanced settings. How this is computed explains the method, and For researchers gives the engine's own figures, the scenario file, the code to run it from Python and the citation.

The Advanced view is the full dashboard: the scenario library, five numbered steps (Choose, Set, Run, Read results, Share or export), the key figures with PASS and FAIL chips where the run states a threshold, and every panel: overview, charts, maps, replay, the engine's report and exports. One search box reaches scenarios, domains and the fields inside them, and you can pin up to four runs and compare them side by side.

The Simple view's opening screen, and the Advanced view after a run

The Studio's source and its build notes are in web/README.md.

The site

The rest of kshana.dev is built from this repository's own files and engine runs: missions, capabilities, the evidence ledger, the published research and the editions.

Capabilities

One engine covers the whole failure chain, from the first jammed satellite to the last nanosecond of clock holdover. The engine has 87 scenario kinds; kshana kinds lists them and docs/SCENARIOS.md documents every field.

The export formats in full: SP3 is Standard Product 3; CCSDS OMM and OEM are the Orbit Mean-elements and Orbit Ephemeris Messages of the Consultative Committee for Space Data Systems; CZML and KML are the Cesium and Keyhole Markup Languages; STK is Systems Tool Kit; SigMF is the Signal Metadata Format.

Each capability, drawn from a real run: the L-band waterfall, the coverage map, the solar system and a low-Earth-orbit pass

Run any of them with kshana example <scenario> > s.toml && kshana s.toml: the scenarios are l-band-waterfall-jamming, constellation-multi-gnss-coverage, solar-system-tour and leo-pass-iridium.

The maritime and interference capabilities, drawn from committed synthetic inputs: a trust score, an interference map with route exposure, a training stream and an evidence pack

All four are made-up data and advisory: they show the format and the behaviour of the software, not how any receiver or system performs against interference. Run the first with kshana receiver-trust examples/maritime-trust/session.toml, the second with kshana route-exposure on the samples in examples/interference-map/, the third with kshana nmea-scenario scenarios/training/coastal-drag-off.toml --out drag.nmea (training use only: never feed it to live navigation equipment), and the fourth as in docs/EVIDENCE-PACKS.md.

The full capability table, domain by domain

The full domain-by-domain detail follows; for a per-capability maturity ledger see docs/CAPABILITY.md and docs/VALIDATION.md.

Each capability is reachable as a Rust API, a runnable scenario kind, or both. Maturity per capability — validated, runnable, or library — is tracked in docs/CAPABILITY.md. A machine-checked verification matrix (src/verification.rs) renders the requirement → module → test → oracle → status cross-reference, with unit-tested honesty invariants that permit a validated label only where an independent external oracle backs it — and that record the hardware/PA (product-assurance) capabilities Kshana deliberately does not provide.

The four sensor packs, as first published (results)

Results

Each scenario compares a quantum sensor against its classical counterpart through a ~1.8 h GNSS outage. Numbers are reproducible (scenario + seed + version).

What quantum sensors buy when GNSS is gone — clock-holdover · seed 42 · drawn at engine 0.39.0, and every figure above re-checked against the current engine on each build by tests/published_figures_still_reproduce.rs · SVG

The advantage is outage- and vibration-dependent, with an explicit break-even where classical wins — shown honestly across the technology-readiness ladder (optical-clock figures are ground-demonstrator targets; no strontium optical clock has flown):

Quantum-vs-classical resilience crossover — clock holdover TRL ladder (top) · inertial advantage map with break-even contour (bottom). Regenerable via cargo run --release --bin crossover_study.

Dead-reckoning position error during a GNSS outage: the quantum sensor (blue) stays flat near the spec; the classical sensor (red) diverges to tens of kilometres. Generated by Kshana from scenarios/imu-deadreckoning.toml.

The capstone shows the fusion thesis: optical inter-satellite time-transfer keeps even a classical clock locked, isolating the inertial sensor as the classical suite's weak link — i.e. quantum inertial + optical timing together.

Clock holdover through a GNSS outage: the optical clock (blue) stays inside the 20 ns spec for the full coast; the chip-scale clock (red) breaches it part-way. Generated by Kshana from scenarios/clock-holdover.toml.

A further scenario, orbit-gnss-challenged.toml, derives GNSS availability from orbital geometry rather than hand-authored windows: a spacecraft inside the GNSS shell is propagated against a GPS-like Walker constellation, and the visible-satellite count (line-of-sight, Earth-occultation, elevation mask) sets the fix state at each step. Over a day the user is in fix only ~59% of the time; the quantum clock holds a 5 ns timing solution through every gap (availability 1.0), the chip-scale clock only ~0.83.

Timing error over a day with GNSS availability derived from orbital geometry: the visible-satellite count (line-of-sight, Earth-occultation, elevation mask) sets the fix state at each step, so the clock must coast every gap — the optical clock holds the 5 ns spec while the chip-scale clock breaches it. Generated by Kshana from scenarios/orbit-gnss-challenged.toml.

The constellation can also be given as real two-line element sets (TLEs). A full TLE (line 1 + line 2) is propagated with the full SGP4/SDP4 model — including atmospheric drag and the deep-space lunar-solar and 12 h / 24 h resonance terms that matter for ~12 h GNSS orbits — validated against the official AIAA 2006-6753 vectors to a worst-case ≈ 4 mm. scenarios/orbit-sgp4-gps.toml ships a real Celestrak gps-ops snapshot of the operational GPS constellation (2021-07-28, 30 satellites) and requires valid TLE checksums — two-line element sets are open data from the US Space Force / 18th Space Defense Squadron catalogue, redistributed by Celestrak (Dr T. S. Kelso, celestrak.org); refresh with scripts/fetch_tles.sh. A line-2-only block keeps the analytic two-body propagation (scenarios/orbit-real-tle.toml); the two forms can be mixed in one constellation. A constellation can equally be built from a block of RINEX-3 GPS broadcast-ephemeris records — the format a receiver decodes — propagated by the IS-GPS-200 user algorithm and fed through the same geometry (scenarios/orbit-rinex.toml).

What it is / is not, in full

What it is / is not

It is: a deterministic, dependency-light engine spanning the PNT stack — orbit geometry, inertial navigation, GNSS/INS fusion, integrity, clocks, and timing. It runs a scenario (often a GNSS outage), evolves calibrated sensor error models through the appropriate estimator, and scores the result against the operational figures of merit — emitting a reproducible JSON (JavaScript Object Notation) result and an SVG chart, from a Rust library, a command-line interface (CLI), a Python extension, an in-browser WebAssembly module, a Model Context Protocol (MCP) server for AI agents, or a JetBrains IDE (integrated development environment) plugin.

It is not: flight hardware, a quantum-payload design, a full GNSS signal receiver, a radio-frequency (RF) signal simulator or hardware-in-the-loop rig, or a certified avionics product — and it does not replace MATLAB/Simulink, STK (Systems Tool Kit) or Orekit; it sits next to them and exchanges files with them. Quantum-hardware fidelity comes from published error models, not from this tool. The granular maturity of each capability is documented in docs/CAPABILITY.md.

It is not (yet): a full atom-interferometry physics engine (most quantum sensors consume published Allan/noise-budget coefficients; the CAI (cold-atom interferometer) accelerometer has a first-principles layer — Mach–Zehnder phase, projection noise, contrast decay, and vibration coupling, plus Coriolis and light-shift systematics — but wavefront systematics and fringe-ambiguity resolution remain a P2 (roadmap phase 2, the quantum physics layer) roadmap layer, see ROADMAP.md and docs/QUANTUM-MODELS.md); a certified or hardware GNSS receiver (it solves a single-point PVT (position, velocity and time) position fix from real RINEX (Receiver Independent Exchange Format) code observations — validated on real IGS (International GNSS Service) data — and its IQ layer (kshana iq, since 0.31.0) acquires and tracks recorded or generated baseband samples in software, as an analysis receiver: it does not drive radio hardware or transmit, is not a certified receiver, and does no carrier-phase positioning (RTK or PPP)); or a full mission-design suite (it has Lambert / porkchop / maneuver / orbit-determination building blocks, but is the performance-simulation layer above GMAT (General Mission Analysis Tool)/Orekit, not a replacement). Owning this scope is deliberate. If you need first-principles cold-atom interferometer error budgets (e.g. CARIOQA-PMP-grade — Cold Atom Rubidium Interferometry in Orbit for Quantum Accelerometry, Pathfinder Mission Preparation — or X-37B-style validation), see the P2 roadmap and get in touch to collaborate.

Low-Earth-orbit navigation

Low-Earth-orbit (LEO) satellites pass fast and loud. The leo-pnt-chain kind follows one system through every stage: the signal, the pass and its link, the navigation message, and the fused position, velocity and time (PVT) fix and precise point positioning (PPP). Each stage hands its numbers to the next. See docs/LEO-PNT.md.

Every scenario kind by family

The engine's scenario kinds, filed under families. Each family has a page with one entry per kind (the engine's description and fields, an example command, headline numbers from a run, the verification matrix rows that name it, and the chart the engine itself writes) and a contact sheet of those charts; docs/KINDS.md indexes them all. The table is written by tools/gen_readme_blocks.py and the pages by tools/gen_kinds_index.py, and both fail if the engine gains a kind no family names.

Every command

kshana <scenario.toml> runs a scenario; every other command is a subcommand, and kshana --help prints the usage of all of them. The commands are --study, --validate, kinds, example, receiver-trust (with live and evidence), evidence (keygen, verify, attach-timestamp, round-trip), jammertest (import, score), trust-telemetry, imu-fit, nmea-scenario, interference-map (adsb, ais, daily, sensitivity, fetch-land), route-exposure, bench (spec, truth, cases, score, baseline, seal, reveal-check, manifest, verify-manifest, validate, leaderboard), bench-export, compliance-report, lunanet-afs-check, standards-pack, osnma, iq (scene, acquire, track, sweep, labfit, campaign, conditions, frontend, monitor, inventory, info, extract, convert, decimate), sky and skyline. docs/COMMANDS.md gives each one's purpose, a verified example and its docs page.

Every surface

One engine, the same results everywhere: the command line, the Rust library, Python, JavaScript and WebAssembly, the MCP server with its plugin commands and skills, Kshana Studio (every page runs in the browser, no install, nothing uploaded), the ROS 2, Signal K, OpenCPN, GNSS-SDR and gnss_lib_py integrations, the systemd, Docker and Grafana deploy kits, and the JetBrains plugin. docs/ALL-SURFACES.md lists them with how to get each and the names of all the plugin commands, skills and Studio pages; docs/SURFACES.md says, for every command and kind, which surface carries it and which do not, with the reason.

How a run works

A scenario is a TOML (Tom's Obvious, Minimal Language) file: a kind, a seed and the parameters. The engine runs it and writes the result, a chart and a report beside it, and the exports you ask for.

This bundled scenario runs 2 h: 10 min of GNSS, then about 1.8 h with GNSS denied. It asks how long a strontium optical lattice clock and a chip-scale atomic clock (CSAC) each hold time to within 20 ns.

kshana example clock-holdover > clock-holdover.toml
kshana clock-holdover.toml

scenario 5ba83a232b94 | quantum holdover 6600s p95 1.20e-4ns integrity 1.000 security n/a (no attack) | classical holdover 2610s p95 19.7ns integrity 1.000 security n/a (no attack)
wrote clock-holdover.result.json, clock-holdover.chart.svg, clock-holdover.report.html, and clock-holdover.report.json

The optical clock holds the 20 ns budget for the whole 6600 s outage; the CSAC holds it for 2610 s, and is inside the budget for 95.6% of the run against 100% for the optical clock. kshana example lists every bundled scenario.

Missions

Ten sectors ask ten different questions of the same engine. Each has bundled scenarios to start from.

The question each sector asks

Evidence

176 of 388 capabilities validated against independent external oracles; 208 honestly labelled Modelled. Each row of the verification matrix names a capability, the oracle it is checked against, the test that runs the check, and the label that follows. Continuous integration (CI) makes it impossible to call a capability VALIDATED without an independent external oracle.

A few of the checks: all 666 AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 SGP4 (Simplified General Perturbations 4) vectors to 4.12 mm; the Cowell force model to 0.08 m against Orekit 12.2; Galileo to 0.61 m and Swarm-A to 0.10 m against real precise ephemerides of the European Space Agency (ESA). Tests hold near 95 % line coverage of src/, gated at 85 % in CI. The ledger is docs/VERIFICATION-MATRIX.md, generated from src/verification.rs: the full 388-row matrix, and why each Modelled row has no external oracle in docs/MODELLED-RATIONALE.md.

How validation works, the curated highlight table and the evidence figures

Validation, reproducibility & honesty

• Every noise term is calibrated to a published, cited figure and validated against the standard relation (Allan deviation for clocks; Groves' dead-reckoning error growth for inertial; the timing→ranging conversion for time transfer). Status per term is tracked in docs/VALIDATION.md as validated or not modeled — nothing is presented as validated that is not.
• Reproducible by construction: scenario + seed + engine version → identical bits. scripts/check-reproducible.sh enforces it; quantum and classical runs use independent seeds so their noise is uncorrelated.
• Maturity is stated honestly: optical-clock and optical-link figures are targets / ground-demonstrator results, not flown.

Validation at a glance

Every row is enforced by a named test in CI. This table is a curated highlight; the full machine-checked matrix is 388 rows — 176 VALIDATED, 208 MODELLED, 4 PARTNER (src/verification.rs), with the complete evidence (and what is honestly not yet validated) in docs/VALIDATION.md and the per-release kshana-validation-summary.html artifact (generated by cargo run --bin validation_report, SLSA-attested — Supply-chain Levels for Software Artifacts).

The Status column states the kind of evidence, matching the validation ladder above: VALIDATED = checked against an independent external oracle (real data, an independent library, or published reference vectors); MODELLED = checked against analytic truth or simulation self-consistency (no independent external dataset). VALIDATED describes the method of checking, not a pass/fail — an honest miss against a real external oracle stays VALIDATED, while a comparison that no matrix row names as an oracle (the LRO — Lunar Reconnaissance Orbiter — fit above) is shown as MODELLED. CI rows are process guards, not figures of merit. A few real-data islands (the measured caesium clock, Stable32 PHASE.DAT, and the OPS-SAT/ICGEM checks where the raw inputs carry no redistribution licence) are data-gated: the test prints a skip notice and stays green when the input is absent, and the public reference numbers are committed under tests/fixtures/. Reproduce the raw inputs with the matching scripts/fetch_*.sh.

How a capability earns its label — the CI-enforced invariant: no external oracle ⇒ cannot be Validated · SVG

Top: every Validated row is backed by an external dataset, by construction. Bottom: SGP4 matches the official reference in every regime (worst 4.12 mm). SVG · SVG

176 Validated · 208 Modelled · 4 Partner — SVG

Capability domains

Every capability of the public map, by domain, with its ledger label. The domain table is written by tools/gen_readme_blocks.py from web/capabilities.json, the same file the Studio's map of everything reads.

The full table, domain by domain with every capability and its label, is docs/CAPABILITY-DOMAINS.md.

Install

One line gets the command-line tool: cargo install kshana. Every channel ships v0.39.0 from the same tagged commit.

MCP is the Model Context Protocol. Pin a release with cargo install kshana --version 0.39.0, pip install kshana==0.39.0 or npm install kshana@0.39.0. To build from source, see Install and build under Reference.

Run a scenario from Python and from WebAssembly

import json, kshana

toml = open("clock-holdover.toml").read()
result = json.loads(kshana.run(toml))
print(kshana.version(), result["quantum"]["fom"]["holdover_s"], result["classical"]["fom"]["holdover_s"])
# 0.39.0 6600.0 2610.0

Beyond run, the module exposes run_full (JSON, SVG and the one-line summary at once), run_typed, validate_toml, list_kinds / scenario_kinds and error_kind; see docs/PYTHON_API.md.

The npm package is the whole engine compiled to WebAssembly. In Node.js, hand the binary to initSync; in a browser, await init() fetches it (see README.npm.md).

import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { initSync, run, summary, version } from "kshana";

const wasm = createRequire(import.meta.url).resolve("kshana/kshana_bg.wasm");
initSync({ module: readFileSync(wasm) });

const toml = readFileSync("clock-holdover.toml", "utf8");
const result = JSON.parse(run(toml));
console.log(version(), result.quantum.fom.holdover_s, result.classical.fom.holdover_s);
// 0.39.0 6600 2610
console.log(summary(toml));

Architecture

One open engine sits at the centre, and every surface runs it: the command line, the Rust library, Python, WebAssembly and Kshana Studio, the MCP server, the Docker image and the JetBrains plugin. The same scenario file gives the same bytes on each. Kshana Pro sits on top as a separate overlay that depends on the engine and never forks it.

Inside the engine: the domain layers and the verification ledger

One engine, many front doors. A single Rust core (kshana) runs every scenario, reached through a CLI, a Python extension, an in-browser WebAssembly module, an MCP server for AI agents, and a JetBrains IDE plugin — all converging on one api::run_toml dispatch. Inside, the sensor packs plug into a common error-model interface; alongside them sit a reference-frame layer (IAU 2006/2000A precession–nutation and the CIO-based GCRS↔ITRS reduction), an astrodynamics/numerical layer (analytic SGP4/SDP4 and a numerical Cowell propagator with its EGM2008/perturbation force model, maneuver design, and orbit determination), an integrity/GNSS layer (RAIM/ARAIM, SBAS, the measurement domain, jamming, cislunar), a fusion / alt-PNT layer (the GNSS/INS estimators and the gravity/terrain/magnetic map-matchers), a deep-space & lunar layer (radiometric Mars-PNT and the lunar PNT suite, its evidence tier per piece in the matrix — LTC time, VLBI, joint OD+clock, frame realisation, service-volume, differential PNT, interop), a mission-analysis layer (launch / re-entry / coverage / pointing / pass / link budgets and the space-weather environment), and the open resilience & AI/ML study layer (RPCF resilience scoring, the RF-impairment optimism gap, and the quantum-enabled PNT demonstrator) whose reproducible artifacts ride the validated kernels.

Two standalone, workspace-excluded crates sit beside the core — mcp/kshana-mcp (the MCP server, built on the edition-2024 rmcp SDK) and xval/anise-frames (the ANISE/SPICE frame cross-check, which pulls MPL-2.0 (Mozilla Public License 2.0) deps) — kept out of the published crate's dependency graph, Cargo.lock, license gate, and MSRV (minimum supported Rust version) build by the root Cargo.toml exclude list. The JetBrains plugin (ide/jetbrains) is a separate Kotlin project. See docs/ARCHITECTURE.md for the full set of diagrams.

The rendered diagrams (engine flow, module map, distribution) are in docs/ARCHITECTURE.md.

Diagrams

The diagrams are Mermaid sources in docs/diagrams/, rendered to SVG and PNG into docs/assets/diagrams/ (tools/render-diagram-chromium.sh <name> on Linux, the other two render-diagram scripts elsewhere), and a record binds each PNG to the exact SVG it came from. Tests pin the counts they state. The charts in the sections above are drawn by tools from engine runs; these show how the parts fit.

One dispatch, one engine, reproducible output · SVG · source system-overview.mmd

Every surface, from the same engine · SVG · source surfaces.mmd

The inner loop of a run · SVG · source engine-flow.mmd

From a receiver log to a trust score and what uses it · SVG · source trust-flow.mmd

Scenario to signed pack; Kshana never produces or replays a signal · SVG · source lab-round-trip.mmd

How Studio runs, locally · SVG · source studio-flow.mmd

Test and release flow, from local gates to a verified release and the site-only path · SVG · source release-flow.mmd · docs/RELEASING.md

Where the code lives · SVG · source module-map.mmd

What ships where, and what checks it · SVG · source distribution.mmd

AI assistant

kshana-mcp is an MCP server: your assistant runs the actual engine and reads back its JSON, instead of guessing the maths. Each of its 49 tools is a thin wrapper over a public function of the kshana library, so no simulation logic lives in the server.

Install the MCP server

Advisory, not type-approved navigation equipment: the operator remains responsible for navigation. The server runs on your computer; nothing is sent to Ashforde OÜ.

Pick any channel. Every link and snippet is generated from one script (scripts/gen_mcp_install.py) and checked in continuous integration; snippets for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Goose, Codex CLI, Gemini CLI and Continue are in docs/MCP-INSTALL.md.

In Claude Code the same server arrives as a plugin: /plugin marketplace add ashfordeOU/kshana, then /plugin install kshana@ashforde. The plugin adds slash commands over the tools: /kshana-run, /kshana-assess-receiver, /kshana-evidence-pack, /kshana-interference-map, /kshana-training-scenario, /kshana-bench-export, /kshana-compliance-report, /kshana-iq, /kshana-import-route, /kshana-marine-integrations and /kshana-jammertest. The vessel-trust tools feed the Signal K and OpenCPN integrations: docs/MARINE-INTEGRATIONS.md.

Per-client set-up is in docs/integrations.md. The server is listed in the official MCP registry as io.github.ashfordeOU/kshana-mcp.

The 49 tools

Scenarios and reports

Export and interoperability

Receiver and vessel trust

GNSS IQ (work-directory files; off in HTTP mode)

Compliance mapping

Benchmark

Editions

The whole engine is free. Kshana Pro and custom studies are for programmes that need more, and every paid route starts with a message: there are no prices here.

What Pro is, in the words of docs/PRO.md:

A strict superset of open Kshana. Pro depends on the open engine as a library and never forks it. Every open scenario kind runs in Pro unchanged, and an open scenario runs in Pro with no licence at all.

No new physics. Pro adds no physical model and changes none. Every Pro number comes from runs of the open engine, so a Pro figure is as trustworthy as the open scenario kind it came from, and never more.

Pro answers a programme's next questions: which design to fly (a design optimiser and its Pareto front), how sure the answer is (uncertainty and sensitivity), and whether the mission meets its requirements (a mission dossier, requirements traceability, trade studies, a scenario regression check, clock digital twins, a study dossier and an on-premises service). It also watches a campaign of figures and fails a pipeline when one gets worse, tests candidate signal plans against the open satellite-navigation signals in both directions (spectrum coexistence), and queues studies in an on-premises job service with a hash-chained delivery ledger. Each is described, with what it produces and what it does not do, in docs/PRO.md. Nothing Pro produces is a certification, and a custom study is not a certification either.

What Kshana Pro reads from the open engine, and support from Ashforde® OÜ

What Kshana Pro builds on. Every part of Pro works from the open engine and leaves it unchanged:

• The design optimiser, the uncertainty study and the mission dossier run open-engine scenarios through the engine's public interface and compute every number from the runs' results. Each output keeps the VALIDATED, MODELLED or PARTNER tier the open engine gave each figure, never a higher one.
• Clock digital twins use the open engine's clock model and its Allan-deviation estimator: a twin is calibrated to the device's published Allan budget, then checked by estimating the twin's Allan deviation with the open estimator.
• Trade studies run every architecture option as an open-engine scenario, unchanged, and rank the options on a figure of merit read from each run's result.
• Campaign watch reads its figures from the results of open-engine runs of the scenarios in a pack, and compares them with the previous passing run.
• Spectrum coexistence reads every physical number from open-engine runs of the leo-signal and constellation-design kinds, and adds only the sum over the satellites in view and the ranking of the plans.
• The on-premises job service runs open and Pro scenarios through the same engine and stores each result as the run returned it.
• Evidence packs record, for each run, the scenario hash the open engine stamps on its result, so a figure in a pack can be reproduced by re-running its scenario.
• Systems-engineering and programme tooling. Kshana Pro's model-based systems-engineering (MBSE) and programme tooling checks a programme's requirements against runs of the open engine: it imports requirements as comma-separated values (CSV), or as a documented subset of the Requirements Interchange Format (ReqIF) or of Systems Modeling Language version 2 (SysML v2) text, evaluates each acceptance criterion, with its unit, against the values a run wrote, and produces a verification cross-reference matrix (VCRM), a SysML v2 model, a change-impact report and an offline evidence pack. It re-runs and recomputes nothing, and reads only what the open engine publishes: each run's result.json (the fields a criterion names, their units, the reproducibility stamp of scenario hash, seed, engine version and schema version, and the run's label and figure tiers), its report.json (kind, reproducibility record and capability labels), the scenario file (its hash, kind, seed and parameters), the field-units schema (each field's unit, provenance and evidence tier) and the verification matrix (each capability's VALIDATED, MODELLED or PARTNER label).

Support & professional services

Kshana is free and open source under the AGPL-3.0 and professionally developed and maintained by Ashforde® OÜ (Estonia). The open engine is complete and usable on its own. For organisations that need more, Ashforde® OÜ offers:

• Commercial support & integration — embedding Kshana in your toolchain, custom scenarios, and priority fixes.
• Custom sensor models — calibrated to your hardware, including export-sensitive resilience models maintained in a private overlay.
• Kshana Pro — proprietary model-based systems-engineering (MBSE) and programme tooling that checks a programme's requirements against runs of the open engine and produces a verification cross-reference matrix (VCRM), a Systems Modeling Language version 2 (SysML v2) model, a change-impact report and an offline evidence pack. It re-runs nothing and reads only the engine's published outputs: each run's result.json and report.json, the scenario file, the field-units schema and the verification matrix's labels (the full list is under Editions).
• Kshana Pro design, uncertainty and mission tooling — the Pareto front of a design space, uncertainty and sensitivity over thousands of runs, and a one-command mission dossier with a verification matrix and a PDF; see docs/PRO.md.
• Kshana Pro campaign watch, spectrum coexistence and job service — a pipeline that fails when a watched figure gets worse, signal plans tested against the open satellite-navigation signals in both directions, and an on-premises job queue with a hash-chained delivery ledger; see docs/PRO.md.
• Training & consulting on quantum/classical PNT performance analysis.

This is the open-core model: the engine is, and stays, openly licensed; the sustaining business is expertise, support, and the proprietary extensions — not license fees. Contact contact@ashforde.org · ashforde.org.

Research

Studies built on the open engine are published on arXiv. Each names the engine command behind it, so its numbers can be regenerated from a committed scenario or study example.

The three study examples write byte-deterministic artifacts (fixed seeds) that record their engine version, seeds and a configuration hash. The three lunar and cislunar papers are built on the lunar suite (each piece's evidence tier is in the verification matrix); their geometry and dilution-of-precision claims are also cross-checked against separate oracles in tests/validate_p*.rs. More in Reproducible study artifacts under Reference.

Cite

If you use Kshana in academic or technical work, please cite the version you used, with the scenario and seed. CITATION.cff holds the machine-readable metadata, and GitHub shows a "Cite this repository" button from it. Every release is archived on Zenodo; the concept DOI (Digital Object Identifier) 10.5281/zenodo.20528627 always resolves to the latest version.

Baweja, C. (2026). Kshana — a PNT-resilience simulator with quantum-sensor performance models. Ashforde OÜ. https://doi.org/10.5281/zenodo.20528627

The papers above:

Baweja, C. (2026). Anticipating the Optimism Gap: Predicting Distribution-Shift Degradation of RF-Impairment Detectors from In-Distribution Statistics. arXiv:2606.22054. https://doi.org/10.48550/arXiv.2606.22054

Baweja, C. (2026). A Conditional Timing Protection Level: Holdover-Limited Undetected Time Error Under GNSS Spoofing. arXiv:2606.24210. https://doi.org/10.48550/arXiv.2606.24210

Baweja, C. (2026). How Stable Is a PNT Resilience Score? Decision-Instability of Single-Number Resilience Ratings under Framework-Aligned Weighting. arXiv:2607.05415. https://doi.org/10.48550/arXiv.2607.05415

Baweja, C. (2026). Earth-baseline VLBI restores the observability of a lunar surface station in joint orbit-and-clock determination. arXiv:2607.02566. https://doi.org/10.48550/arXiv.2607.02566

Baweja, C. (2026). The Cost of Lunar South-Polar Geometry, and Surface Beacons as the Efficient Fix: A Dilution-of-Precision Analysis. arXiv:2607.06212. https://doi.org/10.48550/arXiv.2607.06212

Baweja, C. (2026). Cislunar navigation is an observability problem: arc-length thresholds, Gramian conditioning, and the Doppler lever. arXiv:2610.23871. https://doi.org/10.48550/arXiv.2610.23871

Licence

Kshana is dual-licensed: the GNU AGPL-3.0-only (LICENSE), or a commercial licence from Ashforde® OÜ for closed integration that the AGPL does not suit. LICENSING.md explains which applies. Contributions are licensed inbound under the AGPL and also grant Ashforde® OÜ the right to include them in the commercial edition; sign off each commit with git commit -s (see CONTRIBUTING.md). "Kshana" and its marks are trademarks of Ashforde® OÜ: the licence covers the code, not the name, so please rename forks.

Reference

The long material, collapsed. Every document is listed in Documentation.

Install & build from source

Install & build

Requires a Rust toolchain (≥ 1.85, the rust-version in Cargo.toml; developed on 1.93).

git clone https://github.com/ashfordeOU/kshana
cd kshana
cargo build --release
cargo test          # all tests pass

Usage: the command line in full

Usage

Run any scenario; the CLI dispatches on the scenario's kind field and writes <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html and <scenario>.report.json next to it — plus <scenario>.table.csv for the kinds that publish a table. The report (a HyperText Markup Language (HTML) page and a JSON document with the same content) carries an executive summary, every input with its unit, the results and charts, a campaign's sweep, Monte Carlo or chain tables, an events timeline, the VALIDATED / MODELLED / PARTNER label and source of every capability the run used, what is not modelled, and a reproducibility record (engine version, Secure Hash Algorithm 256-bit (SHA-256) digests, seed, platform and the exact command). It prints to a clean PDF (Portable Document Format) file from the browser on A4 or Letter paper; the engine writes no PDF itself. See docs/REPORTS.md.

cargo run -- scenarios/clock-holdover.toml
cargo run -- scenarios/imu-deadreckoning.toml
cargo run -- scenarios/timetransfer.toml
cargo run -- scenarios/hybrid-pnt.toml
cargo run -- scenarios/orbit-gnss-challenged.toml
cargo run -- scenarios/orbit-sgp4-gps.toml
cargo run -- scenarios/orbit-rinex.toml
cargo run -- scenarios/integrity-raim.toml

# Export a propagated constellation to an SP3-c precise-ephemeris file:
cargo run -- scenarios/orbit-sgp4-gps.toml --export-sp3 gps.sp3

# Export the constellation's mean elements to a CCSDS OMM catalogue (one OMM
# message per TLE-defined satellite, with its real NORAD id / COSPAR designator):
cargo run -- scenarios/orbit-sgp4-gps.toml --export-omm gps.omm

# Export the velocity-carrying state to a CCSDS OEM 2.0 ephemeris (GMAT/Orekit/STK):
cargo run -- scenarios/orbit-sgp4-gps.toml --export-oem gps.oem

# Export the geometry for a globe, a map or a mission-analysis tool: CZML, KML,
# GeoJSON, STK .e, or SigMF for the spectrum kind (every format that applies):
cargo run -- scenarios/jamming-demo.toml --export all

--export <czml|kml|geojson|stk|sigmf|all|list> writes CZML (the Cesium Language),