Merge pull request #482 from nyx-space/feat/gh-291-lunar-time

Implement Lunar Time and Lunar Coordinated Time (experimental scales)

Author: ChristopherRabotin

README.md

@@ -1635,7 +1635,9 @@ class TimeScale:
     TAI: TimeScale = ...
     TCB: TimeScale = ...
     TCG: TimeScale = ...
+    TCL: TimeScale = ...
     TDB: TimeScale = ...
+    TL: TimeScale = ...
     TT: TimeScale = ...
     UTC: TimeScale = ...
 

hifitime.pyi

@@ -31,6 +31,10 @@ use crate::duration::{Duration, Unit};
 #[allow(unused_imports)]
 use crate::errors::{DurationError, ParseSnafu};
 use crate::leap_seconds::{LatestLeapSeconds, LeapSecondProvider};
+use crate::timescale::tcl::{
+    tcl_since_t77_to_tl_since_t77, tcl_since_t77_to_tt_since_t77, tl_since_t77_to_tcl_since_t77,
+    tt_since_t77_to_tcl_since_t77,
+};
 use crate::{
     HifitimeError, MonthName, TimeScale, TimeUnits, BDT_REF_EPOCH, ET_EPOCH_S, GPST_REF_EPOCH,
     GST_REF_EPOCH, MJD_J1900, MJD_OFFSET, QZSST_REF_EPOCH, UNIX_REF_EPOCH,
@@ -257,6 +261,42 @@ impl Epoch {
 
                     tdb_since_t77 - delta_tdb_tai + TimeScale::TCB.prime_epoch_offset()
                 }
+                TimeScale::TCL => {
+                    // self.duration is mean TCL duration since T0.
+                    //
+                    // Exact TCL would require the LCRS/BCRS relativistic integral using the
+                    // Moon center-of-mass state and external potentials. This experimental
+                    // implementation keeps only the conventional mean TCL-TT secular rate.
+                    let tcl_since_t77 = self.duration;
+
+                    // TCL -> TT
+                    let tt_since_t77 = tcl_since_t77_to_tt_since_t77(tcl_since_t77);
+
+                    // Add the TT absolute reference epoch, then TT -> TAI.
+                    let tt_duration = self.time_scale.prime_epoch_offset() + tt_since_t77;
+                    tt_duration - TT_OFFSET_MS.milliseconds()
+                }
+
+                TimeScale::TL => {
+                    // self.duration is TL option-iii duration since T0.
+                    //
+                    // TL option iii removes the secular TCL-TT drift. With bounded periodic
+                    // TCL-TT terms intentionally omitted, TL is equal to TT in this
+                    // experimental implementation.
+                    //
+                    // Keep the path TL -> TCL -> TT explicit so the relationship to
+                    // equation 47 remains visible and testable.
+                    let tl_since_t77 = self.duration;
+
+                    // TL -> TCL -> TT
+                    let tcl_since_t77 = tl_since_t77_to_tcl_since_t77(tl_since_t77);
+                    let tt_since_t77 = tcl_since_t77_to_tt_since_t77(tcl_since_t77);
+
+                    // TT -> TAI
+                    // NOTE: This whole branch can collapse to a simple TT offset because this is option (iii) of the paper
+                    let tt_duration = self.time_scale.prime_epoch_offset() + tt_since_t77;
+                    tt_duration - TT_OFFSET_MS.milliseconds()
+                }
             };
 
             // Convert to the desired time scale from the TAI duration
@@ -346,6 +386,29 @@ impl Epoch {
                     let relativistic_delta = t77_duration - TDB0_S.seconds();
                     t77_duration + relativistic_delta * ELB - TDB0_S.seconds()
                 }
+                TimeScale::TCL => {
+                    // TAI -> TT
+                    let tt_duration = prime_epoch_offset + TT_OFFSET_MS.milliseconds();
+
+                    // TT absolute duration -> TT duration since T0
+                    let tt_since_t77 = tt_duration - ts.prime_epoch_offset();
+
+                    // TT -> mean TCL
+                    tt_since_t77_to_tcl_since_t77(tt_since_t77)
+                }
+
+                TimeScale::TL => {
+                    // TAI -> TT
+                    let tt_duration = prime_epoch_offset + TT_OFFSET_MS.milliseconds();
+
+                    // TT absolute duration -> TT duration since T0
+                    let tt_since_t77 = tt_duration - ts.prime_epoch_offset();
+
+                    // TT -> TCL -> TL, keeping equation 47 explicit.
+                    // NOTE: This whole branch can collapse to a simple TT offset because this is option (iii) of the paper
+                    let tcl_since_t77 = tt_since_t77_to_tcl_since_t77(tt_since_t77);
+                    tcl_since_t77_to_tl_since_t77(tcl_since_t77)
+                }
             };
 
             Self {

src/epoch/mod.rs

@@ -30,6 +30,8 @@ impl fmt::Display for TimeScale {
             Self::QZSST => write!(f, "QZSST"),
             Self::TCG => write!(f, "TCG"),
             Self::TCB => write!(f, "TCB"),
+            Self::TL => write!(f, "TL"),
+            Self::TCL => write!(f, "TCL"),
         }
     }
 }
