kshana 0.11.0 → 0.13.0

package/README.md

@@ -12,11 +12,12 @@
 <p align="center">
   <a href="https://ashfordeou.github.io/kshana/"><img src="https://img.shields.io/badge/playground-try%20in%20browser-c79e63" 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://img.shields.io/badge/coverage-~97%25%20line-3fb950" alt="~97% line coverage on src/ (cargo-tarpaulin LLVM engine), gated at 85% in CI"></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>
   <a href="Cargo.toml"><img src="https://img.shields.io/badge/rust-1.75%2B-orange.svg" alt="Rust 1.75+"></a>
-  <a href="https://doi.org/10.5281/zenodo.20528627"><img src="https://zenodo.org/badge/1256508460.svg" alt="DOI"></a>
+  <a href="https://doi.org/10.5281/zenodo.20528627"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20528627-blue.svg" alt="DOI 10.5281/zenodo.20528627"></a>
 </p>
 
 <p align="center">
@@ -42,16 +43,21 @@ citable table in [`docs/PROVENANCE.md`](docs/PROVENANCE.md).
 *Free and open source under Apache-2.0, professionally developed and maintained by
 Ashforde OÜ — commercial support, integration, and proprietary extensions available.*
 
-> **Status: v0.11.0 · a simulation substrate, not yet a product.** A validated,
+> **Status: v0.13.0 · a simulation substrate, not yet a product.** A validated,
 > fully reproducible engine spanning the PNT stack — orbit geometry and constellation
