Crate siderust

Expand description

§Siderust

Precision positional astrometry, atmospheric optics, ephemerides, sky-brightness and satellite mechanics in Rust.

siderust is a research-grade astronomy toolkit built on two explicit pillars:

Typed quantities everywhere — every physical quantity at a public API boundary is a qtty newtype (e.g. Meters, Radians, JulianDate, Airmass, OpticalDepth, Albedo, IlluminationFraction, Refractivity, CipCoordinate, …). Bare f64 is confined to internal math kernels.
Compile-time model selection — when a function can use one of several algorithms or conventions (nutation theory, airmass formula, extinction parameterisation, …) the choice is expressed as a zero-sized phantom-type parameter, not a runtime enum. For example:
ⓘ
```
// picks Iau2006A nutation at compile time — no runtime dispatch
let equatorial = ecliptic.to_frame_as::<Equatorial, Iau2006A>(ctx);
```

Together these two properties make type errors in physical calculations into compile-time errors and eliminate whole classes of unit-confusion bugs.

See doc/conventions.md for the mandatory authoring rules: the academic-style module-doc template (Scientific scope / Technical scope / References), typed-quantity guidelines, and the phantom-type model-selection pattern.

§Scientific scope

Strongly-typed coordinates (center + frame + unit encoded in the type system)
Ephemerides (VSOP87/ELP2000 always available; optional JPL DE4xx backends)
Observation planning (altitude periods, crossings, culminations, azimuth windows)
Atmospheric refraction and extinction (airmass, optical depth, scattering)
Sky brightness and lunar photometry (phase geometry, albedo, spectral radiance)
Time handling (via the tempoch crate, re-exported as time)
Keplerian / conic orbits and satellite mechanics
Photometric passbands and throughput (optional photometry feature)

§API pillars

Coordinates: cartesian::{Position, Direction, Velocity, ...} and spherical::{Position, Direction} parameterized by Center, Frame, and Unit.
Transforms: frame rotations + center shifts with compile-time guarantees.
Altitude API: AltitudePeriodsProvider + free functions to compute crossings, culminations, altitude ranges, and above/below-threshold windows.
Ephemeris backends: Ephemeris trait with VSOP87/ELP2000 and optional DE440/DE441.
Serde: optional serde feature for public types.

§Crate composition

siderust is an orchestration crate that composes the specialized Siderust sub-crates. Each sub-crate owns a distinct concern:

Crate	Owns
`siderust`	Astronomy API, coordinate transforms, observation planning, ephemeris front-end, satellite workflows, POD
`siderust_archive`	Scientific datasets, manifests, checksums, provenance, generated coefficient snapshots
`tempoch`	Time scales (TT/TAI/UTC/UT1/TDB/TCG/TCB), ΔT, EOP, active time-data status
`qtty`	Physical units and typed quantity arithmetic
`cheby`	Chebyshev / polynomial interpolation
`keplerian`	Keplerian orbital primitives
`principia`	Dynamics and physical force-model primitives
`optica`	Photometry and optics primitives

§Crate Modules

coordinates : Cartesian & Spherical coordinate types and transformations; includes SkyGrid sampling utility
targets : CoordinateWithPM<T> + Trackable trait for observation targets
time : Thin re-export facade over tempoch; adds TT-default JulianDate / J2000 aliases
astro : Aberration, nutation, precession, sidereal time, conic helpers, event support, orbits, orbital mechanics
ephemeris : Ephemeris traits and backends (VSOP87, ELP2000, DE4xx, Pluto); coefficient tables from siderust_archive
event : Altitude/azimuth/lunar/solar/stellar event-search APIs
bodies : Planets, stars, satellites, asteroids, comets, and built-in catalogs
mission : Mission geometry, runtime context, and site metadata (FoV, terrain mask, AzElRange, eclipse, orbit-relative)
catalogs::observatories : Predefined observatory locations (Roque, Paranal, Mauna Kea, La Silla)
qtty : Re-exports of typed quantity newtypes from the qtty crate
formats : Low-level binary file-format parsers (e.g. SPICE DAF/SPK)
atmosphere (optional) : Atmospheric refraction, extinction, airmass, and optical-depth models (atmosphere feature)
photometry (optional) : Astronomical photometric passbands and throughput unit (photometry feature)
Dataset catalog, manifests, and runtime ephemeris download: siderust_archive crate

§Error-handling conventions

siderust deliberately uses three distinct error-reporting patterns; they are not interchangeable. The choice tells you something about the contract of the function:

Pattern	Meaning
`-> Result<T, ConcreteError>`	A recoverable, domain-specific failure (bad input, no convergence, dataset out of range). The error type is module-local and documented.
`-> Option<T>`	A lookup that may legitimately have no answer (e.g. no event in the requested window, parameter outside the table’s interpolation range). The `None` semantics are documented in the `# Returns` section of every public `Option`-returning function.
`panic!` / `unwrap` / `expect`	A bug or contract violation: a non-finite Julian Date, an inverse of a singular rotation, an inconsistent type-system state, or a corrupt build-time table. Public functions that may panic carry a `# Panics` section.

