Skip to main content

satellite_datetime/
instant.rs

1//! Physical instants stored as TAI nanoseconds since 1958-01-01 00:00:00 TAI.
2
3use crate::constants::{
4    GPS_MINUS_TAI, L_B, L_G, NS_PER_DAY, TAI_1977_NS, TAI_EPOCH_JD, TDB0, TDB_EPOCH_JD,
5};
6use crate::duration::Duration;
7use crate::error::{Error, Result};
8use crate::scale::{Gps, Reading, Tai, Tcb, Tcg, Tdb, Tt};
9
10/// A unique event in spacetime's time axis, represented as TAI.
11///
12/// Civil time, DST, leap seconds, sols, and lunar clocks are projections of
13/// this value. Clock sources are injected: the core has no `now()`.
14///
15/// TAI add/sub and scale readings (TT, GPS, …) do not consult leap tables.
16/// Reconstructing civil UTC from an arbitrary instant (`to_utc`, feature `earth`)
17/// is a convenience search; same-day loops should pin `UtcDay` instead.
18#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
19pub struct Instant {
20    tai_ns: i128,
21}
22
23impl Instant {
24    /// TAI epoch: 1958-01-01 00:00:00 TAI.
25    pub const TAI_EPOCH: Self = Self { tai_ns: 0 };
26
27    /// IAU 1977-01-01 00:00:00 TAI (origin of TT/TCG/TCB linear relations).
28    pub const IAU_1977_TAI: Self = Self {
29        tai_ns: TAI_1977_NS,
30    };
31
32    /// Construct from TAI nanoseconds since [`Self::TAI_EPOCH`].
33    pub const fn from_tai_nanos(tai_ns: i128) -> Self {
34        Self { tai_ns }
35    }
36
37    /// TAI nanoseconds since the CCSDS/TAI epoch.
38    pub const fn as_tai_nanos(self) -> i128 {
39        self.tai_ns
40    }
41
42    /// Construct from a TAI reading (nanoseconds since TAI epoch).
43    pub const fn from_tai(reading: Reading<Tai>) -> Self {
44        Self { tai_ns: reading.ns }
45    }
46
47    /// TAI reading.
48    pub const fn reading_tai(self) -> Reading<Tai> {
49        Reading::new(self.tai_ns)
50    }
51
52    /// TT reading: TAI + 32.184 s.
53    pub const fn reading_tt(self) -> Reading<Tt> {
54        Reading::new(self.tai_ns + Duration::TT_MINUS_TAI.as_nanos())
55    }
56
57    /// Instant whose TT reading is `ns` nanoseconds after 1958-01-01 00:00:00 TT.
58    ///
59    /// 1958-01-01 00:00:00 TT = 1957-12-31 23:59:27.816 TAI, so this is TAI_ns = ns − 32.184 s.
60    pub const fn from_tt_nanos_since_1958_tt(ns: i128) -> Result<Self> {
61        match ns.checked_sub(Duration::TT_MINUS_TAI.as_nanos()) {
62            Some(tai_ns) => Ok(Self { tai_ns }),
63            None => Err(Error::Overflow),
64        }
65    }
66
67    /// GPS reading: TAI − 19 s (same origin instant expressed on the GPS clock).
68    pub const fn reading_gps(self) -> Reading<Gps> {
69        Reading::new(self.tai_ns + GPS_MINUS_TAI.as_nanos())
70    }
71
72    /// TCG − TT in nanoseconds (IAU linear term only; exact at the 1977 origin).
73    pub fn tcg_minus_tt(self) -> Duration {
74        let dt_sec = Self::seconds_from_1977_tt(self);
75        Duration::from_seconds_f64(L_G * dt_sec).unwrap_or(Duration::ZERO)
76    }
77
78    /// TCG reading.
79    pub fn reading_tcg(self) -> Reading<Tcg> {
80        let d = self.tcg_minus_tt();
81        Reading::new(self.reading_tt().as_nanos() + d.as_nanos())
82    }
83
84    /// Few-term TDB − TT (seconds). Amplitude ≈ 1.6 ms. Uncertainty: tens of µs
85    /// vs full Fairhead–Bretagnon / ERFA `dtdb` (which needs observer location).
86    pub fn tdb_minus_tt_seconds(self) -> f64 {
87        let jd_tt = self.julian_tt().as_f64();
88        let t = (jd_tt - 2_451_545.0) / 36_525.0;
89        // Mean anomaly of Earth (degrees → rad), IAU 2000/2006 leading terms.
90        let g = (357.528 + 35_999.050_962 * t) * (core::f64::consts::PI / 180.0);
91        0.001_657 * libm::sin(g) + 0.000_013_85 * libm::sin(2.0 * g)
92    }
93
94    /// TDB reading (TT plus periodic terms).
95    pub fn reading_tdb(self) -> Reading<Tdb> {
96        let d = Duration::from_seconds_f64(self.tdb_minus_tt_seconds()).unwrap_or(Duration::ZERO);
97        Reading::new(self.reading_tt().as_nanos() + d.as_nanos())
98    }
99
100    /// TCB − TDB (IAU 2006 linear).
101    pub fn tcb_minus_tdb(self) -> Duration {
102        let jd_tdb = self.julian_tt().as_f64() + self.tdb_minus_tt_seconds() / 86_400.0;
103        let sec = L_B * (jd_tdb - TDB_EPOCH_JD) * 86_400.0 - TDB0;
104        Duration::from_seconds_f64(sec).unwrap_or(Duration::ZERO)
105    }
106
107    /// TCB reading.
108    pub fn reading_tcb(self) -> Reading<Tcb> {
109        let ns = self.reading_tdb().as_nanos() + self.tcb_minus_tdb().as_nanos();
110        Reading::new(ns)
111    }
112
113    /// Add an SI duration.
114    pub const fn checked_add(self, d: Duration) -> Result<Self> {
115        match self.tai_ns.checked_add(d.as_nanos()) {
116            Some(tai_ns) => Ok(Self { tai_ns }),
117            None => Err(Error::Overflow),
118        }
119    }
120
121    /// Subtract an SI duration.
122    pub const fn checked_sub(self, d: Duration) -> Result<Self> {
123        match self.tai_ns.checked_sub(d.as_nanos()) {
124            Some(tai_ns) => Ok(Self { tai_ns }),
125            None => Err(Error::Overflow),
126        }
127    }
128
129    /// SI duration `self - earlier`.
130    pub const fn duration_since(self, earlier: Self) -> Result<Duration> {
131        match self.tai_ns.checked_sub(earlier.tai_ns) {
132            Some(ns) => Ok(Duration::from_nanos(ns)),
133            None => Err(Error::Overflow),
134        }
135    }
136
137    fn seconds_from_1977_tt(self) -> f64 {
138        let tt_ns = self.tai_ns + Duration::TT_MINUS_TAI.as_nanos();
139        let origin_tt_ns = TAI_1977_NS + Duration::TT_MINUS_TAI.as_nanos();
140        (tt_ns - origin_tt_ns) as f64 / 1_000_000_000.0
141    }
142}
143
144impl Instant {
145    /// Days of TAI from epoch as `f64` (for rate formulas).
146    pub fn tai_days(self) -> f64 {
147        self.tai_ns as f64 / NS_PER_DAY as f64
148    }
149
150    /// Julian Date of TAI epoch plus this instant, as `f64`.
151    pub fn jd_tai_f64(self) -> f64 {
152        TAI_EPOCH_JD + self.tai_days()
153    }
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    #[test]
161    fn tt_is_constant_offset() {
162        let t = Instant::TAI_EPOCH;
163        assert_eq!(t.reading_tt().as_nanos(), Duration::TT_MINUS_TAI.as_nanos());
164        let later = t.checked_add(Duration::from_seconds(1_000_000)).unwrap();
165        assert_eq!(
166            later.reading_tt().as_nanos() - later.reading_tai().as_nanos(),
167            Duration::TT_MINUS_TAI.as_nanos()
168        );
169    }
170
171    #[test]
172    fn tcg_equals_tt_at_1977() {
173        let t = Instant::IAU_1977_TAI;
174        let dt = t.tcg_minus_tt().as_nanos();
175        assert!(dt.abs() <= 1, "TCG−TT at origin should be 0 ns, got {dt}");
176    }
177
178    #[test]
179    fn tcg_grows_with_lg() {
180        let year = Duration::from_seconds(32_000_000); // ~370 days
181        let t = Instant::IAU_1977_TAI.checked_add(year).unwrap();
182        let d = t.tcg_minus_tt().as_seconds_f64();
183        let expected = L_G * year.as_seconds_f64();
184        assert!((d - expected).abs() < 1e-8, "d={d} expected={expected}");
185    }
186
187    #[test]
188    fn cannot_overflow_silently() {
189        assert!(Instant::from_tai_nanos(i128::MAX)
190            .checked_add(Duration::NANOSECOND)
191            .is_err());
192    }
193}