Data Structures
struct	novas_timespec
	A structure, which defines a precise instant of time that can be extpressed in any of the astronomical timescales. More...

Macros
#define	NOVAS_DAY 86400.0
	[s] The length of a synodic day, that is 24 hours exactly.

#define	NOVAS_GPS_TO_TAI 19.0
	[s] TAI - GPS time offset

#define	NOVAS_JD_B1900 15019.81352
	[day] Julian date at B1900 precession(), transform_cat()

#define	NOVAS_JD_B1950 2433282.42345905
	[day] Julian date at B1950 precession(), transform_cat()

#define	NOVAS_JD_HIP 2448349.0625
	[day] Julian date for J1991.25, which the Hipparcos catalog is referred to.

#define	NOVAS_JD_J2000 2451545.0
	[day] Julian date at J2000

#define	NOVAS_JD_MJD0 2400000.5
	[day] Julian date at which the Modified Julian Date (MJD) is zero

#define	NOVAS_JD_START_GREGORIAN 2299160.5
	[day] The Julian day the Gregorian calendar was introduced in 15 October 1582.

#define	NOVAS_JULIAN_YEAR_DAYS 365.25
	[day] The length of a tropical year (at J2000) in days.

#define	NOVAS_TAI_TO_TT 32.184
	[s] TT - TAI time offset

#define	NOVAS_TIMESPEC_INIT
	Empty initializer for novas_timespec.

#define	NOVAS_TROPICAL_YEAR_DAYS 365.2421897
	[day] The length of a tropical year (at J2000) in days.

Enumerations
enum	novas_calendar_type { NOVAS_ROMAN_CALENDAR = -1 , NOVAS_ASTRONOMICAL_CALENDAR , NOVAS_GREGORIAN_CALENDAR }
	Constants to disambiguate which type of calendar yo use for interpreting calendar dates. More...

enum	novas_date_format { NOVAS_YMD = 0 , NOVAS_DMY , NOVAS_MDY }
	The general order of date components for parsing. More...

enum	novas_timescale { NOVAS_TCB = 0 , NOVAS_TDB , NOVAS_TCG , NOVAS_TT , NOVAS_TAI , NOVAS_GPS , NOVAS_UTC , NOVAS_UT1 }
	Constants to reference various astrnomical timescales used. More...

Functions
int	cal_date (double tjd, short restrict year, short restrict month, short restrict day, double restrict hour)
	This function will compute a broken down date on the astronomical calendar given the Julian day input.

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	julian_date (short year, short month, short day, double hour)
	Returns the Julian day for a given astronomical calendar date.

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.

int	novas_day_of_week (double tjd)
	Returns the one-based ISO 8601 day-of-week index of a given Julian Date.

int	novas_day_of_year (double tjd, enum novas_calendar_type calendar, int *restrict year)
	Returns the one-based day index in the calendar year for a given Julian Date.

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_epoch (const char *restrict system)
	Returns the Julian day corresponding to an astronomical coordinate epoch.

double	novas_frame_lst (const novas_frame *restrict frame)
	Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.

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_jd_from_date (enum novas_calendar_type calendar, int year, int month, int day, double hour)
	Returns the Julian day for a given calendar date.

int	novas_jd_to_date (double tjd, enum novas_calendar_type calendar, int restrict year, int restrict month, int restrict day, double restrict hour)
	This function will compute a broken down date on the specified calendar for given the Julian day input.

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.

double	novas_next_moon_phase (double phase, double jd_tdb)
	Calculates the date / time at which the Moon will reach the specified phase next, after the specified time.

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.

double	novas_rises_above (double el, const object restrict source, const novas_frame restrict frame, RefractionModel ref_model)
	Returns the UTC date at which a distant source appears to rise above the specified elevation angle.

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_sets_below (double el, const object restrict source, const novas_frame restrict frame, RefractionModel ref_model)
	Returns the UTC date at which a distant source appears to set below the specified elevation angle.

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.

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

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.

double	novas_transit_time (const object restrict source, const novas_frame restrict frame)
	Returns the UTC date at which a source transits the local meridian.

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

Macro Definition Documentation

◆ NOVAS_DAY

#define NOVAS_DAY 86400.0

[s] The length of a synodic day, that is 24 hours exactly.

Since: 1.2

◆ NOVAS_JD_HIP

#define NOVAS_JD_HIP 2448349.0625

[day] Julian date for J1991.25, which the Hipparcos catalog is referred to.

See also: precession(), transform_cat()

◆ NOVAS_JD_START_GREGORIAN

#define NOVAS_JD_START_GREGORIAN 2299160.5

