Functions
double	novas_diff_tcb (const novas_timespec t1, const novas_timespec t2)

double	novas_diff_tcg (const novas_timespec t1, const novas_timespec t2)

double	novas_diff_time (const novas_timespec t1, const novas_timespec t2)

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

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

time_t	novas_get_unix_time (const novas_timespec time, long nanos)

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

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

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

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

Detailed Description

Date: Created on Jun 24, 2024

Author: Attila Kovacs

Since: 1.1

A set of SuperNOVAS routines to make handling of astronomical timescales and conversions among them easier.

See also: frames.c

Function Documentation

◆ 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: [day] Precise TCB time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

See also: novas_diff_tcg(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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: [day] Precise TCG time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

See also: novas_diff_tcb(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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: [day] Precise time difference (t1-t2), or NAN if one of the inputs was NULL (errno will be set to EINVAL)

See also: novas_set_time(); novas_offset_time(); novas_diff_tcb(); novas_diff_tcg()

Since: 1.1

Author: Attila Kovacs

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

◆ novas_get_split_time()

double novas_get_split_time	(	const novas_timespec *	time,
		enum novas_timescale	timescale,
		long *	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:

IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
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 is the time argument is NULL (ijd will be set to -1 also).

See also: novas_set_split_time(); novas_get_time()

Since: 1.1

Author: Attila Kovacs

References novas_timespec::dut1, novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, novas_timespec::tt2tdb, and novas_timespec::ut1_to_tt.

◆ novas_get_time()

double novas_get_time	(	const novas_timespec *	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.

See also: novas_set_time(); novas_get_split_time()

Since: 1.1

Author: Attila Kovacs

References novas_get_split_time().

◆ novas_get_unix_time()

time_t novas_get_unix_time	(	const novas_timespec *	time,
		long *	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.

See also: novas_set_unix_time(); novas_get_time()

Since: 1.1

Author: Attila Kovacs

References novas_get_split_time(), and NOVAS_UTC.

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

See also: novas_set_time(); novas_diff_time()

Since: 1.1

Author: Attila Kovacs

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

◆ novas_set_split_time()

int novas_set_split_time	(	enum novas_timescale	timescale,
		long	ijd,
		double	fjd,
		int	leap,
		double	dut1,
		novas_timespec *	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:

IAU 1991, RECOMMENDATION III. XXIst General Assembly of the International Astronomical Union. Retrieved 6 June 2019.
IAU 2006 resolution 3, see Recommendation and footnotes, note 3.
Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html
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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[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).

See also: novas_set_time(); novas_set_unix_time(); novas_get_split_time()

Since: 1.1

Author: Attila Kovacs

References novas_timespec::dut1, novas_timespec::fjd_tt, novas_timespec::ijd_tt, NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, novas_timespec::tt2tdb, tt2tdb(), and novas_timespec::ut1_to_tt.

◆ novas_set_time()

int novas_set_time	(	enum novas_timescale	timescale,
		double	jd,
		int	leap,
		double	dut1,
		novas_timespec *	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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[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).

See also: novas_set_split_time(); novas_set_unix_time(); novas_get_time()

Since: 1.1

Author: Attila Kovacs

References novas_set_split_time().

◆ novas_set_unix_time()

int novas_set_unix_time	(	time_t	unix_time,
		long	nanos,
		int	leap,
		double	dut1,
		novas_timespec *	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() (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] UT1-UTC time difference, e.g. as published in IERS Bulletin A.
[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).

See also: novas_set_time(); novas_get_unix_time(); clock_gettime(); struct timespec

Since: 1.1

Author: Attila Kovacs

References novas_set_split_time(), and NOVAS_UTC.

Functions

Detailed Description

Function Documentation

◆ novas_diff_tcb()

◆ novas_diff_tcg()

◆ novas_diff_time()

◆ novas_get_split_time()

◆ novas_get_time()

◆ novas_get_unix_time()

◆ novas_offset_time()

◆ novas_set_split_time()

◆ novas_set_time()

◆ novas_set_unix_time()