-> design, time systems, inertial navigation (incl. map-aided), GNSS/INS fusion (loose,
-> tight, UKF, coupled clock+position), ARAIM integrity, clocks, advanced time-and-frequency
-> transfer, the GNSS measurement domain, and resilience (jamming + multi-layer spoofing).
+> design, a numerical (Cowell) propagator with a six-perturbation force model, maneuver
+> and trajectory design, time systems, inertial navigation (incl. map-aided and
+> gravity-map-matching alt-PNT), GNSS/INS fusion (loose, tight, UKF, coupled
+> clock+position, 17-state), orbit determination, ARAIM integrity, clocks, advanced
+> time-and-frequency transfer, the GNSS measurement domain, and resilience (jamming +
+> multi-layer spoofing).
 > Honest by design: every figure of merit is labelled *validated* or *not-modeled*, and
 > optical-clock figures are space goals on ground hardware (no strontium optical clock has flown).
 > See **[Capabilities](#capabilities)** for what it does, **[What it is / is not](#what-it-is--is-not)**
 > for scope, and [`docs/CAPABILITY.md`](docs/CAPABILITY.md) / [`docs/VALIDATION.md`](docs/VALIDATION.md)
-> for per-capability maturity and the claims table.
+> for per-capability maturity. The overclaim closure ledger
+> [`docs/CLAIMS-VS-REALITY.md`](docs/CLAIMS-VS-REALITY.md) tracks every historical overclaim,
+> how it was resolved, and a CI guard (`tests/no_overclaims.rs`) that keeps it resolved.
 
 > **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
@@ -121,9 +127,13 @@ the P2 roadmap and [get in touch](#support--professional-services) to collaborat
 | Domain | Capability |
 |--------|------------|
 | **Orbit & geometry** | SGP4/SDP4 propagation (validated to 4.12 mm against all 666 AIAA 2006-6753 vectors); real two-line elements (a committed, date-stamped Celestrak `gps-ops` snapshot) or synthetic Walker-delta constellations whose mean elements realise the `i:T/P/F` formula to under 1 km over a 24 h propagation; multi-constellation visibility, dilution of precision, and GNSS availability; a gradient-free constellation-design optimiser, streets-of-coverage minimum-satellite sizing, a multi-constellation comparison tool, and a Walker **design sweep** that tabulates coverage / PDOP / revisit-time over a planes × satellites grid and reports the Pareto-optimal designs. |
+| **Numerical propagator** | A **Cowell** numerical propagator (`src/propagator.rs`) complementing the analytic SGP4/SDP4 path, with a hierarchical **six-perturbation** force model (`src/forces.rs`): two-body + the full **J2–J6 zonal** field (the exact analytic gradient of its disturbing potential), **epoch-driven Sun and Moon third-body** gravity (a built-in low-precision ephemeris, no DE/SPK kernel), **solar-radiation pressure** (cannonball model with a conical umbra+penumbra shadow), **atmospheric drag** (Vallado piecewise-exponential density, co-rotating atmosphere), and the **post-Newtonian Schwarzschild relativistic correction** — driven by a choice of two adaptive integrators (RK4 step-doubling or the **Dormand–Prince RK5(4)** embedded pair). Validated against analytic truth stronger than a cross-tool would give: the unperturbed orbit matches the exact universal-variable Kepler solution to **sub-metre over 24 h**, energy/angular-momentum conserve to ~1e-9, and each perturbation matches a hand-derived closed-form signature. |
+| **Maneuvers & trajectory design** | Impulsive ΔV nodes with 6×6 covariance propagation (ECI / LVLH execution-error frames), finite-burn integration checked against the closed-form **Tsiolkovsky** rocket equation to < 0.01 %, an **Izzo-2015** single-revolution **Lambert** solver, an exact universal-variable **Kepler** propagator, and a **porkchop** (launch × arrival) C3 / arrival-V∞ sweep emitted as a JSON contour grid — the performance-simulation layer above GMAT/Orekit, with every Lambert output round-tripped against two-body truth and the porkchop minimum checked against the analytic Hohmann floor. |
 | **Time systems** | IERS leap-second **UTC / TAI / TT / UT1** scales, a Julian-date API, the IAU-2000 **Earth Rotation Angle**, and GMST-based **TEME ↔ ECEF** with WGS-84 geodetic frames — plus IAU 2006 precession (Fukushima–Williams) toward an ITRF-precise reduction. |
 | **Inertial** | Three-axis strapdown INS — quaternion attitude, WGS-84 NED mechanization, coning/sculling compensation, and a deterministic IMU error model (scale-factor, misalignment, g-sensitivity, quantization, drift); a **first-principles cold-atom-interferometer accelerometer** (Mach–Zehnder phase, quantum projection noise, contrast decay, vibration coupling) that *derives* the velocity-random-walk coefficient; and a sequential-importance-resampling **particle filter** for map-aided (terrain-/gravity-referenced) GPS-denied navigation. |
-| **Fusion** | Loosely-coupled 15-state GNSS/INS error-state EKF with closed-loop feedback (the `gnss-ins` pack); a **tightly-coupled** pseudorange update that keeps correcting with fewer than four satellites; a coupled **clock + position** filter; a general **unscented (sigma-point) Kalman** estimator for strongly nonlinear measurements; and a tightly-coupled GNSS/INS **UKF navigator** (pseudorange + Doppler) whose force-model orbital coast is validated to **0.77 m RMS** over a 30-minute curving LEO pass that includes a 120-second GNSS outage. |
+| **Gravity-map / alt-PNT** | A cold-atom **gravimeter measurement model** whose white-noise floor (`σ = ASD/√τ`) is derived from the CAI accelerometer physics; a low-degree, fully-normalised **spherical-harmonic gravity-anomaly field** (validated against the closed-form Legendre functions and a hand-derived single-term anomaly) plus synthetic mascons; and a **gravity-map-matching particle filter** that recovers a GPS-denied track from the anomaly sequence it flies through. A **60-minute GPS-denied benchmark** (a ~700 km / one-hour outage where the inertial solution drifts to ~70 km) is recovered to **~145 m (< 500 m)** by a hierarchical coarse-to-fine matcher — the ESA NAVISP *Quantum Wayfarer* target. |
+| **Fusion** | Loosely-coupled 15-state GNSS/INS error-state EKF with closed-loop feedback (the `gnss-ins` pack); a **tightly-coupled** pseudorange update that keeps correcting with fewer than four satellites; a coupled **clock + position** filter; a general **unscented (sigma-point) Kalman** estimator for strongly nonlinear measurements; a tightly-coupled GNSS/INS **UKF navigator** (pseudorange + Doppler) whose force-model orbital coast is validated to **0.77 m RMS** over a 30-minute curving LEO pass that includes a 120-second GNSS outage; and a full **17-state tightly-coupled GNSS/INS UKF** (position, velocity, attitude error, accelerometer and gyro biases, clock bias and drift) whose **quantum-CAI dead-reckoning** coasts a 120-second outage on the cold-atom accelerometer's derived velocity-random-walk. |
+| **Orbit determination** | Recovery of an orbital state `[r, v]` from ground-station range tracking, composing the two-body + J2 force model and RK4 integrator with a **Gauss–Newton batch** corrector (`determine_orbit_batch`, sub-metre / mm·s⁻¹ from noiseless ranges, ~2 m at a 5 m noise floor) and a **sequential** unscented-filter variant (`determine_orbit_sequential`). |
 | **Integrity** | Snapshot and solution-separation (ARAIM-style) RAIM with horizontal/vertical protection levels (HPL/VPL), fault detection & exclusion, and Stanford integrity diagrams; an explicit integrity-risk-budget (**MHSS**) protection level, including the **dual-/multi-constellation constellation-wide fault mode** (EU ARAIM / DO-316). |
 | **Clock & timing** | Two-state Kalman holdover (Joseph-form covariance, NIS/NEES consistency health); Allan-family stability (ADEV / MDEV / TDEV / HDEV) with noise-type-specific confidence intervals and a full **IEEE-1139 five-coefficient power-law fit**; geometric corrections (Sagnac, GNSS common-view); and the operational transfer methods — **TWSTFT** with the BIPM Sagnac closed form, **GNSS common-view**, **PPP** ionosphere-free time transfer, a free-space **optical** link with turbulence scintillation, and an inverse-variance **clock-ensemble (paper) timescale** below the best contributing clock. |
 | **GNSS measurement domain** | Forward pseudorange / Doppler synthesis with **Klobuchar** (broadcast) and **IONEX / TEC-grid** (measured) ionosphere — including an IONEX file parser, time interpolation between maps, and the thin-shell slant-obliquity mapping — **Saastamoinen + Niell** troposphere, and snapshot RAIM (HPL/VPL). |
@@ -209,6 +219,10 @@ 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
 ```
 
 **Interoperability role.** Kshana is the *performance-simulation* layer that sits
@@ -217,7 +231,11 @@ output into RTKLIB or gLAB for a position solution, and use its **SP3** output 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`).
+`<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 message per TLE-defined satellite, carrying each object's real
+NORAD catalogue number, COSPAR international designator, and epoch, for any
+OMM-aware consumer instead of a bespoke two-line element set.
 
 Example output (clock holdover — note the Integrity and Security figures of merit):
 
@@ -446,8 +464,19 @@ power-law type is identified from its modified-Allan slope, and the χ² interva
 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`](docs/SCHEMA.md). The figures of
