Loading...
Searching...
No Matches
timescale.c File Reference

Functions to define and use different astronomical timescales and to convert among them. More...

## Macros

#define | _DEFAULT_SOURCE 1
| struct timespec

## Functions

double | get_ut1_to_tt (int leap_seconds, double dut1)
| Returns the TT - UT1 time difference given the leap seconds and the actual UT1 - UTC time difference as measured and published by IERS.
double | get_utc_to_tt (int leap_seconds)
| Returns the difference between Terrestrial Time (TT) and Universal Coordinated Time (UTC).
double | novas_clock_skew (const novas_frame *frame, enum novas_timescale timescale)
| Returns the instantaneous incremental rate at which the observer's clock (i.e.
double | novas_date (const char *restrict date)
| Returns a Julian date (in non-specific timescale) corresponding the specified input string date / time.
double | novas_date_scale (const char *restrict date, enum novas_timescale *restrict scale)
| Returns a Julian date and the timescale corresponding the specified input string date/time and timescale marker.
double | novas_diff_tcb (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Barycentric Coordinate Time (TCB) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_tcg (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Geocentric Coordinate Time (TCG) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_time (const novas_timespec *t1, const novas_timespec *t2)
| Returns the Terrestrial Time (TT) based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_diff_time_scale (const novas_timespec *t1, const novas_timespec *t2, enum novas_timescale timescale)
| Returns the UT1 based time difference (t1 - t2) in days between two astronomical time specifications.
double | novas_get_split_time (const novas_timespec *restrict time, enum novas_timescale timescale, long *restrict ijd)
| Returns the fractional Julian date of an astronomical time in the specified timescale, as an integer and fractional part.
double | novas_get_time (const novas_timespec *restrict time, enum novas_timescale timescale)
| Returns the fractional Julian date of an astronomical time in the specified timescale.
time_t | novas_get_unix_time (const novas_timespec *restrict time, long *restrict nanos)
| Returns the UNIX time for an astronomical time instant.
int | novas_iso_timestamp (const novas_timespec *restrict time, char *restrict dst, int maxlen)
| Prints a UTC-based ISO timestamp to millisecond precision to the specified string buffer.
double | novas_mean_clock_skew (const novas_frame *frame, enum novas_timescale timescale)
| Returns the averaged incremental rate at which the observer's clock (i.e.
int | novas_offset_time (const novas_timespec *time, double seconds, novas_timespec *out)
| Increments the astrometric time by a given amount.
int | novas_print_timescale (enum novas_timescale scale, char *restrict buf)
| Prints the standard string representation of the timescale to the specified buffer.
int | novas_set_current_time (int leap, double dut1, novas_timespec *restrict time)
| Sets the time with the UNIX time obtained from the system clock.
int | novas_set_split_time (enum novas_timescale timescale, long ijd, double fjd, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to the split Julian Date value, defined in the specified timescale.
int | novas_set_str_time (enum novas_timescale timescale, const char *restrict str, int leap, double dut1, novas_timespec *restrict time)
| Sets astronomical time in a specific timescale using a string specification.
int | novas_set_time (enum novas_timescale timescale, double jd, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to the fractional Julian Date value, defined in the specified timescale.
int | novas_set_unix_time (time_t unix_time, long nanos, int leap, double dut1, novas_timespec *restrict time)
| Sets an astronomical time to a UNIX time value.
double | novas_time_gst (const novas_timespec *restrict time, enum novas_accuracy accuracy)
| Returns the Greenwich (apparent) Sidereal Time (GST/GaST) for a given astronomical time specification.
int | novas_time_leap (const novas_timespec *time)
| Returns the leap seconds component of an astronomical time specification.
double | novas_time_lst (const novas_timespec *restrict time, double lon, enum novas_accuracy accuracy)
| Returns the Local (apparent) Sidereal Time (LST/LaST) for a given astronomical time specification and observer location.
double | novas_timescale_offset (const novas_timespec *ts, enum novas_timescale timescale, enum novas_timescale ref_scale)
| Returns the time difference between two different timescales at a specific astrometric time instance.
int | novas_timestamp (const novas_timespec *restrict time, enum novas_timescale scale, char *restrict dst, int maxlen)
| Prints an astronomical timestamp to millisecond precision in the specified timescale to the specified string buffer.
int | tdb2tt (double jd_tdb, double *restrict jd_tt, double *restrict secdiff)
| Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (TDB) Julian date, and returns the TDB-TT time difference also.
double | tt2tdb (double jd_tt)
| Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 10 μs for dates between 1600 and 2200.
double | tt2tdb_fp (double jd_tt, double limit)
| Returns the TDB-TT time difference with flexible precision.
double | tt2tdb_hp (double jd_tt)
| Returns the TDB-TT time difference with high precision.

## Detailed Description

Functions to define and use different astronomical timescales and to convert among them.

Date
  Created on Jun 24, 2024

Author
  Attila Kovacs and G. Kaplan

Since
  1.1

See also
  calendar.c, frames.c, observer.c

## Macro Definition Documentation

## _DEFAULT_SOURCE

#define _DEFAULT_SOURCE 1

struct timespec

## Function Documentation

## get_ut1_to_tt()

double get_ut1_to_tt | ( | int | leap_seconds,
|  | double | dut1 )

Returns the TT - UT1 time difference given the leap seconds and the actual UT1 - UTC time difference as measured and published by IERS.

NOTES:

1. The current UT1 - UTC time difference, and polar offsets, historical data and near-term projections are published in the IERS Bulletins

Parameters

  leap_seconds | [s] Leap seconds at the time of observations
  dut1 | [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent.

Returns
  [s] The TT - UT1 time difference that is suitable for use with all calls in this library that require a ut1_to_tt argument. It includes diurnal corrections for libration and ocean tides.

Since
  1.0

Author
  Attila Kovacs

See also
  get_utc_to_tt(), novas_set_time(), novas_gast(), novas_time_gst(), novas_time_lst()

References get_utc_to_tt().

## get_utc_to_tt()

double get_utc_to_tt | ( | int | leap_seconds | ) |

Returns the difference between Terrestrial Time (TT) and Universal Coordinated Time (UTC).

Parameters

  leap_seconds | [s] The current leap seconds (see IERS Bulletins)

Returns
  [s] The TT - UTC time difference

Since
  1.0

Author
  Attila Kovacs

See also
  get_ut1_to_tt()

References NOVAS_TAI_TO_TT.

Referenced by get_ut1_to_tt().

## novas_clock_skew()

double novas_clock_skew | ( | const novas_frame * | frame,
|  | enum novas_timescale | timescale )

Returns the instantaneous incremental rate at which the observer's clock (i.e.

proper time τ) ticks faster than a clock in the specified timescale. I.e., it returns D, which is defined by:

dτobs / dttimescale = (1 + D)

The instantaneous difference in clock rate includes tiny diurnal or orbital variationd for Earth-bound observers as the they cycle through the tidal potential around the geocenter (mainly due to the Sun and Moon). For a closer match to Earth-based timescales (TCG, TT, TAI, GPS, or UTC) you may want to exclude the periodic tidal effects and calculate the averaged observer clock rate over the geocentric cycle (see Eqs. 10.6 and 10.8 of the IERS Conventions 2010), which is provided by novas_mean_clock_skew() instead.

For reduced accuracy frames, the result will be approximate, because the gravitational effect of the Sun and Earth alone may be accounted for.

NOTES:

1. Based on the IERS Conventions 2010, Chapter 10, Eqa. 10.6 / 10.8 but also including the near-Earth tidal effects, and modified for relativistic observer motion.
2. The potential for an observer inside 0.9 planet radii of a major Solar-system body's center will not include the term for that body in the calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 10, see at https://iers-conventions.obspm.fr/content/chapter10/tn36_c10.pdf

Parameters

  frame | The observing frame, defining the observer position as well as the positions of the major solar-system bodies at the time of observation.
  timescale | Reference timescale for the comparison. All timescales except NOVAS_UT1 are supported. (UT1 advances at an irregular rate).

Returns
  The incremental rate at which the observer's proper time clock ticks faster than the specified timescale, or else NAN if the input frame is NULL or uninitialized, or if the timescale is not supported (errno set to EINVAL), or if the frame is configured for full accuracy but it does not have sufficient planet position information to evaluate the local gravitational potential with precision (errno set to EAGAIN).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_mean_clock_skew(), novas_timescale_offset()

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_C_AU_PER_DAY, novas_clock_skew(), NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UTC, novas_vlen(), novas_frame::obs_pos, novas_frame::obs_vel, novas_frame::time, and tt2tdb().

Referenced by supernovas::Frame::clock_skew(), novas_clock_skew(), and novas_mean_clock_skew().

## novas_date()

double novas_date | ( | const char *restrict | date | ) |

Returns a Julian date (in non-specific timescale) corresponding the specified input string date / time.

E.g. for "2025-02-28T09:41:12.041+0200", with some flexibility on how the date is represented as long as it's YMD date followed by HMS time. For other date formats (MDY or DMY) you can use novas_parse_date_format() instead.

Parameters

  date | The date specification, possibly including time and timezone, in a standard format. See novas_parse_date() on more information on acceptable date/time formats.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_date_scale(), novas_parse_date(), novas_parse_date_format(), novas_iso_timestamp()

References novas_parse_date().

## novas_date_scale()

double novas_date_scale | ( | const char *restrict | date,
|  | enum novas_timescale *restrict | scale )

Returns a Julian date and the timescale corresponding the specified input string date/time and timescale marker.

E.g. for "2025-02-28T09:41:12.041+0200 TAI", with some flexibility on how the date is represented as long as it's YMD date followed by HMS time. For other date formats (MDY or DMY) you can use novas_parse_date_format() instead.

Parameters

  | date | The date specification, possibly including time and timezone, in a standard format. See novas_parse_date() on more information on acceptable date/time formats.
  [out] | scale | The timescale constant, or else -1 if the string could not be parsed into a date and timescale. If the string is a bare timestamp without a hint of a timescale marker, then NOVAS_UTC will be assumed.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_date(), novas_timestamp()

References novas_parse_date(), and novas_parse_timescale().

## novas_diff_tcb()

double novas_diff_tcb | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Barycentric Coordinate Time (TCB) based time difference (t1 - t2) in days between two astronomical time specifications.

TCB progresses slightly faster than time on Earth, at a rate about 1.6&times10-8 higher, due to the lack of gravitational time dilation by the Earth or Sun.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise TCB time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcg(), novas_diff_time()

References novas_diff_time().

## novas_diff_tcg()

double novas_diff_tcg | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Geocentric Coordinate Time (TCG) based time difference (t1 - t2) in days between two astronomical time specifications.

TCG progresses slightly faster than time on Earth, at a rate about 7&times10-10 higher, due to the lack of gravitational time dilation by Earth. TCG is an appropriate time measure for a spacecraft that is in the proximity of the orbit of Earth, but far enough from Earth such that the relativistic effects of Earth's gravity can be ignored.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise TCG time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcb(), novas_diff_time()

References novas_diff_time().

## novas_diff_time()

double novas_diff_time | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2 )

Returns the Terrestrial Time (TT) based time difference (t1 - t2) in days between two astronomical time specifications.

Parameters

  t1 | First time
  t2 | Second time

Returns
  [s] Precise time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.1

Author
  Attila Kovacs

See also
  novas_diff_time_scale(), novas_diff_tcb(), novas_diff_tcg(), novas_set_time(), novas_offset_time()

References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.

Referenced by supernovas::Time::equals(), novas_diff_tcb(), novas_diff_tcg(), novas_track_pos(), supernovas::Time::operator<(), and supernovas::Time::operator<=().

## novas_diff_time_scale()

double novas_diff_time_scale | ( | const novas_timespec * | t1,
|  | const novas_timespec * | t2,
|  | enum novas_timescale | timescale )

Returns the UT1 based time difference (t1 - t2) in days between two astronomical time specifications.

Parameters

  t1 | First time
  t2 | Second time
  timescale | Astronomical timescale in which to return the difference.

Returns
  [s] Precise UT1 time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

Since
  1.6

Author
  Attila Kovacs

See also
  novas_diff_time(), novas_diff_tcg(), novas_diff_time()

References novas_get_split_time(), and NOVAS_TIMESCALES.

Referenced by supernovas::Time::offset_from().

## novas_get_split_time()

double novas_get_split_time | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | timescale,
|  | long *restrict | ijd )

Returns the fractional Julian date of an astronomical time in the specified timescale, as an integer and fractional part.

The two-component split of the time allows for absolute precisions at the picosecond level, as opposed to novas_set_time(), whose precision is limited to a few microseconds typically.

The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of the tdb2tt() implementation, to around 10 μs.

REFERENCES:

1. IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
2. IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
3. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
4. Kaplan, G. (2005), US Naval Observatory Circular 179.
5. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
6. https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

  | time | Pointer to the astronomical time specification data structure.
  | timescale | The astronomical time scale in which the returned Julian Date is to be provided
  [out] | ijd | [day] The integer part of the Julian date in the requested timescale. It may be NULL if not required.

Returns
  [day] The fractional part of the Julian date in the requested timescale or NAN if the time argument is NULL (ijd will be set to -1 also).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_split_time(), novas_get_time()

References NOVAS_TIMESCALES.

Referenced by supernovas::Time::jd_day(), supernovas::Time::jd_frac(), supernovas::Time::mjd(), supernovas::Time::mjd_day(), novas_diff_time_scale(), novas_get_time(), novas_get_unix_time(), novas_iso_timestamp(), novas_make_frame(), novas_timestamp(), and supernovas::Time::shifted().

## novas_get_time()

double novas_get_time | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | timescale )

Returns the fractional Julian date of an astronomical time in the specified timescale.

The returned time is accurate to a few μs (microsecond) due to the inherent precision of the double-precision result. For higher precision applications you may use novas_get_split_time() instead, which has an inherent accuracy at the picosecond level.

Parameters

  time | Pointer to the astronomical time specification data structure.
  timescale | The astronomical time scale in which the returned Julian Date is to be provided

Returns
  [day] The Julian date in the requested timescale.

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_get_split_time()

References novas_get_split_time().

Referenced by supernovas::Time::gmst(), supernovas::Time::jd(), novas_approx_sky_pos(), novas_change_observer(), novas_diurnal_eop_at_time(), novas_geom_posvel(), novas_make_frame(), novas_moon_elp_posvel_fp(), novas_site_gcrs_posvel(), novas_site_uvw(), and novas_time_gst().

## novas_get_unix_time()

time_t novas_get_unix_time | ( | const novas_timespec *restrict | time,
|  | long *restrict | nanos )

Returns the UNIX time for an astronomical time instant.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  [out] | nanos | [ns] UTC sub-second component. It may be NULL if not required.

Returns
  [s] The integer UNIX time, or -1 if the input time is NULL.

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_unix_time(), novas_get_time()

References novas_get_split_time(), and NOVAS_UTC.

Referenced by supernovas::Time::unix_time().

## novas_iso_timestamp()

int novas_iso_timestamp | ( | const novas_timespec *restrict | time,
|  | char *restrict | dst,
|  | int | maxlen )

Prints a UTC-based ISO timestamp to millisecond precision to the specified string buffer.

E.g.:

2025-01-26T21:32:49.701Z

NOTES:

1. As per the ISO 8601 specification, the timestamp uses the Gregorian date, even for dates prior to the Gregorian calendar reform of 15 October 1582 (i.e. proleptic Gregorian dates).
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  [out] | dst | Output string buffer. At least 25 bytes are required for a complete timestamp with termination.
  | maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen, then it will be truncated to fit in the allotted space, including a termination character.

Returns
  the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_timestamp(), novas_parse_iso_date()

References novas_get_split_time(), NOVAS_GREGORIAN_CALENDAR, and NOVAS_UTC.

Referenced by supernovas::Time::to_iso_string().

## novas_mean_clock_skew()

double novas_mean_clock_skew | ( | const novas_frame * | frame,
|  | enum novas_timescale | timescale )

Returns the averaged incremental rate at which the observer's clock (i.e.

proper time τ) ticks faster than a clock in the specified timescale. I.e., it returns D, which is defined by:

