source: trunk/FACT++/sofa/doc/intro.lis@ 18368

intro.lis                                                2015 January 29


                  -------------------------------
                  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 166
  "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 164 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 file sofa_pn.pdf describes the SOFA tools for precession-nutation
and other aspects of Earth attitude and includes example code and (see
the appendix) diagrams showing the interrelationships between the
routines supporting the latest (IAU 2006/2000A) models.  Four other
documents introduce time scale transformations (sofa_ts_f.pdf and
sofa_ts_c.pdf for Fortran and C users respectively) 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.