Loading...
Searching...
No Matches
earth.c File Reference

Various functions relating to Earth position and rotation. More...

## Functions

double | era (double jd_ut1_high, double jd_ut1_low)
| Returns the value of the Earth Rotation Angle (θ) for a given UT1 Julian date.
int | limb_angle (const double *pos_src, const double *pos_obs, double *restrict limb_ang, double *restrict nadir_ang)
| Determines the angle of an object above or below the Earth's limb (horizon).
int | novas_diurnal_eop (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict dxp, double *restrict dyp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides.
int | novas_diurnal_eop_at_time (const novas_timespec *restrict time, double *restrict dxp, double *restrict dyp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides at a given astromtric time.
int | novas_diurnal_libration (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict dxp, double *restrict dyp, double *restrict dut1)
| Calculate diurnal and semi-diurnal libration corrections to the Earth orientation parameters (EOP) for the non-rigid Earth.
int | novas_diurnal_ocean_tides (double gmst, const novas_delaunay_args *restrict delaunay, double *restrict dxp, double *restrict dyp, double *restrict dut1)
| Calculate corrections to the Earth orientation parameters (EOP) due to the ocean tides.
double | novas_gast (double jd_ut1, double ut1_to_tt, enum novas_accuracy accuracy)
| Returns the Greenwich Apparent Sidereal Time (GAST) for a given UT1 date.
double | novas_gmst (double jd_ut1, double ut1_to_tt)
| Returns the Greenwich Mean Sidereal Time (GMST) for a given UT1 date, using eq.
short | sidereal_time (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_equinox_type gst_type, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, double *restrict gst)
int | terra (const on_surface *restrict location, double gast, double *restrict pos, double *restrict vel)
int | wobble (double jd_tt, enum novas_wobble_direction direction, double xp, double yp, const double *in, double *out)
| Corrects a vector in the ITRS (rotating Earth-fixed system) for polar motion, and also corrects the longitude origin (by a tiny amount) to the Terrestrial Intermediate Origin (TIO).

## Detailed Description

Various functions relating to Earth position and rotation.

Date
  Created on Mar 6, 2025

Author
  G. Kaplan and Attila Kovacs

See also
  frames.c, itrf.c

## Function Documentation

## era()

double era | ( | double | jd_ut1_high,
|  | double | jd_ut1_low )

Returns the value of the Earth Rotation Angle (θ) for a given UT1 Julian date.

The expression used is taken from the note to IAU Resolution B1.8 of 2000. The input Julian date can be split into an into high and low order parts (e.g. integer and fractional parts) for improved accuracy, or else one of the components (e.g. the low part) can be set to zero if no split is desired.

The algorithm used here is equivalent to the canonical θ = 0.7790572732640 + 1.00273781191135448 * t, where t is the time in days from J2000 (t = jd_high + jd_low - JD_J2000), but it avoids many two-PI 'wraps' that decrease precision (adopted from SOFA Fortran routine iau_era00).

REFERENCES:

1. IERS Conventions 2010, Chapter 5, Eq. 5.15
2. IAU Resolution B1.8, adopted at the 2000 IAU General Assembly, Manchester, UK.
3. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  jd_ut1_high | [day] High-order part of UT1 Julian date.
  jd_ut1_low | [day] Low-order part of UT1 Julian date.

Returns
  [deg] The Earth Rotation Angle (theta) in degrees [0:360].

See also
  novas_gast(), novas_time_gst()
  cirs_to_itrs(), itrs_to_cirs()

Referenced by cel2ter(), novas_gmst(), novas_make_frame(), place(), and ter2cel().

## limb_angle()

int limb_angle | ( | const double * | pos_src,
|  | const double * | pos_obs,
|  | double *restrict | limb_ang,
|  | double *restrict | nadir_ang )

Determines the angle of an object above or below the Earth's limb (horizon).

The geometric limb is computed, assuming the Earth to be an airless sphere (no refraction or oblateness is included). The observer can be on or above the Earth. For an observer on the surface of the Earth, this function returns the approximate unrefracted elevation.

Parameters

  | pos_src | [AU] Position 3-vector of observed object, with respect to origin at geocenter, components in AU.
  | pos_obs | [AU] Position 3-vector of observer, with respect to origin at geocenter, components in AU.
  [out] | limb_ang | [deg] Angle of observed object above (+) or below (-) limb in degrees, or NAN if reurning with an error. It may be NULL if not required.
  [out] | nadir_ang | Nadir angle of observed object as a fraction of apparent radius of limb: lt;1.0 if below the limb; 1.0 on the limb; or >1.0 if above the limb. Returns NAN in case of an error return. It may be NULL if not required.

Returns
  0 if successful, or -1 if either of the input vectors is NULL or if either input position is a null vector (at the geocenter).

References M_PI, and novas_vlen().

## novas_diurnal_eop()

int novas_diurnal_eop | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides.

See Chapters 5 and 8 of the IERS Conventions. This one is faster than novas_diurnal_eop_at_time() if the GMST and/or fundamental arguments are readily avaialbe, e.g. from a previous calculation.

These corrections are typically at the sub-milliarcsecond level in polar offsets x and y and sub-millisecond level in UT1. Thus, these diurnal and semi-diurnal variations are important for the highest precision astrometry only, when converting between ITRS and TIRS frames.

NOTES:

1. These diurnal corrections are automatically added to the mean Earth Orinetation parameters used when defining astronomical times and observing frames. I.e., you should pass mean values to the likes of novas_set_time() and novas_make_frame(), which will then add the diurnal corrections as appropriate automatically.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
2. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction for libration and ocean tides, or NULL if not required.
  [out] | dyp | [arcsec] y-pole corrections for libration and ocean tides, or NULL if not required.
  [out] | dut1 | [s] UT1 correction for libration and ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop_at_time()
  novas_diurnal_libration(), novas_diurnal_ocean_tides()

Referenced by novas_diurnal_eop_at_time().

## novas_diurnal_eop_at_time()

int novas_diurnal_eop_at_time | ( | const novas_timespec *restrict | time,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to short term (diurnal and semidiurnal) libration and the ocean tides at a given astromtric time.

See Chapters 5 and 8 of the IERS Conventions.

NOTES:

1. These diurnal corrections are automatically added to the mean Earth Orinetation parameters used when defining astronomical times and observing frames. I.e., you should pass mean values to the likes of novas_set_time() and novas_make_frame(), which will then add the diurnal corrections as appropriate automatically.
2. This function caches the result of the last calculation.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
2. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  time | Astrometric time specification
  dxp | [arcsec] x-pole correction for libration and ocean tides, or NULL if not required.
  dyp | [arcsec] y-pole corrections for libration and ocean tides, or NULL if not required.
  dut1 | [s] UT1 correction for libration and ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop()

References fund_args(), novas_diurnal_eop(), novas_get_time(), novas_gmst(), NOVAS_JD_J2000, and NOVAS_UT1.

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

## novas_diurnal_libration()

int novas_diurnal_libration | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate diurnal and semi-diurnal libration corrections to the Earth orientation parameters (EOP) for the non-rigid Earth.

Only terms with periods less than 2 days are considered, since the longer period terms are included in the IAU2000A nutation model. See Chapter 5 of the IERS Conventions 2010. The typical amplitude of librations is tens of micro-arcseconds (μas) in polar offsets x and y and tens of micro-seconds in UT1.

Normally, you would need the combined effect from librations and ocean tides together to apply diurnal corrections to the Earth orientation parameters (EOP) published by IERS. For that, novas_diurnal_eop() or novas_diurnal_eop_at_time() is more directly suited.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, Tablea 5.1a and 5.1b, see https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction due to librations, or NULL if not required.
  [out] | dyp | [arcsec] y-pole correction due to librations, or NULL if not required.
  [out] | dut1 | [s] UT1 correction due to librations, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop(), novas_diurnal_ocean_tides()

## novas_diurnal_ocean_tides()

int novas_diurnal_ocean_tides | ( | double | gmst,
|  | const novas_delaunay_args *restrict | delaunay,
|  | double *restrict | dxp,
|  | double *restrict | dyp,
|  | double *restrict | dut1 )

Calculate corrections to the Earth orientation parameters (EOP) due to the ocean tides.

See Chapter 8 of the IERS Conventions 2010. Ocean tides manifest at the sub-milliarcsecond level in polar offsets x and y and sub-millisecond level in UT1.

Normally, you would need the combined effect from librations and ocean tides together to apply diurnal corrections to the Earth orientation parameters (EOP) published by IERS. For that, novas_diurnal_eop() or novas_diurnal_eop_at_time() is more directly suited.

REFERENCES:

1. IERS Conventions 2010, Chapter 8, Tables 8.2a, 8.2b, 8.3a, and 8.3b, see https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | gmst | [h] Greenwich Mean Sidereal Time of observation, e.g. as obtained by novas_gmst().
  | delaunay | [rad] Delaunay arguments, e.g. as returned by fund_args().
  [out] | dxp | [arcsec] x-pole correction due to ocean tides, or NULL if not required.
  [out] | dyp | [arcsec] y-pole correction due to ocean tides, or NULL if not required.
  [out] | dut1 | [s] UT1 correction due to ocean tides, or NULL if not required.

Returns
  0 if successful, or else -1 if the delaunay arguments are NULL (errno set to EINVAL).

Since
  1.5

Author
  Attila Kovacs

See also
  novas_diurnal_eop(), novas_diurnal_libration()

## novas_gast()

double novas_gast | ( | double | jd_ut1,
|  | double | ut1_to_tt,
|  | enum novas_accuracy | accuracy )

Returns the Greenwich Apparent Sidereal Time (GAST) for a given UT1 date.

NOTES:

1. This function caches the result of the last calculation.

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).
2. Kaplan, G. (2005), US Naval Observatory Circular 179.
3. IERS Conventions 2010, Chapter 5, Eq. 5.30 and Table 5.2e, see at https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf and https://iers-conventions.obspm.fr/content/chapter5/additional_info/tab5.2e.txt

Parameters

  jd_ut1 | [day] UT1-based Julian Date.
  ut1_to_tt | [s] UT1 - UTC time difference.
  accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)

Returns
  [h] The Greenwich Apparent Sidereal Time (GAST) in the 0-24 range.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_gmst()

References e_tilt(), and novas_gmst().

Referenced by cel2ter(), geo_posvel(), novas_time_gst(), sidereal_time(), and ter2cel().

## novas_gmst()

double novas_gmst | ( | double | jd_ut1,
|  | double | ut1_to_tt )

Returns the Greenwich Mean Sidereal Time (GMST) for a given UT1 date, using eq.

42 from Capitaine et al. (2003).

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).
2. IERS Conventions 2010, Chapter 5, Eq. 5.32, see at https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf

Parameters

  jd_ut1 | [day] UT1-based Julian Date.
  ut1_to_tt | [s] UT1 - UTC time difference.

Returns
  [h] The Greenwich Mean Sidereal Time (GMST) in the 0-24 range.

Since
  1.5

Author
  Attila Kovacs

See also
  novas_gast(), novas_time_gst()

References era().

Referenced by supernovas::Time::gmst(), novas_diurnal_eop_at_time(), novas_gast(), and sidereal_time().

## sidereal_time()

short sidereal_time | ( | double | jd_ut1_high,
|  | double | jd_ut1_low,
|  | double | ut1_to_tt,
|  | enum novas_equinox_type | gst_type,
|  | enum novas_earth_rotation_measure | erot,
|  | enum novas_accuracy | accuracy,
|  | double *restrict | gst )

Deprecated
  Use novas_gmst() or novas_gast() instead to get the same results simpler.

Computes the Greenwich sidereal time, either mean or apparent, at the specified Julian date. The Julian date can be broken into two parts if convenient, but for the highest precision, set 'jd_high' to be the integral part of the Julian date, and set 'jd_low' to be the fractional part.

NOTES:

1. Contains fix for known sidereal time units bug
2. As of version 1.5.0, the function uses Eq 42 of Capitaine et al. (2003) exclusively. In prior versions, including NOVAS C the same method was provided twice, with the only difference being an unnecessary change of coordinate basis to GCRS. This latter, mor roundabout way of getting the same answer has been eliminated.

