intro.lis 2016 March 14 ------------------------------- THE IAU-SOFA SOFTWARE LIBRARIES ------------------------------- SOFA stands for "Standards Of Fundamental Astronomy". The SOFA software libraries are a collection of subprograms, in source- code form, which implement official IAU algorithms for fundamental- astronomy computations. The subprograms at present comprise 176 "astronomy" routines supported by 55 "vector/matrix" routines, available in both Fortran77 and C implementations. THE SOFA INITIATIVE SOFA is an IAU Service which operates as a Standing Working Group under Division A (Fundamental Astronomy). The IAU set up the SOFA initiative at the 1994 General Assembly, to promulgate an authoritative set of fundamental-astronomy constants and algorithms. At the subsequent General Assembly, in 1997, the appointment of a review board and the selection of a site for the SOFA Center (the outlet for SOFA products) were announced. The SOFA initiative was originally proposed by the IAU Working Group on Astronomical Standards (WGAS), under the chairmanship of Toshio Fukushima. The proposal was for "...new arrangements to establish and maintain an accessible and authoritative set of constants, algorithms and procedures that implement standard models used in fundamental astronomy". The SOFA Software Libraries implement the "algorithms" part of the SOFA initiative. They were developed under the supervision of an international panel called the SOFA Board. The current membership of this panel is listed in an appendix. A feature of the original SOFA software proposals was that the products would be self-contained and not depend on other software. This includes basic documentation, which, like the present file, will mostly be plain ASCII text. It should also be noted that there is no assumption that the software will be used on a particular computer and Operating System. Although OS-related facilities may be present (Unix make files for instance, use by the SOFA Center of automatic code management systems, HTML versions of some documentation), the routines themselves will be visible as individual text files and will run on a variety of platforms. ALGORITHMS The SOFA Board's initial goal has been to create a set of callable subprograms. Whether "subroutines" or "functions", they are all referred to simply as "routines". They are designed for use by software developers wishing to write complete applications; no runnable, free- standing applications are included in SOFA's present plans. The algorithms are drawn from a variety of sources. Because most of the routines so far developed have either been standard "text-book" operations or implement well-documented standard algorithms, it has not been necessary to invite the whole community to submit algorithms, though consultation with authorities has occurred where necessary. It should also be noted that consistency with the conventions published by the International Earth Rotation Service was a stipulation in the original SOFA proposals, further constraining the software designs. This state of affairs will continue to exist for some time, as there is a large backlog of agreed extensions to work on. However, in the future the Board may decide to call for proposals, and is in the meantime willing to look into any suggestions that are received by the SOFA Center. SCOPE The routines currently available are listed in the next two chapters of this document. The "astronomy" library comprises 176 routines (plus one obsolete Fortran routine that now appears under a revised name). The areas addressed include calendars, astrometry, time scales, Earth rotation, ephemerides, precession-nutation, star catalog transformations, and geodetic/geocentric transformations. The "vector-matrix" library, comprising 55 routines, contains a collection of simple tools for manipulating the vectors, matrices and angles used by the astronomy routines. There is no explicit commitment by SOFA to support historical models, though as time goes on a legacy of superseded models will naturally accumulate. There is, for example, no support of B1950/FK4 star coordinates, or pre-1976 precession models, though these capabilities could be added were there significant demand. Though the SOFA software libraries are rather limited in scope, and are likely to remain so for a considerable time, they do offer distinct advantages to prospective users. In particular, the routines are: * authoritative: they are IAU-backed and have been constructed with great care; * practical: they are straightforward to use in spite of being precise and rigorous (to some stated degree); * accessible and supported: they are downloadable from an easy-to- find place, they are in an integrated and consistent form, they come with adequate internal documentation, and help for users is available. VERSIONS Once it has been published, an issue is never revised or updated, and remains accessible indefinitely. Subsequent issues may, however, include corrected versions under the original routine name and filenames. However, where a different model is introduced, it will have a different name. The issues will be referred to by the date when they were announced. The frequency of re-issue will be decided by the Board, taking into account the importance of the changes and the impact on the user community. DOCUMENTATION At present there is little free-standing documentation about individual routines. However, each routine has preamble comments which specify in detail what the routine does and how it is used. The files sofa_pn_f.pdf and sofa_pn_c.pdf (for Fortran and C users respectively) describe the SOFA tools for precession-nutation and other aspects of Earth attitude, and include example code and, in an appendix, diagrams showing the interrelationships between the routines supporting the latest (IAU 2006/2000A) models. Two other pairs of documents introduce time scale transformations (sofa_ts_f.pdf and sofa_ts_c.pdf ) and astrometric transformations (sofa_ast_f.pdf and sofa_ast_c.pdf). PROGRAMMING LANGUAGES AND STANDARDS The SOFA routines are available in two programming languages at present: Fortran77 and ANSI C. Related software in other languages is under consideration. The Fortran code conforms to ANSI X3.9-1978 in all but two minor respects: each has an IMPLICIT NONE declaration, and its name has a prefix of "iau_" and may be longer than 6 characters. A global edit to erase both of these will produce ANSI-compliant code with no change in its function. Coding style, and restrictions on the range of language features, have been much debated by the Board, and the results comply with the majority view. There is (at present) no document that defines the standards, but the code itself offers a wide range of examples of what is acceptable. The Fortran routines contain explicit numerical constants (the INCLUDE statement is not part of ANSI Fortran77). These are drawn from the file consts.lis, which is listed in an appendix. Constants for the SOFA/C functions are defined in a header file sofam.h. The naming convention is such that a SOFA routine referred to generically as "EXAMPL" exists as a Fortran subprogram iau_EXAMPL and a C function iauExampl. The calls for the two versions are very similar, with the same arguments in the same order. In a few cases, the C equivalent of a Fortran SUBROUTINE subprogram uses a return value rather than an argument. Each language version includes a "testbed" main-program that can be used to verify that the SOFA routines have been correctly compiled on the end user's system. The Fortran and C versions are called t_sofa_f.for and t_sofa_c.c respectively. The testbeds execute every SOFA routine and check that the results are within expected accuracy margins. It is not possible to guarantee that all platforms will meet the rather stringent criteria that have been used, and an occasional warning message may be encountered on some systems. COPYRIGHT ISSUES Copyright for all of the SOFA software and documentation is owned by the IAU SOFA Board. The Software is made available free of charge for all classes of user, including commercial. However, there are strict rules designed to avoid unauthorized variants coming into circulation. It is permissible to distribute derived works and other modifications, but they must be clearly marked to avoid confusion with the SOFA originals. Further details are included in the block of comments which concludes every routine. The text is also set out in an appendix to the present document. ACCURACY The SOFA policy is to organize the calculations so that the machine accuracy is fully exploited. The gap between the precision of the underlying model or theory and the computational resolution has to be kept as large as possible, hopefully leaving several orders of magnitude of headroom. The SOFA routines in some cases involve design compromises between rigor and ease of use (and also speed, though nowadays this is seldom a major concern). ACKNOWLEDGEMENTS The Board is indebted to a number of contributors, who are acknowledged in the preamble comments of the routines concerned. The Board's effort is provided by the members' individual institutes. Resources for operating the SOFA Center are provided by Her Majesty's Nautical Almanac Office, operated by the United Kingdom Hydrographic Office.