Skip to main content

satellite_datetime/
lunar.rs

1//! Lunar Coordinate Time (IAU 2024 TCL) and provisional Coordinated Lunar Time.
2
3use crate::constants::{
4    LTC_DEFINITION_STATUS, LUNAR_SURFACE_MINUS_TT_PER_DAY, NS_PER_DAY, TAI_1977_NS,
5};
6use crate::duration::Duration;
7use crate::instant::Instant;
8use crate::scale::{Ltc, Reading, Tcl};
9
10/// IAU 2024 origin: TCB (and TCL) read 1977-01-01 00:00:32.184 at the Moon's center.
11/// That event is 1977-01-01 00:00:00 TAI + 32.184 s on TT; we use the TAI instant
12/// [`Instant::IAU_1977_TAI`] as the conventional origin event (same as TT/TCG).
13pub const TCL_ORIGIN: Instant = Instant::IAU_1977_TAI;
14
15/// Status of the operational LTC realization in this crate version.
16pub fn ltc_status() -> &'static str {
17    LTC_DEFINITION_STATUS
18}
19
20impl Instant {
21    /// TCL reading using the IAU shared origin with TCB, plus a **linear** TCB→TCL model.
22    ///
23    /// Periodic 4-velocity terms of the Moon in the BCRS are **not** applied.
24    /// Uncertainty: microseconds to milliseconds depending on span; sufficient for
25    /// mission planning, not for picosecond PNT. Surface proper time is
26    /// [`Self::lunar_mean_surface_proper`].
27    pub fn reading_tcl(self) -> Reading<Tcl> {
28        // Linear model: TCL and TCB share origin; leading rate uses TCB reading
29        // minus the small Earth–Moon barycentric difference (~GM_E/(c² a_EM)).
30        // With periodic terms omitted, TCL reading tracks TCB at the origin convention:
31        // TCL(t) = TCB(t) − TCB(t0) + TCL(t0), and TCL(t0)=TCB(t0).
32        Reading::new(self.reading_tcb().as_nanos())
33    }
34
35    /// Provisional LTC: currently identical to TCL (no extra conventional frequency offset).
36    pub fn reading_ltc(self) -> Reading<Ltc> {
37        Reading::new(self.reading_tcl().as_nanos())
38    }
39
40    /// Mean proper time of a clock at rest on the lunar surface relative to TT.
41    ///
42    /// Rate: +56.02 µs per terrestrial day (Ashby & Patla 2024; NASA SCaN class figure).
43    /// This is **not** TCL. Location-dependent periodic terms are omitted
44    /// (uncertainty: ~1 µs class over a day near the equator vs poles).
45    pub fn lunar_mean_surface_proper(self) -> Duration {
46        let dt = self.as_tai_nanos().saturating_sub(TAI_1977_NS);
47        let days = dt as f64 / NS_PER_DAY as f64;
48        Duration::from_nanos(
49            libm::round(days * LUNAR_SURFACE_MINUS_TT_PER_DAY.as_nanos() as f64) as i128,
50        )
51    }
52}
53
54#[cfg(test)]
55mod tests {
56    use super::*;
57
58    #[test]
59    fn origin_tcl_matches_tcb() {
60        let t0 = Instant::IAU_1977_TAI;
61        assert_eq!(t0.reading_tcl().as_nanos(), t0.reading_tcb().as_nanos());
62        assert_eq!(t0.reading_ltc().as_nanos(), t0.reading_tcl().as_nanos());
63        assert!(ltc_status().contains("provisional"));
64    }
65
66    #[test]
67    fn lunar_surface_faster_than_tt() {
68        let year = t0_plus_days(365);
69        let d = year.lunar_mean_surface_proper();
70        assert!(d.as_nanos() > 20_000_000); // > 20 ms / year (56µs*365≈20.4ms)
71        assert!(d.as_nanos() < 21_000_000);
72    }
73
74    fn t0_plus_days(days: i64) -> Instant {
75        Instant::IAU_1977_TAI
76            .checked_add(Duration::from_nanos(days as i128 * NS_PER_DAY))
77            .unwrap()
78    }
79}