Astro.Time (Astro v0.8.0) View Source

Calculations converting between geometry and time

All public functions use degrees as their input parameters

Time is a fraction of a day after UTC

Link to this section Summary

Types

The current Julian epoch is defined to have been noon on January 1, 2000. This epoch is denoted J2000 and has the exact Julian day number 2,451,545.0.

A moment is a floating point representations of the fraction of a day.

A time is a floating point number of days since 0000-01-01 including the fractional part of a day.

Functions

Adds the requested minutes to a date returning a datetime in the UTC time zone

Returns the datetime for a given Julian day

Returns the dynamical time for a given universal time.

Converts a number of hourse into days.

Converts a float number of hours since midnight into {hours, minutes, seconds}.

Returns the day number for January 1st, 2000

Returns the Julian centuries for a given Julian day

Returns the astronomical Julian day for a given date

Returns the Julian day for a given Julian century

Returns the local time from the universal time at a given location.

Returns the modified Julian day for a date

Converts a float number of hours since midnight to a DateTime.t()

Returns the offset in float days for a given moment and time zone.

Returns the zone difference in hours between a given location and UTC.

Converts a number of seconds since midnight into {hours, minutes, seconds}.

Returns the standard time for a universal time in a given time zone.

Returns the universal (UTC) time for a given dynamical time.

Returns the universal time (UTC) from the local time at a given location.

Returns the universal (UTC) time for a standard time in a given time zone.

Converts a terrestrial datetime to a UTC datetime

Link to this section Types

Specs

hours() :: number()

Specs

julian_centuries() :: number()

The current Julian epoch is defined to have been noon on January 1, 2000. This epoch is denoted J2000 and has the exact Julian day number 2,451,545.0.

Since there are 365.25 days in a Julian year, a Julian century has 36,525 days.

Specs

moment() :: number()

A moment is a floating point representations of the fraction of a day.

Specs

season() :: Astro.angle()

Specs

time() :: number()

A time is a floating point number of days since 0000-01-01 including the fractional part of a day.

Specs

zone_name() :: binary()

Link to this section Functions

See Astro.Time.julian_day_from_date/1.

Link to this function

datetime_from_date_and_minutes(minutes, date)

View Source

Adds the requested minutes to a date returning a datetime in the UTC time zone

Arguments

  • minutes is a float number of minutes since midnight

  • date is any date in the Gregorian calendar

Returns

  • a datetime in the UTC time zone
Link to this function

datetime_from_julian_days(julian_days)

View Source

Returns the datetime for a given Julian day

Arguments

Returns

  • a DateTime.t in the UTC time zone

Example

iex> Astro.Time.datetime_from_julian_days 2458822.5
{:ok, ~U[2019-12-05 00:00:00Z]}
Link to this function

days_from_minutes(minutes)

View Source
Link to this function

dynamical_from_universal(t)

View Source

Specs

dynamical_from_universal(time()) :: time()

Returns the dynamical time for a given universal time.

Dynamical time is the time-scale that is used in calculating orbital motions within the Solar System. The underlying physical law governing such motions is the law of gravitation.

Converts a number of hourse into days.

Arguments

Returns

Examples

Link to this function

hours_to_hms(time_of_day)

View Source

Converts a float number of hours since midnight into {hours, minutes, seconds}.

Arguments

  • time_of_day is a float number of hours since midnight

Returns

  • A {hour, minute, second} tuple.

Examples

iex> Astro.Time.hours_to_hms 0.0 {0, 0, 0}

iex> Astro.Time.hours_to_hms 23.999 {23, 59, 56}

iex> Astro.Time.hours_to_hms 15.456 {15, 27, 21}

Returns the day number for January 1st, 2000

Link to this function

julian_centuries_from_julian_day(julian_day)

View Source

Returns the Julian centuries for a given Julian day

Arguments

Returns

  • the astronomical Julian century as a float
Link to this function

julian_centuries_from_moment(t)

View Source
Link to this function

julian_day_from_date(date)

View Source

Returns the astronomical Julian day for a given date

Arguments

  • date is any Calendar.date

Returns

  • the astronomical Julian day as a float

Example

iex> Astro.Time.julian_day_from_date ~D[2019-12-05] 2458822.5

Link to this function

julian_day_from_julian_centuries(julian_centuries)

View Source