[day] The Julian day the Gregorian calendar was introduced in 15 October 1582.

The day prior to that was 4 October 1582 in the Julian Calendar.

◆ NOVAS_JULIAN_YEAR_DAYS

#define NOVAS_JULIAN_YEAR_DAYS 365.25

[day] The length of a tropical year (at J2000) in days.

Since: 1.5

◆ NOVAS_TIMESPEC_INIT

#define NOVAS_TIMESPEC_INIT

Empty initializer for novas_timespec.

Since: 1.3

See also: novas_timespec

◆ NOVAS_TROPICAL_YEAR_DAYS

#define NOVAS_TROPICAL_YEAR_DAYS 365.2421897

[day] The length of a tropical year (at J2000) in days.

Since: 1.5

Enumeration Type Documentation

◆ novas_calendar_type

enum novas_calendar_type

Constants to disambiguate which type of calendar yo use for interpreting calendar dates.

Roman/Julian or Gregorian/

Since: 1.3

Author: Attila Kovacs

See also: novas_jd_from_date(), novas_jd_to_date()

Enumerator

NOVAS_ROMAN_CALENDAR

The Roman (a.k.a. Julian) calendar by Julius Caesar, introduced in -45 B.C.

NOVAS_ASTRONOMICAL_CALENDAR

Roman (a.k.a.

Julian) calendar until the Gregorian calendar reform of 1582, after which it is the Gregorian calendar

NOVAS_GREGORIAN_CALENDAR

The Gregorian calendar introduced on 15 October 1582, the day after 4 October 1582 in the Roman (a.k.a.

Julian) calendar.

◆ novas_date_format

enum novas_date_format

The general order of date components for parsing.

Since: 1.3

Author: Attila Kovacs

See also: novas_parse_date_format()

Enumerator
NOVAS_YMD	year, then month, then day.
NOVAS_DMY	day, then month, then year
NOVAS_MDY	month, then day, then year

◆ novas_timescale

enum novas_timescale

Constants to reference various astrnomical timescales used.

Since: 1.1

See also: novas_set_time(), novas_get_time(), novas_diff_time(), novas_clock_skew(), NOVAS_TIMESCALES; timescale.c

Enumerator
NOVAS_TCB	Barycentric Coordinate Time (TCB)
NOVAS_TDB	Barycentric Dynamical Time (TDB)
NOVAS_TCG	Geocentric Coordinate Time (TCG)
NOVAS_TT	Terrestrial Time (TT)
NOVAS_TAI	Innternational Atomic Time (TAI)
NOVAS_GPS	GPS Time.
NOVAS_UTC	Universal Coordinated Time (UTC)
NOVAS_UT1	UT1 earth rotation time, based on the measured Earth orientation parameters published in IERS Bulletin A.

Function Documentation

◆ cal_date()

int cal_date	(	double	tjd,
		short *restrict	year,
		short *restrict	month,
		short *restrict	day,
		double *restrict	hour )

This function will compute a broken down date on the astronomical calendar given the Julian day input.

Input Julian day can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

The Gregorian calendar was introduced on 15 October 1582 only (corresponding to 5 October of the previously used Julian calendar). Prior to it this function returns Julian / Roman calendar dates, e.g. the day before the reform is 1582 October 4. You can use novas_jd_to_date() instead to convert JD days to dates in specific calendars.
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.

REFERENCES:

Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

	tjd	[day] Julian date
[out]	year	[yr] Astronomical calendar year. It may be NULL if not required. B.C. years are represented as <=0, i.e. 1 B.C. as 0 and X B.C. as (1 - X)
[out]	month	[month] Astronomical calendar month [1:12]. It may be NULL if not required.
[out]	day	[day] Day of the month [1:31]. It may be NULL if not required.
[out]	hour	[h] Hour of day [0:24]. It may be NULL if not required.

Returns: 0

See also: novas_jd_to_date(); novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_to_date().

◆ 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:

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] UT1 - UTC time difference [-0.5:0.5]

Returns: [s] The TT - UT1 time difference that is suitable for used with all calls in this library that require a ut1_to_tt argument.

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.

◆ julian_date()

double julian_date	(	short	year,
		short	month,
		short	day,
		double	hour )

Returns the Julian day for a given astronomical calendar date.

Input time value can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output Julian day will have the same basis.

NOTES:

The Gregorian calendar was introduced on 1582 October 15 only. Prior to that, astronomical dates are Julian/Roman dates, so the day before the reform was 1582 October 4. You can also use novas_jd_from_date() to convert dates with more flexibility.
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.
Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

