View Source Astro.Time (Astro v1.0.0)
Calculations converting between geometry and time
All public functions use degrees as their input parameters
Time is a fraction of a day after UTC
Summary
Types
A number of days as a float
A time of day as a float fraction of a day
A tuple of integer hours, integer minutes and integer seconds
A number of hours as a float
The float number of Julian centuries.
A float number of days since the Julian epoch.
A number of minutes as a float
A moment is a floating point representation of the fraction of a day.
Season expressed as a non-negative number that is <= 360 representing the sun angle of incidence (the angle at which the sun hits the earth).
A number of seconds as a float
A time is a floating point number of days since 0000-01-01 including the fractional part of a day.
A time zone name as a string
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.
Returns the adjustment necessary to various celestial calculations at a given time.
Returns the Greenwich mean sidereal time for a given date time.
Converts a number of hours 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 local sidereal time for a given location and date time.
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
Types
@type days() :: number()
A number of days as a float
@type fraction_of_day() :: number()
A time of day as a float fraction of a day
@type hms() :: {Calendar.hour(), Calendar.minute(), Calendar.second()}
A tuple of integer hours, integer minutes and integer seconds
@type hours() :: number()
A number of hours as a float
@type julian_centuries() :: number()
The float number of Julian centuries.
Since there are 365.25 days in a Julian year, a Julian century has 36,525 days.
@type julian_days() :: number()
A float number of days since the Julian epoch.
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
.
@type minutes() :: number()
A number of minutes as a float
@type moment() :: number()
A moment is a floating point representation of the fraction of a day.
@type season() :: Astro.angle()
Season expressed as a non-negative number that is <= 360 representing the sun angle of incidence (the angle at which the sun hits the earth).
@type seconds() :: number()
A number of seconds as a float
@type time() :: number()
A time is a floating point number of days since 0000-01-01 including the fractional part of a day.
@type zone_name() :: binary()
A time zone name as a string
Functions
@spec datetime_from_date_and_minutes(minutes(), Calendar.date()) :: {:ok, Calendar.datetime()}
Adds the requested minutes to a date returning a datetime in the UTC time zone
Arguments
minutes
is a float number of minutes since midnightdate
is any date in the Gregorian calendar
Returns
{:ok, datetime in the UTC time zone}
@spec datetime_from_julian_days(julian_days()) :: {:ok, Calendar.datetime()}
Returns the datetime for a given Julian day
Arguments
julian_day
is any astronomical Julian day such as returned fromAstro.Time.julian_day_from_date/1
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]}
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.
Returns the adjustment necessary to various celestial calculations at a given time.
The ajustment is required since the earth's orbit of the sun is not completely uniform.
@spec greenwich_mean_sidereal_time(Calendar.datetime()) :: moment()
Returns the Greenwich mean sidereal time for a given date time.
Converts a number of hours into days.
Arguments
- a float number of
hours
Returns
- a float number of
days
Examples
iex> Astro.Time.hours_to_days(48)
2.0
@spec hours_to_hms(fraction_of_day()) :: hms()
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
Returns the Julian centuries for a given Julian day
Arguments
julian_day
is any astronomical Julian day such as returned fromAstro.Time.julian_day_from_date/1
Returns
- the astronomical Julian century as a
float
@spec julian_day_from_date(Calendar.date()) :: julian_days()
Returns the astronomical Julian day for a given date
Arguments
date
is anyCalendar.date
Returns
- the astronomical Julian day as a
float
Example
iex> Astro.Time.julian_day_from_date ~D[2019-12-05] 2458822.5
@spec julian_day_from_julian_centuries(julian_centuries()) :: julian_days()
Returns the Julian day for a given Julian century
Arguments
julian_century
is any astronomical Julian century such as returned fromAstro.Time.julian_centuries_from_julian_day/1
Returns
- the astronomical Julian day as a
float
@spec 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.
@spec local_sidereal_time(Astro.location(), Calendar.datetime()) :: moment()
Returns the local sidereal time for a given location and date time.
@spec mjd(Calendar.date()) :: julian_days()
Returns the modified Julian day for a date
Arguments
date
is anyCalendar.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.
@spec moment_to_datetime(fraction_of_day(), Calendar.date()) :: {:ok, Calendar.datetime()}
Converts a float number of hours since midnight to
a DateTime.t()
Arguments
time_of_day
is a float number of hours since midnightdate
is anyCalendar.date()
Returns
A DateTime.t()
combining the date
and time_of_day
in the UTC timezone.
@spec offset_for_zone(moment(), zone_name()) :: fraction_of_day()
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
@spec offset_from_longitude(Geo.PointZ.t() | Astro.longitude()) :: moment()
Returns the zone difference in hours between a given location and UTC.
@spec seconds_to_hms(fraction_of_day()) :: hms()
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}
Returns the standard time for a universal time in a given time zone.
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).
@spec 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.
Returns the universal (UTC) time for a standard time in a given time zone.
@spec utc_datetime_from_terrestrial_datetime(Calendar.datetime()) :: {:ok, Calendar.datetime()}
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).