kshana 0.7.0 → 0.9.0

package/README.md

@@ -1,8 +1,16 @@
+<p align="center">
+  <img src="docs/assets/kshana-mark.svg" alt="Kshana mark — a precision reticle hung from the Devanagari shirorekha" width="104" height="104">
+</p>
+
 <h1 align="center">
   <img src="docs/assets/kshana-banner.svg" alt="Kshana — the precise instant. Open, reproducible hybrid quantum/classical PNT performance simulation." width="760">
 </h1>
 
+<p align="center"><em><strong>Kshana</strong> · <span lang="sa">क्षण</span> — Sanskrit for <em>the precise instant</em>, the smallest measure of time.</em></p>
+
 <p align="center">
+  <a href="https://ashfordeou.github.io/kshana/"><img src="https://img.shields.io/badge/playground-try%20in%20browser-2dd4bf" alt="Live playground — run in your browser, no install"></a>
+  <a href="tests/sgp4_verification.rs"><img src="https://img.shields.io/badge/SGP4-666%2F666%20AIAA%20vectors%20%C2%B7%204.12mm-3fb950" alt="SGP4 validated against all 666 AIAA 2006-6753 vectors, worst 4.12 mm"></a>
   <a href="https://github.com/ashfordeOU/kshana/actions/workflows/ci.yml"><img src="https://github.com/ashfordeOU/kshana/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/ashfordeOU/kshana/releases"><img src="https://img.shields.io/github/v/release/ashfordeOU/kshana?sort=semver" alt="Release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache-2.0"></a>
@@ -11,7 +19,10 @@
 
 <p align="center">
   <strong>Kshana</strong> (क्षण, Sanskrit: <em>"the precise instant"</em>) is an open, reproducible
-  simulator for <strong>hybrid quantum/classical PNT</strong> — positioning, navigation, and timing.
+  <strong>PNT-resilience simulator with quantum-sensor performance models</strong> —
+  positioning, navigation, and timing. It compares quantum and classical sensors using
+  published Allan/noise-budget coefficients; it is not a first-principles quantum-physics
+  simulator (see <a href="docs/QUANTUM-MODELS.md">docs/QUANTUM-MODELS.md</a>).
 </p>
 
 It quantifies, in hard and reproducible numbers, what quantum clocks, quantum
@@ -23,20 +34,36 @@ and every sensor parameter is traceable to a published source.
 *Free and open source under Apache-2.0, professionally developed and maintained by
 Ashforde OÜ — commercial support, integration, and proprietary extensions available.*
 
-> **Status: research-grade, v0.6.0.** Four sensor packs that each report all six
-> operational figures of merit (including a clock-aided spoof-detection security
-> score, with an active spoofing-attack demonstrator), a joint Kalman fusion
-> estimator and an integrity bound, multi-constellation geometry-derived GNSS
-> availability *and* position accuracy (dilution of precision) from orbits — synthetic
-> Walker, Keplerian mean elements, or full two-line element sets propagated with
-> **SGP4/SDP4** (validated against the AIAA 2006-6753 vectors) — a full IMU
-> Allan-variance noise model, Monte Carlo confidence bands,
-> trade-study parameter sweeps, and a shareable HTML scorecard — all calibrated to
-> published data and validated against the standard relations, with optional Python and
-> WebAssembly bindings and a browser playground. Read [`docs/VALIDATION.md`](docs/VALIDATION.md)
+> **Status: v0.9.0 — a simulation substrate, not yet a product.** Four sensor packs
+> that each report all six operational figures of merit (including a clock-stability-based
+> spoof-*detectability* bound — analytic, meaningful only with a configured attack —
+> demonstrated by an active spoofing-attack scenario), two independent Kalman error
+> budgets (clock and position) reported as a combined FoM, and a filter
+> self-consistency bound, multi-constellation geometry-derived GNSS availability *and*
+> dilution of precision from orbits — synthetic Walker, Keplerian mean elements, or
+> full two-line element sets propagated with **SGP4/SDP4** (validated against the AIAA
+> 2006-6753 vectors) — a single-axis (1-DOF) IMU error budget in the shipped
+> inertial pack (velocity/angle random walk and bias-instability), Monte Carlo
+> confidence bands, trade-study parameter sweeps, and a shareable HTML scorecard.
+> As of v0.9.0 the library also carries a genuine **three-axis strapdown INS**
+> (quaternion attitude, WGS-84 NED mechanization, coning/sculling, a five-term IMU
+> error model), a **loosely-coupled GNSS/INS error-state EKF** with closed-loop
+> feedback, **real snapshot and solution-separation (ARAIM-style) RAIM** with
+> HPL/VPL and a runnable `integrity` scenario, and **RINEX-3 GPS ephemeris
+> ingestion** (broadcast orbit + clock). All calibrated to published data and
+> validated against the standard relations, with optional Python and WebAssembly
+> bindings and a browser playground. Read [`docs/VALIDATION.md`](docs/VALIDATION.md)
 > before citing any number — each noise term is labelled `validated` or `not modeled`,
 > and optical-clock figures are *space goals on ground hardware* (no strontium optical
-> clock has flown).
+> clock has flown). What it is still **not**: the shipped `inertial` scenario pack
+> remains the 1-DOF budget (the three-axis navigator is library-level, not yet wired
+> into a pack); the GNSS/INS filter is *loosely* coupled only (tight/pseudorange
+> coupling is a documented stub); the RAIM is real but **not** formally certified to
+> DO-229/DO-178C aviation standards; and the quantum models are phenomenological, not
+> a first-principles quantum simulator. The full
+> honest scope map is in [`docs/CAPABILITY.md`](docs/CAPABILITY.md); see also
+> [`docs/INTEGRITY.md`](docs/INTEGRITY.md) and the claims table in
+> [`docs/VALIDATION.md`](docs/VALIDATION.md).
 
 > **Try it in your browser:** the [playground](web/) runs the engine client-side as
 > WebAssembly — pick a scenario, edit the parameters, and see the result, with nothing