year	[yr] Astronomical calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
month	[month] Astronomical calendar month [1:12]
day	[day] Astronomical day of month [1:31]
hour	[hr] Hour of day [0:24]

Returns: [day] the fractional Julian date for the input calendar date, ot NAN if the month or day components are out of range.

See also: novas_jd_from_date(); get_utc_to_tt(), get_ut1_to_tt(), tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_from_date().

◆ 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:

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

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

References novas_timespec::fjd_tt, novas_timespec::ijd_tt, 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().

◆ 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_day_of_week()

int novas_day_of_week ( double tjd )

Returns the one-based ISO 8601 day-of-week index of a given Julian Date.

The ISO 8601 week begins on Monday, thus index 1 corresponds to Monday, while index 7 is a Sunday.

Parameters

tjd	[day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).

Returns: [1:7] The day-of-week index in the same timescale as the input date. 1:Monday ... 7:Sunday.

Since: 1.4

Author: Attila Kovacs

See also: novas_day_of_year(), novas_jd_to_date()

References NOVAS_JD_J2000.

◆ novas_day_of_year()

int novas_day_of_year	(	double	tjd,
		enum novas_calendar_type	calendar,
		int *restrict	year )

Returns the one-based day index in the calendar year for a given Julian Date.

Parameters

	tjd	[day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).
	calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
[out]	year	[yr] Optional pointer to which to return the calendar year. It may be NULL if not required.

Returns: [1:366] The day-of-year index in the same timescale as the input date.

Since: 1.4

Author: Attila Kovacs

See also: novas_day_of_week(), novas_jd_to_date()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_JD_START_GREGORIAN, novas_jd_to_date(), and NOVAS_ROMAN_CALENDAR.

◆ 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_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_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_set_time(), novas_offset_time(), novas_diff_tcb(), novas_diff_tcg()

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

◆ novas_epoch()

double novas_epoch ( const char *restrict system )

Returns the Julian day corresponding to an astronomical coordinate epoch.

Parameters

system Coordinate system, e.g. "ICRS", "B1950.0", "J2000.0", "FK4", "FK5", "1950", "2000", or "HIP". In general, any Besselian or Julian year epoch can be used by year (e.g. "B1933.193" or "J2022.033"), or else the fixed values listed. If 'B' or 'J' is ommitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0.

Returns: [day] The Julian day corresponding to the given coordinate epoch, or else NAN if the input string is NULL or the input is not recognised as a coordinate epoch specification (errno will be set to EINVAL).

Since: 1.3

Author: Attila Kovacs

See also: make_cat_object_sys(), make_redshifted_object_sys(), transform_cat(), precession(); NOVAS_SYSTEM_ICRS, NOVAS_SYSTEM_B1950, NOVAS_SYSTEM_J2000, NOVAS_SYSTEM_HIP

References NOVAS_JD_B1950, NOVAS_JD_HIP, NOVAS_JD_J2000, NOVAS_SYSTEM_FK4, NOVAS_SYSTEM_FK5, NOVAS_SYSTEM_HIP, and NOVAS_SYSTEM_ICRS.

◆ novas_frame_lst()

double novas_frame_lst ( const novas_frame *restrict frame )

Returns the Local (apparent) Sidereal Time for an observing frame of an Earth-bound observer.

Parameters

frame Observer frame, defining the location and time of observation

Returns: [h] The LST for an Earth-bound observer [0.0–24.0), or NAN otherwise. If NAN is returned errno will indicate the type of error.

Since: 1.3

Author: Attila Kovacs

See also: novas_time_lst()

References NOVAS_AIRBORNE_OBSERVER, and NOVAS_OBSERVER_ON_EARTH.

◆ 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:

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

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.

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

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

◆ 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:

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

◆ novas_jd_from_date()

double novas_jd_from_date	(	enum novas_calendar_type	calendar,
		int	year,
		int	month,
		int	day,
		double	hour )

Returns the Julian day for a given calendar date.

Input time value can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output Julian date will have the same basis.

The input date is the conventional calendar date, affected by the Gregorian calendar reform of

Thus, the input date is for the Gregorian calendar for dates starting 15 October 1582, and for the Julian (Roman) calendar (introduced in 45 B.C.) for dates prior to that.

NOTES:

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.
Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
year	[yr] Calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
month	[month] Calendar month [1:12]
day	[day] Day of month [1:31]
hour	[hr] Hour of day [0:24]

Returns: [day] the fractional Julian day for the input calendar date, ot NAN if the calendar is invalid or the month or day components are out of range.

Author: Attila Kovacs

Since: 1.3

See also: novas_jd_to_date(), novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

◆ novas_jd_to_date()