@@ -75,6 +77,10 @@ impl FromStr for TimeScale {
             Ok(Self::TCG)
         } else if val == "TCB" {
             Ok(Self::TCB)
+        } else if val == "TL" {
+            Ok(Self::TL)
+        } else if val == "TCL" {
+            Ok(Self::TCL)
         } else {
             Err(ParsingError::TimeSystem)
         }

src/timescale/fmt.rs

@@ -19,6 +19,9 @@ use serde_derive::{Deserialize, Serialize};
 
 mod fmt;
 
+/// EXPERIMENTAL Temps Lunaire Coordonnee / Lunar Coordinated Time
+pub(crate) mod tcl;
+
 use crate::{Duration, Epoch, Unit, SECONDS_PER_DAY};
 
 /// The J1900 reference epoch (1900-01-01 at noon) TAI.
@@ -95,7 +98,8 @@ pub enum TimeScale {
     TDB,
     /// Universal Coordinated Time
     UTC,
-    /// GPS Time scale whose reference epoch is UTC midnight between 05 January and 06 January 1980; cf. <https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS#GPS_Time_.28GPST.29>. |UTC - TAI| = 19 Leap Seconds on that day.
+    /// GPS Time scale whose reference epoch is UTC midnight between 05 January and 06 January 1980;
+    /// cf. <https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS#GPS_Time_.28GPST.29>. |UTC - TAI| = 19 Leap Seconds on that day.
     GPST,
     /// Galileo Time scale
     GST,
@@ -107,6 +111,22 @@ pub enum TimeScale {
     TCG,
     /// Barycentric Coordinate Time
     TCB,
+    /// Experimental Lunar Time, option (iii) from the Lunar Reference Timescale paper,  A Bourgoin*, P Defraigne and F Meynadier
+    ///
+    /// TL is defined as a linear scaling of TCL such that TL has no secular drift
+    /// with respect to TT. Since this implementation omits the bounded periodic
+    /// TCL-TT terms, TL is equivalent to TT after the common 1977 reference epoch.
+    TL,
+    /// Experimental mean Lunar Coordinate Time of Lunar reference timescale, A Bourgoin*, P Defraigne and F Meynadier
+    ///
+    /// This is not a full IAU-quality TCL realization. It models only the
+    /// conventional secular mean rate between TCL and TT:
+    /// ```text
+    ///     d(TCL - TT) / dTT ≈ 6.8e-10
+    /// ```
+    /// The bounded periodic TCL-TT terms and ephemeris-dependent relativistic
+    /// integral are intentionally omitted
+    TCL,
 }
 
 impl Default for TimeScale {
@@ -121,8 +141,15 @@ impl TimeScale {
         match &self {
             Self::QZSST => 5,
             Self::GPST => 4,
-            Self::TAI | Self::TDB | Self::UTC | Self::GST | Self::BDT | Self::TCG | Self::TCB => 3,
-            Self::ET | Self::TT => 2,
+            Self::TAI
+            | Self::TDB
+            | Self::UTC
+            | Self::GST
+            | Self::BDT
+            | Self::TCG
+            | Self::TCB
+            | Self::TCL => 3,
+            Self::ET | Self::TT | Self::TL => 2,
         }
     }
 
@@ -164,7 +191,7 @@ impl TimeScale {
                 centuries: 1,
                 nanoseconds: 189_302_433_000_000_000,
             },
-            TimeScale::TCG => {
+            TimeScale::TCG | TimeScale::TL | TimeScale::TCL => {
                 // TCG reference epoch is 1977-01-01 00:00:32.184 TT.
                 Duration {
                     centuries: 0,
@@ -214,6 +241,8 @@ impl From<TimeScale> for u8 {
             TimeScale::QZSST => 8,
             TimeScale::TCG => 9,
             TimeScale::TCB => 10,
+            TimeScale::TL => 11,
+            TimeScale::TCL => 12,
         }
     }
 }
@@ -233,13 +262,15 @@ impl From<u8> for TimeScale {
             8 => Self::QZSST,
             9 => Self::TCG,
             10 => Self::TCB,
+            11 => Self::TL,
+            12 => Self::TCL,
             _ => Self::TAI,
         }
     }
 }
 
 #[cfg(test)]
-mod unit_test_timescale {
+mod ut_timescale {
     use super::TimeScale;
 
     #[test]
@@ -258,7 +289,7 @@ mod unit_test_timescale {
             let ts = TimeScale::from(ts_u8);
             let ts_u8_back: u8 = ts.into();
             // If the u8 is greater than 10, it isn't valid and necessarily encoded as TAI.
-            if ts_u8 < 11 {
+            if ts_u8 < 13 {
                 assert_eq!(ts_u8_back, ts_u8, "got {ts_u8_back} want {ts_u8}");
             } else {
                 assert_eq!(ts, TimeScale::TAI);

src/timescale/mod.rs

@@ -0,0 +1,116 @@
+/*
+* Hifitime
+* Copyright (C) 2017-onward Christopher Rabotin <christopher.rabotin@gmail.com> et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors)
+* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*
+* Documentation: https://nyxspace.com/
+*/
+
+use crate::{Duration, TimeUnits};
+
+/// Mean fractional rate of TCL relative to TT.
+///
+/// Paper option iii removes this secular TCL-TT drift when defining TL.
+/// The paper gives approximately 6.8e-10, i.e. about 58.7 us/day.
+pub(crate) const TCL_MINUS_TT_MEAN_RATE: f64 = 6.8e-10;
+
+/// TL option iii:
+///
+/// ```text
+///     TL = TCL + Δf * (TCL - TCL0) + const0
+/// ```
+/// If:
+/// ```text
+///     dTCL / dTT = 1 + k
+/// ```
+/// then choosing:
+/// ```text
+///     1 + Δf = 1 / (1 + k)
+///
+/// gives:
+/// ```text
+///     dTL / dTT = 1
+/// ```
+/// so TL has no secular drift relative to TT.
+pub(crate) const TL_DELTA_F: f64 = -TCL_MINUS_TT_MEAN_RATE / (1.0 + TCL_MINUS_TT_MEAN_RATE);
+
+/// Recommended experimental convention:
+/// ```text
+///     TL = TCL = TT at T0
+/// ```
+/// with:
+/// ```text
+///     T0 = 1977-01-01T00:00:00 TAI
+///        = 1977-01-01T00:00:32.184 TT
+/// ```
+pub(crate) const TL_CONST0_S: f64 = 0.0;
+
+#[inline]
+pub fn tt_since_t77_to_tcl_since_t77(tt_since_t77: Duration) -> Duration {
+    // Mean TCL model:
+    //
+    //     TCL - TCL0 = (TT - TT0) * (1 + k)
+    //
+    // Do not factor this into tt_since_t77 * (1.0 + k), matching the
+    // style used for TCG/TCB to reduce avoidable rounding noise.
+    tt_since_t77 + tt_since_t77 * TCL_MINUS_TT_MEAN_RATE
+}
+
+#[inline]
+pub fn tcl_since_t77_to_tt_since_t77(tcl_since_t77: Duration) -> Duration {
+    // Inverse of:
+    //
+    //     TCL = TT * (1 + k)
+    //
+    // so:
+    //
+    //     TT = TCL / (1 + k)
+    //        = TCL * (1 - k / (1 + k))
+    tcl_since_t77 - tcl_since_t77 * (TCL_MINUS_TT_MEAN_RATE / (1.0 + TCL_MINUS_TT_MEAN_RATE))
+}
+
+#[inline]
+pub fn tcl_since_t77_to_tl_since_t77(tcl_since_t77: Duration) -> Duration {
+    // Option iii:
+    //
+    //     TL = TCL + Δf * (TCL - TCL0) + const0
+    //
+    // with const0 = 0 and TCL0 = T0.
+    tcl_since_t77 + tcl_since_t77 * TL_DELTA_F + TL_CONST0_S.seconds()
+}
+
+#[inline]
+pub fn tl_since_t77_to_tcl_since_t77(tl_since_t77: Duration) -> Duration {
+    // Since TL = TCL / (1 + k), the inverse is:
+    //
+    //     TCL = TL * (1 + k)
+    //
+    // const0 is zero in this convention.
+    let tl_minus_const0 = tl_since_t77 - TL_CONST0_S.seconds();
+    tl_minus_const0 + tl_minus_const0 * TCL_MINUS_TT_MEAN_RATE
+}
+
+#[cfg(test)]
+mod ut_tcl {
+    use super::*;
+    use crate::{Epoch, TimeScale, TimeUnits};
+
+    /// This test uses the private prime_epoch_offset, hence its definition here.
+    #[test]
+    fn tcl_accumulates_mean_drift_from_tt() {
+        let tt = Epoch::from_gregorian_at_midnight(2024, 2, 29, TimeScale::TT);
+        let tcl = tt.to_time_scale(TimeScale::TCL);
+
+        let tt_since_t77 = tt.duration - TimeScale::TCL.prime_epoch_offset();
+        let expected = tt_since_t77 * TCL_MINUS_TT_MEAN_RATE;
+
+        let actual = tcl.duration - tt_since_t77;
+
+        assert!(
+            (actual - expected).abs() <= 1.nanoseconds(),
+            "actual={actual}, expected={expected}"
+        );
+    }
+}