@@ -148,6 +175,7 @@ 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/integrity-raim.toml
 ```
 
 Example output (clock holdover — note the Integrity and Security figures of merit):
@@ -163,6 +191,20 @@ spoof-detection margin (`security 0.000`). The orbit scenario additionally repor
 geometry block — fraction of samples with a fix, and best/median 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`](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 classification.
+
 ### Python
 
 An optional Python extension (PyO3, abi3) wraps the same engine. Build and install
@@ -240,15 +282,27 @@ drift = 0.0
 Optional fields (off when absent): a clock may add `flicker_floor` (1/f FM 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), completing the IMU Allan-variance noise model. A
+acceleration random walk) — together a **single-axis (1-DOF) accelerometer error
+budget** (VRW/ARW 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
+§A.2; Groves 2013 §4.3). That 3-axis path is **not yet wired into the scenario
+pack/FoM** — switching the pack over, with a loosely-coupled GNSS/INS filter, is
+the next inertial milestone. 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 a single joint Kalman filter as the
-navigator — fusing the clock and position states, disciplined by GNSS and aided by
-optical time transfer — and reports fused holdover with a joint-covariance integrity
-(see `scenarios/fusion-pnt.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 ramping false-time spoof (an `[attack]` block with
 `start_s` and `rate_ns_per_s`) and runs each clock's integrity monitor, reporting
@@ -300,18 +354,24 @@ See `scenarios/` for one example of every kind.
 ## 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, and a
-**scenario hash** — so any chart can be reproduced from the file. The figures of
+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}]`): the overlapping Allan deviation across
+octave-spaced averaging times, the standard way to read a clock's stability. The
+browser playground renders it as a log-log "Clock stability (ADEV)" chart. (MDEV/TDEV/HDEV
+and confidence intervals are not yet computed — roadmap.) Every field, with units and a
+source pointer, is documented in [`docs/SCHEMA.md`](docs/SCHEMA.md). The figures of
 merit follow the standard operational PNT figures of merit:
 
 | Figure of merit | How Kshana computes it |
 |-----------------|------------------------|
-| Positioning / Timing Performance | RMS + 95th-percentile error over the outage |
-| Autonomy | holdover duration — time in-spec after GNSS loss |
+| Timing Performance (clock/orbit packs) | clock-phase error RMS + 95th-percentile over the outage, in **nanoseconds** (`timing_rms_ns`) — a timing metric, not position |
+| Positioning Performance (inertial/hybrid packs) | 1-DOF position-error RMS + 95th-percentile over the outage, in **metres** (`pos_rms_m`); single-axis. A single run is flagged `monte_carlo: false`; set `runs = N` for a Monte Carlo ensemble that reports each metric's mean, spread, and bootstrap 95% CI. Still **not** a 2-D CEP/2DRMS or DOP-weighted accuracy (those need the 3-axis model — roadmap) |
+| Autonomy | holdover duration — time in-spec after GNSS loss (grid-quantised: a lower bound) |
 | Resilience | error-growth slope during the outage |
 | Availability | fraction of the run with an in-spec solution |