REFERENCES:

1. Capitaine, N. et al. (2003), Astronomy and Astrophysics 412, 567-586, eq. (42).
2. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

  | jd_ut1_high | [day] High-order part of UT1 Julian date.
  | jd_ut1_low | [day] Low-order part of UT1 Julian date. (You can leave it at zero if 'jd_high' specified the date with sufficient precision)
  | ut1_to_tt | [s] TT - UT1 Time difference in seconds
  | gst_type | NOVAS_MEAN_EQUINOX (0) or NOVAS_TRUE_EQUINOX (1), depending on whether wanting mean or apparent GST, respectively.
  | erot | Unused as of 1.5.0.
  | accuracy | NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
  [out] | gst | [h] Greenwich (mean or apparent) sidereal time, in hours [0:24]. (In case the returned error code is >1 the gst value will be set to NAN.)

Returns
  0 if successful, or -1 if the 'gst' argument is NULL, 1 if 'accuracy' is

See also
  novas_gmst(), novas_gast(), novas_time_gst()
  era(), get_ut1_to_tt()

References NOVAS_FULL_ACCURACY, novas_gast(), novas_gmst(), NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

## terra()

int terra | ( | const on_surface *restrict | location,
|  | double | gast,
|  | double *restrict | pos,
|  | double *restrict | vel )

