Epochs

Epoch(str[, format])

Construct an Epoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the character code D is supported which is parsed as "day of year" (see the example below) and the character code t which is parsed as the time scale. The default format is yyyy-mm-ddTHH:MM:SS.sss ttt.

Note: Please be aware that this constructor requires that the time scale is part of str, e.g. 2018-02-06T00:00 TAI. Otherwise use an explicit constructor, e.g. Epoch{TAI}.

Example

julia> Epoch("2018-02-06T20:45:00.0 TAI")
2018-02-06T20:45:00.000 TAI

julia> Epoch("2018-037T00:00 TAI", "yyyy-DDDTHH:MM ttt")
2018-02-06T00:00:00.000 TAI

Epoch{S}(str[, format]) where S

Construct an Epoch with time scale S from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D can be used which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> Epoch{InternationalAtomicTime}("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TAI

julia> Epoch{InternationalAtomicTime}("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TAI

julia> Epoch{InternationalAtomicTime}("2018-037T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TAI

Epoch{S2}(ep::Epoch{S1}) where {S1, S2}

Convert ep, an Epoch with time scale S1, to an Epoch with time scale S2.

Examples

julia> ep = TTEpoch(2000,1,1)
2000-01-01T00:00:00.000 TT

julia> TAIEpoch(ep)
1999-12-31T23:59:27.816 TAI

Epoch{S}(year, month, day, hour=0, minute=0, second=0.0) where S

Construct an Epoch with time scale S from date and time components.

Example

julia> Epoch{InternationalAtomicTime}(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TAI

julia> Epoch{InternationalAtomicTime}(2018, 2, 6)
2018-02-06T00:00:00.000 TAI

Epoch{S}(Δtai, ep::TAIEpoch) where S

Convert ep, a TAIEpoch, to an Epoch with time scale S by overriding the offset between S2 and TAI with Δtai.

Examples

julia> ep = TAIEpoch(2000,1,1)
2000-01-01T00:00:00.000 TAI

julia> TTEpoch(32.184, ep)
2000-01-01T00:00:32.184 TT

Epoch(ep::Epoch{S1}, scale::S2) where {S1, S2}

Convert ep, an Epoch with time scale S1, to an Epoch with time scale S2.

Examples

julia> ep = TTEpoch(2000,1,1)
2000-01-01T00:00:00.000 TT

julia> Epoch(ep, TAI)
1999-12-31T23:59:27.816 TAI

Epoch{S}(jd1::T, jd2::T=zero(T); origin=:j2000) where {S, T<:AstroPeriod}

Construct an Epoch with time scale S from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> Epoch{InternationalAtomicTime}(0.0days, 0.5days)
2000-01-02T00:00:00.000 TAI

julia> Epoch{InternationalAtomicTime}(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TAI

TAIEpoch(str[, format])

Construct a TAIEpoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> TAIEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TAI

julia> TAIEpoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TAI

julia> TAIEpoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TAI

TAIEpoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a TAIEpoch from date and time components.

Example

julia> TAIEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TAI

julia> TAIEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 TAI

TAIEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a TAIEpoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> TAIEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 TAI

julia> TAIEpoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TAI

TCBEpoch(str[, format])

Construct a TCBEpoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> TCBEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TCB

julia> TCBEpoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TCB

julia> TCBEpoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TCB

TCBEpoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a TCBEpoch from date and time components.

Example

julia> TCBEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TCB

julia> TCBEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 TCB

TCBEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a TCBEpoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> TCBEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 TCB

julia> TCBEpoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TCB

TCGEpoch(str[, format])

Construct a TCGEpoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> TCGEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TCG

julia> TCGEpoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TCG

julia> TCGEpoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TCG

TCGEpoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a TCGEpoch from date and time components.

Example

julia> TCGEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TCG

julia> TCGEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 TCG

TCGEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a TCGEpoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> TCGEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 TCG

julia> TCGEpoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TCG

TDBEpoch(str[, format])

Construct a TDBEpoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> TDBEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TDB

julia> TDBEpoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TDB

julia> TDBEpoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TDB

TDBEpoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a TDBEpoch from date and time components.

Example

julia> TDBEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TDB

julia> TDBEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 TDB

TDBEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a TDBEpoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> TDBEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 TDB

julia> TDBEpoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TDB

TTEpoch(str[, format])

Construct a TTEpoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> TTEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 TT

julia> TTEpoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 TT

julia> TTEpoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 TT

TTEpoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a TTEpoch from date and time components.

Example

julia> TTEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TT

julia> TTEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 TT

TTEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a TTEpoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> TTEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 TT

julia> TTEpoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 TT

UT1Epoch(str[, format])

Construct a UT1Epoch from a string str. Optionally a format definition can be passed as a DateFormat object or as a string. In addition to the character codes supported by DateFormat the code D is supported which is parsed as "day of year" (see the example below). The default format is yyyy-mm-ddTHH:MM:SS.sss.

Example

julia> UT1Epoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 UT1

julia> UT1Epoch("February 6, 2018", "U d, y")
2018-02-06T00:00:00.000 UT1

julia> UT1Epoch("2018-37T00:00", "yyyy-DDDTHH:MM")
2018-02-06T00:00:00.000 UT1

UT1Epoch(year, month, day, hour=0, minute=0, second=0.0)

Construct a UT1Epoch from date and time components.

Example

julia> UT1Epoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 UT1

julia> UT1Epoch(2018, 2, 6)
2018-02-06T00:00:00.000 UT1

UT1Epoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:AstroPeriod

Construct a UT1Epoch from a Julian date (optionally split into jd1 and jd2). origin determines the variant of Julian date that is used. Possible values are:

• :j2000: J2000 Julian date, starts at 2000-01-01T12:00
• :julian: Julian date, starts at -4712-01-01T12:00
• :modified_julian: Modified Julian date, starts at 1858-11-17T00:00

Examples

julia> UT1Epoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 UT1

julia> UT1Epoch(2.451545e6days, origin=:julian)
2000-01-01T12:00:00.000 UT1

fractionofday(ep::Epoch)

Get the time of the day of the epoch ep as a fraction.

fractionofsecond(ep::Epoch)

Get the fraction of the current second of the epoch ep.

j2000(ep)

Return the J2000 Julian Date for epoch ep.

Example

julia> j2000(TAIEpoch(2000, 1, 1, 12))
0.0 days

julian(ep)

Return the Julian Date for epoch ep.

Example

julia> julian(TAIEpoch(2000, 1, 1, 12))
2.451545e6 days

julian_twopart(ep)

Return the two-part Julian Date for epoch ep, which is a tuple consisting of the Julian day number and the fraction of the day.

Example

julia> julian_twopart(TAIEpoch(2000, 1, 2))
(2.451545e6 days, 0.5 days)

subsecond(ep::Epoch, n)

Get the number of fractional seconds with the unit $s * \frac{1}{10^n}$, e.g. subsecond(ep, 3) for milliseconds, of the epoch ep. n must be divisible by 3.

from_utc(str::AbstractString, dateformat::Dates.DateFormat; scale=TAI)
from_utc(dt::Dates.DateTime; scale=TAI)
from_utc(year, month, day, hour=0, minute=0, second=0, fraction=0.0; scale=TAI)
from_utc(year, month, day, hour, minute, seconds; scale=TAI)

Create an Epoch in scale based on a UTC timestamp, Dates.DateTime or date and time components.

Examples

julia> from_utc(2016, 12, 31, 23, 59, 60, 0.0)
2017-01-01T00:00:36.000 TAI

julia> from_utc(2016, 12, 31, 23, 59, 60.0)
2017-01-01T00:00:36.000 TAI

julia> from_utc("2016-12-31T23:59:60.0")
2017-01-01T00:00:36.000 TAI

julia> from_utc("2016-12-31T23:59:60.0", scale=TDB)
2017-01-01T00:01:08.183 TDB

getoffset(UT1, TAI, second, fraction[, eop])

Return the offset between UT1 and TAI for the current epoch (second after J2000 and fraction) in seconds. Optionally, a custom Earth orientation data struct eop can be provided, see EarthOrientation.jl.

Example

julia> getoffset(UT1, TAI, 0, 0.0)
31.644974965344606

getoffset(TAI, UT1, second, fraction[, eop])

Return the offset between TAI and UT1 for the current epoch (second after J2000 and fraction) in seconds. Optionally, a custom Earth orientation data struct eop can be provided, see EarthOrientation.jl.

Example

julia> getoffset(TAI, UT1, 0, 0.0)
-31.644974644349812

getoffset(TCB, TDB, second, fraction)

Return the linear offset between TCB and TDB for the current epoch (second after J2000 and fraction) in seconds.

Example

julia> getoffset(TCB, TDB, 0, 0.0)
-11.253721593757295

getoffset(TDB, TCB, second, fraction)

Return the linear offset between TDB and TCB for the current epoch (second after J2000 and fraction) in seconds.

Example

julia> getoffset(TDB, TCB, 0, 0.0)
11.253721768248475

getoffset(TDB, TT, second, fraction[, eop])

Return the offset between TDB and TT for the current epoch (second after J2000 and fraction) for an observer on earth in seconds.

Arguments

• second, fraction: Current epoch
• elong: Longitude (east positive, radians)
• u: Distance from Earth's spin axis (km)
• v: Distance north of equatorial plane (km)

Example

julia> getoffset(TDB, TT, 0, 0.0, π, 6371.0, 0.0)
9.928419814106208e-5

References

• ERFA

getoffset(TDB, TT, second, fraction[, eop])

Return the offset between TDB and TT for the current epoch (second after J2000 and fraction) in seconds. This routine is accurate to ~40 microseconds over the interval 1900-2100.

Example

julia> getoffset(TDB, TT, 0, 0.0)
7.273677616693264e-5

References

• https://www.cv.nrao.edu/~rfisher/Ephemerides/times.html#TDB
• Issue #26

getoffset(TCG, TT, second, fraction)

Return the linear offset between TCG and TT for the current epoch (second after J2000 and fraction) in seconds.

Example

julia> getoffset(TCG, TT, 0, 0.0)
-0.5058332856685995

getoffset(TAI, TT, args...)

Return the fixed offset between TAI and TT in seconds.

Example

julia> getoffset(TAI, TT)
32.184

getoffset(TT, TDB, second, fraction[, eop])

Return the offset between TT and TDB for the current epoch (second after J2000 and fraction) for an observer on earth in seconds.

Arguments

• second, fraction: Current epoch
• elong: Longitude (east positive, radians)
• u: Distance from Earth's spin axis (km)
• v: Distance north of equatorial plane (km)

Example

julia> getoffset(TT, TDB, 0, 0.0, π, 6371.0, 0.0)
-9.928419818977206e-5

References

• ERFA

getoffset(TT, TDB, second, fraction[, eop])

Return the offset between TT and TDB for the current epoch (second after J2000 and fraction) in seconds. This routine is accurate to ~40 microseconds over the interval 1900-2100.

Example

julia> getoffset(TT, TDB, 0, 0.0)
-7.273677619130569e-5

References

• https://www.cv.nrao.edu/~rfisher/Ephemerides/times.html#TDB
• Issue #26

getoffset(TT, TCG, second, fraction)

Return the linear offset between TT and TCG for the current epoch (second after J2000 and fraction) in seconds.

Example

julia> getoffset(TT, TCG, 0, 0.0)
0.5058332860211293

getoffset(TT, TAI, args...)

Return the fixed offset between TT and TAI in seconds.

Example

julia> getoffset(TT, TAI)
-32.184

getoffset(ep::Epoch, scale::TimeScale)

For a given epoch ep return the offset between its time scale and another time scale in seconds.

Example

julia> tai = TAIEpoch(2000, 1, 1)
2000-01-01T00:00:00.000 TAI

julia> getoffset(tai, TT)
32.184

julian_period([T,] ep::Epoch; origin=:j2000, scale=timescale(ep), unit=days)

Return the period since Julian Epoch origin within the time scale scale expressed in unit for a given epoch ep. The result is an AstroPeriod object by default. If the type argument T is present, the result is converted to T instead.

Example

julia> ep = TAIEpoch(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 TAI

julia> julian_period(ep; scale=TT)
6611.364955833334 days

julia> julian_period(ep; unit=years)
18.100929728496464 years

julia> julian_period(Float64, ep)
6611.364583333333

modified_julian(ep)

Return the Modified Julian Date for epoch ep.

Example

julia> modified_julian(TAIEpoch(2000, 1, 1, 12))
51544.5 days

timescale(ep)

Return the time scale of epoch ep.

Example

julia> ep = TTEpoch(2000, 1, 1)
2000-01-01T00:00:00.000 TT

julia> timescale(ep)
TT

to_utc(ep)
to_utc(::Type{DateTime}, ep)
to_utc(::Type{Dates.DateTime}, ep)
to_utc(::Type{String}, ep, dateformat=Dates.default_format(DateTime))

Create a UTC timestamp or Dates.DateTime from an Epoch ep.

Examples

julia> tai = from_utc(Dates.DateTime(2018, 2, 6, 20, 45, 0, 0))
2018-02-06T20:45:37.000 TAI

julia> to_utc(tai)
"2018-02-06T20:45:00.000"

julia> to_utc(String, tai, Dates.dateformat"yyyy-mm-dd")
"2018-02-06"

julia> to_utc(Dates.DateTime, tai)
2018-02-06T20:45:00

-(a::Epoch, b::Epoch)

Return the duration between epoch a and epoch b.

Examples

julia> TAIEpoch(2018, 2, 6, 20, 45, 20.0) - TAIEpoch(2018, 2, 6, 20, 45, 0.0)
20.0 seconds

day(ep::Epoch)

Get the day of the epoch ep.

dayofyear(ep::Epoch)

Get the day of the year of the epoch ep.

hour(ep::Epoch)

Get the hour of the epoch ep.

microsecond(ep::Epoch)

Get the number of microseconds of the epoch ep.

millisecond(ep::Epoch)

Get the number of milliseconds of the epoch ep.

minute(ep::Epoch)

Get the minute of the epoch ep.

month(ep::Epoch)

Get the month of the epoch ep.

nanosecond(ep::Epoch)

Get the number of nanoseconds of the epoch ep.

now(::Type{Epoch})
now(::Type{Epoch{S}}) where S<:TimeScale

Get the current date and time as an Epoch. The default time scale is TAI.

Example

julia> now(Epoch)
2021-04-11T13:20:29.160 TAI

julia> now(TDBEpoch)
2021-04-11T13:21:21.518 TDB

second(type, ep::Epoch)

Get the second of the epoch ep as a type.

second(ep::Epoch) -> Int

Get the second of the epoch ep as an Int.

year(ep::Epoch)

Get the year of the epoch ep.

yearmonthday(ep::Epoch)

Get the year, month, and day of the epoch ep as a tuple.

DateTime(ep::Epoch)

Convert the epoch ep to an AstroDates.DateTime.

Date(ep::Epoch)

Get the Date of the epoch ep.

Time(ep::Epoch)

Get the Time of the epoch ep.