Crate ephemerust 

Ephemerust

An accessible, teaching-grade astronomy, orbital-mechanics, and satellite-tracking library for Rust — in spirit, the Rust counterpart to Python’s Skyfield. It deliberately occupies the middle ground between raw numerical engines (such as the sgp4 crate) and ultra-high-fidelity mission toolkits (such as nyx-space): it wraps the messy parts — time systems, coordinate-frame conversions, and planetary theory — behind an ergonomic, thoroughly documented API.

Design philosophy

• Don’t reinvent the wheel. Heavy numerical work is delegated to established crates (the sgp4 propagator, chrono for time); Ephemerust supplies the conversion and convenience layer around them.
• Document the physics, not just the code. Each public item explains the physical reasoning and the conventions (frames, units, epochs) it assumes.
• Errors are teaching moments. Failures explain what was expected and why, so the library is instructive even when input is wrong (see TleError).

Module map

Module	Responsibility
time	Julian Date, Greenwich/Local sidereal time
coordinates	RA/Dec ↔ Alt/Az, ECEF ↔ ECI, and WGS84 ECEF ↔ geodetic
celestial	Sun/Moon position and rise/set; dispatch to planets
orbital	Kepler’s equation, orbital period, elements → state vectors
planets	VSOP87 planetary ephemeris
satellite	TLE / SGP4 propagation, TEME → ECEF → geodetic, look angles, passes, ground track
sgp4_teaching	Educational two-body / Kepler scaffolding vs the real sgp4 model (docs/sgp4.md)

Conventions

Angles are in degrees and times in UTC unless a function states otherwise; right ascension and sidereal time are in hours; distances follow each module’s stated unit (kilometres for orbital/satellite state, metres for ECEF/ECI). No precession or nutation is applied, which bounds accuracy at roughly the arcminute level — see docs/accuracy-and-limits.md.

API stability, MSRV, and Cargo features

The project is in the 0.x semver range: minor releases may include breaking API changes (see CHANGELOG.md). The minimum supported Rust version (MSRV) is declared in the crate Cargo.toml (package.rust-version) and summarized in the top-level readme.

Optional Cargo features:

Feature	Purpose
(none by default)	Default build: no HTTP client dependencies.
network	Exposes the track CLI flag --tle-url for future CelesTrak/Space-Track-style
fetch; the handler is still a stub (“not implemented”) until wired in a later release.

Example

Compute the Julian Date and Greenwich Mean Sidereal Time of the J2000.0 epoch:

use chrono::{TimeZone, Utc};
use ephemerust::{julian_date, greenwich_mean_sidereal_time};

// J2000.0 is defined as 2000-01-01 12:00:00 UTC.
let epoch = Utc.with_ymd_and_hms(2000, 1, 1, 12, 0, 0).unwrap();
let jd = julian_date(epoch);
assert!((jd - 2451545.0).abs() < 1e-6);

// GMST is the Earth's rotation angle expressed in hours of right ascension.
let gmst = greenwich_mean_sidereal_time(jd);
assert!((0.0..24.0).contains(&gmst));

Re-exports

pub use error::AstroError;

pub use error::Result;

pub use coordinates::ecef_to_geodetic_wgs84;

pub use coordinates::geodetic_wgs84_to_ecef;

pub use coordinates::AltAz;

pub use coordinates::Ecef;

pub use coordinates::Eci;

pub use coordinates::Geodetic;

pub use coordinates::RaDec;

pub use celestial::CelestialObject;

pub use celestial::ObserverLocation;

pub use celestial::RiseSetTimes;

pub use planets::calculate_planet_position;

pub use planets::Planet;

pub use satellite::ecef_to_geodetic;

pub use satellite::ground_track;

pub use satellite::ground_track_to_csv;

pub use satellite::ground_track_to_json;

pub use satellite::look_angles;

pub use satellite::look_angles_with_model;

pub use satellite::predict_passes;

pub use satellite::predict_passes_with_model;

pub use satellite::propagate;

pub use satellite::propagate_with_model;

pub use satellite::subpoint;

pub use satellite::subpoint_with_model;

pub use satellite::teme_to_ecef;

pub use satellite::GroundTrackSample;

pub use satellite::LookAngles;

pub use satellite::Pass;

pub use satellite::PropagationModel;

pub use satellite::Subpoint;

pub use satellite::TemeState;

pub use satellite::Tle;

pub use satellite::TleError;

pub use time::greenwich_mean_sidereal_time;

pub use time::julian_date;

pub use time::local_sidereal_time;

Modules

celestial

Positions and rise/set times for the Sun, Moon, and planets.

coordinates

Coordinate systems and the transforms between them.

error

Error handling: the crate-wide error::AstroError type and error::Result alias.

orbital

Classical (two-body Keplerian) orbital mechanics.

planets

Planetary positions from VSOP87 theory.

satellite

Satellite tracking and pass prediction.

sgp4_teaching

Educational SGP4-related mechanics (two-body skeleton vs production sgp4).

time

Time systems: Julian Date and sidereal time.