dτobs / dttimescale = (1 + D)

For a non-Earth-bound observer, this is the same as the instantaneous rate returned by novas_clock_skew(). For an Earth-bound observer however, this function returns the averaged value over the observer's rotation around the geocenter. As such it filters out the tiny diurnal or orbital tidal variations as the observer moves through the tidal potential around the geocenter (mainly due to the Sun and Moon). Thus, for Earth-bound observers it returns Eqs. 10.6 and 10.8 of the IERS Conventions.

For reduced accuracy frames, the result will be approximate, because the gravitational effect of the Sun and Earth alone may be accounted for.

NOTES:

1. Based on the IERS Conventions 2010, Chapter 10, Eqs. 10.6 / 10.8, but modified for relativistic observer motion.
2. The potential for an observer inside 0.9 planet radii of a major Solar-system body's center will not include the term for that body in the calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 10, see at https://iers-conventions.obspm.fr/content/chapter10/tn36_c10.pdf

Parameters

  frame | The observing frame, defining the observer position as well as the positions of the major solar-system bodies at the time of observation.
  timescale | Reference timescale for the comparison. All timescales are supported, except NOVAS_UT1 (since UT1 advances at an irregular rate).

Returns
  The average incremental rate over a geocentric rotation, at which the observer's proper time clock ticks faster than the specified timescale, or else NAN if the input frame is NULL or uninitialized, or if the timescale is not supported (errno set to EINVAL), or if the frame is configured for full accuracy but it does not have sufficient planet position information to evaluate of the local gravitational potential with precision (errno set to EAGAIN).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_clock_skew()

