Scientific dataset manifests, provenance, checksums, and Rust accessors for the Siderust ecosystem.
siderust-archive is the small Rust crate and repository layout used to keep
Siderust scientific data out of downstream application code. It stores dataset
metadata in TOML, keeps raw payloads in their native formats, and exposes only
the Rust bindings needed to parse, verify, fetch, or bundle those datasets.
Pre-1.0 archive: manifest shape and feature-gated APIs may still change. Release v0.2.0 includes compact embedded planetary and lunar ephemerides. See the crate on crates.io, the API documentation, and the changelog.
- TOML archive and family manifests.
- SHA-256 checksum helpers and provenance records.
- IERS/USNO time-data parsing, runtime fetch, and bundled offline snapshots.
- Build-time generated accessors for committed coefficient tables.
- Dataset-family manifests for VSOP87, ELP2000, nutation, JPL kernels, Lagrange kernels, gravity, atmosphere, frames, constants, and Pluto.
- Hiding upstream data provenance.
- Fetching large or mutable datasets from downstream build scripts.
- Silently replacing version-pinned datasets.
- Re-implementing Siderust scientific algorithms in the archive crate.
[dependencies]
siderust-archive = "0.2.0"For no_std + alloc (manifest, checksum, provenance, and scientific tables):
[dependencies]
siderust-archive = { version = "0.2.0", default-features = false }IERS time-data parsers and the bundled offline snapshot:
[dependencies]
siderust-archive = { version = "0.2.0", features = ["time"] }Runtime download/cache support for current IERS/USNO time data and JPL kernel
metadata (fetch requires std):
[dependencies]
siderust-archive = { version = "0.2.0", features = ["fetch"] }Planetary and geophysical tables are opt-in and work with or without std:
[dependencies]
siderust-archive = { version = "0.2.0", default-features = false, features = ["vsop", "elp", "nutation"] }The crate declares its own [workspace], so it is not absorbed into a parent
workspace when used through a local path dependency.
| Feature | Description |
|---|---|
| default | Enables std. |
std |
Standard library support (filesystem, network, env, OS I/O errors). Absent ⇒ no_std + alloc. |
time |
IERS UTC-TAI, Delta T, and EOP types/parsers; includes bundled-time. |
bundled-time |
Compiled UTC-TAI and Delta T fallback snapshot. |
fetch |
Runtime network download/cache support; requires std; implies time and jpl. |
jpl |
JPL DE440/DE441 ephemeris metadata; download/cache needs fetch. |
vsop |
Full VSOP87A/E planetary theory tables. |
vsop-compact |
Compact VSOP87E positions for the Sun and eight planets, 2020–2050. |
elp |
Full ELP2000-82B lunar theory tables. |
elp-compact |
Compact Earth-centered lunar position, 2020–2050. |
nutation |
IAU 2000A/2000B nutation coefficient tables. |
gravity |
Low-degree EGM2008 geopotential coefficients. |
atmosphere |
NRLMSISE-00 lite atmosphere-density table. |
frames |
SPICE-style frame definitions placeholder. |
constants |
SPICE-style body constants placeholder. |
lagrange |
Sun-Earth Lagrange Chebyshev kernel references. |
pluto |
Meeus 1998 abbreviated Pluto series. |
siderust-archive = { version = "0.2.0", default-features = false, features = ["vsop-compact"] }siderust_archive::vsop_compact provides a checked function per body, such as
try_mars(jd_tdb). It returns CompactEphemerisError for non-finite dates or
dates outside [FIRST_JD_TDB, END_JD_TDB) (2020-01-01 through 2050-12-31 TDB).
The direct functions, such as mars(jd_tdb), evaluate unchecked.
On success, the position is a geometric barycentric [X, Y, Z] in AU in the native
VSOP87 dynamical ecliptic and equinox of J2000.0. Subtract the Earth vector at
the same epoch for an Earth-relative vector. The compiled coefficients require
no runtime I/O or allocation.
The validation report includes accuracy, linked size, performance, source checksums, and reproduction commands.
siderust-archive = { version = "0.2.0", default-features = false, features = ["elp-compact"] }elp_compact::try_moon_geocentric(jd_tdb) returns a geometric Cartesian
Earth-to-Moon vector in kilometers in the native ELP2000-82B mean dynamical
ecliptic and inertial equinox of J2000.0. The checked API accepts finite TDB
Julian dates from 2020-01-01 through 2050-12-31. Subtract the observer's vector
in the same frame to include geometric lunar parallax. Enable
vsop-compact alongside it for planetary positions.
The lunar validation report documents distance and pointing errors, the native frame, and firmware measurements.
archive/
├── CHANGELOG.md
├── Cargo.toml
├── LICENSE
├── MANIFEST.toml # top-level dataset registry
├── README.md
├── schema/ # manifest and binary-format specs
├── src/ # crate sources and committed datasets
├── tools/validate/ # structural manifest validator
└── reports/validation/ # validation output, when present
Start with MANIFEST.toml. Each [[family]] entry points to
a src/<family>/manifest.toml file that records source, generator, validity,
units, references, payload files, byte counts, and SHA-256 checksums.
- Metadata is TOML. JSON is not used for archive manifests or provenance.
- Payload files keep their authoritative upstream format where practical.
- Generated Rust tables are build artifacts under Cargo
OUT_DIR; do not commit them. - Dataset generators must record source, generator version, generated time, references, byte counts, and checksums.
Validate the registry and all referenced family manifests:
cargo run -p archive-validate -- MANIFEST.toml- Put upstream payloads under
src/<family>/raw/or the family-specific payload directory. - Update
src/<family>/manifest.toml. - Register new families in
MANIFEST.toml. - Run
cargo run -p archive-validate -- MANIFEST.toml. - Build with the relevant feature enabled, for example
cargo check --features nutation.
Large mutable datasets need a reviewed process before they become automated.
Update Time Data
runs Mondays at 05:23 UTC and can also be dispatched from main. It refreshes
UTC-TAI.history, deltat.data, deltat.preds, and finals2000A.all under
src/time/eop/raw/. Other dataset families use their reviewed, version-pinned
maintenance procedures.
The updater stages all four downloads, checks parsing and coverage against the
committed data, and ignores whitespace-only changes that preserve field
values and fixed-width columns. A changed snapshot carries the fetch time and
SHA-256 hashes in
time_data.provenance.toml. It also updates the checksum and byte-count
entries in src/time/eop/manifest.toml and regenerates
src/time/bundled/snapshot.rs. Identical payloads retain the committed
provenance and generated files. The workflow validates the manifest and runs
the all-features tests before it can commit a refresh.
Transient download failures get up to three attempts per source, each limited
to 60 seconds, with 2- and 4-second backoff. Transport failures, invalid payloads,
and regressed coverage fail the refresh and preserve the committed snapshot.
The job summaries report the changed datasets, validation, and publication
status. Runtime fetch remains available with the fetch feature.
-
Review and merge a PR that sets the intended SemVer in
Cargo.tomland the root package entry inCargo.lock, and adds nonempty notes under## [VERSION]inCHANGELOG.md. Wait for CI to pass on the reviewed release commit onmain. -
Fetch
mainand confirm that the commit you intend to tag has the version and notes you reviewed. Setversionto the version from that commit:git switch main git pull --ff-only origin main python3 scripts/archive-release.py check-metadata version=MAJOR.MINOR.PATCH git tag -a "v${version}" -m "Release v${version}" git push origin "refs/tags/v${version}"
-
Open the Publish workflow. It validates the exact annotated tag on
mainhistory, tests the crate and datasets, and builds the package and its all-features docs. It creates the GitHub Release from the changelog after verifying the indexed crate's checksum, version, and embedded commit. Use the job summary to compare the tag, commit, crate version, and GitHub Release notes. Check the corresponding docs.rs build once it becomes available.
Update Time Data
runs Mondays at 05:23 UTC and can be dispatched on main. It checks out the
latest main, downloads and checks all four IERS/USNO datasets in staging,
and regenerates the bundled snapshot, manifest, and provenance together.
Identical payloads retain the committed provenance. Whitespace-only changes
also retain it, with fixed-width scientific columns preserved.
A changed payload requires a stable version with a verified crate and published GitHub Release at its annotated tag. Every intervening commit must touch only the tracked time-data paths, including changes later reverted. If maintenance finds unrelated work, include the data in a reviewed normal release. Failed downloads or scientific validation stop the run before Git pushes.
Maintenance increments PATCH, commits the datasets and release metadata
together, and validates the committed package. It pushes the commit and new
annotated tag atomically, with a lease on the original main commit. It passes
the exact tag and commit to the shared workflow in the same run, so the
automatic release works with GitHub's workflow token. An unchanged refresh
finishes without a new commit, version, or tag.
- Configure
CARGO_REGISTRY_TOKENwith permission to publishsiderust-archive. Set it as a secret in thecrates.ioActions environment or as a repository Actions secret. - Allow
mainandv*deployments in that environment. Required reviewers, if configured, also approve scheduled releases. Unattended weekly releases require an environment that permits those runs without manual approval. - Allow the workflow's built-in
GITHUB_TOKENto create GitHub Releases and make the scheduled atomic push tomainand a new version tag. Restrict release tag creation to maintainers and authorized automation, and protect existing tags from changes and deletion. If branch rules require PRs for all pushes, use a reviewed data and version PR and tag the merged commit. - Both callers share a concurrency queue. The queue can hold up to 100 pending runs. Use an explicit recovery dispatch if a run is dropped, interrupted, or fails.
If the version tag exists, rerun the failed workflow or dispatch Publish
on main with the existing bare version:
gh workflow run publish.yml --repo Siderust/archive --ref main -f version=0.2.0Recovery validates that exact tag even if main has advanced. Once crates.io
indexes a matching crate, recovery skips the upload and creates or
synchronizes the GitHub Release. A tag/Cargo mismatch, divergent tag,
registry checksum or source mismatch, yanked crate, or draft release needs
maintainer investigation. Preserve existing release tags and versions.
If maintenance fails before the atomic push, rerun Update Time Data to
refresh against current main. If Cargo reports an upload error or times out
waiting for indexing, check the registry and rerun Publish for the same
tag. The workflow polls for the indexed crate before making GitHub Release
changes. Inspect the preceding Cargo or dataset logs to diagnose errors and
use the job summary links to check synchronization.
Open the failed build log on the crate's docs.rs Builds page and identify its
nightly revision. CI runs bash scripts/check-packaged-docs.sh from a clean
checkout with stable and nightly Rust installed. The script unpacks the
Cargo package and runs offline rustdoc with DOCS_RS=1, --cfg docsrs, and
all features enabled, so missing inputs to the scientific table generators
fail before release. Use the matching nightly when investigating a
toolchain-specific failure. The
0.1.5 log shows
that Rust removed doc_auto_cfg and folded it into doc_cfg.
BSD-3-Clause — see LICENSE.
Each upstream dataset keeps the license and attribution declared by its original source. Check the relevant family manifest before redistributing data payloads outside this repository.