Functions
double	era (double jd_ut1_high, double jd_ut1_low)

short	geo_posvel (double jd_tt, double ut1_to_tt, enum novas_accuracy accuracy, const observer restrict obs, double restrict pos, double *restrict vel)

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

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 lst, 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)

Detailed Description

Date: Created on Mar 6, 2025

Author: G. Kaplan and Attila Kovacs

Various finctions relating to Earth position and orientation

Function Documentation

◆ era()

double era	(	double	jd_ut1_high,
		double	jd_ut1_low
	)

Returns the value of the Earth Rotation Angle (theta) 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 cane 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 theta = 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; see also expression at top of page 35 of IERS Conventions (1996)).

REFERENCES:

IAU Resolution B1.8, adopted at the 2000 IAU General Assembly, Manchester, UK.
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: sidereal_time(); cirs_to_itrs(); itrs_to_cirs()

◆ geo_posvel()

short geo_posvel	(	double	jd_tt,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		const observer *restrict	obs,
		double *restrict	pos,
		double *restrict	vel
	)

Computes the geocentric GCRS position and velocity of an observer.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date.
	ut1_to_tt	[s] TT - UT1 time difference in seconds
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	obs	Observer location
[out]	pos	[AU] Position 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU. (It may be NULL if not required.)
[out]	vel	[AU/day] Velocity 3-vector of observer, with respect to origin at geocenter, referred to GCRS axes, components in AU/day. (It must be distinct from the pos output vector, and may be NULL if not required)

Returns: 0 if successful, -1 if the 'obs' is NULL or the two output vectors are the same, or else 1 if 'accuracy' is invalid, or 2 if 'obserrver->where' is invalid.

See also: place(); make_observer(); get_ut1_to_tt(); cel_pole()

References ephemeris(), EROT_ERA, geo_posvel(), NOVAS_AIRBORNE_OBSERVER, NOVAS_BARYCENTER, NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, NOVAS_OBSERVER_AT_GEOCENTER, NOVAS_OBSERVER_IN_EARTH_ORBIT, NOVAS_OBSERVER_ON_EARTH, NOVAS_REDUCED_ACCURACY, NOVAS_SOLAR_SYSTEM_OBSERVER, NOVAS_TRUE_EQUINOX, sidereal_time(), terra(), tod_to_gcrs(), tt2tdb(), and observer::where.

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

See also: place()

References M_PI, and novas_vlen().

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

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:

Contains fix for known sidereal time units bug.

REFERENCES:

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	EROT_ERA (0) or EROT_GST (1), depending on whether to use GST relative to equinox of date (pre IAU 2006) or ERA relative to the CIO (IAU 2006 standard).
	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 invalid 2 if 'method' is invalid, or else 10–30 with 10 + the error from cio_location().

See also: novas_time_gst(); era(); tod_to_itrs(); itrs_to_tod(); cel_pole(); get_ut1_to_tt()

References cio_basis(), cio_location(), e_tilt(), era(), EROT_ERA, EROT_GST, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and tod_to_gcrs().

◆ terra()

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

Computes the position and velocity vectors of a terrestrial observer with respect to the center of the Earth.

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:

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

Parameters

	location	Location of observer in Earth's rotating frame
	lst	[h] Local apparent sidereal time at reference meridian in hours.
[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: make_on_surface(); geo_posvel(); sidereal_time()

References NOVAS_KM.

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

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 to the Earth-fixed ITRS frame.

REFERENCES:

Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Lambert & Bizouard (2002), Astronomy and Astrophysics 394, 317-321.

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, in arcseconds.
	yp	[arcsec] Conventionally-defined Y coordinate of Celestial Intermediate Pole with respect to ITRS pole, in arcseconds.
	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: cel_pole(); cirs_to_itrs(); tod_to_itrs(); place(); sidereal_time(); e_tilt(); NOVAS_FULL_ACCURACY

References NOVAS_WOBBLE_DIRECTIONS, WOBBLE_ITRS_TO_PEF, WOBBLE_ITRS_TO_TIRS, and WOBBLE_TIRS_TO_ITRS.

Functions

Detailed Description

Function Documentation

◆ era()

◆ geo_posvel()

◆ limb_angle()

◆ sidereal_time()

◆ terra()

◆ wobble()