Loading...
Searching...
No Matches
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.

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

NOTES:

- If SuperNOVAS was built without libc support (WITHOUT_LIBC build configuration option), then this function will always return an error (errno set to ENOSYS).

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 xp or yp 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.

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.

NOTES:

- If SuperNOVAS was built without libc support (WITHOUT_LIBC build configuration option), then this function will always return an error (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.

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