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 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.

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.22.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#

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 full GNSS signal-acquisition receiver (it now 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 — but does not acquire or track raw signal); 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.

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 223 rows — 83 VALIDATED, 136 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 real data (the LRO — Lunar Reconnaissance Orbiter — row) is still VALIDATED. 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}

_{83 Validated · 136 Modelled · 4 Partner — SVG}

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.29.1 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.29.1 6600 2610
console.log(summary(toml));

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 MODELLED lunar PNT suite — 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 & machine-learning 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.

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.

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#

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), KML (Keyhole Markup Language), GeoJSON (Request for Comments 7946), Ansys STK (Systems Tool Kit) .e ephemerides and SigMF (Signal Metadata Format) recordings next to the scenario, and --import-route <route.geojson> feeds a GeoJSON line into the track-flying kinds. Each format is validated against its published specification, and a scenario a format does not apply to says why: see docs/INTEROP.md.

Other CLI modes — lint a scenario, feed real Earth-orientation data, or run a whole suite:

# Lint a scenario without running it (checks the kind + required fields):
cargo run -- --validate scenarios/integrity-raim.toml

# Feed a real IERS Earth-orientation file (finals2000A) for frame precision:
cargo run -- scenarios/orbit-sgp4-gps.toml --eop tests/fixtures/agency/eop/finals2000A_2022001.txt

# Run a SUITE of scenarios into one aggregated, stamped study artifact
# (writes <suite>.study.json + <suite>.study.html next to the manifest):
cargo run -- --study scenarios/quantum-pnt-demonstrator.suite.toml

# Animate a run's time series: an animated SVG, a self-contained HTML player, and a
# numbered SVG frame sequence with manifest.json (see docs/ANIMATION.md):
cargo run -- scenarios/campaign-jam-spoof-holdover-integrity.toml --animate all

Animation export. --animate svg|html|frames|all writes <scenario>.animation.svg (Cascading Style Sheets (CSS) keyframes, no script), <scenario>.animation.html (play, pause, scrub, speed and synced panels, with no external asset) and <scenario>.frames/ (frame_0000.svg, … plus manifest.json with the frames per second and duration). A campaign plays its phases and alarms, a spectrum run its waterfall; the theme follows prefers-color-scheme and prefers-reduced-motion shows the finished picture. It renders the run's own samples, byte-identical on a re-run, and adds no evidence. See docs/ANIMATION.md.

