Earth orientation

Earth Orientation Parameters (EOP), for defining the unmodelled (via the IAU 2000 / 2006 precession-nutation models) polar motion and rotational variations of the physical Earth. More...

Classes
class	supernovas::EOP
	IERS Earth Orientation Parameters (EOP). More...

Typedefs
typedef int(*	novas_nutation_provider) (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)
	Function type definition for the IAU 2000 nutation series calculation.

Functions
novas_nutation_provider	get_nutation_lp_provider ()
	Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().
int	novas_get_eop_itrf_year (enum novas_eop_series series)
	Returns the ITRF realization year for a given IERS Earth Orientation Parameter (EOP) series.
const char *	novas_get_eop_url (enum novas_eop_series series)
	Returns the URL currently configured for a given IERS Earth Orientation Parameter (EOP) series.
int	novas_is_auto_fetch_eop ()
	Checks if automatic fetching of Earth Orientation Parameter values from IERS is allowed.
int	novas_lookup_leap (time_t t)
	Returns the leap seconds for the given UNIX timestamp, based either on a locally supplied leap seconds list (see novas_set_leap_list()), or else from data obtained as needed from IERS (provided that fetching it is allowed).
int	novas_set_auto_fetch_eop (int enabled)
	Disable or Re-enabled the automatic fetching of Earth Orientation Parameter values from IERS, when these are left undefined (NAN) when initializing astrometric time or observing frame instances.
int	novas_set_eop_url (enum novas_eop_series series, int itrf_year, const char *url)
	Specify a URL to use for a given IERS Earth Orientation Parameter (EOP) series.
int	novas_set_leap_list (const char *filename)
	Specifies a local file containing the official leap seconds list, i.e.
int	set_nutation_lp_provider (novas_nutation_provider func)
	Set the function to use for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Detailed Description

Earth Orientation Parameters (EOP), for defining the unmodelled (via the IAU 2000 / 2006 precession-nutation models) polar motion and rotational variations of the physical Earth.

EOP are necessary to transform between pseudo Earth-fixed (e.g. the Terrestrial Intermediate Reference System [TIRS]) and the Earth-fixed International Terrestrial Reference System (ITRS). They are essential for precise calculations for Earth-based observers.

IERS publishes daily Earth orientation data, in various ITRF realizations. For the utmost accuracy (below the mas-level), these must be further corrected for diurnal variations caused by librarion and the oceans tides, which is something that SuperNOVAS does automatically when defining astrometric time or an observing frame with the interpolated published EOP values.

Typedef Documentation

novas_nutation_provider

typedef int(* novas_nutation_provider) (double jd_tt_high, double jd_tt_low, double *restrict dpsi, double *restrict deps)

Function type definition for the IAU 2000 nutation series calculation.

Parameters

	jd_tt_high	[day] High-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the integer part of a split date for the highest precision, or the full date for normal (reduced) precision.
	jd_tt_low	[day] Low-order part of the Terrestrial Time (TT) based Julian date. Typically it may be the fractional part of a split date for the highest precision, or 0.0 for normal (reduced) precision.
[out]	dpsi	[rad] δψ Nutation (luni-solar + planetary) in longitude, in radians.
[out]	deps	[rad] δε Nutation (luni-solar + planetary) in obliquity, in radians.

Returns

0 if successful, or else -1 (errno should be set to indicate the type of error).

See also

nutation(), nutation_angles(), iau2000a(), iau2000b(), nu2000k()

Author

Attila Kovacs

Since

1.0

Function Documentation

get_nutation_lp_provider()

novas_nutation_provider get_nutation_lp_provider

(

)

Returns the function configured for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Returns

the function to use for low-precision IAU 2000 nutation calculations

Since

1.3

Author

Attila Kovacs

See also

set_nutation_lp_provider(), nutation_angles(), nutation()

Referenced by nutation_angles().

novas_get_eop_itrf_year()

int novas_get_eop_itrf_year

(

enum novas_eop_series

series

)

Returns the ITRF realization year for a given IERS Earth Orientation Parameter (EOP) series.

Parameters

series

The EOP series identifier constant.

Returns

[yr] ITRF realization year, e.g. as set by novas_set_eop_url().

Since

1.7

Author

Attila Kovacs

See also

novas_set_eop_url(), novas_fetch_eop()

References NOVAS_NUM_EOP_SERIES.

novas_get_eop_url()

const char * novas_get_eop_url

(

enum novas_eop_series

series

)

Returns the URL currently configured for a given IERS Earth Orientation Parameter (EOP) series.

Parameters

series

The EOP series identifier constant.

Returns

The currently configured URL for the given series, or else NULL if the series is invalid (errno set to ERANGE), or if SuperNOVAS was built without cURL support (errno set to ENOSYS).

Since

1.7

Author

Attila Kovacs

See also

novas_set_eop_url(), novas_fetch_eop(), novas_get_eop_itrf_year()

References NOVAS_NUM_EOP_SERIES.

novas_is_auto_fetch_eop()

int novas_is_auto_fetch_eop

(

)

Checks if automatic fetching of Earth Orientation Parameter values from IERS is allowed.

Returns

TRUE (1) if automatic fetching of EOP values from IERS is allowed, or else FALSE (0) if fetching is disabled.

Since

1.7

Author

Attila Kovacs

See also

novas_set_auto_fetch_eop()

Referenced by supernovas::GeodeticObserver::GeodeticObserver(), supernovas::GeodeticObserver::GeodeticObserver(), supernovas::GeodeticObserver::eop_at(), supernovas::GeodeticObserver::mean_eop(), novas_lookup_leap(), novas_make_frame(), and novas_set_split_time().

