Skip to main content

spacelab_frames/
teme.rs

1//! TEME to ITRF: the transform SGP4 forces on us, and nobody standardises.
2//!
3//! What checks it: `derivations/frame_transform.mac` proves the algebra — that `rot3` fixes `ẑ`, so
4//! the single `ω·ẑ` this module attaches to a two-rotation chain is exact for the sidereal half —
5//! and `derivations/polar_motion_rate.py` measures the half it is not, against the whole IERS
6//! series. See [`teme_to_itrf`]'s "What is neglected".
7
8use spacelab_core::{Angle, Epoch, Mat3, Tt, Ut1, Vec3};
9use spacelab_fa::gmst82;
10
11use crate::polar_motion::{pef_to_itrf, tio_locator};
12use crate::rotation::{Itrf, Pef, Rotation, Teme, Transform};
13
14/// Nominal mean angular velocity of the Earth, rad/s.
15///
16/// The IERS conventional value. The instantaneous rate differs by the excess length
17/// of day: `ω = ω₀·(1 − LOD/86400)`, and LOD reaches a couple of milliseconds, so
18/// the correction is order `2×10⁻⁸` relative — a few micrometres per second at the
19/// equator. [`teme_to_itrf`] applies it from the `lod_seconds` the caller supplies;
20/// passing `0` recovers the nominal rate.
21pub const EARTH_ROTATION_RATE: f64 = 7.292_115_146_706_979e-5;
22
23/// Sidereal rotation from TEME into the pseudo-Earth-fixed frame.
24///
25/// A single rotation about the pole, by Greenwich Mean Sidereal Time. TEME is not
26/// defined by any standards body — it is whatever SGP4 emits — and this is the
27/// transform the literature attaches to it.
28#[must_use]
29pub fn teme_to_pef(ut1: Epoch<Ut1>) -> Rotation<Teme, Pef> {
30    Rotation::from_matrix(Mat3::rot3(gmst82(ut1).radians()))
31}
32
33/// The full TEME to ITRF transform, rotation and angular velocity together.
34///
35/// ```text
36/// TEME ──GMST82──▶ PEF ──polar motion──▶ ITRF
37/// ```
38///
39/// The angular velocity is `ω·ẑ` expressed in TEME. Because the first rotation is
40/// about `ẑ`, that vector is carried unchanged into PEF, which is what makes the
41/// velocity transform in [`Transform::state`] correct there.
42///
43/// The rate is the instantaneous one, `ω₀·(1 − LOD/86400)`, from the excess length of
44/// day `lod_seconds`. Pass `0` for the nominal rate.
45///
46/// # What is neglected
47///
48/// The rate of polar motion, and that is the *only* kinematic term dropped:
49/// `derivations/frame_transform.mac` proves `rot3` fixes `ẑ`, so the sidereal axis
50/// survives the first rotation unchanged and `ω·ẑ` in TEME is exact for it. What is
51/// left over is the second rotation's own rate.
52///
53/// Its size is measured against the IERS series rather than inferred from the
54/// wobble's amplitude — `derivations/polar_motion_rate.py`, 19 976 daily rows over
55/// 54.7 years: the pole's angular rate is **1.3×10⁻¹³ rad/s** in the median and
56/// **3.1×10⁻¹³** at its worst, so **2 µm/s** at the equator against the sidereal
57/// term's 465 m/s. `ω` is 2.3×10⁸ times the worst of it. The wobble itself is
58/// 0.57 arcsec peak to peak with a secular drift of 0.003 arcsec a year, and it is
59/// the 433-day Chandler beat that keeps the *rate* this small. Vallado's reduction
60/// neglects it too.
61#[must_use]
62pub fn teme_to_itrf(
63    ut1: Epoch<Ut1>,
64    tt: Epoch<Tt>,
65    xp: Angle,
66    yp: Angle,
67    lod_seconds: f64,
68) -> Transform<Teme, Itrf> {
69    let sp = tio_locator(tt);
70    let rotation: Rotation<Teme, Itrf> = pef_to_itrf(xp, yp, sp) * teme_to_pef(ut1);
71    // LOD is the day's excess over 86400 SI seconds, so that is the exact denominator.
72    let omega = EARTH_ROTATION_RATE * (1.0 - lod_seconds / 86_400.0);
73    Transform::new(rotation, Vec3::new(0.0, 0.0, omega))
74}
75
76/// Earth orientation at one epoch: everything [`teme_to_itrf`] needs.
77#[derive(Debug, Clone, Copy, PartialEq)]
78pub struct Orientation {
79    /// Universal time, for sidereal rotation.
80    pub ut1: Epoch<Ut1>,
81    /// Terrestrial time, for the TIO locator.
82    pub tt: Epoch<Tt>,
83    /// Pole position along the IERS meridian.
84    pub xp: Angle,
85    /// Pole position, ninety degrees west.
86    pub yp: Angle,
87    /// Excess length of day, seconds, for the instantaneous rotation rate.
88    pub lod_seconds: f64,
89}
90
91/// Build a transform for each epoch, writing into a caller-provided slice.
92///
93/// # Why this signature
94///
95/// The frame chain is a function of the epoch alone — not of any satellite. In a
96/// coverage run over 10⁴ objects and 10⁵ epochs it must be evaluated 10⁵ times,
97/// not 10⁹. Hoisting it into a slice, once, wins four orders of magnitude before a
98/// single thread or SIMD lane is considered, and no amount of GPU offload would
99/// have recovered them.
100///
101/// Writing into `&mut [Transform<..>]` rather than returning a `Vec` keeps the
102/// allocation with the caller and lets Rust's non-aliasing guarantee stand in for
103/// C's `restrict`. When a parallel backend arrives it will split this slice; the
104/// kernel does not change.
105///
106/// # Panics
107///
108/// If `out` is shorter than `epochs`.
109pub fn teme_to_itrf_into(epochs: &[Orientation], out: &mut [Transform<Teme, Itrf>]) {
110    assert!(
111        out.len() >= epochs.len(),
112        "output slice holds {} of {} epochs",
113        out.len(),
114        epochs.len()
115    );
116    for (o, slot) in epochs.iter().zip(out.iter_mut()) {
117        *slot = teme_to_itrf(o.ut1, o.tt, o.xp, o.yp, o.lod_seconds);
118    }
119}