Skip to main content

Crate siderust

Crate siderust 

Source
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:

  1. 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.

  2. 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
  • Spectral utilities (optional spectra 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 Modules

  • coordinates : Cartesian & Spherical coordinate types and transformations
  • targets : CoordinateWithPM<T> + Trackable trait for targets
  • time : Time types and scale-based Period<S> / generic Interval<T>
  • astro : Aberration, nutation, precession, sidereal time, event searches, orbits
  • calculus : Numerical kernels (VSOP87, ELP2000, DE4xx, altitude/azimuth/lunar APIs, root-finding)
  • bodies : Planets, stars, satellites, asteroids, comets, and built-in catalogs
  • observatories : Predefined observatory locations (Roque, Paranal, Mauna Kea, La Silla)
  • qtty : Re-exports of typed quantity newtypes from the qtty crate (including OpticalDepth, Airmass, Albedo, IlluminationFraction, Refractivity, CipCoordinate)
  • geometry : Angular geometry primitives (great-circle, parallactic angle, …)
  • interp : Generic interpolation kernels
  • data : Built-in reference data (EOP tables, star catalogs)
  • provenance : Provenance and source-attribution types
  • atmosphere (optional) : Atmospheric refraction, extinction, airmass, and optical-depth models (atmosphere feature)
  • spectra (optional) : Spectral response and photometric bandpass utilities (spectra feature)
  • tables (optional) : Tabulated data loaders (tables feature)

§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:

PatternMeaning
-> 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 / expectA 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,
};
use chrono::prelude::*;

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

// 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 calculus::math_core::intervals::intersect as intersect_periods;
pub use calculus::azimuth::azimuth_crossings;
pub use calculus::azimuth::azimuth_extrema;
pub use calculus::azimuth::azimuth_periods as compute_azimuth_periods;
pub use calculus::azimuth::azimuth_ranges;
pub use calculus::azimuth::in_azimuth_range;
pub use calculus::azimuth::outside_azimuth_range;
pub use calculus::azimuth::AzimuthCrossingDirection;
pub use calculus::azimuth::AzimuthCrossingEvent;
pub use calculus::azimuth::AzimuthExtremum;
pub use calculus::azimuth::AzimuthExtremumKind;
pub use calculus::azimuth::AzimuthProvider;
pub use calculus::azimuth::AzimuthQuery;
pub use calculus::solar::twilight;
pub use calculus::solar::Twilight;
pub use calculus::solar::twilight_classification;
pub use calculus::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 calculus::altitude::above_threshold;
pub use calculus::altitude::altitude_periods as compute_altitude_periods;
pub use calculus::altitude::altitude_ranges;
pub use calculus::altitude::below_threshold;
pub use calculus::altitude::crossings;
pub use calculus::altitude::culminations;
pub use calculus::altitude::AltitudePeriodsProvider;
pub use calculus::altitude::AltitudeQuery;
pub use calculus::altitude::CrossingDirection;
pub use calculus::altitude::CrossingEvent;
pub use calculus::altitude::CulminationEvent;
pub use calculus::altitude::CulminationKind;
pub use calculus::altitude::SearchOpts;
pub use calculus::lunar::phase::find_phase_events;
pub use calculus::lunar::phase::illumination_above;
pub use calculus::lunar::phase::illumination_below;
pub use calculus::lunar::phase::illumination_range;
pub use calculus::lunar::phase::moon_phase_geocentric;
pub use calculus::lunar::phase::moon_phase_topocentric;
pub use calculus::lunar::phase::MoonPhaseGeometry;
pub use calculus::lunar::phase::MoonPhaseLabel;
pub use calculus::lunar::phase::MoonPhaseSeries;
pub use calculus::lunar::phase::PhaseEvent;
pub use calculus::lunar::phase::PhaseKind;
pub use calculus::lunar::phase::PhaseSearchOpts;
pub use calculus::lunar::phase::PhaseThresholds;
pub use calculus::lunar::photometry::lunar_albedo_jones2013;
pub use calculus::lunar::photometry::lunar_full_moon_albedo_jones2013;
pub use calculus::lunar::photometry::lunar_phase_attenuation_jones2013;
pub use calculus::lunar::photometry::reflected_lunar_spectral_radiance_jones2013;
pub use targets::CoordinateWithPM;
pub use targets::Trackable;

Modules§

astro
Astro Module
bodies
Astronomical Bodies
calculus
Celestial Mechanics Calculus Module
coordinates
Coordinates Module
data
Runtime data management
geometry
Geometric utilities: grids, samplers, and sky-coverage helpers.
interp
Shared interpolation policy types
observatories
Observatory catalog
provenance
Provenance metadata
qtty
Internal compatibility facade over the external qtty crate.
targets
Astronomical target representation
time
Time scales and instants

Macros§

assert_cartesian_eq
assert_data_checksum
Pin the SHA-256 of an embedded data blob at compile time.
assert_spherical_eq

Enums§

ConicKind
High-level conic classification derived from eccentricity.