APIs and integrationsEdit on GitHubSource: docs/PYTHON_API.md

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_toml and error_kind execute the scenario, so they surface parse, configuration, and runtime errors. They never raise.
  • run / run_typed raise ValueError on an invalid scenario.
  • Results are reproducible: a scenario carries its seed and the engine records a scenario_hash, so the same input yields byte-identical output on the same platform (see REPRODUCIBILITY.md).
  • .array, .columns and .series return exactly numpy.asarray(...) of the same values .data() gives (same dtype, bit-identical; tests/python/test_numpy_runoutput.py). They import NumPy when called and raise ImportError without it; NumPy stays out of the package's runtime requirements. KeyError means the path is missing, ValueError that the value there is not a numeric array (or not a list of records). Runnable notebooks are in notebooks/.

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.