Deprecated
  This NOVAS C function does not account for polar wobble, so the geodetic ITRS / GRS80 locations on Earth are not converted into a proper equatorial system, such as a true-of-date (TOD) coordinate system. Use novas_site_gcrs_posvel() instead, which you can follow by a coordinate transformation, such as tod_to_gcrs() if you need geocentric observer coordinates in e.g. the true-of-date (TOD) equatorial system.

Computes the position and velocity vectors of a terrestrial observer with respect to the center of the Earth, based on the GRS80 reference ellipsoid, used for the International Terrestrial Reference Frame (ITRF) and its realizations.

This function ignores polar motion, unless the observer's longitude and latitude have been corrected for it, and variation in the length of day (angular velocity of earth).

The true equator and equinox of date do not form an inertial system. Therefore, with respect to an inertial system, the very small velocity component (several meters/day) due to the precession and nutation of the Earth's axis is not accounted for here.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | location | ITRF / GRS80 geodetic location of observer in Earth's rotating frame.
  | gast | [h] Greenwich apparent sidereal time (GAST). If set to 0, it returns positions and velocities w.r.t. the ITRS.
  [out] | pos | [AU] Position vector of observer with respect to center of Earth, equatorial rectangular coordinates, referred to true equator and equinox of date, components in AU. If reference meridian is Greenwich and 'lst' = 0, 'pos' is effectively referred to equator and Greenwich. (It may be NULL if no position data is required).
  [out] | vel | [AU/day] Velocity vector of observer with respect to center of Earth, equatorial rectangular coordinates, referred to true equator and equinox of date, components in AU/day. (It must be distinct from the pos output vector, and may be NULL if no velocity data is required).

Returns
  0 if successful, or -1 if location is NULL or if the pos and vel output arguments are identical pointers.

See also
  novas_site_gcrs_posvel(), geo_posvel()
  make_gps_site(), make_itrf_site(), make_xyz_site(), novas_gast(), novas_time_gst()

