system.c File Reference

Functions
double	app_to_cirs_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
short	cel2ter (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class class, double xp, double yp, const double *in, double *out)
double	cirs_to_app_ra (double jd_tt, enum novas_accuracy accuracy, double ra)
int	cirs_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
int	cirs_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
int	cirs_to_tod (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
int	frame_tie (const double *in, enum novas_frametie_direction direction, double *out)
short	gcrs2equ (double jd_tt, enum novas_dynamical_type sys, enum novas_accuracy accuracy, double rag, double decg, double *restrict ra, double *restrict dec)
int	gcrs_to_cirs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
int	gcrs_to_j2000 (const double *in, double *out)
int	gcrs_to_mod (double jd_tdb, const double *in, double *out)
int	gcrs_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
int	itrs_to_cirs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
int	itrs_to_tod (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
int	j2000_to_gcrs (const double *in, double *out)
int	j2000_to_tod (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
int	mod_to_gcrs (double jd_tdb, const double *in, double *out)
int	nutation (double jd_tdb, enum novas_nutation_direction direction, enum novas_accuracy accuracy, const double *in, double *out)
int	nutation_angles (double t, enum novas_accuracy accuracy, double *restrict dpsi, double *restrict deps)
short	precession (double jd_tdb_in, const double *in, double jd_tdb_out, double *out)
short	ter2cel (double jd_ut1_high, double jd_ut1_low, double ut1_to_tt, enum novas_earth_rotation_measure erot, enum novas_accuracy accuracy, enum novas_equatorial_class class, double xp, double yp, const double *in, double *out)
int	tod_to_cirs (double jd_tt, enum novas_accuracy accuracy, const double *in, double *out)
int	tod_to_gcrs (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)
int	tod_to_itrs (double jd_tt_high, double jd_tt_low, double ut1_to_tt, enum novas_accuracy accuracy, double xp, double yp, const double *in, double *out)
int	tod_to_j2000 (double jd_tdb, enum novas_accuracy accuracy, const double *in, double *out)

Detailed Description

Date

Created on Mar 6, 2025

Author

G. Kaplan and Attila Kovacs

Various functions to transform between different equatorial coordinate systems.

Function Documentation

app_to_cirs_ra()

double app_to_cirs_ra	(	double	jd_tt,
		enum novas_accuracy	accuracy,
		double	ra
	)

Converts an apparent right ascension coordinate (measured from the true equinox of date) to a CIRS R.A., measured from the CIO.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian date
accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
ra	[h] the apparent R.A. coordinate measured from the true equinox of date.

Returns

[h] The CIRS right ascension coordinate, measured from the CIO [0:24], or NAN if the accuracy is invalid, or if there wan an error from cio_ra().

See also

cirs_to_app_ra()

tod_to_cirs()

Since

1.0.1

Author

Attila Kovacs

References cio_ra().

cel2ter()

short cel2ter	(	double	jd_ut1_high,
		double	jd_ut1_low,
		double	ut1_to_tt,
		enum novas_earth_rotation_measure	erot,
		enum novas_accuracy	accuracy,
		enum novas_equatorial_class	class,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a vector from the celestial to the terrestrial system. Specifically, it transforms a vector in the GCRS, or the dynamcal CIRS or TOD frames to the ITRS (a rotating earth-fixed system) by applying rotations for the GCRS-to-dynamical frame tie, precession, nutation, Earth rotation, and polar motion.

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

Deprecated:

This function can be confusing to use due to the input coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV J oint Discussion 16.

Parameters

	jd_ut1_high	[day] High-order part of UT1 Julian date.
	jd_ut1_low	[day] Low-order part of UT1 Julian date.
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	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) as the Earth rotation measure. The main effect of this option is that it specifies the input coordinate system as CIRS or TOD when the input coordinate class is NOVAS_DYNAMICAL_CLASS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	class	Input coordinate class, NOVAS_REFERENCE_CLASS (0) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the input coordinates are in the GCRS, and the latter if they are CIRS or TOD (the 'erot' parameter selects which dynamical system the input is specified in.)
	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 specified input coordinate system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST).
[out]	out	ITRS position vector, geocentric equatorial rectangular coordinates (terrestrial system). It can be the same vector as the input.

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

gcrs_to_cirs()

cirs_to_itrs()

frame_tie()

j2000_to_tod()

tod_to_itrs()

ter2cel()

References era(), EROT_ERA, EROT_GST, gcrs_to_cirs(), gcrs_to_tod(), NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, sidereal_time(), spin(), tt2tdb(), wobble(), and WOBBLE_PEF_TO_ITRS.

cirs_to_app_ra()

double cirs_to_app_ra	(	double	jd_tt,
		enum novas_accuracy	accuracy,
		double	ra
	)

Converts a CIRS right ascension coordinate (measured from the CIO) to an apparent R.A. measured from the true equinox of date.

Parameters

jd_tt	[day] Terrestrial Time (TT) based Julian date
accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
ra	[h] The CIRS right ascension coordinate, measured from the CIO.

Returns

[h] the apparent R.A. coordinate measured from the true equinox of date [0:24], or NAN if the accuracy is invalid, or if there wan an error from cio_ra().

See also

app_to_cirs_ra()

cirs_to_tod()

Since

1.0.1

Author

Attila Kovacs

References cio_ra().

cirs_to_gcrs()

int cirs_to_gcrs	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) frame at the given epoch to the Geocentric Celestial Reference System (GCRS).

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	CIRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the GCRS coordinate frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or an error from cio_location(), or else 10 + the error from cio_basis().

See also

tod_to_gcrs()

gcrs_to_cirs()

cirs_to_itrs()

cirs_to_tod()

Since

1.0

Author

Attila Kovacs

References cio_basis(), and cio_location().

cirs_to_itrs()

int cirs_to_itrs	(	double	jd_tt_high,
		double	jd_tt_low,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a position vector from the dynamical CIRS frame of date to the Earth-fixed ITRS frame (IAU 2000 standard method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

	jd_tt_high	[day] High-order part of Terrestrial Time (TT) based Julian date.
	jd_tt_low	[day] Low-order part of 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)
	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	Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).
[out]	out	Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

tod_to_itrs()

itrs_to_cirs()

gcrs_to_cirs()

cirs_to_gcrs()

cirs_to_tod()

Since

1.0

Author

Attila Kovacs

References cel2ter(), EROT_ERA, and NOVAS_DYNAMICAL_CLASS.

cirs_to_tod()

int cirs_to_tod	(	double	jd_tt,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the Celestial Intermediate Reference System (CIRS) at the given epoch to the True of Date (TOD) reference system.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	CIRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or 10 + the error from cio_location(), or else 20 + the error from cio_basis().

See also

tod_to_cirs()

cirs_to_app_ra()

cirs_to_gcrs()

cirs_to_itrs()

Since

1.1

Author

Attila Kovacs

References cio_ra(), and spin().

frame_tie()

int frame_tie	(	const double *	in,
		enum novas_frametie_direction	direction,
		double *	out
	)

Transforms a vector from the dynamical reference system to the International Celestial Reference System (ICRS), or vice versa. The dynamical reference system is based on the dynamical mean equator and equinox of J2000.0. The ICRS is based on the space-fixed ICRS axes defined by the radio catalog positions of several hundred extragalactic objects.

For geocentric coordinates, the same transformation is used between the dynamical reference system and the GCRS.

NOTES:

1. More efficient 3D rotation implementation for small angles by A. Kovacs

REFERENCES:

1. Hilton, J. and Hohenkerk, C. (2004), Astronomy and Astrophysics 413, 765-770, eq. (6) and (8).
2. IERS (2003) Conventions, Chapter 5.

Parameters

	in	Position vector, equatorial rectangular coordinates.
	direction	<0 for for dynamical to ICRS transformation, or else >=0 for ICRS to dynamical transformation. Alternatively you may use the constants J2000_TO_ICRS (-1; or negative) or ICRS_TO_J2000 (0; or positive).
[out]	out	Position vector, equatorial rectangular coordinates. It can be the same vector as the input.

Returns

0 if successfor or -1 if either of the vector arguments is NULL.

See also

j2000_to_gcrs()

gcrs_to_j2000()

tod_to_j2000()

j2000_to_tod()

j2000_to_gcrs()

gcrs2equ()

short gcrs2equ	(	double	jd_tt,
		enum novas_dynamical_type	sys,
		enum novas_accuracy	accuracy,
		double	rag,
		double	decg,
		double *restrict	ra,
		double *restrict	dec
	)

Converts GCRS right ascension and declination to coordinates with respect to the equator of date (mean or true). For coordinates with respect to the true equator of date, the origin of right ascension can be either the true equinox or the celestial intermediate origin (CIO). This function only supports the CIO-based method.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date. (Unused if 'coord_sys' is NOVAS_ICRS_EQUATOR)
	sys	Dynamical equatorial system type
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1) (unused if 'coord_sys' is not NOVAS_ICRS [3])
	rag	[h] GCRS right ascension in hours.
	decg	[deg] GCRS declination in degrees.
[out]	ra	[h] Right ascension in hours, referred to specified equator and right ascension origin of date.
[out]	dec	[deg] Declination in degrees, referred to specified equator of date.

Returns

0 if successful, or -1 with errno set to EINVAL if the output pointers are NULL or the coord_sys is invalid, otherwise <0 if an error from vector2radec(), 10–20 error is 10 + error cio_location(); or else 20 + error from cio_basis()

References DEG2RAD, gcrs_to_cirs(), gcrs_to_mod(), gcrs_to_tod(), NOVAS_DYNAMICAL_CIRS, NOVAS_DYNAMICAL_MOD, NOVAS_DYNAMICAL_TOD, tt2tdb(), and vector2radec().

gcrs_to_cirs()

int gcrs_to_cirs	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the Geocentric Celestial Reference System (GCRS) to the Celestial Intermediate Reference System (CIRS) frame at the given epoch

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	GCRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or an error from cio_location(), or else 10 + the error from cio_basis().

See also

gcrs_to_j2000()

cirs_to_gcrs()

Since

1.0

Author

Attila Kovacs

References cio_basis(), and cio_location().

gcrs_to_j2000()

int gcrs_to_j2000	(	const double *	in,
		double *	out
	)

Change GCRS coordinates to J2000 coordinates. Same as frame_tie() called with ICRS_TO_J2000

Parameters

	in	GCRS input 3-vector
[out]	out	J2000 output 3-vector

Returns

0 if successful, or else an error from frame_tie()

See also

j2000_to_gcrs()

tod_to_j2000()

Since

1.0

Author

Attila Kovacs

References frame_tie(), and ICRS_TO_J2000.

gcrs_to_mod()

int gcrs_to_mod	(	double	jd_tdb,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the Geocentric Celestial Reference System (GCRS) to the Mean of Date (MOD) reference frame at the given epoch

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	in	GCRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the Mean wquinox of Date coordinate frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL.

See also

mod_to_gcrs()

gcrs_to_tod()

Since

1.2

Author

Attila Kovacs

References frame_tie(), ICRS_TO_J2000, NOVAS_JD_J2000, and precession().

gcrs_to_tod()

int gcrs_to_tod	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the Geocentric Celestial Reference System (GCRS) to the True of Date (TOD) reference frame at the given epoch

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	GCRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL.

See also

gcrs_to_cirs()

tod_to_gcrs()

j2000_to_tod()

Since

1.2

Author

Attila Kovacs

References frame_tie(), ICRS_TO_J2000, and j2000_to_tod().

itrs_to_cirs()

int itrs_to_cirs	(	double	jd_tt_high,
		double	jd_tt_low,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a position vector from the Earth-fixed ITRS frame to the dynamical CIRS frame of date (IAU 2000 standard method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

	jd_tt_high	[day] High-order part of Terrestrial Time (TT) based Julian date.
	jd_tt_low	[day] Low-order part of 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)
	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	Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
[out]	out	Position vector, geocentric equatorial rectangular coordinates, referred to CIRS axes (celestial system).

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

itrs_to_tod()

cirs_to_itrs()

cirs_to_gcrs()

Since

1.0

Author

Attila Kovacs

References EROT_ERA, NOVAS_DYNAMICAL_CLASS, and ter2cel().

itrs_to_tod()

int itrs_to_tod	(	double	jd_tt_high,
		double	jd_tt_low,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a position vector from the Earth-fixed ITRS frame to the dynamical True of Date (TOD) frame of date (pre IAU 2000 method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

	jd_tt_high	[day] High-order part of Terrestrial Time (TT) based Julian date.
	jd_tt_low	[day] Low-order part of 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)
	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	Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system)
[out]	out	Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system)

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

itrs_to_cirs()

tod_to_itrs()

tod_to_j2000()

Since

1.0

Author

Attila Kovacs

References EROT_GST, NOVAS_DYNAMICAL_CLASS, and ter2cel().

j2000_to_gcrs()

int j2000_to_gcrs	(	const double *	in,
		double *	out
	)

Change J2000 coordinates to GCRS coordinates. Same as frame_tie() called with J2000_TO_ICRS

Parameters

	in	J2000 input 3-vector
[out]	out	GCRS output 3-vector

Returns

0 if successful, or else an error from frame_tie()

See also

j2000_to_tod()

gcrs_to_j2000()

Since

1.0

Author

Attila Kovacs

References frame_tie(), and J2000_TO_ICRS.

j2000_to_tod()

int j2000_to_tod	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from J2000 coordinates to the True of Date (TOD) reference frame at the given epoch

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Input (x, y, z) position or velocity vector in rectangular equatorial coordinates at J2000
[out]	out	Output position or velocity 3-vector in the True equinox of Date coordinate frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid.

See also

j2000_to_gcrs()

tod_to_j2000()

gcrs_to_j2000()

Since

1.0

Author

Attila Kovacs

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_MEAN_TO_TRUE, nutation(), and precession().

mod_to_gcrs()

int mod_to_gcrs	(	double	jd_tdb,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from Mean of Date (MOD) reference frame at the given epoch to the Geocentric Celestial Reference System(GCRS)

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	in	Input (x, y, z) position or velocity 3-vector in the Mean equinox of Date coordinate frame.
[out]	out	Output GCRS position or velocity vector. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL.

See also

gcrs_to_mod()

tod_to_gcrs()

Since

1.2

Author

Attila Kovacs

References frame_tie(), J2000_TO_ICRS, NOVAS_JD_J2000, and precession().

nutation()

int nutation	(	double	jd_tdb,
		enum novas_nutation_direction	direction,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Nutates equatorial rectangular coordinates from mean equator and equinox of epoch to true equator and equinox of epoch. Inverse transformation may be applied by setting flag 'direction'.

This is the old (pre IAU 2006) method of nutation calculation. If you follow the now standard IAU 2000/2006 methodology you will want to use nutation_angles() instead.

REFERENCES:

1. Explanatory Supplement To The Astronomical Almanac, pp. 114-115.

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	direction	NUTATE_MEAN_TO_TRUE (0) or NUTATE_TRUE_TO_MEAN (-1; or non-zero)
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean equator and equinox of epoch.
[out]	out	Position vector, geocentric equatorial rectangular coordinates, referred to true equator and equinox of epoch. It can be the same as the input position.

Returns

0 if successful, or -1 if one of the vector arguments is NULL.

See also

nutation_angles()

tt2tdb()

NOVAS_TOD

References e_tilt(), and NUTATE_MEAN_TO_TRUE.

nutation_angles()

int nutation_angles	(	double	t,
		enum novas_accuracy	accuracy,
		double *restrict	dpsi,
		double *restrict	deps
	)

Returns the values for nutation in longitude and nutation in obliquity for a given TDB Julian date. The nutation model selected depends upon the input value of 'accuracy'. See notes below for important details.

This function selects the nutation model depending first upon the input value of 'accuracy'. If 'accuracy' is NOVAS_FULL_ACCURACY (0), the IAU 2000A nutation model is used. Otherwise the model set by set_nutation_lp_provider() is used, or else the default nu2000k().

See the prologs of the nutation functions in file 'nutation.c' for details concerning the models.

REFERENCES:

1. Kaplan, G. (2005), US Naval Observatory Circular 179.

Parameters

	t	[cy] TDB time in Julian centuries since J2000.0
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	dpsi	[arcsec] Nutation in longitude in arcseconds.
[out]	deps	[arcsec] Nutation in obliquity in arcseconds.

Returns

0 if successful, or -1 if the output pointer arguments are NULL

See also

set_nutation_lp_provider()

nutation()

iau2000b()

nu2000k()

cio_basis()

NOVAS_CIRS

NOVAS_JD_J2000

References get_nutation_lp_provider(), iau2000a(), and NOVAS_FULL_ACCURACY.

precession()

short precession	(	double	jd_tdb_in,
		const double *	in,
		double	jd_tdb_out,
		double *	out
	)

Precesses equatorial rectangular coordinates from one epoch to another. Unlike the original NOVAS routine, this routine works for any pairing of the time arguments.

This function calculates precession for the old (pre IAU 2000) methodology. Its main use for NOVAS users is to allow converting older catalog coordinates e.g. to J2000 coordinates, which then can be converted to the now standard ICRS system via frame_tie().

NOTE:

1. Unlike the original NOVAS C 3.1 version, this one does not require that one of the time arguments must be J2000. You can precess from any date to any other date, and the intermediate epoch of J2000 will be handled internally as needed.

REFERENCES:

1. Explanatory Supplement To The Astronomical Almanac, pp. 103-104.
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.
3. Hilton, J. L. et al. (2006), IAU WG report, Celest. Mech., 94, pp. 351-367.

Parameters

	jd_tdb_in	[day] Barycentric Dynamic Time (TDB) based Julian date of the input epoch
	in	Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean dynamical equator and equinox of the initial epoch.
	jd_tdb_out	[day] Barycentric Dynamic Time (TDB) based Julian date of the output epoch
[out]	out	Position 3-vector, geocentric equatorial rectangular coordinates, referred to mean dynamical equator and equinox of the final epoch. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the position vectors is NULL.

See also

nutation()

frame_tie()

novas_epoch()

tt2tdb()

cio_basis()

NOVAS_TOD

NOVAS_JD_J2000

NOVAS_JD_B1950

NOVAS_JD_B1900

References precession().

ter2cel()

short ter2cel	(	double	jd_ut1_high,
		double	jd_ut1_low,
		double	ut1_to_tt,
		enum novas_earth_rotation_measure	erot,
		enum novas_accuracy	accuracy,
		enum novas_equatorial_class	class,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a vector from the terrestrial to the celestial system. Specifically, it transforms a vector in the ITRS (rotating earth-fixed system) to the True of Date (TOD), CIRS, or GCRS (a local space-fixed system) by applying rotations for polar motion, Earth rotation (for TOD); and nutation, precession, and the dynamical-to-GCRS frame tie (for GCRS).

If 'system' is NOVAS_CIRS then method EROT_ERA must be used. Similarly, if 'system' is NOVAS_TOD then method must be EROT_ERA. Otherwise an error 3 is returned.

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

Deprecated:

This function can be confusing to use due to the output coordinate system being specified by a combination of two options. Use itrs_to_cirs() or itrs_to_tod() instead. You can then follow these with other conversions to GCRS (or whatever else) as appropriate.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

	jd_ut1_high	[day] High-order part of UT1 Julian date.
	jd_ut1_low	[day] Low-order part of UT1 Julian date.
	ut1_to_tt	[s] TT - UT1 Time difference in seconds
	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) as the Earth rotation measure. The main effect of this option is that it selects the output coordinate system as CIRS or TOD if the output coordinate class is NOVAS_DYNAMICAL_CLASS.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	class	Output coordinate class NOVAS_REFERENCE_CLASS (0, or any value other than 1) or NOVAS_DYNAMICAL_CLASS (1). Use the former if the output coordinates are to be in the GCRS, and the latter if they are to be in CIRS or TOD (the 'erot' parameter selects which dynamical system to use for the output.)
	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	Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system) in the normal case where 'option' is NOVAS_GCRS (0).
[out]	out	Position vector, equatorial rectangular coordinates in the specified output system (GCRS if 'class' is NOVAS_REFERENCE_CLASS; or else either CIRS if 'erot' is EROT_ERA, or TOD if 'erot' is EROT_GST). It may be the same vector as the input.

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

itrs_to_cirs()

cirs_to_gcrs()

itrs_to_tod()

tod_to_j2000()

frame_tie()

cel2ter()

References cirs_to_gcrs(), era(), EROT_ERA, EROT_GST, NOVAS_DYNAMICAL_CLASS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, sidereal_time(), spin(), tod_to_gcrs(), tt2tdb(), wobble(), and WOBBLE_ITRS_TO_PEF.

tod_to_cirs()

int tod_to_cirs	(	double	jd_tt,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from the True of Date (TOD) reference system to the Celestial Intermediate Reference System (CIRS) at the given epoch to the .

NOTES:

1. The accuracy of the output CIRS coordinates depends on how the input TOD coordinates were obtained. If TOD was calculated via the old (pre IAU 2006) method, using the Lieske et al. 1997 nutation model, then the limited accuracy of that model will affect the resulting coordinates. This is the case for the SuperNOVAS functions novas_geom_posvel() and novas_sky_pos() also, when called with NOVAS_TOD as the system, as well as all legacy NOVAS C functions that produce TOD coordinates.

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date that defines the output epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	CIRS Input (x, y, z) position or velocity vector
[out]	out	Output position or velocity 3-vector in the True of Date (TOD) frame. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the accuracy is invalid, or 10 + the error from cio_location(), or else 20 + the error from cio_basis().

See also

cirs_to_tod()

app_to_cirs_ra()

tod_to_gcrs()

tod_to_j2000()

tod_to_itrs()

Since

1.1

Author

Attila Kovacs

References cio_ra(), and spin().

tod_to_gcrs()

int tod_to_gcrs	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the Geocentric Celestial Reference System(GCRS)

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
[out]	out	Output GCRS position or velocity vector. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL.

See also

j2000_to_tod()

tod_to_cirs()

tod_to_j2000()

tod_to_itrs()

Since

1.2

Author

Attila Kovacs

References frame_tie(), J2000_TO_ICRS, and tod_to_j2000().

tod_to_itrs()

int tod_to_itrs	(	double	jd_tt_high,
		double	jd_tt_low,
		double	ut1_to_tt,
		enum novas_accuracy	accuracy,
		double	xp,
		double	yp,
		const double *	in,
		double *	out
	)

Rotates a position vector from the dynamical True of Date (TOD) frame of date the Earth-fixed ITRS frame (pre IAU 2000 method).

If both 'xp' and 'yp' are set to 0 no polar motion is included in the transformation.

If extreme (sub-microarcsecond) accuracy is not required, you can use UT1-based Julian date instead of the TT-based Julian date and set the 'ut1_to_tt' argument to 0.0. and you can use UTC-based Julian date the same way.for arcsec-level precision also.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
2. Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins', Proceedings of IAU XXV Joint Discussion 16.

Parameters

	jd_tt_high	[day] High-order part of Terrestrial Time (TT) based Julian date.
	jd_tt_low	[day] Low-order part of 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)
	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	Position vector, geocentric equatorial rectangular coordinates, referred to True of Date (TOD) axes (celestial system).
[out]	out	Position vector, geocentric equatorial rectangular coordinates, referred to ITRS axes (terrestrial system).

Returns

0 if successful, -1 if either of the vector arguments is NULL, 1 if 'accuracy' is invalid, 2 if 'method' is invalid 10–20, 3 if the method and option are mutually incompatible, or else 10 + the error from cio_location(), or 20 + error from cio_basis().

See also

cirs_to_itrs()

itrs_to_tod()

j2000_to_tod()

tod_to_gcrs()

tod_to_j2000()

tod_to_cirs()

Since

1.0

Author

Attila Kovacs

References cel2ter(), EROT_GST, and NOVAS_DYNAMICAL_CLASS.

tod_to_j2000()

int tod_to_j2000	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		const double *	in,
		double *	out
	)

Transforms a rectangular equatorial (x, y, z) vector from True of Date (TOD) reference frame at the given epoch to the J2000 coordinates.

Parameters

	jd_tdb	[day] Barycentric Dynamical Time (TDB) based Julian date that defines the input epoch. Typically it does not require much precision, and Julian dates in other time measures will be unlikely to affect the result
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
	in	Input (x, y, z) position or velocity 3-vector in the True equinox of Date coordinate frame.
[out]	out	Output position or velocity vector in rectangular equatorial coordinates at J2000. It can be the same vector as the input.

Returns

0 if successful, or -1 if either of the vector arguments is NULL or the 'accuracy' is invalid.

See also

j2000_to_tod()

j2000_to_gcrs()

tod_to_gcrs()

tod_to_cirs()

tod_to_itrs()

Since

1.0

Author

Attila Kovacs

References NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NUTATE_TRUE_TO_MEAN, nutation(), and precession().