timescale.c File Reference

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

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 eith 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.
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 retuns th 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

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 <a href="https://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html>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 / dt_timescale = (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

Observing frames	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()

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_AU, NOVAS_C, 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_tdb(), 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 tbd2tt() implemenation, 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 of observation and astronomical timescales	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 is 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_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

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 of observation and astronomical timescales	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_moon_elp_posvel_fp(), 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 of observation and astronomical timescales	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 E9, novas_get_split_time(), NOVAS_UTC, and UNIX_UTC_J2000.

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 of observation and astronomical timescales	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 / dt_timescale = (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

Observing frames	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 of observation and astronomical timescales	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 in was introduced on 15 October 1582 only. Thus the

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 eith 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.

NOTE:

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.

Parameters

	leap	[s] Leap seconds, e.g. as published by IERS Bulletin C.
	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.
[out]	Time of observation and astronomical timescales	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_unix_time()

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 tbd2tt() 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

	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.
	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.
[out]	Time of observation and astronomical timescales	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()

References novas_diurnal_eop_at_time(), NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, 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.

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.
	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.
[out]	Time of observation and astronomical timescales	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()

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.

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.
	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.
[out]	Time of observation and astronomical timescales	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()

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).

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.
	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.
[out]	Time of observation and astronomical timescales	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()

References novas_set_split_time(), NOVAS_UTC, and UNIX_UTC_J2000.

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 of observation and astronomical timescales	The astronomoical 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 of observation and astronomical timescales

The astronomoical 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 of observation and astronomical timescales	The astronomoical 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_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 of observation and astronomical timescales	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 retuns th TDB-TT time difference also.

It has a maximum error of 10 μs between for dates 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 exable to convert a TT-based date to a TDB-based date:

double TDB = TT + tt2tdb(TT) / 86400.0;

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;

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<.li>

Parameters

jd_tt

[day] Terrestrial Time (TT) based Julian date, but Barycentri 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().