satellite_datetime/earth/
ut1.rs1use 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
24pub const UT1_TABLE_VERSION: &str = "IERS-EOP-C04-14-IAU2000A224-MJD61045-5day";
26
27#[derive(Clone, Copy, Debug, PartialEq)]
29pub struct Ut1Info {
30 pub dut1: Duration,
32 pub table: &'static str,
34}
35
36pub fn utc_mjd(utc: CivilUtc) -> f64 {
42 utc_mjd_f64(utc)
43}
44
45pub 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
54pub 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
60pub 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
66pub 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
72pub fn dut1(instant: Instant) -> Result<Ut1Info> {
81 dut1_at(instant.to_utc()?)
82}
83
84impl Instant {
85 pub fn julian_ut1(self) -> Result<JulianDate> {
89 julian_ut1_at(self.to_utc()?)
90 }
91
92 pub fn earth_rotation_angle_rad(self) -> Result<f64> {
96 era_at_utc(self.to_utc()?)
97 }
98
99 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
150fn 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}