SuperNOVAS v1.3
The NOVAS C library, made better
Loading...
Searching...
No Matches
timescale.c File Reference

Macros

#define _DEFAULT_SOURCE
 strcasecmp() feature macro starting glibc 2.20 (2014-09-08)
 

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 *restrict time, enum novas_timescale timescale, long *restrict ijd)
 
double novas_get_time (const novas_timespec *restrict time, enum novas_timescale timescale)
 
time_t novas_get_unix_time (const novas_timespec *restrict time, long *restrict nanos)
 
int novas_iso_timestamp (const novas_timespec *restrict time, char *restrict dst, int maxlen)
 
int novas_offset_time (const novas_timespec *time, double seconds, novas_timespec *out)
 
double novas_parse_date (const char *restrict date, char **restrict tail)
 
double novas_parse_date_format (enum novas_calendar_type calendar, enum novas_date_format format, const char *restrict date, char **restrict tail)
 
int novas_print_timescale (enum novas_timescale scale, char *restrict buf)
 
int novas_set_split_time (enum novas_timescale timescale, long ijd, double fjd, int leap, double dut1, novas_timespec *restrict time)
 
int novas_set_time (enum novas_timescale timescale, double jd, int leap, double dut1, novas_timespec *restrict time)
 
int novas_set_unix_time (time_t unix_time, long nanos, int leap, double dut1, novas_timespec *restrict time)
 
enum novas_timescale novas_timescale_for_string (const char *restrict str)
 
int novas_timestamp (const novas_timespec *restrict time, enum novas_timescale scale, char *restrict dst, int maxlen)
 

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
t1First time
t2Second time
Returns
[s] 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
t1First time
t2Second time
Returns
[s] 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
t1First time
t2Second time
Returns
[s] 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 *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
timePointer to the astronomical time specification data structure.
timescaleThe 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_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.

◆ 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
timePointer to the astronomical time specification data structure.
timescaleThe 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 *restrict time,
long *restrict nanos )

Returns the UNIX time for an astronomical time instant.

Parameters
timePointer 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_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. The timestamp uses the conventional date of the time. That is Gregorian dates after the Gregorian calendar reform of 15 October 1582, and Julian/Roman dates prior to that.
  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
timePointer to the astronomical time specification data structure.
[out]dstOutput string buffer. At least 25 bytes are required for a complete timestamp with termination.
maxlenThe 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_time()

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
timeOriginal time specification
seconds[s] Seconds to add to the original
[out]outNew 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_parse_date()

double novas_parse_date ( const char *restrict date,
char **restrict tail )

Parses a date/time string into a Julian date specification. Typically the date may be an ISO date specification, but with some added flexibility. The date must be YMD-type with full year, followed the month (numerical or name or 3-letter abbreviation), and the day. The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ;, or underscore _ or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else {+/-}HH[:[MM]] time zone specification.

For example:

 2025-01-26
 2025 January 26
 2025_Jan_26
 2025-01-26T19:33:08Z
 2025.01.26T19:33:08
 2025 1 26 19h33m28.113
 2025/1/26 19:33:28+02
 2025-01-26T19:33:28-0600
 2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

NOTES:

  1. This function uses Gregorian dates since their introduction on 1582 October 15, and Julian/Roman datew before that, as was the convention of the time. I.e., the day before of the introduction of the Gregorian calendar reform is 1582 October 4.

  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
dateThe date specification, possibly including time and timezone, in a standard format.
[out]tail(optional) If not NULL it will be set to the next character in the string after the parsed time. The parsing will consume empty space characters after the time specification also, returning a pointer to the next token after.
Returns
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_parse_date_format()
novas_timescale_for_string()
novas_iso_timestamp()
novas_timestamp()

References NOVAS_ASTRONOMICAL_CALENDAR, novas_parse_date_format(), and NOVAS_YMD.

◆ novas_parse_date_format()

double novas_parse_date_format ( enum novas_calendar_type calendar,
enum novas_date_format format,
const char *restrict date,
char **restrict tail )

Parses a calndar date/time string, expressed in the specified type of calendar, into a Julian day (JD). The date must be composed of a full year (e.g. 2025), a month (numerical or name or 3-letter abbreviation, e.g. "01", "1", "January", or "Jan"), and a day (e.g. "08" or "8"). The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The components will be parsed in the specified order.

The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ; or underscore '_', or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else by a {+/-}HH[:[MM]] time zone specification.

For example, for format NOVAS_YMD, all of the following strings may specify the date:

 2025-01-26
 2025 January 26
 2025_Jan_26
 2025-01-26T19:33:08Z
 2025.01.26T19:33:08
 2025 1 26 19h33m28.113
 2025/1/26 19:33:28+02
 2025-01-26T19:33:28-0600
 2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

If your date format cannot be parsed with this function, you may parse it with your own function into year, month, day, and decimal hour-of-day components, and use julian_date() with those.

NOTES:

  1. 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
calendarThe type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
formatExpected order of date components: NOVAS_YMD, NOVAS_DMY, or NOVAS_MDY.
dateThe date specification, possibly including time and timezone, in the specified standard format.
[out]tail(optional) If not NULL it will be set to the next character in the string after the parsed time. The parsing will consume empty space characters after the time specification also, returning a pointer to the next token after.
Returns
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_parse_date()
novas_timescale_for_string()
novas_iso_timestamp()
julian_date()

References novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DMY, novas_get_debug_mode(), novas_jd_from_date(), NOVAS_MDY, novas_parse_hms(), and NOVAS_YMD.

◆ 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
scaleThe timescale
bufString 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.

◆ 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
timescaleThe 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]timePointer 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()
novas_timescale_for_string()
Since
1.1
Author
Attila Kovacs

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

◆ 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
timescaleThe 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]timePointer 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()
novas_timescale_for_string()
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 *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() (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]timePointer 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.

◆ novas_timescale_for_string()

enum novas_timescale novas_timescale_for_string ( const char *restrict str)

Returns the timescale constant for a string that denotes the timescale in with a standard abbreviation (case insensitive). The following values are recognised: "UTC", "UT", "UT0", "UT1", "GMT", "TAI", "GPS", "TT", "ET", "TCG", "TCB", "TDB".

Parameters
strString specifying an astronomical timescale
Returns
The SuperNOVAS timescale constant (<=0), or else -1 if the string was NULL, empty, or could not be matched to a timescale value (errno will be set to EINVAL also).
Since
1.3
Author
Attila Kovacs
See also
novas_set_time()
novas_set_split_time()
novas_print_timescale()

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

◆ novas_timestamp()

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

Prints a timestamp to millisecond precision in the specified timescale to the specified string buffer. 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.

  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
timePointer to the astronomical time specification data structure.
scaleThe timescale to use.
[out]dstOutput string buffer. At least 28 bytes are required for a complete timestamp with termination.
maxlenThe 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()

References novas_get_split_time(), and novas_print_timescale().