Frames

frames

GCRS

Geocentric Celestial Reference System (GCRS).

An Earth-centered inertial (ECI) frame aligned to the IAU 2000A/2006 precession-nutation models. Use from_itrf / to_itrf for the most common Earth-fixed ↔ inertial conversions, or from_teme / to_teme when working with SGP4 output.

All epoch-dependent methods load IERS Finals 2000A EOP data; call keplime.data.load_finals_2000 before using them. The bias rotation methods (from_j2000, to_j2000) are epoch-independent.

from_itrf(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from ITRF to GCRS.

Loads IERS Finals 2000A EOP data for epoch and applies the full Earth-orientation rotation (precession, nutation, sidereal, polar motion). The Coriolis velocity correction is included when velocity is not None.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in ITRF [km].	required
velocity	Optional[Vector3]	Velocity in ITRF [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the nutation-precession computation.	required

Returns:

Type	Description
Vector3	(position_gcrs, velocity_gcrs) [km; km/s]. Velocity is None
Optional[Vector3]	if the input velocity was None.

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 2000A EOP table does not cover epoch.

from_j2000(position, velocity) staticmethod

Transforms a position (and optionally velocity) from J2000 to GCRS.

Applies the constant IAU 2006 frame-bias rotation (~84 mas). This transform is epoch-independent and requires no EOP data.

Parameters:

Name	Type	Description	Default
position	Vector3	Position in J2000 (EME2000) [km].	required
velocity	Optional[Vector3]	Velocity in J2000 [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_gcrs, velocity_gcrs) [km; km/s].

from_teme(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from TEME to GCRS.

Converts via the ITRF intermediate frame: TEME → ITRF (IAU 1980) → GCRS (IAU 2006/2000A CIO). Loads both Finals 1980 and Finals 2000A EOP tables.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in TEME [km].	required
velocity	Optional[Vector3]	Velocity in TEME [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the GCRS ← ITRF rotation.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_gcrs, velocity_gcrs) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC time-system conversion fails or the IERS Finals 1980/2000A tables do not cover epoch.

to_itrf(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from GCRS to ITRF.

The inverse of from_itrf. Applies the full Earth-orientation rotation at epoch including the Coriolis velocity correction.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in GCRS [km].	required
velocity	Optional[Vector3]	Velocity in GCRS [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the nutation-precession computation.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_itrf, velocity_itrf) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 2000A EOP table does not cover epoch.

to_j2000(position, velocity) staticmethod

Transforms a position (and optionally velocity) from GCRS to J2000.

Applies the transpose of the IAU 2006 frame-bias rotation (~84 mas). This transform is epoch-independent and requires no EOP data.

Parameters:

Name	Type	Description	Default
position	Vector3	Position in GCRS [km].	required
velocity	Optional[Vector3]	Velocity in GCRS [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_j2000, velocity_j2000) [km; km/s].

to_teme(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from GCRS to TEME.

Converts via the ITRF intermediate frame: GCRS → ITRF → TEME (IAU 1980).

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in GCRS [km].	required
velocity	Optional[Vector3]	Velocity in GCRS [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the GCRS → ITRF rotation.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_teme, velocity_teme) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC time-system conversion fails or the IERS Finals 1980/2000A tables do not cover epoch.

ITRF

International Terrestrial Reference Frame (ITRF).

An Earth-fixed frame that includes the polar-motion correction. Provides static methods for converting between ITRF and the Pseudo-Earth-Fixed (PEF) frame. Polar-motion parameters are loaded from IERS Finals 2000A EOP tables; call keplime.data.load_finals_2000 before using epoch-dependent methods.

from_pef(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from PEF to ITRF.

Applies the inverse polar-motion rotation using parameters from IERS Finals 2000A EOP data at epoch. The inverse of to_pef.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector; used to look up polar-motion parameters.	required
position	Vector3	Position in PEF [km].	required
velocity	Optional[Vector3]	Velocity in PEF [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_itrf, velocity_itrf) [km; km/s].

to_pef(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from ITRF to PEF.

Applies the polar-motion rotation (xp, yp) looked up from IERS Finals 2000A EOP data at epoch. The transform is a pure rotation; no Coriolis term is needed because polar-motion rates are negligible.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector; used to look up polar-motion parameters.	required
position	Vector3	Position in ITRF [km].	required
velocity	Optional[Vector3]	Velocity in ITRF [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_pef, velocity_pef) [km; km/s].

J2000

J2000 mean-equatorial inertial frame (EME2000).

Differs from GCRS by the constant IAU 2006 frame-bias rotation (~84 mas). Use when working with legacy SGP4 output or external tools that report state vectors in J2000/EME2000. Epoch-dependent methods require IERS Finals 2000A EOP data; call keplime.data.load_finals_2000 first. The bias rotation methods (from_gcrs, to_gcrs) are epoch-independent.

from_gcrs(position, velocity) staticmethod

Transforms a position (and optionally velocity) from GCRS to J2000.

Applies the constant IAU 2006 frame-bias transpose rotation (~84 mas). This transform is epoch-independent and requires no EOP data.

Parameters:

Name	Type	Description	Default
position	Vector3	Position in GCRS [km].	required
velocity	Optional[Vector3]	Velocity in GCRS [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_j2000, velocity_j2000) [km; km/s].

from_itrf(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from ITRF to J2000.

Converts via GCRS: ITRF → GCRS (IAU 2006 CIO) → J2000 (bias rotation). Requires IERS Finals 2000A EOP data for the epoch.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in ITRF [km].	required
velocity	Optional[Vector3]	Velocity in ITRF [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the nutation-precession computation.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_j2000, velocity_j2000) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 2000A EOP table does not cover epoch.

from_teme(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from TEME to J2000.

Applies the transpose of the IAU 1980 nutation-precession matrix using nutation offsets (Δε, Δψ) from IERS Finals 1980 EOP data for epoch.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch at which to evaluate the rotation.	required
position	Vector3	Position in TEME [km].	required
velocity	Optional[Vector3]	Velocity in TEME [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_j2000, velocity_j2000) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 1980 EOP table does not cover epoch.

to_gcrs(position, velocity) staticmethod

Transforms a position (and optionally velocity) from J2000 to GCRS.

Applies the constant IAU 2006 frame-bias rotation (~84 mas). This transform is epoch-independent and requires no EOP data.

Parameters:

Name	Type	Description	Default
position	Vector3	Position in J2000 [km].	required
velocity	Optional[Vector3]	Velocity in J2000 [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_gcrs, velocity_gcrs) [km; km/s].

to_itrf(epoch, position, velocity, priority) staticmethod

Transforms a position (and optionally velocity) from J2000 to ITRF.

Converts via GCRS: J2000 (bias rotation) → GCRS → ITRF (IAU 2006 CIO). Requires IERS Finals 2000A EOP data for the epoch.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in J2000 [km].	required
velocity	Optional[Vector3]	Velocity in J2000 [km/s], or None for position-only.	required
priority	PerformancePriority	Accuracy/speed trade-off for the nutation-precession computation.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_itrf, velocity_itrf) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 2000A EOP table does not cover epoch.

to_teme(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from J2000 to TEME.

Applies the IAU 1980 nutation-precession rotation using nutation offsets (Δε, Δψ) from IERS Finals 1980 EOP data for epoch.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch at which to evaluate the rotation.	required
position	Vector3	Position in J2000 [km].	required
velocity	Optional[Vector3]	Velocity in J2000 [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_teme, velocity_teme) [km; km/s].

Raises:

Type	Description
ValueError	When the UTC/TT time-system conversion fails or the IERS Finals 1980 EOP table does not cover epoch.

PEF

Pseudo-Earth-Fixed (PEF) frame.

An Earth-fixed frame that excludes the polar-motion correction. PEF is intermediate between TEME (after the sidereal rotation) and ITRF (after adding polar motion). The TEME ↔ PEF rotation is driven purely by GMST using UT1; call keplime.data.load_finals_2000 so that UTC → UT1 conversion succeeds.

from_teme(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from TEME to PEF.

Converts epoch to UT1, builds the GMST (IAU 1982) sidereal rotation, and subtracts the Earth-rotation Coriolis term (ω × r_teme) from the velocity.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in TEME [km].	required
velocity	Optional[Vector3]	Velocity in TEME [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_pef, velocity_pef) [km; km/s].

Raises:

Type	Description
ValueError	If the UT1 time-system conversion fails (EOP data missing).

to_teme(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from PEF to TEME.

Converts epoch to UT1, builds the GMST (IAU 1982) sidereal rotation, and adds the Earth-rotation Coriolis term (ω × r_teme) to the velocity.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in PEF [km].	required
velocity	Optional[Vector3]	Velocity in PEF [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_teme, velocity_teme) [km; km/s].

Raises:

Type	Description
ValueError	If the UT1 time-system conversion fails (EOP data missing).

TEME

True Equator, Mean Equinox (TEME) frame.

The native output frame of the SGP4/SDP4 propagators. Provides static methods for converting between TEME and ITRF or PEF. All epoch-dependent methods require IERS Finals 1980 EOP data; call keplime.data.load_finals_1980 before using them.

Note

These methods may raise ValueError if EOP data is not loaded and the UTC → UT1 conversion cannot be completed.

from_itrf(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from ITRF to TEME.

Loads IERS Finals 1980 EOP data and converts ITRF → PEF (polar motion) → TEME (sidereal rotation).

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in ITRF [km].	required
velocity	Optional[Vector3]	Velocity in ITRF [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_teme, velocity_teme) [km; km/s].

Raises:

Type	Description
ValueError	If the UTC time-system conversion fails (EOP data missing).

from_pef(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from PEF to TEME.

Applies the inverse GMST sidereal rotation derived from epoch (converted to UT1) and adds the Earth-rotation Coriolis term (ω × r_teme) to the velocity.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in PEF [km].	required
velocity	Optional[Vector3]	Velocity in PEF [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_teme, velocity_teme) [km; km/s].

Raises:

Type	Description
ValueError	If the UT1 time-system conversion fails (EOP data missing).

to_itrf(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from TEME to ITRF.

Loads IERS Finals 1980 EOP data and converts TEME → PEF (sidereal rotation) → ITRF (polar motion).

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in TEME [km].	required
velocity	Optional[Vector3]	Velocity in TEME [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_itrf, velocity_itrf) [km; km/s].

Raises:

Type	Description
ValueError	If the UTC time-system conversion fails (EOP data missing).

to_pef(epoch, position, velocity) staticmethod

Transforms a position (and optionally velocity) from TEME to PEF.

Applies the GMST (IAU 1982) sidereal rotation derived from epoch (converted to UT1) and subtracts the Earth-rotation Coriolis term (ω × r_teme) from the velocity.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state vector.	required
position	Vector3	Position in TEME [km].	required
velocity	Optional[Vector3]	Velocity in TEME [km/s], or None for position-only.	required

Returns:

Type	Description
Tuple[Vector3, Optional[Vector3]]	(position_pef, velocity_pef) [km; km/s].

Raises:

Type	Description
ValueError	If the UT1 time-system conversion fails (EOP data missing).

c2ixys(x, y, s)

Celestial-to-intermediate frame matrix from CIP coordinates and CIO locator.

Computes RC2I, the first stage in the full celestial-to-terrestrial transformation::

[TRS] = RPOM * R_3(ERA) * RC2I * [CRS]

Matches SOFA iauC2ixys.

Parameters:

Name	Type	Description	Default
x	float	CIP X coordinate [rad].	required
y	float	CIP Y coordinate [rad].	required
s	float	CIO locator s [rad].	required

Returns:

Type	Description
Matrix3	3×3 celestial-to-intermediate rotation matrix (RC2I).

fw2m(gamb, phib, psi, eps)

Build a rotation matrix from Fukushima-Williams angles.

Implements R = Rx(-eps) * Rz(-psi) * Rx(phib) * Rz(gamb). Reference: SOFA iauFw2m.

Parameters:

Name	Type	Description	Default
gamb	float	F-W angle γ̄ [rad].	required
phib	float	F-W angle φ̄ [rad].	required
psi	float	F-W angle ψ (nutation-augmented when forming PN) [rad].	required
eps	float	F-W angle ε (nutation-augmented when forming PN) [rad].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix.

fw2xy(gamb, phib, psi, eps)

CIP X, Y coordinates from Fukushima-Williams angles.

X and Y are elements [2][0] and [2][1] of the NxPxB matrix. Near J2000.0 they are essentially small angles in radians.

Parameters:

Name	Type	Description	Default
gamb	float	Fukushima-Williams angle γ̄ [rad].	required
phib	float	Fukushima-Williams angle φ̄ [rad].	required
psi	float	Fukushima-Williams angle ψ (including nutation) [rad].	required
eps	float	Fukushima-Williams angle ε (including nutation) [rad].	required

Returns:

Type	Description
Tuple[float, float]	(x, y) — CIP unit-vector coordinates [rad].

get_1976_precession_matrix(mjd_tt)

IAU 1976 precession matrix from J2000.0 to mean-of-date.

Composes the classical Lieske (1977) zeta-z-theta precession angles into Rz(-z) * Ry(theta) * Rz(-zeta).

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
Matrix3	3×3 matrix mapping J2000 positions to mean-of-date positions.

get_1980_nutation_matrix(mjd_tt, delta_epsilon, delta_psi)

IAU 1976/1980 nutation matrix at mjd_tt.

Builds Rx(-(eps0+Δε)) * Rz(-Δψ) * Rx(eps0) where eps0 is the IAU 1976 mean obliquity and (Δψ, Δε) are EOP-corrected nutation angles.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
delta_epsilon	float	EOP correction to obliquity Δε [rad]; pass 0.0 when not applying EOP corrections.	required
delta_psi	float	EOP correction to longitude Δψ [rad]; pass 0.0 when not applying EOP corrections.	required

Returns:

Type	Description
Matrix3	3×3 nutation rotation matrix.

get_2006_mean_obliquity(mjd_tt)

Mean obliquity of the ecliptic, IAU 2006 model.

Reference: Capitaine et al. (2003) / SOFA iauObl06.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
float	Mean obliquity εA [rad].

get_2006_precession_angles(mjd_tt)

Fukushima-Williams precession angles for IAU 2006.

Returns the four F-W angles (γ̄, φ̄, ψ̄, εA) evaluated at mjd_tt. Combine with [fw2m] (plus nutation (Δψ, Δε) if needed) to build the GCRS → true-of-date precession-nutation matrix.

Reference: Capitaine et al. (2003) / SOFA iauPfw06.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
float	(gamb, phib, psib, epsa) — Fukushima-Williams angles
float	(γ̄, φ̄, ψ̄, εA) [rad].

get_2006_precession_matrix(mjd_tt)

IAU 2006 precession matrix (frame bias + precession, no nutation).

Convenience wrapper that composes [get_2006_precession_angles] with [fw2m] to return the GCRS → mean-of-date rotation at mjd_tt.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
Matrix3	3×3 matrix mapping GCRS positions to mean-of-date positions.

get_cio_locator_s06(mjd_tt, x, y)

CIO locator s, IAU 2006.

Positions the Celestial Intermediate Origin on the equator of the CIP.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
x	float	CIP X coordinate [rad].	required
y	float	CIP Y coordinate [rad].	required

Returns:

Type	Description
float	CIO locator s [rad; ~94 µas at J2000.0, growing secularly].

get_era(mjd_ut1)

Earth Rotation Angle (ERA), IAU 2000.

The fundamental Earth rotation quantity in the modern IAU 2000/2006 conventions, replacing the classical sidereal time approach. Matches SOFA iauEra00 exactly.

Parameters:

Name	Type	Description	Default
mjd_ut1	float	Modified Julian Date in UT1 [days].	required

Returns:

Type	Description
float	ERA [rad; 0..2π).

get_gcrs_to_itrs_matrix(mjd_tt, mjd_ut1, xp, yp, dx, dy)

Full GCRS-to-ITRS rotation matrix (CIO-based, IAU 2006/2000A).

Applies the complete transformation::

[TRS] = RPOM * R_3(ERA) * RC2I * [CRS]

Use GCRS.to_itrf when you have a :py:class:~keplime.time.ModifiedJulianDate and want EOP lookup handled automatically.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
mjd_ut1	float	Modified Julian Date in UT1 [days].	required
xp	float	Polar motion x-component [rad].	required
yp	float	Polar motion y-component [rad].	required
dx	float	Celestial pole offset dX [rad].	required
dy	float	Celestial pole offset dY [rad].	required

Returns:

Type	Description
Matrix3	3×3 matrix transforming GCRS positions to ITRS:
Matrix3	pos_itrs = M @ pos_gcrs.

get_gcrs_to_itrs_matrix_with_model(mjd_tt, mjd_ut1, xp, yp, dx, dy, priority)

GCRS-to-ITRS matrix using a selectable nutation model.

Like [get_gcrs_to_itrs_matrix] but allows choosing between nutation models via priority. Results are cached in a thread-local single-slot cache keyed on all seven inputs.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
mjd_ut1	float	Modified Julian Date in UT1 [days].	required
xp	float	Polar motion x-component [rad].	required
yp	float	Polar motion y-component [rad].	required
dx	float	Celestial pole offset dX [rad].	required
dy	float	Celestial pole offset dY [rad].	required
priority	PerformancePriority	Nutation accuracy/speed selector.	required

Returns:

Type	Description
Matrix3	3×3 matrix transforming GCRS positions to ITRS:
Matrix3	pos_itrs = M @ pos_gcrs.

get_gcrs_to_j2000_bias_matrix()

Frame bias matrix from GCRS to J2000.0 mean equator and equinox.

Applies the constant IAU 2000 frame-bias rotation (~84 mas). Epoch-independent; requires no EOP data.

Returns:

Type	Description
Matrix3	3×3 bias rotation matrix mapping GCRS positions to J2000.0 positions.

get_itrs_to_gcrs_matrix(mjd_tt, mjd_ut1, xp, yp, dx, dy)

Full ITRS-to-GCRS rotation matrix (CIO-based, IAU 2006/2000A).

Transpose of [get_gcrs_to_itrs_matrix]. Use GCRS.from_itrf when you have a :py:class:~keplime.time.ModifiedJulianDate and want EOP lookup handled automatically.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
mjd_ut1	float	Modified Julian Date in UT1 [days].	required
xp	float	Polar motion x-component [rad].	required
yp	float	Polar motion y-component [rad].	required
dx	float	Celestial pole offset dX [rad].	required
dy	float	Celestial pole offset dY [rad].	required

Returns:

Type	Description
Matrix3	3×3 matrix transforming ITRS positions to GCRS:
Matrix3	pos_gcrs = M @ pos_itrs.

get_itrs_to_gcrs_matrix_with_model(mjd_tt, mjd_ut1, xp, yp, dx, dy, priority)

ITRS-to-GCRS matrix using a selectable nutation model.

Like [get_itrs_to_gcrs_matrix] but allows choosing between nutation models via priority.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
mjd_ut1	float	Modified Julian Date in UT1 [days].	required
xp	float	Polar motion x-component [rad].	required
yp	float	Polar motion y-component [rad].	required
dx	float	Celestial pole offset dX [rad].	required
dy	float	Celestial pole offset dY [rad].	required
priority	PerformancePriority	Nutation accuracy/speed selector.	required

Returns:

Type	Description
Matrix3	3×3 matrix transforming ITRS positions to GCRS:
Matrix3	pos_gcrs = M @ pos_itrs.

get_j2000_to_gcrs_bias_matrix()

Frame bias matrix from J2000.0 mean equator and equinox to GCRS.

Transpose of [get_gcrs_to_j2000_bias_matrix]. Epoch-independent; requires no EOP data.

Returns:

Type	Description
Matrix3	3×3 bias rotation matrix mapping J2000.0 positions to GCRS positions.

get_j2000_to_teme_matrix(mjd_tt, delta_epsilon, delta_psi)

IAU 1976/1980 transformation matrix from J2000 to TEME.

Composes the IAU 1976 precession matrix and the IAU 1980 nutation matrix (with EOP corrections) and applies the IAU 1994 equation of equinoxes to land in TEME rather than TETE.

Reference: Vallado et al. (2006), "Revisiting Spacetrack Report #3".

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
delta_epsilon	float	EOP correction to obliquity Δε [rad]; pass 0.0 when not applying EOP corrections.	required
delta_psi	float	EOP correction to longitude Δψ [rad]; pass 0.0 when not applying EOP corrections.	required

Returns:

Type	Description
Matrix3	3×3 matrix mapping J2000 positions to TEME positions.

get_nutation(mjd_tt, priority)

Nutation angles (Δψ, Δε) using a selectable model.

Dispatches to IAU 2000B (Speed/Balanced) or IAU 2000A with P03 adjustments (Precision) based on priority.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required
priority	PerformancePriority	Accuracy/speed trade-off selector.	required

Returns:

Type	Description
Tuple[float, float]	(dpsi, deps) — nutation in longitude and obliquity [rad].

get_pef_to_itrf_matrix(polar_x, polar_y)

Polar-motion rotation matrix from PEF to ITRF.

Builds Ry(-xp) * Rx(-yp) from the IERS polar-motion components. Matches the SOFA iauPom00 convention without the small TIO locator s' (< 50 µas/century, folded into the CIO-based path instead).

Parameters:

Name	Type	Description	Default
polar_x	float	Polar-motion x-component xp [rad].	required
polar_y	float	Polar-motion y-component yp [rad].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix mapping PEF positions to ITRF positions.

get_polar_motion_matrix(xp, yp, sp)

Polar motion matrix, IAU 2000.

Transforms vectors from the Celestial Intermediate Pole frame to the Terrestrial Reference System: V(TRS) = RPOM * V(CIP). Computed as Rx(-yp) * Ry(-xp) * Rz(sp), matching SOFA iauPom00.

Parameters:

Name	Type	Description	Default
xp	float	Polar motion x-component [rad].	required
yp	float	Polar motion y-component [rad].	required
sp	float	TIO locator s' [rad].	required

Returns:

Type	Description
Matrix3	3×3 polar motion rotation matrix (RPOM).

get_teme_to_itrf_matrix(polar_x, polar_y, mjd_ut1)

Fused TEME-to-ITRF rotation matrix.

Equal to get_pef_to_itrf_matrix(polar_x, polar_y) times get_teme_to_pef_matrix(mjd_ut1) but computed in closed form.

Parameters:

Name	Type	Description	Default
polar_x	float	Polar-motion x-component xp [rad].	required
polar_y	float	Polar-motion y-component yp [rad].	required
mjd_ut1	float	Modified Julian Date in UT1 [days].	required

Returns:

Type	Description
Matrix3	3×3 matrix mapping TEME positions to ITRF positions.

get_teme_to_pef_matrix(mjd_ut1)

Sidereal rotation matrix from TEME to PEF (IAU 1982 GMST).

Builds Rz(GMST) where GMST is computed from mjd_ut1 using the IAU 1982 expression. Matches Vallado (2006) for SGP4-compatible pipelines.

Parameters:

Name	Type	Description	Default
mjd_ut1	float	Modified Julian Date in UT1 [days].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix mapping TEME positions to PEF positions.

get_tio_locator_sp00(mjd_tt)

TIO locator s', IAU 2000.

Positions the Terrestrial Intermediate Origin on the equator of the CIP. Dominated by a secular drift of approximately −47 µas/century. Reference: SOFA iauSp00.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
float	TIO locator s' [rad; ~0 at J2000.0, secular drift ≈ −47 µas/century].

get_x_rotation_matrix(psi)

Right-handed rotation matrix about the X axis (SOFA convention).

Returns the 3×3 matrix Rx(psi) such that Rx(psi) @ v rotates column vector v through psi radians about the X axis. Matches SOFA iauRx sign conventions.

Parameters:

Name	Type	Description	Default
psi	float	Rotation angle [rad].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix as a row-major nested tuple.

get_xy_06(mjd_tt)

CIP X, Y coordinates, IAU 2006 series.

Returns the X, Y coordinates of the Celestial Intermediate Pole computed from the IAU 2006 Fukushima-Williams precession series.

Parameters:

Name	Type	Description	Default
mjd_tt	float	Modified Julian Date in TT [days].	required

Returns:

Type	Description
Tuple[float, float]	(x, y) — CIP unit-vector coordinates [rad].

get_y_rotation_matrix(theta)

Right-handed rotation matrix about the Y axis (SOFA convention).

Returns the 3×3 matrix Ry(theta) such that Ry(theta) @ v rotates column vector v through theta radians about the Y axis. Matches SOFA iauRy sign conventions.

Parameters:

Name	Type	Description	Default
theta	float	Rotation angle [rad].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix as a row-major nested tuple.

get_z_rotation_matrix(psi)

Right-handed rotation matrix about the Z axis (SOFA convention).

Returns the 3×3 matrix Rz(psi) such that Rz(psi) @ v rotates column vector v through psi radians about the Z axis. Matches SOFA iauRz sign conventions.

Parameters:

Name	Type	Description	Default
psi	float	Rotation angle [rad].	required

Returns:

Type	Description
Matrix3	3×3 rotation matrix as a row-major nested tuple.

ric_rotation_from_inertial(reference_state)

3x3 rotation matrix from an inertial frame to the local RIC frame.

The RIC frame is defined by a reference state's position and velocity:

• R (Radial) -- unit vector along the position vector r / |r|.
• I (In-track) -- orthogonal to R in the orbital plane (C x R).
• C (Cross-track) -- unit vector along the angular momentum (r x v) / |r x v|.

The result R satisfies v_ric = R @ v_inertial and R^-1 = R^T. This rotation follows the static convention used by STK, GMAT, and CDM-format covariance exchanges.

Parameters:

Name	Type	Description	Default
reference_state	CartesianState	State whose position and velocity define the local RIC axes. Must carry a non-None velocity.	required

Returns:

Type	Description
Matrix3	3x3 rotation matrix (row-major nested tuple) mapping inertial
Matrix3	vectors to RIC [dimensionless].

Raises:

Type	Description
ValueError	If reference_state has no velocity, its position magnitude is near zero, or r x v is near zero (radial trajectory).

ric_rotation_from_inertial_6(reference_state)

6x6 block-diagonal rotation mapping an inertial [r, v] covariance to RIC.

Layout: diag(R3, R3) where R3 is the 3x3 result of ric_rotation_from_inertial. Apply via P_ric = T6 @ P_inertial @ T6.T for a covariance matrix, or [r_ric; v_ric] = T6 @ [r_inertial; v_inertial] for a stacked position-velocity vector. This is the static convention -- no frame-rotation-rate cross-term.

Parameters:

Name	Type	Description	Default
reference_state	CartesianState	Reference state defining the RIC axes. See ric_rotation_from_inertial.	required

Returns:

Type	Description
Matrix6	6x6 block-diagonal rotation matrix (row-major nested tuple)
Matrix6	[dimensionless].

Raises:

Type	Description
ValueError	Same conditions as ric_rotation_from_inertial.

ric_rotation_to_inertial_6(reference_state)

6x6 block-diagonal rotation mapping a RIC [r, v] covariance to inertial.

Transpose of ric_rotation_from_inertial_6. Apply via P_inertial = T6 @ P_ric @ T6.T.

Parameters:

Name	Type	Description	Default
reference_state	CartesianState	Reference state defining the RIC axes. See ric_rotation_from_inertial.	required

Returns:

Type	Description
Matrix6	6x6 block-diagonal rotation matrix (row-major nested tuple)
Matrix6	[dimensionless].

Raises:

Type	Description
ValueError	Same conditions as ric_rotation_from_inertial.