siderust 0.8.0

High-precision astronomy and satellite mechanics in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Vallés Puig, Ramon

//! # Time scales and instants
//!
//! ## Scientific scope
//!
//! Astronomical computations live on top of a small zoo of time scales —
//! TT (Terrestrial Time), TDB and TCB (the dynamical scales used by
//! barycentric ephemerides), TCG (geocentric coordinate time), TAI
//! (atomic time), UTC (civil time, with leap seconds), and UT1 (the
//! Earth-rotation scale). Mixing them silently produces errors of
//! seconds to tens of seconds — large enough to invalidate any
//! sub-arcsecond positional result. Following the IAU SOFA conventions
//! and the IERS Conventions (2010), every astronomical instant in this
//! crate carries its time scale at the type level so that conversions
//! between scales must be explicit.
//!
//! The reference epoch used throughout is **J2000.0 = JD 2 451 545.0
//! TT** (= 2000 January 1, 12:00:00 TT), as defined by IAU 2006
//! Resolution B1.
//!
//! ## Technical scope
//!
//! All time handling is delegated to the `tempoch` crate. This module
//! re-exports its full public surface (`Scale`, `EncodedTime`, `Time`,
//! the `TT`/`TDB`/`TCB`/`TCG`/`TAI`/`UTC`/`UT1` scale markers,
//! `Interval`, `delta_t_seconds`, …) and defines the v1 astronomy-facing
//! defaults as TT-based encoded dates plus the named same-scale helpers
//! (`to_jd`, `to_mjd`, `to_j2000_seconds`, `shifted_by`, `duration_since`)
//! provided by tempoch core:
//!
//! - [`JulianDate`] = `tempoch::JulianDate<TT>` = `EncodedTime<TT, JD>`.
//! - [`ModifiedJulianDate`] = `tempoch::ModifiedJulianDate<TT>` =
//!   `EncodedTime<TT, MJD>`.
//!
//! Advanced scale-aware work still uses `tempoch::JulianDate<S>` and
//! `tempoch::ModifiedJulianDate<S>` directly. The J2000.0 TT epoch is the
//! [`J2000`] constant (JD 2 451 545.0 TT). [`UT`] is a backward-compatible
//! alias for [`UT1`]; [`Period<T>`] is a backward-compatible alias for
//! [`Interval<T>`].
//!
//! ## References
//!
//! - IAU SOFA Board (2021). *IAU SOFA Software Collection*. International
//!   Astronomical Union. <http://www.iausofa.org/>.
//! - Petit, G., Luzum, B. (Eds.) (2010). *IERS Conventions (2010)*. IERS
//!   Technical Note 36. Verlag des Bundesamts für Kartographie und
//!   Geodäsie, Frankfurt am Main.
//! - Seidelmann, P. K. (Ed.) (1992). *Explanatory Supplement to the
//!   Astronomical Almanac*. University Science Books. ISBN 0-935702-68-7.
//! - International Astronomical Union (2006). Resolution B3 ("Re-definition
//!   of Barycentric Dynamical Time, TDB"). IAU Transactions XXVIB.

pub use tempoch::{
    complement_within, constats, delta_t_seconds, delta_t_seconds_extrapolated, eop,
    ContinuousScale, ConversionError, ConversionTarget, CoordinateScale, EncodedTime,
    FormatForScale, InfallibleConversionTarget, InfallibleFormatForScale, Interval,
    InvalidIntervalError, PeriodListError, Scale, Time, TimeContext, TimeDataError, TimeInstant,
    JD, MJD, TAI, TCB, TCG, TDB, TT, UT1, UTC,
};

/// Julian year length in days (`365.25`), matching tempoch's compiled Julian-year definition.
pub const JULIAN_YEAR_DAYS: qtty::Day = qtty::Day::new(365.25);

/// Backward-compatible alias: old siderust code used `UT` for the UT1 axis.
pub type UT = UT1;

/// Backward-compatible generic period alias over an instant type `T`.
pub type Period<T> = Interval<T>;

/// TT-scale Julian Date.  Equivalent to `tempoch::JulianDate<TT>`.
pub type JulianDate = tempoch::JulianDate<TT>;

/// TT-scale Modified Julian Date.  Equivalent to `tempoch::ModifiedJulianDate<TT>`.
pub type ModifiedJulianDate = tempoch::ModifiedJulianDate<TT>;

/// J2000.0 TT as a [`JulianDate`] (`JD 2 451 545.0 TT`); **`const`** everywhere.
pub const J2000: JulianDate = tempoch::JulianDate::<TT>::JD_EPOCH_J2000_0;

/// Runtime helper; prefer [`J2000`] in `const` contexts.
#[inline]
pub fn j2000_tt() -> JulianDate {
    J2000
}

/// Checked TT Julian Date constructor from a typed day quantity.
#[inline]
pub fn try_jd(raw: qtty::Day) -> Result<JulianDate, ConversionError> {
    if !raw.value().is_finite() {
        return Err(ConversionError::NonFinite);
    }
    JulianDate::try_new(raw)
}

/// Checked TT Julian Date constructor from a scalar JD value.
#[inline]
pub fn try_jd_f64(value: f64) -> Result<JulianDate, ConversionError> {
    try_jd(qtty::Day::new(value))
}

/// Checked TT Modified Julian Date constructor from a typed day quantity.
#[inline]
pub fn try_mjd(raw: qtty::Day) -> Result<ModifiedJulianDate, ConversionError> {
    if !raw.value().is_finite() {
        return Err(ConversionError::NonFinite);
    }
    ModifiedJulianDate::try_new(raw)
}

/// Checked TT Modified Julian Date constructor from a scalar MJD value.
#[inline]
pub fn try_mjd_f64(value: f64) -> Result<ModifiedJulianDate, ConversionError> {
    try_mjd(qtty::Day::new(value))
}

/// Helper: build a `ModifiedJulianDate` (TT scale) directly from a `chrono::DateTime<Utc>`.
///
/// This mirrors the common pattern `ModifiedJulianDate::from(dt)` but keeps a
/// crate-local helper for callers that prefer going through `siderust::time`.
#[inline]
pub fn modified_julian_date_from_chrono(dt: chrono::DateTime<chrono::Utc>) -> ModifiedJulianDate {
    ModifiedJulianDate::from(dt)
}

pub use crate::calculus::math_core::intervals::intersect as intersect_periods;