int novas_jd_to_date	(	double	tjd,
		enum novas_calendar_type	calendar,
		int *restrict	year,
		int *restrict	month,
		int *restrict	day,
		double *restrict	hour )

This function will compute a broken down date on the specified calendar for given the Julian day input.

Input Julian day can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

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.

REFERENCES:

Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

	tjd	[day] Julian day.
	calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
[out]	year	[yr] Calendar year. B.C. years are represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X). It may be NULL if not required.
[out]	month	[month] Calendar month [1:12]. It may be NULL if not required.
[out]	day	[day] Day of the month [1:31]. It may be NULL if not required.
[out]	hour	[h] Hour of day [0:24]. It may be NULL if not required.

Returns: 0 if successful, or else -1 if the calendar is invalid (errno will be set to EINVAL).

Since: 1.3

Author: Attila Kovacs

See also: novas_jd_from_date(), novas_set_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

◆ 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:

Based on the IERS Conventions 2010, Chapter 10, Eqs. 10.6 / 10.8, but modified for relativistic observer motion.
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:

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

double novas_next_moon_phase	(	double	phase,
		double	jd_tdb )

Calculates the date / time at which the Moon will reach the specified phase next, after the specified time.

It uses orbital models for Earth (E.M. Standish and J.G. Williams 1992), and for the Moon (Chapront, J. et al., 2002), and takes into account the slightly eccentric nature of both orbits.

NOTES:

The Moon's phase here follows the definition by the Astronomical Almanac, as the excess ecliptic longitude of the Moon over that of the Sun seen from the geocenter.
There are other definitions of the phase too, depending on which you might find slightly different answers, but regardless of the details most phase calculations should match give or take a few hours.

REFERENCES:

The Explanatory Supplement to the Astronomical Almanac, University Science Books, 3rd ed., p. 507
E.M. Standish and J.G. Williams 1992.
https://ssd.jpl.nasa.gov/planets/approx_pos.html
Chapront, J. et al., 2002, A&A 387, 700–709
Chapront-Touze, M, and Chapront, J. 1983, Astronomy and Astrophysics (ISSN 0004-6361), vol. 124, no. 1, July 1983, p. 50-62.

Parameters

phase	[deg] The Moon's phase, or more precisely the ecliptic longitude difference between the Sun and the Moon, as seen from the geocenter. 0: New Moon, 90: 1st quarter, +/- 180 Full Moon, -90: 3rd quarter.
jd_tdb	[day] The lower bound date for the phase, as a Barycentric Dynamical Time (TDB) based Julian Date.

Returns: [day] The Barycentric Dynamical Time (TDB) based Julian Date when the Moon will be in the desired phase next after the input date; or NAN if the solution failed to converge (errno will be set to ECANCELED).

Since: 1.4

Author: Attila Kovacs

See also: novas_moon_phase(), novas_make_moon_orbit()

References novas_inv_max_iter, NOVAS_JD_J2000, and novas_moon_phase().

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

◆ novas_rises_above()

double novas_rises_above	(	double	el,
		const object *restrict	source,
		const novas_frame *restrict	frame,
		RefractionModel	ref_model )

Returns the UTC date at which a distant source appears to rise above the specified elevation angle.

The calculated time will account for the (slow) motion for Solar-system bodies, and optionally for atmospheric refraction also.

NOTES:

The current implementation is not suitable for calculating the nearest successive rise times for near-Earth objects, at or within the geostationary orbit.
This function calculates the time when the center (not the limb!) of the source rises above the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

el	[deg] Elevation angle.
source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.
ref_model	Refraction model, or NULL to calculate unrefracted rise time.

Returns: [day] UTC-based Julian date at which the object rises above the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour period.

Since: 1.3

Author: Attila Kovacs

See also: novas_sets_below(), novas_transit_time()

◆ 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:

For C11 or later, 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] UT1-UTC time difference, e.g. as published in IERS Bulletin A, and possibly corrected for diurnal and semi-diurnal variations, e.g. via `novas_diurnal_eop()`. 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	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().

◆ 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:

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, and possibly corrected for diurnal and semi-diurnal variations, e.g. via `novas_diurnal_eop()`. 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	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_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, and tt2tdb().

◆ 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] UT1-UTC time difference, e.g. as published in IERS Bulletin A, and possibly corrected for diurnal and semi-diurnal variations, e.g. via `novas_diurnal_eop()`. 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	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().

◆ 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] UT1-UTC time difference, e.g. as published in IERS Bulletin A, and possibly corrected for diurnal and semi-diurnal variations, e.g. via `novas_diurnal_eop()`. 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	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().

