cio.c File Reference

Functions to calculate or access the Celestial Intermediate Origin (CIO) location. More...

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)
	Computes the true right ascension of the celestial intermediate origin (CIO) vs the equinox of date on the true equator of date for a given TT Julian date.
int	set_cio_locator_file (const char *restrict filename)

Detailed Description

Functions to calculate or access the Celestial Intermediate Origin (CIO) location.

The CIO is the origin of the Celestial Intermediate Reference System (CIRS), which is the IAU 2000 dynamic equatorial system of date. CIRS and the old equivalent True of Date (TOD) systems share the same dynamical equator, but differ in where the origin lies on the equator: CIO vs the true equinox of date.

The IAU2000 standard for position calculations typically involves converting between GCRS and CIRS systems, and the IERS Conventions 2010, Chapter 5 describes two equivalent methods to do so.

• Method 1 is the more direct method and involves calculating the position of the Celestial Intermediate Pole (CIP) of date in GCRS, using a harmonic series containing some 2825 lunisolar and planetary terms (IERS Conventions 2010, Tables 5.2a and 5.2b).
• Method 2 is more roundabout, transforming GCRS to J2000 first, then using the IAU 2006 (P03) precession-nutation model to calculate True-of-Date coordinates, which are then transformed to CIRS by a simple rotation with the CIO's position relative to the true-equinox of date. The IAU2006 nutation series uses 2414 lunisolar and planetary terms (IERS Conventions 2010, Tables 5.3a and 5.3b).

The two methods are equivalent both in terms of accuracy, down to the μas level, and in terms of computational cost. Neither is 'superior' to the other in any measurable way. In SuperNOVAS we choose to follow Method 2, since its implementation is more readily given with the existing framework of related functions.

REFERENCES:

1. IERS Conventions 2010, Chapter 5, especially Section 5.9
2. Capitaine, N. et al. (2003), Astronomy And Astrophysics 412, pp. 567-586.

Date

Created on Mar 6, 2025

Author

G. Kaplan and Attila Kovacs

See also

equator.c

Function Documentation

cio_array()

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

Deprecated

This function is no longer used within SuperNOVAS. It is still provided, however, in order to retain 100% API compatibility with NOVAS C.

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 on the requested date.

NOTES:

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

2. The CIO locator file that is bundled was prepared with the original IAU2000A nutation model, not with the newer R06 (a.k.a. IAU2006) nutation model, resulting in an error up to the few tens of micro-arcseconds level for dates between 1900 and 2100, and larger errors further away from the current epoch.

3. Prior to version 1.5, this function relied on a CIO locator file (CIO_RA.TXT or cio_ra.bin). The current version no longer does, and instead generates the requested data on the fly.

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 ra_of_cio::jd_tdb, NOVAS_ARCSEC, NOVAS_HOURANGLE, and ra_of_cio::ra_cio.

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 )

Deprecated

This function is no longer used internally in the library, and users are recommended against using it themselves, since SuperNOVAS provides better ways to convert between GCRS and CIRS using frames or via gcrs_to_cirs() / cirs_to_gcrs() or novas_transform() functions.

Computes the CIRS 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).

This function effectively constructs the CIRS to GCRS transformation matrix C in eq. (3) of the reference.

NOTES:

1. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.

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

gcrs_to_cirs(), cirs_to_gcrs(), novas_make_transform()

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 )

Deprecated

This function is no longer used internally in the library. Given that the CIO is defined on the dynamical equator of date, it is not normally meaningful to provide an R.A. coordinate for it in GCRS. Instead, you might use cio_ra() to get the CIO location w.r.t. the equinox of date (on the same dynamical equator), or equivalently ira_equinox() to return the negated value of the same.

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

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.
2. This function caches the results of the last calculation in case it may be re-used at no extra computational cost for the next call.
3. As of version 1.5, this function always returns the CIO location w.r.t. the true equinox of date, on the true equator of date, i.e. the R.A. of the CIO on the true equator of date, meaured from the true equinox of date.

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

cio_ra(), ira_equinox()

References CIO_VS_EQUINOX, ira_equinox(), NOVAS_FULL_ACCURACY, 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) vs the equinox of date on the true equator of date for a given TT Julian date.

This is simply the negated return value ofira_equinox() for the true equator of date.

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 (+ 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()

See also

ira_equinox()

References ira_equinox(), NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, and NOVAS_TRUE_EQUINOX.

set_cio_locator_file()

int set_cio_locator_file

(

const char *restrict

filename

)

Deprecated

SuperNOVAS no longer uses a NOVAS-type CIO locator file, or accesses one in any way. This function is now a dummy.

It used to set the CIO interpolaton data file to use to interpolate CIO locations vs the GCRS. As of version 1.5, this call does exactly nothing. It simply returns 0.

Parameters

filename

(unused) Used to be the path (preferably absolute path) CIO_RA.TXT or else to the binary cio_ra.bin data, or NULL to disable using a CIO locator file altogether.

Returns

0

See also

cio_location()

Since

1.0

Author

Attila Kovacs