-| Integrity | protection-level containment — fraction of outage samples whose error stays inside the Kalman filter's k-sigma bound (clock pack) |
-| Security | clock-aided spoof-detection score — how far below the timing spec a time-spoof can be flagged by cross-checking GNSS time against the clock's own coasted prediction (clock and orbit packs) |
+| Integrity | filter **self-consistency** — fraction of outage samples whose error stays inside the Kalman filter's own k-sigma bound. **Not** an aviation HPL/VPL/RAIM integrity figure (see [`docs/INTEGRITY.md`](docs/INTEGRITY.md)) |
+| Security | **analytic spoof-*detectability* bound** from clock stability — how small/slow a time-spoof a single-clock consistency monitor could flag. Meaningful only with a configured attack; **not** a multi-satellite RAIM detector |
 
 New to these terms? Each is defined in plain language in the [glossary](docs/GLOSSARY.md).
 
@@ -343,7 +403,7 @@ flowchart TD
       models["models — ClockModel (+ flicker)"]
       estimator["estimator — holdover"]
       kalman["kalman — Integrity bound"]
-      security["security — spoof-detection score"]
+      security["security — analytic spoof-detectability bound"]
       fom["fom · report · run"]
     end
     p2["Pack 2 · inertial — accel + gyro"]
@@ -403,6 +463,9 @@ kshana/
 | [Glossary](docs/GLOSSARY.md) | everyone | plain-language definitions of every term |
 | [Architecture](docs/ARCHITECTURE.md) | developers / reviewers | module map, engine pipeline, dispatch, and diagrams |
 | [Validation status](docs/VALIDATION.md) | reviewers / citers | what is `validated` vs `not modeled`, with evidence |
+| [Reproducibility &amp; provenance](docs/REPRODUCIBILITY.md) | reviewers / packagers | determinism guarantees, golden-pinning, SBOM, build provenance |
+| [Positioning](docs/POSITIONING.md) | evaluators | where Kshana sits vs RTKLIB/gLAB (complementary), and the zero-install browser tier |
+| [SGP4 validation](docs/SGP4-VALIDATION.md) | reviewers / citers | agreement with the AIAA 2006-6753 reference (666 states, ~4 mm) |
 | [Changelog](CHANGELOG.md) | everyone | released history (Keep a Changelog + SemVer) |
 | [Contributing](CONTRIBUTING.md) | contributors | build, guards, test/citation discipline, DCO |
 | [Code of Conduct](CODE_OF_CONDUCT.md) | community | expected conduct (Contributor Covenant) |
@@ -476,12 +539,15 @@ CPython versions).
 ## Roadmap
 
 See [`CHANGELOG.md`](CHANGELOG.md) for released history and the `[Unreleased]`
-section for what's next (higher-fidelity SGP4 orbit propagation). An active
-spoofing-attack demonstrator, multi-constellation availability, a full IMU
-Allan-variance noise model, a joint Kalman fusion estimator, real constellation
-geometry from TLEs, an HTML scorecard report, a clock-aided spoof-detection Security
-score across all four packs, geometry-derived GNSS availability *and* position
-accuracy (dilution of precision) from Keplerian orbits with eccentricity and J2 drift,
+section for what's next (Earth-fixed frame reduction — TEME&rarr;ECEF/ITRF — and
+explicit time systems: UTC/UT1/TAI/TT with leap seconds). SGP4/SDP4 orbit
+propagation has **shipped** (v0.7.0, validated against the AIAA 2006-6753 vectors),
+and its inertial velocity is now exposed downstream. An active
+spoofing-attack demonstrator, 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, a
+clock-stability-based spoof-detectability bound, 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`.
@@ -498,7 +564,7 @@ entry for every user-visible change. Participation is governed by our
 
 If you use Kshana in academic or technical work, please cite it. Machine-readable
 metadata is in [`CITATION.cff`](CITATION.cff) (GitHub renders a "Cite this repository"
-button from it); cite the version you used (e.g. `v0.6.0`).
+button from it); cite the version you used (e.g. `v0.7.0`).
 
 ## License
 

package/package.json

@@ -5,7 +5,7 @@
     "Chakshu Baweja <contact@ashforde.org>"
   ],
   "description": "Open hybrid quantum/classical PNT performance simulator",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",