path: root/math/slalib/doc/read.me

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