canonical

Functions
int	iauEform (int n, double *a, double *f)
	Earth reference ellipsoids. More...
int	iauTaitt (double tai1, double tai2, double *tt1, double *tt2)
	TAI to TT. More...
int	iauTaiut1 (double tai1, double tai2, double dta, double *ut11, double *ut12)
	TAI to UT1. More...
int	iauTaiutc (double tai1, double tai2, double *utc1, double *utc2)
	TAI to UTC. More...
int	iauTcbtdb (double tcb1, double tcb2, double *tdb1, double *tdb2)
	TCB to TDB. More...
int	iauTcgtt (double tcg1, double tcg2, double *tt1, double *tt2)
	TCG to TT. More...
int	iauTdbtcb (double tdb1, double tdb2, double *tcb1, double *tcb2)
	TDB to TCB. More...
int	iauTdbtt (double tdb1, double tdb2, double dtr, double *tt1, double *tt2)
	TDB to TT. More...
int	iauTttai (double tt1, double tt2, double *tai1, double *tai2)
	TT to TAI. More...
int	iauTttcg (double tt1, double tt2, double *tcg1, double *tcg2)
	TT to TCG. More...
int	iauTttdb (double tt1, double tt2, double dtr, double *tdb1, double *tdb2)
	TT to TDB. More...
int	iauTtut1 (double tt1, double tt2, double dt, double *ut11, double *ut12)
	TT to UT1. More...
int	iauUt1tai (double ut11, double ut12, double dta, double *tai1, double *tai2)
	UT1 to TAI. More...
int	iauUt1tt (double ut11, double ut12, double dt, double *tt1, double *tt2)
	UT1 to TT. More...
int	iauUt1utc (double ut11, double ut12, double dut1, double *utc1, double *utc2)
	UT1 to UTC. More...
int	iauUtctai (double utc1, double utc2, double *tai1, double *tai2)
	UTC to TAI. More...
int	iauUtcut1 (double utc1, double utc2, double dut1, double *ut11, double *ut12)
	UTC to UT1. More...

Detailed Description

Function Documentation

iauEform()

int iauEform	(	int	n,
		double *	a,
		double *	f
	)

Earth reference ellipsoids.

Parameters

[in]	n	ellipsoid identifier (Note 1)
[out]	a	equatorial radius (meters, Note 2)
[out]	f	flattening (Note 2)

Returns

0 = OK -1 = illegal identifier (Note 3)

Notes:

1) The identifier n is a number that specifies the choice of reference ellipsoid. The following are supported:

n ellipsoid

1 WGS84 2 GRS80 3 WGS72

The n value has no significance outside the SOFA software. For convenience, symbols WGS84 etc. are defined in sofam.h.

2) The ellipsoid parameters are returned in the form of equatorial radius in meters (a) and flattening (f). The latter is a number around 0.00335, i.e. around 1/298.

3) For the case where an unsupported n value is supplied, zero a and f are returned, as well as error status.

References:

Department of Defense World Geodetic System 1984, National Imagery and Mapping Agency Technical Report 8350.2, Third Edition, p3-2.

Moritz, H., Bull. Geodesique 66-2, 187 (1992).

The Department of Defense World Geodetic System 1972, World Geodetic System Committee, May 1974.

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992), p220.

iauTaitt()

int iauTaitt	(	double	tai1,
		double	tai2,
		double *	tt1,
		double *	tt2
	)

TAI to TT.

Time scale transformation: International Atomic Time, TAI, to Terrestrial Time, TT.

Parameters

[in]	tai1,tai2	TAI as a 2-part Julian Date
[out]	tt1,tt2	TT as a 2-part Julian Date

Returns

status: 0 = OK

Note:

tai1+tai2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tai1 is the Julian Day Number and tai2 is the fraction of a day. The returned tt1,tt2 follow suit.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauTaiut1()

int iauTaiut1	(	double	tai1,
		double	tai2,
		double	dta,
		double *	ut11,
		double *	ut12
	)

TAI to UT1.

Time scale transformation: International Atomic Time, TAI, to Universal Time, UT1.

