deep_time/scale.rs
1use core::fmt;
2
3/// Time scales supported for conversions.
4///
5/// This `#[non_exhaustive]` enum defines the complete set of time scales used by
6/// the library for representing instants (`Epoch`) and performing conversions
7/// between them.
8///
9/// It covers atomic, dynamical, coordinate, civil/coordinated, GNSS, and emerging
10/// lunar scales, plus a `Custom` variant for mission-specific or experimental use.
11///
12/// ## Overview
13///
14/// Time scales fall into several broad categories:
15///
16/// - **Atomic / proper time scales**: TAI (basis), TT, TDB/ET — continuous and
17/// suitable for internal representation and dynamical modeling.
18/// - **Coordinate time scales** (relativistic): TCG, TCB, **TCL** — defined in
19/// specific reference frames (GCRS, BCRS, LCRS). Ideal for ephemeris
20/// integration and high-accuracy modeling; not directly realized by clocks.
21/// - **Coordinated / civil scales**: UTC (atomic time with leap seconds inserted
22/// to keep it close to UT1), **UT1** (observed Earth rotation angle — does **not**
23/// use leap seconds), and the lunar operational scale **LTC** (uses defined
24/// secular rate offsets for traceability and cislunar operations).
25/// - **GNSS / navigation scales**: GPS, GST, BDT, QZSS — tied to specific
26/// satellite constellations.
27/// - **Custom**: Fallback for custom scales.
28///
29/// The default variant is [`TAI`], which serves as the internal canonical
30/// representation in many high-precision time libraries because it is
31/// continuous and forms the foundation for most conversions.
32///
33/// The library's epoch when performing conversions between all scales is
34/// 2000-01-01 noon.
35///
36/// ## Lunar Time Scales (LTC and TCL)
37///
38/// The library provides high-accuracy implementations of both lunar time scales
39/// based on the **LTE440** model (Lu et al. 2025, A&A 704, A76):
40///
41/// - [`LTC`] (Coordinated Lunar Time): Applies the secular rate offset
42/// (`L_M ≈ +56.02 µs/day`) **plus** the 13 dominant periodic terms from LTE440.
43/// Conversions use fixed-point iteration for numerical stability.
44/// Achieves sub-nanosecond accuracy (< 0.15 ns before 2050) when the periodic
45/// terms are included.
46///
47/// - [`TCL`] (Lunar Coordinate Time): IAU-defined relativistic coordinate time
48/// in the LCRS. The implementation includes the secular rate vs TDB, the same
49/// LTE440 periodic terms, and a constant bias calibrated so that the model
50/// exactly reproduces the official LTE440 reference value at J2000.0 TDB.
51/// Inverse conversion also uses fixed-point iteration.
52///
53/// See the documentation on the individual variants for rates, historical
54/// models, and conversion notes.
55///
56/// ## Features
57///
58/// - `serde` — full serialization/deserialization support.
59/// - `js` — TypeScript definitions via `tsify`.
60///
61/// ## Non-exhaustive
62///
63/// The enum is marked `#[non_exhaustive]` so new scales can be added in
64/// future minor versions without breaking changes.
65#[non_exhaustive]
66#[repr(u8)]
67#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
68#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
69#[cfg_attr(feature = "js", derive(tsify::Tsify))]
70pub enum Scale {
71 /// TAI is the representation of an Epoch internally.
72 #[default]
73 TAI,
74
75 /// Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT)).
76 TT,
77
78 /// Ephemeris Time as defined by NASA/NAIF SPICE (identical to TDB).
79 ET,
80
81 /// Barycentric Dynamical Time (TDB) — SPICE ephemeris time (ET is an alias for this).
82 TDB,
83
84 /// Universal Coordinated Time using modern IERS leap second rules.
85 UTC,
86
87 /// Universal Coordinated Time using the SPICE historical model
88 /// (fixed +9 s offset against TAI for all dates before 1972-01-01).
89 UTCSpice,
90
91 /// Universal Coordinated Time using the full SOFA historical model
92 /// (varying fractional "rubber second" offsets from 1960–1971).
93 UTCSofa,
94
95 /// GPS Time scale whose reference epoch is UTC midnight between 05 January and
96 /// 06 January 1980.
97 GPS,
98
99 /// Galileo Time scale.
100 GST,
101
102 /// BeiDou Time scale.
103 BDT,
104
105 /// QZSS Time scale has the same properties as GPS but with dedicated clocks.
106 QZSS,
107
108 /// **Geocentric Coordinate Time (TCG)** – relativistic coordinate time in the
109 /// Geocentric Celestial Reference System (GCRS).
110 TCG,
111
112 /// **Barycentric Coordinate Time (TCB)** – relativistic coordinate time in the
113 /// Barycentric Celestial Reference System (BCRS).
114 TCB,
115
116 /// **Coordinated Lunar Time (LTC)** – NASA’s operational lunar time scale
117 /// for Artemis and cislunar operations (based on the NIST/Ashby & Patla
118 /// relativistic framework).
119 ///
120 /// Implements the full **LTE440** model (Lu et al. 2025):
121 /// - Secular rate: **+56.02 µs per Earth day** (`L_M = 6.48378 × 10^{-10}`)
122 /// relative to terrestrial time.
123 /// - Plus the 13 dominant periodic terms (> 1 µs amplitude) from the LTE440
124 /// ephemeris.
125 LTC,
126
127 /// **Lunar Coordinate Time (TCL)** – IAU-defined (2024 Resolution II)
128 /// relativistic coordinate time in the Lunar Celestial Reference System (LCRS).
129 ///
130 /// Directly analogous to **TCG**. This is the theoretical coordinate time
131 /// at the Moon’s center of mass.
132 ///
133 /// The implementation follows the **LTE440** model (Lu et al. 2025):
134 /// - Secular rate vs TDB (`L_D^M`).
135 /// - The same 13-term LTE440 periodic series used for LTC.
136 /// - A constant bias (`TCL_TDB_BIAS_SPAN`) calibrated so the model exactly
137 /// reproduces the published LTE440 reference value at J2000.0 TDB.
138 TCL,
139
140 /// Custom / user-defined type.
141 Custom,
142}
143
144impl Scale {
145 /// Returns `true` if this scale is TAI.
146 #[inline]
147 pub const fn is_tai(&self) -> bool {
148 matches!(self, Self::TAI)
149 }
150
151 /// Converts this [`Scale`] to UTC.
152 /// - If the scale is already one of the UTC variants
153 /// including historical UTC then no change occurs.
154 #[inline]
155 pub const fn to_utc(&self) -> Self {
156 if self.uses_leap_seconds() {
157 *self
158 } else {
159 Scale::UTC
160 }
161 }
162
163 /// Returns `true` if this scale accounts for leap seconds
164 /// (or historical UTC civil time rules).
165 #[inline]
166 pub const fn uses_leap_seconds(&self) -> bool {
167 matches!(self, Self::UTC | Self::UTCSpice | Self::UTCSofa)
168 }
169
170 /// Returns `true` if this scale is based off a GNSS constellation.
171 #[inline]
172 pub const fn is_gnss(&self) -> bool {
173 matches!(self, Self::GPS | Self::GST | Self::BDT | Self::QZSS)
174 }
175
176 /// Parse scale from abbreviation.
177 /// Returns `None` for any non-ASCII input.
178 pub fn from_abbrev(s: &str) -> Option<Self> {
179 let bytes = s.as_bytes();
180 if !bytes.is_ascii() {
181 return None;
182 }
183 let mut buf = [0u8; 8];
184 let mut len = 0;
185 for &byte in bytes {
186 if len >= 8 {
187 return None;
188 }
189 buf[len] = if byte.is_ascii_lowercase() {
190 byte - 32
191 } else {
192 byte
193 };
194 len += 1;
195 }
196 let upper = core::str::from_utf8(&buf[..len]).ok()?;
197 match upper {
198 "TAI" => Some(Self::TAI),
199 "TT" => Some(Self::TT),
200 "ET" => Some(Self::ET),
201 "TDB" => Some(Self::TDB),
202 "UTC" => Some(Self::UTC),
203 "UTCSPICE" => Some(Self::UTCSpice),
204 "UTCSOFA" => Some(Self::UTCSofa),
205 "GPS" => Some(Self::GPS),
206 "GST" => Some(Self::GST),
207 "BDT" => Some(Self::BDT),
208 "QZSS" => Some(Self::QZSS),
209 "TCG" => Some(Self::TCG),
210 "TCB" => Some(Self::TCB),
211 "LTC" => Some(Self::LTC),
212 "TCL" => Some(Self::TCL),
213 "CUSTOM" => Some(Self::Custom),
214 _ => None,
215 }
216 }
217
218 /// Short abbreviation used for formatting / display (e.g. "TAI", "UTC", "UTCSpice").
219 pub const fn abbrev(&self) -> &'static str {
220 match self {
221 Self::TAI => "TAI",
222 Self::TT => "TT",
223 Self::ET => "ET",
224 Self::TDB => "TDB",
225 Self::UTC => "UTC",
226 Self::UTCSpice => "UTCSPICE",
227 Self::UTCSofa => "UTCSOFA",
228 Self::TCG => "TCG",
229 Self::TCB => "TCB",
230 Self::GPS => "GPS",
231 Self::GST => "GST",
232 Self::BDT => "BDT",
233 Self::QZSS => "QZSS",
234 Self::LTC => "LTC",
235 Self::TCL => "TCL",
236 Self::Custom => "CUSTOM",
237 }
238 }
239
240 /// Const-friendly equality comparison.
241 #[inline]
242 pub const fn eq(self, other: Self) -> bool {
243 self.to_wire_byte() == other.to_wire_byte()
244 }
245
246 /// Size of the canonical wire representation in bytes.
247 pub const WIRE_SIZE: usize = 1;
248
249 /// Attempts to reconstruct a `Scale` from its wire byte representation.
250 ///
251 /// - Returns `Custom` for any value that does not correspond to a known variant.
252 /// - This provides safe deserialization from untrusted sources.
253 pub const fn from_u8(v: u8) -> Self {
254 match v {
255 0 => Self::TAI,
256 1 => Self::TT,
257 2 => Self::ET,
258 3 => Self::TDB,
259 4 => Self::UTC,
260 5 => Self::UTCSpice,
261 6 => Self::UTCSofa,
262 7 => Self::GPS,
263 8 => Self::GST,
264 9 => Self::BDT,
265 10 => Self::QZSS,
266 11 => Self::TCG,
267 12 => Self::TCB,
268 13 => Self::LTC,
269 14 => Self::TCL,
270 _ => Self::Custom,
271 }
272 }
273
274 /// Returns the wire representation of this `Scale` as a single byte.
275 ///
276 /// The returned byte is the `repr(u8)` discriminant of the enum.
277 /// This is the canonical on-wire form used by [`Dt`].
278 #[inline]
279 pub const fn to_wire_byte(self) -> u8 {
280 self as u8
281 }
282}
283
284impl fmt::Display for Scale {
285 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
286 f.write_str(self.abbrev())
287 }
288}