Skip to main content

satellite_datetime/earth/
leap.rs

1//! TAI−UTC from IERS Bulletin C / USNO tai-utc.dat (numeric table, not SOFA source).
2//!
3//! Last leap second in this pin: 2016-12-31. Dates more than five years past 2023
4//! return [`Error::LeapTableExpired`] as a warning analog to SOFA `eraDat` (we
5//! error rather than silently extrapolate).
6
7use crate::error::{Error, Result};
8
9/// Result of a TAI−UTC lookup.
10#[derive(Clone, Copy, Debug, PartialEq)]
11pub struct LeapInfo {
12    /// TAI − UTC in SI seconds (may be non-integer before 1972).
13    pub tai_minus_utc: f64,
14    /// +1 if this UTC day *ends* with a positive leap second, 0 otherwise.
15    pub leap_at_end: i8,
16    /// Bulletin / table version pin.
17    pub table: &'static str,
18}
19
20/// Version string for the numeric leap-second table in this crate build.
21pub const LEAP_TABLE_VERSION: &str = "IERS-Bulletin-C-2016-12-31+SOFA-pre1972-numeric";
22const RELEASE_YEAR: i32 = 2023;
23
24struct Change {
25    year: i32,
26    month: u8,
27    delta: f64,
28}
29
30/// Pre-1972 MJD reference and drift (s/day), aligned with IERS tai-utc.dat.
31struct Drift {
32    mjd0: f64,
33    rate: f64,
34}
35
36const CHANGES: &[Change] = &[
37    Change {
38        year: 1960,
39        month: 1,
40        delta: 1.4178180,
41    },
42    Change {
43        year: 1961,
44        month: 1,
45        delta: 1.4228180,
46    },
47    Change {
48        year: 1961,
49        month: 8,
50        delta: 1.3728180,
51    },
52    Change {
53        year: 1962,
54        month: 1,
55        delta: 1.8458580,
56    },
57    Change {
58        year: 1963,
59        month: 11,
60        delta: 1.9458580,
61    },
62    Change {
63        year: 1964,
64        month: 1,
65        delta: 3.2401300,
66    },
67    Change {
68        year: 1964,
69        month: 4,
70        delta: 3.3401300,
71    },
72    Change {
73        year: 1964,
74        month: 9,
75        delta: 3.4401300,
76    },
77    Change {
78        year: 1965,
79        month: 1,
80        delta: 3.5401300,
81    },
82    Change {
83        year: 1965,
84        month: 3,
85        delta: 3.6401300,
86    },
87    Change {
88        year: 1965,
89        month: 7,
90        delta: 3.7401300,
91    },
92    Change {
93        year: 1965,
94        month: 9,
95        delta: 3.8401300,
96    },
97    Change {
98        year: 1966,
99        month: 1,
100        delta: 4.3131700,
101    },
102    Change {
103        year: 1968,
104        month: 2,
105        delta: 4.2131700,
106    },
107    Change {
108        year: 1972,
109        month: 1,
110        delta: 10.0,
111    },
112    Change {
113        year: 1972,
114        month: 7,
115        delta: 11.0,
116    },
117    Change {
118        year: 1973,
119        month: 1,
120        delta: 12.0,
121    },
122    Change {
123        year: 1974,
124        month: 1,
125        delta: 13.0,
126    },
127    Change {
128        year: 1975,
129        month: 1,
130        delta: 14.0,
131    },
132    Change {
133        year: 1976,
134        month: 1,
135        delta: 15.0,
136    },
137    Change {
138        year: 1977,
139        month: 1,
140        delta: 16.0,
141    },
142    Change {
143        year: 1978,
144        month: 1,
145        delta: 17.0,
146    },
147    Change {
148        year: 1979,
149        month: 1,
150        delta: 18.0,
151    },
152    Change {
153        year: 1980,
154        month: 1,
155        delta: 19.0,
156    },
157    Change {
158        year: 1981,
159        month: 7,
160        delta: 20.0,
161    },
162    Change {
163        year: 1982,
164        month: 7,
165        delta: 21.0,
166    },
167    Change {
168        year: 1983,
169        month: 7,
170        delta: 22.0,
171    },
172    Change {
173        year: 1985,
174        month: 7,
175        delta: 23.0,
176    },
177    Change {
178        year: 1988,
179        month: 1,
180        delta: 24.0,
181    },
182    Change {
183        year: 1990,
184        month: 1,
185        delta: 25.0,
186    },
187    Change {
188        year: 1991,
189        month: 1,
190        delta: 26.0,
191    },
192    Change {
193        year: 1992,
194        month: 7,
195        delta: 27.0,
196    },
197    Change {
198        year: 1993,
199        month: 7,
200        delta: 28.0,
201    },
202    Change {
203        year: 1994,
204        month: 7,
205        delta: 29.0,
206    },
207    Change {
208        year: 1996,
209        month: 1,
210        delta: 30.0,
211    },
212    Change {
213        year: 1997,
214        month: 7,
215        delta: 31.0,
216    },
217    Change {
218        year: 1999,
219        month: 1,
220        delta: 32.0,
221    },
222    Change {
223        year: 2006,
224        month: 1,
225        delta: 33.0,
226    },
227    Change {
228        year: 2009,
229        month: 1,
230        delta: 34.0,
231    },
232    Change {
233        year: 2012,
234        month: 7,
235        delta: 35.0,
236    },
237    Change {
238        year: 2015,
239        month: 7,
240        delta: 36.0,
241    },
242    Change {
243        year: 2017,
244        month: 1,
245        delta: 37.0,
246    },
247];
248
249const NERA1: usize = 14;
250
251const DRIFT: &[Drift] = &[
252    Drift {
253        mjd0: 37300.0,
254        rate: 0.0012960,
255    },
256    Drift {
257        mjd0: 37300.0,
258        rate: 0.0012960,
259    },
260    Drift {
261        mjd0: 37300.0,
262        rate: 0.0012960,
263    },
264    Drift {
265        mjd0: 37665.0,
266        rate: 0.0011232,
267    },
268    Drift {
269        mjd0: 37665.0,
270        rate: 0.0011232,
271    },
272    Drift {
273        mjd0: 38761.0,
274        rate: 0.0012960,
275    },
276    Drift {
277        mjd0: 38761.0,
278        rate: 0.0012960,
279    },
280    Drift {
281        mjd0: 38761.0,
282        rate: 0.0012960,
283    },
284    Drift {
285        mjd0: 38761.0,
286        rate: 0.0012960,
287    },
288    Drift {
289        mjd0: 38761.0,
290        rate: 0.0012960,
291    },
292    Drift {
293        mjd0: 38761.0,
294        rate: 0.0012960,
295    },
296    Drift {
297        mjd0: 38761.0,
298        rate: 0.0012960,
299    },
300    Drift {
301        mjd0: 39126.0,
302        rate: 0.0025920,
303    },
304    Drift {
305        mjd0: 39126.0,
306        rate: 0.0025920,
307    },
308];
309
310/// TAI − UTC at 0h of the given UTC date (`fd` is fraction of day, used pre-1972).
311pub fn tai_minus_utc(year: i32, month: u8, day: u8, fd: f64) -> Result<LeapInfo> {
312    if year < 1960 {
313        return Err(Error::UtcUndefined);
314    }
315    if year > RELEASE_YEAR + 5 {
316        return Err(Error::LeapTableExpired);
317    }
318    if !(0.0..=1.0).contains(&fd) {
319        return Err(Error::InvalidTime);
320    }
321    let m = 12 * year + month as i32;
322    let mut idx = 0;
323    for (i, ch) in CHANGES.iter().enumerate().rev() {
324        if m >= 12 * ch.year + ch.month as i32 {
325            idx = i;
326            break;
327        }
328    }
329    let mut da = CHANGES[idx].delta;
330    if idx < NERA1 {
331        let mjd = crate::julian::unix_days_from_civil(year, month, day) as f64 + 40587.0;
332        da += (mjd + fd - DRIFT[idx].mjd0) * DRIFT[idx].rate;
333    }
334    let leap_at_end = leap_seconds_on_utc_day(year, month, day)?;
335    Ok(LeapInfo {
336        tai_minus_utc: da,
337        leap_at_end,
338        table: LEAP_TABLE_VERSION,
339    })
340}
341
342/// +1 if a positive leap second is inserted at the end of this UTC day.
343pub fn leap_seconds_on_utc_day(year: i32, month: u8, day: u8) -> Result<i8> {
344    let dim = crate::earth::days_in_month(year, month)?;
345    if day != dim {
346        return Ok(0);
347    }
348    // Leap seconds occur at the end of June or December in the modern era.
349    let (ny, nm) = if month == 12 {
350        (year + 1, 1)
351    } else if month == 6 {
352        (year, 7)
353    } else {
354        return Ok(0);
355    };
356    let now = lookup_delta(year, month);
357    let nxt = lookup_delta(ny, nm);
358    // Modern UTC leap seconds are exactly +1 s. The 1972-01-01 TAI−UTC step
359    // from the radio-era offset (~4.2 s) to 10 s is not a 23:59:60 leap.
360    let step = nxt - now;
361    if (step - 1.0).abs() < 1e-9 {
362        Ok(1)
363    } else {
364        Ok(0)
365    }
366}
367
368fn lookup_delta(year: i32, month: u8) -> f64 {
369    let m = 12 * year + month as i32;
370    let mut da = CHANGES[0].delta;
371    for ch in CHANGES {
372        if m >= 12 * ch.year + ch.month as i32 {
373            da = ch.delta;
374        }
375    }
376    da
377}
378
379#[cfg(test)]
380mod tests {
381    use super::*;
382
383    #[test]
384    fn modern_leap_offset() {
385        assert_eq!(
386            tai_minus_utc(2016, 12, 31, 0.0).unwrap().tai_minus_utc,
387            36.0
388        );
389        assert_eq!(tai_minus_utc(2017, 1, 1, 0.0).unwrap().tai_minus_utc, 37.0);
390        assert_eq!(leap_seconds_on_utc_day(2016, 12, 31).unwrap(), 1);
391        assert_eq!(leap_seconds_on_utc_day(2016, 12, 30).unwrap(), 0);
392    }
393
394    #[test]
395    fn gps_epoch_offset() {
396        // 1980-01-06: TAI−UTC = 19
397        assert_eq!(tai_minus_utc(1980, 1, 6, 0.0).unwrap().tai_minus_utc, 19.0);
398    }
399}