References NOVAS_KM.

Referenced by geo_posvel(), and novas_site_gcrs_posvel().

## wobble()

int wobble | ( | double | jd_tt,
|  | enum novas_wobble_direction | direction,
|  | double | xp,
|  | double | yp,
|  | const double * | in,
|  | double * | out )

Corrects a vector in the ITRS (rotating Earth-fixed system) for polar motion, and also corrects the longitude origin (by a tiny amount) to the Terrestrial Intermediate Origin (TIO).

The ITRS vector is thereby transformed to the Terrestrial Intermediate Reference System (TIRS), or equivalently the Pseudo Earth Fixed (PEF), based on the true (rotational) equator and TIO; or vice versa. Because the true equator is the plane orthogonal to the direction of the Celestial Intermediate Pole (CIP), the components of the output vector are referred to z and x axes toward the CIP and TIO, respectively.

NOTES:

1. You may obtain Earth orientation parameters from the IERS site and Bulletins. For sub-mas accuracy you should augment the (interpolated) published values for diurnal and semi-diurnal librations and the effect of ocean tides, e.g. by using novas_diurnal_eop() or novas_diurnal_eop_at_time().
2. Generally, this function should not be called if global pole offsets were set via cel_pole() and then used via place() or one of its variants to calculate Earth orientation corrected (TOD or CIRS) apparent coordinates. In such cases, calling wobble() would apply duplicate corrections. It is generally best to forgo using cel_pole() going forward, and instead apply Earth orinetation corrections with wobble() only when converting vectors between the Earth-fixed ITRS and TIRS frames.
3. The Earth orientation parameters xp, yp should be provided in the same ITRF realization as the observer location for an Earth-based observer. You can use novas_itrf_transform_eop() to convert the EOP values as necessary.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Lambert & Bizouard (2002), Astronomy and Astrophysics 394, 317-321.
3. IERS Conventions 2010, Chapter 5, https://iers-conventions.obspm.fr/content/chapter5/icc5.pdf
4. IERS Conventions 2010, Chapter 8, https://iers-conventions.obspm.fr/content/chapter8/icc8.pdf

Parameters

  | jd_tt | [day] Terrestrial Time (TT) based Julian date.
  | direction | WOBBLE_ITRS_TO_TIRS (0) or WOBBLE_TIRS_TO_ITRS (1) to include corrections for the TIO's longitude (IAU 2006 method); or else WOBBLE_ITRS_TO_PEF (2) or WOBBLE_PEF_TO_ITRS (3) to correct for dx, dy but not for the TIO's longitude (old, pre IAU 2006 method). Negative values default to WOBBLE_TIRS_TO_ITRS.
  | xp | [arcsec] Conventionally-defined X coordinate of Celestial Intermediate Pole with respect to ITRS pole. As measured or else the interpolated published value from IERS, possibly augmented for diurnal variations caused by librations ocean tides if precision below the milliarcsecond level is required.
  | yp | [arcsec] Conventionally-defined Y coordinate of Celestial Intermediate Pole with respect to ITRS pole, in arcseconds. As measured or else the interpolated published value from IERS, possibly augmented for diurnal variations caused by librations ocean tides if precision below the milliarcsecond level is required.
  | in | Input position vector, geocentric equatorial rectangular coordinates, in the original system defined by 'direction'
  [out] | out | Output Position vector, geocentric equatorial rectangular coordinates, in the final system defined by 'direction'. It can be the same vector as the input.

Returns
  0 if successful, or -1 if the direction is invalid output vector argument is NULL.

See also
  novas_diurnal_eop(), novas_diurnal_eop_at_time(), novas_itrf_transform_eop()

References NOVAS_WOBBLE_DIRECTIONS, WOBBLE_ITRS_TO_PEF, WOBBLE_ITRS_TO_TIRS, and WOBBLE_TIRS_TO_ITRS.

Referenced by cel2ter(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), and ter2cel().