A suite manifest is a small TOML (Tom's Obvious, Minimal Language) file — a title and a scenarios = [ … ] array of scenario paths — that the engine runs in turn, folding every result (with its MODELLED / VALIDATED labels) into one self-describing study artifact. See scenarios/quantum-pnt-demonstrator.suite.toml.

Interoperability role. Kshana is the performance-simulation layer that sits alongside the post-processing toolchain, not a replacement for it: feed its RINEX output into RTKLIB or gLAB for a position solution, and use its SP3 output as a precise-orbit product for tools like Ginan — Kshana answers what resilience a given PNT architecture buys before you have real signals, in formats those tools already ingest (--export-sp3, or export_sp3 = true in an orbit scenario, writes <scenario>.sp3). The same orbit can be published as standards-track CCSDS OMM mean elements (--export-omm, or export_omm = true, writes <scenario>.omm) — one OMM 502.0 KVN (keyword = value notation) message per TLE-defined satellite, carrying each object's real NORAD (North American Aerospace Defense Command) catalogue number, COSPAR (Committee on Space Research) international designator, and epoch, for any OMM-aware consumer instead of a bespoke two-line element set.

Example output (clock holdover — note how the Integrity and Security figures of merit are reported):

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 scenarios/clock-holdover.result.json, scenarios/clock-holdover.chart.svg, scenarios/clock-holdover.report.html, and scenarios/clock-holdover.report.json

The optical clock's 95th-percentile (p95) timing error is 1.20e-4 ns: the summary prints small values with significant digits rather than rounding them to 0.0. security reads n/a (no attack) because this scenario configures no attack, so there is nothing to detect. The JSON result still carries each clock's analytic spoof-detectability bound in fom.security (0.997 for the optical clock, 0.000 for the chip-scale atomic clock, whose own noise over the monitoring window exceeds the 20 ns spec), and its figure_tiers block marks that figure applicable: false. The spoof scenario kind scores detection against an injected attack. figure_tiers also gives every reported figure its verification tier — VALIDATED (checked against an external oracle) or MODELLED — and the verification-matrix row the tier is read from. The orbit scenario additionally reports a geometry block — fraction of samples with a fix, and best/median position dilution of precision (PDOP) and position accuracy — alongside the clock result.

Read these two numbers carefully. security is an analytic spoof-detectability bound derived from each clock's stability — it is meaningful only against a configured spoofing scenario and is not a multi-satellite RAIM detector. integrity here is the filter's self-consistency (fraction of outage samples inside its own k-sigma bound), not an aviation HPL/VPL integrity figure. See docs/INTEGRITY.md.

For genuine receiver-autonomous integrity, the integrity scenario kind (scenarios/integrity-raim.toml) runs real snapshot and solution-separation (ARAIM-style) RAIM over the propagated constellation geometry: it computes horizontal/vertical protection levels (HPL/VPL) per epoch and reports the fraction of epochs that meet the configured alert limits, with a Stanford integrity diagram for error-vs-PL (protection level) classification.

Reproducible study artifacts

Four open studies each regenerate a byte-deterministic artifact (fixed seed) from one command — the numbers behind the quantum-vs-classical crossover, RF-impairment optimism-gap, PNT-resilience-scoring, and timing-protection-level studies:

# Quantum-vs-classical resilience crossover map (writes paper/crossover/*.json):
cargo run --release --bin crossover_study -- paper/crossover

# RF-impairment optimism-gap study (13-detector panel, scaling laws, LOO predictor):
cargo run --release --example optimism_study -- paper-artifacts/optimism-study.json

# Framework-aligned PNT-resilience scoring + decision-instability study:
cargo run --release --example resilience_report -- paper-artifacts/resilience-study.json

# Conditional Timing Protection Level, calibrated on a real recorded spoof:
cargo run --release --example tpl_jammertest

Each artifact records its engine version, seeds, and a config hash and carries an honest MODELLED/VALIDATED label. The real-data probes (*_probe) run the same pipeline over recordings you supply locally; no datasets are shipped in the repo. The RF-impairment optimism-gap study is written up in the preprint arXiv:2606.22054, and the conditional timing protection level (tpl_jammertest above) in the preprint arXiv:2606.24210 (see Cite).

The published lunar-PNT studies (arXiv:2607.06212 surface-beacon DOP and arXiv:2607.02566 VLBI observability) have their geometry, dilution-of-precision, real-time frame / Earth-orientation-parameter (EOP) prediction, distant-retrograde-orbit and RF-ranging claims independently cross-checked in tests/validate_p*.rs against separate oracles (scipy.special.j1, an independent NumPy (HᵀH)⁻¹ DOP solve, a NumPy re-parse of the same IERS finals2000A rows, and the NASA/JPL Three-Body Periodic Orbit Database). These are additional regression checks over the modelled lunar suite; they do not change the machine-checked matrix count.

Scenario format#

Scenarios are declarative TOML. A top-level kind selects the pack — fifty in all (clock is the default if omitted): inertial, timetransfer, hybrid, hybrid-ukf, fusion, gnss-ins, orbit, ephemeris, gnss-sim, integrity, lunar-integrity, lunar-time-offset, spoof, spoof-detect, jamming, sweep, sweep-nd, gravity-map, terrain-nav, terrain-slam, combined-altpnt, pvt, mars-pnt, impairment-eval (Machine-learning RF-impairment detection evaluation testbed — labelled synthetic corpus + detector-agnostic ROC/AUC harness + in/out-of-distribution optimism gap), quantum-trade (quantum-vs-classical PNT trade with measured-ADEV ingestion + GNSS-denied resilience envelope; MODELLED), space-weather (solar/geomagnetic indices + Jacchia-71 exospheric temperature + activity-driven thermospheric density over the static atmosphere; MODELLED), oem-interop (CCSDS OEM import/round-trip bridge for GMAT/Orekit/STK ephemerides; MODELLED), the mission-analysis trio launch-window (two-body launch azimuth / plane-change / opportunities), reentry (Allen-Eggers ballistic re-entry corridor), eo-coverage (EO swath / GSD / access / revisit geometry), space-packet (CCSDS 133.0 TM/TC — telemetry/telecommand — Space Packet framing — exact bit layout, round-trip verified), and attitude-budget (3-DOF gravity-gradient torque + RSS pointing error budget), passes (ground-station rise/set pass prediction — AOS/TCA/LOS, max elevation, access), and link-budget (one-way CCSDS/DSN link equation — FSPL / Eb·N₀ / margin / closure); telecom-timing (holdover time error, MTIE and TDEV checked against ITU-T masks); spectrum (the whole GNSS L band as one power spectral density: a frequency-by-time waterfall under a scripted continuous-wave, narrowband, chirp or matched-noise jammer timeline, per-band jammer-to-signal ratio and effective carrier-to-noise density from the spectral separation coefficient, and Signal Metadata Format (SigMF) recording input and output with Welch spectral estimates; the signal spectra VALIDATED against textbook values, the jammer scenario MODELLED; see docs/SPECTRUM.md; the same kind draws UHF, S and C band panels with designed low Earth orbit signals); leo-signal (low Earth orbit positioning, navigation and timing signal designs for any system: band-limited spectra, code-tracking jitter and ranging accuracy, acquisition search and time, spectral separation against GPS and Galileo, jammer tolerance and a UHF-to-C band trade, from public presets such as Xona Pulsar, Iridium, Starlink and CentiSpace or inline designs; the closed forms and the LEO Doppler VALIDATED, the designs MODELLED; see docs/LEO-SIGNAL.md); solar-system (the Sun, planets, Pluto, the Moon and seven major moons at one epoch — positions, constants, light times and orbit tracks; planet positions VALIDATED against JPL Horizons) and body-pnt (positioning around any of those bodies with a local navigation constellation and a deep-space link from Earth; MODELLED); campaign (existing kinds composed into a chained mission timeline with state handed between phases, a parameter sweep, a seeded Monte Carlo ensemble, or several scenarios under one shared condition; MODELLED, see docs/CAMPAIGNS.md); constellation-design (Walker delta and star patterns, element lists and multi-shell designs with GPS, Galileo, BeiDou and GLONASS presets, and coverage and dilution of precision over a latitude/longitude grid; the generator and GPS global DOP VALIDATED against the published service documents, see docs/CONSTELLATION-DESIGN.md); leo-pass (a low Earth orbit (LEO) positioning, navigation and timing (PNT) satellite pass and its link budget band by band, from any constellation and any signal design: look angles, Doppler and Doppler rate, ITU-R rain, gas, scintillation and building entry loss, carrier-to-noise density against the MEO GNSS satellites in view, the first-order ionosphere and ionosphere-free pairs, and a low-energy fix budget, ionosphere sounding from every band pair, and spoofing monitors by Doppler and pass-geometry consistency and by cross-band consistency; the ITU-R terms and the static-user Doppler envelope VALIDATED, the pass MODELLED, see docs/LEO-PASS.md); leo-navmsg (the broadcast ephemeris and clock message of a low Earth orbit (LEO) PNT satellite, for any orbit and carrier: a fitter from an integrated truth orbit to the Galileo Keplerian set, that set with along-track, cross-track and radial correction polynomials, the Liu et al. 2025 22-parameter model or the ATOMIC zero-clock ECEF polynomial; signal-in-space range error (SISRE) versus fit interval and update period, a mid-pass update continuity check, Kshana's own documented binary frame with a CRC-24Q cyclic redundancy check and a quantisation budget, and a RINEX-4-style block labelled a Kshana extension; the SISRE weights, the Galileo user algorithm and CRC-24Q VALIDATED, the fits MODELLED; optional presets for Xona Pulsar, Iridium, Starlink, CentiSpace, a representative C-band system, ATOMIC and Celeste IOD; see docs/LEO-NAVMSG.md); the fused MEO + LEO PNT trio leo-pvt (Doppler positioning from low-Earth-orbit (LEO) range rate, joint GNSS + LEO pseudorange fixes with inter-system biases and the DOP against the number of LEO satellites, polar and Arctic coverage, and LEO time transfer to UTC — over any constellation, with optional presets such as Xona Pulsar, Iridium and Starlink signals of opportunity; the LEO Doppler envelope VALIDATED against published Iridium and Xona figures), leo-ppp (precise point positioning convergence with GNSS only and with LEO augmentation, compared with Li et al. 2019) and ntn-positioning (5G non-terrestrial-network positioning from the Cramér-Rao bound of the signal bandwidth), MODELLED apart from that envelope, see docs/LEO-PNT-FUSION.md; leo-pnt-chain (one LEO-PNT system end to end: a leo-signal design carried by a leo-pass band, the pass's C/N0 and the navigation message's signal-in-space range error handed to a fused leo-pvt fix and leo-ppp convergence, every hand-off listed; MODELLED, see docs/LEO-PNT.md, which is also the overview of every LEO-PNT kind and scenario, including the resilience campaigns, one scenario per experiment focus area and one per end-user vertical); the lunar-PNT suite lunar-vlbi, lunar-joint-od-clock, lunar-frame-realisation, moonlight-service-volume, lunar-differential-pnt, lunar-interop-export; the Quantum-Enabled PNT demonstrator quantum-time-transfer, quantum-gnss-free-nav, quantum-anomaly-detect; and the signal-security, cislunar & layered-resilience research kinds lunar-attack-surface, realtime-frame-eop, lunar-time-budget, hybrid-optical-rf, cislunar-observability, conflict-resilience — the mission-analysis trio and these later kinds all MODELLED (each with a validated closed-form core; see the matrix). Common fields: seed, a [time] grid, a [gnss] availability timeline (the outage driver), and per-sensor blocks with provenance strings citing the source of every figure. Example (clock):

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" },  # 10 min GNSS sync
  { t0 = 600.0, t1 = 7200.0, state = "denied"  },  # ~1.8 h outage
]
[clock_quantum]
id = "optical-sr-lattice"
provenance = "Strontium optical lattice clock, space-oriented goal sigma_y(1s)=1e-15 (arXiv:1503.08457)"
y0 = 5.0e-17
q_wf = 1.0e-30   # white FM:  q_wf = sigma_y(1s)^2
q_rw = 0.0       # random-walk FM
drift = 0.0      # linear aging (per second)
[clock_classical]
id = "csac-sa45s"
provenance = "Microchip SA65 / SA.45s CSAC datasheet sigma_y(1s)=3e-10"
y0 = 5.0e-10
q_wf = 9.0e-20
q_rw = 0.0
drift = 0.0

Optional fields (off when absent): a clock may add flicker_floor (1/f FM — frequency modulation — Allan floor); an inertial sensor may add gyro_bias and q_arw (gyro bias and angular random walk), and bias_instability and q_aa (the Allan bias-instability floor and acceleration random walk) — together a single-axis (1-DOF) accelerometer error budget (VRW/ARW — velocity/angular random walk — and bias-instability). This is the error budget the shipped inertial scenario pack runs. Separately, the library now carries a verified 3-axis strapdown navigator (src/inertial/{attitude,mechanization,imu_errors}.rs): quaternion attitude with coning/sculling compensation, a full NED mechanization (Earth-rate and transport-rate terms, WGS-84 Somigliana gravity), and a deterministic IMU error model in which scale-factor, misalignment, g-sensitivity, quantization, and rate-ramp are modelled (IEEE Std 952-1997, the IEEE gyro specification and test-procedure standard, §A.2; Groves 2013 §4.3). That 3-axis path is now wired into a runnable loosely-coupled GNSS/INS pack (kind = "gnss-ins"): a 15-state error-state EKF disciplines the strapdown solution against noisy fixes while GNSS is up, then coasts through the outage, reporting the fused horizontal error against the open-loop free-INS coast. A tightly-coupled pseudorange update is also available (it forms the innovation in the range domain, so it keeps correcting with fewer than four satellites). A clock-holdover scenario may add runs (> 1) to run a Monte Carlo ensemble — each figure of merit is then reported as a mean with a 5th–95th-percentile spread and the chart shades the error confidence band (see scenarios/clock-ensemble.toml).

A fusion scenario (same blocks as hybrid) runs two independent Kalman estimators — one for the clock state, one for the position state — disciplined by GNSS and aided by optical time transfer, and reports a combined holdover FoM. The two blocks share no cross-covariance: this is a stacked pair of error budgets, not a true coupled clock+position joint filter (cross-block covariance is a roadmap item). See scenarios/fusion-pnt.toml.

A spoof scenario injects a time-spoof — one of four [attack.shape] kinds (linear_ramp, step_jump, meaconing, replay; a bare rate_ns_per_s is still accepted as a linear ramp) — and runs each clock's spoof detector. The detector is a two-sided χ²₁ energy / Neyman–Pearson test on the clock-aided monitor statistic: the threshold is set from a target false-alarm budget target_pfa, and the missed-detection probability P_md is reported both closed-form and by Monte-Carlo (mc_runs trials per hypothesis — the two agree to a few ×1/√N). The Security figure of merit is 1 − P_md at the operationally-harmful (spec) magnitude, so a quiet clock that catches a spec-sized spoof scores ≈ 1 and a noisy one that often misses it scores lower (see scenarios/spoof-attack.toml, scenarios/spoof-meaconing.toml).

A gnss-sim scenario is a measurement-domain simulation: for each visible satellite it synthesises the pseudorange ρ = geometric range + c·δt_rx − c·δt_sv + I + T + noise + multipath and the L1 Doppler, with the Klobuchar single-frequency ionosphere ([iono], IS-GPS-200 §20.3.3.5.2.5) and the Saastamoinen zenith troposphere projected by the Niell (1996) mapping function ([tropo]). The residuals feed snapshot RAIM for per-epoch HPL/VPL, and every satellite's pseudorange, Doppler, C/N₀, and iono/tropo corrections are emitted in the JSON gnss_measurements array. It is a forward simulator (it generates measurements from a known truth), not a receiver/solver — a zero-noise run reproduces geometry plus the corrections to sub-millimetre (see scenarios/gnss-sim-raim.toml).

A jamming scenario models RF interference as a link budget: a [jammer] (ECEF position, transmit power_dbw, type) raises the jammer-to-signal ratio at a [receiver] watching a Walker [constellation]. From the geometry (free-space path loss and the per-direction receive-antenna gain) it computes each satellite's J/S, the effective C/N₀ via the standard anti-jam equation (despreading processing gain × the spectral-separation factor Q; Kaplan & Hegarty §9.4), and flags loss of lock below a configurable tracking threshold — reporting an availability_under_jamming figure of merit. A 10 W broadband jammer at 1 km denies the receiver entirely (J/S ≈ 72 dB); the same jammer at 100 km only degrades the links (see scenarios/jamming-demo.toml).

A sweep scenario runs a trade study: it varies one parameter (threshold_ns, duration_s, quantum_q_wf, or classical_q_wf) from start to stop over steps points on a lin or log scale, records a metric (e.g. holdover_s) for both clocks, and charts the two curves. The base scenario goes under [base] (see scenarios/sweep-clock-stability.toml).

A sweep-nd scenario generalises this to any pack and any number of axes: it varies dotted TOML keys of a [base] scenario (of any kind) over the Cartesian product of [[axes]], re-runs each grid node, and records metrics given as dotted JSON paths into the result (e.g. classical.fom.holdover_s). It works for every pack because it operates at the TOML/result boundary; native runs evaluate the grid in parallel (no extra dependency, wasm falls back to sequential) and the output is deterministic and row-major (see scenarios/sweep-nd-inertial.toml).

An orbit scenario derives the [gnss] timeline from geometry instead of authoring it — give a [user] orbit, a [constellation], an elevation mask_deg, and the two clock blocks. It also reports position accuracy from the satellite geometry; the optional sigma_uere_m (1-sigma user-equivalent range error, default 1 m) scales the position dilution of precision into a position sigma. The user orbit may be made eccentric with eccentricity and argp_deg, and j2 = true adds Earth-oblateness secular drift (see scenarios/orbit-molniya.toml). The constellation can instead be a real one: give [constellation] a tle block of two-line element sets and the satellites are parsed from it (see scenarios/orbit-real-tle.toml). Add one or more [[constellations]] blocks for multi-GNSS (e.g. GPS + Galileo; see scenarios/orbit-multignss.toml):

kind = "orbit"
seed = 7
threshold_ns = 5.0
mask_deg = 10.0
sigma_uere_m = 1.0           # optional; position sigma = position-DOP * this
[time]
step_s = 60.0
duration_s = 86400.0
[user]                       # spacecraft (altitude in km, angles in deg)
altitude_km = 8000.0
inclination_deg = 0.0
[constellation]              # Walker-delta GNSS (GPS-like)
altitude_km = 20180.0
inclination_deg = 55.0
planes = 6
sats_per_plane = 4
phasing_f = 1.0
[clock_quantum]  # ... as above
[clock_classical]  # ... as above

The GPS-denied alt-PNT kinds navigate with no GNSS at all, matching a measured field sequence against a map through a particle filter. A gravity-map scenario flies a track through a spherical-harmonic gravity-anomaly field and recovers it from a cold-atom gravimeter's reading (scenarios/gps-denied-gravity-nav.toml); a terrain-nav scenario does the same against an SRTM elevation DEM (TERCOM/SITAN, scenarios/terrain-nav.toml); and a combined-altpnt scenario fuses gravity + IGRF magnetic + terrain in one filter (scenarios/combined-altpnt.toml).

A lunar-integrity scenario evaluates cislunar PNT: it runs a lunar south-pole ARAIM protection-level pass against a LunaNet/LNIS relay set and honestly reports the integrity gap — a ~30 m lunar σ_URE drives the protection level well above a 50 m alert limit, so the service is unavailable under aviation-style integrity rules (scenarios/lunanet-araim.toml).

A lunar-time-offset scenario reports the relativistic Earth–Moon clock rate — the basis of a Lunar Coordinate Time scale (LTC/TCL). A first-principles post-Newtonian identity sums the self-potential difference (IAU L_G geoid potential minus the Moon's surface self-potential) and the Moon's kinetic (second-order Doppler) term to a secular rate of ≈ 57 µs/day, reported with the published 56–59 µs/day band; it also gives the accumulated LTC−TT offset over a horizon and an inverse-variance ensemble (a lunar paper-clock). MODELLED — the headline figure is reference-dependent (Earth geoid vs lunar selenoid, averaging window), which is why a band, not a single certified number, is reported (scenarios/lunar-time-offset.toml).

See scenarios/ for at least one worked example of every kind (75 kinds, 138 scenario .toml files + 1 suite manifest — several kinds ship more than one example). Not every kind has a file named after it: lunar-integrity → scenarios/lunanet-araim.toml and gravity-map → scenarios/gps-denied-gravity-nav.toml are two of several such. List the dispatchable kinds at any time with cargo run -- --validate <file> errors, the Python list_kinds(), or the MCP list_scenario_kinds tool.

Output#

The result artifact is versioned, self-describing JSON: per-step time series, the scored figures of merit, the active model specs (with provenance), the seed, a scenario hash — so any chart can be reproduced from the file — and, for each clock, an adev_curve ([{tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi}]): the overlapping Allan deviation across octave-spaced averaging times — the standard way to read a clock's stability — now with a noise-type-specific 95% confidence band per point (the record's power-law type is identified from its modified-Allan slope, and the χ² interval uses the matching NIST SP 1065 effective degrees of freedom). The browser playground renders it as a log-log "Clock stability (ADEV)" chart. (MDEV, TDEV, and HDEV are available as library estimators; the exported result curve is the overlapping ADEV.) Every field, with units and a source pointer, is documented in docs/SCHEMA.md.

Every chart is self-describing. The browser playground, the CLI's *.chart.svg export, and the HTML (HyperText Markup Language) scorecard all stamp each chart image with a footer reading Kshana v<version> · scenario <hash> · kshana.dev. The scenario <hash> is the first 12 hex characters of the run's scenario hash — a SHA-256 (the 256-bit Secure Hash Algorithm) digest over the canonical scenario definition (seed, thresholds, model parameters, GNSS windows, …); the integrity and lunar reports, which carry no hash of their own, fall back to a SHA-256 of the scenario source. It is the same fingerprint shown in the one-line summary and the result JSON, so a saved or pasted chart always carries its version, the exact scenario that produced it (for bit-for-bit reproduction), and the source — change any input and the hash changes.

The figures of merit follow the standard operational PNT figures of merit:

New to these terms? Each is defined in plain language in the glossary.

Repository layout#

kshana/
├── src/                                       # the kshana core crate (library + CLI)
│   ├── api.rs · main.rs · lib.rs              # typed dispatch (75 kinds) + CLI + crate root
│   ├── python.rs · wasm.rs                    # optional PyO3 / wasm-bindgen bindings
│   ├── types.rs · scenario.rs · allan.rs      # shared core (time grid, GNSS timeline, Allan)
│   │
│   ├── models.rs · estimator.rs · kalman.rs   # Pack 1 — clock holdover + integrity
│   ├── security.rs · detection.rs · spoof.rs · spoof_monitors.rs  # spoof detection
│   ├── filter_health.rs · fom.rs · fom_label.rs · report.rs · chart.rs · run.rs  # health · FoM scoring + labelling · output
│   ├── suite.rs · study.rs                     # scenario suites + aggregated multi-scenario study artifacts (`--study`)
│   ├── inertial/                              # Pack 2 — strapdown INS (attitude · mechanization · imu_errors · quantum_imu)
│   ├── timetransfer.rs · timetransfer_adv.rs · timegeo.rs  # Pack 3 — TWSTFT/CV/PPP/optical, Sagnac
│   ├── hybrid.rs · ensemble.rs · sweep.rs     # Pack 4 — fused PNT, Monte-Carlo, trade sweeps
│   │
│   ├── timescales.rs · jd2.rs · ephem.rs      # time systems, two-part JD, Sun/Moon ephemeris
│   ├── precession.rs · nutation.rs · cio.rs   # IAU 2006/2000A precession-nutation + CIO GCRS↔ITRS
│   ├── frames.rs · *_data.rs                  # TEME↔ECEF + generated nutation/CIO/EGM2008/IGRF tables
│   │
│   ├── orbit.rs · sgp4.rs · tle.rs · walker.rs   # geometry, SGP4/SDP4, TLE, Walker design
│   ├── propagator.rs · forces.rs · gravity_sh.rs · integrator.rs  # Cowell + perturbations (EGM2008 d/o70, GR) + RK4/DOPRI
│   ├── maneuver.rs · batch_ls.rs · orbit_determination.rs  # burns/Lambert/porkchop, Gauss-Newton, OD
│   ├── cr3bp.rs · lunar.rs · lunar_frame.rs · lunar_od.rs  # Earth–Moon CR3BP + halo/NRHO STM corrector, cislunar/LunaNet ARAIM, MCI↔MCMF, lunar OD
│   ├── lunar_time.rs · lunar_vlbi.rs · lunar_combination.rs · lunar_frame_realise.rs · lunar_service.rs · lunar_dpnt.rs · lunar_interop.rs  # MODELLED lunar PNT suite — LTC time · geodetic VLBI · joint OD+clock · frame realisation · Moonlight service-volume · differential PNT · LunaNet/IOAG interop export
│   ├── body.rs · mars_frame.rs · ephem_provider.rs · radiometric.rs · ccsds_tdm.rs  # deep-space: multi-body · Mars frame · ephemeris seam · radiometric obs + CCSDS-TDM
│   ├── deepspace_od.rs · clock_state.rs · mars_atmos.rs · mars_pnt.rs · linkbudget.rs · gse_sim.rs  # SRIF OD · onboard clock · Mars drag · relay-PNT · link budget · GSE sim
│   │
│   ├── fusion/                                # GNSS/INS — EKF · UKF · tightly_coupled(17) · coupled · closed_loop
│   ├── raim.rs · sbas.rs                      # RAIM/ARAIM HPL/VPL, SBAS DO-229E PLs + L1/L5 iono-free
│   ├── gnss_sim.rs · ionex.rs · pvt.rs · jamming.rs  # measurement domain · ionosphere maps · single-point positioning · jamming
│   ├── navsignal.rs                            # nav-signal PSD (BPSK-R/BOC) · spectral-separation → anti-jam Q · DLL code-tracking jitter · multipath envelope
│   ├── gravimeter.rs · igrf.rs · mapmatch.rs · particle_filter.rs · altpnt/  # gravity/magnetic/terrain alt-PNT
│   ├── rinex.rs · rinex_obs.rs · glonass.rs · sp3.rs · oem.rs · omm.rs · permalink.rs  # interop formats
│   ├── launch.rs · reentry.rs · eo_payload.rs · attitude_budget.rs · passes.rs · space_packet.rs  # mission-analysis budgets + CCSDS Space Packet
│   ├── space_weather.rs · holdover.rs · tpl.rs   # space-weather environment · GNSS-denied clock-holdover calculator · conditional Timing Protection Level (under spoofing)
│   ├── resilience/                              # framework-aligned PNT-resilience scoring + decision-instability study (RPCF · Dirichlet · Kendall-τ · diversity collapse · assurance report)
│   ├── impairment_eval.rs · impairment_study.rs · impairment_ml.rs · eval_stats.rs  # Machine-learning RF-impairment eval testbed · optimism-gap study · LR/MLP detectors · bootstrap/DeLong/Spearman stats
│   ├── sdr.rs · realdata/                       # software-defined-receiver front end (IQ/IF → E/P/L taps → SQM) + real-data ingest adapters (RINEX · UBX · GnssLogger · JammerTest · Yunnan · SatGrid)
│   ├── crossover.rs · quantum_trade.rs · frugal.rs · integrity_impact.rs  # quantum-vs-classical crossover map · PNT trade · cost-per-coverage ROI · integrity impact
│   ├── quantum_devices.rs · quantum_faults.rs · quantum_nav_od.rs · qtrade.rs · timetransfer_chain.rs · representativeness.rs  # Quantum-Enabled PNT demonstrator — device error models · fault catalogue · GNSS-free quantum OD · unified trade harness · quantum time-transfer chain · representativeness / gaps-to-flight ledger
│   ├── interchange.rs · verification.rs          # KIF artifact envelope · machine-checked verification matrix
│   └── bin/crossover_study.rs · bin/validation_report.rs  # crossover-study artifact generator · release validation-summary HTML
│
├── mcp/kshana-mcp/        # standalone, workspace-EXCLUDED crate — the MCP server (+ Dockerfile, server.json)
├── ide/jetbrains/         # standalone Kotlin/Gradle IntelliJ-Platform plugin
├── xval/                  # standalone, workspace-EXCLUDED external cross-checks: anise-{frames,lunar-od,mars-od,service-geometry} (Rust ANISE/SPICE DE440) + orekit-passes (Java Orekit)
│
├── examples/            # reproducible study generators: tpl_jammertest · resilience_report · optimism_study + real-data probes (jammertest_probe · yunnan_probe · satgrid_probe · texbat_probe · ingest_realdata)
├── paper-artifacts/     # byte-deterministic study artifacts, regenerable from examples/ (optimism-study.json · resilience-study.json); raw datasets stay out
├── scenarios/            # one cited .toml per kind + geometry-driven + GPS-denied
├── scripts/              # reproducibility + repo-hygiene + SBOM guards
├── docs/                 # CONCEPTS, ARCHITECTURE, CAPABILITY, VALIDATION, PROVENANCE, GLOSSARY, …
├── web/                  # the WebAssembly playground + kshana.dev site
├── tools/                # table generators (EGM2008 · IGRF · nutation · CIO) + fetch_tles.sh
├── .github/workflows/    # ci · release · publish · wheels · pages · mcp-publish · jetbrains-plugin · frame-xval
├── pyproject.toml        # Python packaging (maturin)
├── CHANGELOG.md          # Keep a Changelog + SemVer
└── CITATION.cff · ROADMAP.md · CONTRIBUTING.md · SECURITY.md

FAQ#

Do I need to understand quantum physics to use this? No. If you can run a command line you can run Kshana. Start with the plain-language primer; look terms up in the glossary.

Is this a quantum-hardware design or flight software? No. It is a performance simulator. Quantum-hardware fidelity comes from published error models, not from this tool. See What it is / is not.

Are the quantum results realistic, or marketing? Every parameter is cited to a datasheet or paper, every model is validated against a textbook relation, and maturity is labelled honestly in VALIDATION.md — including that no strontium optical clock has flown. The engine is neutral: quantum and classical are the same code with different published numbers.

Can I trust two runs to agree? Yes — runs are deterministic: scenario + seed + engine version → bit-identical output, enforced by scripts/check-reproducible.sh.

Can I use it from Python or in a browser? Yes — see Install: the Python and WebAssembly examples are under it. Both call the same engine.

How do I model my own sensor? Write a scenario .toml with your sensor's published figures in the provenance fields. See Scenario format and the examples in scenarios/.

Is it free for commercial use? Yes — under the AGPL-3.0, including in commercial settings, as long as you honour the AGPL's copyleft (notably: if you modify Kshana and offer it over a network, you must offer those users your modified source). If that does not suit you — e.g. you need to embed Kshana in a proprietary product or run a closed network service — a commercial licence is available from Ashforde OÜ; see LICENSING.md and Support.

Troubleshooting#

cargo build fails on an old toolchain. Kshana needs Rust ≥ 1.85. Update with rustup update.

Building the Python extension fails to link on macOS (Undefined symbols … _Py…). A Python extension resolves its symbols at load time. maturin sets the right linker flag automatically — use maturin develop --features python rather than a bare cargo build.

The Python build complains the interpreter is newer than PyO3 knows. Set PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 (abi3 wheels are forward-compatible across CPython versions).

WebAssembly build can't find the target. Install it once with rustup target add wasm32-unknown-unknown, then wasm-pack build --target web -- --features wasm.

Where did my output go? Each run writes <scenario>.result.json, <scenario>.chart.svg, <scenario>.report.html and <scenario>.report.json next to the input .toml, and <scenario>.table.csv too for the kinds that publish a table. All of them are git-ignored by design.

Versioning & releases#

Kshana follows Semantic Versioning. While pre-1.0 the public scenario/result schema may still change; breaking changes are called out explicitly in the CHANGELOG.md. Every result is reproducible from scenario + seed + engine version.

Every vX.Y.Z tag publishes all channels automatically, in one order — the full test suite runs on the tagged commit first, nothing is published until it passes, and afterwards the pipeline checks that each registry really serves the new version (docs/RELEASING.md). The channels:

The MCP server's crate / image / registry version tracks the engine (it bundles the library); the JetBrains plugin versions independently (it shells out to your installed kshana binary).

Roadmap#

See ROADMAP.md for the phased roadmap, CHANGELOG.md for released history, and docs/CAPABILITY.md for the per-capability roadmap. The priority order is: timing and holdover evidence for critical infrastructure first (telecom masks, longer holdover with ageing and flicker noise, ingestion of measured clock data); the neutral quantum-vs-classical trade method second (results labelled MODELLED until a partner's measured data promotes them); and lunar / cislunar and deep-space navigation maintained, not expanded as the lead. The ITRF-precise frame reduction is now delivered — the full CIO-based IAU 2006/2000A GCRS↔ITRS chain (polar motion + sub-arcsecond nutation), validated bit-for-bit against SOFA/ERFA and independently cross-checked against ANISE (pure-Rust SPICE) to ≤ 3.6 m at GNSS orbit. Near-term items include tightly-coupled carrier-phase fusion and surfacing the loosely-/tightly-coupled GNSS/INS navigator across more packs; the deep-space / Mars radiometric-navigation engine landed in v0.17.0 (simulation-validated). The quantum physics layer is a P2 item: the CAI accelerometer is now simulated from first principles (Mach–Zehnder phase, projection noise, contrast decay, vibration coupling), while the clock/time-transfer sensors are still driven by published Allan/noise-budget coefficients. GMST-based TEME↔ECEF, the IERS leap-second time systems (UTC/TAI/TT/UT1), SGP4/SDP4 orbit propagation (v0.7.0, validated against the AIAA 2006-6753 vectors), and the runnable gnss-ins fusion pack have all shipped, and the inertial velocity is exposed downstream. An active stochastic time-spoof detector (Neyman–Pearson / χ²₁ energy test with Monte-Carlo P_fa/P_md and a Security FoM of 1−P_md), a link-budget jamming model (J/S → effective C/N₀ → loss of lock), multi-constellation availability, a single-axis (1-DOF) IMU error budget, two independent (clock + position) Kalman estimators reported as a combined FoM, real constellation geometry from TLEs, an HTML scorecard report, geometry-derived GNSS availability and dilution of precision from Keplerian orbits with eccentricity and J2 drift, Monte Carlo confidence bands, trade-study parameter sweeps, an in-browser WebAssembly playground, and optional Python (PyO3) and WebAssembly (wasm-bindgen) bindings have landed on main.

Contributing#

See CONTRIBUTING.md. In short: tests pass (cargo test), the two guard scripts pass, Conventional Commits, and a CHANGELOG.md [Unreleased] entry for every user-visible change. Participation is governed by our Code of Conduct. To report a security issue, see the Security policy — please do not open a public issue for vulnerabilities.

Documentation#

Key references#

Validation oracles & standards — the external authorities Kshana's checks are anchored to:

• Vallado, Crawford, Hujsak & Kelso — Revisiting Spacetrack Report #3 (AIAA 2006-6753; test data): the SGP4/SDP4 verification set Kshana matches to 4.12 mm, and the worked frame examples the TEME→ITRF chain is checked against.
• IAU SOFA / ERFA — the reference time and frame routines the IAU 2000A nutation and the CIO GCRS↔ITRS reduction are validated bit-for-bit against.
• Petit & Luzum (eds.) — IERS Conventions (2010), IERS TN (Technical Note) 36 (Earth-orientation, polar motion, and frame standards).
• Riley — Handbook of Frequency Stability Analysis, NIST SP 1065 (Allan-deviation relations and the NBS14 reference series; NBS = the former US National Bureau of Standards).
• Pedregosa et al. — scikit-learn: Machine Learning in Python, JMLR 12 (2011): the reference ROC/AUC, confusion-matrix and precision/recall/F1 implementations the RF-impairment evaluation testbed is matched to exactly (tests/eval_metrics_reference.rs).
• Virtanen et al. — SciPy 1.0, Nature Methods 17 (2020): optimize.nnls, stats.chi2 and linalg.expm — the reference routines the quantum-trade measured-ADEV NNLS fit, the χ² consistency bands, and the van-Loan clock process-noise covariance are validated against (tests/scipy_reference.rs).
• Knowles, Kanhere, Neamati & Gao — gnss_lib_py, SoftwareX 27 (2024): used both as open prior art (see Comparison & open prior art below) and as the independent DOP oracle the GDOP/PDOP/HDOP/VDOP/TDOP computation is matched to 1e-6 (tests/dop_reference.rs).
• Montenbruck & Gill — Satellite Orbits: Models, Methods and Applications (Springer): the force models behind the force-model fit to agency precise ephemerides.
• Howell — Three-dimensional, periodic, halo orbits, Celestial Mechanics 32(1) (1984), doi:10.1007/BF01358403; Zimovan-Spreen, Howell & Davis — Near rectilinear halo orbits and nearby higher-period dynamical structures, Astrodynamics 6 (2022), doi:10.1007/s42064-021-0125-x (the halo/NRHO families the CR3BP differential corrector reproduces).

Device & method physics — the cited sources behind the sensor models:

• Origlia, Schiller, Bongs et al. — arXiv:1503.08457 (strontium optical lattice clock, space-oriented goal).
• Oelker et al., Nature Photonics (2019) — doi:10.1038/s41566-019-0493-4 (laboratory Sr clock, 4.8×10⁻¹⁷).
• Templier et al., Science Advances (2022) — arXiv:2209.13209 (hybrid quantum accelerometer triad).
• Groves, Principles of GNSS, Inertial, and Multisensor Integrated Navigation — IEEE AESS (Aerospace and Electronic Systems Society) tutorial (University College London Discovery repository) (dead-reckoning error growth).
• Giorgetta et al., Nature Photonics 7, 434 (2013) — arXiv:1211.4902; Deschênes et al., Phys. Rev. X 6, 021016 (2016) — APS (American Physical Society) (optical two-way time-frequency transfer; the optical inter-satellite link models its non-reciprocity budget after these).
• Betz — Binary Offset Carrier Modulations for Radionavigation, NAVIGATION 48(4) (2001), doi:10.1002/j.2161-4296.2001.tb00247.x (the BOC modulation and spectral-separation theory behind src/navsignal.rs).
• Kaplan & Hegarty (eds.) — Understanding GPS/GNSS: Principles and Applications (3rd ed., Artech House, 2017): the anti-jam effective-C/N₀ equation and the early–late DLL code-tracking thermal-noise jitter the nav-signal and jamming models use.

Comparison & open prior art — the tools and surveys Kshana is positioned against:

• Humphreys et al. — TEXBAT (the Texas Spoofing Test Battery; ION — Institute of Navigation — GNSS 2012): the spoofing test-battery parameters the multi-layer detector is characterised against.
• González et al. — NaveGo (2017): the open, validated inertial-navigation error profiles used as the classical baseline.
• Iiyama, Casadesús Vila & Gao — LuPNT (ION GNSS+ 2023, Stanford NavLab): open lunar-PNT simulator.
• Knowles, Kanhere, Neamati & Gao — gnss_lib_py, SoftwareX 27 (2024), doi:10.1016/j.softx.2024.101811: open GNSS data analysis.
• Li, Zaminpardaz, Kealy & Greentree — Quantum sensors for enhanced positioning and navigation: a comprehensive review, GPS Solutions 30(1):62 (2026), doi:10.1007/s10291-026-02030-y.
• Bertone et al. — Earth and Space Science 8(6) (2021), doi:10.1029/2020EA001454: GRAIL reduced-dynamic OD, the empirical-acceleration floor the LRO fit reproduces.