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}