Returns the Julian day for a given Julian century

Arguments

Returns

  • the astronomical Julian day as a float
Link to this function

local_from_universal(t, point_z)

View Source

Specs

local_from_universal(time(), Geo.PointZ.t()) :: time()

Returns the local time from the universal time at a given location.

Locale time is UTC time plus the number of hours offset calculated from the longitude of a location.

This is different to standard time which is UTC time adjusted for a specific time zone name.

Returns the modified Julian day for a date

Arguments

  • date is any Calendar.date

Returns

  • the modified Julian day as a float

Notes

A modified version of the Julian date denoted MJD is obtained by subtracting 2,400,000.5 days from the Julian date JD,

The MJD therefore gives the number of days since midnight on November 17, 1858. This date corresponds to 2400000.5 days after day 0 of the Julian calendar.

Link to this function

moment_to_datetime(time_of_day, map)

View Source

Converts a float number of hours since midnight to a DateTime.t()

Arguments

  • time_of_day is a float number of hours since midnight

  • date is any Calendar.date()

Returns

A DateTime.t() combining the date and time_of_day in the UTC timezone.

Link to this function

offset_for_zone(t, time_zone)

View Source

Returns the offset in float days for a given moment and time zone.

Example

# Returns a 1 hour offset as a fraction of day
iex> t = Date.to_gregorian_days(~D[2021-08-01])
iex> Astro.Time.offset_for_zone t, "Europe/London"
0.041666666666666664
Link to this function

offset_from_location(location, t)

View Source
Link to this function

offset_from_longitude(longitude)

View Source

Specs

offset_from_longitude(Geo.PointZ.t() | Astro.longitude()) :: moment()

Returns the zone difference in hours between a given location and UTC.

Link to this function

seconds_to_hms(time_of_day)

View Source

Converts a number of seconds since midnight into {hours, minutes, seconds}.

Arguments

  • time_of_day is a number of seconds

Returns

  • A {hour, minute, second} tuple.

Examples

iex> Astro.Time.seconds_to_hms 0.0 {0, 0, 0}

iex> Astro.Time.seconds_to_hms 3214 {0, 53, 34}

iex> Astro.Time.seconds_to_hms 10_000 {2, 46, 39}

Link to this function

standard_from_universal(t, zone_name)

View Source

Specs

standard_from_universal(time(), zone_name() | number()) :: time()

Returns the standard time for a universal time in a given time zone.

Link to this function

universal_from_dynamical(t)

View Source

Specs

universal_from_dynamical(time()) :: time()

Returns the universal (UTC) time for a given dynamical time.

Coordinated Universal Time or UTC is the primary time standard by which the world regulates clocks and time.

It is within about 1 second of mean solar time at 0° longitude and is not adjusted for daylight saving time.

It is effectively a successor to Greenwich Mean Time (GMT).

Link to this function

universal_from_local(t, point_z)

View Source

Specs

universal_from_local(time(), Geo.PointZ.t()) :: time()

Returns the universal time (UTC) from the local time at a given location.

Locale time is UTC time plus the number of hours offset calculated from the longitude of a location.

This is different to standard time which is UTC time adjusted for a specific time zone name.

Link to this function

universal_from_standard(t, zone_name)

View Source

Specs

universal_from_standard(time(), zone_name() | number()) :: time()

Returns the universal (UTC) time for a standard time in a given time zone.

Link to this function

utc_datetime_from_terrestrial_datetime(datetime)

View Source

Converts a terrestrial datetime to a UTC datetime

Arguments

  • datetime is any UTC datetime which is considered to be a Terrestrial Time.

Returns

  • A UTC datetime adjusted for the difference between Terrestrial Time and UTC time

Notes

Terrestrial Time (TT) was introduced by the IAU in 1979 as the coordinate time scale for an observer on the surface of Earth. It takes into account relativistic effects and is based on International Atomic Time (TAI), which is a high-precision standard using several hundred atomic clocks worldwide. As such, TD is the atomic time equivalent to its predecessor Ephemeris Time (ET) and is used in the theories of motion for bodies in the solar system.

To ensure continuity with ET, TD was defined to match ET for the date 1977 Jan 01. In 1991, the IAU refined the definition of TT to make it more precise. It was also renamed Terrestrial Time (TT) from the earlier Terrestrial Dynamical Time (TDT).