Parameters

[in]	tai1,tai2	TAI as a 2-part Julian Date
[in]	dta	UT1-TAI in seconds
[out]	ut11,ut12	UT1 as a 2-part Julian Date

Returns

status: 0 = OK

Notes:

1) tai1+tai2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tai1 is the Julian Day Number and tai2 is the fraction of a day. The returned UT11,UT12 follow suit.

2) The argument dta, i.e. UT1-TAI, is an observed quantity, and is available from IERS tabulations.

Reference:

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauTaiutc()

int iauTaiutc	(	double	tai1,
		double	tai2,
		double *	utc1,
		double *	utc2
	)

TAI to UTC.

Time scale transformation: International Atomic Time, TAI, to Coordinated Universal Time, UTC.

Parameters

[in]	tai1,tai2	TAI as a 2-part Julian Date (Note 1)
[out]	utc1,utc2	UTC as a 2-part quasi Julian Date (Notes 1-3)

Returns

status: +1 = dubious year (Note 4) 0 = OK -1 = unacceptable date

Notes:

1) tai1+tai2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tai1 is the Julian Day Number and tai2 is the fraction of a day. The returned utc1 and utc2 form an analogous pair, except that a special convention is used, to deal with the problem of leap seconds - see the next note.

2) JD cannot unambiguously represent UTC during a leap second unless special measures are taken. The convention in the present function is that the JD day represents UTC days whether the length is 86399, 86400 or 86401 SI seconds. In the 1960-1972 era there were smaller jumps (in either direction) each time the linear UTC(TAI) expression was changed, and these "mini-leaps" are also included in the SOFA convention.

3) The function iauD2dtf can be used to transform the UTC quasi-JD into calendar date and clock time, including UTC leap second handling.

4) The warning status "dubious year" flags UTCs that predate the introduction of the time scale or that are too far in the future to be trusted. See iauDat for further details.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

Here is the call graph for this function:

iauTcbtdb()

int iauTcbtdb	(	double	tcb1,
		double	tcb2,
		double *	tdb1,
		double *	tdb2
	)

TCB to TDB.

Time scale transformation: Barycentric Coordinate Time, TCB, to Barycentric Dynamical Time, TDB.

Parameters

[in]	tcb1,tcb2	TCB as a 2-part Julian Date
[out]	tdb1,tdb2	TDB as a 2-part Julian Date

Returns

status: 0 = OK

Notes:

1) tcb1+tcb2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tcb1 is the Julian Day Number and tcb2 is the fraction of a day. The returned tdb1,tdb2 follow suit.

2) The 2006 IAU General Assembly introduced a conventional linear transformation between TDB and TCB. This transformation compensates for the drift between TCB and terrestrial time TT, and keeps TDB approximately centered on TT. Because the relationship between TT and TCB depends on the adopted solar system ephemeris, the degree of alignment between TDB and TT over long intervals will vary according to which ephemeris is used. Former definitions of TDB attempted to avoid this problem by stipulating that TDB and TT should differ only by periodic effects. This is a good description of the nature of the relationship but eluded precise mathematical formulation. The conventional linear relationship adopted in 2006 sidestepped these difficulties whilst delivering a TDB that in practice was consistent with values before that date.

3) TDB is essentially the same as Teph, the time argument for the JPL solar system ephemerides.

Reference:

IAU 2006 Resolution B3

iauTcgtt()

int iauTcgtt	(	double	tcg1,
		double	tcg2,
		double *	tt1,
		double *	tt2
	)

TCG to TT.

Time scale transformation: Geocentric Coordinate Time, TCG, to Terrestrial Time, TT.

Parameters

[in]	tcg1,tcg2	TCG as a 2-part Julian Date
[out]	tt1,tt2	TT as a 2-part Julian Date

Returns

status: 0 = OK

Note:

tcg1+tcg2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tcg1 is the Julian Day Number and tcg22 is the fraction of a day. The returned tt1,tt2 follow suit.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003),. IERS Technical Note No. 32, BKG (2004)

IAU 2000 Resolution B1.9

iauTdbtcb()

