diff options
| author | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
|---|---|---|
| committer | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
| commit | fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 (patch) | |
| tree | bdda434976bc09c864f2e4fa6f16ba1952b1e555 /math/slalib/doc | |
| download | iraf-linux-fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4.tar.gz | |
Initial commit
Diffstat (limited to 'math/slalib/doc')
187 files changed, 24144 insertions, 0 deletions
diff --git a/math/slalib/doc/addet.hlp b/math/slalib/doc/addet.hlp new file mode 100644 index 00000000..464dd86a --- /dev/null +++ b/math/slalib/doc/addet.hlp @@ -0,0 +1,42 @@ +.help addet Jun99 "Slalib Package" +.nf + + SUBROUTINE slADET (RM, DM, EQ, RC, DC) + + - - - - - - + A D E T + - - - - - - + + Add the E-terms (elliptic component of annual aberration) + to a pre IAU 1976 mean place to conform to the old + catalogue convention (double precision) + + Given: + RM,DM dp RA,Dec (radians) without E-terms + EQ dp Besselian epoch of mean equator and equinox + + Returned: + RC,DC dp RA,Dec (radians) with E-terms included + + Note: + + Most star positions from pre-1984 optical catalogues (or + derived from astrometry using such stars) embody the + E-terms. If it is necessary to convert a formal mean + place (for example a pulsar timing position) to one + consistent with such a star catalogue, then the RA,Dec + should be adjusted using this routine. + + Reference: + Explanatory Supplement to the Astronomical Ephemeris, + section 2D, page 48. + + Called: slETRM, slDS2C, slDC2S, slDA2P, slDA1P + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/afin.hlp b/math/slalib/doc/afin.hlp new file mode 100644 index 00000000..f3c5a22c --- /dev/null +++ b/math/slalib/doc/afin.hlp @@ -0,0 +1,91 @@ +.help afin Jun99 "Slalib Package" +.nf + + SUBROUTINE slAFIN (STRING, IPTR, A, J) + + - - - - - + A F I N + - - - - - + + Sexagesimal character string to angle (single precision) + + Given: + STRING c*(*) string containing deg, arcmin, arcsec fields + IPTR i pointer to start of decode (1st = 1) + + Returned: + IPTR i advanced past the decoded angle + A r angle in radians + J i status: 0 = OK + +1 = default, A unchanged + -1 = bad degrees ) + -2 = bad arcminutes ) (note 3) + -3 = bad arcseconds ) + + Example: + + argument before after + + STRING '-57 17 44.806 12 34 56.7' unchanged + IPTR 1 16 (points to 12...) + A ? -1.00000 + J ? 0 + + A further call to slAFIN, without adjustment of IPTR, will + decode the second angle, 12deg 34min 56.7sec. + + Notes: + + 1) The first three "fields" in STRING are degrees, arcminutes, + arcseconds, separated by spaces or commas. The degrees field + may be signed, but not the others. The decoding is carried + out by the DFLTIN routine and is free-format. + + 2) Successive fields may be absent, defaulting to zero. For + zero status, the only combinations allowed are degrees alone, + degrees and arcminutes, and all three fields present. If all + three fields are omitted, a status of +1 is returned and A is + unchanged. In all other cases A is changed. + + 3) Range checking: + + The degrees field is not range checked. However, it is + expected to be integral unless the other two fields are + absent. + + The arcminutes field is expected to be 0-59, and integral if + the arcseconds field is present. If the arcseconds field + is absent, the arcminutes is expected to be 0-59.9999... + + The arcseconds field is expected to be 0-59.9999... + + 4) Decoding continues even when a check has failed. Under these + circumstances the field takes the supplied value, defaulting + to zero, and the result A is computed and returned. + + 5) Further fields after the three expected ones are not treated + as an error. The pointer IPTR is left in the correct state + for further decoding with the present routine or with DFLTIN + etc. See the example, above. + + 6) If STRING contains hours, minutes, seconds instead of degrees + etc, or if the required units are turns (or days) instead of + radians, the result A should be multiplied as follows: + + for to obtain multiply + STRING A in A by + + d ' " radians 1 = 1.0 + d ' " turns 1/2pi = 0.1591549430918953358 + h m s radians 15 = 15.0 + h m s days 15/2pi = 2.3873241463784300365 + + Called: slDAFN + + P.T.Wallace Starlink 13 September 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/airmas.hlp b/math/slalib/doc/airmas.hlp new file mode 100644 index 00000000..c347bb50 --- /dev/null +++ b/math/slalib/doc/airmas.hlp @@ -0,0 +1,51 @@ +.help airmas Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slARMS (ZD) + + - - - - - - - + A R M S + - - - - - - - + + Air mass at given zenith distance (double precision) + + Given: + ZD d Observed zenith distance (radians) + + The result is an estimate of the air mass, in units of that + at the zenith. + + Notes: + + 1) The "observed" zenith distance referred to above means "as + affected by refraction". + + 2) Uses Hardie's (1962) polynomial fit to Bemporad's data for + the relative air mass, X, in units of thickness at the zenith + as tabulated by Schoenberg (1929). This is adequate for all + normal needs as it is accurate to better than 0.1% up to X = + 6.8 and better than 1% up to X = 10. Bemporad's tabulated + values are unlikely to be trustworthy to such accuracy + because of variations in density, pressure and other + conditions in the atmosphere from those assumed in his work. + + 3) The sign of the ZD is ignored. + + 4) At zenith distances greater than about ZD = 87 degrees the + air mass is held constant to avoid arithmetic overflows. + + References: + Hardie, R.H., 1962, in "Astronomical Techniques" + ed. W.A. Hiltner, University of Chicago Press, p180. + Schoenberg, E., 1929, Hdb. d. Ap., + Berlin, Julius Springer, 2, 268. + + Original code by P.W.Hill, St Andrews + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/altaz.hlp b/math/slalib/doc/altaz.hlp new file mode 100644 index 00000000..0f701093 --- /dev/null +++ b/math/slalib/doc/altaz.hlp @@ -0,0 +1,79 @@ +.help altaz Jun99 "Slalib Package" +.nf + + SUBROUTINE slALAZ (HA, DEC, PHI, + : AZ, AZD, AZDD, EL, ELD, ELDD, PA, PAD, PADD) + + - - - - - - + A L A Z + - - - - - - + + Positions, velocities and accelerations for an altazimuth + telescope mount. + + (double precision) + + Given: + HA d hour angle + DEC d declination + PHI d observatory latitude + + Returned: + AZ d azimuth + AZD d " velocity + AZDD d " acceleration + EL d elevation + ELD d " velocity + ELDD d " acceleration + PA d parallactic angle + PAD d " " velocity + PADD d " " acceleration + + Notes: + + 1) Natural units are used throughout. HA, DEC, PHI, AZ, EL + and ZD are in radians. The velocities and accelerations + assume constant declination and constant rate of change of + hour angle (as for tracking a star); the units of AZD, ELD + and PAD are radians per radian of HA, while the units of AZDD, + ELDD and PADD are radians per radian of HA squared. To + convert into practical degree- and second-based units: + + angles * 360/2pi -> degrees + velocities * (2pi/86400)*(360/2pi) -> degree/sec + accelerations * ((2pi/86400)**2)*(360/2pi) -> degree/sec/sec + + Note that the seconds here are sidereal rather than SI. One + sidereal second is about 0.99727 SI seconds. + + The velocity and acceleration factors assume the sidereal + tracking case. Their respective numerical values are (exactly) + 1/240 and (approximately) 1/3300236.9. + + 2) Azimuth is returned in the range 0-2pi; north is zero, + and east is +pi/2. Elevation and parallactic angle are + returned in the range +/-pi/2. Position angle is +ve + for a star west of the meridian and is the angle NP-star-zenith. + + 3) The latitude is geodetic as opposed to geocentric. The + hour angle and declination are topocentric. Refraction and + deficiencies in the telescope mounting are ignored. The + purpose of the routine is to give the general form of the + quantities. The details of a real telescope could profoundly + change the results, especially close to the zenith. + + 4) No range checking of arguments is carried out. + + 5) In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + + P.T.Wallace Starlink 14 March 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/amp.hlp b/math/slalib/doc/amp.hlp new file mode 100644 index 00000000..f5d4dfc4 --- /dev/null +++ b/math/slalib/doc/amp.hlp @@ -0,0 +1,61 @@ +.help amp Jun99 "Slalib Package" +.nf + + SUBROUTINE slAMP (RA, DA, DATE, EQ, RM, DM) + + - - - - + A M P + - - - - + + Convert star RA,Dec from geocentric apparent to mean place + + The mean coordinate system is the post IAU 1976 system, + loosely called FK5. + + Given: + RA d apparent RA (radians) + DA d apparent Dec (radians) + DATE d TDB for apparent place (JD-2400000.5) + EQ d equinox: Julian epoch of mean place + + Returned: + RM d mean RA (radians) + DM d mean Dec (radians) + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Notes: + + 1) The distinction between the required TDB and TT is + always negligible. Moreover, for all but the most + critical applications UTC is adequate. + + 2) The accuracy is limited by the routine slEVP, called + by slMAPA, which computes the Earth position and + velocity using the methods of Stumpff. The maximum + error is about 0.3 milliarcsecond. + + 3) Iterative techniques are used for the aberration and + light deflection corrections so that the routines + slAMP (or slAMPQ) and slMAP (or slMAPQ) are + accurate inverses; even at the edge of the Sun's disc + the discrepancy is only about 1 nanoarcsecond. + + 4) Where multiple apparent places are to be converted to + mean places, for a fixed date and equinox, it is more + efficient to use the slMAPA routine to compute the + required parameters once, followed by one call to + slAMPQ per star. + + Called: slMAPA, slAMPQ + + P.T.Wallace Starlink 19 January 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ampqk.hlp b/math/slalib/doc/ampqk.hlp new file mode 100644 index 00000000..a4b8dee6 --- /dev/null +++ b/math/slalib/doc/ampqk.hlp @@ -0,0 +1,65 @@ +.help ampqk Jun99 "Slalib Package" +.nf + + SUBROUTINE slAMPQ (RA, DA, AMPRMS, RM, DM) + + - - - - - - + A M P Q + - - - - - - + + Convert star RA,Dec from geocentric apparent to mean place + + The mean coordinate system is the post IAU 1976 system, + loosely called FK5. + + Use of this routine is appropriate when efficiency is important + and where many star positions are all to be transformed for + one epoch and equinox. The star-independent parameters can be + obtained by calling the slMAPA routine. + + Given: + RA d apparent RA (radians) + DA d apparent Dec (radians) + + AMPRMS d(21) star-independent mean-to-apparent parameters: + + (1) time interval for proper motion (Julian years) + (2-4) barycentric position of the Earth (AU) + (5-7) heliocentric direction of the Earth (unit vector) + (8) (grav rad Sun)*2/(Sun-Earth distance) + (9-11) ABV: barycentric Earth velocity in units of c + (12) sqrt(1-v**2) where v=modulus(ABV) + (13-21) precession/nutation (3,3) matrix + + Returned: + RM d mean RA (radians) + DM d mean Dec (radians) + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Notes: + + 1) The accuracy is limited by the routine slEVP, called + by slMAPA, which computes the Earth position and + velocity using the methods of Stumpff. The maximum + error is about 0.3 milliarcsecond. + + 2) Iterative techniques are used for the aberration and + light deflection corrections so that the routines + slAMP (or slAMPQ) and slMAP (or slMAPQ) are + accurate inverses; even at the edge of the Sun's disc + the discrepancy is only about 1 nanoarcsecond. + + Called: slDS2C, slDIMV, slDVDV, slDVN, slDC2S, + slDA2P + + P.T.Wallace Starlink 21 June 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/aop.hlp b/math/slalib/doc/aop.hlp new file mode 100644 index 00000000..dc3343bf --- /dev/null +++ b/math/slalib/doc/aop.hlp @@ -0,0 +1,166 @@ +.help aop Jun99 "Slalib Package" +.nf + + SUBROUTINE slAOP (RAP, DAP, DATE, DUT, ELONGM, PHIM, HM, + : XP, YP, TDK, PMB, RH, WL, TLR, + : AOB, ZOB, HOB, DOB, ROB) + + - - - - + A O P + - - - - + + Apparent to observed place, for optical sources distant from + the solar system. + + Given: + RAP d geocentric apparent right ascension + DAP d geocentric apparent declination + DATE d UTC date/time (Modified Julian Date, JD-2400000.5) + DUT d delta UT: UT1-UTC (UTC seconds) + ELONGM d mean longitude of the observer (radians, east +ve) + PHIM d mean geodetic latitude of the observer (radians) + HM d observer's height above sea level (metres) + XP d polar motion x-coordinate (radians) + YP d polar motion y-coordinate (radians) + TDK d local ambient temperature (DegK; std=273.155D0) + PMB d local atmospheric pressure (mB; std=1013.25D0) + RH d local relative humidity (in the range 0D0-1D0) + WL d effective wavelength (micron, e.g. 0.55D0) + TLR d tropospheric lapse rate (DegK/metre, e.g. 0.0065D0) + + Returned: + AOB d observed azimuth (radians: N=0,E=90) + ZOB d observed zenith distance (radians) + HOB d observed Hour Angle (radians) + DOB d observed Declination (radians) + ROB d observed Right Ascension (radians) + + Notes: + + 1) This routine returns zenith distance rather than elevation + in order to reflect the fact that no allowance is made for + depression of the horizon. + + 2) The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted apparent RA,Dec should be within about 0.1 arcsec + for a zenith distance of less than 70 degrees. Even at a + topocentric zenith distance of 90 degrees, the accuracy in + elevation should be better than 1 arcmin; useful results + are available for a further 3 degrees, beyond which the + slRFRO routine returns a fixed value of the refraction. + The complementary routines slAOP (or slAOPQ) and slOAP + (or slOAPQ) are self-consistent to better than 1 micro- + arcsecond all over the celestial sphere. + + 3) It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + + 4) "Apparent" place means the geocentric apparent right ascension + and declination, which is obtained from a catalogue mean place + by allowing for space motion, parallax, precession, nutation, + annual aberration, and the Sun's gravitational lens effect. For + star positions in the FK5 system (i.e. J2000), these effects can + be applied by means of the slMAP etc routines. Starting from + other mean place systems, additional transformations will be + needed; for example, FK4 (i.e. B1950) mean places would first + have to be converted to FK5, which can be done with the + slFK45 etc routines. + + 5) "Observed" Az,El means the position that would be seen by a + perfect theodolite located at the observer. This is obtained + from the geocentric apparent RA,Dec by allowing for Earth + orientation and diurnal aberration, rotating from equator + to horizon coordinates, and then adjusting for refraction. + The HA,Dec is obtained by rotating back into equatorial + coordinates, using the geodetic latitude corrected for polar + motion, and is the position that would be seen by a perfect + equatorial located at the observer and with its polar axis + aligned to the Earth's axis of rotation (n.b. not to the + refracted pole). Finally, the RA is obtained by subtracting + the HA from the local apparent ST. + + 6) To predict the required setting of a real telescope, the + observed place produced by this routine would have to be + adjusted for the tilt of the azimuth or polar axis of the + mounting (with appropriate corrections for mount flexures), + for non-perpendicularity between the mounting axes, for the + position of the rotator axis and the pointing axis relative + to it, for tube flexure, for gear and encoder errors, and + finally for encoder zero points. Some telescopes would, of + course, exhibit other properties which would need to be + accounted for at the appropriate point in the sequence. + + 7) This routine takes time to execute, due mainly to the + rigorous integration used to evaluate the refraction. + For processing multiple stars for one location and time, + call slAOPA once followed by one call per star to slAOPQ. + Where a range of times within a limited period of a few hours + is involved, and the highest precision is not required, call + slAOPA once, followed by a call to slAOPT each time the + time changes, followed by one call per star to slAOPQ. + + 8) The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, wrong, because of leap seconds. However, + as long as the delta UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap delta UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the delta UTC changes by one second to its post-leap new value. + + 9) The delta UT (UT1-UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep delta UT + within +/- 0.9 seconds. + + 10) IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. + The longitude required by the present routine is east-positive, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + slOBS routine are west-positive, following astronomical + usage, and must be reversed in sign before use in the present + routine. + + 11) The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The maximum amplitude + is about 0.3 arcseconds. If XP,YP values are unavailable, + use XP=YP=0D0. See page B60 of the 1988 Astronomical Almanac + for a definition of the two angles. + + 12) The height above sea level of the observing station, HM, + can be obtained from the Astronomical Almanac (Section J + in the 1988 edition), or via the routine slOBS. If P, + the pressure in millibars, is available, an adequate + estimate of HM can be obtained from the expression + + HM ~ -29.3D0*TSL*LOG(P/1013.25D0). + + where TSL is the approximate sea-level air temperature in + deg K (see Astrophysical Quantities, C.W.Allen, 3rd edition, + section 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + + P ~ 1013.25D0*EXP(-HM/(29.3D0*TSL)). + + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + + 13) The azimuths etc produced by the present routine are with + respect to the celestial pole. Corrections to the terrestrial + pole can be computed using slPLMO. + + Called: slAOPA, slAOPQ + + P.T.Wallace Starlink 9 June 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/aoppa.hlp b/math/slalib/doc/aoppa.hlp new file mode 100644 index 00000000..f96d835b --- /dev/null +++ b/math/slalib/doc/aoppa.hlp @@ -0,0 +1,114 @@ +.help aoppa Jun99 "Slalib Package" +.nf + + SUBROUTINE slAOPA (DATE, DUT, ELONGM, PHIM, HM, + : XP, YP, TDK, PMB, RH, WL, TLR, AOPRMS) + + - - - - - - + A O P A + - - - - - - + + Precompute apparent to observed place parameters required by + slAOPQ and slOAPQ. + + Given: + DATE d UTC date/time (modified Julian Date, JD-2400000.5) + DUT d delta UT: UT1-UTC (UTC seconds) + ELONGM d mean longitude of the observer (radians, east +ve) + PHIM d mean geodetic latitude of the observer (radians) + HM d observer's height above sea level (metres) + XP d polar motion x-coordinate (radians) + YP d polar motion y-coordinate (radians) + TDK d local ambient temperature (DegK; std=273.155D0) + PMB d local atmospheric pressure (mB; std=1013.25D0) + RH d local relative humidity (in the range 0D0-1D0) + WL d effective wavelength (micron, e.g. 0.55D0) + TLR d tropospheric lapse rate (DegK/metre, e.g. 0.0065D0) + + Returned: + AOPRMS d(14) star-independent apparent-to-observed parameters: + + (1) geodetic latitude (radians) + (2,3) sine and cosine of geodetic latitude + (4) magnitude of diurnal aberration vector + (5) height (HM) + (6) ambient temperature (TDK) + (7) pressure (PMB) + (8) relative humidity (RH) + (9) wavelength (WL) + (10) lapse rate (TLR) + (11,12) refraction constants A and B (radians) + (13) longitude + eqn of equinoxes + sidereal DUT (radians) + (14) local apparent sidereal time (radians) + + Notes: + + 1) It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + + 2) The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, improper, because of leap seconds. However, + as long as the delta UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap delta UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the delta UTC changes by one second to its post-leap new value. + + 3) The delta UT (UT1-UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep delta UT + within +/- 0.9 seconds. + + 4) IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. + The longitude required by the present routine is east-positive, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + slOBS routine are west-positive, following astronomical + usage, and must be reversed in sign before use in the present + routine. + + 5) The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The maximum amplitude + is about 0.3 arcseconds. If XP,YP values are unavailable, + use XP=YP=0D0. See page B60 of the 1988 Astronomical Almanac + for a definition of the two angles. + + 6) The height above sea level of the observing station, HM, + can be obtained from the Astronomical Almanac (Section J + in the 1988 edition), or via the routine slOBS. If P, + the pressure in millibars, is available, an adequate + estimate of HM can be obtained from the expression + + HM ~ -29.3D0*TSL*LOG(P/1013.25D0). + + where TSL is the approximate sea-level air temperature in + deg K (see Astrophysical Quantities, C.W.Allen, 3rd edition, + section 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + + P ~ 1013.25D0*EXP(-HM/(29.3D0*TSL)). + + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + + 7) Repeated, computationally-expensive, calls to slAOPA for + times that are very close together can be avoided by calling + slAOPA just once and then using slAOPT for the subsequent + times. Fresh calls to slAOPA will be needed only when changes + in the precession have grown to unacceptable levels or when + anything affecting the refraction has changed. + + Called: slGEOC, slRFCO, slEQEX, slAOPT + + P.T.Wallace Starlink 9 June 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/aoppat.hlp b/math/slalib/doc/aoppat.hlp new file mode 100644 index 00000000..c5d6f9c8 --- /dev/null +++ b/math/slalib/doc/aoppat.hlp @@ -0,0 +1,39 @@ +.help aoppat Jun99 "Slalib Package" +.nf + + SUBROUTINE slAOPT (DATE, AOPRMS) + + - - - - - - - + A O P T + - - - - - - - + + Recompute the sidereal time in the apparent to observed place + star-independent parameter block. + + Given: + DATE d UTC date/time (modified Julian Date, JD-2400000.5) + (see AOPPA source for comments on leap seconds) + + AOPRMS d(14) star-independent apparent-to-observed parameters + + (1-12) not required + (13) longitude + eqn of equinoxes + sidereal DUT + (14) not required + + Returned: + AOPRMS d(14) star-independent apparent-to-observed parameters: + + (1-13) not changed + (14) local apparent sidereal time (radians) + + For more information, see slAOPA. + + Called: slGMST + + P.T.Wallace Starlink 1 July 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/aopqk.hlp b/math/slalib/doc/aopqk.hlp new file mode 100644 index 00000000..aa916a5d --- /dev/null +++ b/math/slalib/doc/aopqk.hlp @@ -0,0 +1,131 @@ +.help aopqk Jun99 "Slalib Package" +.nf + + SUBROUTINE slAOPQ (RAP, DAP, AOPRMS, AOB, ZOB, HOB, DOB, ROB) + + - - - - - - + A O P Q + - - - - - - + + Quick apparent to observed place (but see note 8, below, for + remarks about speed). + + Given: + RAP d geocentric apparent right ascension + DAP d geocentric apparent declination + AOPRMS d(14) star-independent apparent-to-observed parameters: + + (1) geodetic latitude (radians) + (2,3) sine and cosine of geodetic latitude + (4) magnitude of diurnal aberration vector + (5) height (HM) + (6) ambient temperature (T) + (7) pressure (P) + (8) relative humidity (RH) + (9) wavelength (WL) + (10) lapse rate (TLR) + (11,12) refraction constants A and B (radians) + (13) longitude + eqn of equinoxes + sidereal DUT (radians) + (14) local apparent sidereal time (radians) + + Returned: + AOB d observed azimuth (radians: N=0,E=90) + ZOB d observed zenith distance (radians) + HOB d observed Hour Angle (radians) + DOB d observed Declination (radians) + ROB d observed Right Ascension (radians) + + Notes: + + 1) This routine returns zenith distance rather than elevation + in order to reflect the fact that no allowance is made for + depression of the horizon. + + 2) The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + observed RA,Dec predicted by this routine should be within + about 0.1 arcsec for a zenith distance of less than 70 degrees. + Even at a topocentric zenith distance of 90 degrees, the + accuracy in elevation should be better than 1 arcmin; useful + results are available for a further 3 degrees, beyond which + the slaRefro routine returns a fixed value of the refraction. + The complementary routines slaAop (or slaAopqk) and slaOap + (or slaOapqk) are self-consistent to better than 1 micro- + arcsecond all over the celestial sphere. + + 3) It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + + 4) "Apparent" place means the geocentric apparent right ascension + and declination, which is obtained from a catalogue mean place + by allowing for space motion, parallax, precession, nutation, + annual aberration, and the Sun's gravitational lens effect. For + star positions in the FK5 system (i.e. J2000), these effects can + be applied by means of the slMAP etc routines. Starting from + other mean place systems, additional transformations will be + needed; for example, FK4 (i.e. B1950) mean places would first + have to be converted to FK5, which can be done with the + slFK45 etc routines. + + 5) "Observed" Az,El means the position that would be seen by a + perfect theodolite located at the observer. This is obtained + from the geocentric apparent RA,Dec by allowing for Earth + orientation and diurnal aberration, rotating from equator + to horizon coordinates, and then adjusting for refraction. + The HA,Dec is obtained by rotating back into equatorial + coordinates, using the geodetic latitude corrected for polar + motion, and is the position that would be seen by a perfect + equatorial located at the observer and with its polar axis + aligned to the Earth's axis of rotation (n.b. not to the + refracted pole). Finally, the RA is obtained by subtracting + the HA from the local apparent ST. + + 6) To predict the required setting of a real telescope, the + observed place produced by this routine would have to be + adjusted for the tilt of the azimuth or polar axis of the + mounting (with appropriate corrections for mount flexures), + for non-perpendicularity between the mounting axes, for the + position of the rotator axis and the pointing axis relative + to it, for tube flexure, for gear and encoder errors, and + finally for encoder zero points. Some telescopes would, of + course, exhibit other properties which would need to be + accounted for at the appropriate point in the sequence. + + 7) The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the slAOPA routine. + If nothing has changed significantly except the time, the + slAOPT routine may be used to perform the requisite + partial recomputation of AOPRMS. + + 8) At zenith distances beyond about 76 degrees, the need for + special care with the corrections for refraction causes a + marked increase in execution time. Moreover, the effect + gets worse with increasing zenith distance. Adroit + programming in the calling application may allow the + problem to be reduced. Prepare an alternative AOPRMS array, + computed for zero air-pressure; this will disable the + refraction corrections and cause rapid execution. Using + this AOPRMS array, a preliminary call to the present routine + will, depending on the application, produce a rough position + which may be enough to establish whether the full, slow + calculation (using the real AOPRMS array) is worthwhile. + For example, there would be no need for the full calculation + if the preliminary call had already established that the + source was well below the elevation limits for a particular + telescope. + + 9) The azimuths etc produced by the present routine are with + respect to the celestial pole. Corrections to the terrestrial + pole can be computed using slPLMO. + + Called: slDS2C, slREFZ, slRFRO, slDC2S, slDA2P + + P.T.Wallace Starlink 22 February 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/atmdsp.hlp b/math/slalib/doc/atmdsp.hlp new file mode 100644 index 00000000..eaa2b411 --- /dev/null +++ b/math/slalib/doc/atmdsp.hlp @@ -0,0 +1,75 @@ +.help atmdsp Jun99 "Slalib Package" +.nf + + SUBROUTINE slATMD (TDK, PMB, RH, WL1, A1, B1, WL2, A2, B2) + + - - - - - - - + A T M D + - - - - - - - + + Apply atmospheric-dispersion adjustments to refraction coefficients. + + Given: + TDK d ambient temperature, degrees K + PMB d ambient pressure, millibars + RH d ambient relative humidity, 0-1 + WL1 d reference wavelength, micrometre (0.4D0 recommended) + A1 d refraction coefficient A for wavelength WL1 (radians) + B1 d refraction coefficient B for wavelength WL1 (radians) + WL2 d wavelength for which adjusted A,B required + + Returned: + A2 d refraction coefficient A for wavelength WL2 (radians) + B2 d refraction coefficient B for wavelength WL2 (radians) + + Notes: + + 1 To use this routine, first call slRFCO specifying WL1 as the + wavelength. This yields refraction coefficients A1,B1, correct + for that wavelength. Subsequently, calls to slATMD specifying + different wavelengths will produce new, slightly adjusted + refraction coefficients which apply to the specified wavelength. + + 2 Most of the atmospheric dispersion happens between 0.7 micrometre + and the UV atmospheric cutoff, and the effect increases strongly + towards the UV end. For this reason a blue reference wavelength + is recommended, for example 0.4 micrometres. + + 3 The accuracy, for this set of conditions: + + height above sea level 2000 m + latitude 29 deg + pressure 793 mB + temperature 17 degC + humidity 50% + lapse rate 0.0065 degC/m + reference wavelength 0.4 micrometre + star elevation 15 deg + + is about 2.5 mas RMS between 0.3 and 1.0 micrometres, and stays + within 4 mas for the whole range longward of 0.3 micrometres + (compared with a total dispersion from 0.3 to 20.0 micrometres + of about 11 arcsec). These errors are typical for ordinary + conditions and the given elevation; in extreme conditions values + a few times this size may occur, while at higher elevations the + errors become much smaller. + + 4 If either wavelength exceeds 100 micrometres, the radio case + is assumed and the returned refraction coefficients are the + same as the given ones. + + 5 The algorithm consists of calculation of the refractivity of the + air at the observer for the two wavelengths, using the methods + of the slRFRO routine, and then scaling of the two refraction + coefficients according to classical refraction theory. This + amounts to scaling the A coefficient in proportion to (n-1) and + the B coefficient almost in the same ratio (see R.M.Green, + "Spherical Astronomy", Cambridge University Press, 1985). + + P.T.Wallace Starlink 6 October 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/av2m.hlp b/math/slalib/doc/av2m.hlp new file mode 100644 index 00000000..0a98df84 --- /dev/null +++ b/math/slalib/doc/av2m.hlp @@ -0,0 +1,37 @@ +.help av2m Jun99 "Slalib Package" +.nf + + SUBROUTINE slAV2M (AXVEC, RMAT) + + - - - - - + A V 2 M + - - - - - + + Form the rotation matrix corresponding to a given axial vector. + + (single precision) + + A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the Euler axis, and the angle through which the + reference frame rotates is called the Euler angle. The axial + vector supplied to this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. + + Given: + AXVEC r(3) axial vector (radians) + + Returned: + RMAT r(3,3) rotation matrix + + If AXVEC is null, the unit matrix is returned. + + The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + + P.T.Wallace Starlink June 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/bear.hlp b/math/slalib/doc/bear.hlp new file mode 100644 index 00000000..97e4f13d --- /dev/null +++ b/math/slalib/doc/bear.hlp @@ -0,0 +1,30 @@ +.help bear Jun99 "Slalib Package" +.nf + + REAL FUNCTION slBEAR (A1, B1, A2, B2) + + - - - - - + B E A R + - - - - - + + Bearing (position angle) of one point on a sphere relative to another + (single precision) + + Given: + A1,B1 r spherical coordinates of one point + A2,B2 r spherical coordinates of the other point + + (The spherical coordinates are RA,Dec, Long,Lat etc, in radians.) + + The result is the bearing (position angle), in radians, of point + A2,B2 as seen from point A1,B1. It is in the range +/- pi. If + A2,B2 is due east of A1,B1 the bearing is +pi/2. Zero is returned + if the two points are coincident. + + P.T.Wallace Starlink 23 March 1991 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/caf2r.hlp b/math/slalib/doc/caf2r.hlp new file mode 100644 index 00000000..7533ff94 --- /dev/null +++ b/math/slalib/doc/caf2r.hlp @@ -0,0 +1,38 @@ +.help caf2r Jun99 "Slalib Package" +.nf + + SUBROUTINE slCAFR (IDEG, IAMIN, ASEC, RAD, J) + + - - - - - - + C A F R + - - - - - - + + Convert degrees, arcminutes, arcseconds to radians + (single precision) + + Given: + IDEG int degrees + IAMIN int arcminutes + ASEC real arcseconds + + Returned: + RAD real angle in radians + J int status: 0 = OK + 1 = IDEG outside range 0-359 + 2 = IAMIN outside range 0-59 + 3 = ASEC outside range 0-59.999... + + Notes: + + 1) The result is computed even if any of the range checks + fail. + + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/caldj.hlp b/math/slalib/doc/caldj.hlp new file mode 100644 index 00000000..1504c667 --- /dev/null +++ b/math/slalib/doc/caldj.hlp @@ -0,0 +1,38 @@ +.help caldj Jun99 "Slalib Package" +.nf + + SUBROUTINE slCADJ (IY, IM, ID, DJM, J) + + - - - - - - + C A D J + - - - - - - + + Gregorian Calendar to Modified Julian Date + + (Includes century default feature: use slCLDJ for years + before 100AD.) + + Given: + IY,IM,ID int year, month, day in Gregorian calendar + + Returned: + DJM dp modified Julian Date (JD-2400000.5) for 0 hrs + J int status: + 0 = OK + 1 = bad year (MJD not computed) + 2 = bad month (MJD not computed) + 3 = bad day (MJD computed) + + Acceptable years are 00-49, interpreted as 2000-2049, + 50-99, " " 1950-1999, + 100 upwards, interpreted literally. + + Called: slCLDJ + + P.T.Wallace Starlink November 1985 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/calyd.hlp b/math/slalib/doc/calyd.hlp new file mode 100644 index 00000000..7011cc41 --- /dev/null +++ b/math/slalib/doc/calyd.hlp @@ -0,0 +1,49 @@ +.help calyd Jun99 "Slalib Package" +.nf + + SUBROUTINE slCAYD (IY, IM, ID, NY, ND, J) + + - - - - - - + C A Y D + - - - - - - + + Gregorian calendar date to year and day in year (in a Julian + calendar aligned to the 20th/21st century Gregorian calendar). + + (Includes century default feature: use slCLYD for years + before 100AD.) + + Given: + IY,IM,ID int year, month, day in Gregorian calendar + (year may optionally omit the century) + Returned: + NY int year (re-aligned Julian calendar) + ND int day in year (1 = January 1st) + J int status: + 0 = OK + 1 = bad year (before -4711) + 2 = bad month + 3 = bad day (but conversion performed) + + Notes: + + 1 This routine exists to support the low-precision routines + slERTH, slMOON and slECOR. + + 2 Between 1900 March 1 and 2100 February 28 it returns answers + which are consistent with the ordinary Gregorian calendar. + Outside this range there will be a discrepancy which increases + by one day for every non-leap century year. + + 3 Years in the range 50-99 are interpreted as 1950-1999, and + years in the range 00-49 are interpreted as 2000-2049. + + Called: slCLYD + + P.T.Wallace Starlink 23 November 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cc2s.hlp b/math/slalib/doc/cc2s.hlp new file mode 100644 index 00000000..8a16e76e --- /dev/null +++ b/math/slalib/doc/cc2s.hlp @@ -0,0 +1,33 @@ +.help cc2s Jun99 "Slalib Package" +.nf + + SUBROUTINE slCC2S (V, A, B) + + - - - - - + C C 2 S + - - - - - + + Direction cosines to spherical coordinates (single precision) + + Given: + V r(3) x,y,z vector + + Returned: + A,B r spherical coordinates in radians + + The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the x axis + at zero longitude and latitude, and the z axis at the + +ve latitude pole. + + If V is null, zero A and B are returned. + At either pole, zero A is returned. + + P.T.Wallace Starlink July 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cc62s.hlp b/math/slalib/doc/cc62s.hlp new file mode 100644 index 00000000..ffd20cb8 --- /dev/null +++ b/math/slalib/doc/cc62s.hlp @@ -0,0 +1,30 @@ +.help cc62s Jun99 "Slalib Package" +.nf + + SUBROUTINE slC62S (V, A, B, R, AD, BD, RD) + + - - - - - - + C 6 2 S + - - - - - - + + Conversion of position & velocity in Cartesian coordinates + to spherical coordinates (single precision) + + Given: + V r(6) Cartesian position & velocity vector + + Returned: + A r longitude (radians) + B r latitude (radians) + R r radial coordinate + AD r longitude derivative (radians per unit time) + BD r latitude derivative (radians per unit time) + RD r radial derivative + + P.T.Wallace Starlink 28 April 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cd2tf.hlp b/math/slalib/doc/cd2tf.hlp new file mode 100644 index 00000000..52e66f62 --- /dev/null +++ b/math/slalib/doc/cd2tf.hlp @@ -0,0 +1,47 @@ +.help cd2tf Jun99 "Slalib Package" +.nf + + SUBROUTINE slCDTF (NDP, DAYS, SIGN, IHMSF) + + - - - - - - + C D T F + - - - - - - + + Convert an interval in days into hours, minutes, seconds + + (single precision) + + Given: + NDP int number of decimal places of seconds + DAYS real interval in days + + Returned: + SIGN char '+' or '-' + IHMSF int(4) hours, minutes, seconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size of + DAYS, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IHMSF(4). For example, + on the VAX, for DAYS up to 1.0, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + + 3) The absolute value of DAYS may exceed 1.0. In cases where it + does not, it is up to the caller to test for and handle the + case where DAYS is very nearly 1.0 and rounds up to 24 hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. + + Called: slDDTF + + P.T.Wallace Starlink 12 December 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cldj.hlp b/math/slalib/doc/cldj.hlp new file mode 100644 index 00000000..3f65adb1 --- /dev/null +++ b/math/slalib/doc/cldj.hlp @@ -0,0 +1,34 @@ +.help cldj Jun99 "Slalib Package" +.nf + + SUBROUTINE slCLDJ (IY, IM, ID, DJM, J) + + - - - - - + C L D J + - - - - - + + Gregorian Calendar to Modified Julian Date + + Given: + IY,IM,ID int year, month, day in Gregorian calendar + + Returned: + DJM dp modified Julian Date (JD-2400000.5) for 0 hrs + J int status: + 0 = OK + 1 = bad year (MJD not computed) + 2 = bad month (MJD not computed) + 3 = bad day (MJD computed) + + The year must be -4699 (i.e. 4700BC) or later. + + The algorithm is derived from that of Hatcher 1984 + (QJRAS 25, 53-55). + + P.T.Wallace Starlink 11 March 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/clyd.hlp b/math/slalib/doc/clyd.hlp new file mode 100644 index 00000000..7afbe1aa --- /dev/null +++ b/math/slalib/doc/clyd.hlp @@ -0,0 +1,50 @@ +.help clyd Jun99 "Slalib Package" +.nf + + SUBROUTINE slCLYD (IY, IM, ID, NY, ND, JSTAT) + + - - - - - + C L Y D + - - - - - + + Gregorian calendar to year and day in year (in a Julian calendar + aligned to the 20th/21st century Gregorian calendar). + + Given: + IY,IM,ID i year, month, day in Gregorian calendar + + Returned: + NY i year (re-aligned Julian calendar) + ND i day in year (1 = January 1st) + JSTAT i status: + 0 = OK + 1 = bad year (before -4711) + 2 = bad month + 3 = bad day (but conversion performed) + + Notes: + + 1 This routine exists to support the low-precision routines + slERTH, slMOON and slECOR. + + 2 Between 1900 March 1 and 2100 February 28 it returns answers + which are consistent with the ordinary Gregorian calendar. + Outside this range there will be a discrepancy which increases + by one day for every non-leap century year. + + 3 The essence of the algorithm is first to express the Gregorian + date as a Julian Day Number and then to convert this back to + a Julian calendar date, with day-in-year instead of month and + day. See 12.92-1 and 12.95-1 in the reference. + + Reference: Explanatory Supplement to the Astronomical Almanac, + ed P.K.Seidelmann, University Science Books (1992), + p604-606. + + P.T.Wallace Starlink 26 November 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cr2af.hlp b/math/slalib/doc/cr2af.hlp new file mode 100644 index 00000000..2a1863ca --- /dev/null +++ b/math/slalib/doc/cr2af.hlp @@ -0,0 +1,46 @@ +.help cr2af Jun99 "Slalib Package" +.nf + + SUBROUTINE slCRAF (NDP, ANGLE, SIGN, IDMSF) + + - - - - - - + C R A F + - - - - - - + + Convert an angle in radians into degrees, arcminutes, arcseconds + (single precision) + + Given: + NDP int number of decimal places of arcseconds + ANGLE real angle in radians + + Returned: + SIGN char '+' or '-' + IDMSF int(4) degrees, arcminutes, arcseconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size of + ANGLE, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IDMSF(4). For example, + on the VAX, for ANGLE up to 2pi, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + + 3) The absolute value of ANGLE may exceed 2pi. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly 2pi and rounds up to 360 deg, + by testing for IDMSF(1)=360 and setting IDMSF(1-4) to zero. + + Called: slCDTF + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cr2tf.hlp b/math/slalib/doc/cr2tf.hlp new file mode 100644 index 00000000..719db50e --- /dev/null +++ b/math/slalib/doc/cr2tf.hlp @@ -0,0 +1,46 @@ +.help cr2tf Jun99 "Slalib Package" +.nf + + SUBROUTINE slCRTF (NDP, ANGLE, SIGN, IHMSF) + + - - - - - - + C R T F + - - - - - - + + Convert an angle in radians into hours, minutes, seconds + (single precision) + + Given: + NDP int number of decimal places of seconds + ANGLE real angle in radians + + Returned: + SIGN char '+' or '-' + IHMSF int(4) hours, minutes, seconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size of + ANGLE, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IHMSF(4). For example, + on the VAX, for ANGLE up to 2pi, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + + 3) The absolute value of ANGLE may exceed 2pi. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly 2pi and rounds up to 24 hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. + + Called: slCDTF + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cs2c.hlp b/math/slalib/doc/cs2c.hlp new file mode 100644 index 00000000..df71c82c --- /dev/null +++ b/math/slalib/doc/cs2c.hlp @@ -0,0 +1,31 @@ +.help cs2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slCS2C (A, B, V) + + - - - - - + C S 2 C + - - - - - + + Spherical coordinates to direction cosines (single precision) + + Given: + A,B real spherical coordinates in radians + (RA,Dec), (Long,Lat) etc + + Returned: + V real(3) x,y,z unit vector + + The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the x axis + at zero longitude and latitude, and the z axis at the + +ve latitude pole. + + P.T.Wallace Starlink October 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/cs2c6.hlp b/math/slalib/doc/cs2c6.hlp new file mode 100644 index 00000000..0b69377d --- /dev/null +++ b/math/slalib/doc/cs2c6.hlp @@ -0,0 +1,30 @@ +.help cs2c6 Jun99 "Slalib Package" +.nf + + SUBROUTINE slS2C6 (A, B, R, AD, BD, RD, V) + + - - - - - - + S 2 C 6 + - - - - - - + + Conversion of position & velocity in spherical coordinates + to Cartesian coordinates (single precision) + + Given: + A r longitude (radians) + B r latitude (radians) + R r radial coordinate + AD r longitude derivative (radians per unit time) + BD r latitude derivative (radians per unit time) + RD r radial derivative + + Returned: + V r(6) Cartesian position & velocity vector + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ctf2d.hlp b/math/slalib/doc/ctf2d.hlp new file mode 100644 index 00000000..e8c985c3 --- /dev/null +++ b/math/slalib/doc/ctf2d.hlp @@ -0,0 +1,37 @@ +.help ctf2d Jun99 "Slalib Package" +.nf + + SUBROUTINE slCTFD (IHOUR, IMIN, SEC, DAYS, J) + + - - - - - - + C T F D + - - - - - - + + Convert hours, minutes, seconds to days (single precision) + + Given: + IHOUR int hours + IMIN int minutes + SEC real seconds + + Returned: + DAYS real interval in days + J int status: 0 = OK + 1 = IHOUR outside range 0-23 + 2 = IMIN outside range 0-59 + 3 = SEC outside range 0-59.999... + + Notes: + + 1) The result is computed even if any of the range checks + fail. + + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ctf2r.hlp b/math/slalib/doc/ctf2r.hlp new file mode 100644 index 00000000..72a1fb56 --- /dev/null +++ b/math/slalib/doc/ctf2r.hlp @@ -0,0 +1,40 @@ +.help ctf2r Jun99 "Slalib Package" +.nf + + SUBROUTINE slCTFR (IHOUR, IMIN, SEC, RAD, J) + + - - - - - - + C T F R + - - - - - - + + Convert hours, minutes, seconds to radians (single precision) + + Given: + IHOUR int hours + IMIN int minutes + SEC real seconds + + Returned: + RAD real angle in radians + J int status: 0 = OK + 1 = IHOUR outside range 0-23 + 2 = IMIN outside range 0-59 + 3 = SEC outside range 0-59.999... + + Called: + slCTFD + + Notes: + + 1) The result is computed even if any of the range checks + fail. + + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/daf2r.hlp b/math/slalib/doc/daf2r.hlp new file mode 100644 index 00000000..f0cf7434 --- /dev/null +++ b/math/slalib/doc/daf2r.hlp @@ -0,0 +1,36 @@ +.help daf2r Jun99 "Slalib Package" +.nf + + SUBROUTINE slDAFR (IDEG, IAMIN, ASEC, RAD, J) + + - - - - - - + D A F R + - - - - - - + + Convert degrees, arcminutes, arcseconds to radians + (double precision) + + Given: + IDEG int degrees + IAMIN int arcminutes + ASEC dp arcseconds + + Returned: + RAD dp angle in radians + J int status: 0 = OK + 1 = IDEG outside range 0-359 + 2 = IAMIN outside range 0-59 + 3 = ASEC outside range 0-59.999... + + Notes: + 1) The result is computed even if any of the range checks + fail. + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dafin.hlp b/math/slalib/doc/dafin.hlp new file mode 100644 index 00000000..2fa24d5c --- /dev/null +++ b/math/slalib/doc/dafin.hlp @@ -0,0 +1,90 @@ +.help dafin Jun99 "Slalib Package" +.nf + + SUBROUTINE slDAFN (STRING, IPTR, A, J) + + - - - - - - + D A F N + - - - - - - + + Sexagesimal character string to angle (double precision) + + Given: + STRING c*(*) string containing deg, arcmin, arcsec fields + IPTR i pointer to start of decode (1st = 1) + + Returned: + IPTR i advanced past the decoded angle + A d angle in radians + J i status: 0 = OK + +1 = default, A unchanged + -1 = bad degrees ) + -2 = bad arcminutes ) (note 3) + -3 = bad arcseconds ) + + Example: + + argument before after + + STRING '-57 17 44.806 12 34 56.7' unchanged + IPTR 1 16 (points to 12...) + A ? -1.00000D0 + J ? 0 + + A further call to slDAFN, without adjustment of IPTR, will + decode the second angle, 12deg 34min 56.7sec. + + Notes: + + 1) The first three "fields" in STRING are degrees, arcminutes, + arcseconds, separated by spaces or commas. The degrees field + may be signed, but not the others. The decoding is carried + out by the DFLTIN routine and is free-format. + + 2) Successive fields may be absent, defaulting to zero. For + zero status, the only combinations allowed are degrees alone, + degrees and arcminutes, and all three fields present. If all + three fields are omitted, a status of +1 is returned and A is + unchanged. In all other cases A is changed. + + 3) Range checking: + + The degrees field is not range checked. However, it is + expected to be integral unless the other two fields are absent. + + The arcminutes field is expected to be 0-59, and integral if + the arcseconds field is present. If the arcseconds field + is absent, the arcminutes is expected to be 0-59.9999... + + The arcseconds field is expected to be 0-59.9999... + + 4) Decoding continues even when a check has failed. Under these + circumstances the field takes the supplied value, defaulting + to zero, and the result A is computed and returned. + + 5) Further fields after the three expected ones are not treated + as an error. The pointer IPTR is left in the correct state + for further decoding with the present routine or with DFLTIN + etc. See the example, above. + + 6) If STRING contains hours, minutes, seconds instead of degrees + etc, or if the required units are turns (or days) instead of + radians, the result A should be multiplied as follows: + + for to obtain multiply + STRING A in A by + + d ' " radians 1 = 1D0 + d ' " turns 1/2pi = 0.1591549430918953358D0 + h m s radians 15 = 15D0 + h m s days 15/2pi = 2.3873241463784300365D0 + + Called: slDFLI + + P.T.Wallace Starlink 1 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dat.hlp b/math/slalib/doc/dat.hlp new file mode 100644 index 00000000..20777dc5 --- /dev/null +++ b/math/slalib/doc/dat.hlp @@ -0,0 +1,55 @@ +.help dat Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDAT (UTC) + + - - - - + D A T + - - - - + + Increment to be applied to Coordinated Universal Time UTC to give + International Atomic Time TAI (double precision) + + Given: + UTC d UTC date as a modified JD (JD-2400000.5) + + Result: TAI-UTC in seconds + + Notes: + + 1 The UTC is specified to be a date rather than a time to indicate + that care needs to be taken not to specify an instant which lies + within a leap second. Though in most cases UTC can include the + fractional part, correct behaviour on the day of a leap second + can only be guaranteed up to the end of the second 23:59:59. + + 2 For epochs from 1961 January 1 onwards, the expressions from the + file ftp://maia.usno.navy.mil/ser7/tai-utc.dat are used. + + 3 The 5ms timestep at 1961 January 1 is taken from 2.58.1 (p87) of + the 1992 Explanatory Supplement. + + 4 UTC began at 1960 January 1.0 (JD 2436934.5) and it is improper + to call the routine with an earlier epoch. However, if this + is attempted, the TAI-UTC expression for the year 1960 is used. + + + :-----------------------------------------: + : : + : IMPORTANT : + : : + : This routine must be updated on each : + : occasion that a leap second is : + : announced : + : : + : Latest leap second: 1999 January 1 : + : : + :-----------------------------------------: + + P.T.Wallace Starlink 31 May 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dav2m.hlp b/math/slalib/doc/dav2m.hlp new file mode 100644 index 00000000..26d5fae6 --- /dev/null +++ b/math/slalib/doc/dav2m.hlp @@ -0,0 +1,36 @@ +.help dav2m Jun99 "Slalib Package" +.nf + + SUBROUTINE slDAVM (AXVEC, RMAT) + + - - - - - - + D A V M + - - - - - - + + Form the rotation matrix corresponding to a given axial vector. + (double precision) + + A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the Euler axis, and the angle through which the + reference frame rotates is called the Euler angle. The axial + vector supplied to this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. + + Given: + AXVEC d(3) axial vector (radians) + + Returned: + RMAT d(3,3) rotation matrix + + If AXVEC is null, the unit matrix is returned. + + The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + + P.T.Wallace Starlink June 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dbear.hlp b/math/slalib/doc/dbear.hlp new file mode 100644 index 00000000..8d796e61 --- /dev/null +++ b/math/slalib/doc/dbear.hlp @@ -0,0 +1,30 @@ +.help dbear Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDBER (A1, B1, A2, B2) + + - - - - - - + D B E R + - - - - - - + + Bearing (position angle) of one point on a sphere relative to another + (double precision) + + Given: + A1,B1 d spherical coordinates of one point + A2,B2 d spherical coordinates of the other point + + (The spherical coordinates are RA,Dec, Long,Lat etc, in radians.) + + The result is the bearing (position angle), in radians, of point + A2,B2 as seen from point A1,B1. It is in the range +/- pi. If + A2,B2 is due east of A1,B1 the bearing is +pi/2. Zero is returned + if the two points are coincident. + + P.T.Wallace Starlink 23 March 1991 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dbjin.hlp b/math/slalib/doc/dbjin.hlp new file mode 100644 index 00000000..017333dd --- /dev/null +++ b/math/slalib/doc/dbjin.hlp @@ -0,0 +1,52 @@ +.help dbjin Jun99 "Slalib Package" +.nf + + SUBROUTINE slDBJI (STRING, NSTRT, DRESLT, J1, J2) + + - - - - - - + D B J I + - - - - - - + + Convert free-format input into double precision floating point, + using DFLTIN but with special syntax extensions. + + The purpose of the syntax extensions is to help cope with mixed + FK4 and FK5 data. In addition to the syntax accepted by DFLTIN, + the following two extensions are recognized by DBJIN: + + 1) A valid non-null field preceded by the character 'B' + (or 'b') is accepted. + + 2) A valid non-null field preceded by the character 'J' + (or 'j') is accepted. + + The calling program is notified of the incidence of either of these + extensions through an supplementary status argument. The rest of + the arguments are as for DFLTIN. + + Given: + STRING char string containing field to be decoded + NSTRT int pointer to 1st character of field in string + + Returned: + NSTRT int incremented + DRESLT double result + J1 int DFLTIN status: -1 = -OK + 0 = +OK + +1 = null field + +2 = error + J2 int syntax flag: 0 = normal DFLTIN syntax + +1 = 'B' or 'b' + +2 = 'J' or 'j' + + Called: slDFLI + + For details of the basic syntax, see slDFLI. + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dc62s.hlp b/math/slalib/doc/dc62s.hlp new file mode 100644 index 00000000..0294205b --- /dev/null +++ b/math/slalib/doc/dc62s.hlp @@ -0,0 +1,30 @@ +.help dc62s Jun99 "Slalib Package" +.nf + + SUBROUTINE slDC6S (V, A, B, R, AD, BD, RD) + + - - - - - - + D C 6 S + - - - - - - + + Conversion of position & velocity in Cartesian coordinates + to spherical coordinates (double precision) + + Given: + V d(6) Cartesian position & velocity vector + + Returned: + A d longitude (radians) + B d latitude (radians) + R d radial coordinate + AD d longitude derivative (radians per unit time) + BD d latitude derivative (radians per unit time) + RD d radial derivative + + P.T.Wallace Starlink 28 April 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dcc2s.hlp b/math/slalib/doc/dcc2s.hlp new file mode 100644 index 00000000..ace02cf7 --- /dev/null +++ b/math/slalib/doc/dcc2s.hlp @@ -0,0 +1,33 @@ +.help dcc2s Jun99 "Slalib Package" +.nf + + SUBROUTINE slDC2S (V, A, B) + + - - - - - - + D C 2 S + - - - - - - + + Direction cosines to spherical coordinates (double precision) + + Given: + V d(3) x,y,z vector + + Returned: + A,B d spherical coordinates in radians + + The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the x axis + at zero longitude and latitude, and the z axis at the + +ve latitude pole. + + If V is null, zero A and B are returned. + At either pole, zero A is returned. + + P.T.Wallace Starlink July 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dcmpf.hlp b/math/slalib/doc/dcmpf.hlp new file mode 100644 index 00000000..914addfd --- /dev/null +++ b/math/slalib/doc/dcmpf.hlp @@ -0,0 +1,70 @@ +.help dcmpf Jun99 "Slalib Package" +.nf + + SUBROUTINE slDCMF (COEFFS,XZ,YZ,XS,YS,PERP,ORIENT) + + - - - - - - + D C M F + - - - - - - + + Decompose an [X,Y] linear fit into its constituent parameters: + zero points, scales, nonperpendicularity and orientation. + + Given: + COEFFS d(6) transformation coefficients (see note) + + Returned: + XZ d x zero point + YZ d y zero point + XS d x scale + YS d y scale + PERP d nonperpendicularity (radians) + ORIENT d orientation (radians) + + The model relates two sets of [X,Y] coordinates as follows. + Naming the elements of COEFFS: + + COEFFS(1) = A + COEFFS(2) = B + COEFFS(3) = C + COEFFS(4) = D + COEFFS(5) = E + COEFFS(6) = F + + the model transforms coordinates [X1,Y1] into coordinates + [X2,Y2] as follows: + + X2 = A + B*X1 + C*Y1 + Y2 = D + E*X1 + F*Y1 + + The transformation can be decomposed into four steps: + + 1) Zero points: + + x' = XZ + X1 + y' = YZ + Y1 + + 2) Scales: + + x'' = XS*x' + y'' = YS*y' + + 3) Nonperpendicularity: + + x''' = cos(PERP/2)*x'' + sin(PERP/2)*y'' + y''' = sin(PERP/2)*x'' + cos(PERP/2)*y'' + + 4) Orientation: + + X2 = cos(ORIENT)*x''' + sin(ORIENT)*y''' + Y2 =-sin(ORIENT)*y''' + cos(ORIENT)*y''' + + See also slFTXY, slPXY, slINVF, slXYXY + + P.T.Wallace Starlink 14 August 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dcs2c.hlp b/math/slalib/doc/dcs2c.hlp new file mode 100644 index 00000000..50010ea4 --- /dev/null +++ b/math/slalib/doc/dcs2c.hlp @@ -0,0 +1,31 @@ +.help dcs2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slDS2C (A, B, V) + + - - - - - - + D S 2 C + - - - - - - + + Spherical coordinates to direction cosines (double precision) + + Given: + A,B dp spherical coordinates in radians + (RA,Dec), (Long,Lat) etc + + Returned: + V dp(3) x,y,z unit vector + + The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the x axis + at zero longitude and latitude, and the z axis at the + +ve latitude pole. + + P.T.Wallace Starlink October 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dd2tf.hlp b/math/slalib/doc/dd2tf.hlp new file mode 100644 index 00000000..124a7fcc --- /dev/null +++ b/math/slalib/doc/dd2tf.hlp @@ -0,0 +1,44 @@ +.help dd2tf Jun99 "Slalib Package" +.nf + + SUBROUTINE slDDTF (NDP, DAYS, SIGN, IHMSF) + + - - - - - - + D D T F + - - - - - - + + Convert an interval in days into hours, minutes, seconds + (double precision) + + Given: + NDP i number of decimal places of seconds + DAYS d interval in days + + Returned: + SIGN c '+' or '-' + IHMSF i(4) hours, minutes, seconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size + of DAYS, the format of DOUBLE PRECISION floating-point numbers + on the target machine, and the risk of overflowing IHMSF(4). + For example, on the VAX, for DAYS up to 1D0, the available + floating-point precision corresponds roughly to NDP=12. + However, the practical limit is NDP=9, set by the capacity of + the 32-bit integer IHMSF(4). + + 3) The absolute value of DAYS may exceed 1D0. In cases where it + does not, it is up to the caller to test for and handle the + case where DAYS is very nearly 1D0 and rounds up to 24 hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. + + P.T.Wallace Starlink 19 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/de2h.hlp b/math/slalib/doc/de2h.hlp new file mode 100644 index 00000000..7e5bcb06 --- /dev/null +++ b/math/slalib/doc/de2h.hlp @@ -0,0 +1,59 @@ +.help de2h Jun99 "Slalib Package" +.nf + + SUBROUTINE slDE2H (HA, DEC, PHI, AZ, EL) + + - - - - - + D E 2 H + - - - - - + + Equatorial to horizon coordinates: HA,Dec to Az,El + + (double precision) + + Given: + HA d hour angle + DEC d declination + PHI d observatory latitude + + Returned: + AZ d azimuth + EL d elevation + + Notes: + + 1) All the arguments are angles in radians. + + 2) Azimuth is returned in the range 0-2pi; north is zero, + and east is +pi/2. Elevation is returned in the range + +/-pi/2. + + 3) The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied. + + 4) In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type of azimuth and elevation. In + particular, it may be important to distinguish between + elevation as affected by refraction, which would + require the "observed" HA,Dec, and the elevation + in vacuo, which would require the "topocentric" HA,Dec. + If the effects of diurnal aberration can be neglected, the + "apparent" HA,Dec may be used instead of the topocentric + HA,Dec. + + 5) No range checking of arguments is carried out. + + 6) In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + + P.T.Wallace Starlink 9 July 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/deuler.hlp b/math/slalib/doc/deuler.hlp new file mode 100644 index 00000000..1dc55844 --- /dev/null +++ b/math/slalib/doc/deuler.hlp @@ -0,0 +1,50 @@ +.help deuler Jun99 "Slalib Package" +.nf + + SUBROUTINE slDEUL (ORDER, PHI, THETA, PSI, RMAT) + + - - - - - - - + D E U L + - - - - - - - + + Form a rotation matrix from the Euler angles - three successive + rotations about specified Cartesian axes (double precision) + + Given: + ORDER c*(*) specifies about which axes the rotations occur + PHI d 1st rotation (radians) + THETA d 2nd rotation ( " ) + PSI d 3rd rotation ( " ) + + Returned: + RMAT d(3,3) rotation matrix + + A rotation is positive when the reference frame rotates + anticlockwise as seen looking towards the origin from the + positive region of the specified axis. + + The characters of ORDER define which axes the three successive + rotations are about. A typical value is 'ZXZ', indicating that + RMAT is to become the direction cosine matrix corresponding to + rotations of the reference frame through PHI radians about the + old Z-axis, followed by THETA radians about the resulting X-axis, + then PSI radians about the resulting Z-axis. + + The axis names can be any of the following, in any order or + combination: X, Y, Z, uppercase or lowercase, 1, 2, 3. Normal + axis labeling/numbering conventions apply; the xyz (=123) + triad is right-handed. Thus, the 'ZXZ' example given above + could be written 'zxz' or '313' (or even 'ZxZ' or '3xZ'). ORDER + is terminated by length or by the first unrecognized character. + + Fewer than three rotations are acceptable, in which case the later + angle arguments are ignored. If all rotations are zero, the + identity matrix is produced. + + P.T.Wallace Starlink 23 May 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dfltin.hlp b/math/slalib/doc/dfltin.hlp new file mode 100644 index 00000000..be42311f --- /dev/null +++ b/math/slalib/doc/dfltin.hlp @@ -0,0 +1,118 @@ +.help dfltin Jun99 "Slalib Package" +.nf + + SUBROUTINE slDFLI (STRING, NSTRT, DRESLT, JFLAG) + + - - - - - - - + D F L I + - - - - - - - + + Convert free-format input into double precision floating point + + Given: + STRING c string containing number to be decoded + NSTRT i pointer to where decoding is to start + DRESLT d current value of result + + Returned: + NSTRT i advanced to next number + DRESLT d result + JFLAG i status: -1 = -OK, 0 = +OK, 1 = null, 2 = error + + Notes: + + 1 The reason DFLTIN has separate OK status values for + + and - is to enable minus zero to be detected. This is + of crucial importance when decoding mixed-radix numbers. + For example, an angle expressed as deg, arcmin, arcsec + may have a leading minus sign but a zero degrees field. + + 2 A TAB is interpreted as a space, and lowercase characters + are interpreted as uppercase. + + 3 The basic format is the sequence of fields #^.^@#^, where + # is a sign character + or -, ^ means a string of decimal + digits, and @, which indicates an exponent, means D or E. + Various combinations of these fields can be omitted, and + embedded blanks are permissible in certain places. + + 4 Spaces: + + . Leading spaces are ignored. + + . Embedded spaces are allowed only after +, -, D or E, + and after the decomal point if the first sequence of + digits is absent. + + . Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + + 5 Delimiters: + + . Any character other than +,-,0-9,.,D,E or space may be + used to signal the end of the number and terminate + decoding. + + . Comma is recognized by DFLTIN as a special case; it + is skipped, leaving the pointer on the next character. + See 13, below. + + 6 Both signs are optional. The default is +. + + 7 The mantissa ^.^ defaults to 1. + + 8 The exponent @#^ defaults to D0. + + 9 The strings of decimal digits may be of any length. + + 10 The decimal point is optional for whole numbers. + + 11 A "null result" occurs when the string of characters being + decoded does not begin with +,-,0-9,.,D or E, or consists + entirely of spaces. When this condition is detected, JFLAG + is set to 1 and DRESLT is left untouched. + + 12 NSTRT = 1 for the first character in the string. + + 13 On return from DFLTIN, NSTRT is set ready for the next + decode - following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to DFLTIN, otherwise + all subsequent calls will return a null result. + + 14 Errors (JFLAG=2) occur when: + + . a +, -, D or E is left unsatisfied; or + + . the decimal point is present without at least + one decimal digit before or after it; or + + . an exponent more than 100 has been presented. + + 15 When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. This + may be after the point at which a more sophisticated + program could have detected the error. For example, + DFLTIN does not detect that '1D999' is unacceptable + (on a computer where this is so) until the entire number + has been decoded. + + 16 Certain highly unlikely combinations of mantissa & + exponent can cause arithmetic faults during the + decode, in some cases despite the fact that they + together could be construed as a valid number. + + 17 Decoding is left to right, one pass. + + 18 See also FLOTIN and INTIN + + Called: slICHF + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dh2e.hlp b/math/slalib/doc/dh2e.hlp new file mode 100644 index 00000000..965653c8 --- /dev/null +++ b/math/slalib/doc/dh2e.hlp @@ -0,0 +1,58 @@ +.help dh2e Jun99 "Slalib Package" +.nf + + SUBROUTINE slDH2E (AZ, EL, PHI, HA, DEC) + + - - - - - + D E 2 H + - - - - - + + Horizon to equatorial coordinates: Az,El to HA,Dec + + (double precision) + + Given: + AZ d azimuth + EL d elevation + PHI d observatory latitude + + Returned: + HA d hour angle + DEC d declination + + Notes: + + 1) All the arguments are angles in radians. + + 2) The sign convention for azimuth is north zero, east +pi/2. + + 3) HA is returned in the range +/-pi. Declination is returned + in the range +/-pi/2. + + 4) The latitude is (in principle) geodetic. In critical + applications, corrections for polar motion should be applied. + + 5) In some applications it will be important to specify the + correct type of elevation in order to produce the required + type of HA,Dec. In particular, it may be important to + distinguish between the elevation as affected by refraction, + which will yield the "observed" HA,Dec, and the elevation + in vacuo, which will yield the "topocentric" HA,Dec. If the + effects of diurnal aberration can be neglected, the + topocentric HA,Dec may be used as an approximation to the + "apparent" HA,Dec. + + 6) No range checking of arguments is done. + + 7) In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude. + + P.T.Wallace Starlink 21 February 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dimxv.hlp b/math/slalib/doc/dimxv.hlp new file mode 100644 index 00000000..805f124a --- /dev/null +++ b/math/slalib/doc/dimxv.hlp @@ -0,0 +1,32 @@ +.help dimxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slDIMV (DM, VA, VB) + + - - - - - - + D I M V + - - - - - - + + Performs the 3-D backward unitary transformation: + + vector VB = (inverse of matrix DM) * vector VA + + (double precision) + + (n.b. the matrix must be unitary, as this routine assumes that + the inverse and transpose are identical) + + Given: + DM dp(3,3) matrix + VA dp(3) vector + + Returned: + VB dp(3) result vector + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/djcal.hlp b/math/slalib/doc/djcal.hlp new file mode 100644 index 00000000..d65c81bd --- /dev/null +++ b/math/slalib/doc/djcal.hlp @@ -0,0 +1,38 @@ +.help djcal Jun99 "Slalib Package" +.nf + + SUBROUTINE slDJCA (NDP, DJM, IYMDF, J) + + - - - - - - + D J C A + - - - - - - + + Modified Julian Date to Gregorian Calendar, expressed + in a form convenient for formatting messages (namely + rounded to a specified precision, and with the fields + stored in a single array) + + Given: + NDP i number of decimal places of days in fraction + DJM d modified Julian Date (JD-2400000.5) + + Returned: + IYMDF i(4) year, month, day, fraction in Gregorian + calendar + J i status: nonzero = out of range + + Any date after 4701BC March 1 is accepted. + + NDP should be 4 or less if internal overflows are to be avoided + on machines which use 32-bit integers. + + The algorithm is derived from that of Hatcher 1984 + (QJRAS 25, 53-55). + + P.T.Wallace Starlink 27 April 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/djcl.hlp b/math/slalib/doc/djcl.hlp new file mode 100644 index 00000000..a6327c1d --- /dev/null +++ b/math/slalib/doc/djcl.hlp @@ -0,0 +1,34 @@ +.help djcl Jun99 "Slalib Package" +.nf + + SUBROUTINE slDJCL (DJM, IY, IM, ID, FD, J) + + - - - - - + D J C L + - - - - - + + Modified Julian Date to Gregorian year, month, day, + and fraction of a day. + + Given: + DJM dp modified Julian Date (JD-2400000.5) + + Returned: + IY int year + IM int month + ID int day + FD dp fraction of day + J int status: + 0 = OK + -1 = unacceptable date (before 4701BC March 1) + + The algorithm is derived from that of Hatcher 1984 + (QJRAS 25, 53-55). + + P.T.Wallace Starlink 27 April 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dm2av.hlp b/math/slalib/doc/dm2av.hlp new file mode 100644 index 00000000..6448b842 --- /dev/null +++ b/math/slalib/doc/dm2av.hlp @@ -0,0 +1,38 @@ +.help dm2av Jun99 "Slalib Package" +.nf + + SUBROUTINE slDMAV (RMAT, AXVEC) + + - - - - - - + D M A V + - - - - - - + + From a rotation matrix, determine the corresponding axial vector. + (double precision) + + A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the Euler axis, and the angle through which the + reference frame rotates is called the Euler angle. The axial + vector returned by this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. (The + magnitude and direction can be separated by means of the routine + slDVN.) + + Given: + RMAT d(3,3) rotation matrix + + Returned: + AXVEC d(3) axial vector (radians) + + The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + + If RMAT is null, so is the result. + + P.T.Wallace Starlink 24 December 1992 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dmat.hlp b/math/slalib/doc/dmat.hlp new file mode 100644 index 00000000..7d496345 --- /dev/null +++ b/math/slalib/doc/dmat.hlp @@ -0,0 +1,58 @@ +.help dmat Jun99 "Slalib Package" +.nf + + SUBROUTINE slDMAT (N, A, Y, D, JF, IW) + + - - - - - + D M A T + - - - - - + + Matrix inversion & solution of simultaneous equations + (double precision) + + For the set of n simultaneous equations in n unknowns: + A.Y = X + + where: + A is a non-singular N x N matrix + Y is the vector of N unknowns + X is the known vector + + DMATRX computes: + the inverse of matrix A + the determinant of matrix A + the vector of N unknowns + + Arguments: + + symbol type dimension before after + + N i no. of unknowns unchanged + A d (N,N) matrix inverse + Y d (N) vector solution + D d - determinant + * JF i - singularity flag + IW i (N) - workspace + + * JF is the singularity flag. If the matrix is non-singular, + JF=0 is returned. If the matrix is singular, JF=-1 & D=0D0 are + returned. In the latter case, the contents of array A on return + are undefined. + + Algorithm: + Gaussian elimination with partial pivoting. + + Speed: + Very fast. + + Accuracy: + Fairly accurate - errors 1 to 4 times those of routines optimized + for accuracy. + + P.T.Wallace Starlink 7 February 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dmoon.hlp b/math/slalib/doc/dmoon.hlp new file mode 100644 index 00000000..5afe24ce --- /dev/null +++ b/math/slalib/doc/dmoon.hlp @@ -0,0 +1,58 @@ +.help dmoon Jun99 "Slalib Package" +.nf + + SUBROUTINE slDMON (DATE, PV) + + - - - - - - + D M O N + - - - - - - + + Approximate geocentric position and velocity of the Moon + (double precision) + + Given: + DATE D TDB (loosely ET) as a Modified Julian Date + (JD-2400000.5) + + Returned: + PV D(6) Moon x,y,z,xdot,ydot,zdot, mean equator and + equinox of date (AU, AU/s) + + Notes: + + 1 This routine is a full implementation of the algorithm + published by Meeus (see reference). + + 2 Meeus quotes accuracies of 10 arcsec in longitude, 3 arcsec in + latitude and 0.2 arcsec in HP (equivalent to about 20 km in + distance). Comparison with JPL DE200 over the interval + 1960-2025 gives RMS errors of 3.7 arcsec and 83 mas/hour in + longitude, 2.3 arcsec and 48 mas/hour in latitude, 11 km + and 81 mm/s in distance. The maximum errors over the same + interval are 18 arcsec and 0.50 arcsec/hour in longitude, + 11 arcsec and 0.24 arcsec/hour in latitude, 40 km and 0.29 m/s + in distance. + + 3 The original algorithm is expressed in terms of the obsolete + timescale Ephemeris Time. Either TDB or TT can be used, but + not UT without incurring significant errors (30 arcsec at + the present time) due to the Moon's 0.5 arcsec/sec movement. + + 4 The algorithm is based on pre IAU 1976 standards. However, + the result has been moved onto the new (FK5) equinox, an + adjustment which is in any case much smaller than the + intrinsic accuracy of the procedure. + + 5 Velocity is obtained by a complete analytical differentiation + of the Meeus model. + + Reference: + Meeus, l'Astronomie, June 1984, p348. + + P.T.Wallace Starlink 22 January 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dmxm.hlp b/math/slalib/doc/dmxm.hlp new file mode 100644 index 00000000..6eeea162 --- /dev/null +++ b/math/slalib/doc/dmxm.hlp @@ -0,0 +1,34 @@ +.help dmxm Jun99 "Slalib Package" +.nf + + SUBROUTINE slDMXM (A, B, C) + + - - - - - + D M X M + - - - - - + + Product of two 3x3 matrices: + + matrix C = matrix A x matrix B + + (double precision) + + Given: + A dp(3,3) matrix + B dp(3,3) matrix + + Returned: + C dp(3,3) matrix result + + To comply with the ANSI Fortran 77 standard, A, B and C must + be different arrays. However, the routine is coded so as to + work properly on the VAX and many other systems even if this + rule is violated. + + P.T.Wallace Starlink 5 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dmxv.hlp b/math/slalib/doc/dmxv.hlp new file mode 100644 index 00000000..025fd396 --- /dev/null +++ b/math/slalib/doc/dmxv.hlp @@ -0,0 +1,29 @@ +.help dmxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slDMXV (DM, VA, VB) + + - - - - - + D M X V + - - - - - + + Performs the 3-D forward unitary transformation: + + vector VB = matrix DM * vector VA + + (double precision) + + Given: + DM dp(3,3) matrix + VA dp(3) vector + + Returned: + VB dp(3) result vector + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dpav.hlp b/math/slalib/doc/dpav.hlp new file mode 100644 index 00000000..d0111a2d --- /dev/null +++ b/math/slalib/doc/dpav.hlp @@ -0,0 +1,38 @@ +.help dpav Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDPAV ( V1, V2 ) + + - - - - - + D P A V + - - - - - + + Position angle of one celestial direction with respect to another. + + (double precision) + + Given: + V1 d(3) direction cosines of one point + V2 d(3) direction cosines of the other point + + (The coordinate frames correspond to RA,Dec, Long,Lat etc.) + + The result is the bearing (position angle), in radians, of point + V2 with respect to point V1. It is in the range +/- pi. The + sense is such that if V2 is a small distance east of V1, the + bearing is about +pi/2. Zero is returned if the two points + are coincident. + + V1 and V2 need not be unit vectors. + + The routine slDBER performs an equivalent function except + that the points are specified in the form of spherical + coordinates. + + Patrick Wallace Starlink 13 July 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dr2af.hlp b/math/slalib/doc/dr2af.hlp new file mode 100644 index 00000000..b12d75c0 --- /dev/null +++ b/math/slalib/doc/dr2af.hlp @@ -0,0 +1,46 @@ +.help dr2af Jun99 "Slalib Package" +.nf + + SUBROUTINE slDRAF (NDP, ANGLE, SIGN, IDMSF) + + - - - - - - + D R A F + - - - - - - + + Convert an angle in radians to degrees, arcminutes, arcseconds + (double precision) + + Given: + NDP i number of decimal places of arcseconds + ANGLE d angle in radians + + Returned: + SIGN c '+' or '-' + IDMSF i(4) degrees, arcminutes, arcseconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size + of ANGLE, the format of DOUBLE PRECISION floating-point + numbers on the target machine, and the risk of overflowing + IDMSF(4). For example, on the VAX, for ANGLE up to 2pi, the + available floating-point precision corresponds roughly to + NDP=12. However, the practical limit is NDP=9, set by the + capacity of the 32-bit integer IDMSF(4). + + 3) The absolute value of ANGLE may exceed 2pi. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly 2pi and rounds up to 360 deg, + by testing for IDMSF(1)=360 and setting IDMSF(1-4) to zero. + + Called: slDDTF + + P.T.Wallace Starlink 19 March 1999 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dr2tf.hlp b/math/slalib/doc/dr2tf.hlp new file mode 100644 index 00000000..49decabc --- /dev/null +++ b/math/slalib/doc/dr2tf.hlp @@ -0,0 +1,46 @@ +.help dr2tf Jun99 "Slalib Package" +.nf + + SUBROUTINE slDRTF (NDP, ANGLE, SIGN, IHMSF) + + - - - - - - + D R T F + - - - - - - + + Convert an angle in radians to hours, minutes, seconds + (double precision) + + Given: + NDP i number of decimal places of seconds + ANGLE d angle in radians + + Returned: + SIGN c '+' or '-' + IHMSF i(4) hours, minutes, seconds, fraction + + Notes: + + 1) NDP less than zero is interpreted as zero. + + 2) The largest useful value for NDP is determined by the size + of ANGLE, the format of DOUBLE PRECISION floating-point + numbers on the target machine, and the risk of overflowing + IHMSF(4). For example, on the VAX, for ANGLE up to 2pi, the + available floating-point precision corresponds roughly to + NDP=12. However, the practical limit is NDP=9, set by the + capacity of the 32-bit integer IHMSF(4). + + 3) The absolute value of ANGLE may exceed 2pi. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly 2pi and rounds up to 24 hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. + + Called: slDDTF + + P.T.Wallace Starlink 19 March 1999 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/drange.hlp b/math/slalib/doc/drange.hlp new file mode 100644 index 00000000..025b6c08 --- /dev/null +++ b/math/slalib/doc/drange.hlp @@ -0,0 +1,23 @@ +.help drange Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDA1P (ANGLE) + + - - - - - - - + D A 1 P + - - - - - - - + + Normalize angle into range +/- pi (double precision) + + Given: + ANGLE dp the angle in radians + + The result (double precision) is ANGLE expressed in the range +/- pi. + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dranrm.hlp b/math/slalib/doc/dranrm.hlp new file mode 100644 index 00000000..a479127e --- /dev/null +++ b/math/slalib/doc/dranrm.hlp @@ -0,0 +1,24 @@ +.help dranrm Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDA2P (ANGLE) + + - - - - - - - + D A 2 P + - - - - - - - + + Normalize angle into range 0-2 pi (double precision) + + Given: + ANGLE dp the angle in radians + + The result is ANGLE expressed in the range 0-2 pi (double + precision). + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ds2c6.hlp b/math/slalib/doc/ds2c6.hlp new file mode 100644 index 00000000..23d3442e --- /dev/null +++ b/math/slalib/doc/ds2c6.hlp @@ -0,0 +1,32 @@ +.help ds2c6 Jun99 "Slalib Package" +.nf + + SUBROUTINE slDSC6 (A, B, R, AD, BD, RD, V) + + - - - - - - + D S C 6 + - - - - - - + + Conversion of position & velocity in spherical coordinates + to Cartesian coordinates + + (double precision) + + Given: + A dp longitude (radians) + B dp latitude (radians) + R dp radial coordinate + AD dp longitude derivative (radians per unit time) + BD dp latitude derivative (radians per unit time) + RD dp radial derivative + + Returned: + V dp(6) Cartesian position & velocity vector + + P.T.Wallace Starlink 10 July 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ds2tp.hlp b/math/slalib/doc/ds2tp.hlp new file mode 100644 index 00000000..ff772145 --- /dev/null +++ b/math/slalib/doc/ds2tp.hlp @@ -0,0 +1,30 @@ +.help ds2tp Jun99 "Slalib Package" +.nf + + SUBROUTINE slDSTP (RA, DEC, RAZ, DECZ, XI, ETA, J) + + - - - - - - + D S T P + - - - - - - + + Projection of spherical coordinates onto tangent plane: + "gnomonic" projection - "standard coordinates" (double precision) + + Given: + RA,DEC dp spherical coordinates of point to be projected + RAZ,DECZ dp spherical coordinates of tangent point + + Returned: + XI,ETA dp rectangular coordinates on tangent plane + J int status: 0 = OK, star on tangent plane + 1 = error, star too far from axis + 2 = error, antistar on tangent plane + 3 = error, antistar too far from axis + + P.T.Wallace Starlink 18 July 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dsep.hlp b/math/slalib/doc/dsep.hlp new file mode 100644 index 00000000..9b0f1117 --- /dev/null +++ b/math/slalib/doc/dsep.hlp @@ -0,0 +1,29 @@ +.help dsep Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDSEP (A1, B1, A2, B2) + + - - - - - + D S E P + - - - - - + + Angle between two points on a sphere (double precision) + + Given: + A1,B1 dp spherical coordinates of one point + A2,B2 dp spherical coordinates of the other point + + (The spherical coordinates are RA,Dec, Long,Lat etc, in radians.) + + The result is the angle, in radians, between the two points. It + is always positive. + + Called: slDS2C + + P.T.Wallace Starlink April 1985 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dt.hlp b/math/slalib/doc/dt.hlp new file mode 100644 index 00000000..65ddca29 --- /dev/null +++ b/math/slalib/doc/dt.hlp @@ -0,0 +1,55 @@ +.help dt Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDT (EPOCH) + + - - - + D T + - - - + + Estimate the offset between dynamical time and Universal Time + for a given historical epoch. + + Given: + EPOCH d (Julian) epoch (e.g. 1850D0) + + The result is a rough estimate of ET-UT (after 1984, TT-UT) at + the given epoch, in seconds. + + Notes: + + 1 Depending on the epoch, one of three parabolic approximations + is used: + + before 979 Stephenson & Morrison's 390 BC to AD 948 model + 979 to 1708 Stephenson & Morrison's 948 to 1600 model + after 1708 McCarthy & Babcock's post-1650 model + + The breakpoints are chosen to ensure continuity: they occur + at places where the adjacent models give the same answer as + each other. + + 2 The accuracy is modest, with errors of up to 20 sec during + the interval since 1650, rising to perhaps 30 min by 1000 BC. + Comparatively accurate values from AD 1600 are tabulated in + the Astronomical Almanac (see section K8 of the 1995 AA). + + 3 The use of double-precision for both argument and result is + purely for compatibility with other SLALIB time routines. + + 4 The models used are based on a lunar tidal acceleration value + of -26.00 arcsec per century. + + Reference: Explanatory Supplement to the Astronomical Almanac, + ed P.K.Seidelmann, University Science Books (1992), + section 2.553, p83. This contains references to + the Stephenson & Morrison and McCarthy & Babcock + papers. + + P.T.Wallace Starlink 1 March 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtf2d.hlp b/math/slalib/doc/dtf2d.hlp new file mode 100644 index 00000000..eef108f4 --- /dev/null +++ b/math/slalib/doc/dtf2d.hlp @@ -0,0 +1,36 @@ +.help dtf2d Jun99 "Slalib Package" +.nf + + SUBROUTINE slDTFD (IHOUR, IMIN, SEC, DAYS, J) + + - - - - - - + D T F D + - - - - - - + + Convert hours, minutes, seconds to days (double precision) + + Given: + IHOUR int hours + IMIN int minutes + SEC dp seconds + + Returned: + DAYS dp interval in days + J int status: 0 = OK + 1 = IHOUR outside range 0-23 + 2 = IMIN outside range 0-59 + 3 = SEC outside range 0-59.999... + + Notes: + + 1) The result is computed even if any of the range checks fail. + + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink July 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtf2r.hlp b/math/slalib/doc/dtf2r.hlp new file mode 100644 index 00000000..ff3fcfbe --- /dev/null +++ b/math/slalib/doc/dtf2r.hlp @@ -0,0 +1,39 @@ +.help dtf2r Jun99 "Slalib Package" +.nf + + SUBROUTINE slDTFR (IHOUR, IMIN, SEC, RAD, J) + + - - - - - - + D T F R + - - - - - - + + Convert hours, minutes, seconds to radians (double precision) + + Given: + IHOUR int hours + IMIN int minutes + SEC dp seconds + + Returned: + RAD dp angle in radians + J int status: 0 = OK + 1 = IHOUR outside range 0-23 + 2 = IMIN outside range 0-59 + 3 = SEC outside range 0-59.999... + + Called: + slDTFD + + Notes: + + 1) The result is computed even if any of the range checks fail. + + 2) The sign must be dealt with outside this routine. + + P.T.Wallace Starlink July 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtp2s.hlp b/math/slalib/doc/dtp2s.hlp new file mode 100644 index 00000000..73010651 --- /dev/null +++ b/math/slalib/doc/dtp2s.hlp @@ -0,0 +1,28 @@ +.help dtp2s Jun99 "Slalib Package" +.nf + + SUBROUTINE slDTPS (XI, ETA, RAZ, DECZ, RA, DEC) + + - - - - - - + D T P S + - - - - - - + + Transform tangent plane coordinates into spherical + (double precision) + + Given: + XI,ETA dp tangent plane rectangular coordinates + RAZ,DECZ dp spherical coordinates of tangent point + + Returned: + RA,DEC dp spherical coordinates (0-2pi,+/-pi/2) + + Called: slDA2P + + P.T.Wallace Starlink 24 July 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtp2v.hlp b/math/slalib/doc/dtp2v.hlp new file mode 100644 index 00000000..efd928ab --- /dev/null +++ b/math/slalib/doc/dtp2v.hlp @@ -0,0 +1,40 @@ +.help dtp2v Jun99 "Slalib Package" +.nf + + SUBROUTINE slDTPV (XI, ETA, V0, V) + + - - - - - - + D T P V + - - - - - - + + Given the tangent-plane coordinates of a star and the direction + cosines of the tangent point, determine the direction cosines + of the star. + + (double precision) + + Given: + XI,ETA d tangent plane coordinates of star + V0 d(3) direction cosines of tangent point + + Returned: + V d(3) direction cosines of star + + Notes: + + 1 If vector V0 is not of unit length, the returned vector V will + be wrong. + + 2 If vector V0 points at a pole, the returned vector V will be + based on the arbitrary assumption that the RA of the tangent + point is zero. + + 3 This routine is the Cartesian equivalent of the routine slDTPS. + + P.T.Wallace Starlink 11 February 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtps2c.hlp b/math/slalib/doc/dtps2c.hlp new file mode 100644 index 00000000..f0207d86 --- /dev/null +++ b/math/slalib/doc/dtps2c.hlp @@ -0,0 +1,58 @@ +.help dtps2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slDPSC (XI, ETA, RA, DEC, RAZ1, DECZ1, + : RAZ2, DECZ2, N) + + - - - - - - - + D P S C + - - - - - - - + + From the tangent plane coordinates of a star of known RA,Dec, + determine the RA,Dec of the tangent point. + + (double precision) + + Given: + XI,ETA d tangent plane rectangular coordinates + RA,DEC d spherical coordinates + + Returned: + RAZ1,DECZ1 d spherical coordinates of tangent point, solution 1 + RAZ2,DECZ2 d spherical coordinates of tangent point, solution 2 + N i number of solutions: + 0 = no solutions returned (note 2) + 1 = only the first solution is useful (note 3) + 2 = both solutions are useful (note 3) + + Notes: + + 1 The RAZ1 and RAZ2 values are returned in the range 0-2pi. + + 2 Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value, and hence it is + meaningless to ask where the tangent point would have to be + to bring about this combination of XI and DEC. + + 3 Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N=1 indicates only one useful + solution, the usual case; under these circumstances, the second + solution corresponds to the "over-the-pole" case, and this is + reflected in the values of RAZ2 and DECZ2 which are returned. + + 4 The DECZ1 and DECZ2 values are returned in the range +/-pi, but + in the usual, non-pole-crossing, case, the range is +/-pi/2. + + 5 This routine is the spherical equivalent of the routine slDPVC. + + Called: slDA2P + + P.T.Wallace Starlink 5 June 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtpv2c.hlp b/math/slalib/doc/dtpv2c.hlp new file mode 100644 index 00000000..acc94985 --- /dev/null +++ b/math/slalib/doc/dtpv2c.hlp @@ -0,0 +1,51 @@ +.help dtpv2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slDPVC (XI, ETA, V, V01, V02, N) + + - - - - - - - + D P V C + - - - - - - - + + Given the tangent-plane coordinates of a star and its direction + cosines, determine the direction cosines of the tangent-point. + + (double precision) + + Given: + XI,ETA d tangent plane coordinates of star + V d(3) direction cosines of star + + Returned: + V01 d(3) direction cosines of tangent point, solution 1 + V02 d(3) direction cosines of tangent point, solution 2 + N i number of solutions: + 0 = no solutions returned (note 2) + 1 = only the first solution is useful (note 3) + 2 = both solutions are useful (note 3) + + Notes: + + 1 The vector V must be of unit length or the result will be wrong. + + 2 Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value, and hence it is meaningless + to ask where the tangent point would have to be. + + 3 Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N=1 indicates only one useful + solution, the usual case; under these circumstances, the second + solution can be regarded as valid if the vector V02 is interpreted + as the "over-the-pole" case. + + 4 This routine is the Cartesian equivalent of the routine slDPSC. + + P.T.Wallace Starlink 5 June 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dtt.hlp b/math/slalib/doc/dtt.hlp new file mode 100644 index 00000000..67c2b1ae --- /dev/null +++ b/math/slalib/doc/dtt.hlp @@ -0,0 +1,41 @@ +.help dtt Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDTT (UTC) + + - - - - + D T T + - - - - + + Increment to be applied to Coordinated Universal Time UTC to give + Terrestrial Time TT (formerly Ephemeris Time ET) + + (double precision) + + Given: + UTC d UTC date as a modified JD (JD-2400000.5) + + Result: TT-UTC in seconds + + Notes: + + 1 The UTC is specified to be a date rather than a time to indicate + that care needs to be taken not to specify an instant which lies + within a leap second. Though in most cases UTC can include the + fractional part, correct behaviour on the day of a leap second + can only be guaranteed up to the end of the second 23:59:59. + + 2 Pre 1972 January 1 a fixed value of 10 + ET-TAI is returned. + + 3 See also the routine slDT, which roughly estimates ET-UT for + historical epochs. + + Called: slDAT + + P.T.Wallace Starlink 6 December 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dv2tp.hlp b/math/slalib/doc/dv2tp.hlp new file mode 100644 index 00000000..6b927741 --- /dev/null +++ b/math/slalib/doc/dv2tp.hlp @@ -0,0 +1,42 @@ +.help dv2tp Jun99 "Slalib Package" +.nf + + SUBROUTINE slDVTP (V, V0, XI, ETA, J) + + - - - - - - + D V T P + - - - - - - + + Given the direction cosines of a star and of the tangent point, + determine the star's tangent-plane coordinates. + + (double precision) + + Given: + V d(3) direction cosines of star + V0 d(3) direction cosines of tangent point + + Returned: + XI,ETA d tangent plane coordinates of star + J i status: 0 = OK + 1 = error, star too far from axis + 2 = error, antistar on tangent plane + 3 = error, antistar too far from axis + + Notes: + + 1 If vector V0 is not of unit length, or if vector V is of zero + length, the results will be wrong. + + 2 If V0 points at a pole, the returned XI,ETA will be based on the + arbitrary assumption that the RA of the tangent point is zero. + + 3 This routine is the Cartesian equivalent of the routine slDSTP. + + P.T.Wallace Starlink 27 November 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dvdv.hlp b/math/slalib/doc/dvdv.hlp new file mode 100644 index 00000000..d3c566dd --- /dev/null +++ b/math/slalib/doc/dvdv.hlp @@ -0,0 +1,24 @@ +.help dvdv Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slDVDV (VA, VB) + + - - - - - + D V D V + - - - - - + + Scalar product of two 3-vectors (double precision) + + Given: + VA dp(3) first vector + VB dp(3) second vector + + The result is the scalar product VA.VB (double precision) + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dvn.hlp b/math/slalib/doc/dvn.hlp new file mode 100644 index 00000000..295937e6 --- /dev/null +++ b/math/slalib/doc/dvn.hlp @@ -0,0 +1,27 @@ +.help dvn Jun99 "Slalib Package" +.nf + + SUBROUTINE slDVN (V, UV, VM) + + - - - - + D V N + - - - - + + Normalizes a 3-vector also giving the modulus (double precision) + + Given: + V dp(3) vector + + Returned: + UV dp(3) unit vector in direction of V + VM dp modulus of V + + If the modulus of V is zero, UV is set to zero as well + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/dvxv.hlp b/math/slalib/doc/dvxv.hlp new file mode 100644 index 00000000..a7db5344 --- /dev/null +++ b/math/slalib/doc/dvxv.hlp @@ -0,0 +1,25 @@ +.help dvxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slDVXV (VA, VB, VC) + + - - - - - + D V X V + - - - - - + + Vector product of two 3-vectors (double precision) + + Given: + VA dp(3) first vector + VB dp(3) second vector + + Returned: + VC dp(3) vector result + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/e2h.hlp b/math/slalib/doc/e2h.hlp new file mode 100644 index 00000000..f962d80a --- /dev/null +++ b/math/slalib/doc/e2h.hlp @@ -0,0 +1,59 @@ +.help e2h Jun99 "Slalib Package" +.nf + + SUBROUTINE slE2H (HA, DEC, PHI, AZ, EL) + + - - - - + E 2 H + - - - - + + Equatorial to horizon coordinates: HA,Dec to Az,El + + (single precision) + + Given: + HA r hour angle + DEC r declination + PHI r observatory latitude + + Returned: + AZ r azimuth + EL r elevation + + Notes: + + 1) All the arguments are angles in radians. + + 2) Azimuth is returned in the range 0-2pi; north is zero, + and east is +pi/2. Elevation is returned in the range + +/-pi/2. + + 3) The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied. + + 4) In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type of azimuth and elevation. In + particular, it may be important to distinguish between + elevation as affected by refraction, which would + require the "observed" HA,Dec, and the elevation + in vacuo, which would require the "topocentric" HA,Dec. + If the effects of diurnal aberration can be neglected, the + "apparent" HA,Dec may be used instead of the topocentric + HA,Dec. + + 5) No range checking of arguments is carried out. + + 6) In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + + P.T.Wallace Starlink 9 July 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/earth.hlp b/math/slalib/doc/earth.hlp new file mode 100644 index 00000000..ea0eccd6 --- /dev/null +++ b/math/slalib/doc/earth.hlp @@ -0,0 +1,44 @@ +.help earth Jun99 "Slalib Package" +.nf + + SUBROUTINE slERTH (IY, ID, FD, PV) + + - - - - - - + E R T H + - - - - - - + + Approximate heliocentric position and velocity of the Earth + + Given: + IY I year + ID I day in year (1 = Jan 1st) + FD R fraction of day + + Returned: + PV R(6) Earth position & velocity vector + + Notes: + + 1 The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900 March 1 to 2100 February 28. + The year and day can be obtained by calling slCAYD or + slCLYD. + + 2 The Earth heliocentric 6-vector is mean equator and equinox + of date. Position part, PV(1-3), is in AU; velocity part, + PV(4-6), is in AU/sec. + + 3 Max/RMS errors 1950-2050: + 13/5 E-5 AU = 19200/7600 km in position + 47/26 E-10 AU/s = 0.0070/0.0039 km/s in speed + + 4 More precise results are obtainable with the routine slEVP. + + P.T.Wallace Starlink 23 November 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ecleq.hlp b/math/slalib/doc/ecleq.hlp new file mode 100644 index 00000000..02fc6c50 --- /dev/null +++ b/math/slalib/doc/ecleq.hlp @@ -0,0 +1,31 @@ +.help ecleq Jun99 "Slalib Package" +.nf + + SUBROUTINE slECEQ (DL, DB, DATE, DR, DD) + + - - - - - - + E C E Q + - - - - - - + + Transformation from ecliptic coordinates to + J2000.0 equatorial coordinates (double precision) + + Given: + DL,DB dp ecliptic longitude and latitude + (mean of date, IAU 1980 theory, radians) + DATE dp TDB (loosely ET) as Modified Julian Date + (JD-2400000.5) + Returned: + DR,DD dp J2000.0 mean RA,Dec (radians) + + Called: + slDS2C, slECMA, slDIMV, slPREC, slEPJ, slDC2S, + slDA2P, slDA1P + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ecmat.hlp b/math/slalib/doc/ecmat.hlp new file mode 100644 index 00000000..a9be4579 --- /dev/null +++ b/math/slalib/doc/ecmat.hlp @@ -0,0 +1,34 @@ +.help ecmat Jun99 "Slalib Package" +.nf + + SUBROUTINE slECMA (DATE, RMAT) + + - - - - - - + E C M A + - - - - - - + + Form the equatorial to ecliptic rotation matrix - IAU 1980 theory + (double precision) + + Given: + DATE dp TDB (loosely ET) as Modified Julian Date + (JD-2400000.5) + Returned: + RMAT dp(3,3) matrix + + Reference: + Murray,C.A., Vectorial Astrometry, section 4.3. + + Note: + The matrix is in the sense V(ecl) = RMAT * V(equ); the + equator, equinox and ecliptic are mean of date. + + Called: slDEUL + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ecor.hlp b/math/slalib/doc/ecor.hlp new file mode 100644 index 00000000..07cf410f --- /dev/null +++ b/math/slalib/doc/ecor.hlp @@ -0,0 +1,54 @@ +.help ecor Jun99 "Slalib Package" +.nf + + SUBROUTINE slECOR (RM, DM, IY, ID, FD, RV, TL) + + - - - - - + E C O R + - - - - - + + Component of Earth orbit velocity and heliocentric + light time in a given direction (single precision) + + Given: + RM,DM real mean RA, Dec of date (radians) + IY int year + ID int day in year (1 = Jan 1st) + FD real fraction of day + + Returned: + RV real component of Earth orbital velocity (km/sec) + TL real component of heliocentric light time (sec) + + Notes: + + 1 The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900 March 1 to 2100 February 28. + The year and day can be obtained by calling slCAYD or + slCLYD. + + 2 Sign convention: + + The velocity component is +ve when the Earth is receding from + the given point on the sky. The light time component is +ve + when the Earth lies between the Sun and the given point on + the sky. + + 3 Accuracy: + + The velocity component is usually within 0.004 km/s of the + correct value and is never in error by more than 0.007 km/s. + The error in light time correction is about 0.03s at worst, + but is usually better than 0.01s. For applications requiring + higher accuracy, see the slEVP routine. + + Called: slERTH, slCS2C, slVDV + + P.T.Wallace Starlink 24 November 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/eg50.hlp b/math/slalib/doc/eg50.hlp new file mode 100644 index 00000000..da2c0fa3 --- /dev/null +++ b/math/slalib/doc/eg50.hlp @@ -0,0 +1,38 @@ +.help eg50 Jun99 "Slalib Package" +.nf + + SUBROUTINE slEG50 (DR, DD, DL, DB) + + - - - - - + E G 5 0 + - - - - - + + Transformation from B1950.0 'FK4' equatorial coordinates to + IAU 1958 galactic coordinates (double precision) + + Given: + DR,DD dp B1950.0 'FK4' RA,Dec + + Returned: + DL,DB dp galactic longitude and latitude L2,B2 + + (all arguments are radians) + + Called: + slDS2C, slDMXV, slDC2S, slSUET, slDA2P, slDA1P + + Note: + The equatorial coordinates are B1950.0 'FK4'. Use the + routine slEQGA if conversion from J2000.0 coordinates + is required. + + Reference: + Blaauw et al, Mon.Not.R.Astron.Soc.,121,123 (1960) + + P.T.Wallace Starlink 5 September 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/el2ue.hlp b/math/slalib/doc/el2ue.hlp new file mode 100644 index 00000000..9271fff6 --- /dev/null +++ b/math/slalib/doc/el2ue.hlp @@ -0,0 +1,133 @@ +.help el2ue Jun99 "Slalib Package" +.nf + + SUBROUTINE slELUE (DATE, JFORM, EPOCH, ORBINC, ANODE, + : PERIH, AORQ, E, AORL, DM, + : U, JSTAT) + + - - - - - - + E L U E + - - - - - - + + Transform conventional osculating orbital elements into "universal" form. + + Given: + DATE d epoch (TT MJD) of osculation (Note 3) + JFORM i choice of element set (1-3, Note 6) + EPOCH d epoch (TT MJD) of the elements + ORBINC d inclination (radians) + ANODE d longitude of the ascending node (radians) + PERIH d longitude or argument of perihelion (radians) + AORQ d mean distance or perihelion distance (AU) + E d eccentricity + AORL d mean anomaly or longitude (radians, JFORM=1,2 only) + DM d daily motion (radians, JFORM=1 only) + + Returned: + U d(13) universal orbital elements (Note 1) + + (1) combined mass (M+m) + (2) total energy of the orbit (alpha) + (3) reference (osculating) epoch (t0) + (4-6) position at reference epoch (r0) + (7-9) velocity at reference epoch (v0) + (10) heliocentric distance at reference epoch + (11) r0.v0 + (12) date (t) + (13) universal eccentric anomaly (psi) of date, approx + + JSTAT i status: 0 = OK + -1 = illegal JFORM + -2 = illegal E + -3 = illegal AORQ + -4 = illegal DM + -5 = numerical error + + Called: slUEPV, slPVUE + + Notes + + 1 The "universal" elements are those which define the orbit for the + purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i) alpha, which is proportional to the total energy of the + orbit, (ii) the heliocentric distance at epoch, (iii) the + outwards component of the velocity at the given epoch, (iv) an + estimate of psi, the "universal eccentric anomaly" at a given + date and (v) that date. + + 2 The companion routine is slUEPV. This takes the set of numbers + that the present routine outputs and uses them to derive the + object's position and velocity. A single prediction requires one + call to the present routine followed by one call to slUEPV; + for convenience, the two calls are packaged as the routine + slPLNE. Multiple predictions may be made by again calling the + present routine once, but then calling slUEPV multiple times, + which is faster than multiple calls to slPLNE. + + 3 DATE is the epoch of osculation. It is in the TT timescale + (formerly Ephemeris Time, ET) and is a Modified Julian Date + (JD-2400000.5). + + 4 The supplied orbital elements are with respect to the J2000 + ecliptic and equinox. The position and velocity parameters + returned in the array U are with respect to the mean equator and + equinox of epoch J2000, and are for the perihelion prior to the + specified epoch. + + 5 The universal elements returned in the array U are in canonical + units (solar masses, AU and canonical days). + + 6 Three different element-format options are available: + + Option JFORM=1, suitable for the major planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = longitude of perihelion, curly pi (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e (range 0 to <1) + AORL = mean longitude L (radians) + DM = daily motion (radians) + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e (range 0 to <1) + AORL = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e (range 0 to 10) + + 7 Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + + 8 The algorithm was originally adapted from the EPHSLA program of + D.H.P.Jones (private communication, 1996). The method is based + on Stumpff's Universal Variables. + + Reference: Everhart & Pitkin, Am.J.Phys. 51, 712 (1983). + + P.T.Wallace Starlink 18 February 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/epb.hlp b/math/slalib/doc/epb.hlp new file mode 100644 index 00000000..6c7ed368 --- /dev/null +++ b/math/slalib/doc/epb.hlp @@ -0,0 +1,27 @@ +.help epb Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEPB (DATE) + + - - - - + E P B + - - - - + + Conversion of Modified Julian Date to Besselian Epoch + (double precision) + + Given: + DATE dp Modified Julian Date (JD - 2400000.5) + + The result is the Besselian Epoch. + + Reference: + Lieske,J.H., 1979. Astron.Astrophys.,73,282. + + P.T.Wallace Starlink February 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/epb2d.hlp b/math/slalib/doc/epb2d.hlp new file mode 100644 index 00000000..b0ded162 --- /dev/null +++ b/math/slalib/doc/epb2d.hlp @@ -0,0 +1,27 @@ +.help epb2d Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEB2D (EPB) + + - - - - - - + E B 2 D + - - - - - - + + Conversion of Besselian Epoch to Modified Julian Date + (double precision) + + Given: + EPB dp Besselian Epoch + + The result is the Modified Julian Date (JD - 2400000.5). + + Reference: + Lieske,J.H., 1979. Astron.Astrophys.,73,282. + + P.T.Wallace Starlink February 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/epco.hlp b/math/slalib/doc/epco.hlp new file mode 100644 index 00000000..d92bfde2 --- /dev/null +++ b/math/slalib/doc/epco.hlp @@ -0,0 +1,40 @@ +.help epco Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEPCO (K0, K, E) + + - - - - - + E P C O + - - - - - + + Convert an epoch into the appropriate form - 'B' or 'J' + + Given: + K0 char form of result: 'B'=Besselian, 'J'=Julian + K char form of given epoch: 'B' or 'J' + E dp epoch + + Called: slEPB, slEJ2D, slEPJ, slEB2D + + Notes: + + 1) The result is always either equal to or very close to + the given epoch E. The routine is required only in + applications where punctilious treatment of heterogeneous + mixtures of star positions is necessary. + + 2) K0 and K are not validated. They are interpreted as follows: + + o If K0 and K are the same the result is E. + o If K0 is 'B' or 'b' and K isn't, the conversion is J to B. + o In all other cases, the conversion is B to J. + + Note that K0 and K won't match if their cases differ. + + P.T.Wallace Starlink 5 September 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/epj.hlp b/math/slalib/doc/epj.hlp new file mode 100644 index 00000000..34d47ec7 --- /dev/null +++ b/math/slalib/doc/epj.hlp @@ -0,0 +1,26 @@ +.help epj Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEPJ (DATE) + + - - - - + E P J + - - - - + + Conversion of Modified Julian Date to Julian Epoch (double precision) + + Given: + DATE dp Modified Julian Date (JD - 2400000.5) + + The result is the Julian Epoch. + + Reference: + Lieske,J.H., 1979. Astron.Astrophys.,73,282. + + P.T.Wallace Starlink February 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/epj2d.hlp b/math/slalib/doc/epj2d.hlp new file mode 100644 index 00000000..ceadf7ab --- /dev/null +++ b/math/slalib/doc/epj2d.hlp @@ -0,0 +1,26 @@ +.help epj2d Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEJ2D (EPJ) + + - - - - - - + E J 2 D + - - - - - - + + Conversion of Julian Epoch to Modified Julian Date (double precision) + + Given: + EPJ dp Julian Epoch + + The result is the Modified Julian Date (JD - 2400000.5). + + Reference: + Lieske,J.H., 1979. Astron.Astrophys.,73,282. + + P.T.Wallace Starlink February 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/eqecl.hlp b/math/slalib/doc/eqecl.hlp new file mode 100644 index 00000000..a8266afe --- /dev/null +++ b/math/slalib/doc/eqecl.hlp @@ -0,0 +1,31 @@ +.help eqecl Jun99 "Slalib Package" +.nf + + SUBROUTINE slEQEC (DR, DD, DATE, DL, DB) + + - - - - - - + E Q E C + - - - - - - + + Transformation from J2000.0 equatorial coordinates to + ecliptic coordinates (double precision) + + Given: + DR,DD dp J2000.0 mean RA,Dec (radians) + DATE dp TDB (loosely ET) as Modified Julian Date + (JD-2400000.5) + Returned: + DL,DB dp ecliptic longitude and latitude + (mean of date, IAU 1980 theory, radians) + + Called: + slDS2C, slPREC, slEPJ, slDMXV, slECMA, slDC2S, + slDA2P, slDA1P + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/eqeqx.hlp b/math/slalib/doc/eqeqx.hlp new file mode 100644 index 00000000..35da9ab4 --- /dev/null +++ b/math/slalib/doc/eqeqx.hlp @@ -0,0 +1,33 @@ +.help eqeqx Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slEQEX (DATE) + + - - - - - - + E Q E X + - - - - - - + + Equation of the equinoxes (IAU 1994, double precision) + + Given: + DATE dp TDB (loosely ET) as Modified Julian Date + (JD-2400000.5) + + The result is the equation of the equinoxes (double precision) + in radians: + + Greenwich apparent ST = GMST + slEQEX + + References: IAU Resolution C7, Recommendation 3 (1994) + Capitaine, N. & Gontier, A.-M., Astron. Astrophys., + 275, 645-650 (1993) + + Called: slNUTC + + Patrick Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/eqgal.hlp b/math/slalib/doc/eqgal.hlp new file mode 100644 index 00000000..1f37716f --- /dev/null +++ b/math/slalib/doc/eqgal.hlp @@ -0,0 +1,38 @@ +.help eqgal Jun99 "Slalib Package" +.nf + + SUBROUTINE slEQGA (DR, DD, DL, DB) + + - - - - - - + E Q G A + - - - - - - + + Transformation from J2000.0 equatorial coordinates to + IAU 1958 galactic coordinates (double precision) + + Given: + DR,DD dp J2000.0 RA,Dec + + Returned: + DL,DB dp galactic longitude and latitude L2,B2 + + (all arguments are radians) + + Called: + slDS2C, slDMXV, slDC2S, slDA2P, slDA1P + + Note: + The equatorial coordinates are J2000.0. Use the routine + slEG50 if conversion from B1950.0 'FK4' coordinates is + required. + + Reference: + Blaauw et al, Mon.Not.R.Astron.Soc.,121,123 (1960) + + P.T.Wallace Starlink 21 September 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/etrms.hlp b/math/slalib/doc/etrms.hlp new file mode 100644 index 00000000..bc14b655 --- /dev/null +++ b/math/slalib/doc/etrms.hlp @@ -0,0 +1,35 @@ +.help etrms Jun99 "Slalib Package" +.nf + + SUBROUTINE slETRM (EP, EV) + + - - - - - - + E T R M + - - - - - - + + Compute the E-terms (elliptic component of annual aberration) + vector (double precision) + + Given: + EP dp Besselian epoch + + Returned: + EV dp(3) E-terms as (dx,dy,dz) + + Note the use of the J2000 aberration constant (20.49552 arcsec). + This is a reflection of the fact that the E-terms embodied in + existing star catalogues were computed from a variety of + aberration constants. Rather than adopting one of the old + constants the latest value is used here. + + References: + 1 Smith, C.A. et al., 1989. Astr.J. 97, 265. + 2 Yallop, B.D. et al., 1989. Astr.J. 97, 274. + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/euler.hlp b/math/slalib/doc/euler.hlp new file mode 100644 index 00000000..7ae2fedc --- /dev/null +++ b/math/slalib/doc/euler.hlp @@ -0,0 +1,52 @@ +.help euler Jun99 "Slalib Package" +.nf + + SUBROUTINE slEULR (ORDER, PHI, THETA, PSI, RMAT) + + - - - - - - + E U L R + - - - - - - + + Form a rotation matrix from the Euler angles - three successive + rotations about specified Cartesian axes (single precision) + + Given: + ORDER c*(*) specifies about which axes the rotations occur + PHI r 1st rotation (radians) + THETA r 2nd rotation ( " ) + PSI r 3rd rotation ( " ) + + Returned: + RMAT r(3,3) rotation matrix + + A rotation is positive when the reference frame rotates + anticlockwise as seen looking towards the origin from the + positive region of the specified axis. + + The characters of ORDER define which axes the three successive + rotations are about. A typical value is 'ZXZ', indicating that + RMAT is to become the direction cosine matrix corresponding to + rotations of the reference frame through PHI radians about the + old Z-axis, followed by THETA radians about the resulting X-axis, + then PSI radians about the resulting Z-axis. + + The axis names can be any of the following, in any order or + combination: X, Y, Z, uppercase or lowercase, 1, 2, 3. Normal + axis labeling/numbering conventions apply; the xyz (=123) + triad is right-handed. Thus, the 'ZXZ' example given above + could be written 'zxz' or '313' (or even 'ZxZ' or '3xZ'). ORDER + is terminated by length or by the first unrecognized character. + + Fewer than three rotations are acceptable, in which case the later + angle arguments are ignored. If all rotations are zero, the + identity matrix is produced. + + Called: slDEUL + + P.T.Wallace Starlink 23 May 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/evp.hlp b/math/slalib/doc/evp.hlp new file mode 100644 index 00000000..e7fa04cf --- /dev/null +++ b/math/slalib/doc/evp.hlp @@ -0,0 +1,66 @@ +.help evp Jun99 "Slalib Package" +.nf + + SUBROUTINE slEVP (DATE, DEQX, DVB, DPB, DVH, DPH) + + - - - - + E V P + - - - - + + Barycentric and heliocentric velocity and position of the Earth + + All arguments are double precision + + Given: + + DATE TDB (loosely ET) as a Modified Julian Date + (JD-2400000.5) + + DEQX Julian Epoch (e.g. 2000.0D0) of mean equator and + equinox of the vectors returned. If DEQX .LE. 0D0, + all vectors are referred to the mean equator and + equinox (FK5) of epoch DATE. + + Returned (all 3D Cartesian vectors): + + DVB,DPB barycentric velocity, position + + DVH,DPH heliocentric velocity, position + + (Units are AU/s for velocity and AU for position) + + Called: slEPJ, slPREC + + Accuracy: + + The maximum deviations from the JPL DE96 ephemeris are as + follows: + + barycentric velocity 0.42 m/s + barycentric position 6900 km + + heliocentric velocity 0.42 m/s + heliocentric position 1600 km + + This routine is adapted from the BARVEL and BARCOR + subroutines of P.Stumpff, which are described in + Astron. Astrophys. Suppl. Ser. 41, 1-8 (1980). Most of the + changes are merely cosmetic and do not affect the results at + all. However, some adjustments have been made so as to give + results that refer to the new (IAU 1976 'FK5') equinox + and precession, although the differences these changes make + relative to the results from Stumpff's original 'FK4' version + are smaller than the inherent accuracy of the algorithm. One + minor shortcoming in the original routines that has NOT been + corrected is that better numerical accuracy could be achieved + if the various polynomial evaluations were nested. Note also + that one of Stumpff's precession constants differs by 0.001 arcsec + from the value given in the Explanatory Supplement to the A.E. + + P.T.Wallace Starlink 21 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fitxy.hlp b/math/slalib/doc/fitxy.hlp new file mode 100644 index 00000000..814deb9f --- /dev/null +++ b/math/slalib/doc/fitxy.hlp @@ -0,0 +1,76 @@ +.help fitxy Jun99 "Slalib Package" +.nf + + SUBROUTINE slFTXY (ITYPE,NP,XYE,XYM,COEFFS,J) + + - - - - - - + F T X Y + - - - - - - + + Fit a linear model to relate two sets of [X,Y] coordinates. + + Given: + ITYPE i type of model: 4 or 6 (note 1) + NP i number of samples (note 2) + XYE d(2,np) expected [X,Y] for each sample + XYM d(2,np) measured [X,Y] for each sample + + Returned: + COEFFS d(6) coefficients of model (note 3) + J i status: 0 = OK + -1 = illegal ITYPE + -2 = insufficient data + -3 = singular solution + + Notes: + + 1) ITYPE, which must be either 4 or 6, selects the type of model + fitted. Both allowed ITYPE values produce a model COEFFS which + consists of six coefficients, namely the zero points and, for + each of XE and YE, the coefficient of XM and YM. For ITYPE=6, + all six coefficients are independent, modelling squash and shear + as well as origin, scale, and orientation. However, ITYPE=4 + selects the "solid body rotation" option; the model COEFFS + still consists of the same six coefficients, but now two of + them are used twice (appropriately signed). Origin, scale + and orientation are still modelled, but not squash or shear - + the units of X and Y have to be the same. + + 2) For NC=4, NP must be at least 2. For NC=6, NP must be at + least 3. + + 3) The model is returned in the array COEFFS. Naming the + elements of COEFFS as follows: + + COEFFS(1) = A + COEFFS(2) = B + COEFFS(3) = C + COEFFS(4) = D + COEFFS(5) = E + COEFFS(6) = F + + the model is: + + XE = A + B*XM + C*YM + YE = D + E*XM + F*YM + + For the "solid body rotation" option (ITYPE=4), the + magnitudes of B and F, and of C and E, are equal. The + signs of these coefficients depend on whether there is a + sign reversal between XE,YE and XM,YM; fits are performed + with and without a sign reversal and the best one chosen. + + 4) Error status values J=-1 and -2 leave COEFFS unchanged; + if J=-3 COEFFS may have been changed. + + See also slPXY, slINVF, slXYXY, slDCMF + + Called: slDMAT, slDMXV + + P.T.Wallace Starlink 11 February 1991 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk425.hlp b/math/slalib/doc/fk425.hlp new file mode 100644 index 00000000..808dcb7b --- /dev/null +++ b/math/slalib/doc/fk425.hlp @@ -0,0 +1,81 @@ +.help fk425 Jun99 "Slalib Package" +.nf + + SUBROUTINE slFK45 (R1950,D1950,DR1950,DD1950,P1950,V1950, + : R2000,D2000,DR2000,DD2000,P2000,V2000) + + - - - - - - + F K 4 5 + - - - - - - + + Convert B1950.0 FK4 star data to J2000.0 FK5 (double precision) + + This routine converts stars from the old, Bessel-Newcomb, FK4 + system to the new, IAU 1976, FK5, Fricke system. The precepts + of Smith et al (Ref 1) are followed, using the implementation + by Yallop et al (Ref 2) of a matrix method due to Standish. + Kinoshita's development of Andoyer's post-Newcomb precession is + used. The numerical constants from Seidelmann et al (Ref 3) are + used canonically. + + Given: (all B1950.0,FK4) + R1950,D1950 dp B1950.0 RA,Dec (rad) + DR1950,DD1950 dp B1950.0 proper motions (rad/trop.yr) + P1950 dp parallax (arcsec) + V1950 dp radial velocity (km/s, +ve = moving away) + + Returned: (all J2000.0,FK5) + R2000,D2000 dp J2000.0 RA,Dec (rad) + DR2000,DD2000 dp J2000.0 proper motions (rad/Jul.yr) + P2000 dp parallax (arcsec) + V2000 dp radial velocity (km/s, +ve = moving away) + + Notes: + + 1) The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt, and are per year rather than per century. + + 2) Conversion from Besselian epoch 1950.0 to Julian epoch + 2000.0 only is provided for. Conversions involving other + epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or + after FK425 is called. + + 3) In the FK4 catalogue the proper motions of stars within + 10 degrees of the poles do not embody the differential + E-term effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch 2000, + and measuring on the sky rather than in terms of dRA, the + errors resulting from this simplification are less than + 1 milliarcsecond in position and 1 milliarcsecond per + century in proper motion. + + References: + + 1 Smith, C.A. et al, 1989. "The transformation of astrometric + catalog systems to the equinox J2000.0". Astron.J. 97, 265. + + 2 Yallop, B.D. et al, 1989. "Transformation of mean star places + from FK4 B1950.0 to FK5 J2000.0 using matrices in 6-space". + Astron.J. 97, 274. + + 3 Seidelmann, P.K. (ed), 1992. "Explanatory Supplement to + the Astronomical Almanac", ISBN 0-935702-68-7. + + P.T.Wallace Starlink 19 December 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk45z.hlp b/math/slalib/doc/fk45z.hlp new file mode 100644 index 00000000..6994302f --- /dev/null +++ b/math/slalib/doc/fk45z.hlp @@ -0,0 +1,83 @@ +.help fk45z Jun99 "Slalib Package" +.nf + + SUBROUTINE slF45Z (R1950,D1950,BEPOCH,R2000,D2000) + + - - - - - - + F 4 5 Z + - - - - - - + + Convert B1950.0 FK4 star data to J2000.0 FK5 assuming zero + proper motion in the FK5 frame (double precision) + + This routine converts stars from the old, Bessel-Newcomb, FK4 + system to the new, IAU 1976, FK5, Fricke system, in such a + way that the FK5 proper motion is zero. Because such a star + has, in general, a non-zero proper motion in the FK4 system, + the routine requires the epoch at which the position in the + FK4 system was determined. + + The method is from Appendix 2 of Ref 1, but using the constants + of Ref 4. + + Given: + R1950,D1950 dp B1950.0 FK4 RA,Dec at epoch (rad) + BEPOCH dp Besselian epoch (e.g. 1979.3D0) + + Returned: + R2000,D2000 dp J2000.0 FK5 RA,Dec (rad) + + Notes: + + 1) The epoch BEPOCH is strictly speaking Besselian, but + if a Julian epoch is supplied the result will be + affected only to a negligible extent. + + 2) Conversion from Besselian epoch 1950.0 to Julian epoch + 2000.0 only is provided for. Conversions involving other + epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or + after FK45Z is called. + + 3) In the FK4 catalogue the proper motions of stars within + 10 degrees of the poles do not embody the differential + E-term effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch 2000, + and measuring on the sky rather than in terms of dRA, the + errors resulting from this simplification are less than + 1 milliarcsecond in position and 1 milliarcsecond per + century in proper motion. + + References: + + 1 Aoki,S., et al, 1983. Astron.Astrophys., 128, 263. + + 2 Smith, C.A. et al, 1989. "The transformation of astrometric + catalog systems to the equinox J2000.0". Astron.J. 97, 265. + + 3 Yallop, B.D. et al, 1989. "Transformation of mean star places + from FK4 B1950.0 to FK5 J2000.0 using matrices in 6-space". + Astron.J. 97, 274. + + 4 Seidelmann, P.K. (ed), 1992. "Explanatory Supplement to + the Astronomical Almanac", ISBN 0-935702-68-7. + + Called: slDS2C, slEPJ, slEB2D, slDC2S, slDA2P + + P.T.Wallace Starlink 21 September 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk524.hlp b/math/slalib/doc/fk524.hlp new file mode 100644 index 00000000..ed86273b --- /dev/null +++ b/math/slalib/doc/fk524.hlp @@ -0,0 +1,81 @@ +.help fk524 Jun99 "Slalib Package" +.nf + + SUBROUTINE slFK54 (R2000,D2000,DR2000,DD2000,P2000,V2000, + : R1950,D1950,DR1950,DD1950,P1950,V1950) + + - - - - - - + F K 5 4 + - - - - - - + + Convert J2000.0 FK5 star data to B1950.0 FK4 (double precision) + + This routine converts stars from the new, IAU 1976, FK5, Fricke + system, to the old, Bessel-Newcomb, FK4 system. The precepts + of Smith et al (Ref 1) are followed, using the implementation + by Yallop et al (Ref 2) of a matrix method due to Standish. + Kinoshita's development of Andoyer's post-Newcomb precession is + used. The numerical constants from Seidelmann et al (Ref 3) are + used canonically. + + Given: (all J2000.0,FK5) + R2000,D2000 dp J2000.0 RA,Dec (rad) + DR2000,DD2000 dp J2000.0 proper motions (rad/Jul.yr) + P2000 dp parallax (arcsec) + V2000 dp radial velocity (km/s, +ve = moving away) + + Returned: (all B1950.0,FK4) + R1950,D1950 dp B1950.0 RA,Dec (rad) + DR1950,DD1950 dp B1950.0 proper motions (rad/trop.yr) + P1950 dp parallax (arcsec) + V1950 dp radial velocity (km/s, +ve = moving away) + + Notes: + + 1) The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt, and are per year rather than per century. + + 2) Note that conversion from Julian epoch 2000.0 to Besselian + epoch 1950.0 only is provided for. Conversions involving + other epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or after + FK524 is called. + + 3) In the FK4 catalogue the proper motions of stars within + 10 degrees of the poles do not embody the differential + E-term effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch 2000, + and measuring on the sky rather than in terms of dRA, the + errors resulting from this simplification are less than + 1 milliarcsecond in position and 1 milliarcsecond per + century in proper motion. + + References: + + 1 Smith, C.A. et al, 1989. "The transformation of astrometric + catalog systems to the equinox J2000.0". Astron.J. 97, 265. + + 2 Yallop, B.D. et al, 1989. "Transformation of mean star places + from FK4 B1950.0 to FK5 J2000.0 using matrices in 6-space". + Astron.J. 97, 274. + + 3 Seidelmann, P.K. (ed), 1992. "Explanatory Supplement to + the Astronomical Almanac", ISBN 0-935702-68-7. + + P.T.Wallace Starlink 19 December 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk52h.hlp b/math/slalib/doc/fk52h.hlp new file mode 100644 index 00000000..ad7cb724 --- /dev/null +++ b/math/slalib/doc/fk52h.hlp @@ -0,0 +1,56 @@ +.help fk52h Jun99 "Slalib Package" +.nf + + SUBROUTINE slFK5H (R5,D5,DR5,DD5,RH,DH,DRH,DDH) + + - - - - - - + F K 5 H + - - - - - - + + Transform FK5 (J2000) star data into the Hipparcos frame. + + (double precision) + + This routine transforms FK5 star positions and proper motions + into the frame of the Hipparcos catalogue. + + Given (all FK5, equinox J2000, epoch J2000): + R5 d RA (radians) + D5 d Dec (radians) + DR5 d proper motion in RA (dRA/dt, rad/Jyear) + DD5 d proper motion in Dec (dDec/dt, rad/Jyear) + + Returned (all Hipparcos, epoch J2000): + RH d RA (radians) + DH d Dec (radians) + DRH d proper motion in RA (dRA/dt, rad/Jyear) + DDH d proper motion in Dec (dDec/dt, rad/Jyear) + + Called: slDSC6, slDAVM, slDMXV, slDVXV, slDC6S + + Notes: + + 1) The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt, and are per year rather than per century. + + 2) The FK5 to Hipparcos transformation consists of a pure + rotation and spin; zonal errors in the FK5 catalogue are + not taken into account. + + 3) The published orientation and spin components are interpreted + as "axial vectors". An axial vector points at the pole of the + rotation and its length is the amount of rotation in radians. + + 4) See also slHFK5, slF5HZ, slHF5Z. + + Reference: + + M.Feissel & F.Mignard, Astron. Astrophys. 331, L33-L36 (1998). + + P.T.Wallace Starlink 7 October 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk54z.hlp b/math/slalib/doc/fk54z.hlp new file mode 100644 index 00000000..b453bad9 --- /dev/null +++ b/math/slalib/doc/fk54z.hlp @@ -0,0 +1,56 @@ +.help fk54z Jun99 "Slalib Package" +.nf + + SUBROUTINE slF54Z (R2000,D2000,BEPOCH, + : R1950,D1950,DR1950,DD1950) + + - - - - - - + F 5 4 Z + - - - - - - + + Convert a J2000.0 FK5 star position to B1950.0 FK4 assuming + zero proper motion and parallax (double precision) + + This routine converts star positions from the new, IAU 1976, + FK5, Fricke system to the old, Bessel-Newcomb, FK4 system. + + Given: + R2000,D2000 dp J2000.0 FK5 RA,Dec (rad) + BEPOCH dp Besselian epoch (e.g. 1950D0) + + Returned: + R1950,D1950 dp B1950.0 FK4 RA,Dec (rad) at epoch BEPOCH + DR1950,DD1950 dp B1950.0 FK4 proper motions (rad/trop.yr) + + Notes: + + 1) The proper motion in RA is dRA/dt rather than cos(Dec)*dRA/dt. + + 2) Conversion from Julian epoch 2000.0 to Besselian epoch 1950.0 + only is provided for. Conversions involving other epochs will + require use of the appropriate precession routines before and + after this routine is called. + + 3) Unlike in the slFK54 routine, the FK5 proper motions, the + parallax and the radial velocity are presumed zero. + + 4) It is the intention that FK5 should be a close approximation + to an inertial frame, so that distant objects have zero proper + motion; such objects have (in general) non-zero proper motion + in FK4, and this routine returns those fictitious proper + motions. + + 5) The position returned by this routine is in the B1950 + reference frame but at Besselian epoch BEPOCH. For + comparison with catalogues the BEPOCH argument will + frequently be 1950D0. + + Called: slFK54, slPM + + P.T.Wallace Starlink 10 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/fk5hz.hlp b/math/slalib/doc/fk5hz.hlp new file mode 100644 index 00000000..4d5e5ab0 --- /dev/null +++ b/math/slalib/doc/fk5hz.hlp @@ -0,0 +1,54 @@ +.help fk5hz Jun99 "Slalib Package" +.nf + + SUBROUTINE slF5HZ (R5,D5,EPOCH,RH,DH) + + - - - - - - + F 5 H Z + - - - - - - + + Transform an FK5 (J2000) star position into the frame of the + Hipparcos catalogue, assuming zero Hipparcos proper motion. + + (double precision) + + This routine converts a star position from the FK5 system to + the Hipparcos system, in such a way that the Hipparcos proper + motion is zero. Because such a star has, in general, a non-zero + proper motion in the FK5 system, the routine requires the epoch + at which the position in the FK5 system was determined. + + Given: + R5 d FK5 RA (radians), equinox J2000, epoch EPOCH + D5 d FK5 Dec (radians), equinox J2000, epoch EPOCH + EPOCH d Julian epoch (TDB) + + Returned (all Hipparcos): + RH d RA (radians) + DH d Dec (radians) + + Called: slDS2C, slDAVM, slDIMV, slDMXV, slDC2S + + Notes: + + 1) The FK5 to Hipparcos transformation consists of a pure + rotation and spin; zonal errors in the FK5 catalogue are + not taken into account. + + 2) The published orientation and spin components are interpreted + as "axial vectors". An axial vector points at the pole of the + rotation and its length is the amount of rotation in radians. + + 3) See also slFK5H, slHFK5, slHF5Z. + + Reference: + + M.Feissel & F.Mignard, Astron. Astrophys. 331, L33-L36 (1998). + + P.T.Wallace Starlink 7 October 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/flotin.hlp b/math/slalib/doc/flotin.hlp new file mode 100644 index 00000000..5e3d8bd6 --- /dev/null +++ b/math/slalib/doc/flotin.hlp @@ -0,0 +1,118 @@ +.help flotin Jun99 "Slalib Package" +.nf + + SUBROUTINE slRFLI (STRING, NSTRT, RESLT, JFLAG) + + - - - - - - - + R F L I + - - - - - - - + + Convert free-format input into single precision floating point + + Given: + STRING c string containing number to be decoded + NSTRT i pointer to where decoding is to start + RESLT r current value of result + + Returned: + NSTRT i advanced to next number + RESLT r result + JFLAG i status: -1 = -OK, 0 = +OK, 1 = null, 2 = error + + Called: slDFLI + + Notes: + + 1 The reason FLOTIN has separate OK status values for + + and - is to enable minus zero to be detected. This is + of crucial importance when decoding mixed-radix numbers. + For example, an angle expressed as deg, arcmin, arcsec + may have a leading minus sign but a zero degrees field. + + 2 A TAB is interpreted as a space, and lowercase characters + are interpreted as uppercase. + + 3 The basic format is the sequence of fields #^.^@#^, where + # is a sign character + or -, ^ means a string of decimal + digits, and @, which indicates an exponent, means D or E. + Various combinations of these fields can be omitted, and + embedded blanks are permissible in certain places. + + 4 Spaces: + + . Leading spaces are ignored. + + . Embedded spaces are allowed only after +, -, D or E, + and after the decomal point if the first sequence of + digits is absent. + + . Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + + 5 Delimiters: + + . Any character other than +,-,0-9,.,D,E or space may be + used to signal the end of the number and terminate + decoding. + + . Comma is recognized by FLOTIN as a special case; it + is skipped, leaving the pointer on the next character. + See 13, below. + + 6 Both signs are optional. The default is +. + + 7 The mantissa ^.^ defaults to 1. + + 8 The exponent @#^ defaults to E0. + + 9 The strings of decimal digits may be of any length. + + 10 The decimal point is optional for whole numbers. + + 11 A "null result" occurs when the string of characters being + decoded does not begin with +,-,0-9,.,D or E, or consists + entirely of spaces. When this condition is detected, JFLAG + is set to 1 and RESLT is left untouched. + + 12 NSTRT = 1 for the first character in the string. + + 13 On return from FLOTIN, NSTRT is set ready for the next + decode - following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to FLOTIN, otherwise + all subsequent calls will return a null result. + + 14 Errors (JFLAG=2) occur when: + + . a +, -, D or E is left unsatisfied; or + + . the decimal point is present without at least + one decimal digit before or after it; or + + . an exponent more than 100 has been presented. + + 15 When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. This + may be after the point at which a more sophisticated + program could have detected the error. For example, + FLOTIN does not detect that '1E999' is unacceptable + (on a computer where this is so) until the entire number + has been decoded. + + 16 Certain highly unlikely combinations of mantissa & + exponent can cause arithmetic faults during the + decode, in some cases despite the fact that they + together could be construed as a valid number. + + 17 Decoding is left to right, one pass. + + 18 See also DFLTIN and INTIN + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/galeq.hlp b/math/slalib/doc/galeq.hlp new file mode 100644 index 00000000..6bda60d1 --- /dev/null +++ b/math/slalib/doc/galeq.hlp @@ -0,0 +1,38 @@ +.help galeq Jun99 "Slalib Package" +.nf + + SUBROUTINE slGAEQ (DL, DB, DR, DD) + + - - - - - - + G A E Q + - - - - - - + + Transformation from IAU 1958 galactic coordinates to + J2000.0 equatorial coordinates (double precision) + + Given: + DL,DB dp galactic longitude and latitude L2,B2 + + Returned: + DR,DD dp J2000.0 RA,Dec + + (all arguments are radians) + + Called: + slDS2C, slDIMV, slDC2S, slDA2P, slDA1P + + Note: + The equatorial coordinates are J2000.0. Use the routine + slGE50 if conversion to B1950.0 'FK4' coordinates is + required. + + Reference: + Blaauw et al, Mon.Not.R.Astron.Soc.,121,123 (1960) + + P.T.Wallace Starlink 21 September 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/galsup.hlp b/math/slalib/doc/galsup.hlp new file mode 100644 index 00000000..497211ac --- /dev/null +++ b/math/slalib/doc/galsup.hlp @@ -0,0 +1,43 @@ +.help galsup Jun99 "Slalib Package" +.nf + + SUBROUTINE slGASU (DL, DB, DSL, DSB) + + - - - - - - - + G A S U + - - - - - - - + + Transformation from IAU 1958 galactic coordinates to + de Vaucouleurs supergalactic coordinates (double precision) + + Given: + DL,DB dp galactic longitude and latitude L2,B2 + + Returned: + DSL,DSB dp supergalactic longitude and latitude + + (all arguments are radians) + + Called: + slDS2C, slDMXV, slDC2S, slDA2P, slDA1P + + References: + + de Vaucouleurs, de Vaucouleurs, & Corwin, Second Reference + Catalogue of Bright Galaxies, U. Texas, page 8. + + Systems & Applied Sciences Corp., Documentation for the + machine-readable version of the above catalogue, + Contract NAS 5-26490. + + (These two references give different values for the galactic + longitude of the supergalactic origin. Both are wrong; the + correct value is L2=137.37.) + + P.T.Wallace Starlink 25 January 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ge50.hlp b/math/slalib/doc/ge50.hlp new file mode 100644 index 00000000..b064e834 --- /dev/null +++ b/math/slalib/doc/ge50.hlp @@ -0,0 +1,38 @@ +.help ge50 Jun99 "Slalib Package" +.nf + + SUBROUTINE slGE50 (DL, DB, DR, DD) + + - - - - - + G E 5 0 + - - - - - + + Transformation from IAU 1958 galactic coordinates to + B1950.0 'FK4' equatorial coordinates (double precision) + + Given: + DL,DB dp galactic longitude and latitude L2,B2 + + Returned: + DR,DD dp B1950.0 'FK4' RA,Dec + + (all arguments are radians) + + Called: + slDS2C, slDIMV, slDC2S, slADET, slDA2P, slDA1P + + Note: + The equatorial coordinates are B1950.0 'FK4'. Use the + routine slGAEQ if conversion to J2000.0 coordinates + is required. + + Reference: + Blaauw et al, Mon.Not.R.Astron.Soc.,121,123 (1960) + + P.T.Wallace Starlink 5 September 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/geoc.hlp b/math/slalib/doc/geoc.hlp new file mode 100644 index 00000000..538474d1 --- /dev/null +++ b/math/slalib/doc/geoc.hlp @@ -0,0 +1,33 @@ +.help geoc Jun99 "Slalib Package" +.nf + + SUBROUTINE slGEOC (P, H, R, Z) + + - - - - - + G E O C + - - - - - + + Convert geodetic position to geocentric (double precision) + + Given: + P dp latitude (geodetic, radians) + H dp height above reference spheroid (geodetic, metres) + + Returned: + R dp distance from Earth axis (AU) + Z dp distance from plane of Earth equator (AU) + + Notes: + 1) Geocentric latitude can be obtained by evaluating ATAN2(Z,R). + 2) IAU 1976 constants are used. + + Reference: + Green,R.M., Spherical Astronomy, CUP 1985, p98. + + P.T.Wallace Starlink 4th October 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/gmst.hlp b/math/slalib/doc/gmst.hlp new file mode 100644 index 00000000..7e58aec9 --- /dev/null +++ b/math/slalib/doc/gmst.hlp @@ -0,0 +1,41 @@ +.help gmst Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slGMST (UT1) + + - - - - - + G M S T + - - - - - + + Conversion from universal time to sidereal time (double precision) + + Given: + UT1 dp universal time (strictly UT1) expressed as + modified Julian Date (JD-2400000.5) + + The result is the Greenwich mean sidereal time (double + precision, radians). + + The IAU 1982 expression (see page S15 of 1984 Astronomical + Almanac) is used, but rearranged to reduce rounding errors. + This expression is always described as giving the GMST at + 0 hours UT. In fact, it gives the difference between the + GMST and the UT, which happens to equal the GMST (modulo + 24 hours) at 0 hours UT each day. In this routine, the + entire UT is used directly as the argument for the + standard formula, and the fractional part of the UT is + added separately; note that the factor 1.0027379... does + not appear. + + See also the routine slGMSA, which delivers better numerical + precision by accepting the UT date and time as separate arguments. + + Called: slDA2P + + P.T.Wallace Starlink 14 September 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/gmsta.hlp b/math/slalib/doc/gmsta.hlp new file mode 100644 index 00000000..e959d6cc --- /dev/null +++ b/math/slalib/doc/gmsta.hlp @@ -0,0 +1,55 @@ +.help gmsta Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slGMSA (DATE, UT) + + - - - - - - + G M S A + - - - - - - + + Conversion from Universal Time to Greenwich mean sidereal time, + with rounding errors minimized. + + double precision + + Given: + DATE d UT1 date (MJD: integer part of JD-2400000.5)) + UT d UT1 time (fraction of a day) + + The result is the Greenwich mean sidereal time (double precision, + radians, in the range 0 to 2pi). + + There is no restriction on how the UT is apportioned between the + DATE and UT arguments. Either of the two arguments could, for + example, be zero and the entire date+time supplied in the other. + However, the routine is designed to deliver maximum accuracy when + the DATE argument is a whole number and the UT lies in the range + 0 to 1 (or vice versa). + + The algorithm is based on the IAU 1982 expression (see page S15 of + the 1984 Astronomical Almanac). This is always described as giving + the GMST at 0 hours UT1. In fact, it gives the difference between + the GMST and the UT, the steady 4-minutes-per-day drawing-ahead of + ST with respect to UT. When whole days are ignored, the expression + happens to equal the GMST at 0 hours UT1 each day. + + In this routine, the entire UT1 (the sum of the two arguments DATE + and UT) is used directly as the argument for the standard formula. + The UT1 is then added, but omitting whole days to conserve accuracy. + + See also the routine slGMST, which accepts the UT as a single + argument. Compared with slGMST, the extra numerical precision + delivered by the present routine is unlikely to be important in + an absolute sense, but may be useful when critically comparing + algorithms and in applications where two sidereal times close + together are differenced. + + Called: slDA2P + + P.T.Wallace Starlink 13 April 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/h2e.hlp b/math/slalib/doc/h2e.hlp new file mode 100644 index 00000000..06fd4282 --- /dev/null +++ b/math/slalib/doc/h2e.hlp @@ -0,0 +1,58 @@ +.help h2e Jun99 "Slalib Package" +.nf + + SUBROUTINE slH2E (AZ, EL, PHI, HA, DEC) + + - - - - - + D E 2 H + - - - - - + + Horizon to equatorial coordinates: Az,El to HA,Dec + + (single precision) + + Given: + AZ r azimuth + EL r elevation + PHI r observatory latitude + + Returned: + HA r hour angle + DEC r declination + + Notes: + + 1) All the arguments are angles in radians. + + 2) The sign convention for azimuth is north zero, east +pi/2. + + 3) HA is returned in the range +/-pi. Declination is returned + in the range +/-pi/2. + + 4) The latitude is (in principle) geodetic. In critical + applications, corrections for polar motion should be applied. + + 5) In some applications it will be important to specify the + correct type of elevation in order to produce the required + type of HA,Dec. In particular, it may be important to + distinguish between the elevation as affected by refraction, + which will yield the "observed" HA,Dec, and the elevation + in vacuo, which will yield the "topocentric" HA,Dec. If the + effects of diurnal aberration can be neglected, the + topocentric HA,Dec may be used as an approximation to the + "apparent" HA,Dec. + + 6) No range checking of arguments is done. + + 7) In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude. + + P.T.Wallace Starlink 21 February 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/h2fk5.hlp b/math/slalib/doc/h2fk5.hlp new file mode 100644 index 00000000..158d9cfb --- /dev/null +++ b/math/slalib/doc/h2fk5.hlp @@ -0,0 +1,57 @@ +.help h2fk5 Jun99 "Slalib Package" +.nf + + SUBROUTINE slHFK5 (RH,DH,DRH,DDH,R5,D5,DR5,DD5) + + - - - - - - + H F K 5 + - - - - - - + + Transform Hipparcos star data into the FK5 (J2000) system. + + (double precision) + + This routine transforms Hipparcos star positions and proper + motions into FK5 J2000. + + Given (all Hipparcos, epoch J2000): + RH d RA (radians) + DH d Dec (radians) + DRH d proper motion in RA (dRA/dt, rad/Jyear) + DDH d proper motion in Dec (dDec/dt, rad/Jyear) + + Returned (all FK5, equinox J2000, epoch J2000): + R5 d RA (radians) + D5 d Dec (radians) + DR5 d proper motion in RA (dRA/dt, rad/Jyear) + DD5 d proper motion in Dec (dDec/dt, rad/Jyear) + + Called: slDSC6, slDAVM, slDMXV, slDIMV, slDVXV, + slDC6S + + Notes: + + 1) The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt, and are per year rather than per century. + + 2) The FK5 to Hipparcos transformation consists of a pure + rotation and spin; zonal errors in the FK5 catalogue are + not taken into account. + + 3) The published orientation and spin components are interpreted + as "axial vectors". An axial vector points at the pole of the + rotation and its length is the amount of rotation in radians. + + 4) See also slFK5H, slF5HZ, slHF5Z. + + Reference: + + M.Feissel & F.Mignard, Astron. Astrophys. 331, L33-L36 (1998). + + P.T.Wallace Starlink 7 October 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/hfk5z.hlp b/math/slalib/doc/hfk5z.hlp new file mode 100644 index 00000000..a2bea786 --- /dev/null +++ b/math/slalib/doc/hfk5z.hlp @@ -0,0 +1,60 @@ +.help hfk5z Jun99 "Slalib Package" +.nf + + SUBROUTINE slHF5Z (RH,DH,EPOCH,R5,D5,DR5,DD5) + + - - - - - - + H F 5 Z + - - - - - - + + Transform a Hipparcos star position into FK5 J2000, assuming + zero Hipparcos proper motion. + + (double precision) + + Given: + RH d Hipparcos RA (radians) + DH d Hipparcos Dec (radians) + EPOCH d Julian epoch (TDB) + + Returned (all FK5, equinox J2000, epoch EPOCH): + R5 d RA (radians) + D5 d Dec (radians) + + Called: slDS2C, slDAVM, slDMXV, slDAVM, slDMXM, + slDIMV, slDVXV, slDC6S + + Notes: + + 1) The proper motion in RA is dRA/dt rather than cos(Dec)*dRA/dt. + + 2) The FK5 to Hipparcos transformation consists of a pure + rotation and spin; zonal errors in the FK5 catalogue are + not taken into account. + + 3) The published orientation and spin components are interpreted + as "axial vectors". An axial vector points at the pole of the + rotation and its length is the amount of rotation in radians. + + 4) It was the intention that Hipparcos should be a close + approximation to an inertial frame, so that distant objects + have zero proper motion; such objects have (in general) + non-zero proper motion in FK5, and this routine returns those + fictitious proper motions. + + 5) The position returned by this routine is in the FK5 J2000 + reference frame but at Julian epoch EPOCH. + + 6) See also slFK5H, slHFK5, slF5HZ. + + Reference: + + M.Feissel & F.Mignard, Astron. Astrophys. 331, L33-L36 (1998). + + P.T.Wallace Starlink 7 October 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/imxv.hlp b/math/slalib/doc/imxv.hlp new file mode 100644 index 00000000..025c7122 --- /dev/null +++ b/math/slalib/doc/imxv.hlp @@ -0,0 +1,32 @@ +.help imxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slIMXV (RM, VA, VB) + + - - - - - + I M X V + - - - - - + + Performs the 3-D backward unitary transformation: + + vector VB = (inverse of matrix RM) * vector VA + + (single precision) + + (n.b. the matrix must be unitary, as this routine assumes that + the inverse and transpose are identical) + + Given: + RM real(3,3) matrix + VA real(3) vector + + Returned: + VB real(3) result vector + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/intin.hlp b/math/slalib/doc/intin.hlp new file mode 100644 index 00000000..f0b0c8ee --- /dev/null +++ b/math/slalib/doc/intin.hlp @@ -0,0 +1,90 @@ +.help intin Jun99 "Slalib Package" +.nf + + SUBROUTINE slINTI (STRING, NSTRT, IRESLT, JFLAG) + + - - - - - - + I N T I + - - - - - - + + Convert free-format input into an integer + + Given: + STRING c string containing number to be decoded + NSTRT i pointer to where decoding is to start + IRESLT i current value of result + + Returned: + NSTRT i advanced to next number + IRESLT i result + JFLAG i status: -1 = -OK, 0 = +OK, 1 = null, 2 = error + + Called: slICHI + + Notes: + + 1 The reason INTIN has separate OK status values for + + and - is to enable minus zero to be detected. This is + of crucial importance when decoding mixed-radix numbers. + For example, an angle expressed as deg, arcmin, arcsec + may have a leading minus sign but a zero degrees field. + + 2 A TAB is interpreted as a space. + + 3 The basic format is the sequence of fields #^, where + # is a sign character + or -, and ^ means a string of + decimal digits. + + 4 Spaces: + + . Leading spaces are ignored. + + . Spaces between the sign and the number are allowed. + + . Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + + 5 Delimiters: + + . Any character other than +,-,0-9 or space may be + used to signal the end of the number and terminate + decoding. + + . Comma is recognized by INTIN as a special case; it + is skipped, leaving the pointer on the next character. + See 9, below. + + 6 The sign is optional. The default is +. + + 7 A "null result" occurs when the string of characters being + decoded does not begin with +,- or 0-9, or consists + entirely of spaces. When this condition is detected, JFLAG + is set to 1 and IRESLT is left untouched. + + 8 NSTRT = 1 for the first character in the string. + + 9 On return from INTIN, NSTRT is set ready for the next + decode - following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to INTIN, otherwise + all subsequent calls will return a null result. + + 10 Errors (JFLAG=2) occur when: + + . there is a + or - but no number; or + + . the number is greater than BIG (defined below). + + 11 When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. + + 12 See also FLOTIN and DFLTIN. + + P.T.Wallace Starlink 27 April 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/invf.hlp b/math/slalib/doc/invf.hlp new file mode 100644 index 00000000..e1d8588e --- /dev/null +++ b/math/slalib/doc/invf.hlp @@ -0,0 +1,66 @@ +.help invf Jun99 "Slalib Package" +.nf + + SUBROUTINE slINVF (FWDS,BKWDS,J) + + - - - - - + I N V F + - - - - - + + Invert a linear model of the type produced by the + slFTXY routine. + + Given: + FWDS d(6) model coefficients + + Returned: + BKWDS d(6) inverse model + J i status: 0 = OK, -1 = no inverse + + The models relate two sets of [X,Y] coordinates as follows. + Naming the elements of FWDS: + + FWDS(1) = A + FWDS(2) = B + FWDS(3) = C + FWDS(4) = D + FWDS(5) = E + FWDS(6) = F + + where two sets of coordinates [X1,Y1] and [X2,Y1] are related + thus: + + X2 = A + B*X1 + C*Y1 + Y2 = D + E*X1 + F*Y1 + + the present routine generates a new set of coefficients: + + BKWDS(1) = P + BKWDS(2) = Q + BKWDS(3) = R + BKWDS(4) = S + BKWDS(5) = T + BKWDS(6) = U + + such that: + + X1 = P + Q*X2 + R*Y2 + Y1 = S + T*X2 + U*Y2 + + Two successive calls to slINVF will thus deliver a set + of coefficients equal to the starting values. + + To comply with the ANSI Fortran standard, FWDS and BKWDS must + not be the same array, even though the routine is coded to + work on the VAX and most other computers even if this rule + is violated. + + See also slFTXY, slPXY, slXYXY, slDCMF + + P.T.Wallace Starlink 11 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/kbj.hlp b/math/slalib/doc/kbj.hlp new file mode 100644 index 00000000..519868a7 --- /dev/null +++ b/math/slalib/doc/kbj.hlp @@ -0,0 +1,28 @@ +.help kbj Jun99 "Slalib Package" +.nf + + SUBROUTINE slKBJ (JB, E, K, J) + + - - - - + K B J + - - - - + + Select epoch prefix 'B' or 'J' + + Given: + JB int slDBJI prefix status: 0=none, 1='B', 2='J' + E dp epoch - Besselian or Julian + + Returned: + K char 'B' or 'J' + J int status: 0=OK + + If JB=0, B is assumed for E < 1984D0, otherwise J. + + P.T.Wallace Starlink 31 July 1989 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/m2av.hlp b/math/slalib/doc/m2av.hlp new file mode 100644 index 00000000..51d04343 --- /dev/null +++ b/math/slalib/doc/m2av.hlp @@ -0,0 +1,38 @@ +.help m2av Jun99 "Slalib Package" +.nf + + SUBROUTINE slM2AV (RMAT, AXVEC) + + - - - - - + M 2 A V + - - - - - + + From a rotation matrix, determine the corresponding axial vector + (single precision) + + A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the Euler axis, and the angle through which the + reference frame rotates is called the Euler angle. The axial + vector returned by this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. (The + magnitude and direction can be separated by means of the routine + slVN.) + + Given: + RMAT r(3,3) rotation matrix + + Returned: + AXVEC r(3) axial vector (radians) + + The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + + If RMAT is null, so is the result. + + P.T.Wallace Starlink 11 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/map.hlp b/math/slalib/doc/map.hlp new file mode 100644 index 00000000..4a66189b --- /dev/null +++ b/math/slalib/doc/map.hlp @@ -0,0 +1,65 @@ +.help map Jun99 "Slalib Package" +.nf + + SUBROUTINE slMAP (RM, DM, PR, PD, PX, RV, EQ, DATE, RA, DA) + + - - - - + M A P + - - - - + + Transform star RA,Dec from mean place to geocentric apparent + + The reference frames and timescales used are post IAU 1976. + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Given: + RM,DM dp mean RA,Dec (rad) + PR,PD dp proper motions: RA,Dec changes per Julian year + PX dp parallax (arcsec) + RV dp radial velocity (km/sec, +ve if receding) + EQ dp epoch and equinox of star data (Julian) + DATE dp TDB for apparent place (JD-2400000.5) + + Returned: + RA,DA dp apparent RA,Dec (rad) + + Called: + slMAPA star-independent parameters + slMAPQ quick mean to apparent + + Notes: + + 1) EQ is the Julian epoch specifying both the reference + frame and the epoch of the position - usually 2000. + For positions where the epoch and equinox are + different, use the routine slPM to apply proper + motion corrections before using this routine. + + 2) The distinction between the required TDB and TT is + always negligible. Moreover, for all but the most + critical applications UTC is adequate. + + 3) The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt. + + 4) This routine may be wasteful for some applications + because it recomputes the Earth position/velocity and + the precession/nutation matrix each time, and because + it allows for parallax and proper motion. Where + multiple transformations are to be carried out for one + epoch, a faster method is to call the slMAPA routine + once and then either the slMAPQ routine (which includes + parallax and proper motion) or slMAPZ (which assumes + zero parallax and proper motion). + + P.T.Wallace Starlink 19 January 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/mappa.hlp b/math/slalib/doc/mappa.hlp new file mode 100644 index 00000000..7a2bf727 --- /dev/null +++ b/math/slalib/doc/mappa.hlp @@ -0,0 +1,69 @@ +.help mappa Jun99 "Slalib Package" +.nf + + SUBROUTINE slMAPA (EQ, DATE, AMPRMS) + + - - - - - - + M A P A + - - - - - - + + Compute star-independent parameters in preparation for + conversions between mean place and geocentric apparent place. + + The parameters produced by this routine are required in the + parallax, light deflection, aberration, and precession/nutation + parts of the mean/apparent transformations. + + The reference frames and timescales used are post IAU 1976. + + Given: + EQ d epoch of mean equinox to be used (Julian) + DATE d TDB (JD-2400000.5) + + Returned: + AMPRMS d(21) star-independent mean-to-apparent parameters: + + (1) time interval for proper motion (Julian years) + (2-4) barycentric position of the Earth (AU) + (5-7) heliocentric direction of the Earth (unit vector) + (8) (grav rad Sun)*2/(Sun-Earth distance) + (9-11) ABV: barycentric Earth velocity in units of c + (12) sqrt(1-v**2) where v=modulus(ABV) + (13-21) precession/nutation (3,3) matrix + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Notes: + + 1) For DATE, the distinction between the required TDB and TT + is always negligible. Moreover, for all but the most + critical applications UTC is adequate. + + 2) The accuracy of the routines using the parameters AMPRMS is + limited by the routine slEVP, used here to compute the + Earth position and velocity by the methods of Stumpff. + The maximum error in the resulting aberration corrections is + about 0.3 milliarcsecond. + + 3) The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to + the mean equinox and equator of epoch EQ. + + 4) The parameters AMPRMS produced by this routine are used by + slMAPQ and slMAPZ. + + Called: + slEPJ MDJ to Julian epoch + slEVP earth position & velocity + slDVN normalize vector + slPRNU precession/nutation matrix + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/mapqk.hlp b/math/slalib/doc/mapqk.hlp new file mode 100644 index 00000000..adfa1f3d --- /dev/null +++ b/math/slalib/doc/mapqk.hlp @@ -0,0 +1,76 @@ +.help mapqk Jun99 "Slalib Package" +.nf + + SUBROUTINE slMAPQ (RM, DM, PR, PD, PX, RV, AMPRMS, RA, DA) + + - - - - - - + M A P Q + - - - - - - + + Quick mean to apparent place: transform a star RA,Dec from + mean place to geocentric apparent place, given the + star-independent parameters. + + Use of this routine is appropriate when efficiency is important + and where many star positions, all referred to the same equator + and equinox, are to be transformed for one epoch. The + star-independent parameters can be obtained by calling the + slMAPA routine. + + If the parallax and proper motions are zero the slMAPZ + routine can be used instead. + + The reference frames and timescales used are post IAU 1976. + + Given: + RM,DM d mean RA,Dec (rad) + PR,PD d proper motions: RA,Dec changes per Julian year + PX d parallax (arcsec) + RV d radial velocity (km/sec, +ve if receding) + + AMPRMS d(21) star-independent mean-to-apparent parameters: + + (1) time interval for proper motion (Julian years) + (2-4) barycentric position of the Earth (AU) + (5-7) heliocentric direction of the Earth (unit vector) + (8) (grav rad Sun)*2/(Sun-Earth distance) + (9-11) barycentric Earth velocity in units of c + (12) sqrt(1-v**2) where v=modulus(ABV) + (13-21) precession/nutation (3,3) matrix + + Returned: + RA,DA d apparent RA,Dec (rad) + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Notes: + + 1) The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to + the mean equinox and equator of epoch EQ. + + 2) Strictly speaking, the routine is not valid for solar-system + sources, though the error will usually be extremely small. + However, to prevent gross errors in the case where the + position of the Sun is specified, the gravitational + deflection term is restrained within about 920 arcsec of the + centre of the Sun's disc. The term has a maximum value of + about 1.85 arcsec at this radius, and decreases to zero as + the centre of the disc is approached. + + Called: + slDS2C spherical to Cartesian + slDVDV dot product + slDMXV matrix x vector + slDC2S Cartesian to spherical + slDA2P normalize angle 0-2Pi + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/mapqkz.hlp b/math/slalib/doc/mapqkz.hlp new file mode 100644 index 00000000..2ca9b493 --- /dev/null +++ b/math/slalib/doc/mapqkz.hlp @@ -0,0 +1,68 @@ +.help mapqkz Jun99 "Slalib Package" +.nf + + SUBROUTINE slMAPZ (RM, DM, AMPRMS, RA, DA) + + - - - - - - - + M A P Z + - - - - - - - + + Quick mean to apparent place: transform a star RA,Dec from + mean place to geocentric apparent place, given the + star-independent parameters, and assuming zero parallax + and proper motion. + + Use of this routine is appropriate when efficiency is important + and where many star positions, all with parallax and proper + motion either zero or already allowed for, and all referred to + the same equator and equinox, are to be transformed for one + epoch. The star-independent parameters can be obtained by + calling the slMAPA routine. + + The corresponding routine for the case of non-zero parallax + and proper motion is slMAPQ. + + The reference frames and timescales used are post IAU 1976. + + Given: + RM,DM d mean RA,Dec (rad) + AMPRMS d(21) star-independent mean-to-apparent parameters: + + (1-4) not used + (5-7) heliocentric direction of the Earth (unit vector) + (8) (grav rad Sun)*2/(Sun-Earth distance) + (9-11) ABV: barycentric Earth velocity in units of c + (12) sqrt(1-v**2) where v=modulus(ABV) + (13-21) precession/nutation (3,3) matrix + + Returned: + RA,DA d apparent RA,Dec (rad) + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Notes: + + 1) The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to the + mean equinox and equator of epoch EQ. + + 2) Strictly speaking, the routine is not valid for solar-system + sources, though the error will usually be extremely small. + However, to prevent gross errors in the case where the + position of the Sun is specified, the gravitational + deflection term is restrained within about 920 arcsec of the + centre of the Sun's disc. The term has a maximum value of + about 1.85 arcsec at this radius, and decreases to zero as + the centre of the disc is approached. + + Called: slDS2C, slDVDV, slDMXV, slDC2S, slDA2P + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/moon.hlp b/math/slalib/doc/moon.hlp new file mode 100644 index 00000000..403984eb --- /dev/null +++ b/math/slalib/doc/moon.hlp @@ -0,0 +1,59 @@ +.help moon Jun99 "Slalib Package" +.nf + + SUBROUTINE slMOON (IY, ID, FD, PV) + + - - - - - + M O O N + - - - - - + + Approximate geocentric position and velocity of the Moon + (single precision). + + Given: + IY i year + ID i day in year (1 = Jan 1st) + FD r fraction of day + + Returned: + PV r(6) Moon position & velocity vector + + Notes: + + 1 The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900 March 1 to 2100 February 28. + The year and day can be obtained by calling slCAYD or + slCLYD. + + 2 The Moon 6-vector is Moon centre relative to Earth centre, + mean equator and equinox of date. Position part, PV(1-3), + is in AU; velocity part, PV(4-6), is in AU/sec. + + 3 The position is accurate to better than 0.5 arcminute + in direction and 1000 km in distance. The velocity + is accurate to better than 0.5"/hour in direction and + 4 m/s in distance. (RMS figures with respect to JPL DE200 + for the interval 1960-2025 are 14 arcsec and 0.2 arcsec/hour in + longitude, 9 arcsec and 0.2 arcsec/hour in latitude, 350 km and + 2 m/s in distance.) Note that the distance accuracy is + comparatively poor because this routine is principally intended + for computing topocentric direction. + + 4 This routine is only a partial implementation of the original + Meeus algorithm (reference below), which offers 4 times the + accuracy in direction and 30 times the accuracy in distance + when fully implemented (as it is in slDMON). + + Reference: + Meeus, l'Astronomie, June 1984, p348. + + Called: slS2C6 + + P.T.Wallace Starlink 8 December 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/mxm.hlp b/math/slalib/doc/mxm.hlp new file mode 100644 index 00000000..7ee561e4 --- /dev/null +++ b/math/slalib/doc/mxm.hlp @@ -0,0 +1,33 @@ +.help mxm Jun99 "Slalib Package" +.nf + + SUBROUTINE slMXM (A, B, C) + + - - - - + M X M + - - - - + + Product of two 3x3 matrices: + matrix C = matrix A x matrix B + + (single precision) + + Given: + A real(3,3) matrix + B real(3,3) matrix + + Returned: + C real(3,3) matrix result + + To comply with the ANSI Fortran 77 standard, A, B and C must + be different arrays. However, the routine is coded so as to + work properly on the VAX and many other systems even if this + rule is violated. + + P.T.Wallace Starlink 5 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/mxv.hlp b/math/slalib/doc/mxv.hlp new file mode 100644 index 00000000..bacba504 --- /dev/null +++ b/math/slalib/doc/mxv.hlp @@ -0,0 +1,29 @@ +.help mxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slMXV (RM, VA, VB) + + - - - - + M X V + - - - - + + Performs the 3-D forward unitary transformation: + + vector VB = matrix RM * vector VA + + (single precision) + + Given: + RM real(3,3) matrix + VA real(3) vector + + Returned: + VB real(3) result vector + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/nut.hlp b/math/slalib/doc/nut.hlp new file mode 100644 index 00000000..95ea2ff0 --- /dev/null +++ b/math/slalib/doc/nut.hlp @@ -0,0 +1,34 @@ +.help nut Jun99 "Slalib Package" +.nf + + SUBROUTINE slNUT (DATE, RMATN) + + - - - - + N U T + - - - - + + Form the matrix of nutation for a given date - IAU 1980 theory + (double precision) + + References: + Final report of the IAU Working Group on Nutation, + chairman P.K.Seidelmann, 1980. + Kaplan,G.H., 1981, USNO circular no. 163, pA3-6. + + Given: + DATE dp TDB (loosely ET) as Modified Julian Date + (=JD-2400000.5) + Returned: + RMATN dp(3,3) nutation matrix + + The matrix is in the sense V(true) = RMATN * V(mean) + + Called: slNUTC, slDEUL + + P.T.Wallace Starlink 1 January 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/nutc.hlp b/math/slalib/doc/nutc.hlp new file mode 100644 index 00000000..b028219d --- /dev/null +++ b/math/slalib/doc/nutc.hlp @@ -0,0 +1,33 @@ +.help nutc Jun99 "Slalib Package" +.nf + + SUBROUTINE slNUTC (DATE, DPSI, DEPS, EPS0) + + - - - - - + N U T C + - - - - - + + Nutation: longitude & obliquity components and mean + obliquity - IAU 1980 theory (double precision) + + Given: + + DATE dp TDB (loosely ET) as Modified Julian Date + (JD-2400000.5) + Returned: + + DPSI,DEPS dp nutation in longitude,obliquity + EPS0 dp mean obliquity + + References: + Final report of the IAU Working Group on Nutation, + chairman P.K.Seidelmann, 1980. + Kaplan,G.H., 1981, USNO circular no. 163, pA3-6. + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/oap.hlp b/math/slalib/doc/oap.hlp new file mode 100644 index 00000000..7322c0ee --- /dev/null +++ b/math/slalib/doc/oap.hlp @@ -0,0 +1,163 @@ +.help oap Jun99 "Slalib Package" +.nf + + SUBROUTINE slOAP (TYPE, OB1, OB2, DATE, DUT, ELONGM, PHIM, + : HM, XP, YP, TDK, PMB, RH, WL, TLR, + : RAP, DAP) + + - - - - + O A P + - - - - + + Observed to apparent place + + Given: + TYPE c*(*) type of coordinates - 'R', 'H' or 'A' (see below) + OB1 d observed Az, HA or RA (radians; Az is N=0,E=90) + OB2 d observed ZD or Dec (radians) + DATE d UTC date/time (modified Julian Date, JD-2400000.5) + DUT d delta UT: UT1-UTC (UTC seconds) + ELONGM d mean longitude of the observer (radians, east +ve) + PHIM d mean geodetic latitude of the observer (radians) + HM d observer's height above sea level (metres) + XP d polar motion x-coordinate (radians) + YP d polar motion y-coordinate (radians) + TDK d local ambient temperature (DegK; std=273.155D0) + PMB d local atmospheric pressure (mB; std=1013.25D0) + RH d local relative humidity (in the range 0D0-1D0) + WL d effective wavelength (micron, e.g. 0.55D0) + TLR d tropospheric lapse rate (DegK/metre, e.g. 0.0065D0) + + Returned: + RAP d geocentric apparent right ascension + DAP d geocentric apparent declination + + Notes: + + 1) Only the first character of the TYPE argument is significant. + 'R' or 'r' indicates that OBS1 and OBS2 are the observed Right + Ascension and Declination; 'H' or 'h' indicates that they are + Hour Angle (West +ve) and Declination; anything else ('A' or + 'a' is recommended) indicates that OBS1 and OBS2 are Azimuth + (North zero, East is 90 deg) and zenith distance. (Zenith + distance is used rather than elevation in order to reflect the + fact that no allowance is made for depression of the horizon.) + + 2) The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted apparent RA,Dec should be within about 0.1 arcsec + for a zenith distance of less than 70 degrees. Even at a + topocentric zenith distance of 90 degrees, the accuracy in + elevation should be better than 1 arcmin; useful results + are available for a further 3 degrees, beyond which the + slRFRO routine returns a fixed value of the refraction. + The complementary routines slAOP (or slAOPQ) and slOAP + (or slOAPQ) are self-consistent to better than 1 micro- + arcsecond all over the celestial sphere. + + 3) It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + + 4) "Observed" Az,El means the position that would be seen by a + perfect theodolite located at the observer. This is + related to the observed HA,Dec via the standard rotation, using + the geodetic latitude (corrected for polar motion), while the + observed HA and RA are related simply through the local + apparent ST. "Observed" RA,Dec or HA,Dec thus means the + position that would be seen by a perfect equatorial located + at the observer and with its polar axis aligned to the + Earth's axis of rotation (n.b. not to the refracted pole). + By removing from the observed place the effects of + atmospheric refraction and diurnal aberration, the + geocentric apparent RA,Dec is obtained. + + 5) Frequently, mean rather than apparent RA,Dec will be required, + in which case further transformations will be necessary. The + slAMP etc routines will convert the apparent RA,Dec produced + by the present routine into an "FK5" (J2000) mean place, by + allowing for the Sun's gravitational lens effect, annual + aberration, nutation and precession. Should "FK4" (1950) + coordinates be needed, the routines slFK54 etc will also + need to be applied. + + 6) To convert to apparent RA,Dec the coordinates read from a + real telescope, corrections would have to be applied for + encoder zero points, gear and encoder errors, tube flexure, + the position of the rotator axis and the pointing axis + relative to it, non-perpendicularity between the mounting + axes, and finally for the tilt of the azimuth or polar axis + of the mounting (with appropriate corrections for mount + flexures). Some telescopes would, of course, exhibit other + properties which would need to be accounted for at the + appropriate point in the sequence. + + 7) The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the slAOPA routine. + If nothing has changed significantly except the time, the + slAOPT routine may be used to perform the requisite + partial recomputation of AOPRMS. + + 8) The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, wrong, because of leap seconds. However, + as long as the delta UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap delta UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the delta UTC changes by one second to its post-leap new value. + + 9) The delta UT (UT1-UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep delta UT + within +/- 0.9 seconds. + + 10) IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. + The longitude required by the present routine is east-positive, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + slOBS routine are west-positive, following astronomical + usage, and must be reversed in sign before use in the present + routine. + + 11) The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The maximum amplitude + is about 0.3 arcseconds. If XP,YP values are unavailable, + use XP=YP=0D0. See page B60 of the 1988 Astronomical Almanac + for a definition of the two angles. + + 12) The height above sea level of the observing station, HM, + can be obtained from the Astronomical Almanac (Section J + in the 1988 edition), or via the routine slOBS. If P, + the pressure in millibars, is available, an adequate + estimate of HM can be obtained from the expression + + HM ~ -29.3D0*TSL*LOG(P/1013.25D0). + + where TSL is the approximate sea-level air temperature in + deg K (see Astrophysical Quantities, C.W.Allen, 3rd edition, + section 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + + P ~ 1013.25D0*EXP(-HM/(29.3D0*TSL)). + + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + + 13) The azimuths etc used by the present routine are with respect + to the celestial pole. Corrections from the terrestrial pole + can be computed using slPLMO. + + Called: slAOPA, slOAPQ + + P.T.Wallace Starlink 9 June 1998 + + Copyright (C) 1998 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/oapqk.hlp b/math/slalib/doc/oapqk.hlp new file mode 100644 index 00000000..70a37f86 --- /dev/null +++ b/math/slalib/doc/oapqk.hlp @@ -0,0 +1,114 @@ +.help oapqk Jun99 "Slalib Package" +.nf + + SUBROUTINE slOAPQ (TYPE, OB1, OB2, AOPRMS, RAP, DAP) + + - - - - - - + O A P Q + - - - - - - + + Quick observed to apparent place + + Given: + TYPE c*(*) type of coordinates - 'R', 'H' or 'A' (see below) + OB1 d observed Az, HA or RA (radians; Az is N=0,E=90) + OB2 d observed ZD or Dec (radians) + AOPRMS d(14) star-independent apparent-to-observed parameters: + + (1) geodetic latitude (radians) + (2,3) sine and cosine of geodetic latitude + (4) magnitude of diurnal aberration vector + (5) height (HM) + (6) ambient temperature (T) + (7) pressure (P) + (8) relative humidity (RH) + (9) wavelength (WL) + (10) lapse rate (TLR) + (11,12) refraction constants A and B (radians) + (13) longitude + eqn of equinoxes + sidereal DUT (radians) + (14) local apparent sidereal time (radians) + + Returned: + RAP d geocentric apparent right ascension + DAP d geocentric apparent declination + + Notes: + + 1) Only the first character of the TYPE argument is significant. + 'R' or 'r' indicates that OBS1 and OBS2 are the observed Right + Ascension and Declination; 'H' or 'h' indicates that they are + Hour Angle (West +ve) and Declination; anything else ('A' or + 'a' is recommended) indicates that OBS1 and OBS2 are Azimuth + (North zero, East is 90 deg) and zenith distance. (Zenith + distance is used rather than elevation in order to reflect the + fact that no allowance is made for depression of the horizon.) + + 2) The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted apparent RA,Dec should be within about 0.1 arcsec + for a zenith distance of less than 70 degrees. Even at a + topocentric zenith distance of 90 degrees, the accuracy in + elevation should be better than 1 arcmin; useful results + are available for a further 3 degrees, beyond which the + slRFRO routine returns a fixed value of the refraction. + The complementary routines slAOP (or slAOPQ) and slOAP + (or slOAPQ) are self-consistent to better than 1 micro- + arcsecond all over the celestial sphere. + + 3) It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + + 5) "Observed" Az,El means the position that would be seen by a + perfect theodolite located at the observer. This is + related to the observed HA,Dec via the standard rotation, using + the geodetic latitude (corrected for polar motion), while the + observed HA and RA are related simply through the local + apparent ST. "Observed" RA,Dec or HA,Dec thus means the + position that would be seen by a perfect equatorial located + at the observer and with its polar axis aligned to the + Earth's axis of rotation (n.b. not to the refracted pole). + By removing from the observed place the effects of + atmospheric refraction and diurnal aberration, the + geocentric apparent RA,Dec is obtained. + + 5) Frequently, mean rather than apparent RA,Dec will be required, + in which case further transformations will be necessary. The + slAMP etc routines will convert the apparent RA,Dec produced + by the present routine into an "FK5" (J2000) mean place, by + allowing for the Sun's gravitational lens effect, annual + aberration, nutation and precession. Should "FK4" (1950) + coordinates be needed, the routines slFK54 etc will also + need to be applied. + + 6) To convert to apparent RA,Dec the coordinates read from a + real telescope, corrections would have to be applied for + encoder zero points, gear and encoder errors, tube flexure, + the position of the rotator axis and the pointing axis + relative to it, non-perpendicularity between the mounting + axes, and finally for the tilt of the azimuth or polar axis + of the mounting (with appropriate corrections for mount + flexures). Some telescopes would, of course, exhibit other + properties which would need to be accounted for at the + appropriate point in the sequence. + + 7) The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the slAOPA routine. + If nothing has changed significantly except the time, the + slAOPT routine may be used to perform the requisite + partial recomputation of AOPRMS. + + 8) The azimuths etc used by the present routine are with respect + to the celestial pole. Corrections from the terrestrial pole + can be computed using slPLMO. + + Called: slDS2C, slDC2S, slRFRO, slDA2P + + P.T.Wallace Starlink 23 June 1997 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/obs.hlp b/math/slalib/doc/obs.hlp new file mode 100644 index 00000000..bce6404e --- /dev/null +++ b/math/slalib/doc/obs.hlp @@ -0,0 +1,83 @@ +.help obs Jun99 "Slalib Package" +.nf + + SUBROUTINE slOBS (N, C, NAME, W, P, H) + + - - - - + O B S + - - - - + + Parameters of selected groundbased observing stations + + Given: + N int number specifying observing station + + Either given or returned + C c*(*) identifier specifying observing station + + Returned: + NAME c*(*) name of specified observing station + W dp longitude (radians, West +ve) + P dp geodetic latitude (radians, North +ve) + H dp height above sea level (metres) + + Notes: + + Station identifiers C may be up to 10 characters long, + and station names NAME may be up to 40 characters long. + + C and N are alternative ways of specifying the observing + station. The C option, which is the most generally useful, + may be selected by specifying an N value of zero or less. + If N is 1 or more, the parameters of the Nth station + in the currently supported list are interrogated, and + the station identifier C is returned as well as NAME, W, + P and H. + + If the station parameters are not available, either because + the station identifier C is not recognized, or because an + N value greater than the number of stations supported is + given, a name of '?' is returned and C, W, P and H are left + in their current states. + + Programs can obtain a list of all currently supported + stations by calling the routine repeatedly, with N=1,2,3... + When NAME='?' is seen, the list of stations has been + exhausted. + + Station numbers, identifiers, names and other details are + subject to change and should not be hardwired into + application programs. + + All station identifiers C are uppercase only; lowercase + characters must be converted to uppercase by the calling + program. The station names returned may contain both upper- + and lowercase. All characters up to the first space are + checked; thus an abbreviated ID will return the parameters + for the first station in the list which matches the + abbreviation supplied, and no station in the list will ever + contain embedded spaces. C must not have leading spaces. + + IMPORTANT -- BEWARE OF THE LONGITUDE SIGN CONVENTION. The + longitude returned by slOBS is west-positive in accordance + with astronomical usage. However, this sign convention is + left-handed and is the opposite of the one used by geographers; + elsewhere in SLALIB the preferable east-positive convention is + used. In particular, note that for use in slAOP, slAOPA + and slOAP the sign of the longitude must be reversed. + + Users are urged to inform the author of any improvements + they would like to see made. For example: + + typographical corrections + more accurate parameters + better station identifiers or names + additional stations + + P.T.Wallace Starlink 21 April 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pa.hlp b/math/slalib/doc/pa.hlp new file mode 100644 index 00000000..a7ee7357 --- /dev/null +++ b/math/slalib/doc/pa.hlp @@ -0,0 +1,36 @@ +.help pa Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slPA (HA, DEC, PHI) + + - - - + P A + - - - + + HA, Dec to Parallactic Angle (double precision) + + Given: + HA d hour angle in radians (geocentric apparent) + DEC d declination in radians (geocentric apparent) + PHI d observatory latitude in radians (geodetic) + + The result is in the range -pi to +pi + + Notes: + + 1) The parallactic angle at a point in the sky is the position + angle of the vertical, i.e. the angle between the direction to + the pole and to the zenith. In precise applications care must + be taken only to use geocentric apparent HA,Dec and to consider + separately the effects of atmospheric refraction and telescope + mount errors. + + 2) At the pole a zero result is returned. + + P.T.Wallace Starlink 16 August 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pav.hlp b/math/slalib/doc/pav.hlp new file mode 100644 index 00000000..a74d3ca3 --- /dev/null +++ b/math/slalib/doc/pav.hlp @@ -0,0 +1,40 @@ +.help pav Jun99 "Slalib Package" +.nf + + REAL FUNCTION slPAV ( V1, V2 ) + + - - - - + P A V + - - - - + + Position angle of one celestial direction with respect to another. + + (single precision) + + Given: + V1 r(3) direction cosines of one point + V2 r(3) direction cosines of the other point + + (The coordinate frames correspond to RA,Dec, Long,Lat etc.) + + The result is the bearing (position angle), in radians, of point + V2 with respect to point V1. It is in the range +/- pi. The + sense is such that if V2 is a small distance east of V1, the + bearing is about +pi/2. Zero is returned if the two points + are coincident. + + V1 and V2 do not have to be unit vectors. + + The routine slBEAR performs an equivalent function except + that the points are specified in the form of spherical + coordinates. + + Called: slDPAV + + Patrick Wallace Starlink 23 May 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pcd.hlp b/math/slalib/doc/pcd.hlp new file mode 100644 index 00000000..dd6263a4 --- /dev/null +++ b/math/slalib/doc/pcd.hlp @@ -0,0 +1,51 @@ +.help pcd Jun99 "Slalib Package" +.nf + + SUBROUTINE slPCD (DISCO,X,Y) + + - - - - + P C D + - - - - + + Apply pincushion/barrel distortion to a tangent-plane [x,y]. + + Given: + DISCO d pincushion/barrel distortion coefficient + X,Y d tangent-plane coordinates + + Returned: + X,Y d distorted coordinates + + Notes: + + 1) The distortion is of the form RP = R*(1 + C*R**2), where R is + the radial distance from the tangent point, C is the DISCO + argument, and RP is the radial distance in the presence of + the distortion. + + 2) For pincushion distortion, C is +ve; for barrel distortion, + C is -ve. + + 3) For X,Y in units of one projection radius (in the case of + a photographic plate, the focal length), the following + DISCO values apply: + + Geometry DISCO + + astrograph 0.0 + Schmidt -0.3333 + AAT PF doublet +147.069 + AAT PF triplet +178.585 + AAT f/8 +21.20 + JKT f/8 +13.32 + + 4) There is a companion routine, slUPCD, which performs + an approximately inverse operation. + + P.T.Wallace Starlink 31 December 1992 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pda2h.hlp b/math/slalib/doc/pda2h.hlp new file mode 100644 index 00000000..6a5a7dc4 --- /dev/null +++ b/math/slalib/doc/pda2h.hlp @@ -0,0 +1,33 @@ +.help pda2h Jun99 "Slalib Package" +.nf + + SUBROUTINE slPDAH (P, D, A, H1, J1, H2, J2) + + - - - - - - + P D A H + - - - - - - + + Hour Angle corresponding to a given azimuth + + (double precision) + + Given: + P d latitude + D d declination + A d azimuth + + Returned: + H1 d hour angle: first solution if any + J1 i flag: 0 = solution 1 is valid + H2 d hour angle: second solution if any + J2 i flag: 0 = solution 2 is valid + + Called: slDA1P + + P.T.Wallace Starlink 6 October 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pdq2h.hlp b/math/slalib/doc/pdq2h.hlp new file mode 100644 index 00000000..cdb0702f --- /dev/null +++ b/math/slalib/doc/pdq2h.hlp @@ -0,0 +1,33 @@ +.help pdq2h Jun99 "Slalib Package" +.nf + + SUBROUTINE slPDQH (P, D, Q, H1, J1, H2, J2) + + - - - - - - + P D Q H + - - - - - - + + Hour Angle corresponding to a given parallactic angle + + (double precision) + + Given: + P d latitude + D d declination + Q d parallactic angle + + Returned: + H1 d hour angle: first solution if any + J1 i flag: 0 = solution 1 is valid + H2 d hour angle: second solution if any + J2 i flag: 0 = solution 2 is valid + + Called: slDA1P + + P.T.Wallace Starlink 6 October 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pertel.hlp b/math/slalib/doc/pertel.hlp new file mode 100644 index 00000000..c1685eca --- /dev/null +++ b/math/slalib/doc/pertel.hlp @@ -0,0 +1,121 @@ +.help pertel Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRTL (JFORM, DATE0, DATE1, + : EPOCH0, ORBI0, ANODE0, PERIH0, AORQ0, E0, AM0, + : EPOCH1, ORBI1, ANODE1, PERIH1, AORQ1, E1, AM1, + : JSTAT) + + - - - - - - - + P R T L + - - - - - - - + + Update the osculating orbital elements of an asteroid or comet by + applying planetary perturbations. + + Given (format and dates): + JFORM i choice of element set (2 or 3; Note 1) + DATE0 d date of osculation (TT MJD) for the given elements + DATE1 d date of osculation (TT MJD) for the updated elements + + Given (the unperturbed elements): + EPOCH0 d epoch (TT MJD) of the given element set (Note 2) + ORBI0 d inclination (radians) + ANODE0 d longitude of the ascending node (radians) + PERIH0 d argument of perihelion (radians) + AORQ0 d mean distance or perihelion distance (AU) + E0 d eccentricity + AM0 d mean anomaly (radians, JFORM=2 only) + + Returned (the updated elements): + EPOCH1 d epoch (TT MJD) of the updated element set (Note 2) + ORBI1 d inclination (radians) + ANODE1 d longitude of the ascending node (radians) + PERIH1 d argument of perihelion (radians) + AORQ1 d mean distance or perihelion distance (AU) + E1 d eccentricity + AM1 d mean anomaly (radians, JFORM=2 only) + + Returned (status flag): + JSTAT i status: +102 = warning, distant epoch + +101 = warning, large timespan ( > 100 years) + +1 to +8 = coincident with major planet (Note 6) + 0 = OK + -1 = illegal JFORM + -2 = illegal E0 + -3 = illegal AORQ0 + -4 = internal error + -5 = numerical error + + Notes: + + 1 Two different element-format options are available: + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBI = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AM = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBI = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e + + 2 DATE0, DATE1, EPOCH0 and EPOCH1 are all instants of time in + the TT timescale (formerly Ephemeris Time, ET), expressed + as Modified Julian Dates (JD-2400000.5). + + DATE0 is the instant at which the given (i.e. unperturbed) + osculating elements are correct. + + DATE1 is the specified instant at which the updated osculating + elements are correct. + + EPOCH0 and EPOCH1 will be the same as DATE0 and DATE1 + (respectively) for the JFORM=2 case, normally used for minor + planets. For the JFORM=3 case, the two epochs will refer to + perihelion passage and so will not, in general, be the same as + DATE0 and/or DATE1 though they may be similar to one another. + + 3 The elements are with respect to the J2000 ecliptic and equinox. + + 4 Unused elements (AM0 and AM1 for JFORM=3) are not accessed. + + 5 See the slPRTE routine for details of the algorithm used. + + 6 This routine is not intended to be used for major planets, which + is why JFORM=1 is not available and why there is no opportunity + to specify either the longitude of perihelion or the daily + motion. However, if JFORM=2 elements are somehow obtained for a + major planet and supplied to the routine, sensible results will, + in fact, be produced. This happens because the slPRTE routine + that is called to perform the calculations checks the separation + between the body and each of the planets and interprets a + suspiciously small value (0.001 AU) as an attempt to apply it to + the planet concerned. If this condition is detected, the + contribution from that planet is ignored, and the status is set to + the planet number (Mercury=1,...,Neptune=8) as a warning. + + Reference: + + Sterne, Theodore E., "An Introduction to Celestial Mechanics", + Interscience Publishers Inc., 1960. Section 6.7, p199. + + Called: slELUE, slPRTE, slUEEL + + P.T.Wallace Starlink 14 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pertue.hlp b/math/slalib/doc/pertue.hlp new file mode 100644 index 00000000..4f5cf166 --- /dev/null +++ b/math/slalib/doc/pertue.hlp @@ -0,0 +1,152 @@ +.help pertue Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRTE (DATE, U, JSTAT) + + - - - - - - - + P R T E + - - - - - - - + + Update the universal elements of an asteroid or comet by applying + planetary perturbations. + + Given: + DATE d final epoch (TT MJD) for the updated elements + + Given and returned: + U d(13) universal elements (updated in place) + + (1) combined mass (M+m) + (2) total energy of the orbit (alpha) + (3) reference (osculating) epoch (t0) + (4-6) position at reference epoch (r0) + (7-9) velocity at reference epoch (v0) + (10) heliocentric distance at reference epoch + (11) r0.v0 + (12) date (t) + (13) universal eccentric anomaly (psi) of date, approx + + Returned: + JSTAT i status: + +102 = warning, distant epoch + +101 = warning, large timespan ( > 100 years) + +1 to +8 = coincident with major planet (Note 5) + 0 = OK + -1 = numerical error + + Called: slPLNT, slUEPV, slPVUE + + Notes: + + 1 The "universal" elements are those which define the orbit for the + purposes of the method of universal variables (see reference 2). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i) alpha, which is proportional to the total energy of the + orbit, (ii) the heliocentric distance at epoch, (iii) the + outwards component of the velocity at the given epoch, (iv) an + estimate of psi, the "universal eccentric anomaly" at a given + date and (v) that date. + + 2 The universal elements are with respect to the J2000 equator and + equinox. + + 3 The epochs DATE, U(3) and U(12) are all Modified Julian Dates + (JD-2400000.5). + + 4 The algorithm is a simplified form of Encke's method. It takes as + a basis the unperturbed motion of the body, and numerically + integrates the perturbing accelerations from the major planets. + The expression used is essentially Sterne's 6.7-2 (reference 1). + Everhart and Pitkin (reference 2) suggest rectifying the orbit at + each integration step by propagating the new perturbed position + and velocity as the new universal variables. In the present + routine the orbit is rectified less frequently than this, in order + to gain a slight speed advantage. However, the rectification is + done directly in terms of position and velocity, as suggested by + Everhart and Pitkin, bypassing the use of conventional orbital + elements. + + The f(q) part of the full Encke method is not used. The purpose + of this part is to avoid subtracting two nearly equal quantities + when calculating the "indirect member", which takes account of the + small change in the Sun's attraction due to the slightly displaced + position of the perturbed body. A simpler, direct calculation in + double precision proves to be faster and not significantly less + accurate. + + Apart from employing a variable timestep, and occasionally + "rectifying the orbit" to keep the indirect member small, the + integration is done in a fairly straightforward way. The + acceleration estimated for the middle of the timestep is assumed + to apply throughout that timestep; it is also used in the + extrapolation of the perturbations to the middle of the next + timestep, to predict the new disturbed position. There is no + iteration within a timestep. + + Measures are taken to reach a compromise between execution time + and accuracy. The starting-point is the goal of achieving + arcsecond accuracy for ordinary minor planets over a ten-year + timespan. This goal dictates how large the timesteps can be, + which in turn dictates how frequently the unperturbed motion has + to be recalculated from the osculating elements. + + Within predetermined limits, the timestep for the numerical + integration is varied in length in inverse proportion to the + magnitude of the net acceleration on the body from the major + planets. + + The numerical integration requires estimates of the major-planet + motions. Approximate positions for the major planets (Pluto + alone is omitted) are obtained from the routine slPLNT. Two + levels of interpolation are used, to enhance speed without + significantly degrading accuracy. At a low frequency, the routine + slPLNT is called to generate updated position+velocity "state + vectors". The only task remaining to be carried out at the full + frequency (i.e. at each integration step) is to use the state + vectors to extrapolate the planetary positions. In place of a + strictly linear extrapolation, some allowance is made for the + curvature of the orbit by scaling back the radius vector as the + linear extrapolation goes off at a tangent. + + Various other approximations are made. For example, perturbations + by Pluto and the minor planets are neglected, relativistic effects + are not taken into account and the Earth-Moon system is treated as + a single body. + + In the interests of simplicity, the background calculations for + the major planets are carried out en masse. The mean elements and + state vectors for all the planets are refreshed at the same time, + without regard for orbit curvature, mass or proximity. + + 5 This routine is not intended to be used for major planets. + However, if major-planet elements are supplied, sensible results + will, in fact, be produced. This happens because the routine + checks the separation between the body and each of the planets and + interprets a suspiciously small value (0.001 AU) as an attempt to + apply the routine to the planet concerned. If this condition is + detected, the contribution from that planet is ignored, and the + status is set to the planet number (Mercury=1,...,Neptune=8) as a + warning. + + References: + + 1 Sterne, Theodore E., "An Introduction to Celestial Mechanics", + Interscience Publishers Inc., 1960. Section 6.7, p199. + + 2 Everhart, E. & Pitkin, E.T., Am.J.Phys. 51, 712, 1983. + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp + +.fi +.endhelp diff --git a/math/slalib/doc/planel.hlp b/math/slalib/doc/planel.hlp new file mode 100644 index 00000000..c5a0f02f --- /dev/null +++ b/math/slalib/doc/planel.hlp @@ -0,0 +1,96 @@ +.help planel Jun99 "Slalib Package" +.nf + + SUBROUTINE slPLNE (DATE, JFORM, EPOCH, ORBINC, ANODE, PERIH, + : AORQ, E, AORL, DM, PV, JSTAT) + + - - - - - - - + P L N L + - - - - - - - + + Heliocentric position and velocity of a planet, asteroid or comet, + starting from orbital elements. + + Given: + DATE d date, Modified Julian Date (JD - 2400000.5) + JFORM i choice of element set (1-3; Note 3) + EPOCH d epoch of elements (TT MJD) + ORBINC d inclination (radians) + ANODE d longitude of the ascending node (radians) + PERIH d longitude or argument of perihelion (radians) + AORQ d mean distance or perihelion distance (AU) + E d eccentricity + AORL d mean anomaly or longitude (radians, JFORM=1,2 only) + DM d daily motion (radians, JFORM=1 only) + + Returned: + PV d(6) heliocentric x,y,z,xdot,ydot,zdot of date, + J2000 equatorial triad (AU,AU/s) + JSTAT i status: 0 = OK + -1 = illegal JFORM + -2 = illegal E + -3 = illegal AORQ + -4 = illegal DM + -5 = numerical error + + Called: slELUE, slUEPV + + Notes + + 1 DATE is the instant for which the prediction is required. It is + in the TT timescale (formerly Ephemeris Time, ET) and is a + Modified Julian Date (JD-2400000.5). + + 2 The elements are with respect to the J2000 ecliptic and equinox. + + 3 Three different element-format options are available: + + Option JFORM=1, suitable for the major planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = longitude of perihelion, curly pi (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e (range 0 to <1) + AORL = mean longitude L (radians) + DM = daily motion (radians) + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e (range 0 to <1) + AORL = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e (range 0 to 10) + + 4 Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + + 5 The reference frame for the result is with respect to the mean + equator and equinox of epoch J2000. + + 6 The algorithm was originally adapted from the EPHSLA program of + D.H.P.Jones (private communication, 1996). The method is based + on Stumpff's Universal Variables. + + Reference: Everhart, E. & Pitkin, E.T., Am.J.Phys. 51, 712, 1983. + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/planet.hlp b/math/slalib/doc/planet.hlp new file mode 100644 index 00000000..3bdb7b9f --- /dev/null +++ b/math/slalib/doc/planet.hlp @@ -0,0 +1,130 @@ +.help planet Jun99 "Slalib Package" +.nf + + SUBROUTINE slPLNT (DATE, NP, PV, JSTAT) + + - - - - - - - + P L N T + - - - - - - - + + Approximate heliocentric position and velocity of a specified + major planet. + + Given: + DATE d Modified Julian Date (JD - 2400000.5) + NP i planet (1=Mercury, 2=Venus, 3=EMB ... 9=Pluto) + + Returned: + PV d(6) heliocentric x,y,z,xdot,ydot,zdot, J2000 + equatorial triad (AU,AU/s) + JSTAT i status: +1 = warning: date out of range + 0 = OK + -1 = illegal NP (outside 1-9) + -2 = solution didn't converge + + Called: slPLNE + + Notes + + 1 The epoch, DATE, is in the TDB timescale and is a Modified + Julian Date (JD-2400000.5). + + 2 The reference frame is equatorial and is with respect to the + mean equinox and ecliptic of epoch J2000. + + 3 If an NP value outside the range 1-9 is supplied, an error + status (JSTAT = -1) is returned and the PV vector set to zeroes. + + 4 The algorithm for obtaining the mean elements of the planets + from Mercury to Neptune is due to J.L. Simon, P. Bretagnon, + J. Chapront, M. Chapront-Touze, G. Francou and J. Laskar + (Bureau des Longitudes, Paris). The (completely different) + algorithm for calculating the ecliptic coordinates of Pluto + is by Meeus. + + 5 Comparisons of the present routine with the JPL DE200 ephemeris + give the following RMS errors over the interval 1960-2025: + + position (km) speed (metre/sec) + + Mercury 334 0.437 + Venus 1060 0.855 + EMB 2010 0.815 + Mars 7690 1.98 + Jupiter 71700 7.70 + Saturn 199000 19.4 + Uranus 564000 16.4 + Neptune 158000 14.4 + Pluto 36400 0.137 + + From comparisons with DE102, Simon et al quote the following + longitude accuracies over the interval 1800-2200: + + Mercury 4" + Venus 5" + EMB 6" + Mars 17" + Jupiter 71" + Saturn 81" + Uranus 86" + Neptune 11" + + In the case of Pluto, Meeus quotes an accuracy of 0.6 arcsec + in longitude and 0.2 arcsec in latitude for the period + 1885-2099. + + For all except Pluto, over the period 1000-3000 the accuracy + is better than 1.5 times that over 1800-2200. Outside the + period 1000-3000 the accuracy declines. For Pluto the + accuracy declines rapidly outside the period 1885-2099. + Outside these ranges (1885-2099 for Pluto, 1000-3000 for + the rest) a "date out of range" warning status (JSTAT=+1) + is returned. + + 6 The algorithms for (i) Mercury through Neptune and (ii) Pluto + are completely independent. In the Mercury through Neptune + case, the present SLALIB implementation differs from the + original Simon et al Fortran code in the following respects. + + * The date is supplied as a Modified Julian Date rather + than a Julian Date (MJD = JD - 2400000.5). + + * The result is returned only in equatorial Cartesian form; + the ecliptic longitude, latitude and radius vector are not + returned. + + * The velocity is in AU per second, not AU per day. + + * Different error/warning status values are used. + + * Kepler's equation is not solved inline. + + * Polynomials in T are nested to minimize rounding errors. + + * Explicit double-precision constants are used to avoid + mixed-mode expressions. + + * There are other, cosmetic, changes to comply with + Starlink/SLALIB style guidelines. + + None of the above changes affects the result significantly. + + 7 For NP=3 the result is for the Earth-Moon Barycentre. To + obtain the heliocentric position and velocity of the Earth, + either use the SLALIB routine slEVP or call slDMON and + subtract 0.012150581 times the geocentric Moon vector from + the EMB vector produced by the present routine. (The Moon + vector should be precessed to J2000 first, but this can + be omitted for modern epochs without introducing significant + inaccuracy.) + + References: Simon et al., Astron. Astrophys. 282, 663 (1994). + Meeus, Astronomical Algorithms, Willmann-Bell (1991). + + P.T.Wallace Starlink 27 May 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/plante.hlp b/math/slalib/doc/plante.hlp new file mode 100644 index 00000000..a801ca51 --- /dev/null +++ b/math/slalib/doc/plante.hlp @@ -0,0 +1,97 @@ +.help plante Jun99 "Slalib Package" +.nf + + SUBROUTINE slPLTE (DATE, ELONG, PHI, JFORM, EPOCH, + : ORBINC, ANODE, PERIH, AORQ, E, + : AORL, DM, RA, DEC, R, JSTAT) + + - - - - - - - + P L T E + - - - - - - - + + Topocentric apparent RA,Dec of a Solar-System object whose + heliocentric orbital elements are known. + + Given: + DATE d MJD of observation (JD - 2400000.5) + ELONG d observer's east longitude (radians) + PHI d observer's geodetic latitude (radians) + JFORM i choice of element set (1-3; Note 4) + EPOCH d epoch of elements (TT MJD) + ORBINC d inclination (radians) + ANODE d longitude of the ascending node (radians) + PERIH d longitude or argument of perihelion (radians) + AORQ d mean distance or perihelion distance (AU) + E d eccentricity + AORL d mean anomaly or longitude (radians, JFORM=1,2 only) + DM d daily motion (radians, JFORM=1 only ) + + Returned: + RA,DEC d RA, Dec (topocentric apparent, radians) + R d distance from observer (AU) + JSTAT i status: 0 = OK + -1 = illegal JFORM + -2 = illegal E + -3 = illegal AORQ + -4 = illegal DM + -5 = numerical error + + Notes: + + 1 DATE is the instant for which the prediction is required. It is + in the TT timescale (formerly Ephemeris Time, ET) and is a + Modified Julian Date (JD-2400000.5). + + 2 The longitude and latitude allow correction for geocentric + parallax. This is usually a small effect, but can become + important for Earth-crossing asteroids. Geocentric positions + can be generated by appropriate use of routines slEVP and + slPLNE. + + 3 The elements are with respect to the J2000 ecliptic and equinox. + + 4 Three different element-format options are available: + + Option JFORM=1, suitable for the major planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = longitude of perihelion, curly pi (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean longitude L (radians) + DM = daily motion (radians) + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e + + 5 Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + + Called: slGMST, slDT, slEPJ, slPVOB, slPRNU, + slPLNE, slDMXV, slDC2S, slDA2P + + P.T.Wallace Starlink 17 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pm.hlp b/math/slalib/doc/pm.hlp new file mode 100644 index 00000000..a6d755ff --- /dev/null +++ b/math/slalib/doc/pm.hlp @@ -0,0 +1,45 @@ +.help pm Jun99 "Slalib Package" +.nf + + SUBROUTINE slPM (R0, D0, PR, PD, PX, RV, EP0, EP1, R1, D1) + + - - - + P M + - - - + + Apply corrections for proper motion to a star RA,Dec + (double precision) + + References: + 1984 Astronomical Almanac, pp B39-B41. + (also Lederle & Schwan, Astron. Astrophys. 134, + 1-6, 1984) + + Given: + R0,D0 dp RA,Dec at epoch EP0 (rad) + PR,PD dp proper motions: RA,Dec changes per year of epoch + PX dp parallax (arcsec) + RV dp radial velocity (km/sec, +ve if receding) + EP0 dp start epoch in years (e.g. Julian epoch) + EP1 dp end epoch in years (same system as EP0) + + Returned: + R1,D1 dp RA,Dec at epoch EP1 (rad) + + Called: + slDS2C spherical to Cartesian + slDC2S Cartesian to spherical + slDA2P normalize angle 0-2Pi + + Note: + The proper motions in RA are dRA/dt rather than + cos(Dec)*dRA/dt, and are in the same coordinate + system as R0,D0. + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/polmo.hlp b/math/slalib/doc/polmo.hlp new file mode 100644 index 00000000..b3f68383 --- /dev/null +++ b/math/slalib/doc/polmo.hlp @@ -0,0 +1,87 @@ +.help polmo Jun99 "Slalib Package" +.nf + + SUBROUTINE slPLMO ( ELONGM, PHIM, XP, YP, ELONG, PHI, DAZ ) + + - - - - - - + P L M O + - - - - - - + + Polar motion: correct site longitude and latitude for polar + motion and calculate azimuth difference between celestial and + terrestrial poles. + + Given: + ELONGM d mean longitude of the observer (radians, east +ve) + PHIM d mean geodetic latitude of the observer (radians) + XP d polar motion x-coordinate (radians) + YP d polar motion y-coordinate (radians) + + Returned: + ELONG d true longitude of the observer (radians, east +ve) + PHI d true geodetic latitude of the observer (radians) + DAZ d azimuth correction (terrestrial-celestial, radians) + + Notes: + + 1) "Mean" longitude and latitude are the (fixed) values for the + site's location with respect to the IERS terrestrial reference + frame; the latitude is geodetic. TAKE CARE WITH THE LONGITUDE + SIGN CONVENTION. The longitudes used by the present routine + are east-positive, in accordance with geographical convention + (and right-handed). In particular, note that the longitudes + returned by the slOBS routine are west-positive, following + astronomical usage, and must be reversed in sign before use in + the present routine. + + 2) XP and YP are the (changing) coordinates of the Celestial + Ephemeris Pole with respect to the IERS Reference Pole. + XP is positive along the meridian at longitude 0 degrees, + and YP is positive along the meridian at longitude + 270 degrees (i.e. 90 degrees west). Values for XP,YP can + be obtained from IERS circulars and equivalent publications; + the maximum amplitude observed so far is about 0.3 arcseconds. + + 3) "True" longitude and latitude are the (moving) values for + the site's location with respect to the celestial ephemeris + pole and the meridian which corresponds to the Greenwich + apparent sidereal time. The true longitude and latitude + link the terrestrial coordinates with the standard celestial + models (for precession, nutation, sidereal time etc). + + 4) The azimuths produced by slAOP and slAOPQ are with + respect to due north as defined by the Celestial Ephemeris + Pole, and can therefore be called "celestial azimuths". + However, a telescope fixed to the Earth measures azimuth + essentially with respect to due north as defined by the + IERS Reference Pole, and can therefore be called "terrestrial + azimuth". Uncorrected, this would manifest itself as a + changing "azimuth zero-point error". The value DAZ is the + correction to be added to a celestial azimuth to produce + a terrestrial azimuth. + + 5) The present routine is rigorous. For most practical + purposes, the following simplified formulae provide an + adequate approximation: + + ELONG = ELONGM+XP*COS(ELONGM)-YP*SIN(ELONGM) + PHI = PHIM+(XP*SIN(ELONGM)+YP*COS(ELONGM))*TAN(PHIM) + DAZ = -SQRT(XP*XP+YP*YP)*COS(ELONGM-ATAN2(XP,YP))/COS(PHIM) + + An alternative formulation for DAZ is: + + X = COS(ELONGM)*COS(PHIM) + Y = SIN(ELONGM)*COS(PHIM) + DAZ = ATAN2(-X*YP-Y*XP,X*X+Y*Y) + + Reference: Seidelmann, P.K. (ed), 1992. "Explanatory Supplement + to the Astronomical Almanac", ISBN 0-935702-68-7, + sections 3.27, 4.25, 4.52. + + P.T.Wallace Starlink 22 February 1996 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/prebn.hlp b/math/slalib/doc/prebn.hlp new file mode 100644 index 00000000..e2c1991b --- /dev/null +++ b/math/slalib/doc/prebn.hlp @@ -0,0 +1,36 @@ +.help prebn Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRBN (BEP0, BEP1, RMATP) + + - - - - - - + P R B N + - - - - - - + + Generate the matrix of precession between two epochs, + using the old, pre-IAU1976, Bessel-Newcomb model, using + Kinoshita's formulation (double precision) + + Given: + BEP0 dp beginning Besselian epoch + BEP1 dp ending Besselian epoch + + Returned: + RMATP dp(3,3) precession matrix + + The matrix is in the sense V(BEP1) = RMATP * V(BEP0) + + Reference: + Kinoshita, H. (1975) 'Formulas for precession', SAO Special + Report No. 364, Smithsonian Institution Astrophysical + Observatory, Cambridge, Massachusetts. + + Called: slDEUL + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/prec.hlp b/math/slalib/doc/prec.hlp new file mode 100644 index 00000000..4b12d918 --- /dev/null +++ b/math/slalib/doc/prec.hlp @@ -0,0 +1,53 @@ +.help prec Jun99 "Slalib Package" +.nf + + SUBROUTINE slPREC (EP0, EP1, RMATP) + + - - - - - + P R E C + - - - - - + + Form the matrix of precession between two epochs (IAU 1976, FK5) + (double precision) + + Given: + EP0 dp beginning epoch + EP1 dp ending epoch + + Returned: + RMATP dp(3,3) precession matrix + + Notes: + + 1) The epochs are TDB (loosely ET) Julian epochs. + + 2) The matrix is in the sense V(EP1) = RMATP * V(EP0) + + 3) Though the matrix method itself is rigorous, the precession + angles are expressed through canonical polynomials which are + valid only for a limited time span. There are also known + errors in the IAU precession rate. The absolute accuracy + of the present formulation is better than 0.1 arcsec from + 1960AD to 2040AD, better than 1 arcsec from 1640AD to 2360AD, + and remains below 3 arcsec for the whole of the period + 500BC to 3000AD. The errors exceed 10 arcsec outside the + range 1200BC to 3900AD, exceed 100 arcsec outside 4200BC to + 5600AD and exceed 1000 arcsec outside 6800BC to 8200AD. + The SLALIB routine slPREL implements a more elaborate + model which is suitable for problems spanning several + thousand years. + + References: + Lieske,J.H., 1979. Astron.Astrophys.,73,282. + equations (6) & (7), p283. + Kaplan,G.H., 1981. USNO circular no. 163, pA2. + + Called: slDEUL + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/preces.hlp b/math/slalib/doc/preces.hlp new file mode 100644 index 00000000..7652ea8a --- /dev/null +++ b/math/slalib/doc/preces.hlp @@ -0,0 +1,47 @@ +.help preces Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRCE (SYSTEM, EP0, EP1, RA, DC) + + - - - - - - - + P R C E + - - - - - - - + + Precession - either FK4 (Bessel-Newcomb, pre IAU 1976) or + FK5 (Fricke, post IAU 1976) as required. + + Given: + SYSTEM char precession to be applied: 'FK4' or 'FK5' + EP0,EP1 dp starting and ending epoch + RA,DC dp RA,Dec, mean equator & equinox of epoch EP0 + + Returned: + RA,DC dp RA,Dec, mean equator & equinox of epoch EP1 + + Called: slDA2P, slPRBN, slPREC, slDS2C, + slDMXV, slDC2S + + Notes: + + 1) Lowercase characters in SYSTEM are acceptable. + + 2) The epochs are Besselian if SYSTEM='FK4' and Julian if 'FK5'. + For example, to precess coordinates in the old system from + equinox 1900.0 to 1950.0 the call would be: + CALL slPRCE ('FK4', 1900D0, 1950D0, RA, DC) + + 3) This routine will NOT correctly convert between the old and + the new systems - for example conversion from B1950 to J2000. + For these purposes see slFK45, slFK54, slF45Z and + slF54Z. + + 4) If an invalid SYSTEM is supplied, values of -99D0,-99D0 will + be returned for both RA and DC. + + P.T.Wallace Starlink 20 April 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/precl.hlp b/math/slalib/doc/precl.hlp new file mode 100644 index 00000000..b715172a --- /dev/null +++ b/math/slalib/doc/precl.hlp @@ -0,0 +1,47 @@ +.help precl Jun99 "Slalib Package" +.nf + + SUBROUTINE slPREL (EP0, EP1, RMATP) + + - - - - - - + P R E L + - - - - - - + + Form the matrix of precession between two epochs, using the + model of Simon et al (1994), which is suitable for long + periods of time. + + (double precision) + + Given: + EP0 dp beginning epoch + EP1 dp ending epoch + + Returned: + RMATP dp(3,3) precession matrix + + Notes: + + 1) The epochs are TDB Julian epochs. + + 2) The matrix is in the sense V(EP1) = RMATP * V(EP0) + + 3) The absolute accuracy of the model is limited by the + uncertainty in the general precession, about 0.3 arcsec per + 1000 years. The remainder of the formulation provides a + precision of 1 mas over the interval from 1000AD to 3000AD, + 0.1 arcsec from 1000BC to 5000AD and 1 arcsec from + 4000BC to 8000AD. + + Reference: + Simon, J.L. et al., 1994. Astron.Astrophys., 282, 663-683. + + Called: slDEUL + + P.T.Wallace Starlink 23 August 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/precss.hlp b/math/slalib/doc/precss.hlp new file mode 100644 index 00000000..ab244cf5 --- /dev/null +++ b/math/slalib/doc/precss.hlp @@ -0,0 +1,44 @@ +.help precss Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRCS (SYSTEM, EP0, EP1, RA, DC) + + - - - - - - - + P R C E + - - - - - - - + + Precession - either FK4 (Bessel-Newcomb, pre IAU 1976) or + FK5 (Fricke, post IAU 1976) as required. + + Given: + SYSTEM int precession to be applied: 1 = FK4 or 2 = FK5 + EP0,EP1 dp starting and ending epoch + RA,DC dp RA,Dec, mean equator & equinox of epoch EP0 + + Returned: + RA,DC dp RA,Dec, mean equator & equinox of epoch EP1 + + Called: slDA2P, slPRBN, slPREC, slDS2C, + slDMXV, slDC2S + + Notes: + + 1) Lowercase characters in SYSTEM are acceptable. + + 2) The epochs are Besselian if SYSTEM=FK4 and Julian if FK5. + For example, to precess coordinates in the old system from + equinox 1900.0 to 1950.0 the call would be: + CALL slPRCS (1, 1900D0, 1950D0, RA, DC) + + 3) This routine will NOT correctly convert between the old and + the new systems - for example conversion from B1950 to J2000. + For these purposes see slFK45, slFK54, slF45Z and + slF54Z. + + 4) If an invalid SYSTEM is supplied, values of -99D0,-99D0 will + be returned for both RA and DC. + + P.T.Wallace Starlink 20 April 1990 + +.fi +.endhelp diff --git a/math/slalib/doc/prenut.hlp b/math/slalib/doc/prenut.hlp new file mode 100644 index 00000000..bbe3ceff --- /dev/null +++ b/math/slalib/doc/prenut.hlp @@ -0,0 +1,35 @@ +.help prenut Jun99 "Slalib Package" +.nf + + SUBROUTINE slPRNU (EPOCH, DATE, RMATPN) + + - - - - - - - + P R N U + - - - - - - - + + Form the matrix of precession and nutation (IAU1976/FK5) + (double precision) + + Given: + EPOCH dp Julian Epoch for mean coordinates + DATE dp Modified Julian Date (JD-2400000.5) + for true coordinates + + Returned: + RMATPN dp(3,3) combined precession/nutation matrix + + Called: slPREC, slEPJ, slNUT, slDMXM + + Notes: + + 1) The epoch and date are TDB (loosely ET). + + 2) The matrix is in the sense V(true) = RMATPN * V(mean) + + P.T.Wallace Starlink April 1987 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pv2el.hlp b/math/slalib/doc/pv2el.hlp new file mode 100644 index 00000000..ef027a38 --- /dev/null +++ b/math/slalib/doc/pv2el.hlp @@ -0,0 +1,145 @@ +.help pv2el Jun99 "Slalib Package" +.nf + + SUBROUTINE slPVEL (PV, DATE, PMASS, JFORMR, + : JFORM, EPOCH, ORBINC, ANODE, PERIH, + : AORQ, E, AORL, DM, JSTAT) + + - - - - - - + P V E L + - - - - - - + + Heliocentric osculating elements obtained from instantaneous position + and velocity. + + Given: + PV d(6) heliocentric x,y,z,xdot,ydot,zdot of date, + J2000 equatorial triad (AU,AU/s; Note 1) + DATE d date (TT Modified Julian Date = JD-2400000.5) + PMASS d mass of the planet (Sun=1; Note 2) + JFORMR i requested element set (1-3; Note 3) + + Returned: + JFORM d element set actually returned (1-3; Note 4) + EPOCH d epoch of elements (TT MJD) + ORBINC d inclination (radians) + ANODE d longitude of the ascending node (radians) + PERIH d longitude or argument of perihelion (radians) + AORQ d mean distance or perihelion distance (AU) + E d eccentricity + AORL d mean anomaly or longitude (radians, JFORM=1,2 only) + DM d daily motion (radians, JFORM=1 only) + JSTAT i status: 0 = OK + -1 = illegal PMASS + -2 = illegal JFORMR + -3 = position/velocity out of range + + Notes + + 1 The PV 6-vector is with respect to the mean equator and equinox of + epoch J2000. The orbital elements produced are with respect to + the J2000 ecliptic and mean equinox. + + 2 The mass, PMASS, is important only for the larger planets. For + most purposes (e.g. asteroids) use 0D0. Values less than zero + are illegal. + + 3 Three different element-format options are supported: + + Option JFORM=1, suitable for the major planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = longitude of perihelion, curly pi (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean longitude L (radians) + DM = daily motion (radians) + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e + + 4 It may not be possible to generate elements in the form + requested through JFORMR. The caller is notified of the form + of elements actually returned by means of the JFORM argument: + + JFORMR JFORM meaning + + 1 1 OK - elements are in the requested format + 1 2 never happens + 1 3 orbit not elliptical + + 2 1 never happens + 2 2 OK - elements are in the requested format + 2 3 orbit not elliptical + + 3 1 never happens + 3 2 never happens + 3 3 OK - elements are in the requested format + + 5 The arguments returned for each value of JFORM (cf Note 5: JFORM + may not be the same as JFORMR) are as follows: + + JFORM 1 2 3 + EPOCH t0 t0 T + ORBINC i i i + ANODE Omega Omega Omega + PERIH curly pi omega omega + AORQ a a q + E e e e + AORL L M - + DM n - - + + where: + + t0 is the epoch of the elements (MJD, TT) + T " epoch of perihelion (MJD, TT) + i " inclination (radians) + Omega " longitude of the ascending node (radians) + curly pi " longitude of perihelion (radians) + omega " argument of perihelion (radians) + a " mean distance (AU) + q " perihelion distance (AU) + e " eccentricity + L " longitude (radians, 0-2pi) + M " mean anomaly (radians, 0-2pi) + n " daily motion (radians) + - means no value is set + + 6 At very small inclinations, the longitude of the ascending node + ANODE becomes indeterminate and under some circumstances may be + set arbitrarily to zero. Similarly, if the orbit is close to + circular, the true anomaly becomes indeterminate and under some + circumstances may be set arbitrarily to zero. In such cases, + the other elements are automatically adjusted to compensate, + and so the elements remain a valid description of the orbit. + + Reference: Sterne, Theodore E., "An Introduction to Celestial + Mechanics", Interscience Publishers, 1960 + + Called: slDA2P + + P.T.Wallace Starlink 13 February 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pv2ue.hlp b/math/slalib/doc/pv2ue.hlp new file mode 100644 index 00000000..776f877a --- /dev/null +++ b/math/slalib/doc/pv2ue.hlp @@ -0,0 +1,70 @@ +.help pv2ue Jun99 "Slalib Package" +.nf + + SUBROUTINE slPVUE (PV, DATE, PMASS, U, JSTAT) + + - - - - - - + P V U E + - - - - - - + + Construct a universal element set based on an instantaneous position + and velocity. + + Given: + PV d(6) heliocentric x,y,z,xdot,ydot,zdot of date, + (AU,AU/s; Note 1) + DATE d date (TT Modified Julian Date = JD-2400000.5) + PMASS d mass of the planet (Sun=1; Note 2) + + Returned: + U d(13) universal orbital elements (Note 3) + + (1) combined mass (M+m) + (2) total energy of the orbit (alpha) + (3) reference (osculating) epoch (t0) + (4-6) position at reference epoch (r0) + (7-9) velocity at reference epoch (v0) + (10) heliocentric distance at reference epoch + (11) r0.v0 + (12) date (t) + (13) universal eccentric anomaly (psi) of date, approx + + JSTAT i status: 0 = OK + -1 = illegal PMASS + -2 = too close to Sun + -3 = too slow + + Notes + + 1 The PV 6-vector can be with respect to any chosen inertial frame, + and the resulting universal-element set will be with respect to + the same frame. A common choice will be mean equator and ecliptic + of epoch J2000. + + 2 The mass, PMASS, is important only for the larger planets. For + most purposes (e.g. asteroids) use 0D0. Values less than zero + are illegal. + + 3 The "universal" elements are those which define the orbit for the + purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i) alpha, which is proportional to the total energy of the + orbit, (ii) the heliocentric distance at epoch, (iii) the + outwards component of the velocity at the given epoch, (iv) an + estimate of psi, the "universal eccentric anomaly" at a given + date and (v) that date. + + Reference: Everhart, E. & Pitkin, E.T., Am.J.Phys. 51, 712, 1983. + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pvobs.hlp b/math/slalib/doc/pvobs.hlp new file mode 100644 index 00000000..607d73a5 --- /dev/null +++ b/math/slalib/doc/pvobs.hlp @@ -0,0 +1,31 @@ +.help pvobs Jun99 "Slalib Package" +.nf + + SUBROUTINE slPVOB (P, H, STL, PV) + + - - - - - - + P V O B + - - - - - - + + Position and velocity of an observing station (double precision) + + Given: + P dp latitude (geodetic, radians) + H dp height above reference spheroid (geodetic, metres) + STL dp local apparent sidereal time (radians) + + Returned: + PV dp(6) position/velocity 6-vector (AU, AU/s, true equator + and equinox of date) + + Called: slGEOC + + IAU 1976 constants are used. + + P.T.Wallace Starlink 14 November 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/pxy.hlp b/math/slalib/doc/pxy.hlp new file mode 100644 index 00000000..e2764150 --- /dev/null +++ b/math/slalib/doc/pxy.hlp @@ -0,0 +1,56 @@ +.help pxy Jun99 "Slalib Package" +.nf + + SUBROUTINE slPXY (NP,XYE,XYM,COEFFS,XYP,XRMS,YRMS,RRMS) + + - - - - + P X Y + - - - - + + Given arrays of "expected" and "measured" [X,Y] coordinates, and a + linear model relating them (as produced by slFTXY), compute + the array of "predicted" coordinates and the RMS residuals. + + Given: + NP i number of samples + XYE d(2,np) expected [X,Y] for each sample + XYM d(2,np) measured [X,Y] for each sample + COEFFS d(6) coefficients of model (see below) + + Returned: + XYP d(2,np) predicted [X,Y] for each sample + XRMS d RMS in X + YRMS d RMS in Y + RRMS d total RMS (vector sum of XRMS and YRMS) + + The model is supplied in the array COEFFS. Naming the + elements of COEFF as follows: + + COEFFS(1) = A + COEFFS(2) = B + COEFFS(3) = C + COEFFS(4) = D + COEFFS(5) = E + COEFFS(6) = F + + the model is applied thus: + + XP = A + B*XM + C*YM + YP = D + E*XM + F*YM + + The residuals are (XP-XE) and (YP-YE). + + If NP is less than or equal to zero, no coordinates are + transformed, and the RMS residuals are all zero. + + See also slFTXY, slINVF, slXYXY, slDCMF + + Called: slXYXY + + P.T.Wallace Starlink 22 May 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/range.hlp b/math/slalib/doc/range.hlp new file mode 100644 index 00000000..b65a1a92 --- /dev/null +++ b/math/slalib/doc/range.hlp @@ -0,0 +1,24 @@ +.help range Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRA1P (ANGLE) + + - - - - - - + R A 1 P + - - - - - - + + Normalize angle into range +/- pi (single precision) + + Given: + ANGLE dp the angle in radians + + The result is ANGLE expressed in the +/- pi (single + precision). + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ranorm.hlp b/math/slalib/doc/ranorm.hlp new file mode 100644 index 00000000..5ee46937 --- /dev/null +++ b/math/slalib/doc/ranorm.hlp @@ -0,0 +1,24 @@ +.help ranorm Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRA2P (ANGLE) + + - - - - - - - + R A 2 P + - - - - - - - + + Normalize angle into range 0-2 pi (single precision) + + Given: + ANGLE dp the angle in radians + + The result is ANGLE expressed in the range 0-2 pi (single + precision). + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rcc.hlp b/math/slalib/doc/rcc.hlp new file mode 100644 index 00000000..fef7f578 --- /dev/null +++ b/math/slalib/doc/rcc.hlp @@ -0,0 +1,83 @@ +.help rcc Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slRCC (TDB, UT1, WL, U, V) + + - - - - + R C C + - - - - + + Relativistic clock correction: the difference between proper time at + a point on the surface of the Earth and coordinate time in the Solar + System barycentric space-time frame of reference. + + The proper time is Terrestrial Time TT; the coordinate + time is an implementation of the Barycentric Dynamical Time TDB. + + Given: + TDB dp coordinate time (MJD: JD-2400000.5) + UT1 dp universal time (fraction of one day) + WL dp clock longitude (radians west) + U dp clock distance from Earth spin axis (km) + V dp clock distance north of Earth equatorial plane (km) + + Returned: + The clock correction, TDB-TT, in seconds. TDB may be considered + to be the coordinate time in the Solar System barycentre frame of + reference, and TT is the proper time given by clocks at mean sea + level on the Earth. + + The result has a main (annual) sinusoidal term of amplitude + approximately 0.00166 seconds, plus planetary terms up to about + 20 microseconds, and lunar and diurnal terms up to 2 microseconds. + The variation arises from the transverse Doppler effect and the + gravitational red-shift as the observer varies in speed and moves + through different gravitational potentials. + + The argument TDB is, strictly, the barycentric coordinate time; + however, the terrestrial proper time (TT) can in practice be used. + + The geocentric model is that of Fairhead & Bretagnon (1990), in its + full form. It was supplied by Fairhead (private communication) as a + FORTRAN subroutine. The original Fairhead routine used explicit + formulae, in such large numbers that problems were experienced with + certain compilers (Microsoft Fortran on PC aborted with stack + overflow, Convex compiled successfully but extremely slowly). The + present implementation is a complete recoding, with the original + Fairhead coefficients held in a table. To optimize arithmetic + precision, the terms are accumulated in reverse order, smallest + first. A number of other coding changes were made, in order to match + the calling sequence of previous versions of the present routine, and + to comply with Starlink programming standards. Under VAX/VMS, the + numerical results compared with those from the Fairhead form are + essentially unaffected by the changes, the differences being at the + 10^-20 sec level. + + The topocentric part of the model is from Moyer (1981) and + Murray (1983). + + During the interval 1950-2050, the absolute accuracy is better + than +/- 3 nanoseconds relative to direct numerical integrations + using the JPL DE200/LE200 solar system ephemeris. + + The IAU definition of TDB is that it must differ from TT only by + periodic terms. Though practical, this is an imprecise definition + which ignores the existence of very long-period and secular effects + in the dynamics of the solar system. As a consequence, different + implementations of TDB will, in general, differ in zero-point and + will drift linearly relative to one other. + + References: + Bretagnon P, 1982 Astron. Astrophys., 114, 278-288. + Fairhead L & Bretagnon P, 1990, Astron. Astrophys., 229, 240-247. + Meeus J, 1984, l'Astronomie, 348-354. + Moyer T D, 1981, Cel. Mech., 23, 33. + Murray C A, 1983, Vectorial Astrometry, Adam Hilger. + + P.T.Wallace Starlink 10 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rdplan.hlp b/math/slalib/doc/rdplan.hlp new file mode 100644 index 00000000..5b9d560a --- /dev/null +++ b/math/slalib/doc/rdplan.hlp @@ -0,0 +1,73 @@ +.help rdplan Jun99 "Slalib Package" +.nf + + SUBROUTINE slRDPL (DATE, NP, ELONG, PHI, RA, DEC, DIAM) + + - - - - - - - + R D P L + - - - - - - - + + Approximate topocentric apparent RA,Dec of a planet, and its + angular diameter. + + Given: + DATE d MJD of observation (JD - 2400000.5) + NP i planet: 1 = Mercury + 2 = Venus + 3 = Moon + 4 = Mars + 5 = Jupiter + 6 = Saturn + 7 = Uranus + 8 = Neptune + 9 = Pluto + else = Sun + ELONG,PHI d observer's east longitude and geodetic + latitude (radians) + + Returned: + RA,DEC d RA, Dec (topocentric apparent, radians) + DIAM d angular diameter (equatorial, radians) + + Notes: + + 1 The date is in a dynamical timescale (TDB, formerly ET) and is + in the form of a Modified Julian Date (JD-2400000.5). For all + practical purposes, TT can be used instead of TDB, and for many + applications UT will do (except for the Moon). + + 2 The longitude and latitude allow correction for geocentric + parallax. This is a major effect for the Moon, but in the + context of the limited accuracy of the present routine its + effect on planetary positions is small (negligible for the + outer planets). Geocentric positions can be generated by + appropriate use of the routines slDMON and slPLNT. + + 3 The direction accuracy (arcsec, 1000-3000AD) is of order: + + Sun 5 + Mercury 2 + Venus 10 + Moon 30 + Mars 50 + Jupiter 90 + Saturn 90 + Uranus 90 + Neptune 10 + Pluto 1 (1885-2099AD only) + + The angular diameter accuracy is about 0.4% for the Moon, + and 0.01% or better for the Sun and planets. + + See the slPLNT routine for references. + + Called: slGMST, slDT, slEPJ, slDMON, slPVOB, slPRNU, + slPLNT, slDMXV, slDC2S, slDA2P + + P.T.Wallace Starlink 26 May 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/read.me b/math/slalib/doc/read.me new file mode 100644 index 00000000..e7f5f358 --- /dev/null +++ b/math/slalib/doc/read.me @@ -0,0 +1,437 @@ +READ.ME + +Revision date 31 May 1999 SLALIB Version 2.3-0 + +----------------------------------------------------------------------- + +FILES IN THE ORIGINAL SOURCE DIRECTORY (VAX) + + READ.ME this file + *.FOR Fortran source (separate modules) + *.OBS ditto, but obsolete routines + *.NEW ditto, but new and not yet ready for release + *.VAX Fortran source for VAX/VMS + *.CNVX Fortran source for Convex + *.MIPS Fortran source for DECstation + *.SUN4 Fortran source for Sun SPARCstation + *.LNX Fortran source for Linux + *.PCM Microsoft Fortran source for PC + *.C C functions needed for Linux version + PC.BAT rebuilds PC version + REP.BAT on PC, compiles one module and updates library + CREATE.COM complete rebuild of VAX and Unix releases + PUT.COM compile one module and update libraries + VAX_TO_UNIX.USH script to complete transfer to Unix platforms + SLA.NEWS NEWS item for latest release + MAKEFILE Unix make file + MK C-shell script to run make + SUN67.TEX document + +FILES IN [.RELEASE] DIRECTORY ON VAX + + SLALIB.OLB object library + SLALIB.TLB source library + SUN67.TEX document + +FILES IN [.UNIX] DIRECTORY ON VAX + + MAKEFILE make file for DECstation and Sun SPARC + MK C-shell script to run make + SLA.A archive file containing everything else + VAX_TO_UNIX script to complete transfer to Unix platforms + SLA.NEWS NEWS item for latest release + SUN67.TEX document + +FILES IN (INFORMAL) FTP DIRECTORIES + + The files distributed informally through anonymous FTP may differ + slightly in both content and name from the ones listed above. For + example the PC Fortran modules may be stored in archive files and + called xxx.f_pcm rather than XXX.PCM etc. + +----------------------------------------------------------------------- + +DISTRIBUTION - THIS DIRECTORY + + Nothing from this directory needs to be distributed. + +DISTRIBUTION - [.RELEASE] DIRECTORY + + SLALIB.* SLALIB_DIR + SLA.NEWS SLALIB_DIR + SUN67.TEX DOCSDIR + +INSTRUCTIONS FOR SAVING SPACE + + Extract from the SLALIB_DIR BACKUP save set only the file SLALIB.OLB. + +----------------------------------------------------------------------- + +PORTING FORTRAN SLALIB TO OTHER SYSTEMS + +FORTRAN SLALIB runs on VAX (VMS), PC (Linux+f2c), PC (Microsoft FORTRAN), +Convex (ConvexOS), DECstation (Ultrix), DEC Alpha (OSF-1) and Sun +SPARCstation (SunOS and Solaris). + +For most platforms, the required changes are confined to these routines: + + sla_GRESID + sla_RANDOM + sla_WAIT + +VAX, CONVEX, DECSTATION/ALPHA, SUN & PC + +Versions suitable for the above platforms are supplied in the +development directory as *.VAX, *,CNVX, *.MIPS, *.SUN4, *.PCM and +*.LNX respectively. + + +----------------------------------------------------------------------- + +LATEST RELEASE INFORMATION + +The latest release of SLALIB includes the following changes (most recent +at the end): + +* In sla_RCC, the topocentric term of coefficient 1.3184D-10 sec + had the wrong sign. Minus is correct. + +* The IAU decided in 1991 to rename the Terrestrial Dynamical + Time, TDT, which is now called "Terrestrial Time" or TT. + Appropriate changes have been made in the SLALIB documentation. + The same IAU resolutions introduced the timescales TCG and TCB; + there are at present no SLALIB routines to handle these new + timescales. + +* The Keck 1 Telescope has been added to sla_OBS. + +* The handling of the random-number seed in the PC versions of + sla_RANDOM and sla_GRESID was flawed and has been improved. + +* The UTC leap second at the end of June 1993 has been added to the + routine sla_DAT. Existing applications which call sla_DAT or + sla_DTT require relinking. + +* Some unnecessary code in sla_AMPQK has been removed. + +* Minor reorganization of the sla_REFRO code has led to an improvement + in speed of about 20%, and precautions have been taken against + potential arithmetic errors. + +* There have been small revisions to sla_FK425 and sla_FK524. The + results are not significantly affected, except in the pathological + case of large proper motion combined with immense distance, where + sla_FK524 could produce erroneous radial velocity values. The + latest versions are close to the algorithms published in the 1992 + Explanatory Supplement to the Astronomical Almanac. + +* The leap second at the end of June 1994 has been added to sla_DAT. + +* THE SLA_RVLSR ROUTINE HAS BEEN RETIRED. Its place has been taken + by two new routines: sla_RVLSRK and sla_RVLSRD. The original + sla_RVLSR had used a "kinematical" LSR. When this was later changed + to a "dynamical" LSR for (what seemed liked good reasons at the time), + the small differences were noticed by spectral-line radio observers, + who had to fall back on old copies of the routine to remain consistent + with existing practice. The new routines provide both sorts of LSR: + sla_RVLSRK uses a kinematical LSR and sla_RVLSRD uses the dynamical LSR. + +* The sla_PA routine (computation of parallactic angle) used an + unnecessarily complicated formulation, which has been simplified. + The results are unaffected. + +* The sla_ZD routine (computation of zenith distance) used a + straightforward cosine-formula-based method, which suffered from + decreased accuracy near the zenith. A better, vector-derived, + formulation has been substituted, without materially affecting + the results. Because sla_ZD is double precision, the old + formulation was always adequate; however, had anyone transcribed + the code in single precision errors approaching 1 arcmin could + have resulted. The new formulation delivers good results all + over the sky even in a single precision version. + +* Routines have been added to transform equatorial coordinates + (HA,Dec) to horizon coordinates (Az,El) and back. Single and + double precision are both supported. The routines are called + sla_E2H, sla_DE2H, sla_H2E, sla_DH2E. + +* A new routine has been added to the tangent-plane projection set. + The single and double precision versions are called sla_TPRD and + sla_DTPRD respectively. Given the RA,Dec of a star and its + xi,eta coordinates, the routine determines the "plate centre". + +* The existing routine sla_PREC for obtaining the precession matrix + uses the official IAU model and should continue to be used for + canonical purposes. A new version, called sla_PRECL, uses a + more up-to-date model which delivers better accuracy, especially + over intervals of millennia. + +* The routine sla_PVOBS was returning velocities in AU per sidereal + second rather than per UT second. This has been corrected. The + maximum error was equivalent to about 0.001 km/s. + +* In sla_MAPQK and sla_MAPQKZ, the area within which the gravitional + light-deflection term is restrained has been extended from its + original 300 arcsec radius to about 920 arcsec, just inside the + Sun's disc. + +* A chapter of explanation, with examples, has been added to SUN/67, + which has also undergone various cosmetic revisions. + +* There were two discrepancies between the documentation of sla_DCMPF + (program comments and SUN/67) and the code. The first was that the + formulae for the nonperpendicularity used PERP instead of PERP/2; + the documentation has been corrected. The other was that the + documentation showed the zero point corrections being applied first, + whereas the code returned zero point corrections corresponding to + being applied last. The code has been corrected to match the + documentation. + +* The C module slaCldj gave incorrect answers for dates during + January and February. The error, which did not affect the Fortran + version, has been corrected. + +* THE CALL FOR TPRD AND DTPRD HAS BEEN CHANGED. An integer status + argument has been added; non-zero means the supplied RA,Dec + and Xi,Eta describe an impossible case. (This can only happen + near the pole and with non-zero Xi.) Also, a slightly neater + formulation has been introduced. + +* Three new routines have been added. ALTAZ takes a star's HA,Dec + and produces position, velocity and acceleration for azimuth, + elevation and parallactic angle. PDA2H predicts the HA at which + a given azimuth will be reached. PDQ2H does the same for + position angle. + +* In the OBS routine, the wrong sign was returned for the Perkins + 72 inch telescope at Lowell - fixed. + +* A revised model for the equation of the equinoxes has been + installed in EQEQX, in line with recent IAU resolutions. The + change amounts to less than 3 mas. + +* A bug in DFLTIN has been corrected. A negative number following + an E- or D-format number without intervening spaces lost its + sign. + +* Four stations have been added to OBS: + + TAUTENBERG Tautenberg 1.34 metre Schmidt + PALOMAR48 Palomar 48-inch Schmidt + UKST UK 1.2 metre Schmidt, Siding Spring + KISO Kiso 1.05 metre Schmidt, Japan + ESOSCHMIDT ESO 1 metre Schmidt, La Silla + +* The EARTH and MOON routines could give an integer divide by zero + for years before 1 BC. This has been corrected. + +* CALYD (provided to support the EARTH and MOON routines) has been + upgraded to work outside the interval 1900 March 1 to + 2100 February 28. The status value indicating dates outside that + range has been dropped; a new error value for year before -4711 + has been introduced. + +* A new routine, CLYD, has been added. It is a version of CALYD + without the century-default feature and is to enable 1st-century + dates to be supplied to EARTH and MOON. + +* Two new routines, PLANETS and RDPLAN, have been added, which + compute approximate planetary ephemerides. + +* A new routine, DMOON, implements the same (Meeus) model as the + MOON routine, but in full and in double precision. The time + argument is a straightforward MJD rather than MOON's year and + day-in-year. + +* The REFRO code has been speeded up by a factor of two (and is + also clearer). + +* REFV and REFZ have, in different ways, been made more accurate for + cases close to the horizon. The improvement to REFV is relatively + modest, but REFZ is now capable of delivering useful results for + rise/set phenomena. + +* AOPQK has been speeded up for low-elevation cases. + +* Versions of the tangent-plane routines working directly in x,y,z + instead of spherical coordinates have been added. They may be + faster in some applications. The routines are DV2TP, V2TP, DTP2V, + TP2V, DTPXYZ, TPXYZ. + +* The coordinates of the Australia Telescope Compact Array have been + added to OBS. The name is 'ATCA'. + +* Despite their recent introduction THE ROUTINES DTPRD, DTPXYZ, TPRD + AND TPXYZ HAVE BEEN WITHDRAWN. They have been replaced by the new + routines DTPS2C, DTPV2C, TPS2C and TPV2C. These are functionally + equivalent to the earlier routines but return two solutions instead + of one: the second solution can arise near a pole. + +* The UTC leap second at the end of 1995 has been added to sla_DAT. + +* The refraction routine REFRO has been extensively revised. The + principal motivation was to improve the radio predictions by + introducing better humidity models. The models previously in + use had been entirely adequate for the optical case, for which + they had been devised, but improved models were required for + the radio case. None of the changes significantly affects the + optical results with respect to the earlier version of the REFRO + routine. For example, at 70 deg zenith distance the new version + agrees with the old version to better than 0.05 arcsec for any + reasonable combination of parameters. However, the improved + water-vapour expressions do make a significant difference in the + radio band, at 70 deg zenith distance reaching almost 4 arcsec + for a hot, humid, low-altitude site during a period of low pressure. + +* There was a bug in the (private) C version of RDPLAN. The + answers were unaffected but there could be floating-point + problems on some platforms. + +* A new routine has been added, GMSTA. This gives greater numerical + precision than the existing GMST function by allowing the date and + time to be specified separately rather than as a single MJD. + +* Measures taken in MAPQK to avoid trouble when processing Solar + positions had not been carried through into MAPQKZ. The two + routines now use the same strategy. + +* In REFRO, at zenith distances well beyond 90 deg and under some + conditions, it was possible to encounter arithmetic errors due to + failure of the tropospheric model-atmosphere to deliver sensible + temperatures. This is inherent in the published algorithm. To + avoid the problem, the temperature delivered by the model has been + constrained to the range 200 to 320 deg K. + +* A new routine has been added, ATMDSP, for rapidly recalculating + the A,B refraction coefficients for different wavelengths. + +* The first UTC leap-second date in the DAT routine was one day early. + This will have had no effect on the results for more recent epochs. + +* The C version of OBS had some problems related to character string + handling. A call using the "number" option retured an invalid + station ID, and station ID and name strings of the stipulated 10 + and 40 character lengths were improperly terminated. + +* A new routine, POLMO has been added. This is a specialist tool + to do with Earth polar motion. + +* DC62S and CC62S could give floating point errors if vectors in + unlikely units were supplied. The handling of difficult cases + has been improved. + +* Support for Linux has been added. + +* The C version of REFRO was not re-entrant. It is now; there has + been a small (4%) speed penalty. + +* RANDOM, GRESID and WAIT have been dropped from the C version. They + could not easily be made re-entrant and posed perennial platform- + dependency problems. + +* The value for the arcsec to radians factor in several routines + had an incorrect (and superfluous) 19th digit, which has been + removed. + +* There was a minor bug in DV2TP and V2TP, to do with protection + against the special case where the tangent point is the pole. + +* In OBS, the position of the Parkes radiotelescope has been revised, + and the ATNF Mopra observatory has been added. + +* Two new routines have been added. PAV (single precision) and DPAV + (double precision) are like BEAR and DBEAR but start with direction + cosines rather than spherical coordinates - they return the position + angle of one point with respect to the other. + +* The C version of REFRO still wasn't re-entrant, but is now. + +* The C version of DTF2D used to accept 60.0 in the seconds field; + this has been corrected. + +* The PLANET and RDPLAN routines now include Pluto. The ephemeris + is accurate (sub-arcsecond) but covers the 20th and 21st centuries + only. + + !!! IMPORTANT NOTE !!! + + RDPLAN used to interpret any planet number outside the range 1-8 + as meaning the Sun. The new version uses planet number 9. Existing + programs using 9 for the Sun should be changed to use 0. The rule + has not been changed, except that the range is now 1-9 instead of + 1-8, as it is unlikely that the equivalent problem will arise in the + future. + +* Two new routines have been added, PLANEL and PLANTE. They are + analogues of PLANET and RDPLAN but for the case where orbital + elements are available. They can be used for predicting the + positions of asteroids and comets, and, if up-to-date osculating + elements are supplied, more accurate positions for the major + planets than can be provided through the PLANET and RDPLAN + routines. + +* The REFRO routine could give inaccurate results for low temperatures + (subzero C). This was caused by over-cautious defensive programming, + which prevented the tropospheric temperature falling below 200 K. + +* A new routine has been added, REFCOQ. This calculates the coefficients + of a two-term refraction model. It complements the existing REFCO + routine, being much faster at the expense of some accuracy. + +* The 1997 July 1 UTC leap second has been added to the DAT routine. + +* A bug in the C version of SVD (slaSvd) caused occasional false + indications of ill-conditioning. The results of least-squares + fits do not seem to have been affected. The Fortran version + (sla_SVD) did not have the bug. + +* The Subaru telescope (Japanese National 8-metre telescope, Mauna Kea) + has been added to the OBS routine. + +* The DAT routine has been extended back to the inception of UTC in + 1960. + +* The "earliest date possible" in DJCL was two days out (disagreeing + with DJCAL, which had the correct value). + +* The GMSTA code has been improved. + +* A new routine, PV2EL, takes a heliocentric J2000 equatorial position + and velocity and produces the equivalent set of osculating elements. + +* The 1999 January 1 UTC leap second has been added to the DAT routine. + +* Four new routines have been introduced which transform between the + FK5 system and the ICRS (Hipparcos) system. FK52H and H2FK5 transform + star positions and proper motions from FK5 coordinates to Hipparcos + coordinates and vice versa. FK5HZ and HFK5Z do the same but for the + case where the Hipparcos proper motions are zero. + +* Six new routines have been introduced for dealing with orbital elements. + Four of them (sla_EL2UE, sla_PV2UE, sla_UE2EL and sla_UE2PV) provide + applications with direct access to the "universal variables" method + that was already being used internally. Compared with using conventional + (angular) elements and solving Kepler's equation, the universal variables + approach has a number of advantages, including better handling of near- + parabolic orbits and greater efficiency. The remaining two routines + (sla_PERTEL and sla_PERTUE) generate updated elements by applying + major-planet perturbations. The new elements can then be used to + predict positions that are much more accurate. For minor planets, + sub-arcsecond accuracy over a decade is achievable. + +* Several observatory sites have been added to the OBS routine: CFHT, + Keck 2, Gemini North, FCRAO, IRTF and CSO. The coordinates for all + the Mauna Kea sites have been updated in accordance with recent aerial + photography results made available by the Institute for Astronomy, + University of Hawaii. + +* A coding error in DAT produced incorrect results for dates in the + first 54 days of 1972. + +----------------------------------------------------------------------- + + + P.T.Wallace + + ptw@star.rl.ac.uk + +44-1235-44-5372 diff --git a/math/slalib/doc/refco.hlp b/math/slalib/doc/refco.hlp new file mode 100644 index 00000000..98be6d4c --- /dev/null +++ b/math/slalib/doc/refco.hlp @@ -0,0 +1,54 @@ +.help refco Jun99 "Slalib Package" +.nf + + SUBROUTINE slRFCO (HM, TDK, PMB, RH, WL, PHI, TLR, EPS, + : REFA, REFB) + + - - - - - - + R F C O + - - - - - - + + Determine the constants A and B in the atmospheric refraction + model dZ = A tan Z + B tan**3 Z. + + Z is the "observed" zenith distance (i.e. affected by refraction) + and dZ is what to add to Z to give the "topocentric" (i.e. in vacuo) + zenith distance. + + Given: + HM d height of the observer above sea level (metre) + TDK d ambient temperature at the observer (deg K) + PMB d pressure at the observer (millibar) + RH d relative humidity at the observer (range 0-1) + WL d effective wavelength of the source (micrometre) + PHI d latitude of the observer (radian, astronomical) + TLR d temperature lapse rate in the troposphere (degK/metre) + EPS d precision required to terminate iteration (radian) + + Returned: + REFA d tan Z coefficient (radian) + REFB d tan**3 Z coefficient (radian) + + Called: slRFRO + + Notes: + + 1 Typical values for the TLR and EPS arguments might be 0.0065D0 and + 1D-10 respectively. + + 2 The radio refraction is chosen by specifying WL > 100 micrometres. + + 3 The routine is a slower but more accurate alternative to the + slRFCQ routine. The constants it produces give perfect + agreement with slRFRO at zenith distances arctan(1) (45 deg) + and arctan(4) (about 76 deg). It achieves 0.5 arcsec accuracy + for ZD < 80 deg, 0.01 arcsec accuracy for ZD < 60 deg, and + 0.001 arcsec accuracy for ZD < 45 deg. + + P.T.Wallace Starlink 3 June 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/refcoq.hlp b/math/slalib/doc/refcoq.hlp new file mode 100644 index 00000000..153ed66e --- /dev/null +++ b/math/slalib/doc/refcoq.hlp @@ -0,0 +1,167 @@ +.help refcoq Jun99 "Slalib Package" +.nf + + SUBROUTINE slRFCQ (TDK, PMB, RH, WL, REFA, REFB) + + - - - - - - - + R F C Q + - - - - - - - + + Determine the constants A and B in the atmospheric refraction + model dZ = A tan Z + B tan**3 Z. This is a fast alternative + to the slRFCO routine - see notes. + + Z is the "observed" zenith distance (i.e. affected by refraction) + and dZ is what to add to Z to give the "topocentric" (i.e. in vacuo) + zenith distance. + + Given: + TDK d ambient temperature at the observer (deg K) + PMB d pressure at the observer (millibar) + RH d relative humidity at the observer (range 0-1) + WL d effective wavelength of the source (micrometre) + + Returned: + REFA d tan Z coefficient (radian) + REFB d tan**3 Z coefficient (radian) + + The radio refraction is chosen by specifying WL > 100 micrometres. + + Notes: + + 1 The model is an approximation, for moderate zenith distances, + to the predictions of the slRFRO routine. The approximation + is maintained across a range of conditions, and applies to + both optical/IR and radio. + + 2 The algorithm is a fast alternative to the slRFCO routine. + The latter calls the slRFRO routine itself: this involves + integrations through a model atmosphere, and is costly in + processor time. However, the model which is produced is precisely + correct for two zenith distance (45 degrees and about 76 degrees) + and at other zenith distances is limited in accuracy only by the + A tan Z + B tan**3 Z formulation itself. The present routine + is not as accurate, though it satisfies most practical + requirements. + + 3 The model omits the effects of (i) height above sea level (apart + from the reduced pressure itself), (ii) latitude (i.e. the + flattening of the Earth) and (iii) variations in tropospheric + lapse rate. + + The model was tested using the following range of conditions: + + lapse rates 0.0055, 0.0065, 0.0075 deg/metre + latitudes 0, 25, 50, 75 degrees + heights 0, 2500, 5000 metres ASL + pressures mean for height -10% to +5% in steps of 5% + temperatures -10 deg to +20 deg with respect to 280 deg at SL + relative humidity 0, 0.5, 1 + wavelengths 0.4, 0.6, ... 2 micron, + radio + zenith distances 15, 45, 75 degrees + + The accuracy with respect to direct use of the slRFRO routine + was as follows: + + worst RMS + + optical/IR 62 mas 8 mas + radio 319 mas 49 mas + + For this particular set of conditions: + + lapse rate 0.0065 degK/metre + latitude 50 degrees + sea level + pressure 1005 mB + temperature 280.15 degK + humidity 80% + wavelength 5740 Angstroms + + the results were as follows: + + ZD slRFRO slRFCQ Saastamoinen + + 10 10.27 10.27 10.27 + 20 21.19 21.20 21.19 + 30 33.61 33.61 33.60 + 40 48.82 48.83 48.81 + 45 58.16 58.18 58.16 + 50 69.28 69.30 69.27 + 55 82.97 82.99 82.95 + 60 100.51 100.54 100.50 + 65 124.23 124.26 124.20 + 70 158.63 158.68 158.61 + 72 177.32 177.37 177.31 + 74 200.35 200.38 200.32 + 76 229.45 229.43 229.42 + 78 267.44 267.29 267.41 + 80 319.13 318.55 319.10 + + deg arcsec arcsec arcsec + + The values for Saastamoinen's formula (which includes terms + up to tan^5) are taken from Hohenkerk and Sinclair (1985). + + The results from the much slower but more accurate slRFCO + routine have not been included in the tabulation as they are + identical to those in the slRFRO column to the 0.01 arcsec + resolution used. + + 4 Outlandish input parameters are silently limited to mathematically + safe values. Zero pressure is permissible, and causes zeroes to + be returned. + + 5 The algorithm draws on several sources, as follows: + + a) The formula for the saturation vapour pressure of water as + a function of temperature and temperature is taken from + expressions A4.5-A4.7 of Gill (1982). + + b) The formula for the water vapour pressure, given the + saturation pressure and the relative humidity, is from + Crane (1976), expression 2.5.5. + + c) The refractivity of air is a function of temperature, + total pressure, water-vapour pressure and, in the case + of optical/IR but not radio, wavelength. The formulae + for the two cases are developed from the Essen and Froome + expressions adopted in Resolution 1 of the 12th International + Geodesy Association General Assembly (1963). + + The above three items are as used in the slRFRO routine. + + d) The formula for beta, the ratio of the scale height of the + atmosphere to the geocentric distance of the observer, is + an adaption of expression 9 from Stone (1996). The + adaptations, arrived at empirically, consist of (i) a + small adjustment to the coefficient and (ii) a humidity + term for the radio case only. + + e) The formulae for the refraction constants as a function of + n-1 and beta are from Green (1987), expression 4.31. + + References: + + Crane, R.K., Meeks, M.L. (ed), "Refraction Effects in the Neutral + Atmosphere", Methods of Experimental Physics: Astrophysics 12B, + Academic Press, 1976. + + Gill, Adrian E., "Atmosphere-Ocean Dynamics", Academic Press, 1982. + + Hohenkerk, C.Y., & Sinclair, A.T., NAO Technical Note No. 63, 1985. + + International Geodesy Association General Assembly, Bulletin + Geodesique 70 p390, 1963. + + Stone, Ronald C., P.A.S.P. 108 1051-1058, 1996. + + Green, R.M., "Spherical Astronomy", Cambridge University Press, 1987. + + P.T.Wallace Starlink 4 June 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/refro.hlp b/math/slalib/doc/refro.hlp new file mode 100644 index 00000000..8b66c95d --- /dev/null +++ b/math/slalib/doc/refro.hlp @@ -0,0 +1,123 @@ +.help refro Jun99 "Slalib Package" +.nf + + SUBROUTINE slRFRO (ZOBS, HM, TDK, PMB, RH, WL, PHI, TLR, + : EPS, REF) + + - - - - - - + R F R O + - - - - - - + + Atmospheric refraction for radio and optical/IR wavelengths. + + Given: + ZOBS d observed zenith distance of the source (radian) + HM d height of the observer above sea level (metre) + TDK d ambient temperature at the observer (deg K) + PMB d pressure at the observer (millibar) + RH d relative humidity at the observer (range 0-1) + WL d effective wavelength of the source (micrometre) + PHI d latitude of the observer (radian, astronomical) + TLR d temperature lapse rate in the troposphere (degK/metre) + EPS d precision required to terminate iteration (radian) + + Returned: + REF d refraction: in vacuo ZD minus observed ZD (radian) + + Notes: + + 1 A suggested value for the TLR argument is 0.0065D0. The + refraction is significantly affected by TLR, and if studies + of the local atmosphere have been carried out a better TLR + value may be available. + + 2 A suggested value for the EPS argument is 1D-8. The result is + usually at least two orders of magnitude more computationally + precise than the supplied EPS value. + + 3 The routine computes the refraction for zenith distances up + to and a little beyond 90 deg using the method of Hohenkerk + and Sinclair (NAO Technical Notes 59 and 63, subsequently adopted + in the Explanatory Supplement, 1992 edition - see section 3.281). + + 4 The code is a development of the optical/IR refraction subroutine + AREF of C.Hohenkerk (HMNAO, September 1984), with extensions to + support the radio case. Apart from merely cosmetic changes, the + following modifications to the original HMNAO optical/IR refraction + code have been made: + + . The angle arguments have been changed to radians. + + . Any value of ZOBS is allowed (see note 6, below). + + . Other argument values have been limited to safe values. + + . Murray's values for the gas constants have been used + (Vectorial Astrometry, Adam Hilger, 1983). + + . The numerical integration phase has been rearranged for + extra clarity. + + . A better model for Ps(T) has been adopted (taken from + Gill, Atmosphere-Ocean Dynamics, Academic Press, 1982). + + . More accurate expressions for Pwo have been adopted + (again from Gill 1982). + + . Provision for radio wavelengths has been added using + expressions devised by A.T.Sinclair, RGO (private + communication 1989), based on the Essen & Froome + refractivity formula adopted in Resolution 1 of the + 13th International Geodesy Association General Assembly + (Bulletin Geodesique 70 p390, 1963). + + . Various small changes have been made to gain speed. + + None of the changes significantly affects the optical/IR results + with respect to the algorithm given in the 1992 Explanatory + Supplement. For example, at 70 deg zenith distance the present + routine agrees with the ES algorithm to better than 0.05 arcsec + for any reasonable combination of parameters. However, the + improved water-vapour expressions do make a significant difference + in the radio band, at 70 deg zenith distance reaching almost + 4 arcsec for a hot, humid, low-altitude site during a period of + low pressure. + + 5 The radio refraction is chosen by specifying WL > 100 micrometres. + Because the algorithm takes no account of the ionosphere, the + accuracy deteriorates at low frequencies, below about 30 MHz. + + 6 Before use, the value of ZOBS is expressed in the range +/- pi. + If this ranged ZOBS is -ve, the result REF is computed from its + absolute value before being made -ve to match. In addition, if + it has an absolute value greater than 93 deg, a fixed REF value + equal to the result for ZOBS = 93 deg is returned, appropriately + signed. + + 7 As in the original Hohenkerk and Sinclair algorithm, fixed values + of the water vapour polytrope exponent, the height of the + tropopause, and the height at which refraction is negligible are + used. + + 8 The radio refraction has been tested against work done by + Iain Coulson, JACH, (private communication 1995) for the + James Clerk Maxwell Telescope, Mauna Kea. For typical conditions, + agreement at the 0.1 arcsec level is achieved for moderate ZD, + worsening to perhaps 0.5-1.0 arcsec at ZD 80 deg. At hot and + humid sea-level sites the accuracy will not be as good. + + 9 It should be noted that the relative humidity RH is formally + defined in terms of "mixing ratio" rather than pressures or + densities as is often stated. It is the mass of water per unit + mass of dry air divided by that for saturated air at the same + temperature and pressure (see Gill 1982). + + Called: slDA1P, slATMT, slATMS + + P.T.Wallace Starlink 3 June 1997 + + Copyright (C) 1997 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/refv.hlp b/math/slalib/doc/refv.hlp new file mode 100644 index 00000000..104736a5 --- /dev/null +++ b/math/slalib/doc/refv.hlp @@ -0,0 +1,79 @@ +.help refv Jun99 "Slalib Package" +.nf + + SUBROUTINE slREFV (VU, REFA, REFB, VR) + + - - - - - + R E F V + - - - - - + + Adjust an unrefracted Cartesian vector to include the effect of + atmospheric refraction, using the simple A tan Z + B tan**3 Z + model. + + Given: + VU dp unrefracted position of the source (Az/El 3-vector) + REFA dp tan Z coefficient (radian) + REFB dp tan**3 Z coefficient (radian) + + Returned: + VR dp refracted position of the source (Az/El 3-vector) + + Notes: + + 1 This routine applies the adjustment for refraction in the + opposite sense to the usual one - it takes an unrefracted + (in vacuo) position and produces an observed (refracted) + position, whereas the A tan Z + B tan**3 Z model strictly + applies to the case where an observed position is to have the + refraction removed. The unrefracted to refracted case is + harder, and requires an inverted form of the text-book + refraction models; the algorithm used here is equivalent to + one iteration of the Newton-Raphson method applied to the above + formula. + + 2 Though optimized for speed rather than precision, the present + routine achieves consistency with the refracted-to-unrefracted + A tan Z + B tan**3 Z model at better than 1 micro-arcsecond within + 30 degrees of the zenith and remains within 1 milliarcsecond to + beyond ZD 70 degrees. The inherent accuracy of the model is, of + course, far worse than this - see the documentation for slRFCO + for more information. + + 3 At low elevations (below about 3 degrees) the refraction + correction is held back to prevent arithmetic problems and + wildly wrong results. Over a wide range of observer heights + and corresponding temperatures and pressures, the following + levels of accuracy (arcsec) are achieved, relative to numerical + integration through a model atmosphere: + + ZD error + + 80 0.4 + 81 0.8 + 82 1.6 + 83 3 + 84 7 + 85 17 + 86 45 + 87 150 + 88 340 + 89 620 + 90 1100 + 91 1900 } relevant only to + 92 3200 } high-elevation sites + + 4 See also the routine slREFZ, which performs the adjustment to + the zenith distance rather than in Cartesian Az/El coordinates. + The present routine is faster than slREFZ and, except very low down, + is equally accurate for all practical purposes. However, beyond + about ZD 84 degrees slREFZ should be used, and for the utmost + accuracy iterative use of slRFRO should be considered. + + P.T.Wallace Starlink 26 December 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/refz.hlp b/math/slalib/doc/refz.hlp new file mode 100644 index 00000000..5c91ab03 --- /dev/null +++ b/math/slalib/doc/refz.hlp @@ -0,0 +1,78 @@ +.help refz Jun99 "Slalib Package" +.nf + + SUBROUTINE slREFZ (ZU, REFA, REFB, ZR) + + - - - - - + R E F Z + - - - - - + + Adjust an unrefracted zenith distance to include the effect of + atmospheric refraction, using the simple A tan Z + B tan**3 Z + model (plus special handling for large ZDs). + + Given: + ZU dp unrefracted zenith distance of the source (radian) + REFA dp tan Z coefficient (radian) + REFB dp tan**3 Z coefficient (radian) + + Returned: + ZR dp refracted zenith distance (radian) + + Notes: + + 1 This routine applies the adjustment for refraction in the + opposite sense to the usual one - it takes an unrefracted + (in vacuo) position and produces an observed (refracted) + position, whereas the A tan Z + B tan**3 Z model strictly + applies to the case where an observed position is to have the + refraction removed. The unrefracted to refracted case is + harder, and requires an inverted form of the text-book + refraction models; the formula used here is based on the + Newton-Raphson method. For the utmost numerical consistency + with the refracted to unrefracted model, two iterations are + carried out, achieving agreement at the 1D-11 arcseconds level + for a ZD of 80 degrees. The inherent accuracy of the model + is, of course, far worse than this - see the documentation for + slRFCO for more information. + + 2 At ZD 83 degrees, the rapidly-worsening A tan Z + B tan**3 Z + model is abandoned and an empirical formula takes over. Over a + wide range of observer heights and corresponding temperatures and + pressures, the following levels of accuracy (arcsec) are + typically achieved, relative to numerical integration through a + model atmosphere: + + ZR error + + 80 0.4 + 81 0.8 + 82 1.5 + 83 3.2 + 84 4.9 + 85 5.8 + 86 6.1 + 87 7.1 + 88 10 + 89 20 + 90 40 + 91 100 } relevant only to + 92 200 } high-elevation sites + + The high-ZD model is scaled to match the normal model at the + transition point; there is no glitch. + + 3 Beyond 93 deg zenith distance, the refraction is held at its + 93 deg value. + + 4 See also the routine slREFV, which performs the adjustment in + Cartesian Az/El coordinates, and with the emphasis on speed + rather than numerical accuracy. + + P.T.Wallace Starlink 19 September 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rverot.hlp b/math/slalib/doc/rverot.hlp new file mode 100644 index 00000000..5f61abd7 --- /dev/null +++ b/math/slalib/doc/rverot.hlp @@ -0,0 +1,40 @@ +.help rverot Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRVER (PHI, RA, DA, ST) + + - - - - - - - + R V E R + - - - - - - - + + Velocity component in a given direction due to Earth rotation + (single precision) + + Given: + PHI real latitude of observing station (geodetic) + RA,DA real apparent RA,DEC + ST real local apparent sidereal time + + PHI, RA, DEC and ST are all in radians. + + Result: + Component of Earth rotation in direction RA,DA (km/s) + + Sign convention: + The result is +ve when the observatory is receding from the + given point on the sky. + + Accuracy: + The simple algorithm used assumes a spherical Earth, of + a radius chosen to give results accurate to about 0.0005 km/s + for observing stations at typical latitudes and heights. For + applications requiring greater precision, use the routine + slPVOB. + + P.T.Wallace Starlink 20 July 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rvgalc.hlp b/math/slalib/doc/rvgalc.hlp new file mode 100644 index 00000000..b0e2773e --- /dev/null +++ b/math/slalib/doc/rvgalc.hlp @@ -0,0 +1,42 @@ +.help rvgalc Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRVGA (R2000, D2000) + + - - - - - - - + R V G A + - - - - - - - + + Velocity component in a given direction due to the rotation + of the Galaxy (single precision) + + Given: + R2000,D2000 real J2000.0 mean RA,Dec (radians) + + Result: + Component of dynamical LSR motion in direction R2000,D2000 (km/s) + + Sign convention: + The result is +ve when the dynamical LSR is receding from the + given point on the sky. + + Note: The Local Standard of Rest used here is a point in the + vicinity of the Sun which is in a circular orbit around + the Galactic centre. Sometimes called the "dynamical" LSR, + it is not to be confused with a "kinematical" LSR, which + is the mean standard of rest of star catalogues or stellar + populations. + + Reference: The orbital speed of 220 km/s used here comes from + Kerr & Lynden-Bell (1986), MNRAS, 221, p1023. + + Called: + slCS2C, slVDV + + P.T.Wallace Starlink 23 March 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rvlg.hlp b/math/slalib/doc/rvlg.hlp new file mode 100644 index 00000000..e333c1e4 --- /dev/null +++ b/math/slalib/doc/rvlg.hlp @@ -0,0 +1,36 @@ +.help rvlg Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRVLG (R2000, D2000) + + - - - - - + R V L G + - - - - - + + Velocity component in a given direction due to the combination + of the rotation of the Galaxy and the motion of the Galaxy + relative to the mean motion of the local group (single precision) + + Given: + R2000,D2000 real J2000.0 mean RA,Dec (radians) + + Result: + Component of SOLAR motion in direction R2000,D2000 (km/s) + + Sign convention: + The result is +ve when the Sun is receding from the + given point on the sky. + + Reference: + IAU Trans 1976, 168, p201. + + Called: + slCS2C, slVDV + + P.T.Wallace Starlink June 1985 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rvlsrd.hlp b/math/slalib/doc/rvlsrd.hlp new file mode 100644 index 00000000..f7539867 --- /dev/null +++ b/math/slalib/doc/rvlsrd.hlp @@ -0,0 +1,51 @@ +.help rvlsrd Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRVLD (R2000, D2000) + + - - - - - - - + R V L D + - - - - - - - + + Velocity component in a given direction due to the Sun's motion + with respect to the dynamical Local Standard of Rest. + + (single precision) + + Given: + R2000,D2000 r J2000.0 mean RA,Dec (radians) + + Result: + Component of "peculiar" solar motion in direction R2000,D2000 (km/s) + + Sign convention: + The result is +ve when the Sun is receding from the given point on + the sky. + + Note: The Local Standard of Rest used here is the "dynamical" LSR, + a point in the vicinity of the Sun which is in a circular + orbit around the Galactic centre. The Sun's motion with + respect to the dynamical LSR is called the "peculiar" solar + motion. + + There is another type of LSR, called a "kinematical" LSR. A + kinematical LSR is the mean standard of rest of specified star + catalogues or stellar populations, and several slightly + different kinematical LSRs are in use. The Sun's motion with + respect to an agreed kinematical LSR is known as the "standard" + solar motion. To obtain a radial velocity correction with + respect to an adopted kinematical LSR use the routine slRVLK. + + Reference: Delhaye (1965), in "Stars and Stellar Systems", vol 5, + p73. + + Called: + slCS2C, slVDV + + P.T.Wallace Starlink 9 March 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/rvlsrk.hlp b/math/slalib/doc/rvlsrk.hlp new file mode 100644 index 00000000..04cbca89 --- /dev/null +++ b/math/slalib/doc/rvlsrk.hlp @@ -0,0 +1,50 @@ +.help rvlsrk Jun99 "Slalib Package" +.nf + + REAL FUNCTION slRVLK (R2000, D2000) + + - - - - - - - + R V L K + - - - - - - - + + Velocity component in a given direction due to the Sun's motion + with respect to an adopted kinematic Local Standard of Rest. + + (single precision) + + Given: + R2000,D2000 r J2000.0 mean RA,Dec (radians) + + Result: + Component of "standard" solar motion in direction R2000,D2000 (km/s) + + Sign convention: + The result is +ve when the Sun is receding from the given point on + the sky. + + Note: The Local Standard of Rest used here is one of several + "kinematical" LSRs in common use. A kinematical LSR is the + mean standard of rest of specified star catalogues or stellar + populations. The Sun's motion with respect to a kinematical + LSR is known as the "standard" solar motion. + + There is another sort of LSR, the "dynamical" LSR, which is a + point in the vicinity of the Sun which is in a circular orbit + around the Galactic centre. The Sun's motion with respect to + the dynamical LSR is called the "peculiar" solar motion. To + obtain a radial velocity correction with respect to the + dynamical LSR use the routine slRVLD. + + Reference: Delhaye (1965), in "Stars and Stellar Systems", vol 5, + p73. + + Called: + slCS2C, slVDV + + P.T.Wallace Starlink 11 March 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/s2tp.hlp b/math/slalib/doc/s2tp.hlp new file mode 100644 index 00000000..fb92a6f9 --- /dev/null +++ b/math/slalib/doc/s2tp.hlp @@ -0,0 +1,31 @@ +.help s2tp Jun99 "Slalib Package" +.nf + + SUBROUTINE slS2TP (RA, DEC, RAZ, DECZ, XI, ETA, J) + + - - - - - + S 2 T P + - - - - - + + Projection of spherical coordinates onto tangent plane: + "gnomonic" projection - "standard coordinates" + (single precision) + + Given: + RA,DEC real spherical coordinates of point to be projected + RAZ,DECZ real spherical coordinates of tangent point + + Returned: + XI,ETA real rectangular coordinates on tangent plane + J int status: 0 = OK, star on tangent plane + 1 = error, star too far from axis + 2 = error, antistar on tangent plane + 3 = error, antistar too far from axis + + P.T.Wallace Starlink 18 July 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/sedscript b/math/slalib/doc/sedscript new file mode 100755 index 00000000..3797f980 --- /dev/null +++ b/math/slalib/doc/sedscript @@ -0,0 +1,35 @@ +#!/bin/csh + +# EZSEDSCRIPT -- Script for automatically creating simple help for the +# SLALIB FORTRAN routines. +# +# First argument $1 is the month and year combined, e.g. Jun84 + +foreach file (../*.f) + set rootfile = `basename $file .f` + set package = '"Slalib Package"' + set outfile = $rootfile.hlp + set d = `echo \$d` + set s = `echo \$s` + echo $outfile + echo "1i\\ +.help $rootfile $1 $package\\ +.nf\\ +\ +/^\*-/a\\ +\\ +.fi\\ +.endhelp\ +/^\*-/,$d\ +1,$s/^*+//\ +1,$s/^*//" > tmpfile + sed -f tmpfile $file > $outfile + rm tmpfile +end + +rm atms.hlp +rm atmt.hlp +rm idchf.hlp +rm idchi.hlp +rm sla_test.hlp +cp slalib.hlp.sav slalib.hlp diff --git a/math/slalib/doc/sep.hlp b/math/slalib/doc/sep.hlp new file mode 100644 index 00000000..71808737 --- /dev/null +++ b/math/slalib/doc/sep.hlp @@ -0,0 +1,29 @@ +.help sep Jun99 "Slalib Package" +.nf + + REAL FUNCTION slSEP (A1, B1, A2, B2) + + - - - - + S E P + - - - - + + Angle between two points on a sphere (single precision) + + Given: + A1,B1 real spherical coordinates of one point + A2,B2 real spherical coordinates of the other point + + (The spherical coordinates are RA,Dec, Long,Lat etc, in radians.) + + The result is the angle, in radians, between the two points. It + is always positive. + + Called: slCS2C + + P.T.Wallace Starlink April 1985 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/sla.news b/math/slalib/doc/sla.news new file mode 100644 index 00000000..541b6c8a --- /dev/null +++ b/math/slalib/doc/sla.news @@ -0,0 +1,36 @@ +SLALIB_Version_2.3-0 Expiry 30 September 1999 + +The latest releases of SLALIB include the following changes: + +* The 1999 January 1 UTC leap second has been added to the DAT routine. + +* Four new routines have been introduced which transform between the + FK5 system and the ICRS (Hipparcos) system. FK52H and H2FK5 transform + star positions and proper motions from FK5 coordinates to Hipparcos + coordinates and vice versa. FK5HZ and HFK5Z do the same but for the + case where the Hipparcos proper motions are zero. + +* Six new routines have been introduced for dealing with orbital elements. + Four of them (sla_EL2UE, sla_PV2UE, sla_UE2EL and sla_UE2PV) provide + applications with direct access to the "universal variables" method + that was already being used internally. Compared with using conventional + (angular) elements and solving Kepler's equation, the universal variables + approach has a number of advantages, including better handling of near- + parabolic orbits and greater efficiency. The remaining two routines + (sla_PERTEL and sla_PERTUE) generate updated elements by applying + major-planet perturbations. The new elements can then be used to + predict positions that are much more accurate. For minor planets, + sub-arcsecond accuracy over a decade is achievable. + +* Several observatory sites have been added to the OBS routine: CFHT, + Keck 2, Gemini North, FCRAO, IRTF and CSO. The coordinates for all + the Mauna Kea sites have been updated in accordance with recent aerial + photography results made available by the Institute for Astronomy, + University of Hawaii. + + P.T.Wallace + 21 April 1999 + + ptw@star.rl.ac.uk + +44-1235-44-5372 +-------------------------------------------------------------------------- diff --git a/math/slalib/doc/slalib.hd b/math/slalib/doc/slalib.hd new file mode 100644 index 00000000..35fe8ea0 --- /dev/null +++ b/math/slalib/doc/slalib.hd @@ -0,0 +1,183 @@ +# Help directory the SLALIB library + +$slalib = "math$slalib/" + +addet hlp=addet.hlp, src=slalib$addet.f +afin hlp=afin.hlp, src=slalib$afin.f +airmas hlp=airmas.hlp, src=slalib$airmas.f +altaz hlp=altaz.hlp, src=slalib$altaz.f +amp hlp=amp.hlp, src=slalib$amp.f +ampqk hlp=ampqk.hlp, src=slalib$ampqk.f +aop hlp=aop.hlp, src=slalib$aop.f +aoppa hlp=aoppa.hlp, src=slalib$aoppa.f +aoppat hlp=aoppat.hlp, src=slalib$aoppat.f +aopqk hlp=aopqk.hlp, src=slalib$aopqk.f +atmdsp hlp=atmdsp.hlp, src=slalib$atmdsp.f +av2m hlp=av2m.hlp, src=slalib$av2m.f +bear hlp=bear.hlp, src=slalib$bear.f +caf2r hlp=caf2r.hlp, src=slalib$caf2r.f +caldj hlp=caldj.hlp, src=slalib$caldj.f +calyd hlp=calyd.hlp, src=slalib$calyd.f +cc2s hlp=cc2s.hlp, src=slalib$cc2s.f +cc62s hlp=cc62s.hlp, src=slalib$cc62s.f +cd2tf hlp=cd2tf.hlp, src=slalib$cd2tf.f +cldj hlp=cldj.hlp, src=slalib$cldj.f +clyd hlp=clyd.hlp, src=slalib$clyd.f +cr2af hlp=cr2af.hlp, src=slalib$cr2af.f +cr2tf hlp=cr2tf.hlp, src=slalib$cr2tf.f +cs2c hlp=cs2c.hlp, src=slalib$cs2c.f +cs2c6 hlp=cs2c6.hlp, src=slalib$cs2c6.f +ctf2d hlp=ctf2d.hlp, src=slalib$ctf2d.f +ctf2r hlp=ctf2r.hlp, src=slalib$ctf2r.f +daf2r hlp=daf2r.hlp, src=slalib$daf2r.f +dafin hlp=dafin.hlp, src=slalib$dafin.f +dat hlp=dat.hlp, src=slalib$dat.f +dav2m hlp=dav2m.hlp, src=slalib$dav2m.f +dbear hlp=dbear.hlp, src=slalib$dbear.f +dbjin hlp=dbjin.hlp, src=slalib$dbjin.f +dc62s hlp=dc62s.hlp, src=slalib$dc62s.f +dcc2s hlp=dcc2s.hlp, src=slalib$dcc2s.f +dcmpf hlp=dcmpf.hlp, src=slalib$dcmpf.f +dcs2c hlp=dcs2c.hlp, src=slalib$dcs2c.f +dd2tf hlp=dd2tf.hlp, src=slalib$dd2tf.f +de2h hlp=de2h.hlp, src=slalib$de2h.f +deuler hlp=deuler.hlp, src=slalib$deuler.f +dfltin hlp=dfltin.hlp, src=slalib$dfltin.f +dh2e hlp=dh2e.hlp, src=slalib$dh2e.f +dimxv hlp=dimxv.hlp, src=slalib$dimxv.f +djcal hlp=djcal.hlp, src=slalib$djcal.f +djcl hlp=djcl.hlp, src=slalib$djcl.f +dm2av hlp=dm2av.hlp, src=slalib$dm2av.f +dmat hlp=dmat.hlp, src=slalib$dmat.f +dmoon hlp=dmoon.hlp, src=slalib$dmoon.f +dmxm hlp=dmxm.hlp, src=slalib$dmxm.f +dmxv hlp=dmxv.hlp, src=slalib$dmxv.f +dpav hlp=dpav.hlp, src=slalib$dpav.f +dr2af hlp=dr2af.hlp, src=slalib$dr2af.f +dr2tf hlp=dr2tf.hlp, src=slalib$dr2tf.f +drange hlp=drange.hlp, src=slalib$drange.f +dranrm hlp=dranrm.hlp, src=slalib$dranrm.f +ds2c6 hlp=ds2c6.hlp, src=slalib$ds2c6.f +ds2tp hlp=ds2tp.hlp, src=slalib$ds2tp.f +dsep hlp=dsep.hlp, src=slalib$dsep.f +dt hlp=dt.hlp, src=slalib$dt.f +dtf2d hlp=dtf2d.hlp, src=slalib$dtf2d.f +dtf2r hlp=dtf2r.hlp, src=slalib$dtf2r.f +dtp2s hlp=dtp2s.hlp, src=slalib$dtp2s.f +dtp2v hlp=dtp2v.hlp, src=slalib$dtp2v.f +dtps2c hlp=dtps2c.hlp, src=slalib$dtps2c.f +dtpv2c hlp=dtpv2c.hlp, src=slalib$dtpv2c.f +dtt hlp=dtt.hlp, src=slalib$dtt.f +dv2tp hlp=dv2tp.hlp, src=slalib$dv2tp.f +dvdv hlp=dvdv.hlp, src=slalib$dvdv.f +dvn hlp=dvn.hlp, src=slalib$dvn.f +dvxv hlp=dvxv.hlp, src=slalib$dvxv.f +e2h hlp=e2h.hlp, src=slalib$e2h.f +earth hlp=earth.hlp, src=slalib$earth.f +ecleq hlp=ecleq.hlp, src=slalib$ecleq.f +ecmat hlp=ecmat.hlp, src=slalib$ecmat.f +ecor hlp=ecor.hlp, src=slalib$ecor.f +eg50 hlp=eg50.hlp, src=slalib$eg50.f +el2ue hlp=el2ue.hlp, src=slalib$el2ue.f +epb hlp=epb.hlp, src=slalib$epb.f +epb2d hlp=epb2d.hlp, src=slalib$epb2d.f +epco hlp=epco.hlp, src=slalib$epco.f +epj hlp=epj.hlp, src=slalib$epj.f +epj2d hlp=epj2d.hlp, src=slalib$epj2d.f +eqecl hlp=eqecl.hlp, src=slalib$eqecl.f +eqeqx hlp=eqeqx.hlp, src=slalib$eqeqx.f +eqgal hlp=eqgal.hlp, src=slalib$eqgal.f +etrms hlp=etrms.hlp, src=slalib$etrms.f +euler hlp=euler.hlp, src=slalib$euler.f +evp hlp=evp.hlp, src=slalib$evp.f +fitxy hlp=fitxy.hlp, src=slalib$fitxy.f +fk425 hlp=fk425.hlp, src=slalib$fk425.f +fk45z hlp=fk45z.hlp, src=slalib$fk45z.f +fk524 hlp=fk524.hlp, src=slalib$fk524.f +fk54z hlp=fk54z.hlp, src=slalib$fk54z.f +fk52h hlp=fk52h.hlp, src=slalib$fk52h.f +fk5hz hlp=fk5hz.hlp, src=slalib$fk5hz.f +flotin hlp=flotin.hlp, src=slalib$flotin.f +galeq hlp=galeq.hlp, src=slalib$galeq.f +galsup hlp=galsup.hlp, src=slalib$galsup.f +ge50 hlp=ge50.hlp, src=slalib$ge50.f +geoc hlp=geoc.hlp, src=slalib$geoc.f +gmst hlp=gmst.hlp, src=slalib$gmst.f +gmsta hlp=gmsta.hlp, src=slalib$gmsta.f +h2e hlp=h2e.hlp, src=slalib$h2e.f +h2fk5 hlp=h2fk5.hlp, src=slalib$h2fk5.f +hfk5z hlp=hfk5z.hlp, src=slalib$hfk5z.f +imxv hlp=imxv.hlp, src=slalib$imxv.f +intin hlp=intin.hlp, src=slalib$intin.f +invf hlp=invf.hlp, src=slalib$invf.f +kbj hlp=kbj.hlp, src=slalib$kbj.f +m2av hlp=m2av.hlp, src=slalib$m2av.f +map hlp=map.hlp, src=slalib$map.f +mappa hlp=mappa.hlp, src=slalib$mappa.f +mapqk hlp=mapqk.hlp, src=slalib$mapqk.f +mapqkz hlp=mapqkz.hlp, src=slalib$mapqkz.f +moon hlp=moon.hlp, src=slalib$moon.f +mxm hlp=mxm.hlp, src=slalib$mxm.f +mxv hlp=mxv.hlp, src=slalib$mxv.f +nut hlp=nut.hlp, src=slalib$nut.f +nutc hlp=nutc.hlp, src=slalib$nutc.f +oap hlp=oap.hlp, src=slalib$oap.f +oapqk hlp=oapqk.hlp, src=slalib$oapqk.f +obs hlp=obs.hlp, src=slalib$obs.f +pa hlp=pa.hlp, src=slalib$pa.f +pav hlp=pav.hlp, src=slalib$pav.f +pcd hlp=pcd.hlp, src=slalib$pcd.f +pda2h hlp=pda2h.hlp, src=slalib$pda2h.f +pdq2h hlp=pdq2h.hlp, src=slalib$pdq2h.f +pertel hlp=pertel.hlp, src=slalib$pertel.f +pertue hlp=pertue.hlp, src=slalib$pertue.f +planel hlp=planel.hlp, src=slalib$planel.f +planet hlp=planet.hlp, src=slalib$planet.f +plante hlp=plante.hlp, src=slalib$plante.f +pm hlp=pm.hlp, src=slalib$pm.f +polmo hlp=polmo.hlp, src=slalib$polmo.f +prebn hlp=prebn.hlp, src=slalib$prebn.f +prec hlp=prec.hlp, src=slalib$prec.f +preces hlp=preces.hlp, src=slalib$preces.f +precl hlp=precl.hlp, src=slalib$precl.f +precss hlp=precss.hlp, src=slalib$precss.f +prenut hlp=prenut.hlp, src=slalib$prenut.f +pv2ue hlp=pv2ue.hlp, src=slalib$pv2ue.f +pv2el hlp=pv2el.hlp, src=slalib$pv2el.f +pvobs hlp=pvobs.hlp, src=slalib$pvobs.f +pxy hlp=pxy.hlp, src=slalib$pxy.f +range hlp=range.hlp, src=slalib$range.f +ranorm hlp=ranorm.hlp, src=slalib$ranorm.f +rcc hlp=rcc.hlp, src=slalib$rcc.f +rdplan hlp=rdplan.hlp, src=slalib$rdplan.f +refco hlp=refco.hlp, src=slalib$refco.f +refcoq hlp=refcoq.hlp, src=slalib$refcoq.f +refro hlp=refro.hlp, src=slalib$refro.f +refv hlp=refv.hlp, src=slalib$refv.f +refz hlp=refz.hlp, src=slalib$refz.f +rverot hlp=rverot.hlp, src=slalib$rverot.f +rvgalc hlp=rvgalc.hlp, src=slalib$rvgalc.f +rvlg hlp=rvlg.hlp, src=slalib$rvlg.f +rvlsrd hlp=rvlsrd.hlp, src=slalib$rvlsrd.f +rvlsrk hlp=rvlsrk.hlp, src=slalib$rvlsrk.f +s2tp hlp=s2tp.hlp, src=slalib$s2tp.f +sep hlp=sep.hlp, src=slalib$sep.f +smat hlp=smat.hlp, src=slalib$smat.f +subet hlp=subet.hlp, src=slalib$subet.f +supgal hlp=supgal.hlp, src=slalib$supgal.f +svd hlp=svd.hlp, src=slalib$svd.f +svdcov hlp=svdcov.hlp, src=slalib$svdcov.f +svdsol hlp=svdsol.hlp, src=slalib$svdsol.f +tp2s hlp=tp2s.hlp, src=slalib$tp2s.f +tp2v hlp=tp2v.hlp, src=slalib$tp2v.f +tps2c hlp=tps2c.hlp, src=slalib$tps2c.f +tpv2c hlp=tpv2c.hlp, src=slalib$tpv2c.f +ue2el hlp=ue2el.hlp, src=slalib$ue2el.f +ue2pv hlp=ue2pv.hlp, src=slalib$ue2pv.f +unpcd hlp=unpcd.hlp, src=slalib$unpcd.f +v2tp hlp=v2tp.hlp, src=slalib$v2tp.f +vdv hlp=vdv.hlp, src=slalib$vdv.f +vn hlp=vn.hlp, src=slalib$vn.f +vxv hlp=vxv.hlp, src=slalib$vxv.f +xy2xy hlp=xy2xy.hlp, src=slalib$xy2xy.f +zd hlp=zd.hlp, src=slalib$zd.f diff --git a/math/slalib/doc/slalib.hlp b/math/slalib/doc/slalib.hlp new file mode 100644 index 00000000..8da465cf --- /dev/null +++ b/math/slalib/doc/slalib.hlp @@ -0,0 +1,591 @@ +.help slalib Nov95 "Immatch Package" +.ih +NAME +slalib -- Starlink library of positional astronomy routines + +.ih +DESCRIPTION +SLALIB is a library of Fortran 77 routines intended to make accurate +and reliable positional-astronomy applications easier to write. Most +SLALIB library routines are concerned with astronomical position and time, +but a number have wider trigonometrical, numerical or general applications. +SLALIB contains routines covering the following topics: 1) string +decoding and sexagesimal conversions, 2) angles, vectors and rotation +matrices, 3) calendars and timescales, 4) precession and nutation, 5) +proper motion, 6) FK4/5 and elliptic aberration, 7) geocentric coordinates, +8) apparent and observed place, 9) azimuth and elevation, 10) refraction +and air mass, 11) ecliptic, galactic, and supergalactic coordinates, +12) ephemerides, 13) astrometry, and 14) numerical methods. + +The labels and calling sequences of the SLALIB are listed below grouped +by function. To get more detailed help on any individual routine type +the help command followed by the label, e.g the command "help flotin" +will give detailed help on the subroutine slrfli. + +.ih +STRING DECODING +.nf + intin -- call subroutine slinti (string, nstrt, ireslt, jflag) + Convert free-format string into integer + +flotin -- call subroutine slrfli (string, nstrt, reslt, jflag) +dfltin -- call subroutine sldfli (string, nstrt, dreslt, jflag) + Convert free-format string into floating point number + + afin -- call subroutine slafin (string, iptr, a, j) + dafin -- call subroutine sldafn (string, iptr, a, j) + Convert free-format string from deg, armin, arcsec to radians +.fi +.ih +SEXAGESIMAL CONVERSIONS +.nf + ctf2d -- call subroutine slctfd (ihour, imin, sec, days, j) + dtf2d -- call subroutine sldtfd (ihour, imin, sec, days, j) + Hours, minutes, seconds to days + + cd2tf -- call subroutine slcdtf (ndp, days, sign, ihmsf) + dd2tf -- call subroutine slddtf (ndp, days, sign, ihmsf) + Days to hours, minutes, and seconds + + ctf2r -- call subroutine slctfr (ihour, imin, sec, rad, j) + dtf2r -- call subroutine sldtfr (ihour, imin, sec, rad, j) + Hours, minutes, seconds to radians + + cr2tf -- call subroutine slcrtf (ndp, angle, sign, ihmsf) + dr2tf -- call subroutine sldrtf (ndp, angle, sign, ihmsf) + Radians to hours, minutes, seconds + + caf2r -- call subroutine slcafr (ideg, iamin, asec, rad, j) + daf2r -- call subroutine sldafr (ideg, iamin, asec, rad, j) + Degrees, arcminutes, arcseconds to radians + + cr2af -- call subroutine slcraf (ndp, angle, sign, idmsf) + dr2af -- call subroutine sldraf (ndp, angle, sign, idmsf) + Radians to degrees, arcminutes, arcseconds +.fi +.ih +ANGLES, VECTORS AND ROTATION MATRICES +.nf + range -- r = slra1p (angle) +drange -- d = slda1p (angle) + Normalize angle into range [-pi,pi] + +ranorm -- r = slra2p (angle) +dranrm -- d = slda2p (angle) + Normalize angle into range [0,2pi] + + cs2c -- call subroutine slcs2c (a, b, v) + dcs2c -- call subroutine slds2c (a, b, v) + Spherical coordinates to [x,y,z] + + cc2s -- call subroutine slcc2s (v, a, b) + dcc2s -- call subroutine sldc2s (v, a, b) + [x,y,z] to spherical coordinates + + vdv -- r = slvdv (va, vb) + dvdv -- d = sldvdv (va, vb) + Scalar product of two 3-vectors + + vxv -- call subroutine slvxv (va, vb, vc) + dvxv -- call subroutine sldvxv (va, vb, vc) + Vector product of two 3-vectors + + vn -- call subroutine slvn (v, uv, vm) + dvn -- call subroutine sldvn (v, uv, vm) + Normalize a 3-vector also giving the modulus + + sep -- s = slsep (a1, b1, a2, b2) + dsep -- d = sldsep (a1, b1, a2, b2) + Angle between two points on a sphere + + bear -- s = slbear (a1, b1, a2, b2) + dbear -- d = sldber (a1, b1, a2, b2) + pav -- s = slpav (v1, v2) + dpav -- d = sldpav (v1, v2) + Direction of one point on a sphere seen from another + + euler -- call subroutine sleulr (order, phi, theta, psi, rmat) +deuler -- call subroutine sldeul (order, phi, theta, psi, rmat) + Form form rotation matrix from three Euler angles + + + av2m -- call subroutine slav2m (axvec, rmat) + dav2m -- call subroutine sldavm (axvec, rmat) + Form rotation matrix from axial vector + + m2av -- call subroutine slm2av (rmat, axvec) + dm2av -- call subroutine sldmav (rmat, axvec) + Determine axial vector from rotation matrix + + dmxv -- call subroutine sldmxv (dm, va, vb) + mxv -- call subroutine slmxv (rm, va, vb) + Rotate vector forwards + + imxv -- call subroutine slimxv (rm, va, vb) + dimxv -- call subroutine sldimv (dm, va, vb) + Rotate vector backwards + + dmxm -- call subroutine sldmxm (a, b, c) + mxm -- call subroutine slmxm (a, b, c) + Product of two 3X3 matrices + + cs2c6 -- call subroutine sls2c6 (a, b, r, ad, bd, rd, v) + ds2c6 -- call subroutine sldsc6 (a, b, r, ad, bd, rd, v) + Conversion of position/velocity from spherical to Cartesian + coordinates + + cc62s -- call subroutine slc62s (v, a, b, r, ad, bd, rd) + dc62s -- call subroutine sldc6s (v, a, b, r, ad, bd, rd) + Conversion of position/velocity from Cartesian to spherical + coordinates +.fi +.ih +CALENDARS +.nf + cldj -- call subroutine slcadj (iy, im, id, djm, j) + Gregorian calendar to Modified Julian Date + + caldj -- call subroutine slcadj (iy, im, id, djm, j) + Gregorian calendar to Modified Julian Date, permitting century by + default + + djcal -- call subroutine sldjca (ndp, djm, iymdf, j) + Modified Julian Date to Gregorian calendar, in a from convenient + for formatted output + + djcl -- call subroutine sldjcl (djm, iy, im, id, fd, j) + Modified Julian Date to Gregorian Year, Month, Day, Fraction + + calyd -- call subroutine slcayd (iy, im, id, ny, nd, j) + Calendar to year and day in year, permitting century default + + clyd -- call subroutine slclyd (iy, im, id, ny, nd, jstat) + Calendar to year and day in year + + epb -- d = slepb (date) + Modified Julian Date to Besselian Epoch + + epb2d -- d = sleb2d (epb) + Besselian epoch to Modified Julian Date + + epj -- d = slepj (date) + Modified Julian Date to Julian Epoch + + epj2d -- d = slej2d (epj) + Julian epoch to Modified Julian Date +.fi +.fi +.ih +TIMESCALES +.nf + gmst -- d = slgmst (ut1) + Conversion from Universal Time to siderial time + + gmsta -- d = slgmsa (date, ut) + Conversion from Universal Time to siderial time, rounding errors + minimized + + eqeqx -- d = sleqex (date) + Equation of the equinoxes + + dat -- d = sldat (utc) + Offset of Atomic Time from Coordinated Universal Time: + TAI - UTC + + dt -- d = sldt (epoch) + Approximate offset between dynamical time and universal time + + dtt -- d = sldtt (utc) + Offset of Terrestrial Time from Coordinated Universal Time: + TT - UTC + + rcc -- d = slrcc (tdb, ut1, wl, u, v) + Relativistic clock correction: TDB - TT +.fi +.ih +PRECESSION AND NUTATION +.nf + nut -- call subroutine slnut (date, rmatn) + Nutation matrix + + nutc -- call subroutine slnutc (date, dpsi, deps, eps0) + Longitude and obliquity components of nutation, mean obliquity + + prec -- call subroutine slprec (ep0, ep1, rmatp) + Precession matrix (IAU) + + precl -- call subroutine slprel (ep0, ep1, rmatp) + Precession matrix (suitable for long periods) + +prenut -- call subroutine slprnu (epoch, date, rmatpn) + Combined precession/nutation matrix + + prebn -- call subroutine slprbn (bep0, bep1, rmatp) + Precession matrix (old system) + +preces -- call subroutine slprce (system, ep0, ep1, ra, dc) + Precession in either the old or new system, character string + ep0 and ep1 + +precss -- call subroutine slprcs (system, ep0, ep1, ra, dc) + Precession in either the old or new system, integer ep0 and ep1 +.fi +.fi +.ih +PROPER MOTION +.nf + pm -- call subroutine slpm (r0, d0, pr, pd, px, rv, ep0, ep1, r1, d1) + Adjust for proper motion +.fi +.ih +FK4/5/ICRS CONVERSIONS +.nf + fk425 -- call subroutine slfk45 (r1950, d1950, dr1950, dd1950, + p1950, v1950, r2000, d2000, dr2000, dd2000, p2000, v2000) + Convert B1950.0 FK4 star data to J2000.0 FK5 + + fk45z -- call subroutine slf45z (r1950, d1950, bepoch, r2000, d2000) + Convert B1950.0 FK4 position to J2000.0 FK5 assuming zero proper + motion in an inertial frame and no parallax + + fk524 -- call subroutine slfk54 (r2000, d2000, dr2000, dd2000, + p2000, v2000, r1950, d1950, dr1950, dd1950, p1950, v1950) + Convert J2000.0 FK5 star data to B1950.0 FK4 + + fk54z -- call subroutine slf54z (r2000, d2000, bepoch, r1950, d1950, + dr1950, dd1950) + Convert J2000.0 FK5 star data to B1950.0 FK4 assuming zero proper + motion in an inertial frame and no parallax + + fk52h -- call subroutine slfk5h (r5, d5, dr5, dd5, rh, dh, drh, ddh) + Convert J2000.0 FK5 star data to ICRS J2000.0 data + + fk5hz -- call subroutine slf5hz (r5, d5, epoch, rh, dh) + Convert J2000.0 FK5 star data to ICRS J2000.0 data assuming + no Hipparcos proper motion. + + h2fk5 -- call subroutine slhfk5 (rh, dh, drh, ddh, r5, d5, dr5, dd5) + Convert ICRS J2000.0 data to J2000.0 Fk5 star data. + + hfk5z -- call subroutine slhf5z (rh, dh, epoch, r5, d5) + Convert ICRS J2000.0 data to J2000.0 Fk5 star data assuming no + Hipparchos proper motion. + + dbjin -- call subroutine sldbji (string, nstrt, dreslt, j1, j2) + Like dfltin but with extensions to accept leading 'B' and 'J' + + kbj -- call subroutine slkbj (jb, e, k, j) + Select epoch prefix 'B' or 'J' + + epco -- d = slepco (k0, k, e) + Convert an epoch into the appropriate form 'B' or 'J' +.fi +.ih +ELLIPTIC ABERRATIONS +.nf + etrms -- call subroutine sletrm (ep, ev) + E-terms + + subet -- call subroutine slsuet (rc, dc, eq, rm, dm) + Remove the E-terms + + addet -- call subroutine sladet (rm, dm, eq, rc, dc) + Add the E-terms +.fi +.ih +GEOCENTRIC COORDINATES +.nf + obs -- call subroutine slobs (n, c, name, w, p, h) + Interrogate list of observatory parameters + + geoc -- call subroutine slgeoc (p, h, r, z) + Convert geodetic position to geocentric + + pvobs -- call subroutine slpvob (p, h, stl, pv) + Position and velocity of observatory +.fi +.ih +APPARENT AND OBSERVED PLACE +.nf + map -- call subroutine slmap (rm, dm, pr, pd, px, rv, eq, date, ra, da) + Mean place to geocentric apparent place + + mappa -- call subroutine slmapa (eq, date, amprms) + Precompute mean to apparent parameters + + mapqk -- call subroutine slmapq (rm, dm, pr, pd, px, rv, amprms, ra, da) + Mean to apparent place using precomputed parameters + +mapqkz -- call subroutine slmapz (rm, dm, amprms, ra, da) + Mean to apparent place using precomputed parameters, for zero + proper motion, parallax, and radial velocity + + amp -- call subroutine slamp (ra, da, date, eq, rm, dm) + Geocentric apparent place to mean place + + ampqk -- call subroutine slampq (ra, da, amprms, rm, dm) + Apparent to mean place using precomputed parameters + + aop -- call subroutine slaop (rap, dap, date, dut, elongm, phim, hm, + xp, yp, tdk, pmb, rh, wl, tlr, aob, zob, hob, dob, rob) + Apparent place to observed place + + aoppa -- call subroutine slaopa (date, dut, elongm, phim, hm, xy, yp, + tdk, pmb, rh, wl, tlr, aoprms) + Precompute apparent to observed parameters + +aoppat -- call subroutine slaopt (date, aoprms) + Update siderial time in apparent to observed parameters + + aopqk -- call subroutine slaopq (rap, dap, aoprms, aob, zob, hob, dob, rob) + Apparent to observed using precomputed parameters + + oap -- call subroutine sloap (type, ob1, ob2, date, dut, elongm, phim, + xp, yp, tdk, pmb, rh, wl, tlr, rap, dap) + Observed to apparent + + oapqk -- call subroutine sloapq (type, ob1, ob2, aoprms, rap, dap) + Observed to apparent using precomputed parameters + + polmo -- call subroutine slplmo (elongim, phim, xp, yp, elong, phi, daz) + Correct site longitude and latitude for polar motion +.fi +.ih +AZIMUTH AND ELEVATION +.nf + altaz -- call subroutine slalaz (ha, dec, phi, + Positions, velocities, etc. for an altazimuth mount + + e2h -- call subroutine sle2h (ha, dec, phi, az, el) + de2h -- call subroutine slde2h (ha, dec, phi, az, el) + Hour angle and declination to azimuth and elevation + + h2e -- call subroutine slh2e (az, el, phi, ha, dec) + dh2e -- call subroutine sldh2e (az, el, phi, ha, dec) + Azimuth and elevation to hour angle and declination + + pda2h -- call subroutine slpdah (p, d, a, h1, j1, h2, j2) + Hour angle corresponding to a given azimuth + + pdq2h -- call subroutine slpdqh (p, d, q, h1, j1, h2, j2) + Hour angle corresponding to a given parallactic angle + + pa -- d = slpa (ha, dec, phi) + Hour angle and declination to parallactic angle + + zd -- d = slzd (ha, dec, phi) + Hour angle and declination to zenith distance +.fi +.ih +REFRACTION AND AIR MASS +.nf + refro -- call subroutine slrfro (zobs, hm, tdk, pmb, rh, wl, phi, tlr, + eps, ref) + Change in zenith distance due to refraction + + refco -- call subroutine slrfco (hm, tdk, pmb, rh, wl, phi, tlr, eps, + refa, refb) + Constants for simple refraction model + +refcoq -- call subroutine slrfcq (tdk, pmb, rl, wl, refa, refb) + Constants for simple refraction model (quick version) + +atmdsp -- call subroutine slatmd (tdk, pmb, rh, wl1, a1, b1, wl2, a2, b2) + Adjust refraction constants for color + + refz -- call subroutine slrefz (zu, refa, refb, zr) + Unrefracted to refracted zenith distance, simple model + + refv -- call subroutine slrefv (vu, refa, refb, vr) + Unrefracted to refracted azimuth and elevation, simple model + +airmas -- d = slarms (zd) + Air mass +.fi +.ih +ECLIPTIC COORDINATES +.nf + ecmat -- call subroutine slecma (date, rmat) + Equatorial to ecliptic rotation matrix + + eqecl -- call subroutine sleqec (dr, dd, date, dl, db) + J2000.0 FK5 to ecliptic coordinates + + ecleq -- call subroutine sleceq (dl, db, date, dr, dd) + Ecliptic to J2000.0 FK5 coordinates +.fi +.ih +GALACTIC COORDINATES +.nf + eg50 -- call subroutine sleg50 (dr, dd, dl, db) + B1950.0 FK4 to galactic coordinates + + ge50 -- call subroutine slge50 (dl, db, dr, dd) + Galactic to B1950.0 FK4 coordinates + + eqgal -- call subroutine sleqga (dr, dd, dl, db) + J2000.0 FK5 to galactic coordinates + + galeq -- call subroutine slgaeq (dl, db, dr, dd) + Galactic to J2000.0 FK5 coordinates +.fi +.ih +SUPERGALACTIC COORDINATES +.nf +galsup -- call subroutine slgasu (dl, db, dsl, dsb) + Galactic to supergalactic coordinates + +supgal -- call subroutine slsuga (dsl, dsb, dl, db) + Supergalactic to galactic coordinates +.fi +.ih +EPHEMERIDES +.nf + dmoon -- call subroutine sldmon (date, pv) + Approximate geocentric position and velocity of moon + + earth -- call subroutine slerth (iy, id, fd, pv) + Approximate heliocentric position and velocity of earth + + evp -- call subroutine slevp (date, deqx, dvb, dpb, dvh, dph) + Barycentric and heliocentric velocity and position of earth + + moon -- call subroutine slmoon (iy, id, fd, pv) + Approximate geocentric position and velocity of moon + +planet -- call subroutine slplnt (date, np, pv, jstat) + Approximate heliocentric position and velocity of planet + +rdplan -- call subroutine slrdpl (date, np, elong, phi, ra, dec, diam) + Approximate topocentric apparent place of a planet + +planel -- call subroutine slplnl (date, jform, epoch, orbinc, anode, + perih, aorg, e, aorl, dm, pv, jstat) + Approximate heliocentric position and velocity of planet + +plante -- call subroutine slplte (date, elong, phi, jform, epoch, orbinc, + anode, perih, aorq, e, aorl, dm, ra, dec, r, jstat) + Approximate topocentric apparent place of a planet + + pv2el -- call subroutine slpvel (pv, date, pmass, jformr, jform, epoch, + orbinc, anode, perih, aorg, e, aorl, dm, jstat) + Convert J2000 position and velocity to equivalent osculating elements + + el2ue -- call subroutine slelue (date, jform, epoch, orbinc, anode, perih, + aorq, e, aorl, dm, u, jstat) + Convert conventional osculating orbital elements into universal + form. + + ue2el -- call subroutine slueel (u, jformr, jform, epoch, orbinc, anode, + perih, aorq, e, aorl, dm, jstat) + Convert universal elements into conventional heliocentric osculating + form. + + pv2ue -- call subroutine slpvue (pv, date, pmass, u, jstat) + Construct a universal element set based on instantaneous position + and velocity. + + ue2pv -- call subroutine sluepv (date, u, pv, jstat) + Compute heliocentric position and velocity of a planet, asteroid, or + comet, starting from orbital elements in the "universal variables" + form. + +pertel -- call subroutine slprtl (jform, date0, date1, epoch0, epoch1, + orbi0, anode0, perih0, aorq0, e0, am0, epoch1, orbi1, anode1, + perih1, aorq1m e1, am1, jstat) + Update the osculating elements of a comet or asteroid by applying + planetary perturbations. + +pertue -- call subroutine slprue (date, u, jstat) + Update universal elements of a comet or asteroid by applying planetary + perturbations. +.fi +.ih +RADIAL VELOCITIES +rverot -- s = slrver (phi, ra, da, st) + Velocity component due to rotation of the earth + + ecor -- call subroutine slecor (rm, dm, iy, id, fd, rv, tl) + Components of velocity and light time due to earth orbital motion + +rvlsrd -- r = slrvld (r2000, d2000) + Velocity component due to solar motion wrt dynamical LSR + +rvlsrk -- r = slrvlk (r2000, d2000) + Velocity component due to solar motion wrt kinematical LSR + +rvgalc -- r = slrvga (r2000, d2000) + Velocity component due to rotation of the Galaxy + + rvlg -- r = slrvlg (r2000, d2000) + Velocity component due to rotation and translation of the Galaxy, + relative to the mean motion of the local group +.fi +.ih +ASTROMETRY +.nf + s2tp -- call subroutine sls2tp (ra, dec, raz, decz, xi, eta, j) + ds2tp -- call subroutine sldstp (ra, dec, raz, decz, xi, eta, j) + Transform spherical into tangent plane coordinates + + v2tp -- call subroutine slv2tp (v, v0, xi, eta, j) + dv2tp -- call subroutine sldvtp (v, v0, xi, eta, j) + Transform [x,y,z] into tangent plane coordinates + + tp2s -- call subroutine sltp2s (xi, eta, raz, decz, ra, dec) + dtp2s -- call subroutine sldtps (xi, eta, raz, decz, ra, dec) + Transform tangent plane into spherical coordinates + + tp2v -- call subroutine sltp2v (xi, eta, v0, v) + dtp2v -- call subroutine sldtpv (xi, eta, v0, v) + Transform tangent plane coordinates into [x,y,z] + + tps2c -- call subroutine sltpsc (xi, eta, ra, dec, raz1, decz1, + raz2, decz2, n) +dtps2c -- call subroutine sldpsc (xi, eta, ra, dec, raz1, decz1, + raz2, decz2, n) + Get plate center from tangent plane and spherical coordinates + + tpv2c -- call subroutine sltpvc (xi, eta, v, v01, v02, n) +dtpv2c -- call subroutine sldpvc (xi, eta, v, v01, v02, n) + Get plate center from [x,y,x] and tangent plane coordinates + + pcd -- call subroutine slpcd (disco, x, y) + Apply pincushion/barrel distortion + + unpcd -- call subroutine slupcd (disco, x, y) + Remove pincushion/barrel distortion + + fitxy -- call subroutine slftxy (itype, np, xye, xym, coeffs, j) + Fit a linear model to relate two sets of [x,y] coordinates + + pxy -- call subroutine slpxy (np, xye, xym, coeffs, xyp, + xrms, yrms, rrms) + Compute predicted coordinates and residuals + + invf -- call subroutine slinvf (fwds, bkwds, j) + Invert a linear model + + xy2xy -- call subroutine slxyxy (x1, y1, coeffs, x2, y2) + Transform one set of [x,y] coordinates + + dcmpf -- call subroutine sldcmf (coeffs, xz, yz, xs, ys, perp, orient) + Decompose a linear fit into geometric parameters +.fi +.ih +NUMERICAL METHODS +.nf + smat -- call subroutine slsmat (n, a, y, d, jf, iw) + dmat -- call subroutine sldmat (n, a, y, d, jf, iw) + Matrix inversion and solution of simultaneous equations + + svd -- call subroutine slsvd (m, n, mp, np, a, w, v, work, jstat) + Singular value decomposition of a matrix + +svdsol -- call subroutine slsvds (m, n, mp, np, b, u, w, v, work, x) + Solution from a given vector plus SVD + +svdcov -- call subroutine slsvdc (n, np, nc, w, v, work, cvm) + Covariance matrix from SVD +.fi +.endhelp diff --git a/math/slalib/doc/slalib.hlp.sav b/math/slalib/doc/slalib.hlp.sav new file mode 100644 index 00000000..8da465cf --- /dev/null +++ b/math/slalib/doc/slalib.hlp.sav @@ -0,0 +1,591 @@ +.help slalib Nov95 "Immatch Package" +.ih +NAME +slalib -- Starlink library of positional astronomy routines + +.ih +DESCRIPTION +SLALIB is a library of Fortran 77 routines intended to make accurate +and reliable positional-astronomy applications easier to write. Most +SLALIB library routines are concerned with astronomical position and time, +but a number have wider trigonometrical, numerical or general applications. +SLALIB contains routines covering the following topics: 1) string +decoding and sexagesimal conversions, 2) angles, vectors and rotation +matrices, 3) calendars and timescales, 4) precession and nutation, 5) +proper motion, 6) FK4/5 and elliptic aberration, 7) geocentric coordinates, +8) apparent and observed place, 9) azimuth and elevation, 10) refraction +and air mass, 11) ecliptic, galactic, and supergalactic coordinates, +12) ephemerides, 13) astrometry, and 14) numerical methods. + +The labels and calling sequences of the SLALIB are listed below grouped +by function. To get more detailed help on any individual routine type +the help command followed by the label, e.g the command "help flotin" +will give detailed help on the subroutine slrfli. + +.ih +STRING DECODING +.nf + intin -- call subroutine slinti (string, nstrt, ireslt, jflag) + Convert free-format string into integer + +flotin -- call subroutine slrfli (string, nstrt, reslt, jflag) +dfltin -- call subroutine sldfli (string, nstrt, dreslt, jflag) + Convert free-format string into floating point number + + afin -- call subroutine slafin (string, iptr, a, j) + dafin -- call subroutine sldafn (string, iptr, a, j) + Convert free-format string from deg, armin, arcsec to radians +.fi +.ih +SEXAGESIMAL CONVERSIONS +.nf + ctf2d -- call subroutine slctfd (ihour, imin, sec, days, j) + dtf2d -- call subroutine sldtfd (ihour, imin, sec, days, j) + Hours, minutes, seconds to days + + cd2tf -- call subroutine slcdtf (ndp, days, sign, ihmsf) + dd2tf -- call subroutine slddtf (ndp, days, sign, ihmsf) + Days to hours, minutes, and seconds + + ctf2r -- call subroutine slctfr (ihour, imin, sec, rad, j) + dtf2r -- call subroutine sldtfr (ihour, imin, sec, rad, j) + Hours, minutes, seconds to radians + + cr2tf -- call subroutine slcrtf (ndp, angle, sign, ihmsf) + dr2tf -- call subroutine sldrtf (ndp, angle, sign, ihmsf) + Radians to hours, minutes, seconds + + caf2r -- call subroutine slcafr (ideg, iamin, asec, rad, j) + daf2r -- call subroutine sldafr (ideg, iamin, asec, rad, j) + Degrees, arcminutes, arcseconds to radians + + cr2af -- call subroutine slcraf (ndp, angle, sign, idmsf) + dr2af -- call subroutine sldraf (ndp, angle, sign, idmsf) + Radians to degrees, arcminutes, arcseconds +.fi +.ih +ANGLES, VECTORS AND ROTATION MATRICES +.nf + range -- r = slra1p (angle) +drange -- d = slda1p (angle) + Normalize angle into range [-pi,pi] + +ranorm -- r = slra2p (angle) +dranrm -- d = slda2p (angle) + Normalize angle into range [0,2pi] + + cs2c -- call subroutine slcs2c (a, b, v) + dcs2c -- call subroutine slds2c (a, b, v) + Spherical coordinates to [x,y,z] + + cc2s -- call subroutine slcc2s (v, a, b) + dcc2s -- call subroutine sldc2s (v, a, b) + [x,y,z] to spherical coordinates + + vdv -- r = slvdv (va, vb) + dvdv -- d = sldvdv (va, vb) + Scalar product of two 3-vectors + + vxv -- call subroutine slvxv (va, vb, vc) + dvxv -- call subroutine sldvxv (va, vb, vc) + Vector product of two 3-vectors + + vn -- call subroutine slvn (v, uv, vm) + dvn -- call subroutine sldvn (v, uv, vm) + Normalize a 3-vector also giving the modulus + + sep -- s = slsep (a1, b1, a2, b2) + dsep -- d = sldsep (a1, b1, a2, b2) + Angle between two points on a sphere + + bear -- s = slbear (a1, b1, a2, b2) + dbear -- d = sldber (a1, b1, a2, b2) + pav -- s = slpav (v1, v2) + dpav -- d = sldpav (v1, v2) + Direction of one point on a sphere seen from another + + euler -- call subroutine sleulr (order, phi, theta, psi, rmat) +deuler -- call subroutine sldeul (order, phi, theta, psi, rmat) + Form form rotation matrix from three Euler angles + + + av2m -- call subroutine slav2m (axvec, rmat) + dav2m -- call subroutine sldavm (axvec, rmat) + Form rotation matrix from axial vector + + m2av -- call subroutine slm2av (rmat, axvec) + dm2av -- call subroutine sldmav (rmat, axvec) + Determine axial vector from rotation matrix + + dmxv -- call subroutine sldmxv (dm, va, vb) + mxv -- call subroutine slmxv (rm, va, vb) + Rotate vector forwards + + imxv -- call subroutine slimxv (rm, va, vb) + dimxv -- call subroutine sldimv (dm, va, vb) + Rotate vector backwards + + dmxm -- call subroutine sldmxm (a, b, c) + mxm -- call subroutine slmxm (a, b, c) + Product of two 3X3 matrices + + cs2c6 -- call subroutine sls2c6 (a, b, r, ad, bd, rd, v) + ds2c6 -- call subroutine sldsc6 (a, b, r, ad, bd, rd, v) + Conversion of position/velocity from spherical to Cartesian + coordinates + + cc62s -- call subroutine slc62s (v, a, b, r, ad, bd, rd) + dc62s -- call subroutine sldc6s (v, a, b, r, ad, bd, rd) + Conversion of position/velocity from Cartesian to spherical + coordinates +.fi +.ih +CALENDARS +.nf + cldj -- call subroutine slcadj (iy, im, id, djm, j) + Gregorian calendar to Modified Julian Date + + caldj -- call subroutine slcadj (iy, im, id, djm, j) + Gregorian calendar to Modified Julian Date, permitting century by + default + + djcal -- call subroutine sldjca (ndp, djm, iymdf, j) + Modified Julian Date to Gregorian calendar, in a from convenient + for formatted output + + djcl -- call subroutine sldjcl (djm, iy, im, id, fd, j) + Modified Julian Date to Gregorian Year, Month, Day, Fraction + + calyd -- call subroutine slcayd (iy, im, id, ny, nd, j) + Calendar to year and day in year, permitting century default + + clyd -- call subroutine slclyd (iy, im, id, ny, nd, jstat) + Calendar to year and day in year + + epb -- d = slepb (date) + Modified Julian Date to Besselian Epoch + + epb2d -- d = sleb2d (epb) + Besselian epoch to Modified Julian Date + + epj -- d = slepj (date) + Modified Julian Date to Julian Epoch + + epj2d -- d = slej2d (epj) + Julian epoch to Modified Julian Date +.fi +.fi +.ih +TIMESCALES +.nf + gmst -- d = slgmst (ut1) + Conversion from Universal Time to siderial time + + gmsta -- d = slgmsa (date, ut) + Conversion from Universal Time to siderial time, rounding errors + minimized + + eqeqx -- d = sleqex (date) + Equation of the equinoxes + + dat -- d = sldat (utc) + Offset of Atomic Time from Coordinated Universal Time: + TAI - UTC + + dt -- d = sldt (epoch) + Approximate offset between dynamical time and universal time + + dtt -- d = sldtt (utc) + Offset of Terrestrial Time from Coordinated Universal Time: + TT - UTC + + rcc -- d = slrcc (tdb, ut1, wl, u, v) + Relativistic clock correction: TDB - TT +.fi +.ih +PRECESSION AND NUTATION +.nf + nut -- call subroutine slnut (date, rmatn) + Nutation matrix + + nutc -- call subroutine slnutc (date, dpsi, deps, eps0) + Longitude and obliquity components of nutation, mean obliquity + + prec -- call subroutine slprec (ep0, ep1, rmatp) + Precession matrix (IAU) + + precl -- call subroutine slprel (ep0, ep1, rmatp) + Precession matrix (suitable for long periods) + +prenut -- call subroutine slprnu (epoch, date, rmatpn) + Combined precession/nutation matrix + + prebn -- call subroutine slprbn (bep0, bep1, rmatp) + Precession matrix (old system) + +preces -- call subroutine slprce (system, ep0, ep1, ra, dc) + Precession in either the old or new system, character string + ep0 and ep1 + +precss -- call subroutine slprcs (system, ep0, ep1, ra, dc) + Precession in either the old or new system, integer ep0 and ep1 +.fi +.fi +.ih +PROPER MOTION +.nf + pm -- call subroutine slpm (r0, d0, pr, pd, px, rv, ep0, ep1, r1, d1) + Adjust for proper motion +.fi +.ih +FK4/5/ICRS CONVERSIONS +.nf + fk425 -- call subroutine slfk45 (r1950, d1950, dr1950, dd1950, + p1950, v1950, r2000, d2000, dr2000, dd2000, p2000, v2000) + Convert B1950.0 FK4 star data to J2000.0 FK5 + + fk45z -- call subroutine slf45z (r1950, d1950, bepoch, r2000, d2000) + Convert B1950.0 FK4 position to J2000.0 FK5 assuming zero proper + motion in an inertial frame and no parallax + + fk524 -- call subroutine slfk54 (r2000, d2000, dr2000, dd2000, + p2000, v2000, r1950, d1950, dr1950, dd1950, p1950, v1950) + Convert J2000.0 FK5 star data to B1950.0 FK4 + + fk54z -- call subroutine slf54z (r2000, d2000, bepoch, r1950, d1950, + dr1950, dd1950) + Convert J2000.0 FK5 star data to B1950.0 FK4 assuming zero proper + motion in an inertial frame and no parallax + + fk52h -- call subroutine slfk5h (r5, d5, dr5, dd5, rh, dh, drh, ddh) + Convert J2000.0 FK5 star data to ICRS J2000.0 data + + fk5hz -- call subroutine slf5hz (r5, d5, epoch, rh, dh) + Convert J2000.0 FK5 star data to ICRS J2000.0 data assuming + no Hipparcos proper motion. + + h2fk5 -- call subroutine slhfk5 (rh, dh, drh, ddh, r5, d5, dr5, dd5) + Convert ICRS J2000.0 data to J2000.0 Fk5 star data. + + hfk5z -- call subroutine slhf5z (rh, dh, epoch, r5, d5) + Convert ICRS J2000.0 data to J2000.0 Fk5 star data assuming no + Hipparchos proper motion. + + dbjin -- call subroutine sldbji (string, nstrt, dreslt, j1, j2) + Like dfltin but with extensions to accept leading 'B' and 'J' + + kbj -- call subroutine slkbj (jb, e, k, j) + Select epoch prefix 'B' or 'J' + + epco -- d = slepco (k0, k, e) + Convert an epoch into the appropriate form 'B' or 'J' +.fi +.ih +ELLIPTIC ABERRATIONS +.nf + etrms -- call subroutine sletrm (ep, ev) + E-terms + + subet -- call subroutine slsuet (rc, dc, eq, rm, dm) + Remove the E-terms + + addet -- call subroutine sladet (rm, dm, eq, rc, dc) + Add the E-terms +.fi +.ih +GEOCENTRIC COORDINATES +.nf + obs -- call subroutine slobs (n, c, name, w, p, h) + Interrogate list of observatory parameters + + geoc -- call subroutine slgeoc (p, h, r, z) + Convert geodetic position to geocentric + + pvobs -- call subroutine slpvob (p, h, stl, pv) + Position and velocity of observatory +.fi +.ih +APPARENT AND OBSERVED PLACE +.nf + map -- call subroutine slmap (rm, dm, pr, pd, px, rv, eq, date, ra, da) + Mean place to geocentric apparent place + + mappa -- call subroutine slmapa (eq, date, amprms) + Precompute mean to apparent parameters + + mapqk -- call subroutine slmapq (rm, dm, pr, pd, px, rv, amprms, ra, da) + Mean to apparent place using precomputed parameters + +mapqkz -- call subroutine slmapz (rm, dm, amprms, ra, da) + Mean to apparent place using precomputed parameters, for zero + proper motion, parallax, and radial velocity + + amp -- call subroutine slamp (ra, da, date, eq, rm, dm) + Geocentric apparent place to mean place + + ampqk -- call subroutine slampq (ra, da, amprms, rm, dm) + Apparent to mean place using precomputed parameters + + aop -- call subroutine slaop (rap, dap, date, dut, elongm, phim, hm, + xp, yp, tdk, pmb, rh, wl, tlr, aob, zob, hob, dob, rob) + Apparent place to observed place + + aoppa -- call subroutine slaopa (date, dut, elongm, phim, hm, xy, yp, + tdk, pmb, rh, wl, tlr, aoprms) + Precompute apparent to observed parameters + +aoppat -- call subroutine slaopt (date, aoprms) + Update siderial time in apparent to observed parameters + + aopqk -- call subroutine slaopq (rap, dap, aoprms, aob, zob, hob, dob, rob) + Apparent to observed using precomputed parameters + + oap -- call subroutine sloap (type, ob1, ob2, date, dut, elongm, phim, + xp, yp, tdk, pmb, rh, wl, tlr, rap, dap) + Observed to apparent + + oapqk -- call subroutine sloapq (type, ob1, ob2, aoprms, rap, dap) + Observed to apparent using precomputed parameters + + polmo -- call subroutine slplmo (elongim, phim, xp, yp, elong, phi, daz) + Correct site longitude and latitude for polar motion +.fi +.ih +AZIMUTH AND ELEVATION +.nf + altaz -- call subroutine slalaz (ha, dec, phi, + Positions, velocities, etc. for an altazimuth mount + + e2h -- call subroutine sle2h (ha, dec, phi, az, el) + de2h -- call subroutine slde2h (ha, dec, phi, az, el) + Hour angle and declination to azimuth and elevation + + h2e -- call subroutine slh2e (az, el, phi, ha, dec) + dh2e -- call subroutine sldh2e (az, el, phi, ha, dec) + Azimuth and elevation to hour angle and declination + + pda2h -- call subroutine slpdah (p, d, a, h1, j1, h2, j2) + Hour angle corresponding to a given azimuth + + pdq2h -- call subroutine slpdqh (p, d, q, h1, j1, h2, j2) + Hour angle corresponding to a given parallactic angle + + pa -- d = slpa (ha, dec, phi) + Hour angle and declination to parallactic angle + + zd -- d = slzd (ha, dec, phi) + Hour angle and declination to zenith distance +.fi +.ih +REFRACTION AND AIR MASS +.nf + refro -- call subroutine slrfro (zobs, hm, tdk, pmb, rh, wl, phi, tlr, + eps, ref) + Change in zenith distance due to refraction + + refco -- call subroutine slrfco (hm, tdk, pmb, rh, wl, phi, tlr, eps, + refa, refb) + Constants for simple refraction model + +refcoq -- call subroutine slrfcq (tdk, pmb, rl, wl, refa, refb) + Constants for simple refraction model (quick version) + +atmdsp -- call subroutine slatmd (tdk, pmb, rh, wl1, a1, b1, wl2, a2, b2) + Adjust refraction constants for color + + refz -- call subroutine slrefz (zu, refa, refb, zr) + Unrefracted to refracted zenith distance, simple model + + refv -- call subroutine slrefv (vu, refa, refb, vr) + Unrefracted to refracted azimuth and elevation, simple model + +airmas -- d = slarms (zd) + Air mass +.fi +.ih +ECLIPTIC COORDINATES +.nf + ecmat -- call subroutine slecma (date, rmat) + Equatorial to ecliptic rotation matrix + + eqecl -- call subroutine sleqec (dr, dd, date, dl, db) + J2000.0 FK5 to ecliptic coordinates + + ecleq -- call subroutine sleceq (dl, db, date, dr, dd) + Ecliptic to J2000.0 FK5 coordinates +.fi +.ih +GALACTIC COORDINATES +.nf + eg50 -- call subroutine sleg50 (dr, dd, dl, db) + B1950.0 FK4 to galactic coordinates + + ge50 -- call subroutine slge50 (dl, db, dr, dd) + Galactic to B1950.0 FK4 coordinates + + eqgal -- call subroutine sleqga (dr, dd, dl, db) + J2000.0 FK5 to galactic coordinates + + galeq -- call subroutine slgaeq (dl, db, dr, dd) + Galactic to J2000.0 FK5 coordinates +.fi +.ih +SUPERGALACTIC COORDINATES +.nf +galsup -- call subroutine slgasu (dl, db, dsl, dsb) + Galactic to supergalactic coordinates + +supgal -- call subroutine slsuga (dsl, dsb, dl, db) + Supergalactic to galactic coordinates +.fi +.ih +EPHEMERIDES +.nf + dmoon -- call subroutine sldmon (date, pv) + Approximate geocentric position and velocity of moon + + earth -- call subroutine slerth (iy, id, fd, pv) + Approximate heliocentric position and velocity of earth + + evp -- call subroutine slevp (date, deqx, dvb, dpb, dvh, dph) + Barycentric and heliocentric velocity and position of earth + + moon -- call subroutine slmoon (iy, id, fd, pv) + Approximate geocentric position and velocity of moon + +planet -- call subroutine slplnt (date, np, pv, jstat) + Approximate heliocentric position and velocity of planet + +rdplan -- call subroutine slrdpl (date, np, elong, phi, ra, dec, diam) + Approximate topocentric apparent place of a planet + +planel -- call subroutine slplnl (date, jform, epoch, orbinc, anode, + perih, aorg, e, aorl, dm, pv, jstat) + Approximate heliocentric position and velocity of planet + +plante -- call subroutine slplte (date, elong, phi, jform, epoch, orbinc, + anode, perih, aorq, e, aorl, dm, ra, dec, r, jstat) + Approximate topocentric apparent place of a planet + + pv2el -- call subroutine slpvel (pv, date, pmass, jformr, jform, epoch, + orbinc, anode, perih, aorg, e, aorl, dm, jstat) + Convert J2000 position and velocity to equivalent osculating elements + + el2ue -- call subroutine slelue (date, jform, epoch, orbinc, anode, perih, + aorq, e, aorl, dm, u, jstat) + Convert conventional osculating orbital elements into universal + form. + + ue2el -- call subroutine slueel (u, jformr, jform, epoch, orbinc, anode, + perih, aorq, e, aorl, dm, jstat) + Convert universal elements into conventional heliocentric osculating + form. + + pv2ue -- call subroutine slpvue (pv, date, pmass, u, jstat) + Construct a universal element set based on instantaneous position + and velocity. + + ue2pv -- call subroutine sluepv (date, u, pv, jstat) + Compute heliocentric position and velocity of a planet, asteroid, or + comet, starting from orbital elements in the "universal variables" + form. + +pertel -- call subroutine slprtl (jform, date0, date1, epoch0, epoch1, + orbi0, anode0, perih0, aorq0, e0, am0, epoch1, orbi1, anode1, + perih1, aorq1m e1, am1, jstat) + Update the osculating elements of a comet or asteroid by applying + planetary perturbations. + +pertue -- call subroutine slprue (date, u, jstat) + Update universal elements of a comet or asteroid by applying planetary + perturbations. +.fi +.ih +RADIAL VELOCITIES +rverot -- s = slrver (phi, ra, da, st) + Velocity component due to rotation of the earth + + ecor -- call subroutine slecor (rm, dm, iy, id, fd, rv, tl) + Components of velocity and light time due to earth orbital motion + +rvlsrd -- r = slrvld (r2000, d2000) + Velocity component due to solar motion wrt dynamical LSR + +rvlsrk -- r = slrvlk (r2000, d2000) + Velocity component due to solar motion wrt kinematical LSR + +rvgalc -- r = slrvga (r2000, d2000) + Velocity component due to rotation of the Galaxy + + rvlg -- r = slrvlg (r2000, d2000) + Velocity component due to rotation and translation of the Galaxy, + relative to the mean motion of the local group +.fi +.ih +ASTROMETRY +.nf + s2tp -- call subroutine sls2tp (ra, dec, raz, decz, xi, eta, j) + ds2tp -- call subroutine sldstp (ra, dec, raz, decz, xi, eta, j) + Transform spherical into tangent plane coordinates + + v2tp -- call subroutine slv2tp (v, v0, xi, eta, j) + dv2tp -- call subroutine sldvtp (v, v0, xi, eta, j) + Transform [x,y,z] into tangent plane coordinates + + tp2s -- call subroutine sltp2s (xi, eta, raz, decz, ra, dec) + dtp2s -- call subroutine sldtps (xi, eta, raz, decz, ra, dec) + Transform tangent plane into spherical coordinates + + tp2v -- call subroutine sltp2v (xi, eta, v0, v) + dtp2v -- call subroutine sldtpv (xi, eta, v0, v) + Transform tangent plane coordinates into [x,y,z] + + tps2c -- call subroutine sltpsc (xi, eta, ra, dec, raz1, decz1, + raz2, decz2, n) +dtps2c -- call subroutine sldpsc (xi, eta, ra, dec, raz1, decz1, + raz2, decz2, n) + Get plate center from tangent plane and spherical coordinates + + tpv2c -- call subroutine sltpvc (xi, eta, v, v01, v02, n) +dtpv2c -- call subroutine sldpvc (xi, eta, v, v01, v02, n) + Get plate center from [x,y,x] and tangent plane coordinates + + pcd -- call subroutine slpcd (disco, x, y) + Apply pincushion/barrel distortion + + unpcd -- call subroutine slupcd (disco, x, y) + Remove pincushion/barrel distortion + + fitxy -- call subroutine slftxy (itype, np, xye, xym, coeffs, j) + Fit a linear model to relate two sets of [x,y] coordinates + + pxy -- call subroutine slpxy (np, xye, xym, coeffs, xyp, + xrms, yrms, rrms) + Compute predicted coordinates and residuals + + invf -- call subroutine slinvf (fwds, bkwds, j) + Invert a linear model + + xy2xy -- call subroutine slxyxy (x1, y1, coeffs, x2, y2) + Transform one set of [x,y] coordinates + + dcmpf -- call subroutine sldcmf (coeffs, xz, yz, xs, ys, perp, orient) + Decompose a linear fit into geometric parameters +.fi +.ih +NUMERICAL METHODS +.nf + smat -- call subroutine slsmat (n, a, y, d, jf, iw) + dmat -- call subroutine sldmat (n, a, y, d, jf, iw) + Matrix inversion and solution of simultaneous equations + + svd -- call subroutine slsvd (m, n, mp, np, a, w, v, work, jstat) + Singular value decomposition of a matrix + +svdsol -- call subroutine slsvds (m, n, mp, np, b, u, w, v, work, x) + Solution from a given vector plus SVD + +svdcov -- call subroutine slsvdc (n, np, nc, w, v, work, cvm) + Covariance matrix from SVD +.fi +.endhelp diff --git a/math/slalib/doc/slalib.men b/math/slalib/doc/slalib.men new file mode 100644 index 00000000..2288c0aa --- /dev/null +++ b/math/slalib/doc/slalib.men @@ -0,0 +1,179 @@ + addet - add the E-terms to a pre IAU 1976 mean place + afin - convert a sexagesimal character string to radians (s.p.) + airmas - compute the airmass at a given zenith distance + altaz - compute altazimuth positions, velocities, accelerations + amp - convert a geocentric apparent to post IAU 1976 mean place + ampqk - convert a geocentric apparent to post IAU 1976 mean place + aop - convert an apparent to observed place + aoppa - pre-compute the set of apparent to observed place parameters + aoppat - recompute the apparent to observed place sidereal time parameter + aopqk - convert an apparent to observed place + atmdsp - apply atmospheric dispersion terms to refraction coefficients + av2m - compute a rotation matrix from an axial vector (s.p.) + bear - compute the bearing of a point on a sphere w.r.t. another + caf2r - convert degrees, arcminutes, and arcseconds to radians + caldj - convert a Gregorian calendar date to a modified Julian date + calyd - convert a Gregorian calendar date to a Julian calendar year, day + cc2s - convert Cartesian to spherical coordinates (s.p.) + cc62s - convert a 6-vector from Cartesian to spherical coordinates + cd2tf - convert an interval in days to hours, minutes, and seconds + cldj - convert a Gregorian calendar date to a modified Julian date + clyd - convert a Gregorian calendar date a Julian calendar year, day + cr2af - convert radians to degrees, arcminutes, and arcseconds + cr2tf - convert radians to hours, minutes, and seconds + cs2c - convert spherical to Cartesian coordinates (s.p.) + cs2c6 - convert spherical position/velocity to Cartesian coordinates + ctf2d - convert hours, minutes, and seconds to days + ctf2r - convert hours, minutes, and seconds to radians + daf2r - convert degrees, arcminutes, and arcseconds to radians (d.p) + dafin - convert a sexagesimal character string to radians (d.p.) + dat - compute difference between TAI and UTC in seconds + dav2m - compute a rotation matrix from an axial vector (d.p) + dbear - compute the bearing of a point on a sphere w.r.t. another (d.p.) + dbjin - convert a character string to a Besselian/Julian epoch + dc62s - convert Cartesian position/velocity to spherical coordinates (d.p.) + dcc2s - convert Cartesian to spherical coordinates (d.p) + dcmpf - convert linear fit coefficients to geometric parameters + dcs2c - convert spherical to Cartesian coordinates (d.p) + dd2tf - convert interval in days to hours, minutes, and seconds (d.p.) + de2h - convert hour angle and declination to azimuth and elevation (d.p.) + deuler - convert Euler angles to a rotation matrix (d.p.) + dfltin - convert a character string to a floating point number (d.p.) + dh2e - convert azimuth and elevation to hour angle and declination (d.p.) + dimxv - apply a 3D reverse rotation to a 3-vector (d.p.) + djcal - convert an MJD to a Gregorian calendar date + djcl - convert an MJD to a Gregorian year, month, and day + dm2av - convert a rotation matrix to an axial vector (d.p) + dmat - solve a set of simultaneous equations (d.p.) + dmoon - compute approximate geocentric position/velocity of moon (d.p.) + dmxm - compute the product of two 3X3 matrices (d.p.) + dmxv - multiple a 3-vector by a rotation matrix (d.p.) + dpav - compute the bearing of a point on a sphere w.r.t. another (d.p.) + dr2af - convert radians to degrees, arcminutes, and arcseconds (d.p) + dr2tf - convert radians to hours, minutes, and seconds (d.p.) + drange - normalize an angle to the range -pi <= angle <= pi (d.p.) + dranrm - normalize an angle to the range 0 <= angle <= 2pi (d.p.) + ds2c6 - convert spherical position/velocity to Cartesian coordinates (d.p.) + ds2tp - project spherical coordinates onto the tangent plane (d.p) + dsep - compute the angle between two points on a sphere (d.p.) + dt - estimate the approximate difference between ET and UT in seconds + dtf2d - convert hours, minutes, and seconds to days (d.p) + dtf2r - convert hours, minutes, and seconds to radians (d.p.) + dtp2s - convert tangent plane to spherical coordinates (d.p.) + dtp2v - convert tangent plane coordinates to direction cosines (d.p.) + dtps2c - compute the spherical coordinates of the tangent point (d.p.) + dtpv2c - compute the direction cosines of the tangent point (d.p.) + dtt - compute the difference between TT and UTC in seconds + dv2tp - convert direction cosines to tangent plane coordinates (d.p) + dvdv - compute the scalar product of 2 3-vectors (d.p.) + dvn - normalize a 3-vector and compute the modulus (d.p.) + dvxv - compute the vector product of 2 3-vectors (d.p.) + e2h - convert hour angle and declination to azimuth and elevation (d.p.) + earth - compute approximate heliocentric position/velocity of earth + ecleq - convert from ecliptic to equatorial FK5 coordinates + ecmat - compute the equatorial FK5 to ecliptic coordinates rotation matrix + ecor - compute rv of earth and time correction to sun in given direction + eg50 - convert equatorial FK4 to IAU 1958 galactic coordinates + el2ue - convert osculating orbital elements into universal form + epb - convert an MJD to a Besselian epoch + epb2d - convert a Besselian epoch to an MJD + epco - convert a Besselian/Julian epoch to match a given epoch + epj - convert an MJD to a Julian epoch + epj2d - convert a Julian epoch to an MJD + eqecl - convert equatorial FK5 to ecliptic coordinates + eqeqx - compute the equation of the equinoxes + eqgal - convert equatorial FK5 to IAU 1958 galactic coordinates + etrms - compute the E-terms vector + euler - convert Euler angles to a rotation matrix (s.p.) + evp - compute the barycentric/heliocentric velocity/position of earth + fitxy - fit a linear model to 2 sets of [x,y] coordinates + fk425 - convert equatorial FK4 to FK5 coordinates + fk45z - convert equatorial FK4 to FK5 coordinates excluding proper motion + fk524 - convert equatorial FK5 to FK4 coordinates + fk54z - convert equatorial FK5 to FK4 coordinates excluding proper motion + fk52h - convert equatorial FK5 to ICRS coordinates + fk5hz - Convert equatorial FK5 to ICRS coordinates (0 ICRS proper motions) + flotin - convert a character string to a floating point number + galeq - convert IAU 1958 galactic to equatorial FK5 coordinates + galsup - convert IAU 1958 galactic to deVaucouleurs supergalactic coordinates + ge50 - convert IAU 1958 galactic to equatorial FK4 coordinates + geoc - convert geodetic to geocentric position + gmst - convert from UT1 to GMST + gmsta - convert from UT1 to GMST while minimizing rounding errors + h2e - convert azimuth and elevation to hour angle and declination (s.p.) + h2fk5 - Convert equatorial ICRS to FK5 coordinates + hfk5z - Convert equatorial ICRS to FK5 coordinates (0 ICRS proper motions) + imxv - apply a 3D reverse rotation to a 3-vector (s.p.) + intin - convert a character string into an integer + invf - invert the linear model computed from 2 sets of [x,y] coordinates + kbj - select the epoch prefix B or J + m2av - convert a rotation matrix to an axial vector (s.p.) + map - convert a post IAU 1976 mean to geocentric apparent place + mappa - precompute the set of mean to geocentric apparent place parameters + mapqk - convert a post IAU 1976 mean to geocentric apparent place + mapqkz - convert a post IAU 1976 mean to geocentric apparent place + moon - compute approximate geocentric position/velocity of moon + mxm - compute the product of two 3X3 matrices (s.p.) + mxv - multiply a 3-vector by a rotation matrix (s.p.) + nut - compute the nutation matrix for a given date + nutc - compute the nutation components for a given date + oap - convert from observed to apparent place + oapqk - convert from observed to apparent place + obs - look up an entry in a list of groundbased observing stations + pa - compute the parallactic angle from the hour angle and declination + pav - compute the bearing of a point on a sphere w.r.t. another + pcd - apply pincushion/barrel distortion to tangent plane coordinates + pda2h - compute the hour angle corresponding to a given azimuth + pdq2h - compute the hour angle corresponding to a given parallactic angle + pertel - update osculating orbital elements by applying perturbations + pertue - update universal elements by applying perturbations + planel - compute the approximate heliocentric position/velocity of a planet + planet - compute the approximate heliocentric position/velocity of a planet + plante - compute approximate topocentric apparent position of a planet + pm - apply the correction for proper motion to a star + polmo - correct site longitude and latitude for polar motion + prebn - compute the FK4 matrix of precession between two epochs + prec - compute the FK5 matrix of precession between two epochs + preces - precess coordinates in either the FK4 or FK5 systems + precl - compute the longterm matrix of precession between two epochs + precss - precess coordinates in either the FK4 or FK5 systems + prenut - compute the FK5 matrix of precession and nutation + pv2el - convert J2000 position and velocity to osculating elements + pv2ue - convert instantaneous position and velocity to universal element set + pvobs - compute the geocentric position / velocity of an observing station + pxy - apply a linear model to a set of expected and measured [x,y] + range - normalize an angle to the range -pi <= angle <= pi (s.p.) + ranorm - normalize an angle to the range 0 <= angle <= 2pi (s.p.) + rcc - compute the difference between TDB and TT in seconds + rdplan - compute approximate topocentric apparent position of a planet + refco - compute the refraction coefficients + refcoq - compute the refraction coefficients (fast version) + refro - compute the atmospheric refraction for optical and radio wavelengths + refv - apply the refraction correction to a Cartesian 3-vector + refz - apply the refraction correction to a zenith distance + rverot - compute the earth rotation velocity component in a given direction + rvgalc - compute the dynamical LSR velocity component in a given direction + rvlg - compute the solar velocity component in a given direction + rvlsrd - compute the peculiar solar velocity component in a given direction + rvlsrk - compute the standard solar velocity component in a given direction + s2tp - project spherical coordinates onto the tangent plane (s.p.) + sep - compute the angle between two points on a sphere (s.p.) + smat - solve a set of simultaneous equations (s.p.) + subet - remove the E-terms from a pre IAU 1976 catalog position + supgal - convert deVaucouleurs supergalactic to IAU 1958 galactic coordinates + svd - compute the SVD factorization of a matrix + svdcov - compute the covariance matrix from the SVD factorization + svdsol - solve a set of simultaneous equations using SVD factorization + tp2s - convert tangent plane to spherical coordinates (s.p.) + tp2v - convert tangent plane coordinates to direction cosines (s.p.) + tps2c - compute the spherical coordinates of the tangent point (s.p.) + tpv2c - compute the direction cosines of the tangent point (s.p.) + ue2el - convert universal elements into heliocentric osculating elements + ue2pv - compute heliocentric position and velocity from universal form + unpcd - remove pincushion/barrel distortion from distorted coordinates + v2tp - convert direction cosines to tangent plane coordinates (s.p.) + vdv - convert the scale production of two 3-vectors (s.p.) + vn - normalize a 3-vector and compute the modulus (s.p.) + vxv - compute the vector product of two 3-vectors (s.p.) + xy2xy - apply a computed linear model to a set of [x,y] + zd - convert hour angle and declination to zenith distance diff --git a/math/slalib/doc/smat.hlp b/math/slalib/doc/smat.hlp new file mode 100644 index 00000000..ad2b1f2d --- /dev/null +++ b/math/slalib/doc/smat.hlp @@ -0,0 +1,60 @@ +.help smat Jun99 "Slalib Package" +.nf + + SUBROUTINE slSMAT (N, A, Y, D, JF, IW) + + - - - - - + S M A T + - - - - - + + Matrix inversion & solution of simultaneous equations + (single precision) + + For the set of n simultaneous equations in n unknowns: + A.Y = X + + where: + A is a non-singular N x N matrix + Y is the vector of N unknowns + X is the known vector + + SMATRX computes: + the inverse of matrix A + the determinant of matrix A + the vector of N unknowns + + Arguments: + + symbol type dimension before after + + N int no. of unknowns unchanged + A real (N,N) matrix inverse + Y real (N) vector solution + D real - determinant + * JF int - singularity flag + IW int (N) - workspace + + * JF is the singularity flag. If the matrix is non-singular, + JF=0 is returned. If the matrix is singular, JF=-1 & D=0.0 are + returned. In the latter case, the contents of array A on return + are undefined. + + Algorithm: + Gaussian elimination with partial pivoting. + + Speed: + Very fast. + + Accuracy: + Fairly accurate - errors 1 to 4 times those of routines optimized + for accuracy. + + Note: replaces the obsolete slSMATRX routine. + + P.T.Wallace Starlink 10 September 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/subet.hlp b/math/slalib/doc/subet.hlp new file mode 100644 index 00000000..42d74ccf --- /dev/null +++ b/math/slalib/doc/subet.hlp @@ -0,0 +1,41 @@ +.help subet Jun99 "Slalib Package" +.nf + + SUBROUTINE slSUET (RC, DC, EQ, RM, DM) + + - - - - - - + S U E T + - - - - - - + + Remove the E-terms (elliptic component of annual aberration) + from a pre IAU 1976 catalogue RA,Dec to give a mean place + (double precision) + + Given: + RC,DC dp RA,Dec (radians) with E-terms included + EQ dp Besselian epoch of mean equator and equinox + + Returned: + RM,DM dp RA,Dec (radians) without E-terms + + Called: + slETRM, slDS2C, sla_,DVDV, slDC2S, slDA2P + + Explanation: + Most star positions from pre-1984 optical catalogues (or + derived from astrometry using such stars) embody the + E-terms. This routine converts such a position to a + formal mean place (allowing, for example, comparison with a + pulsar timing position). + + Reference: + Explanatory Supplement to the Astronomical Ephemeris, + section 2D, page 48. + + P.T.Wallace Starlink 10 May 1990 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/sun67.tex b/math/slalib/doc/sun67.tex new file mode 100644 index 00000000..3e586f5e --- /dev/null +++ b/math/slalib/doc/sun67.tex @@ -0,0 +1,12311 @@ +\documentclass[11pt,twoside]{article} +\setcounter{tocdepth}{2} +\pagestyle{myheadings} + +% ----------------------------------------------------------------------------- +% ? Document identification +\newcommand{\stardoccategory} {Starlink User Note} +\newcommand{\stardocinitials} {SUN} +\newcommand{\stardocsource} {sun67.44} +\newcommand{\stardocnumber} {67.44} +\newcommand{\stardocauthors} {P.\,T.\,Wallace} +\newcommand{\stardocdate} {29 April 1999} +\newcommand{\stardoctitle} {SLALIB --- Positional Astronomy Library} +\newcommand{\stardocversion} {2.3-0} +\newcommand{\stardocmanual} {Programmer's Manual} +% ? End of document identification + +%%% Also see \nroutines definition later %%% + +% ----------------------------------------------------------------------------- + +\newcommand{\stardocname}{\stardocinitials /\stardocnumber} +\markright{\stardocname} +\setlength{\textwidth}{160mm} +\setlength{\textheight}{230mm} +\setlength{\topmargin}{-2mm} +\setlength{\oddsidemargin}{0mm} +\setlength{\evensidemargin}{0mm} +\setlength{\parindent}{0mm} +\setlength{\parskip}{\medskipamount} +\setlength{\unitlength}{1mm} + +% ----------------------------------------------------------------------------- +% Hypertext definitions. +% ====================== +% These are used by the LaTeX2HTML translator in conjunction with star2html. + +% Comment.sty: version 2.0, 19 June 1992 +% Selectively in/exclude pieces of text. +% +% Author +% Victor Eijkhout <eijkhout@cs.utk.edu> +% Department of Computer Science +% University Tennessee at Knoxville +% 104 Ayres Hall +% Knoxville, TN 37996 +% USA + +% Do not remove the %\begin{rawtex} and %\end{rawtex} lines (used by +% star2html to signify raw TeX that latex2html cannot process). +%\begin{rawtex} +\makeatletter +\def\makeinnocent#1{\catcode`#1=12 } +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} + +\def\ThrowAwayComment#1{\begingroup + \def\CurrentComment{#1}% + \let\do\makeinnocent \dospecials + \makeinnocent\^^L% and whatever other special cases + \endlinechar`\^^M \catcode`\^^M=12 \xComment} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xComment#1^^M{\def\test{#1} + \csarg\ifx{PlainEnd\CurrentComment Test}\test + \let\html@next\endgroup + \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test + \edef\html@next{\endgroup\noexpand\end{\CurrentComment}} + \else \let\html@next\xComment + \fi \fi \html@next} +} +\makeatother + +\def\includecomment + #1{\expandafter\def\csname#1\endcsname{}% + \expandafter\def\csname end#1\endcsname{}} +\def\excludecomment + #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}% + {\escapechar=-1\relax + \csarg\xdef{PlainEnd#1Test}{\string\\end#1}% + \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}% + }} + +% Define environments that ignore their contents. +\excludecomment{comment} +\excludecomment{rawhtml} +\excludecomment{htmlonly} +%\end{rawtex} + +% Hypertext commands etc. This is a condensed version of the html.sty +% file supplied with LaTeX2HTML by: Nikos Drakos <nikos@cbl.leeds.ac.uk> & +% Jelle van Zeijl <jvzeijl@isou17.estec.esa.nl>. The LaTeX2HTML documentation +% should be consulted about all commands (and the environments defined above) +% except \xref and \xlabel which are Starlink specific. + +\newcommand{\htmladdnormallinkfoot}[2]{#1\footnote{#2}} +\newcommand{\htmladdnormallink}[2]{#1} +\newcommand{\htmladdimg}[1]{} +\newenvironment{latexonly}{}{} +\newcommand{\hyperref}[4]{#2\ref{#4}#3} +\newcommand{\htmlref}[2]{#1} +\newcommand{\htmlimage}[1]{} +\newcommand{\htmladdtonavigation}[1]{} + +% Starlink cross-references and labels. +\newcommand{\xref}[3]{#1} +\newcommand{\xlabel}[1]{} + +% LaTeX2HTML symbol. +\newcommand{\latextohtml}{{\bf LaTeX}{2}{\tt{HTML}}} + +% Define command to re-centre underscore for Latex and leave as normal +% for HTML (severe problems with \_ in tabbing environments and \_\_ +% generally otherwise). +\newcommand{\latex}[1]{#1} +\newcommand{\setunderscore}{\renewcommand{\_}{{\tt\symbol{95}}}} +\latex{\setunderscore} + +% Redefine the \tableofcontents command. This procrastination is necessary +% to stop the automatic creation of a second table of contents page +% by latex2html. +\newcommand{\latexonlytoc}[0]{\tableofcontents} + +% ----------------------------------------------------------------------------- +% Debugging. +% ========= +% Remove % on the following to debug links in the HTML version using Latex. + +% \newcommand{\hotlink}[2]{\fbox{\begin{tabular}[t]{@{}c@{}}#1\\\hline{\footnotesize #2}\end{tabular}}} +% \renewcommand{\htmladdnormallinkfoot}[2]{\hotlink{#1}{#2}} +% \renewcommand{\htmladdnormallink}[2]{\hotlink{#1}{#2}} +% \renewcommand{\hyperref}[4]{\hotlink{#1}{\S\ref{#4}}} +% \renewcommand{\htmlref}[2]{\hotlink{#1}{\S\ref{#2}}} +% \renewcommand{\xref}[3]{\hotlink{#1}{#2 -- #3}} +% ----------------------------------------------------------------------------- +% ? Document specific \newcommand or \newenvironment commands. +%------------------------------------------------------------------------------ + +\newcommand{\nroutines} {181} +\newcommand{\radec} {$[\,\alpha,\delta\,]$} +\newcommand{\hadec} {$[\,h,\delta\,]$} +\newcommand{\xieta} {$[\,\xi,\eta\,]$} +\newcommand{\azel} {$[\,Az,El~]$} +\newcommand{\ecl} {$[\,\lambda,\beta~]$} +\newcommand{\gal} {$[\,l^{I\!I},b^{I\!I}\,]$} +\newcommand{\xy} {$[\,x,y\,]$} +\newcommand{\xyz} {$[\,x,y,z\,]$} +\newcommand{\xyzd} {$[\,\dot{x},\dot{y},\dot{z}\,]$} +\newcommand{\xyzxyzd} {$[\,x,y,z,\dot{x},\dot{y},\dot{z}\,]$} +\newcommand{\degree}[2] {$#1^{\circ} + \hspace{-0.37em}.\hspace{0.02em}#2$} + +\newcommand{\arcsec}[2] {\arcseci{#1}$\hspace{-0.4em}.#2$} +\begin{htmlonly} + \newcommand{\arcsec}[2] { + {$#1\hspace{-0.05em}^{'\hspace{-0.1em}'}\hspace{-0.4em}.#2$} + } +\end{htmlonly} + +\newcommand{\arcseci}[1] {$#1\hspace{-0.05em}$\raisebox{-0.5ex} + {$^{'\hspace{-0.1em}'}$}} +\begin{htmlonly} + \renewcommand{\arcseci}[1] {$#1\hspace{-0.05em}^{'\hspace{-0.1em}'}$} +\end{htmlonly} + +\newcommand{\dms}[4] {$#1^{\circ}\,#2\raisebox{-0.5ex} + {$^{'}$}\,$\arcsec{#3}{#4}} +\begin{htmlonly} + \renewcommand{\dms}[4]{$#1^{\circ}\,#2^{'}\,#3^{''}.#4$} +\end{htmlonly} + +\newcommand{\tseci}[1] {$#1$\mbox{$^{\rm s}$}} +\newcommand{\tsec}[2] {\tseci{#1}$\hspace{-0.3em}.#2$} +\begin{htmlonly} + \renewcommand{\tsec}[2] {$#1^{\rm s}\hspace{-0.3em}.#2$} +\end{htmlonly} + +\newcommand{\hms}[4] {$#1^{\rm h}\,#2^{\rm m}\,$\tsec{#3}{#4}} +\begin{htmlonly} + \renewcommand{\hms}[4] {$#1^{h}\,#2^{m}\,#3^{s}.#4$} +\end{htmlonly} + +\newcommand{\callhead}[1]{\goodbreak\vspace{\bigskipamount}{\large\bf{#1}}} +\newenvironment{callset}{\begin{list}{}{\setlength{\leftmargin}{2cm} + \setlength{\parsep}{\smallskipamount}}}{\end{list}} +\newcommand{\subp}[1]{\item\hspace{-1cm}#1\\} +\newcommand{\subq}[2]{\item\hspace{-1cm}#1\\\hspace*{-1cm}#2\\} +\newcommand{\name}[1]{\mbox{#1}} +\newcommand{\fortvar}[1]{\mbox{\em #1}} + +\newcommand{\routine}[3] +{\hbadness=10000 + \vbox + { + \rule{\textwidth}{0.3mm}\\ + {\Large {\bf #1} \hfill #2 \hfill {\bf #1}}\\ + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + #3 + \end{description} + \setlength{\topsep}{\oldspacing} + } +} + +% Replacement for HTML version (each routine in own subsection). +\begin{htmlonly} + \renewcommand{\routine}[3] + { + \subsection{#1\xlabel{#1} - #2\label{#1}} + \begin{description} + #3 + \end{description} + } +\end{htmlonly} + +\newcommand{\action}[1] +{\item[ACTION]: #1} + +\begin{htmlonly} + \newcommand{\action}[1] + {\item[ACTION:] #1} +\end{htmlonly} + +\newcommand{\call}[1] +{\item[CALL]: \hspace{0.4em}{\tt #1}} +\newlength{\oldspacing} + +\begin{htmlonly} + \renewcommand{\call}[1] + { + \item[CALL:] {\tt #1} + } +\end{htmlonly} + +\newcommand{\args}[2] +{ + \goodbreak + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + \item[#1]:\\[1.5ex] + \begin{tabular}{p{7em}p{6em}p{22em}} + #2 + \end{tabular} + \end{description} + \setlength{\topsep}{\oldspacing} +} +\begin{htmlonly} + \renewcommand{\args}[2] + { + \begin{description} + \item[#1:]\\ + \begin{tabular}{p{7em}p{6em}l} + #2 + \end{tabular} + \end{description} + } +\end{htmlonly} + +\newcommand{\spec}[3] +{ + {\em {#1}} & {\bf \mbox{#2}} & {#3} +} + +\newcommand{\specel}[2] +{ + \multicolumn{1}{c}{#1} & {} & {#2} +} + +\newcommand{\anote}[1] +{ + \goodbreak + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + \item[NOTE]: + #1 + \end{description} + \setlength{\topsep}{\oldspacing} +} + +\begin{htmlonly} + \renewcommand{\anote}[1] + { + \begin{description} + \item[NOTE:] + #1 + \end{description} + } +\end{htmlonly} + +\newcommand{\notes}[1] +{ + \goodbreak + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + \item[NOTES]: + #1 + \end{description} + \setlength{\topsep}{\oldspacing} +} + +\begin{htmlonly} + \renewcommand{\notes}[1] + { + \begin{description} + \item[NOTES:] + #1 + \end{description} + } +\end{htmlonly} + +\newcommand{\aref}[1] +{ + \goodbreak + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + \item[REFERENCE]: + #1 + \end{description} + \setlength{\topsep}{\oldspacing} +} + +\begin{htmlonly} + \newcommand{\aref}[1] + { + \begin{description} + \item[REFERENCE:] + #1 + \end{description} + } +\end{htmlonly} + +\newcommand{\refs}[1] +{ + \goodbreak + \setlength{\oldspacing}{\topsep} + \setlength{\topsep}{0.3ex} + \begin{description} + \item[REFERENCES]: + #1 + \end{description} + \setlength{\topsep}{\oldspacing} +} +\begin{htmlonly} + \newcommand{\refs}[1] + { + \begin{description} + \item[REFERENCES:] + #1 + \end{description} + } +\end{htmlonly} + +\newcommand{\exampleitem}{\item [EXAMPLE]:} +\begin{htmlonly} + \renewcommand{\exampleitem}{\item [EXAMPLE:]} +\end{htmlonly} + +%------------------------------------------------------------------------------ +% ? End of document specific commands +% ----------------------------------------------------------------------------- +% Title Page. +% =========== +\renewcommand{\thepage}{\roman{page}} +\begin{document} +\thispagestyle{empty} + +% Latex document header. +% ====================== +\begin{latexonly} + CCLRC / {\sc Rutherford Appleton Laboratory} \hfill {\bf \stardocname}\\ + {\large Particle Physics \& Astronomy Research Council}\\ + {\large Starlink Project\\} + {\large \stardoccategory\ \stardocnumber} + \begin{flushright} + \stardocauthors\\ + \stardocdate + \end{flushright} + \vspace{-4mm} + \rule{\textwidth}{0.5mm} + \vspace{5mm} + \begin{center} + {\Huge\bf \stardoctitle \\ [2.5ex]} + {\LARGE\bf \stardocversion \\ [4ex]} + {\Huge\bf \stardocmanual} + \end{center} + \vspace{5mm} + +% ? Heading for abstract if used. + \vspace{10mm} + \begin{center} + {\Large\bf Abstract} + \end{center} +% ? End of heading for abstract. +\end{latexonly} + +% HTML documentation header. +% ========================== +\begin{htmlonly} + \xlabel{} + \begin{rawhtml} <H1> \end{rawhtml} + \stardoctitle\\ + \stardocversion\\ + \stardocmanual + \begin{rawhtml} </H1> \end{rawhtml} + +% ? Add picture here if required. +% ? End of picture + + \begin{rawhtml} <P> <I> \end{rawhtml} + \stardoccategory \stardocnumber \\ + \stardocauthors \\ + \stardocdate + \begin{rawhtml} </I> </P> <H3> \end{rawhtml} + \htmladdnormallink{CCLRC}{http://www.cclrc.ac.uk} / + \htmladdnormallink{Rutherford Appleton Laboratory} + {http://www.cclrc.ac.uk/ral} \\ + \htmladdnormallink{Particle Physics \& Astronomy Research Council} + {http://www.pparc.ac.uk} \\ + \begin{rawhtml} </H3> <H2> \end{rawhtml} + \htmladdnormallink{Starlink Project}{http://star-www.rl.ac.uk/} + \begin{rawhtml} </H2> \end{rawhtml} + \htmladdnormallink{\htmladdimg{source.gif} Retrieve hardcopy} + {http://star-www.rl.ac.uk/cgi-bin/hcserver?\stardocsource}\\ + +% HTML document table of contents. +% ================================ +% Add table of contents header and a navigation button to return to this +% point in the document (this should always go before the abstract \section). + \label{stardoccontents} + \begin{rawhtml} + <HR> + <H2>Contents</H2> + \end{rawhtml} + \renewcommand{\latexonlytoc}[0]{} + \htmladdtonavigation{\htmlref{\htmladdimg{contents_motif.gif}} + {stardoccontents}} + +% ? New section for abstract if used. + \section{\xlabel{abstract}Abstract} +% ? End of new section for abstract +\end{htmlonly} + +% ----------------------------------------------------------------------------- +% ? Document Abstract. (if used) +% ================== +SLALIB is a library used by writers of positional-astronomy applications. +Most of the \nroutines\ routines are concerned with astronomical position and time, +but a number have wider trigonometrical, numerical or general applications. +% ? End of document abstract +% ----------------------------------------------------------------------------- +% ? Latex document Table of Contents (if used). +% =========================================== + \newpage + \begin{latexonly} + \setlength{\parskip}{0mm} + \latexonlytoc + \setlength{\parskip}{\medskipamount} + \markright{\stardocname} + \end{latexonly} +% ? End of Latex document table of contents +% ----------------------------------------------------------------------------- +\newpage +\renewcommand{\thepage}{\arabic{page}} +\setcounter{page}{1} + +\section{INTRODUCTION} +\subsection{Purpose} +SLALIB\footnote{The name isn't an acronym; +it just stands for ``Subprogram Library~A''.} +is a library of routines +intended to make accurate and reliable positional-astronomy +applications easier to write. +Most SLALIB routines are concerned with astronomical position and time, but a +number have wider trigonometrical, numerical or general applications. +The applications ASTROM, COCO, RV and TPOINT +all make extensive use of the SLALIB +routines, as do a number of telescope control systems around the world. +The SLALIB versions currently in service are written in +Fortran~77 and run on VAX/VMS, several Unix platforms and PC. +A generic ANSI~C version is also available from the author; it is +functionally similar to the Fortran version upon which the present +document concentrates. + +\subsection{Example Application} +Here is a simple example of an application program written +using SLALIB calls: + +\begin{verbatim} + PROGRAM FK4FK5 + * + * Read a B1950 position from I/O unit 5 and reply on I/O unit 6 + * with the J2000 equivalent. Enter a period to quit. + * + IMPLICIT NONE + CHARACTER C*80,S + INTEGER I,J,IHMSF(4),IDMSF(4) + DOUBLE PRECISION R4,D4,R5,D5 + LOGICAL BAD + + * Loop until a period is entered + C = ' ' + DO WHILE (C(:1).NE.'.') + + * Read h m s d ' " + READ (5,'(A)') C + IF (C(:1).NE.'.') THEN + BAD = .TRUE. + + * Decode the RA + I = 1 + CALL sla_DAFIN(C,I,R4,J) + IF (J.EQ.0) THEN + R4 = 15D0*R4 + + * Decode the Dec + CALL sla_DAFIN(C,I,D4,J) + IF (J.EQ.0) THEN + + * FK4 to FK5 + CALL sla_FK45Z(R4,D4,1950D0,R5,D5) + + * Format and output the result + CALL sla_DR2TF(2,R5,S,IHMSF) + CALL sla_DR2AF(1,D5,S,IDMSF) + WRITE (6, + : '(1X,I2.2,2I3.2,''.'',I2.2,2X,A,I2.2,2I3.2,''.'',I1)') + : IHMSF,S,IDMSF + BAD = .FALSE. + END IF + END IF + IF (BAD) WRITE (6,'(1X,''?'')') + END IF + END DO + + END +\end{verbatim} +In this example, SLALIB not only provides the complicated FK4 to +FK5 transformation but also +simplifies the tedious and error-prone tasks +of decoding and formatting angles +expressed as hours, minutes {\it etc}. The +example incorporates range checking, and avoids the +notorious ``minus zero'' problem (an often-perpetrated bug where +declinations between $0^{\circ}$ and $-1^{\circ}$ lose their minus +sign). +With a little extra elaboration and a few more calls to SLALIB, +defaulting can be provided (enabling unused fields to +be replaced with commas to avoid retyping), proper motions +can be handled, different epochs can be specified, and +so on. See the program COCO (SUN/56) for further ideas. + +\subsection{Scope} +SLALIB contains \nroutines\ routines covering the following topics: +\begin{itemize} +\item String Decoding, + Sexagesimal Conversions +\item Angles, Vectors \& Rotation Matrices +\item Calendars, + Timescales +\item Precession \& Nutation +\item Proper Motion +\item FK4/FK5/Hipparcos, + Elliptic Aberration +\item Geocentric Coordinates +\item Apparent \& Observed Place +\item Azimuth \& Elevation +\item Refraction \& Air Mass +\item Ecliptic, + Galactic, + Supergalactic Coordinates +\item Ephemerides +\item Astrometry +\item Numerical Methods +\end{itemize} + +\subsection{Objectives} +SLALIB was designed to give application programmers +a basic set of positional-astronomy tools which were +accurate and easy to use. To this end, the library is: +\begin{itemize} +\item Readily available, including source code and documentation. +\item Supported and maintained. +\item Portable -- coded in standard languages and available for +multiple computers and operating systems. +\item Thoroughly commented, both for maintainability and to +assist those wishing to cannibalize the code. +\item Stable. +\item Trustworthy -- some care has gone into +testing SLALIB, both by comparison with published data and +by checks for internal consistency. +\item Rigorous -- corners are not cut, +even where the practical consequences would, as a rule, be +negligible. +\item Comprehensive, without including too many esoteric features +required only by specialists. +\item Practical -- almost all the routines have been written to +satisfy real needs encountered during the development of +real-life applications. +\item Environment-independent -- the package is +completely free of pauses, stops, I/O {\it etc}. +\item Self-contained -- SLALIB calls no other libraries. +\end{itemize} +A few {\it caveats}: +\begin{itemize} +\item SLALIB does not pretend to be canonical. It is in essence +an anthology, and the adopted algorithms are liable +to change as more up-to-date ones become available. +\item The functions aren't orthogonal -- there are several +cases of different +routines doing similar things, and many examples where +sequences of SLALIB calls have simply been packaged, all to +make applications less trouble to write. +\item There are omissions -- for example there are no +routines for calculating physical ephemerides of +Solar-System bodies. +\item SLALIB is not homogeneous, though important subsets +(for example the FK4/FK5 routines) are. +\item The library is not foolproof. You have to know what +you are trying to do ({\it e.g.}\ by reading textbooks on positional +astronomy), and it is the caller's responsibility to supply +sensible arguments (although enough internal validation is done to +avoid arithmetic errors). +\item Without being written in a wasteful +manner, SLALIB is nonetheless optimized for maintainability +rather than speed. In addition, there are many places +where considerable simplification would be possible if some +specified amount of accuracy could be sacrificed; such +compromises are left to the individual programmer and +are not allowed to limit SLALIB's value as a source +of comparison results. +\end{itemize} + +\subsection{Fortran Version} +The Fortran versions of SLALIB use ANSI Fortran~77 with a few +commonplace extensions. Just three out of the \nroutines\ routines require +platform-specific techniques and accordingly are supplied +in different forms. +SLALIB has been implemented on the following platforms: +VAX/VMS, +PC (Microsoft Fortran, Linux), +DECstation (Ultrix), +DEC Alpha (DEC Unix), +Sun (SunOS, Solaris), +Hewlett Packard (HP-UX), +CONVEX, +Perkin-Elmer and +Fujitsu. + +\subsection{C Version} +An ANSI C version of SLALIB is available from the author +but is not part of the Starlink release. +The functionality of this (proprietary) C version closely matches +that of the Starlink Fortran SLALIB, partly for the convenience of +existing users of the Fortran version, some of whom have in the past +implemented C ``wrappers''. The function names +cannot be the same as the Fortran versions because of potential +linking problems when +both forms of the library are present; the C routine which +is the equivalent of (for example) {\tt SLA\_REFRO} is {\tt slaRefro}. +The types of arguments follow the Fortran version, except +that integers are {\tt int} rather than {\tt long}. +Argument passing is by value +(except for arrays and strings of course) +for given arguments and by pointer for returned arguments. +All the C functions are re-entrant. + +The Fortran routines {\tt sla\_GRESID}, {\tt sla\_RANDOM} and +{\tt sla\_WAIT} have no C counterparts. + +Further details of the C version of SLALIB are available +from the author. The definitive guide to +the calling sequences is the file {\tt slalib.h}. + +\subsection{Future Versions} +The homogeneity and ease of use of SLALIB could perhaps be improved +in the future +by turning to C++ and object-oriented techniques. For example ``celestial +position'' could be a class and many of the transformations +could happen automatically. This requires further study and +would almost certainly result in a complete redesign. +Similarly, +the impact of Fortran~90 has yet to be assessed. Once compilers +become widely available, some internal recoding may be worthwhile +in order to simplify parts of the code. However, as with C++, +a redesign of the +application interfaces will be needed if the capabilities of the +new language are to be exploited to the full. + +\subsection{New Functions} +In a package like SLALIB it is difficult to know how far to go. Is it +enough to provide the primitive operations, or should more +complicated functions be packaged? Is it worth encroaching on +specialist areas, where individual experts have all written their +own software already? To what extent should CPU efficiency be +an issue? How much support of different numerical precisions is +required? And so on. + +In practice, almost all the routines in SLALIB are there because they were +needed for some specific application, and this is likely to remain the +pattern for any enhancements in the future. +Suggestions for additional SLALIB routines should be addressed to the +author. + +\subsection{Acknowledgements} +SLALIB is descended from a package of routines written +for the AAO 16-bit minicomputers +in the mid-1970s. The coming of the VAX +allowed a much more comprehensive and thorough package +to be designed for Starlink, especially important +at a time when the adoption +of the IAU 1976 resolutions meant that astronomers +would have to cope with a mixture of reference frames, +timescales and nomenclature. + +Much of the preparatory work on SLALIB was done by +Althea~Wilkinson of Manchester University. +During its development, +Andrew~Murray, +Catherine~Hohenkerk, +Andrew~Sinclair, +Bernard~Yallop +and +Brian~Emerson of Her Majesty's Nautical Almanac Office were consulted +on many occasions; their advice was indispensable. +I am especially grateful to +Catherine~Hohenkerk +for supplying preprints of papers, and test data. A number of +enhancements to SLALIB were at the suggestion of +Russell~Owen, University of Washington, +Phil~Hill, St~Andrews University, +Bill~Vacca, JILA, Boulder and +Ron~Maddalena, NRAO. +Mark~Calabretta, CSIRO Radiophysics, Sydney supplied changes to suit Convex. +I am indebted to Derek~Jones (RGO) for providing algorithms for +calculating 2-body orbital motion. + +The first C version of SLALIB was a hand-coded transcription +of the Starlink Fortran version carried out by +Steve~Eaton (University of Leeds) in the course of +MSc work. This was later +enhanced by John~Straede (AAO) and Martin~Shepherd (Caltech). +The current C SLALIB is a complete rewrite by the present author and +includes a comprehensive validation suite. +Additional comments on the C version came from Bob~Payne (NRAO) and +Jeremy~Bailey (AAO). + +\section{LINKING} + +On Unix systems (Sun, DEC Alpha {\it etc.}): +\begin{verse} +{\tt \%~~f77 progname.o -L/star/lib `sla\_link` -o progname} +\end{verse} +(The above assumes that all Starlink directories have been added to +the {\tt LD\_LIBRARY\_PATH} and {\tt PATH} environment variables +as described in SUN/202.) + +On VAX/VMS: +\begin{verse} +{\tt \$~~LINK progname,SLALIB\_DIR:SLALIB/LIB} +\end{verse} + +\pagebreak + +\section{SUBPROGRAM SPECIFICATIONS} +%----------------------------------------------------------------------- +\routine{SLA\_ADDET}{Add E-terms of Aberration} +{ + \action{Add the E-terms (elliptic component of annual aberration) to a + pre IAU 1976 mean place to conform to the old catalogue convention.} + \call{CALL sla\_ADDET (RM, DM, EQ, RC, DC)} +} +\args{GIVEN} +{ + \spec{RM,DM}{D}{\radec\ without E-terms (radians)} \\ + \spec{EQ}{D}{Besselian epoch of mean equator and equinox} +} +\args{RETURNED} +{ + \spec{RC,DC}{D}{\radec\ with E-terms included (radians)} +} +\anote{Most star positions from pre-1984 optical catalogues (or + obtained by astrometry with respect to such stars) have the + E-terms built-in. If it is necessary to convert a formal mean + place (for example a pulsar timing position) to one + consistent with such a star catalogue, then the + \radec\ should be adjusted using this routine.} +\aref{{\it Explanatory Supplement to the Astronomical Ephemeris}, + section 2D, page 48.} +%----------------------------------------------------------------------- +\routine{SLA\_AFIN}{Sexagesimal character string to angle} +{ + \action{Decode a free-format sexagesimal string (degrees, arcminutes, + arcseconds) into a single precision floating point + number (radians).} + \call{CALL sla\_AFIN (STRING, NSTRT, RESLT, JF)} +} +\args{GIVEN} +{ + \spec{STRING}{C*(*)}{string containing deg, arcmin, arcsec fields} \\ + \spec{NSTRT}{I}{pointer to start of decode (beginning of STRING = 1)} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{advanced past the decoded angle} \\ + \spec{RESLT}{R}{angle in radians} \\ + \spec{JF}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{0.7em} $+1$ = default, RESLT unchanged (note 2)} \\ + \spec{}{}{\hspace{0.7em} $-1$ = bad degrees (note 3)} \\ + \spec{}{}{\hspace{0.7em} $-2$ = bad arcminutes (note 3)} \\ + \spec{}{}{\hspace{0.7em} $-3$ = bad arcseconds (note 3)} \\ +} +\goodbreak +\setlength{\oldspacing}{\topsep} +\setlength{\topsep}{0.3ex} +\begin{description} + \exampleitem \\ [1.5ex] + \begin{tabular}{p{7em}p{15em}p{12em}} + {\it argument} & {\it before} & {\it after} \\ \\ + STRING & $'$\verb*}-57 17 44.806 12 34 56.7}$'$ & unchanged \\ + NSTRT & 1 & 16 ({\it i.e.}\ pointing to 12...) \\ + RESLT & - & $-1.00000$ \\ + JF & - & 0 + \end{tabular} + \item A further call to sla\_AFIN, without adjustment of NSTRT, will + decode the second angle, \dms{12}{34}{56}{7}. +\end{description} +\setlength{\topsep}{\oldspacing} +\notes +{ + \begin{enumerate} + \item The first three ``fields'' in STRING are degrees, arcminutes, + arcseconds, separated by spaces or commas. The degrees field + may be signed, but not the others. The decoding is carried + out by the sla\_DFLTIN routine and is free-format. + \item Successive fields may be absent, defaulting to zero. For + zero status, the only combinations allowed are degrees alone, + degrees and arcminutes, and all three fields present. If all + three fields are omitted, a status of +1 is returned and RESLT is + unchanged. In all other cases RESLT is changed. + \item Range checking: + \begin{itemize} + \item The degrees field is not range checked. However, it is + expected to be integral unless the other two fields are absent. + \item The arcminutes field is expected to be 0-59, and integral if + the arcseconds field is present. If the arcseconds field + is absent, the arcminutes is expected to be 0-59.9999... + \item The arcseconds field is expected to be 0-59.9999... + \item Decoding continues even when a check has failed. Under these + circumstances the field takes the supplied value, defaulting to + zero, and the result RESLT is computed and returned. + \end{itemize} + \item Further fields after the three expected ones are not treated as + an error. The pointer NSTRT is left in the correct state for + further decoding with the present routine or with sla\_DFLTIN + {\it etc}. See the example, above. + \item If STRING contains hours, minutes, seconds instead of + degrees {\it etc}, + or if the required units are turns (or days) instead of radians, + the result RESLT should be multiplied as follows: \\ [1.5ex] + \begin{tabular}{p{6em}p{5em}p{15em}} + {\it for STRING} & {\it to obtain} & {\it multiply RESLT by} \\ \\ + ${\circ}$~~\raisebox{-0.7ex}{$'$}~~\raisebox{-0.7ex}{$''$} + & radians & $1.0$ \\ + ${\circ}$~~\raisebox{-0.7ex}{$'$}~~\raisebox{-0.7ex}{$''$} + & turns & $1/{2 \pi} = 0.1591549430918953358$ \\ + h m s & radians & $15.0$ \\ + h m s & days & $15/{2\pi} = 2.3873241463784300365$ \\ + \end{tabular} + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AIRMAS}{Air Mass} +{ + \action{Air mass at given zenith distance (double precision).} + \call{D~=~sla\_AIRMAS (ZD)} +} +\args{GIVEN} +{ + \spec{ZD}{D}{observed zenith distance (radians)} +} +\args{RETURNED} +{ + \spec{sla\_AIRMAS}{D}{air mass (1 at zenith)} +} +\notes +{ + \begin{enumerate} + \item The {\it observed}\/ zenith distance referred to above means + ``as affected by refraction''. + \item The routine uses Hardie's (1962) polynomial fit to Bemporad's + data for the relative air mass, $X$, in units of thickness at the + zenith as tabulated by Schoenberg (1929). This is adequate for all + normal needs as it is accurate to better than + 0.1\% up to $X = 6.8$ and better than 1\% up to $X = 10$. + Bemporad's tabulated values are unlikely to be trustworthy + to such accuracy + because of variations in density, pressure and other + conditions in the atmosphere from those assumed in his work. + \item The sign of the ZD is ignored. + \item At zenith distances greater than about $\zeta = 87^{\circ}$ the + air mass is held constant to avoid arithmetic overflows. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Hardie, R.H., 1962, in {\it Astronomical Techniques}\, + ed. W.A.\ Hiltner, University of Chicago Press, p180. + \item Schoenberg, E., 1929, Hdb.\ d.\ Ap., + Berlin, Julius Springer, 2, 268. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_ALTAZ}{Velocities {\it etc.}\ for Altazimuth Mount} +{ + \action{Positions, velocities and accelerations for an altazimuth + telescope mount tracking a star (double precision).} + \call{CALL sla\_ALTAZ (\vtop{ + \hbox{HA, DEC, PHI,} + \hbox{AZ, AZD, AZDD, EL, ELD, ELDD, PA, PAD, PADD)}}} +} +\args{GIVEN} +{ + \spec{HA}{D}{hour angle} \\ + \spec{DEC}{D}{declination} \\ + \spec{PHI}{D}{observatory latitude} +} +\args{RETURNED} +{ + \spec{AZ}{D}{azimuth} \\ + \spec{AZD}{D}{azimuth velocity} \\ + \spec{AZDD}{D}{azimuth acceleration} \\ + \spec{EL}{D}{elevation} \\ + \spec{ELD}{D}{elevation velocity} \\ + \spec{ELDD}{D}{elevation acceleration} \\ + \spec{PA}{D}{parallactic angle} \\ + \spec{PAD}{D}{parallactic angle velocity} \\ + \spec{PADD}{D}{parallactic angle acceleration} +} +\notes +{ + \begin{enumerate} + \setlength{\parskip}{\medskipamount} + \item Natural units are used throughout. HA, DEC, PHI, AZ, EL + and ZD are in radians. The velocities and accelerations + assume constant declination and constant rate of change of + hour angle (as for tracking a star); the units of AZD, ELD + and PAD are radians per radian of HA, while the units of AZDD, + ELDD and PADD are radians per radian of HA squared. To + convert into practical degree- and second-based units: + + \begin{center} + \begin{tabular}{rlcl} + angles & $\times 360/2\pi$ & $\rightarrow$ & degrees \\ + velocities & $\times (2\pi/86400) \times (360/2\pi)$ + & $\rightarrow$ & degree/sec \\ + accelerations & $\times (2\pi/86400)^2 \times (360/2\pi)$ + & $\rightarrow$ & degree/sec/sec \\ + \end{tabular} + \end{center} + + Note that the seconds here are sidereal rather than SI. One + sidereal second is about 0.99727 SI seconds. + + The velocity and acceleration factors assume the sidereal + tracking case. Their respective numerical values are (exactly) + 1/240 and (approximately) 1/3300236.9. + \item Azimuth is returned in the range $[\,0,2\pi\,]$; north is zero, + and east is $+\pi/2$. Elevation and parallactic angle are + returned in the range $\pm\pi/2$. Position angle is +ve + for a star west of the meridian and is the angle NP--star--zenith. + \item The latitude is geodetic as opposed to geocentric. The + hour angle and declination are topocentric. Refraction and + deficiencies in the telescope mounting are ignored. The + purpose of the routine is to give the general form of the + quantities. The details of a real telescope could profoundly + change the results, especially close to the zenith. + \item No range checking of arguments is carried out. + \item In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AMP}{Apparent to Mean} +{ + \action{Convert star \radec\ from geocentric apparent to + mean place (post IAU 1976).} + \call{CALL sla\_AMP (RA, DA, DATE, EQ, RM, DM)} +} +\args{GIVEN} +{ + \spec{RA,DA}{D}{apparent \radec\ (radians)} \\ + \spec{DATE}{D}{TDB for apparent place (JD$-$2400000.5)} \\ + \spec{EQ}{D}{equinox: Julian epoch of mean place} +} +\args{RETURNED} +{ + \spec{RM,DM}{D}{mean \radec\ (radians)} +} +\notes +{ + \begin{enumerate} + \item The distinction between the required TDB and TT is + always negligible. Moreover, for all but the most + critical applications UTC is adequate. + \item The accuracy is limited by the routine sla\_EVP, called + by sla\_MAPPA, which computes the Earth position and + velocity using the methods of Stumpff. The maximum + error is about 0.3~milliarcsecond. + \item Iterative techniques are used for the aberration and + light deflection corrections so that the routines + sla\_AMP (or sla\_AMPQK) and sla\_MAP (or sla\_MAPQK) are + accurate inverses; even at the edge of the Sun's disc + the discrepancy is only about 1~nanoarcsecond. + \item Where multiple apparent places are to be converted to + mean places, for a fixed date and equinox, it is more + efficient to use the sla\_MAPPA routine to compute the + required parameters once, followed by one call to + sla\_AMPQK per star. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AMPQK}{Quick Apparent to Mean} +{ + \action{Convert star \radec\ from geocentric apparent to mean place + (post IAU 1976). Use of this routine is appropriate when + efficiency is important and where many star positions are + all to be transformed for one epoch and equinox. The + star-independent parameters can be obtained by calling + the sla\_MAPPA routine.} + \call{CALL sla\_AMPQK (RA, DA, AMPRMS, RM, DM)} +} +\args{GIVEN} +{ + \spec{RA,DA}{D}{apparent \radec\ (radians)} \\ + \spec{AMPRMS}{D(21)}{star-independent mean-to-apparent parameters:} \\ + \specel {(1)} {time interval for proper motion (Julian years)} \\ + \specel {(2-4)} {barycentric position of the Earth (AU)} \\ + \specel {(5-7)} {heliocentric direction of the Earth (unit vector)} \\ + \specel {(8)} {(gravitational radius of + Sun)$\times 2 / $(Sun-Earth distance)} \\ + \specel {(9-11)} {{\bf v}: barycentric Earth velocity in units of c} \\ + \specel {(12)} {$\sqrt{1-\left|\mbox{\bf v}\right|^2}$} \\ + \specel {(13-21)} {precession/nutation $3\times3$ matrix} +} +\args{RETURNED} +{ + \spec{RM,DM}{D}{mean \radec\ (radians)} +} +\notes +{ + \begin{enumerate} + \item The accuracy is limited by the routine sla\_EVP, called + by sla\_MAPPA, which computes the Earth position and + velocity using the methods of Stumpff. The maximum + error is about 0.3~milliarcsecond. + \item Iterative techniques are used for the aberration and + light deflection corrections so that the routines + sla\_AMP (or sla\_AMPQK) and sla\_MAP (or sla\_MAPQK) are + accurate inverses; even at the edge of the Sun's disc + the discrepancy is only about 1~nanoarcsecond. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AOP}{Apparent to Observed} +{ + \action{Apparent to observed place, for optical sources distant from + the solar system.} + \call{CALL sla\_AOP (\vtop{ + \hbox{RAP, DAP, DATE, DUT, ELONGM, PHIM, HM, XP, YP,} + \hbox{TDK, PMB, RH, WL, TLR, AOB, ZOB, HOB, DOB, ROB)}}} +} +\args{GIVEN} +{ + \spec{RAP,DAP}{D}{geocentric apparent \radec\ (radians)} \\ + \spec{DATE}{D}{UTC date/time (Modified Julian Date, JD$-$2400000.5)} \\ + \spec{DUT}{D}{$\Delta$UT: UT1$-$UTC (UTC seconds)} \\ + \spec{ELONGM}{D}{observer's mean longitude (radians, east +ve)} \\ + \spec{PHIM}{D}{observer's mean geodetic latitude (radians)} \\ + \spec{HM}{D}{observer's height above sea level (metres)} \\ + \spec{XP,YP}{D}{polar motion \xy\ coordinates (radians)} \\ + \spec{TDK}{D}{local ambient temperature (degrees K; std=273.155D0)} \\ + \spec{PMB}{D}{local atmospheric pressure (mB; std=1013.25D0)} \\ + \spec{RH}{D}{local relative humidity (in the range 0D0\,--\,1D0)} \\ + \spec{WL}{D}{effective wavelength ($\mu{\rm m}$, {\it e.g.}\ 0.55D0)} \\ + \spec{TLR}{D}{tropospheric lapse rate (degrees K per metre, + {\it e.g.}\ 0.0065D0)} +} +\args{RETURNED} +{ + \spec{AOB}{D}{observed azimuth (radians: N=0, E=$90^{\circ}$)} \\ + \spec{ZOB}{D}{observed zenith distance (radians)} \\ + \spec{HOB}{D}{observed Hour Angle (radians)} \\ + \spec{DOB}{D}{observed $\delta$ (radians)} \\ + \spec{ROB}{D}{observed $\alpha$ (radians)} +} +\notes +{ + \begin{enumerate} + \item This routine returns zenith distance rather than elevation + in order to reflect the fact that no allowance is made for + depression of the horizon. + \item The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted azimuth and elevation should be within about + \arcsec{0}{1} for $\zeta<70^{\circ}$. Even + at a topocentric zenith distance of + $90^{\circ}$, the accuracy in elevation should be better than + 1~arcminute; useful results are available for a further + $3^{\circ}$, beyond which the sla\_REFRO routine returns a + fixed value of the refraction. The complementary + routines sla\_AOP (or sla\_AOPQK) and sla\_OAP (or sla\_OAPQK) + are self-consistent to better than 1~microarcsecond all over + the celestial sphere. + \item It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + \item {\it Apparent}\/ \radec\ means the geocentric apparent right ascension + and declination, which is obtained from a catalogue mean place + by allowing for space motion, parallax, precession, nutation, + annual aberration, and the Sun's gravitational lens effect. For + star positions in the FK5 system ({\it i.e.}\ J2000), these effects can + be applied by means of the sla\_MAP {\it etc.}\ routines. Starting from + other mean place systems, additional transformations will be + needed; for example, FK4 ({\it i.e.}\ B1950) mean places would first + have to be converted to FK5, which can be done with the + sla\_FK425 {\it etc.}\ routines. + \item {\it Observed}\/ \azel\ means the position that would be seen by a + perfect theodolite located at the observer. This is obtained + from the geocentric apparent \radec\ by allowing for Earth + orientation and diurnal aberration, rotating from equator + to horizon coordinates, and then adjusting for refraction. + The \hadec\ is obtained by rotating back into equatorial + coordinates, using the geodetic latitude corrected for polar + motion, and is the position that would be seen by a perfect + equatorial located at the observer and with its polar axis + aligned to the Earth's axis of rotation ({\it n.b.}\ not to the + refracted pole). Finally, the $\alpha$ is obtained by subtracting + the {\it h}\/ from the local apparent ST. + \item To predict the required setting of a real telescope, the + observed place produced by this routine would have to be + adjusted for the tilt of the azimuth or polar axis of the + mounting (with appropriate corrections for mount flexures), + for non-perpendicularity between the mounting axes, for the + position of the rotator axis and the pointing axis relative + to it, for tube flexure, for gear and encoder errors, and + finally for encoder zero points. Some telescopes would, of + course, exhibit other properties which would need to be + accounted for at the appropriate point in the sequence. + \item This routine takes time to execute, due mainly to the + rigorous integration used to evaluate the refraction. + For processing multiple stars for one location and time, + call sla\_AOPPA once followed by one call per star to sla\_AOPQK. + Where a range of times within a limited period of a few hours + is involved, and the highest precision is not required, call + sla\_AOPPA once, followed by a call to sla\_AOPPAT each time the + time changes, followed by one call per star to sla\_AOPQK. + \item The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, wrong, because of leap seconds. However, + as long as the $\Delta$UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap $\Delta$UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the $\Delta$UT changes by one second to its post-leap new value. + \item The $\Delta$UT (UT1$-$UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep $\Delta$UT + within $\pm$\tsec{0}{9}. + \item IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. The + longitude required by the present routine is {\bf east-positive}, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + sla\_OBS routine are west-positive (as in the {\it Astronomical + Almanac}\/ before 1984) and must be reversed in sign before use + in the present routine. + \item The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The + maximum amplitude is about \arcsec{0}{3}. If XP,YP values + are unavailable, use XP=YP=0D0. See page B60 of the 1988 + {\it Astronomical Almanac}\/ for a definition of the two angles. + \item The height above sea level of the observing station, HM, + can be obtained from the {\it Astronomical Almanac}\/ (Section J + in the 1988 edition), or via the routine sla\_OBS. If P, + the pressure in mB, is available, an adequate + estimate of HM can be obtained from the following expression: + \begin{quote} + {\tt HM=-29.3D0*TSL*LOG(P/1013.25D0)} + \end{quote} + where TSL is the approximate sea-level air temperature in degrees K + (see {\it Astrophysical Quantities}, C.W.Allen, 3rd~edition, + \S 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + \begin{quote} + {\tt P=1013.25D0*EXP(-HM/(29.3D0*TSL))} + \end{quote} + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + \item The azimuths {\it etc.}\ used by the present routine are with + respect to the celestial pole. Corrections to the terrestrial pole + can be computed using sla\_POLMO. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AOPPA}{Appt-to-Obs Parameters} +{ + \action{Pre-compute the set of apparent to observed place parameters + required by the ``quick'' routines sla\_AOPQK and sla\_OAPQK.} + \call{CALL sla\_AOPPA (\vtop{ + \hbox{DATE, DUT, ELONGM, PHIM, HM, XP, YP,} + \hbox{TDK, PMB, RH, WL, TLR, AOPRMS)}}} +} +\args{GIVEN} +{ + \spec{DATE}{D}{UTC date/time (Modified Julian Date, JD$-$2400000.5)} \\ + \spec{DUT}{D}{$\Delta$UT: UT1$-$UTC (UTC seconds)} \\ + \spec{ELONGM}{D}{observer's mean longitude (radians, east +ve)} \\ + \spec{PHIM}{D}{observer's mean geodetic latitude (radians)} \\ + \spec{HM}{D}{observer's height above sea level (metres)} \\ + \spec{XP,YP}{D}{polar motion \xy\ coordinates (radians)} \\ + \spec{TDK}{D}{local ambient temperature (degrees K; std=273.155D0)} \\ + \spec{PMB}{D}{local atmospheric pressure (mB; std=1013.25D0)} \\ + \spec{RH}{D}{local relative humidity (in the range 0D0\,--\,1D0)} \\ + \spec{WL}{D}{effective wavelength ($\mu{\rm m}$, {\it e.g.}\ 0.55D0)} \\ + \spec{TLR}{D}{tropospheric lapse rate (degrees K per metre, + {\it e.g.}\ 0.0065D0)} +} +\args{RETURNED} +{ + \spec{AOPRMS}{D(14)}{star-independent apparent-to-observed parameters:} \\ + \specel {(1)} {geodetic latitude (radians)} \\ + \specel {(2,3)} {sine and cosine of geodetic latitude} \\ + \specel {(4)} {magnitude of diurnal aberration vector} \\ + \specel {(5)} {height (HM)} \\ + \specel {(6)} {ambient temperature (TDK)} \\ + \specel {(7)} {pressure (PMB)} \\ + \specel {(8)} {relative humidity (RH)} \\ + \specel {(9)} {wavelength (WL)} \\ + \specel {(10)} {lapse rate (TLR)} \\ + \specel {(11,12)} {refraction constants A and B (radians)} \\ + \specel {(13)} {longitude + eqn of equinoxes + + ``sidereal $\Delta$UT'' (radians)} \\ + \specel {(14)} {local apparent sidereal time (radians)} +} +\notes +{ + \begin{enumerate} + \item It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + \item The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, wrong, because of leap seconds. However, + as long as the $\Delta$UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap $\Delta$UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the $\Delta$UT changes by one second to its post-leap new value. + \item The $\Delta$UT (UT1$-$UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep $\Delta$UT + within $\pm$\tsec{0}{9}. The ``sidereal $\Delta$UT'' which forms + part of AOPRMS(13) is the same quantity, but converted from solar + to sidereal seconds and expressed in radians. + \item IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. The + longitude required by the present routine is {\bf east-positive}, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + sla\_OBS routine are west-positive (as in the {\it Astronomical + Almanac}\/ before 1984) and must be reversed in sign before use in + the present routine. + \item The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The + maximum amplitude is about \arcsec{0}{3}. If XP,YP values + are unavailable, use XP=YP=0D0. See page B60 of the 1988 + {\it Astronomical Almanac}\/ for a definition of the two angles. + \item The height above sea level of the observing station, HM, + can be obtained from the {\it Astronomical Almanac}\/ (Section J + in the 1988 edition), or via the routine sla\_OBS. If P, + the pressure in mB, is available, an adequate + estimate of HM can be obtained from the following expression: + \begin{quote} + {\tt HM=-29.3D0*TSL*LOG(P/1013.25D0)} + \end{quote} + where TSL is the approximate sea-level air temperature in degrees K + (see {\it Astrophysical Quantities}, C.W.Allen, 3rd~edition, + \S 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + \begin{quote} + {\tt P=1013.25D0*EXP(-HM/(29.3D0*TSL))} + \end{quote} + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AOPPAT}{Update Appt-to-Obs Parameters} +{ + \action{Recompute the sidereal time in the apparent to observed place + star-independent parameter block.} + \call{CALL sla\_AOPPAT (DATE, AOPRMS)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{UTC date/time (Modified Julian Date, JD$-$2400000.5)} \\ + \spec{AOPRMS}{D(14)}{star-independent apparent-to-observed parameters:} \\ + \specel{(1-12)}{not required} \\ + \specel{(13)}{longitude + eqn of equinoxes + + ``sidereal $\Delta$UT'' (radians)} \\ + \specel{(14)}{not required} +} +\args{RETURNED} +{ + \spec{AOPRMS}{D(14)}{star-independent apparent-to-observed parameters:} \\ + \specel{(1-13)}{not changed} \\ + \specel{(14)}{local apparent sidereal time (radians)} +} +\anote{For more information, see sla\_AOPPA.} +%----------------------------------------------------------------------- +\routine{SLA\_AOPQK}{Quick Appt-to-Observed} +{ + \action{Quick apparent to observed place (but see Note~8, below).} + \call{CALL sla\_AOPQK (RAP, DAP, AOPRMS, AOB, ZOB, HOB, DOB, ROB)} +} +\args{GIVEN} +{ + \spec{RAP,DAP}{D}{geocentric apparent \radec\ (radians)} \\ + \spec{AOPRMS}{D(14)}{star-independent apparent-to-observed parameters:} \\ + \specel{(1)}{geodetic latitude (radians)} \\ + \specel{(2,3)}{sine and cosine of geodetic latitude} \\ + \specel{(4)}{magnitude of diurnal aberration vector} \\ + \specel{(5)}{height (metres)} \\ + \specel{(6)}{ambient temperature (degrees K)} \\ + \specel{(7)}{pressure (mB)} \\ + \specel{(8)}{relative humidity (0\,--\,1)} \\ + \specel{(9)}{wavelength ($\mu{\rm m}$)} \\ + \specel{(10)}{lapse rate (degrees K per metre)} \\ + \specel{(11,12)}{refraction constants A and B (radians)} \\ + \specel{(13)}{longitude + eqn of equinoxes + + ``sidereal $\Delta$UT'' (radians)} \\ + \specel{(14)}{local apparent sidereal time (radians)} +} +\args{RETURNED} +{ + \spec{AOB}{D}{observed azimuth (radians: N=0, E=$90^{\circ}$)} \\ + \spec{ZOB}{D}{observed zenith distance (radians)} \\ + \spec{HOB}{D}{observed Hour Angle (radians)} \\ + \spec{DOB}{D}{observed Declination (radians)} \\ + \spec{ROB}{D}{observed Right Ascension (radians)} +} +\notes +{ + \begin{enumerate} + \item This routine returns zenith distance rather than elevation + in order to reflect the fact that no allowance is made for + depression of the horizon. + \item The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted azimuth and elevation should be within about + \arcsec{0}{1} for $\zeta<70^{\circ}$. Even + at a topocentric zenith distance of + $90^{\circ}$, the accuracy in elevation should be better than + 1~arcminute; useful results are available for a further + $3^{\circ}$, beyond which the sla\_REFRO routine returns a + fixed value of the refraction. The complementary + routines sla\_AOP (or sla\_AOPQK) and sla\_OAP (or sla\_OAPQK) + are self-consistent to better than 1~microarcsecond all over + the celestial sphere. + \item It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + \item {\it Apparent}\/ \radec\ means the geocentric apparent right ascension + and declination, which is obtained from a catalogue mean place + by allowing for space motion, parallax, precession, nutation, + annual aberration, and the Sun's gravitational lens effect. For + star positions in the FK5 system ({\it i.e.}\ J2000), these effects can + be applied by means of the sla\_MAP {\it etc.}\ routines. Starting from + other mean place systems, additional transformations will be + needed; for example, FK4 ({\it i.e.}\ B1950) mean places would first + have to be converted to FK5, which can be done with the + sla\_FK425 {\it etc.}\ routines. + \item {\it Observed}\/ \azel\ means the position that would be seen by a + perfect theodolite located at the observer. This is obtained + from the geocentric apparent \radec\ by allowing for Earth + orientation and diurnal aberration, rotating from equator + to horizon coordinates, and then adjusting for refraction. + The \hadec\ is obtained by rotating back into equatorial + coordinates, using the geodetic latitude corrected for polar + motion, and is the position that would be seen by a perfect + equatorial located at the observer and with its polar axis + aligned to the Earth's axis of rotation ({\it n.b.}\ not to the + refracted pole). Finally, the $\alpha$ is obtained by subtracting + the {\it h}\/ from the local apparent ST. + \item To predict the required setting of a real telescope, the + observed place produced by this routine would have to be + adjusted for the tilt of the azimuth or polar axis of the + mounting (with appropriate corrections for mount flexures), + for non-perpendicularity between the mounting axes, for the + position of the rotator axis and the pointing axis relative + to it, for tube flexure, for gear and encoder errors, and + finally for encoder zero points. Some telescopes would, of + course, exhibit other properties which would need to be + accounted for at the appropriate point in the sequence. + \item The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the sla\_AOPPA routine. + If nothing has changed significantly except the time, the + sla\_AOPPAT routine may be used to perform the requisite + partial recomputation of AOPRMS. + \item The ``sidereal $\Delta$UT'' which forms part of AOPRMS(13) + is UT1$-$UTC converted from solar to + sidereal seconds and expressed in radians. + \item At zenith distances beyond about $76^\circ$, the need for + special care with the corrections for refraction causes a + marked increase in execution time. Moreover, the effect + gets worse with increasing zenith distance. Adroit + programming in the calling application may allow the + problem to be reduced. Prepare an alternative AOPRMS array, + computed for zero air-pressure; this will disable the + refraction corrections and cause rapid execution. Using + this AOPRMS array, a preliminary call to the present routine + will, depending on the application, produce a rough position + which may be enough to establish whether the full, slow + calculation (using the real AOPRMS array) is worthwhile. + For example, there would be no need for the full calculation + if the preliminary call had already established that the + source was well below the elevation limits for a particular + telescope. + \item The azimuths {\it etc.}\ used by the present routine are with + respect to the celestial pole. Corrections to the terrestrial pole + can be computed using sla\_POLMO. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_ATMDSP}{Atmospheric Dispersion} +{ + \action{Apply atmospheric-dispersion adjustments to refraction coefficients.} + \call{CALL sla\_ATMDSP (TDK, PMB, RH, WL1, A1, B1, WL2, A2, B2)} +} +\args{GIVEN} +{ + \spec{TDK}{D}{ambient temperature at the observer (degrees K)} \\ + \spec{PMB}{D}{pressure at the observer (mB)} \\ + \spec{RH}{D}{relative humidity at the observer (range 0\,--\,1)} \\ + \spec{WL1}{D}{base wavelength ($\mu{\rm m}$)} \\ + \spec{A1}{D}{refraction coefficient A for wavelength WL1 (radians)} \\ + \spec{B1}{D}{refraction coefficient B for wavelength WL1 (radians)} \\ + \spec{WL2}{D}{wavelength for which adjusted A,B required ($\mu{\rm m}$)} +} +\args{RETURNED} +{ + \spec{A2}{D}{refraction coefficient A for wavelength WL2 (radians)} \\ + \spec{B2}{D}{refraction coefficient B for wavelength WL2 (radians)} +} +\notes +{ + \begin{enumerate} + \item To use this routine, first call sla\_REFCO specifying WL1 as the + wavelength. This yields refraction coefficients A1, B1, correct + for that wavelength. Subsequently, calls to sla\_ATMDSP specifying + different wavelengths will produce new, slightly adjusted + refraction coefficients A2, B2, which apply to the specified wavelength. + \item Most of the atmospheric dispersion happens between $0.7\,\mu{\rm m}$ + and the UV atmospheric cutoff, and the effect increases strongly + towards the UV end. For this reason a blue reference wavelength + is recommended, for example $0.4\,\mu{\rm m}$. + \item The accuracy, for this set of conditions: \\[1pc] + \hspace*{5ex} \begin{tabular}{rcl} + height above sea level & ~ & 2000\,m \\ + latitude & ~ & $29^\circ$ \\ + pressure & ~ & 793\,mB \\ + temperature & ~ & $290^\circ$\,K \\ + humidity & ~ & 0.5 (50\%) \\ + lapse rate & ~ & $0.0065^\circ m^{-1}$ \\ + reference wavelength & ~ & $0.4\,\mu{\rm m}$ \\ + star elevation & ~ & $15^\circ$ \\ + \end{tabular}\\[1pc] + is about 2.5\,mas RMS between 0.3 and $1.0\,\mu{\rm m}$, and stays + within 4\,mas for the whole range longward of $0.3\,\mu{\rm m}$ + (compared with a total dispersion from 0.3 to $20\,\mu{\rm m}$ + of about \arcseci{11}). These errors are typical for ordinary + conditions; in extreme conditions values a few times this size + may occur. + \item If either wavelength exceeds $100\,\mu{\rm m}$, the radio case + is assumed and the returned refraction coefficients are the + same as the given ones. + \item The algorithm consists of calculation of the refractivity of the + air at the observer for the two wavelengths, using the methods + of the sla\_REFRO routine, and then scaling of the two refraction + coefficients according to classical refraction theory. This + amounts to scaling the A coefficient in proportion to $(\mu-1)$ and + the B coefficient almost in the same ratio (see R.M.Green, + {\it Spherical Astronomy,}\/ Cambridge University Press, 1985). + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_AV2M}{Rotation Matrix from Axial Vector} +{ + \action{Form the rotation matrix corresponding to a given axial vector + (single precision).} + \call{CALL sla\_AV2M (AXVEC, RMAT)} +} +\args{GIVEN} +{ + \spec{AXVEC}{R(3)}{axial vector (radians)} +} +\args{RETURNED} +{ + \spec{RMAT}{R(3,3)}{rotation matrix} +} +\notes +{ + \begin{enumerate} + \item A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the {\it Euler axis}, and the angle through which the + reference frame rotates is called the Euler angle. The axial + vector supplied to this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. + \item If AXVEC is null, the unit matrix is returned. + \item The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_BEAR}{Direction Between Points on a Sphere} +{ + \action{Returns the bearing (position angle) of one point on a + sphere seen from another (single precision).} + \call{R~=~sla\_BEAR (A1, B1, A2, B2)} +} +\args{GIVEN} +{ + \spec{A1,B1}{R}{spherical coordinates of one point} \\ + \spec{A2,B2}{R}{spherical coordinates of the other point} +} +\args{RETURNED} +{ + \spec{sla\_BEAR}{R}{bearing from first point to second} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are \radec, + $[\lambda,\phi]$ {\it etc.}, in radians. + \item The result is the bearing (position angle), in radians, + of point [A2,B2] as seen + from point [A1,B1]. It is in the range $\pm \pi$. The sense + is such that if [A2,B2] + is a small distance due east of [A1,B1] the result + is about $+\pi/2$. Zero is returned + if the two points are coincident. + \item If either B-coordinate is outside the range $\pm\pi/2$, the + result may correspond to ``the long way round''. + \item The routine sla\_PAV performs an equivalent function except + that the points are specified in the form of Cartesian unit + vectors. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CAF2R}{Deg,Arcmin,Arcsec to Radians} +{ + \action{Convert degrees, arcminutes, arcseconds to radians + (single precision).} + \call{CALL sla\_CAF2R (IDEG, IAMIN, ASEC, RAD, J)} +} +\args{GIVEN} +{ + \spec{IDEG}{I}{degrees} \\ + \spec{IAMIN}{I}{arcminutes} \\ + \spec{ASEC}{R}{arcseconds} +} +\args{RETURNED} +{ + \spec{RAD}{R}{angle in radians} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 1 = IDEG outside range 0$-$359} \\ + \spec{}{}{\hspace{1.5em} 2 = IAMIN outside range 0$-$59} \\ + \spec{}{}{\hspace{1.5em} 3 = ASEC outside range 0$-$59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CALDJ}{Calendar Date to MJD} +{ + \action{Gregorian Calendar to Modified Julian Date, with century default.} + \call{CALL sla\_CALDJ (IY, IM, ID, DJM, J)} +} +\args{GIVEN} +{ + \spec{IY,IM,ID}{I}{year, month, day in Gregorian calendar} +} +\args{RETURNED} +{ + \spec{DJM}{D}{modified Julian Date (JD$-$2400000.5) for $0^{\rm h}$} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = bad year (MJD not computed)} \\ + \spec{}{}{\hspace{1.5em} 2 = bad month (MJD not computed)} \\ + \spec{}{}{\hspace{1.5em} 3 = bad day (MJD computed)} \\ +} +\notes +{ + \begin{enumerate} + \item This routine supports the {\it century default}\/ feature. + Acceptable years are: + \begin{itemize} + \item 00-49, interpreted as 2000\,--\,2049, + \item 50-99, interpreted as 1950\,--\,1999, and + \item 100 upwards, interpreted literally. + \end{itemize} + For 1-100AD use the routine sla\_CLDJ instead. + \item For year $n$BC use IY = $-(n-1)$. + \item When an invalid year or month is supplied (status J~=~1~or~2) + the MJD is {\bf not} computed. When an invalid day is supplied + (status J~=~3) the MJD {\bf is} computed. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CALYD}{Calendar to Year, Day} +{ + \action{Gregorian calendar date to year and day in year, in a Julian + calendar aligned to the 20th/21st century Gregorian calendar, + with century default.} + \call{CALL sla\_CALYD (IY, IM, ID, NY, ND, J)} +} +\args{GIVEN} +{ + \spec{IY,IM,ID}{I}{year, month, day in Gregorian calendar: + year may optionally omit the century} +} +\args{RETURNED} +{ + \spec{NY}{I}{year (re-aligned Julian calendar)} \\ + \spec{ND}{I}{day in year (1 = January 1st)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = bad year (before $-4711$)} \\ + \spec{}{}{\hspace{1.5em} 2 = bad month} \\ + \spec{}{}{\hspace{1.5em} 3 = bad day} +} +\notes +{ + \begin{enumerate} + \item This routine supports the {\it century default}\/ feature. + Acceptable years are: + \begin{itemize} + \item 00-49, interpreted as 2000\,--\,2049, + \item 50-99, interpreted as 1950\,--\,1999, and + \item other years after -4712 , interpreted literally. + \end{itemize} + Use sla\_CLYD for years before 100AD. + \item The purpose of sla\_CALDJ is to support + sla\_EARTH, sla\_MOON and sla\_ECOR. + \item Between 1900~March~1 and 2100~February~28 it returns answers + which are consistent with the ordinary Gregorian calendar. + Outside this range there will be a discrepancy which increases + by one day for every non-leap century year. + \item When an invalid year or month is supplied (status J~=~1 or J~=~2) + the results are {\bf not} computed. When a day is + supplied which is outside the conventional range (status J~=~3) + the results {\bf are} computed. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CC2S}{Cartesian to Spherical} +{ + \action{Cartesian coordinates to spherical coordinates (single precision).} + \call{CALL sla\_CC2S (V, A, B)} +} +\args{GIVEN} +{ + \spec{V}{R(3)}{\xyz\ vector} +} +\args{RETURNED} +{ + \spec{A,B}{R}{spherical coordinates in radians} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the {\it x}-axis + at zero longitude and latitude, and the {\it z}-axis at the + +ve latitude pole. + \item If V is null, zero A and B are returned. + \item At either pole, zero A is returned. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CC62S}{Cartesian 6-Vector to Spherical} +{ + \action{Conversion of position \& velocity in Cartesian coordinates + to spherical coordinates (single precision).} + \call{CALL sla\_CC62S (V, A, B, R, AD, BD, RD)} +} +\args{GIVEN} +{ + \spec{V}{R(6)}{\xyzxyzd} +} +\args{RETURNED} +{ + \spec{A}{R}{longitude (radians) -- for example $\alpha$} \\ + \spec{B}{R}{latitude (radians) -- for example $\delta$} \\ + \spec{R}{R}{radial coordinate} \\ + \spec{AD}{R}{longitude derivative (radians per unit time)} \\ + \spec{BD}{R}{latitude derivative (radians per unit time)} \\ + \spec{RD}{R}{radial derivative} +} +%----------------------------------------------------------------------- +\routine{SLA\_CD2TF}{Days to Hour,Min,Sec} +{ + \action{Convert an interval in days to hours, minutes, seconds + (single precision).} + \call{CALL sla\_CD2TF (NDP, DAYS, SIGN, IHMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of seconds} \\ + \spec{DAYS}{R}{interval in days} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IHMSF}{I(4)}{hours, minutes, seconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size of + DAYS, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IHMSF(4). For example, + on a VAX computer, for DAYS up to 1.0, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + \item The absolute value of DAYS may exceed 1.0. In cases where it + does not, it is up to the caller to test for and handle the + case where DAYS is very nearly 1.0 and rounds up to 24~hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. +\end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CLDJ}{Calendar to MJD} +{ + \action{Gregorian Calendar to Modified Julian Date.} + \call{CALL sla\_CLDJ (IY, IM, ID, DJM, J)} +} +\args{GIVEN} +{ + \spec{IY,IM,ID}{I}{year, month, day in Gregorian calendar} +} +\args{RETURNED} +{ + \spec{DJM}{D}{modified Julian Date (JD$-$2400000.5) for $0^{\rm h}$} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = bad year} \\ + \spec{}{}{\hspace{1.5em} 2 = bad month} \\ + \spec{}{}{\hspace{1.5em} 3 = bad day} +} +\notes +{ + \begin{enumerate} + \item When an invalid year or month is supplied (status J~=~1~or~2) + the MJD is {\bf not} computed. When an invalid day is supplied + (status J~=~3) the MJD {\bf is} computed. + \item The year must be $-$4699 ({\it i.e.}\ 4700BC) or later. + For year $n$BC use IY = $-(n-1)$. + \item An alternative to the present routine is sla\_CALDJ, which + accepts a year with the century missing. + \end{enumerate} +} +\aref{The algorithm is derived from that of Hatcher, + {\it Q.\,Jl.\,R.\,astr.\,Soc.}\ (1984) {\bf 25}, 53-55.} +%----------------------------------------------------------------------- +\routine{SLA\_CLYD}{Calendar to Year, Day} +{ + \action{Gregorian calendar date to year and day in year, in a Julian + calendar aligned to the 20th/21st century Gregorian calendar.} + \call{CALL sla\_CLYD (IY, IM, ID, NY, ND, J)} +} +\args{GIVEN} +{ + \spec{IY,IM,ID}{I}{year, month, day in Gregorian calendar} +} +\args{RETURNED} +{ + \spec{NY}{I}{year (re-aligned Julian calendar)} \\ + \spec{ND}{I}{day in year (1 = January 1st)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = bad year (before $-4711$)} \\ + \spec{}{}{\hspace{1.5em} 2 = bad month} \\ + \spec{}{}{\hspace{1.5em} 3 = bad day} +} +\notes +{ + \begin{enumerate} + \item The purpose of sla\_CLYD is to support sla\_EARTH, + sla\_MOON and sla\_ECOR. + \item Between 1900~March~1 and 2100~February~28 it returns answers + which are consistent with the ordinary Gregorian calendar. + Outside this range there will be a discrepancy which increases + by one day for every non-leap century year. + \item When an invalid year or month is supplied (status J~=~1 or J~=~2) + the results are {\bf not} computed. When a day is + supplied which is outside the conventional range (status J~=~3) + the results {\bf are} computed. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CR2AF}{Radians to Deg,Arcmin,Arcsec} +{ + \action{Convert an angle in radians to degrees, arcminutes, + arcseconds (single precision).} + \call{CALL sla\_CR2AF (NDP, ANGLE, SIGN, IDMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of arcseconds} \\ + \spec{ANGLE}{R}{angle in radians} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IDMSF}{I(4)}{degrees, arcminutes, arcseconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size of + ANGLE, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IDMSF(4). For example, + on a VAX computer, for ANGLE up to $2\pi$, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + \item The absolute value of ANGLE may exceed $2\pi$. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly $2\pi$ and rounds up to $360^{\circ}$, + by testing for IDMSF(1)=360 and setting IDMSF(1-4) to zero. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CR2TF}{Radians to Hour,Min,Sec} +{ + \action{Convert an angle in radians to hours, minutes, seconds + (single precision).} + \call{CALL sla\_CR2TF (NDP, ANGLE, SIGN, IHMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of seconds} \\ + \spec{ANGLE}{R}{angle in radians} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IHMSF}{I(4)}{hours, minutes, seconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size of + ANGLE, the format of REAL floating-point numbers on the target + machine, and the risk of overflowing IHMSF(4). For example, + on a VAX computer, for ANGLE up to $2\pi$, the available floating-point + precision corresponds roughly to NDP=3. This is well below + the ultimate limit of NDP=9 set by the capacity of the 32-bit + integer IHMSF(4). + \item The absolute value of ANGLE may exceed $2\pi$. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly $2\pi$ and rounds up to 24~hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. +\end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CS2C}{Spherical to Cartesian} +{ + \action{Spherical coordinates to Cartesian coordinates (single precision).} + \call{CALL sla\_CS2C (A, B, V)} +} +\args{GIVEN} +{ + \spec{A,B}{R}{spherical coordinates in radians: \radec\ {\it etc.}} +} +\args{RETURNED} +{ + \spec{V}{R(3)}{\xyz\ unit vector} +} +\anote{The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the {\it x}-axis + at zero longitude and latitude, and the {\it z}-axis at the + +ve latitude pole.} +%----------------------------------------------------------------------- +\routine{SLA\_CS2C6}{Spherical Pos/Vel to Cartesian} +{ + \action{Conversion of position \& velocity in spherical coordinates + to Cartesian coordinates (single precision).} + \call{CALL sla\_CS2C6 (A, B, R, AD, BD, RD, V)} +} +\args{GIVEN} +{ + \spec{A}{R}{longitude (radians) -- for example $\alpha$} \\ + \spec{B}{R}{latitude (radians) -- for example $\delta$} \\ + \spec{R}{R}{radial coordinate} \\ + \spec{AD}{R}{longitude derivative (radians per unit time)} \\ + \spec{BD}{R}{latitude derivative (radians per unit time)} \\ + \spec{RD}{R}{radial derivative} +} +\args{RETURNED} +{ + \spec{V}{R(6)}{\xyzxyzd} +} +%----------------------------------------------------------------------- +\routine{SLA\_CTF2D}{Hour,Min,Sec to Days} +{ + \action{Convert hours, minutes, seconds to days (single precision).} + \call{CALL sla\_CTF2D (IHOUR, IMIN, SEC, DAYS, J)} +} +\args{GIVEN} +{ + \spec{IHOUR}{I}{hours} \\ + \spec{IMIN}{I}{minutes} \\ + \spec{SEC}{R}{seconds} +} +\args{RETURNED} +{ + \spec{DAYS}{R}{interval in days} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = IHOUR outside range 0-23} \\ + \spec{}{}{\hspace{1.5em} 2 = IMIN outside range 0-59} \\ + \spec{}{}{\hspace{1.5em} 3 = SEC outside range 0-59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_CTF2R}{Hour,Min,Sec to Radians} +{ + \action{Convert hours, minutes, seconds to radians (single precision).} + \call{CALL sla\_CTF2R (IHOUR, IMIN, SEC, RAD, J)} +} +\args{GIVEN} +{ + \spec{IHOUR}{I}{hours} \\ + \spec{IMIN}{I}{minutes} \\ + \spec{SEC}{R}{seconds} +} +\args{RETURNED} +{ + \spec{RAD}{R}{angle in radians} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = IHOUR outside range 0-23} \\ + \spec{}{}{\hspace{1.5em} 2 = IMIN outside range 0-59} \\ + \spec{}{}{\hspace{1.5em} 3 = SEC outside range 0-59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DAF2R}{Deg,Arcmin,Arcsec to Radians} +{ + \action{Convert degrees, arcminutes, arcseconds to radians + (double precision).} + \call{CALL sla\_DAF2R (IDEG, IAMIN, ASEC, RAD, J)} +} +\args{GIVEN} +{ + \spec{IDEG}{I}{degrees} \\ + \spec{IAMIN}{I}{arcminutes} \\ + \spec{ASEC}{D}{arcseconds} +} +\args{RETURNED} +{ + \spec{RAD}{D}{angle in radians} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 1 = IDEG outside range 0$-$359} \\ + \spec{}{}{\hspace{1.5em} 2 = IAMIN outside range 0$-$59} \\ + \spec{}{}{\hspace{1.5em} 3 = ASEC outside range 0$-$59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DAFIN}{Sexagesimal character string to angle} +{ + \action{Decode a free-format sexagesimal string (degrees, arcminutes, + arcseconds) into a double precision floating point + number (radians).} + \call{CALL sla\_DAFIN (STRING, NSTRT, DRESLT, JF)} +} +\args{GIVEN} +{ + \spec{STRING}{C*(*)}{string containing deg, arcmin, arcsec fields} \\ + \spec{NSTRT}{I}{pointer to start of decode (beginning of STRING = 1)} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{advanced past the decoded angle} \\ + \spec{DRESLT}{D}{angle in radians} \\ + \spec{JF}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{0.7em} $+1$ = default, DRESLT unchanged (note 2)} \\ + \spec{}{}{\hspace{0.7em} $-1$ = bad degrees (note 3)} \\ + \spec{}{}{\hspace{0.7em} $-2$ = bad arcminutes (note 3)} \\ + \spec{}{}{\hspace{0.7em} $-3$ = bad arcseconds (note 3)} \\ +} +\goodbreak +\setlength{\oldspacing}{\topsep} +\setlength{\topsep}{0.3ex} +\begin{description} + \item [EXAMPLE]: \\ [1.5ex] + \begin{tabular}{p{7em}p{15em}p{12em}} + {\it argument} & {\it before} & {\it after} \\ \\ + STRING & $'$\verb*}-57 17 44.806 12 34 56.7}$'$ & unchanged \\ + NSTRT & 1 & 16 ({\it i.e.}\ pointing to 12...) \\ + RESLT & - & $-1.00000${\tt D0} \\ + JF & - & 0 + \end{tabular} + \item A further call to sla\_DAFIN, without adjustment of NSTRT, will + decode the second angle, \dms{12}{34}{56}{7}. +\end{description} +\setlength{\topsep}{\oldspacing} +\notes +{ + \begin{enumerate} + \item The first three ``fields'' in STRING are degrees, arcminutes, + arcseconds, separated by spaces or commas. The degrees field + may be signed, but not the others. The decoding is carried + out by the sla\_DFLTIN routine and is free-format. + \item Successive fields may be absent, defaulting to zero. For + zero status, the only combinations allowed are degrees alone, + degrees and arcminutes, and all three fields present. If all + three fields are omitted, a status of +1 is returned and DRESLT is + unchanged. In all other cases DRESLT is changed. + \item Range checking: + \begin{itemize} + \item The degrees field is not range checked. However, it is + expected to be integral unless the other two fields are absent. + \item The arcminutes field is expected to be 0-59, and integral if + the arcseconds field is present. If the arcseconds field + is absent, the arcminutes is expected to be 0-59.9999... + \item The arcseconds field is expected to be 0-59.9999... + \item Decoding continues even when a check has failed. Under these + circumstances the field takes the supplied value, defaulting to + zero, and the result DRESLT is computed and returned. + \end{itemize} + \item Further fields after the three expected ones are not treated as + an error. The pointer NSTRT is left in the correct state for + further decoding with the present routine or with sla\_DFLTIN + {\it etc}. See the example, above. + \item If STRING contains hours, minutes, seconds instead of + degrees {\it etc}, + or if the required units are turns (or days) instead of radians, + the result DRESLT should be multiplied as follows: \\ [1.5ex] + \begin{tabular}{p{6em}p{5em}p{18em}} + {\it for STRING} & {\it to obtain} & {\it multiply DRESLT by} \\ \\ + ${\circ}$~~\raisebox{-0.7ex}{$'$}~~\raisebox{-0.7ex}{$''$} + & radians & $1.0${\tt D0} \\ + ${\circ}$~~\raisebox{-0.7ex}{$'$}~~\raisebox{-0.7ex}{$''$} + & turns & $1/{2 \pi} = 0.1591549430918953358${\tt D0} \\ + h m s & radians & $15.0${\tt D0} \\ + h m s & days & $15/{2\pi} = 2.3873241463784300365${\tt D0} + \end{tabular} + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_DAT}{TAI$-$UTC} +{ + \action{Increment to be applied to Coordinated Universal Time UTC to give + International Atomic Time TAI.} + \call{D~=~sla\_DAT (UTC)} +} +\args{GIVEN} +{ + \spec{UTC}{D}{UTC date as a modified JD (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_DAT}{D}{TAI$-$UTC in seconds} +} +\notes +{ + \begin{enumerate} + \item The UTC is specified to be a date rather than a time to indicate + that care needs to be taken not to specify an instant which lies + within a leap second. Though in most cases UTC can include the + fractional part, correct behaviour on the day of a leap second + can be guaranteed only up to the end of the second + $23^{\rm h}\,59^{\rm m}\,59^{\rm s}$. + \item UTC began at 1960 January 1. To specify a UTC prior to this + date would be meaningless; in such cases the parameters + for the year 1960 are used by default. + \item This routine has to be updated on each occasion that a + leap second is announced, and programs using it relinked. + Refer to the program source code for information on when the + most recent leap second was added. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DAV2M}{Rotation Matrix from Axial Vector} +{ + \action{Form the rotation matrix corresponding to a given axial vector + (double precision).} + \call{CALL sla\_DAV2M (AXVEC, RMAT)} +} +\args{GIVEN} +{ + \spec{AXVEC}{D(3)}{axial vector (radians)} +} +\args{RETURNED} +{ + \spec{RMAT}{D(3,3)}{rotation matrix} +} +\notes +{ + \begin{enumerate} + \item A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the {\it Euler axis}, and the angle through which the + reference frame rotates is called the {\it Euler angle}. The axial + vector supplied to this routine has the same direction as the + Euler axis, and its magnitude is the Euler angle in radians. + \item If AXVEC is null, the unit matrix is returned. + \item The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DBEAR}{Direction Between Points on a Sphere} +{ + \action{Returns the bearing (position angle) of one point on a + sphere relative to another (double precision).} + \call{D~=~sla\_DBEAR (A1, B1, A2, B2)} +} +\args{GIVEN} +{ + \spec{A1,B1}{D}{spherical coordinates of one point} \\ + \spec{A2,B2}{D}{spherical coordinates of the other point} +} +\args{RETURNED} +{ + \spec{sla\_DBEAR}{D}{bearing from first point to second} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are \radec, + $[\lambda,\phi]$ {\it etc.}, in radians. + \item The result is the bearing (position angle), in radians, + of point [A2,B2] as seen + from point [A1,B1]. It is in the range $\pm \pi$. The sense + is such that if [A2,B2] + is a small distance due east of [A1,B1] the result + is about $+\pi/2$. Zero is returned + if the two points are coincident. + \item If either B-coordinate is outside the range $\pm\pi/2$, the + result may correspond to ``the long way round''. + \item The routine sla\_DPAV performs an equivalent function except + that the points are specified in the form of Cartesian unit + vectors. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DBJIN}{Decode String to B/J Epoch (DP)} +{ + \action{Decode a character string into a DOUBLE PRECISION number, + with special provision for Besselian and Julian epochs. + The string syntax is as for sla\_DFLTIN, prefixed by + an optional `B' or `J'.} + \call{CALL sla\_DBJIN (STRING, NSTRT, DRESLT, J1, J2)} +} +\args{GIVEN} +{ + \spec{STRING}{C}{string containing field to be decoded} \\ + \spec{NSTRT}{I}{pointer to first character of field in string} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{incremented past the decoded field} \\ + \spec{DRESLT}{D}{result} \\ + \spec{J1}{I}{DFLTIN status:} \\ + \spec{}{}{\hspace{0.7em} $-$1 = $-$OK} \\ + \spec{}{}{\hspace{1.5em} 0 = +OK} \\ + \spec{}{}{\hspace{1.5em} 1 = null field} \\ + \spec{}{}{\hspace{1.5em} 2 = error} \\ + \spec{J2}{I}{syntax flag:} \\ + \spec{}{}{\hspace{1.5em} 0 = normal DFLTIN syntax} \\ + \spec{}{}{\hspace{1.5em} 1 = `B' or `b'} \\ + \spec{}{}{\hspace{1.5em} 2 = `J' or `j'} +} +\notes +{ + \begin{enumerate} + \item The purpose of the syntax extensions is to help cope with mixed + FK4 and FK5 data, allowing fields such as `B1950' or `J2000' + to be decoded. + \item In addition to the syntax accepted by sla\_DFLTIN, + the following two extensions are recognized by sla\_DBJIN: + \begin{enumerate} + \item A valid non-null field preceded by the character `B' + (or `b') is accepted. + \item A valid non-null field preceded by the character `J' + (or `j') is accepted. + \end{enumerate} + \item The calling program is told of the `B' or `J' through an + supplementary status argument. The rest of + the arguments are as for sla\_DFLTIN. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DC62S}{Cartesian 6-Vector to Spherical} +{ + \action{Conversion of position \& velocity in Cartesian coordinates + to spherical coordinates (double precision).} + \call{CALL sla\_DC62S (V, A, B, R, AD, BD, RD)} +} +\args{GIVEN} +{ + \spec{V}{D(6)}{\xyzxyzd} +} +\args{RETURNED} +{ + \spec{A}{D}{longitude (radians)} \\ + \spec{B}{D}{latitude (radians)} \\ + \spec{R}{D}{radial coordinate} \\ + \spec{AD}{D}{longitude derivative (radians per unit time)} \\ + \spec{BD}{D}{latitude derivative (radians per unit time)} \\ + \spec{RD}{D}{radial derivative} +} +%----------------------------------------------------------------------- +\routine{SLA\_DCC2S}{Cartesian to Spherical} +{ + \action{Cartesian coordinates to spherical coordinates (double precision).} + \call{CALL sla\_DCC2S (V, A, B)} +} +\args{GIVEN} +{ + \spec{V}{D(3)}{\xyz\ vector} +} +\args{RETURNED} +{ + \spec{A,B}{D}{spherical coordinates in radians} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the {\it x}-axis + at zero longitude and latitude, and the {\it z}-axis at the + +ve latitude pole. + \item If V is null, zero A and B are returned. + \item At either pole, zero A is returned. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DCMPF}{Interpret Linear Fit} +{ + \action{Decompose an \xy\ linear fit into its constituent parameters: + zero points, scales, nonperpendicularity and orientation.} + \call{CALL sla\_DCMPF (COEFFS,XZ,YZ,XS,YS,PERP,ORIENT)} +} +\args{GIVEN} +{ + \spec{COEFFS}{D(6)}{transformation coefficients (see note)} +} +\args{RETURNED} +{ + \spec{XZ}{D}{{\it x} zero point} \\ + \spec{YZ}{D}{{\it y} zero point} \\ + \spec{XS}{D}{{\it x} scale} \\ + \spec{YS}{D}{{\it y} scale} \\ + \spec{PERP}{D}{nonperpendicularity (radians)} \\ + \spec{ORIENT}{D}{orientation (radians)} +} +\notes +{ + \begin{enumerate} + \item The model relates two sets of \xy\ coordinates as follows. + Naming the six elements of COEFFS $a,b,c,d,e$ \& $f$, + the model transforms coordinates $[x_{1},y_{1}\,]$ into coordinates + $[x_{2},y_{2}\,]$ as follows: + \begin{verse} + $x_{2} = a + bx_{1} + cy_{1}$ \\ + $y_{2} = d + ex_{1} + fy_{1}$ + \end{verse} + The sla\_DCMPF routine decomposes this transformation + into four steps: + \begin{enumerate} + \item Zero points: + \begin{verse} + $x' = x_{1} + {\rm XZ}$ \\ + $y' = y_{1} + {\rm YZ}$ + \end{verse} + \item Scales: + \begin{verse} + $x'' = x' {\rm XS}$ \\ + $y'' = y' {\rm YS}$ + \end{verse} + \item Nonperpendicularity: + \begin{verse} + $x''' = + x'' \cos {\rm PERP}/2 + y'' \sin {\rm PERP}/2$ \\ + $y''' = + x'' \sin {\rm PERP}/2 + y'' \cos {\rm PERP}/2$ + \end{verse} + \item Orientation: + \begin{verse} + $x_{2} = + x''' \cos {\rm ORIENT} + + y''' \sin {\rm ORIENT}$ \\ + $y_{2} = - x''' \sin {\rm ORIENT} + + y''' \cos {\rm ORIENT}$ + \end{verse} + \end{enumerate} + \item See also sla\_FITXY, sla\_PXY, sla\_INVF, sla\_XY2XY. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DCS2C}{Spherical to Cartesian} +{ + \action{Spherical coordinates to Cartesian coordinates (double precision).} + \call{CALL sla\_DCS2C (A, B, V)} +} +\args{GIVEN} +{ + \spec{A,B}{D}{spherical coordinates in radians: \radec\ {\it etc.}} +} +\args{RETURNED} +{ + \spec{V}{D(3)}{\xyz\ unit vector} +} +\anote{The spherical coordinates are longitude (+ve anticlockwise + looking from the +ve latitude pole) and latitude. The + Cartesian coordinates are right handed, with the {\it x}-axis + at zero longitude and latitude, and the {\it z}-axis at the + +ve latitude pole.} +%----------------------------------------------------------------------- +\routine{SLA\_DD2TF}{Days to Hour,Min,Sec} +{ + \action{Convert an interval in days into hours, minutes, seconds + (double precision).} + \call{CALL sla\_DD2TF (NDP, DAYS, SIGN, IHMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of seconds} \\ + \spec{DAYS}{D}{interval in days} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IHMSF}{I(4)}{hours, minutes, seconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size + of DAYS, the format of DOUBLE PRECISION floating-point numbers + on the target machine, and the risk of overflowing IHMSF(4). + For example, on a VAX computer, for DAYS up to 1D0, the available + floating-point precision corresponds roughly to NDP=12. However, + the practical limit is NDP=9, set by the capacity of the 32-bit + integer IHMSF(4). + \item The absolute value of DAYS may exceed 1D0. In cases where it + does not, it is up to the caller to test for and handle the + case where DAYS is very nearly 1D0 and rounds up to 24~hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. +\end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DE2H}{$h,\delta$ to Az,El} +{ + \action{Equatorial to horizon coordinates + (double precision).} + \call{CALL sla\_DE2H (HA, DEC, PHI, AZ, EL)} +} +\args{GIVEN} +{ + \spec{HA}{D}{hour angle (radians)} \\ + \spec{DEC}{D}{declination (radians)} \\ + \spec{PHI}{D}{latitude (radians)} +} +\args{RETURNED} +{ + \spec{AZ}{D}{azimuth (radians)} \\ + \spec{EL}{D}{elevation (radians)} +} +\notes +{ + \begin{enumerate} + \item Azimuth is returned in the range $0\!-\!2\pi$; north is zero, + and east is $+\pi/2$. Elevation is returned in the range + $\pm\pi$. + \item The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied. + \item In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type of azimuth and elevation. In + particular, it may be important to distinguish between + elevation as affected by refraction, which would + require the {\it observed} \hadec, and the elevation + {\it in vacuo}, which would require the {\it topocentric} + \hadec. + If the effects of diurnal aberration can be neglected, the + {\it apparent} \hadec\ may be used instead of the topocentric + \hadec. + \item No range checking of arguments is carried out. + \item In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DEULER}{Euler Angles to Rotation Matrix} +{ + \action{Form a rotation matrix from the Euler angles -- three + successive rotations about specified Cartesian axes + (double precision).} + \call{CALL sla\_DEULER (ORDER, PHI, THETA, PSI, RMAT)} +} +\args{GIVEN} +{ + \spec{ORDER}{C}{specifies about which axes the rotations occur} \\ + \spec{PHI}{D}{1st rotation (radians)} \\ + \spec{THETA}{D}{2nd rotation (radians)} \\ + \spec{PSI}{D}{3rd rotation (radians)} +} +\args{RETURNED} +{ + \spec{RMAT}{D(3,3)}{rotation matrix} +} +\notes +{ + \begin{enumerate} + \item A rotation is positive when the reference frame rotates + anticlockwise as seen looking towards the origin from the + positive region of the specified axis. + \item The characters of ORDER define which axes the three successive + rotations are about. A typical value is `ZXZ', indicating that + RMAT is to become the direction cosine matrix corresponding to + rotations of the reference frame through PHI radians about the + old {\it z}-axis, followed by THETA radians about the resulting + {\it x}-axis, + then PSI radians about the resulting {\it z}-axis. + \item The axis names can be any of the following, in any order or + combination: X, Y, Z, uppercase or lowercase, 1, 2, 3. Normal + axis labelling/numbering conventions apply; the {\it xyz} ($\equiv123$) + triad is right-handed. Thus, the `ZXZ' example given above + could be written `zxz' or `313' (or even `ZxZ' or `3xZ'). ORDER + is terminated by length or by the first unrecognized character. + Fewer than three rotations are acceptable, in which case the later + angle arguments are ignored. Zero rotations produces a unit RMAT. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DFLTIN}{Decode a Double Precision Number} +{ + \action{Convert free-format input into double precision floating point.} + \call{CALL sla\_DFLTIN (STRING, NSTRT, DRESLT, JFLAG)} +} +\args{GIVEN} +{ + \spec{STRING}{C}{string containing number to be decoded} \\ + \spec{NSTRT}{I}{pointer to where decoding is to commence} \\ + \spec{DRESLT}{D}{current value of result} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{advanced to next number} \\ + \spec{DRESLT}{D}{result} \\ + \spec{JFLAG}{I}{status: $-$1~=~$-$OK, 0~=~+OK, 1~=~null result, 2~=~error} +} +\notes +{ + \begin{enumerate} + \item The reason sla\_DFLTIN has separate `OK' status values + for + and $-$ is to enable minus zero to be detected. + This is of crucial importance + when decoding mixed-radix numbers. For example, an angle + expressed as degrees, arcminutes and arcseconds may have a + leading minus sign but a zero degrees field. + \item A TAB is interpreted as a space, and lowercase characters are + interpreted as uppercase. {\it n.b.}\ The test for TAB is + ASCII-specific. + \item The basic format is the sequence of fields $\pm n.n x \pm n$, + where $\pm$ is a sign + character `+' or `$-$', $n$ means a string of decimal digits, + `.' is a decimal point, and $x$, which indicates an exponent, + means `D' or `E'. Various combinations of these fields can be + omitted, and embedded blanks are permissible in certain places. + \item Spaces: + \begin{itemize} + \item Leading spaces are ignored. + \item Embedded spaces are allowed only after +, $-$, D or E, + and after the decimal point if the first sequence of + digits is absent. + \item Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + \end{itemize} + \item Delimiters: + \begin{itemize} + \item Any character other than +,$-$,0-9,.,D,E or space may be + used to signal the end of the number and terminate decoding. + \item Comma is recognized by sla\_DFLTIN as a special case; it + is skipped, leaving the pointer on the next character. See + 13, below. + \item Decoding will in all cases terminate if end of string + is reached. + \end{itemize} + \item Both signs are optional. The default is +. + \item The mantissa $n.n$ defaults to unity. + \item The exponent $x\!\pm\!n$ defaults to `D0'. + \item The strings of decimal digits may be of any length. + \item The decimal point is optional for whole numbers. + \item A {\it null result}\/ occurs when the string of characters + being decoded does not begin with +,$-$,0-9,.,D or E, or + consists entirely of spaces. When this condition is + detected, JFLAG is set to 1 and DRESLT is left untouched. + \item NSTRT = 1 for the first character in the string. + \item On return from sla\_DFLTIN, NSTRT is set ready for the next + decode -- following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to sla\_DFLTIN, otherwise + all subsequent calls will return a null result. + \item Errors (JFLAG=2) occur when: + \begin{itemize} + \item a +, $-$, D or E is left unsatisfied; or + \item the decimal point is present without at least + one decimal digit before or after it; or + \item an exponent more than 100 has been presented. + \end{itemize} + \item When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. This + may be after the point at which a more sophisticated + program could have detected the error. For example, + sla\_DFLTIN does not detect that `1D999' is unacceptable + (on a computer where this is so) until the entire number + has been decoded. + \item Certain highly unlikely combinations of mantissa and + exponent can cause arithmetic faults during the + decode, in some cases despite the fact that they + together could be construed as a valid number. + \item Decoding is left to right, one pass. + \item See also sla\_FLOTIN and sla\_INTIN. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DH2E}{Az,El to $h,\delta$} +{ + \action{Horizon to equatorial coordinates + (double precision).} + \call{CALL sla\_DH2E (AZ, EL, PHI, HA, DEC)} +} +\args{GIVEN} +{ + \spec{AZ}{D}{azimuth (radians)} \\ + \spec{EL}{D}{elevation (radians)} \\ + \spec{PHI}{D}{latitude (radians)} +} +\args{RETURNED} +{ + \spec{HA}{D}{hour angle (radians)} \\ + \spec{DEC}{D}{declination (radians)} +} +\notes +{ + \begin{enumerate} + \item The sign convention for azimuth is north zero, east $+\pi/2$. + \item HA is returned in the range $\pm\pi$. Declination is returned + in the range $\pm\pi$. + \item The latitude is (in principle) geodetic. In critical + applications, corrections for polar motion should be applied + (see sla\_POLMO). + \item In some applications it will be important to specify the + correct type of elevation in order to produce the required + type of \hadec. In particular, it may be important to + distinguish between the elevation as affected by refraction, + which will yield the {\it observed} \hadec, and the elevation + {\it in vacuo}, which will yield the {\it topocentric} + \hadec. If the + effects of diurnal aberration can be neglected, the + topocentric \hadec\ may be used as an approximation to the + {\it apparent} \hadec. + \item No range checking of arguments is carried out. + \item In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DIMXV}{Apply 3D Reverse Rotation} +{ + \action{Multiply a 3-vector by the inverse of a rotation + matrix (double precision).} + \call{CALL sla\_DIMXV (DM, VA, VB)} +} +\args{GIVEN} +{ + \spec{DM}{D(3,3)}{rotation matrix} \\ + \spec{VA}{D(3)}{vector to be rotated} +} +\args{RETURNED} +{ + \spec{VB}{D(3)}{result vector} +} +\notes +{ + \begin{enumerate} + \item This routine performs the operation: + \begin{verse} + {\bf b} = {\bf M}$^{T}\cdot${\bf a} + \end{verse} + where {\bf a} and {\bf b} are the 3-vectors VA and VB + respectively, and {\bf M} is the $3\times3$ matrix DM. + \item The main function of this routine is apply an inverse + rotation; under these circumstances, ${\bf \rm M}$ is + {\it orthogonal}, with its inverse the same as its transpose. + \item To comply with the ANSI Fortran 77 standard, VA and VB must + {\bf not} be the same array. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DJCAL}{MJD to Gregorian for Output} +{ + \action{Modified Julian Date to Gregorian Calendar Date, expressed + in a form convenient for formatting messages (namely + rounded to a specified precision, and with the fields + stored in a single array).} + \call{CALL sla\_DJCAL (NDP, DJM, IYMDF, J)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of days in fraction} \\ + \spec{DJM}{D}{modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{IYMDF}{I(4)}{year, month, day, fraction in Gregorian calendar} \\ + \spec{J}{I}{status: nonzero = out of range} +} +\notes +{ + \begin{enumerate} + \item Any date after 4701BC March 1 is accepted. + \item NDP should be 4 or less to avoid overflow on machines which + use 32-bit integers. + \end{enumerate} +} +\aref{The algorithm is derived from that of Hatcher, + {\it Q.\,Jl.\,R.\,astr.\,Soc.}\ (1984) {\bf 25}, 53-55.} +%----------------------------------------------------------------------- +\routine{SLA\_DJCL}{MJD to Year,Month,Day,Frac} +{ + \action{Modified Julian Date to Gregorian year, month, day, + and fraction of a day.} + \call{CALL sla\_DJCL (DJM, IY, IM, ID, FD, J)} +} +\args{GIVEN} +{ + \spec{DJM}{D}{modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{IY}{I}{year} \\ + \spec{IM}{I}{month} \\ + \spec{ID}{I}{day} \\ + \spec{FD}{D}{fraction of day} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{0.7em} $-$1 = unacceptable date (before 4701BC March 1)} +} +\aref{The algorithm is derived from that of Hatcher, + {\it Q.\,Jl.\,R.\,astr.\,Soc.}\ (1984) {\bf 25}, 53-55.} +%----------------------------------------------------------------------- +\routine{SLA\_DM2AV}{Rotation Matrix to Axial Vector} +{ + \action{From a rotation matrix, determine the corresponding axial vector + (double precision).} + \call{CALL sla\_DM2AV (RMAT, AXVEC)} +} +\args{GIVEN} +{ + \spec{RMAT}{D(3,3)}{rotation matrix} +} +\args{RETURNED} +{ + \spec{AXVEC}{D(3)}{axial vector (radians)} +} +\notes +{ + \begin{enumerate} + \item A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the {\it Euler axis}, and the angle through + which the reference frame rotates is called the {\it Euler angle}. + The {\it axial vector}\/ returned by this routine has the same + direction as the Euler axis, and its magnitude is the Euler angle + in radians. + \item The magnitude and direction of the axial vector can be separated + by means of the routine sla\_DVN. + \item The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + \item If RMAT is null, so is the result. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DMAT}{Solve Simultaneous Equations} +{ + \action{Matrix inversion and solution of simultaneous equations + (double precision).} + \call{CALL sla\_DMAT (N, A, Y, D, JF, IW)} +} +\args{GIVEN} +{ + \spec{N}{I}{number of unknowns} \\ + \spec{A}{D(N,N)}{matrix} \\ + \spec{Y}{D(N)}{vector} +} +\args{RETURNED} +{ + \spec{A}{D(N,N)}{matrix inverse} \\ + \spec{Y}{D(N)}{solution} \\ + \spec{D}{D}{determinant} \\ + \spec{JF}{I}{singularity flag: 0=OK} \\ + \spec{IW}{I(N)}{workspace} +} +\notes +{ + \begin{enumerate} + \item For the set of $n$ simultaneous linear equations in $n$ unknowns: + \begin{verse} + {\bf A}$\cdot${\bf y} = {\bf x} + \end{verse} + where: + \begin{itemize} + \item {\bf A} is a non-singular $n \times n$ matrix, + \item {\bf y} is the vector of $n$ unknowns, and + \item {\bf x} is the known vector, + \end{itemize} + sla\_DMAT computes: + \begin{itemize} + \item the inverse of matrix {\bf A}, + \item the determinant of matrix {\bf A}, and + \item the vector of $n$ unknowns {\bf y}. + \end{itemize} + Argument N is the order $n$, A (given) is the matrix {\bf A}, + Y (given) is the vector {\bf x} and Y (returned) + is the vector {\bf y}. + The argument A (returned) is the inverse matrix {\bf A}$^{-1}$, + and D is {\it det}\/({\bf A}). + \item JF is the singularity flag. If the matrix is non-singular, + JF=0 is returned. If the matrix is singular, JF=$-$1 + and D=0D0 are returned. In the latter case, the contents + of array A on return are undefined. + \item The algorithm is Gaussian elimination with partial pivoting. + This method is very fast; some much slower algorithms can give + better accuracy, but only by a small factor. + \item This routine replaces the obsolete sla\_DMATRX. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DMOON}{Approx Moon Pos/Vel} +{ + \action{Approximate geocentric position and velocity of the Moon + (double precision).} + \call{CALL sla\_DMOON (DATE, PV)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (loosely ET) as a Modified Julian Date (JD$-$2400000.5) +} +} +\args{RETURNED} +{ + \spec{PV}{D(6)}{Moon \xyzxyzd, mean equator and equinox + of date (AU, AU~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item This routine is a full implementation of the algorithm + published by Meeus (see reference). + \item Meeus quotes accuracies of \arcseci{10} in longitude, + \arcseci{3} in latitude and \arcsec{0}{2} arcsec in HP + (equivalent to about 20~km in distance). Comparison with + JPL~DE200 over the interval 1960-2025 gives RMS errors of + \arcsec{3}{7} and 83~mas/hour in longitude, + \arcsec{2}{3} arcsec and 48~mas/hour in latitude, + 11~km and 81~mm/s in distance. + The maximum errors over the same interval are + \arcseci{18} and \arcsec{0}{50}/hour in longitude, + \arcseci{11} and \arcsec{0}{24}/hour in latitude, + 40~km and 0.29~m/s in distance. + \item The original algorithm is expressed in terms of the obsolete + timescale {\it Ephemeris Time}. Either TDB or TT can be used, + but not UT without incurring significant errors (\arcseci{30} at + the present time) due to the Moon's \arcsec{0}{5}/s movement. + \item The algorithm is based on pre IAU 1976 standards. However, + the result has been moved onto the new (FK5) equinox, an + adjustment which is in any case much smaller than the + intrinsic accuracy of the procedure. + \item Velocity is obtained by a complete analytical differentiation + of the Meeus model. + \end{enumerate} +} +\aref{Meeus, {\it l'Astronomie}, June 1984, p348.} +%----------------------------------------------------------------------- +\routine{SLA\_DMXM}{Multiply $3\times3$ Matrices} +{ + \action{Product of two $3\times3$ matrices (double precision).} + \call{CALL sla\_DMXM (A, B, C)} +} +\args{GIVEN} +{ + \spec{A}{D(3,3)}{matrix {\bf A}} \\ + \spec{B}{D(3,3)}{matrix {\bf B}} +} +\args{RETURNED} +{ + \spec{C}{D(3,3)}{matrix result: {\bf A}$\times${\bf B}} +} +\anote{To comply with the ANSI Fortran 77 standard, A, B and C must + be different arrays. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended.} +%----------------------------------------------------------------------- +\routine{SLA\_DMXV}{Apply 3D Rotation} +{ + \action{Multiply a 3-vector by a rotation matrix (double precision).} + \call{CALL sla\_DMXV (DM, VA, VB)} +} +\args{GIVEN} +{ + \spec{DM}{D(3,3)}{rotation matrix} \\ + \spec{VA}{D(3)}{vector to be rotated} +} +\args{RETURNED} +{ + \spec{VB}{D(3)}{result vector} +} +\notes +{ + \begin{enumerate} + \item This routine performs the operation: + \begin{verse} + {\bf b} = {\bf M}$\cdot${\bf a} + \end{verse} + where {\bf a} and {\bf b} are the 3-vectors VA and VB + respectively, and {\bf M} is the $3\times3$ matrix DM. + \item The main function of this routine is apply a + rotation; under these circumstances, {\bf M} is a + {\it proper real orthogonal}\/ matrix. + \item To comply with the ANSI Fortran 77 standard, VA and VB must + {\bf not} be the same array. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DPAV}{Position-Angle Between Two Directions} +{ + \action{Returns the bearing (position angle) of one celestial + direction with respect to another (double precision).} + \call{D~=~sla\_DPAV (V1, V2)} +} +\args{GIVEN} +{ + \spec{V1}{D(3)}{direction cosines of one point} \\ + \spec{V2}{D(3)}{directions cosines of the other point} +} +\args{RETURNED} +{ + \spec{sla\_DPAV}{D}{position-angle of 2nd point with respect to 1st} +} +\notes +{ + \begin{enumerate} + \item The coordinate frames correspond to \radec, + $[\lambda,\phi]$ {\it etc.}. + \item The result is the bearing (position angle), in radians, + of point V2 as seen + from point V1. It is in the range $\pm \pi$. The sense + is such that if V2 + is a small distance due east of V1 the result + is about $+\pi/2$. Zero is returned + if the two points are coincident. + \item The routine sla\_DBEAR performs an equivalent function except + that the points are specified in the form of spherical coordinates. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_DR2AF}{Radians to Deg,Min,Sec,Frac} +{ + \action{Convert an angle in radians to degrees, arcminutes, arcseconds, + fraction (double precision).} + \call{CALL sla\_DR2AF (NDP, ANGLE, SIGN, IDMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of arcseconds} \\ + \spec{ANGLE}{D}{angle in radians} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IDMSF}{I(4)}{degrees, arcminutes, arcseconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size + of ANGLE, the format of DOUBLE~PRECISION floating-point numbers + on the target machine, and the risk of overflowing IDMSF(4). + For example, on a VAX computer, for ANGLE up to $2\pi$, the available + floating-point precision corresponds roughly to NDP=12. However, + the practical limit is NDP=9, set by the capacity of the 32-bit + integer IDMSF(4). + \item The absolute value of ANGLE may exceed $2\pi$. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly $2\pi$ and rounds up to $360^{\circ}$, + by testing for IDMSF(1)=360 and setting IDMSF(1-4) to zero. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DR2TF}{Radians to Hour,Min,Sec,Frac} +{ + \action{Convert an angle in radians to hours, minutes, seconds, + fraction (double precision).} + \call{CALL sla\_DR2TF (NDP, ANGLE, SIGN, IHMSF)} +} +\args{GIVEN} +{ + \spec{NDP}{I}{number of decimal places of seconds} \\ + \spec{ANGLE}{D}{angle in radians} +} +\args{RETURNED} +{ + \spec{SIGN}{C}{`+' or `$-$'} \\ + \spec{IHMSF}{I(4)}{hours, minutes, seconds, fraction} +} +\notes +{ + \begin{enumerate} + \item NDP less than zero is interpreted as zero. + \item The largest useful value for NDP is determined by the size + of ANGLE, the format of DOUBLE PRECISION floating-point numbers + on the target machine, and the risk of overflowing IHMSF(4). + For example, on a VAX computer, for ANGLE up to $2\pi$, the available + floating-point precision corresponds roughly to NDP=12. However, + the practical limit is NDP=9, set by the capacity of the 32-bit + integer IHMSF(4). + \item The absolute value of ANGLE may exceed $2\pi$. In cases where it + does not, it is up to the caller to test for and handle the + case where ANGLE is very nearly $2\pi$ and rounds up to 24~hours, + by testing for IHMSF(1)=24 and setting IHMSF(1-4) to zero. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DRANGE}{Put Angle into Range $\pm\pi$} +{ + \action{Normalize an angle into the range $\pm\pi$ (double precision).} + \call{D~=~sla\_DRANGE (ANGLE)} +} +\args{GIVEN} +{ + \spec{ANGLE}{D}{angle in radians} +} +\args{RETURNED} +{ + \spec{sla\_DRANGE}{D}{ANGLE expressed in the range $\pm\pi$.} +} +%----------------------------------------------------------------------- +\routine{SLA\_DRANRM}{Put Angle into Range $0\!-\!2\pi$} +{ + \action{Normalize an angle into the range $0\!-\!2\pi$ + (double precision).} + \call{D~=~sla\_DRANRM (ANGLE)} +} +\args{GIVEN} +{ + \spec{ANGLE}{D}{angle in radians} +} +\args{RETURNED} +{ + \spec{sla\_DRANRM}{D}{ANGLE expressed in the range $0\!-\!2\pi$} +} +%----------------------------------------------------------------------- +\routine{SLA\_DS2C6}{Spherical Pos/Vel to Cartesian} +{ + \action{Conversion of position \& velocity in spherical coordinates + to Cartesian coordinates (double precision).} + \call{CALL sla\_DS2C6 (A, B, R, AD, BD, RD, V)} +} +\args{GIVEN} +{ + \spec{A}{D}{longitude (radians) -- for example $\alpha$} \\ + \spec{B}{D}{latitude (radians) -- for example $\delta$} \\ + \spec{R}{D}{radial coordinate} \\ + \spec{AD}{D}{longitude derivative (radians per unit time)} \\ + \spec{BD}{D}{latitude derivative (radians per unit time)} \\ + \spec{RD}{D}{radial derivative} +} +\args{RETURNED} +{ + \spec{V}{D(6)}{\xyzxyzd} +} +%----------------------------------------------------------------------- +\routine{SLA\_DS2TP}{Spherical to Tangent Plane} +{ + \action{Projection of spherical coordinates onto the tangent plane + (double precision).} + \call{CALL sla\_DS2TP (RA, DEC, RAZ, DECZ, XI, ETA, J)} +} +\args{GIVEN} +{ + \spec{RA,DEC}{D}{spherical coordinates of star (radians)} \\ + \spec{RAZ,DECZ}{D}{spherical coordinates of tangent point (radians)} +} +\args{RETURNED} +{ + \spec{XI,ETA}{D}{tangent plane coordinates (radians)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK, star on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 1 = error, star too far from axis} \\ + \spec{}{}{\hspace{1.5em} 2 = error, antistar on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 3 = error, antistar too far from axis} +} +\notes +{ + \begin{enumerate} + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_DV2TP is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DSEP}{Angle Between 2 Points on Sphere} +{ + \action{Angle between two points on a sphere (double precision).} + \call{D~=~sla\_DSEP (A1, B1, A2, B2)} +} +\args{GIVEN} +{ + \spec{A1,B1}{D}{spherical coordinates of one point (radians)} \\ + \spec{A2,B2}{D}{spherical coordinates of the other point (radians)} +} +\args{RETURNED} +{ + \spec{sla\_DSEP}{D}{angle between [A1,B1] and [A2,B2] in radians} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are right ascension and declination, + longitude and latitude, {\it etc.}, in radians. + \item The result is always positive. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DT}{Approximate ET minus UT} +{ + \action{Estimate $\Delta$T, the offset between dynamical time + and Universal Time, for a given historical epoch.} + \call{D~=~sla\_DT (EPOCH)} +} +\args{GIVEN} +{ + \spec{EPOCH}{D}{(Julian) epoch ({\it e.g.}\ 1850D0)} +} +\args{RETURNED} +{ + \spec{sla\_DT}{D}{approximate ET$-$UT (after 1984, TT$-$UT1) in seconds} +} +\notes +{ + \begin{enumerate} + \item Depending on the epoch, one of three parabolic approximations + is used: +\begin{tabbing} +xx \= xxxxxxxxxxxxxxxxxx \= \kill +\> before AD 979 \> Stephenson \& Morrison's 390 BC to AD 948 model \\ +\> AD 979 to AD 1708 \> Stephenson \& Morrison's AD 948 to AD 1600 model \\ +\> after AD 1708 \> McCarthy \& Babcock's post-1650 model +\end{tabbing} + The breakpoints are chosen to ensure continuity: they occur + at places where the adjacent models give the same answer as + each other. + \item The accuracy is modest, with errors of up to $20^{\rm s}$ during + the interval since 1650, rising to perhaps $30^{\rm m}$ + by 1000~BC. Comparatively accurate values from AD~1600 + are tabulated in + the {\it Astronomical Almanac}\/ (see section K8 of the 1995 + edition). + \item The use of {\tt DOUBLE PRECISION} for both argument and result is + simply for compatibility with other SLALIB time routines. + \item The models used are based on a lunar tidal acceleration value + of \arcsec{-26}{00} per century. + \end{enumerate} +} +\aref{Seidelmann, P.K.\ (ed), 1992. {\it Explanatory + Supplement to the Astronomical Almanac,}\/ ISBN~0-935702-68-7. + This contains references to the papers by Stephenson \& Morrison + and by McCarthy \& Babcock which describe the models used here.} +%----------------------------------------------------------------------- +\routine{SLA\_DTF2D}{Hour,Min,Sec to Days} +{ + \action{Convert hours, minutes, seconds to days (double precision).} + \call{CALL sla\_DTF2D (IHOUR, IMIN, SEC, DAYS, J)} +} +\args{GIVEN} +{ + \spec{IHOUR}{I}{hours} \\ + \spec{IMIN}{I}{minutes} \\ + \spec{SEC}{D}{seconds} +} +\args{RETURNED} +{ + \spec{DAYS}{D}{interval in days} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = IHOUR outside range 0-23} \\ + \spec{}{}{\hspace{1.5em} 2 = IMIN outside range 0-59} \\ + \spec{}{}{\hspace{1.5em} 3 = SEC outside range 0-59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTF2R}{Hour,Min,Sec to Radians} +{ + \action{Convert hours, minutes, seconds to radians (double precision).} + \call{CALL sla\_DTF2R (IHOUR, IMIN, SEC, RAD, J)} +} +\args{GIVEN} +{ + \spec{IHOUR}{I}{hours} \\ + \spec{IMIN}{I}{minutes} \\ + \spec{SEC}{D}{seconds} +} +\args{RETURNED} +{ + \spec{RAD}{D}{angle in radians} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} 1 = IHOUR outside range 0-23} \\ + \spec{}{}{\hspace{1.5em} 2 = IMIN outside range 0-59} \\ + \spec{}{}{\hspace{1.5em} 3 = SEC outside range 0-59.999$\cdots$} +} +\notes +{ + \begin{enumerate} + \item The result is computed even if any of the range checks fail. + \item The sign must be dealt with outside this routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTP2S}{Tangent Plane to Spherical} +{ + \action{Transform tangent plane coordinates into spherical + coordinates (double precision)} + \call{CALL sla\_DTP2S (XI, ETA, RAZ, DECZ, RA, DEC)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{D}{tangent plane rectangular coordinates (radians)} \\ + \spec{RAZ,DECZ}{D}{spherical coordinates of tangent point (radians)} +} +\args{RETURNED} +{ + \spec{RA,DEC}{D}{spherical coordinates (radians)} +} +\notes +{ + \begin{enumerate} + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_DTP2V is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTP2V}{Tangent Plane to Direction Cosines} +{ + \action{Given the tangent-plane coordinates of a star and the direction + cosines of the tangent point, determine the direction cosines + of the star + (double precision).} + \call{CALL sla\_DTP2V (XI, ETA, V0, V)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{D}{tangent plane coordinates of star (radians)} \\ + \spec{V0}{D(3)}{direction cosines of tangent point} +} +\args{RETURNED} +{ + \spec{V}{D(3)}{direction cosines of star} +} +\notes +{ + \begin{enumerate} + \item If vector V0 is not of unit length, the returned vector V will + be wrong. + \item If vector V0 points at a pole, the returned vector V will be + based on the arbitrary assumption that $\alpha=0$ at + the tangent point. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_DTP2S. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTPS2C}{Plate centre from $\xi,\eta$ and $\alpha,\delta$} +{ + \action{From the tangent plane coordinates of a star of known \radec, + determine the \radec\ of the tangent point (double precision)} + \call{CALL sla\_DTPS2C (XI, ETA, RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2, N)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{D}{tangent plane rectangular coordinates (radians)} \\ + \spec{RA,DEC}{D}{spherical coordinates (radians)} +} +\args{RETURNED} +{ + \spec{RAZ1,DECZ1}{D}{spherical coordinates of tangent point, + solution 1} \\ + \spec{RAZ2,DECZ2}{D}{spherical coordinates of tangent point, + solution 2} \\ + \spec{N}{I}{number of solutions:} \\ + \spec{}{}{\hspace{1em} 0 = no solutions returned (note 2)} \\ + \spec{}{}{\hspace{1em} 1 = only the first solution is useful (note 3)} \\ + \spec{}{}{\hspace{1em} 2 = there are two useful solutions (note 3)} +} +\notes +{ + \begin{enumerate} + \item The RAZ1 and RAZ2 values returned are in the range $0\!-\!2\pi$. + \item Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero $\xi$ value, and hence it is + meaningless to ask where the tangent point would have to be + to bring about this combination of $\xi$ and $\delta$. + \item Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N\,=\,1 + indicates only one useful solution, the usual case; under + these circumstances, the second solution corresponds to the + ``over-the-pole'' case, and this is reflected in the values + of RAZ2 and DECZ2 which are returned. + \item The DECZ1 and DECZ2 values returned are in the range $\pm\pi$, + but in the ordinary, non-pole-crossing, case, the range is + $\pm\pi/2$. + \item RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2 are all in radians. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_DTPV2C is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTPV2C}{Plate centre from $\xi,\eta$ and $x,y,z$} +{ + \action{From the tangent plane coordinates of a star of known + direction cosines, determine the direction cosines + of the tangent point (double precision)} + \call{CALL sla\_DTPV2C (XI, ETA, V, V01, V02, N)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{D}{tangent plane coordinates of star (radians)} \\ + \spec{V}{D(3)}{direction cosines of star} +} +\args{RETURNED} +{ + \spec{V01}{D(3)}{direction cosines of tangent point, solution 1} \\ + \spec{V01}{D(3)}{direction cosines of tangent point, solution 2} \\ + \spec{N}{I}{number of solutions:} \\ + \spec{}{}{\hspace{1em} 0 = no solutions returned (note 2)} \\ + \spec{}{}{\hspace{1em} 1 = only the first solution is useful (note 3)} \\ + \spec{}{}{\hspace{1em} 2 = there are two useful solutions (note 3)} +} +\notes +{ + \begin{enumerate} + \item The vector V must be of unit length or the result will be wrong. + \item Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value. + \item Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. + N\,=\,1 + indicates only one useful solution, the usual case; under these + circumstances, the second solution can be regarded as valid if + the vector V02 is interpreted as the ``over-the-pole'' case. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_DTPS2C. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DTT}{TT minus UTC} +{ + \action{Compute $\Delta$TT, the increment to be applied to + Coordinated Universal Time UTC to give + Terrestrial Time TT.} + \call{D~=~sla\_DTT (DJU)} +} +\args{GIVEN} +{ + \spec{DJU}{D}{UTC date as a modified JD (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_DTT}{D}{TT$-$UTC in seconds} +} +\notes +{ + \begin{enumerate} + \item The UTC is specified to be a date rather than a time to indicate + that care needs to be taken not to specify an instant which lies + within a leap second. Though in most cases UTC can include the + fractional part, correct behaviour on the day of a leap second + can be guaranteed only up to the end of the second + $23^{\rm h}\,59^{\rm m}\,59^{\rm s}$. + \item Pre 1972 January 1 a fixed value of 10 + ET$-$TAI is returned. + \item TT is one interpretation of the defunct timescale + {\it Ephemeris Time}, ET. + \item See also the routine sla\_DT, which roughly estimates ET$-$UT for + historical epochs. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DV2TP}{Direction Cosines to Tangent Plane} +{ + \action{Given the direction cosines of a star and of the tangent point, + determine the star's tangent-plane coordinates + (double precision).} + \call{CALL sla\_DV2TP (V, V0, XI, ETA, J)} +} +\args{GIVEN} +{ + \spec{V}{D(3)}{direction cosines of star} \\ + \spec{V0}{D(3)}{direction cosines of tangent point} +} +\args{RETURNED} +{ + \spec{XI,ETA}{D}{tangent plane coordinates (radians)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK, star on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 1 = error, star too far from axis} \\ + \spec{}{}{\hspace{1.5em} 2 = error, antistar on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 3 = error, antistar too far from axis} +} +\notes +{ + \begin{enumerate} + \item If vector V0 is not of unit length, or if vector V is of zero + length, the results will be wrong. + \item If V0 points at a pole, the returned $\xi,\eta$ + will be based on the + arbitrary assumption that $\alpha=0$ at the tangent point. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_DS2TP. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_DVDV}{Scalar Product} +{ + \action{Scalar product of two 3-vectors (double precision).} + \call{D~=~sla\_DVDV (VA, VB)} +} +\args{GIVEN} +{ + \spec{VA}{D(3)}{first vector} \\ + \spec{VB}{D(3)}{second vector} +} +\args{RETURNED} +{ + \spec{sla\_DVDV}{D}{scalar product VA.VB} +} +%----------------------------------------------------------------------- +\routine{SLA\_DVN}{Normalize Vector} +{ + \action{Normalize a 3-vector, also giving the modulus (double precision).} + \call{CALL sla\_DVN (V, UV, VM)} +} +\args{GIVEN} +{ + \spec{V}{D(3)}{vector} +} +\args{RETURNED} +{ + \spec{UV}{D(3)}{unit vector in direction of V} \\ + \spec{VM}{D}{modulus of V} +} +\anote{If the modulus of V is zero, UV is set to zero as well.} +%----------------------------------------------------------------------- +\routine{SLA\_DVXV}{Vector Product} +{ + \action{Vector product of two 3-vectors (double precision).} + \call{CALL sla\_DVXV (VA, VB, VC)} +} +\args{GIVEN} +{ + \spec{VA}{D(3)}{first vector} \\ + \spec{VB}{D(3)}{second vector} +} +\args{RETURNED} +{ + \spec{VC}{D(3)}{vector product VA$\times$VB} +} +%----------------------------------------------------------------------- +\routine{SLA\_E2H}{$h,\delta$ to Az,El} +{ + \action{Equatorial to horizon coordinates + (single precision).} + \call{CALL sla\_DE2H (HA, DEC, PHI, AZ, EL)} +} +\args{GIVEN} +{ + \spec{HA}{R}{hour angle (radians)} \\ + \spec{DEC}{R}{declination (radians)} \\ + \spec{PHI}{R}{latitude (radians)} +} +\args{RETURNED} +{ + \spec{AZ}{R}{azimuth (radians)} \\ + \spec{EL}{R}{elevation (radians)} +} +\notes +{ + \begin{enumerate} + \item Azimuth is returned in the range $0\!-\!2\pi$; north is zero, + and east is $+\pi/2$. Elevation is returned in the range + $\pm\pi$. + \item The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied. + \item In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type of azimuth and elevation. In + particular, it may be important to distinguish between + elevation as affected by refraction, which would + require the {\it observed} \hadec, and the elevation + {\it in vacuo}, which would require the {\it topocentric} + \hadec. + If the effects of diurnal aberration can be neglected, the + {\it apparent} \hadec\ may be used instead of the topocentric + \hadec. + \item No range checking of arguments is carried out. + \item In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and (for tracking a star) + sine and cosine of declination. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_EARTH}{Approx Earth Pos/Vel} +{ + \action{Approximate heliocentric position and velocity of the Earth + (single precision).} + \call{CALL sla\_EARTH (IY, ID, FD, PV)} +} +\args{GIVEN} +{ + \spec{IY}{I}{year} \\ + \spec{ID}{I}{day in year (1 = Jan 1st)} \\ + \spec{FD}{R}{fraction of day} +} +\args{RETURNED} +{ + \spec{PV}{R(6)}{Earth \xyzxyzd\ (AU, AU~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900~March~1 to 2100~February~28. + The year and day can be obtained by calling sla\_CALYD or + sla\_CLYD. + \item The Earth heliocentric 6-vector is referred to the + FK4 mean equator and equinox of date. + \item Maximum/RMS errors 1950-2050: + \begin{itemize} + \item 13/5~$\times10^{-5}$~AU = 19200/7600~km in position + \item 47/26~$\times10^{-10}$~AU~s$^{-1}$ = + 0.0070/0.0039~km~s$^{-1}$ in speed + \end{itemize} + \item More accurate results are obtainable with the routine sla\_EVP. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_ECLEQ}{Ecliptic to Equatorial} +{ + \action{Transformation from ecliptic longitude and latitude to + J2000.0 \radec.} + \call{CALL sla\_ECLEQ (DL, DB, DATE, DR, DD)} +} +\args{GIVEN} +{ + \spec{DL,DB}{D}{ecliptic longitude and latitude + (mean of date, IAU 1980 theory, radians)} \\ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date + (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{DR,DD}{D}{J2000.0 mean \radec\ (radians)} +} +%----------------------------------------------------------------------- +\routine{SLA\_ECMAT}{Form $\alpha,\delta\rightarrow\lambda,\beta$ Matrix} +{ + \action{Form the equatorial to ecliptic rotation matrix (IAU 1980 theory).} + \call{CALL sla\_ECMAT (DATE, RMAT)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date + (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{RMAT}{D(3,3)}{rotation matrix} +} +\notes +{ + \begin{enumerate} + \item RMAT is matrix {\bf M} in the expression + {\bf v}$_{ecl}$~=~{\bf M}$\cdot${\bf v}$_{equ}$. + \item The equator, equinox and ecliptic are mean of date. + \end{enumerate} +} +\aref{Murray, C.A., {\it Vectorial Astrometry}, section 4.3.} +%----------------------------------------------------------------------- +\routine{SLA\_ECOR}{RV \& Time Corrns to Sun} +{ + \action{Component of Earth orbit velocity and heliocentric + light time in a given direction.} + \call{CALL sla\_ECOR (RM, DM, IY, ID, FD, RV, TL)} +} +\args{GIVEN} +{ + \spec{RM,DM}{R}{mean \radec\ of date (radians)} \\ + \spec{IY}{I}{year} \\ + \spec{ID}{I}{day in year (1 = Jan 1st)} \\ + \spec{FD}{R}{fraction of day} +} +\args{RETURNED} +{ + \spec{RV}{R}{component of Earth orbital velocity (km~s$^{-1}$)} \\ + \spec{TL}{R}{component of heliocentric light time (s)} +} +\notes +{ + \begin{enumerate} + \item The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900 March 1 to 2100 February 28. + The year and day can be obtained by calling sla\_CALYD or + sla\_CLYD. + \item Sign convention: + \begin{itemize} + \item The velocity component is +ve when the + Earth is receding from + the given point on the sky. + \item The light time component is +ve + when the Earth lies between the Sun and + the given point on the sky. + \end{itemize} + \item Accuracy: + \begin{itemize} + \item The velocity component is usually within 0.004~km~s$^{-1}$ + of the correct value and is never in error by more than + 0.007~km~s$^{-1}$. + \item The error in light time correction is about + \tsec{0}{03} at worst, + but is usually better than \tsec{0}{01}. + \end{itemize} + For applications requiring higher accuracy, see the sla\_EVP routine. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_EG50}{B1950 $\alpha,\delta$ to Galactic} +{ + \action{Transformation from B1950.0 FK4 equatorial coordinates to + IAU 1958 galactic coordinates.} + \call{CALL sla\_EG50 (DR, DD, DL, DB)} +} +\args{GIVEN} +{ + \spec{DR,DD}{D}{B1950.0 \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal\ (radians)} +} +\anote{The equatorial coordinates are B1950.0 FK4. Use the + routine sla\_EQGAL if conversion from J2000.0 FK5 coordinates + is required.} +\aref{Blaauw {\it et al.}, 1960, {\it Mon.Not.R.astr.Soc.}, + {\bf 121}, 123.} +%----------------------------------------------------------------------- +\routine{SLA\_EL2UE}{Conventional to Universal Elements} +{ + \action{Transform conventional osculating orbital elements + into ``universal'' form.} + \call{CALL sla\_EL2UE (\vtop{ + \hbox{DATE, JFORM, EPOCH, ORBINC, ANODE,} + \hbox{PERIH, AORQ, E, AORL, DM,} + \hbox{U, JSTAT)}}} +} +\args{GIVEN} +{ + \spec{DATE}{D}{epoch (TT MJD) of osculation (Note~3)} \\ + \spec{JFORM}{I}{choice of element set (1-3; Note~6)} \\ + \spec{EPOCH}{D}{epoch of elements ($t_0$ or $T$, TT MJD)} \\ + \spec{ORBINC}{D}{inclination ($i$, radians)} \\ + \spec{ANODE}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH}{D}{longitude or argument of perihelion + ($\varpi$ or $\omega$,} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{AORQ}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E}{D}{eccentricity ($e$)} \\ + \spec{AORL}{D}{mean anomaly or longitude + ($M$ or $L$, radians,} \\ + \spec{}{}{\hspace{1.5em} JFORM=1,2 only)} \\ + \spec{DM}{D}{daily motion ($n$, radians, JFORM=1 only)} +} +\args{RETURNED} +{ + \spec{U}{D(13)}{universal orbital elements (Note~1)} \\ + \specel {(1)} {combined mass ($M+m$)} \\ + \specel {(2)} {total energy of the orbit ($\alpha$)} \\ + \specel {(3)} {reference (osculating) epoch ($t_0$)} \\ + \specel {(4-6)} {position at reference epoch (${\rm \bf r}_0$)} \\ + \specel {(7-9)} {velocity at reference epoch (${\rm \bf v}_0$)} \\ + \specel {(10)} {heliocentric distance at reference epoch} \\ + \specel {(11)} {${\rm \bf r}_0.{\rm \bf v}_0$} \\ + \specel {(12)} {date ($t$)} \\ + \specel {(13)} {universal eccentric anomaly ($\psi$) of date, + approx} \\ \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{1.95em} 0 = OK} \\ + \spec{}{}{\hspace{1.2em} $-$1 = illegal JFORM} \\ + \spec{}{}{\hspace{1.2em} $-$2 = illegal E} \\ + \spec{}{}{\hspace{1.2em} $-$3 = illegal AORQ} \\ + \spec{}{}{\hspace{1.2em} $-$4 = illegal DM} \\ + \spec{}{}{\hspace{1.2em} $-$5 = numerical error} +} +\notes +{ + \begin{enumerate} + \item The ``universal'' elements are those which define the orbit for + the purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i)~$\alpha$, which is proportional to the total energy of the + orbit, (ii)~the heliocentric distance at epoch, + (iii)~the outwards component of the velocity at the given epoch, + (iv)~an estimate of $\psi$, the ``universal eccentric anomaly'' at a + given date and (v)~that date. + \item The companion routine is sla\_UE2PV. This takes the set of numbers + that the present routine outputs and uses them to derive the + object's position and velocity. A single prediction requires one + call to the present routine followed by one call to sla\_UE2PV; + for convenience, the two calls are packaged as the routine + sla\_PLANEL. Multiple predictions may be made by again calling the + present routine once, but then calling sla\_UE2PV multiple times, + which is faster than multiple calls to sla\_PLANEL. + \item DATE is the epoch of osculation. It is in the TT timescale + (formerly Ephemeris Time, ET) and is a Modified Julian Date + (JD$-$2400000.5). + \item The supplied orbital elements are with respect to the J2000 + ecliptic and equinox. The position and velocity parameters + returned in the array U are with respect to the mean equator and + equinox of epoch J2000, and are for the perihelion prior to the + specified epoch. + \item The universal elements returned in the array U are in canonical + units (solar masses, AU and canonical days). + \item Three different element-format options are supported, as + follows. \\ + + JFORM=1, suitable for the major planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> longitude of perihelion $\varpi$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean longitude $L$ (radians) \\ + \> DM \> = \> daily motion $n$ (radians) + \end{tabbing} + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e \leq 10 )$ + \end{tabbing} + \item Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + \item The algorithm was originally adapted from the EPHSLA program of + D.\,H.\,P.\,Jones (private communication, 1996). The method + is based on Stumpff's Universal Variables. + \end{enumerate} +} +\aref{Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983.} +%------------------------------------------------------------------------------ +\routine{SLA\_EPB}{MJD to Besselian Epoch} +{ + \action{Conversion of Modified Julian Date to Besselian Epoch.} + \call{D~=~sla\_EPB (DATE)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{Modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_EPB}{D}{Besselian Epoch} +} +\aref{Lieske, J.H., 1979, {\it Astr.Astrophys.}\ {\bf 73}, 282.} +%----------------------------------------------------------------------- +\routine{SLA\_EPB2D}{Besselian Epoch to MJD} +{ + \action{Conversion of Besselian Epoch to Modified Julian Date.} + \call{D~=~sla\_EPB2D (EPB)} +} +\args{GIVEN} +{ + \spec{EPB}{D}{Besselian Epoch} +} +\args{RETURNED} +{ + \spec{sla\_EPB2D}{D}{Modified Julian Date (JD$-$2400000.5)} +} +\aref{Lieske, J.H., 1979. {\it Astr.Astrophys.}\ {\bf 73}, 282.} +%----------------------------------------------------------------------- +\routine{SLA\_EPCO}{Convert Epoch to B or J} +{ + \action{Convert an epoch to Besselian or Julian to match another one.} + \call{D~=~sla\_EPCO (K0, K, E)} + +} +\args{GIVEN} +{ + \spec{K0}{C}{form of result: `B'=Besselian, `J'=Julian} \\ + \spec{K}{C}{form of given epoch: `B' or `J'} \\ + \spec{E}{D}{epoch} +} +\args{RETURNED} +{ + \spec{sla\_EPCO}{D}{the given epoch converted as necessary} +} +\notes +{ + \begin{enumerate} + \item The result is always either equal to or very close to + the given epoch E. The routine is required only in + applications where punctilious treatment of heterogeneous + mixtures of star positions is necessary. + \item K0 and K are not validated. They are interpreted as follows: + \begin{itemize} + \item If K0 and K are the same, the result is E. + \item If K0 is `B' and K isn't, the conversion is J to B. + \item In all other cases, the conversion is B to J. + \end{itemize} + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_EPJ}{MJD to Julian Epoch} +{ + \action{Convert Modified Julian Date to Julian Epoch.} + \call{D~=~sla\_EPJ (DATE)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{Modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_EPJ}{D}{Julian Epoch} +} +\aref{Lieske, J.H., 1979.\ {\it Astr.Astrophys.}, {\bf 73}, 282.} +%----------------------------------------------------------------------- +\routine{SLA\_EPJ2D}{Julian Epoch to MJD} +{ + \action{Convert Julian Epoch to Modified Julian Date.} + \call{D~=~sla\_EPJ2D (EPJ)} +} +\args{GIVEN} +{ + \spec{EPJ}{D}{Julian Epoch} +} +\args{RETURNED} +{ + \spec{sla\_EPJ2D}{D}{Modified Julian Date (JD$-$2400000.5)} +} +\aref{Lieske, J.H., 1979.\ {\it Astr.Astrophys.}, {\bf 73}, 282.} +%----------------------------------------------------------------------- +\routine{SLA\_EQECL}{J2000 $\alpha,\delta$ to Ecliptic} +{ + \action{Transformation from J2000.0 equatorial coordinates to + ecliptic longitude and latitude.} + \call{CALL sla\_EQECL (DR, DD, DATE, DL, DB)} +} +\args{GIVEN} +{ + \spec{DR,DD}{D}{J2000.0 mean \radec\ (radians)} \\ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{DL,DB}{D}{ecliptic longitude and latitude + (mean of date, IAU 1980 theory, radians)} +} +%----------------------------------------------------------------------- +\routine{SLA\_EQEQX}{Equation of the Equinoxes} +{ + \action{Equation of the equinoxes (IAU 1994).} + \call{D~=~sla\_EQEQX (DATE)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_EQEQX}{D}{The equation of the equinoxes (radians)} +} +\notes{ + \begin{enumerate} + \item The equation of the equinoxes is defined here as GAST~$-$~GMST: + it is added to a {\it mean}\/ sidereal time to give the + {\it apparent}\/ sidereal time. + \item The change from the classic ``textbook'' expression + $\Delta\psi\,cos\,\epsilon$ occurred with IAU Resolution C7, + Recommendation~3 (1994). The new formulation takes into + account cross-terms between the various precession and + nutation quantities, amounting to about 3~milliarcsec. + The transition from the old to the new model officially + takes place on 1997 February~27. + \end{enumerate} +} +\aref{Capitaine, N.\ \& Gontier, A.-M.\ (1993), + {\it Astron. Astrophys.}, + {\bf 275}, 645-650.} +%----------------------------------------------------------------------- +\routine{SLA\_EQGAL}{J2000 $\alpha,\delta$ to Galactic} +{ + \action{Transformation from J2000.0 FK5 equatorial coordinates to + IAU 1958 galactic coordinates.} + \call{CALL sla\_EQGAL (DR, DD, DL, DB)} +} +\args{GIVEN} +{ + \spec{DR,DD}{D}{J2000.0 \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal\ (radians)} +} +\anote{The equatorial coordinates are J2000.0 FK5. Use the routine + sla\_EG50 if conversion from B1950.0 FK4 coordinates is required.} +\aref{Blaauw {\it et al.}, 1960, {\it Mon.Not.R.astr.Soc.}, + {\bf 121}, 123.} +%----------------------------------------------------------------------- +\routine{SLA\_ETRMS}{E-terms of Aberration} +{ + \action{Compute the E-terms vector -- the part of the annual + aberration which arises from the eccentricity of the + Earth's orbit.} + \call{CALL sla\_ETRMS (EP, EV)} +} +\args{GIVEN} +{ + \spec{EP}{D}{Besselian epoch} +} +\args{RETURNED} +{ + \spec{EV}{D(3)}{E-terms as $[\Delta x, \Delta y, \Delta z\,]$} +} +\anote{Note the use of the J2000 aberration constant (\arcsec{20}{49552}). + This is a reflection of the fact that the E-terms embodied in + existing star catalogues were computed from a variety of + aberration constants. Rather than adopting one of the old + constants the latest value is used here.} +\refs +{ + \begin{enumerate} + \item Smith, C.A.\ {\it et al.}, 1989. {\it Astr.J.}\ {\bf 97}, 265. + \item Yallop, B.D.\ {\it et al.}, 1989. {\it Astr.J.}\ {\bf 97}, 274. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_EULER}{Rotation Matrix from Euler Angles} +{ + \action{Form a rotation matrix from the Euler angles -- three + successive rotations about specified Cartesian axes + (single precision).} + \call{CALL sla\_EULER (ORDER, PHI, THETA, PSI, RMAT)} +} +\args{GIVEN} +{ + \spec{ORDER}{C*(*)}{specifies about which axes the rotations occur} \\ + \spec{PHI}{R}{1st rotation (radians)} \\ + \spec{THETA}{R}{2nd rotation (radians)} \\ + \spec{PSI}{R}{3rd rotation (radians)} +} +\args{RETURNED} +{ + \spec{RMAT}{R(3,3)}{rotation matrix} +} +\notes +{ + \begin{enumerate} + \item A rotation is positive when the reference frame rotates + anticlockwise as seen looking towards the origin from the + positive region of the specified axis. + \item The characters of ORDER define which axes the three successive + rotations are about. A typical value is `ZXZ', indicating that + RMAT is to become the direction cosine matrix corresponding to + rotations of the reference frame through PHI radians about the + old {\it z}-axis, followed by THETA radians about the resulting + {\it x}-axis, + then PSI radians about the resulting {\it z}-axis. In detail: + \begin{itemize} + \item The axis names can be any of the following, in any order or + combination: X, Y, Z, uppercase or lowercase, 1, 2, 3. Normal + axis labelling/numbering conventions apply; + the {\it xyz} ($\equiv123$) + triad is right-handed. Thus, the `ZXZ' example given above + could be written `zxz' or `313' (or even `ZxZ' or `3xZ'). + \item ORDER is terminated by length or by the first unrecognized + character. + \item Fewer than three rotations are acceptable, in which case + the later angle arguments are ignored. + \end{itemize} + \item Zero rotations produces a unit RMAT. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_EVP}{Earth Position \& Velocity} +{ + \action{Barycentric and heliocentric velocity and position of the Earth.} + \call{CALL sla\_EVP (DATE, DEQX, DVB, DPB, DVH, DPH)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (formerly ET) as a Modified Julian Date + (JD$-$2400000.5)} \\ + \spec{DEQX}{D}{Julian Epoch ({\it e.g.}\ 2000D0) of mean equator and + equinox of the vectors returned. If DEQX~$<0$, + all vectors are referred to the mean equator and + equinox (FK5) of date DATE.} +} +\args{RETURNED} +{ + \spec{DVB}{D(3)}{barycentric \xyzd, AU~s$^{-1}$} \\ + \spec{DPB}{D(3)}{barycentric \xyz, AU} \\ + \spec{DVH}{D(3)}{heliocentric \xyzd, AU~s$^{-1}$} \\ + \spec{DPH}{D(3)}{heliocentric \xyz, AU} +} +\notes +{ + \begin{enumerate} + \item This routine is used when accuracy is more important + than CPU time, yet the extra complication of reading a + pre-computed ephemeris is not justified. The maximum + deviations from the JPL~DE96 ephemeris are as follows: + \begin{itemize} + \item velocity (barycentric or heliocentric): 420~mm~s$^{-1}$ + \item position (barycentric): 6900~km + \item position (heliocentric): 1600~km + \end{itemize} + \item The routine is an adaption of the BARVEL and BARCOR + subroutines of P.Stumpff, which are described in + {\it Astr.Astrophys.Suppl.Ser.}\ {\bf 41}, 1-8 (1980). + Most of the changes are merely cosmetic and do not affect + the results at all. However, some adjustments have been + made so as to give results that refer to the new (IAU 1976 + `FK5') equinox and precession, although the differences these + changes make relative to the results from Stumpff's original + `FK4' version are smaller than the inherent accuracy of the + algorithm. One minor shortcoming in the original routines + that has {\bf not} been corrected is that slightly better + numerical accuracy could be achieved if the various polynomial + evaluations were to be so arranged that the smallest terms were + computed first. Note also that one of Stumpff's precession + constants differs by \arcsec{0}{001} from the value given in the + {\it Explanatory Supplement}. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FITXY}{Fit Linear Model to Two \xy\ Sets} +{ + \action{Fit a linear model to relate two sets of \xy\ coordinates.} + \call{CALL sla\_FITXY (ITYPE,NP,XYE,XYM,COEFFS,J)} +} +\args{GIVEN} +{ + \spec{ITYPE}{I}{type of model: 4 or 6 (note 1)} \\ + \spec{NP}{I}{number of samples (note 2)} \\ + \spec{XYE}{D(2,NP)}{expected \xy\ for each sample} \\ + \spec{XYM}{D(2,NP)}{measured \xy\ for each sample} +} +\args{RETURNED} +{ + \spec{COEFFS}{D(6)}{coefficients of model (note 3)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK} \\ + \spec{}{}{\hspace{0.7em} $-$1 = illegal ITYPE} \\ + \spec{}{}{\hspace{0.7em} $-$2 = insufficient data} \\ + \spec{}{}{\hspace{0.7em} $-$3 = singular solution} +} +\notes +{ + \begin{enumerate} + \item ITYPE, which must be either 4 or 6, selects the type of model + fitted. Both allowed ITYPE values produce a model COEFFS which + consists of six coefficients, namely the zero points and, for + each of XE and YE, the coefficient of XM and YM. For ITYPE=6, + all six coefficients are independent, modelling squash and shear + as well as origin, scale, and orientation. However, ITYPE=4 + selects the {\it solid body rotation}\/ option; the model COEFFS + still consists of the same six coefficients, but now two of + them are used twice (appropriately signed). Origin, scale + and orientation are still modelled, but not squash or shear -- + the units of X and Y have to be the same. + \item For NC=4, NP must be at least 2. For NC=6, NP must be at + least 3. + \item The model is returned in the array COEFFS. Naming the + six elements of COEFFS $a,b,c,d,e$ \& $f$, + the model transforms {\it measured}\/ coordinates + $[x_{m},y_{m}\,]$ into {\it expected}\/ coordinates + $[x_{e},y_{e}\,]$ as follows: + \begin{verse} + $x_{e} = a + bx_{m} + cy_{m}$ \\ + $y_{e} = d + ex_{m} + fy_{m}$ + \end{verse} + For the {\it solid body rotation}\/ option (ITYPE=4), the + magnitudes of $b$ and $f$, and of $c$ and $e$, are equal. The + signs of these coefficients depend on whether there is a + sign reversal between $[x_{e},y_{e}]$ and $[x_{m},y_{m}]$; + fits are performed + with and without a sign reversal and the best one chosen. + \item Error status values J=$-$1 and $-$2 leave COEFFS unchanged; + if J=$-$3 COEFFS may have been changed. + \item See also sla\_PXY, sla\_INVF, sla\_XY2XY, sla\_DCMPF. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FK425}{FK4 to FK5} +{ + \action{Convert B1950.0 FK4 star data to J2000.0 FK5. + This routine converts stars from the old, Bessel-Newcomb, FK4 + system to the new, IAU~1976, FK5, Fricke system. The precepts + of Smith~{\it et~al.}\ (see reference~1) are followed, + using the implementation + by Yallop~{\it et~al.}\ (reference~2) of a matrix method + due to Standish. + Kinoshita's development of Andoyer's post-Newcomb precession is + used. The numerical constants from + Seidelmann~{\it et~al.}\ (reference~3) are used canonically.} + \call{CALL sla\_FK425 (\vtop{ + \hbox{R1950,D1950,DR1950,DD1950,P1950,V1950,} + \hbox{R2000,D2000,DR2000,DD2000,P2000,V2000)}}} +} +\args{GIVEN} +{ + \spec{R1950}{D}{B1950.0 $\alpha$ (radians)} \\ + \spec{D1950}{D}{B1950.0 $\delta$ (radians)} \\ + \spec{DR1950}{D}{B1950.0 proper motion in $\alpha$ + (radians per tropical year)} \\ + \spec{DD1950}{D}{B1950.0 proper motion in $\delta$ + (radians per tropical year)} \\ + \spec{P1950}{D}{B1950.0 parallax (arcsec)} \\ + \spec{V1950}{D}{B1950.0 radial velocity (km~s$^{-1}$, +ve = moving away)} +} +\args{RETURNED} +{ + \spec{R2000}{D}{J2000.0 $\alpha$ (radians)} \\ + \spec{D2000}{D}{J2000.0 $\delta$ (radians)} \\ + \spec{DR2000}{D}{J2000.0 proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DD2000}{D}{J2000.0 proper motion in $\delta$ + (radians per Julian year)} \\ + \spec{P2000}{D}{J2000.0 parallax (arcsec)} \\ + \spec{V2000}{D}{J2000.0 radial velocity (km~s$^{-1}$, +ve = moving away)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item Conversion from Besselian epoch 1950.0 to Julian epoch + 2000.0 only is provided for. Conversions involving other + epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or after FK425 + is called. + \item In the FK4 catalogue the proper motions of stars within + $10^{\circ}$ of the poles do not include the {\it differential + E-terms}\/ effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch J2000, + and measuring on the sky rather than in terms of $\Delta\alpha$, + the errors resulting from this simplification are less than + 1~milliarcsecond in position and 1~milliarcsecond per + century in proper motion. + \item See also sla\_FK45Z, sla\_FK524, sla\_FK54Z. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Smith, C.A.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 265. + \item Yallop, B.D.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 274. + \item Seidelmann, P.K.\ (ed), 1992. {\it Explanatory + Supplement to the Astronomical Almanac,}\/ ISBN~0-935702-68-7. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FK45Z}{FK4 to FK5, no P.M. or Parallax} +{ + \action{Convert B1950.0 FK4 star data to J2000.0 FK5 assuming zero + proper motion in the FK5 frame. + This routine converts stars from the old, Bessel-Newcomb, FK4 + system to the new, IAU~1976, FK5, Fricke system, in such a + way that the FK5 proper motion is zero. Because such a star + has, in general, a non-zero proper motion in the FK4 system, + the routine requires the epoch at which the position in the + FK4 system was determined. The method is from appendix~2 of + reference~1, but using the constants of reference~4.} + \call{CALL sla\_FK45Z (R1950,D1950,BEPOCH,R2000,D2000)} +} +\args{GIVEN} +{ + \spec{R1950}{D}{B1950.0 FK4 $\alpha$ at epoch BEPOCH (radians)} \\ + \spec{D1950}{D}{B1950.0 FK4 $\delta$ at epoch BEPOCH (radians)} \\ + \spec{BEPOCH}{D}{Besselian epoch ({\it e.g.}\ 1979.3D0)} +} +\args{RETURNED} +{ + \spec{R2000}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D2000}{D}{J2000.0 FK5 $\delta$ (radians)} +} +\notes +{ + \begin{enumerate} + \item The epoch BEPOCH is strictly speaking Besselian, but + if a Julian epoch is supplied the result will be + affected only to a negligible extent. + \item Conversion from Besselian epoch 1950.0 to Julian epoch + 2000.0 only is provided for. Conversions involving other + epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or + after FK45Z is called. + \item In the FK4 catalogue the proper motions of stars within + $10^{\circ}$ of the poles do not include the {\it differential + E-terms}\/ effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch 2000, + and measuring on the sky rather than in terms of $\Delta\alpha$, + the errors resulting from this simplification are less than + 1~milliarcsecond in position and 1~milliarcsecond per + century in proper motion. + \item See also sla\_FK425, sla\_FK524, sla\_FK54Z. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Aoki, S., {\it et al.}, 1983.\ {\it Astr.Astrophys.}, {\bf 128}, 263. + \item Smith, C.A.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 265. + \item Yallop, B.D.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 274. + \item Seidelmann, P.K.\ (ed), 1992. {\it Explanatory + Supplement to the Astronomical Almanac,}\/ ISBN~0-935702-68-7. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FK524}{FK5 to FK4} +{ + \action{Convert J2000.0 FK5 star data to B1950.0 FK4. + This routine converts stars from the new, IAU~1976, FK5, Fricke + system, to the old, Bessel-Newcomb, FK4 system. + The precepts of Smith~{\it et~al.}\ (reference~1) are followed, + using the implementation by Yallop~{\it et~al.}\ (reference~2) + of a matrix method due to Standish. Kinoshita's development of + Andoyer's post-Newcomb precession is used. The numerical + constants from Seidelmann~{\it et~al.}\ (reference~3) are + used canonically.} + \call{CALL sla\_FK524 (\vtop{ + \hbox{R2000,D2000,DR2000,DD2000,P2000,V2000,} + \hbox{R1950,D1950,DR1950,DD1950,P1950,V1950)}}} +} +\args{GIVEN} +{ + \spec{R2000}{D}{J2000.0 $\alpha$ (radians)} \\ + \spec{D2000}{D}{J2000.0 $\delta$ (radians)} \\ + \spec{DR2000}{D}{J2000.0 proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DD2000}{D}{J2000.0 proper motion in $\delta$ + (radians per Julian year)} \\ + \spec{P2000}{D}{J2000.0 parallax (arcsec)} \\ + \spec{V2000}{D}{J2000 radial velocity (km~s$^{-1}$, +ve = moving away)} +} +\args{RETURNED} +{ + \spec{R1950}{D}{B1950.0 $\alpha$ (radians)} \\ + \spec{D1950}{D}{B1950.0 $\delta$ (radians)} \\ + \spec{DR1950}{D}{B1950.0 proper motion in $\alpha$ + (radians per tropical year)} \\ + \spec{DD1950}{D}{B1950.0 proper motion in $\delta$ + (radians per tropical year)} \\ + \spec{P1950}{D}{B1950.0 parallax (arcsec)} \\ + \spec{V1950}{D}{radial velocity (km~s$^{-1}$, +ve = moving away)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item Note that conversion from Julian epoch 2000.0 to Besselian + epoch 1950.0 only is provided for. Conversions involving + other epochs will require use of the appropriate precession, + proper motion, and E-terms routines before and/or after + FK524 is called. + \item In the FK4 catalogue the proper motions of stars within + $10^{\circ}$ of the poles do not include the {\it differential + E-terms}\/ effect and should, strictly speaking, be handled + in a different manner from stars outside these regions. + However, given the general lack of homogeneity of the star + data available for routine astrometry, the difficulties of + handling positions that may have been determined from + astrometric fields spanning the polar and non-polar regions, + the likelihood that the differential E-terms effect was not + taken into account when allowing for proper motion in past + astrometry, and the undesirability of a discontinuity in + the algorithm, the decision has been made in this routine to + include the effect of differential E-terms on the proper + motions for all stars, whether polar or not. At epoch 2000, + and measuring on the sky rather than in terms of $\Delta\alpha$, + the errors resulting from this simplification are less than + 1~milliarcsecond in position and 1~milliarcsecond per + century in proper motion. + \item See also sla\_FK425, sla\_FK45Z, sla\_FK54Z. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Smith, C.A.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 265. + \item Yallop, B.D.\ {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 274. + \item Seidelmann, P.K.\ (ed), 1992. {\it Explanatory + Supplement to the Astronomical Almanac,}\/ ISBN~0-935702-68-7. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FK52H}{FK5 to Hipparcos} +{ + \action{Transform an FK5 (J2000) position and proper motion + into the frame of the Hipparcos catalogue.} + \call{CALL sla\_FK52H (R5,D5,DR5,DD5,RH,DH,DRH,DDH)} +} +\args{GIVEN} +{ + \spec{R5}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D5}{D}{J2000.0 FK5 $\delta$ (radians)} \\ + \spec{DR5}{D}{J2000.0 FK5 proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DD5}{D}{J2000.0 FK5 proper motion in $\delta$ + (radians per Julian year)} +} +\args{RETURNED} +{ + \spec{RH}{D}{Hipparcos $\alpha$ (radians)} \\ + \spec{DH}{D}{Hipparcos $\delta$ (radians)} \\ + \spec{DRH}{D}{Hipparcos proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DDH}{D}{Hipparcos proper motion in $\delta$ + (radians per Julian year)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item The FK5 to Hipparcos + transformation consists of a pure rotation and spin; + zonal errors in the FK5 catalogue are not taken into account. + \item The adopted epoch J2000.0 FK5 to Hipparcos orientation and spin + values are as follows (see reference): + + \vspace{2ex} + + ~~~~~~~~~~~~ + \begin{tabular}{|r|r|r|} \hline + & + \multicolumn{1}{|c}{\it orientation} & + \multicolumn{1}{|c|}{\it ~~~spin~~~} \\ \hline + $x$ & $-19.9$~~~~ & ~$-0.30$~~ \\ + $y$ & $-9.1$~~~~ & ~$+0.60$~~ \\ + $z$ & $+22.9$~~~~ & ~$+0.70$~~ \\ \hline + & {\it mas}~~~~~ & ~{\it mas/y}~ \\ \hline + \end{tabular} + + \vspace{3ex} + + These orientation and spin components are interpreted as + {\it axial vectors.} An axial vector points at the pole of + the rotation and its length is the amount of rotation in radians. + \item See also sla\_FK5HZ, sla\_H2FK5, sla\_HFK5Z. + \end{enumerate} +} +\aref {Feissel, M.\ \& Mignard, F., 1998., {\it Astron.Astrophys.}\ + {\bf 331}, L33-L36.} +%----------------------------------------------------------------------- +\routine{SLA\_FK54Z}{FK5 to FK4, no P.M. or Parallax} +{ + \action{Convert a J2000.0 FK5 star position to B1950.0 FK4 assuming + FK5 zero proper motion and parallax. + This routine converts star positions from the new, IAU~1976, + FK5, Fricke system to the old, Bessel-Newcomb, FK4 system.} + \call{CALL sla\_FK54Z (R2000,D2000,BEPOCH,R1950,D1950,DR1950,DD1950)} +} +\args{GIVEN} +{ + \spec{R2000}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D2000}{D}{J2000.0 FK5 $\delta$ (radians)} \\ + \spec{BEPOCH}{D}{Besselian epoch ({\it e.g.}\ 1950D0)} +} +\args{RETURNED} +{ + \spec{R1950}{D}{B1950.0 FK4 $\alpha$ at epoch BEPOCH (radians)} \\ + \spec{D1950}{D}{B1950.0 FK4 $\delta$ at epoch BEPOCH (radians)} \\ + \spec{DR1950}{D}{B1950.0 FK4 proper motion in $\alpha$ + (radians per tropical year)} \\ + \spec{DD1950}{D}{B1950.0 FK4 proper motion in $\delta$ + (radians per tropical year)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item Conversion from Julian epoch 2000.0 to Besselian epoch 1950.0 + only is provided for. Conversions involving other epochs will + require use of the appropriate precession routines before and + after this routine is called. + \item Unlike in the sla\_FK524 routine, the FK5 proper motions, the + parallax and the radial velocity are presumed zero. + \item It was the intention that FK5 should be a close approximation + to an inertial frame, so that distant objects have zero proper + motion; such objects have (in general) non-zero proper motion + in FK4, and this routine returns those {\it fictitious proper + motions}. + \item The position returned by this routine is in the B1950 + reference frame but at Besselian epoch BEPOCH. For + comparison with catalogues the BEPOCH argument will + frequently be 1950D0. + \item See also sla\_FK425, sla\_FK45Z, sla\_FK524. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_FK5HZ}{FK5 to Hipparcos, no P.M.} +{ + \action{Transform an FK5 (J2000) star position into the frame of the + Hipparcos catalogue, assuming zero Hipparcos proper motion.} + \call{CALL sla\_FK52H (R5,D5,EPOCH,RH,DH)} +} +\args{GIVEN} +{ + \spec{R5}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D5}{D}{J2000.0 FK5 $\delta$ (radians)} \\ + \spec{EPOCH}{D}{Julian epoch (TDB)} +} +\args{RETURNED} +{ + \spec{RH}{D}{Hipparcos $\alpha$ (radians)} \\ + \spec{DH}{D}{Hipparcos $\delta$ (radians)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item The FK5 to Hipparcos + transformation consists of a pure rotation and spin; + zonal errors in the FK5 catalogue are not taken into account. + \item The adopted epoch J2000.0 FK5 to Hipparcos orientation and spin + values are as follows (see reference): + + \vspace{2ex} + + ~~~~~~~~~~~~ + \begin{tabular}{|r|r|r|} \hline + & + \multicolumn{1}{|c}{\it orientation} & + \multicolumn{1}{|c|}{\it ~~~spin~~~} \\ \hline + $x$ & $-19.9$~~~~ & ~$-0.30$~~ \\ + $y$ & $-9.1$~~~~ & ~$+0.60$~~ \\ + $z$ & $+22.9$~~~~ & ~$+0.70$~~ \\ \hline + & {\it mas}~~~~~ & ~{\it mas/y}~ \\ \hline + \end{tabular} + + \vspace{3ex} + + These orientation and spin components are interpreted as + {\it axial vectors.} An axial vector points at the pole of + the rotation and its length is the amount of rotation in radians. + \item See also sla\_FK52H, sla\_H2FK5, sla\_HFK5Z. + \end{enumerate} +} +\aref {Feissel, M.\ \& Mignard, F., 1998., {\it Astron.Astrophys.}\ + {\bf 331}, L33-L36.} +%----------------------------------------------------------------------- +\routine{SLA\_FLOTIN}{Decode a Real Number} +{ + \action{Convert free-format input into single precision floating point.} + \call{CALL sla\_FLOTIN (STRING, NSTRT, RESLT, JFLAG)} +} +\args{GIVEN} +{ + \spec{STRING}{C}{string containing number to be decoded} \\ + \spec{NSTRT}{I}{pointer to where decoding is to commence} \\ + \spec{RESLT}{R}{current value of result} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{advanced to next number} \\ + \spec{RESLT}{R}{result} \\ + \spec{JFLAG}{I}{status: $-$1~=~$-$OK, 0~=~+OK, 1~=~null result, 2~=~error} +} +\notes +{ + \begin{enumerate} + \item The reason sla\_FLOTIN has separate `OK' status values + for + and $-$ is to enable minus zero to be detected. + This is of crucial importance + when decoding mixed-radix numbers. For example, an angle + expressed as degrees, arcminutes and arcseconds may have a + leading minus sign but a zero degrees field. + \item A TAB is interpreted as a space, and lowercase characters are + interpreted as uppercase. {\it n.b.}\ The test for TAB is + ASCII-specific. + \item The basic format is the sequence of fields $\pm n.n x \pm n$, + where $\pm$ is a sign + character `+' or `$-$', $n$ means a string of decimal digits, + `.' is a decimal point, and $x$, which indicates an exponent, + means `D' or `E'. Various combinations of these fields can be + omitted, and embedded blanks are permissible in certain places. + \item Spaces: + \begin{itemize} + \item Leading spaces are ignored. + \item Embedded spaces are allowed only after +, $-$, D or E, + and after the decimal point if the first sequence of + digits is absent. + \item Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + \end{itemize} + \item Delimiters: + \begin{itemize} + \item Any character other than +,$-$,0-9,.,D,E or space may be + used to signal the end of the number and terminate decoding. + \item Comma is recognized by sla\_FLOTIN as a special case; it + is skipped, leaving the pointer on the next character. See + 13, below. + \item Decoding will in all cases terminate if end of string + is reached. + \end{itemize} + \item Both signs are optional. The default is +. + \item The mantissa $n.n$ defaults to unity. + \item The exponent $x\!\pm\!n$ defaults to `E0'. + \item The strings of decimal digits may be of any length. + \item The decimal point is optional for whole numbers. + \item A {\it null result}\/ occurs when the string of characters + being decoded does not begin with +,$-$,0-9,.,D or E, or + consists entirely of spaces. When this condition is + detected, JFLAG is set to 1 and RESLT is left untouched. + \item NSTRT = 1 for the first character in the string. + \item On return from sla\_FLOTIN, NSTRT is set ready for the next + decode -- following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to sla\_FLOTIN, otherwise + all subsequent calls will return a null result. + \item Errors (JFLAG=2) occur when: + \begin{itemize} + \item a +, $-$, D or E is left unsatisfied; or + \item the decimal point is present without at least + one decimal digit before or after it; or + \item an exponent more than 100 has been presented. + \end{itemize} + \item When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. This + may be after the point at which a more sophisticated + program could have detected the error. For example, + sla\_FLOTIN does not detect that `1E999' is unacceptable + (on a computer where this is so) + until the entire number has been decoded. + \item Certain highly unlikely combinations of mantissa and + exponent can cause arithmetic faults during the + decode, in some cases despite the fact that they + together could be construed as a valid number. + \item Decoding is left to right, one pass. + \item See also sla\_DFLTIN and sla\_INTIN. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_GALEQ}{Galactic to J2000 $\alpha,\delta$} +{ + \action{Transformation from IAU 1958 galactic coordinates + to J2000.0 FK5 equatorial coordinates.} + \call{CALL sla\_GALEQ (DL, DB, DR, DD)} +} +\args{GIVEN} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal} +} +\args{RETURNED} +{ + \spec{DR,DD}{D}{J2000.0 \radec} +} +\notes +{ + \begin{enumerate} + \item All arguments are in radians. + \item The equatorial coordinates are J2000.0 FK5. Use the routine + sla\_GE50 if conversion to B1950.0 FK4 coordinates is + required. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_GALSUP}{Galactic to Supergalactic} +{ + \action{Transformation from IAU 1958 galactic coordinates to + de Vaucouleurs supergalactic coordinates.} + \call{CALL sla\_GALSUP (DL, DB, DSL, DSB)} +} +\args{GIVEN} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal\ (radians)} +} +\args{RETURNED} +{ + \spec{DSL,DSB}{D}{supergalactic longitude and latitude (radians)} +} +\refs +{ + \begin{enumerate} + \item de Vaucouleurs, de Vaucouleurs, \& Corwin, {\it Second Reference + Catalogue of Bright Galaxies}, U.Texas, p8. + \item Systems \& Applied Sciences Corp., documentation for the + machine-readable version of the above catalogue, + Contract NAS 5-26490. + \end{enumerate} + (These two references give different values for the galactic + longitude of the supergalactic origin. Both are wrong; the + correct value is $l^{I\!I}=137.37$.) +} +%----------------------------------------------------------------------- +\routine{SLA\_GE50}{B1950 $\alpha,\delta$ to Galactic} +{ + \action{Transformation from IAU 1958 galactic coordinates to + B1950.0 FK4 equatorial coordinates.} + \call{CALL sla\_GE50 (DL, DB, DR, DD)} +} +\args{GIVEN} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal} +} +\args{RETURNED} +{ + \spec{DR,DD}{D}{B1950.0 \radec} +} +\notes +{ + \begin{enumerate} + \item All arguments are in radians. + \item The equatorial coordinates are B1950.0 FK4. Use the + routine sla\_GALEQ if conversion to J2000.0 FK5 coordinates + is required. + \end{enumerate} +} +\aref{Blaauw {\it et al.}, 1960, {\it Mon.Not.R.astr.Soc.}, + {\bf 121}, 123.} +%----------------------------------------------------------------------- +\routine{SLA\_GEOC}{Geodetic to Geocentric} +{ + \action{Convert geodetic position to geocentric.} + \call{CALL sla\_GEOC (P, H, R, Z)} +} +\args{GIVEN} +{ + \spec{P}{D}{latitude (geodetic, radians)} \\ + \spec{H}{D}{height above reference spheroid (geodetic, metres)} +} +\args{RETURNED} +{ + \spec{R}{D}{distance from Earth axis (AU)} \\ + \spec{Z}{D}{distance from plane of Earth equator (AU)} +} +\notes +{ + \begin{enumerate} + \item Geocentric latitude can be obtained by evaluating {\tt ATAN2(Z,R)}. + \item IAU 1976 constants are used. + \end{enumerate} +} +\aref{Green, R.M., 1985.\ {\it Spherical Astronomy}, Cambridge U.P., p98.} +%----------------------------------------------------------------------- +\routine{SLA\_GMST}{UT to GMST} +{ + \action{Conversion from universal time UT1 to Greenwich mean + sidereal time.} + \call{D~=~sla\_GMST (UT1)} +} +\args{GIVEN} +{ + \spec{UT1}{D}{universal time (strictly UT1) expressed as + modified Julian Date (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{sla\_GMST}{D}{Greenwich mean sidereal time (radians)} +} +\notes +{ + \begin{enumerate} + \item The IAU~1982 expression + (see page~S15 of the 1984 {\it Astronomical + Almanac})\/ is used, but rearranged to reduce rounding errors. This + expression is always described as giving the GMST at $0^{\rm h}$UT; + in fact, it gives the difference between the + GMST and the UT, which happens to equal the GMST (modulo + 24~hours) at $0^{\rm h}$UT each day. In sla\_GMST, the + entire UT is used directly as the argument for the + canonical formula, and the fractional part of the UT is + added separately; note that the factor $1.0027379\cdots$ does + not appear. + \item See also the routine sla\_GMSTA, which + delivers better numerical + precision by accepting the UT date and time as separate arguments. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_GMSTA}{UT to GMST (extra precision)} +{ + \action{Conversion from universal time UT1 to Greenwich Mean + sidereal time, with rounding errors minimized.} + \call{D~=~sla\_GMSTA (DATE, UT1)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{UT1 date as Modified Julian Date (integer part + of JD$-$2400000.5)} \\ + \spec{UT1}{D}{UT1 time (fraction of a day)} +} +\args{RETURNED} +{ + \spec{sla\_GMST}{D}{Greenwich mean sidereal time (radians)} +} +\notes +{ + \begin{enumerate} + \item The algorithm is derived from the IAU 1982 expression + (see page~S15 of the 1984 Astronomical Almanac). + \item There is no restriction on how the UT is apportioned between the + DATE and UT1 arguments. Either of the two arguments could, for + example, be zero and the entire date\,+\,time supplied in the other. + However, the routine is designed to deliver maximum accuracy when + the DATE argument is a whole number and the UT1 argument + lies in the range $[\,0,\,1\,]$, or {\it vice versa}. + \item See also the routine sla\_GMST, which accepts the UT1 as a single + argument. Compared with sla\_GMST, the extra numerical precision + delivered by the present routine is unlikely to be important in + an absolute sense, but may be useful when critically comparing + algorithms and in applications where two sidereal times close + together are differenced. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_GRESID}{Gaussian Residual} +{ + \action{Generate pseudo-random normal deviate or {\it Gaussian residual}.} + \call{R~=~sla\_GRESID (S)} +} +\args{GIVEN} +{ + \spec{S}{R}{standard deviation} +} +\notes +{ + \begin{enumerate} + \item The results of many calls to this routine will be + normally distributed with mean zero and standard deviation S. + \item The Box-Muller algorithm is used. + \item The implementation is machine-dependent. + \end{enumerate} +} +\aref{Ahrens \& Dieter, 1972.\ {\it Comm.A.C.M.}\ {\bf 15}, 873.} +%----------------------------------------------------------------------- +\routine{SLA\_H2E}{Az,El to $h,\delta$} +{ + \action{Horizon to equatorial coordinates + (single precision).} + \call{CALL sla\_H2E (AZ, EL, PHI, HA, DEC)} +} +\args{GIVEN} +{ + \spec{AZ}{R}{azimuth (radians)} \\ + \spec{EL}{R}{elevation (radians)} \\ + \spec{PHI}{R}{latitude (radians)} +} +\args{RETURNED} +{ + \spec{HA}{R}{hour angle (radians)} \\ + \spec{DEC}{R}{declination (radians)} +} +\notes +{ + \begin{enumerate} + \item The sign convention for azimuth is north zero, east $+\pi/2$. + \item HA is returned in the range $\pm\pi$. Declination is returned + in the range $\pm\pi$. + \item The latitude is (in principle) geodetic. In critical + applications, corrections for polar motion should be applied + (see sla\_POLMO). + \item In some applications it will be important to specify the + correct type of elevation in order to produce the required + type of \hadec. In particular, it may be important to + distinguish between the elevation as affected by refraction, + which will yield the {\it observed} \hadec, and the elevation + {\it in vacuo}, which will yield the {\it topocentric} + \hadec. If the + effects of diurnal aberration can be neglected, the + topocentric \hadec\ may be used as an approximation to the + {\it apparent} \hadec. + \item No range checking of arguments is carried out. + \item In applications which involve many such calculations, rather + than calling the present routine it will be more efficient to + use inline code, having previously computed fixed terms such + as sine and cosine of latitude. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_H2FK5}{Hipparcos to FK5} +{ + \action{Transform a Hipparcos star position and proper motion + into the FK5 (J2000) frame.} + \call{CALL sla\_H2FK5 (RH,DH,DRH,DDH,R5,D5,DR5,DD5)} +} +\args{GIVEN} +{ + \spec{RH}{D}{Hipparcos $\alpha$ (radians)} \\ + \spec{DH}{D}{Hipparcos $\delta$ (radians)} \\ + \spec{DRH}{D}{Hipparcos proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DDH}{D}{Hipparcos proper motion in $\delta$ + (radians per Julian year)} +} +\args{RETURNED} +{ + \spec{R5}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D5}{D}{J2000.0 FK5 $\delta$ (radians)} \\ + \spec{DR5}{D}{J2000.0 FK5 proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DD5}{D}{FK5 J2000.0 proper motion in $\delta$ + (radians per Julian year)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item The FK5 to Hipparcos + transformation consists of a pure rotation and spin; + zonal errors in the FK5 catalogue are not taken into account. + \item The adopted epoch J2000.0 FK5 to Hipparcos orientation and spin + values are as follows (see reference): + + \vspace{2ex} + + ~~~~~~~~~~~~ + \begin{tabular}{|r|r|r|} \hline + & + \multicolumn{1}{|c}{\it orientation} & + \multicolumn{1}{|c|}{\it ~~~spin~~~} \\ \hline + $x$ & $-19.9$~~~~ & ~$-0.30$~~ \\ + $y$ & $-9.1$~~~~ & ~$+0.60$~~ \\ + $z$ & $+22.9$~~~~ & ~$+0.70$~~ \\ \hline + & {\it mas}~~~~~ & ~{\it mas/y}~ \\ \hline + \end{tabular} + + \vspace{3ex} + + These orientation and spin components are interpreted as + {\it axial vectors.} An axial vector points at the pole of + the rotation and its length is the amount of rotation in radians. + \item See also sla\_FK52H, sla\_FK5HZ, sla\_HFK5Z. + \end{enumerate} +} +\aref {Feissel, M.\ \& Mignard, F., 1998., {\it Astron.Astrophys.}\ + {\bf 331}, L33-L36.} +%----------------------------------------------------------------------- +\routine{SLA\_HFK5Z}{Hipparcos to FK5, no P.M.} +{ + \action{Transform a Hipparcos star position + into the FK5 (J2000) frame assuming zero Hipparcos proper motion.} + \call{CALL sla\_HFK5Z (RH,DH,EPOCH,R5,D5,DR5,DD5)} +} +\args{GIVEN} +{ + \spec{RH}{D}{Hipparcos $\alpha$ (radians)} \\ + \spec{DH}{D}{Hipparcos $\delta$ (radians)} \\ + \spec{EPOCH}{D}{Julian epoch (TDB)} +} +\args{RETURNED} +{ + \spec{R5}{D}{J2000.0 FK5 $\alpha$ (radians)} \\ + \spec{D5}{D}{J2000.0 FK5 $\delta$ (radians)} \\ + \spec{DR5}{D}{J2000.0 FK5 proper motion in $\alpha$ + (radians per Julian year)} \\ + \spec{DD5}{D}{FK5 J2000.0 proper motion in $\delta$ + (radians per Julian year)} +} +\notes +{ + \begin{enumerate} + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item The FK5 to Hipparcos + transformation consists of a pure rotation and spin; + zonal errors in the FK5 catalogue are not taken into account. + \item The adopted epoch J2000.0 FK5 to Hipparcos orientation and spin + values are as follows (see reference): + + \vspace{2ex} + + ~~~~~~~~~~~~ + \begin{tabular}{|r|r|r|} \hline + & + \multicolumn{1}{|c}{\it orientation} & + \multicolumn{1}{|c|}{\it ~~~spin~~~} \\ \hline + $x$ & $-19.9$~~~~ & ~$-0.30$~~ \\ + $y$ & $-9.1$~~~~ & ~$+0.60$~~ \\ + $z$ & $+22.9$~~~~ & ~$+0.70$~~ \\ \hline + & {\it mas}~~~~~ & ~{\it mas/y}~ \\ \hline + \end{tabular} + + \vspace{3ex} + + These orientation and spin components are interpreted as + {\it axial vectors.} An axial vector points at the pole of + the rotation and its length is the amount of rotation in radians. + The order of the rotations, which are very small, + \item It was the intention that Hipparcos should be a close + approximation to an inertial frame, so that distant objects + have zero proper motion; such objects have (in general) + non-zero proper motion in FK5, and this routine returns those + {\it fictitious proper motions.} + \item The position returned by this routine is in the FK5 J2000 + reference frame but at Julian epoch EPOCH. + \item See also sla\_FK52H, sla\_FK5HZ, sla\_H2FK5. + \end{enumerate} +} +\aref {Feissel, M.\ \& Mignard, F., 1998., {\it Astron.Astrophys.}\ + {\bf 331}, L33-L36.} +%----------------------------------------------------------------------- +\routine{SLA\_IMXV}{Apply 3D Reverse Rotation} +{ + \action{Multiply a 3-vector by the inverse of a rotation + matrix (single precision).} + \call{CALL sla\_IMXV (RM, VA, VB)} +} +\args{GIVEN} +{ + \spec{RM}{R(3,3)}{rotation matrix} \\ + \spec{VA}{R(3)}{vector to be rotated} +} +\args{RETURNED} +{ + \spec{VB}{R(3)}{result vector} +} +\notes +{ + \begin{enumerate} + \item This routine performs the operation: + \begin{verse} + {\bf b} = {\bf M}$^{T}\cdot${\bf a} + \end{verse} + where {\bf a} and {\bf b} are the 3-vectors VA and VB + respectively, and {\bf M} is the $3\times3$ matrix RM. + \item The main function of this routine is apply an inverse + rotation; under these circumstances, ${\bf M}$ is + {\it orthogonal}, with its inverse the same as its transpose. + \item To comply with the ANSI Fortran 77 standard, VA and VB must + {\bf not} be the same array. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_INTIN}{Decode an Integer Number} +{ + \action{Convert free-format input into an integer.} + \call{CALL sla\_INTIN (STRING, NSTRT, IRESLT, JFLAG)} +} +\args{GIVEN} +{ + \spec{STRING}{C}{string containing number to be decoded} \\ + \spec{NSTRT}{I}{pointer to where decoding is to commence} \\ + \spec{IRESLT}{I}{current value of result} +} +\args{RETURNED} +{ + \spec{NSTRT}{I}{advanced to next number} \\ + \spec{IRESLT}{I}{result} \\ + \spec{JFLAG}{I}{status: $-$1 = $-$OK, 0~=~+OK, 1~=~null result, 2~=~error} +} +\notes +{ + \begin{enumerate} + \item The reason sla\_INTIN has separate `OK' status values + for + and $-$ is to enable minus zero to be detected. + This is of crucial importance + when decoding mixed-radix numbers. For example, an angle + expressed as degrees, arcminutes and arcseconds may have a + leading minus sign but a zero degrees field. + \item A TAB is interpreted as a space. {\it n.b.}\ The test for TAB is + ASCII-specific. + \item The basic format is the sequence of fields $\pm n$, + where $\pm$ is a sign + character `+' or `$-$', and $n$ means a string of decimal digits. + \item Spaces: + \begin{itemize} + \item Leading spaces are ignored. + \item Spaces between the sign and the number are allowed. + \item Trailing spaces are ignored; the first signifies + end of decoding and subsequent ones are skipped. + \end{itemize} + \item Delimiters: + \begin{itemize} + \item Any character other than +,$-$,0-9 or space may be + used to signal the end of the number and terminate decoding. + \item Comma is recognized by sla\_INTIN as a special case; it + is skipped, leaving the pointer on the next character. See + 9, below. + \item Decoding will in all cases terminate if end of string + is reached. + \end{itemize} + \item The sign is optional. The default is +. + \item A {\it null result}\/ occurs when the string of characters + being decoded does not begin with +,$-$ or 0-9, or + consists entirely of spaces. When this condition is + detected, JFLAG is set to 1 and IRESLT is left untouched. + \item NSTRT = 1 for the first character in the string. + \item On return from sla\_INTIN, NSTRT is set ready for the next + decode -- following trailing blanks and any comma. If a + delimiter other than comma is being used, NSTRT must be + incremented before the next call to sla\_INTIN, otherwise + all subsequent calls will return a null result. + \item Errors (JFLAG=2) occur when: + \begin{itemize} + \item there is a + or $-$ but no number; or + \item the number is greater than $2^{31}-1$. + \end{itemize} + \item When an error has been detected, NSTRT is left + pointing to the character following the last + one used before the error came to light. + \item See also sla\_FLOTIN and sla\_DFLTIN. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_INVF}{Invert Linear Model} +{ + \action{Invert a linear model of the type produced by the + sla\_FITXY routine.} + \call{CALL sla\_INVF (FWDS,BKWDS,J)} +} +\args{GIVEN} +{ + \spec{FWDS}{D(6)}{model coefficients} +} +\args{RETURNED} +{ + \spec{BKWDS}{D(6)}{inverse model} \\ + \spec{J}{I}{status: 0 = OK, $-$1 = no inverse} +} +\notes +{ + \begin{enumerate} + \item The models relate two sets of \xy\ coordinates as follows. + Naming the six elements of FWDS $a,b,c,d,e$ \& $f$, + where two sets of coordinates $[x_{1},y_{1}]$ and + $[x_{2},y_{2}\,]$ are related thus: + \begin{verse} + $x_{2} = a + bx_{1} + cy_{1}$ \\ + $y_{2} = d + ex_{1} + fy_{1}$ + \end{verse} + The present routine generates a new set of coefficients + $p,q,r,s,t$ \& $u$ (the array BKWDS) such that: + \begin{verse} + $x_{1} = p + qx_{2} + ry_{2}$ \\ + $y_{1} = s + tx_{2} + uy_{2}$ + \end{verse} + \item Two successive calls to this routine will deliver a set + of coefficients equal to the starting values. + \item To comply with the ANSI Fortran 77 standard, FWDS and BKWDS must + {\bf not} be the same array. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended. + \item See also sla\_FITXY, sla\_PXY, sla\_XY2XY, sla\_DCMPF. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_KBJ}{Select Epoch Prefix} +{ + \action{Select epoch prefix `B' or `J'.} + \call{CALL sla\_KBJ (JB, E, K, J)} +} +\args{GIVEN} +{ + \spec{JB}{I}{sla\_DBJIN prefix status: 0=none, 1=`B', 2=`J'} \\ + \spec{E}{D}{epoch -- Besselian or Julian} +} +\args{RETURNED} +{ + \spec{K}{C}{`B' or `J'} \\ + \spec{J}{I}{status: 0=OK} +} +\anote{The routine is mainly intended for use in conjunction with the + sla\_DBJIN routine. If the value of JB indicates that an explicit + B or J prefix was detected by sla\_DBJIN, a `B' or `J' + is returned to match. If JB indicates that no explicit B or J + was supplied, the choice is made on the basis of the epoch + itself; B is assumed for E $<1984$, otherwise J.} +%----------------------------------------------------------------------- +\routine{SLA\_M2AV}{Rotation Matrix to Axial Vector} +{ + \action{From a rotation matrix, determine the corresponding axial vector + (single precision).} + \call{CALL sla\_M2AV (RMAT, AXVEC)} +} +\args{GIVEN} +{ + \spec{RMAT}{R(3,3)}{rotation matrix} +} +\args{RETURNED} +{ + \spec{AXVEC}{R(3)}{axial vector (radians)} +} +\notes +{ + \begin{enumerate} + \item A rotation matrix describes a rotation about some arbitrary axis. + The axis is called the {\it Euler axis}, and the angle through + which the reference frame rotates is called the {\it Euler angle}. + The {\it axial vector}\/ returned by this routine has the same + direction as the Euler axis, and its magnitude is the Euler angle + in radians. + \item The magnitude and direction of the axial vector can be separated + by means of the routine sla\_VN. + \item The reference frame rotates clockwise as seen looking along + the axial vector from the origin. + \item If RMAT is null, so is the result. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_MAP}{Mean to Apparent} +{ + \action{Transform star \radec\ from mean place to geocentric apparent. + The reference frames and timescales used are post IAU~1976.} + \call{CALL sla\_MAP (RM, DM, PR, PD, PX, RV, EQ, DATE, RA, DA)} +} +\args{GIVEN} +{ + \spec{RM,DM}{D}{mean \radec\ (radians)} \\ + \spec{PR,PD}{D}{proper motions: \radec\ changes per Julian year} \\ + \spec{PX}{D}{parallax (arcsec)} \\ + \spec{RV}{D}{radial velocity (km~s$^{-1}$, +ve if receding)} \\ + \spec{EQ}{D}{epoch and equinox of star data (Julian)} \\ + \spec{DATE}{D}{TDB for apparent place (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{RA,DA}{D}{apparent \radec\ (radians)} +} +\notes +{ + \begin{enumerate} + \item EQ is the Julian epoch specifying both the reference + frame and the epoch of the position -- usually 2000. + For positions where the epoch and equinox are + different, use the routine sla\_PM to apply proper + motion corrections before using this routine. + \item The distinction between the required TDB and TT is + always negligible. Moreover, for all but the most + critical applications UTC is adequate. + \item The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are per year rather than per century. + \item This routine may be wasteful for some applications + because it recomputes the Earth position/velocity and + the precession/nutation matrix each time, and because + it allows for parallax and proper motion. Where + multiple transformations are to be carried out for one + epoch, a faster method is to call the sla\_MAPPA routine + once and then either the sla\_MAPQK routine (which includes + parallax and proper motion) or sla\_MAPQKZ (which assumes + zero parallax and FK5 proper motion). + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_MAPPA}{Mean to Apparent Parameters} +{ + \action{Compute star-independent parameters in preparation for + conversions between mean place and geocentric apparent place. + The parameters produced by this routine are required in the + parallax, light deflection, aberration, and precession/nutation + parts of the mean/apparent transformations. + The reference frames and timescales used are post IAU~1976.} + \call{CALL sla\_MAPPA (EQ, DATE, AMPRMS)} +} +\args{GIVEN} +{ + \spec{EQ}{D}{epoch of mean equinox to be used (Julian)} \\ + \spec{DATE}{D}{TDB (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{AMPRMS}{D(21)}{star-independent mean-to-apparent parameters:} \\ + \specel {(1)} {time interval for proper motion (Julian years)} \\ + \specel {(2-4)} {barycentric position of the Earth (AU)} \\ + \specel {(5-7)} {heliocentric direction of the Earth (unit vector)} \\ + \specel {(8)} {(gravitational radius of + Sun)$\times 2 / $(Sun-Earth distance)} \\ + \specel {(9-11)} {{\bf v}: barycentric Earth velocity in units of c} \\ + \specel {(12)} {$\sqrt{1-\left|\mbox{\bf v}\right|^2}$} \\ + \specel {(13-21)} {precession/nutation $3\times3$ matrix} +} +\notes +{ + \begin{enumerate} + \item For DATE, the distinction between the required TDB and TT + is always negligible. Moreover, for all but the most + critical applications UTC is adequate. + \item The accuracy of the routines using the parameters AMPRMS is + limited by the routine sla\_EVP, used here to compute the + Earth position and velocity by the methods of Stumpff. + The maximum error in the resulting aberration corrections is + about 0.3 milliarcsecond. + \item The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to + the mean equinox and equator of epoch EQ. + \item The parameters produced by this routine are used by + sla\_MAPQK and sla\_MAPQKZ. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_MAPQK}{Quick Mean to Apparent} +{ + \action{Quick mean to apparent place: transform a star \radec\ from + mean place to geocentric apparent place, given the + star-independent parameters. The reference frames and + timescales used are post IAU 1976.} + \call{CALL sla\_MAPQK (RM, DM, PR, PD, PX, RV, AMPRMS, RA, DA)} +} +\args{GIVEN} +{ + \spec{RM,DM}{D}{mean \radec\ (radians)} \\ + \spec{PR,PD}{D}{proper motions: \radec\ changes per Julian year} \\ + \spec{PX}{D}{parallax (arcsec)} \\ + \spec{RV}{D}{radial velocity (km~s$^{-1}$, +ve if receding)} \\ + \spec{AMPRMS}{D(21)}{star-independent mean-to-apparent parameters:} \\ + \specel {(1)} {time interval for proper motion (Julian years)} \\ + \specel {(2-4)} {barycentric position of the Earth (AU)} \\ + \specel {(5-7)} {heliocentric direction of the Earth (unit vector)} \\ + \specel {(8)} {(gravitational radius of + Sun)$\times 2 / $(Sun-Earth distance)} \\ + \specel {(9-11)} {{\bf v}: barycentric Earth velocity in units of c} \\ + \specel {(12)} {$\sqrt{1-\left|\mbox{\bf v}\right|^2}$} \\ + \specel {(13-21)} {precession/nutation $3\times3$ matrix} +} +\args{RETURNED} +{ + \spec{RA,DA}{D }{apparent \radec\ (radians)} +} +\notes +{ + \begin{enumerate} + \item Use of this routine is appropriate when efficiency is important + and where many star positions, all referred to the same equator + and equinox, are to be transformed for one epoch. The + star-independent parameters can be obtained by calling the + sla\_MAPPA routine. + \item If the parallax and proper motions are zero the sla\_MAPQKZ + routine can be used instead. + \item The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to + the mean equinox and equator of epoch EQ. + \item Strictly speaking, the routine is not valid for solar-system + sources, though the error will usually be extremely small. + However, to prevent gross errors in the case where the + position of the Sun is specified, the gravitational + deflection term is restrained within about \arcseci{920} of the + centre of the Sun's disc. The term has a maximum value of + about \arcsec{1}{85} at this radius, and decreases to zero as + the centre of the disc is approached. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_MAPQKZ}{Quick Mean-Appt, no PM {\it etc.}} +{ + \action{Quick mean to apparent place: transform a star \radec\ from + mean place to geocentric apparent place, given the + star-independent parameters, and assuming zero parallax + and FK5 proper motion. + The reference frames and timescales used are post IAU~1976.} + \call{CALL sla\_MAPQKZ (RM, DM, AMPRMS, RA, DA)} +} +\args{GIVEN} +{ + \spec{RM,DM}{D}{mean \radec\ (radians)} \\ + \spec{AMPRMS}{D(21)}{star-independent mean-to-apparent parameters:} \\ + \specel {(1)} {time interval for proper motion (Julian years)} \\ + \specel {(2-4)} {barycentric position of the Earth (AU)} \\ + \specel {(5-7)} {heliocentric direction of the Earth (unit vector)} \\ + \specel {(8)} {(gravitational radius of + Sun)$\times 2 / $(Sun-Earth distance)} \\ + \specel {(9-11)} {{\bf v}: barycentric Earth velocity in units of c} \\ + \specel {(12)} {$\sqrt{1-\left|\mbox{\bf v}\right|^2}$} \\ + \specel {(13-21)} {precession/nutation $3\times3$ matrix} +} +\args{RETURNED} +{ + \spec{RA,DA}{D}{apparent \radec\ (radians)} +} +\notes +{ + \begin{enumerate} + \item Use of this routine is appropriate when efficiency is important + and where many star positions, all with parallax and proper + motion either zero or already allowed for, and all referred to + the same equator and equinox, are to be transformed for one + epoch. The star-independent parameters can be obtained by + calling the sla\_MAPPA routine. + \item The corresponding routine for the case of non-zero parallax + and FK5 proper motion is sla\_MAPQK. + \item The vectors AMPRMS(2-4) and AMPRMS(5-7) are referred to the + mean equinox and equator of epoch EQ. + \item Strictly speaking, the routine is not valid for solar-system + sources, though the error will usually be extremely small. + However, to prevent gross errors in the case where the + position of the Sun is specified, the gravitational + deflection term is restrained within about \arcseci{920} of the + centre of the Sun's disc. The term has a maximum value of + about \arcsec{1}{85} at this radius, and decreases to zero as + the centre of the disc is approached. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr.Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_MOON}{Approx Moon Pos/Vel} +{ + \action{Approximate geocentric position and velocity of the Moon + (single precision).} + \call{CALL sla\_MOON (IY, ID, FD, PV)} +} +\args{GIVEN} +{ + \spec{IY}{I}{year} \\ + \spec{ID}{I}{day in year (1 = Jan 1st)} \\ + \spec{FD}{R }{fraction of day} +} +\args{RETURNED} +{ + \spec{PV}{R(6)}{Moon \xyzxyzd, mean equator and equinox of + date (AU, AU~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item The date and time is TDB (loosely ET) in a Julian calendar + which has been aligned to the ordinary Gregorian + calendar for the interval 1900 March 1 to 2100 February 28. + The year and day can be obtained by calling sla\_CALYD or + sla\_CLYD. + \item The position is accurate to better than 0.5~arcminute + in direction and 1000~km in distance. The velocity + is accurate to better than \arcsec{0}{5} per hour in direction + and 4~metres per socond in distance. (RMS figures with respect + to JPL DE200 for the interval 1960-2025 are \arcseci{14} and + \arcsec{0}{2} per hour in longitude, \arcseci{9} and \arcsec{0}{2} + per hour in latitude, 350~km and 2~metres per second in distance.) + Note that the distance accuracy is comparatively poor because this + routine is principally intended for computing topocentric direction. + \item This routine is only a partial implementation of the original + Meeus algorithm (reference below), which offers 4 times the + accuracy in direction and 20 times the accuracy in distance + when fully implemented (as it is in sla\_DMOON). + \end{enumerate} +} +\aref{Meeus, {\it l'Astronomie}, June 1984, p348.} +%----------------------------------------------------------------------- +\routine{SLA\_MXM}{Multiply $3\times3$ Matrices} +{ + \action{Product of two $3\times3$ matrices (single precision).} + \call{CALL sla\_MXM (A, B, C)} +} +\args{GIVEN} +{ + \spec{A}{R(3,3)}{matrix {\bf A}} \\ + \spec{B}{R(3,3)}{matrix {\bf B}} +} +\args{RETURNED} +{ + \spec{C}{R(3,3)}{matrix result: {\bf A}$\times${\bf B}} +} +\anote{To comply with the ANSI Fortran 77 standard, A, B and C must + be different arrays. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended.} +%----------------------------------------------------------------------- +\routine{SLA\_MXV}{Apply 3D Rotation} +{ + \action{Multiply a 3-vector by a rotation matrix (single precision).} + \call{CALL sla\_MXV (RM, VA, VB)} +} +\args{GIVEN} +{ + \spec{RM}{R(3,3)}{rotation matrix} \\ + \spec{VA}{R(3)}{vector to be rotated} +} +\args{RETURNED} +{ + \spec{VB}{R(3)}{result vector} +} +\notes +{ + \begin{enumerate} + \item This routine performs the operation: + \begin{verse} + {\bf b} = {\bf M}$\cdot${\bf a} + \end{verse} + where {\bf a} and {\bf b} are the 3-vectors VA and VB + respectively, and {\bf M} is the $3\times3$ matrix RM. + \item The main function of this routine is apply a + rotation; under these circumstances, ${\bf M}$ is a + {\it proper real orthogonal}\/ matrix. + \item To comply with the ANSI Fortran 77 standard, VA and VB must + {\bf not} be the same array. The routine is, in fact, coded + so as to work properly on the VAX and many other systems even + if this rule is violated, something that is {\bf not}, however, + recommended. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_NUT}{Nutation Matrix} +{ + \action{Form the matrix of nutation (IAU 1980 theory) for a given date.} + \call{CALL sla\_NUT (DATE, RMATN)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date + (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{RMATN}{D(3,3)}{nutation matrix} +} +\anote{The matrix is in the sense: + \begin{verse} + {\bf v}$_{true}$ = {\bf M}$\cdot${\bf v}$_{mean}$ + \end{verse} + where {\bf v}$_{true}$ is the star vector relative to the + true equator and equinox of date, {\bf M} is the + $3\times3$ matrix RMATN and + {\bf v}$_{mean}$ is the star vector relative to the + mean equator and equinox of date.} +\refs +{ + \begin{enumerate} + \item Final report of the IAU Working Group on Nutation, + chairman P.K.Seidelmann, 1980. + \item Kaplan, G.H., 1981.\ {\it USNO circular No.\ 163}, pA3-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_NUTC}{Nutation Components} +{ + \action{Nutation (IAU 1980 theory): longitude \& obliquity + components, and mean obliquity.} + \call{CALL sla\_NUTC (DATE, DPSI, DEPS, EPS0)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{TDB (formerly ET) as Modified Julian Date + (JD$-$2400000.5)} +} +\args{RETURNED} +{ + \spec{DPSI,DEPS}{D}{nutation in longitude and obliquity (radians)} \\ + \spec{EPS0}{D}{mean obliquity (radians)} +} +\refs +{ + \begin{enumerate} + \item Final report of the IAU Working Group on Nutation, + chairman P.K.Seidelmann, 1980. + \item Kaplan, G.H., 1981.\ {\it USNO circular no.\ 163}, pA3-6. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_OAP}{Observed to Apparent} +{ + \action{Observed to apparent place.} + \call{CALL sla\_OAP (\vtop{ + \hbox{TYPE, OB1, OB2, DATE, DUT, ELONGM, PHIM,} + \hbox{HM, XP, YP, TDK, PMB, RH, WL, TLR, RAP, DAP)}}} +} +\args{GIVEN} +{ + \spec{TYPE}{C*(*)}{type of coordinates -- `R', `H' or `A' (see below)} \\ + \spec{OB1}{D}{observed Az, HA or RA (radians; Az is N=0, E=$90^{\circ}$)} \\ + \spec{OB2}{D}{observed zenith distance or $\delta$ (radians)} \\ + \spec{DATE}{D }{UTC date/time (Modified Julian Date, JD$-$2400000.5)} \\ + \spec{DUT}{D}{$\Delta$UT: UT1$-$UTC (UTC seconds)} \\ + \spec{ELONGM}{D}{observer's mean longitude (radians, east +ve)} \\ + \spec{PHIM}{D}{observer's mean geodetic latitude (radians)} \\ + \spec{HM}{D}{observer's height above sea level (metres)} \\ + \spec{XP,YP}{D}{polar motion \xy\ coordinates (radians)} \\ + \spec{TDK}{D}{local ambient temperature (degrees K; std=273.155D0)} \\ + \spec{PMB}{D}{local atmospheric pressure (mB; std=1013.25D0)} \\ + \spec{RH}{D}{local relative humidity (in the range 0D0\,--\,1D0)} \\ + \spec{WL}{D}{effective wavelength ($\mu{\rm m}$, {\it e.g.}\ 0.55D0)} \\ + \spec{TLR}{D}{tropospheric lapse rate (degrees K per metre, + {\it e.g.}\ 0.0065D0)} +} +\args{RETURNED} +{ + \spec{RAP,DAP}{D}{geocentric apparent \radec} +} +\notes +{ + \begin{enumerate} + \item Only the first character of the TYPE argument is significant. + `R' or `r' indicates that OBS1 and OBS2 are the observed Right + Ascension and Declination; `H' or `h' indicates that they are + Hour Angle (west +ve) and Declination; anything else (`A' or + `a' is recommended) indicates that OBS1 and OBS2 are Azimuth + (north zero, east is $90^{\circ}$) and Zenith Distance. (Zenith + distance is used rather than elevation in order to reflect the + fact that no allowance is made for depression of the horizon.) + \item The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted azimuth and elevation should be within about + \arcsec{0}{1} for $\zeta<70^{\circ}$. Even + at a topocentric zenith distance of + $90^{\circ}$, the accuracy in elevation should be better than + 1~arcminute; useful results are available for a further + $3^{\circ}$, beyond which the sla\_REFRO routine returns a + fixed value of the refraction. The complementary + routines sla\_AOP (or sla\_AOPQK) and sla\_OAP (or sla\_OAPQK) + are self-consistent to better than 1~microarcsecond all over + the celestial sphere. + \item It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + \item {\it Observed}\/ \azel\ means the position that would be seen by a + perfect theodolite located at the observer. This is + related to the observed \hadec\ via the standard rotation, using + the geodetic latitude (corrected for polar motion), while the + observed HA and RA are related simply through the local + apparent ST. {\it Observed}\/ \radec\ or \hadec\ thus means the + position that would be seen by a perfect equatorial located + at the observer and with its polar axis aligned to the + Earth's axis of rotation ({\it n.b.}\ not to the refracted pole). + By removing from the observed place the effects of + atmospheric refraction and diurnal aberration, the + geocentric apparent \radec\ is obtained. + \item Frequently, {\it mean}\/ rather than {\it apparent}\, + \radec\ will be required, + in which case further transformations will be necessary. The + sla\_AMP {\it etc.}\ routines will convert + the apparent \radec\ produced + by the present routine into an FK5 J2000 mean place, by + allowing for the Sun's gravitational lens effect, annual + aberration, nutation and precession. Should FK4 B1950 + coordinates be needed, the routines sla\_FK524 {\it etc.}\ will also + need to be applied. + \item To convert to apparent \radec\ the coordinates read from a + real telescope, corrections would have to be applied for + encoder zero points, gear and encoder errors, tube flexure, + the position of the rotator axis and the pointing axis + relative to it, non-perpendicularity between the mounting + axes, and finally for the tilt of the azimuth or polar axis + of the mounting (with appropriate corrections for mount + flexures). Some telescopes would, of course, exhibit other + properties which would need to be accounted for at the + appropriate point in the sequence. + \item The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the sla\_AOPPA routine. + If nothing has changed significantly except the time, the + sla\_AOPPAT routine may be used to perform the requisite + partial recomputation of AOPRMS. + \item The DATE argument is UTC expressed as an MJD. This is, + strictly speaking, wrong, because of leap seconds. However, + as long as the $\Delta$UT and the UTC are consistent there + are no difficulties, except during a leap second. In this + case, the start of the 61st second of the final minute should + begin a new MJD day and the old pre-leap $\Delta$UT should + continue to be used. As the 61st second completes, the MJD + should revert to the start of the day as, simultaneously, + the $\Delta$UT changes by one second to its post-leap new value. + \item The $\Delta$UT (UT1$-$UTC) is tabulated in IERS circulars and + elsewhere. It increases by exactly one second at the end of + each UTC leap second, introduced in order to keep $\Delta$UT + within $\pm$\tsec{0}{9}. + \item IMPORTANT -- TAKE CARE WITH THE LONGITUDE SIGN CONVENTION. The + longitude required by the present routine is {\bf east-positive}, + in accordance with geographical convention (and right-handed). + In particular, note that the longitudes returned by the + sla\_OBS routine are west-positive (as in the {\it Astronomical + Almanac}\/ before 1984) and must be reversed in sign before use + in the present routine. + \item The polar coordinates XP,YP can be obtained from IERS + circulars and equivalent publications. The + maximum amplitude is about \arcsec{0}{3}. If XP,YP values + are unavailable, use XP=YP=0D0. See page B60 of the 1988 + {\it Astronomical Almanac}\/ for a definition of the two angles. + \item The height above sea level of the observing station, HM, + can be obtained from the {\it Astronomical Almanac}\/ (Section J + in the 1988 edition), or via the routine sla\_OBS. If P, + the pressure in mB, is available, an adequate + estimate of HM can be obtained from the following expression: + \begin{quote} + {\tt HM=-29.3D0*TSL*LOG(P/1013.25D0)} + \end{quote} + where TSL is the approximate sea-level air temperature in degrees K + (see {\it Astrophysical Quantities}, C.W.Allen, 3rd~edition, + \S 52.) Similarly, if the pressure P is not known, + it can be estimated from the height of the observing + station, HM as follows: + \begin{quote} + {\tt P=1013.25D0*EXP(-HM/(29.3D0*TSL))} + \end{quote} + Note, however, that the refraction is proportional to the + pressure and that an accurate P value is important for + precise work. + \item The azimuths {\it etc.}\ used by the present routine are with + respect to the celestial pole. Corrections from the terrestrial pole + can be computed using sla\_POLMO. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_OAPQK}{Quick Observed to Apparent} +{ + \action{Quick observed to apparent place.} + \call{CALL sla\_OAPQK (TYPE, OB1, OB2, AOPRMS, RAP, DAP)} +} +\args{GIVEN} +{ + \spec{TYPE}{C*(*)}{type of coordinates -- `R', `H' or `A' (see below)} \\ + \spec{OB1}{D}{observed Az, HA or RA (radians; Az is N=0, E=$90^{\circ}$)} \\ + \spec{OB2}{D}{observed zenith distance or $\delta$ (radians)} \\ + \spec{AOPRMS}{D(14)}{star-independent apparent-to-observed parameters:} \\ + \specel {(1)} {geodetic latitude (radians)} \\ + \specel {(2,3)} {sine and cosine of geodetic latitude} \\ + \specel {(4)} {magnitude of diurnal aberration vector} \\ + \specel {(5)} {height (HM)} \\ + \specel {(6)} {ambient temperature (TDK)} \\ + \specel {(7)} {pressure (PMB)} \\ + \specel {(8)} {relative humidity (RH)} \\ + \specel {(9)} {wavelength (WL)} \\ + \specel {(10)} {lapse rate (TLR)} \\ + \specel {(11,12)} {refraction constants A and B (radians)} \\ + \specel {(13)} {longitude + eqn of equinoxes + + ``sidereal $\Delta$UT'' (radians)} \\ + \specel {(14)} {local apparent sidereal time (radians)} +} +\args{RETURNED} +{ + \spec{RAP,DAP}{D}{geocentric apparent \radec} +} +\notes +{ + \begin{enumerate} + \item Only the first character of the TYPE argument is significant. + `R' or `r' indicates that OBS1 and OBS2 are the observed Right + Ascension and Declination; `H' or `h' indicates that they are + Hour Angle (west +ve) and Declination; anything else (`A' or + `a' is recommended) indicates that OBS1 and OBS2 are Azimuth + (north zero, east is $90^{\circ}$) and Zenith Distance. (Zenith + distance is used rather than elevation in order to reflect the + fact that no allowance is made for depression of the horizon.) + \item The accuracy of the result is limited by the corrections for + refraction. Providing the meteorological parameters are + known accurately and there are no gross local effects, the + predicted azimuth and elevation should be within about + \arcsec{0}{1} for $\zeta<70^{\circ}$. Even + at a topocentric zenith distance of + $90^{\circ}$, the accuracy in elevation should be better than + 1~arcminute; useful results are available for a further + $3^{\circ}$, beyond which the sla\_REFRO routine returns a + fixed value of the refraction. The complementary + routines sla\_AOP (or sla\_AOPQK) and sla\_OAP (or sla\_OAPQK) + are self-consistent to better than 1~microarcsecond all over + the celestial sphere. + \item It is advisable to take great care with units, as even + unlikely values of the input parameters are accepted and + processed in accordance with the models used. + \item {\it Observed}\/ \azel\ means the position that would be seen by a + perfect theodolite located at the observer. This is + related to the observed \hadec\ via the standard rotation, using + the geodetic latitude (corrected for polar motion), while the + observed HA and RA are related simply through the local + apparent ST. {\it Observed}\/ \radec\ or \hadec\ thus means the + position that would be seen by a perfect equatorial located + at the observer and with its polar axis aligned to the + Earth's axis of rotation ({\it n.b.}\ not to the refracted pole). + By removing from the observed place the effects of + atmospheric refraction and diurnal aberration, the + geocentric apparent \radec\ is obtained. + \item Frequently, {\it mean}\/ rather than {\it apparent}\, + \radec\ will be required, + in which case further transformations will be necessary. The + sla\_AMP {\it etc.}\ routines will convert + the apparent \radec\ produced + by the present routine into an FK5 J2000 mean place, by + allowing for the Sun's gravitational lens effect, annual + aberration, nutation and precession. Should FK4 B1950 + coordinates be needed, the routines sla\_FK524 {\it etc.}\ will also + need to be applied. + \item To convert to apparent \radec\ the coordinates read from a + real telescope, corrections would have to be applied for + encoder zero points, gear and encoder errors, tube flexure, + the position of the rotator axis and the pointing axis + relative to it, non-perpendicularity between the mounting + axes, and finally for the tilt of the azimuth or polar axis + of the mounting (with appropriate corrections for mount + flexures). Some telescopes would, of course, exhibit other + properties which would need to be accounted for at the + appropriate point in the sequence. + \item The star-independent apparent-to-observed-place parameters + in AOPRMS may be computed by means of the sla\_AOPPA routine. + If nothing has changed significantly except the time, the + sla\_AOPPAT routine may be used to perform the requisite + partial recomputation of AOPRMS. + \item The azimuths {\it etc.}\ used by the present routine are with + respect to the celestial pole. Corrections from the terrestrial pole + can be computed using sla\_POLMO. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_OBS}{Observatory Parameters} +{ + \action{Look up an entry in a standard list of + groundbased observing stations parameters.} + \call{CALL sla\_OBS (N, C, NAME, W, P, H)} +} +\args{GIVEN} +{ + \spec{N}{I}{number specifying observing station} +} +\args{GIVEN or RETURNED} +{ + \spec{C}{C*(*)}{identifier specifying observing station} +} +\args{RETURNED} +{ + \spec{NAME}{C*(*)}{name of specified observing station} \\ + \spec{W}{D}{longitude (radians, west +ve)} \\ + \spec{P}{D}{geodetic latitude (radians, north +ve)} \\ + \spec{H}{D}{height above sea level (metres)} +} +\notes +{ + \begin{enumerate} + \item Station identifiers C may be up to 10 characters long, + and station names NAME may be up to 40 characters long. + \item C and N are {\it alternative}\/ ways of specifying the observing + station. The C option, which is the most generally useful, + may be selected by specifying an N value of zero or less. + If N is 1 or more, the parameters of the Nth station + in the currently supported list are interrogated, and + the station identifier C is returned as well as NAME, W, + P and H. + \item If the station parameters are not available, either because + the station identifier C is not recognized, or because an + N value greater than the number of stations supported is + given, a name of `?' is returned and W, P and H are left in + their current states. + \item Programs can obtain a list of all currently supported + stations by calling the routine repeatedly, with N=1,2,3... + When NAME=`?' is seen, the list of stations has been + exhausted. The stations at the time of writing are listed + below. + \item Station numbers, identifiers, names and other details are + subject to change and should not be hardwired into + application programs. + \item All station identifiers C are uppercase only; lower case + characters must be converted to uppercase by the calling + program. The station names returned may contain both upper- + and lowercase. All characters up to the first space are + checked; thus an abbreviated ID will return the parameters + for the first station in the list which matches the + abbreviation supplied, and no station in the list will ever + contain embedded spaces. C must not have leading spaces. + \item IMPORTANT -- BEWARE OF THE LONGITUDE SIGN CONVENTION. The + longitude returned by sla\_OBS is + {\bf west-positive}, following the pre-1984 {\it Astronomical + Almanac}. However, this sign convention is left-handed and is + the opposite of the one now used; elsewhere in + SLALIB the preferable east-positive convention is used. In + particular, note that for use in sla\_AOP, sla\_AOPPA and + sla\_OAP the sign of the longitude must be reversed. + \item Users are urged to inform the author of any improvements + they would like to see made. For example: + \begin{itemize} + \item typographical corrections + \item more accurate parameters + \item better station identifiers or names + \item additional stations + \end{itemize} + \end{enumerate} +Stations supported by sla\_OBS at the time of writing: +\begin{tabbing} +xxxxxxxxxxxxxxxxx \= \kill +{\it ID} \> {\it NAME} \\ \\ +AAT \> Anglo-Australian 3.9m Telescope \\ +ANU2.3 \> Siding Spring 2.3 metre \\ +APO3.5 \> Apache Point 3.5m \\ +ARECIBO \> Arecibo 1000 foot \\ +ATCA \> Australia Telescope Compact Array \\ +BLOEMF \> Bloemfontein 1.52 metre \\ +BOSQALEGRE \> Bosque Alegre 1.54 metre \\ +CAMB1MILE \> Cambridge 1 mile \\ +CAMB5KM \> Cambridge 5km \\ +CATALINA61 \> Catalina 61 inch \\ +CFHT \> Canada-France-Hawaii 3.6m Telescope \\ +CSO \> Caltech Sub-mm Observatory, Mauna Kea \\ +DAO72 \> DAO Victoria BC 1.85 metre \\ +DUNLAP74 \> David Dunlap 74 inch \\ +DUPONT \> Du Pont 2.5m Telescope, Las Campanas \\ +EFFELSBERG \> Effelsberg 100 metre \\ +ESO3.6 \> ESO 3.6 metre \\ +ESONTT \> ESO 3.5 metre NTT \\ +ESOSCHM \> ESO 1 metre Schmidt, La Silla \\ +FCRAO \> Five College Radio Astronomy Obs \\ +FLAGSTF61 \> USNO 61 inch astrograph, Flagstaff \\ +GBVA140 \> Greenbank 140 foot \\ +GBVA300 \> Greenbank 300 foot \\ +GEMININ \> Gemini North 8-m telescope \\ +HARVARD \> Harvard College Observatory 1.55m \\ +HPROV1.52 \> Haute Provence 1.52 metre \\ +HPROV1.93 \> Haute Provence 1.93 metre \\ +IRTF \> NASA IR Telescope Facility, Mauna Kea \\ +JCMT \> JCMT 15 metre \\ +JODRELL1 \> Jodrell Bank 250 foot \\ +KECK1 \> Keck 10m Telescope 1 \\ +KECK2 \> Keck 10m Telescope 2 \\ +KISO \> Kiso 1.05 metre Schmidt, Japan \\ +KOTTAMIA \> Kottamia 74 inch \\ +KPNO158 \> Kitt Peak 158 inch \\ +KPNO36FT \> Kitt Peak 36 foot \\ +KPNO84 \> Kitt Peak 84 inch \\ +KPNO90 \> Kitt Peak 90 inch \\ +LICK120 \> Lick 120 inch \\ +LOWELL72 \> Perkins 72 inch, Lowell \\ +LPO1 \> Jacobus Kapteyn 1m Telescope \\ +LPO2.5 \> Isaac Newton 2.5m Telescope \\ +LPO4.2 \> William Herschel 4.2m Telescope \\ +MAUNAK88 \> Mauna Kea 88 inch \\ +MCDONLD2.1 \> McDonald 2.1 metre \\ +MCDONLD2.7 \> McDonald 2.7 metre \\ +MMT \> MMT, Mt Hopkins \\ +MOPRA \> ATNF Mopra Observatory \\ +MTEKAR \> Mt Ekar 1.82 metre \\ +MTHOP1.5 \> Mt Hopkins 1.5 metre \\ +MTLEMMON60 \> Mt Lemmon 60 inch \\ +NOBEYAMA \> Nobeyama 45 metre \\ +OKAYAMA \> Okayama 1.88 metre \\ +PALOMAR200 \> Palomar 200 inch \\ +PALOMAR48 \> Palomar 48-inch Schmidt \\ +PALOMAR60 \> Palomar 60 inch \\ +PARKES \> Parkes 64 metre \\ +QUEBEC1.6 \> Quebec 1.6 metre \\ +SAAO74 \> Sutherland 74 inch \\ +SANPM83 \> San Pedro Martir 83 inch \\ +ST.ANDREWS \> St Andrews University Observatory \\ +STEWARD90 \> Steward 90 inch \\ +STROMLO74 \> Mount Stromlo 74 inch \\ +SUBARU \> Subaru 8 metre \\ +SUGARGROVE \> Sugar Grove 150 foot \\ +TAUTNBG \> Tautenburg 2 metre \\ +TAUTSCHM \> Tautenberg 1.34 metre Schmidt \\ +TIDBINBLA \> Tidbinbilla 64 metre \\ +TOLOLO1.5M \> Cerro Tololo 1.5 metre \\ +TOLOLO4M \> Cerro Tololo 4 metre \\ +UKIRT \> UK Infra Red Telescope \\ +UKST \> UK 1.2 metre Schmidt, Siding Spring \\ +USSR6 \> USSR 6 metre \\ +USSR600 \> USSR 600 foot \\ +VLA \> Very Large Array +\end{tabbing} +} +%----------------------------------------------------------------------- +\routine{SLA\_PA}{$h,\delta$ to Parallactic Angle} +{ + \action{Hour angle and declination to parallactic angle + (double precision).} + \call{D~=~sla\_PA (HA, DEC, PHI)} +} +\args{GIVEN} +{ + \spec{HA}{D}{hour angle in radians (geocentric apparent)} \\ + \spec{DEC}{D}{declination in radians (geocentric apparent)} \\ + \spec{PHI}{D}{latitude in radians (geodetic)} +} +\args{RETURNED} +{ + \spec{sla\_PA}{D}{parallactic angle (radians, in the range $\pm \pi$)} +} +\notes +{ + \begin{enumerate} + \item The parallactic angle at a point in the sky is the position + angle of the vertical, {\it i.e.}\ the angle between the direction to + the pole and to the zenith. In precise applications care must + be taken only to use geocentric apparent \hadec\ and to consider + separately the effects of atmospheric refraction and telescope + mount errors. + \item At the pole a zero result is returned. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PAV}{Position-Angle Between Two Directions} +{ + \action{Returns the bearing (position angle) of one celestial + direction with respect to another (single precision).} + \call{R~=~sla\_PAV (V1, V2)} +} +\args{GIVEN} +{ + \spec{V1}{R(3)}{direction cosines of one point} \\ + \spec{V2}{R(3)}{directions cosines of the other point} +} +\args{RETURNED} +{ + \spec{sla\_PAV}{R}{position-angle of 2nd point with respect to 1st} +} +\notes +{ + \begin{enumerate} + \item The coordinate frames correspond to \radec, + $[\lambda,\phi]$ {\it etc.}. + \item The result is the bearing (position angle), in radians, + of point V2 as seen + from point V1. It is in the range $\pm \pi$. The sense + is such that if V2 + is a small distance due east of V1 the result + is about $+\pi/2$. Zero is returned + if the two points are coincident. + \item The routine sla\_BEAR performs an equivalent function except + that the points are specified in the form of spherical coordinates. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_PCD}{Apply Radial Distortion} +{ + \action{Apply pincushion/barrel distortion to a tangent-plane \xy.} + \call{CALL sla\_PCD (DISCO,X,Y)} +} +\args{GIVEN} +{ + \spec{DISCO}{D}{pincushion/barrel distortion coefficient} \\ + \spec{X,Y}{D}{tangent-plane \xy} +} +\args{RETURNED} +{ + \spec{X,Y}{D}{distorted \xy} +} +\notes +{ + \begin{enumerate} + \item The distortion is of the form $\rho = r (1 + c r^{2})$, where $r$ is + the radial distance from the tangent point, $c$ is the DISCO + argument, and $\rho$ is the radial distance in the presence of + the distortion. + \item For {\it pincushion}\/ distortion, C is +ve; for + {\it barrel}\/ distortion, C is $-$ve. + \item For X,Y in units of one projection radius (in the case of + a photographic plate, the focal length), the following + DISCO values apply: + + \vspace{2ex} + + \hspace{5em} + \begin{tabular}{|l|c|} \hline + Geometry & DISCO \\ \hline \hline + astrograph & 0.0 \\ \hline + Schmidt & $-$0.3333 \\ \hline + AAT PF doublet & +147.069 \\ \hline + AAT PF triplet & +178.585 \\ \hline + AAT f/8 & +21.20 \\ \hline + JKT f/8 & +14.6 \\ \hline + \end{tabular} + + \vspace{2ex} + + \item There is a companion routine, sla\_UNPCD, which performs + an approximately inverse operation. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PDA2H}{H.A.\ for a Given Azimuth} +{ + \action{Hour Angle corresponding to a given azimuth (double precision).} + \call{CALL sla\_PDA2H (P, D, A, H1, J1, H2, J2)} +} +\args{GIVEN} +{ + \spec{P}{D}{latitude} \\ + \spec{D}{D}{declination} \\ + \spec{A}{D}{azimuth} +} +\args{RETURNED} +{ + \spec{H1}{D}{hour angle: first solution if any} \\ + \spec{J1}{I}{flag: 0 = solution 1 is valid} \\ + \spec{H2}{D}{hour angle: second solution if any} \\ + \spec{J2}{I}{flag: 0 = solution 2 is valid} +} +%----------------------------------------------------------------------- +\routine{SLA\_PDQ2H}{H.A.\ for a Given P.A.} +{ + \action{Hour Angle corresponding to a given parallactic angle + (double precision).} + \call{CALL sla\_PDQ2H (P, D, Q, H1, J1, H2, J2)} +} +\args{GIVEN} +{ + \spec{P}{D}{latitude} \\ + \spec{D}{D}{declination} \\ + \spec{Q}{D}{azimuth} +} +\args{RETURNED} +{ + \spec{H1}{D}{hour angle: first solution if any} \\ + \spec{J1}{I}{flag: 0 = solution 1 is valid} \\ + \spec{H2}{D}{hour angle: second solution if any} \\ + \spec{J2}{I}{flag: 0 = solution 2 is valid} +} +%------------------------------------------------------------------------------ +\routine{SLA\_PERTEL}{Perturbed Orbital Elements} +{ + \action{Update the osculating elements of an asteroid or comet by + applying planetary perturbations.} + \call{CALL sla\_PERTEL (\vtop{ + \hbox{JFORM, DATE0, DATE1,} + \hbox{EPOCH0, ORBI0, ANODE0, PERIH0, AORQ0, E0, AM0,} + \hbox{EPOCH1, ORBI1, ANODE1, PERIH1, AORQ1, E1, AM1,} + \hbox{JSTAT)}}} +} +\args{GIVEN (format and dates)} +{ + \spec{JFORM}{I}{choice of element set (2 or 3; Note~1)} \\ + \spec{DATE0}{D}{date of osculation (TT MJD) for the given} \\ + \spec{}{}{\hspace{1.5em} elements} \\ + \spec{DATE1}{D}{date of osculation (TT MJD) for the updated} \\ + \spec{}{}{\hspace{1.5em} elements} +} +\args{GIVEN (the unperturbed elements)} +{ + \spec{EPOCH0}{D}{epoch of the given element set + ($t_0$ or $T$, TT MJD;} \\ + \spec{}{}{\hspace{1.5em} Note~2)} \\ + \spec{ORBI0}{D}{inclination ($i$, radians)} \\ + \spec{ANODE0}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH0}{D}{argument of perihelion + ($\omega$, radians)} \\ + \spec{AORQ0}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E0}{D}{eccentricity ($e$)} \\ + \spec{AM0}{D}{mean anomaly ($M$, radians, JFORM=2 only)} +} +\args{RETURNED (the updated elements)} +{ + \spec{EPOCH1}{D}{epoch of the updated element set + ($t_0$ or $T$,} \\ + \spec{}{}{\hspace{1.5em} TT MJD; Note~2)} \\ + \spec{ORBI1}{D}{inclination ($i$, radians)} \\ + \spec{ANODE1}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH1}{D}{argument of perihelion + ($\omega$, radians)} \\ + \spec{AORQ1}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E1}{D}{eccentricity ($e$)} \\ + \spec{AM1}{D}{mean anomaly ($M$, radians, JFORM=2 only)} +} +\args{RETURNED (status flag)} +{ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{0.5em}+102 = warning, distant epoch} \\ + \spec{}{}{\hspace{0.5em}+101 = warning, large timespan + ($>100$ years)} \\ + \spec{}{}{\hspace{-1.3em}+1 to +8 = coincident with major planet + (Note~6)} \\ + \spec{}{}{\hspace{1.95em} 0 = OK} \\ + \spec{}{}{\hspace{1.2em} $-$1 = illegal JFORM} \\ + \spec{}{}{\hspace{1.2em} $-$2 = illegal E0} \\ + \spec{}{}{\hspace{1.2em} $-$3 = illegal AORQ0} \\ + \spec{}{}{\hspace{1.2em} $-$4 = internal error} \\ + \spec{}{}{\hspace{1.2em} $-$5 = numerical error} +} +\notes +{ + \begin{enumerate} + \item Two different element-format options are supported, as follows. \\ + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e \leq 10 )$ + \end{tabbing} + \item DATE0, DATE1, EPOCH0 and EPOCH1 are all instants of time in + the TT timescale (formerly Ephemeris Time, ET), expressed + as Modified Julian Dates (JD$-$2400000.5). + \begin{itemize} + \item DATE0 is the instant at which the given + ({\it i.e.}\ unperturbed) osculating elements are correct. + \item DATE1 is the specified instant at which the updated osculating + elements are correct. + \item EPOCH0 and EPOCH1 will be the same as DATE0 and DATE1 + (respectively) for the JFORM=2 case, normally used for minor + planets. For the JFORM=3 case, the two epochs will refer to + perihelion passage and so will not, in general, be the same as + DATE0 and/or DATE1 though they may be similar to one another. + \end{itemize} + \item The elements are with respect to the J2000 ecliptic and mean equinox. + \item Unused elements (AM0 and AM1 for JFORM=3) are not accessed. + \item See the sla\_PERTUE routine for details of the algorithm used. + \item This routine is not intended to be used for major planets, which + is why JFORM=1 is not available and why there is no opportunity + to specify either the longitude of perihelion or the daily + motion. However, if JFORM=2 elements are somehow obtained for a + major planet and supplied to the routine, sensible results will, + in fact, be produced. This happens because the sla\_PERTUE routine + that is called to perform the calculations checks the separation + between the body and each of the planets and interprets a + suspiciously small value (0.001~AU) as an attempt to apply it to + the planet concerned. If this condition is detected, the + contribution from that planet is ignored, and the status is set to + the planet number (Mercury=1,\ldots,Neptune=8) as a warning. + \end{enumerate} +} +\aref{Sterne, Theodore E., {\it An Introduction to Celestial Mechanics,}\/ + Interscience Publishers, 1960. Section 6.7, p199.} +%------------------------------------------------------------------------------ +\routine{SLA\_PERTUE}{Perturbed Universal Elements} +{ + \action{Update the universal elements of an asteroid or comet by + applying planetary perturbations.} + \call{CALL sla\_PERTUE (DATE, U, JSTAT)} +} +\args{GIVEN} +{ + \spec{DATE1}{D}{final epoch (TT MJD) for the updated elements} +} +\args{GIVEN and RETURNED} +{ + \spec{U}{D(13)}{universal elements (updated in place)} \\ + \specel {(1)} {combined mass ($M+m$)} \\ + \specel {(2)} {total energy of the orbit ($\alpha$)} \\ + \specel {(3)} {reference (osculating) epoch ($t_0$)} \\ + \specel {(4-6)} {position at reference epoch (${\rm \bf r}_0$)} \\ + \specel {(7-9)} {velocity at reference epoch (${\rm \bf v}_0$)} \\ + \specel {(10)} {heliocentric distance at reference epoch} \\ + \specel {(11)} {${\rm \bf r}_0.{\rm \bf v_0}$} \\ + \specel {(12)} {date ($t$)} \\ + \specel {(13)} {universal eccentric anomaly ($\psi$) of date, approx} +} +\args{RETURNED} +{ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{0.5em}+102 = warning, distant epoch} \\ + \spec{}{}{\hspace{0.5em}+101 = warning, large timespan + ($>100$ years)} \\ + \spec{}{}{\hspace{-1.3em}+1 to +8 = coincident with major planet + (Note~5)} \\ + \spec{}{}{\hspace{1.95em} 0 = OK} \\ + \spec{}{}{\hspace{1.2em} $-$1 = numerical error} +} +\notes +{ + \begin{enumerate} + \setlength{\parskip}{\medskipamount} + \item The ``universal'' elements are those which define the orbit for the + purposes of the method of universal variables (see reference 2). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i)~$\alpha$, which is proportional to the total energy of the + orbit, (ii)~the heliocentric distance at epoch, + (iii)~the outwards component of the velocity at the given epoch, + (iv)~an estimate of $\psi$, the ``universal eccentric anomaly'' at a + given date and (v)~that date. + \item The universal elements are with respect to the J2000 equator and + equinox. + \item The epochs DATE, U(3) and U(12) are all Modified Julian Dates + (JD$-$2400000.5). + \item The algorithm is a simplified form of Encke's method. It takes as + a basis the unperturbed motion of the body, and numerically + integrates the perturbing accelerations from the major planets. + The expression used is essentially Sterne's 6.7-2 (reference 1). + Everhart and Pitkin (reference 2) suggest rectifying the orbit at + each integration step by propagating the new perturbed position + and velocity as the new universal variables. In the present + routine the orbit is rectified less frequently than this, in order + to gain a slight speed advantage. However, the rectification is + done directly in terms of position and velocity, as suggested by + Everhart and Pitkin, bypassing the use of conventional orbital + elements. + + The $f(q)$ part of the full Encke method is not used. The purpose + of this part is to avoid subtracting two nearly equal quantities + when calculating the ``indirect member'', which takes account of the + small change in the Sun's attraction due to the slightly displaced + position of the perturbed body. A simpler, direct calculation in + double precision proves to be faster and not significantly less + accurate. + + Apart from employing a variable timestep, and occasionally + ``rectifying the orbit'' to keep the indirect member small, the + integration is done in a fairly straightforward way. The + acceleration estimated for the middle of the timestep is assumed + to apply throughout that timestep; it is also used in the + extrapolation of the perturbations to the middle of the next + timestep, to predict the new disturbed position. There is no + iteration within a timestep. + + Measures are taken to reach a compromise between execution time + and accuracy. The starting-point is the goal of achieving + arcsecond accuracy for ordinary minor planets over a ten-year + timespan. This goal dictates how large the timesteps can be, + which in turn dictates how frequently the unperturbed motion has + to be recalculated from the osculating elements. + + Within predetermined limits, the timestep for the numerical + integration is varied in length in inverse proportion to the + magnitude of the net acceleration on the body from the major + planets. + + The numerical integration requires estimates of the major-planet + motions. Approximate positions for the major planets (Pluto + alone is omitted) are obtained from the routine sla\_PLANET. Two + levels of interpolation are used, to enhance speed without + significantly degrading accuracy. At a low frequency, the routine + sla\_PLANET is called to generate updated position+velocity ``state + vectors''. The only task remaining to be carried out at the full + frequency ({\it i.e.}\ at each integration step) is to use the state + vectors to extrapolate the planetary positions. In place of a + strictly linear extrapolation, some allowance is made for the + curvature of the orbit by scaling back the radius vector as the + linear extrapolation goes off at a tangent. + + Various other approximations are made. For example, perturbations + by Pluto and the minor planets are neglected, relativistic effects + are not taken into account and the Earth-Moon system is treated as + a single body. + + In the interests of simplicity, the background calculations for + the major planets are carried out {\it en masse.} + The mean elements and + state vectors for all the planets are refreshed at the same time, + without regard for orbit curvature, mass or proximity. + + \item This routine is not intended to be used for major planets. + However, if major-planet elements are supplied, sensible results + will, in fact, be produced. This happens because the routine + checks the separation between the body and each of the planets and + interprets a suspiciously small value (0.001~AU) as an attempt to + apply the routine to the planet concerned. If this condition + is detected, the + contribution from that planet is ignored, and the status is set to + the planet number (Mercury=1,\ldots,Neptune=8) as a warning. + \end{enumerate} +} +\refs{ + \begin{enumerate} + \item Sterne, Theodore E., {\it An Introduction to Celestial Mechanics,}\/ + Interscience Publishers, 1960. Section 6.7, p199. + \item Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PLANEL}{Planet Position from Elements} +{ + \action{Heliocentric position and velocity of a planet, + asteroid or comet, starting from orbital elements.} + \call{CALL sla\_PLANEL (\vtop{ + \hbox{DATE, JFORM, EPOCH, ORBINC, ANODE, PERIH,} + \hbox{AORQ, E, AORL, DM, PV, JSTAT)}}} +} +\args{GIVEN} +{ + \spec{DATE}{D}{Modified Julian Date (JD$-$2400000.5)} \\ + \spec{JFORM}{I}{choice of element set (1-3, see Note~3, below)} \\ + \spec{EPOCH}{D}{epoch of elements ($t_0$ or $T$, TT MJD)} \\ + \spec{ORBINC}{D}{inclination ($i$, radians)} \\ + \spec{ANODE}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH}{D}{longitude or argument of perihelion + ($\varpi$ or $\omega$,} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{AORQ}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E}{D}{eccentricity ($e$)} \\ + \spec{AORL}{D}{mean anomaly or longitude + ($M$ or $L$, radians,} \\ + \spec{}{}{\hspace{1.5em} JFORM=1,2 only)} \\ + \spec{DM}{D}{daily motion ($n$, radians, JFORM=1 only)} +} +\args{RETURNED} +{ + \spec{PV}{D(6)}{heliocentric \xyzxyzd, equatorial, J2000} \\ + \spec{}{}{\hspace{1.5em} (AU, AU/s)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{2.3em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} $-$1 = illegal JFORM} \\ + \spec{}{}{\hspace{1.5em} $-$2 = illegal E} \\ + \spec{}{}{\hspace{1.5em} $-$3 = illegal AORQ} \\ + \spec{}{}{\hspace{1.5em} $-$4 = illegal DM} \\ + \spec{}{}{\hspace{1.5em} $-$5 = numerical error} +} +\notes +{ + \begin{enumerate} + \item DATE is the instant for which the prediction is + required. It is in the TT timescale (formerly + Ephemeris Time, ET) and is a + Modified Julian Date (JD$-$2400000.5). + \item The elements are with respect to + the J2000 ecliptic and equinox. + \item Three different element-format options are available, as + follows. \\ + + JFORM=1, suitable for the major planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> longitude of perihelion $\varpi$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean longitude $L$ (radians) \\ + \> DM \> = \> daily motion $n$ (radians) + \end{tabbing} + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e \leq 10 )$ + \end{tabbing} + \item Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + \item The reference frame for the result is equatorial and is with + respect to the mean equinox and ecliptic of epoch J2000. + \item The algorithm was originally adapted from the EPHSLA program of + D.\,H.\,P.\,Jones (private communication, 1996). The method + is based on Stumpff's Universal Variables. + \end{enumerate} +} +\aref{Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983.} +%------------------------------------------------------------------------------ +\routine{SLA\_PLANET}{Planetary Ephemerides} +{ + \action{Approximate heliocentric position and velocity of a planet.} + \call{CALL sla\_PLANET (DATE, NP, PV, JSTAT)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{Modified Julian Date (JD$-$2400000.5)} \\ + \spec{NP}{I}{planet:} \\ + \spec{}{}{\hspace{1.5em} 1\,=\,Mercury} \\ + \spec{}{}{\hspace{1.5em} 2\,=\,Venus} \\ + \spec{}{}{\hspace{1.5em} 3\,=\,Earth-Moon Barycentre} \\ + \spec{}{}{\hspace{1.5em} 4\,=\,Mars} \\ + \spec{}{}{\hspace{1.5em} 5\,=\,Jupiter} \\ + \spec{}{}{\hspace{1.5em} 6\,=\,Saturn} \\ + \spec{}{}{\hspace{1.5em} 7\,=\,Uranus} \\ + \spec{}{}{\hspace{1.5em} 8\,=\,Neptune} \\ + \spec{}{}{\hspace{1.5em} 9\,=\,Pluto} +} +\args{RETURNED} +{ + \spec{PV}{D(6)}{heliocentric \xyzxyzd, equatorial, J2000} \\ + \spec{}{}{\hspace{1.5em} (AU, AU/s)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} $+$1 = warning: date outside of range} \\ + \spec{}{}{\hspace{2.3em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} $-$1 = illegal NP (outside 1-9)} \\ + \spec{}{}{\hspace{1.5em} $-$2 = solution didn't converge} +} +\notes +{ + \begin{enumerate} + \item The epoch, DATE, is in the TDB timescale and is in the form + of a Modified Julian Date (JD$-$2400000.5). + \item The reference frame is equatorial and is with respect to + the mean equinox and ecliptic of epoch J2000. + \item If a planet number, NP, outside the range 1-9 is supplied, an error + status is returned (JSTAT~=~$-1$) and the PV vector + is set to zeroes. + \item The algorithm for obtaining the mean elements of the + planets from Mercury to Neptune is due to + J.\,L.\,Simon, P.\,Bretagnon, J.\,Chapront, + M.\,Chapront-Touze, G.\,Francou and J.\,Laskar (Bureau des + Longitudes, Paris, France). The (completely different) + algorithm for calculating the ecliptic coordinates of + Pluto is by Meeus. + \item Comparisons of the present routine with the JPL DE200 ephemeris + give the following RMS errors over the interval 1960-2025: + \begin{tabbing} + xxxxx \= xxxxxxxxxxxxxxxxx \= xxxxxxxxxxxxxx \= \kill + \> \> {\it position (km)} \> {\it speed (metre/sec)} \\ \\ + \> Mercury \> \hspace{2em}334 \> \hspace{2.5em}0.437 \\ + \> Venus \> \hspace{1.5em}1060 \> \hspace{2.5em}0.855 \\ + \> EMB \> \hspace{1.5em}2010 \> \hspace{2.5em}0.815 \\ + \> Mars \> \hspace{1.5em}7690 \> \hspace{2.5em}1.98 \\ + \> Jupiter \> \hspace{1em}71700 \> \hspace{2.5em}7.70 \\ + \> Saturn \> \hspace{0.5em}199000 \> \hspace{2em}19.4 \\ + \> Uranus \> \hspace{0.5em}564000 \> \hspace{2em}16.4 \\ + \> Neptune \> \hspace{0.5em}158000 \> \hspace{2em}14.4 \\ + \> Pluto \> \hspace{1em}36400 \> \hspace{2.5em}0.137 + \end{tabbing} + From comparisons with DE102, Simon {\it et al.}\/ quote the following + longitude accuracies over the interval 1800-2200: + \begin{tabbing} + xxxxx \= xxxxxxxxxxxxxxxxxxxx \= \kill + \> Mercury \> \hspace{0.5em}\arcseci{4} \\ + \> Venus \> \hspace{0.5em}\arcseci{5} \\ + \> EMB \> \hspace{0.5em}\arcseci{6} \\ + \> Mars \> \arcseci{17} \\ + \> Jupiter \> \arcseci{71} \\ + \> Saturn \> \arcseci{81} \\ + \> Uranus \> \arcseci{86} \\ + \> Neptune \> \arcseci{11} + \end{tabbing} + In the case of Pluto, Meeus quotes an accuracy of \arcsec{0}{6} + in longitude and \arcsec{0}{2} in latitude for the period + 1885-2099. + + For all except Pluto, over the period 1000-3000, + the accuracy is better than 1.5 + times that over 1800-2200. Outside the interval 1000-3000 the + accuracy declines. For Pluto the accuracy declines rapidly + outside the period 1885-2099. Outside these ranges + (1885-2099 for Pluto, 1000-3000 for the rest) a ``date out + of range'' warning status ({\tt JSTAT=+1}) is returned. + \item The algorithms for (i)~Mercury through Neptune and + (ii)~Pluto are completely independent. In the Mercury + through Neptune case, the present SLALIB + implementation differs from the original + Simon {\it et al.}\/ Fortran code in the following respects: + \begin{itemize} + \item The date is supplied as a Modified Julian Date rather + a Julian Date (${\rm MJD} = ({\rm JD} - 2400000.5$). + \item The result is returned only in equatorial + Cartesian form; the ecliptic + longitude, latitude and radius vector are not returned. + \item The velocity is in AU per second, not AU per day. + \item Different error/warning status values are used. + \item Kepler's Equation is not solved inline. + \item Polynomials in T are nested to minimize rounding errors. + \item Explicit double-precision constants are used to avoid + mixed-mode expressions. + \item There are other, cosmetic, changes to comply with + Starlink/SLALIB style guidelines. + \end{itemize} + None of the above changes affects the result significantly. + \item NP\,=\,3 the result is for the Earth-Moon Barycentre. To + obtain the heliocentric position and velocity of the Earth, + either use the SLALIB routine sla\_EVP or call sla\_DMOON and + subtract 0.012150581 times the geocentric Moon vector from + the EMB vector produced by the present routine. (The Moon + vector should be precessed to J2000 first, but this can + be omitted for modern epochs without introducing significant + inaccuracy.) + \end{enumerate} +\refs +{ + \begin{enumerate} + \item Simon {\it et al.,}\/ + Astron.\ Astrophys.\ {\bf 282}, 663 (1994). + \item Meeus, J., + {\it Astronomical Algorithms,}\/ Willmann-Bell (1991). + \end{enumerate} +} +} +%------------------------------------------------------------------------------ +\routine{SLA\_PLANTE}{\radec\ of Planet from Elements} +{ + \action{Topocentric apparent \radec\ of a Solar-System object whose + heliocentric orbital elements are known.} + \call{CALL sla\_PLANTE (\vtop{ + \hbox{DATE, ELONG, PHI, JFORM, EPOCH, ORBINC, ANODE, PERIH,} + \hbox{AORQ, E, AORL, DM, RA, DEC, R, JSTAT)}}} +} +\args{GIVEN} +{ + \spec{DATE}{D}{MJD of observation (JD$-$2400000.5)} \\ + \spec{ELONG,PHI}{D}{observer's longitude (east +ve) and latitude} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{JFORM}{I}{choice of element set (1-3, see Note~4, below)} \\ + \spec{EPOCH}{D}{epoch of elements ($t_0$ or $T$, TT MJD)} \\ + \spec{ORBINC}{D}{inclination ($i$, radians)} \\ + \spec{ANODE}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH}{D}{longitude or argument of perihelion + ($\varpi$ or $\omega$,} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{AORQ}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E}{D}{eccentricity ($e$)} \\ + \spec{AORL}{D}{mean anomaly or longitude ($M$ or $L$,} \\ + \spec{}{}{\hspace{1.5em} radians, JFORM=1,2 only)} \\ + \spec{DM}{D}{daily motion ($n$, radians, JFORM=1 only)} +} +\args{RETURNED} +{ + \spec{RA,DEC}{D}{topocentric apparent \radec\ (radians)} \\ + \spec{R}{D}{distance from observer (AU)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{2.3em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} $-$1 = illegal JFORM} \\ + \spec{}{}{\hspace{1.5em} $-$2 = illegal E} \\ + \spec{}{}{\hspace{1.5em} $-$3 = illegal AORQ} \\ + \spec{}{}{\hspace{1.5em} $-$4 = illegal DM} \\ + \spec{}{}{\hspace{1.5em} $-$5 = numerical error} +} +\notes +{ + \begin{enumerate} + \item DATE is the instant for which the prediction is + required. It is in the TT timescale (formerly + Ephemeris Time, ET) and is a + Modified Julian Date (JD$-$2400000.5). + \item The longitude and latitude allow correction for geocentric + parallax. This is usually a small effect, but can become + important for Earth-crossing asteroids. Geocentric positions + can be generated by appropriate use of the routines + sla\_EVP and sla\_PLANEL. + \item The elements are with respect to the J2000 ecliptic and equinox. + \item Three different element-format options are available, as + follows. \\ + + JFORM=1, suitable for the major planets: + + \begin{tabbing} + xxx \= xxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> longitude of perihelion $\varpi$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ \\ + \> AORL \> = \> mean longitude $L$ (radians) \\ + \> DM \> = \> daily motion $n$ (radians) + \end{tabbing} + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ + \end{tabbing} + \item Unused elements (DM for JFORM=2, AORL and DM for JFORM=3) are + not accessed. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_PM}{Proper Motion} +{ + \action{Apply corrections for proper motion to a star \radec.} + \call{CALL sla\_PM (R0, D0, PR, PD, PX, RV, EP0, EP1, R1, D1)} +} +\args{GIVEN} +{ + \spec{R0,D0}{D}{\radec\ at epoch EP0 (radians)} \\ + \spec{PR,PD}{D}{proper motions: rate of change of + \radec\ (radians per year)} \\ + \spec{PX}{D}{parallax (arcsec)} \\ + \spec{RV}{D}{radial velocity (km~s$^{-1}$, +ve if receding)} \\ + \spec{EP0}{D}{start epoch in years ({\it e.g.}\ Julian epoch)} \\ + \spec{EP1}{D}{end epoch in years (same system as EP0)} +} +\args{RETURNED} +{ + \spec{R1,D1}{D}{\radec\ at epoch EP1 (radians)} +} +\anote{The $\alpha$ proper motions are $\dot{\alpha}$ rather than + $\dot{\alpha}\cos\delta$, and are in the same coordinate + system as R0,D0.} +\refs +{ + \begin{enumerate} + \item 1984 {\it Astronomical Almanac}, pp B39-B41. + \item Lederle \& Schwan, 1984.\ {\it Astr. Astrophys.}\ {\bf 134}, 1-6. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_POLMO}{Polar Motion} +{ + \action{Polar motion: correct site longitude and latitude for polar + motion and calculate azimuth difference between celestial and + terrestrial poles.} + \call{CALL sla\_POLMO (ELONGM, PHIM, XP, YP, ELONG, PHI, DAZ)} +} +\args{GIVEN} +{ + \spec{ELONGM}{D}{mean longitude of the site (radians, east +ve)} \\ + \spec{PHIM}{D}{mean geodetic latitude of the site (radians)} \\ + \spec{XP}{D}{polar motion $x$-coordinate (radians)} \\ + \spec{YP}{D}{polar motion $y$-coordinate (radians)} +} +\args{RETURNED} +{ + \spec{ELONG}{D}{true longitude of the site (radians, east +ve)} \\ + \spec{PHI}{D}{true geodetic latitude of the site (radians)} \\ + \spec{DAZ}{D}{azimuth correction (terrestrial$-$celestial, radians)} +} +\notes +{ +\begin{enumerate} +\item ``Mean'' longitude and latitude are the (fixed) values for the + site's location with respect to the IERS terrestrial reference + frame; the latitude is geodetic. TAKE CARE WITH THE LONGITUDE + SIGN CONVENTION. The longitudes used by the present routine + are east-positive, in accordance with geographical convention + (and right-handed). In particular, note that the longitudes + returned by the sla\_OBS routine are west-positive, following + astronomical usage, and must be reversed in sign before use in + the present routine. +\item XP and YP are the (changing) coordinates of the Celestial + Ephemeris Pole with respect to the IERS Reference Pole. + XP is positive along the meridian at longitude $0^\circ$, + and YP is positive along the meridian at longitude + $270^\circ$ ({\it i.e.}\ $90^\circ$ west). Values for XP,YP can + be obtained from IERS circulars and equivalent publications; + the maximum amplitude observed so far is about \arcsec{0}{3}. +\item ``True'' longitude and latitude are the (moving) values for + the site's location with respect to the celestial ephemeris + pole and the meridian which corresponds to the Greenwich + apparent sidereal time. The true longitude and latitude + link the terrestrial coordinates with the standard celestial + models (for precession, nutation, sidereal time {\it etc}). +\item The azimuths produced by sla\_AOP and sla\_AOPQK are with + respect to due north as defined by the Celestial Ephemeris + Pole, and can therefore be called ``celestial azimuths''. + However, a telescope fixed to the Earth measures azimuth + essentially with respect to due north as defined by the + IERS Reference Pole, and can therefore be called ``terrestrial + azimuth''. Uncorrected, this would manifest itself as a + changing ``azimuth zero-point error''. The value DAZ is the + correction to be added to a celestial azimuth to produce + a terrestrial azimuth. +\item The present routine is rigorous. For most practical + purposes, the following simplified formulae provide an + adequate approximation: \\[2ex] + \hspace*{1em}\begin{tabular}{lll} + {\tt ELONG} & {\tt =} & + {\tt ELONGM+XP*COS(ELONGM)-YP*SIN(ELONGM)} \\ + {\tt PHI } & {\tt =} & + {\tt PHIM+(XP*SIN(ELONGM)+YP*COS(ELONGM))*TAN(PHIM)} \\ + {\tt DAZ } & {\tt =} & + {\tt -SQRT(XP*XP+YP*YP)*COS(ELONGM-ATAN2(XP,YP))/COS(PHIM)} \\ + \end{tabular} \\[2ex] + An alternative formulation for DAZ is:\\[2ex] + \hspace*{1em}\begin{tabular}{lll} + {\tt X } & {\tt =} & {\tt COS(ELONGM)*COS(PHIM)} \\ + {\tt Y } & {\tt =} & {\tt SIN(ELONGM)*COS(PHIM)} \\ + {\tt DAZ} & {\tt =} & {\tt ATAN2(-X*YP-Y*XP,X*X+Y*Y)} \\ + \end{tabular} +\end{enumerate} +} +\aref{Seidelmann, P.K.\ (ed), 1992. {\it Explanatory + Supplement to the Astronomical Almanac,}\/ ISBN~0-935702-68-7, + sections 3.27, 4.25, 4.52.} +%----------------------------------------------------------------------- +\routine{SLA\_PREBN}{Precession Matrix (FK4)} +{ + \action{Generate the matrix of precession between two epochs, + using the old, pre IAU~1976, Bessel-Newcomb model, in + Andoyer's formulation.} + \call{CALL sla\_PREBN (BEP0, BEP1, RMATP)} +} +\args{GIVEN} +{ + \spec{BEP0}{D}{beginning Besselian epoch} \\ + \spec{BEP1}{D}{ending Besselian epoch} +} +\args{RETURNED} +{ + \spec{RMATP}{D(3,3)}{precession matrix} +} +\anote{The matrix is in the sense: + \begin{verse} + {\bf v}$_{1}$ = {\bf M}$\cdot${\bf v}$_{0}$ + \end{verse} + where {\bf v}$_{1}$ is the star vector relative to the + mean equator and equinox of epoch BEP1, {\bf M} is the + $3\times3$ matrix RMATP and + {\bf v}$_{0}$ is the star vector relative to the + mean equator and equinox of epoch BEP0.} +\aref{Smith {\it et al.}, 1989.\ {\it Astr.J.}\ {\bf 97}, 269.} +%----------------------------------------------------------------------- +\routine{SLA\_PREC}{Precession Matrix (FK5)} +{ + \action{Form the matrix of precession between two epochs (IAU 1976, FK5).} + \call{CALL sla\_PREC (EP0, EP1, RMATP)} +} +\args{GIVEN} +{ + \spec{EP0}{D}{beginning epoch} \\ + \spec{EP1}{D}{ending epoch} +} +\args{RETURNED} +{ + \spec{RMATP}{D(3,3)}{precession matrix} +} +\notes +{ + \begin{enumerate} + \item The epochs are TDB Julian epochs. + \item The matrix is in the sense: + \begin{verse} + {\bf v}$_{1}$ = {\bf M}$\cdot${\bf v}$_{0}$ + \end{verse} + where {\bf v}$_{1}$ is the star vector relative to the + mean equator and equinox of epoch EP1, {\bf M} is the + $3\times3$ matrix RMATP and + {\bf v}$_{0}$ is the star vector relative to the + mean equator and equinox of epoch EP0. + \item Though the matrix method itself is rigorous, the precession + angles are expressed through canonical polynomials which are + valid only for a limited time span. There are also known + errors in the IAU precession rate. The absolute accuracy + of the present formulation is better than \arcsec{0}{1} from + 1960\,AD to 2040\,AD, better than \arcseci{1} from 1640\,AD to 2360\,AD, + and remains below \arcseci{3} for the whole of the period + 500\,BC to 3000\,AD. The errors exceed \arcseci{10} outside the + range 1200\,BC to 3900\,AD, exceed \arcseci{100} outside 4200\,BC to + 5600\,AD and exceed \arcseci{1000} outside 6800\,BC to 8200\,AD. + The SLALIB routine sla\_PRECL implements a more elaborate + model which is suitable for problems spanning several + thousand years. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Lieske, J.H., 1979.\ {\it Astr.Astrophys.}\ {\bf 73}, 282; + equations 6 \& 7, p283. + \item Kaplan, G.H., 1981.\ {\it USNO circular no.\ 163}, pA2. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PRECES}{Precession} +{ + \action{Precession -- either the old ``FK4'' (Bessel-Newcomb, pre~IAU~1976) + or new ``FK5'' (Fricke, post~IAU~1976) as required.} + \call{CALL sla\_PRECES (SYSTEM, EP0, EP1, RA, DC)} +} +\args{GIVEN} +{ + \spec{SYSTEM}{C}{precession to be applied: `FK4' or `FK5'} \\ + \spec{EP0,EP1}{D}{starting and ending epoch} \\ + \spec{RA,DC}{D}{\radec, mean equator \& equinox of epoch EP0} +} +\args{RETURNED} +{ + \spec{RA,DC}{D}{\radec, mean equator \& equinox of epoch EP1} +} +\notes +{ + \begin{enumerate} + \item Lowercase characters in SYSTEM are acceptable. + \item The epochs are Besselian if SYSTEM=`FK4' and Julian if `FK5'. + For example, to precess coordinates in the old system from + equinox 1900.0 to 1950.0 the call would be: + \begin{quote} + {\tt CALL sla\_PRECES ('FK4', 1900D0, 1950D0, RA, DC)} + \end{quote} + \item This routine will {\bf NOT} correctly convert between the old and + the new systems -- for example conversion from B1950 to J2000. + For these purposes see sla\_FK425, sla\_FK524, sla\_FK45Z and + sla\_FK54Z. + \item If an invalid SYSTEM is supplied, values of $-$99D0,$-$99D0 are + returned for both RA and DC. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PRECL}{Precession Matrix (latest)} +{ + \action{Form the matrix of precession between two epochs, using the + model of Simon {\it et al}.\ (1994), which is suitable for long + periods of time.} + \call{CALL sla\_PRECL (EP0, EP1, RMATP)} +} +\args{GIVEN} +{ + \spec{EP0}{D}{beginning epoch} \\ + \spec{EP1}{D}{ending epoch} +} +\args{RETURNED} +{ + \spec{RMATP}{D(3,3)}{precession matrix} +} +\notes +{ + \begin{enumerate} + \item The epochs are TDB Julian epochs. + \item The matrix is in the sense: + \begin{verse} + {\bf v}$_{1}$ = {\bf M}$\cdot${\bf v}$_{0}$ + \end{verse} + where {\bf v}$_{1}$ is the star vector relative to the + mean equator and equinox of epoch EP1, {\bf M} is the + $3\times3$ matrix RMATP and + {\bf v}$_{0}$ is the star vector relative to the + mean equator and equinox of epoch EP0. + \item The absolute accuracy of the model is limited by the + uncertainty in the general precession, about \arcsec{0}{3} per + 1000~years. The remainder of the formulation provides a + precision of 1~milliarcsecond over the interval from 1000\,AD + to 3000\,AD, \arcsec{0}{1} from 1000\,BC to 5000\,AD and + \arcseci{1} from 4000\,BC to 8000\,AD. + \end{enumerate} +} +\aref{Simon, J.L.\ {\it et al}., 1994.\ {\it Astr.Astrophys.}\ {\bf 282}, + 663.} +%----------------------------------------------------------------------- +\routine{SLA\_PRENUT}{Precession/Nutation Matrix} +{ + \action{Form the matrix of precession and nutation (IAU~1976, FK5).} + \call{CALL sla\_PRENUT (EPOCH, DATE, RMATPN)} +} +\args{GIVEN} +{ + \spec{EPOCH}{D}{Julian Epoch for mean coordinates} \\ + \spec{DATE}{D}{Modified Julian Date (JD$-$2400000.5) + for true coordinates} +} +\args{RETURNED} +{ + \spec{RMATPN}{D(3,3)}{combined precession/nutation matrix} +} +\notes +{ + \begin{enumerate} + \item The epoch and date are TDB. + \item The matrix is in the sense: + \begin{verse} + {\bf v}$_{true}$ = {\bf M}$\cdot${\bf v}$_{mean}$ + \end{verse} + where {\bf v}$_{true}$ is the star vector relative to the + true equator and equinox of epoch DATE, {\bf M} is the + $3\times3$ matrix RMATPN and + {\bf v}$_{mean}$ is the star vector relative to the + mean equator and equinox of epoch EPOCH. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_PV2EL}{Orbital Elements from Position/Velocity} +{ + \action{Heliocentric osculating elements obtained from instantaneous + position and velocity.} + \call{CALL sla\_PV2EL (\vtop{ + \hbox{PV, DATE, PMASS, JFORMR, JFORM, EPOCH, ORBINC,} + \hbox{ANODE, PERIH, AORQ, E, AORL, DM, JSTAT)}}} +} +\args{GIVEN} +{ + \spec{PV}{D(6)}{heliocentric \xyzxyzd, equatorial, J2000} \\ + \spec{}{}{\hspace{1.5em} (AU, AU/s; Note~1)} \\ + \spec{DATE}{D}{date (TT Modified Julian Date = JD$-$2400000.5)} \\ + \spec{PMASS}{D}{mass of the planet (Sun = 1; Note~2)} \\ + \spec{JFORMR}{I}{requested element set (1-3; Note~3)} +} +\args{RETURNED} +{ + \spec{JFORM}{I}{element set actually returned (1-3; Note~4)} \\ + \spec{EPOCH}{D}{epoch of elements ($t_0$ or $T$, TT MJD)} \\ + \spec{ORBINC}{D}{inclination ($i$, radians)} \\ + \spec{ANODE}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH}{D}{longitude or argument of perihelion + ($\varpi$ or $\omega$,} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{AORQ}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E}{D}{eccentricity ($e$)} \\ + \spec{AORL}{D}{mean anomaly or longitude + ($M$ or $L$, radians,} \\ + \spec{}{}{\hspace{1.5em} JFORM=1,2 only)} \\ + \spec{DM}{D}{daily motion ($n$, radians, JFORM=1 only)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{2.3em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} $-$1 = illegal PMASS} \\ + \spec{}{}{\hspace{1.5em} $-$2 = illegal JFORMR} \\ + \spec{}{}{\hspace{1.5em} $-$3 = position/velocity out of allowed range} +} +\notes +{ + \begin{enumerate} + \item The PV 6-vector is with respect to the mean equator and equinox of + epoch J2000. The orbital elements produced are with respect to + the J2000 ecliptic and mean equinox. + \item The mass, PMASS, is important only for the larger planets. For + most purposes ({\it e.g.}~asteroids) use 0D0. Values less than zero + are illegal. + \item Three different element-format options are supported, as + follows. \\ + + JFORM=1, suitable for the major planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> longitude of perihelion $\varpi$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean longitude $L$ (radians) \\ + \> DM \> = \> daily motion $n$ (radians) + \end{tabbing} + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e \leq 10 )$ + \end{tabbing} + \item It may not be possible to generate elements in the form + requested through JFORMR. The caller is notified of the form + of elements actually returned by means of the JFORM argument: + + \begin{tabbing} + xx \= xxxxxxxxxx \= xxxxxxxxxxx \= \kill + \> JFORMR \> JFORM \> meaning \\ \\ + \> ~~~~~1 \> ~~~~~1 \> OK: elements are in the requested format \\ + \> ~~~~~1 \> ~~~~~2 \> never happens \\ + \> ~~~~~1 \> ~~~~~3 \> orbit not elliptical \\ + \> ~~~~~2 \> ~~~~~1 \> never happens \\ + \> ~~~~~2 \> ~~~~~2 \> OK: elements are in the requested format \\ + \> ~~~~~2 \> ~~~~~3 \> orbit not elliptical \\ + \> ~~~~~3 \> ~~~~~1 \> never happens \\ + \> ~~~~~3 \> ~~~~~2 \> never happens \\ + \> ~~~~~3 \> ~~~~~3 \> OK: elements are in the requested format + \end{tabbing} + \item The arguments returned for each value of JFORM ({\it cf}\/ Note~5: + JFORM may not be the same as JFORMR) are as follows: + + \begin{tabbing} + xxx \= xxxxxxxxxxxx \= xxxxxx \= xxxxxx \= \kill + \> JFORM \> 1 \> 2 \> 3 \\ \\ + \> EPOCH \> $t_0$ \> $t_0$ \> $T$ \\ + \> ORBINC \> $i$ \> $i$ \> $i$ \\ + \> ANODE \> $\Omega$ \> $\Omega$ \> $\Omega$ \\ + \> PERIH \> $\varpi$ \> $\omega$ \> $\omega$ \\ + \> AORQ \> $a$ \> $a$ \> $q$ \\ + \> E \> $e$ \> $e$ \> $e$ \\ + \> AORL \> $L$ \> $M$ \> - \\ + \> DM \> $n$ \> - \> - + \end{tabbing} + + where: + \begin{tabbing} + xxx \= xxxxxxxx \= xxx \= \kill + \> $t_0$ \> is the epoch of the elements (MJD, TT) \\ + \> $T$ \> is the epoch of perihelion (MJD, TT) \\ + \> $i$ \> is the inclination (radians) \\ + \> $\Omega$ \> is the longitude of the ascending node (radians) \\ + \> $\varpi$ \> is the longitude of perihelion (radians) \\ + \> $\omega$ \> is the argument of perihelion (radians) \\ + \> $a$ \> is the mean distance (AU) \\ + \> $q$ \> is the perihelion distance (AU) \\ + \> $e$ \> is the eccentricity \\ + \> $L$ \> is the longitude (radians, $0-2\pi$) \\ + \> $M$ \> is the mean anomaly (radians, $0-2\pi$) \\ + \> $n$ \> is the daily motion (radians) \\ + \> - \> means no value is set + \end{tabbing} + \item At very small inclinations, the longitude of the ascending node + ANODE becomes indeterminate and under some circumstances may be + set arbitrarily to zero. Similarly, if the orbit is close to + circular, the true anomaly becomes indeterminate and under some + circumstances may be set arbitrarily to zero. In such cases, + the other elements are automatically adjusted to compensate, + and so the elements remain a valid description of the orbit. + \end{enumerate} +} +\aref{Sterne, Theodore E., {\it An Introduction to Celestial Mechanics,}\/ + Interscience Publishers, 1960.} +%----------------------------------------------------------------------- +\routine{SLA\_PV2UE}{Position/Velocity to Universal Elements} +{ + \action{Construct a universal element set based on an instantaneous + position and velocity.} + \call{CALL sla\_PV2UE (PV, DATE, PMASS, U, JSTAT)} +} +\args{GIVEN} +{ + \spec{PV}{D(6)}{heliocentric \xyzxyzd, equatorial, J2000} \\ + \spec{}{}{\hspace{1.5em} (AU, AU/s; Note~1)} \\ + \spec{DATE}{D}{date (TT Modified Julian Date = JD$-$2400000.5)} \\ + \spec{PMASS}{D}{mass of the planet (Sun = 1; Note~2)} +} +\args{RETURNED} +{ + \spec{U}{D(13)}{universal orbital elements (Note~3)} \\ + \specel {(1)} {combined mass ($M+m$)} \\ + \specel {(2)} {total energy of the orbit ($\alpha$)} \\ + \specel {(3)} {reference (osculating) epoch ($t_0$)} \\ + \specel {(4-6)} {position at reference epoch (${\rm \bf r}_0$)} \\ + \specel {(7-9)} {velocity at reference epoch (${\rm \bf v}_0$)} \\ + \specel {(10)} {heliocentric distance at reference epoch} \\ + \specel {(11)} {${\rm \bf r}_0.{\rm \bf v}_0$} \\ + \specel {(12)} {date ($t$)} \\ + \specel {(13)} {universal eccentric anomaly ($\psi$) of date, approx} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{1.95em} 0 = OK} \\ + \spec{}{}{\hspace{1.2em} $-$1 = illegal PMASS} \\ + \spec{}{}{\hspace{1.2em} $-$2 = too close to Sun} \\ + \spec{}{}{\hspace{1.2em} $-$3 = too slow} +} +\notes +{ + \begin{enumerate} + \item The PV 6-vector can be with respect to any chosen inertial frame, + and the resulting universal-element set will be with respect to + the same frame. A common choice will be mean equator and ecliptic + of epoch J2000. + \item The mass, PMASS, is important only for the larger planets. For + most purposes ({\it e.g.}~asteroids) use 0D0. Values less than zero + are illegal. + \item The ``universal'' elements are those which define the orbit for the + purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i)~$\alpha$, which is proportional to the total energy of the + orbit, (ii)~the heliocentric distance at epoch, + (iii)~the outwards component of the velocity at the given epoch, + (iv)~an estimate of $\psi$, the ``universal eccentric anomaly'' at a + given date and (v)~that date. + \end{enumerate} +} +\aref{Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983.} +%----------------------------------------------------------------------- +\routine{SLA\_PVOBS}{Observatory Position \& Velocity} +{ + \action{Position and velocity of an observing station.} + \call{CALL sla\_PVOBS (P, H, STL, PV)} +} +\args{GIVEN} +{ + \spec{P}{D}{latitude (geodetic, radians)} \\ + \spec{H}{D}{height above reference spheroid (geodetic, metres)} \\ + \spec{STL}{D}{local apparent sidereal time (radians)} +} +\args{RETURNED} +{ + \spec{PV}{D(6)}{\xyzxyzd\ (AU, AU~s$^{-1}$, true equator and equinox + of date)} +} +\anote{IAU 1976 constants are used.} +%----------------------------------------------------------------------- +\routine{SLA\_PXY}{Apply Linear Model} +{ + \action{Given arrays of {\it expected}\/ and {\it measured}\, + \xy\ coordinates, and a + linear model relating them (as produced by sla\_FITXY), compute + the array of {\it predicted}\/ coordinates and the RMS residuals.} + \call{CALL sla\_PXY (NP,XYE,XYM,COEFFS,XYP,XRMS,YRMS,RRMS)} +} +\args{GIVEN} +{ + \spec{NP}{I}{number of samples} \\ + \spec{XYE}{D(2,NP)}{expected \xy\ for each sample} \\ + \spec{XYM}{D(2,NP)}{measured \xy\ for each sample} \\ + \spec{COEFFS}{D(6)}{coefficients of model (see below)} +} +\args{RETURNED} +{ + \spec{XYP}{D(2,NP)}{predicted \xy\ for each sample} \\ + \spec{XRMS}{D}{RMS in X} \\ + \spec{YRMS}{D}{RMS in Y} \\ + \spec{RRMS}{D }{total RMS (vector sum of XRMS and YRMS)} +} +\notes +{ + \begin{enumerate} + \item The model is supplied in the array COEFFS. Naming the + six elements of COEFFS $a,b,c,d,e$ \& $f$, + the model transforms {\it measured}\/ coordinates + $[x_{m},y_{m}\,]$ into {\it predicted}\/ coordinates + $[x_{p},y_{p}\,]$ as follows: + \begin{verse} + $x_{p} = a + bx_{m} + cy_{m}$ \\ + $y_{p} = d + ex_{m} + fy_{m}$ + \end{verse} + \item The residuals are $(x_{p}-x_{e})$ and $(y_{p}-y_{e})$. + \item If NP is less than or equal to zero, no coordinates are + transformed, and the RMS residuals are all zero. + \item See also sla\_FITXY, sla\_INVF, sla\_XY2XY, sla\_DCMPF + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_RANDOM}{Random Number} +{ + \action{Generate pseudo-random real number in the range $0 \leq x < 1$.} + \call{R~=~sla\_RANDOM (SEED)} +} +\args{GIVEN} +{ + \spec{SEED}{R}{an arbitrary real number} +} +\args{RETURNED} +{ + \spec{SEED}{R}{a new arbitrary value} \\ + \spec{sla\_RANDOM}{R}{Pseudo-random real number $0 \leq x < 1$.} +} +\anote{The implementation is machine-dependent.} +%----------------------------------------------------------------------- +\routine{SLA\_RANGE}{Put Angle into Range $\pm\pi$} +{ + \action{Normalize an angle into the range $\pm\pi$ (single precision).} + \call{R~=~sla\_RANGE (ANGLE)} +} +\args{GIVEN} +{ + \spec{ANGLE}{R}{angle in radians} +} +\args{RETURNED} +{ + \spec{sla\_RANGE}{R}{ANGLE expressed in the range $\pm\pi$.} +} +%----------------------------------------------------------------------- +\routine{SLA\_RANORM}{Put Angle into Range $0\!-\!2\pi$} +{ + \action{Normalize an angle into the range $0\!-\!2\pi$ (single precision).} + \call{R~=~sla\_RANORM (ANGLE)} +} +\args{GIVEN} +{ + \spec{ANGLE}{R}{angle in radians} +} +\args{RETURNED} +{ + \spec{sla\_RANORM}{R}{ANGLE expressed in the range $0\!-\!2\pi$} +} +%----------------------------------------------------------------------- +\routine{SLA\_RCC}{Barycentric Coordinate Time} +{ + \call{D~=~sla\_RCC (TDB, UT1, WL, U, V)} + \action{The relativistic clock correction TDB$-$TT, the + difference between {\it proper time}\, + on Earth and {\it coordinate time}\/ in the solar system barycentric + space-time frame of reference. The proper time is TT; the + coordinate time is {\it an implementation}\/ of TDB.} +} +\args{GIVEN} +{ + \spec{TDB}{D}{coordinate time (MJD: JD$-$2400000.5)} \\ + \spec{UT1}{D}{universal time (fraction of one day)} \\ + \spec{WL}{D}{clock longitude (radians west)} \\ + \spec{U}{D}{clock distance from Earth spin axis (km)} \\ + \spec{V}{D}{clock distance north of Earth equatorial plane (km)} +} +\args{RETURNED} +{ + \spec{sla\_RCC}{D}{TDB$-$TT (sec)} +} +\notes +{ + \begin{enumerate} + \item TDB may be considered to + be the coordinate time in the solar system barycentre frame of + reference, and TT is the proper time given by clocks at mean sea + level on the Earth. + \item The result has a main (annual) sinusoidal term of amplitude + approximately 1.66ms, plus planetary terms up to about + 20$\mu$s, and lunar and diurnal terms up to 2$\mu$s. The + variation arises from the transverse Doppler effect and the + gravitational red-shift as the observer varies in speed and + moves through different gravitational potentials. + \item The argument TDB is, strictly, the barycentric coordinate time; + however, the terrestrial proper time (TT) can in practice be used. + \item The geocentric model is that of Fairhead \& Bretagnon (1990), + in its full + form. It was supplied by Fairhead (private communication) + as a Fortran subroutine. A number of coding changes were made to + this subroutine in order + match the calling sequence of previous versions of the present + routine, to comply with Starlink programming standards and to + avoid compilation problems on certain machines. On the supported + computer types, + the numerical results are essentially unaffected by the + changes. The topocentric model is from Moyer (1981) and Murray (1983). + During the interval 1950-2050, the absolute accuracy of the + geocentric model is better than $\pm3$~nanoseconds + relative to direct numerical integrations using the JPL DE200/LE200 + solar system ephemeris. + \item The IAU definition of TDB is that it must differ from TT only by + periodic terms. Though practical, this is an imprecise definition + which ignores the existence of very long-period and secular effects + in the dynamics of the solar system. As a consequence, different + implementations of TDB will, in general, differ in zero-point and + will drift linearly relative to one other. + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Fairhead, L.\ \& + Bretagnon, P., 1990.\ {\it Astr.Astrophys.}\ {\bf 229}, 240-247. + \item Moyer, T.D., 1981.\ {\it Cel.Mech.}\ {\bf 23}, 33. + \item Murray, C.A., 1983,\ {\it Vectorial Astrometry}, Adam Hilger. + \end{enumerate} +} +%------------------------------------------------------------------------------ +\routine{SLA\_RDPLAN}{Apparent \radec\ of Planet} +{ + \action{Approximate topocentric apparent \radec\ and angular + size of a planet.} + \call{CALL sla\_RDPLAN (DATE, NP, ELONG, PHI, RA, DEC, DIAM)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{MJD of observation (JD$-$2400000.5)} \\ + \spec{NP}{I}{planet:} \\ + \spec{}{}{\hspace{1.5em} 1\,=\,Mercury} \\ + \spec{}{}{\hspace{1.5em} 2\,=\,Venus} \\ + \spec{}{}{\hspace{1.5em} 3\,=\,Moon} \\ + \spec{}{}{\hspace{1.5em} 4\,=\,Mars} \\ + \spec{}{}{\hspace{1.5em} 5\,=\,Jupiter} \\ + \spec{}{}{\hspace{1.5em} 6\,=\,Saturn} \\ + \spec{}{}{\hspace{1.5em} 7\,=\,Uranus} \\ + \spec{}{}{\hspace{1.5em} 8\,=\,Neptune} \\ + \spec{}{}{\hspace{1.5em} 9\,=\,Pluto} \\ + \spec{}{}{\hspace{0.44em} else\,=\,Sun} \\ + \spec{ELONG,PHI}{D}{observer's longitude (east +ve) and latitude + (radians)} +} +\args{RETURNED} +{ + \spec{RA,DEC}{D}{topocentric apparent \radec\ (radians)} \\ + \spec{DIAM}{D}{angular diameter (equatorial, radians)} +} +\notes +{ + \begin{enumerate} + \item The date is in a dynamical timescale (TDB, formerly ET) + and is in the form of a Modified + Julian Date (JD$-$2400000.5). For all practical purposes, TT can + be used instead of TDB, and for many applications UT will do + (except for the Moon). + \item The longitude and latitude allow correction for geocentric + parallax. This is a major effect for the Moon, but in the + context of the limited accuracy of the present routine its + effect on planetary positions is small (negligible for the + outer planets). Geocentric positions can be generated by + appropriate use of the routines sla\_DMOON and sla\_PLANET. + \item The direction accuracy (arcsec, 1000-3000\,AD) is of order: + \begin{tabbing} + xxxxxxx \= xxxxxxxxxxxxxxxxxx \= \kill + \> Sun \> \hspace{0.5em}5 \\ + \> Mercury \> \hspace{0.5em}2 \\ + \> Venus \> 10 \\ + \> Moon \> 30 \\ + \> Mars \> 50 \\ + \> Jupiter \> 90 \\ + \> Saturn \> 90 \\ + \> Uranus \> 90 \\ + \> Neptune \> 10 \\ + \> Pluto \> \hspace{0.5em}1~~~(1885-2099\,AD only) + \end{tabbing} + The angular diameter accuracy is about 0.4\% for the Moon, + and 0.01\% or better for the Sun and planets. + For more information on accuracy, + refer to the routines sla\_PLANET and sla\_DMOON, + which the present routine uses. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_REFCO}{Refraction Constants} +{ + \action{Determine the constants $a$ and $b$ in the + atmospheric refraction model + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$, + where $\zeta$ is the {\it observed}\/ zenith distance + ({\it i.e.}\ affected by refraction) and $\Delta \zeta$ is + what to add to $\zeta$ to give the {\it topocentric}\, + ({\it i.e.\ in vacuo}) zenith distance.} + \call{CALL sla\_REFCO (HM, TDK, PMB, RH, WL, PHI, TLR, EPS, REFA, REFB)} +} +\args{GIVEN} +{ + \spec{HM}{D}{height of the observer above sea level (metre)} \\ + \spec{TDK}{D}{ambient temperature at the observer (degrees K)} \\ + \spec{PMB}{D}{pressure at the observer (mB)} \\ + \spec{RH}{D}{relative humidity at the observer (range 0\,--\,1)} \\ + \spec{WL}{D}{effective wavelength of the source ($\mu{\rm m}$)} \\ + \spec{PHI}{D}{latitude of the observer (radian, astronomical)} \\ + \spec{TLR}{D}{temperature lapse rate in the troposphere + (degrees K per metre)} \\ + \spec{EPS}{D}{precision required to terminate iteration (radian)} +} +\args{RETURNED} +{ + \spec{REFA}{D}{$\tan \zeta$ coefficient (radians)} \\ + \spec{REFB}{D}{$\tan^{3} \zeta$ coefficient (radians)} +} +\notes +{ + \begin{enumerate} + \item Suggested values for the TLR and EPS arguments are 0.0065D0 and + 1D$-$8 respectively. + \item The radio refraction is chosen by specifying WL $>100$~$\mu{\rm m}$. + \item The routine is a slower but more accurate alternative to the + sla\_REFCOQ routine. The constants it produces give perfect + agreement with sla\_REFRO at zenith distances + $\tan^{-1} 1$ ($45^\circ$) and $\tan^{-1} 4$ ($\sim 76^\circ$). + At other zenith distances, the model achieves: + \arcsec{0}{5} accuracy for $\zeta<80^{\circ}$, + \arcsec{0}{01} accuracy for $\zeta<60^{\circ}$, and + \arcsec{0}{001} accuracy for $\zeta<45^{\circ}$. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_REFCOQ}{Refraction Constants (fast)} +{ + \action{Determine the constants $a$ and $b$ in the + atmospheric refraction model + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$, + where $\zeta$ is the {\it observed}\/ zenith distance + ({\it i.e.}\ affected by refraction) and $\Delta \zeta$ is + what to add to $\zeta$ to give the {\it topocentric}\, + ({\it i.e.\ in vacuo}) zenith distance. (This is a fast + alternative to the sla\_REFCO routine -- see notes.)} + \call{CALL sla\_REFCOQ (TDK, PMB, RH, WL, REFA, REFB)} +} +\args{GIVEN} +{ + \spec{TDK}{D}{ambient temperature at the observer (degrees K)} \\ + \spec{PMB}{D}{pressure at the observer (mB)} \\ + \spec{RH}{D}{relative humidity at the observer (range 0\,--\,1)} \\ + \spec{WL}{D}{effective wavelength of the source ($\mu{\rm m}$)} +} +\args{RETURNED} +{ + \spec{REFA}{D}{$\tan \zeta$ coefficient (radians)} \\ + \spec{REFB}{D}{$\tan^{3} \zeta$ coefficient (radians)} +} +\notes +{ + \begin{enumerate} + \item The radio refraction is chosen by specifying WL $>100$~$\mu{\rm m}$. + \item The model is an approximation, for moderate zenith distances, + to the predictions of the sla\_REFRO routine. The approximation + is maintained across a range of conditions, and applies to + both optical/IR and radio. + \item The algorithm is a fast alternative to the sla\_REFCO routine. + The latter calls the sla\_REFRO routine itself: this involves + integrations through a model atmosphere, and is costly in + processor time. However, the model which is produced is precisely + correct for two zenith distances ($45^\circ$ and $\sim\!76^\circ$) + and at other zenith distances is limited in accuracy only by the + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ formulation + itself. The present routine is not as accurate, though it + satisfies most practical requirements. + \item The model omits the effects of (i)~height above sea level (apart + from the reduced pressure itself), (ii)~latitude ({\it i.e.}\ the + flattening of the Earth) and (iii)~variations in tropospheric + lapse rate. + \item The model has been tested using the following range of conditions: + \begin{itemize} + \item [$\cdot$] lapse rates 0.0055, 0.0065, 0.0075~degrees K per metre + \item [$\cdot$] latitudes $0^\circ$, $25^\circ$, $50^\circ$, $75^\circ$ + \item [$\cdot$] heights 0, 2500, 5000 metres above sea level + \item [$\cdot$] pressures mean for height $-10$\% to $+5$\% in steps of $5$\% + \item [$\cdot$] temperatures $-10^\circ$ to $+20^\circ$ with respect to + $280^\circ$K at sea level + \item [$\cdot$] relative humidity 0, 0.5, 1 + \item [$\cdot$] wavelength 0.4, 0.6, \ldots\ $2\mu{\rm m}$, + radio + \item [$\cdot$] zenith distances $15^\circ$, $45^\circ$, $75^\circ$ + \end{itemize} + For the above conditions, the comparison with sla\_REFRO + was as follows: + + \vspace{2ex} + + ~~~~~~~~~~ + \begin{tabular}{|r|r|r|} \hline + & {\it worst} & {\it RMS} \\ \hline + optical/IR & 62 & 8 \\ + radio & 319 & 49 \\ \hline + & mas & mas \\ \hline + \end{tabular} + + \vspace{3ex} + + For this particular set of conditions: + \begin{itemize} + \item [$\cdot$] lapse rate $6.5^\circ K km^{-1}$ + \item [$\cdot$] latitude $50^\circ$ + \item [$\cdot$] sea level + \item [$\cdot$] pressure 1005\,mB + \item [$\cdot$] temperature $7^\circ$C + \item [$\cdot$] humidity 80\% + \item [$\cdot$] wavelength 5740\,\.{A} + \end{itemize} + the results were as follows: + + \vspace{2ex} + + ~~~~~~~~~~ + \begin{tabular}{|r|r|r|r|} \hline + \multicolumn{1}{|c}{$\zeta$} & + \multicolumn{1}{|c}{sla\_REFRO} & + \multicolumn{1}{|c}{sla\_REFCOQ} & + \multicolumn{1}{|c|}{Saastamoinen} \\ \hline + 10 & 10.27 & 10.27 & 10.27 \\ + 20 & 21.19 & 21.20 & 21.19 \\ + 30 & 33.61 & 33.61 & 33.60 \\ + 40 & 48.82 & 48.83 & 48.81 \\ + 45 & 58.16 & 58.18 & 58.16 \\ + 50 & 69.28 & 69.30 & 69.27 \\ + 55 & 82.97 & 82.99 & 82.95 \\ + 60 & 100.51 & 100.54 & 100.50 \\ + 65 & 124.23 & 124.26 & 124.20 \\ + 70 & 158.63 & 158.68 & 158.61 \\ + 72 & 177.32 & 177.37 & 177.31 \\ + 74 & 200.35 & 200.38 & 200.32 \\ + 76 & 229.45 & 229.43 & 229.42 \\ + 78 & 267.44 & 267.29 & 267.41 \\ + 80 & 319.13 & 318.55 & 319.10 \\ \hline + deg & arcsec & arcsec & arcsec \\ \hline + \end{tabular} + + \vspace{3ex} + + The values for Saastamoinen's formula (which includes terms + up to $\tan^5$) are taken from Hohenkerk and Sinclair (1985). + + The results from the much slower but more accurate sla\_REFCO + routine have not been included in the tabulation as they are + identical to those in the sla\_REFRO column to the \arcsec{0}{01} + resolution used. + \item Outlandish input parameters are silently limited + to mathematically safe values. Zero pressure is permissible, + and causes zeroes to be returned. + \item The algorithm draws on several sources, as follows: + \begin{itemize} + \item The formula for the saturation vapour pressure of water as + a function of temperature and temperature is taken from + expressions A4.5-A4.7 of Gill (1982). + \item The formula for the water vapour pressure, given the + saturation pressure and the relative humidity is from + Crane (1976), expression 2.5.5. + \item The refractivity of air is a function of temperature, + total pressure, water-vapour pressure and, in the case + of optical/IR but not radio, wavelength. The formulae + for the two cases are developed from the Essen and Froome + expressions adopted in Resolution 1 of the 12th International + Geodesy Association General Assembly (1963). + \end{itemize} + The above three items are as used in the sla\_REFRO routine. + \begin{itemize} + \item The formula for $\beta~(=H_0/r_0)$ is + an adaption of expression 9 from Stone (1996). The + adaptations, arrived at empirically, consist of (i)~a + small adjustment to the coefficient and (ii)~a humidity + term for the radio case only. + \item The formulae for the refraction constants as a function of + $n-1$ and $\beta$ are from Green (1987), expression 4.31. + \end{itemize} + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Crane, R.K., Meeks, M.L.\ (ed), ``Refraction Effects in + the Neutral Atmosphere'', + {\it Methods of Experimental Physics: Astrophysics 12B,}\/ + Academic Press, 1976. + \item Gill, Adrian E., {\it Atmosphere-Ocean Dynamics,}\/ + Academic Press, 1982. + \item Hohenkerk, C.Y., \& Sinclair, A.T., NAO Technical Note + No.~63, 1985. + \item International Geodesy Association General Assembly, Bulletin + G\'{e}od\'{e}sique {\bf 70} p390, 1963. + \item Stone, Ronald C., P.A.S.P.~{\bf 108} 1051-1058, 1996. + \item Green, R.M., {\it Spherical Astronomy,}\/ Cambridge + University Press, 1987. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_REFRO}{Refraction} +{ + \action{Atmospheric refraction, for radio or optical/IR wavelengths.} + \call{CALL sla\_REFRO (ZOBS, HM, TDK, PMB, RH, WL, PHI, TLR, EPS, REF)} +} +\args{GIVEN} +{ + \spec{ZOBS}{D}{observed zenith distance of the source (radians)} \\ + \spec{HM}{D}{height of the observer above sea level (metre)} \\ + \spec{TDK}{D}{ambient temperature at the observer (degrees K)} \\ + \spec{PMB}{D}{pressure at the observer (mB)} \\ + \spec{RH}{D}{relative humidity at the observer (range 0\,--\,1)} \\ + \spec{WL}{D}{effective wavelength of the source ($\mu{\rm m}$)} \\ + \spec{PHI}{D}{latitude of the observer (radian, astronomical)} \\ + \spec{TLR}{D}{temperature lapse rate in the troposphere + (degrees K per metre)} \\ + \spec{EPS}{D}{precision required to terminate iteration (radian)} +} +\args{RETURNED} +{ + \spec{REF}{D}{refraction: {\it in vacuo}\/ ZD minus observed ZD (radians)} +} +\notes +{ + \begin{enumerate} + \item A suggested value for the TLR argument is 0.0065D0. The + refraction is significantly affected by TLR, and if studies + of the local atmosphere have been carried out a better TLR + value may be available. + \item A suggested value for the EPS argument is 1D$-$8. The result is + usually at least two orders of magnitude more computationally + precise than the supplied EPS value. + \item The routine computes the refraction for zenith distances up + to and a little beyond $90^\circ$ using the method of Hohenkerk + \& Sinclair (NAO Technical Notes 59 and 63, subsequently adopted + in the {\it Explanatory Supplement to the Astronomical Almanac,}\/ + 1992 -- see section 3.281). + \item The code is based on the AREF optical/IR refraction subroutine + of C.\,Hohenkerk (HMNAO, September 1984), with extensions to + support the radio case. The modifications to the original HMNAO + optical/IR refraction code which affect the results are: + \begin{itemize} + \item Murray's values for the gas constants have been used + ({\it Vectorial Astrometry,}\/ Adam Hilger, 1983). + \item A better model for $P_s(T)$ has been adopted (taken from + Gill, {\it Atmosphere-Ocean Dynamics,}\/ Academic Press, 1982). + \item More accurate expressions for $Pw_o$ have been adopted + (again from Gill 1982). + \item Provision for radio wavelengths has been added using + expressions devised by A.\,T.\,Sinclair, RGO (private + communication 1989), based on the Essen \& Froome + refractivity formula adopted in Resolution~1 of the + 12th International Geodesy Association General Assembly + (Bulletin G\'{e}od\'{e}sique {\bf 70} p390, 1963). + \end{itemize} + None of the changes significantly affects the optical/IR results + with respect to the algorithm given in the 1992 {\it Explanatory + Supplement.}\/ For example, at $70^\circ$ zenith distance the present + routine agrees with the ES algorithm to better than \arcsec{0}{05} + for any reasonable combination of parameters. However, the + improved water-vapour expressions do make a significant difference + in the radio band, at $70^\circ$ zenith distance reaching almost + \arcseci{4} for a hot, humid, low-altitude site during a period of + low pressure. + \item The radio refraction is chosen by specifying WL $>100$~$\mu{\rm m}$. + Because the algorithm takes no account of the ionosphere, the + accuracy deteriorates at low frequencies, below about 30\,MHz. + \item Before use, the value of ZOBS is expressed in the range $\pm\pi$. + If this ranged ZOBS is negative, the result REF is computed from its + absolute value before being made negative to match. In addition, if + it has an absolute value greater than $93^\circ$, a fixed REF value + equal to the result for ZOBS~$=93^\circ$ is returned, appropriately + signed. + \item As in the original Hohenkerk and Sinclair algorithm, fixed values + of the water vapour polytrope exponent, the height of the + tropopause, and the height at which refraction is negligible are + used. + \item The radio refraction has been tested against work done by + Iain~Coulson, JACH, (private communication 1995) for the + James Clerk Maxwell Telescope, Mauna Kea. For typical conditions, + agreement at the \arcsec{0}{1} level is achieved for moderate ZD, + worsening to perhaps \arcsec{0}{5}\,--\,\arcsec{1}{0} at ZD $80^\circ$. + At hot and humid sea-level sites the accuracy will not be as good. + \item It should be noted that the relative humidity RH is formally + defined in terms of ``mixing ratio'' rather than pressures or + densities as is often stated. It is the mass of water per unit + mass of dry air divided by that for saturated air at the same + temperature and pressure (see Gill 1982). The familiar + $\nu=p_w/p_s$ or $\nu=\rho_w/\rho_s$ expressions can differ from + the formal definition by several percent, significant in the + radio case. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_REFV}{Apply Refraction to Vector} +{ + \action{Adjust an unrefracted Cartesian vector to include the effect of + atmospheric refraction, using the simple + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ model.} + \call{CALL sla\_REFV (VU, REFA, REFB, VR)} +} +\args{GIVEN} +{ + \spec{VU}{D}{unrefracted position of the source (\azel\ 3-vector)} \\ + \spec{REFA}{D}{$\tan \zeta$ coefficient (radians)} \\ + \spec{REFB}{D}{$\tan^{3} \zeta$ coefficient (radians)} +} +\args{RETURNED} +{ + \spec{VR}{D}{refracted position of the source (\azel\ 3-vector)} +} +\notes +{ + \begin{enumerate} + \item This routine applies the adjustment for refraction in the + opposite sense to the usual one -- it takes an unrefracted + ({\it in vacuo}\/) position and produces an observed (refracted) + position, whereas the + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ + model strictly + applies to the case where an observed position is to have the + refraction removed. The unrefracted to refracted case is + harder, and requires an inverted form of the text-book + refraction models; the algorithm used here is equivalent to + one iteration of the Newton-Raphson method applied to the + above formula. + \item Though optimized for speed rather than precision, the present + routine achieves consistency with the refracted-to-unrefracted + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ + model at better than 1~microarcsecond within + $30^\circ$ of the zenith and remains within 1~milliarcsecond to + $\zeta=70^\circ$. The inherent accuracy of the model is, of + course, far worse than this -- see the documentation for sla\_REFCO + for more information. + \item At low elevations (below about $3^\circ$) the refraction + correction is held back to prevent arithmetic problems and + wildly wrong results. Over a wide range of observer heights + and corresponding temperatures and pressures, the following + levels of accuracy are achieved, relative to numerical + integration through a model atmosphere: + + \begin{center} + \begin{tabular}{ccl} + $\zeta_{obs}$ & {\it error} \\ \\ + $80^\circ$ & \arcsec{0}{4} \\ + $81^\circ$ & \arcsec{0}{8} \\ + $82^\circ$ & \arcsec{1}{6} \\ + $83^\circ$ & \arcseci{3} \\ + $84^\circ$ & \arcseci{7} \\ + $85^\circ$ & \arcseci{17} \\ + $86^\circ$ & \arcseci{45} \\ + $87^\circ$ & \arcseci{150} \\ + $88^\circ$ & \arcseci{340} \\ + $89^\circ$ & \arcseci{620} \\ + $90^\circ$ & \arcseci{1100} \\ + $91^\circ$ & \arcseci{1900} & $<$ high-altitude \\ + $92^\circ$ & \arcseci{3200} & $<$ sites only \\ + \end{tabular} + \end{center} + \item See also the routine sla\_REFZ, which performs the adjustment to + the zenith distance rather than in \xyz . + The present routine is faster than sla\_REFZ and, + except very low down, + is equally accurate for all practical purposes. However, beyond + about $\zeta=84^\circ$ sla\_REFZ should be used, and for the utmost + accuracy iterative use of sla\_REFRO should be considered. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_REFZ}{Apply Refraction to ZD} +{ + \action{Adjust an unrefracted zenith distance to include the effect of + atmospheric refraction, using the simple + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ model.} + \call{CALL sla\_REFZ (ZU, REFA, REFB, ZR)} +} +\args{GIVEN} +{ + \spec{ZU}{D}{unrefracted zenith distance of the source (radians)} \\ + \spec{REFA}{D}{$\tan \zeta$ coefficient (radians)} \\ + \spec{REFB}{D}{$\tan^{3} \zeta$ coefficient (radians)} +} +\args{RETURNED} +{ + \spec{ZR}{D}{refracted zenith distance (radians)} +} +\notes +{ + \begin{enumerate} + \item This routine applies the adjustment for refraction in the + opposite sense to the usual one -- it takes an unrefracted + ({\it in vacuo}\/) position and produces an observed (refracted) + position, whereas the + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ + model strictly + applies to the case where an observed position is to have the + refraction removed. The unrefracted to refracted case is + harder, and requires an inverted form of the text-book + refraction models; the formula used here is based on the + Newton-Raphson method. For the utmost numerical consistency + with the refracted to unrefracted model, two iterations are + carried out, achieving agreement at the $10^{-11}$~arcsecond level + for $\zeta=80^\circ$. The inherent accuracy of the model + is, of course, far worse than this -- see the documentation for + sla\_REFCO for more information. + \item At $\zeta=83^\circ$, the rapidly-worsening + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ + model is abandoned and an empirical formula takes over: + + \[\Delta \zeta = F \left( + \frac{0^\circ\hspace{-0.37em}.\hspace{0.02em}55445 + - 0^\circ\hspace{-0.37em}.\hspace{0.02em}01133 E + + 0^\circ\hspace{-0.37em}.\hspace{0.02em}00202 E^2} + {1 + 0.28385 E +0.02390 E^2} \right) \] + where $E=90^\circ-\zeta_{true}$ + and $F$ is a factor chosen to meet the + $\Delta \zeta = a \tan \zeta + b \tan^{3} \zeta$ + formula at $\zeta=83^\circ$. Over a + wide range of observer heights and corresponding temperatures and + pressures, the following levels of accuracy are achieved, + relative to numerical integration through a model atmosphere: + + \begin{center} + \begin{tabular}{ccl} + $\zeta_{obs}$ & {\it error} \\ \\ + $80^\circ$ & \arcsec{0}{4} \\ + $81^\circ$ & \arcsec{0}{8} \\ + $82^\circ$ & \arcsec{1}{5} \\ + $83^\circ$ & \arcsec{3}{2} \\ + $84^\circ$ & \arcsec{4}{9} \\ + $85^\circ$ & \arcsec{5}{8} \\ + $86^\circ$ & \arcsec{6}{1} \\ + $87^\circ$ & \arcsec{7}{1} \\ + $88^\circ$ & \arcseci{11} \\ + $89^\circ$ & \arcseci{21} \\ + $90^\circ$ & \arcseci{43} \\ + $91^\circ$ & \arcseci{92} & $<$ high-altitude \\ + $92^\circ$ & \arcseci{220} & $<$ sites only \\ + \end{tabular} + \end{center} + \item See also the routine sla\_REFV, which performs the adjustment in + \xyz , and with the emphasis on speed rather than numerical accuracy. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_RVEROT}{RV Corrn to Earth Centre} +{ + \action{Velocity component in a given direction due to Earth rotation.} + \call{R~=~sla\_RVEROT (PHI, RA, DA, ST)} +} +\args{GIVEN} +{ + \spec{PHI}{R}{geodetic latitude of observing station (radians)} \\ + \spec{RA,DA}{R}{apparent \radec\ (radians)} \\ + \spec{ST}{R}{local apparent sidereal time (radians)} +} +\args{RETURNED} +{ + \spec{sla\_RVEROT}{R}{Component of Earth rotation in + direction RA,DA (km~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item Sign convention: the result is positive when the observatory + is receding from the given point on the sky. + \item Accuracy: the simple algorithm used assumes a spherical Earth and + an observing station at sea level; for actual observing + sites, the error is unlikely to be greater than 0.0005~km~s$^{-1}$. + For applications requiring greater precision, use the routine + sla\_PVOBS. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_RVGALC}{RV Corrn to Galactic Centre} +{ + \action{Velocity component in a given direction due to the rotation + of the Galaxy.} + \call{R~=~sla\_RVGALC (R2000, D2000)} +} +\args{GIVEN} +{ + \spec{R2000,D2000}{R}{J2000.0 mean \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{sla\_RVGALC}{R}{Component of dynamical LSR motion in direction + R2000,D2000 (km~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item Sign convention: the result is positive when the LSR + is receding from the given point on the sky. + \item The Local Standard of Rest used here is a point in the + vicinity of the Sun which is in a circular orbit around + the Galactic centre. Sometimes called the {\it dynamical}\/ LSR, + it is not to be confused with a {\it kinematical}\/ LSR, which + is the mean standard of rest of star catalogues or stellar + populations. + \item The dynamical LSR velocity due to Galactic rotation is assumed to + be 220~km~s$^{-1}$ towards $l^{I\!I}=90^{\circ}$, + $b^{I\!I}=0$. + \end{enumerate} +} +\aref{Kerr \& Lynden-Bell (1986), MNRAS, 221, p1023.} +%----------------------------------------------------------------------- +\routine{SLA\_RVLG}{RV Corrn to Local Group} +{ + \action{Velocity component in a given direction due to the combination + of the rotation of the Galaxy and the motion of the Galaxy + relative to the mean motion of the local group.} + \call{R~=~sla\_RVLG (R2000, D2000)} +} +\args{GIVEN} +{ + \spec{R2000,D2000}{R}{J2000.0 mean \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{sla\_RVLG}{R}{Component of {\bf solar} ({\it n.b.}) + motion in direction R2000,D2000 (km~s$^{-1}$)} +} +\anote{Sign convention: the result is positive when + the Sun is receding from the given point on the sky.} +\aref{{\it IAU Trans.}\ 1976.\ {\bf 16B}, p201.} +%----------------------------------------------------------------------- +\routine{SLA\_RVLSRD}{RV Corrn to Dynamical LSR} +{ + \action{Velocity component in a given direction due to the Sun's + motion with respect to the ``dynamical'' Local Standard of Rest.} + \call{R~=~sla\_RVLSRD (R2000, D2000)} +} +\args{GIVEN} +{ + \spec{R2000,D2000}{R}{J2000.0 mean \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{sla\_RVLSRD}{R}{Component of {\it peculiar}\/ solar motion + in direction R2000,D2000 (km~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item Sign convention: the result is positive when + the Sun is receding from the given point on the sky. + \item The Local Standard of Rest used here is the {\it dynamical}\/ LSR, + a point in the vicinity of the Sun which is in a circular + orbit around the Galactic centre. The Sun's motion with + respect to the dynamical LSR is called the {\it peculiar}\/ solar + motion. + \item There is another type of LSR, called a {\it kinematical}\/ LSR. A + kinematical LSR is the mean standard of rest of specified star + catalogues or stellar populations, and several slightly + different kinematical LSRs are in use. The Sun's motion with + respect to an agreed kinematical LSR is known as the + {\it standard}\/ solar motion. + The dynamical LSR is seldom used by observational astronomers, + who conventionally use a kinematical LSR such as the one implemented + in the routine sla\_RVLSRK. + \item The peculiar solar motion is from Delhaye (1965), in {\it Stars + and Stellar Systems}, vol~5, p73: in Galactic Cartesian + coordinates (+9,+12,+7)~km~s$^{-1}$. + This corresponds to about 16.6~km~s$^{-1}$ + towards Galactic coordinates $l^{I\!I}=53^{\circ},b^{I\!I}=+25^{\circ}$. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_RVLSRK}{RV Corrn to Kinematical LSR} +{ + \action{Velocity component in a given direction due to the Sun's + motion with respect to a kinematical Local Standard of Rest.} + \call{R~=~sla\_RVLSRK (R2000, D2000)} +} +\args{GIVEN} +{ + \spec{R2000,D2000}{R}{J2000.0 mean \radec\ (radians)} +} +\args{RETURNED} +{ + \spec{sla\_RVLSRK}{R}{Component of {\it standard}\/ solar motion + in direction R2000,D2000 (km~s$^{-1}$)} +} +\notes +{ + \begin{enumerate} + \item Sign convention: the result is positive when + the Sun is receding from the given point on the sky. + \item The Local Standard of Rest used here is one of several + {\it kinematical}\/ LSRs in common use. A kinematical LSR is the + mean standard of rest of specified star catalogues or stellar + populations. The Sun's motion with respect to a kinematical + LSR is known as the {\it standard}\/ solar motion. + \item There is another sort of LSR, seldom used by observational + astronomers, called the {\it dynamical}\/ LSR. This is a + point in the vicinity of the Sun which is in a circular orbit + around the Galactic centre. The Sun's motion with respect to + the dynamical LSR is called the {\it peculiar}\/ solar motion. To + obtain a radial velocity correction with respect to the + dynamical LSR use the routine sla\_RVLSRD. + \item The adopted standard solar motion is 20~km~s$^{-1}$ + towards $\alpha=18^{\rm h},\delta=+30^{\circ}$ (1900). + \end{enumerate} +} +\refs +{ + \begin{enumerate} + \item Delhaye (1965), in {\it Stars and Stellar Systems}, vol~5, p73. + \item {\it Methods of Experimental Physics}\/ (ed Meeks), vol~12, + part~C, sec~6.1.5.2, p281. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_S2TP}{Spherical to Tangent Plane} +{ + \action{Projection of spherical coordinates onto the tangent plane + (single precision).} + \call{CALL sla\_S2TP (RA, DEC, RAZ, DECZ, XI, ETA, J)} +} +\args{GIVEN} +{ + \spec{RA,DEC}{R}{spherical coordinates of star (radians)} \\ + \spec{RAZ,DECZ}{R}{spherical coordinates of tangent point (radians)} +} +\args{RETURNED} +{ + \spec{XI,ETA}{R}{tangent plane coordinates (radians)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK, star on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 1 = error, star too far from axis} \\ + \spec{}{}{\hspace{1.5em} 2 = error, antistar on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 3 = error, antistar too far from axis} +} +\notes +{ + \begin{enumerate} + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_V2TP is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_SEP}{Angle Between 2 Points on Sphere} +{ + \action{Angle between two points on a sphere (single precision).} + \call{R~=~sla\_SEP (A1, B1, A2, B2)} +} +\args{GIVEN} +{ + \spec{A1,B1}{R}{spherical coordinates of one point (radians)} \\ + \spec{A2,B2}{R}{spherical coordinates of the other point (radians)} +} +\args{RETURNED} +{ + \spec{sla\_SEP}{R}{angle between [A1,B1] and [A2,B2] in radians} +} +\notes +{ + \begin{enumerate} + \item The spherical coordinates are right ascension and declination, + longitude and latitude, {\it etc.}\ in radians. + \item The result is always positive. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_SMAT}{Solve Simultaneous Equations} +{ + \action{Matrix inversion and solution of simultaneous equations + (single precision).} + \call{CALL sla\_SMAT (N, A, Y, D, JF, IW)} +} +\args{GIVEN} +{ + \spec{N}{I}{number of unknowns} \\ + \spec{A}{R(N,N)}{matrix} \\ + \spec{Y}{R(N)}{vector} +} +\args{RETURNED} +{ + \spec{A}{R(N,N)}{matrix inverse} \\ + \spec{Y}{R(N)}{solution} \\ + \spec{D}{R}{determinant} \\ + \spec{JF}{I}{singularity flag: 0=OK} \\ + \spec{IW}{I(N)}{workspace} +} +\notes +{ + \begin{enumerate} + \item For the set of $n$ simultaneous linear equations in $n$ unknowns: + \begin{verse} + {\bf A}$\cdot${\bf y} = {\bf x} + \end{verse} + where: + \begin{itemize} + \item {\bf A} is a non-singular $n \times n$ matrix, + \item {\bf y} is the vector of $n$ unknowns, and + \item {\bf x} is the known vector, + \end{itemize} + sla\_SMAT computes: + \begin{itemize} + \item the inverse of matrix {\bf A}, + \item the determinant of matrix {\bf A}, and + \item the vector of $n$ unknowns {\bf y}. + \end{itemize} + Argument N is the order $n$, A (given) is the matrix {\bf A}, + Y (given) is the vector {\bf x} and Y (returned) + is the vector {\bf y}. + The argument A (returned) is the inverse matrix {\bf A}$^{-1}$, + and D is {\it det}\/({\bf A}). + \item JF is the singularity flag. If the matrix is non-singular, + JF=0 is returned. If the matrix is singular, JF=$-$1 + and D=0.0 are returned. In the latter case, the contents + of array A on return are undefined. + \item The algorithm is Gaussian elimination with partial pivoting. + This method is very fast; some much slower algorithms can give + better accuracy, but only by a small factor. + \item This routine replaces the obsolete sla\_SMATRX. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_SUBET}{Remove E-terms} +{ + \action{Remove the E-terms (elliptic component of annual aberration) + from a pre IAU~1976 catalogue \radec\ to give a mean place.} + \call{CALL sla\_SUBET (RC, DC, EQ, RM, DM)} +} +\args{GIVEN} +{ + \spec{RC,DC}{D}{\radec\ with E-terms included (radians)} \\ + \spec{EQ}{D}{Besselian epoch of mean equator and equinox} +} +\args{RETURNED} +{ + \spec{RM,DM}{D}{\radec\ without E-terms (radians)} +} +\anote{Most star positions from pre-1984 optical catalogues (or + obtained by astrometry with respect to such stars) have the + E-terms built-in. This routine converts such a position to a + formal mean place (allowing, for example, comparison with a + pulsar timing position).} +\aref{{\it Explanatory Supplement to the Astronomical Ephemeris}, + section 2D, page 48.} +%----------------------------------------------------------------------- +\routine{SLA\_SUPGAL}{Supergalactic to Galactic} +{ + \action{Transformation from de Vaucouleurs supergalactic coordinates + to IAU 1958 galactic coordinates.} + \call{CALL sla\_GALSUP (DL, DB, DSL, DSB)} +} +\args{GIVEN} +{ + \spec{DSL,DSB}{D}{supergalactic longitude and latitude (radians)} +} +\args{RETURNED} +{ + \spec{DL,DB}{D}{galactic longitude and latitude \gal\ (radians)} +} +\refs +{ + \begin{enumerate} + \item de Vaucouleurs, de Vaucouleurs, \& Corwin, {\it Second Reference + Catalogue of Bright Galaxies}, U.Texas, p8. + \item Systems \& Applied Sciences Corp., documentation for the + machine-readable version of the above catalogue, + Contract NAS 5-26490. + \end{enumerate} + (These two references give different values for the galactic + longitude of the supergalactic origin. Both are wrong; the + correct value is $l^{I\!I}=137.37$.) +} +%------------------------------------------------------------------------------ +\routine{SLA\_SVD}{Singular Value Decomposition} +{ + \action{Singular value decomposition. + This routine expresses a given matrix {\bf A} as the product of + three matrices {\bf U}, {\bf W}, {\bf V}$^{T}$: + \begin{tabbing} + XXXXXX \= \kill + \> {\bf A} = {\bf U} $\cdot$ {\bf W} $\cdot$ {\bf V}$^{T}$ + \end{tabbing} + where: + \begin{tabbing} + XXXXXX \= XXXX \= \kill + \> {\bf A} \> is any $m$ (rows) $\times n$ (columns) matrix, + where $m \geq n$ \\ + \> {\bf U} \> is an $m \times n$ column-orthogonal matrix \\ + \> {\bf W} \> is an $n \times n$ diagonal matrix with + $w_{ii} \geq 0$ \\ + \> {\bf V}$^{T}$ \> is the transpose of an $n \times n$ + orthogonal matrix +\end{tabbing} +} + \call{CALL sla\_SVD (M, N, MP, NP, A, W, V, WORK, JSTAT)} +} +\args{GIVEN} +{ + \spec{M,N}{I}{$m$, $n$, the numbers of rows and columns in matrix {\bf A}} \\ + \spec{MP,NP}{I}{physical dimensions of array containing matrix {\bf A}} \\ + \spec{A}{D(MP,NP)}{array containing $m \times n$ matrix {\bf A}} +} +\args{RETURNED} +{ + \spec{A}{D(MP,NP)}{array containing $m \times n$ column-orthogonal + matrix {\bf U}} \\ + \spec{W}{D(N)}{$n \times n$ diagonal matrix {\bf W} + (diagonal elements only)} \\ + \spec{V}{D(NP,NP)}{array containing $n \times n$ orthogonal + matrix {\bf V} ({\it n.b.}\ not {\bf V}$^{T}$)} \\ + \spec{WORK}{D(N)}{workspace} \\ + \spec{JSTAT}{I}{0~=~OK, $-$1~=~array A wrong shape, $>$0~=~index of W + for which convergence failed (see note~3, below)} +} +\notes +{ + \begin{enumerate} + \item M and N are the {\it logical}\/ dimensions of the + matrices and vectors concerned, which can be located in + arrays of larger {\it physical}\/ dimensions, given by MP and NP. + \item V contains matrix V, not the transpose of matrix V. + \item If the status JSTAT is greater than zero, this need not + necessarily be treated as a failure. It means that, due to + chance properties of the matrix A, the QR transformation + phase of the routine did not fully converge in a predefined + number of iterations, something that very seldom occurs. + When this condition does arise, it is possible that the + elements of the diagonal matrix W have not been correctly + found. However, in practice the results are likely to + be trustworthy. Applications should report the condition + as a warning, but then proceed normally. + \end{enumerate} +} +\refs{The algorithm is an adaptation of the routine SVD in the {\it EISPACK}\, + library (Garbow~{\it et~al.}\ 1977, {\it EISPACK Guide Extension}, + Springer Verlag), which is a FORTRAN~66 implementation of the Algol + routine SVD of Wilkinson \& Reinsch 1971 ({\it Handbook for Automatic + Computation}, vol~2, ed Bauer~{\it et~al.}, Springer Verlag). These + references give full details of the algorithm used here. + A good account of the use of SVD in least squares problems is given + in {\it Numerical Recipes}\/ (Press~{\it et~al.}\ 1987, Cambridge + University Press), which includes another variant of the EISPACK code.} +%----------------------------------------------------------------------- +\routine{SLA\_SVDCOV}{Covariance Matrix from SVD} +{ + \action{From the {\bf W} and {\bf V} matrices from the SVD + factorization of a matrix + (as obtained from the sla\_SVD routine), obtain + the covariance matrix.} + \call{CALL sla\_SVDCOV (N, NP, NC, W, V, WORK, CVM)} +} +\args{GIVEN} +{ + \spec{N}{I}{$n$, the number of rows and columns in + matrices {\bf W} and {\bf V}} \\ + \spec{NP}{I}{first dimension of array containing $n \times n$ + matrix {\bf V}} \\ + \spec{NC}{I}{first dimension of array CVM} \\ + \spec{W}{D(N)}{$n \times n$ diagonal matrix {\bf W} + (diagonal elements only)} \\ + \spec{V}{D(NP,NP)}{array containing $n \times n$ orthogonal matrix {\bf V}} +} +\args{RETURNED} +{ + \spec{WORK}{D(N)}{workspace} \\ + \spec{CVM}{D(NC,NC)}{array to receive covariance matrix} +} +\aref{{\it Numerical Recipes}, section 14.3.} +%----------------------------------------------------------------------- +\routine{SLA\_SVDSOL}{Solution Vector from SVD} +{ + \action{From a given vector and the SVD of a matrix (as obtained from + the sla\_SVD routine), obtain the solution vector. + This routine solves the equation: + \begin{tabbing} + XXXXXX \= \kill + \> {\bf A} $\cdot$ {\bf x} = {\bf b} + \end{tabbing} + where: + \begin{tabbing} + XXXXXX \= XXXX \= \kill + \> {\bf A} \> is a given $m$ (rows) $\times n$ (columns) + matrix, where $m \geq n$ \\ + \> {\bf x} \> is the $n$-vector we wish to find, and \\ + \> {\bf b} \> is a given $m$-vector + \end{tabbing} + by means of the {\it Singular Value Decomposition}\/ method (SVD).} + \call{CALL sla\_SVDSOL (M, N, MP, NP, B, U, W, V, WORK, X)} +} +\args{GIVEN} +{ + \spec{M,N}{I}{$m$, $n$, the numbers of rows and columns in matrix {\bf A}} \\ + \spec{MP,NP}{I}{physical dimensions of array containing matrix {\bf A}} \\ + \spec{B}{D(M)}{known vector {\bf b}} \\ + \spec{U}{D(MP,NP)}{array containing $m \times n$ matrix {\bf U}} \\ + \spec{W}{D(N)}{$n \times n$ diagonal matrix {\bf W} + (diagonal elements only)} \\ + \spec{V}{D(NP,NP)}{array containing $n \times n$ orthogonal matrix {\bf V}} +} +\args{RETURNED} +{ + \spec{WORK}{D(N)}{workspace} \\ + \spec{X}{D(N)}{unknown vector {\bf x}} +} +\notes +{ + \begin{enumerate} + \item In the Singular Value Decomposition method (SVD), + the matrix {\bf A} is first factorized (for example by + the routine sla\_SVD) into the following components: + \begin{tabbing} + XXXXXX \= \kill + \> {\bf A} = {\bf U} $\cdot$ {\bf W} $\cdot$ {\bf V}$^{T}$ + \end{tabbing} + where: + \begin{tabbing} + XXXXXX \= XXXX \= \kill + \> {\bf A} \> is any $m$ (rows) $\times n$ (columns) matrix, + where $m > n$ \\ + \> {\bf U} \> is an $m \times n$ column-orthogonal matrix \\ + \> {\bf W} \> is an $n \times n$ diagonal matrix with + $w_{ii} \geq 0$ \\ + \> {\bf V}$^{T}$ \> is the transpose of an $n \times n$ + orthogonal matrix + \end{tabbing} + Note that $m$ and $n$ are the {\it logical}\/ dimensions of the + matrices and vectors concerned, which can be located in + arrays of larger {\it physical}\/ dimensions MP and NP. + The solution is then found from the expression: + \begin{tabbing} + XXXXXX \= \kill + \> {\bf x} = {\bf V} $\cdot~[diag(1/${\bf W}$_{j})] + \cdot (${\bf U}$^{T} \cdot${\bf b}) + \end{tabbing} + \item If matrix {\bf A} is square, and if the diagonal matrix {\bf W} is not + altered, the method is equivalent to conventional solution + of simultaneous equations. + \item If $m > n$, the result is a least-squares fit. + \item If the solution is poorly determined, this shows up in the + SVD factorization as very small or zero {\bf W}$_{j}$ values. Where + a {\bf W}$_{j}$ value is small but non-zero it can be set to zero to + avoid ill effects. The present routine detects such zero + {\bf W}$_{j}$ values and produces a sensible solution, with highly + correlated terms kept under control rather than being allowed + to elope to infinity, and with meaningful values for the + other terms. + \end{enumerate} +} +\aref{{\it Numerical Recipes}, section 2.9.} +%----------------------------------------------------------------------- +\routine{SLA\_TP2S}{Tangent Plane to Spherical} +{ + \action{Transform tangent plane coordinates into spherical + coordinates (single precision)} + \call{CALL sla\_TP2S (XI, ETA, RAZ, DECZ, RA, DEC)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{R}{tangent plane rectangular coordinates (radians)} \\ + \spec{RAZ,DECZ}{R}{spherical coordinates of tangent point (radians)} +} +\args{RETURNED} +{ + \spec{RA,DEC}{R}{spherical coordinates (radians)} +} +\notes +{ + \begin{enumerate} + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_TP2V is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_TP2V}{Tangent Plane to Direction Cosines} +{ + \action{Given the tangent-plane coordinates of a star and the direction + cosines of the tangent point, determine the direction cosines + of the star + (single precision).} + \call{CALL sla\_TP2V (XI, ETA, V0, V)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{R}{tangent plane coordinates of star (radians)} \\ + \spec{V0}{R(3)}{direction cosines of tangent point} +} +\args{RETURNED} +{ + \spec{V}{R(3)}{direction cosines of star} +} +\notes +{ + \begin{enumerate} + \item If vector V0 is not of unit length, the returned vector V will + be wrong. + \item If vector V0 points at a pole, the returned vector V will be + based on the arbitrary assumption that $\alpha=0$ at + the tangent point. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_TP2S. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_TPS2C}{Plate centre from $\xi,\eta$ and $\alpha,\delta$} +{ + \action{From the tangent plane coordinates of a star of known \radec, + determine the \radec\ of the tangent point (single precision)} + \call{CALL sla\_TPS2C (XI, ETA, RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2, N)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{R}{tangent plane rectangular coordinates (radians)} \\ + \spec{RA,DEC}{R}{spherical coordinates (radians)} +} +\args{RETURNED} +{ + \spec{RAZ1,DECZ1}{R}{spherical coordinates of tangent point, + solution 1} \\ + \spec{RAZ2,DECZ2}{R}{spherical coordinates of tangent point, + solution 2} \\ + \spec{N}{I}{number of solutions:} \\ + \spec{}{}{\hspace{1em} 0 = no solutions returned (note 2)} \\ + \spec{}{}{\hspace{1em} 1 = only the first solution is useful (note 3)} \\ + \spec{}{}{\hspace{1em} 2 = there are two useful solutions (note 3)} +} +\notes +{ + \begin{enumerate} + \item The RAZ1 and RAZ2 values returned are in the range $0\!-\!2\pi$. + \item Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero $\xi$ value, and hence it is + meaningless to ask where the tangent point would have to be + to bring about this combination of $\xi$ and $\delta$. + \item Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N\,=\,1 + indicates only one useful solution, the usual case; under + these circumstances, the second solution corresponds to the + ``over-the-pole'' case, and this is reflected in the values + of RAZ2 and DECZ2 which are returned. + \item The DECZ1 and DECZ2 values returned are in the range $\pm\pi$, + but in the ordinary, non-pole-crossing, case, the range is + $\pm\pi/2$. + \item RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2 are all in radians. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item When working in \xyz\ rather than spherical coordinates, the + equivalent Cartesian routine sla\_TPV2C is available. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_TPV2C}{Plate centre from $\xi,\eta$ and $x,y,z$} +{ + \action{From the tangent plane coordinates of a star of known + direction cosines, determine the direction cosines + of the tangent point (single precision)} + \call{CALL sla\_TPV2C (XI, ETA, V, V01, V02, N)} +} +\args{GIVEN} +{ + \spec{XI,ETA}{R}{tangent plane coordinates of star (radians)} \\ + \spec{V}{R(3)}{direction cosines of star} +} +\args{RETURNED} +{ + \spec{V01}{R(3)}{direction cosines of tangent point, solution 1} \\ + \spec{V01}{R(3)}{direction cosines of tangent point, solution 2} \\ + \spec{N}{I}{number of solutions:} \\ + \spec{}{}{\hspace{1em} 0 = no solutions returned (note 2)} \\ + \spec{}{}{\hspace{1em} 1 = only the first solution is useful (note 3)} \\ + \spec{}{}{\hspace{1em} 2 = there are two useful solutions (note 3)} +} +\notes +{ + \begin{enumerate} + \item The vector V must be of unit length or the result will be wrong. + \item Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value. + \item Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. + N\,=\,1 + indicates only one useful solution, the usual case; under these + circumstances, the second solution can be regarded as valid if + the vector V02 is interpreted as the ``over-the-pole'' case. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_TPS2C. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_UE2EL}{Universal to Conventional Elements} +{ + \action{Transform universal elements into conventional heliocentric + osculating elements.} + \call{CALL sla\_UE2EL (\vtop{ + \hbox{U, JFORMR,} + \hbox{JFORM, EPOCH, ORBINC, ANODE, PERIH,} + \hbox{AORQ, E, AORL, DM, JSTAT)}}} +} +\args{GIVEN} +{ + \spec{U}{D(13)}{universal orbital elements (updated; Note~1)} \\ + \specel {(1)} {combined mass ($M+m$)} \\ + \specel {(2)} {total energy of the orbit ($\alpha$)} \\ + \specel {(3)} {reference (osculating) epoch ($t_0$)} \\ + \specel {(4-6)} {position at reference epoch (${\rm \bf r}_0$)} \\ + \specel {(7-9)} {velocity at reference epoch (${\rm \bf v}_0$)} \\ + \specel {(10)} {heliocentric distance at reference epoch} \\ + \specel {(11)} {${\rm \bf r}_0.{\rm \bf v}_0$} \\ + \specel {(12)} {date ($t$)} \\ + \specel {(13)} {universal eccentric anomaly ($\psi$) of date, approx} \\ \\ + \spec{JFORMR}{I}{requested element set (1-3; Note~3)} +} +\args{RETURNED} +{ + \spec{JFORM}{I}{element set actually returned (1-3; Note~4)} \\ + \spec{EPOCH}{D}{epoch of elements ($t_0$ or $T$, TT MJD)} \\ + \spec{ORBINC}{D}{inclination ($i$, radians)} \\ + \spec{ANODE}{D}{longitude of the ascending node ($\Omega$, radians)} \\ + \spec{PERIH}{D}{longitude or argument of perihelion + ($\varpi$ or $\omega$,} \\ + \spec{}{}{\hspace{1.5em} radians)} \\ + \spec{AORQ}{D}{mean distance or perihelion distance ($a$ or $q$, AU)} \\ + \spec{E}{D}{eccentricity ($e$)} \\ + \spec{AORL}{D}{mean anomaly or longitude + ($M$ or $L$, radians,} \\ + \spec{}{}{\hspace{1.5em} JFORM=1,2 only)} \\ + \spec{DM}{D}{daily motion ($n$, radians, JFORM=1 only)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{2.3em} 0 = OK} \\ + \spec{}{}{\hspace{1.5em} $-$1 = illegal PMASS} \\ + \spec{}{}{\hspace{1.5em} $-$2 = illegal JFORMR} \\ + \spec{}{}{\hspace{1.5em} $-$3 = position/velocity out of allowed range} +} +\notes +{ + \begin{enumerate} + \setlength{\parskip}{\medskipamount} + \item The ``universal'' elements are those which define the orbit for the + purposes of the method of universal variables (see reference 2). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i)~$\alpha$, which is proportional to the total energy of the + orbit, (ii)~the heliocentric distance at epoch, + (iii)~the outwards component of the velocity at the given epoch, + (iv)~an estimate of $\psi$, the ``universal eccentric anomaly'' at a + given date and (v)~that date. + \item The universal elements are with respect to the mean equator and + equinox of epoch J2000. The orbital elements produced are with + respect to the J2000 ecliptic and mean equinox. + \item Three different element-format options are supported, as + follows. \\ + + JFORM=1, suitable for the major planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> longitude of perihelion $\varpi$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean longitude $L$ (radians) \\ + \> DM \> = \> daily motion $n$ (radians) + \end{tabbing} + + JFORM=2, suitable for minor planets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of elements $t_0$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> mean distance $a$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e < 1 )$ \\ + \> AORL \> = \> mean anomaly $M$ (radians) + \end{tabbing} + + JFORM=3, suitable for comets: + + \begin{tabbing} + xxx \= xxxxxxxx \= xx \= \kill + \> EPOCH \> = \> epoch of perihelion $T$ (TT MJD) \\ + \> ORBINC \> = \> inclination $i$ (radians) \\ + \> ANODE \> = \> longitude of the ascending node $\Omega$ (radians) \\ + \> PERIH \> = \> argument of perihelion $\omega$ (radians) \\ + \> AORQ \> = \> perihelion distance $q$ (AU) \\ + \> E \> = \> eccentricity $e$ $( 0 \leq e \leq 10 )$ + \end{tabbing} + \item It may not be possible to generate elements in the form + requested through JFORMR. The caller is notified of the form + of elements actually returned by means of the JFORM argument: + + \begin{tabbing} + xx \= xxxxxxxxxx \= xxxxxxxxxxx \= \kill + \> JFORMR \> JFORM \> meaning \\ \\ + \> ~~~~~1 \> ~~~~~1 \> OK: elements are in the requested format \\ + \> ~~~~~1 \> ~~~~~2 \> never happens \\ + \> ~~~~~1 \> ~~~~~3 \> orbit not elliptical \\ + \> ~~~~~2 \> ~~~~~1 \> never happens \\ + \> ~~~~~2 \> ~~~~~2 \> OK: elements are in the requested format \\ + \> ~~~~~2 \> ~~~~~3 \> orbit not elliptical \\ + \> ~~~~~3 \> ~~~~~1 \> never happens \\ + \> ~~~~~3 \> ~~~~~2 \> never happens \\ + \> ~~~~~3 \> ~~~~~3 \> OK: elements are in the requested format + \end{tabbing} + \item The arguments returned for each value of JFORM ({\it cf}\/ Note~5: + JFORM may not be the same as JFORMR) are as follows: + + \begin{tabbing} + xxx \= xxxxxxxxxxxx \= xxxxxx \= xxxxxx \= \kill + \> JFORM \> 1 \> 2 \> 3 \\ \\ + \> EPOCH \> $t_0$ \> $t_0$ \> $T$ \\ + \> ORBINC \> $i$ \> $i$ \> $i$ \\ + \> ANODE \> $\Omega$ \> $\Omega$ \> $\Omega$ \\ + \> PERIH \> $\varpi$ \> $\omega$ \> $\omega$ \\ + \> AORQ \> $a$ \> $a$ \> $q$ \\ + \> E \> $e$ \> $e$ \> $e$ \\ + \> AORL \> $L$ \> $M$ \> - \\ + \> DM \> $n$ \> - \> - + \end{tabbing} + + where: + \begin{tabbing} + xxx \= xxxxxxxx \= xxx \= \kill + \> $t_0$ \> is the epoch of the elements (MJD, TT) \\ + \> $T$ \> is the epoch of perihelion (MJD, TT) \\ + \> $i$ \> is the inclination (radians) \\ + \> $\Omega$ \> is the longitude of the ascending node (radians) \\ + \> $\varpi$ \> is the longitude of perihelion (radians) \\ + \> $\omega$ \> is the argument of perihelion (radians) \\ + \> $a$ \> is the mean distance (AU) \\ + \> $q$ \> is the perihelion distance (AU) \\ + \> $e$ \> is the eccentricity \\ + \> $L$ \> is the longitude (radians, $0-2\pi$) \\ + \> $M$ \> is the mean anomaly (radians, $0-2\pi$) \\ + \> $n$ \> is the daily motion (radians) \\ + \> - \> means no value is set + \end{tabbing} + \item At very small inclinations, the longitude of the ascending node + ANODE becomes indeterminate and under some circumstances may be + set arbitrarily to zero. Similarly, if the orbit is close to + circular, the true anomaly becomes indeterminate and under some + circumstances may be set arbitrarily to zero. In such cases, + the other elements are automatically adjusted to compensate, + and so the elements remain a valid description of the orbit. + \end{enumerate} +} +\refs{ + \begin{enumerate} + \item Sterne, Theodore E., {\it An Introduction to Celestial Mechanics,}\/ + Interscience Publishers, 1960. Section 6.7, p199. + \item Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_UE2PV}{Pos/Vel from Universal Elements} +{ + \action{Heliocentric position and velocity of a planet, asteroid or comet, + starting from orbital elements in the ``universal variables'' form.} + \call{CALL sla\_UE2PV (DATE, U, PV, JSTAT)} +} +\args{GIVEN} +{ + \spec{DATE}{D}{date (TT Modified Julian Date = JD$-$2400000.5)} +} +\args{GIVEN and RETURNED} +{ + \spec{U}{D(13)}{universal orbital elements (updated; Note~1)} \\ + \specel {(1)} {combined mass ($M+m$)} \\ + \specel {(2)} {total energy of the orbit ($\alpha$)} \\ + \specel {(3)} {reference (osculating) epoch ($t_0$)} \\ + \specel {(4-6)} {position at reference epoch (${\rm \bf r}_0$)} \\ + \specel {(7-9)} {velocity at reference epoch (${\rm \bf v}_0$)} \\ + \specel {(10)} {heliocentric distance at reference epoch} \\ + \specel {(11)} {${\rm \bf r}_0.{\rm \bf v}_0$} \\ + \specel {(12)} {date ($t$)} \\ + \specel {(13)} {universal eccentric anomaly ($\psi$) of date, approx} +} +\args{RETURNED} +{ + \spec{PV}{D(6)}{heliocentric \xyzxyzd, equatorial, J2000} \\ + \spec{}{}{\hspace{1.5em} (AU, AU/s; Note~1)} \\ + \spec{JSTAT}{I}{status:} \\ + \spec{}{}{\hspace{1.95em} 0 = OK} \\ + \spec{}{}{\hspace{1.2em} $-$1 = radius vector zero} \\ + \spec{}{}{\hspace{1.2em} $-2$ = failed to converge} +} +\notes +{ + \begin{enumerate} + \setlength{\parskip}{\medskipamount} + \item The ``universal'' elements are those which define the orbit for the + purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i)~$\alpha$, which is proportional to the total energy of the + orbit, (ii)~the heliocentric distance at epoch, + (iii)~the outwards component of the velocity at the given epoch, + (iv)~an estimate of $\psi$, the ``universal eccentric anomaly'' at a + given date and (v)~that date. + \item The companion routine is sla\_EL2UE. This takes the conventional + orbital elements and transforms them into the set of numbers + needed by the present routine. A single prediction requires one + one call to sla\_EL2UE followed by one call to the present routine; + for convenience, the two calls are packaged as the routine + sla\_PLANEL. Multiple predictions may be made by again + calling sla\_EL2UE once, but then calling the present routine + multiple times, which is faster than multiple calls to sla\_PLANEL. + + It is not obligatory to use sla\_EL2UE to obtain the parameters. + However, it should be noted that because sla\_EL2UE performs its + own validation, no checks on the contents of the array U are made + by the present routine. + \item DATE is the instant for which the prediction is required. It is + in the TT timescale (formerly Ephemeris Time, ET) and is a + Modified Julian Date (JD$-$2400000.5). + \item The universal elements supplied in the array U are in canonical + units (solar masses, AU and canonical days). The position and + velocity are not sensitive to the choice of reference frame. The + sla\_EL2UE routine in fact produces coordinates with respect to the + J2000 equator and equinox. + \item The algorithm was originally adapted from the EPHSLA program of + D.\,H.\,P.\,Jones (private communication, 1996). The method + is based on Stumpff's Universal Variables. + \end{enumerate} +} +\aref{Everhart, E. \& Pitkin, E.T., Am.~J.~Phys.~51, 712, 1983.} +%----------------------------------------------------------------------- +\routine{SLA\_UNPCD}{Remove Radial Distortion} +{ + \action{Remove pincushion/barrel distortion from a distorted + \xy\ to give tangent-plane \xy.} + \call{CALL sla\_UNPCD (DISCO,X,Y)} +} +\args{GIVEN} +{ + \spec{DISCO}{D}{pincushion/barrel distortion coefficient} \\ + \spec{X,Y}{D}{distorted \xy} +} +\args{RETURNED} +{ + \spec{X,Y}{D}{tangent-plane \xy} +} +\notes +{ + \begin{enumerate} + \item The distortion is of the form $\rho = r (1 + c r^{2})$, where $r$ is + the radial distance from the tangent point, $c$ is the DISCO + argument, and $\rho$ is the radial distance in the presence of + the distortion. + \item For {\it pincushion}\/ distortion, C is +ve; for + {\it barrel}\/ distortion, C is $-$ve. + \item For X,Y in units of one projection radius (in the case of + a photographic plate, the focal length), the following + DISCO values apply: + + \vspace{2ex} + + \hspace{5em} + \begin{tabular}{|l|c|} \hline + Geometry & DISCO \\ \hline \hline + astrograph & 0.0 \\ \hline + Schmidt & $-$0.3333 \\ \hline + AAT PF doublet & +147.069 \\ \hline + AAT PF triplet & +178.585 \\ \hline + AAT f/8 & +21.20 \\ \hline + JKT f/8 & +14.6 \\ \hline + \end{tabular} + + \vspace{2ex} + + \item The present routine is an approximate inverse to the + companion routine sla\_PCD, obtained from two iterations + of Newton's method. The mismatch between the sla\_PCD + and sla\_UNPCD is negligible for astrometric applications; + to reach 1~milliarcsec at the edge of the AAT triplet or + Schmidt field would require field diameters of \degree{2}{4} + and $42^{\circ}$ respectively. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_V2TP}{Direction Cosines to Tangent Plane} +{ + \action{Given the direction cosines of a star and of the tangent point, + determine the star's tangent-plane coordinates + (single precision).} + \call{CALL sla\_V2TP (V, V0, XI, ETA, J)} +} +\args{GIVEN} +{ + \spec{V}{R(3)}{direction cosines of star} \\ + \spec{V0}{R(3)}{direction cosines of tangent point} +} +\args{RETURNED} +{ + \spec{XI,ETA}{R}{tangent plane coordinates (radians)} \\ + \spec{J}{I}{status:} \\ + \spec{}{}{\hspace{1.5em} 0 = OK, star on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 1 = error, star too far from axis} \\ + \spec{}{}{\hspace{1.5em} 2 = error, antistar on tangent plane} \\ + \spec{}{}{\hspace{1.5em} 3 = error, antistar too far from axis} +} +\notes +{ + \begin{enumerate} + \item If vector V0 is not of unit length, or if vector V is of zero + length, the results will be wrong. + \item If V0 points at a pole, the returned $\xi,\eta$ + will be based on the + arbitrary assumption that $\alpha=0$ at the tangent point. + \item The projection is called the {\it gnomonic}\/ projection; the + Cartesian coordinates \xieta\ are called + {\it standard coordinates.}\/ The latter + are in units of the distance from the tangent plane to the projection + point, {\it i.e.}\ radians near the origin. + \item This routine is the Cartesian equivalent of the routine sla\_S2TP. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_VDV}{Scalar Product} +{ + \action{Scalar product of two 3-vectors (single precision).} + \call{R~=~sla\_VDV (VA, VB)} +} +\args{GIVEN} +{ + \spec{VA}{R(3)}{first vector} \\ + \spec{VB}{R(3)}{second vector} +} +\args{RETURNED} +{ + \spec{sla\_VDV}{R}{scalar product VA.VB} +} +%----------------------------------------------------------------------- +\routine{SLA\_VN}{Normalize Vector} +{ + \action{Normalize a 3-vector, also giving the modulus (single precision).} + \call{CALL sla\_VN (V, UV, VM)} +} +\args{GIVEN} +{ + \spec{V}{R(3)}{vector} +} +\args{RETURNED} +{ + \spec{UV}{R(3)}{unit vector in direction of V} \\ + \spec{VM}{R}{modulus of V} +} +\anote{If the modulus of V is zero, UV is set to zero as well.} +%----------------------------------------------------------------------- +\routine{SLA\_VXV}{Vector Product} +{ + \action{Vector product of two 3-vectors (single precision).} + \call{CALL sla\_VXV (VA, VB, VC)} +} +\args{GIVEN} +{ + \spec{VA}{R(3)}{first vector} \\ + \spec{VB}{R(3)}{second vector} +} +\args{RETURNED} +{ + \spec{VC}{R(3)}{vector product VA$\times$VB} +} +%----------------------------------------------------------------------- +\routine{SLA\_WAIT}{Time Delay} +{ + \action{Wait for a specified interval.} + \call{CALL sla\_WAIT (DELAY)} +} +\args{GIVEN} +{ + \spec{DELAY}{R}{delay in seconds} +} +\notes +{ + \begin{enumerate} + \item The implementation is machine-specific. + \item The delay actually requested is restricted to the range + 100ns-200s in the present implementation. + \item There is no guarantee of accuracy, though on almost all + types of computer the program will certainly not + resume execution {\it before}\/ the stated interval has + elapsed. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_XY2XY}{Apply Linear Model to an \xy} +{ + \action{Transform one \xy\ into another using a linear model of the type + produced by the sla\_FITXY routine.} + \call{CALL sla\_XY2XY (X1,Y1,COEFFS,X2,Y2)} +} +\args{GIVEN} +{ + \spec{X1,Y1}{D}{\xy\ before transformation} \\ + \spec{COEFFS}{D(6)}{transformation coefficients (see note)} +} +\args{RETURNED} +{ + \spec{X2,Y2}{D}{\xy\ after transformation} +} +\notes +{ + \begin{enumerate} + \item The model relates two sets of \xy\ coordinates as follows. + Naming the six elements of COEFFS $a,b,c,d,e$ \& $f$, + the present routine performs the transformation: + \begin{verse} + $x_{2} = a + bx_{1} + cy_{1}$ \\ + $y_{2} = d + ex_{1} + fy_{1}$ + \end{verse} + \item See also sla\_FITXY, sla\_PXY, sla\_INVF, sla\_DCMPF. + \end{enumerate} +} +%----------------------------------------------------------------------- +\routine{SLA\_ZD}{$h,\delta$ to Zenith Distance} +{ + \action{Hour angle and declination to zenith distance + (double precision).} + \call{D~=~sla\_ZD (HA, DEC, PHI)} +} +\args{GIVEN} +{ + \spec{HA}{D}{hour angle in radians} \\ + \spec{DEC}{D}{declination in radians} \\ + \spec{PHI}{D}{latitude in radians} +} +\args{RETURNED} +{ + \spec{sla\_ZD}{D}{zenith distance (radians, $0\!-\!\pi$)} +} +\notes +{ + \begin{enumerate} + \item The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied (see sla\_POLMO). + \item In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type + of zenith distance. In particular, it may be + important to distinguish between the zenith distance + as affected by refraction, which would require the + {\it observed}\/ \hadec, and the zenith distance {\it in vacuo}, + which would require the {\it topocentric}\/ \hadec. If + the effects of diurnal aberration can be neglected, the + {\it apparent}\/ \hadec\ may be used instead of the + {\it topocentric}\/ \hadec. + \item No range checking of arguments is done. + \item In applications which involve many zenith distance calculations, + rather than calling the present routine it will be more + efficient to use inline code, having previously computed fixed + terms such as sine and cosine of latitude, and perhaps sine and + cosine of declination. + \end{enumerate} +} + +\pagebreak + +\section{EXPLANATION AND EXAMPLES} +To guide the writer of positional-astronomy applications software, +this final chapter puts the SLALIB routines into the context of +astronomical phenomena and techniques, and presents a few +``cookbook'' examples +of the SLALIB calls in action. The astronomical content of the chapter +is not, of course, intended to be a substitute for specialist text-books on +positional astronomy, but may help bridge the gap between +such books and the SLALIB routines. For further reading, the following +cover a wide range of material and styles: +\begin{itemize} +\item {\it Explanatory Supplement to the Astronomical Almanac}, + ed.\ P.\,Kenneth~Seidelmann (1992), University Science Books. +\item {\it Vectorial Astrometry}, C.\,A.\,Murray (1983), Adam Hilger. +\item {\it Spherical Astronomy}, Robin~M.\,Green (1985), Cambridge + University Press. +\item {\it Spacecraft Attitude Determination and Control}, + ed.\ James~R.\,Wertz (1986), Reidel. +\item {\it Practical Astronomy with your Calculator}, + Peter~Duffett-Smith (1981), Cambridge University Press. +\end{itemize} +Also of considerable value, though out of date in places, are: +\begin{itemize} +\item {\it Explanatory Supplement to the Astronomical Ephemeris + and the American Ephemeris and Nautical Almanac}, RGO/USNO (1974), + HMSO. +\item {\it Textbook on Spherical Astronomy}, W.\,M.\,Smart (1977), + Cambridge University Press. +\end{itemize} +Only brief details of individual SLALIB routines are given here, and +readers will find it useful to refer to the subprogram specifications +elsewhere in this document. The source code for the SLALIB routines +(available in both Fortran and C) is also intended to be used as +documentation. + +\subsection {Spherical Trigonometry} +Celestial phenomena occur at such vast distances from the +observer that for most practical purposes there is no need to +work in 3D; only the direction +of a source matters, not how far away it is. Things can +therefore be viewed as if they were happening +on the inside of sphere with the observer at the centre -- +the {\it celestial sphere}. Problems involving +positions and orientations in the sky can then be solved by +using the formulae of {\it spherical trigonometry}, which +apply to {\it spherical triangles}, the sides of which are +{\it great circles}. + +Positions on the celestial sphere may be specified by using +a spherical polar coordinate system, defined in terms of +some fundamental plane and a line in that plane chosen to +represent zero longitude. Mathematicians usually work with the +co-latitude, with zero at the principal pole, whereas most +astronomical coordinate systems use latitude, reckoned plus and +minus from the equator. +Astronomical coordinate systems may be either right-handed +({\it e.g.}\ right ascension and declination \radec, +Galactic longitude and latitude \gal) +or left-handed ({\it e.g.}\ hour angle and +declination \hadec). In some cases +different conventions have been used in the past, a fruitful source of +mistakes. Azimuth and geographical longitude are examples; azimuth +is now generally reckoned north through east +(making a left-handed system); geographical longitude is now usually +taken to increase eastwards (a right-handed system) but astronomers +used to employ a west-positive convention. In reports +and program comments it is wise to spell out what convention +is being used, if there is any possibility of confusion. + +When applying spherical trigonometry formulae, attention must be +paid to +rounding errors (for example it is a bad idea to find a +small angle through its cosine) and to the possibility of +problems close to poles. +Also, if a formulation relies on inspection to establish +the quadrant of the result, it is an indication that a vector-related +method might be preferable. + +As well as providing many routines which work in terms of specific +spherical coordinates such as \radec, SLALIB provides +two routines which operate directly on generic spherical +coordinates: +sla\_SEP +computes the separation between +two points (the distance along a great circle) and +sla\_BEAR +computes the bearing (or {\it position angle}) +of one point seen from the other. The routines +sla\_DSEP +and +sla\_DBEAR +are double precision equivalents. As a simple demonstration +of SLALIB, we will use these facilities to estimate the distance from +London to Sydney and the initial compass heading: +\goodbreak +\begin{verbatim} + IMPLICIT NONE + + * Degrees to radians + REAL D2R + PARAMETER (D2R=0.01745329252) + + * Longitudes and latitudes (radians) for London and Sydney + REAL AL,BL,AS,BS + PARAMETER (AL=-0.2*D2R,BL=51.5*D2R,AS=151.2*D2R,BS=-33.9*D2R) + + * Earth radius in km (spherical approximation) + REAL RKM + PARAMETER (RKM=6375.0) + + REAL sla_SEP,sla_BEAR + + + * Distance and initial heading (N=0, E=90) + WRITE (*,'(1X,I5,'' km,'',I4,'' deg'')') + : NINT(sla_SEP(AL,BL,AS,BS)*RKM),NINT(sla_BEAR(AL,BL,AS,BS)/D2R) + + END +\end{verbatim} +\goodbreak +(The result is 17011~km, $61^\circ$.) + +The routines +sla\_PAV and +sla\_DPAV +are equivalents of sla\_BEAR and sla\_DBEAR but starting from +direction-cosines instead of spherical coordinates. + +\subsubsection{Formatting angles} +SLALIB has routines for decoding decimal numbers +from character form and for converting angles to and from +sexagesimal form (hours, minutes, seconds or degrees, +arcminutes, arcseconds). These apparently straightforward +operations contain hidden traps which the SLALIB routines +avoid. + +There are five routines for decoding numbers from a character +string, such as might be entered using a keyboard. +They all work in the same style, and successive calls +can work their way along a single string decoding +a sequence of numbers of assorted types. Number +fields can be separated by spaces or commas, and can be defaulted +to previous values or to preset defaults. + +Three of the routines decode single numbers: +sla\_INTIN +(integer), +sla\_FLOTIN +(single precision floating point) and +sla\_DFLTIN +(double precision). A minus sign can be +detected even when the number is zero; this avoids +the frequently-encountered ``minus zero'' bug, where +declinations {\it etc.}\ in +the range $0^{\circ}$ to $-1^{\circ}$ mysteriously migrate to +the range $0^{\circ}$ to $+1^{\circ}$. +Here is an example (in Fortran) where we wish to +read two numbers, and integer {\tt IX} and a real, {\tt Y}, +with {\tt X} defaulting to zero and {\tt Y} defaulting to +{\tt X}: +\goodbreak +\begin{verbatim} + DOUBLE PRECISION Y + CHARACTER*80 A + INTEGER IX,I,J + + * Input the string to be decoded + READ (*,'(A)') A + + * Preset IX to its default value + IX = 0 + + * Point to the start of the string + I = 1 + + * Decode an integer + CALL sla_INTIN(A,I,IX,J) + IF (J.GT.1) GO TO ... (bad IX) + + * Preset Y to its default value + Y = DBLE(IX) + + * Decode a double precision number + CALL sla_DFLTIN(A,I,Y,J) + IF (J.GT.1) GO TO ... (bad Y) +\end{verbatim} +\goodbreak +Two additional routines decode a 3-field sexagesimal number: +sla\_AFIN +(degrees, arcminutes, arcseconds to single +precision radians) and +sla\_DAFIN +(the same but double precision). They also +work using other units such as hours {\it etc}.\ if +you multiply the result by the appropriate factor. An example +Fortran program which uses +sla\_DAFIN +was given earlier, in section 1.2. + +SLALIB provides four routines for expressing an angle in radians +in a preferred range. The function +sla\_RANGE +expresses an angle +in the range $\pm\pi$; +sla\_RANORM +expresses an angle in the range +$0-2\pi$. The functions +sla\_DRANGE +and +sla\_DRANRM +are double precision versions. + +Several routines +(sla\_CTF2D, +sla\_CR2AF +{\it etc.}) are provided to convert +angles to and from +sexagesimal form (hours, minute, seconds or degrees, +arcminutes and arcseconds). +They avoid the common +``converting from integer to real at the wrong time'' +bug, which produces angles like \hms{24}{59}{59}{999}. +Here is a program which displays an hour angle +stored in radians: +\goodbreak +\begin{verbatim} + DOUBLE PRECISION HA + CHARACTER SIGN + INTEGER IHMSF(4) + : + CALL sla_DR2TF(3,HA,SIGN,IHMSF) + WRITE (*,'(1X,A,3I3.2,''.'',I3.3)') SIGN,IHMSF +\end{verbatim} +\goodbreak + +\subsection {Vectors and Matrices} +As an alternative to employing a spherical polar coordinate system, +the direction of an object can be defined in terms of the sum of any +three vectors as long as they are different and +not coplanar. In practice, three vectors at right angles are +usually chosen, forming a system +of {\it Cartesian coordinates}. The {\it x}- and {\it y}-axes +lie in the fundamental plane ({\it e.g.}\ the equator in the +case of \radec), with the {\it x}-axis pointing to zero longitude. +The {\it z}-axis is normal to the fundamental plane and points +towards positive latitudes. The {\it y}-axis can lie in either +of the two possible directions, depending on whether the +coordinate system is right-handed or left-handed. +The three axes are sometimes called +a {\it triad}. For most applications involving arbitrarily +distant objects such as stars, the vector which defines +the direction concerned is constrained to have unit length. +The {\it x}-, {\it y-} and {\it z-}components +can be regarded as the scalar (dot) product of this vector +onto the three axes of the triad in turn. Because the vector +is a unit vector, +each of the three dot-products is simply the cosine of the angle +between the unit vector and the axis concerned, and the +{\it x}-, {\it y-} and {\it z-}components are sometimes +called {\it direction cosines}. + +For some applications involving objects +with the Solar System, unit vectors are inappropriate, and +it is necessary to use vectors scaled in length-units such as +AU, km {\it etc.} +In these cases the origin of the coordinate system may not be +the observer, but instead might be the Sun, the Solar-System +barycentre, the centre of the Earth {\it etc.} But whatever the application, +the final direction in which the observer sees the object can be +expressed as direction cosines. + +But where has this got us? Instead of two numbers -- a longitude and +a latitude -- we now have three numbers to look after +-- the {\it x}-, {\it y-} and +{\it z-}components -- whose quadratic sum we have somehow to contrive to +be unity. And, in addition to this apparent redundancy, +most people find it harder to visualize +problems in terms of \xyz\ than in $[\,\theta,\phi~]$. +Despite these objections, the vector approach turns out to have +significant advantages over the spherical trigonometry approach: +\begin{itemize} +\item Vector formulae tend to be much more succinct; one vector + operation is the equivalent of strings of sines and cosines. +\item The formulae are as a rule rigorous, even at the poles. +\item Accuracy is maintained all over the celestial sphere. + When one Cartesian component is nearly unity and + therefore insensitive to direction, the others become small + and therefore more precise. +\item Formulations usually deliver the quadrant of the result + without the need for any inspection (except within the + library function ATAN2). +\end{itemize} +A number of important transformations in positional +astronomy turn out to be nothing more than changes of coordinate +system, something which is especially convenient if +the vector approach is used. A direction with respect +to one triad can be expressed relative to another triad simply +by multiplying the \xyz\ column vector by the appropriate +$3\times3$ orthogonal matrix +(a tensor of Rank~2, or {\it dyadic}). The three rows of this +{\it rotation matrix}\/ +are the vectors in the old coordinate system of the three +new axes, and the transformation amounts to obtaining the +dot-product of the direction-vector with each of the three +new axes. Precession, nutation, \hadec\ to \azel, +\radec\ to \gal\ and so on are typical examples of the +technique. A useful property of the rotation matrices +is that they can be inverted simply by taking the transpose. + +The elements of these vectors and matrices are assorted combinations of +the sines and cosines of the various angles involved (hour angle, +declination and so on, depending on which transformation is +being applied). If you write out the matrix multiplications +in full you get expressions which are essentially the same as the +equivalent spherical trigonometry formulae. Indeed, many of the +standard formulae of spherical trigonometry are most easily +derived by expressing the problem initially in +terms of vectors. + +\subsubsection{Using vectors} +SLALIB provides conversions between spherical and vector +form +(sla\_CS2C, +sla\_CC2S +{\it etc.}), plus an assortment +of standard vector and matrix operations +(sla\_VDV, +sla\_MXV +{\it etc.}). +There are also routines +(sla\_EULER +{\it etc.}) for creating a rotation matrix +from three {\it Euler angles}\/ (successive rotations about +specified Cartesian axes). Instead of Euler angles, a rotation +matrix can be expressed as an {\it axial vector}\/ (the pole of the rotation, +and the amount of rotation), and routines are provided for this +(sla\_AV2M, +sla\_M2AV +{\it etc.}). + +Here is an example where spherical coordinates {\tt P1} and {\tt Q1} +undergo a coordinate transformation and become {\tt P2} and {\tt Q2}; +the transformation consists of a rotation of the coordinate system +through angles {\tt A}, {\tt B} and {\tt C} about the +{\it z}, new {\it y}\/ and new {\it z}\/ axes respectively: +\goodbreak +\begin{verbatim} + REAL A,B,C,R(3,3),P1,Q1,V1(3),V2(3),P2,Q2 + : + * Create rotation matrix + CALL sla_EULER('ZYZ',A,B,C,R) + + * Transform position (P,Q) from spherical to Cartesian + CALL sla_CS2C(P1,Q1,V1) + + * Multiply by rotation matrix + CALL sla_MXV(R,V1,V2) + + * Back to spherical + CALL sla_CC2S(V2,P2,Q2) +\end{verbatim} +\goodbreak +Small adjustments to the direction of a position +vector are often most conveniently described in terms of +$[\,\Delta x,\Delta y, \Delta z\,]$. Adding the correction +vector needs careful handling if the position +vector is to remain of length unity, an advisable precaution which +ensures that +the \xyz\ components are always available to mean the cosines of +the angles between the vector and the axis concerned. Two types +of shifts are commonly used, +the first where a small vector of arbitrary direction is +added to the unit vector, and the second where there is a displacement +in the latitude coordinate (declination, elevation {\it etc.}) alone. + +For a shift produced by adding a small \xyz\ vector ${\bf D}$ to a +unit vector ${\bf V1}$, the resulting vector ${\bf V2}$ has direction +$<{\bf V1}+{\bf D}>$ but is no longer of unit length. A better approximation +is available if the result is multiplied by a scaling factor of +$(1-{\bf D}\cdot{\bf V1})$, where the dot +means scalar product. In Fortran: +\goodbreak +\begin{verbatim} + F = (1D0-(DX*V1X+DY*V1Y+DZ*V1Z)) + V2X = F*(V1X+DX) + V2Y = F*(V1Y+DY) + V2Z = F*(V1Z+DZ) +\end{verbatim} +\goodbreak +\noindent +The correction for diurnal aberration (discussed later) is +an example of this form of shift. + +As an example of the second kind of displacement +we will apply a small change in elevation $\delta E$ to an +\azel\ direction vector. The direction of the +result can be obtained by making the allowable approximation +${\tan \delta E\approx\delta E}$ and adding a adjustment +vector of length $\delta E$ normal +to the direction vector in the vertical plane containing the direction +vector. The $z$-component of the adjustment vector is +$\delta E \cos E$, +and the horizontal component is +$\delta E \sin E$ which has then to be +resolved into $x$ and $y$ in proportion to their current sizes. To +approximate a unit vector more closely, a correction factor of +$\cos \delta E$ can then be applied, which is nearly +$(1-\delta E^2 /2)$ for +small $\delta E$. Expressed in Fortran, for initial vector +{\tt V1X,V1Y,V1Z}, change in elevation {\tt DEL} +(+ve $\equiv$ upwards), and result +vector {\tt V2X,V2Y,V2Z}: +\goodbreak +\begin{verbatim} + COSDEL = 1DO-DEL*DEL/2D0 + R1 = SQRT(V1X*V1X+V1Y*V1Y) + F = COSDEL*(R1-DEL*V1Z)/R1 + V2X = F*V1X + V2Y = F*V1Y + V2Z = COSDEL*(V1Z+DEL*R1) +\end{verbatim} +\goodbreak +An example of this type of shift is the correction for atmospheric +refraction (see later). +Depending on the relationship between $\delta E$ and $E$, special +handling at the pole (the zenith for our example) may be required. + +SLALIB includes routines for the case where both a position +and a velocity are involved. The routines +sla\_CS2C6 +and +sla\_CC62S +convert from $[\theta,\phi,\dot{\theta},\dot{\phi}]$ +to \xyzxyzd\ and back; +sla\_DCS26 +and +sla\_DC62S +are double precision equivalents. + +\subsection {Celestial Coordinate Systems} +SLALIB has routines to perform transformations +of celestial positions between different spherical +coordinate systems, including those shown in the following table: + +\begin{center} +\begin{tabular}{|l|c|c|c|c|c|c|} \hline +{\it system} & {\it symbols} & {\it longitude} & {\it latitude} & + {\it x-y plane} & {\it long.\ zero} & {\it RH/LH} +\\ \hline \hline +horizon & -- & azimuth & elevation & horizontal & north & L +\\ \hline +equatorial & $\alpha,\delta$ & R.A.\ & Dec.\ & equator & equinox & R +\\ \hline +local equ.\ & $h,\delta$ & H.A.\ & Dec.\ & equator & meridian & L +\\ \hline +ecliptic & $\lambda,\beta$ & ecl.\ long.\ & ecl.\ lat.\ & + ecliptic & equinox & R +\\ \hline +galactic & $l^{I\!I},b^{I\!I}$ & gal.\ long.\ & gal.\ lat.\ & + gal.\ equator & gal.\ centre & R +\\ \hline +supergalactic & SGL,SGB & SG long.\ & SG lat.\ & + SG equator & node w.\ gal.\ equ.\ & R +\\ \hline +\end{tabular} +\end{center} +Transformations between \hadec\ and \azel\ can be performed by +calling +sla\_E2H +and +sla\_H2E, +or, in double precision, +sla\_DE2H +and +sla\_DH2E. +There is also a routine for obtaining +zenith distance alone for a given \hadec, +sla\_ZD, +and one for determining the parallactic angle, +sla\_PA. +Three routines are included which relate to altazimuth telescope +mountings. For a given \hadec\ and latitude, +sla\_ALTAZ +returns the azimuth, elevation and parallactic angle, plus +velocities and accelerations for sidereal tracking. +The routines +sla\_PDA2H +and +sla\_PDQ2H +predict at what hour angle a given azimuth or +parallactic angle will be reached. + +The routines +sla\_EQECL +and +sla\_ECLEQ +transform between ecliptic +coordinates and \radec\/; there is also a routine for generating the +equatorial to ecliptic rotation matrix for a given date: +sla\_ECMAT. + +For conversion between Galactic coordinates and \radec\ there are +two sets of routines, depending on whether the \radec\ is +old-style, B1950, or new-style, J2000; +sla\_EG50 +and +sla\_GE50 +are \radec\ to \gal\ and {\it vice versa}\/ for the B1950 case, while +sla\_EQGAL +and +sla\_GALEQ +are the J2000 equivalents. + +Finally, the routines +sla\_GALSUP +and +sla\_SUPGAL +transform \gal\ to de~Vaucouleurs supergalactic longitude and latitude +and {\it vice versa.} + +It should be appreciated that the table, above, constitutes +a gross oversimplification. Apparently +simple concepts such as equator, equinox {\it etc.}\ are apt to be very hard to +pin down precisely (polar motion, orbital perturbations \ldots) and +some have several interpretations, all subtly different. The various +frames move in complicated ways with respect to one another or to +the stars (themselves in motion). And in some instances the +coordinate system is slightly distorted, so that the +ordinary rules of spherical trigonometry no longer strictly apply. + +These {\it caveats}\/ +apply particularly to the bewildering variety of different +\radec\ systems that are in use. Figure~1 shows how +some of these systems are related, to one another and +to the direction in which a celestial source actually +appears in the sky. At the top of the diagram are +the various sorts of {\it mean place}\/ +found in star catalogues and papers;\footnote{One frame not included in +Figure~1 is that of the Hipparcos catalogue. This is currently the +best available implementation in the optical of the {\it International +Celestial Reference System}\/ (ICRS), which is based on extragalactic +radio sources observed by VLBI. The distinction between FK5 J2000 +and Hipparcos coordinates only becomes important when accuracies of +50~mas or better are required. More details are given in +Section~4.14.} at the bottom is the +{\it observed}\/ \azel, where a perfect theodolite would +be pointed to see the source; and in the body of +the diagram are +the intermediate processing steps and coordinate +systems. To help +understand this diagram, and the SLALIB routines that can +be used to carry out the various calculations, we will look at the coordinate +systems involved, and the astronomical phenomena that +affect them. + +\begin{figure} +\begin{center} +\begin{tabular}{|cccccc|} \hline +& & & & & \\ +\hspace{5em} & \hspace{5em} & \hspace{5em} & + \hspace{5em} & \hspace{5em} & \hspace{5em} \\ +\multicolumn{2}{|c}{\hspace{0em}\fbox{\parbox{8.5em}{\center \vspace{-2ex} + mean \radec, FK4, \\ + any equinox + \vspace{0.5ex}}}} & + \multicolumn{2}{c}{\hspace{0em}\fbox{\parbox{8.5em}{\center \vspace{-2ex} + mean \radec, FK4, + no $\mu$, any equinox + \vspace{0.5ex}}}} & +\multicolumn{2}{c|}{\hspace{0em}\fbox{\parbox{8.5em}{\center \vspace{-2ex} + mean \radec, FK5, \\ + any equinox + \vspace{0.5ex}}}} \\ +& \multicolumn{2}{|c|}{} & \multicolumn{2}{c|}{} & \\ +\multicolumn{2}{|c}{space motion} & \multicolumn{1}{c|}{} & & + \multicolumn{2}{c|}{space motion} \\ +\multicolumn{2}{|c}{-- E-terms} & + \multicolumn{2}{c}{-- E-terms} & \multicolumn{1}{c|}{} & \\ +\multicolumn{2}{|c}{precess to B1950} & \multicolumn{2}{c}{precess to B1950} & + \multicolumn{2}{c|}{precess to J2000} \\ +\multicolumn{2}{|c}{+ E-terms} & + \multicolumn{2}{c}{+ E-terms} & \multicolumn{1}{c|}{} & \\ +\multicolumn{2}{|c}{FK4 to FK5, no $\mu$} & + \multicolumn{2}{c}{FK4 to FK5, no $\mu$} & \multicolumn{1}{c|}{} & \\ +\multicolumn{2}{|c}{parallax} & \multicolumn{1}{c|}{} & & + \multicolumn{2}{c|}{parallax} \\ +& \multicolumn{2}{|c|}{} & \multicolumn{2}{c|}{} & \\ \cline{2-5} +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{\parbox{18em}{\center \vspace{-2ex} + FK5, J2000, current epoch, geocentric + \vspace{0.5ex}}}} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{light deflection} & \\ +& \multicolumn{4}{c}{annual aberration} & \\ +& \multicolumn{4}{c}{precession/nutation} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{Apparent \radec}} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{Earth rotation} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{Apparent \hadec}} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{diurnal aberration} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{Topocentric \hadec}} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\hadec\ to \azel} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{Topocentric \azel}} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{refraction} & \\ +\multicolumn{3}{|c|}{} & & & \\ +& \multicolumn{4}{c}{\fbox{Observed \azel}} & \\ +& & & & & \\ +& & & & & \\ \hline +\end{tabular} +\end{center} +\vspace{-0.5ex} +\caption{Relationship Between Celestial Coordinates} + +Star positions are published or catalogued using +one of the mean \radec\ systems shown at +the top. The ``FK4'' systems +were used before about 1980 and are usually +equinox B1950. The ``FK5'' system, equinox J2000, is now preferred, +or rather its modern equivalent, the International Celestial Reference +Frame (in the optical, the Hipparcos catalogue). +The figure relates a star's mean \radec\ to the actual +line-of-sight to the star. +Note that for the conventional choices of equinox, namely +B1950 or J2000, all of the precession and E-terms corrections +are superfluous. +\end{figure} + +\subsection{Precession and Nutation} +{\it Right ascension and declination}, (\radec), are the names +of the longitude and latitude in a spherical +polar coordinate system based on the Earth's axis of rotation. +The zero point of $\alpha$ is the point of intersection of +the {\it celestial +equator}\/ and the {\it ecliptic}\/ (the apparent path of the Sun +through the year) where the Sun moves into the northern +hemisphere. This point is called the +{\it first point of Aries}, +the {\it vernal equinox}\/ (with apologies to +southern-hemisphere readers) or simply the {\it equinox}.\footnote{With +the introduction of the International Celestial Reference System (ICRS), the +connection between (i)~star coordinates and (ii)~the Earth's orientation +and orbit has been broken. However, the orientation of the +International Celestial Reference Frame (ICRF) axes was, for convenience, +chosen to match J2000 FK5, and for most practical purposes ICRF coordinates +(for example entries in the Hipparcos catalogue) can be regarded as +synonymous with J2000 FK5. See Section 4.14 for further details.} + +This simple picture is unfortunately +complicated by the difficulty of defining +a suitable equator and equinox. One problem is that the +Sun's apparent motion is not completely regular, due to the +ellipticity of the Earth's orbit and its continuous disturbance +by the Moon and planets. This is dealt with by +separating the motion into (i)~a smooth and steady {\it mean Sun}\/ +and (ii)~a set of periodic corrections and perturbations; only the former +is involved in establishing reference frames and timescales. +A second, far larger problem, is that +the celestial equator and the ecliptic +are both moving with respect to the stars. +These motions arise because of the gravitational +interactions between the Earth and the other solar-system bodies. + +By far the largest effect is the +so-called ``precession of the equinoxes'', where the Earth's +rotation axis sweeps out a cone centred on the ecliptic +pole, completing one revolution in about 26,000 years. The +cause of the motion is the torque exerted on the distorted and +spinning Earth by the Sun and the Moon. Consider the effect of the +Sun alone, at or near the northern summer solstice. The Sun +`sees' the top (north pole) of the Earth tilted towards it +(by about \degree{23}{5}, the {\it obliquity of the +ecliptic}\/), +and sees the nearer part of the Earth's equatorial bulge +below centre and the further part above centre. +Although the Earth is in free fall, +the gravitational force on the nearer part of the +equatorial bulge is greater than that on the further part, and +so there is a net torque acting +as if to eliminate the tilt. Six months later the same thing +is happening in reverse, except that the torque is still +trying to eliminate the tilt. In between (at the equinoxes) the +torque shrinks to zero. A torque acting on a spinning body +is gyroscopically translated +into a precessional motion of the spin axis at right-angles to the torque, +and this happens to the Earth. +The motion varies during the +year, going through two maxima, but always acts in the +same direction. The Moon produces the same effect, +adding a contribution to the precession which peaks twice +per month. The Moon's proximity to the Earth more than compensates +for its smaller mass and gravitational attraction, so that it +in fact contributes most of the precessional effect. + +The complex interactions between the three bodies produce a +precessional motion that is wobbly rather than completely smooth. +However, the main 26,000-year component is on such a grand scale that +it dwarfs the remaining terms, the biggest of +which has an amplitude of only \arcseci{17} and a period of +about 18.6~years. This difference of scale makes it convenient to treat +these two components of the motion separately. The main 26,000-year +effect is called {\it luni-solar precession}; the smaller, +faster, periodic terms are called the {\it nutation}. + +Note that precession and nutation are simply +different frequency components of the same physical effect. It is +a common misconception that precession is caused +by the Sun and nutation is caused by the Moon. In fact +the Moon is responsible for two-thirds of the precession, and, +while it is true that much of the complex detail of the nutation is +a reflection of the intricacies of the lunar orbit, there are +nonetheless important solar terms in the nutation. + +In addition to and quite separate +from the precession/nutation effect, the orbit of the Earth-Moon system +is not fixed in orientation, a result of the attractions of the +planets. This slow (about \arcsec{0}{5}~per~year) +secular rotation of the ecliptic about a slowly-moving diameter is called, +confusingly, {\it planetary +precession}\/ and, along with the luni-solar precession is +included in the {\it general precession}. The equator and +ecliptic as affected by general precession +are what define the various ``mean'' \radec\ reference frames. + +The models for precession and nutation come from a combination +of observation and theory, and are subject to continuous +refinement. Nutation models in particular have reached a high +degree of sophistication, taking into account such things as +the non-rigidity of the Earth and the effects of +the planets; SLALIB's nutation +model (IAU~1980) involves 106 terms in each of $\psi$ (longitude) +and $\epsilon$ (obliquity), some as small as \arcsec{0}{0001}. + +\subsubsection{SLALIB support for precession and nutation} +SLALIB offers a choice of three precession models: +\begin{itemize} +\item The old Bessel-Newcomb, pre IAU~1976, ``FK4'' model, used for B1950 + star positions and other pre-1984.0 purposes +(sla\_PREBN). +\item The new Fricke, IAU~1976, ``FK5'' model, used for J2000 star + positions and other post-1984.0 purposes +(sla\_PREC). +\item A model published by Simon {\it et al.}\ which is more accurate than + the IAU~1976 model and which is suitable for long + periods of time +(sla\_PRECL). +\end{itemize} +In each case, the named SLALIB routine generates the $(3\times3)$ +{\it precession +matrix}\/ for a given start and finish time. For example, +here is the Fortran code for generating the rotation +matrix which describes the precession between the epochs +J2000 and J1985.372 (IAU 1976 model): +\goodbreak +\begin{verbatim} + DOUBLE PRECISION PMAT(3,3) + : + CALL sla_PREC(2000D0,1985.372D0,PMAT) +\end{verbatim} +\goodbreak +It is instructive to examine the resulting matrix: +\goodbreak +\begin{verbatim} + +0.9999936402 +0.0032709208 +0.0014214694 + -0.0032709208 +0.9999946505 -0.0000023247 + -0.0014214694 -0.0000023248 +0.9999989897 +\end{verbatim} +\goodbreak +Note that the diagonal elements are close to unity, and the +other elements are small. This shows that over an interval as +short as 15~years the precession isn't going to move a +position vector very far (in this case about \degree{0}{2}). + +For convenience, a direct \radec\ to \radec\ precession routine is +also provided +(sla\_PRECES), +suitable for either the old or the new system (but not a +mixture of the two). + +SLALIB provides only one nutation model, the new, IAU~1980 model, +implemented in the routine +sla\_NUTC. +This returns the components of nutation +in longitude and latitude (and also provides the obliquity) from +which a nutation matrix can be generated by calling +sla\_DEULER +(and from which the {\it equation of the equinoxes}, described +later, can be found). Alternatively, +the nutation matrix can be generated in a single call by using +sla\_NUT. + +A rotation matrix for applying the entire precession/nutation +transformation in one go can be generated by calling +sla\_PRENUT. + +\subsection{Mean Places} +The main effect of the precession/nutation is a steady increase of about +\arcseci{50}/year in the ecliptic longitudes of the stars. It is therefore +essential, when reporting the position of an astronomical target, to +qualify the coordinates with a date, or {\it epoch}. +Specifying the epoch ties down the equator and +equinox which define the \radec\ coordinate system that is +being used. +\footnote{An equinox is, however, not required for coordinates +in the International Celestial Reference System. Such coordinates must +be labelled simply ``ICRS'', or the specific catalogue can be mentioned, +such as ``Hipparcos''; constructions such as ``Hipparcos, J2000'' are +redundant and misleading.} For simplicity, only +the smooth and steady ``general +precession'' part of the complete precession/nutation effect is +included, thereby defining what is called the {\it mean}\/ +equator and equinox for the epoch concerned. We say a star +has a mean place of (for example) +\hms{12}{07}{58}{09}~\dms{-19}{44}{37}{1} ``with respect to the mean equator +and equinox of epoch J2000''. The short way of saying +this is ``\radec\ equinox J2000'' ({\bf not} ``\radec\ epoch J2000'', +which means something different to do with +proper motion). + +\subsection{Epoch} +The word ``epoch'' just means a moment in time, and can be supplied +in a variety of forms, using different calendar systems and timescales. + +For the purpose of specifying the epochs associated with the +mean place of a star, two conventions exist. Both sorts of epoch +superficially resemble years AD but are not tied to the civil +(Gregorian) calendar; to distinguish them from ordinary calendar-years +there is often +a ``.0'' suffix (as in ``1950.0''), although any other fractional +part is perfectly legal ({\it e.g.}\ 1987.5). + +The older system, +{\it Besselian epoch}, is defined in such a way that its units are +tropical years of about 365.2422~days and its timescale is the +obsolete {\it Ephemeris Time}. +The start of the Besselian year is the moment +when the ecliptic longitude of the mean Sun is +$280^{\circ}$; this happens near the start of the +calendar year (which is why $280^{\circ}$ was chosen). + +The new system, {\it Julian epoch}, was adopted as +part of the IAU~1976 revisions (about which more will be said +in due course) and came formally into use at the +beginning of 1984. It uses the Julian year of exactly +365.25~days; Julian epoch 2000 is defined to be 2000~January~1.5 in the +TT timescale. + +For specifying mean places, various standard epochs are in use, the +most common ones being Besselian epoch 1950.0 and Julian epoch 2000.0. +To distinguish the two systems, Besselian epochs +are now prefixed ``B'' and Julian epochs are prefixed ``J''. +Epochs without an initial letter can be assumed to be Besselian +if before 1984.0, otherwise Julian. These details are supported by +the SLALIB routines +sla\_DBJIN +(decodes numbers from a +character string, accepting an optional leading B or J), +sla\_KBJ +(decides whether B or J depending on prefix or range) and +sla\_EPCO +(converts one epoch to match another). + +SLALIB has four routines for converting +Besselian and Julian epochs into other forms. +The functions +sla\_EPB2D +and +sla\_EPJ2D +convert Besselian and Julian epochs into MJD; the functions +sla\_EPB +and +sla\_EPJ +do the reverse. For example, to express B1950 as a Julian epoch: +\goodbreak +\begin{verbatim} + DOUBLE PRECISION sla_EPJ,sla_EPB2D + : + WRITE (*,'(1X,''J'',F10.5)') sla_EPJ(sla_EPB2D(1950D0)) +\end{verbatim} +\goodbreak +(The answer is J1949.99979.) + +\subsection{Proper Motion} +Stars in catalogues usually have, in addition to the +\radec\ coordinates, a {\it proper motion} $[\mu_\alpha,\mu_\delta]$. +This is an intrinsic motion +of the star across the background. Very few stars have a +proper motion which exceeds \arcseci{1}/year, and most are +far below this level. A star observed as part of normal +astronomy research will, as a rule, have a proper motion +which is unknown. + +Mean \radec\ and rate of change are not sufficient to pin +down a star; the epoch at which the \radec\ was or will +be correct is also needed. Note the distinction +between the epoch which specifies the +coordinate system and the epoch at which the star passed +through the given \radec. The full specification for a star +is \radec, proper motions, equinox and epoch (plus something to +identify which set of models for the precession {\it etc.}\ is +being used -- see the next section). +For convenience, coordinates given in star catalogues are almost +always adjusted to make the equinox and epoch the same -- for +example B1950 in the case of the SAO~catalogue. + +SLALIB provides one routine to handle proper motion on its own, +sla\_PM. +Proper motion is also allowed for in various other +routines as appropriate, for example +sla\_MAP +and +sla\_FK425. +Note that in all SLALIB routines which involve proper motion +the units are radians per year and the +$\alpha$ component is in the form $\dot{\alpha}$ ({\it i.e.}\ big +numbers near the poles). +Some star catalogues have proper motion per century, and +in some catalogues the $\alpha$ component is in the form +$\dot{\alpha}\cos\delta$ ({\it i.e.}\ angle on the sky). + +\subsection{Parallax and Radial Velocity} +For the utmost accuracy and the nearest stars, allowance can +be made for {\it annual parallax}\/ and for the effects of perspective +on the proper motion. + +Parallax is appreciable only for nearby stars; even +the nearest, Proxima Centauri, is displaced from its average +position by less than +an arcsecond as the Earth revolves in its orbit. + +For stars with a known parallax, knowledge of the radial velocity +allows the proper motion to be expressed as an actual space +motion in 3~dimensions. The proper motion is, +in fact, a snapshot of the transverse component of the +space motion, and in the case of nearby stars will +change with time due to perspective. + +SLALIB does not provide facilities for handling parallax +and radial-velocity on their own, but their contribution is +allowed for in such routines as +sla\_PM, +sla\_MAP +and +sla\_FK425. +Catalogue mean +places do not include the effects of parallax and are therefore +{\it barycentric}; when pointing telescopes {\it etc.}\ it is +usually most efficient to apply the slowly-changing +parallax correction to the mean place of the target early on +and to work with the {\it geocentric}\/ mean place. This latter +approach is implied in Figure~1. + +\subsection{Aberration} +The finite speed of light combined with the motion of the observer +around the Sun during the year causes apparent displacements of +the positions of the stars. The effect is called +the {\it annual aberration} (or ``stellar'' +aberration). Its maximum size, about \arcsec{20}{5}, +occurs for stars $90^{\circ}$ from the point towards which +the Earth is headed as it orbits the Sun; a star exactly in line with +the Earth's motion is not displaced. To receive the light of +a star, the telescope has to be offset slightly in the direction of +the Earth's motion. A familiar analogy is the need to tilt your +umbrella forward when on the move, to avoid getting wet. This +Newtonian model is, +in fact, highly misleading in the context of light as opposed +to rain, but happens to give the same answer as a relativistic +treatment to first order (better than 1~milliarcsecond). + +Before the IAU 1976 resolutions, different +values for the approximately +\arcsec{20}{5} {\it aberration constant}\/ were employed +at different times, and this can complicate comparisons +between different catalogues. Another complication comes from +the so-called {\it E-terms of aberration}, +that small part of the annual aberration correction that is a +function of the eccentricity of the Earth's orbit. The E-terms, +maximum amplitude about \arcsec{0}{3}, +happen to be approximately constant for a given star, and so they +used to be incorporated in the catalogue \radec\/ +to reduce the labour of converting to and from apparent place. +The E-terms can be removed from a catalogue \radec\/ by +calling +sla\_SUBET +or applied (for example to allow a pulsar +timing-position to be plotted on a B1950 finding chart) +by calling +sla\_ADDET; +the E-terms vector itself can be obtained by calling +sla\_ETRMS. +Star positions post IAU 1976 are free of these distortions, and to +apply corrections for annual aberration involves the actual +barycentric velocity of the Earth rather than the use of +canonical circular-orbit models. + +The annual aberration is the aberration correction for +an imaginary observer at the Earth's centre. +The motion of a real observer around the Earth's rotation axis in +the course of the day makes a small extra contribution to the total +aberration effect called the {\it diurnal aberration}. Its +maximum amplitude is about \arcsec{0}{2}. + +No SLALIB routine is provided for calculating the aberration on +its own, though the required velocity vectors can be +generated using +sla\_EVP +and +sla\_GEOC. +Annual and diurnal aberration are allowed for where required, for example in +sla\_MAP +{\it etc}.\ and +sla\_AOP +{\it etc}. Note that this sort +of aberration is different from the {\it planetary +aberration}, which is the apparent displacement of a solar-system +body, with respect to the ephemeris position, as a consequence +of the motion of {\it both}\/ the Earth and the source. The +planetary aberration can be computed either by correcting the +position of the solar-system body for light-time, followed by +the ordinary stellar aberration correction, or more +directly by expressing the position and velocity of the source +in the observer's frame and correcting for light-time alone. + +\subsection{Different Sorts of Mean Place} +A particularly confusing aspect of published mean places is that they +are sensitive to the precise way they were determined. A mean +place is not directly observable, even with fundamental +instruments such as transit circles, and to produce a mean +place will involve relying on some existing star catalogue, +for example the fundamental catalogues FK4 and FK5, +and applying given mathematical models of precession, nutation, +aberration and so on. +Note in particular that no star catalogue, +even a fundamental catalogue such as FK4 or +FK5, defines a coordinate system, strictly speaking; +it is merely a list of star positions and proper motions. +However, once the stars from a given catalogue +are used as position calibrators, {\it e.g.}\ for +transit-circle observations or for plate reductions, then a +broader sense of there being a coordinate grid naturally +arises, and such phrases as ``in the system of +the FK4'' can legitimately be employed. However, +there is no formal link between the +two concepts -- no ``standard least squares fit'' between +reality and the inevitably flawed catalogues.\footnote{This was +true until the inception of the International Celestial Reference +System, which is based on the idea of axes locked into the +distant background. The coordinates +of the extragalactic sources which realize these +axes have no individual significance; there is a ``no net rotation'' +condition which has to be satisfied each time any revisions take +place.} All such +catalogues suffer at some level from systematic, zonal distortions +of both the star positions and of the proper motions, +and include measurement errors peculiar to individual +stars. + +Many of these complications are of little significance except to +specialists. However, observational astronomers cannot +escape exposure to at least the two main varieties of +mean place, loosely called +FK4 and FK5, and should be aware of +certain pitfalls. For most practical purposes the more recent +system, FK5, is free of surprises and tolerates naive +use well. FK4, in contrast, contains two important traps: +\begin{itemize} +\item The FK4 system rotates at about + \arcsec{0}{5} per century relative to distant galaxies. + This is manifested as a systematic distortion in the + proper motions of all FK4-derived catalogues, which will + in turn pollute any astrometry done using those catalogues. + For example, FK4-based astrometry of a QSO using plates + taken decades apart will reveal a non-zero {\it fictitious proper + motion}, and any FK4 star which happens to have zero proper + motion is, in fact, slowly moving against the distant + background. The FK4 frame rotates because it was + established before the nature of the Milky Way, and hence the + existence of systematic motions of nearby stars, had been + recognized. +\item Star positions in the FK4 system are part-corrected for + annual aberration (see above) and embody the so-called + E-terms of aberration. +\end{itemize} +The change from the old FK4-based system to FK5 +occurred at the beginning +of 1984 as part of a package of resolutions made by the IAU in 1976, +along with the adoption of J2000 as the reference epoch. Star +positions in the newer, FK5, system are free from the E-terms, and +the system is a much better approximation to an +inertial frame (about five times better). + +It may occasionally be convenient to specify the FK4 fictitious proper +motion directly. In FK4, the centennial proper motion of (for example) +a QSO is: + +$\mu_\alpha=-$\tsec{0}{015869}$ + +(($\tsec{0}{029032}$~\sin \alpha + +$\tsec{0}{000340}$~\cos \alpha ) \sin \delta + -$\tsec{0}{000105}$~\cos \alpha + -$\tsec{0}{000083}$~\sin \alpha ) \sec \delta $ \\ +$\mu_\delta\,=+$\arcsec{0}{43549}$~\cos \alpha + -$\arcsec{0}{00510}$~\sin \alpha + + ($\arcsec{0}{00158}$~\sin \alpha + -$\arcsec{0}{00125}$~\cos \alpha ) \sin \delta + -$\arcsec{0}{00066}$~\cos \delta $ + +\subsection{Mean Place Transformations} +Figure~1 is based upon three varieties of mean \radec\ all of which are +of practical significance to observing astronomers in the present era: +\begin{itemize} + \item Old style (FK4) with known proper motion in the FK4 + system, and with parallax and radial velocity either + known or assumed zero. + \item Old style (FK4) with zero proper motion in FK5, + and with parallax and radial velocity assumed zero. + \item New style (FK5) with proper motion, parallax and + radial velocity either known or assumed zero. +\end{itemize} +The figure outlines the steps required to convert positions in +any of these systems to a J2000 \radec\ for the current +epoch, as might be required in a telescope-control +program for example. +Most of the steps can be carried out by calling a single +SLALIB routines; there are other SLALIB routines which +offer set-piece end-to-end transformation routines for common cases. +Note, however, that SLALIB does not set out to provide the capability +for arbitrary transformations of star-catalogue data +between all possible systems of mean \radec. +Only in the (common) cases of FK4, equinox and epoch B1950, +to FK5, equinox and epoch J2000, and {\it vice versa}\/ are +proper motion, parallax and radial velocity transformed +along with the star position itself, the +focus of SLALIB support. + +As an example of using SLALIB to transform mean places, here is +a program which implements the top-left path of Figure~1. +An FK4 \radec\ of arbitrary equinox and epoch and with +known proper motion and +parallax is transformed into an FK5 J2000 \radec\ for the current +epoch. As a test star we will use $\alpha=$\hms{16}{09}{55}{13}, +$\delta=$\dms{-75}{59}{27}{2}, equinox 1900, epoch 1963.087, +$\mu_\alpha=$\tsec{-0}{0312}$/y$, $\mu_\delta=$\arcsec{+0}{103}$/y$, +parallax = \arcsec{0}{062}, radial velocity = $-34.22$~km/s. The +epoch of observation is 1994.35. +\goodbreak +\begin{verbatim} + IMPLICIT NONE + DOUBLE PRECISION AS2R,S2R + PARAMETER (AS2R=4.8481368110953599D-6,S2R=7.2722052166430399D-5) + INTEGER J,I + DOUBLE PRECISION R0,D0,EQ0,EP0,PR,PD,PX,RV,EP1,R1,D1,R2,D2,R3,D3, + : R4,D4,R5,D5,R6,D6,EP1D,EP1B,W(3),EB(3),PXR,V(3) + DOUBLE PRECISION sla_EPB,sla_EPJ2D + + * RA, Dec etc of example star + CALL sla_DTF2R(16,09,55.13D0,R0,J) + CALL sla_DAF2R(75,59,27.2D0,D0,J) + D0=-D0 + EQ0=1900D0 + EP0=1963.087D0 + PR=-0.0312D0*S2R + PD=+0.103D0*AS2R + PX=0.062D0 + RV=-34.22D0 + EP1=1994.35D0 + + * Epoch of observation as MJD and Besselian epoch + EP1D=sla_EPJ2D(EP1) + EP1B=sla_EPB(EP1D) + + * Space motion to the current epoch + CALL sla_PM(R0,D0,PR,PD,PX,RV,EP0,EP1B,R1,D1) + + * Remove E-terms of aberration for the original equinox + CALL sla_SUBET(R1,D1,EQ0,R2,D2) + + * Precess to B1950 + R3=R2 + D3=D2 + CALL sla_PRECES('FK4',EQ0,1950D0,R3,D3) + + * Add E-terms for the standard equinox B1950 + CALL sla_ADDET(R3,D3,1950D0,R4,D4) + + * Transform to J2000, no proper motion + CALL sla_FK45Z(R4,D4,EP1B,R5,D5) + + * Parallax + CALL sla_EVP(sla_EPJ2D(EP1),2000D0,W,EB,W,W) + PXR=PX*AS2R + CALL sla_DCS2C(R5,D5,V) + DO I=1,3 + V(I)=V(I)-PXR*EB(I) + END DO + CALL sla_DCC2S(V,R6,D6) + : +\end{verbatim} +\goodbreak +It is interesting to look at how the \radec\ changes during the +course of the calculation: +\begin{tabbing} +xxxxxxxxxxxxxx \= xxxxxxxxxxxxxxxxxxxxxxxxx \= x \= \kill +\> {\tt 16 09 55.130 -75 59 27.20} \> \> {\it original equinox and epoch} \\ +\> {\tt 16 09 54.155 -75 59 23.98} \> \> {\it with space motion} \\ +\> {\tt 16 09 54.229 -75 59 24.18} \> \> {\it with old E-terms removed} \\ +\> {\tt 16 16 28.213 -76 06 54.57} \> \> {\it precessed to 1950.0} \\ +\> {\tt 16 16 28.138 -76 06 54.37} \> \> {\it with new E-terms} \\ +\> {\tt 16 23 07.901 -76 13 58.87} \> \> {\it J2000, current epoch} \\ +\> {\tt 16 23 07.907 -76 13 58.92} \> \> {\it including parallax} +\end{tabbing} + +Other remarks about the above (unusually complicated) example: +\begin{itemize} +\item If the original equinox and epoch were B1950, as is quite + likely, then it would be unnecessary to treat space motions + and E-terms explicitly. Transformation to FK5 J2000 could + be accomplished simply by calling +sla\_FK425, after which + a call to +sla\_PM and the parallax code would complete the + work. +\item The rigorous treatment of the E-terms + has only a small effect on the result. Such refinements + are, nevertheless, worthwhile in order to facilitate comparisons and + to increase the chances that star positions from different + suppliers are compatible. +\item The FK4 to FK5 transformations, +sla\_FK425 + and +sla\_FK45Z, + are not as is sometimes assumed simply 50 years of precession, + though this indeed accounts for most of the change. The + transformations also include adjustments + to the equinox, a revised precession model, elimination of the + E-terms, a change to the proper-motion time unit and so on. + The reason there are two routines rather than just one + is that the FK4 frame rotates relative to the background, whereas + the FK5 frame is a much better approximation to an + inertial frame, and zero proper + motion in FK4 does not, therefore, mean zero proper motion in FK5. + SLALIB also provides two routines, +sla\_FK524 + and +sla\_FK54Z, + to perform the inverse transformations. +\item Some star catalogues (FK4 itself is one) were constructed using slightly + different procedures for the polar regions compared with + elsewhere. SLALIB ignores this inhomogeneity and always + applies the standard + transformations irrespective of location on the celestial sphere. +\end{itemize} + +\subsection {Mean Place to Apparent Place} +The {\it geocentric apparent place}\/ of a source, or {\it apparent place}\/ +for short, +is the \radec\ if viewed from the centre of the Earth, +with respect to the true equator and equinox of date. +Transformation of an FK5 mean \radec, equinox J2000, +current epoch, to apparent place involves the following effects: +\goodbreak +\begin{itemize} + \item Light deflection -- the gravitational lens effect of + the sun. + \item Annual aberration. + \item Precession/nutation. +\end{itemize} +The {\it light deflection}\/ is seldom significant. Its value +at the limb of the Sun is about +\arcsec{1}{74}; it falls off rapidly with distance from the +Sun and has shrunk to about +\arcsec{0}{02} at an elongation of $20^\circ$. + +As already described, the {\it annual aberration}\/ +is a function of the Earth's velocity +relative to the solar system barycentre (available through the +SLALIB routine +sla\_EVP) +and produces shifts of up to about \arcsec{20}{5}. + +The {\it precession/nutation}, from J2000 to the current epoch, is +expressed by a rotation matrix which is available through the +SLALIB routine +sla\_PRENUT. + +The whole mean-to-apparent transformation can be done using the SLALIB +routine +sla\_MAP. As a demonstration, here is a program which lists the +{\it North Polar Distance}\/ ($90^\circ-\delta$) of Polaris for +the decade of closest approach to the Pole: +\goodbreak +\begin{verbatim} + IMPLICIT NONE + DOUBLE PRECISION PI,PIBY2,D2R,S2R,AS2R + PARAMETER (PI=3.141592653589793238462643D0) + PARAMETER (D2R=PI/180D0, + : PIBY2=PI/2D0, + : S2R=PI/(12D0*3600D0), + : AS2R=PI/(180D0*3600D0)) + DOUBLE PRECISION RM,DM,PR,PD,DATE,RA,DA + INTEGER J,IDS,IDE,ID,IYMDF(4),I + DOUBLE PRECISION sla_EPJ2D + + CALL sla_DTF2R(02,31,49.8131D0,RM,J) + CALL sla_DAF2R(89,15,50.661D0,DM,J) + PR=+21.7272D0*S2R/100D0 + PD=-1.571D0*AS2R/100D0 + WRITE (*,'(1X,'// + : '''Polaris north polar distance (deg) 2096-2105''/)') + WRITE (*,'(4X,''Date'',7X''NPD''/)') + CALL sla_CLDJ(2096,1,1,DATE,J) + IDS=NINT(DATE) + CALL sla_CLDJ(2105,12,31,DATE,J) + IDE=NINT(DATE) + DO ID=IDS,IDE,10 + DATE=DBLE(ID) + CALL sla_DJCAL(0,DATE,IYMDF,J) + CALL sla_MAP(RM,DM,PR,PD,0D0,0D0,2000D0,DATE,RA,DA) + WRITE (*,'(1X,I4,2I3.2,F9.5)') (IYMDF(I),I=1,3),(PIBY2-DA)/D2R + END DO + + END +\end{verbatim} +\goodbreak +For cases where the transformation has to be repeated for different +times or for more than one star, the straightforward +sla\_MAP +approach is apt to be +wasteful as both the Earth velocity and the +precession/nutation matrix can be re-calculated relatively +infrequently without ill effect. A more efficient method is to +perform the target-independent calculations only when necessary, +by calling +sla\_MAPPA, +and then to use either +sla\_MAPQKZ, +when only the \radec\/ is known, or +sla\_MAPQK, +when full catalogue positions, including proper motion, parallax and +radial velocity, are available. How frequently to call +sla\_MAPPA +depends on the accuracy objectives; once per +night will deliver sub-arcsecond accuracy for example. + +The routines +sla\_AMP +and +sla\_AMPQK +allow the reverse transformation, from apparent to mean place. + +\subsection{Apparent Place to Observed Place} +The {\it observed place}\/ of a source is its position as +seen by a perfect theodolite at the location of the +observer. Transformation of an apparent \radec\ to observed +place involves the following effects: +\goodbreak +\begin{itemize} + \item \radec\ to \hadec. + \item Diurnal aberration. + \item \hadec\ to \azel. + \item Refraction. +\end{itemize} +The transformation from apparent \radec\ to +apparent \hadec\ is made by allowing for +{\it Earth rotation}\/ through the {\it sidereal time}, $\theta$: +\[ h = \theta - \alpha \] +For this equation to work, $\alpha$ must be the apparent right +ascension for the time of observation, and $\theta$ must be +the {\it local apparent sidereal time}. The latter is obtained +as follows: +\begin{enumerate} +\item from civil time obtain the coordinated universal time, UTC + (more later on this); +\item add the UT1$-$UTC (typically a few tenths of a second) to + give the UT; +\item from the UT compute the Greenwich mean sidereal time (using +sla\_GMST); +\item add the observer's (east) longitude, giving the local mean + sidereal time; +\item add the equation of the equinoxes (using +sla\_EQEQX). +\end{enumerate} +The {\it equation of the equinoxes}\/~($=\Delta\psi\cos\epsilon$ plus +small terms) +is the effect of nutation on the sidereal time. +Its value is typically a second or less. It is +interesting to note that if the object of the exercise is to +transform a mean place all the way into an observed place (very +often the case), +then the equation of the +equinoxes and the longitude component of nutation can both be +omitted, removing a great deal of computation. However, SLALIB +follows the normal convention and works {\it via}\/ the apparent place. + +Note that for very precise work the observer's longitude should +be corrected for {\it polar motion}. This can be done with +sla\_POLMO. +The corrections are always less than about \arcsec{0}{3}, and +are futile unless the position of the observer's telescope is known +to better than a few metres. + +Tables of observed and +predicted UT1$-$UTC corrections and polar motion data +are published every few weeks by the International Earth Rotation Service. + +The transformation from apparent \hadec\ to {\it topocentric}\/ +\hadec\ consists of allowing for +{\it diurnal aberration}. This effect, maximum amplitude \arcsec{0}{2}, +was described earlier. There is no specific SLALIB routine +for computing the diurnal aberration, +though the routines +sla\_AOP {\it etc.}\ +include it, and the required velocity vector can be +determined by calling +sla\_GEOC. + +The next stage is the major coordinate rotation from local equatorial +coordinates \hadec\ into horizon coordinates. The SLALIB routines +sla\_E2H +{\it etc.}\ can be used for this. For high-precision +applications the mean geodetic latitude should be corrected for polar +motion. + +\subsubsection{Refraction} +The final correction is for atmospheric refraction. +This effect, which depends on local meteorological conditions and +the effective colour of the source/detector combination, +increases the observed elevation of the source by a +significant effect even at moderate zenith distances, and near the +horizon by over \degree{0}{5}. The amount of refraction can by +computed by calling the SLALIB routine +sla\_REFRO; +however, +this requires as input the observed zenith distance, which is what +we are trying to predict. For high precision it is +therefore necessary to iterate, using the topocentric +zenith distance as the initial estimate of the +observed zenith distance. + +The full +sla\_REFRO refraction calculation is onerous, and for +zenith distances of less than, say, $75^{\circ}$ the following +model can be used instead: + +\[ \zeta _{vac} \approx \zeta _{obs} + + A \tan \zeta _{obs} + + B \tan ^{3}\zeta _{obs} \] +where $\zeta _{vac}$ is the topocentric +zenith distance (i.e.\ {\it in vacuo}), +$\zeta _{obs}$ is the observed +zenith distance (i.e.\ affected by refraction), and $A$ and $B$ are +constants, about \arcseci{60} +and \arcsec{-0}{06} respectively for a sea-level site. +The two constants can be calculated for a given set of conditions +by calling either +sla\_REFCO or +sla\_REFCOQ. + +sla\_REFCO works by calling +sla\_REFRO for two zenith distances and fitting $A$ and $B$ +to match. The calculation is onerous, but delivers accurate +results whatever the conditions. +sla\_REFCOQ uses a direct formulation of $A$ and $B$ and +is much faster; it is slightly less accurate than +sla\_REFCO but more than adequate for most practical purposes. + +Like the full refraction model, the two-term formulation works in the wrong +direction for our purposes, predicting +the {\it in vacuo}\/ (topocentric) zenith distance +given the refracted (observed) zenith distance, +rather than {\it vice versa}. The obvious approach of +interchanging $\zeta _{vac}$ and $\zeta _{obs}$ and +reversing the signs, though approximately +correct, gives avoidable errors which are just significant in +some applications; for +example about \arcsec{0}{2} at $70^\circ$ zenith distance. A +much better result can easily be obtained, by using one Newton-Raphson +iteration as follows: + +\[ \zeta _{obs} \approx \zeta _{vac} + - \frac{A \tan \zeta _{vac} + B \tan ^{3}\zeta _{vac}} + {1 + ( A + 3 B \tan ^{2}\zeta _{vac} ) \sec ^{2}\zeta _{vac}}\] + +The effect of refraction can be applied to an unrefracted +zenith distance by calling +sla\_REFZ or to an unrefracted +\xyz\ by calling +sla\_REFV. +Over most of the sky these two routines deliver almost identical +results, but beyond $\zeta=83^\circ$ +sla\_REFV +becomes unacceptably inaccurate while +sla\_REFZ +remains usable. (However +sla\_REFV +is significantly faster, which may be important in some applications.) +SLALIB also provides a routine for computing the airmass, the function +sla\_AIRMAS. + +The refraction ``constants'' returned by +sla\_REFCO and +sla\_REFCOQ +are slightly affected by colour, especially at the blue end +of the spectrum. Where values for more than one +wavelength are needed, rather than calling +sla\_REFCO +several times it is more efficient to call +sla\_REFCO +just once, for a selected ``base'' wavelength, and then to call +sla\_ATMDSP +once for each wavelength of interest. + +All the SLALIB refraction routines work for radio wavelengths as well +as the optical/IR band. The radio refraction is very dependent on +humidity, and an accurate value must be supplied. There is no +wavelength dependence, however. The choice of optical/IR or +radio is made by specifying a wavelength greater than $100\mu m$ +for the radio case. + +\subsubsection{Efficiency considerations} +The complete apparent place to observed place transformation +can be carried out by calling +sla\_AOP. +For improved efficiency +in cases of more than one star or a sequence of times, the +target-independent calculations can be done once by +calling +sla\_AOPPA, +the time can be updated by calling +sla\_AOPPAT, +and +sla\_AOPQK +can then be used to perform the +apparent-to-observed transformation. The reverse transformation +is available through +sla\_OAP +and +sla\_OAPQK. +({\it n.b.}\ These routines use accurate but computationally-expensive +refraction algorithms for zenith distances beyond about $76^\circ$. +For many purposes, in-line code tailored to the accuracy requirements +of the application will be preferable, for example ignoring UT1$-$UTC, +omitting diurnal aberration and using +sla\_REFZ +to apply the refraction.) + +\subsection{The Hipparcos Catalogue and the ICRS} +With effect from the beginning of 1998, the IAU adopted a new +reference system to replace FK5 J2000. The new system, called the +International Celestial Reference System (ICRS), differs profoundly +from all predecessors in that the link with solar-system dynamics +was broken; the ICRS axes are defined in terms of the directions +of a set of extragalactic sources, not in terms of the mean equator and +equinox at a given reference epoch. Although the ICRS and FK5 coordinates +of any given object are almost the same, the orientation of the new frame +was essentially arbitrary, and the close match to FK5 J2000 was contrived +purely for reasons of continuity and convenience. + +A distinction is made between the reference {\it system}\/ (the ICRS) +and {\it frame}\/ (ICRF). The ICRS is the set of prescriptions and +conventions together with the modelling required to define, at any +time, a triad of axes. The ICRF is a practical realization, and +currently consists of a catalogue of equatorial coordinates for 608 +extragalactic radio sources observed by VLBI. + +The best optical realization of the ICRF currently available is the +Hipparcos catalogue. The extragalactic sources were not directly +observable by the Hipparcos satellite and so the link from Hipparcos +to ICRF was established through a variety of indirect techniques: VLBI and +conventional interferometry of radio stars, photographic astrometry +and so on. The Hipparcos frame is aligned to the ICRF to within about +0.5~mas and 0.5~mas/year (at epoch 1991.25). + +The Hipparcos catalogue includes all of the FK5 stars, which has enabled +the orientation and spin of the latter to be studied. At epoch J2000, +the misalignment of the FK5 frame with respect to Hipparcos +(and hence ICRS) are about 32~mas and 1~mas/year respectively. +Consequently, for many practical purposes, including pointing +telescopes, the IAU 1976-1982 conventions on reference frames and +Earth orientation remain adequate and there is no need to change to +Hipparcos coordinates, new precession/nutation models and so on. +However, for the most exacting astrometric applications, SLALIB +provides some support for Hipparcos coordinates in the form of +four new routines: +sla\_FK52H and +sla\_H2FK5, +which transform FK5 positions and proper motions to the Hipparcos frame +and {\it vice versa,}\/ and +sla\_FK5HZ and +sla\_HFK5Z, +where the transformations are for stars whose Hipparcos proper motion is +zero. + +Further information on the ICRS can be found in the paper by M.\,Feissel +and F.\,Mignard, Astron.\,Astrophys. 331, L33-L36 (1988). + +\subsection{Timescales} +SLALIB provides for conversion between several timescales, and involves +use of one or two others. The full list is as follows: +\begin{itemize} +\item TAI: International Atomic Time +\item UTC: Coordinated Universal Time +\item UT: Universal Time +\item GMST: Greenwich Mean Sidereal Time +\item LAST: Local Apparent Sidereal Time +\item TT: Terrestrial Time +\item TDB: Barycentric Dynamical Time. +\end{itemize} +Three obsolete timescales should be mentioned here to avoid confusion. +\begin{itemize} +\item GMT: Greenwich Mean Time -- can mean either UTC or UT. +\item ET: Ephemeris Time -- more or less the same as either TT or TDB. +\item TDT: Terrestrial Dynamical Time -- former name of TT. +\end{itemize} + +\subsubsection{Atomic Time: TAI} +{\it International Atomic Time}\/ TAI is a laboratory timescale. Its +unit is the SI second, which is defined in terms of a +defined number +of wavelengths of the radiation produced by a certain electronic +transition in the caesium 133 atom. It +is realized through a changing +population of high-precision atomic clocks held +at standards institutes in various countries. There is an +elaborate process of continuous intercomparison, leading to +a weighted average of all the clocks involved. + +Though TAI shares the same second as the more familiar UTC, the +two timescales are noticeably separated in epoch because of the +build-up of leap seconds. At the time of writing, UTC +lags about half a minute behind TAI. + +For any given date, the difference TAI$-$UTC +can be obtained by calling the SLALIB routine +sla\_DAT. +Note, however, that an up-to-date copy of the routine must be used if +the most recent leap seconds are required. For applications +where this is critical, mechanisms independent of SLALIB +and under local control must +be set up; in such cases +sla\_DAT +can be useful as an +independent check, for test dates within the range of the +available version. Up-to-date information on TAI$-$UTC is available +from {\tt ftp://maia.usno.navy.mil/ser7/tai-utc.dat}. + +\subsubsection{Universal Time: UTC, UT1} +{\it Coordinated Universal Time}\/ UTC is the basis of civil timekeeping. +Most time zones differ from UTC by an integer number +of hours, though a few ({\it e.g.}\ parts of Canada and Australia) differ +by $n+0.5$~hours. The UTC second is the same as the SI second, +as for TAI. In the long term, UTC keeps in step with the +Sun. It does so even though the Earth's rotation is slightly +variable (due to large scale movements of water and atmosphere +among other things) by occasionally introducing a {\it leap +second}. + +{\it Universal Time}\/ UT, or more specifically UT1, +is in effect the mean solar time. It is continuous +({\it i.e.}\ there are no leap seconds) but has a variable +rate because of the Earth's non-uniform rotation period. It is +needed for computing the sidereal time, an essential part of +pointing a telescope at a celestial source. To obtain UT1, you +have to look up the value of UT1$-$UTC for the date concerned +in tables published by the International Earth Rotation +Service; this quantity, kept in the range +$\pm$\tsec{0}{9} by means of UTC leap +seconds, is then added to the UTC. The quantity UT1$-$UTC, +which typically changes by 1 or 2~ms per day, +can only be obtained by observation, though seasonal trends +are known and the IERS listings are able to predict some way into +the future with adequate accuracy for pointing telescopes. + +UTC leap seconds are introduced as necessary, +usually at the end of December or June. +On the average the solar day is slightly longer +than the nominal 86,400~SI~seconds and so leap seconds are always positive; +however, provision exists for negative leap seconds if needed. +The form of a leap second can be seen from the +following description of the end of June~1994: + +\hspace{3em} +\begin{tabular}{clrccc} \\ + & & & UTC & UT1$-$UTC & UT1 \\ \\ +1994 & June & 30 & 23 59 58 & $-0.218$ & 23 59 57.782 \\ + & & & 23 59 59 & $-0.218$ & 23 59 58.782 \\ + & & & 23 59 60 & $-0.218$ & 23 59 59.782 \\ + & July & 1 & 00 00 00 & $+0.782$ & 00 00 00.782 \\ + & & & 00 00 01 & $+0.782$ & 00 00 01.782 \\ +\end{tabular} + +Note that UTC has to be expressed as hours, minutes and +seconds (or at least in seconds for a given date) if leap seconds +are to be taken into account. It is improper to express a UTC as a +Julian Date, for example, because there will be an ambiguity +during a leap second (in the above example, +1994~June~30 \hms{23}{59}{60}{0} and +1994~July~1 \hms{00}{00}{00}{0} would {\it both}\/ come out as +MJD~49534.00000). Although in the vast majority of +cases this won't matter, there are potential problems in +on-line data acquisition systems and in applications involving +taking the difference between two times. Note that although the routines +sla\_DAT +and +sla\_DTT +expect UTC in the form of an MJD, the meaning here is really a +whole-number {\it date}\/ rather than a time. Though the routines will accept +a fractional part and will almost always function correctly, on a day +which ends with a leap +second incorrect results would be obtained during the leap second +itself because by then the MJD would have moved into the next day. + +\subsubsection{Sidereal Time: GMST, LAST} +Sidereal Time is the ``time of day'' relative to the +stars rather than to the Sun. After +one sidereal day the stars come back to the same place in the +sky, apart from sub-arcsecond precession effects. Because the Earth +rotates faster relative to the stars than to the Sun by one day +per year, the sidereal second is shorter than the solar +second; the ratio is about 0.9973. + +The {\it Greenwich Mean Sidereal Time}\/ GMST is +linked to UT1 by a numerical formula which +is implemented in the SLALIB routines +sla\_GMST +and +sla\_GMSTA. +There are, of course, no leap seconds in GMST, but the second +changes in length along with the UT1 second, and also varies +over long periods of time because of slow changes in the Earth's +orbit. This makes the timescale unsuitable for everything except +predicting the apparent directions of celestial sources. + +The {\it Local Apparent Sidereal Time}\/ LAST is the apparent right +ascension of the local meridian, from which the hour angle of any +star can be determined knowing its $\alpha$. It can be obtained from the +GMST by adding the east longitude (corrected for polar motion +in precise work) and the {\it equation of the equinoxes}. The +latter, already described, is an aspect of the nutation effect +and can be predicted by calling the SLALIB routine +sla\_EQEQX +or, neglecting certain very small terms, by calling +sla\_NUTC +and using the expression $\Delta\psi\cos\epsilon$. + +\subsubsection{Dynamical Time: TT, TDB} +Dynamical time is the independent variable in the theories +which describe the motions of bodies in the solar system. When +you use published formulae which model the position of the +Earth in its orbit, for example, or look up +the Moon's position in a precomputed ephemeris, the date and time +you use must be in terms of one of the dynamical timescales. It +is a common but understandable mistake to use UT directly, in which +case the results will be about 1~minute out (in the present +era). + +It is not hard to see why such timescales are necessary. +UTC would clearly be unsuitable as the argument of an +ephemeris because of leap seconds. +A solar-system ephemeris based on UT1 or sidereal time would somehow +have to include the unpredictable variations of the Earth's rotation. +TAI would work, but eventually +the ephemeris and the ensemble of atomic clocks would drift apart. +In effect, the ephemeris {\it is}\/ a clock, with the bodies of +the solar system the hands. + +Only two of the dynamical timescales are of any great importance to +observational astronomers, TT and TDB. (The obsolete +timescale ET, ephemeris time, was more or less the same as TT.) + +{\it Terrestrial Time}\/ TT is +the theoretical timescale of apparent geocentric ephemerides of solar +system bodies. It applies, in principle, +to an Earthbound clock, at sea-level, and for practical purposes +it is tied to +Atomic Time TAI through the formula TT~$=$~TAI~$+$~\tsec{32}{184}. +In practice, therefore, the units of TT are ordinary SI seconds, and +the offset of \tsec{32}{184} with respect to TAI is fixed. +The SLALIB routine +sla\_DTT +returns TT$-$UTC for a given UTC +({\it n.b.}\ sla\_DTT +calls +sla\_DAT, +and the latter must be an up-to-date version if recent leap seconds are +to be taken into account). + +{\it Barycentric Dynamical Time}\/ TDB differs from TT by an amount which +cycles back and forth by a millisecond or two due to +relativistic effects. The variation is +negligible for most purposes, but unless taken into +account would swamp +long-term analysis of pulse arrival times from the +millisecond pulsars. It is a consequence of +the TT clock being on the Earth rather than in empty +space: the ellipticity of +the Earth's orbit means that the TT clock's speed and +gravitational potential vary slightly +during the course of the year, and as a consequence +its rate as seen from an outside observer +varies due to transverse Doppler effect and gravitational +redshift. By definition, TDB and TT differ only +by periodic terms, and the main effect +is a sinusoidal variation of amplitude \tsec{0}{0016}; the +largest planetary terms are nearly two orders of magnitude +smaller. The SLALIB routine +sla\_RCC +provides a model of +TDB-TT accurate to a few nanoseconds. +There are other dynamical timescales, not supported by +SLALIB routines, which include allowance also for the secular terms. +These timescales gain on TT and TDB by about \tsec{0}{0013}/day. + +For most purposes the more accessible TT is the timescale to use, +for example when calling +sla\_PRENUT +to generate a precession/nutation matrix or when calling +sla\_EVP +to predict the +Earth's position and velocity. For some purposes TDB is the +correct timescale, for example when interrogating the JPL planetary +ephemeris (see {\it Starlink User Note~87}\/), though in most cases +TT will be near enough and will involve less computation. + +Investigations of topocentric solar-system phenomena such as +occultations and eclipses require solar time as well as dynamical +time. TT/TDB/ET is all that is required in order to compute the geocentric +circumstances, but if horizon coordinates or geocentric parallax +are to be tackled UT is also needed. A rough estimate +of $\Delta {\rm T} = {\rm ET} - {\rm UT}$ is +available via the routine +sla\_DT. +For a given epoch ({\it e.g.}\ 1650) this returns an approximation +to $\Delta {\rm T}$ in seconds. + +\subsection{Calendars} +The ordinary {\it Gregorian Calendar Date}, +together with a time of day, can be +used to express an epoch in any desired timescale. For many purposes, +however, a continuous count of days is more convenient, and for +this purpose the system of {\it Julian Day Number}\/ can be used. +JD zero is located about 7000~years ago, well before the +historical era, and is formally defined in terms of Greenwich noon; +Julian Day Number 2449444 began at noon on 1994 April~1. {\it Julian Date}\/ +is the same system but with a fractional part appended; +Julian Date 2449443.5 was the midnight on which 1994 April~1 +commenced. Because of the unwieldy size of Julian Dates +and the awkwardness of the half-day offset, it is +accepted practice to remove the leading `24' and the trailing `.5', +producing what is called the {\it Modified Julian Date}: +MJD~=~JD$-2400000.5$. SLALIB routines use MJD, as opposed to +JD, throughout, largely to avoid loss of precision. +1994 April~1 commenced at MJD~49443.0. + +Despite JD (and hence MJD) being defined in terms of (in effect) +UT, the system can be used in conjunction with other timescales +such as TAI, TT and TDB (and even sidereal time through the +concept of {\it Greenwich Sidereal Date}). However, it is improper +to express a UTC as a JD or MJD because of leap seconds. + +SLALIB has six routines for converting to and from dates in +the Gregorian calendar. The routines +sla\_CLDJ +and +sla\_CALDJ +both convert a calendar date into an MJD, the former interpreting +years between 0 and 99 as 1st century and the latter as late 20th or +early 21st century. The routines sla\_DJCL +and +sla\_DJCAL +both convert an MJD into calendar year, month, day and fraction of a day; +the latter performs rounding to a specified precision, important +to avoid dates like `{\tt 94 04 01.***}' appearing in messages. +Some of SLALIB's low-precision ephemeris routines +(sla\_EARTH, +sla\_MOON +and +sla\_ECOR) +work in terms of year plus day-in-year (where +day~1~=~January~1st, at least for the modern era). +This form of date can be generated by +calling +sla\_CALYD +(which defaults years 0-99 into 1950-2049) +or +sla\_CLYD +(which covers the full range from prehistoric times). + +\subsection{Geocentric Coordinates} +The location of the observer on the Earth is significant in a +number of ways. The most obvious, of course, is the effect of latitude +on the observed \azel\ of a star. Less obvious is the need to +allow for geocentric parallax when finding the Moon with a +telescope (and when doing high-precision work involving the +Sun or planets), and the need to correct observed radial +velocities and apparent pulsar periods for the effects +of the Earth's rotation. + +The SLALIB routine +sla\_OBS +supplies details of groundbased observatories from an internal +list. This is useful when writing applications that apply to +more than one observatory; the user can enter a brief name, +or browse through a list, and be spared the trouble of typing +in the full latitude, longitude {\it etc}. The following +Fortran code returns the full name, longitude and latitude +of a specified observatory: +\goodbreak +\begin{verbatim} + CHARACTER IDENT*10,NAME*40 + DOUBLE PRECISION W,P,H + : + CALL sla_OBS(0,IDENT,NAME,W,P,H) + IF (NAME.EQ.'?') ... (not recognized) +\end{verbatim} +\goodbreak +(Beware of the longitude sign convention, which is west +ve +for historical reasons.) The following lists all +the supported observatories: +\goodbreak +\begin{verbatim} + : + INTEGER N + : + N=1 + NAME=' ' + DO WHILE (NAME.NE.'?') + CALL sla_OBS(N,IDENT,NAME,W,P,H) + IF (NAME.NE.'?') THEN + WRITE (*,'(1X,I3,4X,A,4X,A)') N,IDENT,NAME + N=N+1 + END IF + END DO +\end{verbatim} +\goodbreak +The routine +sla\_GEOC +converts a {\it geodetic latitude}\/ +(one referred to the local horizon) to a geocentric position, +taking into account the Earth's oblateness and also the height +above sea level of the observer. The results are expressed in +vector form, namely as the distance of the observer from +the spin axis and equator respectively. The {\it geocentric +latitude}\/ can be found be evaluating ATAN2 of the +two numbers. A full 3-D vector description of the position +and velocity of the observer is available through the routine +sla\_PVOBS. +For a specified geodetic latitude, height above +sea level, and local sidereal time, +sla\_PVOBS +generates a 6-element vector containing the position and +velocity with respect to the true equator and equinox of +date ({\it i.e.}\ compatible with apparent \radec). For +some applications it will be necessary to convert to a +mean \radec\ frame (notably FK5, J2000) by multiplying +elements 1-3 and 4-6 respectively with the appropriate +precession matrix. (In theory an additional correction to the +velocity vector is needed to allow for differential precession, +but this correction is always negligible.) + +See also the discussion of the routine +sla\_RVEROT, +later. + +\subsection{Ephemerides} +SLALIB includes routines for generating positions and +velocities of Solar-System bodies. The accuracy objectives are +modest, and the SLALIB facilities do not attempt +to compete with precomputed ephemerides such as +those provided by JPL, or with models containing +thousands of terms. It is also worth noting +that SLALIB's very accurate star coordinate conversion +routines are not strictly applicable to solar-system cases, +though they are adequate for most practical purposes. + +Earth/Sun ephemerides can be generated using the routine +sla\_EVP, +which predicts Earth position and velocity with respect to both the +solar-system barycentre and the +Sun. Maximum velocity error is 0.42~metres per second; maximum +heliocentric position error is 1600~km (about \arcseci{2}), with +barycentric position errors about 4 times worse. +(The Sun's position as +seen from the Earth can, of course, be obtained simply by +reversing the signs of the Cartesian components of the +Earth\,:\,Sun vector.) + +Geocentric Moon ephemerides are available from +sla\_DMOON, +which predicts the Moon's position and velocity with respect to +the Earth's centre. Direction accuracy is usually better than +10~km (\arcseci{5}) and distance accuracy a little worse. + +Lower-precision but faster predictions for the Sun and Moon +can be made by calling +sla\_EARTH +and +sla\_MOON. +Both are single precision and accept dates in the form of +year, day-in-year and fraction of day +(starting from a calendar date you need to call +sla\_CLYD +or +sla\_CALYD +to get the required year and day). +The +sla\_EARTH +routine returns the heliocentric position and velocity +of the Earth's centre for the mean equator and +equinox of date. The accuracy is better than 20,000~km in position +and 10~metres per second in speed. +The +position and velocity of the Moon with respect to the +Earth's centre for the mean equator and ecliptic of date +can be obtained by calling +sla\_MOON. +The positional accuracy is better than \arcseci{30} in direction +and 1000~km in distance. + +Approximate ephemerides for all the major planets +can be generated by calling +sla\_PLANET +or +sla\_RDPLAN. These routines offer arcminute accuracy (much +better for the inner planets and for Pluto) over a span of several +millennia (but only $\pm100$ years for Pluto). +The routine +sla\_PLANET produces heliocentric position and +velocity in the form of equatorial \xyzxyzd\ for the +mean equator and equinox of J2000. The vectors +produced by +sla\_PLANET +can be used in a variety of ways according to the +requirements of the application concerned. The routine +sla\_RDPLAN +uses +sla\_PLANET +and +sla\_DMOON +to deal with the common case of predicting +a planet's apparent \radec\ and angular size as seen by a +terrestrial observer. + +Note that in predicting the position in the sky of a solar-system body +it is necessary to allow for geocentric parallax. This correction +is {\it essential}\/ in the case of the Moon, where the observer's +position on the Earth can affect the Moon's \radec\ by up to +$1^\circ$. The calculation can most conveniently be done by calling +sla\_PVOBS and subtracting the resulting 6-vector from the +one produced by +sla\_DMOON, as is demonstrated by the following example: +\goodbreak +\begin{verbatim} + * Demonstrate the size of the geocentric parallax correction + * in the case of the Moon. The test example is for the AAT, + * before midnight, in summer, near first quarter. + + IMPLICIT NONE + CHARACTER NAME*40,SH,SD + INTEGER J,I,IHMSF(4),IDMSF(4) + DOUBLE PRECISION SLONGW,SLAT,H,DJUTC,FDUTC,DJUT1,DJTT,STL, + : RMATN(3,3),PMM(6),PMT(6),RM,DM,PVO(6),TL + DOUBLE PRECISION sla_DTT,sla_GMST,sla_EQEQX,sla_DRANRM + + * Get AAT longitude and latitude in radians and height in metres + CALL sla_OBS(0,'AAT',NAME,SLONGW,SLAT,H) + + * UTC (1992 January 13, 11 13 59) to MJD + CALL sla_CLDJ(1992,1,13,DJUTC,J) + CALL sla_DTF2D(11,13,59.0D0,FDUTC,J) + DJUTC=DJUTC+FDUTC + + * UT1 (UT1-UTC value of -0.152 sec is from IERS Bulletin B) + DJUT1=DJUTC+(-0.152D0)/86400D0 + + * TT + DJTT=DJUTC+sla_DTT(DJUTC)/86400D0 + + * Local apparent sidereal time + STL=sla_GMST(DJUT1)-SLONGW+sla_EQEQX(DJTT) + + * Geocentric position/velocity of Moon (mean of date) + CALL sla_DMOON(DJTT,PMM) + + * Nutation to true equinox of date + CALL sla_NUT(DJTT,RMATN) + CALL sla_DMXV(RMATN,PMM,PMT) + CALL sla_DMXV(RMATN,PMM(4),PMT(4)) + + * Report geocentric HA,Dec + CALL sla_DCC2S(PMT,RM,DM) + CALL sla_DR2TF(2,sla_DRANRM(STL-RM),SH,IHMSF) + CALL sla_DR2AF(1,DM,SD,IDMSF) + WRITE (*,'(1X,'' geocentric:'',2X,A,I2.2,2I3.2,''.'',I2.2,'// + : '1X,A,I2.2,2I3.2,''.'',I1)') + : SH,IHMSF,SD,IDMSF + + * Geocentric position of observer (true equator and equinox of date) + CALL sla_PVOBS(SLAT,H,STL,PVO) + + * Place origin at observer + DO I=1,6 + PMT(I)=PMT(I)-PVO(I) + END DO + + * Allow for planetary aberration + TL=499.004782D0*SQRT(PMT(1)**2+PMT(2)**2+PMT(3)**2) + DO I=1,3 + PMT(I)=PMT(I)-TL*PMT(I+3) + END DO + + * Report topocentric HA,Dec + CALL sla_DCC2S(PMT,RM,DM) + CALL sla_DR2TF(2,sla_DRANRM(STL-RM),SH,IHMSF) + CALL sla_DR2AF(1,DM,SD,IDMSF) + WRITE (*,'(1X,''topocentric:'',2X,A,I2.2,2I3.2,''.'',I2.2,'// + : '1X,A,I2.2,2I3.2,''.'',I1)') + : SH,IHMSF,SD,IDMSF + END +\end{verbatim} +\goodbreak +The output produced is as follows: +\goodbreak +\begin{verbatim} + geocentric: +03 06 55.59 +15 03 39.0 + topocentric: +03 09 23.79 +15 40 51.5 +\end{verbatim} +\goodbreak +(An easier but +less instructive method of estimating the topocentric apparent place of the +Moon is to call the routine +sla\_RDPLAN.) + +As an example of using +sla\_PLANET, +the following program estimates the geocentric separation +between Venus and Jupiter during a close conjunction +in 2\,BC, which is a star-of-Bethlehem candidate: +\goodbreak +\begin{verbatim} + * Compute time and minimum geocentric apparent separation + * between Venus and Jupiter during the close conjunction of 2 BC. + + IMPLICIT NONE + + DOUBLE PRECISION SEPMIN,DJD0,FD,DJD,DJDM,DF,PV(6),RMATP(3,3), + : PVM(6),PVE(6),TL,RV,DV,RJ,DJ,SEP + INTEGER IHOUR,IMIN,J,I,IHMIN,IMMIN + DOUBLE PRECISION sla_EPJ,sla_DSEP + + + * Search for closest approach on the given day + DJD0=1720859.5D0 + SEPMIN=1D10 + DO IHOUR=20,22 + DO IMIN=0,59 + CALL sla_DTF2D(IHOUR,IMIN,0D0,FD,J) + + * Julian date and MJD + DJD=DJD0+FD + DJDM=DJD-2400000.5D0 + + * Earth to Moon (mean of date) + CALL sla_DMOON(DJDM,PV) + + * Precess Moon position to J2000 + CALL sla_PRECL(sla_EPJ(DJDM),2000D0,RMATP) + CALL sla_DMXV(RMATP,PV,PVM) + + * Sun to Earth-Moon Barycentre (mean J2000) + CALL sla_PLANET(DJDM,3,PVE,J) + + * Correct from EMB to Earth + DO I=1,3 + PV(I)=PVE(I)-0.012150581D0*PVM(I) + END DO + + * Sun to Venus + CALL sla_PLANET(DJDM,2,PV,J) + + * Earth to Venus + DO I=1,6 + PV(I)=PV(I)-PVE(I) + END DO + + * Light time to Venus (sec) + TL=499.004782D0*SQRT((PV(1)-PVE(1))**2+ + : (PV(2)-PVE(2))**2+ + : (PV(3)-PVE(3))**2) + + * Extrapolate backwards in time by that much + DO I=1,3 + PV(I)=PV(I)-TL*PV(I+3) + END DO + + * To RA,Dec + CALL sla_DCC2S(PV,RV,DV) + + * Same for Jupiter + CALL sla_PLANET(DJDM,5,PV,J) + DO I=1,6 + PV(I)=PV(I)-PVE(I) + END DO + TL=499.004782D0*SQRT((PV(1)-PVE(1))**2+ + : (PV(2)-PVE(2))**2+ + : (PV(3)-PVE(3))**2) + DO I=1,3 + PV(I)=PV(I)-TL*PV(I+3) + END DO + CALL sla_DCC2S(PV,RJ,DJ) + + * Separation (arcsec) + SEP=sla_DSEP(RV,DV,RJ,DJ) + + * Keep if smallest so far + IF (SEP.LT.SEPMIN) THEN + IHMIN=IHOUR + IMMIN=IMIN + SEPMIN=SEP + END IF + END DO + END DO + + * Report + WRITE (*,'(1X,I2.2,'':'',I2.2,F6.1)') IHMIN,IMMIN, + : 206264.8062D0*SEPMIN + + END +\end{verbatim} +\goodbreak +The output produced (the Ephemeris Time on the day in question, and +the closest approach in arcseconds) is as follows: +\goodbreak +\begin{verbatim} + 21:19 33.7 +\end{verbatim} +\goodbreak +For comparison, accurate predictions based on the JPL DE\,102 ephemeris +give a separation about \arcseci{8} less than +the above estimate, occurring about half an hour earlier +(see {\it Sky and Telescope,}\/ April~1987, p\,357). + +The following program demonstrates +sla\_RDPLAN. +\begin{verbatim} + * For a given date, time and geographical location, output + * a table of planetary positions and diameters. + + IMPLICIT NONE + CHARACTER PNAMES(0:9)*7,B*80,S + INTEGER I,NP,IY,J,IM,ID,IHMSF(4),IDMSF(4) + DOUBLE PRECISION R2AS,FD,DJM,ELONG,PHI,RA,DEC,DIAM + PARAMETER (R2AS=206264.80625D0) + DATA PNAMES / 'Sun','Mercury','Venus','Moon','Mars','Jupiter', + : 'Saturn','Uranus','Neptune', 'Pluto' / + + + * Loop until 'end' typed + B=' ' + DO WHILE (B.NE.'END'.AND.B.NE.'end') + + * Get date, time and observer's location + PRINT *,'Date? (Y,M,D, Gregorian)' + READ (*,'(A)') B + IF (B.NE.'END'.AND.B.NE.'end') THEN + I=1 + CALL sla_INTIN(B,I,IY,J) + CALL sla_INTIN(B,I,IM,J) + CALL sla_INTIN(B,I,ID,J) + PRINT *,'Time? (H,M,S, dynamical)' + READ (*,'(A)') B + I=1 + CALL sla_DAFIN(B,I,FD,J) + FD=FD*2.3873241463784300365D0 + CALL sla_CLDJ(IY,IM,ID,DJM,J) + DJM=DJM+FD + PRINT *,'Longitude? (D,M,S, east +ve)' + READ (*,'(A)') B + I=1 + CALL sla_DAFIN(B,I,ELONG,J) + PRINT *,'Latitude? (D,M,S, (geodetic)' + READ (*,'(A)') B + I=1 + CALL sla_DAFIN(B,I,PHI,J) + + * Loop planet by planet + DO NP=0,8 + + * Get RA,Dec and diameter + CALL sla_RDPLAN(DJM,NP,ELONG,PHI,RA,DEC,DIAM) + + * One line of report + CALL sla_DR2TF(2,RA,S,IHMSF) + CALL sla_DR2AF(1,DEC,S,IDMSF) + WRITE (*, + : '(1X,A,2X,3I3.2,''.'',I2.2,2X,A,I2.2,2I3.2,''.'',I1,F8.1)') + : PNAMES(NP),IHMSF,S,IDMSF,R2AS*DIAM + + * Next planet + END DO + PRINT *,' ' + END IF + + * Next case + END DO + + END +\end{verbatim} +Entering the following data (for 1927~June~29 at $5^{\rm h}\,25^{\rm m}$~ET +and the position of Preston, UK.): +\begin{verbatim} + 1927 6 29 + 5 25 + -2 42 + 53 46 +\end{verbatim} +produces the following report: +\begin{verbatim} + Sun 06 28 14.03 +23 17 17.5 1887.8 + Mercury 08 08 58.62 +19 20 57.3 9.3 + Venus 09 38 53.64 +15 35 32.9 22.8 + Moon 06 28 18.30 +23 18 37.3 1903.9 + Mars 09 06 49.34 +17 52 26.7 4.0 + Jupiter 00 11 12.06 -00 10 57.5 41.1 + Saturn 16 01 43.34 -18 36 55.9 18.2 + Uranus 00 13 33.53 +00 39 36.0 3.5 + Neptune 09 49 35.75 +13 38 40.8 2.2 + Pluto 07 05 29.50 +21 25 04.2 .1 +\end{verbatim} +Inspection of the Sun and Moon data reveals that +a total solar eclipse is in progress. + +SLALIB also provides for the case where orbital elements (with respect +to the J2000 equinox and ecliptic) +are available. This allows predictions to be made for minor-planets and +(if you ignore non-gravitational effects) +comets. Furthermore, if major-planet elements for an epoch close to the date +in question are available, more accurate predictions can be made than +are offered by +sla\_RDPLAN and +sla\_PLANET. + +The SLALIB planetary-prediction +routines that work with orbital elements are +sla\_PLANTE (the orbital-elements equivalent of +sla\_RDPLAN), which predicts the topocentric \radec, and +sla\_PLANEL (the orbital-elements equivalent of +sla\_PLANET), which predicts the heliocentric \xyzxyzd\ with respect to the +J2000 equinox and equator. In addition, the routine +sla\_PV2EL does the inverse of +sla\_PLANEL, transforming \xyzxyzd\ into {\it osculating elements.} + +Osculating elements describe the unperturbed 2-body orbit. This is +a good approximation to the actual orbit for a few weeks either +side of the specified epoch, outside which perturbations due to +the other bodies of the Solar System lead to +increasing errors. Given a minor planet's osculating elements for +a particular date, predictions for a date even just +100 days earlier or later +are likely to be in error by several arcseconds. +These errors can +be reduced if new elements are generated which take account of +the perturbations of the major planets, and this is what the routine +sla\_PERTEL does. Once +sla\_PERTEL has been called, to provide osculating elements +close to the required date, the elements can be passed to +sla\_PLANEL or +sla\_PLANTE in the normal way. Predictions of arcsecond accuracy +over a span of a decade or more are available using this +technique. + +Three different combinations of orbital elements are +provided for, matching the usual conventions +for major planets, minor planets and +comets respectively. The choice is made through the +argument {\tt JFORM}:\\ + +\hspace{4em} +\begin{tabular}{|c|c|c|} \hline +{\tt JFORM=1} & {\tt JFORM=2} & {\tt JFORM=3} \\ +\hline \hline +$t_0$ & $t_0$ & $T$ \\ +\hline +$i$ & $i$ & $i$ \\ +\hline +$\Omega$ & $\Omega$ & $\Omega$ \\ +\hline +$\varpi$ & $\omega$ & $\omega$ \\ +\hline +$a$ & $a$ & $q$ \\ +\hline +$e$ & $e$ & $e$ \\ +\hline +$L$ & $M$ & \\ +\hline +$n$ & & \\ +\hline +\end{tabular}\\[5ex] +The symbols have the following meanings: +\begin{tabbing} +xxxxxxx \= xxxx \= \kill +\> $t_0$ \> epoch at which the elements were correct \\ +\> $T$ \> epoch of perihelion passage \\ +\> $i$ \> inclination of the orbit \\ +\> $\Omega$ \> longitude of the ascending node \\ +\> $\varpi$ \> longitude of perihelion ($\varpi = \Omega + \omega$) \\ +\> $\omega$ \> argument of perihelion \\ +\> $a$ \> semi-major axis of the orbital ellipse \\ +\> $q$ \> perihelion distance \\ +\> $e$ \> orbital eccentricity \\ +\> $L$ \> mean longitude ($L = \varpi + M$) \\ +\> $M$ \> mean anomaly \\ +\> $n$ \> mean motion \\ +\end{tabbing} + +The mean motion, $n$, tells sla\_PLANEL the mass of the planet. +If it is not available, it should be claculated +from $n^2 a^3 = k^2 (1+m)$, where $k = 0.01720209895$ and +m is the mass of the planet ($M_\odot = 1$); $a$ is in AU. + +Conventional elements are not the only way of specifying an orbit. +The \xyzxyzd\ state vector is an equally valid specification, +and the so-called {\it method of universal variables}\/ allows +orbital calculations to be made directly, bypassing angular +quantities and avoiding Kepler's Equation. The universal-variables +approach has various advantages, including better handling of +near-parabolic cases and greater efficiency. +SLALIB uses universal variables for its internal +calculations and also offers a number of routines which +applications can call. + +The universal elements are the \xyzxyzd\ and its epoch, plus the mass +of the body. The SLALIB routines supplement these elements with +certain redundant values in order to +avoid unnecessary recomputation when the elements are next used. + +The routines +sla\_EL2UE and +sla\_UE2EL transform conventional elements into the +universal form and {\it vice versa.} +The routine +sla\_PV2UE takes an \xyzxyzd\ and forms the set of universal +elements; +sla\_UE2PV takes a set of universal elements and predicts the \xyzxyzd\ +for a specified epoch. +The routine +sla\_PERTUE provides updated universal elements, +taking into account perturbations from the major planets. + +\subsection{Radial Velocity and Light-Time Corrections} +When publishing high-resolution spectral observations +it is necessary to refer them to a specified standard of rest. +This involves knowing the component in the direction of the +source of the velocity of the observer. SLALIB provides a number +of routines for this purpose, allowing observations to be +referred to the Earth's centre, the Sun, a Local Standard of Rest +(either dynamical or kinematical), the centre of the Galaxy, and +the mean motion of the Local Group. + +The routine +sla\_RVEROT +corrects for the diurnal rotation of +the observer around the Earth's axis. This is always less than 0.5~km/s. + +No specific routine is provided to correct a radial velocity +from geocentric to heliocentric, but this can easily be done by calling +sla\_EVP +as follows (array declarations {\it etc}.\ omitted): +\goodbreak +\begin{verbatim} + : + * Star vector, J2000 + CALL sla_DCS2C(RM,DM,V) + + * Earth/Sun velocity and position, J2000 + CALL sla_EVP(TDB,2000D0,DVB,DPB,DVH,DPH) + + * Radial velocity correction due to Earth orbit (km/s) + VCORB = -sla_DVDV(V,DVH)*149.597870D6 + : +\end{verbatim} +\goodbreak +The maximum value of this correction is the Earth's orbital speed +of about 30~km/s. A related routine, +sla\_ECOR, +computes the light-time correction with respect to the Sun. It +would be used when reducing observations of a rapid variable-star +for instance. +Note, however, that the accuracy objectives for pulsar work are +beyond the scope of these SLALIB routines, and even the superior +sla\_EVP +routine is unsuitable for arrival-time calculations of better +than 25~millisecond accuracy. + +To remove the intrinsic $\sim20$~km/s motion of the Sun relative +to other stars in the solar neighbourhood, +a velocity correction to a +{\it local standard of rest}\/ (LSR) is required. There are +opportunities for mistakes here. There are two sorts of LSR, +{\it dynamical}\/ and {\it kinematical}, and +multiple definitions exist for the latter. The +dynamical LSR is a point near the Sun which is in a circular +orbit around the Galactic centre; the Sun has a ``peculiar'' +motion relative to the dynamical LSR. A kinematical LSR is +the mean standard of rest of specified star catalogues or stellar +populations, and its precise definition depends on which +catalogues or populations were used and how the analysis was +carried out. The Sun's motion with respect to a kinematical +LSR is called the ``standard'' solar motion. Radial +velocity corrections to the dynamical LSR are produced by the routine +sla\_RVLSRD +and to the adopted kinematical LSR by +sla\_RVLSRK. +See the individual specifications for these routines for the +precise definition of the LSR in each case. + +For extragalactic sources, the centre of the Galaxy can be used as +a standard of rest. The radial velocity correction from the +dynamical LSR to the Galactic centre can be obtained by calling +sla\_RVGALC. +Its maximum value is 220~km/s. + +For very distant sources it is appropriate to work relative +to the mean motion of the Local Group. The routine for +computing the radial velocity correction in this case is +sla\_RVLG. +Note that in this case the correction is with respect to the +dynamical LSR, not the Galactic centre as might be expected. +This conforms to the IAU definition, and confers immunity from +revisions of the Galactic rotation speed. + +\subsection{Focal-Plane Astrometry} +The relationship between the position of a star image in +the focal plane of a telescope and the star's celestial +coordinates is usually described in terms of the {\it tangent plane}\/ +or {\it gnomonic}\/ projection. This is the projection produced +by a pin-hole camera and is a good approximation to the projection +geometry of a traditional large {\it f}\/-ratio astrographic refractor. +SLALIB includes a group of routines which transform +star positions between their observed places on the celestial +sphere and their \xy\ coordinates in the tangent plane. The +spherical coordinate system does not have to be \radec\ but +usually is. The so-called {\it standard coordinates}\/ of a star +are the tangent plane \xy, in radians, with respect to an origin +at the tangent point, with the $y$-axis pointing north and +the $x$-axis pointing east (in the direction of increasing $\alpha$). +The factor relating the standard coordinates to +the actual \xy\ coordinates in, say, millimetres is simply +the focal length of the telescope. + +Given the \radec\ of the {\it plate centre}\/ (the tangent point) +and the \radec\ of a star within the field, the standard +coordinates can be determined by calling +sla\_S2TP +(single precision) or +sla\_DS2TP +(double precision). The reverse transformation, where the +\xy\ is known and we wish to find the \radec, is carried out by calling +sla\_TP2S +or +sla\_DTP2S. +Occasionally we know the both the \xy\ and the \radec\ of a +star and need to deduce the \radec\ of the tangent point; +this can be done by calling +sla\_TPS2C +or +sla\_DTPS2C. +(All of these transformations apply not just to \radec\ but to +other spherical coordinate systems, of course.) +Equivalent (and faster) +routines are provided which work directly in \xyz\ instead of +spherical coordinates: +sla\_V2TP and +sla\_DV2TP, +sla\_TP2V and +sla\_DTP2V, +sla\_TPV2C and +sla\_DTPV2C. + +Even at the best of times, the tangent plane projection is merely an +approximation. Some telescopes and cameras exhibit considerable pincushion +or barrel distortion and some have a curved focal surface. +For example, neither Schmidt cameras nor (especially) +large reflecting telescopes with wide-field corrector lenses +are adequately modelled by tangent-plane geometry. In such +cases, however, it is still possible to do most of the work +using the (mathematically convenient) tangent-plane +projection by inserting an extra step which applies or +removes the distortion peculiar to the system concerned. +A simple $r_1=r_0(1+Kr_0^2)$ law works well in the +majority of cases; $r_0$ is the radial distance in the +tangent plane, $r_1$ is the radial distance after adding +the distortion, and $K$ is a constant which depends on the +telescope ($\theta$ is unaffected). The routine +sla\_PCD +applies the distortion to an \xy\ and +sla\_UNPCD +removes it. For \xy\ in radians, $K$ values range from $-1/3$ for the +tiny amount of barrel distortion in Schmidt geometry to several +hundred for the serious pincushion distortion +produced by wide-field correctors in big reflecting telescopes +(the AAT prime focus triplet corrector is about $K=+178.6$). + +SLALIB includes a group of routines which can be put together +to build a simple plate-reduction program. The heart of the group is +sla\_FITXY, +which fits a linear model to relate two sets of \xy\ coordinates, +in the case of a plate reduction the measured positions of the +images of a set of +reference stars and the standard +coordinates derived from their catalogue positions. The +model is of the form: +\[x_{p} = a + bx_{m} + cy_{m}\] +\[y_{p} = d + ex_{m} + fy_{m}\] + +where the {\it p}\/ subscript indicates ``predicted'' coordinates +(the model's approximation to the ideal ``expected'' coordinates) and the +{\it m}\/ subscript indicates ``measured coordinates''. The +six coefficients {\it a--f}\/ can optionally be +constrained to represent a ``solid body rotation'' free of +any squash or shear distortions. Without this constraint +the model can, to some extent, accommodate effects like refraction, +allowing mean places to be used directly and +avoiding the extra complications of a +full mean-apparent-observed transformation for each star. +Having obtained the linear model, +sla\_PXY +can be used to process the set of measured and expected +coordinates, giving the predicted coordinates and determining +the RMS residuals in {\it x}\/ and {\it y}. +The routine +sla\_XY2XY +transforms one \xy\ into another using the linear model. A model +can be inverted by calling +sla\_INVF, +and decomposed into zero points, scales, $x/y$ nonperpendicularity +and orientation by calling +sla\_DCMPF. + +\subsection{Numerical Methods} +SLALIB contains a small number of simple, general-purpose +numerical-methods routines. They have no specific +connection with positional astronomy but have proved useful in +applications to do with simulation and fitting. + +At the heart of many simulation programs is the generation of +pseudo-random numbers, evenly distributed in a given range: +sla\_RANDOM +does this. Pseudo-random normal deviates, or ``Gaussian +residuals'', are often required to simulate noise and +can be generated by means of the function +sla\_GRESID. +Neither routine will pass super-sophisticated +statistical tests, but they work adequately for most +practical purposes and avoid the need to call non-standard +library routines peculiar to one sort of computer. + +Applications which perform a least-squares fit using a traditional +normal-equations methods can accomplish the required matrix-inversion +by calling either +sla\_SMAT +(single precision) or +sla\_DMAT +(double). A generally better way to perform such fits is +to use singular value decomposition. SLALIB provides a routine +to do the decomposition itself, +sla\_SVD, +and two routines to use the results: +sla\_SVDSOL +generates the solution, and +sla\_SVDCOV +produces the covariance matrix. +A simple demonstration of the use of the SLALIB SVD +routines is given below. It generates 500 simulated data +points and fits them to a model which has 4 unknown coefficients. +(The arrays in the example are sized to accept up to 1000 +points and 20 unknowns.) The model is: +\[ y = C_{1} +C_{2}x +C_{3}sin{x} +C_{4}cos{x} \] +The test values for the four coefficients are +$C_1\!=\!+50.0$, +$C_2\!=\!-2.0$, +$C_3\!=\!-10.0$ and +$C_4\!=\!+25.0$. +Gaussian noise, $\sigma=5.0$, is added to each ``observation''. +\goodbreak +\begin{verbatim} + IMPLICIT NONE + + * Sizes of arrays, physical and logical + INTEGER MP,NP,NC,M,N + PARAMETER (MP=1000,NP=10,NC=20,M=500,N=4) + + * The unknowns we are going to solve for + DOUBLE PRECISION C1,C2,C3,C4 + PARAMETER (C1=50D0,C2=-2D0,C3=-10D0,C4=25D0) + + * Arrays + DOUBLE PRECISION A(MP,NP),W(NP),V(NP,NP), + : WORK(NP),B(MP),X(NP),CVM(NC,NC) + + DOUBLE PRECISION VAL,BF1,BF2,BF3,BF4,SD2,D,VAR + REAL sla_GRESID + INTEGER I,J + + * Fill the design matrix + DO I=1,M + + * Dummy independent variable + VAL=DBLE(I)/10D0 + + * The basis functions + BF1=1D0 + BF2=VAL + BF3=SIN(VAL) + BF4=COS(VAL) + + * The observed value, including deliberate Gaussian noise + B(I)=C1*BF1+C2*BF2+C3*BF3+C4*BF4+DBLE(sla_GRESID(5.0)) + + * Fill one row of the design matrix + A(I,1)=BF1 + A(I,2)=BF2 + A(I,3)=BF3 + A(I,4)=BF4 + END DO + + * Factorize the design matrix, solve and generate covariance matrix + CALL sla_SVD(M,N,MP,NP,A,W,V,WORK,J) + CALL sla_SVDSOL(M,N,MP,NP,B,A,W,V,WORK,X) + CALL sla_SVDCOV(N,NP,NC,W,V,WORK,CVM) + + * Compute the variance + SD2=0D0 + DO I=1,M + VAL=DBLE(I)/10D0 + BF1=1D0 + BF2=VAL + BF3=SIN(VAL) + BF4=COS(VAL) + D=B(I)-(X(1)*BF1+X(2)*BF2+X(3)*BF3+X(4)*BF4) + SD2=SD2+D*D + END DO + VAR=SD2/DBLE(M) + + * Report the RMS and the solution + WRITE (*,'(1X,''RMS ='',F5.2/)') SQRT(VAR) + DO I=1,N + WRITE (*,'(1X,''C'',I1,'' ='',F7.3,'' +/-'',F6.3)') + : I,X(I),SQRT(VAR*CVM(I,I)) + END DO + END +\end{verbatim} +\goodbreak +The program produces the following output: +\goodbreak +\begin{verbatim} + RMS = 4.88 + + C1 = 50.192 +/- 0.439 + C2 = -2.002 +/- 0.015 + C3 = -9.771 +/- 0.310 + C4 = 25.275 +/- 0.310 +\end{verbatim} +\goodbreak +In this above example, essentially +identical results would be obtained if the more +commonplace normal-equations method had been used, and the large +$1000\times20$ array would have been avoided. However, the SVD method +comes into its own when the opportunity is taken to edit the W-matrix +(the so-called ``singular values'') in order to control +possible ill-conditioning. The procedure involves replacing with +zeroes any W-elements smaller than a nominated value, for example +0.001 times the largest W-element. Small W-elements indicate +ill-conditioning, which in the case of the normal-equations +method would produce spurious large coefficient values and +possible arithmetic overflows. Using SVD, the effect on the solution +of setting suspiciously small W-elements to zero is to restrain +the offending coefficients from moving very far. The +fact that action was taken can be reported to show the program user that +something is amiss. Furthermore, if element W(J) was set to zero, +the row numbers of the two biggest elements in the Jth column of the +V-matrix identify the pair of solution coefficients that are +dependent. + +A more detailed description of SVD and its use in least-squares +problems would be out of place here, and the reader is urged +to refer to the relevant sections of the book {\it Numerical Recipes} +(Press {\it et al.}, Cambridge University Press, 1987). + +\pagebreak + +\section{SUMMARY OF CALLS} +The basic trigonometrical and numerical facilities are supplied in both single +and double precision versions. +Most of the more esoteric position and time routines use double precision +arguments only, even in cases where single precision would normally be adequate +in practice. +Certain routines with modest accuracy objectives are supplied in +single precision versions only. +In the calling sequences which follow, no attempt has been made +to distinguish between single and double precision argument names, +and frequently the same name is used on different occasions to +mean different things. +However, none of the routines uses a mixture of single and +double precision arguments; each routine is either wholly +single precision or wholly double precision. + +In the classified list, below, +{\it subroutine}\/ subprograms are those whose names and argument lists +are preceded by `CALL', whereas {\it function}\/ subprograms are +those beginning `R=' (when the result is REAL) or `D=' (when +the result is DOUBLE~PRECISION). + +The list is, of course, merely for quick reference; inexperienced +users {\bf must} refer to the detailed specifications given later. +In particular, {\bf don't guess} whether arguments are single or +double precision; the result could be a program that happens to +works on one sort of machine but not on another. + +\callhead{String Decoding} +\begin{callset} +\subp{CALL sla\_INTIN (STRING, NSTRT, IRESLT, JFLAG)} + Convert free-format string into integer +\subq{CALL sla\_FLOTIN (STRING, NSTRT, RESLT, JFLAG)} + {CALL sla\_DFLTIN (STRING, NSTRT, DRESLT, JFLAG)} + Convert free-format string into floating-point number +\subq{CALL sla\_AFIN (STRING, NSTRT, RESLT, JFLAG)} + {CALL sla\_DAFIN (STRING, NSTRT, DRESLT, JFLAG)} + Convert free-format string from deg,arcmin,arcsec to radians +\end{callset} + +\callhead{Sexagesimal Conversions} +\begin{callset} +\subq{CALL sla\_CTF2D (IHOUR, IMIN, SEC, DAYS, J)} + {CALL sla\_DTF2D (IHOUR, IMIN, SEC, DAYS, J)} + Hours, minutes, seconds to days +\subq{CALL sla\_CD2TF (NDP, DAYS, SIGN, IHMSF)} + {CALL sla\_DD2TF (NDP, DAYS, SIGN, IHMSF)} + Days to hours, minutes, seconds +\subq{CALL sla\_CTF2R (IHOUR, IMIN, SEC, RAD, J)} + {CALL sla\_DTF2R (IHOUR, IMIN, SEC, RAD, J)} + Hours, minutes, seconds to radians +\subq{CALL sla\_CR2TF (NDP, ANGLE, SIGN, IHMSF)} + {CALL sla\_DR2TF (NDP, ANGLE, SIGN, IHMSF)} + Radians to hours, minutes, seconds +\subq{CALL sla\_CAF2R (IDEG, IAMIN, ASEC, RAD, J)} + {CALL sla\_DAF2R (IDEG, IAMIN, ASEC, RAD, J)} + Degrees, arcminutes, arcseconds to radians +\subq{CALL sla\_CR2AF (NDP, ANGLE, SIGN, IDMSF)} + {CALL sla\_DR2AF (NDP, ANGLE, SIGN, IDMSF)} + Radians to degrees, arcminutes, arcseconds +\end{callset} + +\callhead{Angles, Vectors and Rotation Matrices} +\begin{callset} +\subq{R~=~sla\_RANGE (ANGLE)} + {D~=~sla\_DRANGE (ANGLE)} + Normalize angle into range $\pm\pi$ +\subq{R~=~sla\_RANORM (ANGLE)} + {D~=~sla\_DRANRM (ANGLE)} + Normalize angle into range $0\!-\!2\pi$ +\subq{CALL sla\_CS2C (A, B, V)} + {CALL sla\_DCS2C (A, B, V)} + Spherical coordinates to \xyz +\subq{CALL sla\_CC2S (V, A, B)} + {CALL sla\_DCC2S (V, A, B)} + \xyz\ to spherical coordinates +\subq{R~=~sla\_VDV (VA, VB)} + {D~=~sla\_DVDV (VA, VB)} + Scalar product of two 3-vectors +\subq{CALL sla\_VXV (VA, VB, VC)} + {CALL sla\_DVXV (VA, VB, VC)} + Vector product of two 3-vectors +\subq{CALL sla\_VN (V, UV, VM)} + {CALL sla\_DVN (V, UV, VM)} + Normalize a 3-vector also giving the modulus +\subq{R~=~sla\_SEP (A1, B1, A2, B2)} + {D~=~sla\_DSEP (A1, B1, A2, B2)} + Angle between two points on a sphere +\subq{R~=~sla\_BEAR (A1, B1, A2, B2)} + {D~=~sla\_DBEAR (A1, B1, A2, B2)} + Direction of one point on a sphere seen from another +\subq{R~=~sla\_PAV (V1, V2)} + {D~=~sla\_DPAV (V1, V2)} + Position-angle of one \xyz\ with respect to another +\subq{CALL sla\_EULER (ORDER, PHI, THETA, PSI, RMAT)} + {CALL sla\_DEULER (ORDER, PHI, THETA, PSI, RMAT)} + Form rotation matrix from three Euler angles +\subq{CALL sla\_AV2M (AXVEC, RMAT)} + {CALL sla\_DAV2M (AXVEC, RMAT)} + Form rotation matrix from axial vector +\subq{CALL sla\_M2AV (RMAT, AXVEC)} + {CALL sla\_DM2AV (RMAT, AXVEC)} + Determine axial vector from rotation matrix +\subq{CALL sla\_MXV (RM, VA, VB)} + {CALL sla\_DMXV (DM, VA, VB)} + Rotate vector forwards +\subq{CALL sla\_IMXV (RM, VA, VB)} + {CALL sla\_DIMXV (DM, VA, VB)} + Rotate vector backwards +\subq{CALL sla\_MXM (A, B, C)} + {CALL sla\_DMXM (A, B, C)} + Product of two 3x3 matrices +\subq{CALL sla\_CS2C6 (A, B, R, AD, BD, RD, V)} + {CALL sla\_DS2C6 (A, B, R, AD, BD, RD, V)} + Conversion of position and velocity in spherical + coordinates to Cartesian coordinates +\subq{CALL sla\_CC62S (V, A, B, R, AD, BD, RD)} + {CALL sla\_DC62S (V, A, B, R, AD, BD, RD)} + Conversion of position and velocity in Cartesian + coordinates to spherical coordinates +\end{callset} + +\callhead{Calendars} +\begin{callset} +\subp{CALL sla\_CLDJ (IY, IM, ID, DJM, J)} + Gregorian Calendar to Modified Julian Date +\subp{CALL sla\_CALDJ (IY, IM, ID, DJM, J)} + Gregorian Calendar to Modified Julian Date, + permitting century default +\subp{CALL sla\_DJCAL (NDP, DJM, IYMDF, J)} + Modified Julian Date to Gregorian Calendar, + in a form convenient for formatted output +\subp{CALL sla\_DJCL (DJM, IY, IM, ID, FD, J)} + Modified Julian Date to Gregorian Year, Month, Day, Fraction +\subp{CALL sla\_CALYD (IY, IM, ID, NY, ND, J)} + Calendar to year and day in year, permitting century default +\subp{CALL sla\_CLYD (IY, IM, ID, NY, ND, J)} + Calendar to year and day in year +\subp{D~=~sla\_EPB (DATE)} + Modified Julian Date to Besselian Epoch +\subp{D~=~sla\_EPB2D (EPB)} + Besselian Epoch to Modified Julian Date +\subp{D~=~sla\_EPJ (DATE)} + Modified Julian Date to Julian Epoch +\subp{D~=~sla\_EPJ2D (EPJ)} + Julian Epoch to Modified Julian Date +\end{callset} + +\callhead{Timescales} +\begin{callset} +\subp{D~=~sla\_GMST (UT1)} + Conversion from Universal Time to sidereal time +\subp{D~=~sla\_GMSTA (DATE, UT1)} + Conversion from Universal Time to sidereal time, rounding errors minimized +\subp{D~=~sla\_EQEQX (DATE)} + Equation of the equinoxes +\subp{D~=~sla\_DAT (DJU)} + Offset of Atomic Time from Coordinated Universal Time: TAI$-$UTC +\subp{D~=~sla\_DT (EPOCH)} + Approximate offset between dynamical time and universal time +\subp{D~=~sla\_DTT (DJU)} + Offset of Terrestrial Time from Coordinated Universal Time: TT$-$UTC +\subp{D~=~sla\_RCC (TDB, UT1, WL, U, V)} + Relativistic clock correction: TDB$-$TT +\end{callset} + +\callhead{Precession and Nutation} +\begin{callset} +\subp{CALL sla\_NUT (DATE, RMATN)} + Nutation matrix +\subp{CALL sla\_NUTC (DATE, DPSI, DEPS, EPS0)} + Longitude and obliquity components of nutation, and + mean obliquity +\subp{CALL sla\_PREC (EP0, EP1, RMATP)} + Precession matrix (IAU) +\subp{CALL sla\_PRECL (EP0, EP1, RMATP)} + Precession matrix (suitable for long periods) +\subp{CALL sla\_PRENUT (EPOCH, DATE, RMATPN)} + Combined precession/nutation matrix +\subp{CALL sla\_PREBN (BEP0, BEP1, RMATP)} + Precession matrix, old system +\subp{CALL sla\_PRECES (SYSTEM, EP0, EP1, RA, DC)} + Precession, in either the old or the new system +\end{callset} + +\callhead{Proper Motion} +\begin{callset} +\subp{CALL sla\_PM (R0, D0, PR, PD, PX, RV, EP0, EP1, R1, D1)} + Adjust for proper motion +\end{callset} + +\callhead{FK4/FK5/Hipparcos Conversions} +\begin{callset} +\subp{CALL sla\_FK425 (\vtop + {\hbox{R1950, D1950, DR1950, DD1950, P1950, V1950,} + \hbox{R2000, D2000, DR2000, DD2000, P2000, V2000)}}} + Convert B1950.0 FK4 star data to J2000.0 FK5 +\subp{CALL sla\_FK45Z (R1950, D1950, EPOCH, R2000, D2000)} + Convert B1950.0 FK4 position to J2000.0 FK5 assuming zero + FK5 proper motion and no parallax +\subp{CALL sla\_FK524 (\vtop + {\hbox{R2000, D2000, DR2000, DD2000, P2000, V2000,} + \hbox{R1950, D1950, DR1950, DD1950, P1950, V1950)}}} + Convert J2000.0 FK5 star data to B1950.0 FK4 +\subp{CALL sla\_FK54Z (R2000, D2000, BEPOCH, + R1950, D1950, DR1950, DD1950)} + Convert J2000.0 FK5 position to B1950.0 FK4 assuming zero + FK5 proper motion and no parallax +\subp{CALL sla\_FK52H (R5, D5, DR5, DD5, RH, DH, DRH, DDH)} + Convert J2000.0 FK5 star data to Hipparcos +\subp{CALL sla\_FK5HZ (R5, D5, EPOCH, RH, DH )} + Convert J2000.0 FK5 position to Hipparcos assuming zero Hipparcos + proper motion +\subp{CALL sla\_H2FK5 (RH, DH, DRH, DDH, R5, D5, DR5, DD5)} + Convert Hipparcos star data to J2000.0 FK5 +\subp{CALL sla\_HFK5Z (RH, DH, EPOCH, R5, D5, DR5, DD5)} + Convert Hipparcos position to J2000.0 FK5 assuming zero Hipparcos + proper motion +\subp{CALL sla\_DBJIN (STRING, NSTRT, DRESLT, J1, J2)} + Like sla\_DFLTIN but with extensions to accept leading `B' and `J' +\subp{CALL sla\_KBJ (JB, E, K, J)} + Select epoch prefix `B' or `J' +\subp{D~=~sla\_EPCO (K0, K, E)} + Convert an epoch into the appropriate form -- `B' or `J' +\end{callset} + +\callhead{Elliptic Aberration} +\begin{callset} +\subp{CALL sla\_ETRMS (EP, EV)} + E-terms +\subp{CALL sla\_SUBET (RC, DC, EQ, RM, DM)} + Remove the E-terms +\subp{CALL sla\_ADDET (RM, DM, EQ, RC, DC)} + Add the E-terms +\end{callset} + +\callhead{Geographical and Geocentric Coordinates} +\begin{callset} +\subp{CALL sla\_OBS (NUMBER, ID, NAME, WLONG, PHI, HEIGHT)} + Interrogate list of observatory parameters +\subp{CALL sla\_GEOC (P, H, R, Z)} + Convert geodetic position to geocentric +\subp{CALL sla\_POLMO (ELONGM, PHIM, XP, YP, ELONG, PHI, DAZ)} + Polar motion +\subp{CALL sla\_PVOBS (P, H, STL, PV)} + Position and velocity of observatory +\end{callset} + +\callhead{Apparent and Observed Place} +\begin{callset} +\subp{CALL sla\_MAP (RM, DM, PR, PD, PX, RV, EQ, DATE, RA, DA)} + Mean place to geocentric apparent place +\subp{CALL sla\_MAPPA (EQ, DATE, AMPRMS)} + Precompute mean to apparent parameters +\subp{CALL sla\_MAPQK (RM, DM, PR, PD, PX, RV, AMPRMS, RA, DA)} + Mean to apparent using precomputed parameters +\subp{CALL sla\_MAPQKZ (RM, DM, AMPRMS, RA, DA)} + Mean to apparent using precomputed parameters, for zero proper + motion, parallax and radial velocity +\subp{CALL sla\_AMP (RA, DA, DATE, EQ, RM, DM)} + Geocentric apparent place to mean place +\subp{CALL sla\_AMPQK (RA, DA, AOPRMS, RM, DM)} + Apparent to mean using precomputed parameters +\subp{CALL sla\_AOP (\vtop + {\hbox{RAP, DAP, UTC, DUT, ELONGM, PHIM, HM, XP, YP,} + \hbox{TDK, PMB, RH, WL, TLR, AOB, ZOB, HOB, DOB, ROB)}}} + Apparent place to observed place +\subp{CALL sla\_AOPPA (\vtop + {\hbox{UTC, DUT, ELONGM, PHIM, HM, XP, YP,} + \hbox{TDK, PMB, RH, WL, TLR, AOPRMS)}}} + Precompute apparent to observed parameters +\subp{CALL sla\_AOPPAT (UTC, AOPRMS)} + Update sidereal time in apparent to observed parameters +\subp{CALL sla\_AOPQK (RAP, DAP, AOPRMS, AOB, ZOB, HOB, DOB, ROB)} + Apparent to observed using precomputed parameters +\subp{CALL sla\_OAP (\vtop + {\hbox{TYPE, OB1, OB2, UTC, DUT, ELONGM, PHIM, HM, XP, YP,} + \hbox{TDK, PMB, RH, WL, TLR, RAP, DAP)}}} + Observed to apparent +\subp{CALL sla\_OAPQK (TYPE, OB1, OB2, AOPRMS, RA, DA)} + Observed to apparent using precomputed parameters +\end{callset} + +\callhead{Azimuth and Elevation} +\begin{callset} +\subp{CALL sla\_ALTAZ (\vtop + {\hbox{HA, DEC, PHI,} + \hbox{AZ, AZD, AZDD, EL, ELD, ELDD, PA, PAD, PADD)}}} + Positions, velocities {\it etc.}\ for an altazimuth mount +\subq{CALL sla\_E2H (HA, DEC, PHI, AZ, EL)} + {CALL sla\_DE2H (HA, DEC, PHI, AZ, EL)} + \hadec\ to \azel +\subq{CALL sla\_H2E (AZ, EL, PHI, HA, DEC)} + {CALL sla\_DH2E (AZ, EL, PHI, HA, DEC)} + \azel\ to \hadec +\subp{CALL sla\_PDA2H (P, D, A, H1, J1, H2, J2)} + Hour Angle corresponding to a given azimuth +\subp{CALL sla\_PDQ2H (P, D, Q, H1, J1, H2, J2)} + Hour Angle corresponding to a given parallactic angle +\subp{D~=~sla\_PA (HA, DEC, PHI)} + \hadec\ to parallactic angle +\subp{D~=~sla\_ZD (HA, DEC, PHI)} + \hadec\ to zenith distance +\end{callset} + +\callhead{Refraction and Air Mass} +\begin{callset} +\subp{CALL sla\_REFRO (ZOBS, HM, TDK, PMB, RH, WL, PHI, TLR, EPS, REF)} + Change in zenith distance due to refraction +\subp{CALL sla\_REFCO (HM, TDK, PMB, RH, WL, PHI, TLR, EPS, REFA, REFB)} + Constants for simple refraction model (accurate) +\subp{CALL sla\_REFCOQ (TDK, PMB, RH, WL, REFA, REFB)} + Constants for simple refraction model (fast) +\subp{CALL sla\_ATMDSP ( TDK, PMB, RH, WL1, REFA1, REFB1, WL2, REFA2, REFB2 )} + Adjust refraction constants for colour +\subp{CALL sla\_REFZ (ZU, REFA, REFB, ZR)} + Unrefracted to refracted ZD, simple model +\subp{CALL sla\_REFV (VU, REFA, REFB, VR)} + Unrefracted to refracted \azel\ vector, simple model +\subp{D~=~sla\_AIRMAS (ZD)} + Air mass +\end{callset} + +\callhead{Ecliptic Coordinates} +\begin{callset} +\subp{CALL sla\_ECMAT (DATE, RMAT)} + Equatorial to ecliptic rotation matrix +\subp{CALL sla\_EQECL (DR, DD, DATE, DL, DB)} + J2000.0 `FK5' to ecliptic coordinates +\subp{CALL sla\_ECLEQ (DL, DB, DATE, DR, DD)} + Ecliptic coordinates to J2000.0 `FK5' +\end{callset} + +\callhead{Galactic Coordinates} +\begin{callset} +\subp{CALL sla\_EG50 (DR, DD, DL, DB)} + B1950.0 `FK4' to galactic +\subp{CALL sla\_GE50 (DL, DB, DR, DD)} + Galactic to B1950.0 `FK4' +\subp{CALL sla\_EQGAL (DR, DD, DL, DB)} + J2000.0 `FK5' to galactic +\subp{CALL sla\_GALEQ (DL, DB, DR, DD)} + Galactic to J2000.0 `FK5' +\end{callset} + +\callhead{Supergalactic Coordinates} +\begin{callset} +\subp{CALL sla\_GALSUP (DL, DB, DSL, DSB)} + Galactic to supergalactic +\subp{CALL sla\_SUPGAL (DSL, DSB, DL, DB)} + Supergalactic to galactic +\end{callset} + +\callhead{Ephemerides} +\begin{callset} +\subp{CALL sla\_DMOON (DATE, PV)} + Approximate geocentric position and velocity of the Moon +\subp{CALL sla\_EARTH (IY, ID, FD, PV)} + Approximate heliocentric position and velocity of the Earth +\subp{CALL sla\_EVP (DATE, DEQX, DVB, DPB, DVH, DPH)} + Barycentric and heliocentric velocity and position of the Earth +\subp{CALL sla\_MOON (IY, ID, FD, PV)} + Approximate geocentric position and velocity of the Moon +\subp{CALL sla\_PLANET (DATE, NP, PV, JSTAT)} + Approximate heliocentric position and velocity of a planet +\subp{CALL sla\_RDPLAN (DATE, NP, ELONG, PHI, RA, DEC, DIAM)} + Approximate topocentric apparent place of a planet +\subp{CALL sla\_PLANEL (\vtop + {\hbox{DATE, JFORM, EPOCH, ORBINC, ANODE, PERIH,} + \hbox{AORQ, E, AORL, DM, PV, JSTAT)}}} + Heliocentric position and velocity of a planet, asteroid or + comet, starting from orbital elements +\subp{CALL sla\_PLANTE (\vtop + {\hbox{DATE, ELONG, PHI, JFORM, EPOCH, ORBINC, ANODE,} + \hbox{PERIH, AORQ, E, AORL, DM, RA, DEC, R, JSTAT)}}} + Topocentric apparent place of a Solar-System object whose + heliocentric orbital elements are known +\subp{CALL sla\_PV2EL (\vtop + {\hbox{PV, DATE, PMASS, JFORMR, JFORM, EPOCH, ORBINC,} + \hbox{ANODE, PERIH, AORQ, E, AORL, DM, JSTAT)}}} + Orbital elements of a planet from instantaneous position and velocity +\subp{CALL sla\_PERTEL (\vtop + {\hbox{JFORM, DATE0, DATE1,} + \hbox{EPOCH0, ORBI0, ANODE0, PERIH0, AORQ0, E0, AM0,} + \hbox{EPOCH1, ORBI1, ANODE1, PERIH1, AORQ1, E1, AM1,} + \hbox{JSTAT)}}} + Update elements by applying perturbations +\subp{CALL sla\_EL2UE (\vtop + {\hbox{DATE, JFORM, EPOCH, ORBINC, ANODE,} + \hbox{PERIH, AORQ, E, AORL, DM,} + \hbox{U, JSTAT)}}} + Transform conventional elements to universal elements +\subp{CALL sla\_UE2EL (\vtop + {\hbox{U, JFORMR,} + \hbox{JFORM, EPOCH, ORBINC, ANODE, PERIH,} + \hbox{AORQ, E, AORL, DM, JSTAT)}}} + Transform universal elements to conventional elements +\subp{CALL sla\_PV2UE (PV, DATE, PMASS, U, JSTAT)} + Package a position and velocity for use as universal elements +\subp{CALL sla\_UE2PV (DATE, U, PV, JSTAT)} + Extract the position and velocity from universal elements +\subp{CALL sla\_PERTUE (DATE, U, JSTAT)} + Update universal elements by applying perturbations +\subp{R~=~sla\_RVEROT (PHI, RA, DA, ST)} + Velocity component due to rotation of the Earth +\subp{CALL sla\_ECOR (RM, DM, IY, ID, FD, RV, TL)} + Components of velocity and light time due to Earth orbital motion +\subp{R~=~sla\_RVLSRD (R2000, D2000)} + Velocity component due to solar motion wrt dynamical LSR +\subp{R~=~sla\_RVLSRK (R2000, D2000)} + Velocity component due to solar motion wrt kinematical LSR +\subp{R~=~sla\_RVGALC (R2000, D2000)} + Velocity component due to rotation of the Galaxy +\subp{R~=~sla\_RVLG (R2000, D2000)} + Velocity component due to rotation and translation of the + Galaxy, relative to the mean motion of the local group +\end{callset} + +\callhead{Astrometry} +\begin{callset} +\subq{CALL sla\_S2TP (RA, DEC, RAZ, DECZ, XI, ETA, J)} + {CALL sla\_DS2TP (RA, DEC, RAZ, DECZ, XI, ETA, J)} + Transform spherical coordinates into tangent plane +\subq{CALL sla\_V2TP (V, V0, XI, ETA, J)} + {CALL sla\_DV2TP (V, V0, XI, ETA, J)} + Transform \xyz\ into tangent plane coordinates +\subq{CALL sla\_DTP2S (XI, ETA, RAZ, DECZ, RA, DEC)} + {CALL sla\_TP2S (XI, ETA, RAZ, DECZ, RA, DEC)} + Transform tangent plane coordinates into spherical coordinates +\subq{CALL sla\_DTP2V (XI, ETA, V0, V)} + {CALL sla\_TP2V (XI, ETA, V0, V)} + Transform tangent plane coordinates into \xyz +\subq{CALL sla\_DTPS2C (XI, ETA, RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2, N)} + {CALL sla\_TPS2C (XI, ETA, RA, DEC, RAZ1, DECZ1, RAZ2, DECZ2, N)} + Get plate centre from star \radec\ and tangent plane coordinates +\subq{CALL sla\_DTPV2C (XI, ETA, V, V01, V02, N)} + {CALL sla\_TPV2C (XI, ETA, V, V01, V02, N)} + Get plate centre from star \xyz\ and tangent plane coordinates +\subp{CALL sla\_PCD (DISCO, X, Y)} + Apply pincushion/barrel distortion +\subp{CALL sla\_UNPCD (DISCO, X, Y)} + Remove pincushion/barrel distortion +\subp{CALL sla\_FITXY (ITYPE, NP, XYE, XYM, COEFFS, J)} + Fit a linear model to relate two sets of \xy\ coordinates +\subp{CALL sla\_PXY (NP, XYE, XYM, COEFFS, XYP, XRMS, YRMS, RRMS)} + Compute predicted coordinates and residuals +\subp{CALL sla\_INVF (FWDS, BKWDS, J)} + Invert a linear model +\subp{CALL sla\_XY2XY (X1, Y1, COEFFS, X2, Y2)} + Transform one \xy +\subp{CALL sla\_DCMPF (COEFFS, XZ, YZ, XS, YS, PERP, ORIENT)} + Decompose a linear fit into scales {\it etc.} +\end{callset} + +\callhead{Numerical Methods} +\begin{callset} +\subq{CALL sla\_SMAT (N, A, Y, D, JF, IW)} + {CALL sla\_DMAT (N, A, Y, D, JF, IW)} + Matrix inversion and solution of simultaneous equations +\subp{CALL sla\_SVD (M, N, MP, NP, A, W, V, WORK, JSTAT)} + Singular value decomposition of a matrix +\subp{CALL sla\_SVDSOL (M, N, MP, NP, B, U, W, V, WORK, X)} + Solution from given vector plus SVD +\subp{CALL sla\_SVDCOV (N, NP, NC, W, V, WORK, CVM)} + Covariance matrix from SVD +\subp{R~=~sla\_RANDOM (SEED)} + Generate pseudo-random real number in the range {$0 \leq x < 1$} +\subp{R~=~sla\_GRESID (S)} + Generate pseudo-random normal deviate ($\equiv$ `Gaussian residual') +\end{callset} + +\callhead{Real-time} +\begin{callset} +\subp{CALL sla\_WAIT (DELAY)} + Interval wait +\end{callset} + +\end{document} diff --git a/math/slalib/doc/supgal.hlp b/math/slalib/doc/supgal.hlp new file mode 100644 index 00000000..aa260719 --- /dev/null +++ b/math/slalib/doc/supgal.hlp @@ -0,0 +1,43 @@ +.help supgal Jun99 "Slalib Package" +.nf + + SUBROUTINE slSUGA (DSL, DSB, DL, DB) + + - - - - - - - + S U G A + - - - - - - - + + Transformation from de Vaucouleurs supergalactic coordinates + to IAU 1958 galactic coordinates (double precision) + + Given: + DSL,DSB dp supergalactic longitude and latitude + + Returned: + DL,DB dp galactic longitude and latitude L2,B2 + + (all arguments are radians) + + Called: + slDS2C, slDIMV, slDC2S, slDA2P, slDA1P + + References: + + de Vaucouleurs, de Vaucouleurs, & Corwin, Second Reference + Catalogue of Bright Galaxies, U. Texas, page 8. + + Systems & Applied Sciences Corp., Documentation for the + machine-readable version of the above catalogue, + Contract NAS 5-26490. + + (These two references give different values for the galactic + longitude of the supergalactic origin. Both are wrong; the + correct value is L2=137.37.) + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/svd.hlp b/math/slalib/doc/svd.hlp new file mode 100644 index 00000000..14b87c43 --- /dev/null +++ b/math/slalib/doc/svd.hlp @@ -0,0 +1,73 @@ +.help svd Jun99 "Slalib Package" +.nf + + SUBROUTINE slSVD (M, N, MP, NP, A, W, V, WORK, JSTAT) + + - - - - + S V D + - - - - + + Singular value decomposition (double precision) + + This routine expresses a given matrix A as the product of + three matrices U, W, V: + + A = U x W x VT + + Where: + + A is any M (rows) x N (columns) matrix, where M.GE.N + U is an M x N column-orthogonal matrix + W is an N x N diagonal matrix with W(I,I).GE.0 + VT is the transpose of an N x N orthogonal matrix + + Note that M and N, above, are the LOGICAL dimensions of the + matrices and vectors concerned, which can be located in + arrays of larger PHYSICAL dimensions, given by MP and NP. + + Given: + M,N i numbers of rows and columns in matrix A + MP,NP i physical dimensions of array containing matrix A + A d(MP,NP) array containing MxN matrix A + + Returned: + A d(MP,NP) array containing MxN column-orthogonal matrix U + W d(N) NxN diagonal matrix W (diagonal elements only) + V d(NP,NP) array containing NxN orthogonal matrix V + WORK d(N) workspace + JSTAT i 0 = OK, -1 = A wrong shape, >0 = index of W + for which convergence failed. See note 2, below. + + Notes: + + 1) V contains matrix V, not the transpose of matrix V. + + 2) If the status JSTAT is greater than zero, this need not + necessarily be treated as a failure. It means that, due to + chance properties of the matrix A, the QR transformation + phase of the routine did not fully converge in a predefined + number of iterations, something that very seldom occurs. + When this condition does arise, it is possible that the + elements of the diagonal matrix W have not been correctly + found. However, in practice the results are likely to + be trustworthy. Applications should report the condition + as a warning, but then proceed normally. + + References: + The algorithm is an adaptation of the routine SVD in the EISPACK + library (Garbow et al 1977, EISPACK Guide Extension, Springer + Verlag), which is a FORTRAN 66 implementation of the Algol + routine SVD of Wilkinson & Reinsch 1971 (Handbook for Automatic + Computation, vol 2, ed Bauer et al, Springer Verlag). These + references give full details of the algorithm used here. A good + account of the use of SVD in least squares problems is given in + Numerical Recipes (Press et al 1986, Cambridge University Press), + which includes another variant of the EISPACK code. + + P.T.Wallace Starlink 22 December 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/svdcov.hlp b/math/slalib/doc/svdcov.hlp new file mode 100644 index 00000000..48ce38df --- /dev/null +++ b/math/slalib/doc/svdcov.hlp @@ -0,0 +1,35 @@ +.help svdcov Jun99 "Slalib Package" +.nf + + SUBROUTINE slSVDC (N, NP, NC, W, V, WORK, CVM) + + - - - - - - - + S V D C + - - - - - - - + + From the W and V matrices from the SVD factorisation of a matrix + (as obtained from the slSVD routine), obtain the covariance matrix. + + (double precision) + + Given: + N i number of rows and columns in matrices W and V + NP i first dimension of array containing matrix V + NC i first dimension of array to receive CVM + W d(N) NxN diagonal matrix W (diagonal elements only) + V d(NP,NP) array containing NxN orthogonal matrix V + + Returned: + WORK d(N) workspace + CVM d(NC,NC) array to receive covariance matrix + + Reference: + Numerical Recipes, section 14.3. + + P.T.Wallace Starlink December 1988 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/svdsol.hlp b/math/slalib/doc/svdsol.hlp new file mode 100644 index 00000000..42513cfa --- /dev/null +++ b/math/slalib/doc/svdsol.hlp @@ -0,0 +1,82 @@ +.help svdsol Jun99 "Slalib Package" +.nf + + SUBROUTINE slSVDS (M, N, MP, NP, B, U, W, V, WORK, X) + + - - - - - - - + S V D S + - - - - - - - + + From a given vector and the SVD of a matrix (as obtained from + the SVD routine), obtain the solution vector (double precision) + + This routine solves the equation: + + A . x = b + + where: + + A is a given M (rows) x N (columns) matrix, where M.GE.N + x is the N-vector we wish to find + b is a given M-vector + + by means of the Singular Value Decomposition method (SVD). In + this method, the matrix A is first factorised (for example by + the routine slSVD) into the following components: + + A = U x W x VT + + where: + + A is the M (rows) x N (columns) matrix + U is an M x N column-orthogonal matrix + W is an N x N diagonal matrix with W(I,I).GE.0 + VT is the transpose of an NxN orthogonal matrix + + Note that M and N, above, are the LOGICAL dimensions of the + matrices and vectors concerned, which can be located in + arrays of larger PHYSICAL dimensions MP and NP. + + The solution is found from the expression: + + x = V . [diag(1/Wj)] . (transpose(U) . b) + + Notes: + + 1) If matrix A is square, and if the diagonal matrix W is not + adjusted, the method is equivalent to conventional solution + of simultaneous equations. + + 2) If M>N, the result is a least-squares fit. + + 3) If the solution is poorly determined, this shows up in the + SVD factorisation as very small or zero Wj values. Where + a Wj value is small but non-zero it can be set to zero to + avoid ill effects. The present routine detects such zero + Wj values and produces a sensible solution, with highly + correlated terms kept under control rather than being allowed + to elope to infinity, and with meaningful values for the + other terms. + + Given: + M,N i numbers of rows and columns in matrix A + MP,NP i physical dimensions of array containing matrix A + B d(M) known vector b + U d(MP,NP) array containing MxN matrix U + W d(N) NxN diagonal matrix W (diagonal elements only) + V d(NP,NP) array containing NxN orthogonal matrix V + + Returned: + WORK d(N) workspace + X d(N) unknown vector x + + Reference: + Numerical Recipes, section 2.9. + + P.T.Wallace Starlink 29 October 1993 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/tp2s.hlp b/math/slalib/doc/tp2s.hlp new file mode 100644 index 00000000..3cbf1c8e --- /dev/null +++ b/math/slalib/doc/tp2s.hlp @@ -0,0 +1,28 @@ +.help tp2s Jun99 "Slalib Package" +.nf + + SUBROUTINE slTP2S (XI, ETA, RAZ, DECZ, RA, DEC) + + - - - - - + T P 2 S + - - - - - + + Transform tangent plane coordinates into spherical + (single precision) + + Given: + XI,ETA real tangent plane rectangular coordinates + RAZ,DECZ real spherical coordinates of tangent point + + Returned: + RA,DEC real spherical coordinates (0-2pi,+/-pi/2) + + Called: slRA2P + + P.T.Wallace Starlink 24 July 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/tp2v.hlp b/math/slalib/doc/tp2v.hlp new file mode 100644 index 00000000..e81c60d1 --- /dev/null +++ b/math/slalib/doc/tp2v.hlp @@ -0,0 +1,40 @@ +.help tp2v Jun99 "Slalib Package" +.nf + + SUBROUTINE slTP2V (XI, ETA, V0, V) + + - - - - - + T P 2 V + - - - - - + + Given the tangent-plane coordinates of a star and the direction + cosines of the tangent point, determine the direction cosines + of the star. + + (single precision) + + Given: + XI,ETA r tangent plane coordinates of star + V0 r(3) direction cosines of tangent point + + Returned: + V r(3) direction cosines of star + + Notes: + + 1 If vector V0 is not of unit length, the returned vector V will + be wrong. + + 2 If vector V0 points at a pole, the returned vector V will be + based on the arbitrary assumption that the RA of the tangent + point is zero. + + 3 This routine is the Cartesian equivalent of the routine slTP2S. + + P.T.Wallace Starlink 11 February 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/tps2c.hlp b/math/slalib/doc/tps2c.hlp new file mode 100644 index 00000000..d1914ef2 --- /dev/null +++ b/math/slalib/doc/tps2c.hlp @@ -0,0 +1,58 @@ +.help tps2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slTPSC (XI, ETA, RA, DEC, RAZ1, DECZ1, + : RAZ2, DECZ2, N) + + - - - - - - + T P S C + - - - - - - + + From the tangent plane coordinates of a star of known RA,Dec, + determine the RA,Dec of the tangent point. + + (single precision) + + Given: + XI,ETA r tangent plane rectangular coordinates + RA,DEC r spherical coordinates + + Returned: + RAZ1,DECZ1 r spherical coordinates of tangent point, solution 1 + RAZ2,DECZ2 r spherical coordinates of tangent point, solution 2 + N i number of solutions: + 0 = no solutions returned (note 2) + 1 = only the first solution is useful (note 3) + 2 = both solutions are useful (note 3) + + Notes: + + 1 The RAZ1 and RAZ2 values are returned in the range 0-2pi. + + 2 Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value, and hence it is + meaningless to ask where the tangent point would have to be + to bring about this combination of XI and DEC. + + 3 Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N=1 indicates only one useful + solution, the usual case; under these circumstances, the second + solution corresponds to the "over-the-pole" case, and this is + reflected in the values of RAZ2 and DECZ2 which are returned. + + 4 The DECZ1 and DECZ2 values are returned in the range +/-pi, but + in the usual, non-pole-crossing, case, the range is +/-pi/2. + + 5 This routine is the spherical equivalent of the routine slDPVC. + + Called: slRA2P + + P.T.Wallace Starlink 5 June 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/tpv2c.hlp b/math/slalib/doc/tpv2c.hlp new file mode 100644 index 00000000..7a1b688d --- /dev/null +++ b/math/slalib/doc/tpv2c.hlp @@ -0,0 +1,51 @@ +.help tpv2c Jun99 "Slalib Package" +.nf + + SUBROUTINE slTPVC (XI, ETA, V, V01, V02, N) + + - - - - - - + T P V C + - - - - - - + + Given the tangent-plane coordinates of a star and its direction + cosines, determine the direction cosines of the tangent-point. + + (single precision) + + Given: + XI,ETA r tangent plane coordinates of star + V r(3) direction cosines of star + + Returned: + V01 r(3) direction cosines of tangent point, solution 1 + V02 r(3) direction cosines of tangent point, solution 2 + N i number of solutions: + 0 = no solutions returned (note 2) + 1 = only the first solution is useful (note 3) + 2 = both solutions are useful (note 3) + + Notes: + + 1 The vector V must be of unit length or the result will be wrong. + + 2 Cases where there is no solution can only arise near the poles. + For example, it is clearly impossible for a star at the pole + itself to have a non-zero XI value, and hence it is meaningless + to ask where the tangent point would have to be. + + 3 Also near the poles, cases can arise where there are two useful + solutions. The argument N indicates whether the second of the + two solutions returned is useful. N=1 indicates only one useful + solution, the usual case; under these circumstances, the second + solution can be regarded as valid if the vector V02 is interpreted + as the "over-the-pole" case. + + 4 This routine is the Cartesian equivalent of the routine slTPSC. + + P.T.Wallace Starlink 5 June 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ue2el.hlp b/math/slalib/doc/ue2el.hlp new file mode 100644 index 00000000..6eb0996a --- /dev/null +++ b/math/slalib/doc/ue2el.hlp @@ -0,0 +1,167 @@ +.help ue2el Jun99 "Slalib Package" +.nf + + SUBROUTINE slUEEL (U, JFORMR, + : JFORM, EPOCH, ORBINC, ANODE, PERIH, + : AORQ, E, AORL, DM, JSTAT) + + - - - - - - + U E E L + - - - - - - + + Transform universal elements into conventional heliocentric + osculating elements. + + Given: + U d(13) universal orbital elements (Note 1) + + (1) combined mass (M+m) + (2) total energy of the orbit (alpha) + (3) reference (osculating) epoch (t0) + (4-6) position at reference epoch (r0) + (7-9) velocity at reference epoch (v0) + (10) heliocentric distance at reference epoch + (11) r0.v0 + (12) date (t) + (13) universal eccentric anomaly (psi) of date, approx + + JFORMR i requested element set (1-3; Note 3) + + Returned: + JFORM d element set actually returned (1-3; Note 4) + EPOCH d epoch of elements (TT MJD) + ORBINC d inclination (radians) + ANODE d longitude of the ascending node (radians) + PERIH d longitude or argument of perihelion (radians) + AORQ d mean distance or perihelion distance (AU) + E d eccentricity + AORL d mean anomaly or longitude (radians, JFORM=1,2 only) + DM d daily motion (radians, JFORM=1 only) + JSTAT i status: 0 = OK + -1 = illegal combined mass + -2 = illegal JFORMR + -3 = position/velocity out of range + + Notes + + 1 The "universal" elements are those which define the orbit for the + purposes of the method of universal variables (see reference 2). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i) alpha, which is proportional to the total energy of the + orbit, (ii) the heliocentric distance at epoch, (iii) the + outwards component of the velocity at the given epoch, (iv) an + estimate of psi, the "universal eccentric anomaly" at a given + date and (v) that date. + + 2 The universal elements are with respect to the mean equator and + equinox of epoch J2000. The orbital elements produced are with + respect to the J2000 ecliptic and mean equinox. + + 3 Three different element-format options are supported: + + Option JFORM=1, suitable for the major planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = longitude of perihelion, curly pi (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean longitude L (radians) + DM = daily motion (radians) + + Option JFORM=2, suitable for minor planets: + + EPOCH = epoch of elements (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = mean distance, a (AU) + E = eccentricity, e + AORL = mean anomaly M (radians) + + Option JFORM=3, suitable for comets: + + EPOCH = epoch of perihelion (TT MJD) + ORBINC = inclination i (radians) + ANODE = longitude of the ascending node, big omega (radians) + PERIH = argument of perihelion, little omega (radians) + AORQ = perihelion distance, q (AU) + E = eccentricity, e + + 4 It may not be possible to generate elements in the form + requested through JFORMR. The caller is notified of the form + of elements actually returned by means of the JFORM argument: + + JFORMR JFORM meaning + + 1 1 OK - elements are in the requested format + 1 2 never happens + 1 3 orbit not elliptical + + 2 1 never happens + 2 2 OK - elements are in the requested format + 2 3 orbit not elliptical + + 3 1 never happens + 3 2 never happens + 3 3 OK - elements are in the requested format + + 5 The arguments returned for each value of JFORM (cf Note 6: JFORM + may not be the same as JFORMR) are as follows: + + JFORM 1 2 3 + EPOCH t0 t0 T + ORBINC i i i + ANODE Omega Omega Omega + PERIH curly pi omega omega + AORQ a a q + E e e e + AORL L M - + DM n - - + + where: + + t0 is the epoch of the elements (MJD, TT) + T " epoch of perihelion (MJD, TT) + i " inclination (radians) + Omega " longitude of the ascending node (radians) + curly pi " longitude of perihelion (radians) + omega " argument of perihelion (radians) + a " mean distance (AU) + q " perihelion distance (AU) + e " eccentricity + L " longitude (radians, 0-2pi) + M " mean anomaly (radians, 0-2pi) + n " daily motion (radians) + - means no value is set + + 6 At very small inclinations, the longitude of the ascending node + ANODE becomes indeterminate and under some circumstances may be + set arbitrarily to zero. Similarly, if the orbit is close to + circular, the true anomaly becomes indeterminate and under some + circumstances may be set arbitrarily to zero. In such cases, + the other elements are automatically adjusted to compensate, + and so the elements remain a valid description of the orbit. + + References: + + 1 Sterne, Theodore E., "An Introduction to Celestial Mechanics", + Interscience Publishers Inc., 1960. Section 6.7, p199. + + 2 Everhart, E. & Pitkin, E.T., Am.J.Phys. 51, 712, 1983. + + Called: slPVEL + + P.T.Wallace Starlink 18 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/ue2pv.hlp b/math/slalib/doc/ue2pv.hlp new file mode 100644 index 00000000..ed5c9609 --- /dev/null +++ b/math/slalib/doc/ue2pv.hlp @@ -0,0 +1,87 @@ +.help ue2pv Jun99 "Slalib Package" +.nf + + SUBROUTINE slUEPV (DATE, U, PV, JSTAT) + + - - - - - - + U E P V + - - - - - - + + Heliocentric position and velocity of a planet, asteroid or comet, + starting from orbital elements in the "universal variables" form. + + Given: + DATE d date, Modified Julian Date (JD-2400000.5) + + Given and returned: + U d(13) universal orbital elements (updated; Note 1) + + given (1) combined mass (M+m) + " (2) total energy of the orbit (alpha) + " (3) reference (osculating) epoch (t0) + " (4-6) position at reference epoch (r0) + " (7-9) velocity at reference epoch (v0) + " (10) heliocentric distance at reference epoch + " (11) r0.v0 + returned (12) date (t) + " (13) universal eccentric anomaly (psi) of date + + Returned: + PV d(6) position (AU) and velocity (AU/s) + JSTAT i status: 0 = OK + -1 = radius vector zero + -2 = failed to converge + + Notes + + 1 The "universal" elements are those which define the orbit for the + purposes of the method of universal variables (see reference). + They consist of the combined mass of the two bodies, an epoch, + and the position and velocity vectors (arbitrary reference frame) + at that epoch. The parameter set used here includes also various + quantities that can, in fact, be derived from the other + information. This approach is taken to avoiding unnecessary + computation and loss of accuracy. The supplementary quantities + are (i) alpha, which is proportional to the total energy of the + orbit, (ii) the heliocentric distance at epoch, (iii) the + outwards component of the velocity at the given epoch, (iv) an + estimate of psi, the "universal eccentric anomaly" at a given + date and (v) that date. + + 2 The companion routine is slELUE. This takes the conventional + orbital elements and transforms them into the set of numbers + needed by the present routine. A single prediction requires one + one call to slELUE followed by one call to the present routine; + for convenience, the two calls are packaged as the routine + slPLNE. Multiple predictions may be made by again + calling slELUE once, but then calling the present routine + multiple times, which is faster than multiple calls to slPLNE. + + It is not obligatory to use slELUE to obtain the parameters. + However, it should be noted that because slELUE performs its + own validation, no checks on the contents of the array U are made + by the present routine. + + 3 DATE is the instant for which the prediction is required. It is + in the TT timescale (formerly Ephemeris Time, ET) and is a + Modified Julian Date (JD-2400000.5). + + 4 The universal elements supplied in the array U are in canonical + units (solar masses, AU and canonical days). The position and + velocity are not sensitive to the choice of reference frame. The + slELUE routine in fact produces coordinates with respect to the + J2000 equator and equinox. + + 5 The algorithm was originally adapted from the EPHSLA program of + D.H.P.Jones (private communication, 1996). The method is based + on Stumpff's Universal Variables. + + Reference: Everhart, E. & Pitkin, E.T., Am.J.Phys. 51, 712, 1983. + + P.T.Wallace Starlink 19 March 1999 + + Copyright (C) 1999 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/unpcd.hlp b/math/slalib/doc/unpcd.hlp new file mode 100644 index 00000000..26654492 --- /dev/null +++ b/math/slalib/doc/unpcd.hlp @@ -0,0 +1,57 @@ +.help unpcd Jun99 "Slalib Package" +.nf + + SUBROUTINE slUPCD (DISCO,X,Y) + + - - - - - - + U P C D + - - - - - - + + Remove pincushion/barrel distortion from a distorted [x,y] + to give tangent-plane [x,y]. + + Given: + DISCO d pincushion/barrel distortion coefficient + X,Y d distorted coordinates + + Returned: + X,Y d tangent-plane coordinates + + Notes: + + 1) The distortion is of the form RP = R*(1 + C*R**2), where R is + the radial distance from the tangent point, C is the DISCO + argument, and RP is the radial distance in the presence of + the distortion. + + 2) For pincushion distortion, C is +ve; for barrel distortion, + C is -ve. + + 3) For X,Y in "radians" - units of one projection radius, + which in the case of a photograph is the focal length of + the camera - the following DISCO values apply: + + Geometry DISCO + + astrograph 0.0 + Schmidt -0.3333 + AAT PF doublet +147.069 + AAT PF triplet +178.585 + AAT f/8 +21.20 + JKT f/8 +13.32 + + 4) The present routine is an approximate inverse to the + companion routine slPCD, obtained from two iterations + of Newton's method. The mismatch between the slPCD and + slUPCD routines is negligible for astrometric applications; + to reach 1 milliarcsec at the edge of the AAT triplet or + Schmidt field would require field diameters of 2.4 degrees + and 42 degrees respectively. + + P.T.Wallace Starlink 1 August 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/v2tp.hlp b/math/slalib/doc/v2tp.hlp new file mode 100644 index 00000000..6522e398 --- /dev/null +++ b/math/slalib/doc/v2tp.hlp @@ -0,0 +1,42 @@ +.help v2tp Jun99 "Slalib Package" +.nf + + SUBROUTINE slV2TP (V, V0, XI, ETA, J) + + - - - - - + V 2 T P + - - - - - + + Given the direction cosines of a star and of the tangent point, + determine the star's tangent-plane coordinates. + + (single precision) + + Given: + V r(3) direction cosines of star + V0 r(3) direction cosines of tangent point + + Returned: + XI,ETA r tangent plane coordinates of star + J i status: 0 = OK + 1 = error, star too far from axis + 2 = error, antistar on tangent plane + 3 = error, antistar too far from axis + + Notes: + + 1 If vector V0 is not of unit length, or if vector V is of zero + length, the results will be wrong. + + 2 If V0 points at a pole, the returned XI,ETA will be based on the + arbitrary assumption that the RA of the tangent point is zero. + + 3 This routine is the Cartesian equivalent of the routine slS2TP. + + P.T.Wallace Starlink 27 November 1996 + + Copyright (C) 1996 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/vdv.hlp b/math/slalib/doc/vdv.hlp new file mode 100644 index 00000000..526ce406 --- /dev/null +++ b/math/slalib/doc/vdv.hlp @@ -0,0 +1,24 @@ +.help vdv Jun99 "Slalib Package" +.nf + + REAL FUNCTION slVDV (VA, VB) + + - - - - + V D V + - - - - + + Scalar product of two 3-vectors (single precision) + + Given: + VA real(3) first vector + VB real(3) second vector + + The result is the scalar product VA.VB (single precision) + + P.T.Wallace Starlink November 1984 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/vn.hlp b/math/slalib/doc/vn.hlp new file mode 100644 index 00000000..17b7b3ba --- /dev/null +++ b/math/slalib/doc/vn.hlp @@ -0,0 +1,27 @@ +.help vn Jun99 "Slalib Package" +.nf + + SUBROUTINE slVN (V, UV, VM) + + - - - + V N + - - - + + Normalizes a 3-vector also giving the modulus (single precision) + + Given: + V real(3) vector + + Returned: + UV real(3) unit vector in direction of V + VM real modulus of V + + If the modulus of V is zero, UV is set to zero as well + + P.T.Wallace Starlink 23 November 1995 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/vxv.hlp b/math/slalib/doc/vxv.hlp new file mode 100644 index 00000000..64272c33 --- /dev/null +++ b/math/slalib/doc/vxv.hlp @@ -0,0 +1,25 @@ +.help vxv Jun99 "Slalib Package" +.nf + + SUBROUTINE slVXV (VA, VB, VC) + + - - - - + V X V + - - - - + + Vector product of two 3-vectors (single precision) + + Given: + VA real(3) first vector + VB real(3) second vector + + Returned: + VC real(3) vector result + + P.T.Wallace Starlink March 1986 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/xy2xy.hlp b/math/slalib/doc/xy2xy.hlp new file mode 100644 index 00000000..64ab43e2 --- /dev/null +++ b/math/slalib/doc/xy2xy.hlp @@ -0,0 +1,45 @@ +.help xy2xy Jun99 "Slalib Package" +.nf + + SUBROUTINE slXYXY (X1,Y1,COEFFS,X2,Y2) + + - - - - - - + X Y X Y + - - - - - - + + Transform one [X,Y] into another using a linear model of the type + produced by the slFTXY routine. + + Given: + X1 d x-coordinate + Y1 d y-coordinate + COEFFS d(6) transformation coefficients (see note) + + Returned: + X2 d x-coordinate + Y2 d y-coordinate + + The model relates two sets of [X,Y] coordinates as follows. + Naming the elements of COEFFS: + + COEFFS(1) = A + COEFFS(2) = B + COEFFS(3) = C + COEFFS(4) = D + COEFFS(5) = E + COEFFS(6) = F + + the present routine performs the transformation: + + X2 = A + B*X1 + C*Y1 + Y2 = D + E*X1 + F*Y1 + + See also slFTXY, slPXY, slINVF, slDCMF + + P.T.Wallace Starlink 5 December 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp diff --git a/math/slalib/doc/zd.hlp b/math/slalib/doc/zd.hlp new file mode 100644 index 00000000..109b4d10 --- /dev/null +++ b/math/slalib/doc/zd.hlp @@ -0,0 +1,48 @@ +.help zd Jun99 "Slalib Package" +.nf + + DOUBLE PRECISION FUNCTION slZD (HA, DEC, PHI) + + - - - + Z D + - - - + + HA, Dec to Zenith Distance (double precision) + + Given: + HA d Hour Angle in radians + DEC d declination in radians + PHI d observatory latitude in radians + + The result is in the range 0 to pi. + + Notes: + + 1) The latitude must be geodetic. In critical applications, + corrections for polar motion should be applied. + + 2) In some applications it will be important to specify the + correct type of hour angle and declination in order to + produce the required type of zenith distance. In particular, + it may be important to distinguish between the zenith distance + as affected by refraction, which would require the "observed" + HA,Dec, and the zenith distance in vacuo, which would require + the "topocentric" HA,Dec. If the effects of diurnal aberration + can be neglected, the "apparent" HA,Dec may be used instead of + the topocentric HA,Dec. + + 3) No range checking of arguments is done. + + 4) In applications which involve many zenith distance calculations, + rather than calling the present routine it will be more efficient + to use inline code, having previously computed fixed terms such + as sine and cosine of latitude, and perhaps sine and cosine of + declination. + + P.T.Wallace Starlink 3 April 1994 + + Copyright (C) 1995 Rutherford Appleton Laboratory + Copyright (C) 1995 Association of Universities for Research in Astronomy Inc. + +.fi +.endhelp |