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

NOTES:

• If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

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.

NOTES:

• If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

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.

NOTES:

• If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

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

Leap seconds were first introduced on 1 Jan 1972. Thus for date preceding the introduction, 0 is returned. The last leap of 27 seconds was introduced on 1 January 2017, and the decision has been made to not introduce further leap seconds as of 20 May 2027, leaving 37 seconds for the foreseeable future.

REFERENCES:

1. General Conference on Weights and Measures. "Resolution 5: On the adoption of a continuous UTC." Document presented at the 28th Meeting of the CGPM, Bureau International des Poids et Mesures (BIPM), Versailles, France, October 15, 2026. https://www.bipm.org/en/cgpm-2026/resolution-5.

Parameters

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

Returns

The leap seconds for the given time.

Since

1.7

Author

Attila Kovacs

See also

novas_leap_for_jd(), novas_fetch_eop(), novas_is_auto_fetch_eop()

Referenced by novas_leap_for_jd().

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

NOTES:

• If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS) if trying to enable EOP fetching.
• This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.

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.
• This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.
• The IERS data service may encounter outages. Possible alternative URLs for the IERS EOP series are:
  • C01: https://hpiers.obspm.fr/iers/eop/eopc01/eopc01.1846-now
  • C04: https://hpiers.obspm.fr/iers/eop/eopc04/eopc04.1962-now
  • rapid service: https://maia.usno.navy.mil/ser7/finals2000A.daily.extended
• You may also download the relevant EOP series from IERS or from the alternative sources to store in local files, and then use this function to set file:// type urls with absolute paths. This may be the preferred approach for critical / time critical applications.

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 is the leap second 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_get_eop_itrf_year()

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

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