# 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, maneuvers, 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`
- US English spelling

## Foundations

These are depended on, not reimplemented.

| Crate | License | 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` and Orekit on the same benchmarks with matched force
models, on the same hardware. Neither publishes usable figures, so the references
are measured here rather than cited.

| Benchmark | astrokit | nyx-space | 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 | — | — |

## Development

Enable the pre-commit hook once per clone:

```sh
git config core.hooksPath .githooks
```

It runs `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D
warnings`, and a US English spelling check. `git commit --no-verify` skips it.
Tests and docs are left out to keep it under a few seconds; run `cargo test`
yourself.

## License

MIT. See [LICENSE](./LICENSE).