◆ 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] UT1-UTC time difference, e.g. as published in IERS Bulletin A, and possibly corrected for diurnal and semi-diurnal variations, e.g. via `novas_diurnal_eop()`. 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	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(), and NOVAS_UTC.

◆ novas_sets_below()

double novas_sets_below	(	double	el,
		const object *restrict	source,
		const novas_frame *restrict	frame,
		RefractionModel	ref_model )

Returns the UTC date at which a distant source appears to set below the specified elevation angle.

The calculated time will account for the (slow) motion of Solar-system bodies, and optionally for atmopsheric refraction also.

NOTES:

The current implementation is not suitable for calculating the nearest successive set times for near-Earth objects, at or within the geostationary orbit.
This function calculates the time when the center (not the limb!) of the source sets below the specified elevation threshold. Something to keep in mind for calculating Sun/Moon rise times.

Parameters

el	[deg] Elevation angle.
source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.
ref_model	Refraction model, or NULL to calculate unrefracted setting time.

Returns: [day] UTC-based Julian date at which the object sets below the specified elevation next after the specified date, or else NAN if the source stays above or below the given elevation for the entire 24-hour day..

Since: 1.3

Author: Attila Kovacs

See also: novas_rises_above(), novas_transit_time()

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

◆ 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", and "TDB".

Parameters

str	String 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_parse_timescale(), novas_set_str_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 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:

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

◆ novas_transit_time()

double novas_transit_time	(	const object *restrict	source,
		const novas_frame *restrict	frame )

Returns the UTC date at which a source transits the local meridian.

The calculated time will account for the (slow) motion of Solar-system bodies.

NOTES:

The current implementation is not suitable for calculating the nearest successive transit times for near-Earth objects, at or within the geostationary orbit.

Parameters

source	Observed source
frame	Observing frame, defining the observer location and astronomical time of observation.

Returns: [day] UTC-based Julian date at which the object transits the local meridian next after the specified date, or NAN if either input pointer is NULL.

Since: 1.3

Author: Attila Kovacs

See also: novas_rises_above(), novas_sets_below()

◆ 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;

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:175

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:

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:

Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
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.

◆ 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

Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys. 229, 240.
Kaplan, G. (2005), US Naval Observatory Circular 179.
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().

◆ tt2tdb_fp()

double tt2tdb_fp	(	double	jd_tt,
		double	limit )

Returns the TDB-TT time difference with flexible precision.

This implementation uses the series expansion by Fairhead & Bretagnon 1990, terminating the terms at or below the specified limiting amplitude.

REFERENCES:

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

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian date, but Barycentric Dynamical Time (TDB)
limit	[us] Amplitude of limiting term to include in series. 0 or negative values will include all terms, producing the same result as `tt2tdb_hp()`.

Returns: [s] TDB - TT time difference.

Since: 1.4

Author: Attila Kovacs

See also: tt2tdb_hp(), tt2tdb()

References NOVAS_JD_J2000.

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

REFERENCES:

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

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NOVAS_DAY

◆ NOVAS_JD_HIP

◆ NOVAS_JD_START_GREGORIAN

◆ NOVAS_JULIAN_YEAR_DAYS

◆ NOVAS_TIMESPEC_INIT

◆ NOVAS_TROPICAL_YEAR_DAYS

Enumeration Type Documentation

◆ novas_calendar_type

◆ novas_date_format

◆ novas_timescale

Function Documentation

◆ cal_date()

◆ get_ut1_to_tt()

◆ get_utc_to_tt()

◆ julian_date()

◆ novas_clock_skew()

◆ novas_date()

◆ novas_date_scale()

◆ novas_day_of_week()

◆ novas_day_of_year()

◆ novas_diff_tcb()

◆ novas_diff_tcg()

◆ novas_diff_time()

◆ novas_epoch()

◆ novas_frame_lst()

◆ novas_get_split_time()

◆ novas_get_time()

◆ novas_get_unix_time()

◆ novas_iso_timestamp()

◆ novas_jd_from_date()

◆ novas_jd_to_date()

◆ novas_mean_clock_skew()

◆ novas_next_moon_phase()

◆ novas_offset_time()

◆ novas_print_timescale()

◆ novas_rises_above()

◆ novas_set_current_time()

◆ novas_set_split_time()

◆ novas_set_str_time()

◆ novas_set_time()

◆ novas_set_unix_time()

◆ novas_sets_below()

◆ novas_time_lst()

◆ novas_timescale_for_string()

◆ novas_timestamp()

◆ novas_transit_time()

◆ tdb2tt()

◆ tt2tdb()

◆ tt2tdb_fp()

◆ tt2tdb_hp()