Skip to main content

satellite_datetime/earth/
ut1.rs

1//! Pinned IERS C04 DUT1 (UT1−UTC) and Earth rotation from UT1.
2//!
3//! **Hot path** (sub-search-loop): [`utc_mjd`], [`dut1_at`], [`era_at_utc`], [`gmst_mean_at_utc`]
4//! on an existing [`CivilUtc`], or [`crate::UtcDay`] / [`crate::UtcContext`] for many instants on one UTC date.
5//!
6//! **Convenience** (runs [`Instant::to_utc`] search): [`dut1`], [`Instant::julian_ut1`],
7//! [`Instant::earth_rotation_angle_rad`], [`Instant::gmst_mean_rad`].
8//!
9//! DUT1 is sampled at 0h UTC on a 5-day knot grid (see [`UT1_TABLE_VERSION`]).
10//! Polar motion and the equation of the equinoxes are **not** included.
11//!
12//! [`crate::bodies::EARTH`] remains the IAU WGCCRE cartographic rotation model;
13//! it is **not** IERS UT1.
14
15use super::ut1_table::{FIRST_MJD, KNOTS, KNOT_SPACING, LAST_MJD};
16
17use crate::duration::Duration;
18use crate::error::{Error, Result};
19use crate::instant::Instant;
20use crate::julian::{unix_days_from_civil, JulianDate};
21
22use super::CivilUtc;
23
24/// Version string for the pinned DUT1 table in this crate build.
25pub const UT1_TABLE_VERSION: &str = "IERS-EOP-C04-14-IAU2000A224-MJD61045-5day";
26
27/// Result of a DUT1 lookup.
28#[derive(Clone, Copy, Debug, PartialEq)]
29pub struct Ut1Info {
30    /// UT1 − UTC in SI seconds (may be negative).
31    pub dut1: Duration,
32    /// Table version pin.
33    pub table: &'static str,
34}
35
36// ---------------------------------------------------------------------------
37// Hot path: caller already has civil UTC (no `Instant::to_utc` search).
38// ---------------------------------------------------------------------------
39
40/// Modified Julian Date of `utc` (continuous through leap seconds).
41pub fn utc_mjd(utc: CivilUtc) -> f64 {
42    utc_mjd_f64(utc)
43}
44
45/// DUT1 at `utc` via the pinned C04 table (no [`Instant::to_utc`]).
46pub fn dut1_at(utc: CivilUtc) -> Result<Ut1Info> {
47    let dut1_sec = lookup_dut1_seconds(utc_mjd_f64(utc))?;
48    Ok(Ut1Info {
49        dut1: Duration::from_seconds_f64(dut1_sec)?,
50        table: UT1_TABLE_VERSION,
51    })
52}
53
54/// Julian Date on UT1 from civil UTC (no [`Instant::to_utc`]).
55pub fn julian_ut1_at(utc: CivilUtc) -> Result<JulianDate> {
56    let mjd_ut1 = utc_mjd_f64(utc) + lookup_dut1_seconds(utc_mjd_f64(utc))? / 86_400.0;
57    Ok(julian_from_mjd(mjd_ut1))
58}
59
60/// IAU 2000 Earth Rotation Angle at `utc` (radians, `[0, 2π)`).
61pub fn era_at_utc(utc: CivilUtc) -> Result<f64> {
62    let jd = julian_ut1_at(utc)?.as_f64();
63    Ok(era_from_jd_ut1(jd))
64}
65
66/// IAU 2006 mean GMST at `utc` (radians, `[0, 2π)`).
67pub fn gmst_mean_at_utc(utc: CivilUtc) -> Result<f64> {
68    let jd = julian_ut1_at(utc)?.as_f64();
69    Ok(gmst_mean_from_jd_ut1(jd))
70}
71
72// ---------------------------------------------------------------------------
73// Convenience: `Instant` → search loop → civil → hot path internals.
74// ---------------------------------------------------------------------------
75
76/// DUT1 (UT1 − UTC) at this instant via the pinned C04 table.
77///
78/// Convenience wrapper: [`Instant::to_utc`] then [`dut1_at`]. For hot loops on a known
79/// UTC day, use [`crate::UtcDay`] + [`dut1_at`] instead.
80pub fn dut1(instant: Instant) -> Result<Ut1Info> {
81    dut1_at(instant.to_utc()?)
82}
83
84impl Instant {
85    /// Julian Date on UT1 (two-part).
86    ///
87    /// Convenience wrapper around [`julian_ut1_at`] after [`Self::to_utc`].
88    pub fn julian_ut1(self) -> Result<JulianDate> {
89        julian_ut1_at(self.to_utc()?)
90    }
91
92    /// IAU 2000 Earth Rotation Angle θ (radians), folded to `[0, 2π)`.
93    ///
94    /// Convenience wrapper around [`era_at_utc`] after [`Self::to_utc`].
95    pub fn earth_rotation_angle_rad(self) -> Result<f64> {
96        era_at_utc(self.to_utc()?)
97    }
98
99    /// IAU 2006 mean Greenwich sidereal time (radians), folded to `[0, 2π)`.
100    ///
101    /// Convenience wrapper around [`gmst_mean_at_utc`] after [`Self::to_utc`].
102    pub fn gmst_mean_rad(self) -> Result<f64> {
103        gmst_mean_at_utc(self.to_utc()?)
104    }
105}
106
107fn utc_mjd_f64(utc: CivilUtc) -> f64 {
108    let unix_days = unix_days_from_civil(utc.year, utc.month, utc.day) as f64;
109    let mjd0 = unix_days + 40_587.0;
110    let sod = utc.hour as f64 * 3600.0
111        + utc.minute as f64 * 60.0
112        + utc.second as f64
113        + utc.nanosecond as f64 / 1e9;
114    mjd0 + sod / 86_400.0
115}
116
117fn julian_from_mjd(mjd: f64) -> JulianDate {
118    let jd = mjd + 2_400_000.5;
119    let d1 = libm::floor(jd);
120    JulianDate { d1, d2: jd - d1 }
121}
122
123fn lookup_dut1_seconds(mjd: f64) -> Result<f64> {
124    if mjd < FIRST_MJD as f64 {
125        return Err(Error::Ut1Undefined);
126    }
127    if mjd > LAST_MJD as f64 {
128        return Err(Error::Ut1TableExpired);
129    }
130    let span = KNOT_SPACING as f64;
131    let idx = libm::floor((mjd - FIRST_MJD as f64) / span) as usize;
132    let idx = idx.min(KNOTS.len() - 2);
133    let (m0, t0) = KNOTS[idx];
134    let (m1, t1) = KNOTS[idx + 1];
135    let frac = (mjd - m0 as f64) / (m1 - m0) as f64;
136    let tenths = t0 as f64 + frac * (t1 - t0) as f64;
137    Ok(tenths / 10_000.0)
138}
139
140const J2000_JD: f64 = 2_451_545.0;
141const TWO_PI: f64 = 2.0 * core::f64::consts::PI;
142const ERA0: f64 = 0.7790572732640;
143const ERA_RATE: f64 = 1.002_737_811_911_354_6;
144
145fn era_from_jd_ut1(jd_ut1: f64) -> f64 {
146    let era = TWO_PI * (ERA0 + ERA_RATE * (jd_ut1 - J2000_JD));
147    fold_two_pi(era)
148}
149
150/// IAU 2006 mean GMST polynomial (degrees → radians).
151fn gmst_mean_from_jd_ut1(jd_ut1: f64) -> f64 {
152    let d = jd_ut1 - J2000_JD;
153    let t = d / 36_525.0;
154    let gmst_deg =
155        280.460_618_37 + 360.985_647_366_29 * d + 0.000_387_933 * t * t - t * t * t / 38_710_000.0;
156    let gmst_deg = libm::fmod(gmst_deg, 360.0);
157    let gmst_deg = if gmst_deg < 0.0 {
158        gmst_deg + 360.0
159    } else {
160        gmst_deg
161    };
162    gmst_deg * (core::f64::consts::PI / 180.0)
163}
164
165fn fold_two_pi(rad: f64) -> f64 {
166    let x = libm::fmod(rad, TWO_PI);
167    if x < 0.0 {
168        x + TWO_PI
169    } else {
170        x
171    }
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177    use crate::earth::tai_minus_utc;
178
179    #[test]
180    fn knot_hit_1972_epoch() {
181        let dut1 = lookup_dut1_seconds(41_317.0).unwrap();
182        assert!((dut1 - (-0.045_5)).abs() < 1e-4);
183    }
184
185    #[test]
186    fn linear_mid_interval() {
187        let mid = 41_319.5;
188        let d0 = lookup_dut1_seconds(41_317.0).unwrap();
189        let d1 = lookup_dut1_seconds(41_322.0).unwrap();
190        let mid_d = lookup_dut1_seconds(mid).unwrap();
191        assert!((mid_d - (d0 + d1) / 2.0).abs() < 1e-7);
192    }
193
194    #[test]
195    fn pre_1972_errors() {
196        let c = CivilUtc::new(1971, 12, 31, 12, 0, 0, 0).unwrap();
197        assert_eq!(dut1_at(c), Err(Error::Ut1Undefined));
198    }
199
200    #[test]
201    fn post_pin_errors() {
202        assert_eq!(
203            lookup_dut1_seconds(LAST_MJD as f64 + 1.0),
204            Err(Error::Ut1TableExpired)
205        );
206    }
207
208    #[test]
209    fn hot_path_matches_convenience() {
210        let c = CivilUtc::new(2010, 7, 24, 11, 18, 7, 318_000_000).unwrap();
211        let inst = c.to_instant().unwrap();
212        let d_slow = dut1(inst).unwrap();
213        let d_fast = dut1_at(c).unwrap();
214        assert_eq!(d_slow, d_fast);
215        let era_slow = inst.earth_rotation_angle_rad().unwrap();
216        let era_fast = era_at_utc(c).unwrap();
217        assert!((era_slow - era_fast).abs() < 1e-12);
218        let gmst_slow = inst.gmst_mean_rad().unwrap();
219        let gmst_fast = gmst_mean_at_utc(c).unwrap();
220        assert!((gmst_slow - gmst_fast).abs() < 1e-12);
221    }
222
223    #[test]
224    fn era_in_range() {
225        let c = CivilUtc::new(2010, 7, 24, 11, 18, 7, 318_000_000).unwrap();
226        let era = era_at_utc(c).unwrap();
227        assert!(era >= 0.0 && era < TWO_PI);
228    }
229
230    #[test]
231    fn gmst_in_range() {
232        let c = CivilUtc::new(2000, 1, 1, 12, 0, 0, 0).unwrap();
233        let gmst = gmst_mean_at_utc(c).unwrap();
234        assert!(gmst >= 0.0 && gmst < TWO_PI);
235    }
236
237    #[test]
238    fn j2000_era_near_classical_gmst() {
239        let c = CivilUtc::new(2000, 1, 1, 12, 0, 0, 0).unwrap();
240        let jd = julian_ut1_at(c).unwrap().as_f64();
241        let era = era_from_jd_ut1(jd);
242        let expected = TWO_PI * ERA0;
243        assert!((era - expected).abs() < 0.05);
244    }
245
246    #[test]
247    fn dut1_via_instant() {
248        let c = CivilUtc::new(2017, 1, 1, 0, 0, 0, 0).unwrap();
249        let inst = c.to_instant().unwrap();
250        let info = dut1(inst).unwrap();
251        assert_eq!(info.table, UT1_TABLE_VERSION);
252        assert!(info.dut1.as_seconds_f64().abs() < 1.0);
253        assert_eq!(tai_minus_utc(2017, 1, 1, 0.0).unwrap().tai_minus_utc, 37.0);
254    }
255
256    #[test]
257    fn utc_mjd_matches_julian() {
258        let c = CivilUtc::new(2010, 7, 24, 11, 18, 7, 0).unwrap();
259        let mjd = utc_mjd(c);
260        assert!(mjd > 55_000.0 && mjd < 56_000.0);
261    }
262}