int iauTdbtcb	(	double	tdb1,
		double	tdb2,
		double *	tcb1,
		double *	tcb2
	)

TDB to TCB.

Time scale transformation: Barycentric Dynamical Time, TDB, to Barycentric Coordinate Time, TCB.

Parameters

[in]	tdb1,tdb2	TDB as a 2-part Julian Date
[out]	tcb1,tcb2	TCB as a 2-part Julian Date

Returns

status: 0 = OK

Notes:

1) tdb1+tdb2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tdb1 is the Julian Day Number and tdb2 is the fraction of a day. The returned tcb1,tcb2 follow suit.

2) The 2006 IAU General Assembly introduced a conventional linear transformation between TDB and TCB. This transformation compensates for the drift between TCB and terrestrial time TT, and keeps TDB approximately centered on TT. Because the relationship between TT and TCB depends on the adopted solar system ephemeris, the degree of alignment between TDB and TT over long intervals will vary according to which ephemeris is used. Former definitions of TDB attempted to avoid this problem by stipulating that TDB and TT should differ only by periodic effects. This is a good description of the nature of the relationship but eluded precise mathematical formulation. The conventional linear relationship adopted in 2006 sidestepped these difficulties whilst delivering a TDB that in practice was consistent with values before that date.

3) TDB is essentially the same as Teph, the time argument for the JPL solar system ephemerides.

Reference:

IAU 2006 Resolution B3

iauTdbtt()

int iauTdbtt	(	double	tdb1,
		double	tdb2,
		double	dtr,
		double *	tt1,
		double *	tt2
	)

TDB to TT.

Time scale transformation: Barycentric Dynamical Time, TDB, to Terrestrial Time, TT.

Parameters

[in]	tdb1,tdb2	TDB as a 2-part Julian Date
[in]	dtr	TDB-TT in seconds
[out]	tt1,tt2	TT as a 2-part Julian Date

Returns

status: 0 = OK

Notes:

1) tdb1+tdb2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tdb1 is the Julian Day Number and tdb2 is the fraction of a day. The returned tt1,tt2 follow suit.

2) The argument dtr represents the quasi-periodic component of the GR transformation between TT and TCB. It is dependent upon the adopted solar-system ephemeris, and can be obtained by numerical integration, by interrogating a precomputed time ephemeris or by evaluating a model such as that implemented in the SOFA function iauDtdb. The quantity is dominated by an annual term of 1.7 ms amplitude.

3) TDB is essentially the same as Teph, the time argument for the JPL solar system ephemerides.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

IAU 2006 Resolution 3

iauTttai()

int iauTttai	(	double	tt1,
		double	tt2,
		double *	tai1,
		double *	tai2
	)

TT to TAI.

Time scale transformation: Terrestrial Time, TT, to International Atomic Time, TAI.

Parameters

[in]	tt1,tt2	TT as a 2-part Julian Date
[out]	tai1,tai2	TAI as a 2-part Julian Date

Returns

status: 0 = OK

Note:

tt1+tt2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tt1 is the Julian Day Number and tt2 is the fraction of a day. The returned tai1,tai2 follow suit.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauTttcg()

int iauTttcg	(	double	tt1,
		double	tt2,
		double *	tcg1,
		double *	tcg2
	)

TT to TCG.

Time scale transformation: Terrestrial Time, TT, to Geocentric Coordinate Time, TCG.

Parameters

[in]	tt1,tt2	TT as a 2-part Julian Date
[out]	tcg1,tcg2	TCG as a 2-part Julian Date

Returns

status: 0 = OK

Note:

tt1+tt2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tt1 is the Julian Day Number and tt2 is the fraction of a day. The returned tcg1,tcg2 follow suit.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

IAU 2000 Resolution B1.9

iauTttdb()

int iauTttdb	(	double	tt1,
		double	tt2,
		double	dtr,
		double *	tdb1,
		double *	tdb2
	)

TT to TDB.

Time scale transformation: Terrestrial Time, TT, to Barycentric Dynamical Time, TDB.

Parameters

