API

@timescale scale epoch [args...] body

Define a new time scale, the corresponding Epoch type alias, and a function that calculates the offset from TAI for the new time scale.

Arguments

• scale: The name of the time scale
• epoch: The name of the Epoch parameter that is passed to the tai_offset function
• args: Optional additional parameters that are passed to the tai_offset function
• body: The body of the tai_offset function

Example

julia> @timescale GMT ep tai_offset(UTC, ep)

julia> GMT isa TimeScale
true

julia> GMTEpoch
Epoch{GMT,T} where T

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 UTC. Otherwise use an explicit constructor, e.g. Epoch{UTC}.

Example

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

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

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{UTC}("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 UTC

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

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

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{UTC}(2018, 2, 6, 20, 45, 0.0)
2018-02-06T20:45:00.000 UTC

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

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}(Δ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{S}(jd1::T, jd2::T=zero(T); origin=:j2000) where {S, T<:Period}

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{UTC}(0.0days, 0.5days)
2000-01-02T00:00:00.000 UTC

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

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<:Period

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<:Period

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<:Period

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<:Period

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<:Period

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<:Period

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

UTCEpoch(str[, format])

Construct a UTCEpoch 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> UTCEpoch("2018-02-06T20:45:00.0")
2018-02-06T20:45:00.000 UTC

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

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

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

Construct a UTCEpoch from date and time components.

Example

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

julia> UTCEpoch(2018, 2, 6)
2018-02-06T00:00:00.000 UTC

UTCEpoch(jd1::T, jd2::T=zero(T); origin=:j2000) where T<:Period

Construct a UTCEpoch 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> UTCEpoch(0.0days, 0.5days)
2000-01-02T00:00:00.000 UTC

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

date(ep::Epoch)

Get the date of the epoch ep.

fractionofday(ep::Epoch)

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

j2000(scale, ep)

Returns the J2000 Julian date for epoch ep within a specific time scale.

Example

julia> j2000(TAI, TTEpoch(2000, 1, 1, 12, 0, 32.184))
0.0 days

j2000(ep)

Returns the J2000 Julian date for epoch ep.

Example

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

julian(scale, ep)

Returns the Julian Date for epoch ep within a specific time scale.

Example

julia> julian(TAI, TTEpoch(2000, 1, 1, 12, 0, 32.184))
2.451545e6 days

julian(ep)

Returns the Julian Date for epoch ep.

Example

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

julian_twopart(scale, ep)

Returns the two-part Julian date for epoch ep within a specific time scale, which is a tuple consisting of the Julian day number and the fraction of the day.

Example

julia> julian_twopart(TAI, TTEpoch(2000, 1, 1, 12, 0, 32.184))
(2.451545e6 days, 0.0 days)

julian_twopart(ep)

Returns 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(UTCEpoch(2000, 1, 2))
(2.451545e6 days, 0.5 days)

modified_julian(scale, ep)

Returns the Modified Julian Date for epoch ep within a specific time scale.

Example

julia> modified_julian(TAI, TTEpoch(2000, 1, 1, 12, 0, 32.184))
51544.5 days

modified_julian(ep)

Returns the Modified Julian Date for epoch ep.

Example

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

now()

Get the current date and time as a UTCEpoch.

tai_offset(TCB, ep)

Returns the difference TCB-TAI in seconds at the epoch ep.

tai_offset(TDB, ep, elong, u, v)

Returns the difference TDB-TAI in seconds at the epoch ep for an observer on Earth.

Arguments

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

References

• ERFA

tai_offset(TDB, ep)

Returns the difference TDB-TAI in seconds at the epoch ep.

This routine is accurate to ~40 microseconds in the interval 1900-2100.

References

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

tai_offset(UTC, ep)

Returns the difference UTC-TAI in seconds at the epoch ep.

tai_offset(ep)

Returns the offset from TAI for the epoch ep.

tai_offset(TCG, ep)

Returns the difference TCG-TAI in seconds at the epoch ep.

tai_offset(TT, ep)

Returns the difference TT-TAI in seconds at the epoch ep.

tai_offset(UT1, ep)

Returns the difference UT1-TAI in seconds at the epoch ep.

time(ep::Epoch)

Get the time of the epoch ep.

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.

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.

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.

Period{U}(Δt)

A Period object represents a time interval of Δt with a TimeUnit of U. Periods can be constructed via the shorthand syntax shown in the examples below.

Examples

julia> 3.0seconds
3.0 seconds

julia> 1.0minutes
1.0 minutes

julia> 12hours
12 hours

julia> days_per_year = 365
365
julia> days_per_year * days
365 days

julia> 10.0years
10.0 years

julia> 1centuries
1 century

All time units are subtypes of the abstract type TimeUnit. The following time units are defined:

• Second
• Minute
• Hour
• Day
• Year
• Century

All timescales are subtypes of the abstract type TimeScale. The following timescales are defined:

• UTC — Coordinated Universal Time
• UT1 — Universal Time
• TAI — International Atomic Time
• TT — Terrestrial Time
• TCG — Geocentric Coordinate Time
• TCB — Barycentric Coordinate Time
• TDB — Barycentric Dynamical Time