216 lines
9.4 KiB
Plaintext
216 lines
9.4 KiB
Plaintext
intro.lis 2018 December 7
|
|
|
|
|
|
-------------------------------
|
|
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 189
|
|
"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 189 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,
|
|
gnomonic projection, horizon/equatorial 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 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.
|