When extending the public API, prefer Result over Option whenever the caller might want to know why there is no answer (e.g. “out of EOP range” vs “no event”). Reserve panics for true invariant violations, and document the trigger in the # Panics section.

§Minimal Example

use siderust::{bodies::Mars, time::{JulianDate, JD, TT, Time, UTC}};
use chrono::prelude::*;

// 1. Select an epoch (UTC now to JD)
let jd: JulianDate = Time::<UTC>::from_chrono(Utc::now()).to::<TT>().to::<JD>();

// 2. Compute barycentric ecliptic coordinates via VSOP87
let mars = Mars::vsop87e(jd);

// 3. Print Mars's barycentric ecliptic position (AstronomicalUnits)
println!("{:?}", mars);

For a runnable tour of the library, see the examples/ directory.

Re-exports§

pub use time::JulianDate;
pub use time::ModifiedJulianDate;
pub use time::J2000;
pub use coordinates::SkyGrid;
pub use coordinates::SkyGridCell;
pub use event::azimuth::azimuth_crossings;
pub use event::azimuth::azimuth_extrema;
pub use event::azimuth::azimuth_periods as compute_azimuth_periods;
pub use event::azimuth::azimuth_ranges;
pub use event::azimuth::in_azimuth_range;
pub use event::azimuth::outside_azimuth_range;
pub use event::azimuth::AzimuthCrossingDirection;
pub use event::azimuth::AzimuthCrossingEvent;
pub use event::azimuth::AzimuthExtremum;
pub use event::azimuth::AzimuthExtremumKind;
pub use event::azimuth::AzimuthProvider;
pub use event::azimuth::AzimuthQuery;
pub use event::solar::twilight;
pub use event::solar::Twilight;
pub use event::solar::twilight_classification;
pub use event::solar::TwilightPhase;
pub use astro::conic::ConicError;
pub use astro::conic::ConicOrbit;
pub use astro::conic::MeanMotionOrbit;
pub use astro::orbit::KeplerianOrbit;
pub use astro::orbit::PreparedOrbit;
pub use event::altitude::above_threshold;
pub use event::altitude::altitude_periods as compute_altitude_periods;
pub use event::altitude::altitude_ranges;
pub use event::altitude::below_threshold;
pub use event::altitude::crossings;
pub use event::altitude::culminations;
pub use event::altitude::AltitudePeriodsProvider;
pub use event::altitude::AltitudeQuery;
pub use event::altitude::CrossingDirection;
pub use event::altitude::CrossingEvent;
pub use event::altitude::CulminationEvent;
pub use event::altitude::CulminationKind;
pub use event::altitude::SearchOpts;
pub use event::lunar::phase::find_phase_events;
pub use event::lunar::phase::illumination_above;
pub use event::lunar::phase::illumination_below;
pub use event::lunar::phase::illumination_range;
pub use event::lunar::phase::moon_phase_geocentric;
pub use event::lunar::phase::moon_phase_topocentric;
pub use event::lunar::phase::MoonPhaseGeometry;
pub use event::lunar::phase::MoonPhaseLabel;
pub use event::lunar::phase::MoonPhaseSeries;
pub use event::lunar::phase::PhaseEvent;
pub use event::lunar::phase::PhaseKind;
pub use event::lunar::phase::PhaseSearchOpts;
pub use event::lunar::phase::PhaseThresholds;
pub use event::lunar::photometry::lunar_albedo_jones2013;
pub use event::lunar::photometry::lunar_full_moon_albedo_jones2013;
pub use event::lunar::photometry::lunar_phase_attenuation_jones2013;
pub use event::lunar::photometry::reflected_lunar_spectral_radiance_jones2013;
pub use targets::CoordinateWithPM;
pub use targets::Trackable;

Modules§

astro: Astro Module
bodies: Astronomical Bodies
catalogs: Large catalog ingestion, cone search, and observatory constants
checksum: Build-time integrity pinning for embedded data tables
coordinates: Coordinates Module
ephemeris: Ephemeris Provider Abstraction
event: Event searches
formats: File-format parsers and writers
mission: Mission-analysis building blocks
qtty: siderust::qtty — typed physical quantities
targets: Astronomical target representation
time: Time scales and instants

Macros§

assert_cartesian_eq: Assert that two cartesian::Position values agree component-wise within epsilon (same type and units). Panics with a coordinate-aware message on failure.
assert_data_checksum: Pin the SHA-256 of an embedded data blob at compile time.
assert_spherical_eq: Assert that two spherical::Position values agree within epsilon (distance in the typed length unit, angles in degrees). Panics with a coordinate-aware message on failure.

Structs§

JD: Julian Day (days since noon 1 January 4713 BC on the proleptic Julian calendar, TT axis by convention).
MJD: Modified Julian Day (JD − 2 400 000.5).

Enums§

ConicKind: High-level conic classification derived from eccentricity.

Crate siderust

Crate siderust Copy item path

§Siderust

§Scientific scope

§API pillars

§Crate composition

§Crate Modules

§Error-handling conventions

§Minimal Example

Re-exports§

Modules§

Macros§

Structs§

Enums§

Crate siderust