Loading...
Searching...
No Matches
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 )

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 novas_ra_of_cio::jd_tdb, NOVAS_ARCSEC, NOVAS_HOURANGLE, and novas_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 )

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, loc_type, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, novas_vlen(), ra_cio, 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 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(), loc_type, NOVAS_FULL_ACCURACY, NOVAS_REDUCED_ACCURACY, NOVAS_TRUE_EQUINOX, and ra_cio.

## set_cio_locator_file()

int set_cio_locator_file | ( | const char *restrict | filename | ) |

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