-merit follow the standard operational PNT figures of merit:
+source pointer, is documented in [`docs/SCHEMA.md`](docs/SCHEMA.md).
+
+**Every chart is self-describing.** The browser playground, the CLI's `*.chart.svg`
+export, and the HTML 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 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:
 
 | Figure of merit | How Kshana computes it |
 |-----------------|------------------------|
@@ -463,7 +492,10 @@ New to these terms? Each is defined in plain language in the [glossary](docs/GLO
 
 ## Architecture
 
-One engine; each sensor pack plugs in via a common error-model interface. See
+One engine. The sensor packs plug in via a common error-model interface; alongside
+them sit an astrodynamics/numerical layer (analytic SGP4/SDP4 **and** a numerical
+Cowell propagator with its force model, maneuver design, and orbit determination) and a
+fusion / alt-PNT layer (the GNSS/INS estimators and the gravity-map matcher). See
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full set of diagrams.
 
 ```mermaid
@@ -479,30 +511,45 @@ flowchart LR
 
 ```mermaid
 flowchart TD
-    cli["CLI · Python · WebAssembly"] --> api["api — run_toml: dispatch by kind"]
+    cli["CLI · Python · WebAssembly"] --> api["api — run_toml / run_scenario: typed dispatch by kind"]
     subgraph shared["Shared core"]
       types["types"]
       scenario["scenario · GNSS timeline"]
       allan["allan — Allan deviation"]
     end
-    subgraph p1["Pack 1 · Clock"]
-      models["models — ClockModel (+ flicker)"]
-      estimator["estimator — holdover"]
-      kalman["kalman — Integrity bound"]
-      security["security — analytic spoof-detectability bound"]
-      fom["fom · report · run"]
+    subgraph packs["Sensor packs"]
+      p1["Clock — models · estimator · kalman · security · fom"]
+      p2["inertial — strapdown INS + quantum-CAI"]
+      p3["timetransfer (+ _adv) — optical/RF link"]
+      p4["hybrid — fused PNT suite"]
+    end
+    subgraph astro["Astrodynamics & numerical"]
+      orbit["orbit — geometry → GNSS timeline + DOP"]
+      sgp4["sgp4 · tle — SGP4/SDP4"]
+      prop["propagator — Cowell"]
+      forces["forces — J2–J6 · 3rd-body · SRP · drag · relativity"]
+      integ["integrator — RK4 · DOPRI"]
+      ephem["ephem — Sun/Moon"]
+      man["maneuver — burns · Lambert · porkchop"]
+      od["orbit_determination — batch · sequential"]
+    end
+    subgraph fnav["Fusion & alt-PNT"]
+      fus["fusion — EKF · UKF · 17-state · coupled"]
+      grav["gravimeter · mapmatch · particle_filter"]
     end
-    p2["Pack 2 · inertial — accel + gyro"]
-    p3["Pack 3 · timetransfer — optical/RF link"]
-    p4["Pack 4 · hybrid — fused PNT suite"]
-    orbit["orbit — geometry → GNSS timeline + DOP"]
-    api --> p1
-    api --> p2
-    api --> p3
-    api --> p4
-    p1 --> shared
-    p2 --> shared
-    p3 --> shared
+    api --> packs
+    api --> astro
+    api --> fnav
+    packs --> shared
+    orbit --> sgp4
+    prop --> forces
+    prop --> integ
+    forces --> ephem
+    man --> integ
+    od --> forces
+    od --> integ
+    fus --> p2
+    grav --> p2
     orbit --> p1
     p4 -. composes .-> p1
     p4 -. composes .-> p2
@@ -514,27 +561,32 @@ flowchart TD
 ```
 kshana/
 ├── src/
-│   ├── types.rs        # Seconds, TimeGrid, ModelSpec
-│   ├── scenario.rs     # GNSS timeline, clock scenario config
-│   ├── models.rs       # ErrorModel trait, ClockModel (white FM, RWFM, aging)
-│   ├── estimator.rs    # HoldoverEstimator (quadratic offset+aging removal)
-│   ├── fom.rs          # figure-of-merit scoring
-│   ├── allan.rs        # overlapping Allan deviation
-│   ├── kalman.rs       # two-state Kalman clock estimator + integrity bound
-│   ├── report.rs       # result schema, scenario hash, SVG chart (clock)
-│   ├── run.rs          # clock + orbit-clock run pipelines
-│   ├── inertial.rs     # Pack 2: inertial dead-reckoning (accel + gyro) + FoMs
-│   ├── timetransfer.rs # Pack 3: optical/RF time-transfer link
-│   ├── hybrid.rs       # Pack 4: combined PNT suite + ISL clock-aiding
-│   ├── orbit.rs        # orbit propagation + GNSS line-of-sight visibility
-│   ├── api.rs          # scenario dispatch shared by the CLI and bindings
-│   ├── python.rs       # optional PyO3 extension (feature = "python")
-│   ├── wasm.rs         # optional wasm-bindgen module (feature = "wasm")
-│   └── main.rs         # CLI
-├── scenarios/          # cited scenarios (one per pack + a geometry-driven one)
+│   ├── types.rs · scenario.rs · allan.rs   # shared core (time grid, GNSS timeline, Allan)
+│   ├── api.rs · main.rs                     # typed dispatch + CLI
+│   ├── python.rs · wasm.rs                  # optional PyO3 / wasm-bindgen bindings
+│   │
+│   ├── 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 · report.rs · chart.rs · run.rs  # health · scoring · output
+│   ├── 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 suite, Monte-Carlo, trade sweeps
+│   │
+│   ├── orbit.rs · sgp4.rs · tle.rs · walker.rs   # geometry, SGP4/SDP4, TLE, Walker design
+│   ├── propagator.rs · forces.rs · integrator.rs # numerical Cowell propagator + force model + RK4/DOPRI
+│   ├── ephem.rs · precession.rs · frames.rs · timescales.rs · jd2.rs # ephemerides, IAU precession, time/frames
+│   ├── maneuver.rs · batch_ls.rs · orbit_determination.rs # burns/Lambert/porkchop, Gauss-Newton, OD
+│   │
+│   ├── fusion/          # GNSS/INS — EKF, UKF, tightly_coupled, tightly_coupled17, coupled
+│   ├── gravimeter.rs · mapmatch.rs · particle_filter.rs  # gravity-map / alt-PNT navigation
+│   ├── raim.rs · lunar.rs        # ARAIM HPL/VPL, cislunar integrity
+│   ├── gnss_sim.rs · ionex.rs · jamming.rs   # measurement domain, ionosphere maps, jamming
+│   └── rinex.rs · rinex_obs.rs · glonass.rs · sp3.rs · oem.rs · omm.rs · permalink.rs # interop formats
+├── scenarios/          # cited scenarios (one per kind + geometry-driven + GPS-denied)
 ├── scripts/            # reproducibility + repo-hygiene guards
-├── docs/               # CONCEPTS, ARCHITECTURE, VALIDATION, GLOSSARY, assets/
-├── .github/workflows/  # CI gate, release, and wheel-build pipelines
+├── docs/               # CONCEPTS, ARCHITECTURE, CAPABILITY, VALIDATION, PROVENANCE, GLOSSARY, …
+├── web/                # the WebAssembly playground + kshana.dev site
+├── .github/workflows/  # CI gate, release, wheels, publish, and pages pipelines
 ├── pyproject.toml      # Python packaging (maturin)
 ├── CHANGELOG.md        # Keep a Changelog + SemVer
 └── CONTRIBUTING.md
@@ -552,7 +604,7 @@ kshana/
 | [Provenance](docs/PROVENANCE.md) | reviewers / citers | every sensor parameter, model, and dataset traced to its published source, in one citable table |
 | [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) |
+| [SGP4 validation](docs/SGP4-VALIDATION.md) | reviewers / citers | agreement with the AIAA 2006-6753 reference (666 states, ~4 mm) **and** a head-to-head against the independent `sgp4` crate (agree to sub-micron / 4.12 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) |
@@ -661,7 +713,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.11.0`) together with the
+button from it); cite the version you used (e.g. `v0.13.0`) together with the
 scenario and seed for full reproducibility. Every release is archived on Zenodo with
 a citable DOI — the concept DOI [10.5281/zenodo.20528627](https://doi.org/10.5281/zenodo.20528627)
 always resolves to the latest version.

package/package.json

@@ -5,7 +5,7 @@
     "Chakshu Baweja <contact@ashforde.org>"
   ],
   "description": "Open, reproducible PNT-resilience simulator with quantum-sensor performance models",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",