novas_lookup_leap()

int novas_lookup_leap

(

time_t

t

)

Returns the leap seconds for the given UNIX timestamp, based either on a locally supplied leap seconds list (see novas_set_leap_list()), or else from data obtained as needed from IERS (provided that fetching it is allowed).

In case of errors -1 is returned, with errno set as appropriate.

Leap seconds were first introduced on 1 Jan 1972. Thus for date preceding the introduction, 0 is returned. Leap seconds prognosis into the future is available only up to the expiration date of the leap-seconds.list file (as supplied or updated from IERS).

Parameters

t	[s] UNIX time (seconds since 0 UTC, 1 Jan 1970)

Returns

The leap seconds for the given time, or NOVAS_INVALID_LEAP (-999) if there was an error (errno will indicate the type of error).

Since

1.7

Author

Attila Kovacs

See also

novas_set_leap_list(), novas_set_eop_url(), novas_fetch_eop(), novas_is_auto_fetch_eop(), NOVAS_INVALID_LEAP

References NOVAS_INVALID_LEAP, and novas_is_auto_fetch_eop().

Referenced by novas_set_eop_url().

novas_set_auto_fetch_eop()

int novas_set_auto_fetch_eop

(

int

enabled

)

Disable or Re-enabled the automatic fetching of Earth Orientation Parameter values from IERS, when these are left undefined (NAN) when initializing astrometric time or observing frame instances.

If set to TRUE (non-zero) then when an astrometric time is initialized with an undefined EOP, whose dUT1 value is NAN, it will automatically fetch appropriate leap second and dUT1 values from IERS, if possible. Similarly, if an observing frame is configured with a x_p or y_p values are NAN, the frame will fetch appropriate polar offsets from IERS for the time of observation.

The default value of this global setting is TRUE (1), hence the automatic fetching of EOP values from IERS is enabled by default, and will override NAN EOP values with the fetched interpolated data, whenever possible.

If you do not want this behavior, e.g. because of the associated arbitrary latencies involved with getting data from IERS, or because you are using SuperNOVAS offline, then simply call this function with FALSE (0) to disable the automatic fetching of EOP values.

Parameters

enabled

TRUE (non-zero) to enabled automatic fetching of EOP values from IERS, or else FALSE (0) to disable. By default EOP fetching is enabled.

Since

1.7

Author

Attila Kovacs

See also

novas_is_auto_fetch_eop(), novas_fetch_eop(), novas_lookup_leap()

novas_set_time(), novas_make_frame()

Time, Frame, GeodeticObserver, CalendarDate::to_time()

novas_set_eop_url()

int novas_set_eop_url	(	enum novas_eop_series	series,
		int	itrf_year,
		const char *	url )

Specify a URL to use for a given IERS Earth Orientation Parameter (EOP) series.

By default, novas_fetch_eop() will use the standard IERS data center URLs to obtain EOP, but users may want to use a local file, or a local mirror instead for faster, more reliable source(s) for the IERS data. This function allows you to do just that.

This call will check out the specified URL, to ensure it points to a suitable file for the series, and will return an error if the file is not appropriate. As such, the call may be delayed for a long time, while cURL fetches a few kilobytes from the file, needed for validation.

NOTES:

• Requires SuperNOVAS to be compiled with cURL support enabled, otherwise -1 is returned with errno set to ENOSYS.

Parameters

series	The EOP series identifier constant.
itrf_year	[yr] ITRF realization year. Needed only for precision at the few μas level, otherwise, you can set it to something recent, like 2020. It is unused if the URL is NULL, or if the series if the leap seconds list. For years prior to the first ITRF realization (in 1988), 1988 will be used.
url	The new URL to use for the given data series, or NULL to use the default IERS data center URL.

Returns

0 if successful, or else -1 if there was an error (errno will be set to ERANGE if the series is invalid, EINVAL if the URL is an empty string, or ENOSYS if SuperNOVAS was built without cURL support).

Since

1.7

Author

Attila Kovacs

See also

novas_get_eop_url(), novas_fetch_eop(), novas_set_leap_list(), novas_get_eop_itrf_year()

References EOP_C01_IAU2000, EOP_C04_IAU2000_0UTC, EOP_LEAP_LIST, EOP_RAPID_IAU2000, novas_lookup_leap(), and novas_set_leap_list().

novas_set_leap_list()

int novas_set_leap_list

(

const char *

filename

)

Specifies a local file containing the official leap seconds list, i.e.

leap-seconds.list, to use, at least until its expiry. (If the local leap file expires, a new one will be fetched from IERS as needed).

It is similar to novas_set_eop_url() for the EOP_LEAP_LIST series, with a file:// type URL, except that this one does not need cURL support, and can work with relative paths also.

Parameters

filename

Path to a local leap-seconds.list file (as obtained from IERS or a mirror). It is typically included in the tzdata package on Linux, where it may be found as /usr/share/zoneinfo/leap-seconds.list typically. Or, NULL to clean up any prior leap seconds resources.

Returns

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

Since

1.7

Author

Attila Kovacs

See also

https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list

novas_set_eop_url(), novas_lookup_leap(), novas_fetch_eop(), novas_reset_eop()

Referenced by novas_set_eop_url().

set_nutation_lp_provider()

int set_nutation_lp_provider

(

novas_nutation_provider

func

)

Set the function to use for low-precision IAU 2000 nutation calculations instead of the default nu2000k().

Parameters

func	the new function to use for low-precision IAU 2000 nutation calculations

Returns

0 if successful, or -1 if the input argument is NULL

Since

1.0

Author

Attila Kovacs

See also

get_nutation_lp_provider(), nutation_angles(), nutation()