Skip to main content

spacelab_frames/
cio_fast.rs

1//! CIO-frame interpolation — the fast GCRF→ITRF provider for high-fidelity Earth-fixed propagation.
2//!
3//! Almost all of the exact [`crate::gcrf_to_itrf`] is the IAU 2006/2000A CIP series
4//! ([`spacelab_fa::cip_xy`], ~1600 amplitudes over 1309 distinct frequencies). Those coordinates are
5//! driven by TT and so vary on **day** scales, while the Earth Rotation Angle (from UT1) is what
6//! moves fast within a step. [`CioInterpolator`] precomputes the four slow scalars `(X, Y, s, s′)` on
7//! a coarse grid over the propagation span and degree-`(STENCIL−1)` Lagrange-interpolates them per
8//! query, applying the **exact** ERA every time. The per-stage cost drops from a ~1600-term series to
9//! a handful of multiplies — two to three orders of magnitude on the machines measured so far; run
10//! `cargo run --release --features std --example cio_bench` for the ratio on yours. It matches the exact
11//! transform to the f64 floor (sub-nanometre at LEO) — see
12//! `cio_interpolation_matches_the_exact_transform`.
13//!
14//! **A query outside the grid is never extrapolated.** A degree-7 polynomial leaves its stencil
15//! badly, and an interpolator that answers plausibly for an epoch it does not cover is worse than one
16//! that is slow: it is wrong without saying so. Outside the grid the four scalars are re-evaluated
17//! from the series, so every query is correct and only the uncovered ones are slow.
18//!
19//! Polar motion `(xp, yp)`, the CIP offsets `(dx, dy)` and the length-of-day are held fixed over the
20//! span — that is the approximation this type does make, and it is the one that decides the answer
21//! (up to decimetres over a six-hour arc), not the interpolation. For a time-varying-EOP or
22//! double-double path, use the exact per-stage [`crate::gcrf_to_itrf`].
23//!
24//! # How small the interpolation error is, as a bound rather than a sample
25//!
26//! `derivations/cio_interpolation.mac` does the Lagrange remainder — the node product is exactly
27//! `11025/256` for a centred query and 14.87× that when the stencil is clamped at a grid end — and
28//! `derivations/cio_interpolation.py` bounds `sup|d⁸X/dt⁸|` from the shipped
29//! [`spacelab_fa`] table itself: **9.84e-48 rad/s⁸**, set by a 306 µas term of 5.6-day period, with
30//! the fastest argument combination in the series at 3.495 days. At `GRID_DT` the truncation error
31//! is then **1.3e-21 m at LEO** centred and 1.9e-20 m clamped.
32//!
33//! That is seven orders *below* the other half of the error, which is what actually sets the floor:
34//! the nodes are `f64`, and Lagrange interpolation amplifies whatever they carry by the stencil's
35//! Lebesgue constant — **1.488** centred, **6.93** clamped — so one ulp of a CIP coordinate
36//! (4.34e-19 rad, 2.9 pm at LEO) comes out as 4.4 pm or 20 pm. The measured sub-nanometre agreement
37//! is arithmetic, not method, and `GRID_DT` is not what sets it: truncation would not reach one
38//! nanometre at LEO until the grid was **22× coarser**. `s′` is linear in `t`, so its eighth
39//! derivative is zero and degree-7 interpolation reproduces it exactly.
40
41// Grid indices and nanosecond stamps are small, in-range integer-valued quantities; the single-letter
42// names (X, Y, s, s′ and the Lagrange indices) are the notation of the CIO chain and the interpolant.
43#![allow(
44    clippy::cast_possible_truncation,
45    clippy::cast_sign_loss,
46    clippy::cast_precision_loss,
47    clippy::cast_possible_wrap,
48    clippy::many_single_char_names
49)]
50
51use spacelab_core::{Angle, Epoch, Tt, Ut1, Vec3};
52use spacelab_fa::{cio_locator_s, cip_xy, era};
53
54use crate::cio::{cirs_to_tirs, gcrf_to_cirs, tirs_to_itrf};
55use crate::polar_motion::tio_locator;
56use crate::rotation::{Gcrf, Itrf, Rotation, Transform};
57use crate::teme::EARTH_ROTATION_RATE;
58
59/// Lagrange stencil width; the interpolating polynomial has degree `STENCIL − 1`.
60const STENCIL: usize = 8;
61/// Grid spacing in seconds — the CIP is smooth on day scales, so a degree-7 stencil at 10-minute
62/// spacing resolves it far below the f64 floor.
63const GRID_DT: f64 = 600.0;
64
65/// The four slow, TT-driven scalars of the CIO chain at one grid node.
66#[derive(Clone, Copy)]
67struct Node {
68    x: f64,
69    y: f64,
70    s: f64,
71    sp: f64,
72}
73
74/// A GCRF→ITRF transform provider that interpolates the slow precession-nutation geometry from a grid
75/// precomputed over the propagation span, applying the exact Earth Rotation Angle per query.
76pub struct CioInterpolator {
77    nodes: Vec<Node>,
78    /// Propagation time (s) of node 0; `≤ 0` so backward arcs are covered.
79    t_start: f64,
80    epoch_ut1: Epoch<Ut1>,
81    /// The arc's start on TT, kept so an uncovered query can re-evaluate the series.
82    epoch_tt: Epoch<Tt>,
83    xp: Angle,
84    yp: Angle,
85    dx: Angle,
86    dy: Angle,
87    lod_seconds: f64,
88}
89
90impl CioInterpolator {
91    /// Build the interpolator for propagation over `[min(0, span), max(0, span)]` seconds from the
92    /// epoch. `epoch_ut1`/`epoch_tt` are the arc's start on the two time scales; `xp`/`yp` polar
93    /// motion, `dx`/`dy` the celestial-pole offsets, `lod_seconds` the length-of-day excess — all held
94    /// fixed over the span.
95    #[must_use]
96    #[allow(clippy::too_many_arguments)] // two epochs, the span, and the five fixed EOP scalars
97    pub fn new(
98        epoch_ut1: Epoch<Ut1>,
99        epoch_tt: Epoch<Tt>,
100        span: f64,
101        xp: Angle,
102        yp: Angle,
103        dx: Angle,
104        dy: Angle,
105        lod_seconds: f64,
106    ) -> Self {
107        // Cover the arc plus a full stencil of margin at each end, so no query ever extrapolates.
108        let margin = STENCIL as f64 * GRID_DT;
109        let t_start = span.min(0.0) - margin;
110        let reach = span.abs() + 2.0 * margin;
111        let count = (reach / GRID_DT).ceil() as usize + 1;
112        let mut nodes = Vec::with_capacity(count);
113        let epoch_tt_ns = epoch_tt.ns_since_j2000();
114        for i in 0..count {
115            let ti = t_start + i as f64 * GRID_DT;
116            let tt = Epoch::<Tt>::from_ns_since_j2000(epoch_tt_ns + (ti * 1e9).round() as i128);
117            let (x, y) = cip_xy(tt);
118            let s = cio_locator_s(tt, x, y);
119            let sp = tio_locator(tt).radians();
120            nodes.push(Node { x, y, s, sp });
121        }
122        Self {
123            nodes,
124            t_start,
125            epoch_ut1,
126            epoch_tt,
127            xp,
128            yp,
129            dx,
130            dy,
131            lod_seconds,
132        }
133    }
134
135    /// The GCRF→ITRF rotation at propagation time `t` seconds.
136    #[must_use]
137    pub fn rotation(&self, t: f64) -> Rotation<Gcrf, Itrf> {
138        let node = self.interpolate(t);
139        let ut1 = Epoch::<Ut1>::from_ns_since_j2000(
140            self.epoch_ut1.ns_since_j2000() + (t * 1e9).round() as i128,
141        );
142        let q = gcrf_to_cirs(
143            node.x + self.dx.radians(),
144            node.y + self.dy.radians(),
145            node.s,
146        );
147        tirs_to_itrf(self.xp, self.yp, Angle::from_radians(node.sp)) * cirs_to_tirs(era(ut1)) * q
148    }
149
150    /// The GCRF→ITRF rotation as row-major matrix rows at propagation time `t` seconds — the form a
151    /// force model's `BodyOriented` closure consumes, without the caller reaching through
152    /// [`Rotation::matrix`].
153    #[must_use]
154    pub fn rotation_rows(&self, t: f64) -> [[f64; 3]; 3] {
155        self.rotation(t).matrix().rows
156    }
157
158    /// The full GCRF→ITRF transform (rotation and angular velocity) at propagation time `t` seconds.
159    #[must_use]
160    pub fn transform(&self, t: f64) -> Transform<Gcrf, Itrf> {
161        let node = self.interpolate(t);
162        let ut1 = Epoch::<Ut1>::from_ns_since_j2000(
163            self.epoch_ut1.ns_since_j2000() + (t * 1e9).round() as i128,
164        );
165        let q = gcrf_to_cirs(
166            node.x + self.dx.radians(),
167            node.y + self.dy.radians(),
168            node.s,
169        );
170        let rotation = tirs_to_itrf(self.xp, self.yp, Angle::from_radians(node.sp))
171            * cirs_to_tirs(era(ut1))
172            * q;
173        let rate = EARTH_ROTATION_RATE * (1.0 - self.lod_seconds / 86_400.0);
174        let omega = q.inverse().matrix() * Vec3::new(0.0, 0.0, rate);
175        Transform::new(rotation, omega)
176    }
177
178    /// Whether propagation time `t` falls inside the precomputed grid.
179    ///
180    /// The grid covers the construction span plus a full stencil of margin at each end. A query
181    /// outside it is still answered — from the series rather than the polynomial — so this reports
182    /// which of the two paths a query would take, not whether it is allowed.
183    #[must_use]
184    pub fn covers(&self, t: f64) -> bool {
185        self.node_index(t).is_some()
186    }
187
188    /// The fractional grid index of propagation time `t`, or `None` if the grid does not reach it.
189    fn node_index(&self, t: f64) -> Option<f64> {
190        let u = (t - self.t_start) / GRID_DT;
191        (0.0..=(self.nodes.len() - 1) as f64)
192            .contains(&u)
193            .then_some(u)
194    }
195
196    /// The four scalars evaluated from the series, for a query the grid does not reach.
197    fn exact_node(&self, t: f64) -> Node {
198        let tt = Epoch::<Tt>::from_ns_since_j2000(
199            self.epoch_tt.ns_since_j2000() + (t * 1e9).round() as i128,
200        );
201        let (x, y) = cip_xy(tt);
202        Node {
203            x,
204            y,
205            s: cio_locator_s(tt, x, y),
206            sp: tio_locator(tt).radians(),
207        }
208    }
209
210    /// Degree-`(STENCIL−1)` Lagrange interpolation of the four scalars at propagation time `t`.
211    ///
212    /// Outside the grid the stencil would have to be clamped and the polynomial evaluated beyond its
213    /// nodes; a degree-7 extrapolation leaves the truth quickly and quietly. Those queries take the
214    /// series instead, so this function interpolates or it is exact — it never extrapolates.
215    fn interpolate(&self, t: f64) -> Node {
216        let Some(u) = self.node_index(t) else {
217            return self.exact_node(t);
218        };
219        let last = self.nodes.len() - STENCIL;
220        let i0 = (u.floor() as isize - STENCIL as isize / 2 + 1).clamp(0, last as isize) as usize;
221        // The promise above, checked rather than trusted. No accuracy test can make it: the CIP is
222        // smooth enough over 600 s that sliding this stencil by four nodes in either direction —
223        // past the point where the query leaves it — moves the position by 1.86 nm to 2.31 nm at
224        // LEO. The property is which nodes were chosen, so it is asserted as an index.
225        debug_assert!(
226            i0 as f64 <= u && u <= (i0 + STENCIL - 1) as f64,
227            "stencil [{i0}, {}] does not contain the query at u = {u}: this is extrapolation",
228            i0 + STENCIL - 1
229        );
230        let xq = u - i0 as f64;
231        let (mut x, mut y, mut s, mut sp) = (0.0, 0.0, 0.0, 0.0);
232        for j in 0..STENCIL {
233            let mut l = 1.0;
234            for k in 0..STENCIL {
235                if k != j {
236                    l *= (xq - k as f64) / (j as f64 - k as f64);
237                }
238            }
239            let n = self.nodes[i0 + j];
240            x += l * n.x;
241            y += l * n.y;
242            s += l * n.s;
243            sp += l * n.sp;
244        }
245        Node { x, y, s, sp }
246    }
247}
248
249#[cfg(test)]
250mod tests {
251    use super::*;
252    use crate::gcrf_to_itrf;
253    use spacelab_testkit::nan_max;
254
255    #[test]
256    fn cio_interpolation_matches_the_exact_transform() {
257        // A representative recent epoch (TT ns since J2000) and a small UT1−TT offset.
258        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
259        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
260        let xp = Angle::from_arcseconds(0.16);
261        let yp = Angle::from_arcseconds(0.35);
262        let zero = Angle::from_radians(0.0);
263        let span = 6.0 * 3600.0; // 6-hour arc
264
265        let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, xp, yp, zero, zero, 0.0);
266        // A LEO position to turn a rotation-matrix difference into metres.
267        let r = Vec3::new(6_800e3, 1_200e3, 900e3);
268
269        let mut worst = 0.0_f64;
270        for k in 0..=240 {
271            let t = span * f64::from(k) / 240.0;
272            let ut1 = Epoch::<Ut1>::from_ns_since_j2000(
273                epoch_ut1.ns_since_j2000() + (t * 1e9).round() as i128,
274            );
275            let tt = Epoch::<Tt>::from_ns_since_j2000(
276                epoch_tt.ns_since_j2000() + (t * 1e9).round() as i128,
277            );
278            let exact = gcrf_to_itrf(ut1, tt, xp, yp, zero, zero, 0.0)
279                .rotation
280                .matrix()
281                * r;
282            let interp = cio.rotation(t).matrix() * r;
283            worst = nan_max(worst, (exact - interp).norm());
284        }
285        // Interpolation error is far below a micron at LEO — the CIP is polynomial-smooth on this arc.
286        assert!(
287            worst < 1e-6,
288            "CIO interpolation error {worst:.3e} m exceeds 1 µm"
289        );
290    }
291
292    /// A query the grid does not reach is answered from the series, not extrapolated.
293    ///
294    /// This is the test the type exists to survive. Clamping the stencil and evaluating the
295    /// degree-7 polynomial a year past its last node is not a small error — it is metres to
296    /// kilometres, delivered with no diagnostic. Here the uncovered queries must agree with the
297    /// exact chain to the floating-point floor, i.e. be *the same computation*, while an in-span
298    /// query must still take the fast path.
299    #[test]
300    fn a_query_outside_the_grid_is_exact_rather_than_extrapolated() {
301        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
302        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
303        let xp = Angle::from_arcseconds(0.16);
304        let yp = Angle::from_arcseconds(0.35);
305        let zero = Angle::from_radians(0.0);
306        let span = 6.0 * 3600.0;
307
308        let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, xp, yp, zero, zero, 0.0);
309        let r = Vec3::new(6_800e3, 1_200e3, 900e3);
310
311        assert!(cio.covers(0.0) && cio.covers(span), "the arc is covered");
312
313        // One day, one month and one year outside the arc, in both directions.
314        let mut worst = 0.0_f64;
315        for days in [-365.0, -30.0, -1.0, 1.0, 30.0, 365.0] {
316            let t = span + days * 86_400.0;
317            assert!(!cio.covers(t), "t = {t} should be outside the grid");
318            let ut1 = Epoch::<Ut1>::from_ns_since_j2000(
319                epoch_ut1.ns_since_j2000() + (t * 1e9).round() as i128,
320            );
321            let tt = Epoch::<Tt>::from_ns_since_j2000(
322                epoch_tt.ns_since_j2000() + (t * 1e9).round() as i128,
323            );
324            let exact = gcrf_to_itrf(ut1, tt, xp, yp, zero, zero, 0.0)
325                .rotation
326                .matrix()
327                * r;
328            worst = nan_max(worst, (exact - cio.rotation(t).matrix() * r).norm());
329        }
330        // Not "close to" the exact chain: the same arithmetic, so nanometres at LEO at worst.
331        assert!(
332            worst < 1e-9,
333            "an uncovered query differs from the exact chain by {worst:.3e} m — it extrapolated"
334        );
335    }
336
337    #[test]
338    #[allow(clippy::float_cmp)] // rotation_rows is a bit-for-bit copy of rotation().matrix().rows
339    fn rows_and_transform_match_rotation_and_carry_the_earth_rate() {
340        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
341        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
342        let xp = Angle::from_arcseconds(0.16);
343        let yp = Angle::from_arcseconds(0.35);
344        let zero = Angle::from_radians(0.0);
345        let span = 6.0 * 3600.0;
346        let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, xp, yp, zero, zero, 0.0);
347
348        let t = span * 0.37;
349        // rotation_rows is exactly rotation().matrix().rows.
350        let rows = cio.rotation_rows(t);
351        assert_eq!(rows, cio.rotation(t).matrix().rows);
352
353        // transform() carries the same rotation, and |omega| is the Earth rotation rate: a pure
354        // rotation of (0, 0, rate), with lod = 0 here.
355        let tf = cio.transform(t);
356        assert_eq!(tf.rotation.matrix().rows, rows);
357        assert!((tf.omega.norm() - EARTH_ROTATION_RATE).abs() <= 1e-12 * EARTH_ROTATION_RATE);
358
359        // The full transform's rotation matches the exact chain to below a micron at LEO.
360        let r = Vec3::new(6_800e3, 1_200e3, 900e3);
361        let ut1 = Epoch::<Ut1>::from_ns_since_j2000(
362            epoch_ut1.ns_since_j2000() + (t * 1e9).round() as i128,
363        );
364        let tt =
365            Epoch::<Tt>::from_ns_since_j2000(epoch_tt.ns_since_j2000() + (t * 1e9).round() as i128);
366        let exact = gcrf_to_itrf(ut1, tt, xp, yp, zero, zero, 0.0)
367            .rotation
368            .matrix()
369            * r;
370        let got = tf.rotation.matrix() * r;
371        assert!((exact - got).norm() < 1e-6);
372    }
373
374    #[test]
375    fn the_celestial_pole_offsets_reach_the_interpolated_stencil() {
376        // The interpolator writes the `X + dX`, `Y + dY` correction out again for its own nodes.
377        // Every test above passes zeros, where dropping the offsets, flipping their sign and
378        // swapping them are all the same interpolator. The scalar chain is held against pyerfa at
379        // these offsets in `tests/cio_oracle.rs`; here the fast path must reproduce it.
380        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
381        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
382        let xp = Angle::from_arcseconds(0.16);
383        let yp = Angle::from_arcseconds(0.35);
384        let zero = Angle::from_radians(0.0);
385        // Asymmetric in size and opposite in sign, so a swapped pair is a different pole.
386        let dx = Angle::from_arcseconds(12e-3);
387        let dy = Angle::from_arcseconds(-7e-3);
388        let span = 6.0 * 3600.0;
389        let r = Vec3::new(6_800e3, 1_200e3, 900e3);
390
391        let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, xp, yp, dx, dy, 0.0);
392        let mut worst = 0.0_f64;
393        let mut offsets_are_worth = 0.0_f64;
394        for k in 0..=48 {
395            let t = span * f64::from(k) / 48.0;
396            let ns = (t * 1e9).round() as i128;
397            let ut1 = Epoch::<Ut1>::from_ns_since_j2000(epoch_ut1.ns_since_j2000() + ns);
398            let tt = Epoch::<Tt>::from_ns_since_j2000(epoch_tt.ns_since_j2000() + ns);
399            let exact = gcrf_to_itrf(ut1, tt, xp, yp, dx, dy, 0.0).rotation.matrix() * r;
400            let zeroed = gcrf_to_itrf(ut1, tt, xp, yp, zero, zero, 0.0)
401                .rotation
402                .matrix()
403                * r;
404            // `rotation` and `transform` each write the `X + dX`, `Y + dY` correction out for
405            // themselves, so checking one leaves the other free to drift. Both, every sample.
406            worst = nan_max(worst, (exact - cio.rotation(t).matrix() * r).norm());
407            worst = nan_max(
408                worst,
409                (exact - cio.transform(t).rotation.matrix() * r).norm(),
410            );
411            offsets_are_worth = nan_max(offsets_are_worth, (exact - zeroed).norm());
412        }
413        assert!(
414            worst < 1e-6,
415            "interpolated rotation differs from the exact chain by {worst:.3e} m with offsets"
416        );
417        // and that agreement is evidence only because the offsets move the position at all:
418        // centimetres, four orders above the micron just asserted.
419        assert!(
420            offsets_are_worth > 0.01,
421            "the offsets moved the position by {offsets_are_worth:.3e} m — too little for the \
422             agreement above to show they were applied"
423        );
424    }
425
426    #[test]
427    #[allow(clippy::float_cmp)] // exact by construction: Lagrange on its own node
428    fn the_grid_boundary_is_exact_and_every_node_reproduces_the_series() {
429        // `covers` is the whole safety property: inside it a degree-7 polynomial is evaluated, and
430        // one node past the last one that polynomial is an extrapolation. A boundary off by a
431        // single node is invisible to an accuracy test — 600 s of extrapolation on a curve this
432        // smooth is still sub-micron — so the boundary is pinned as an index, not as an error.
433        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
434        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
435        let zero = Angle::from_radians(0.0);
436        let span = 6.0 * 3600.0;
437        let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, zero, zero, zero, zero, 0.0);
438
439        // The grid runs from `t_start` to the last node, both of which are a whole number of
440        // `GRID_DT` steps from the construction span; nothing outside is covered.
441        let t_first = cio.t_start;
442        let t_last = cio.t_start + (cio.nodes.len() - 1) as f64 * GRID_DT;
443        assert!(cio.covers(t_first), "the first node must be covered");
444        assert!(cio.covers(t_last), "the last node must be covered");
445        assert!(
446            !cio.covers(t_last + GRID_DT * 1e-6),
447            "a query past the last node must not be covered — that is extrapolation"
448        );
449        assert!(
450            !cio.covers(t_first - GRID_DT * 1e-6),
451            "a query before the first node must not be covered"
452        );
453        assert!(cio.covers(0.0) && cio.covers(span), "the arc itself");
454
455        // On its own nodes the interpolator is not an approximation. A Lagrange basis evaluated at
456        // node `j` is exactly 1 there and exactly 0 at every other node — the weights are products
457        // of `(xq − k)/(j − k)` at integer `xq`, so one factor is exactly zero or every factor is
458        // exactly one — and the node holds the series value. So an exact-node query must reproduce
459        // the exact chain bit for bit, and does: measured, zero metres at all 53 nodes.
460        //
461        // That is also the only query that resolves *which* nodes the stencil picked. Away from a
462        // node the CIP is smooth enough over 600 s that shifting the stencil by one node changes
463        // the position by less than an ulp — measured, both give 2.0825e-9 m, identical. On a node
464        // a stencil that has slid off it no longer contains it, and interpolation becomes
465        // extrapolation. Sweeping every node also reaches the two at the ends, where the stencil
466        // clamps and an over-long clamp bound indexes past the grid.
467        let r = Vec3::new(6_800e3, 1_200e3, 900e3);
468        for i in 0..cio.nodes.len() {
469            let t = cio.t_start + i as f64 * GRID_DT;
470            let ns = (t * 1e9).round() as i128;
471            let ut1 = Epoch::<Ut1>::from_ns_since_j2000(epoch_ut1.ns_since_j2000() + ns);
472            let tt = Epoch::<Tt>::from_ns_since_j2000(epoch_tt.ns_since_j2000() + ns);
473            let exact = gcrf_to_itrf(ut1, tt, zero, zero, zero, zero, 0.0)
474                .rotation
475                .matrix()
476                * r;
477            let gap = (exact - cio.rotation(t).matrix() * r).norm();
478            assert!(
479                gap == 0.0,
480                "node {i} at t = {t} is off the exact chain by {gap:.3e} m — the stencil that \
481                 interpolated it does not contain it"
482            );
483        }
484    }
485
486    #[test]
487    fn the_interpolated_rate_carries_lod_exactly_as_the_scalar_chain_does() {
488        // `transform` writes `AVE * (1 - LOD/86400)` out for itself. `tests/cio_oracle.rs` pins
489        // that expression against Orekit 13.1.7's bytecode for the two public entry points; this
490        // requires the third to be bit-for-bit the same, which is what makes it inherit the oracle.
491        let epoch_tt = Epoch::<Tt>::from_ns_since_j2000(788_400_000_000_000_000);
492        let epoch_ut1 = Epoch::<Ut1>::from_ns_since_j2000(788_400_000_000_000_000 - 69_000_000_000);
493        let zero = Angle::from_radians(0.0);
494        let span = 6.0 * 3600.0;
495
496        for lod in [0.0, 0.0018, -0.0005, 0.0035] {
497            let cio = CioInterpolator::new(epoch_ut1, epoch_tt, span, zero, zero, zero, zero, lod);
498            let scalar = gcrf_to_itrf(epoch_ut1, epoch_tt, zero, zero, zero, zero, lod)
499                .omega
500                .norm();
501            let interpolated = cio.transform(span * 0.37).omega.norm();
502            assert!(
503                (interpolated - scalar).abs() < 1e-20,
504                "LOD {lod} s: interpolator |ω| = {interpolated:.20e}, scalar = {scalar:.20e}"
505            );
506            // and LOD is not being ignored: 1.8 ms is 1.5e-12 rad/s below the nominal rate.
507            if lod > 0.0 {
508                assert!(
509                    EARTH_ROTATION_RATE - interpolated > 0.5e-12,
510                    "a positive LOD must slow the interpolated rate"
511                );
512            }
513        }
514    }
515}