cio.c File Reference

Functions
short	cio_array (double jd_tdb, long n_pts, ra_of_cio *restrict cio)
short	cio_basis (double jd_tdb, double ra_cio, enum novas_cio_location_type loc_type, enum novas_accuracy accuracy, double *restrict x, double *restrict y, double *restrict z)
short	cio_location (double jd_tdb, enum novas_accuracy accuracy, double *restrict ra_cio, short *restrict loc_type)
short	cio_ra (double jd_tt, enum novas_accuracy accuracy, double *restrict ra_cio)
int	set_cio_locator_file (const char *restrict filename)

Detailed Description

Date

Created on Mar 6, 2025

Author

G. Kaplan and Attila Kovacs

Functions to handle the CIO location and basis.

Function Documentation

cio_array()

short cio_array	(	double	jd_tdb,
		long	n_pts,
		ra_of_cio *restrict	cio
	)

Given an input TDB Julian date and the number of data points desired, this function returns a set of Julian dates and corresponding values of the GCRS right ascension of the celestial intermediate origin (CIO). The range of dates is centered (at least approximately) on the requested date. The function obtains the data from an external data file.

This function assumes that a CIO locator file (CIO_RA.TXT or cio_ra.bin) exists in the default location (configured at build time), or else was specified via set_cio_locator_file() prior to calling this function.

NOTES:

1. This function has been completely re-written by A. Kovacs to provide much more efficient caching and I/O.

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	n_pts	Number of Julian dates and right ascension values requested (not less than 2 or more than NOVAS_CIO_CACHE_SIZE).
[out]	cio	A time series (array) of the right ascension of the Celestial Intermediate Origin (CIO) with respect to the GCRS.

Returns

0 if successful, -1 if the output array is NULL or there was an I/O error accessing the CIO location data file. Or else 1 if no locator data file is available, 2 if 'jd_tdb' not in the range of the CIO file, 3 if 'n_pts' out of range, or 6 if 'jd_tdb' is too close to either end of the CIO file do we are unable to put 'n_pts' data points into the output

See also

set_cio_locator_file()

cio_location()

References DEFAULT_CIO_LOCATOR_FILE, NOVAS_CIO_CACHE_SIZE, and set_cio_locator_file().

cio_basis()

short cio_basis	(	double	jd_tdb,
		double	ra_cio,
		enum novas_cio_location_type	loc_type,
		enum novas_accuracy	accuracy,
		double *restrict	x,
		double *restrict	y,
		double *restrict	z
	)

Computes the orthonormal basis vectors, with respect to the GCRS (geocentric ICRS), of the celestial intermediate system defined by the celestial intermediate pole (CIP) (in the z direction) and the celestial intermediate origin (CIO) (in the x direction). A TDB Julian date and the right ascension of the CIO at that date is required as input. The right ascension of the CIO can be with respect to either the GCRS origin or the true equinox of date – different algorithms are used in the two cases.

This function effectively constructs the matrix C in eq. (3) of the reference.

REFERENCES:

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

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	ra_cio	[h] Right ascension of the CIO at epoch (hours).
	loc_type	CIO_VS_GCRS (1) if the cio location is relative to the GCRS or else CIO_VS_EQUINOX (2) if relative to the true equinox of date.
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	x	Unit 3-vector toward the CIO, equatorial rectangular coordinates, referred to the GCRS.
[out]	y	Unit 3-vector toward the y-direction, equatorial rectangular coordinates, referred to the GCRS.
[out]	z	Unit 3-vector toward north celestial pole (CIP), equatorial rectangular coordinates, referred to the GCRS.

Returns

0 if successful, or -1 if any of the output vector arguments are NULL or if the accuracy is invalid, or else 1 if 'ref-sys' is invalid.

See also

cio_location()

gcrs_to_cirs()

References CIO_VS_EQUINOX, CIO_VS_GCRS, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, novas_vlen(), and tod_to_gcrs().

cio_location()

short cio_location	(	double	jd_tdb,
		enum novas_accuracy	accuracy,
		double *restrict	ra_cio,
		short *restrict	loc_type
	)

Returns the location of the celestial intermediate origin (CIO) for a given Julian date, as a right ascension with respect to either the GCRS (geocentric ICRS) origin or the true equinox of date. The CIO is always located on the true equator (= intermediate equator) of date.

The user may specify an interpolation file to use via set_cio_locator_file() prior to calling this function. In that case the call will return CIO location relative to GCRS. In the absence of the table, it will calculate the CIO location relative to the true equinox. In either case the type of the location is returned alongside the corresponding CIO location value.

NOTES:

1. Unlike the NOVAS C version of this function, this version will always return a CIO location as long as the pointer arguments are not NULL. The returned values will be interpolated from the locator file if possible, otherwise it falls back to calculating an equinox-based location per default.

Parameters

	jd_tdb	[day] Barycentric Dynamic Time (TDB) based Julian date
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra_cio	[h] Right ascension of the CIO, in hours, or NAN if returning with an error.
[out]	loc_type	Pointer in which to return the reference system in which right ascension is given, which is either CIO_VS_GCRS (1) if the location was obtained via interpolation of the available data file, or else CIO_VS_EQUINOX (2) if it was calculated locally. It is set to -1 if returning with an error.

Returns

0 if successful, -1 if one of the pointer arguments is NULL or the accuracy is invalid.

See also

set_cio_locator_file()

cio_ra()

gcrs_to_cirs()

References cio_array(), CIO_VS_EQUINOX, CIO_VS_GCRS, ira_equinox(), novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DEBUG_ON, NOVAS_FULL_ACCURACY, novas_get_debug_mode(), NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

cio_ra()

short cio_ra	(	double	jd_tt,
		enum novas_accuracy	accuracy,
		double *restrict	ra_cio
	)

Computes the true right ascension of the celestial intermediate origin (CIO) at a given TT Julian date. This is the negative value for the equation of the origins.

REFERENCES:

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

Parameters

	jd_tt	[day] Terrestrial Time (TT) based Julian date
	accuracy	NOVAS_FULL_ACCURACY (0) or NOVAS_REDUCED_ACCURACY (1)
[out]	ra_cio	[h] Right ascension of the CIO, with respect to the true equinox of date, in hours (+ or -), or NAN when returning with an error code.

Returns

0 if successful, -1 if the output pointer argument is NULL, 1 if 'accuracy' is invalid, 10–20: 10 + error code from cio_location(), or else 20 + error from cio_basis()

References cio_basis(), cio_location(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, tod_to_gcrs(), and tt2tdb().

set_cio_locator_file()

int set_cio_locator_file

(

const char *restrict

filename

)

Sets the CIO interpolaton data file to use to interpolate CIO locations vs the GCRS. You can specify either the original CIO_RA.TXT file included in the distribution (preferred since v1.1), or else a platform-specific binary data file compiled from it via the cio_file utility (the old way).

Parameters

filename

Path (preferably absolute path) CIO_RA.TXT or else to the binary cio_ra.bin data.

Returns

0 if successful, or else -1 if the specified file does not exists or we have no permission to read it.

See also

cio_location()

gcrs_to_cirs()

Since

1.0

Author

Attila Kovacs