sofa_lib.lis 2008 December 17
----------------------
SOFA Astronomy Library
----------------------
PREFACE
The routines described here comprise the SOFA astronomy library. Their
general appearance and coding style conforms to conventions agreed by
the SOFA Review Board, and their functions, names and algorithms have
been ratified by the Board. Procedures for soliciting and agreeing
additions to the library are still evolving.
PROGRAMMING LANGUAGES
The SOFA routines are available in two programming languages at present:
Fortran 77 and ANSI C.
Except for a single obsolete Fortran routine, which has no C equivalent,
there is a one-to-one relationship between the two language versions.
The naming convention is such that a SOFA routine referred to
generically as "EXAMPL" exists as a Fortran subprogram iau_EXAMPL and a
C function iauExampl. The calls for the two versions are very similar,
with the same arguments in the same order. In a few cases, the C
equivalent of a Fortran SUBROUTINE subprogram uses a return value rather
than an argument.
GENERAL PRINCIPLES
The principal function of the SOFA Astronomy Library is to provide
definitive algorithms. A secondary function is to provide software
suitable for convenient direct use by writers of astronomical
applications.
The astronomy routines call on the SOFA vector/matrix library routines,
which are separately listed.
The routines are designed to exploit the full floating-point accuracy
of the machines on which they run, and not to rely on compiler
optimizations. Within these constraints, the intention is that the code
corresponds to the published formulation (if any).
Dates are always Julian Dates (except in calendar conversion routines)
and are expressed as two double precision numbers which sum to the
required value.
A distinction is made between routines that implement IAU-approved
models and those that use those models to create other results. The
former are referred to as "canonical models" in the preamble comments;
the latter are described as "support routines".
Using the library requires knowledge of positional astronomy and
time-scales. These topics are covered in "Explanatory Supplement to the
Astronomical Almanac", P. Kenneth Seidelmann (ed.), University Science
Books, 1992. Recent developments are documented in the journals, and
references to the relevant papers are given in the SOFA code as
required. The IERS Conventions are also an essential reference. The
routines concerned with Earth attitude (precession-nutation etc.) are
described in the SOFA document sofa_pn.pdf.
ROUTINES
Calendars
CAL2JD Gregorian calendar to Julian Day number
EPB Julian Date to Besselian Epoch
EPB2JD Besselian Epoch to Julian Date
EPJ Julian Date to Julian Epoch
EPJ2JD Julian Epoch to Julian Date
JD2CAL Julian Date to Gregorian year, month, day, fraction
JDCALF Julian Date to Gregorian date for formatted output
Time scales
DAT Delta(AT) (=TAI-UTC) for a given UTC date
DTDB TDB-TT
Earth rotation angle and sidereal time
EE00 equation of the equinoxes, IAU 2000
EE00A equation of the equinoxes, IAU 2000A
EE00B equation of the equinoxes, IAU 2000B
EE06A equation of the equinoxes, IAU 2006/2000A
EECT00 equation of the equinoxes complementary terms, IAU 2000
EQEQ94 equation of the equinoxes, IAU 1994
ERA00 Earth rotation angle, IAU 2000
GMST00 Greenwich mean sidereal time, IAU 2000
GMST06 Greenwich mean sidereal time, IAU 2006
GMST82 Greenwich mean sidereal time, IAU 1982
GST00A Greenwich apparent sidereal time, IAU 2000A
GST00B Greenwich apparent sidereal time, IAU 2000B
GST06 Greenwich apparent ST, IAU 2006, given NPB matrix
GST06A Greenwich apparent sidereal time, IAU 2006/2000A
GST94 Greenwich apparent sidereal time, IAU 1994
Ephemerides (limited precision)
EPV00 Earth position and velocity
PLAN94 major-planet position and velocity
Precession, nutation, polar motion
BI00 frame bias components, IAU 2000
BP00 frame bias and precession matrices, IAU 2000
BP06 frame bias and precession matrices, IAU 2006
BPN2XY extract CIP X,Y coordinates from NPB matrix
C2I00A celestial-to-intermediate matrix, IAU 2000A
C2I00B celestial-to-intermediate matrix, IAU 2000B
C2I06A celestial-to-intermediate matrix, IAU 2006/2000A
C2IBPN celestial-to-intermediate matrix, given NPB matrix, IAU 2000
C2IXY celestial-to-intermediate matrix, given X,Y, IAU 2000
C2IXYS celestial-to-intermediate matrix, given X,Y and s
C2T00A celestial-to-terrestrial matrix, IAU 2000A
C2T00B celestial-to-terrestrial matrix, IAU 2000B
C2T06A celestial-to-terrestrial matrix, IAU 2006/2000A
C2TCIO form CIO-based celestial-to-terrestrial matrix
C2TEQX form equinox-based celestial-to-terrestrial matrix
C2TPE celestial-to-terrestrial matrix given nutation, IAU 2000
C2TXY celestial-to-terrestrial matrix given CIP, IAU 2000
EO06A equation of the origins, IAU 2006/2000A
EORS equation of the origins, given NPB matrix and s
FW2M Fukushima-Williams angles to r-matrix
FW2XY Fukushima-Williams angles to X,Y
NUM00A nutation matrix, IAU 2000A
NUM00B nutation matrix, IAU 2000B
NUM06A nutation matrix, IAU 2006/2000A
NUMAT form nutation matrix
NUT00A nutation, IAU 2000A
NUT00B nutation, IAU 2000B
NUT06A nutation, IAU 2006/2000A
NUT80 nutation, IAU 1980
NUTM80 nutation matrix, IAU 1980
OBL06 mean obliquity, IAU 2006
OBL80 mean obliquity, IAU 1980
PB06 zeta,z,theta precession angles, IAU 2006, including bias
PFW06 bias-precession Fukushima-Williams angles, IAU 2006
PMAT00 precession matrix (including frame bias), IAU 2000
PMAT06 PB matrix, IAU 2006
PMAT76 precession matrix, IAU 1976
PN00 bias/precession/nutation results, IAU 2000
PN00A bias/precession/nutation, IAU 2000A
PN00B bias/precession/nutation, IAU 2000B
PN06 bias/precession/nutation results, IAU 2006
PN06A bias/precession/nutation results, IAU 2006/2000A
PNM00A classical NPB matrix, IAU 2000A
PNM00B classical NPB matrix, IAU 2000B
PNM06A classical NPB matrix, IAU 2006/2000A
PNM80 precession/nutation matrix, IAU 1976/1980
P06E precession angles, IAU 2006, equinox based
POM00 polar motion matrix
PR00 IAU 2000 precession adjustments
PREC76 accumulated precession angles, IAU 1976
S00 the CIO locator s, given X,Y, IAU 2000A
S00A the CIO locator s, IAU 2000A
S00B the CIO locator s, IAU 2000B
S06 the CIO locator s, given X,Y, IAU 2006
S06A the CIO locator s, IAU 2006/2000A
SP00 the TIO locator s', IERS 2003
XY06 CIP, IAU 2006/2000A, from series
XYS00A CIP and s, IAU 2000A
XYS00B CIP and s, IAU 2000B
XYS06A CIP and s, IAU 2006/2000A
Fundamental arguments for nutation etc.
FAD03 mean elongation of the Moon from the Sun
FAE03 mean longitude of Earth
FAF03 mean argument of the latitude of the Moon
FAJU03 mean longitude of Jupiter
FAL03 mean anomaly of the Moon
FALP03 mean anomaly of the Sun
FAMA03 mean longitude of Mars
FAME03 mean longitude of Mercury
FANE03 mean longitude of Neptune
FAOM03 mean longitude of the Moon's ascending node
FAPA03 general accumulated precession in longitude
FASA03 mean longitude of Saturn
FAUR03 mean longitude of Uranus
FAVE03 mean longitude of Venus
Star space motion
PVSTAR space motion pv-vector to star catalog data
STARPV star catalog data to space motion pv-vector
Star catalog conversions
FK52H transform FK5 star data into the Hipparcos system
FK5HIP FK5 to Hipparcos rotation and spin
FK5HZ FK5 to Hipparcos assuming zero Hipparcos proper motion
H2FK5 transform Hipparcos star data into the FK5 system
HFK5Z Hipparcos to FK5 assuming zero Hipparcos proper motion
STARPM proper motion between two epochs
Obsolete
C2TCEO former name of C2TCIO
CALLS: FORTRAN VERSION
CALL iau_BI00 ( DPSIBI, DEPSBI, DRA )
CALL iau_BP00 ( DATE1, DATE2, RB, RP, RBP )
CALL iau_BP06 ( DATE1, DATE2, RB, RP, RBP )
CALL iau_BPN2XY ( RBPN, X, Y )
CALL iau_C2I00A ( DATE1, DATE2, RC2I )
CALL iau_C2I00B ( DATE1, DATE2, RC2I )
CALL iau_C2I06A ( DATE1, DATE2, RC2I )
CALL iau_C2IBPN ( DATE1, DATE2, RBPN, RC2I )
CALL iau_C2IXY ( DATE1, DATE2, X, Y, RC2I )
CALL iau_C2IXYS ( X, Y, S, RC2I )
CALL iau_C2T00A ( TTA, TTB, UTA, UTB, XP, YP, RC2T )
CALL iau_C2T00B ( TTA, TTB, UTA, UTB, XP, YP, RC2T )
CALL iau_C2T06A ( TTA, TTB, UTA, UTB, XP, YP, RC2T )
CALL iau_C2TCEO ( RC2I, ERA, RPOM, RC2T )
CALL iau_C2TCIO ( RC2I, ERA, RPOM, RC2T )
CALL iau_C2TEQX ( RBPN, GST, RPOM, RC2T )
CALL iau_C2TPE ( TTA, TTB, UTA, UTB, DPSI, DEPS, XP, YP, RC2T )
CALL iau_C2TXY ( TTA, TTB, UTA, UTB, X, Y, XP, YP, RC2T )
CALL iau_CAL2JD ( IY, IM, ID, DJM0, DJM, J )
CALL iau_DAT ( IY, IM, ID, FD, DELTAT, J )
D = iau_DTDB ( DATE1, DATE2, UT, ELONG, U, V )
D = iau_EE00 ( DATE1, DATE2, EPSA, DPSI )
D = iau_EE00A ( DATE1, DATE2 )
D = iau_EE00B ( DATE1, DATE2 )
D = iau_EE06A ( DATE1, DATE2 )
D = iau_EECT00 ( DATE1, DATE2 )
D = iau_EO06A ( DATE1, DATE2 )
D = iau_EORS ( RNPB, S )
D = iau_EPB ( DJ1, DJ2 )
CALL iau_EPB2JD ( EPB, DJM0, DJM )
D = iau_EPJ ( DJ1, DJ2 )
CALL iau_EPJ2JD ( EPJ, DJM0, DJM )
CALL iau_EPV00 ( DJ1, DJ2, PVH, PVB, J )
D = iau_EQEQ94 ( DATE1, DATE2 )
D = iau_ERA00 ( DJ1, DJ2 )
D = iau_FAD03 ( T )
D = iau_FAE03 ( T )
D = iau_FAF03 ( T )
D = iau_FAJU03 ( T )
D = iau_FAL03 ( T )
D = iau_FALP03 ( T )
D = iau_FAMA03 ( T )
D = iau_FAME03 ( T )
D = iau_FANE03 ( T )
D = iau_FAOM03 ( T )
D = iau_FAPA03 ( T )
D = iau_FASA03 ( T )
D = iau_FAUR03 ( T )
D = iau_FAVE03 ( T )
CALL iau_FK52H ( R5, D5, DR5, DD5, PX5, RV5,
: RH, DH, DRH, DDH, PXH, RVH )
CALL iau_FK5HIP ( R5H, S5H )
CALL iau_FK5HZ ( R5, D5, DATE1, DATE2, RH, DH )
CALL iau_FW2M ( GAMB, PHIB, PSI, EPS, R )
CALL iau_FW2XY ( GAMB, PHIB, PSI, EPS, X, Y )
D = iau_GMST00 ( UTA, UTB, TTA, TTB )
D = iau_GMST06 ( UTA, UTB, TTA, TTB )
D = iau_GMST82 ( UTA, UTB )
D = iau_GST00A ( UTA, UTB, TTA, TTB )
D = iau_GST00B ( UTA, UTB )
D = iau_GST06 ( UTA, UTB, TTA, TTB, RNPB )
D = iau_GST06A ( UTA, UTB, TTA, TTB )
D = iau_GST94 ( UTA, UTB )
CALL iau_H2FK5 ( RH, DH, DRH, DDH, PXH, RVH,
: R5, D5, DR5, DD5, PX5, RV5 )
CALL iau_HFK5Z ( RH, DH, DATE1, DATE2, R5, D5, DR5, DD5 )
CALL iau_JD2CAL ( DJ1, DJ2, IY, IM, ID, FD, J )
CALL iau_JDCALF ( NDP, DJ1, DJ2, IYMDF, J )
CALL iau_NUM00A ( DATE1, DATE2, RMATN )
CALL iau_NUM00B ( DATE1, DATE2, RMATN )
CALL iau_NUM06A ( DATE1, DATE2, RMATN )
CALL iau_NUMAT ( EPSA, DPSI, DEPS, RMATN )
CALL iau_NUT00A ( DATE1, DATE2, DPSI, DEPS )
CALL iau_NUT00B ( DATE1, DATE2, DPSI, DEPS )
CALL iau_NUT06A ( DATE1, DATE2, DPSI, DEPS )
CALL iau_NUT80 ( DATE1, DATE2, DPSI, DEPS )
CALL iau_NUTM80 ( DATE1, DATE2, RMATN )
D = iau_OBL06 ( DATE1, DATE2 )
D = iau_OBL80 ( DATE1, DATE2 )
CALL iau_PB06 ( DATE1, DATE2, BZETA, BZ, BTHETA )
CALL iau_PFW06 ( DATE1, DATE2, GAMB, PHIB, PSIB, EPSA )
CALL iau_PLAN94 ( DATE1, DATE2, NP, PV, J )
CALL iau_PMAT00 ( DATE1, DATE2, RBP )
CALL iau_PMAT06 ( DATE1, DATE2, RBP )
CALL iau_PMAT76 ( DATE1, DATE2, RMATP )
CALL iau_PN00 ( DATE1, DATE2, DPSI, DEPS,
: EPSA, RB, RP, RBP, RN, RBPN )
CALL iau_PN00A ( DATE1, DATE2,
: DPSI, DEPS, EPSA, RB, RP, RBP, RN, RBPN )
CALL iau_PN00B ( DATE1, DATE2,
: DPSI, DEPS, EPSA, RB, RP, RBP, RN, RBPN )
CALL iau_PN06 ( DATE1, DATE2, DPSI, DEPS,
: EPSA, RB, RP, RBP, RN, RBPN )
CALL iau_PN06A ( DATE1, DATE2,
DPSI, DEPS, RB, RP, RBP, RN, RBPN )
CALL iau_PNM00A ( DATE1, DATE2, RBPN )
CALL iau_PNM00B ( DATE1, DATE2, RBPN )
CALL iau_PNM06A ( DATE1, DATE2, RNPB )
CALL iau_PNM80 ( DATE1, DATE2, RMATPN )
CALL iau_P06E ( DATE1, DATE2,
: EPS0, PSIA, OMA, BPA, BQA, PIA, BPIA,
: EPSA, CHIA, ZA, ZETAA, THETAA, PA, GAM, PHI, PSI )
CALL iau_POM00 ( XP, YP, SP, RPOM )
CALL iau_PR00 ( DATE1, DATE2, DPSIPR, DEPSPR )
CALL iau_PREC76 ( EP01, EP02, EP11, EP12, ZETA, Z, THETA )
CALL iau_PVSTAR ( PV, RA, DEC, PMR, PMD, PX, RV, J )
D = iau_S00 ( DATE1, DATE2, X, Y )
D = iau_S00A ( DATE1, DATE2 )
D = iau_S00B ( DATE1, DATE2 )
D = iau_S06 ( DATE1, DATE2, X, Y )
D = iau_S06A ( DATE1, DATE2 )
D = iau_SP00 ( DATE1, DATE2 )
CALL iau_STARPM ( RA1, DEC1, PMR1, PMD1, PX1, RV1,
: EP1A, EP1B, EP2A, EP2B,
: RA2, DEC2, PMR2, PMD2, PX2, RV2, J )
CALL iau_STARPV ( RA, DEC, PMR, PMD, PX, RV, PV, J )
CALL iau_XYS06 ( DATE1, DATE2, X, Y )
CALL iau_XYS00A ( DATE1, DATE2, X, Y, S )
CALL iau_XYS00B ( DATE1, DATE2, X, Y, S )
CALL iau_XYS06A ( DATE1, DATE2, X, Y, S )
CALLS: C VERSION
iauBi00 ( &dpsibi, &depsbi, &dra );
iauBp00 ( date1, date2, rb, rp, rbp );
iauBp06 ( date1, date2, rb, rp, rbp );
iauBpn2xy ( rbpn, &x, &y );
iauC2i00a ( date1, date2, rc2i );
iauC2i00b ( date1, date2, rc2i );
iauC2i06a ( date1, date2, rc2i );
iauC2ibpn ( date1, date2, rbpn, rc2i );
iauC2ixy ( date1, date2, x, y, rc2i );
iauC2ixys ( x, y, s, rc2i );
iauC2t00a ( tta, ttb, uta, utb, xp, yp, rc2t );
iauC2t00b ( tta, ttb, uta, utb, xp, yp, rc2t );
iauC2t06a ( tta, ttb, uta, utb, xp, yp, rc2t );
iauC2tcio ( rc2i, era, rpom, rc2t );
iauC2teqx ( rbpn, gst, rpom, rc2t );
iauC2tpe ( tta, ttb, uta, utb, dpsi, deps, xp, yp, rc2t );
iauC2txy ( tta, ttb, uta, utb, x, y, xp, yp, rc2t );
i = iauCal2jd ( iy, im, id, &djm0, &djm );
i = iauDat ( iy, im, id, fd, &deltat );
d = iauDtdb ( date1, date2, ut, elong, u, v );
d = iauEe00 ( date1, date2, epsa, dpsi );
d = iauEe00a ( date1, date2 );
d = iauEe00b ( date1, date2 );
d = iauEe06 ( date1, date2 );
d = iauEect00 ( date1, date2 );
d = iauEo06 ( date1, date2 );
d = iauEors ( rnpb, s );
d = iauEpb ( dj1, dj2 );
iauEpb2jd ( epb, &djm0, &djm );
d = iauEpj ( dj1, dj2 );
iauEpj2jd ( epj, &djm0, &djm );
i = iauEpv00 ( dj1, dj2, pvh, pvb );
d = iauEqeq94 ( date1, date2 );
d = iauEra00 ( dj1, dj2 );
d = iauFad03 ( t );
d = iauFae03 ( t );
d = iauFaf03 ( t );
d = iauFaju03 ( t );
d = iauFal03 ( t );
d = iauFalp03 ( t );
d = iauFama03 ( t );
d = iauFame03 ( t );
d = iauFane03 ( t );
d = iauFaom03 ( t );
d = iauFapa03 ( t );
d = iauFasa03 ( t );
d = iauFaur03 ( t );
d = iauFave03 ( t );
iauFk52h ( r5, d5, dr5, dd5, px5, rv5,
&rh, &dh, &drh, &ddh, &pxh, &rvh );
iauFk5hip ( r5h, s5h );
iauFk5hz ( r5, d5, date1, date2, &rh, &dh );
iauFw2m ( gamb, phib, psi, eps, r );
iauFw2xy ( gamb, phib, psi, eps, &x, &y );
d = iauGmst00 ( uta, utb, tta, ttb );
d = iauGmst06 ( uta, utb, tta, ttb );
d = iauGmst82 ( uta, utb );
d = iauGst00a ( uta, utb, tta, ttb );
d = iauGst00b ( uta, utb );
d = iauGst06 ( uta, utb, tta, ttb, rnpb );
d = iauGst06a ( uta, utb, tta, ttb );
d = iauGst94 ( uta, utb );
iauH2fk5 ( rh, dh, drh, ddh, pxh, rvh,
&r5, &d5, &dr5, &dd5, &px5, &rv5 );
iauHfk5z ( rh, dh, date1, date2,
&r5, &d5, &dr5, &dd5 );
i = iauJd2cal ( dj1, dj2, &iy, &im, &id, &fd );
i = iauJdcalf ( ndp, dj1, dj2, iymdf );
iauNum00a ( date1, date2, rmatn );
iauNum00b ( date1, date2, rmatn );
iauNum06a ( date1, date2, rmatn );
iauNumat ( epsa, dpsi, deps, rmatn );
iauNut00a ( date1, date2, &dpsi, &deps );
iauNut00b ( date1, date2, &dpsi, &deps );
iauNut06a ( date1, date2, &dpsi, &deps );
iauNut80 ( date1, date2, &dpsi, &deps );
iauNutm80 ( date1, date2, rmatn );
d = iauObl06 ( date1, date2 );
d = iauObl80 ( date1, date2 );
iauPb06 ( date1, date2, &bzeta, &bz, &btheta );
iauPfw06 ( date1, date2, &gamb, &phib, &psib, &epsa );
i = iauPlan94 ( date1, date2, np, pv );
iauPmat00 ( date1, date2, rbp );
iauPmat06 ( date1, date2, rbp );
iauPmat76 ( date1, date2, rmatp );
iauPn00 ( date1, date2, dpsi, deps,
&epsa, rb, rp, rbp, rn, rbpn );
iauPn00a ( date1, date2,
&dpsi, &deps, &epsa, rb, rp, rbp, rn, rbpn );
iauPn00b ( date1, date2,
&dpsi, &deps, &epsa, rb, rp, rbp, rn, rbpn );
iauPn06 ( date1, date2, dpsi, deps,
&epsa, rb, rp, rbp, rn, rbpn );
iauPn06a ( date1, date2,
&dpsi, &deps, &epsa, rb, rp, rbp, rn, rbpn );
iauPnm00a ( date1, date2, rbpn );
iauPnm00b ( date1, date2, rbpn );
iauPnm06a ( date1, date2, rnpb );
iauPnm80 ( date1, date2, rmatpn );
iauP06e ( date1, date2,
&eps0, &psia, &oma, &bpa, &bqa, &pia, &bpia,
&epsa, &chia, &za, &zetaa, &thetaa, &pa,
&gam, &phi, &psi );
iauPom00 ( xp, yp, sp, rpom );
iauPr00 ( date1, date2, &dpsipr, &depspr );
iauPrec76 ( ep01, ep02, ep11, ep12, &zeta, &z, &theta );
i = iauPvstar ( pv, &ra, &dec, &pmr, &pmd, &px, &rv );
d = iauS00 ( date1, date2, x, y );
d = iauS00a ( date1, date2 );
d = iauS00b ( date1, date2 );
d = iauS06 ( date1, date2, x, y );
d = iauS06a ( date1, date2 );
d = iauSp00 ( date1, date2 );
i = iauStarpm ( ra1, dec1, pmr1, pmd1, px1, rv1,
ep1a, ep1b, ep2a, ep2b,
&ra2, &dec2, &pmr2, &pmd2, &px2, &rv2 );
i = iauStarpv ( ra, dec, pmr, pmd, px, rv, pv );
iauXys06 ( date1, date2, &x, &y );
iauXys00a ( date1, date2, &x, &y, &s );
iauXys00b ( date1, date2, &x, &y, &s );
iauXys06a ( date1, date2, &x, &y, &s );