1 INTRODUCTION

1.1 Purpose

1.3 Scope
1.4 Objectives

1.6 C Version

1.1 Purpose

SLALIB1 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 proprietary ANSI C version is also available from the author; it is functionally similar to the Fortran version upon which the present document concentrates.

1.2 Example Application

Here is a simple example of an application program written using SLALIB calls:

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

*   Loop until a period is entered
C = ’ ’
DO WHILE (C(:1).NE.’.’)

*     Read h m s d ’ "
IF (C(:1).NE.’.’) THEN

*        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
END IF
END IF
END IF
END DO

END

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 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.

1.3 Scope

SLALIB contains 188 routines covering the following topics:

• String Decoding, Sexagesimal Conversions
• Angles, Vectors & Rotation Matrices
• Calendars, Time Scales
• Precession & Nutation
• Proper Motion
• FK4/FK5/Hipparcos, Elliptic Aberration
• Geocentric Coordinates
• Apparent & Observed Place
• Azimuth & Elevation
• Refraction & Air Mass
• Ecliptic, Galactic, Supergalactic Coordinates
• Ephemerides
• Astrometry
• Numerical Methods

1.4 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:

• Readily available, including source code and documentation.
• Supported and maintained.
• Portable – coded in standard languages and available for multiple computers and operating systems.
• Thoroughly commented, both for maintainability and to assist those wishing to cannibalize the code.
• Stable.
• Trustworthy – some care has gone into testing SLALIB, both by comparison with published data and by checks for internal consistency.
• Rigorous – corners are not cut, even where the practical consequences would, as a rule, be negligible.
• Comprehensive, without including too many esoteric features required only by specialists.
• Practical – almost all the routines have been written to satisfy real needs encountered during the development of real-life applications.
• Environment-independent – the package is completely free of pauses, stops, I/O etc.
• Self-contained – SLALIB calls no other libraries.

A few caveats:

• 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.
• 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.
• There are omissions – for example there are no routines for calculating physical ephemerides of Solar-System bodies.
• SLALIB is not homogeneous, though important subsets (for example the FK4/FK5 routines) are.
• The library is not foolproof. You have to know what you are trying to do (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).
• 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.

1.5 Fortran Version

The Fortran versions of SLALIB use ANSI Fortran 77 with a few commonplace extensions. Just three out of the 188 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.

1.6 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) SLA_REFRO is slaRefro. The types of arguments follow the Fortran version, except that integers are int rather than long (the one exception being slaIntin, which returns a long and is supplemented by an additional routine, not present in the Fortran SLALIB, called slaInt2in, which returns an int). 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 sla_GRESID, sla_RANDOM and 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 slalib.h.

1.7 Future Versions

The homogeneity and ease of use of SLALIB could perhaps be improved in the future by turning to object-oriented techniques, in particular through the C++ and Java languages. For example “celestial position” could be a class and many of the transformations could happen automatically. This requires further study and would result in a complete redesign. Various attempts have been made to do this, but none as yet has the author’s seal of approval. Furthermore, the impact of Fortran 90 has yet to be assessed. Should 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.

1.8 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.

1.9 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, time scales 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, the late 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 introducing me to the “universal variables” method of calculating orbits.

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).

1The name isn’t an acronym; it just stands for “Subprogram Library A”.