docs menu

Module Ymir.Earth

The Earth's orientation and motion.

The Earth's orientation at an instant is how its axes stand among the stars: the precession-nutation of its axis, which moves the celestial pole and the equator, and its rotation about that axis. Ymir holds the IAU 2006/2000A model the IERS Conventions (2010) give in chapter 5: the IAU 2006 precession (Capitaine et al. 2003; Hilton et al. 2006) in the four Fukushima-Williams angles, and the IAU 2000A nutation (Mathews et al. 2002), 1365 terms, with its IAU 2006 adjustments. The IERS states the model at the 0.2 mas level. It leaves out the free core nutation and the celestial pole offsets the IERS observes, together a few tenths of a mas, and polar motion: the pole is the CIP, the Celestial Intermediate Pole, as the model places it.

The rotation is the Earth rotation angle (ERA), the angle about the CIP from the CIO, the Celestial Intermediate Origin, to the terrestrial origin, a linear function of UT1, the time of the Earth's rotation. UT1 is measured: the IERS publishes UT1 − UTC, within 0.9 s, in its bulletins, and ΔT = TT − UT1 for past instants. An error of 1 s in UT1 turns the Earth by 15″, so an orientation takes one of the two from its caller (Earth.of_utc, Earth.of_tt).

A t holds a batch of instants as TT and UT1. Its functions work on each instant alone and carry their derivative in the seconds and the offset. Frame.matrix_at and Direction.convert take an orientation to place the geocentric frames.

The Earth's ephemeris, its position and velocity about the Sun and the barycentre of the solar system, is the IAU SOFA library's analytic model iauEpv00, a simplified VSOP2000 (Moisson and Bretagnon 2001) of 1951 terms. SOFA states it against JPL's DE405 from 1900 to 2100: the barycentric position within 4.6 km rms and 13.4 km at most, and the velocity within 1.4 mm/s rms and 4.9 mm/s at most, which bounds the aberration it gives at 5 µas. By 1800 and 2200 the position errors double, by 1500 and 2500 they grow tenfold. Positions and velocities are [...; 3] on ICRS's axes, in au and au/d of TDB.

A bound a function states against the IAU SOFA library is against its functions as ERFA 2.0.1 gives them, at instants from 1600 to 2400.

The Greenwich hour angle of a star at a UTC timestamp, with UT1 − UTC from IERS Bulletin A, is 2π less its longitude in TIRS:

ocaml

let e =
  Earth.of_utc (Time.of_date Time.utc (2025, 3, 20) (21, 0, 0.))
    ~dut1:(Quantity.v Unit.second (Nx.scalar Nx.float64 0.0428))

let gha =
  Quantity.map (Nx.rsub_s (2. *. Float.pi))
    (Direction.lon (Direction.convert e Frame.tirs star))

#type 'd t

The type for the Earth's orientation at a batch of instants.

val of_utc : 
  (Time.utc, 'd) Time.t ->
  dut1:(float, Nx.float64_elt, 'd) Nx.t Quantity.t ->
  'd t

of_utc t ~dut1 is the Earth's orientation at the UTC instants t, with UT1 − UTC dut1: UT1 is t's day and seconds since 0h moved by dut1 over days of 86400 s, so a leap second reads as SOFA's iauUtcut1 reads it. Before 1972, when UTC's seconds were not SI seconds, dut1 is read against UTC's clock. iauUtcut1 adds it to the SI seconds since UTC's 0h instead, up to 1.3 ms apart by the day's end. The shapes of t and dut1 broadcast.

Raises Invalid_argument if dut1 is not a time or where it is infinite, as in "Earth.of_utc: dut1 at [2] is infinite".

val of_tt : 
  (Time.tt, 'd) Time.t ->
  delta_t:(float, Nx.float64_elt, 'd) Nx.t Quantity.t ->
  'd t

of_tt t ~delta_t is the Earth's orientation at the TT instants t, with ΔT = TT − UT1 delta_t, as of_utc reads its offset. It raises as of_utc does.

#val tt : 'd t -> (Time.tt, 'd) Time.t

tt e is e's instants on TT.

#val era : 'd t -> (float, Nx.float64_elt, 'd) Nx.t Quantity.t

era e is the Earth rotation angle in [0, 2π) radians, 2π (0.7790572732640 + 1.00273781191135448 T_u), T_u the UT1 Julian date less 2451545.0 (IERS Conventions 2010, 5.14), within 4e-15 radians of the exact value.

#val gmst : 'd t -> (float, Nx.float64_elt, 'd) Nx.t Quantity.t

gmst e is the IAU 2006 Greenwich mean sidereal time in [0, 2π) radians: era plus a polynomial of TT (IERS Conventions 2010, 5.32), within 4e-15 radians of the exact value.

#val gst : 'd t -> (float, Nx.float64_elt, 'd) Nx.t Quantity.t

gst e is the Greenwich apparent sidereal time in [0, 2π) radians, the angle from the true equinox to the terrestrial origin: era less the equation of the origins, the CIO's right ascension of the equinox (IERS Conventions 2010, 5.30). era e − gst e is iauEo06a's within 1e-15 radians.

val heliocentric : 
  (Time.tdb, 'd) Time.t ->
  (float, Nx.float64_elt, 'd) Nx.t Quantity.t
  * (float, Nx.float64_elt, 'd) Nx.t Quantity.t

heliocentric t is (p, v), the Earth's position and velocity from the Sun's centre at TDB t, each [...; 3] in au and au/d, within 5e-15 au and 1e-16 au/d of iauEpv00's.

val barycentric : 
  (Time.tdb, 'd) Time.t ->
  (float, Nx.float64_elt, 'd) Nx.t Quantity.t
  * (float, Nx.float64_elt, 'd) Nx.t Quantity.t

barycentric t is (p, v) as heliocentric but from the barycentre of the solar system.

#val walk : ('a, 'b, 'd, 'e) Nx.Ptree.Walk.cursor -> 'd t -> 'e t

walk c e walks e: its TT instants at field "tt" as Time.walk walks them, then UT1's days at "ut1_day" and seconds at "ut1_second", as tensors of a fixed type.

#val ptree : unit -> ('d t, 'd) Nx.Ptree.t

ptree () is Nx.Ptree.v walk, the structure of orientations.