Initial commit
This commit is contained in:
Francois NGUYEN
215
20200721/c/doc/intro.lis
Normal file
215
20200721/c/doc/intro.lis
Normal file
@@ -0,0 +1,215 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user