[in]	tt1,tt2	TT as a 2-part Julian Date
[in]	dtr	TDB-TT in seconds
[out]	tdb1,tdb2	TDB as a 2-part Julian Date

Returns

status: 0 = OK

Notes:

1) tt1+tt2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tt1 is the Julian Day Number and tt2 is the fraction of a day. The returned tdb1,tdb2 follow suit.

2) The argument dtr represents the quasi-periodic component of the GR transformation between TT and TCB. It is dependent upon the adopted solar-system ephemeris, and can be obtained by numerical integration, by interrogating a precomputed time ephemeris or by evaluating a model such as that implemented in the SOFA function iauDtdb. The quantity is dominated by an annual term of 1.7 ms amplitude.

3) TDB is essentially the same as Teph, the time argument for the JPL solar system ephemerides.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

IAU 2006 Resolution 3

iauTtut1()

int iauTtut1	(	double	tt1,
		double	tt2,
		double	dt,
		double *	ut11,
		double *	ut12
	)

TT to UT1.

Time scale transformation: Terrestrial Time, TT, to Universal Time, UT1.

Parameters

[in]	tt1,tt2	TT as a 2-part Julian Date
[in]	dt	TT-UT1 in seconds
[out]	ut11,ut12	UT1 as a 2-part Julian Date

Returns

0 = OK

Notes:

1) tt1+tt2 is Julian Date, apportioned in any convenient way between the two arguments, for example where tt1 is the Julian Day Number and tt2 is the fraction of a day. The returned ut11,ut12 follow suit.

2) The argument dt is classical Delta T.

Reference:

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauUt1tai()

int iauUt1tai	(	double	ut11,
		double	ut12,
		double	dta,
		double *	tai1,
		double *	tai2
	)

UT1 to TAI.

Time scale transformation: Universal Time, UT1, to International Atomic Time, TAI.

Parameters

[in]	ut11,ut12	UT1 as a 2-part Julian Date
[in]	dta	UT1-TAI in seconds
[out]	tai1,tai2	TAI as a 2-part Julian Date

Returns

0 = OK

Notes:

1) ut11+ut12 is Julian Date, apportioned in any convenient way between the two arguments, for example where ut11 is the Julian Day Number and ut12 is the fraction of a day. The returned tai1,tai2 follow suit.

2) The argument dta, i.e. UT1-TAI, is an observed quantity, and is available from IERS tabulations.

Reference:

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauUt1tt()

int iauUt1tt	(	double	ut11,
		double	ut12,
		double	dt,
		double *	tt1,
		double *	tt2
	)

UT1 to TT.

Time scale transformation: Universal Time, UT1, to Terrestrial Time, TT.

Parameters

[in]	ut11,ut12	UT1 as a 2-part Julian Date
[in]	dt	TT-UT1 in seconds
[out]	tt1,tt2	TT as a 2-part Julian Date

Returns

0 = OK

Notes:

1) ut11+ut12 is Julian Date, apportioned in any convenient way between the two arguments, for example where ut11 is the Julian Day Number and ut12 is the fraction of a day. The returned tt1,tt2 follow suit.

2) The argument dt is classical Delta T.

Reference:

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

iauUt1utc()

int iauUt1utc	(	double	ut11,
		double	ut12,
		double	dut1,
		double *	utc1,
		double *	utc2
	)

UT1 to UTC.

Time scale transformation: Universal Time, UT1, to Coordinated Universal Time, UTC.

Parameters

[in]	ut11,ut12	UT1 as a 2-part Julian Date (Note 1)
[in]	dut1	Delta UT1: UT1-UTC in seconds (Note 2)
[out]	utc1,utc2	UTC as a 2-part quasi Julian Date (Notes 3,4)

Returns

+1 = dubious year (Note 5) 0 = OK -1 = unacceptable date

Notes:

1) ut11+ut12 is Julian Date, apportioned in any convenient way between the two arguments, for example where ut11 is the Julian Day Number and ut12 is the fraction of a day. The returned utc1 and utc2 form an analogous pair, except that a special convention is used, to deal with the problem of leap seconds - see Note 3.

