docs menu

Module Ymir.Frame

Celestial frames.

A frame is a celestial coordinate system: an orientation of three axes. Its orientation R_f is the matrix taking ICRS components to frame f's, v_f = R_f · v_icrs. Frames come in two families. A fixed frame is one whose orientation from ICRS is constant: the catalogue frames, whose directions are as seen from the barycentre of the solar system. A geocentric frame's directions are as seen from the Earth's centre: the GCRS, whose axes are ICRS's, and the frames of date, whose axes follow the Earth's orientation (Earth) and so depend on the instant. Light that reaches the geocentre has been deflected by the Sun and arrives from a direction aberrated by the Earth's motion, so a direction to a source changes between the families by more than a rotation: Direction.convert.

The frames of date are the intermediate frames of the IERS Conventions (2010): each has the CIP as its pole. CIRS, the Celestial Intermediate Reference System, takes the CIO as its origin; TIRS, the Terrestrial Intermediate Reference System, takes the terrestrial origin, so it turns with the Earth; the true equator and equinox of date takes the equinox.

Each frame type has exactly one value, so two values of one type are one frame and a frame mismatch is a type error. A fixed frame's type is an instance of Frame.fixed and a geocentric frame's of Frame.geocentric: Frame.matrix and Direction.rotate take any two fixed frames, and no other. The users of a frame write its type, as in Frame.galactic Direction.t.

Each fixed frame's orientation is its standard's own numbers, rounded once to float64. A conversion between two fixed frames is computed from their two orientations alone, so it depends only on the two frames, never on a path through others.

#type 'f t

The type for celestial frames. Each frame type has exactly one value.

#type !'a fixed

The type of a frame at a constant orientation from ICRS.

#type icrs = [ `Icrs ] fixed

#type fk5_j2000 = [ `Fk5_j2000 ] fixed

#type galactic = [ `Galactic ] fixed

#type ecliptic_j2000 = [ `Ecliptic_j2000 ] fixed

#type supergalactic = [ `Supergalactic ] fixed

#type !'a geocentric

The type of a frame whose directions are as seen from the Earth's centre.

#type gcrs = [ `Gcrs ] geocentric

#type cirs = [ `Cirs ] geocentric

#type true_of_date = [ `True_of_date ] geocentric

#type tirs = [ `Tirs ] geocentric

#val icrs : icrs t

icrs is the International Celestial Reference System.

#val fk5_j2000 : fk5_j2000 t

fk5_j2000 is FK5, mean equator and equinox of J2000.0, oriented at epoch J2000.0: the rotation from ICRS by the vector (−19.9, −9.1, +22.9) mas of Mignard and Froeschlé (2000), 31.7 mas in all.

#val galactic : galactic t

galactic is Galactic coordinates as the Hipparcos Catalogue defines them on ICRS: the north Galactic pole at α = 192.85948°, δ = 27.12825°, and the north celestial pole at l = 122.93192°.

#val ecliptic_j2000 : ecliptic_j2000 t

ecliptic_j2000 is the IAU 2006 mean ecliptic and equinox of J2000.0, on ICRS: the obliquity ε₀ = 84381.406″ applied to the IAU 2006 frame bias at J2000.0.

#val supergalactic : supergalactic t

supergalactic is supergalactic coordinates, defined on galactic: the north supergalactic pole at Galactic (47.37°, +6.32°), the origin at l = 137.37°.

#val gcrs : gcrs t

gcrs is the Geocentric Celestial Reference System: ICRS's axes at the Earth's centre.

#val cirs : cirs t

cirs is the Celestial Intermediate Reference System of date: from GCRS by the IAU 2006/2000A precession-nutation, which takes the pole to the CIP, and the CIO locator s, which places the CIO (IERS Conventions 2010, 5.4.4).

#val true_of_date : true_of_date t

true_of_date is the true equator and equinox of date: from GCRS by the IAU 2006/2000A bias, precession and nutation, the classical, equinox based form of cirs's pole (IERS Conventions 2010, 5.4.4). It is CIRS turned about the CIP by the equation of the origins.

#val tirs : tirs t

tirs is the Terrestrial Intermediate Reference System: CIRS turned about the CIP by the Earth rotation angle (IERS Conventions 2010, 5.4.2), the Earth's frame less polar motion. A direction's longitude in it is minus its Greenwich hour angle.

#val matrix : 'a fixed t -> 'b fixed t -> (float, Nx.float64_elt, Nx.host) Nx.t

matrix a b is M, [3; 3] on the host, with v_b = M · v_a: for quantities that are not directions, such as a velocity (M v) or a covariance (M Σ Mᵀ).

M is R_b · R_aᵀ. matrix a a is the identity, matrix icrs b is R_b and matrix a icrs is R_aᵀ; another pair's entries are each computed with one Float.fma chain, so matrix b a is the exact transpose of matrix a b.

#val matrix_at : 'd Earth.t -> 'a t -> 'b t -> (float, Nx.float64_elt, 'd) Nx.t

matrix_at e a b is M, [...; 3; 3] beside and across e's instants, with v_b = M · v_a at each instant, for any two frames, as matrix is for fixed ones: R_b · R_aᵀ, with GCRS's axes ICRS's. A direction to a source converts by it only within a family (Direction.convert).

For two fixed frames it is matrix's entries. Between the frames of date it is the rotation about the CIP by the difference of their origins' angles, which the series of the precession-nutation give only for the equinox. Its entries from GCRS are within 4e-16 of iauPnm06a's to the true equator and equinox, and within 5e-16 of iauC2i06a's to CIRS. Each matrix is a rotation within 1e-15 per entry, and matrix_at e b a is matrix_at e a b transposed within 2e-16.

#val name : 'f t -> string

name f is f's canonical name: "icrs", "fk5_j2000", "galactic", "ecliptic_j2000", "supergalactic", "gcrs", "cirs", "true_of_date", "tirs". It is the frame's identity in keys, text and files.

#val pp : Stdlib.Format.formatter -> 'f t -> unit

pp prints name.

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

walk c f reports name as one case at c's path and is f. A frame holds no tensors.