Library

T_ECEFs

Union of all Earth-Centered Earth-Fixed (ECEF) frames supported by the IAU-76/FK5 theory.

T_ECEFs_IAU_2006

Union of all Earth-Centered Earth-Fixed (ECEF) frames supported by IAU-2006/2010 theory.

T_ECIs

Union of all Earth-Centered Inertial (ECI) frames supported by the IAU-76/FK5 theory.

T_ECIs_IAU_2006

Union of all Earth-Centered Inertial (ECI) frames supported by IAU-2006/2010 theory.

T_ECIs_IAU_2006_CIO

Union of all Earth-Centered Inertial (ECI) frames supported by CIO-based IAU-2006/2010 theory.

T_ECIs_IAU_2006_Equinox

Union of all Earth-Centered Inertial (ECI) frames supported by Equinox-based IAU-2006/2010 theory.

T_ECIs_IAU_2006_Equinox_of_date

Union of all of date Earth-Centered Inertial (ECI) frames supported by the equinox-based IAU-2006/2010 theory.

T_ECIs_of_date

Union of all of date Earth-Centered Inertial (ECI) frames supported by the IAU-76/FK5 theory.

T_ROT

Union of all supported rotation descriptions.

struct EopIau1980{T}

Store the Earth Orientation Parameters (EOP) for the model IAU 1980.

Each field is a callable interpolation evaluated at the Julian Day [UTC], e.g. eop.x(jd_utc). The interpolation is linear inside the tabulated span and constant outside it. The field Δut1_utc is continuous across the leap seconds. Hence, the X component of the polar motion with respect to the crust at 19 June 2018 [UTC] can be obtained with:

eop.x(datetime2julian(DateTime(2018, 6, 19, 0, 0, 0)))

Fields

• x::T: X component of the polar motion with respect to the crust [arcsec].
• y::T: Y component of the polar motion with respect to the crust [arcsec].
• Δut1_utc::T: Irregularities of the rotation angle, i.e. the difference UT1-UTC [s].
• lod::T: Length of day offset [ms].
• δΔψ::T: Celestial pole offset in longitude referred to the model IAU 1980 [mas].
• δΔϵ::T: Celestial pole offset in obliquity referred to the model IAU 1980 [mas].
• x_error::T: Error in x [arcsec].
• y_error::T: Error in y [arcsec].
• Δut1_utc_error::T: Error in Δut1_utc [s].
• lod_error::T: Error in lod [ms].
• δΔψ_error::T: Error in δΔψ [mas].
• δΔϵ_error::T: Error in δΔϵ [mas].

struct EopIau2000A{T}

Store the Earth Orientation Parameters (EOP) for the model IAU 2000A.

Each field is a callable interpolation evaluated at the Julian Day [UTC], e.g. eop.x(jd_utc). The interpolation is linear inside the tabulated span and constant outside it. The field Δut1_utc is continuous across the leap seconds. Hence, the X component of the polar motion with respect to the crust at 19 June 2018 [UTC] can be obtained with:

eop.x(datetime2julian(DateTime(2018, 6, 19, 0, 0, 0)))

Fields

• x::T: X component of the polar motion with respect to the crust [arcsec].
• y::T: Y component of the polar motion with respect to the crust [arcsec].
• Δut1_utc::T: Irregularities of the rotation angle, i.e. the difference UT1-UTC [s].
• lod::T: Length of day offset [ms].
• δx::T: X component of the celestial pole offset referred to the model IAU 2000A [mas].
• δy::T: Y component of the celestial pole offset referred to the model IAU 2000A [mas].
• x_error::T: Error in x [arcsec].
• y_error::T: Error in y [arcsec].
• Δut1_utc_error::T: Error in Δut1_utc [s].
• lod_error::T: Error in lod [ms].
• δx_error::T: Error in δx [mas].
• δy_error::T: Error in δy [mas].

struct EopInterpolation{T, I, V <: AbstractVector{T}} <: DataInterpolations.AbstractInterpolation{T}

Linear interpolation of one EOP field indexed by the Julian Day [UTC], constant outside the tabulated span. When leap_safe is true, the wrapped interpolation holds UT1-TAI [s], which is continuous across the leap seconds, and the UTC offset is restored when the interpolation is evaluated. The inner constructor infers the type parameter T from the element type of values.

Only the evaluation is supported. DataInterpolations.derivative and DataInterpolations.integral are not implemented for this type. Unknown properties are forwarded to interpolation, so that t and u behave as in DataInterpolations.jl, u being the tabulated values of the field.

Fields

• interpolation::I: Wrapped DataInterpolations.jl interpolation.
• values::V: Tabulated values of the field, exposed as the property u [same unit as the field].
• leap_safe::Bool: Whether interpolation holds UT1-TAI instead of UT1-UTC.

(itp::EopInterpolation{T})(JD::Number) -> Number

Evaluate the EOP interpolation itp at the Julian Day JD [UTC] and return the value of the field [same unit as the field]. The value is constant outside the tabulated span and, for leap-safe interpolations, the UTC leap-second offset is restored at JD.

struct Iau2006Series{T}

Store the pre-processed form of one of the IAU-2006 series tables, holding the terms in the layout consumed by _iau2006_sum.

The IERS tables are transcribed in constants/*.jl with one term per row and seventeen columns: a running term index, the sine and cosine amplitudes, and the fourteen multipliers of the fundamental arguments (five luni-solar followed by nine planetary). This structure stores the same data with the term index dropped and the terms split by whether they involve the planetary arguments.

Fields

• luni_solar::Matrix{T}: Terms whose nine planetary multipliers are all zero, one term per column, with rows As, Ac, and the five luni-solar multipliers.
• mixed::Matrix{T}: The remaining terms, one term per column, with rows As, Ac, and all fourteen multipliers.

Base.getproperty(itp::EopInterpolation, name::Symbol) -> Any

Return the property name of the EOP interpolation itp. The property u returns the tabulated values, the fields are returned directly, and any other property is forwarded to the wrapped interpolation.

Base.propertynames(itp::EopInterpolation, private::Bool = false) -> Tuple

Return the property names of the EOP interpolation itp, which are its fields followed by the properties of the wrapped interpolation.

Base.show(io::IO, eop::EopIau1980) -> Nothing

Print the compact type name of the IAU 1980 EOP data eop to io.

Base.show(io::IO, eop::EopIau2000A) -> Nothing

Print the compact type name of the IAU 2000A EOP data eop to io.

Base.show(io::IO, ::MIME"text/plain", eop::EopIau1980) -> Nothing

Print the IAU 1980 EOP data eop to io as a table with the timespan of each field.

Base.show(io::IO, ::MIME"text/plain", eop::EopIau2000A) -> Nothing

Print the IAU 2000A EOP data eop to io as a table with the timespan of each field.

CIRS() -> Val{:CIRS}

Return the tag that selects the Celestial Intermediate Reference System (CIRS) of the IAU-2006/2010 theory in the reference frame transformation functions.

ERS() -> Val{:ERS}

Return the tag that selects the Earth Reference System (ERS) of the equinox-based IAU-2006/2010 theory in the reference frame transformation functions.

GCRF() -> Val{:GCRF}

Return the tag that selects the Geocentric Celestial Reference Frame (GCRF) in the reference frame transformation functions.

ITRF() -> Val{:ITRF}

Return the tag that selects the International Terrestrial Reference Frame (ITRF) in the reference frame transformation functions.

J2000() -> Val{:J2000}

Return the tag that selects the J2000 mean equator and equinox reference frame in the reference frame transformation functions.

MJ2000() -> Val{:MJ2000}

Return the tag that selects the J2000 mean equator and equinox reference frame of the IAU-2006/2010 theory in the reference frame transformation functions.

MOD() -> Val{:MOD}

Return the tag that selects the Mean of Date (MOD) reference frame of the IAU-76/FK5 theory in the reference frame transformation functions.

MOD06() -> Val{:MOD06}

Return the tag that selects the Mean of Date (MOD) reference frame of the IAU-2006/2010 theory in the reference frame transformation functions.

PEF() -> Val{:PEF}

Return the tag that selects the Pseudo-Earth Fixed (PEF) reference frame of the IAU-76/FK5 theory in the reference frame transformation functions.

TEME() -> Val{:TEME}

Return the tag that selects the True Equator Mean Equinox (TEME) reference frame in the reference frame transformation functions.

TIRS() -> Val{:TIRS}

Return the tag that selects the Terrestrial Intermediate Reference System (TIRS) of the IAU-2006/2010 theory in the reference frame transformation functions.

TOD() -> Val{:TOD}

Return the tag that selects the True of Date (TOD) reference frame of the IAU-76/FK5 theory in the reference frame transformation functions.

_create_iers_eop_interpolation(
    knots::AbstractVector{<:Real},
    field::AbstractVector{<:Real};
    kwargs...
) -> EopInterpolation

Create the interpolation of the EOP field [same unit as the field] indexed by the Julian Day knots [UTC], which must be sorted. Missing values, represented by NaN, are allowed only at the end of field, in which case the interpolation is created only up to the last available value. The function throws if the data cannot be interpolated.

Keywords

• leap_safe::Bool: If true, the field is the UT1-UTC difference [s], which is interpolated as UT1-TAI so that it does not jump across the leap seconds. (Default: false)

Extended help

Throws

• ArgumentError: field has no valid value, has a missing value that is not at its end, or the knots up to the last available value contain NaN.

_download_eop(url::String, key::String, filename::String; kwargs...) -> String

Download the EOP file at url into the scratch space key with the name filename, and return the path of the cached file. The file is downloaded only when it is missing, when its timestamp is older than 7 days or cannot be read, or when the download is forced.

Keywords

• force_download::Bool: If true, download the file even when a current cached file exists. (Default: false)

_earth_rotation_angle_iau2006(jd_ut1::Number) -> Number

Compute the Earth Rotation Angle (ERA) [rad] at the Julian Day jd_ut1 [UT1] according to the IAU-2006 theory, reduced to the interval [0, 2π).

The ERA is the angle between the Celestial Intermediate Origin (CIO) and the Terrestrial Intermediate Origin (TIO) [1](p. 212). The latter is a reference meridian on Earth located about 100 m away from the Greenwich meridian along the equator of the Celestial Intermediate Pole (CIP).

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, p. 212.

_earth_rotation_rate(
    jd_utc::Number,
    eop::Union{Nothing, EopIau1980, EopIau2000A}
) -> Number

Return the Earth angular speed [rad/s] at the Julian Day jd_utc [UTC], corrected by the length of day of the EOP data eop when it is available.

_equation_of_equinoxes_1982(Ω_m::Number, Δψ_1980::Number, mϵ_1980::Number) -> Number

Compute the complete form of the 1982 equation of the equinoxes [rad].

The equation of the equinoxes is the difference between the Greenwich apparent sidereal time and the Greenwich mean sidereal time. The two complementary terms that depend on the mean longitude of the ascending node of the Moon are the ones introduced in [3].

Arguments

• Ω_m::Number: Mean longitude of the ascending node of the Moon [rad], as returned by _nutation_fk5.
• Δψ_1980::Number: Nutation in longitude [rad], including the IERS EOP correction if the caller applies one.
• mϵ_1980::Number: Mean obliquity of the ecliptic [rad].

Returns

• Number: Equation of the equinoxes [rad].

References

• [3] Gontier, A. M., Capitaine, N (1991). High-Accuracy Equation of Equinoxes and VLBI Astrometric Modelling. Radio Interferometry: Theory, Techniques and Applications, IAU Coll. 131, ASP Conference Series, Vol. 19.

_hill_triad(
    r_eci::AbstractVector{T1},
    v_eci::AbstractVector{T2}
) where {T1 <: Number, T2 <: Number} -> NTuple{3, SVector{3, T}}

Compute the orthonormal triad of the Hill frame given the satellite position r_eci [m] and velocity v_eci [m/s] represented in an Earth-Centered Inertial (ECI) reference frame.

The element type T of the returned vectors is obtained by promoting T1 and T2 to a float. The function throws if r_eci and v_eci do not define an orbital plane.

Returns

• SVector{3, T}: Unit vector [-] along the radial direction (from the Earth's center to the satellite) represented in the ECI frame.
• SVector{3, T}: Unit vector [-] along the along-track direction represented in the ECI frame.
• SVector{3, T}: Unit vector [-] along the orbit angular momentum represented in the ECI frame.

References

• [2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, pp. 163-164.

Extended help

Throws

• ArgumentError: r_eci and v_eci are parallel or at least one of them is zero, so that the orbit angular momentum vanishes and the frame is undefined.

_iau2006_sum(
    coefs::Tuple,
    t_tt::Number,
    M_s::Number,
    M_m::Number,
    u_Mm::Number,
    D_s::Number,
    Ω_m::Number,
    λ_M☿::Number,
    λ_M♀::Number,
    λ_Me::Number,
    λ_M♂::Number,
    λ_M♃::Number,
    λ_M♄::Number,
    λ_M⛢::Number,
    λ_M♆::Number,
    p_λ::Number
) -> Number

Compute a polynomial sum of sinusoidal terms used by the IAU-2006 theory.

Arguments

• coefs::Tuple: Tuple of Iau2006Series, one per power of t_tt, in increasing order of the power, with the amplitudes in [10⁻⁶ arcsec] as in the IERS tables.
• t_tt::Number: Julian centuries since J2000.0 [TT].
• M_s::Number: Mean anomaly of the Sun [rad].
• M_m::Number: Mean anomaly of the Moon [rad].
• u_Mm::Number: Mean argument of latitude of the Moon [rad].
• D_s::Number: Mean elongation of the Moon from the Sun [rad].
• Ω_m::Number: Mean longitude of the ascending node of the Moon [rad].
• λ_M☿::Number: Mean heliocentric longitude of Mercury [rad].
• λ_M♀::Number: Mean heliocentric longitude of Venus [rad].
• λ_Me::Number: Mean heliocentric longitude of the Earth [rad].
• λ_M♂::Number: Mean heliocentric longitude of Mars [rad].
• λ_M♃::Number: Mean heliocentric longitude of Jupiter [rad].
• λ_M♄::Number: Mean heliocentric longitude of Saturn [rad].
• λ_M⛢::Number: Mean heliocentric longitude of Uranus [rad].
• λ_M♆::Number: Mean heliocentric longitude of Neptune [rad].
• p_λ::Number: General accumulated precession in longitude [rad].

Returns

• Number: The value of the polynomial sum [arcsec].

_iers_eop_pole_offset_column(::Type{Eop}) -> Int

Return the column of the first celestial pole offset in the 33-column layout of the IERS EOP file related to the model Eop.

_itp_timespan(itp::EopInterpolation) -> String

Format the knot span of the EOP interpolation itp for display.

_luni_solar_args_iau2006(t_tt::Number) -> NTuple{5, Number}

Compute the fundamental arguments related to the luni-solar effect for the IAU-2006 theory [1](p. 211) given the Julian centuries t_tt since J2000.0 in Terrestrial Time (TT).

This is the implementation of luni_solar_args_iau2006. It takes t_tt instead of the Julian Day so that the callers that already have it, like cio_iau2006 and nutation_eo_iau2006, do not need to compute it again.

Returns

• Number: Mean anomaly of the Sun [rad].
• Number: Mean anomaly of the Moon [rad].
• Number: Mean argument of latitude of the Moon [rad].
• Number: Mean elongation of the Moon from the Sun [rad].
• Number: Mean longitude of the ascending node of the Moon [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

_mean_obliquity_iau2006(t_tt::Number) -> Number

Compute the mean obliquity of the ecliptic [rad] using the equinox-based IAU-2006 theory given the Julian centuries t_tt since J2000.0 in Terrestrial Time (TT).

This is the implementation of mean_obliquity_iau2006. It takes t_tt instead of the Julian Day so that nutation_eo_iau2006, which already has it, does not need to compute it again.

The algorithm was obtained in [3].

References

• [3] Wallace, P. T., Capitaine, N (2006). Precession-nutation procedures consistent with IAU 2006 resolutions. Astronomy & Astrophysics.

_nutation_and_equation_of_equinoxes_fk5(
    jd_tt::Number,
    δΔϵ_1980::Number,
    δΔψ_1980::Number
) -> NTuple{4, Number}

Compute the IAU-76/FK5 nutation at the Julian Day jd_tt [TT], applying the EOP corrections δΔϵ_1980 [rad] and δΔψ_1980 [rad] to the nutation in obliquity and in longitude, together with the 1982 equation of the equinoxes. The nutation series is evaluated only once, which is the expensive part of the rotations between the PEF, TEME, TOD, and MOD frames.

Returns

• Number: The mean obliquity of the ecliptic [rad].
• Number: The corrected nutation in obliquity of the ecliptic [rad].
• Number: The corrected nutation in longitude [rad].
• Number: The equation of the equinoxes [rad].

_nutation_fk5(
    jd_tt::Number,
    n_max::Integer,
    nut_coefs_1980::AbstractMatrix;
    kwargs...
) -> NTuple{4, Number}

Compute the nutation parameters at the Julian Day jd_tt [TT] using the IAU-76/FK5 theory with the first n_max terms of the coefficient table nut_coefs_1980, as in nutation_fk5, also returning the mean longitude of the ascending node of the Moon, which is required by the 1982 equation of the equinoxes.

The function throws if nut_coefs_1980 does not have enough rows or columns, as described in nutation_fk5.

Keywords

• verbose::Val: If Val(true), warn when n_max is outside the supported range and is replaced by the default value of 106. (Default: Val(false))

Returns

• Number: The mean obliquity of the ecliptic [rad].
• Number: The nutation in obliquity of the ecliptic [rad].
• Number: The nutation in longitude [rad].
• Number: The mean longitude of the ascending node of the Moon [rad].

_nutation_fk5_series(
    ::Type{NT},
    coefs::AbstractMatrix,
    n_max::Integer,
    t_tt::Number,
    M_m::Number,
    M_s::Number,
    u_Mm::Number,
    D_s::Number,
    Ω_m::Number
) where {NT} -> NTuple{2, NT}

Accumulate the first n_max terms of the 1980 IAU nutation series and return the nutation in longitude and in obliquity [0.0001"].

Arguments

• ::Type{NT}: Type of the accumulators. The caller must provide it so that it does not depend on which table is passed in coefs.
• coefs::AbstractMatrix: Coefficient table holding one term per column, the rows being an1, an2, an3, an4, an5, Ai, Bi, Ci, and Di (see nutation_fk5 for their units).
• n_max::Integer: Number of terms to accumulate. It must not exceed the number of columns of coefs.
• t_tt::Number: Julian centuries since J2000.0 [TT].
• M_m::Number: Mean anomaly of the Moon [rad].
• M_s::Number: Mean anomaly of the Sun [rad].
• u_Mm::Number: Mean argument of latitude of the Moon [rad].
• D_s::Number: Mean elongation of the Moon from the Sun [rad].
• Ω_m::Number: Mean longitude of the ascending node of the Moon [rad].

Returns

• NT: Nutation in longitude [0.0001"].
• NT: Nutation in obliquity of the ecliptic [0.0001"].

_parse_iers_eop(::Type{Eop}, eop::AbstractMatrix{<:Real}) -> Eop

Parse the IERS EOP matrix eop, read from the file finals.all.csv when Eop is EopIau1980 or from the file finals2000A.all.csv when Eop is EopIau2000A, into the interpolations indexed by the Julian Day [UTC]. Both the 33- and the 37-column layouts of the IERS files are supported, and any other width is rejected.

The interpolation is linear between two points of the grid and constant outside it.

Extended help

Throws

• ArgumentError: The matrix does not have 33 or 37 columns.

_planetary_args_iau2006(t_tt::Number) -> NTuple{9, Number}

Compute the fundamental arguments related to the planetary effects for the IAU-2006 theory [1](p. 211) given the Julian centuries t_tt since J2000.0 in Terrestrial Time (TT).

This is the implementation of planetary_args_iau2006. It takes t_tt instead of the Julian Day so that the callers that already have it, like cio_iau2006 and nutation_eo_iau2006, do not need to compute it again.

Returns

• Number: Mean heliocentric longitude of Mercury [rad].
• Number: Mean heliocentric longitude of Venus [rad].
• Number: Mean heliocentric longitude of the Earth [rad].
• Number: Mean heliocentric longitude of Mars [rad].
• Number: Mean heliocentric longitude of Jupiter [rad].
• Number: Mean heliocentric longitude of Saturn [rad].
• Number: Mean heliocentric longitude of Uranus [rad].
• Number: Mean heliocentric longitude of Neptune [rad].
• Number: General accumulated precession in longitude [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

_read_iers_eop_csv(filename::AbstractString) -> Matrix{Float64}

Read the IERS EOP file filename in CSV format and return its data rows as a Matrix{Float64}, discarding the header. Fields that are empty or textual, such as the Type columns, are returned as NaN, marking them as unavailable. The function throws if the file does not contain a header and at least one data row.

Extended help

Throws

• ArgumentError: The file has fewer than two lines.

_rotate_state_vector(sv::OrbitStateVector, D::DCM) -> OrbitStateVector

Rotate the position, velocity, and acceleration of the orbit state vector sv by the DCM D, keeping the epoch. This function must be used only between frames without a significant relative angular velocity, since no kinematic term is added.

_show_eop(
    io::IO,
    name::String,
    labels::NTuple{6, String},
    itps::NTuple{6, EopInterpolation}
) -> Nothing

Print to io a table titled name with one row per EOP interpolation in itps, labeled by labels, showing the timespan of each field. The styles are rendered only if io supports colors.

_split_iau2006_table(coefs::AbstractMatrix) -> Iau2006Series

Pre-process the raw IAU-2006 series table coefs into an Iau2006Series.

coefs must have 17 rows, i.e. it must be the transposed transcription of an IERS table so that each column holds one term (see Iau2006Series for the row meaning). The function throws otherwise.

Extended help

This is called once per table when the package is loaded, and it addresses two problems with the raw tables:

1. The transcriptions are written as Float64[...]', which yields a lazy Adjoint over a column-major parent. No data is ever reordered, so reading the 17 coefficients of one term touches 16 different cache lines. Indexing here materializes the result, making each term contiguous.
2. In most tables the majority of the terms have all nine planetary multipliers equal to zero (e.g. 650 of the 1306 terms of _IAU_2006_CIP_X0, and every term of _IAU_2006_CIP_X2). Splitting them out lets _iau2006_sum skip nine multiply-adds per such term.

Throws

• ArgumentError: coefs does not have 17 rows.

_sv_inertial_to_rotating(sv::OrbitStateVector, D::DCM, ω::Number) -> OrbitStateVector

Convert the orbit state vector sv, represented in an inertial frame, to the frame reached by the DCM D, which rotates about its Z-axis with angular speed ω [rad/s]. The velocity and the acceleration are corrected by the kinematic terms of the axial rotation.

_sv_rotating_to_inertial(sv::OrbitStateVector, D::DCM, ω::Number) -> OrbitStateVector

Convert the orbit state vector sv, represented in a frame that rotates about its Z-axis with angular speed ω [rad/s], to the inertial frame reached by the DCM D. The velocity and the acceleration are corrected by the kinematic terms of the axial rotation.

cio_iau2006(jd_tt::Number) -> NTuple{3, Number}

Compute the coordinates X and Y of the Celestial Intermediate Pole (CIP) with respect to the Geocentric Celestial Reference Frame (GCRF), and the CIO locator s at the Julian Day jd_tt [Terrestrial Time]. The algorithm is based on the IAU-2006 theory.

The CIO locator s provides the position of the CIO on the Equator of the CIP corresponding to the kinematical definition of the non-rotation origin in the GCRS when the CIP is moving with respect to the GCRS between the reference epoch and the epoch due to precession and nutation [1](p. 214).

Returns

• Number: The coordinate X of the CIP w.r.t. the GCRF [rad].
• Number: The coordinate Y of the CIP w.r.t. the GCRF [rad].
• Number: The CIO locator s [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

compute_δΔϵ_δΔψ(eop_iau2000a::EopIau2000A, JD_UTC::Number) -> Number, Number
compute_δΔϵ_δΔψ(
    eop_iau2000a::EopIau2000A,
    JD_UTC::Number,
    JD_TT::Number
) -> Number, Number

Compute the celestial pole offsets in obliquity (δΔϵ_2000) and in longitude (δΔψ_2000) [mas] given the IERS EOP IAU-2000A data eop_iau2000a at the Julian Day JD_UTC [UTC].

The celestial pole offsets are tabulated against UTC, whereas the precession polynomials are functions of TT. If the caller already computed the Julian Day JD_TT [TT], it can be passed to avoid recomputing it. Otherwise, it is obtained from JD_UTC using jd_utc_to_tt.

The offsets are obtained by converting the celestial pole offsets with respect to the GCRS (δx and δy [mas]), which is what the EOP data provides. The result is required by the equinox-based IAU-2006 theory, whose functions expect it in [rad], so the caller must convert it before use.

The algorithm was obtained from [1] (eq. 5.25) and [2] (DPSIDEPS2000_DXDY2000).

Returns

• Number: Celestial pole offset in obliquity δΔϵ_2000 [mas].
• Number: Celestial pole offset in longitude δΔψ_2000 [mas].

References

• [1] IERS (2010). Transformation between the International Terrestrial Reference System and the Geocentric Celestial Reference System. IERS Technical Note No. 36, Chapter 5.
• [2] ftp://hpiers.obspm.fr/eop-pc/models/uai2000.package

ecef_to_geocentric(r_e::AbstractVector{T}) -> NTuple{3, T}

Convert the vector r_e [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame into geocentric coordinates (geocentric latitude, longitude, and distance from the Earth's center). The function throws if r_e is the origin, where the latitude and the longitude are undefined.

The returned type T is the floating-point promotion of eltype(r_e).

Returns

• T: Geocentric latitude [rad] ∈ [-π / 2, π / 2].
• T: Longitude [rad] ∈ [-π, π].
• T: Distance from the Earth's center [m].

Extended help

Throws

• DomainError: r_e is the null vector, for which the latitude and the longitude are undefined.

ecef_to_geodetic(r_e::AbstractVector; kwargs...) -> NTuple{3, RT}

Convert the vector r_e [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame into geodetic coordinates (geodetic latitude, longitude, and altitude) with respect to the reference ellipsoid. The function throws if r_e is the origin, where the geodetic coordinates are undefined.

The returned type RT is the promotion of eltype(r_e) and the ellipsoid parameter type T.

The algorithm is based on [3].

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

Returns

• RT: Geodetic latitude [rad].
• RT: Longitude [rad].
• RT: Altitude above the reference ellipsoid [m].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA, p. 172.
• [3] mu-blox ag (1999). Datum Transformations of GPS Positions. Application Note.

Extended help

The closed-form estimate of the latitude in [3] is refined with a few bounded Newton steps to keep the accuracy for high-altitude points. Points on the equator and on the polar axis are handled explicitly, and the altitude is computed with the alternative expression suggested in [1] when the point is within 1° of the poles.

Throws

• DomainError: r_e is the null vector, for which the geodetic coordinates are undefined.

ecef_to_ned(r_ecef::AbstractVector{T1}, lat::T2, lon::T3, h::T4; kwargs...) -> SVector{3, T}

Convert the vector r_ecef [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame to the local North-East-Down (NED) reference frame defined at the geodetic latitude lat [rad], longitude lon [rad], and altitude h [m].

The NED frame is centered at the geodetic position and its axes are defined as follows:

• X-axis: Toward the geodetic North;
• Y-axis: Toward the East; and
• Z-axis: Downward, along the inward ellipsoid normal.

The element type T of the returned vector is obtained by promoting T1, T2, T3, and T4 to a float.

See also: ned_to_ecef

Keywords

• translate::Bool: If true, the vector is also translated by the ECEF position of the NED origin, so that the input is treated as a position. If false, only the rotation is applied, so that the input is treated as a free vector. (Default: false)

Returns

• SVector{3, T}: Vector r_ecef represented in the NED reference frame.

References

• [1] Transformations between ECEF and ENU coordinates

Extended help

The rotation is the direct form of angle_to_dcm(lon, -(lat + π / 2), 0, :ZYX), avoiding the general Euler-angle construction. The translation uses the WGS-84 ellipsoid through geodetic_to_ecef.

fetch_iers_eop([data_type]; kwargs...) -> Union{EopIau1980, EopIau2000A}

Download and parse the IERS EOP data related to the model selected by data_type, which can be Val(:IAU1980) for the IAU 1980 model (file finals.all.csv) or Val(:IAU2000A) for the IAU 2000A model (file finals2000A.all.csv). If data_type is omitted, it defaults to Val(:IAU1980).

The file is downloaded from url into a scratch space and reused for 7 days unless force_download is true. The result is an EopIau1980 or an EopIau2000A, depending on data_type, with the interpolations of the EOP fields indexed by the Julian Day [UTC].

See also: read_iers_eop

Keywords

• force_download::Bool: If true, download the file even when a cached file less than 7 days old exists. (Default: false)
• url::String: URL of the EOP file in the CSV format provided by IERS. (Default: the IERS URL of finals.all.csv or finals2000A.all.csv, depending on data_type)

Extended help

Examples

julia> eop = fetch_iers_eop();

julia> eop = fetch_iers_eop(Val(:IAU2000A));

geocentric_to_ecef(geocentric_state::AbstractVector) -> SVector{3, T}

Convert the geocentric coordinates in geocentric_state (geocentric latitude [rad], longitude [rad], and distance from the Earth's center [m], in this order) into a vector [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame.

The element type T is obtained as in the method that receives the coordinates as separate arguments.

geocentric_to_ecef(lat::Number, lon::Number, r::Number) -> SVector{3, T}

Convert the geocentric coordinates (geocentric latitude lat [rad], longitude lon [rad], and distance from the Earth's center r [m]) into a vector [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame.

The element type T is the promotion of the types of lat, lon, and r. If all of them are integers, the result is converted to float.

geocentric_to_geodetic(geocentric_state::AbstractVector; kwargs...) -> NTuple{2, NT}

Compute the geodetic latitude and altitude above the reference ellipsoid from geocentric_state, which contains the geocentric latitude [rad] ∈ (-π / 2, π / 2) and the radius [m], in this order. Notice that the longitude is the same in both geocentric and geodetic coordinates, so it is not part of the state.

The returned type NT is the promotion of the element type of geocentric_state and the ellipsoid parameter T, converted to float.

The algorithm is based on [5].

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

Returns

• NT: Geodetic latitude [rad].
• NT: Altitude above the reference ellipsoid [m].

References

• [5] Borkowski, K. M (1987). Transformation of geocentric to geodetic coordinates without approximations. Astrophysics and Space Science, vol. 139, pp. 1-4.

geocentric_to_geodetic(ϕ_gc::Number, r::Number; kwargs...) -> NTuple{2, NT}

Compute the geodetic latitude and altitude above the reference ellipsoid from the geocentric latitude ϕ_gc [rad] ∈ (-π / 2, π / 2) and radius r [m]. Notice that the longitude is the same in both geocentric and geodetic coordinates.

The returned type NT is the promotion of the types of ϕ_gc, r, and the ellipsoid parameter T, converted to float.

The algorithm is based on [5].

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

Returns

• NT: Geodetic latitude [rad].
• NT: Altitude above the reference ellipsoid [m].

References

• [5] Borkowski, K. M (1987). Transformation of geocentric to geodetic coordinates without approximations. Astrophysics and Space Science, vol. 139, pp. 1-4.

geodetic_to_ecef(geodetic_state::AbstractVector; kwargs...) -> SVector{3, RT}

Convert the geodetic coordinates in geodetic_state (geodetic latitude [rad], longitude [rad], and altitude above the reference ellipsoid [m], in this order) into a vector [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame.

The element type RT is the promotion of the element type of geodetic_state and the ellipsoid parameter T.

The algorithm is based on [3].

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

References

• [3] mu-blox ag (1999). Datum Transformations of GPS Positions. Application Note.

geodetic_to_ecef(lat::Number, lon::Number, h::Number; kwargs...) -> SVector{3, RT}

Convert the geodetic latitude lat [rad], longitude lon [rad], and altitude h [m] above the reference ellipsoid into a vector [m] represented in the Earth-Centered, Earth-Fixed (ECEF) reference frame.

The element type RT is the promotion of the types of lat, lon, h, and the ellipsoid parameter T.

The algorithm is based on [3].

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

References

• [3] mu-blox ag (1999). Datum Transformations of GPS Positions. Application Note.

geodetic_to_geocentric(geodetic_state::AbstractVector; kwargs...) -> NTuple{2, NT}

Compute the geocentric latitude and radius from geodetic_state, which contains the geodetic latitude [rad] ∈ (-π / 2, π / 2) and the altitude above the reference ellipsoid [m], in this order. Notice that the longitude is the same in both geocentric and geodetic coordinates, so it is not part of the state.

The returned type NT is the promotion of the element type of geodetic_state and the ellipsoid parameter T, converted to float.

The algorithm is based on [4] (p. 3).

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

Returns

• NT: Geocentric latitude [rad].
• NT: Distance from the Earth's center [m].

References

• [4] ISO TC 20/SC 14 N (2011). Geomagnetic Reference Models.

geodetic_to_geocentric(ϕ_gd::Number, h::Number; kwargs...) -> NTuple{2, NT}

Compute the geocentric latitude and radius from the geodetic latitude ϕ_gd [rad] ∈ (-π / 2, π / 2) and altitude h [m] above the reference ellipsoid. Notice that the longitude is the same in both geocentric and geodetic coordinates.

The returned type NT is the promotion of the types of ϕ_gd, h, and the ellipsoid parameter T, converted to float.

The algorithm is based on [4] (p. 3).

Keywords

• ellipsoid::Ellipsoid{T}: Reference ellipsoid used in the conversion. (Default: WGS84_ELLIPSOID)

Returns

• NT: Geocentric latitude [rad].
• NT: Distance from the Earth's center [m].

References

• [4] ISO TC 20/SC 14 N (2011). Geomagnetic Reference Models.

get_Δat(JD::Number) -> Number

Get the accumulated leap seconds ΔAT [s] between UTC and the International Atomic Time (TAI) at the Julian Day JD [UTC].

The table of leap seconds is valid from 1972-01-01 [UTC], when UTC started counting integer leap seconds. Earlier epochs return 10 s, which is only an approximation. Epochs after the last tabulated leap second (2017-01-01) return the last value, since future leap seconds cannot be predicted.

jd_tt_to_utc(JD_TT::Number[, ΔAT::Number]) -> Number

Convert the Julian Day JD_TT [TT] (Terrestrial Time) to the Julian Day [UTC] using the accumulated leap seconds ΔAT [s] between UTC and the International Atomic Time (TAI). If ΔAT is not provided, it is obtained from get_Δat at the UTC epoch, which is only an approximation for epochs before 1972-01-01 [UTC].

jd_ut1_to_utc(JD_UT1::Number, ΔUT1::Number) -> Number

Convert the Julian Day JD_UT1 [UT1] to the Julian Day [UTC] using the difference ΔUT1 [s] between UT1 and UTC, which is provided by the IERS EOP data.

jd_ut1_to_utc(JD_UT1::Number, eop::Union{EopIau1980, EopIau2000A}) -> Number

Convert the Julian Day JD_UT1 [UT1] to the Julian Day [UTC] using the difference between UT1 and UTC [s] interpolated from the EOP data eop (see fetch_iers_eop). Since the difference is tabulated against UTC, the inverse is solved iteratively, so the result is consistent with jd_utc_to_ut1.

jd_utc_to_tt(JD_UTC::Number[, ΔAT::Number]) -> Number

Convert the Julian Day JD_UTC [UTC] to the Julian Day [TT] (Terrestrial Time) using the accumulated leap seconds ΔAT [s] between UTC and the International Atomic Time (TAI). If ΔAT is not provided, it is obtained from get_Δat, which is only an approximation for epochs before 1972-01-01 [UTC].

jd_utc_to_ut1(JD_UTC::Number, ΔUT1::Number) -> Number

Convert the Julian Day JD_UTC [UTC] to the Julian Day [UT1] using the difference ΔUT1 [s] between UT1 and UTC, which is provided by the IERS EOP data.

jd_utc_to_ut1(JD_UTC::Number, eop::Union{EopIau1980, EopIau2000A}) -> Number

Convert the Julian Day JD_UTC [UTC] to the Julian Day [UT1] using the difference between UT1 and UTC [s] interpolated at JD_UTC from the EOP data eop (see fetch_iers_eop).

luni_solar_args_iau2006(jd_tt::Number) -> NTuple{5, Number}

Compute the fundamental arguments related to the luni-solar effect for the IAU-2006 theory [1](p. 211) at the Julian Day jd_tt [Terrestrial Time].

Returns

• Number: Mean anomaly of the Sun [rad].
• Number: Mean anomaly of the Moon [rad].
• Number: Mean argument of latitude of the Moon [rad].
• Number: Mean elongation of the Moon from the Sun [rad].
• Number: Mean longitude of the ascending node of the Moon [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

mean_obliquity_iau2006(jd_tt::Number) -> Number

Compute the mean obliquity of the ecliptic [rad] using the equinox-based IAU-2006 theory at the Julian Day jd_tt [Terrestrial Time].

The algorithm was obtained in [3].

References

• [3] Wallace, P. T., Capitaine, N (2006). Precession-nutation procedures consistent with IAU 2006 resolutions. Astronomy & Astrophysics.

ned_to_ecef(r_ned::AbstractVector{T1}, lat::T2, lon::T3, h::T4; kwargs...) -> SVector{3, T}

Convert the vector r_ned [m] represented in the local North-East-Down (NED) reference frame defined at the geodetic latitude lat [rad], longitude lon [rad], and altitude h [m] to the Earth-Centered, Earth-Fixed (ECEF) reference frame.

The NED frame is centered at the geodetic position and its axes are defined as follows:

• X-axis: Toward the geodetic North;
• Y-axis: Toward the East; and
• Z-axis: Downward, along the inward ellipsoid normal.

The element type T of the returned vector is obtained by promoting T1, T2, T3, and T4 to a float.

See also: ecef_to_ned

Keywords

• translate::Bool: If true, the vector is also translated by the ECEF position of the NED origin, so that the input is treated as a position. If false, only the rotation is applied, so that the input is treated as a free vector. (Default: false)

Returns

• SVector{3, T}: Vector r_ned represented in the ECEF reference frame.

References

• [1] Transformations between ECEF and ENU coordinates

Extended help

The rotation is the transpose of the one used in ecef_to_ned. The translation uses the WGS-84 ellipsoid through geodetic_to_ecef.

nutation_eo_iau2006(
    jd_tt::Number,
    δΔϵ_2000::Number = 0,
    δΔΨ_2000::Number = 0
) -> NTuple{4, Number}

Compute the nutation parameters and the Equation of Origins (EO) at the Julian Day jd_tt [TT] using the equinox-based 2006 IAU Theory of Nutation. Notice that one can provide corrections for the nutation in obliquity (δΔϵ_2000) [rad] and in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ).

Returns

• Number: The mean obliquity of the ecliptic [rad].
• Number: The nutation in obliquity of the ecliptic [rad].
• Number: The nutation in longitude [rad].
• Number: The Equation of Origins (EO) [rad].

nutation_fk5(
    jd_tt::Number,
    n_max::Integer = 106,
    nut_coefs_1980::AbstractMatrix = _IAU_1980_NUTATION_COEFFICIENTS;
    kwargs...
) -> NTuple{3, Number}

Compute the nutation parameters at the Julian Day jd_tt [Terrestrial Time] using the 1980 IAU Theory of Nutation. The coefficients are nut_coefs_1980 that must be a matrix in which each line has the following syntax [1](p. 1043):

an1  an2  an3  an4  an5  Ai  Bi  Ci  Di

where the units of Ai and Ci are [0.0001"] and the units of Bi and Di are [0.0001"/JC]. The user can also specify the number of coefficients n_max that will be used when computing the nutation. If n_max is omitted or lies outside the interval [1, 106], it defaults to 106.

The function throws if nut_coefs_1980 does not have enough rows or columns.

Keywords

• verbose::Val: If Val(true), warn when n_max is outside the supported range and is replaced by the default value of 106. (Default: Val(false))

Returns

• Number: The mean obliquity of the ecliptic [rad].
• Number: The nutation in obliquity of the ecliptic [rad].
• Number: The nutation in longitude [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

Extended help

Throws

• ArgumentError: nut_coefs_1980 has fewer rows than the effective number of terms or fewer than nine columns.

orb_eci_to_eci(orb::T, ECIo, ECIf[, jd_utc::Number][, eop]) where {T <: Orbit} -> T
orb_eci_to_eci(
    orb::T,
    ECIo[, jd_utco::Number],
    ECIf[, jd_utcf::Number][, eop]
) where {T <: Orbit} -> T

Convert the orbit representation orb from an Earth-Centered Inertial (ECI) reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frames contain only one of date frame, the first signature is used and the Julian Day jd_utc [UTC] is the epoch of this frame. On the other hand, if the origin and destination frames contain two of date frames¹, e.g. TOD => MOD, the second signature must be used, in which the Julian Day jd_utco [UTC] is the epoch of the origin frame and the Julian Day jd_utcf [UTC] is the epoch of the destination frame. If the epochs are not provided, the algorithm uses the epoch of the orbit representation orb. The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

¹: TEME is an of date frame.

Returns

• T: Orbit representation converted to the ECIf reference frame.

Extended help

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

The orbit is converted through an orbit state vector, whose epoch direction cosine matrix (DCM) includes the polar-motion and precession/nutation orientation. The same epoch DCM is applied to r, v, and a, without Ḋ or D̈ terms. Thus, the time derivatives of the polar motion and precession/nutation orientation, angular acceleration arising from changing length of day (LOD), and the corresponding kinematic terms are omitted. Axial Earth rotation and the associated Coriolis and centrifugal terms are retained where applicable.

Supported ECI Reference Frames

The supported ECI frames for both origin ECIo and destination ECIf are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP Data (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

²: The transformation between GCRF and MJ2000 is a constant rotation matrix called bias. Hence, the date does not modify it. However, this signature was kept to avoid complications in the API.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> orb = KeplerianElements(
    date_to_jd(2025, 1, 1),
    8000e3,
    0.015,
    28.5 |> deg2rad,
    100  |> deg2rad,
    200  |> deg2rad,
    45   |> deg2rad
)
KeplerianElements{Float64, Float64}:
           Epoch :    2.46068e6 (2025-01-01T00:00:00)
 Semi-major axis : 8000.0   km
    Eccentricity :    0.015
     Inclination :   28.5   °
            RAAN :  100.0   °
 Arg. of Perigee :  200.0   °
    True Anomaly :   45.0   °

julia> orb_eci_to_eci(orb, TOD(), J2000())
KeplerianElements{Float64, Float64}:
           Epoch :    2.46068e6 (2025-01-01T00:00:00)
 Semi-major axis : 8000.0    km
    Eccentricity :    0.015
     Inclination :   28.6376 °
            RAAN :   99.6403 °
 Arg. of Perigee :  200.045  °
    True Anomaly :   45.0    °

planetary_args_iau2006(jd_tt::Number) -> NTuple{9, Number}

Compute the fundamental arguments related to the planetary effects for the IAU-2006 theory [1](p. 211) at the Julian Day jd_tt [Terrestrial Time].

Returns

• Number: Mean heliocentric longitude of Mercury [rad].
• Number: Mean heliocentric longitude of Venus [rad].
• Number: Mean heliocentric longitude of the Earth [rad].
• Number: Mean heliocentric longitude of Mars [rad].
• Number: Mean heliocentric longitude of Jupiter [rad].
• Number: Mean heliocentric longitude of Saturn [rad].
• Number: Mean heliocentric longitude of Uranus [rad].
• Number: Mean heliocentric longitude of Neptune [rad].
• Number: General accumulated precession in longitude [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

precession_fk5(jd_tt::Number) -> NTuple{3, Number}

Compute the angles related to the precession movement in the Julian Day jd_tt [Terrestrial Time] using the theory IAU-76/FK5. The angles ζ, Θ, and z are described in [1](p. 226-228).

Returns

• Number: The precession angle ζ [rad].
• Number: The precession angle Θ [rad].
• Number: The precession angle z [rad].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

precession_iau2006(jd_tt::Number) -> NTuple{3, Number}

Compute the precession angles [rad] according to equinox-based IAU-2006 theory at the Julian Day jd_tt [Terrestrial Time].

This algorithm was obtained from [3](p. 49).

Returns

• Number: The IAU-2006 precession angle Ψ_a [rad].
• Number: The IAU-2006 precession angle ω_a [rad].
• Number: The IAU-2006 precession angle χ_a [rad].

References

• [3] IERS (2010). Transformation between the International Terrestrial Reference System and the Geocentric Celestial Reference System. IERS Technical Note No. 36, Chapter 5.

r_cirs_to_gcrf_iau2006([T, ]jd_tt::Number, δx::Number = 0, δy::Number = 0) -> T

Compute the rotation that aligns the Celestial Intermediate Reference System (CIRS) with the Geocentric Celestial Reference Frame (GCRF) at the Julian Day jd_tt [TT] and considering the IERS EOP Data δx [rad] and δy [rad] (see fetch_iers_eop). This algorithm uses the IAU-2006 theory.

The IERS EOP Data δx and δy accounts for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the CIRS frame with the GCRF frame.

r_cirs_to_tirs_iau2006([T, ]jd_ut1::Number) -> T

Compute the rotation that aligns the Celestial Intermediate Reference System (CIRS) with the Terrestrial Intermediate Reference System (TIRS) at the Julian Day jd_ut1 [UT1]. This algorithm uses the IAU-2006 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the CIRS frame with the TIRS frame.

Remarks

The reference frames TIRS and CIRS are separated by a rotation about the Z-axis of the Earth Rotation Angle, which is the angle between the Celestial Intermediate Origin (CIO) and the Terrestrial Intermediate Origin (TIO) [1]. The latter is a reference meridian on Earth that is located about 100m away from Greenwich meridian along the equator of the Celestial Intermediate Pole (CIP) [1].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_ecef_to_ecef([T, ]ECEFo, ECEFf, jd_utc::Number, eop) -> T

Compute the rotation from an Earth-Centered, Earth-Fixed (ECEF) reference frame ECEFo to another ECEF reference frame ECEFf at the Julian Day jd_utc [UTC]. The rotation description that will be used is given by T, which can be DCM or Quaternion. The algorithm also requires the Earth Orientation Parameters (EOP) eop.

Returns

• T: Rotation entity that aligns the ECEFo reference frame with the ECEFf reference frame at the epoch jd_utc [UTC].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

Supported ECEF Reference Frames

The supported ECEF frames for both origin ECEFo and destination ECEFf are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame (IAU-76/FK5).
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS) (IAU-2006/2010).

Earth Orientation Parameters (EOP)

The conversion between the supported ECEF frames always depends on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A.

Examples

julia> eop_iau1980 = fetch_iers_eop();

julia> r_ecef_to_ecef(PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
  1.0         -6.29476e-13  -4.34677e-7
 -0.0          1.0          -1.44815e-6
  4.34677e-7   1.44815e-6    1.0

julia> r_ecef_to_ecef(Quaternion, PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
  + 1.0 - 7.24073e-7⋅i + 2.17339e-7⋅j + 0.0⋅k

julia> eop_iau2000A = fetch_iers_eop(Val(:IAU2000A));

julia> r_ecef_to_ecef(TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000A)
DCM{Float64}:
  1.0          3.08408e-11  -4.34677e-7
 -3.14703e-11  1.0          -1.44815e-6
  4.34677e-7   1.44815e-6    1.0

julia> r_ecef_to_ecef(Quaternion, TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000A)
Quaternion{Float64}:
  + 1.0 - 7.24073e-7⋅i + 2.17339e-7⋅j + 1.55778e-11⋅k

r_ecef_to_eci([T, ]ECEF, ECI, jd_utc::Number[, eop]) -> T

Compute the rotation from an Earth-Centered, Earth-Fixed (ECEF) reference frame to an Earth-Centered Inertial (ECI) reference frame at the Julian Day jd_utc [UTC]. The rotation description that will be used is given by T, which can be DCM or Quaternion. The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

Returns

• T: Rotation entity that aligns the ECEF reference frame with the ECI reference frame at the epoch jd_utc [UTC].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

Supported ECEF Reference Frames

The ECEF frame is selected by the parameter ECEF. The possible values are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame.
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS).

Supported ECI Reference Frames

The ECI frame is selected by the parameter ECI. The possible values are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, UTC will be assumed equal to UT1 to compute the Greenwich Mean Sidereal Time. This is an approximation, but should be sufficiently accurate for some applications. Notice that, if EOP data are provided, UT1 will be accurately computed.

²: In this case, the terms that account for the free core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> r_ecef_to_eci(DCM, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33509e-5
 -0.000797312   0.00106478   0.999999

julia> r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33509e-5
 -0.000797312   0.00106478   0.999999

julia> r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
 -0.619271      0.785176    -0.00133066
 -0.785177     -0.619272     3.45854e-5
 -0.000796885   0.00106622   0.999999

julia> r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267      0.78518     -0.00133066
 -0.78518      -0.619267     3.45854e-5
 -0.000796879   0.00106623   0.999999

julia> r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
  + 0.43631 - 0.000590997⋅i + 0.000305106⋅j + 0.899796⋅k

julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));

julia> r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
DCM{Float64}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33516e-5
 -0.000797311   0.00106478   0.999999

julia> r_ecef_to_eci(TIRS(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
 -0.619271      0.785176    -0.00133066
 -0.785177     -0.619272     3.45884e-5
 -0.000796885   0.00106623   0.999999

julia> r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
Quaternion{Float64}:
  + 0.43631 - 0.000590997⋅i + 0.000305106⋅j + 0.899796⋅k

r_eci_to_ecef([T, ]ECI, ECEF, jd_utc::Number[, eop]) -> T

Compute the rotation from an Earth-Centered Inertial (ECI) reference frame to an Earth-Centered, Earth-Fixed (ECEF) reference frame at the Julian Day jd_utc [UTC]. The rotation description that will be used is given by T, which can be DCM or Quaternion. The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

Returns

• T: Rotation entity that aligns the ECI reference frame with the ECEF reference frame at the epoch jd_utc [UTC].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

Supported ECI Reference Frames

The ECI frame is selected by the parameter ECI. The possible values are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Supported ECEF Reference Frames

The ECEF frame is selected by the parameter ECEF. The possible values are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame.
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, UTC will be assumed equal to UT1 to compute the Greenwich Mean Sidereal Time. This is an approximation but should be sufficiently accurate for some applications. Notice that, if EOP data are provided, UT1 will be accurately computed.

²: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> r_eci_to_ecef(DCM, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267    -0.78518     -0.000797312
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33509e-5   0.999999

julia> r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267    -0.78518     -0.000797312
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33509e-5   0.999999

julia> r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
 -0.619271    -0.785177    -0.000796885
  0.785176    -0.619272     0.00106622
 -0.00133066   3.45854e-5   0.999999

julia> r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
 -0.619267    -0.78518     -0.000796879
  0.78518     -0.619267     0.00106623
 -0.00133066   3.45854e-5   0.999999

julia> r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
  + 0.43631 + 0.000590997⋅i - 0.000305106⋅j - 0.899796⋅k

julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));

julia> r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
DCM{Float64}:
 -0.619267    -0.78518     -0.000797311
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33516e-5   0.999999

julia> r_eci_to_ecef(GCRF(), TIRS(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
 -0.619271    -0.785177    -0.000796885
  0.785176    -0.619272     0.00106623
 -0.00133066   3.45884e-5   0.999999

julia> r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
Quaternion{Float64}:
  + 0.43631 + 0.000590997⋅i - 0.000305106⋅j - 0.899796⋅k

r_eci_to_eci([T, ]ECIo, ECIf, jd_utc::Number[, eop]) -> T
r_eci_to_eci([T, ]ECIo, jd_utco::Number, ECIf, jd_utcf::Number[, eop]) -> T

Compute the rotation from an Earth-Centered Inertial (ECI) reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frames contain only one of date frame, the first signature is used and the Julian Day jd_utc [UTC] is the epoch of this frame. On the other hand, if the origin and destination frames contain two of date frames¹, e.g. TOD => MOD, the second signature must be used in which the Julian Day jd_utco [UTC] is the epoch of the origin frame and the Julian Day jd_utcf [UTC] is the epoch of the destination frame. The rotation description that will be used is given by T, which can be DCM or Quaternion. The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

¹: TEME is an of date frame.

Returns

• T: Rotation that aligns the origin ECI reference frame ECIo with the destination ECI reference frame ECIf.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T.

The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

Supported ECI Reference Frames

The supported ECI frames for both origin ECIo and destination ECIf are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP data (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

²: The transformation between GCRF and MJ2000 is a constant rotation matrix called bias. Hence, the date does not modify it. However, this signature was kept to avoid complications in the API.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> r_eci_to_eci(DCM, GCRF(), J2000(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
  1.0          -4.71326e-12   1.53474e-9
  4.71332e-12   1.0          -3.53979e-9
 -1.53474e-9    3.53979e-9    1.0

julia> r_eci_to_eci(Quaternion, TEME(), GCRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
  + 0.999999 + 1.83013e-5⋅i + 0.000665304⋅j - 0.00151324⋅k

julia> r_eci_to_eci(TOD(), date_to_jd(1986,6,19,21,35,0), TOD(), date_to_jd(1987,5,19,3,0,0), eop_iau1980)
DCM{Float64}:
 1.0          -0.000224088  -9.73787e-5
 0.000224087   1.0          -5.80065e-6
 9.738e-5      5.77883e-6    1.0

julia> r_eci_to_eci(Quaternion, TOD(), JD_J2000, MOD(), JD_J2000, eop_iau1980)
Quaternion{Float64}:
  + 1.0 - 1.40025e-5⋅i + 1.34736e-5⋅j - 3.10785e-5⋅k

julia> r_eci_to_eci(J2000(), TEME(), date_to_jd(1986,6,19,21,35,0))
DCM{Float64}:
  0.999995    0.0030265    0.00133055
 -0.00302645  0.999995    -3.86125e-5
 -0.00133066  3.45854e-5   0.999999

julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));

julia> r_eci_to_eci(CIRS(), GCRF(), date_to_jd(1986,6,19,21,35,0), eop_iau2000a)
DCM{Float64}:
 0.999999     3.88389e-8  -0.00133066
 7.18837e-9   1.0          3.45897e-5
 0.00133066  -3.45897e-5   0.999999

julia> r_eci_to_eci(Quaternion, CIRS(), GCRF(), date_to_jd(1986,6,19,21,35,0), eop_iau2000a)
Quaternion{Float64}:
  + 1.0 + 1.72949e-5⋅i + 0.000665332⋅j + 7.91263e-9⋅k

r_eci_to_hill([T, ]r_eci::AbstractVector, v_eci::AbstractVector) -> T
r_eci_to_hill([T, ]sv::OrbitStateVector) -> T

Compute the rotation from an Earth-Centered Inertial (ECI) reference frame to the Hill frame, also known as RSW or RTN frame, given the satellite position r_eci [m] and velocity v_eci [m/s] represented in the ECI frame. The state can also be provided as the orbit state vector sv, whose position sv.r [m] and velocity sv.v [m/s] must be represented in the ECI frame. The rotation description is selected by T, which can be DCM or Quaternion. If T is omitted, it defaults to DCM.

The Hill frame is centered at the satellite and its axes are defined as follows:

• X-axis (R): Radial direction, from the Earth's center to the satellite;
• Y-axis (S): Along-track direction, perpendicular to the radial direction in the orbital plane and positive toward the direction of motion; and
• Z-axis (W): Cross-track direction, along the orbit angular momentum vector, completing the right-handed frame.

The Y-axis is aligned with the velocity vector only in circular orbits. The function throws if r_eci and v_eci do not define an orbital plane.

See also: r_hill_to_eci, r_eci_to_lvlh

Returns

• T: Rotation that maps a vector represented in the ECI frame to the Hill frame (D_hill_eci or q_hill_eci).

References

• [2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, pp. 163-164.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Throws

• ArgumentError: r_eci and v_eci are parallel or at least one of them is zero, so that the orbit angular momentum vanishes and the cross-track direction is undefined. The frame is ill-conditioned, but not rejected, when the two vectors are nearly parallel.

r_eci_to_lvlh([T, ]r_eci::AbstractVector, v_eci::AbstractVector) -> T
r_eci_to_lvlh([T, ]sv::OrbitStateVector) -> T

Compute the rotation from an Earth-Centered Inertial (ECI) reference frame to the Local Vertical, Local Horizontal (LVLH) frame, given the satellite position r_eci [m] and velocity v_eci [m/s] represented in the ECI frame. The state can also be provided as the orbit state vector sv, whose position sv.r [m] and velocity sv.v [m/s] must be represented in the ECI frame. The rotation description is selected by T, which can be DCM or Quaternion. If T is omitted, it defaults to DCM.

The LVLH frame is centered at the satellite and its axes are defined as follows:

• X-axis: Along-track direction, perpendicular to the radial direction in the orbital plane and positive toward the direction of motion;
• Y-axis: Opposite to the orbit angular momentum vector, completing the right-handed frame; and
• Z-axis: Nadir direction, from the satellite to the Earth's center.

The X-axis is aligned with the velocity vector only in circular orbits. This frame is a permutation of the Hill frame axes: x_lvlh = y_hill, y_lvlh = -z_hill, and z_lvlh = -x_hill. The function throws if r_eci and v_eci do not define an orbital plane.

See also: r_lvlh_to_eci, r_eci_to_hill

Returns

• T: Rotation that maps a vector represented in the ECI frame to the LVLH frame (D_lvlh_eci or q_lvlh_eci).

References

• [2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, pp. 163-164.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Throws

• ArgumentError: r_eci and v_eci are parallel or at least one of them is zero, so that the orbit angular momentum vanishes and the cross-track direction is undefined. The frame is ill-conditioned, but not rejected, when the two vectors are nearly parallel.

r_ers_to_mod_iau2006(
    [T, ]jd_tt::Number,
    δΔϵ_2000::Number = 0,
    δΔΨ_2000::Number = 0
) -> T

Compute the rotation that aligns the Earth Reference System (ERS) with the Mean of Date (MOD) reference frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in obliquity (δΔϵ_2000) and in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the ERS frame with the MOD frame.

r_ers_to_tirs_iau2006([T, ]jd_ut1::Number, jd_tt::Number, δΔΨ_2000::Number = 0) -> T

Compute the rotation that aligns the Earth Reference System (ERS) with the Terrestrial Intermediate Reference System (TIRS) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the ERS frame with the TIRS frame.

Remarks

The reference frames TIRS and ERS are separated by a rotation about the Z-axis of the Greenwich apparent sidereal angle (GAST). This angle is computed using the IAU-2006 theory, which consist of obtaining the Earth Rotation Angle (ERA) and subtracting the result of the Equation of Origins (EO).

r_gcrf_to_cirs_iau2006([T, ]jd_tt::Number, δx::Number = 0, δy::Number = 0) -> T

Compute the rotation that aligns the Geocentric Celestial Reference Frame (GCRF) with the Celestial Intermediate Reference System (CIRS) at the Julian Day jd_tt [TT] and considering the IERS EOP Data δx [rad] and δy [rad] (see fetch_iers_eop). This algorithm uses the IAU-2006 theory.

The IERS EOP Data δx and δy accounts for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the GCRF frame with the CIRS frame.

r_gcrf_to_itrf_fk5(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    x_p::Number,
    y_p::Number,
    δΔϵ_1980::Number = 0,
    δΔψ_1980::Number = 0
) -> T

Compute the rotation that aligns the Geocentric Celestial Reference Frame (GCRF) with the International Terrestrial Reference Frame (ITRF) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time], and considering the IERS EOP Data x_p [rad], y_p [rad], δΔϵ_1980 [rad], and δΔψ_1980 [rad] (see fetch_iers_eop). This algorithm uses the IAU-76/FK5 theory.

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian). δΔϵ_1980 is the correction to the nutation in obliquity. δΔψ_1980 is the correction to the nutation in longitude.

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the GCRF frame with the ITRF frame.

Remarks

The EOP data related to the polar motion (x_p and y_p) is required, since this is the only way available to compute the conversion ITRF <=> PEF (the models are highly imprecise since the motion is still not very well understood [1]). However, the EOP data related to the nutation of the obliquity (δΔϵ_1980) and the nutation of the longitude (δΔψ_1980) can be omitted. In this case, the GCRF frame is what is usually called J2000 reference frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_gcrf_to_mj2000_iau2006([T, ]jd_tt::Number = 0) -> T

Compute the rotation that aligns the Geocentric Celestial Reference Frame (GCRF) with the J2000 mean equatorial frame. This algorithm uses the IAU-2006 theory. Notice that this rotation is just a bias matrix that does not depend on the date. However, this function receives the argument jd_tt [Terrestrial Time] just to keep the API compatibility.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the GCRF frame with the MJ2000 frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_gcrf_to_mod_fk5([T, ]jd_tt::Number) -> T

Compute the rotation that aligns the Geocentric Celestial Reference Frame (GCRF) with the Mean of Date (MOD) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the GCRF frame with the MOD frame.

Remarks

The Geocentric Celestial Reference Frame (GCRF) is rotated into the Mean of Date (MOD) frame considering the IAU 1976 Precession model.

Notice that if the conversion MOD => TOD is performed without considering the EOP corrections, then the GCRF in this rotation is what is usually called the J2000 reference frame.

r_gcrf_to_teme([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the Geocentric Celestial Reference Frame (GCRF) with the True Equator Mean Equinox (TEME) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the GCRF frame with the TEME frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_hill_to_eci([T, ]r_eci::AbstractVector, v_eci::AbstractVector) -> T
r_hill_to_eci([T, ]sv::OrbitStateVector) -> T

Compute the rotation from the Hill frame, also known as RSW or RTN frame to an Earth-Centered Inertial (ECI) reference frame, given the satellite position r_eci [m] and velocity v_eci [m/s] represented in the ECI frame. The state can also be provided as the orbit state vector sv, whose position sv.r [m] and velocity sv.v [m/s] must be represented in the ECI frame. The rotation description is selected by T, which can be DCM or Quaternion. If T is omitted, it defaults to DCM.

The Hill frame is centered at the satellite and its axes are defined as follows:

• X-axis (R): Radial direction, from the Earth's center to the satellite;
• Y-axis (S): Along-track direction, perpendicular to the radial direction in the orbital plane and positive toward the direction of motion; and
• Z-axis (W): Cross-track direction, along the orbit angular momentum vector, completing the right-handed frame.

The Y-axis is aligned with the velocity vector only in circular orbits. The function throws if r_eci and v_eci do not define an orbital plane.

See also: r_eci_to_hill, r_lvlh_to_eci

Returns

• T: Rotation that maps a vector represented in the Hill frame to the ECI frame (D_eci_hill or q_eci_hill).

References

• [2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, pp. 163-164.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Throws

• ArgumentError: r_eci and v_eci are parallel or at least one of them is zero, so that the orbit angular momentum vanishes and the cross-track direction is undefined. The frame is ill-conditioned, but not rejected, when the two vectors are nearly parallel.

r_itrf_to_gcrf_fk5(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    x_p::Number,
    y_p::Number,
    δΔϵ_1980::Number = 0,
    δΔψ_1980::Number = 0
) -> T

Compute the rotation that aligns the International Terrestrial Reference Frame (ITRF) with the Geocentric Celestial Reference Frame (GCRF) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time], and considering the IERS EOP Data x_p [rad], y_p [rad], δΔϵ_1980 [rad], and δΔψ_1980 [rad] (see fetch_iers_eop). This algorithm uses the IAU-76/FK5 theory.

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian). δΔϵ_1980 is the correction to the nutation in obliquity. δΔψ_1980 is the correction to the nutation in longitude.

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the ITRF frame with the GCRF frame.

Remarks

The EOP data related to the polar motion (x_p and y_p) is required, since this is the only way available to compute the conversion ITRF <=> PEF (the models are highly imprecise since the motion is still not very well understood [1]). However, the EOP data related to the nutation of the obliquity (δΔϵ_1980) and the nutation of the longitude (δΔψ_1980) can be omitted. In this case, the GCRF frame is what is usually called J2000 reference frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_itrf_to_pef_fk5([T, ]x_p::Number, y_p::Number) -> T

Compute the rotation that aligns the International Terrestrial Reference Frame (ITRF) with the Pseudo-Earth Fixed (PEF) frame considering the polar motion represented by the angles x_p [rad] and y_p [rad] that are obtained from IERS EOP Data (see fetch_iers_eop).

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the ITRF frame with the PEF frame.

Remarks

The ITRF is defined based on the International Reference Pole (IRP), which is the location of the terrestrial pole agreed by international committees [1]. The Pseudo-Earth Fixed, on the other hand, is defined based on the Earth axis of rotation, or the Celestial Intermediate Pole (CIP). Hence, PEF XY-plane contains the True Equator. Furthermore, since the recovered latitude and longitude are sensitive to the CIP, then it should be computed considering the PEF frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_itrf_to_tirs_iau2006([T, ]jd_tt::Number, x_p::Number, y_p::Number) -> T

Compute the rotation that aligns the International Terrestrial Reference Frame (ITRF) with the Terrestrial Intermediate Reference System (TIRS) at the Julian Day jd_tt [Terrestrial Time] considering the polar motion represented by the angles x_p [rad] and y_p [rad] that are obtained from IERS EOP Data (see fetch_iers_eop).

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the ITRF frame with the TIRS frame.

Remarks

The ITRF is defined based on the International Reference Pole (IRP), which is the location of the terrestrial pole agreed by international committees [1]. The Terrestrial Intermediate Reference Frame (TIRS), on the other hand, is defined based on the Earth axis of rotation, or the Celestial Intermediate Pole (CIP). Hence, TIRS XY-plane contains the True Equator. Furthermore, since the recovered latitude and longitude are sensitive to the CIP, then it should be computed considering the TIRS frame.

The TIRS and PEF (IAU-76/FK5) are virtually the same reference frame, but according to [1] it is convenient to separate the names as the exact formulae differ.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_lvlh_to_eci([T, ]r_eci::AbstractVector, v_eci::AbstractVector) -> T
r_lvlh_to_eci([T, ]sv::OrbitStateVector) -> T

Compute the rotation from the Local Vertical, Local Horizontal (LVLH) frame to an Earth-Centered Inertial (ECI) reference frame, given the satellite position r_eci [m] and velocity v_eci [m/s] represented in the ECI frame. The state can also be provided as the orbit state vector sv, whose position sv.r [m] and velocity sv.v [m/s] must be represented in the ECI frame. The rotation description is selected by T, which can be DCM or Quaternion. If T is omitted, it defaults to DCM.

The LVLH frame is centered at the satellite and its axes are defined as follows:

• X-axis: Along-track direction, perpendicular to the radial direction in the orbital plane and positive toward the direction of motion;
• Y-axis: Opposite to the orbit angular momentum vector, completing the right-handed frame; and
• Z-axis: Nadir direction, from the satellite to the Earth's center.

The X-axis is aligned with the velocity vector only in circular orbits. This frame is a permutation of the Hill frame axes: x_lvlh = y_hill, y_lvlh = -z_hill, and z_lvlh = -x_hill. The function throws if r_eci and v_eci do not define an orbital plane.

See also: r_eci_to_lvlh, r_hill_to_eci

Returns

• T: Rotation that maps a vector represented in the LVLH frame to the ECI frame (D_eci_lvlh or q_eci_lvlh).

References

• [2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, pp. 163-164.

Extended help

Rotation Description

The rotation can be described by Direction Cosine Matrices (DCMs) or Quaternions. This is selected by the parameter T. The possible values are:

• DCM: The rotation will be described by a Direction Cosine Matrix.
• Quaternion: The rotation will be described by a Quaternion.

If no value is specified, it falls back to DCM.

Throws

• ArgumentError: r_eci and v_eci are parallel or at least one of them is zero, so that the orbit angular momentum vanishes and the cross-track direction is undefined. The frame is ill-conditioned, but not rejected, when the two vectors are nearly parallel.

r_mj2000_to_gcrf_iau2006([T, ]jd_tt::Number = 0) -> T

Compute the rotation that aligns the J2000 mean equatorial frame with the Geocentric Celestial Reference Frame (GCRF). This algorithm uses the IAU-2006 theory. Notice that this rotation is just a bias matrix that does not depend on the date. However, this function receives the argument jd_tt [Terrestrial Time] just to keep the API compatibility.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MJ2000 frame with the GCRF frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_mj2000_to_mod_iau2006([T, ]jd_tt::Number) -> T

Compute the rotation that aligns the J2000 mean equatorial frame with the Mean of Date (MOD) reference frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MJ2000 frame with the MOD frame.

Remarks

The J2000 reference frame here is not equal to the previous definition in FK5 theory. It is the reason why it is internally called MJ2000. According to [3]:

The mean equinox of J2000.0 to be considered is not the “rotational dynamical mean equinox of J2000.0” as used in the past, but the “inertial dynamical mean equinox of J2000.0” to which the recent numerical or analytical solutions refer. The latter is associated with the ecliptic in the inertial sense, which is the plane perpendicular to the angular momentum vector of the orbital motion of the Earth-Moon barycenter as computed from the velocity of the barycenter relative to an inertial system. The rotational equinox is associated with the ecliptic in the rotational sense, which is perpendicular to the angular momentum vector computed from the velocity referred to the rotating orbital plane of the Earth-Moon barycenter. (The difference between the two angular momenta is the angular momentum associated with the rotation of the orbital plane.)

References

• [3] IERS (2010). Transformation between the International Terrestrial Reference System and the Geocentric Celestial Reference System. IERS Technical Note No. 36, Chapter 5.

r_mod_to_ers_iau2006(
    [T, ]jd_tt::Number,
    δΔϵ_2000::Number = 0,
    δΔΨ_2000::Number = 0
) -> T

Compute the rotation that aligns the Mean of Date (MOD) reference frame with the Earth Reference System (ERS) at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in obliquity (δΔϵ_2000) and in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the ERS frame.

r_mod_to_gcrf_fk5([T, ]jd_tt::Number) -> T

Compute the rotation that aligns the Mean of Date (MOD) frame with the Geocentric Celestial Reference Frame (GCRF) at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the GCRF frame.

Remarks

The Mean of Date (MOD) frame is rotated into the Geocentric Celestial Reference Frame (GCRF) considering the IAU 1976 Precession model.

Notice that if the conversion TOD => MOD is performed without considering the EOP corrections, then the GCRF obtained by this rotation is what is usually called the J2000 reference frame.

r_mod_to_mj2000_iau2006([T, ]jd_tt::Number) -> T

Compute the rotation that aligns the Mean of Date (MOD) reference frame with the J2000 mean equatorial frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the MJ2000 frame.

Remarks

The J2000 reference frame here is not equal to the previous definition in FK5 theory. It is the reason why it is internally called MJ2000. According to [3]:

The mean equinox of J2000.0 to be considered is not the “rotational dynamical mean equinox of J2000.0” as used in the past, but the “inertial dynamical mean equinox of J2000.0” to which the recent numerical or analytical solutions refer. The latter is associated with the ecliptic in the inertial sense, which is the plane perpendicular to the angular momentum vector of the orbital motion of the Earth-Moon barycenter as computed from the velocity of the barycenter relative to an inertial system. The rotational equinox is associated with the ecliptic in the rotational sense, which is perpendicular to the angular momentum vector computed from the velocity referred to the rotating orbital plane of the Earth-Moon barycenter. (The difference between the two angular momenta is the angular momentum associated with the rotation of the orbital plane.)

References

• [3] IERS (2010). Transformation between the International Terrestrial Reference System and the Geocentric Celestial Reference System. IERS Technical Note No. 36, Chapter 5.

r_mod_to_pef_fk5(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    δΔϵ_1980::Number = 0,
    δΔψ_1980::Number = 0
) -> T

Compute the rotation that aligns the Mean of Date (MOD) reference frame with the Pseudo-Earth Fixed (PEF) frame at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the PEF frame.

r_mod_to_teme([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the Mean of Date (MOD) frame with the True Equator Mean Equinox (TEME) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the TEME frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_mod_to_tirs_iau2006(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    δΔϵ_2000::Number = 0,
    δΔΨ_2000::Number = 0
) -> T

Compute the rotation that aligns the Mean of Date (MOD) reference frame with the Terrestrial Intermediate Reference System (TIRS) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in obliquity (δΔϵ_2000) and in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the TIRS frame.

r_mod_to_tod_fk5([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the Mean of Date (MOD) frame with the True of Date (TOD) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the MOD frame with the TOD frame.

Remarks

The Mean of Date (MOD) frame is rotated into the True of Date (TOD) frame considering the 1980 IAU Theory of Nutation. The IERS EOP corrections must be added if one wants to make the rotation consistent with the Geocentric Celestial Reference Systems (GCRS).

r_pef_to_itrf_fk5([T, ]x_p::Number, y_p::Number) -> T

Compute the rotation that aligns the Pseudo-Earth Fixed (PEF) with the International Terrestrial Reference Frame (ITRF) considering the polar motion represented by the angles x_p [rad] and y_p [rad] that are obtained from IERS EOP Data (see fetch_iers_eop).

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the PEF frame with the ITRF.

Remarks

The ITRF is defined based on the International Reference Pole (IRP), which is the location of the terrestrial pole agreed by international committees [1]. The Pseudo-Earth Fixed, on the other hand, is defined based on the Earth axis of rotation, or the Celestial Intermediate Pole (CIP). Hence, PEF XY-plane contains the True Equator. Furthermore, since the recovered latitude and longitude are sensitive to the CIP, then it should be computed considering the PEF frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_pef_to_mod_fk5(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    δΔϵ_1980::Number = 0,
    δΔψ_1980::Number = 0
) -> T

Compute the rotation that aligns the Pseudo-Earth Fixed (PEF) frame with the Mean of Date (MOD) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the PEF frame with the MOD frame.

r_pef_to_teme([T, ]jd_ut1::Number) -> T

Compute the rotation that aligns the Pseudo-Earth Fixed (PEF) frame with the True Equator Mean Equinox (TEME) frame at the Julian Day jd_ut1 [UT1]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the PEF frame with the TEME frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_pef_to_tod_fk5([T, ]jd_ut1::Number, jd_tt::Number, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the Pseudo-Earth Fixed (PEF) frame with the True of Date (TOD) frame at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide correction for the nutation in longitude (δΔψ_1980) [rad] that is usually obtained from IERS EOP Data (see fetch_iers_eop).

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the PEF frame with the TOD frame.

Remarks

The Pseudo-Earth Fixed (PEF) frame is rotated into the True of Date (TOD) frame considering the 1980 IAU Theory of Nutation. The IERS EOP corrections must be added if one wants to make the rotation consistent with the Geocentric Celestial Reference Systems (GCRS).

r_teme_to_gcrf([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True Equator Mean Equinox (TEME) frame with the Geocentric Celestial Reference Frame (GCRF) at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TEME frame with the GCRF frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_teme_to_mod([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True Equator Mean Equinox (TEME) frame with the Mean of Date (MOD) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TEME frame with the MOD frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_teme_to_pef([T, ]jd_ut1::Number) -> T

Compute the rotation that aligns the True Equator Mean Equinox (TEME) frame with the Pseudo-Earth Fixed (PEF) frame at the Julian Day jd_ut1 [UT1]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TEME frame with the PEF frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_teme_to_tod([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True Equator Mean Equinox (TEME) frame with the True of Date (TOD) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TEME frame with the TOD frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_tirs_to_cirs_iau2006([T, ]jd_ut1::Number) -> T

Compute the rotation that aligns the Terrestrial Intermediate Reference System (TIRS) with the Celestial Intermediate Reference System (CIRS) at the Julian Day jd_ut1 [UT1]. This algorithm uses the IAU-2006 theory.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TIRS frame with the CIRS frame.

Remarks

The reference frames TIRS and CIRS are separated by a rotation about the Z-axis of the Earth Rotation Angle, which is the angle between the Celestial Intermediate Origin (CIO) and the Terrestrial Intermediate Origin (TIO) [1]. The latter is a reference meridian on Earth that is located about 100m away from Greenwich meridian along the equator of the Celestial Intermediate Pole (CIP) [1].

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_tirs_to_ers_iau2006([T, ]jd_ut1::Number, jd_tt::Number, δΔΨ_2000::Number = 0) -> T

Compute the rotation that aligns the Terrestrial Intermediate Reference System (TIRS) with the Earth Reference System (ERS) at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TIRS frame with the ERS frame.

Remarks

The reference frames TIRS and ERS are separated by a rotation about the Z-axis of the Greenwich apparent sidereal angle (GAST). This angle is computed using the IAU-2006 theory, which consist of obtaining the Earth Rotation Angle (ERA) and subtracting the result of the Equation of Origins (EO).

r_tirs_to_itrf_iau2006([T, ]jd_tt::Number, x_p::Number, y_p::Number) -> T

Compute the rotation that aligns the Terrestrial Intermediate Reference System (TIRS) with the International Terrestrial Reference Frame (ITRF) at the Julian Day jd_tt [Terrestrial Time] considering the polar motion represented by the angles x_p [rad] and y_p [rad] that are obtained from IERS EOP Data (see fetch_iers_eop).

x_p is the polar motion displacement about X-axis, which is the IERS Reference Meridian direction (positive south along the 0° longitude meridian). y_p is the polar motion displacement about Y-axis (90°W or 270°E meridian).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TIRS frame with the ITRF frame.

Remarks

The ITRF is defined based on the International Reference Pole (IRP), which is the location of the terrestrial pole agreed by international committees [1]. The Terrestrial Intermediate Reference Frame (TIRS), on the other hand, is defined based on the Earth axis of rotation, or the Celestial Intermediate Pole (CIP). Hence, TIRS XY-plane contains the True Equator. Furthermore, since the recovered latitude and longitude are sensitive to the CIP, then it should be computed considering the TIRS frame.

The TIRS and PEF (IAU-76/FK5) are virtually the same reference frame, but according to [1] it is convenient to separate the names as the exact formulae differ.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

r_tirs_to_mod_iau2006(
    [T, ]jd_ut1::Number,
    jd_tt::Number,
    δΔϵ_2000::Number = 0,
    δΔΨ_2000::Number = 0
) -> T

Compute the rotation that aligns the Terrestrial Intermediate Reference System (TIRS) with the Mean of Date (MOD) reference frame at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-2006 theory.

Notice that one can provide corrections for the nutation in obliquity (δΔϵ_2000) and in longitude (δΔΨ_2000) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop and compute_δΔϵ_δΔψ). These corrections are related to Free Core Nutation (FCN) that models the effect of a liquid Earth core.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TIRS frame with the MOD frame.

r_tod_to_mod_fk5([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True of Date (TOD) frame with the Mean of Date (MOD) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TOD frame with the MOD frame.

Remarks

The True of Date (TOD) frame is rotated into the Mean of Date (MOD) frame considering the 1980 IAU Theory of Nutation. The IERS EOP corrections must be added if one wants to make the rotation consistent with the Geocentric Celestial Reference Systems (GCRS).

r_tod_to_pef_fk5([T, ]jd_ut1::Number, jd_tt::Number, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True of Date (TOD) frame with the Pseudo-Earth Fixed (PEF) frame at the Julian Day jd_ut1 [UT1] and jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory. Notice that one can provide correction for the nutation in longitude (δΔψ_1980) [rad] that is usually obtained from IERS EOP Data (see fetch_iers_eop).

The Julian Day in UT1 is used to compute the Greenwich Mean Sidereal Time (GMST) (see jd_to_gmst), whereas the Julian Day in Terrestrial Time is used to compute the nutation in the longitude. Notice that the Julian Day in UT1 and in Terrestrial Time must be equivalent, i.e. must be related to the same instant. The consistency between jd_ut1 and jd_tt is not verified.

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TOD frame with the PEF frame.

Remarks

The True of Date (TOD) frame is rotated into the Pseudo-Earth Fixed (PEF) frame considering the 1980 IAU Theory of Nutation. The IERS EOP corrections must be added if one wants to make the rotation consistent with the Geocentric Celestial Reference Systems (GCRS).

r_tod_to_teme([T, ]jd_tt::Number, δΔϵ_1980::Number = 0, δΔψ_1980::Number = 0) -> T

Compute the rotation that aligns the True of Date (TOD) frame with the True Equator Mean Equinox (TEME) frame at the Julian Day jd_tt [Terrestrial Time]. This algorithm uses the IAU-76/FK5 theory and TEME definition in [1](p. 233). Notice that one can provide corrections for the nutation in obliquity (δΔϵ_1980) [rad] and in longitude (δΔψ_1980) [rad] that are usually obtained from IERS EOP Data (see fetch_iers_eop).

The rotation type is described by the optional variable T. If it is DCM, then a DCM will be returned. Otherwise, if it is Quaternion, then a Quaternion will be returned. In case this parameter is omitted, then it falls back to DCM.

Returns

• T: The rotation that aligns the TOD frame with the TEME frame.

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.

read_iers_eop(filename::AbstractString[, data_type]) -> Union{EopIau1980, EopIau2000A}

Read the IERS EOP data from the file filename related to the model selected by data_type, which can be Val(:IAU1980) for the IAU 1980 model (file finals.all.csv) or Val(:IAU2000A) for the IAU 2000A model (file finals2000A.all.csv). If data_type is omitted, it defaults to Val(:IAU1980). The function throws if the file does not follow the layout of the IERS files.

See also: fetch_iers_eop

Returns

• Union{EopIau1980, EopIau2000A}: EopIau1980 or EopIau2000A, depending on data_type, with the interpolations of the EOP fields indexed by the Julian Day [UTC].

Extended help

Throws

• ArgumentError: The file does not contain a header and at least one data row, its number of columns is neither 33 nor 37, or a field has no valid value or a missing value that is not at its end.

sv_ecef_to_ecef(
    sv::OrbitStateVector,
    ECEFo,
    ECEFf[, jd_utc::Number],
    eop
) -> OrbitStateVector

Convert the orbit state vector sv from an Earth-Centered, Earth-Fixed (ECEF) reference frame ECEFo to another ECEF reference frame ECEFf at the Julian Day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm uses the epoch of the orbit state vector sv (sv.t). The algorithm also requires the Earth Orientation Parameters (EOP) eop.

Returns

• OrbitStateVector: Orbit state vector sv converted to the ECEFf reference frame.

Extended help

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

The epoch direction cosine matrix (DCM) includes the polar-motion and precession/nutation orientation. For state vectors, the same epoch DCM is applied to r, v, and a, without Ḋ or D̈ terms. Consequently, the time derivatives of the polar motion and precession/nutation orientation, angular acceleration arising from changing length of day (LOD), and the corresponding kinematic terms are omitted from the velocity and acceleration conversion. Axial Earth rotation and its associated Coriolis and centrifugal terms are retained where applicable.

Supported ECEF Reference Frames

The supported ECEF frames for both origin ECEFo and destination ECEFf are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame (IAU-76/FK5).
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS) (IAU-2006/2010).

Earth Orientation Parameters (EOP)

The conversion between the supported ECEF frames always depends on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A.

Examples

julia> eop_iau1980 = fetch_iers_eop();

julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009)
2.453101827411875e6

julia> r_itrf  = [-1033.4793830; 7901.2952754; 6380.3565958] * 1000;

julia> v_itrf  = [-3.225636520; -2.872451450; +5.531924446] * 1000;

julia> sv_itrf = OrbitStateVector(jd_utc, r_itrf, v_itrf);

julia> sv_ecef_to_ecef(sv_itrf, ITRF(), PEF(), eop_iau1980)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1033.48, 7901.31, 6380.34]   km
      v : [-3.22563, -2.87244, 5.53193]  km/s

sv_ecef_to_eci(
    sv::OrbitStateVector,
    ECEF,
    ECI[, jd_utc::Number][, eop]
) -> OrbitStateVector

Convert the orbit state vector sv from the Earth-Centered, Earth-Fixed (ECEF) reference frame to the Earth-Centered Inertial (ECI) reference frame at the Julian Day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm uses the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

It is assumed that the input velocity and acceleration in sv are obtained by an observer on the ECEF frame. Thus, the output will contain the velocity and acceleration as measured by an observer on the ECI frame.

Returns

• OrbitStateVector: Orbit state vector sv converted to the ECI reference frame.

Extended help

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

The epoch direction cosine matrix (DCM) includes the polar-motion and precession/nutation orientation. For state vectors, the velocity and acceleration conversion retains the axial Earth-rotation Coriolis and centrifugal terms, but omits the time derivatives of the polar motion and precession/nutation orientation, angular acceleration arising from changing length of day (LOD), and the corresponding kinematic terms. Consequently, the converted acceleration is consistent with this approximation, rather than being the exact derivative of the complete time-dependent frame rotation.

Supported ECEF Reference Frames

The ECEF frame is selected by the parameter ECEF. The possible values are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame.
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS).

Supported ECI Reference Frames

The ECI frame is selected by the parameter ECI. The possible values are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, UTC will be assumed equal to UT1 to compute the Greenwich Mean Sidereal Time. This is an approximation, but should be sufficiently accurate for some applications. Notice that, if EOP Data is provided, UT1 will be accurately computed.

²: In this case, the terms that account for the free core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009);

julia> r_itrf  = [-1033.4793830; 7901.2952754; 6380.3565958] * 1000;

julia> v_itrf  = [-3.225636520; -2.872451450; +5.531924446] * 1000;

julia> sv_itrf = OrbitStateVector(jd_utc, r_itrf, v_itrf)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1033.48, 7901.3, 6380.36]    km
      v : [-3.22564, -2.87245, 5.53192]  km/s

julia> sv_gcrf = sv_ecef_to_eci(sv_itrf, ITRF(), GCRF(), eop_iau1980)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [5102.51, 6123.01, 6378.14]    km
      v : [-4.74322, 0.790537, 5.53376]  km/s

julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));

julia> sv_cirs = sv_ecef_to_eci(sv_itrf, ITRF(), CIRS(), eop_iau2000a)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [5100.02, 6122.79, 6380.34]    km
      v : [-4.74538, 0.790342, 5.53193]  km/s

sv_eci_to_ecef(
    sv::OrbitStateVector,
    ECI,
    ECEF[, jd_utc::Number][, eop]
) -> OrbitStateVector

Convert the orbit state vector sv from an Earth-Centered Inertial (ECI) reference frame to an Earth-Centered, Earth-Fixed (ECEF) reference frame at the Julian Day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm uses the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

It is assumed that the input velocity and acceleration in sv are obtained by an observer on the ECI frame. Thus, the output will contain the velocity and acceleration as measured by an observer on the ECEF frame.

Returns

• OrbitStateVector: Orbit state vector sv converted to the ECEF reference frame.

Extended help

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

The epoch direction cosine matrix (DCM) includes the polar-motion and precession/nutation orientation. For state vectors, the velocity and acceleration conversion retains the axial Earth-rotation Coriolis and centrifugal terms, but omits the time derivatives of the polar motion and precession/nutation orientation, angular acceleration arising from changing length of day (LOD), and the corresponding kinematic terms. Consequently, the converted acceleration is consistent with this approximation, rather than being the exact derivative of the complete time-dependent frame rotation.

Supported ECI Reference Frames

The ECI frame is selected by the parameter ECI. The possible values are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Supported ECEF Reference Frames

The ECEF frame is selected by the parameter ECEF. The possible values are:

• ITRF(): ECEF will be selected as the International Terrestrial Reference Frame (ITRF).
• PEF(): ECEF will be selected as the Pseudo-Earth Fixed (PEF) reference frame.
• TIRS(): ECEF will be selected as the Terrestrial Intermediate Reference System (TIRS).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, UTC will be assumed equal to UT1 to compute the Greenwich Mean Sidereal Time. This is an approximation but should be sufficiently accurate for some applications. Notice that, if EOP Data is provided, UT1 will be accurately computed.

²: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009);

julia> r_gcrf = [5102.50895790; 6123.01140070; 6378.13692820] * 1000;

julia> v_gcrf = [-4.7432201570; 0.7905364970; 5.5337557270] * 1000;

julia> sv_gcrf = OrbitStateVector(jd_utc, r_gcrf, v_gcrf)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [5102.51, 6123.01, 6378.14]    km
      v : [-4.74322, 0.790536, 5.53376]  km/s

julia> sv_itrf = sv_eci_to_ecef(sv_gcrf, GCRF(), ITRF(), eop_iau1980)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1033.48, 7901.3, 6380.36]    km
      v : [-3.22564, -2.87245, 5.53192]  km/s

julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));

julia> sv_tirs = sv_eci_to_ecef(sv_gcrf, GCRF(), TIRS(), eop_iau2000a)
OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1033.48, 7901.31, 6380.34]   km
      v : [-3.22563, -2.87244, 5.53193]  km/s

sv_eci_to_eci(
    sv::OrbitStateVector,
    ECIo,
    ECIf[, jd_utc::Number][, eop]
) -> OrbitStateVector
sv_eci_to_eci(
    sv::OrbitStateVector,
    ECIo[, jd_utco::Number],
    ECIf[, jd_utcf::Number][, eop]
) -> OrbitStateVector

Convert the orbit state vector sv from an Earth-Centered Inertial (ECI) reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frames contain only one of date frame, the first signature is used and the Julian Day jd_utc [UTC] is the epoch of this frame. On the other hand, if the origin and destination frames contain two of date frames¹, e.g. TOD => MOD, the second signature must be used, in which the Julian Day jd_utco [UTC] is the epoch of the origin frame and the Julian Day jd_utcf [UTC] is the epoch of the destination frame. If the epochs are not provided, the algorithm uses the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

¹: TEME is an of date frame.

Returns

• OrbitStateVector: Orbit state vector sv converted to the ECIf reference frame.

Extended help

Conversion Model

The model that will be used to compute the rotation is automatically inferred given the selection of the origin and destination frames. Notice that mixing IAU-76/FK5 and IAU-2006/2010 frames is not supported.

The epoch direction cosine matrix (DCM) includes the polar-motion and precession/nutation orientation. For state vectors, the same epoch DCM is applied to r, v, and a; no Ḋ or D̈ terms are included. Consequently, the time derivatives of the polar motion and precession/nutation orientation, angular acceleration arising from changing length of day (LOD), and the corresponding kinematic terms are omitted from the velocity and acceleration conversion. Axial Earth rotation and its associated Coriolis and centrifugal terms are retained where applicable.

Supported ECI Reference Frames

The supported ECI frames for both origin ECIo and destination ECIf are:

• TEME(): ECI will be selected as the True Equator Mean Equinox (TEME) reference frame.
• TOD(): ECI will be selected as the True of Date (TOD).
• MOD(): ECI will be selected as the Mean of Date (MOD).
• J2000(): ECI will be selected as the J2000 reference frame.
• GCRF(): ECI will be selected as the Geocentric Celestial Reference Frame (GCRF).
• CIRS(): ECI will be selected as the Celestial Intermediate Reference System (CIRS).
• ERS(): ECI will be selected as the Earth Reference System (ERS).
• MOD06(): ECI will be selected as the Mean of Date (MOD) according to the definition in IAU-2006/2010 theory.
• MJ2000(): ECI will be selected as the J2000 mean equatorial frame (MJ2000).

Earth Orientation Parameters (EOP)

The conversion between the frames might depend on EOP Data (see fetch_iers_eop and read_iers_eop). If IAU-76/FK5 model is used, the type of eop must be EopIau1980. Otherwise, if IAU-2006/2010 model is used, the type of eop must be EopIau2000A. The following table shows the requirements for EOP data given the selected frames.

¹: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

²: The transformation between GCRF and MJ2000 is a constant rotation matrix called bias. Hence, the date does not modify it. However, this signature was kept to avoid complications in the API.

³: In this case, the terms that corrects the nutation in obliquity and in longitude due to the free core nutation will not be available, reducing the precision.

Examples

julia> eop_iau1980 = fetch_iers_eop(Val(:IAU1980));

julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009);

julia> r_gcrf = [5102.50895790; 6123.01140070; 6378.13692820] * 1000;

julia> v_gcrf = [-4.7432201570; 0.7905364970; 5.5337557270] * 1000;

julia> sv_gcrf = OrbitStateVector(jd_utc, r_gcrf, v_gcrf);

julia> sv_j2000 = sv_eci_to_eci(sv_gcrf, GCRF(), J2000(), eop_iau1980);

julia> sv_tod = sv_eci_to_eci(sv_j2000, J2000(), TOD());

julia> sv_mod = sv_eci_to_eci(sv_tod, TOD(), jd_utc, MOD(), jd_utc);