2) Delta UT1 can be obtained from tabulations provided by the International Earth Rotation and Reference Systems Service. The value changes abruptly by 1s at a leap second; however, close to a leap second the algorithm used here is tolerant of the "wrong" choice of value being made.

3) JD cannot unambiguously represent UTC during a leap second unless special measures are taken. The convention in the present function is that the returned quasi JD day UTC1+UTC2 represents UTC days whether the length is 86399, 86400 or 86401 SI seconds.

4) The function iauD2dtf can be used to transform the UTC quasi-JD into calendar date and clock time, including UTC leap second handling.

5) The warning status "dubious year" flags UTCs that predate the introduction of the time scale or that are too far in the future to be trusted. See iauDat for further details.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

Here is the call graph for this function:

iauUtctai()

int iauUtctai	(	double	utc1,
		double	utc2,
		double *	tai1,
		double *	tai2
	)

UTC to TAI.

Time scale transformation: Coordinated Universal Time, UTC, to International Atomic Time, TAI.

Parameters

[in]	utc1,utc2	UTC as a 2-part quasi Julian Date (Notes 1-4)
[out]	tai1,tai2	TAI as a 2-part Julian Date (Note 5)

Returns

+1 = dubious year (Note 3) 0 = OK -1 = unacceptable date

Notes:

1) utc1+utc2 is quasi Julian Date (see Note 2), apportioned in any convenient way between the two arguments, for example where utc1 is the Julian Day Number and utc2 is the fraction of a day.

2) JD cannot unambiguously represent UTC during a leap second unless special measures are taken. The convention in the present function is that the JD day represents UTC days whether the length is 86399, 86400 or 86401 SI seconds. In the 1960-1972 era there were smaller jumps (in either direction) each time the linear UTC(TAI) expression was changed, and these "mini-leaps" are also included in the SOFA convention.

3) The warning status "dubious year" flags UTCs that predate the introduction of the time scale or that are too far in the future to be trusted. See iauDat for further details.

4) The function iauDtf2d converts from calendar date and time of day into 2-part Julian Date, and in the case of UTC implements the leap-second-ambiguity convention described above.

5) The returned TAI1,TAI2 are such that their sum is the TAI Julian Date.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

Here is the call graph for this function:

iauUtcut1()

int iauUtcut1	(	double	utc1,
		double	utc2,
		double	dut1,
		double *	ut11,
		double *	ut12
	)

UTC to UT1.

Time scale transformation: Coordinated Universal Time, UTC, to Universal Time, UT1.

Parameters

[in]	utc1,utc2	UTC as a 2-part quasi Julian Date (Notes 1-4)
[in]	dut1	Delta UT1 = UT1-UTC in seconds (Note 5)
[out]	ut11,ut12	UT1 as a 2-part Julian Date (Note 6)

Returns

+1 = dubious year (Note 3) 0 = OK -1 = unacceptable date

Notes:

1) utc1+utc2 is quasi Julian Date (see Note 2), apportioned in any convenient way between the two arguments, for example where utc1 is the Julian Day Number and utc2 is the fraction of a day.

2) JD cannot unambiguously represent UTC during a leap second unless special measures are taken. The convention in the present function is that the JD day represents UTC days whether the length is 86399, 86400 or 86401 SI seconds.

3) The warning status "dubious year" flags UTCs that predate the introduction of the time scale or that are too far in the future to be trusted. See iauDat for further details.

4) The function iauDtf2d converts from calendar date and time of day into 2-part Julian Date, and in the case of UTC implements the leap-second-ambiguity convention described above.

5) Delta UT1 can be obtained from tabulations provided by the International Earth Rotation and Reference Systems Service. It is the caller's responsibility to supply a dut1 argument containing the UT1-UTC value that matches the given UTC.

6) The returned ut11,ut12 are such that their sum is the UT1 Julian Date.

References:

McCarthy, D. D., Petit, G. (eds.), IERS Conventions (2003), IERS Technical Note No. 32, BKG (2004)

Explanatory Supplement to the Astronomical Almanac, P. Kenneth Seidelmann (ed), University Science Books (1992)

Here is the call graph for this function: