kshana 0.7.0__tar.gz

kshana-0.7.0/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.rs]
+indent_size = 4
+
+[*.{toml,yml,yaml,md}]
+indent_size = 2

kshana-0.7.0/.gitignore

@@ -0,0 +1,20 @@
+/target
+*.result.json
+*.chart.svg
+*.report.html
+
+# Python packaging / build artifacts (maturin)
+/dist
+*.so
+*.pyd
+__pycache__/
+*.egg-info/
+.venv/
+
+# WebAssembly package (wasm-pack output)
+/pkg
+
+# Playground build outputs (generated/copied by web/build.sh and the Pages workflow)
+/web/pkg
+/web/scenarios
+/web/assets

kshana-0.7.0/CHANGELOG.md

@@ -0,0 +1,225 @@
+# Changelog
+
+All notable changes to Kshana are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the project is pre-1.0, the public scenario/result schema may still change;
+breaking changes are called out explicitly.
+
+## [Unreleased]
+
+### Planned
+- Velocity-domain outputs from the SGP4 propagator (currently position drives the
+  availability and dilution-of-precision geometry).
+
+## [0.7.0] - 2026-06-02
+
+### Added
+- **SGP4/SDP4 orbit propagation.** A full, dependency-free implementation of the
+  standard simplified-perturbations propagator — near-Earth SGP4 together with the
+  deep-space SDP4 extension (lunar-solar secular and periodic perturbations and
+  12 h / 24 h geopotential resonance). It is validated against the official AIAA
+  2006-6753 ("Revisiting Spacetrack Report #3") verification vectors: all 666
+  reference states across the near-Earth, deep-space, resonant, and error-code
+  cases match to a worst-case position error of about 4 mm. This is the model
+  two-line element sets are defined against, so it represents real constellations
+  — notably the ~12 h GNSS orbits, which are deep-space and resonant and which the
+  earlier two-body + J2-secular model cannot capture.
+- A constellation given as **full two-line element sets** (line 1 + line 2) is now
+  propagated with SGP4/SDP4; a constellation given as line-2-only elements keeps
+  the analytic Keplerian two-body propagation, unchanged. The two forms can be
+  mixed in one block. New `orbit-sgp4-gps.toml` reference scenario (a GPS-like MEO
+  constellation in real two-line format, propagated with SGP4) — drop in a current
+  Celestrak "gps-ops" set to study the live constellation.
+
+## [0.6.0] - 2026-06-02
+
+### Added
+- **Active spoofing-attack demonstrator.** A new `spoof` scenario kind injects a
+  ramping false-time spoof and runs each clock's clock-aided integrity monitor,
+  reporting whether and when the spoof is detected and whether it reaches the
+  operational spec undetected — turning the Security figure of merit into a concrete
+  attack/defence demonstration. New `spoof-attack.toml` reference scenario.
+- **Multi-constellation availability.** An orbit scenario can combine several
+  constellations (a `[[constellations]]` list alongside the primary
+  `[constellation]`) for multi-GNSS availability and dilution of precision — e.g.
+  GPS plus Galileo. New `orbit-multignss.toml` reference scenario.
+
+## [0.5.0] - 2026-06-02
+
+### Added
+- **HTML scorecard report.** Every run now also produces a self-contained, branded
+  HTML scorecard — the one-line summary, the chart (embedded as an inert data-URI
+  image), and the full JSON — written by the CLI alongside the JSON and SVG. A
+  shareable single-file artifact for a study deliverable or annex.
+- **Joint sensor-fusion estimator.** A new `fusion` scenario kind runs a single
+  recursive Kalman filter as the navigation solution — fusing the clock state
+  `[phase, frequency]` and the position state `[position, velocity]`, disciplined by
+  GNSS (learning the frequency offset and velocity) and aided by optical time
+  transfer during the outage — rather than composing independent predictors. It
+  reports fused timing/position holdover and a joint-covariance integrity. New
+  `fusion-pnt.toml` reference scenario.
+- **Fuller IMU noise model.** The accelerometer now models the remaining
+  Allan-variance terms beyond the constant bias and velocity random walk:
+  **bias instability** (a 1/f flicker floor at the standard Allan bias-instability
+  coefficient, reusing the clock's flicker synthesis) and **acceleration random
+  walk**. New optional `bias_instability` and `q_aa` inertial scenario fields; a
+  GNSS re-fix re-calibrates the residual bias drift.
+- **Real constellation geometry from TLEs.** A constellation can be given as a block
+  of two-line element sets (the standard NORAD/Celestrak format) via a `tle` field,
+  so availability and dilution of precision use a real constellation's published
+  geometry instead of a synthetic Walker pattern. The engine reads each TLE's mean
+  Keplerian elements and propagates them two-body — not SGP4 — which is sound for a
+  snapshot study from a common epoch. New `orbit-real-tle.toml` reference scenario.
+
+## [0.4.0] - 2026-06-02
+
+### Added
+- **Trade-study parameter sweeps.** A new `sweep` scenario kind varies one
+  parameter (`threshold_ns`, `duration_s`, `quantum_q_wf`, or `classical_q_wf`)
+  across a linear or logarithmic range and records a chosen figure of merit at each
+  point for both clocks, producing the "how does holdover scale with clock
+  stability?" comparison chart a design trade needs. New `sweep-clock-stability.toml`
+  reference scenario.
+- **Monte Carlo confidence bands.** The clock-holdover scenario can run many
+  realizations (new optional `runs` field): each figure of merit is then reported
+  as a mean with a 5th–95th-percentile spread, and the chart shades the 5–95%
+  error envelope around the median for each clock. A single run remains the default.
+  New `clock-ensemble.toml` reference scenario.
+- **Eccentric orbits and J2 drift.** The orbit type is now a full Keplerian orbit
+  (semi-major axis, eccentricity, inclination, RAAN, argument of perigee, mean
+  anomaly), propagated by solving Kepler's equation, with optional secular J2 nodal
+  regression and apsidal precession. New optional `eccentricity`, `argp_deg`, and
+  `j2` scenario fields, and an `orbit-molniya.toml` reference scenario (a 12 h
+  highly-eccentric critically-inclined user). Circular orbits keep the original
+  closed-form path bit-for-bit.
+- The hybrid (combined-PNT) pack now reports **Integrity** and **Security**, so all
+  four packs cover the full set of operational figures of merit. Integrity is the
+  timing-channel protection-bound containment from a Kalman estimator disciplined to
+  truth while GNSS is nominal and re-anchored (more loosely) at each optical re-sync;
+  its bound includes the link's measurement-noise floor, so a clock far better than
+  the link is scored against the delivered solution's actual noise. Security is the
+  clock-aided spoof-detection score against the timing spec.
+
+### Changed
+- Release notes are now generated from the curated CHANGELOG section for the tag
+  (`scripts/changelog-extract.sh`), so each GitHub release highlights what changed
+  instead of listing raw commits.
+
+## [0.3.0] - 2026-06-02
+
+### Added
+- **Security** figure of merit (previously unpopulated): a clock-aided
+  spoof-detection score for the clock-holdover and orbit packs. It models an
+  integrity monitor that cross-checks GNSS-derived time against the clock's own
+  coasted prediction over a coherent window; the detection floor combines the
+  averaged measurement noise with the clock's coast uncertainty, so a quieter
+  clock detects smaller, slower time-spoofs. The score is reported in `[0, 1]`
+  relative to the timing spec, completing the six operational figures of merit.
+- Geometry-derived **position accuracy** for the orbit pack: from the
+  line-of-sight geometry to the visible satellites it forms the design matrix
+  and its covariance factor `Q = (HᵀH)⁻¹`, yielding the dilution-of-precision
+  factors (GDOP/PDOP/HDOP/VDOP/TDOP). Position accuracy is the position DOP
+  scaled by a configurable user-equivalent range error (new optional
+  `sigma_uere_m` scenario field). An orbit result now carries a geometry summary
+  (fraction of samples with a fix, best and median PDOP and position sigma).
+- An in-browser **playground** (`web/`) that runs the engine client-side as
+  WebAssembly: pick a reference scenario or edit the TOML, run it, and see the
+  summary, chart, and full JSON, with nothing uploaded. A `pages` workflow
+  builds and publishes it to GitHub Pages, and a new `summary` WebAssembly export
+  backs the readout.
+- Labelled y-axes on the SVG charts: gridlines, numeric tick labels, and a units
+  axis title (via a shared `chart` helper), so magnitudes are readable.
+- Package-publishing workflow (`publish`) for crates.io, PyPI, and npm, each
+  gated on its registry token and triggered by a published release.
+
+## [0.2.0] - 2026-06-02
+
+### Added
+- Flicker (1/f) FM floor for the clock error model, synthesised as a sum of
+  log-spaced Ornstein-Uhlenbeck processes and calibrated so the flat
+  Allan-deviation floor sits at a configurable level. Off by default; enabled
+  per clock via the optional `flicker_floor` scenario field.
+- Gyro channel for the inertial model: residual gyro bias and angular random
+  walk drive an attitude (tilt) error that couples gravity into a horizontal
+  specific-force error, the dominant strapdown error-growth mechanism. Off by
+  default; enabled per sensor via the optional `gyro_bias` and `q_arw` fields.
+- Two-state (phase, frequency) Kalman clock estimator with exact van Loan
+  process-noise discretisation. Coasting from a known state reproduces the
+  analytic holdover error growth (`q_wf*T + q_rw*T^3/3`) exactly, and the filter
+  additionally yields an online 1-sigma uncertainty bound.
+- The clock run now reports the **Integrity** figure of merit (previously
+  unpopulated): the fraction of outage samples whose error stays inside the
+  filter's 3-sigma protection bound, surfaced in the JSON result and CLI summary.
+- Geometry-derived GNSS availability: circular-orbit propagation, a Walker-delta
+  constellation generator, and line-of-sight visibility (Earth-occultation plus
+  elevation mask) produce the availability timeline from real orbital geometry.
+  New `orbit` scenario kind and the `orbit-gnss-challenged.toml` reference
+  scenario (a spacecraft inside the GNSS shell with intermittent coverage).
+- Optional Python extension (PyO3, abi3) exposing `run`, `run_full`, and
+  `version`, packaged with maturin (`pyproject.toml`) and built for Linux, macOS,
+  and Windows by a release-tag `wheels` workflow. The binding is a feature-gated,
+  optional dependency: the default build, tests, and dependency-audit gate are
+  unaffected.
+- Optional WebAssembly module (wasm-bindgen) exposing `run`, `chart_svg`, and
+  `version`, built with wasm-pack under the `wasm` feature; `getrandom` is
+  target-gated to use the browser entropy source on `wasm32`.
+- Shared `api::run_toml` dispatch used by the CLI and both bindings, so the
+  command line and the bindings cannot drift.
+
+### Changed
+- Holdover scoring is now segment-aware: outage timelines are split into
+  contiguous segments at GNSS re-acquisition, and the reported holdover is the
+  worst-case (shortest) coast across them. Single-outage scenarios are
+  unchanged. Applies to the clock, inertial, and hybrid scorers.
+- The inertial model's reported `kind` is now `inertial` (was `accelerometer`),
+  reflecting the combined accelerometer and gyro channels.
+
+## [0.1.0] - 2026-06-01
+
+Initial release.
+
+### Added
+- **Deterministic simulation engine** for hybrid quantum/classical PNT: a common
+  error-model interface, declarative GNSS-availability scenarios, holdover /
+  dead-reckoning estimators, and figure-of-merit scoring against the standard
+  operational PNT criteria. Results are reproducible from `scenario + seed + engine
+  version` (versioned, self-describing JSON with a scenario hash) and rendered as SVG
+  charts. The CLI dispatches scenarios by `kind`.
+- **Four sensor packs**, each calibrated to published data and validated against the
+  standard relation:
+  - **Clock holdover** — white FM, random-walk FM, and linear aging; validated by
+    overlapping Allan deviation (Riley, NIST SP 1065). Chip-scale atomic clock vs
+    strontium optical lattice clock.
+  - **Inertial dead-reckoning** — residual bias + velocity random walk, double
+    integrated to position error; validated against Groves' error-growth relations.
+    Cold-atom vs navigation-grade accelerometer.
+  - **Time transfer** — optical vs RF link timing jitter → synchronization precision →
+    one-way ranging.
+  - **Hybrid fusion (capstone)** — a combined PNT suite that must hold both timing and
+    position, with optional optical inter-satellite time-transfer clock-aiding.
+- **One cited reference scenario per pack** under `scenarios/`, every numeric
+  parameter carrying a peer-reviewed `provenance`.
+- **Reproducibility and repository-hygiene guards**; CI (format, clippy, tests,
+  guards, MSRV) and a tag-gated release pipeline that re-runs all checks.
+- **Documentation**: README with architecture diagrams, validation-status report,
+  contributing guide, security policy, and code of conduct; Apache-2.0 license;
+  issue/PR templates and Dependabot configuration.
+- Vendor-neutral throughout; peer-reviewed scientific and metrology citations retained.
+- Apache-2.0 license hygiene: SPDX headers on all sources, a `NOTICE` with trademark
+  notice, Developer Certificate of Origin (DCO) sign-off for contributions, and
+  `cargo-deny` enforcement of dependency licenses/advisories in CI.
+- Open-core positioning (README): a free Apache-2.0 engine plus available commercial
+  support, integration, and proprietary extensions from Ashforde OÜ — sustained by
+  services, not license fees.
+- `CITATION.cff` so the software can be cited.
+
+[Unreleased]: https://github.com/AshfordeOU/kshana/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/AshfordeOU/kshana/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/AshfordeOU/kshana/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/AshfordeOU/kshana/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/AshfordeOU/kshana/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/AshfordeOU/kshana/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/AshfordeOU/kshana/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/AshfordeOU/kshana/releases/tag/v0.1.0

kshana-0.7.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+title: "Kshana — hybrid quantum/classical PNT performance simulator"
+message: "If you use Kshana in your work, please cite it using this metadata."
+type: software
+authors:
+  - family-names: Baweja
+    given-names: Chakshu
+    email: contact@ashforde.org
+repository-code: "https://github.com/AshfordeOU/kshana"
+url: "https://github.com/AshfordeOU/kshana"
+abstract: >-
+  Open, reproducible simulator for hybrid quantum/classical positioning,
+  navigation and timing (PNT). Quantifies the performance, autonomy, and
+  resilience advantage of quantum clocks, quantum inertial sensors, and optical
+  time transfer over classical PNT, scored against operational figures of merit,
+  with every sensor parameter traceable to a published source.
+keywords:
+  - PNT
+  - navigation
+  - quantum
+  - GNSS
+  - simulation
+license: Apache-2.0
+version: 0.7.0
+date-released: "2026-06-02"

kshana-0.7.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at contact@ashforde.org. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

kshana-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to Kshana
+
+Thanks for your interest. Kshana aims to be a **neutral, reproducible, honestly-
+validated** reference for hybrid quantum/classical PNT. Contributions are held to that
+bar: correctness, citations, and reproducibility over breadth.
+
+## Development
+
+```bash
+cargo build
+cargo test          # all tests must pass
+cargo clippy        # keep it warning-clean
+cargo fmt
+```
+
+The optional language bindings are feature-gated and off by default (so the build
+above and the dependency-audit gate never touch them). To work on them:
+
+```bash
+maturin develop --features python                 # Python extension (needs maturin)
+wasm-pack build --target web -- --features wasm    # WebAssembly module
+cargo clippy --features python --features wasm     # lint the binding modules
+```
+
+## Before every commit, both guards must pass
+
+```bash
+./scripts/check-reproducible.sh     # reference scenario is byte-identical across runs
+./scripts/check-no-attribution.sh   # repo hygiene (see below)
+```
+
+- **Reproducibility is a hard invariant.** A change that makes `(scenario, seed,
+  version)` non-deterministic is a bug. Randomness must flow through the seeded RNG;
+  quantum and classical runs use independent, deterministically-derived seeds.
+- **Repository hygiene.** Commits and content must carry no automated-tool attribution
+  trailers or footers, and must not name an AI assistant as an author anywhere in
+  content, file names, or history. The guard enforces this.
+
+## Adding or changing a sensor model
+
+1. **Every numeric parameter needs provenance.** Put the citation in the model's
+   `provenance` string and the scenario file. No anonymous constants.
+2. **Validate against the standard relation,** not just internal consistency — e.g.
+   Allan deviation for clocks, Groves' dead-reckoning error growth for inertial, the
+   timing→ranging conversion for time transfer. Add a test that the simulated output
+   reproduces the published/relation value within a stated tolerance.
+3. **Be honest about maturity.** Update `docs/VALIDATION.md`: mark each term
+   `validated` or `not modeled`, and label figures that are targets or ground-
+   demonstrator results as such.
+
+## Tests
+
+- Test-driven: write the failing test first, with the expected value **derived by
+  hand** from the physics/relation before implementing.
+- Deterministic tests assert exact (hand-derived) values; statistical tests assert a
+  stated tolerance and, ideally, average over seeds to control scatter.
+
+## Commits and versioning
+
+- **Conventional Commits** (`feat:`, `fix:`, `docs:`, `test:`, `chore:` …).
+- **Semantic Versioning.** Pre-1.0, the scenario/result schema may change; call out
+  breaking changes.
+- **Publishing to crates.io is a manual maintainer step.** It requires a registry
+  token and is run by hand (`cargo publish`). The CI and Release pipelines never
+  publish to external registries automatically; the tag-gated Release workflow only
+  re-runs all checks and attaches a build artifact to a GitHub release.
+
+## Changelog maintenance (required)
+
+Every user-visible change updates [`CHANGELOG.md`](CHANGELOG.md):
+
+1. Add an entry under the **`[Unreleased]`** section, in the right group
+   (`Added` / `Changed` / `Fixed` / `Removed` / `Documented` / `Planned`).
+2. On release, rename `[Unreleased]` to the new `[x.y.z] - YYYY-MM-DD`, start a fresh
+   `[Unreleased]`, bump the `version` in `Cargo.toml` (so `engine_version` in result
+   JSON matches), update the compare links at the bottom, and tag `vx.y.z`.
+3. Keep entries terse and user-facing; link issues/PRs where useful.
+
+A pull request that changes behaviour without a changelog entry is incomplete.
+
+## Export control
+
+PNT resilience and quantum sensing can touch dual-use export controls. Keep the public
+repository to generic, published models and methods. Anything resembling
+export-sensitive resilience/anti-spoof depth belongs in the private overlay, not here.
+If unsure, ask before contributing it.
+
+## License
+
+By contributing you agree your contributions are licensed under Apache-2.0.
+
+Sign off each commit to certify the [Developer Certificate of Origin](https://developercertificate.org/):
+`git commit -s` (adds a `Signed-off-by` line). Inbound contributions are under the
+same Apache-2.0 license as the project (inbound = outbound); there is no CLA.