References novas_clock_skew().

## novas_offset_time()

int novas_offset_time | ( | const novas_timespec * | time,
|  | double | seconds,
|  | novas_timespec * | out )

Increments the astrometric time by a given amount.

Parameters

  | time | Original time specification
  | seconds | [s] Seconds to add to the original
  [out] | out | New incremented time specification. It may be the same as the input.

Returns
  0 if successful, or else -1 if either the input or the output is NULL (errno will be set to EINVAL).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_diff_time()

References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.

## novas_print_timescale()

int novas_print_timescale | ( | enum novas_timescale | scale,
|  | char *restrict | buf )

Prints the standard string representation of the timescale to the specified buffer.

The string is terminated after. E.g. "UTC", or "TAI". It will print dates in the Gregorian calendar, which was introduced on 15 October 1582 only.

Parameters

  scale | The timescale
  buf | String in which to print. It should have at least 4-bytes of available storage.

Returns
  the number of characters printed, not including termination, or else -1 if the timescale is invalid or the output buffer is NULL.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_timestamp(), novas_timescale_for_string()

References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

Referenced by novas_timestamp().

## novas_set_current_time()

int novas_set_current_time | ( | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets the time with the UNIX time obtained from the system clock.

This is only as precise as the system clock is. You should generally make sure the sytem clock is synchronized to a time reference e.g. via ntp, preferably to a local time reference.

NOTES:

1. With MSC, this function uses the C11 standard timespec_get() function, which is portable. For older C standard, the POSIX only clock_gettime() function is used.
2. If SuperNOVAS was built with the WITHOUT_SYSTEM_CLOCK preprocessor flag (or with the WITHOUT_LIBC build configuration option), then this function will always return an error (errno set to ENOSYS). You may want to set the time explicitly with one of the other functions instead.
3. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.5

Author
  Attila Kovacs, Kiran Shila

See also
  novas_set_unix_time()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_unix_time().

Referenced by supernovas::Time::now().

## novas_set_split_time()

int novas_set_split_time | ( | enum novas_timescale | timescale,
|  | long | ijd,
|  | double | fjd,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to the split Julian Date value, defined in the specified timescale.

The split into the integer and fractional parts can be done in any convenient way. The highest precision is reached if the fractional part is ≤ 1 day. In that case, the time may be specified to picosecond accuracy, if needed.

The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of tdb2tt() implementation, to around 10 μs.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set leap and dut1 appropriately explicitly.

REFERENCES:

1. IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
2. IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
3. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
4. Kaplan, G. (2005), US Naval Observatory Circular 179.
5. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
6. https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | ijd | [day] integer part of the Julian day in the specified timescale
  | fjd | [day] fractional part Julian day value in the specified timescale
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN and novas_is_auto_fetch_eop() is TRUE, then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_time(), novas_set_unix_time(), novas_get_split_time(), novas_timescale_for_string(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_eop::dut1, novas_eop::leap, novas_diurnal_eop_at_time(), novas_fetch_eop(), novas_is_auto_fetch_eop(), NOVAS_TCB, NOVAS_TDB, NOVAS_TIMESCALES, and tt2tdb_hp().

Referenced by supernovas::Time::Time(), novas_set_time(), novas_set_unix_time(), and supernovas::Time::shifted().

## novas_set_str_time()

int novas_set_str_time | ( | enum novas_timescale | timescale,
|  | const char *restrict | str,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets astronomical time in a specific timescale using a string specification.

It is effectively just a shorthand for using novas_parse_date() followed by novas_set_time() and the error checking in-between.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | str | The astronomical date specification, possibly including time and timezone, in a standard format. The date is assumed to be in the astronomical calendar of date, which differs from ISO 8601 timestamps for dates prior to the Gregorian calendar reform of 1582 October 15 (otherwise, the two are identical). See novas_parse_date() for more on acceptable formats.
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides). If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_set_time(), novas_parse_date()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_parse_date(), and novas_set_time().

Referenced by supernovas::Time::Time().

## novas_set_time()

int novas_set_time | ( | enum novas_timescale | timescale,
|  | double | jd,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to the fractional Julian Date value, defined in the specified timescale.

The time set this way is accurate to a few μs (microseconds) due to the inherent precision of the double-precision argument. For higher precision applications you may use novas_set_split_time() instead, which has an inherent accuracy at the picosecond level.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | timescale | The astronomical time scale in which the Julian Date is given
  | jd | [day] Julian day value in the specified timescale
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides). If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_split_time(), novas_set_unix_time(), novas_set_str_time(), novas_set_current_time(), novas_get_time(), novas_timescale_for_string(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_split_time().

Referenced by supernovas::Time::Time(), and novas_set_str_time().

## novas_set_unix_time()

int novas_set_unix_time | ( | time_t | unix_time,
|  | long | nanos,
|  | int | leap,
|  | double | dut1,
|  | novas_timespec *restrict | time )

Sets an astronomical time to a UNIX time value.

UNIX time is defined as UTC seconds measured since 0 UTC, 1 Jan 1970 (the start of the UNIX era). Specifying time this way supports precisions to the nanoseconds level by construct. Specifying UNIX time in split seconds and nanoseconds is a common way CLIB handles precision time, e.g. with struct timespec and functions like clock_gettime() or the C11 timespec_get (see time.h).

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set leap and dut1 appropriately explicitly.

Parameters

  | unix_time | [s] UNIX time (UTC) seconds
  | nanos | [ns] UTC sub-second component
  | leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. (It may be unused if dut1 is NAN – see below).

  dut1

  [s] mean UT1-UTC time difference, e.g. as published in IERS Bulletin A (without diurnal corrections for libration and ocean tides), If the time offset is defined for a different ITRS realization than what is used for the coordinates of an Earth-based observer, you can use novas_itrf_transform_eop() to make it consistent. If dut1 is NAN, and novas_is_auto_fetch_eop() is TRUE then both leap and dut1 will be fetched from IERS if possible. Note, that prior to 1956 IERS does not provide UT1-UTC difference.

  [out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications.

Returns
  0 if successful, or else -1 if there was an error (errno will be set to indicate the type of error).

Since
  1.1

Author
  Attila Kovacs

See also
  novas_set_current_time(), novas_set_time(), novas_get_unix_time(), novas_diurnal_eop()
  novas_set_auto_fetch_eop(), novas_lookup_leap(), novas_fetch_eop()

References novas_set_split_time(), and NOVAS_UTC.

Referenced by supernovas::Time::Time(), and novas_set_current_time().

## novas_time_gst()

double novas_time_gst | ( | const novas_timespec *restrict | time,
|  | enum novas_accuracy | accuracy )

Returns the Greenwich (apparent) Sidereal Time (GST/GaST) for a given astronomical time specification.

If you need mean sidereal time (GMST), you should use sidereal_time() instead.

Parameters

  time | The astronomical time specification.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).

Returns
  [h] The Greenwich apparent Sidereal Time (GST / GaST) in the [0:24) hour range, or else NAN if there was an error (errno will indicate the type of error).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_time_lst(), novas_set_time()

References novas_gast(), novas_get_time(), and NOVAS_UT1.

Referenced by supernovas::Time::gst(), and novas_time_lst().

## novas_time_leap()

int novas_time_leap | ( | const novas_timespec * | time | ) |

Returns the leap seconds component of an astronomical time specification.

Parameters

  time | The astronomical time specification.

Returns
  [s] The leap seconds that was used to initialize the time specification, or -1 if the input pointer is NULL (errno is set to EINVAL).

Since
  1.6

Author
  Attila Kovacs

References novas_timespec::dut1, and novas_timespec::ut1_to_tt.

Referenced by supernovas::Frame::eop(), and supernovas::Time::leap_seconds().

## novas_time_lst()

double novas_time_lst | ( | const novas_timespec *restrict | time,
|  | double | lon,
|  | enum novas_accuracy | accuracy )

Returns the Local (apparent) Sidereal Time (LST/LaST) for a given astronomical time specification and observer location.

Parameters

  time | The astronomical time specification.
  lon | [deg] The geodetic longitude of the observer.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1).

Returns
  [h] The Local apparent Sidereal Time (LST / LaST) in the [0:24) hour range, or else NAN if there was an error (errno will indicate the type of error).

Since
  1.4

Author
  Attila Kovacs

See also
  novas_frame_lst(), novas_set_time()

References novas_time_gst().

Referenced by supernovas::Time::lst().

## novas_timescale_offset()

double novas_timescale_offset | ( | const novas_timespec * | ts,
|  | enum novas_timescale | timescale,
|  | enum novas_timescale | ref_scale )

Returns the time difference between two different timescales at a specific astrometric time instance.

Parameters

  ts | astrometric time
  timescale | a timescale
  ref_scale | the reference timescale

Returns
  [s] the time difference between the time expressed in the first timescale vs that in the reference timescale, or else NAN if either timescale parameter is invalid.

Since
  1.6

Author
  Attila Kovacs

See also
  novas_clock_skew()

References NOVAS_TIMESCALES.

Referenced by supernovas::Time::timescale_offset().

## novas_timestamp()

int novas_timestamp | ( | const novas_timespec *restrict | time,
|  | enum novas_timescale | scale,
|  | char *restrict | dst,
|  | int | maxlen )

Prints an astronomical timestamp to millisecond precision in the specified timescale to the specified string buffer.

It differs from ISO 8601 timestamps for dates prior to the Gregorian calendar reform of 1582 October 15 (otherwise two are identical). E.g.:

2025-01-26T21:32:49.701 TAI

NOTES:

1. The timestamp uses the astronomical date. That is Gregorian dates after the Gregorian calendar reform of 15 October 1582, and Julian/Roman dates prior to that. This is in contrast to ISO 8601 timestamps, which use Gregorian dates even for dates the precede the calendar reform that introduced them.
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | time | Pointer to the astronomical time specification data structure.
  | scale | The timescale to use.
  [out] | dst | Output string buffer. At least 28 bytes are required for a complete timestamp with termination.
  | maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen, then it will be truncated to fit in the allotted space, including a termination character.

Returns
  the number of characters printed into the string buffer, not including the termination. As such it is at most maxlen - 1.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_iso_timestamp(), novas_parse_date()

References NOVAS_ASTRONOMICAL_CALENDAR, novas_get_split_time(), and novas_print_timescale().

Referenced by supernovas::Time::to_string().

## tdb2tt()

int tdb2tt | ( | double | jd_tdb,
|  | double *restrict | jd_tt,
|  | double *restrict | secdiff )

Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (TDB) Julian date, and returns the TDB-TT time difference also.

It has a maximum error of 10 μs between 1600 and 2200.

This function is wrapped by tt2tdb(), which is typically a lot easier to use as it returns the time difference directly, which can then be used to convert time in both directions with greater ease. For example, to convert a TT-based date to a TDB-based date:

double TDB = TT + tt2tdb(TT) / 86400.0;
tt2tdb
double tt2tdb(double jd_tt)
Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 1...
Definition timescale.c:167

is equivalent to:

double dt;
tdb2tt(TT, NULL, &dt); // Uses TT input so don't attempt to calculate TT here...
double TDB = TT + dt / 86400.0;
tdb2tt
int tdb2tt(double jd_tdb, double *restrict jd_tt, double *restrict secdiff)
Computes the Terrestrial Time (TT) based Julian date corresponding to a Barycentric Dynamical Time (T...
Definition timescale.c:125

NOTES:

1. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.

REFERENCES:

1. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
2. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  | jd_tdb | [day] Barycentric Dynamic Time (TDB) based Julian date.
  [out] | jd_tt | [day] Terrestrial Time (TT) based Julian date. (It may be NULL if not required)
  [out] | secdiff | [s] Difference 'tdb_jd'-'tt_jd', in seconds. (It may be NULL if not required)

Returns
  0

See also
  tt2tdb()

References NOVAS_JD_J2000.

Referenced by tt2tdb().

## tt2tdb()

double tt2tdb | ( | double | jd_tt | ) |

Returns the TDB - TT time difference in seconds for a given TT or TDB date, with a maximum error of 10 μs for dates between 1600 and 2200.

REFERENCES

1. Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
2. Kaplan, G. (2005), US Naval Observatory Circular 179.
3. Moyer, T.D. (1981), Celestial mechanics, Volume 23, Issue 1, pp. 57-68

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date, but Barycentric Dynamical Time (TDB) can also be used here without any loss of precision on the result.

Returns
  [s] TDB - TT time difference.

Since
  1.0

Author
  Attila Kovacs

See also
  tt2tdb_hp(), tt2tdb_fp(), tdb2tt()

References tdb2tt().

Referenced by geo_posvel(), novas_clock_skew(), obs_posvel(), and place().

## tt2tdb_hp()

double tt2tdb_hp | ( | double | jd_tt | ) |

Returns the TDB-TT time difference with high precision.

This implementation uses the full series expansion by Fairhead & Bretagnon 1990, resulting in an accuracy below 100 ns.

NOTES:

1. This function caches the result of the last calculation.

REFERENCES:

1. Fairhead, L., & Bretagnon, P. (1990) A&A, 229, 240

Parameters

  jd_tt | [day] Terrestrial Time (TT) based Julian date, but Barycentric Dynamical Time (TDB)

Returns
  [s] TDB - TT time difference.

Since
  1.4

Author
  Attila Kovacs

See also
  tt2tdb_fp(), tt2tdb()

References tt2tdb_fp().

Referenced by novas_set_split_time().