Initial commit. Scaffolding, license, readme

readme.md

@@ -0,0 +1,80 @@
+# astrokit
+
+A highly-performant astrodynamics engine, written in Rust. Force models, propagation, reference
+frames, spacecraft geometry and measurement models — built on
+[`ordinary-diffeq`](https://crates.io/crates/ordinary-diffeq) for integration,
+and generic over the scalar type so that any propagation you can solve you can
+also differentiate.
+
+## Status
+
+The crate is still being built to a milestone plan:
+
+- **M1** — the study-critical subset: two-body and spherical-harmonic gravity,
+  drag, third-body, cannonball SRP, GCRF/ITRF frames, ground stations and the
+  four measurement types, with a validation suite against Orekit reference
+  trajectories.
+- **M2** — general-purpose completion: higher-degree gravity fields, more
+  density models, box-wing SRP and eclipses, manoeuvres, covariance propagation,
+  relative motion, TLE and CCSDS I/O.
+
+The tables under [Validation](#validation) and [Performance](#performance) are
+the acceptance criteria.
+
+## Conventions
+
+- Everything is SI
+- Time is typed, using `hifitime`
+
+## Foundations
+
+These are depended on, not reimplemented.
+
+| Crate | Licence | Provides |
+|---|---|---|
+| [`hifitime`](https://crates.io/crates/hifitime) 4.3 | MPL-2.0 | TAI/TT/ET/TDB/UTC/GPS time scales, leap seconds |
+| [`anise`](https://crates.io/crates/anise) 0.10 | MPL-2.0 | Reference frames, planetary ephemerides, SPICE-format kernels |
+| [`ordinary-diffeq`](https://crates.io/crates/ordinary-diffeq) 0.4 | MIT | Adaptive integration, dense output, callbacks, autodiff |
+
+## Validation
+
+Before we can make a highly-performant propagator, we have to make a *correct* propagator.
+
+1. **Orekit reference fixtures.** A committed, rerunnable generation script
+   produces reference trajectories and observations; the data lands under
+   `tests/fixtures/` with the Orekit version, force-model configuration and
+   generation date recorded beside it; Rust tests assert agreement within
+   declared tolerances.
+2. **Analytic invariants.**: ie, "does a two-body orbit close back in on itself after one-period?" and similar conservation-tests, meant to run fast as unit tests to ensure that nothing has broken.
+3. **ANISE cross-checks.** Frame transformations and ephemeris lookups against
+   ANISE's own validated values, confirming that we are calling it correctly.
+
+Every fixture comparison matches gravity degree and order, density model,
+third-body ephemeris source and integrator tolerances; anything that cannot be
+matched is documented and its contribution bounded.
+
+| Case | Target | Achieved | Test |
+|---|---|---|---|
+| 1-day LEO arc, full matched force model | 1 m position, 1 mm/s velocity | not yet measured | — |
+| 6-day LEO arc | to be set from the 1-day result | not yet measured | — |
+| GEO arc, including a time-varying-area change | to be set | not yet measured | — |
+| Two-body energy and angular momentum | integrator tolerance | not yet measured | — |
+| Two-body closure over N periods | integrator tolerance | not yet measured | — |
+| J2 secular nodal regression and apsidal rotation | to be set | not yet measured | — |
+| RA/DEC, range, range-rate, az/el against Orekit | to be set | not yet measured | — |
+
+## Performance
+
+Measured against `nyx-space`, `astrolabe` and Orekit on the same benchmarks with
+matched force models, on the same hardware. None of the three publishes usable
+figures, so the references are measured here rather than cited.
+
+| Benchmark | astrokit | nyx-space | astrolabe | Orekit |
+|---|---|---|---|---|
+| Two-body throughput (state-steps/s) | not yet measured | — | — | — |
+| Full-force LEO, 1 day | not yet measured | — | — | — |
+| Ensemble of N states, scaling vs. cores | not yet measured | — | — | — |
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).