astrokit/readme.md

astrokit

A highly-performant astrodynamics engine, written in Rust. Force models, propagation, reference frames, spacecraft geometry and measurement models — built on 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 core 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 and 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 4.3	MPL-2.0	TAI/TT/ET/TDB/UTC/GPS time scales, leap seconds
anise 0.10	MPL-2.0	Reference frames, planetary ephemerides, SPICE-format kernels
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	—	—

Kernels

Ephemerides and Earth orientation come from NAIF kernels, which are too large to commit. data/kernels.tsv pins each one by URL and SHA-256:

scripts/fetch-kernels.sh            # into data/kernels
scripts/fetch-kernels.sh /somewhere # or wherever you keep them

The script verifies checksums and leaves an already-correct file alone. Point ASTROKIT_KERNELS at the directory if it is not data/kernels. Tests that need kernels say so and skip when they are absent.

earth_latest_high_prec.bpc is deliberately not used: a result that cites "the latest Earth orientation kernel" cannot be reproduced, so the dated snapshot covering the same span is pinned instead.

Examples

cargo run --example two_body   # one orbital period of a point mass
cargo run --example attitude   # orbit and attitude together, on a tumbling box

Development

Enable the pre-commit hook once per clone:

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.