Functions
short	cel_pole (double jd_tt, enum novas_pole_offset_type type, double dpole1, double dpole2)

int	e_tilt (double jd_tdb, enum novas_accuracy accuracy, double restrict mobl, double restrict tobl, double restrict ee, double restrict dpsi, double *restrict deps)

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)

Variables
double	EPS_COR = 0.0

double	PSI_COR = 0.0

Detailed Description

Date: Created on Mar 6, 2025

Author: G. Kaplan and Attila Kovacs

Various finctions relating to Earth position and orientation

Function Documentation

◆ cel_pole()

short cel_pole	(	double	jd_tt,
		enum novas_pole_offset_type	type,
		double	dpole1,
		double	dpole2
	)

specifies the celestial pole offsets for high-precision applications. Each set of offsets is a correction to the modeled position of the pole for a specific date, derived from observations and published by the IERS.

The variables 'PSI_COR' and 'EPS_COR' are used only in NOVAS function e_tilt().

This function, if used, should be called before any other NOVAS functions for a given date. Values of the pole offsets specified via a call to this function will be used until explicitly changed.

'tjd' is used only if 'type' is POLE_OFFSETS_X_Y (2), to transform dx and dy to the equivalent Δδψ and Δδε values.

If 'type' is POLE_OFFSETS_X_Y (2), dx and dy are unit vector component corrections, but are expressed in milliarcseconds simply by multiplying by 206264806, the number of milliarcseconds in one radian.

NOTES:

The current UT1 - UTC time difference, and polar offsets, historical data and near-term projections are published in the <a href="https://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html>IERS Bulletins

REFERENCES:

Kaplan, G. (2005), US Naval Observatory Circular 179.
Kaplan, G. (2003), USNO/AA Technical Note 2003-03.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian date.
type	POLE_OFFSETS_DPSI_DEPS (1) or POLE_OFFSETS_X_Y (2)
dpole1	[mas] Value of celestial pole offset in first coordinate, (Δδψ or dx) in milliarcseconds.
dpole2	[mas] Value of celestial pole offset in second coordinate, (Δδε or dy) in milliarcseconds.

Returns: 0 if successful, or else 1 if 'type' is invalid.

See also: cirs_to_itrs(); tod_to_itrs(); e_tilt(); place(); get_ut1_to_tt(); sidereal_time(); NOVAS_FULL_ACCURACY

References EPS_COR, POLE_OFFSETS_DPSI_DEPS, POLE_OFFSETS_X_Y, and PSI_COR.

◆ e_tilt()

int e_tilt	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		double *restrict	mobl,
		double *restrict	tobl,
		double *restrict	ee,
		double *restrict	dpsi,
		double *restrict	deps
	)

Computes quantities related to the orientation of the Earth's rotation axis at Julian date 'jd_tdb'.

Values of the celestial pole offsets 'PSI_COR' and 'EPS_COR' are set using function 'cel_pole', if desired. See the prolog of cel_pole() for details.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	mobl	[deg] Mean obliquity of the ecliptic in degrees. It may be NULL if not required.
[out]	tobl	[deg] True obliquity of the ecliptic in degrees. It may be NULL if not required.
[out]	ee	[deg] Equation of the equinoxes in seconds of time. It may be NULL if not required.
[out]	dpsi	[arcsec] Nutation in longitude in arcseconds. It may be NULL if not required.
[out]	deps	[arcsec] Nutation in obliquity in arcseconds. It may be NULL if not required.

Returns: 0 if successful, or -1 if the accuracy argument is invalid

See also: cel_pole(); place(); equ2ecl(); ecl2equ()

References ee_ct(), EPS_COR, mean_obliq(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, nutation_angles(), and PSI_COR.

◆ 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 position and velocity of an observer. The final vectors are expressed in the GCRS.

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 e_tilt(), 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, 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: 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, tod_to_gcrs(), and tt2tdb().

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

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_PEF (0) or WOBBLE_PEF_TO_ITRS (nonzero)
	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 output vector argument is NULL.

See also: cel_pole(); cirs_to_itrs(); tod_to_itrs(); place(); sidereal_time(); e_tilt(); NOVAS_FULL_ACCURACY

References WOBBLE_ITRS_TO_PEF.

Variable Documentation

◆ EPS_COR

double EPS_COR = 0.0

Celestial pole offset ε for high-precision applications. It was visible to users in NOVAS C 3.1, hence we continue to expose it also for back compatibility.

See also: PSI_COR; cel_pole()

◆ PSI_COR

double PSI_COR = 0.0

Celestial pole offset ψ for high-precision applications. It was visible to users in NOVAS C 3.1, hence we continue to expose it also for back compatibility.

See also: EPS_COR; cel_pole()

Functions

Variables

Detailed Description

Function Documentation

◆ cel_pole()

◆ e_tilt()

◆ era()

◆ geo_posvel()

◆ limb_angle()

◆ sidereal_time()

◆ terra()

◆ wobble()

Variable Documentation

◆ EPS_COR

◆ PSI_COR