Python API
Kshana ships a first-class Python application programming interface (API), built with
PyO3 and maturin. Its abi3 wheels are
built against the stable Python application binary interface (ABI), so one wheel per
platform works across CPython ≥ 3.9; wheels cover Linux, macOS and Windows, each on
x86-64 and 64-bit ARM (see WHEEL_TAGS.md). A bundled type stub
(kshana.pyi + py.typed) gives editors and mypy/pyright full type information.
pip install kshana # from the Python Package Index, PyPI (release wheels)
# or, from a checkout:
pip install maturin && maturin develop --features python
Quickstart#
Run these snippets from the root of a repository checkout: they read scenario files
under scenarios/. The NumPy line needs pip install numpy.
import kshana
toml = open("scenarios/clock-holdover.toml").read()
# Typed result with a parsed-dict accessor:
out = kshana.run_typed(toml)
print(out.summary)
data = out.data() # a Python dict — no JSON re-parsing
fom = data["quantum"]["fom"] # figures of merit, quantum side
classical_fom = data["classical"]["fom"] # … and the classical baseline
print(out.json[:80], "...") # raw JSON also available
open("chart.svg", "w").write(out.svg) # the chart SVG
# NumPy arrays straight from the result (NumPy is imported on call; it is not a
# dependency of the package):
curve = out.columns("quantum.adev_curve") # {"tau_s": ndarray, "adev": ndarray, ...}
adev = curve["adev"]
everything = out.series() # every record series, keyed by path
Surface#
| Symbol | Signature | Returns |
|---|---|---|
run_typed |
(toml: str) -> RunOutput |
typed result (.json, .svg, .summary, .csv, .data(), .array(), .columns(), .series(), .write_csv()) |
run |
(toml: str) -> str |
result document as a JSON (JavaScript Object Notation) string |
run_full |
(toml: str) -> tuple[str, str, str] |
(json, svg, summary) |
scenario_kinds |
() -> list[dict] |
available scenario kinds + metadata (parsed) |
list_kinds |
() -> str |
the same metadata as ONE JSON-array string, not a list (kept for existing callers; use scenario_kinds for the parsed list) |
validate_toml |
(toml: str) -> list[str] |
error messages (empty if valid) |
error_kind |
(toml: str) -> str | None |
failure-category tag (invalid_input, non_convergence, unsupported or io_error), or None on success |
version / __version__ |
() -> str / str |
engine version |
receiver_trust |
(toml: str) -> RunOutput |
assess a real receiver log described by a receiver-trust scenario: result document, per-epoch trust CSV, chart and summary; a [platform] kind = "vessel" table adds the maritime monitors and the 0-100 trust score with reasons (advisory) |
receiver_trust_replay |
(session_toml, nmea) -> dict |
a bounded NMEA excerpt scored the way live mode scores it: per-epoch state, 0-100 score and reasons, a summary (no socket, no gate; advisory) |
assess_vessel_log |
(session_toml, log) -> dict |
a vessel's NMEA log as a batch run: the score model and every epoch's score with its deductions (advisory) |
jammertest_import |
(catalog_json, plans, log_start_utc, location=None, local_offset_h=2.0, year=None) -> dict |
the published Jammertest catalogue and plan as scheduled-truth events (events_toml, events); planned slots, not recorded on-air times |
jammertest_score |
(session_toml, log, catalog_json, plans, location=None, local_offset_h=2.0, log_start_utc=None, year=None, recover_hold_s=10.0, guard_s=60.0) -> dict |
a receiver log scored against that schedule: per-test latency, missed, time to recover, false alarms (MODELLED; a signed pack needs the command line) |
evidence_create |
(session_toml, log, from_s, to_s, title=None, created_utc=None, seed_hex=None) -> dict |
a signed evidence pack for a window of the log, in memory: files, public_key, seed_hex (keep it private); a technical record, not a legal opinion |
evidence_verify |
(files, public_key=None, full_log=None, require_timestamp=False) -> dict |
verify a pack: hashes, chain, signature, optionally the trusted signer, the full log and a timestamp; verdict is verified, intact-signer-not-pinned (no public key given: intact, signer not established) or failed |
export_sp3, export_omm, export_oem |
(toml) -> str |
the CLI's --export-sp3/-omm/-oem artifacts as text |
export_formats |
(toml) -> list[dict] |
which interoperability formats apply to a scenario, without running it |
export_scenario |
(toml, format) -> dict |
czml, kml, geojson, stk or sigmf in memory: {format, spec_url, files}, each file {suffix, bytes, sha256, encoding, content} (utf-8 text or base64) |
import_route |
(toml, geojson) -> str |
a GeoJSON route written into a waypoint-track scenario (--import-route) |
animate_scenario |
(toml, format="svg", fps=None, duration_s=None, width=None) -> dict |
the run's time series as an animated SVG, an HTML player or up to 120 SVG frames: {summary, files} |
list_examples, get_example |
(kind=None) -> dict, (name) -> str |
the bundled reference scenarios and their TOML |
evidence_attach_timestamp |
(files, token, replace=False) -> dict |
bind an RFC 3161 token (bytes or base64) to a pack in memory: {files, notes}; the pack must still verify; the authority's signature is not checked |
evidence_keygen |
() -> dict |
a new signing key in memory: seed_hex (PRIVATE), public_key, fingerprint, warning; Python only |
iq_sweep |
(i, q, fs_hz, signal, prns, ..., pll_bws=None, dll_bws=None, spacings=None, coherents=None, design=None) -> dict |
replay one recording across loop designs (iq sweep): per design and PRN steady-state jitter, lock fractions and C/N0; one acquisition per PRN, every channel on the same samples |
iq_info, iq_inventory |
(path, hash=False) -> dict, (directory, recursive=False, hash=False) -> list |
describe one recording, or every recording in a folder (reads files; hash reads them fully) |
bench_export |
(toml, epoch=None) -> dict |
a scenario's vehicle motion and events for a laboratory GNSS simulator, in memory: {files: {suffix: text}, notes, notice}; kinds gnss-ins, jamming, gnss-sim; no signal is written, keep notice with the files |
compliance_report |
(runs) -> dict |
the public-framework mapping filled from result texts: runs is a list of {label, result, scenario?} dicts (text, at most 64); returns {report, markdown}; each row's status says the runs support evidence for its capabilities, not that a framework is met; carry report["statement"] with any display |
compliance_mapping |
(sources=False) -> str |
the static mapping tables (or the source documents) as Markdown, led by the statement |
standards_pack_list |
() -> dict |
the standards packs (id, title, framework, test counts) and a notice; a pack measures modelled scenarios against bars stated before the run |
standards_pack_run |
(pack_id) -> dict |
one pack run: each test MET, NOT MET or NEEDS INPUT with measured and expected values, plus the report as Markdown under markdown; raises ValueError for an unknown id |
lunanet_afs_check_spec |
() -> dict |
the LunaNet AFS implementation checked against the printed tables and worked examples of LSIS-AFS V1.0 (bars B1 to B10; B4 reports one pinned miss) |
lunanet_afs_check_symbols |
(symbols, max_sp_errors=0) -> dict |
an AFS symbol stream (text of 0 and 1) checked for sync pattern, SB1 decoding, FID, TOI continuity and spacing; LDPC and CRC-24Q of subframes 2 to 4 are not verified |
lunanet_afs_generate |
(frames=1, toi0=0) -> str |
a test symbol stream with placeholder subframes (not a waveform) |
evidence_round_trip |
(scoring_toml, scenario_toml, conditions, log, from_s, to_s, title=None, created_utc=None, seed_hex=None) -> dict |
the signed laboratory round-trip pack linking scenario, test conditions (docs/spec/TEST-CONDITIONS.md), receiver log and score by hash; as evidence_create |
bench_score |
(truth_json, predictions_json, threshold=None) -> str |
a kshana-bench result file (JSON text) from a truth file and a predictions file; MODELLED |
bench_leaderboard |
(results: list[str]) -> str |
kshana-bench result files rendered as the static leaderboard page (HTML) |
osnma_verify |
(data, format="", start_gst=None, merkle_root_hex="", public_keys=None, reference_time=None, max_time_error=None) -> dict |
Galileo OSNMA authentication of I/NAV pages or a UBX stream in memory: the dict kshana osnma verify --json prints, with the advisory in its advisory field; advisory only, not a navigation integrity service |
sky_geometry |
(request) -> dict |
the satellites a site sees under an azimuth-dependent skyline: per satellite visible / masked, GDOP, PDOP, HDOP, VDOP, TDOP, the east-north-up cofactor and covariance and the horizontal error ellipses; request is JSON or TOML text or a dict (site, time_s, systems, tle, satellites, mask_deg, skyline, clock, sigma_uere_m, confidence); the visibility decision and the ellipse are checked against independent libraries, the rest is MODELLED, and the result carries the advisory (sky_source, sky_statement say whether the sky is representative or from element sets) |
sky_monte_carlo |
(request, seed=0, n=1000) -> dict |
n (1 to 5000) seeded least-squares errors on the visible set of request, with their empirical covariance, RMS and the fraction inside the 95 % ellipse |
skyline_presets |
() -> list[dict] |
the skyline presets (city-street, harbour-approach, fjord, container-terminal) with their REPRESENTATIVE label, provenance and the cut every degree of azimuth; representative geometries, not surveys |
skyline_profile |
(skyline) -> dict |
a skyline section (table, street canyon, sectors, terrain) reduced to the normalised 360-entry table the engine uses |
skyplot_svg |
(request) -> str |
the skyplot of request as static SVG text |
trust_telemetry |
(input, format, host="", input_kind="jsonl", expose_position=False, syslog_all=False, unix_nano=0) -> str |
a trust stream (jsonl) or receiver-trust result as Prometheus text, CEF or LEEF syslog lines or an OTLP JSON payload, with the kshana trust-telemetry encoders; nothing is sent and no clock is read (syslog lines carry no timestamp) |
interference_map |
(source, csv, dataset, cell_deg=None, licence=None, licence_url=None, attribution=None, land_geojson=None) -> list[dict] |
a GNSS interference map from ADS-B or AIS CSV text: one dict per UTC day with kshana-interference-map/v1 GeoJSON (aggregate only; a degraded cell does not name interference as the cause) |
interference_emitter_regions |
(source, csv, dataset, licence=None, licence_url=None, attribution=None, land_geojson=None) -> dict |
estimated emitter regions from ADS-B or AIS CSV text: {stem, geojson, summary, csv, svg, sessions_published, sessions_withheld}, each labelled MODELLED; regions at stated confidence with a centroid and an uncertainty ellipse, never a bare point; aggregate only, and a region is not the position of anyone nor a finding of the cause |
route_exposure |
(route, maps, date_from=None, date_to=None) -> str |
share of a route through degraded cells of those maps, as JSON text (not a forecast; unobserved cells are not evidence of a clear route) |
nmea_training |
(toml, seed=None) -> dict |
synthetic bridge NMEA for crew training plus the instructor log (nmea, log_json, log_text); text only, never for a vessel's live navigation systems |
iq_signals |
() -> list[str] |
the GNSS IQ signal names iq_scene, iq_acquire and iq_track accept (gps-l1ca, galileo-e1b, glonass-l1of, ...) |
iq_scene |
(fs_hz, duration_s, signal, prns, **options) -> dict |
a multi-satellite GNSS IQ scene in memory: samples_i / samples_q and per-epoch truth |
iq_scene_broadcast |
(fs_hz, window_s, nav_text, rx_lat, rx_lon, rx_alt, **options) -> dict |
the same, with each GPS satellite at its broadcast-ephemeris geometry from a RINEX (Receiver Independent Exchange Format) navigation message |
iq_acquire |
(i, q, fs_hz, signal, prns, **options) -> list[dict] |
FFT (fast Fourier transform) acquisition of each PRN (pseudorandom noise code): Doppler, code phase, statistic, threshold |
iq_acq_surface |
(i, q, fs_hz, signal, prn, **options) -> dict |
the whole acquisition surface of one PRN (kshana.acq-surface/1): rows[doppler][lag] correlation power, the peak and two fine-Doppler refinements (parabolic, fine_search) |
iq_track |
(i, q, fs_hz, signal, prns, **options) -> dict |
acquire, then track each PRN: per-epoch Doppler, code phase, lock indicators, C/N0, prompt correlator |
iq_frontend |
(i, q, fs_hz, **options) -> dict |
the receiver front-end chain (band-pass, notch, blanking, excision, AGC (automatic gain control), quantiser) over complex samples |
iq_labfit |
(toml: str) -> dict |
fit the tracking-loop loss-of-lock model to a receiver-trust timeline (an iq-labfit scenario) |
iq_loop_designs |
(toml) -> list[dict] |
parse a kshana.loop-design/1 file (a path or TOML text) into its resolved designs, each with its name and hash; ValueError on an invalid file |
iq_read_epochs |
(path) -> dict |
read a binary tracking-epoch file (kshana.track-epoch/1, as kshana iq track --epochs writes it): the header and one dict per epoch in records |
iq_monitor |
(path, signal=None, prns=None, power=False, spectral=False, settings=None, ...) -> dict |
the IQ detection monitors over a recording in one streaming pass (iq monitor): series, events, spectra and notes; reads a file |
iq_test_conditions |
(conditions) -> dict |
validate a lab test-condition file (kshana.test-conditions/1, TOML or JSON, a path or text) and return it resolved, with its hash |
iq_campaign |
(campaign, out_dir, workers=0, resume=True, max_cells=None, dry_run=False) -> dict |
run a lab-replay campaign (kshana.campaign/1) into out_dir as kshana iq campaign does; finished cells are skipped; returns the cell counts, failures and the digest once every cell is done |
iq_campaign_report |
(out_dir) -> dict |
rebuild a campaign's scorecards, HTML report and digest from its cells: the cell and row counts, the rows failing a bar and the digest |
GNSS IQ and receiver-trust signatures#
The full signatures, as kshana.pyi states them (every keyword after the required
arguments has a default; the docstrings in the stub give each one's meaning). Wrap the
samples_i / samples_q lists, and the i / q inputs, with numpy.asarray(...) for
arrays.
def receiver_trust(toml: str) -> RunOutput: ...
def receiver_trust_replay(session_toml: str, nmea: str | bytes) -> dict: ...
def assess_vessel_log(session_toml: str, log: str | bytes) -> dict: ...
def jammertest_import(catalog_json: str, plans: list[str], log_start_utc: str, location: int | None = None,
local_offset_h: float = 2.0, year: int | None = None) -> dict: ...
def jammertest_score(session_toml: str, log: str | bytes, catalog_json: str, plans: list[str],
location: int | None = None, local_offset_h: float = 2.0,
log_start_utc: str | None = None, year: int | None = None,
recover_hold_s: float = 10.0, guard_s: float = 60.0) -> dict: ...
def evidence_create(session_toml: str, log: str | bytes, from_s: float, to_s: float,
title: str | None = None, created_utc: str | None = None,
seed_hex: str | None = None) -> dict: ...
def evidence_verify(files: dict[str, str | bytes], public_key: str | None = None,
full_log: str | bytes | None = None,
require_timestamp: bool = False) -> dict: ...
def interference_map(source: str, csv: str, dataset: str, cell_deg: float | None = None,
licence: str | None = None, licence_url: str | None = None,
attribution: str | None = None, land_geojson: str | None = None) -> list[dict]: ...
def route_exposure(route: str, maps: list[str], date_from: str | None = None,
date_to: str | None = None) -> str: ...
def export_sp3(toml: str) -> str: ...
def export_omm(toml: str) -> str: ...
def export_oem(toml: str) -> str: ...
def export_formats(toml: str) -> list[dict]: ...
def export_scenario(toml: str, format: str) -> dict: ...
def import_route(toml: str, geojson: str) -> str: ...
def animate_scenario(toml: str, format: str = "svg", fps: int | None = None,
duration_s: float | None = None, width: int | None = None) -> dict: ...
def list_examples(kind: str | None = None) -> dict: ...
def get_example(name: str) -> str: ...
def evidence_attach_timestamp(files: dict[str, str | bytes], token: str | bytes,
replace: bool = False) -> dict: ...
def evidence_keygen() -> dict: ...
def iq_sweep(i: list[float], q: list[float], fs_hz: float, signal: str, prns: list[int],
**options) -> dict: ...
def iq_info(path: str, hash: bool = False) -> dict: ...
def iq_inventory(directory: str, recursive: bool = False, hash: bool = False) -> list[dict]: ...
def bench_export(toml: str, epoch: str | None = None) -> dict: ...
def compliance_report(runs: list[dict[str, str]]) -> dict: ...
def compliance_mapping(sources: bool = False) -> str: ...
def standards_pack_list() -> dict[str, Any]: ...
def standards_pack_run(pack_id: str) -> dict[str, Any]: ...
def lunanet_afs_check_spec() -> dict[str, Any]: ...
def lunanet_afs_check_symbols(symbols: str, max_sp_errors: int = 0) -> dict[str, Any]: ...
def lunanet_afs_generate(frames: int = 1, toi0: int = 0) -> str: ...
def evidence_round_trip(scoring_toml: str, scenario_toml: str, conditions: str, log: str | bytes, from_s: float, to_s: float, title: Optional[str] = None, created_utc: Optional[str] = None, seed_hex: Optional[str] = None) -> dict[str, Any]: ...
def bench_score(truth_json: str, predictions_json: str, threshold: float | None = None) -> str: ...
def bench_leaderboard(results: list[str]) -> str: ...
def osnma_verify(data: bytes | str, format: str = "", start_gst: int | None = None,
merkle_root_hex: str = "", public_keys: list[str] | None = None,
reference_time: int | None = None, max_time_error: int | None = None) -> dict: ...
def sky_geometry(request: str | dict[str, Any]) -> dict[str, Any]: ...
def sky_monte_carlo(request: str | dict[str, Any], seed: int = 0, n: int = 1000) -> dict[str, Any]: ...
def skyline_presets() -> list[dict[str, Any]]: ...
def skyline_profile(skyline: str | dict[str, Any]) -> dict[str, Any]: ...
def skyplot_svg(request: str | dict[str, Any]) -> str: ...
def trust_telemetry(input: str, format: str, host: str = "", input_kind: str = "jsonl",
expose_position: bool = False, syslog_all: bool = False,
unix_nano: int = 0) -> str: ...
def nmea_training(toml: str, seed: int | None = None) -> dict[str, str]: ...
def iq_signals() -> list[str]: ...
def iq_scene(
fs_hz: float,
duration_s: float,
signal: str,
prns: list[int],
dopplers: Optional[list[float]] = ...,
cn0_dbhz: Optional[float] = ...,
center_hz: Optional[float] = ...,
if_hz: float = ...,
noise: bool = ...,
noise_figure_db: float = ...,
seed: int = ...,
data: bool = ...,
threads: int = ...,
iono_stec: Optional[float] = ...,
iono_vtec: Optional[float] = ...,
iono_klobuchar: bool = ...,
tropo: bool = ...,
tropo_doy: float = ...,
s4: Optional[float] = ...,
scint_tau0: float = ...,
sigma_phi: float = ...,
multipath_height: Optional[float] = ...,
multipath_ground: str = ...,
land_mobile: bool = ...,
nlos: bool = ...,
) -> dict[str, Any]: ...
def iq_scene_broadcast(
fs_hz: float,
window_s: float,
nav_text: str,
rx_lat: float,
rx_lon: float,
rx_alt: float,
prns: Optional[list[int]] = ...,
start_tow: float = ...,
cn0_dbhz: Optional[float] = ...,
center_hz: Optional[float] = ...,
if_hz: float = ...,
noise: bool = ...,
noise_figure_db: float = ...,
seed: int = ...,
mask_deg: float = ...,
threads: int = ...,
) -> dict[str, Any]: ...
def iq_acquire(
i: list[float],
q: list[float],
fs_hz: float,
signal: str,
prns: list[int],
if_hz: float = ...,
center_hz: Optional[float] = ...,
coherent: int = ...,
noncoherent: int = ...,
doppler_max: float = ...,
doppler_step: Optional[float] = ...,
pfa: float = ...,
) -> list[dict[str, Any]]: ...
def iq_acq_surface(
i: list[float],
q: list[float],
fs_hz: float,
signal: str,
prn: int,
if_hz: float = ...,
center_hz: Optional[float] = ...,
coherent: int = ...,
noncoherent: int = ...,
doppler_max: float = ...,
doppler_step: Optional[float] = ...,
pfa: float = ...,
) -> dict[str, Any]: ...
def iq_track(
i: list[float],
q: list[float],
fs_hz: float,
signal: str,
prns: list[int],
if_hz: float = ...,
center_hz: Optional[float] = ...,
pll_bw: Optional[float] = ...,
fll_bw: Optional[float] = ...,
dll_bw: Optional[float] = ...,
spacing: Optional[float] = ...,
coherent: Optional[int] = ...,
periods_per_bit: Optional[int] = ...,
acq_coherent: Optional[int] = ...,
acq_noncoherent: int = ...,
doppler_max: float = ...,
max_seconds: Optional[float] = ...,
) -> dict[str, Any]: ...
def iq_frontend(
i: list[float],
q: list[float],
fs_hz: float,
bandpass_lo: Optional[float] = ...,
bandpass_hi: Optional[float] = ...,
bandpass_transition: Optional[float] = ...,
bandpass_atten: float = ...,
notch: bool = ...,
notch_r: float = ...,
notch_mu: float = ...,
blank: Optional[float] = ...,
blank_hold: int = ...,
excise: bool = ...,
excise_fft: int = ...,
excise_pfa: float = ...,
agc: bool = ...,
agc_tau: float = ...,
bits: Optional[int] = ...,
quant_step: Optional[float] = ...,
no_agc: bool = ...,
) -> dict[str, Any]: ...
def iq_labfit(toml: str) -> dict[str, Any]: ...
def iq_loop_designs(toml: str) -> list[dict[str, Any]]: ...
def iq_read_epochs(path: str) -> dict[str, Any]: ...
def iq_monitor(path: str, signal: Optional[str] = ..., prns: Optional[list[int]] = ...,
power: bool = ..., spectral: bool = ..., settings: Optional[str] = ...,
**options) -> dict[str, Any]: ...
def iq_test_conditions(conditions: str) -> dict[str, Any]: ...
def iq_campaign(campaign: str, out_dir: str, workers: int = 0, resume: bool = True,
max_cells: Optional[int] = None, dry_run: bool = False) -> dict[str, Any]: ...
def iq_campaign_report(out_dir: str) -> dict[str, Any]: ...
A lab-replay campaign from Python, then its report (the campaign file and its recordings
are yours; a finished cell is skipped on the next call; iq_read_epochs reads a tracking-epoch file a
kshana iq track --epochs run wrote):
import kshana
summary = kshana.iq_campaign("lab.campaign.toml", "campaign-out", workers=4)
report = kshana.iq_campaign_report("campaign-out")
print(report["digest"]) # None until every cell is done
iq_track's acq_coherent sets how many code periods the hand-off acquisition
integrates coherently. From 0.33.0 it defaults to None, meaning auto: about 4 ms
(4 periods for a 1 ms code such as GPS L1 C/A, 1 for a code of 4 ms or longer), so the
channel starts close enough for the frequency loop to pull in; acq_coherent=1 keeps
the 0.32 one-period search.
Types#
kshana.pyi types the closed vocabularies for checkers (mypy, pyright): ScenarioKind
(every kind name, a Literal), ErrorKind (the four tags error_kind returns),
ProvenanceClass, and the TypedDicts KindMeta (what scenario_kinds() returns a
list of) and FieldUnit (an entry of a result's units block, which extends the required-keys base _FieldUnitBase). They exist for type
checkers only and are not importable at runtime; tests/typed_api_sync.rs keeps them
equal to the engine's lists.
from typing import TYPE_CHECKING
import kshana
if TYPE_CHECKING:
from kshana import ScenarioKind
names: "list[ScenarioKind]" = [k["name"] for k in kshana.scenario_kinds()]
RunOutput#
| Member | Type | Notes |
|---|---|---|
.json |
str |
full result document (JSON) |
.svg |
str |
standalone chart SVG (Scalable Vector Graphics) |
.summary |
str |
one-line human summary |
.csv |
str | None |
the reproducibility table, for the kinds that emit one (see below) |
.data() |
dict |
the result parsed into a Python dict (see the shape note below) |
.array(path) |
numpy.ndarray |
the numeric list at path (dotted, "points.0.coords", or a JSON Pointer, "/points/0/coords"): 1-D for numbers, 2-D for equal-length numeric lists |
.columns(path) |
dict[str, numpy.ndarray] |
the list of records at path (a time series), one array per field that is a number in every record |
.series() |
dict[str, dict[str, numpy.ndarray]] |
every list of records with a numeric field, keyed by dotted path, each as .columns |
.write_csv(path) |
int |
write that table to path; returns the bytes written, or 0 (and writes nothing) when the kind emits no table |
The reproducibility table#
realtime-frame-eop, lunar-time-budget, lunar-jamming, telecom-timing and
leo-navmsg always publish a table; moonlight-service-volume publishes one when an
export site (export_site_lat_deg + export_site_lon_deg) is configured. Every other kind returns csv = None. The text is
the same bytes the CLI (command-line interface) writes as <scenario>.table.csv, so a reviewer reproducing a
published table from the wheel never has to drop to the command line:
import kshana
out = kshana.run_typed(open("scenarios/realtime-frame-eop.toml").read())
if out.csv is not None:
print(out.write_csv("table.csv"), "bytes written")
Result shape#
The figures of merit and the time series live per run side, not at the top level. For a clock run the document is:
schema_version engine_version scenario_hash seed threshold_ns units figure_tiers
quantum → spec · series · fom · adev_curve · filter_health
classical → spec · series · fom · adev_curve · filter_health
so the figures of merit are data["quantum"]["fom"], never data["figures_of_merit"].
Other kinds emit their own packs; the complete per-field reference, with units and a
source pointer, is field-units-schema.json and the reader's
guide is SCHEMA.md.
Notes#
validate_tomlanderror_kindexecute the scenario, so they surface parse, configuration, and runtime errors. They never raise.run/run_typedraiseValueErroron an invalid scenario.- Results are reproducible: a scenario carries its
seedand the engine records ascenario_hash, so the same input yields byte-identical output on the same platform (seeREPRODUCIBILITY.md). .array,.columnsand.seriesreturn exactlynumpy.asarray(...)of the same values.data()gives (same dtype, bit-identical;tests/python/test_numpy_runoutput.py). They import NumPy when called and raiseImportErrorwithout it; NumPy stays out of the package's runtime requirements.KeyErrormeans the path is missing,ValueErrorthat the value there is not a numeric array (or not a list of records). Runnable notebooks are innotebooks/.
Not in Python: long-running processes#
kshana receiver-trust live (a stream process with a gate and an optional --listen TCP
server) and the telemetry exporters (Prometheus, OTLP, syslog; docs/TRUST-TELEMETRY.md) and kshana nmea-scenario --tcp/--udp streaming are command-line only: a binding
returns when the call returns and does not hold a socket open. Python covers the batch
form of each: receiver_trust for a log, receiver_trust_replay for a stream excerpt (scores and states; the gate is not applied), nmea_training for the generated text.