Tutorials

Hands-on, worked examples that take you from “run a shipped scenario” to “quantify and defend a result.” Every number quoted in the three tutorials is a real engine output, anchored to an external (non-circular) authoritative oracle, and pinned by an integration test (tests/tutorials.rs), so a tutorial can never silently drift from what the engine actually does. If a tutorial says the optical clock holds 6600 s, the test fails the build the day that stops being true.

Kshana is a positioning, navigation and timing (PNT) simulator. The tutorials use a few more abbreviations, each spelled out where it first appears: GNSS (Global Navigation Satellite System), GPS (Global Positioning System), CLI (command-line interface) and TOML (Tom's Obvious Minimal Language, the scenario file format).

New to the project? Read the concepts primer and the glossary first, then come back here.

The three worked examples#

How to run a tutorial#

Every tutorial runs the same scenario three ways; pick whichever fits you. They all call the one engine, so the numbers are identical (mirrors the README Usage section).

Command line. 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 the input (JSON is JavaScript Object Notation, SVG Scalable Vector Graphics, HTML HyperText Markup Language). A few kinds also publish a reproducibility table as <scenario>.table.csv (comma-separated values): realtime-frame-eop, lunar-time-budget, lunar-jamming, leo-navmsg, telecom-timing, and moonlight-service-volume when an export site is set. None of the three tutorials is one of them, so you will not see that file here.

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

cargo run -- builds the CLI from this checkout. With an installed binary (cargo install kshana) the same command is kshana scenarios/orbit-sgp4-gps.toml. Without a checkout, most shipped scenarios are bundled in the binary: kshana example lists them (and names the few that are not bundled, with the reason), and kshana example orbit-sgp4-gps > orbit-sgp4-gps.toml writes one out: the copy of scenarios/orbit-sgp4-gps.toml the binary was built with.

Python. Build the extension from this checkout once with maturin, inside an active virtual environment, then call kshana.run:

pip install maturin
maturin develop --features python

import json, kshana
result = json.loads(kshana.run(open("scenarios/orbit-sgp4-gps.toml").read()))
print(result["geometry"]["best_pdop"])

pip install kshana installs the published wheel instead. It can lag this checkout: json.loads(kshana.list_kinds()) tells you which scenario kinds your build has.

Browser playground. Zero install: open the playground, pick a scenario, edit the parameters, and read the result. Nothing is uploaded; the engine runs client-side as WebAssembly.

The tutorials quote the CLI, but every command has the Python and playground equivalent above. Each result is reproducible from scenario + seed + engine version: run it twice and you get bit-identical output.

Annotated teaching scenarios#

For each capability domain there is one heavily-commented .toml under scenarios/: a teaching copy of a canonical scenario with every field explained inline, the cited oracle named, and the expected one-line summary recorded as an # expected: comment. The field values are identical to the parent’s in the repo’s top-level scenarios/ directory (tests/tutorials.rs compares the parsed TOML), so the documented output stays true. The golden hashes are untouched too: a comment never changes a scenario hash.

The teaching file for security uses kind = "spoof" inside: the Security figure of merit (1 − P_md, one minus the probability of missed detection) is produced by the spoof pack. The file name follows the capability (security), the kind follows the pack (spoof). The header of that file calls this out.

The full scenario-kind catalogue#

The engine dispatches on the scenario’s kind. The table below lists the most commonly-used kinds (the eight tutorial domains above plus their nearest neighbours). It is not the complete set: src/api.rs::list_scenario_kinds() returns all 75 built-in kinds. That function (exposed as list_kinds() in the Python and WebAssembly (WASM) bindings, and as kshana kinds --json on the command line) is the authoritative, always-current catalogue, and SCENARIOS.md is its generated enumeration, one section per kind with the required and optional TOML fields. tests/tutorials.rs::tutorial_scenarios_use_real_kinds enforces that every kind a tutorial documents is a real dispatch kind, so nothing in this table can name a kind that does not exist.

Beyond the tutorials: newer capabilities#

The three tutorials stay on the classic clock, orbit and security packs. The engine has grown well past them. Each row below is a shipped scenario you can run as it stands (cargo run -- <file> or kshana <file>); the summary is the first line kshana 0.29.0 printed for it on 2026-09-29. Unlike the tutorial figures, these lines are a record of one run, not pinned by tests/tutorials.rs: rerun the scenario for the current value. Results state their own scope (most carry a label), and the verification matrix states which capabilities are VALIDATED against an external oracle and which are MODELLED.

LEO is low Earth orbit and MEO medium Earth orbit; PVT is position, velocity and time; PPP is precise point positioning; 5G is the fifth-generation mobile standard; TDB is Barycentric Dynamical Time; JD is Julian Date; TE is time error.

The CLI adds three outputs on top of any run:

• Reports. Every run writes <scenario>.report.html and <scenario>.report.json (see REPORTS.md). kshana --study <suite.toml> runs a suite of scenarios into one .study.json and .study.html, for example kshana --study scenarios/quantum-pnt-demonstrator.suite.toml.
• Animation. kshana <scenario.toml> --animate <svg|html|frames|all> renders the run’s time series, for example --animate html on scenarios/orbit-sgp4-gps.toml writes orbit-sgp4-gps.animation.html. A kind with no sampled time axis (such as solar-system) is refused with an error; see ANIMATION.md.
• Interop exports. --export <czml|kml|geojson|stk|sigmf|all|list> writes the result for other tools: CZML (Cesium Language), KML (Keyhole Markup Language, for Google Earth), GeoJSON (geographic JSON), an STK (Systems Tool Kit) ephemeris, or a SigMF (Signal Metadata Format) recording. --export list says which formats apply to a scenario; SigMF applies only to spectrum. The orbit pack also exports --export-sp3, --export-omm and --export-oem (CCSDS, the Consultative Committee for Space Data Systems, orbit messages). See INTEROP.md.

Graded exercises#

Work through the ladder. Each tier is harder and more defensible than the last; reference solutions live in exercises/.

The reference solutions use the Python extension (maturin develop --features python first). Run from the repository root, tier2_sweep.py prints the chip-scale atomic clock’s holdover falling from 2610 s at a 20 ns spec to 1140 s at 5 ns.

Want fresh data?#

The headline numbers in these tutorials run entirely from scenarios already in the repo. Nothing is fetched, which is what keeps them reproducible and safe to run in continuous integration (CI). For the “extend it” exercises you can pull live data:

• GPS two-line elements (TLEs) (refresh the orbit constellation): https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle, plain-text 3-line element sets (name + line 1 + line 2). Helper: scripts/fetch_tles.sh. Open data (US Space Force 18th Space Defense Squadron catalogue, redistributed by Celestrak, Dr T. S. Kelso).
• SGP4 (Simplified General Perturbations 4) verification oracle (already vendored, don’t refetch): AIAA (American Institute of Aeronautics and Astronautics) 2006-6753 “Revisiting Spacetrack Report #3” test vectors, https://celestrak.org/publications/AIAA/2006-6753/, used by tests/sgp4_verification.rs; see docs/SGP4-VALIDATION.md.
• Clock-stability relations oracle: NIST (National Institute of Standards and Technology) Special Publication 1065 (Riley, Handbook of Frequency Stability Analysis), https://tf.nist.gov/general/pdf/2220.pdf, the σ_y(τ)↔phase relations behind Tutorial 2.