User's Guide To NOVAS Version C3.1
NOVAS_C3.1_Guide
NOVAS_C3.1_Guide
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 124
| Download | |
| Open PDF In Browser | View PDF |
User’s Guide
to NOVAS Version C3.1
Naval Observatory Vector Astrometry Software
C Edition
John Bangert
Wendy Puatua
George Kaplan
Jennifer Bartlett
William Harris
Amy Fredericks
Alice Monet
U.S. Naval Observatory
March 2011
Approved for Public Release
User ’s Guide to NOVAS Ver sion C3.1
Naval Obser vator y Vector Astr ometr y Softwar e
C Edition
In this document, hyperlinks are in blue.
Table of Contents
Introduction
Citing NOVAS
Acknowledgements
References
Abbreviations and Symbols Frequently Used
C-7
C-8
C-9
C-9
C-10
Chapter
1 Astronomical Background
1.1
Astronomical Coordinate Systems
1.2
Computing Observable Quantities
1.3
Time Scales for Astronomy
1.4
Adopted Models for Precession and Nutation
1.5
New Model for the Rotation of the Earth about its Axis
1.6
Terrestrial-Celestial Relationships
1.7
References
C-13
C-13
C-16
C-19
C-21
C-22
C-23
C-24
Chapter
2 Installing NOVAS
2.1
List of Distribution Files
2.2
Installation and Basic Validation
2.3
Using External Solar System Ephemeris Files
2.4
Using External Minor Planet Ephemeris Files
2.5
Using an External CIO File
2.6
Reduced-accuracy Mode
2.7
References
C-25
C-25
C-27
C-28
C-29
C-30
C-31
C-32
Chapter
3 Sample Calculations
3.1
Initialization
3.2
Setting Time Arguments
3.3
Example 1—Position of a Star
3.4
Example 2—Position of the Moon
3.5
Example 3—Greenwich Sidereal Time
3.6
Example 4—Other Frequently Requested Quantities
C-33
C-33
C-34
C-35
C-36
C-38
C-38
Chapter
4 Data Structures and Functions
4.1
Important Data Structures
Structure cat_entry
Structure object
Structure on_surface
Structure in_space
C-41
C-41
C-41
C-42
C-42
C-43
C-3
4.2
4.3
Chapter
Structure observer
Structure sky_pos
Structure ra_of_cio
Function List (table)
Important Functions in NOVAS
place
sidereal_time
ter2cel
cel2ter
equ2hor
transform_cat
transform_hip
app_star
topo_star
virtual_star
local_star
astro_star
app_planet
topo_planet
virtual_planet
local_planet
astro_planet
precession
equ2ecl
cio_ra
era
cel_pole
e_tilt
ephemeris
solarsystem
solarsystem, Version 1
solarsystem, Version 2
solarsystem, Version 3
solarsystem_hp
solarsystem_hp, Version 1
solarsystem_hp, Version 2
solarsystem_hp, Version 3
Nutation Models
5 Equinox- and CIO-Based Paradigms Compared
5.1
Computing Hour Angles
5.2
Other Computational Considerations
5.3
How NOVAS Implements the CIO-Based Paradigm
5.4
References
C-4
C-43
C-43
C-43
C-44
C-47
C-48
C-51
C-53
C-54
C-55
C-57
C-59
C-61
C-62
C-64
C-65
C-66
C-67
C-68
C-70
C-71
C-73
C-74
C-76
C-78
C-79
C-80
C-82
C-83
C-85
C-87
C-88
C-90
C-91
C-92
C-93
C-95
C-96
C-97
C-97
C-98
C-99
C-100
Appendix A Overview of How NOVAS Has Changed
A.1
Important Changes in Calls
A.2
place: A New General-Purpose “Place” Function
A.3
New Reference Systems
A.4
New Models for Precession and Nutation
A.5
New Model for the Rotation of the Earth about its Axis
A.6
New Features
A.7
New Terminology
A.8
References
C-101
C-101
C-102
C-102
C-103
C-104
C-105
C-105
C-105
Appendix B List of Changes from NOVAS C2.0.1 to C3.1
B.1
New Functions
B.1.1
New Functions in NOVAS C3.0
B.1.2
New Functions in NOVAS C3.1
B.2
Changes to NOVAS C Structures and Calling Sequences
B.2.1
Changes from C2.0.1 to C3.0
B.2.2
Changes from C3.0 to C3.1
B.3
Significant Internal Changes to Code
B.3.1
Significant Internal Changes to Code from C2.0.1 to C3.0
B.3.2
Significant Internal Changes to Code from C3.0 to C3.1
B.4
Other Internal Code Changes
B.4.1
Other Internal Code Changes from C2.0.1 to C3.0
B.4.2
Other Internal Code Changes from C3.0 to C3.1
B.5
References
C-107
C-107
C-107
C-109
C-109
C-109
C-110
C-111
C-111
C-113
C-114
C-114
C-114
C-114
Appendix C How to Set Up the JPL Ephemerides
C.1
Overview
C.2
Step-by-Step Guide
C-117
C-117
C-117
Appendix D A Comparison of SOFA and NOVAS C3.0
D.1
Goal
D.2
Procedure
D.3
Results
D.4
References
D.5
Addendum: NOVAS C3.0 Code
C-121
C-121
C-121
C-122
C-123
C-124
C-5
C-6
Intr oduction
The Naval Observatory Vector Astrometry Software (NOVAS) is a source-code library in
Fortran, C, and Python that provides common astrometric quantities and transformations. It
can supply, in one or two function calls, the instantaneous celestial position of any star or
planet in a variety of coordinate systems. The library also provides access to all of the
“building blocks” that go into such computations—single-purpose functions for common
astrometric algorithms, such as those for precession, nutation, aberration, parallax, etc.
NOVAS calculations are accurate at the sub-milliarcsecond level. The package is an easy-touse facility that can be incorporated into data reduction programs, telescope control systems,
and simulations. The United States (U.S.) Nautical Almanac Office uses NOVAS in the
production of its sections of The Astronomical Almanac.
The NOVAS algorithms are based on a vector and matrix formulation that is rigorous and
consistent with recent recommendations of the International Astronomical Union (IAU).
Objects inside and outside the solar system are treated similarly. The position vectors formed
and operated on by the NOVAS functions are defined within either the Barycentric Celestial
Reference System (BCRS) or the Geocentric Celestial Reference System (GCRS), as
appropriate. Both of these systems are described in IAU resolutions passed in 2000. GCRS
quantities are converted to more familiar coordinate systems, such as the equator and equinox
of date, by applying standard rotations.
Three levels of functions are involved: basic, utility, and supervisory. Basic-level functions
supply the values of fundamental variables, such as the nutation angles and the heliocentric
positions of solar system bodies, for specific epochs. Utility-level functions perform
computations corresponding to individual physical effects or transformations (aberration,
light-bending, precession, polar motion, etc.). Supervisory-level functions call the basic and
utility subroutines in the proper order to compute the apparent coordinates of stars or solar
system bodies for specific dates and times. If desired, users can interact exclusively with the
supervisory-level functions and not become concerned with the details of the geometry or
physical models involved in the computation.
The Fortran version of NOVAS goes back to the late 1970s but has been updated periodically
to use new, more accurate models that represent the evolving standards of the international
astronomical and geodetic communities. The success of the initial Fortran package led to
requests for a C-language version. In the early 1990s, the U.S. Naval Observatory
(USNO)/Naval Research Laboratory (NRL) optical interferometer group converted parts of
NOVAS to C for use in their project. That work formed the basis for the first complete
edition of NOVAS in C (designated NOVAS Version C1.0), which the USNO Astronomical
Applications (AA) Department completed and released in 1996. A major revision of the
NOVAS Fortran code took place in 1998, with the primary goal of supporting data
conforming to the International Celestial Reference System (ICRS). Shortly thereafter, the C
version of NOVAS was updated to version C2.0 to reflect the changes in the Fortran code
and to extend its capabilities. In response to user requests, NOVAS 3.1 introduces a Python
edition. The initial Python release is a set of wrappers around the current C code. In fullaccuracy calculations using the same data sources, differences in the results from Fortran and
C-7
C editions of NOVAS, for the same calculation, should not exceed 6 × 10−8 arcseconds
(3 × 10−13 radians) for solar system bodies and 7 × 10−10 arcseconds (3 × 10−15 radians) for
stars.
Previous versions of NOVAS were based on the algorithms described in Kaplan et al.
(1989). 1 Although the phenomena that are considered and the overall sequence of
calculations remains much the same in the current release, many of the models have been
improved substantially over the last two decades in response to increased accuracy in
observing techniques. Specifically, version 3.0 of NOVAS, released in 2009 and described
in USNO Circular 180, 2 implements the resolutions on astronomical reference systems and
Earth-rotation models passed at the IAU General Assemblies in 1997, 2000, and 2006. An
explanation of the recent IAU resolutions can be found in The IAU Resolutions on
Astronomical Reference Systems, Time Scales, and Earth Rotation Models: Explanation and
Implementation (Kaplan 2005; hereafter USNO Circular 179 3), which contains significantly
more information on topics only briefly mentioned in this document. NOVAS 3.0 also
improves the accuracy of its star and planet position calculations by including several small
effects not previously implemented in the code; see, for example, Klioner (2003). In addition,
some new convenience functions have been added in NOVAS 3.0. The current version,
NOVAS 3.1, provides some new capabilities and fixes some bugs.
Although Chapter 1 provides some background material, the intent of this user’s guide is not
to explain positional astronomy. Many books have been written on this subject. NOVAS
users who desire additional information on the terminology and concepts used in the software
should consult The Explanatory Supplement to the Astronomical Almanac (Seidelmann 1992;
hereafter The Explanatory Supplement) and USNO Circular 179. Until the revision of the
former publication is completed, the latter serves as an important update providing an
explanation of the recent IAU resolutions.
Citing NOVAS
If you use NOVAS, please send us an e-mail 4 that outlines your application. This
information helps justify further improvements to NOVAS. Your comments and suggestions
are also welcome.
This user's guide is the official reference for NOVAS C3.1 and may be cited as
Bangert, J., Puatua, W., Kaplan, G., Bartlett, J., Harris, W., Fredericks, A., & Monet, A.
2011, User’s Guide to NOVAS Version C3.1 (Washington, DC: USNO)
In addition, we ask that you also direct your readers to the NOVAS website. 5
1
Hohenkerk et al. (1992) reprinted parts of this article in Chapter 3 of The Explanatory Supplement to the
Astronomical Almanac.
2
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-180
3
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
4
http://www.usno.navy.mil/help/astronomy-help
5
The current version of NOVAS may be obtained at http://www.usno.navy.mil/USNO/astronomicalapplications/software-products/novas
C-8
The official reference for NOVAS 3.0 is USNO Circular 180, which may be cited as
Kaplan, G., Bangert, J., Bartlett, J., Puatua, W., & Monet, A. 2009, User’s Guide to NOVAS
3.0, USNO Circular 180 (Washington, DC: USNO)
The official reference for all versions of NOVAS prior to 3.0 is the 1990 software report
announcing its release, which is
Kaplan, G. 1990, “NOVAS: U. S. Naval Observatory,” Bull. AAS, 22, 930
Acknowledgements
Current version: William T. Harris of the USNO AA Department wrote most of the C code
that accesses the JPL binary solar-system ephemerides (files eph_manager.c and solsys1.c).
Previous versions: Thomas K. Buchanan, working as part of the USNO/NRL Optical
Interferometer team, did the initial conversion of many of the NOVAS Fortran subroutines to
C. William T. Harris was largely responsible for completing the conversion, and for NOVAS
Version C1.0. David Buscher, James Hilton, Christian Hummel, and Sandra Martinka, users
of early C versions of NOVAS, provided valuable comments and suggestions.
References
Hohenkerk, C. Y., Yallop, B. D., Smith, C. A., & Sinclair, A. T. 1992, in The Explanatory
Supplement to the Astronomical Almanac, ed. P. K. Seidelmann (Mill Valley, CA: Univ. Sci.
Books) 95
Kaplan, G. 1990, Bull. AAS, 22, 930
Kaplan, G. H. 2005, The IAU Resolutions on Astronomical Reference Systems, Time Scales,
and Earth Rotation Models, USNO Circular 179 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
(USNO Circular 179)
Kaplan, G., Bangert, J., Bartlett, J., Puatua, W., & Monet, A. 2009, User’s Guide to NOVAS
3.0, USNO Circular 180 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-180
(USNO Circular 180)
Kaplan, G. H., Hughes, J. A., Seidelmann, P. K., Smith, C. A., & Yallop, B. D. 1989, AJ, 97,
1197
Klioner, S. A. 2003, AJ, 125, 1580
Seidelmann, K., ed. 1992, The Explanatory Supplement to the Astronomical Almanac (Mill
Valley, CA: Univ. Sci. Books) (The Explanatory Supplement)
C-9
Abbr eviations and Symbols Fr equently Used
∆AT
∆T
θ
A&A
AA
AJ
ASCII
AU
BCRS
Bull. AAS
c
CIO
CIP
dec
ECEF
EO
ERA
GCRS
IAU
ICRS
IERS
ITRS
J2000.0
JD
JPL
NOVAS
NRL
RA
SI
SOFA
TAI
TDB
TIO
TT
U.S.
USNO
UT1
UTC
TAI – UTC (an integral number of seconds)
TT – UT1
Earth Rotation Angle (also ERA)
Astronomy and Astrophysics (journal)
Astronomical Applications, a USNO department
The Astronomical Journal (journal)
American Standard Code for Information Interchange
astronomical unit
Barycentric Celestial Reference System
Bulletin of the American Astronomical Society (journal)
speed of light
Celestial Intermediate Origin
Celestial Intermediate Pole
declination
Earth-centered, Earth-fixed
Earth Orientation, a USNO department
Earth Rotation Angle (also θ)
Geocentric Celestial Reference System
International Astronomical Union
International Celestial Reference System
International Earth Rotation and Reference Systems Service
International Terrestrial Reference System
epoch 2000 January 1, 12h TT (JD 2451545.0 TT) at the geocenter
(“J2000.0 system” is shorthand for the celestial reference system defined by
the mean equator and equinox of J2000.0)
Julian date
Jet Propulsion Laboratory
Naval Observatory Vector Astrometry Software
Naval Research Laboratory
right ascension
Système International
Standards of Fundamental Astronomy (software)
International Atomic Time (TAI = UTC + ∆AT)
Barycentric Dynamical Time
Terrestrial Intermediate Origin
Terrestrial Time (TT = TAI + 32.184 s = UT1 + ∆T)
United States
U.S. Naval Observatory
“Universal Time 1,” universal time that is a measure of the Earth’s rotational
angle and subject to irregularities in the Earth’s rotation (UT1 = TT – ∆T)
Coordinated Universal Time, an atomic time scale that is the basis for
worldwide civil time (replaces Greenwich Mean Time); currently kept within
0.9 s of UT1 through the addition or subtraction of leap seconds
C-10
VLBI
WGS-84
xp, yp
Very Long Baseline Interferometry
World Geodetic System 1984
Polar motion components; coordinates of the CIP with respect to the ITRS
(Return to Table of Contents)
C-11
C-12
Chapter 1 Astr onomical Backgr ound
At its highest level, NOVAS computes the precise positions of selected celestial objects at
specified dates and times, as seen from a given location on, or near, the Earth. Such positions
can then be expressed in a number of coordinate systems. Dates and times are specified in
several astronomical time scales, depending on the application. Users of NOVAS should
have a basic knowledge of astronomical coordinate systems and time; terms like right
ascension (RA), declination (dec), hour angle, ecliptic, equinox, precession, and sidereal time
should be familiar. Any number of texts on fundamental astronomyfor example, Spherical
Astronomy (Green 1985)can provide the essential concepts. For more technical
descriptions of the latest international standards on reference systems, USNO Circular 179, 6
cited in the Introduction, can provide the background. USNO Circular 179 documents the
algorithms for many important calculations in NOVAS. Others are described in the Kaplan
et al. (1989) paper mentioned in the Introduction or in the Explanatory Supplement. In
addition, two glossaries may be useful to NOVAS users: one published in The Astronomical
Almanac, 7 and one compiled by the IAU Working Group on Nomenclature for Fundamental
Astronomy. 8
A very cursory overview of some of the most important aspects of the astronomical
calculations performed by NOVAS follows. In this chapter, names of functions relevant to
the subject being discussed are shown in [brackets]. In the background material, special
terms referred to in IAU resolutions are printed in bold when first mentioned; other relevant
terms with widely accepted meanings in astronomy are initially printed in italics. In
descriptions of specific C code, bold text will be used to refer to file names and italic text
will be used to refer to function names. Variable names or code snippets will be presented in
a typewriter-like font.
1.1 Astronomical Coordinate Systems
Astronomical coordinate systems have traditionally been based on the extension of the
Earth’s equatorial plane to infinity, along with a fiducial direction in that plane, the equinox.
The direction of the equinox is along the line of nodes where the equatorial and ecliptic
planes meet. Because the Earth’s equator and ecliptic are both in motion (the equator’s
motion is described by precession and nutation; the ecliptic’s motion is due to the Earth’s
orbital variations), an infinite number of such coordinate systems exist, each one
corresponding to the orientation of the two planes at a specific date and time. The situation is
complicated by the fact that for some purposes in the past it was convenient to consider only
precession—and to neglect nutation—in defining celestial coordinate systems, so that we can
have, for any given date and time, both a mean system (in which only precession is
considered) and a true system (in which both precession and nutation are taken into account).
6
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
http://asa.usno.navy.mil/SecM/Section_M.html
8
http://syrte.obspm.fr/iauWGnfa/NFA_Glossary.html
7
C-13
Thus we have the mean system of some date, the true system of some date, the mean system
of 2000.0, etc. [precession, nutation, gcrs2equ]
Sidereal time is closely tied to the equatorial coordinate systems: one day of sidereal time is
marked by successive transits of the equinox across a specific geographic meridian, and local
sidereal time is just the apparent right ascension of stars transiting the observer’s meridian.
Like the equatorial coordinate systems, sidereal time comes in two flavors, mean and
apparent, based on, respectively, the mean and true equinox and the system of right
ascension that each defines. [sidereal_time]
In the last few decades of the 20th century, several IAU working groups led a general reexamination of astronomical coordinate systems at a very basic level. Part of the motivation
was quite practical: most large ground-based telescopes were no longer built on equatorial
mounts, and the equatorial coordinate systems were irrelevant to increasingly important
space observations. Furthermore, the most precise fundamental measurement—those that by
their nature are most closely related to the equatorial systems—are now obtained from Very
Long Baseline Interferometry (VLBI), a radio technique that has no direct sensitivity to the
equinox. Another important consideration was the need for astronomical coordinate systems
that were part of a general relativistic framework. All of these factors were folded into some
very important resolutions passed by the IAU in 1997 and 2000, which form the basis for the
coordinate systems used in the current version of NOVAS.
These resolutions have introduced concepts and terminology that may not be familiar to
astronomers accustomed to the traditional systems and names, which were used in the
previous versions of NOVAS. The new systems are outlined in the following paragraphs, but
see USNO Circular 179 9 for a much more complete description.
One of the resolutions passed by the IAU in 2000 defined two systems of space-time
coordinates, one for the solar system and the other for the near-Earth environment, within the
framework of General Relativity, by specifying the form of the metric tensors for each and
the four-dimensional space-time transformation between them. The former is called the
Barycentric Celestial Reference System (BCRS) and the latter is called the Geocentric
Celestial Reference System (GCRS). The BCRS is the system appropriate for the basic
ephemerides of solar system objects and astrometric reference data on galactic and
extragalactic objects, i.e., the data in astrometric star catalogs. The GCRS is the system
appropriate for describing the rotation of the Earth, the orbits of Earth satellites, and geodetic
quantities such as instrument locations and baselines. The directions of astronomical objects
as seen from the geocenter can also be expressed in the GCRS. The analysis of precise
observations inevitably involves quantities expressed in both systems and the transformations
between them. Functions in NOVAS may work with BCRS vectors, GCRS vectors, or both
with appropriate conversions.
If the orientation of the BCRS axes in space is specified, the orientation of the GCRS axes
then follows from the relativistic transformation between the two systems. The orientation of
the BCRS is given by what is called the International Celestial Reference System (ICRS).
9
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-14
The ICRS is a triad of coordinate axes with their origin at the solar system barycenter and
with axis directions effectively defined by the adopted coordinates of about 200 extragalactic
radio sources observed by VLBI (listed in Section H of The Astronomical Almanac). The
abbreviations BCRS and ICRS are often used interchangeably, because the two concepts are
so closely related: the ICRS is the orientation of the BCRS while the BCRS is the metric for
the ICRS.
The extragalactic radio sources that define the ICRS orientation are assumed to have no
observable intrinsic angular motions. Thus, the ICRS is a “space-fixed” system (more
precisely, a kinematically non-rotating system) and, as such, it has no associated epoch—its
axes always point in the same directions with respect to distant galaxies. However, the ICRS
was set up to approximate the conventional system defined by the Earth’s mean equator and
equinox of epoch J2000.0; the alignment difference is at the 0.02-arcsecond level, which is
negligible for many applications. [frame_tie]
Reference data for positional astronomy, such as the data in astrometric star catalogs (e.g.,
Hipparcos, UCAC, or 2MASS) or barycentric planetary ephemerides (e.g., JPL’s DE405) are
now specified within the ICRS; more precisely stated, they are specified within the BCRS,
with respect to the ICRS axes.
In the near-Earth environment, celestial coordinates and related quantities are expressed with
respect to the GCRS or reference systems that are derived from it. Because the orientation of
the GCRS is derived from that of the BCRS, the GCRS can be thought of as the “geocentric
ICRS.”
Besides the GCRS itself, the two reference systems most commonly used for expressing the
apparent directions of astronomical objects as seen from the Earth are the true equator and
equinox of date and the Celestial Intermediate Reference System. Both are obtained from
simple rotations of the GCRS, and, in both cases, the fundamental plane is the true equator of
date. [gcrs2equ] In the new terminology, the true or instantaneous equator is the plane
orthogonal to the Celestial Intermediate Pole (CIP), which is the celestial pole defined by
the adopted precession and nutation algorithms (see section 1.4). The only difference
between these two systems is the origin of right ascension: the points on the equator where
RA = 0 are, respectively, the true equinox and the Celestial Intermediate Origin (CIO).
The CIO is a recently introduced fiducial point on the equator that rigorously defines one
rotation of the Earth (see section 1.5). [cio_location]
The GCRS and the two equatorial systems obtained from it have their origin at the geocenter.
For topocentric coordinates or vectors, referred to an observer at a specific location on, or
near, the surface of the Earth, analogous coordinate systems exist although no semantic
distinction is usually made between them and their geocentric equivalents. In NOVAS, the
topocentric equivalent of the GCRS is referred to as the “local GCRS,” and its spatial axes
are assumed to be obtained from the GCRS by a Galilean transformation (simple shift of
origin without a change in orientation). The two topocentric equator-of-date systems are
obtained similarly.
Reference System for NOVAS Input Data: NOVAS now assumes that input reference data,
such as catalog star positions and proper motions and the basic solar system ephemerides, are
provided in the ICRS (that is, within the BCRS as aligned to the ICRS axes), or at least are
C-15
consistent with it to within the data’s inherent accuracy. [place, ephemeris] The latter case
will probably apply to most FK5-compatible data specified with respect to the mean equator
and equinox of J2000.0 (the “J2000.0 system”). The distinction between the ICRS and the
J2000.0 system becomes important only when an accuracy of 0.02 arcsecond or better is
important. [frame_tie] Nevertheless, because NOVAS is designed for the highest-accuracy
applications, the ICRS is mentioned as the reference system of choice for many input
arguments to NOVAS functions.
Reference Systems for NOVAS Output Data: For output coordinates (e.g., the position of
Mars on a certain date), three options for the coordinate system are available. (The
coordinates themselves can be right ascension and declination or the components of a unit
vector.) You can request coordinates expressed in the GCRS, the equator and equinox of
date, or the Celestial Intermediate Reference System (equator and CIO of date). These
coordinate systems can be requested for either geocentric or topocentric output. [place,
gcrs2equ]
NOVAS can also convert topocentric right ascension and declination, with respect to the
equator and equinox of date, to local horizon coordinates, zenith distance and azimuth. The
angular shift due to atmospheric refraction can be included as an option. [equ2hor] Another
function is available to transform right ascension and declination to ecliptic longitude and
latitude. [equ2ecl] Still another transforms right ascension and declination to galactic
longitude and latitude. [equ2gal]
Reference System for the Location of the Observer: The location of an Earth-based observer
is specified in NOVAS by longitude, latitude, and height with respect to the World Geodetic
System 1984 (WGS-84) reference ellipsoid. Coordinates provided by GPS (if uncorrected for
the local datum) are referred to WGS-84, which is also sometimes called the Earth-centered,
Earth-fixed (ECEF) system. The International Terrestrial Reference System (ITRS) is a
geocentric rectangular coordinate system used for high-precision work. WGS-84 coordinates
are functionally equivalent (within a few centimeters) to ITRS coordinates. Thus, the
geodetic positions used by NOVAS are consistent with the ITRS. [geo_posvel]
1.2 Computing Observable Quantities
NOVAS is mostly used for computing, for a selected object, the instantaneous angular
coordinates (or the equivalent unit vector components) at which it might be observed within
one of several user-selected coordinate systems. Obviously the values of the angular
coordinates computed by NOVAS depend on the coordinate system requested, but there are
several phenomena that affect the observed position of a star or planet that are independent of
the coordinate system. For stars, the effects are
•
Proper motion (generalized): the three-dimensional space motion of the star,
relative to that of the solar system barycenter, between the catalog epoch and the
date of interest. Assumed linear and computed from the catalog proper motion
components, radial velocity, and parallax. Projected onto the sky, the motion
amounts to less than 1 arcsecond per year (usually much less) except for a few
nearby stars. [starvectors, proper_motion]
C-16
•
Parallax: the change in our perspective on stars in the solar neighborhood due to the
position of the Earth in its orbit. Its magnitude is (distance in parsecs)-1 and, hence,
is always less than 1 arcsecond. [bary2obs]
•
Gravitational light bending: the apparent deflection of the light path in the
gravitational field of the Sun and, to a much lesser extent, the other planets.
Although it reaches 1.8 arcsecond at the limb of the Sun, it falls to 0.05 arcsecond
10º from the Sun and amounts to no more than a few milliarcseconds over the
hemisphere of the sky opposite the Sun. [grav_def, grav_vec]
•
Aberration: the change in the apparent direction of light caused by the observer’s
velocity (v) with respect to the solar system barycenter. Independent of distance, it
is approximately equal to v/c, expressed as an angle. Therefore, it can reach
21 arcseconds for observers on the surface of the Earth and somewhat more for
instruments in orbit. [aberration]
•
Atmospheric refraction: the total angular change in the direction of the light path
through the Earth’s atmosphere; applies only to an observer on, or near, the surface
of the Earth. The direction of refraction is always assumed to be parallel to the local
vertical and a function only of zenith distance although these assumptions may not
be true in all cases. At optical wavelengths, its magnitude is zero at the zenith,
about 1 arcminute at a zenith distance of 45°, and 0.5° at the horizon. Refraction is
roughly proportional to the atmospheric pressure at the observer, but it also depends
on other atmospheric parameters and the observational wavelength. [equ2hor,
refract]
The same effects are relevant to objects in the solar system, except that the proper motion
calculation is replaced by a function that retrieves the object’s barycentric position from its
ephemeris as part of an iterative light-time calculation. [light_time, ephemeris] Extragalactic
objects can be considered to be stars with zero parallax and proper motion. The star or planet
positions computed by considering all these effects obviously depend on the location of the
observer; so that an observer on the surface of the Earth will see a slightly different position
than one at the geocenter, the differences being greater for solar system objects, especially
nearby ones (reaching about 1º for the Moon).
In computing these effects, the same functions are used for stars and planets, because
NOVAS uses position vectors rather than directions; that is, internally, it places all objects at
their computed distance from the solar system barycenter. (Objects of unknown distance are
placed on the “NOVAS celestial sphere” at a radius of 1 Gigaparsec = 2 × 1014 astronomical
units). [starvectors] These vectors are all defined within the BCRS until the relativistic
aberration calculation is applied, which effectively takes an input vector in the BCRS and
produces an output vector in the GCRS.
Nomenclature: When all these effects are included, we obtain star or planet coordinates in
the GCRS that reflect where the star or planet actually appears in the sky. The coordinates
can then be transformed to other reference systems, if desired. We will call the results of this
process, generically, the “apparent position” or “observed position” of the object.
C-17
However, some caution with the semantics is in order, because the term apparent place has
traditionally been reserved specifically for the star or planet position we obtain by applying
all these effects (except refraction) for a geocentric observer, with the coordinates expressed
with respect to the true equator and equinox of date. For an observer on the surface of the
Earth, the corresponding term is topocentric place. If the apparent star or planet position is
instead expressed with respect to the mean equator and equinox of J2000.0, the terms used in
NOVAS have been virtual place and local place, respectively. (Although these last two
terms were suggested in the Kaplan et al. (1989) paper previously cited, they do not appear to
have been widely used outside of the context of NOVAS.)
The above terminology is reflected in the names of the high-level functions that perform the
computations, where “app” stands for “apparent place”, “topo” stands for “topocentric
place”, etc. [app_star, app_planet, topo_star, topo_planet, virtual_star, virtual_planet,
local_star, local_planet] In addition, an astrometric place calculation can be used for some
differential measurements; it is the same as virtual place except that light bending and
aberration (and refraction) are not computed, under the assumption that these effects are the
same for all objects within a small field of view. [astro_star, astro_planet]
In response to the introduction of the new IAU-recommended coordinate systems, we must
make some adjustments and additions to the nomenclature. The mean equator and equinox
of J2000.0, considered as a geocentric system, has been replaced by the GCRS. The IAU
Working Group on Nomenclature (2003–2006) recommended that the term proper place be
used for what is called virtual place in NOVAS. With the introduction of the Celestial
Intermediate Reference System, with its right ascension origin at the CIO, we now have two
more possibilities for apparent positions, one geocentric and one topocentric. The geocentric
coordinates are called the object’s intermediate place, and right ascension measured with
respect to the CIO is called intermediate right ascension.
The complete table of nomenclature for apparent positions of various types, updated for
NOVAS 3.0, and later, is below.
Final Coordinate System
Observer at Geocenter
True equator and equinox of date
apparent place
Observer near
Surface of Earth
topocentric place
Celestial Intermediate Reference System
intermediate place
[no name]
GCRS
proper or virtual place
local place
GCRS
astrometric place*
[no name]
*variant of proper or virtual place, in which some calculations are omitted
The only difference between a position expressed in the Celestial Intermediate Reference
System and the same position expressed with respect to the true equator and equinox of date
is an offset in right ascension, the equation of the origins. The equation of the origins is the
angle between the equinox and the CIO, both of which lie on the instantaneous equator.
[ira_equinox]
C-18
NOVAS function place can be used to compute all of these types of positions; the input arguments allow you to select both the location of the observer and the coordinate system in
which the computed position is to be expressed. These selections make the nomenclature
superfluous. place does not apply atmospheric refraction, but that can be added by a
subsequent call to equ2hor.
1.3 Time Scales for Astronomy
As explained in USNO Circular 179, 10 basically two kinds of time scales are used in
astronomy; those that are based on the Système International (SI) second (“atomic time”) and
those that are tied to the irregular rotation of the Earth; in essence, “lab” time and
“astronomical” time, respectively. Theoretical time scales, not kept by any real clocks, are
also used that are the time basis for—that is, the fourth dimension of—the BCRS and GCRS.
We almost always start with Coordinated Universal Time (UTC), which is the worldwide
basis for civil time. UTC (USNO) is obtained from the Global Positioning System (GPS). In
addition, UTC can be obtained with varying accuracy from Network Time Protocol (NTP)
services on the Internet and from radio time broadcasts (e.g., WWV, WWV, WWVB, and
CHU), cell phones, TV, etc. UTC is based on SI seconds at sea level on the rotating Earth.
From UTC, one adds an integral number of (SI) seconds to obtain International Atomic
Time (TAI): TAI = UTC + ∆AT, where ∆AT is a total count of leap seconds in UTC (for
example, ∆AT = 34 s for 2011). The USNO Earth Orientation (EO) Department 11 provides a
complete table of ∆AT values on-line. The current value may also be found at the beginning
of Bulletin A 12 published by the International Earth Rotation and Reference System Service
(IERS). The addition of a leap second to UTC, which increases ∆AT by 1 second, is usually
done, when needed, at 23:59:59 UTC on December 31 and is announced about six months in
advance.
NOVAS Time Arguments: Typically, the first input argument to most NOVAS functions is
the time of interest (for example, the time of an observation), expressed as a Julian date (JD).
Julian dates are simply a convenient format for representing a date and time in any time scale
and are discussed below. Two time scales are used as the basis for most of the Julian dates
that are input arguments to the higher-level NOVAS functions.
The first is Terrestrial Time (TT), which is effectively just a constant offset from TAI:
TT = TAI + 32.184 s. Therefore, TT = UTC + ∆AT + 32.184 s. Historically, TT is
considered continuous with the obsolete time scales Ephemeris Time (ET) and Terrestrial
Dynamical Time (TDT). It is meant to be a smooth and continuous “coordinate” time scale
independent of the rotation of the Earth. The high-level NOVAS functions that compute the
apparent direction of an object at a specified time use Julian dates based on TT. [place,
app_star, topo_star, app_planet, transform_cat]
10
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
http://maia.usno.navy.mil/ser7/tai-utc.dat
12
http://maia.usno.navy.mil/ser7/ser7.dat
11
C-19
The second time scale is Universal Time (UT1), which is based on the rotation of the Earth.
It is needed for computing sidereal time [sidereal_time] or the Earth Rotation Angle (ERA or
θ) [era], which in turn allows one to compute hour angles, altitude and azimuth, or other
topocentric quantities. UT1 is also obtained from UTC: UT1 = UTC + (UT1−UTC). The
value of UT1−UTC is available in a daily-interval tabulation on the IERS web site 13 (data
marked “P” are predictions); IERS publishes historical values in Bulletin B. 14 The values of
UT1−UTC often change at the millisecond level over one day. In computing the topocentric
direction of a celestial object with respect to Earth-fixed axes (e.g., altitude and azimuth),
1-arcsecond accuracy in the final angles requires 67-ms accuracy in UT1. Because
UT1−UTC can have an absolute value up to 900 ms, it is an important correction for all but
the crudest applications; that is, in most cases, it is not acceptable to approximate UT1 as
being equal to UTC.
A few of the lower-level NOVAS functions use time arguments based on Barycentric
Dynamical Time (TDB). [e_tilt, precession, ephemeris, solarsystem] TDB differs from TT
only by periodic variations (due mainly to the Earth’s elliptical orbit and described by
General Relativity), the largest of which has an amplitude of 1.6 ms and a period of one year.
[tdb2tt] The difference between the two time scales can often be neglected in practice as
noted in the function preambles where appropriate. TDB is equivalent to Teph, the barycentric
coordinate time argument of the Jet Propulsion Laboratory (JPL) planetary and lunar
ephemerides.
As previously mentioned, time is specified within NOVAS as Julian dates, which can be used
for any of the above time scales. Julian dates are a simple count of days since noon on 4713
BC January 1, so that any date in recorded human history has a positive JD. Over 2.4 million
days have elapsed since JD 0, and thus, for current dates, seven digits of precision are taken
up just by the day count; if the JD is given by a standard double-precision floating-point
number, about 9 digits are left to represent the time of day. Therefore, we expect a doubleprecision floating-point JD can represent time to a precision of about 10-9 day ≈ 100 μs.
However, after further examination, Kaplan, Bartlett, and Harris (2011) determined that the
actual precision is closer to 20.1 μs. In those NOVAS functions where more precision is
appropriate, the JD can be split between two input arguments, one that carries the high-order
part of the JD (e.g., the day count) and the other that carries the low-order part (e.g., the
fraction of a day). Note that for 0h (TT, UT1, or TDB), the fractional part of the Julian date
is 0.5. An online calendar-date-to-Julian-date converter is available at the AA Department
web site. 15 NOVAS has utility functions to convert between calendar date and Julian date
and vice versa. They work for any time scale; that is, their input and output arguments should
be considered to be just different ways of expressing the same instant within the same time
scale. [julian_date, cal_date]
The epoch J2000.0 is considered to be an event at the geocenter at Julian date 2451545.0 TT,
which is 2000 January 1, 12h TT.
13
http://maia.usno.navy.mil/ser7/mark3.out
http://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html
15
http://www.usno.navy.mil/USNO/astronomical-applications/data-services/cal-to-jd-conv
14
C-20
The difference ∆T = TT – UT1, expressed in seconds, is required for certain NOVAS
functions that use both TT and UT1 internally but require only one type of input time
argument. A table of historical values of ∆T is on pages K9–K10 of The Astronomical
Almanac and more recent values and predictions can be found online at EO web site. 16
Values of ∆T can also be computed from
∆T = 32.184s + ∆AT – (UT1–UTC)
For example, on 2010 December 1, ∆T = 66.3054 s, which is based on a ∆AT value of 34 s
and a UT1-UTC value of –0.1214 s (obtained from finals.data 17 and rounded to the
nearest ten-thousandth of a second). More information on ∆T is given in section 1.6
below.
1.4 Adopted Models for Precession and Nutation
Astronomers realized over a decade ago that the old standard models for the precession and
nutation were in need of revision. The value of the angular rate of precession in longitude
adopted by the IAU in 1976—and incorporated into the widely used precession formulation
by Lieske and collaborators (1977)—is too large by about 0.3 arcsecond per century (3 milliarcseconds per year). The amplitudes of a number of the largest nutation components
specified in the 1980 IAU Theory of Nutation are also known to be in error by several
milliarcseconds. Both the precession and nutation errors are significant relative to current
observational capabilities.
Thus, the resolutions passed by the IAU in 2000 mandated an improvement to the precession
and nutation formulations. NOVAS 3.0, and later, incorporate the models adopted in
response to these resolutions. [precession, nutation] The precession model is the P03 solution
of Capitaine, Wallace, and Chapront (2003), as recommended by the IAU Working Group on
Precession and the Ecliptic (Hilton et al. 2006). The P03 precession model was formally
adopted by the IAU in 2006. The nutation model is taken from Mathews, Herring, and
Buffett (2002). This model, referred to as the IAU 2000A nutation, consists of 1,365
trigonometric terms, more than ten times the number in the previous model.
[nutation_angles, iau2000a] Because evaluation of nutation has always been the most
computationally intensive task in NOVAS, you may notice an increase in execution time for
some applications.
To reduce execution time, NOVAS 3.0, and later, provide an optional reduced-accuracy
mode in which a truncated nutation series is used. This nutation series is specific to NOVAS
and is referred to as 2000K. [nu2000k] It consists of the largest 488 terms in the IAU 2000A
series and provides an accuracy of about 0.1 milliarcsecond (specifically, 0.1 milliarcsecond
for Δψ and about 0.04 milliarcsecond for Δε and Δψ sin ε). 2000K is the default reducedaccuracy nutation series in both Fortran and C editions of NOVAS, but the C edition also
includes the 77-term, IAU-approved truncated nutation series, IAU 2000B [iau2000b], which
is accurate to about 1 milliarcsecond in the interval 1995–2050 (McCarthy & Luzum 2003).
16
17
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
http://maia.usno.navy.mil/ser7/finals.data (See http://maia.usno.navy.mil/ser7/readme.finals for file format.)
C-21
More information on the implementation of nutation in NOVAS can be found section 2.6,
section 4.3, and in USNO Circular 181, 18 Nutation Series Evaluation in NOVAS 3.0 (Kaplan
2009).
As mentioned in section 1.1, the celestial pole described by the new precession and nutation
models (with very small observational corrections) is called the Celestial Intermediate Pole
(CIP). The true equator of date, also called the instantaneous equator or the intermediate
equator, is the plane orthogonal to the direction of the CIP. The CIP is also the rotational
pole on the surface of the Earth (see section 1.6).
1.5 New Model for the Rotation of the Earth about its Axis
IAU resolutions passed in 2000 also dealt in a very fundamental way with how the Earth’s
spin around its axis is described. The conventional treatment is based on the equinox and
sidereal time; Greenwich (or local) sidereal time is just the Greenwich (or local) hour angle
of the equinox of date. However, the equinox is constantly moving due to precession, so that
sidereal time combines two angular motions, the Earth’s rotation and the precession of its
axis. (In the case of apparent sidereal time, nutation is also included.) One rotation of the
Earth is about 8 ms longer than one mean sidereal day.
For about two decades, people who routinely deal with the most precise measurements of the
Earth’s rotation have been advocating for a change in the way it is described. Their ideas
were introduced in resolutions passed by the IAU in 2000. In this new paradigm, the
reference point on the moving celestial equator for the description of Earth rotation is called
the Celestial Intermediate Origin (CIO). Unlike the equinox, this point has no motion
along the equator at all; as the orientation of the equator changes in space due to precession
and nutation, the CIO remains on the equator but its instantaneous motion is always at right
angles to it. [cio_location, cio_ra] Thus, loosely speaking, two transits of the CIO across a
terrestrial meridian define one rotation of the Earth. The CIO is a point on the celestial
equator near RA = 0 (in the Celestial Intermediate Reference System, it defines RA = 0), and
there is a corresponding point on the terrestrial equator near longitude = 0 called the
Terrestrial Intermediate Origin (TIO). For all astronomical purposes, the TIO can be
considered a point fixed at geodetic longitude zero on the Earth’s rotational equator. 19 In the
new paradigm, the rotation of the Earth is specified by the angle (in the instantaneous
equatorial plane) between the TIO and the CIO, which is a linear function of universal time
(UT1). This angle is called the Earth Rotation Angle (ERA) and is designated by θ. [era]
Some internal calculations in NOVAS can be performed using either the equinox or the CIO
as the fundamental fiducial point on the moving astronomical equator. The user can select the
basis for these calculations via an input parameter method. The results are identical to within
a microarcsecond around the current time and the computational burden is about the same.
18
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-181
The CIO and TIO are technically examples of non-rotating origins, although neither is fixed within its
respective coordinate system. However, the slow drift of the TIO, due to polar motion, with respect to standard
geodetic coordinates (the ITRS, or, effectively, WGS-84) amounts to only 1.5 millimeters per century and is
completely negligible for astronomical purposes.
19
C-22
1.6 Terrestrial-Celestial Relationships
NOVAS uses the ITRS for specifying locations and directions on, or near, the surface of the
Earth. As mentioned at the end of section 1.1, the ITRS is consistent, to within a few
centimeters, with WGS-84 coordinates provided by GPS, and it is sometimes referred to as
the Earth-centered, Earth-fixed system (ECEF). The ITRS is a geocentric system with the
directions of its axes defined by the coordinates of a large number of observing stations, in a
way completely analogous to the definition of the ICRS by the coordinates of extragalactic
radio sources. The ITRS z-axis is toward the north geodetic pole and its x-axis is toward a
point at longitude and latitude zero; the y-axis forms a right-handed system with the other
two axes.
Practical applications of astronomical data often require relating terrestrial coordinates to
celestial coordinates and vice versa. For example, we may want the position of a celestial
object expressed with respect to the local horizon system. [equ2hor] Or, we may have a
vector, expressed in an Earth-fixed system, that represents some instrumental axis, and we
would like to know where that vector is pointed on the celestial sphere. NOVAS can
perform the terrestrial-to-celestial transformation or its inverse; specifically, the
transformation from the ITRS to the GCRS or the GCRS to the ITRS. [ter2cel, cel2ter]
These transformations are a series of rotations that, taken together, represent the
instantaneous orientation of the Earth in space. [precession, nutation, cio_basis,
sidereal_time, era, wobble]
Not all aspects of the Earth’s orientation are predictable. Polar motion represents the small
shift of the geodetic north pole (the ITRS z-axis) with respect to the rotational axis (the CIP),
the largest part of which must be determined from observations. Typically, the total shift
amounts to a few tenths of an arcsecond (1-2 µrad, 10 meters) and is specified by the
parameters xp and yp. The observational determinations are designated simply as x and y,
and current values are available from IERS Bulletin A. 20 Past values can be obtained at the
EO web site. 21 For most purposes, we can set xp=x and yp=y (see USNO Circular 179 22
section 6.5.2 or the IERS Conventions (2010) section 5.5.1). Several NOVAS functions
require as input the xp and yp values for the date of interest, although, if the final accuracy
requirements are no better than one arcsecond, these values can be set to zero.
Because the difference ∆T = TT – UT1 is used in only a few internal computations where the
conversion from one time scale to another is not critical, the value of ∆T needs to be accurate
to only about one second. Therefore, one ∆T value will typically apply to all dates for a given
year.
Finally, the new IAU precession and nutation models are neither perfect nor complete and,
for very high-accuracy applications, observational corrections are sometimes needed. These
corrections now amount to less than one milliarcsecond (5 nrad). These corrections are
available from the same sources as the polar motion determinations, and are designated as dX
20
http://maia.usno.navy.mil/ser7/ser7.dat
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/daily
22
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
21
C-23
and dY (note that the units are milliarcseconds). In the rare cases where they are needed,
they are pre-specified to NOVAS for use in subsequent calculations for a specific date.
[cel_pole]
1.7 References
Capitaine, N. Wallace, P. T., & Chapront. J. 2003, A&A, 412, 567 (P03)
Green, R. 1985, Spherical Astronomy (New York: Cambridge Univ. Press)
Hilton, J. L. et al. 2006, Celest. Mech. & Dynamical Astron., 94, 351
Kaplan, G. H. 2005, The IAU Resolutions on Astronomical Reference Systems, Time Scales,
and Earth Rotation Models, USNO Circular 179 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
Kaplan, G. H. 2009, Nutation Series Evaluation in NOVAS 3.0, USNO Circular 181
(Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-181
Kaplan, G., Bartlett J., & Harris, W. 2011, The Error in the Double Precision Representation
of Julian Dates, USNO-AA Tech. Note 2011-02
Kaplan, G. H., Hughes, J. A., Seidelmann, P. K., Smith, C. A., & Yallop, B. D. 1989, AJ, 97,
1197
Lieske, J. H., Lederle, T., Fricke, W., & Morando, B. 1977, A&A, 58, 1
Mathews, P. M., Herring, T. A., & Buffett, B. A. 2003, J. of Geophys. Res., 107, ETG 3-1
McCarthy, D. D. & Luzum, B. J. 2003, Celest. Mech. & Dynamical Astron., 85, 37
Petit, G. & Luzum, B. (eds.) 2010, Chapter 5, in IERS Conventions, IERS Tech. Not. 36
(Frankfurt: IERS)
Seidelmann, K., ed. 1992, The Explanatory Supplement to the Astronomical Almanac (Mill
Valley, CA: Univ. Science Books) (The Explanatory Supplement)
USNO & HMNAO. 2009, The Astronomical Almanac for the Year 2011, (Washington, DC:
GPO) and subsequent editions
(Return to Table of Contents)
C-24
Chapter 2
Installing NOVAS
2.1 List of Distribution Files
The table below lists the fifteen files that comprise the main distribution of NOVAS C3.1. 23
Except for the user’s guide, which is in Portable Document Format (PDF), the files are all
plain ASCII text. Files with a .c extension are C source code; their associated header files are
designated by a .h extension. The single file with a .f extension contains Fortran source code.
File name
novas.c
novas.h
novascon.c
novascon.h
nutation.c
nutation.h
solsys1.c
solsys2.c
solsys3.c
solarsystem.h
eph_manager.c
23
Description
contains all supervisory and utility functions and most basic
functions (see Section 4.2 for a full listing)
header file for novas.c
(includes structure definitions and function prototypes)
contains most mathematical and physical constants used by
NOVAS
header file for novascon.c
contains functions implementing the IAU 2000A,
IAU 2000B, and 2000K nutation models
header file for nutation.c
versions of functions solarsystem and solarsystem_hp that,
when used with eph_manager.c, provide a complete “all
C” interface between NOVAS and JPL’s lunar and
planetary ephemerides
(see detailed discussion in Chapter 4)
versions of functions solarsystem and solarsystem_hp that,
when used with jplint.f, provide an interface between
NOVAS and JPL’s Fortran solar system ephemeris-access
code
(see detailed discussion in Chapter 4)
versions of functions solarsystem and solarsystem_hp that
provide the position and velocity of the Earth and Sun
without reference to an external data file
(see detailed discussion in Chapter 4)
header file for the solsys1.c, solsys2.c, and solsys3.c files
C implementation of JPL’s solar system ephemeris-access
code for use with solsys1.c; requires a binary JPL ephemeris
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/novas/novas-c
C-25
File name
eph_manager.h
readeph0.c
jplint.f
README.txt
NOVAS_C3.1_Guide.pdf
Description
Header file for eph_manager.c
dummy version of function readeph, the highest-level call
to the USNO/AE98 24 minor planet ephemerides software;
when positions of selected minor planets are desired,
replace this file with readeph.c from the USNO/AE98
package
Fortran subroutines that, when used with solsys2.c, provide
an interface between NOVAS and JPL’s Fortran ephemerisaccess code (see detailed discussion in Chapter 4)
basic information for using NOVAS C3.1
User’s Guide to NOVAS C3.1, this manual
In addition, the following six files are provided to assist you in validating the installation of
NOVAS on your local system. Files with a .c extension are the C source code that created the
associated ASCII text files ending with .txt extensions. Compare the USNO-generated output
files with the results produced by your local installation as described in Section 2.2 (basic
installation), Section 2.3 (including a JPL solar system ephemeris), and Section 2.4
(including a USNO/AE98 minor planet ephemeris).
File name
checkout-stars.c
checkout-stars-usno.txt
checkout-stars-full.c
checkout-stars-full-usno.txt
checkout-mp.c
checkout-mp-usno.txt
24
Description
main function that calls functions in novas.c and solsys3.c
to validate a basic local installation
USNO output from checkout-stars application
main function that calls functions in novas.c and solsys1.c
with full accuracy to validate a local installation for use
with solar system ephemerides; requires binary JPL
ephemeris file
USNO output from checkout-stars-full application
main function that calls functions in novas.c, solsys1.c,
and USNO/AE98 minor planet software to validate a local
installation for use with minor planet ephemerides;
requires minor planet ephemeris and binary JPL ephemeris
files
USNO output from checkout-mp application
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/usnoae98
C-26
The following two files contain sample code to get you started developing your own
applications using NOVAS. Chapter 3 discusses each of the examples included and provides
instructions for using the sample code. The file with a .c extension is the C source code that
produced the associated ASCII text file (.txt).
File name
example.c
example-usno.txt
Description
main function that calls selected functions in novas.c and
solsys1.c; example code discussed in Chapter 3; requires a
binary JPL ephemeris
USNO output from example application
Finally, an ASCII text file (.txt) containing the right ascensions of the CIO in the GCRS is
supplied along with C source code (.c) to convert it to a binary direct-access file. The set-up
and use of this file is discussed in Section 2.5.
File name
CIO_RA.TXT
cio_file.c
Description
right ascensions of the CIO in the GCRS from 1700 to 2300
main function that converts CIO_RA.TXT (ASCII) to
cio_ra.bin (binary)
2.2 Installation and Basic Validation
To install NOVAS and perform a basic validation of the code on your local system, follow
the instructions given below. These instructions assume that you know how to compile and
link C source code on your computer system. Details of the process are dependent on your
particular computer system. In particular, some C compilers require an explicit link to the
math library, which is typically accomplished using the –lm option in the command line; see
your compiler’s documentation for details. NOVAS has been successfully implemented on
Microsoft Windows, Apple Macintosh, and Red Hat Enterprise Linux systems.
The most basic validation of NOVAS requires no external ephemeris files.
a. Copy all NOVAS files to a directory on your local system.
b. Compile and link files checkout-stars.c, novas.c, novascon.c, nutation.c, solsys3.c,
and readeph0.c. Name the resulting application checkout-stars.
c. Run the checkout-stars application.
d. Compare the results that you get from checkout-stars with the data in file checkoutstars-usno.txt. If the results agree, the installation was probably successful, but see
the important note below.
Important Note
The checkout-stars application exercises one supervisory function and most, but not all,
of the low-level functions in novas.c. The use of the checkout-stars application is not a
complete test of NOVAS. Comparing the results from the NOVAS C supervisory
functions with results from the analogous NOVAS Fortran supervisory functions will
constitute a more complete check of your NOVAS implementation.
C-27
This setup of NOVAS, using solarsystem version 3, will calculate the positions of stars or
extragalactic objects with errors not exceeding 1.5 milliarcseconds (if your input catalog data
is that good) or the Sun with an error not exceeding 2 arcseconds. However, it will not
provide the positions of solar system objects other than the Sun. For more general or
demanding applications, NOVAS must use another version of solarsystem.
2.3 Using External Solar System Ephemeris Files
NOVAS requires access to a solar system ephemeris, which provides NOVAS with the
heliocentric and barycentric positions and velocities of desired solar system objects referred
to the ICRS. A solar system ephemeris is required even when only precise star positions are
needed—in that case, the “desired solar system objects” are the Earth and Sun. Thus, an
ephemeris of the barycentric Earth and the barycentric Sun is the minimum requirement.
NOVAS C3.0, and later, access such data for solar system objects through function
ephemeris. As provided, ephemeris supports access to a JPL ephemeris of the major solar
system bodies (here defined as Sun, Moon, eight planets, and Pluto) and provides direct
support for access to the USNO Ephemerides of the Largest Asteroids (Hilton 1999;
hereafter USNO/AE98 25). Function ephemeris accesses the JPL ephemerides by calling the
appropriate version of solarsystem or solarsystem_hp.
If you need to compute star or radio-source positions to better than 1.5 milliarcseconds,
positions of the Sun to better than 2 arcseconds, or positions of solar system bodies other
than the Sun, you will have to use function solarsystem version 1 or version 2, which require
external ephemerides, instead of solarsystem version 3, which is self-contained.
solarsystem version 1, along with functions in eph_manager.c, provides a complete C
language interface between NOVAS and one of the JPL “development ephemerides”
(DEnnn), such as DE405. The planet_ephemeris function is the C version of the Fortran
subroutine PLEPH, and it, in turn, calls other functions in the JPL ephemeris software
package. Alternatively, solarsystem version 2, along with subroutines in jplint.f, provides an
interface to the JPL ephemeris access code, which is available in Fortran. Subroutine jplint
contains a single call to JPL’s Fortran subroutine PLEPH, which in turn calls other Fortran
subroutines in the JPL ephemeris software package.
Establishing a working copy of the JPL software and the DEnnn binary files on your system
is not, unfortunately, a trivial process. The files for doing that can be obtained directly from
JPL26 as discussed in Appendix C.
Once you have generated a DEnnn binary file, you can test the combined set-up with
solarsystem version 1 on your system as follows:
a. Compile and link files checkout-stars-full.c, novas.c, novascon.c, nutation.c,
solsys1.c, eph_manager.c, and readeph0.c.
b. Name the resulting application checkout-stars-full.
c. Run the checkout-stars-full application.
25
26
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/usnoae98
http://ssd.jpl.nasa.gov/?planet_eph_export
C-28
d. Compare the results that you get from checkout-stars-full with the data in file
checkout-stars-full-usno.txt. If the results agree, the installation was probably
successful, but see the important note above.
The USNO output file, checkout-stars-full-usno.txt, was generated using DE405. The
application, check-out-stars-full, uses the full-accuracy mode of NOVAS, which includes
the IAU 2000A nutation model, a three-body gravitational deflection model, two-part Julian
dates in calls to function ephemeris, and the full series when computing the “complementary
terms” in the equation of the equinoxes [iau2000a, nutation_angles, grav_def, ephemeris,
ee_ct]. If your accuracy requirements are no better than about 1 milliarcsecond, you may
wish to consider “reduced-accuracy” mode, which is described in Section 2.6, for your own
applications.
2.4 Using External Minor Planet Ephemeris Files
The USNO/AE98 27 minor planet ephemerides contain positions for fifteen of the largest
asteroids and are used in the production of The Astronomical Almanac. These ephemerides
along with software to compact, read, and interpolate them are available on CD-ROM from
the USNO. The software is written in C and designed to be used with NOVAS. To include
these ephemeris files in your NOVAS programs, you will need to install a working copy of
the USNO/AE98 software and convert the relevant ASCII ephemerides to binary Chebyshev
polynomial ephemerides. You will still need one version of solarsystem; solarsystem
version 1 with access to the JPL lunar and planetary ephemeris is recommended.
Instructions 28 for installing and testing the USNO/AE98 software and for converting
ephemerides are provided with the software. Section 2.3 and Appendix C discuss the use and
installation of a JPL lunar and planetary ephemeris.
In order to access the USNO/AE98 minor planet ephemerides, function ephemeris calls
function readeph, which is part of the USNO/AE98 package and is not part of, or supplied
with, NOVAS. A dummy version of readeph is provided in file readeph0.c. The dummy
function enables NOVAS to be used without the minor planet package (i.e., for computing
positions of major solar system bodies and “stars” only). To use USNO/AE98 with NOVAS,
replace file readeph0.c provided with NOVAS, with readeph.c, allocate.c, and chby.c from
the USNO minor planet ephemerides software when compiling and linking.
Once you have a DEnnn binary solar system ephemeris file, the USNO/AE98 software, and a
binary Chebyshev polynomial ephemeris of a minor planet, you can test the combined set-up
with solarsystem version 1 on your system as follows:
a. Compile and link files checkout-mp.c, novas.c, novascon.c, nutation.c, solsys1.c,
eph_manager.c, readeph.c, allocate.c, and chby.c. The last three code files are
from the USNO/AE98 software.
b. Name the resulting application checkout-mp.
c. Run the checkout-mp application.
27
28
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/usnoae98
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/usnoae98/ae98-rm
C-29
d. Compare the results that you get from checkout-mp with the data in file checkoutmp-usno.txt. If the results agree, the installation was probably successful, but see the
important note above.
The USNO output file, checkout-mp-usno.txt, was generated using DE405 from JPL and
pallas.chby from the minor planet ephemerides. Like the check-out-stars-full application,
checkout-mp uses the full-accuracy mode of NOVAS. If you do not require accuracy better
than about 1 milliarcsecond, you may wish to consider the “reduced-accuracy” mode
discussed in Section 2.6.
2.5 Using an External CIO File
You have the option of using an external file of CIO right ascension values on the GCRS or
of allowing NOVAS to calculate the true right ascension of the CIO (the arc on the
instantaneous equator from the equinox to the CIO) using a series expansion. Section 5.3
explains how NOVAS handles these two situations. If you choose to use CIO_RA.TXT,
which is provided with NOVAS, you must first convert it to a binary direct-access file as
follows:
a. Copy CIO_RA.TXT and cio_file.c to a directory on your local system.
b. Compile cio_file.c.
c. Name the resulting application cio_file.
d. Run the cio_file application. If everything runs smoothly, you should get the
following message
Results from program cio_file:
Input file identifier: CIO RA P03
@ 1.200d
182657 records read from the input file:
First Julian date: 2341951.400000
Last Julian date: 2561138.600000
Data interval: 1.200000 days
First data point: 2341951.400000
Last data point: 2561138.600000
-1.948328
1.942125
Binary file cio_ra.bin created.
e. Verify the presence of cio_ra.bin, which should contain approximately 2.9 Mbytes.
The file CIO_RA.TXT, as supplied, contains six centuries of data, most of which is seldom
used, so trimming it down can reduce the file size. It is plain text (ASCII) that can be
modified by any text editor. The first record is a header, which should remain as such
(although its contents are not used by NOVAS), but all the other records contain a Julian date
and information for that date in ascending date order. Simply trim from the beginning and
ending of the file any records for dates that you are sure you will never need; be sure to leave
at least ten extra dates on each end to allow the internal interpolation scheme to work
properly. For example, CIO_RA.TXT contains data for years 1700 through 2300 but you
may need only the range from 2010 to 2015. Leave the data within your overall anticipated
date range as is—that is, do not attempt to make several groups of dates within the same file.
The final file that you create must be a fixed-interval list running from the first date to the
last date with no gaps after the header record. When you have modified CIO_RA.TXT
C-30
appropriately, follow the steps above to convert your custom version to the binary directaccess format useable by NOVAS. The output message and file will differ from that above
based on the changes you made.
If a CIO file (cio_ra.bin) is not present when NOVAS needs to determine the location of the
CIO, NOVAS will simply revert to using an internal computation for this information. The
results differ by a few microarcseconds at most, and those differences are reached only for
dates before 1900 or after 2200. The two approaches represent independent algorithms for
determining the location of the CIO on the equator, and the tiny differences for dates that are
several centuries from now are of no practical consequence. Small differences in execution
time may occur for the two approaches, but those timing differences are likely to vary with
the specific application—depending, for example, on the order and spread of the dates that
are processed by NOVAS. For some applications using such an external file may be
undesirable. Because, in many simple NOVAS applications, the location of the CIO is never
needed, the best scheme is probably to start without using the CIO file. If your application’s
execution time is critical, you might want to experiment to see whether using a CIO file
affects its performance one way or the other.
2.6 Reduced-accuracy Mode
NOVAS has “full-accuracy” and “reduced-accuracy” modes that must be selected when
calling about half of the functions in novas.c; see the prolog to each function and the
corresponding description in Chapter 4 for specific functions. Each of those functions has a
short integer input parameter, accuracy. If accuracy is set to zero (0), the function and
any lower-level functions that it calls will proceed with full accuracy. Alternatively, if
accuracy is set to one (1), the function and any lower-level functions that it calls will
proceed with reduced accuracy.
In full-accuracy mode,
•
•
•
•
•
nutation calculations use the IAU 2000A model [iau2000a, nutation_angles];
gravitational deflection is calculated using three bodies: Sun, Jupiter, and Saturn
[grav_def];
the equation of the equinoxes includes the entire series when computing the
“complementary terms" [ee_ct];
geocentric positions of solar system bodies are adjusted for light travel time using
split, or two-part, Julian dates in calls to ephemeris and iterate with a convergence
tolerance of 10-12 days [light_time, ephemeris];
ephemeris calls the appropriate solar system ephemeris using split, or two-part, Julian
dates primarily to support light-time calculations [ephemeris, solarsystem_hp,
light_time].
In reduced-accuracy mode,
•
•
nutation calculations use the 2000K model, which is the default for this mode, or the
IAU 2000B model, which may be set manually by user [nu2000k, iau2000b,
nutation_angles];
gravitational deflection is calculated using only one body, the Sun [grav_def];
C-31
•
•
•
the equation of the equinoxes excludes terms smaller than 2 microarcseconds when
computing the "complementary terms" [ee_ct];
geocentric positions of solar system bodies are adjusted for light travel time using
single-value Julian dates in calls to ephemeris and iterate with a convergence
tolerance of 10-9 days [light-time, ephemeris, solarsystem];
ephemeris calls the appropriate solar system ephemeris using single-value Julian
dates [ephemeris, solarsystem].
In full-accuracy mode, the IAU 2000A nutation series (1,365 terms) is used [iau2000a].
Evaluating the series for nutation is usually the main computational burden in NOVAS, so
using reduced-accuracy mode improves execution time, often noticeably. In reducedaccuracy mode, the NOVAS 2000K nutation series (488 terms) is used by default [nu2000k].
This mode can be used when the accuracy requirements are not better than 0.1 milliarcsecond
for stars or 3.5 milliarcseconds for solar system bodies. Selecting this approach can reduce
the time required for Earth-rotation computations by about two-thirds. However, if your
reduced-accuracy application requires the IAU-approved truncated nutation series, IAU
2000B (77 terms), you can edit the function nutation_angles slightly so that it calls iau2000b
in reduced-accuracy mode instead of nu2000k; the necessary changes are described in the
prolog to that function. Section 1.4 and USNO Circular 181 29 (Kaplan 2009) provide some
additional information about nutation series.
2.7 References
Hilton, J. L. 1999, AJ, 117, 1077 http://www.usno.navy.mil/USNO/astronomicalapplications/software-products/usnoae98 (USNO/AE98)
Kaplan, G. H. 2009, Nutation Series Evaluation in NOVAS 3.0, USNO Circular 181
(Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-181
USNO & HMNAO. 2010, The Astronomical Almanac for the Year 2011, (Washington, DC:
GPO) and subsequent editions
(Return to Table of Contents)
29
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-181
C-32
Chapter 3
Sample Calculations
The sample C code discussed in this chapter can be found in the file example.c, which is
distributed along with NOVAS; it is a main function that can be linked to the NOVAS
modules and executed. It requires solarsystem version 1, a working copy of the JPL software,
and a DEnnn binary file. To use it,
a. compile and link files: example.c, novas.c, novascon.c, nutation.c, solsys1.c,
eph_manager.c, and readeph0.c.
b. name the resulting application example.
c. verify that the JPL ephemeris file JPLEPH, or an alias to it, is available in the same
directory as example.
d. execute the example application.
The results are given in the file example-usno.txt, which was generated at the USNO with
the JPL DE405 ephemeris. example.c may be modified for use with solarsystem version 2;
see the comments within that file for details.
NOVAS has a number of high-level functions that make obtaining frequently needed
information on the positions of celestial objects easy; some of these are described below. In
addition, Chapter 4 describes many of the functions and all of the structures used in these
examples. The checkout programs used to validate a local installation (checkout-stars.c,
checkout-stars-full.c, and checkout-mp.c) also provide other examples of NOVAS function
calls.
Note that all floating-point arguments to NOVAS functions, input or output, are double
precision floating-point values (type double).
3.1 Initialization
You may choose to call many NOVAS functions in either full- or reduced-accuracy modes.
Usually all functions in a single application will have the same accuracy requirements.
Therefore, you may wish to define a short integer constant for this purpose at the beginning
of your main function. example operates in full-accuracy mode, so accuracy is set to zero
const short int accuracy = 0;
A value of one (1) would have set reduced accuracy. For more information on the two
modes, see section 2.6.
Three high-level NOVAS functions sidereal_time, ter2cel, and cel2ter can perform their
internal calculations using either the CIO-based method or equinox-based method. If you will
be calling these functions multiple times, you may also wish to define a short integer constant
for this purpose, with a value of zero (0) for the CIO-based method or one (1) for the
equinox-based method. In example, the appropriate method is chosen when these functions
are called. Because the equinox-based method is more efficient for computing sidereal time,
example chooses this mode. For more information about these two methods, see section 5.2.
C-33
3.2 Setting Time Arguments
You should also consider how you will handle dates and times. As described in section 1.3,
NOVAS uses either of two time scales, TT or UT1, as the basis for the time input argument
to its higher-level functions. However, you may be working with UTC, Coordinated
Universal Time. UTC is the basis for civil time systems worldwide and, because it is
distributed quite accurately by GPS, is often used as the time-tag for observations. The key
relationship is
TT = UTC + ∆AT + 32.184s
where ∆AT is an integer representing the total count of leap seconds in UTC (for example,
∆AT = 34 s for 2011). Equivalently,
TT = TAI + 32.184s
where TAI is International Atomic Time. If you will only be dealing with the geocentric
celestial coordinates of objects, TT is all you will need.
If you will also be computing topocentric coordinates (for a specific location on the surface
of the Earth), you will also need to obtain UT1. The key relationship is
UT1 = UTC + (UT1–UTC)
where UT1–UTC is interpolated from the daily values of this quantity published by the
IERS. 30 Alternatively,
UT1 = TT – ∆T
See section 1.3 for more information on time scales, including sources of data that can be
used for the values of ∆AT, UT1–UTC, and ∆T.
To convert a date and time in the common format (year/month/day/hour/minute/second) to a
Julian date, which is used by NOVAS for time arguments, call julian_date. Dates and times
based on UTC, TT, or UT1 (or any other time scale) can be converted using julian_date; the
output Julian date simply has the same basis as the input date and time. In the examples
below, we will be using 2008 April 24, 10:36:18.0 UTC as the time of interest; this
corresponds to a Julian date of 2454580.9441875 UTC. 31 Consequently, we will use a ∆AT
value of 33 s and a UT1–UTC value of −0.387845 s, which are appropriate for this date.
const
const
const
const
short
short
short
short
int
int
int
int
year = 2008;
month = 4;
day = 24;
leap_secs = 33;
const double hour = 10.605;
const double ut1_utc = -0.387845;
const double x_pole = -0.002;
const double y_pole = +0.529;
30
http://maia.usno.navy.mil/ser7/mark3.out
A “UTC Julian date” is something of a non sequitur, because UTC is not continuous due to leap seconds.
Here we are simply using julian_date with UTC input to obtain a value that allows us to compute Julian dates in
better-behaved time scales.
31
C-34
where x_pole and y_pole are the coordinates of the CIO with respect to the ITRS pole for
2008 April 24. So, if we use
jd_utc = julian_date (year,month,day,hour);
the output argument, jd_utc, will have a value of 2454580.9441875. The next few lines
of code should be something like
jd_tt = jd_utc + ((double) leap_secs + 32.184) / 86400.0;
jd_ut1 = jd_utc + ut1_utc / 86400.0;
delta_t = 32.184 + leap_secs - ut1_utc;
where 86400.0 is the number of seconds in a day, and the value of delta_t would be
computed to be 65.571845 (seconds). If we had known the value of ∆T (delta_t) at the
start, rather than the value of ut1_utc (UT1–UTC), then the lines immediately above could
have been replaced by
jd_tt = jd_utc + ((double) leap_secs + 32.184) / 86400.0;
jd_ut1 = jd_tt - delta_t / 86400.0;
3.3 Example 1—Position of a Star
Suppose we have the catalog data from star FK6 1307 (Groombridge 1830) for epoch
J2000.0, expressed in the ICRS:
11.88299133
ICRS right ascension at J2000.0 (hours):
37.71867646
ICRS declination at J2000.0 (degrees):
4003.27
Proper motion in RA (milliarcseconds per year):
–5815.07
Proper motion in dec (milliarcseconds per year):
109.21
Parallax (milliarcseconds):
–98.8
Radial velocity (kilometers per second):
To obtain the apparent geocentric place of the star on our date of interest, with respect to the
equator and equinox of that date, first make a structure of type cat_entry,
make_cat_entry ("GMB 1830","FK6",1307,11.88299133,37.71867646,
4003.27,-5815.07109.21,-98.8, &star);
Then, simply call app_star supplying it with the catalog quantities:
error = app_star (jd_tt,&star,accuracy,&ra,&dec)
In this example and other examples in this chapter, the returned value from the function—
error—is an error indicator. Non-zero values of error indicate an error condition inside
the function; see the function prolog for details. The calling function should take appropriate
action in such cases. The output coordinates, ra and dec (hours and degrees, respectively),
represent the apparent geocentric coordinates of the star, with respect to the true equator and
equinox of date. The computation takes into account all time-dependent effects that shift the
star’s position from its catalog coordinates (except atmospheric refraction, which is locationand weather-dependent): the star’s space motion to the date of interest, parallax due to the
Earth’s position in its orbit, gravitational light-bending in the solar system, aberration due to
the Earth’s orbital velocity, and the precession and nutation of the Earth’s axis.
Important note: Hipparcos catalog data, although expressed with respect to the ICRS, refer
to epoch 1991.25 and must be converted to epoch J2000.0 before being used as input
arguments to any NOVAS function. Use function transform_hip to do this. Most other
C-35
modern catalogs, including the FK6 (used above), Tycho-2, UCAC, etc., provide data for
epoch J2000.0 that need no conversion.
If we want the apparent topocentric place of the star, that is, the star’s position as it would be
seen (except for refraction) from a particular location on Earth, such as off the Atlantic coast
near Truro, Massachusetts
const
const
const
const
const
double
double
double
double
double
latitude = 42.0;
longitude = -70;
height = 0.0;
temperature = 10.0;
pressure = 1010.0;
where longitude and latitude are the location’s geodetic longitude and latitude
(degrees, with east longitude and north latitude positive) and height is the height of the
location above sea level (meters). The temperature and pressure (in degrees Celsius
and millibars, respectively) are only used in calculations involving atmospheric refraction;
here, the values are simply placeholders. You should create a structure of type on_surface
for that location
make_on_surface (latitude,longitude,height,temperature,pressure,&geo_loc);
Now, call topo_star
error = topo_star (jd_tt,delta_t,&star,&geo_loc,accuracy,&rat,&dect)
where rat and dect reflect the position of the star as it would be seen from that particular
location—the small differences from the geocentric coordinates ra and dec arise mainly
from diurnal aberration. topo_star uses the catalog data on the star created earlier.
3.4 Example 2—Position of the Moon
Obtaining the coordinates of solar system objects other than the Sun requires that either
solarsystem version 1 or version 2 be used. First, you will need to create a structure of type
cat_entry for a “dummy” star, which is, then, used as a placeholder in a structure of type
object for the Moon.
make_cat_entry ("DUMMY","xxx",0,0.0,0.0,0.0,0.0,0.0,0.0,&dummy_star);
error = make_object (0,11,"Moon",&dummy_star,&moon)
Then, call function app_planet
error = app_planet (jd_tt,&moon,accuracy,&ra,&dec,&dis)
where, again, ra and dec are the apparent geocentric coordinates of the Moon (hours and
degrees, respectively), with respect to the true equator and equinox of date, and dis is the
true (Euclidean) geocentric distance (astronomical units or AU) at time jd_tt. The
computation of the angular coordinates of solar system objects takes light-time into account,
along with the other effects (light bending, aberration, precession, and nutation) that also
apply to stars.
To get the topocentric celestial coordinates of the Moon, call topo_planet
error = topo_planet(jd_tt,&moon,delta_t,&geo_loc,accuracy,&rat,&dect,&dist)
However, a single function, place, can be used for all types of positions of both stars and
solar system objects. In fact, app_star, topo_star, app_planet, and topo_planet, along with
C-36
several other similar functions, are actually just special-purpose front-ends to place. place
uses three structure arguments (cel_object of type object and location of type
observer for input and output of type sky_pos for output) as well as several scalar
arguments. The cel_object of type object is same as was created earlier for use by
app_planet and topo_planet in calculating the position of the Moon. Function
make_observer_on_surface creates a structure of type observer for an observer on, or near,
the surface of the Earth:
make_observer_on_surface (latitude,longitude,height,temperature,pressure,
&obs_loc);
The call to place to obtain topocentric coordinates of the Moon, with respect to the true
equator and equinox of date, then is
error = place (jd_tt,&moon,&obs_loc,delta_t,1,accuracy,&t_place)
where short integer coord_sys has been set to one (1) so that the output coordinates in
t_place, a structure of type sky_pos, will be based on the true equator and equinox of
date:
typedef struct
{
double r_hat[3];
double ra;
double dec;
double dis;
double rv;
} sky_pos;
Here, double r_hat[3] is a dimensionless unit vector in the apparent direction of the
Moon, in the same coordinate system as the right ascension and declination (i.e., it is exactly
equivalent to the spherical coordinates). place has many options for both input and output;
refer to its description in Chapter 4 or look at its prolog.
Once you have the topocentric celestial coordinates of an object, these can be transformed
into local altitude and azimuth by a call to equ2hor. If we have used place to obtain the
topocentric coordinates, then
equ2hor (jd_ut1,delta_t,accuracy,0.0,0.0,&geo_loc,rat,dect,1,&zd,&az,&rar,
&decr);
where the refraction option, short integer ref_option, is set here to one (1) and the x- and
y-coordinates of the CIO with respect to the ITRS pole, double xp and double yp, have been
set to zero (0.0). The refraction option selected here is for “standard atmospheric” conditions.
The other options for refraction are zero (0) for no refraction or two (2) for refraction based
on the atmospheric conditions indicated by location, a structure of type on_surface.
Setting the CIO coordinates to zero is appropriate when sub-arcsecond accuracy is
unnecessary; otherwise these arguments should contain the appropriate pole coordinates for
the date of interest. The output coordinates, zd, az, rar, and decr, are, respectively, the
zenith distance (degrees), azimuth (degrees), right ascension (hours), and declination
(degrees). The output values of zd, rar, and decr are affected by atmospheric refraction for
refraction options 1 and 2. If ref_option equals 0, the output right ascension and
declination values are the same as the input values. zd and az are referred to the horizon
C-37
system that is tangent to the Earth’s reference ellipsoid at the observer’s location; that is, the
deflection of the vertical (the local undulation of the geoid) is not taken into account.
3.5 Example 3—Greenwich Sidereal Time
To obtain Greenwich sidereal time, call sidereal_time:
error = sidereal_time (jd_ut1,0.0,delta_t,1,1,accuracy,&gast)
where short integer gst_type and short integer method have each been set to one (1) to
compute Greenwich apparent sidereal time using the equinox-based method. In this example,
the output sidereal time gast is Greenwich apparent sidereal time in hours. If gst_type
had been set to zero (0), the output sidereal time would have been Greenwich mean sidereal
time in hours. Choosing between equinox-based and CIO-based methods is discussed in
section 3.1 and section 5.2.
sidereal_time and several other functions allow for a “split” input UT1 Julian date—highand low-order parts in the first two arguments—for increased precision. Generally, the split
would be at the Julian date’s decimal point, with the day count in the first argument and the
fraction of a day in the second. However, using two arguments for the Julian date provides
more precision only if the fractional part of the Julian date has been handled separately all
along. We have not done that, so here, the entire Julian date is just placed in the first
argument and the second argument is set to zero (0.0).
To compute local sidereal time (either mean or apparent), add the longitude (east positive)
expressed in hours:
last = gast + geo_loc.longitude / 15.0;
The result may have to be reduced to the range 0 to 24 hours by statements similar to the
following:
if (last >= 24.0)
last -= 24.0;
if (last < 0.0)
last += 24.0;
The quantity that is analogous to Greenwich apparent sidereal time in the CIO-based
paradigm is θ, the ERA. It can be computed
theta = era (jd_ut1,0.0);
where theta is the ERA (degrees). era, like sidereal_time, allows for a split input UT1
Julian date.
See section 5.1 for information on the difference between Greenwich apparent sidereal time
and the ERA, and how hour angles are computed in the two paradigms.
3.6 Example 4—Other Frequently Requested Quantities
In the following function calls, vectors are used. Vectors are simply double-precision arrays
with a dimension of 3. Most NOVAS internal calculations are performed with vectors and
matrices. The following vectors are referred to below:
double pos[3], vel[3], pose[3], vter[3], vcel[3];
C-38
To obtain the barycentric or heliocentric coordinates (BCRS vectors) of a solar system body,
for example, Mars, first create an appropriate structure of type object
error = make_object (0,4,"Mars",&dummy_star,&mars)) != 0
which uses the dummy_star structure created in Example 2. Then, call ephemeris:
jd_tdb = jd_tt;
/* Approximation good to 0.0017 seconds. */
jd[0] = jd_tdb;
jd[1] = 0.0;
error = ephemeris (jd,&mars,1,accuracy,pos,vel)
where short integer origin has been set to one (1) to obtain a heliocentric position, we have
approximated jd_tdb = jd_tt, 32 and the output position and velocity vectors are pos and
vel (components in AU and AU/day, respectively). For barycentric positions, set origin
to zero (0).
If pos is a heliocentric vector, it can be transformed to the ecliptic system (fixed ecliptic of
J2000.0) by calling equ2ecl_vec:
error = equ2ecl_vec (T0,2,accuracy,pos,pose)
where pose is the output vector in the ecliptic system (same units as pos). pose could then
easily be converted to heliocentric spherical coordinates: ecliptic longitude, ecliptic latitude,
and radius vector.
error = vector2radec (pose,&elon,&elat)
elon *= 15.0;
r = sqrt (pose[0] * pose[0] + pose[1] * pose[1] + pose[2] * pose[2]);
Finally, transforming a vector from the terrestrial reference system to the celestial reference
system can be useful. The vector might represent a geographic position, a geodetic reference
line or direction, or an instrumental axis. For this transformation, the vector starts out as an
Earth-fixed vector expressed with respect to the ITRS axes. For example, the vector toward
the local vertical (orthogonal to the ellipsoid at the place of interest) is simply (cos φ cos λ,
cos φ sin λ, sin φ), where φ is the geodetic latitude and λ is the longitude. A vector along a
telescope’s polar axis would nominally point toward (0,0,1) in this system.
lon_rad
lat_rad
sin_lon
cos_lon
sin_lat
cos_lat
vter[0]
vter[1]
vter[2]
=
=
=
=
=
=
=
=
=
geo_loc.longitude * DEG2RAD;
geo_loc.latitude * DEG2RAD;
sin (lon_rad);
cos (lon_rad);
sin (lat_rad);
cos (lat_rad);
cos_lat * cos_lon;
cos_lat * sin_lon;
sin_lat;
Any such ITRS vector can be transformed into the equivalent GCRS vector with a single call
to ter2cel:
error = ter2cel (jd_ut1,0.0,delta_t,1,accuracy,0,x_pole,y_pole,vter,vcel)
32
Strictly, ephemeris requires a TDB-based Julian date as input. TDB differs from TT by at most 1.7 ms; see
section 1.3. If this time difference is important, use function tbd2tt to determine the difference between the two
time scales and adjust jd_tdb accordingly. For the example here, neglecting the difference can lead to an
error in the position of Mars of about 50 meters.
C-39
where vter is the input vector (terrestrial, ITRS) and vcel is the equivalent output vector
(celestial, GCRS). The components of vter can be in any units; vcel will be in the same
units. vcel will sweep around the celestial sphere as the Earth rotates, i.e., as jd_ut1
advances. (ter2cel, like sidereal_time, allows for a split input UT1 Julian date.) Use
vector2radec to obtain vcel’s instantaneous spherical coordinates:
error = vector2radec (vcel,&ra,&dec)
where ra and dec are the GCRS right ascension and declination (hours and degrees,
respectively) of the point on the celestial sphere toward which vcel points. At any jd_ut1,
vcel can be compared to the directions of stars computed by place for the equivalent jd_tt,
with GCRS output coordinates selected.
(Return to Table of Contents)
C-40
Chapter 4
Data Str uctur es and Functions
NOVAS can be used several different ways. Some users will simply want to adopt a subset
of the basic or utility functions for use in their own code systems. For these users, the
function prologs should be sufficient for providing the information needed to use the
functions. Other users will want to implement the supervisory functions to compute, for
example, apparent places of stars or topocentric places of solar system bodies. This section
of the user’s guide is intended for these users.
4.1 Important Data Structures
Seven important data structures are used throughout NOVAS. They are formally declared in
file novas.h.
Structure cat_entry
Structure cat_entry contains the astrometric catalog data for a celestial object; equator and
equinox and units will depend on the catalog. While this structure can be used as a generic
container for catalog data, all high-level NOVAS functions require ICRS catalog data with
the appropriate units, which are shown in parentheses below:
typedef struct
{
char starname[SIZE_OF_OBJ_NAME];
char catalog[SIZE_OF_CAT_NAME];
long int starnumber;
double ra;
double dec;
double promora;
double promodec;
double parallax;
double radialvelocity;
} cat_entry;
where
starname[SIZE_OF_OBJ_NAME]
catalog[SIZE_OF_CAT_NAME]
starnumber
ra
dec
promora
promodec
parallax
radialvelocity
=
=
=
=
=
=
name of celestial object
catalog designator (e.g., HIP)
integer identifier assigned to object
ICRS right ascension (hours)
ICRS declination (degrees)
ICRS proper motion in right ascension
(milliarcseconds/year)
= ICRS proper motion in declination
(milliarcseconds/year)
= parallax (milliarcseconds)
= radial velocity (km/s)
SIZE_OF_OBJ_NAME and SIZE_OF_CAT_NAME are constants also defined in novas.h. Each
is the number of characters in the string (the string length) plus the null terminator.
C-41
Structure object
Structure object designates a celestial object:
typedef struct
{
short int type;
short int number;
char name[SIZE_OF_OBJ_NAME];
cat_entry star;
} object;
where
type
number
name
star
=
=
=
=
type of object
0 ... major planet, Pluto, Sun, or Moon
1 ... minor planet
2 ... object located outside the solar system
(star, nebula, galaxy, etc.)
= object number
For 'type' = 0: Mercury = 1, ..., Pluto = 9,
Sun = 10, Moon = 11
For 'type' = 1: minor planet number
For 'type' = 2: set to 0 (object is
fully specified in 'struct cat_entry')
= name of the object (limited to
(SIZE_OF_OBJ_NAME – 1) characters)
= basic astrometric data for any celestial object
located outside the solar system; the catalog
data for a star
Structure on_surface
Structure on_surface contains data for the observer’s location on the surface of the Earth.
The atmospheric parameters (temperature and pressure) are used only by the refraction
function (refract) called from function equ2hor when ref_option = 2; dummy values can
be used otherwise. Additional parameters can be added to this structure if a more
sophisticated refraction model is employed:
typedef struct
{
double latitude;
double longitude;
double height;
double temperature;
double pressure;
} on_surface;
where
latitude
longitude
height
temperature
pressure
=
=
=
=
=
geodetic (ITRS) latitude; north positive (degrees)
geodetic (ITRS) longitude; east positive (degrees)
height of the observer (meters)
temperature (degrees Celsius)
atmospheric pressure (millibars)
C-42
Structure in_space
Structure in_space contains data for an observer’s location on a near-Earth spacecraft:
typedef struct
{
double sc_pos[3];
double sc_vel[3];
} in_space;
where
sc_pos[3]
sc_vel[3]
= geocentric position vector (x, y, z), components
in km
= geocentric velocity vector (x_dot, y_dot,
z_dot), components in km/s
Both vectors with respect to true equator and
equinox of date
Structure observer
Structure observer is a general container for information specifying the location of the
observer:
typedef struct
{
short int where;
on_surface on_surf;
in_space near_earth;
} observer;
where
where
on_surface
near_earth
= integer code specifying location of observer
= 0: observer at geocenter
= 1: observer on surface of earth
= 2: observer on near-earth spacecraft
= structure containing data for an observer's
location on the surface of the Earth (where = 1)
= data for an observer's location on a near-Earth
spacecraft (where = 2)
Structure sky_pos
Structure sky_pos contains data specifying a celestial object’s place on the sky, specifically
the output from function place:
typedef struct
{
double r_hat[3];
double ra;
double dec;
double dis;
double rv;
} sky_pos;
where
r_hat[3]
= unit vector toward object (dimensionless)
C-43
ra
dec
dis
rv
= apparent, topocentric, or astrometric
right ascension (hours)
= apparent, topocentric, or astrometric
declination (degrees)
= true (geometric, Euclidian) distance to solar
system body or 0.0 for star (AU)
= radial velocity (km/s)
Structure ra_of_cio
Structure ra_of_cio contains the right ascension of the Celestial Intermediate Origin (CIO)
with respect to the GCRS:
typedef struct
{
double jd_tdb;
double ra_cio;
} ra_of_cio;
where
jd_tdb
ra_cio
= TDB Julian date
= right ascension of the CIO with respect
to the GCRS (arcseconds)
4.2 Function List
The following functions are contained in file novas.c:
Function name
place *
sidereal_time
ter2cel **
cel2ter ***
equ2hor
transform_cat
transform_hip
app_star
topo_star
virtual_star
local_star
astro_star
mean_star
app_planet
topo_planet
virtual_planet
Level Purpose
super Computes apparent direction of a star or solar system body, given the
time and observer’s location. Direction is expressed in one of several
selectable coordinate systems.
super Computes Greenwich sidereal time, either mean or apparent
super Transforms arbitrary vector in rotating Earth-fixed (ITRS) system to
space-fixed (GCRS) system, terrestrial-to-celestial transformation
super Transforms arbitrary vector in space-fixed (GCRS) system to rotating
Earth-fixed (ITRS) system, celestial-to-terrestrial transformation
super Transforms topocentric RA and dec to zenith distance and azimuth,
optionally accounts for atmospheric refraction
super Transforms star’s catalog quantities for a change of epoch and/or
equator and equinox
super Converts Hipparcos catalog data at epoch J1991.25 to epoch J2000.0
super Computes apparent place of a star, given its catalog data
super Computes topocentric place of a star, given geodetic location of
observer
super Computes virtual place of a star, given its catalog data
super Computes local place of a star, given geodetic location of observer
super Computes astrometric place of a star, given its catalog data
super Computes ICRS/J2000.0 place of a star, given its apparent place
super Computes apparent place of a solar system body
super Computes topocentric place of a solar system body, given geodetic
location of observer
super Computes virtual place of a solar system body
C-44
Function name
local_planet
Level Purpose
super Computes local place of a solar system body, given geodetic location
of observer
astro_planet
super Computes astrometric place of a solar system body
aberration
util
Adjusts position vector for aberration of light due to motion of Earth
bary2obs **
util
Changes origin of coordinates from barycenter of solar system to
center of mass of Earth
cio_basis *
util
Computes orthonormal basis vectors, with respect to GCRS, of righthanded system defined by CIP (z-direction) and CIO (x-direction)
d_light *
util
For a star, returns difference in light-time between solar system
barycenter and observer. Or, returns the light-time from observer to
point on light ray closest to a given solar system body.
ecl2equ_vec *
util
Converts ecliptic position vector to an equatorial position vector
equ2ecl *
util
Converts RA and dec to ecliptic longitude and latitude
equ2ecl_vec *
util
Converts equatorial position vector to an ecliptic position vector
equ2gal *
util
Converts ICRS RA and dec to galactic longitude and latitude
era *
util
Returns ERA (θ) for given UT1 Julian date
frame_tie *
util
Transforms vector between dynamical reference system (mean
equator and equinox of J2000.0) and ICRS
gcrs2equ *
util
Converts GCRS RA and dec to coordinates with respect to the
equator of date (mean or true)
geo_posvel *
util
Computes geocentric position and velocity, in GCRS, of observer on,
or near, the surface of Earth
grav_def **
util
Computes total gravitational deflection of light for an object due to
major solar system bodies
grav_vec *
util
Corrects position vector for deflection of light in gravitational field
of given body
light_time *
util
Computes position of a solar system body antedated for light-time
limb_angle *
util
Determines angle of object above or below Earth's limb (horizon)
make_cat_entry
util
Creates a structure of type cat_entry containing catalog data for a
star or “star-like” object
make_object **
util
Creates structure of type object—specifying a celestial object based
on the input parameters
make_observer *
util
Creates structure of type observer—specifying the location of the
observer
make_observer_at_geocenter * util
Creates structure of type observer—specifying that the “observer”
is at the geocenter
make_observer_in_space *
util
Creates structure of type observer—specifying the position and
velocity of an observer situated on a near-Earth spacecraft
make_observer_on_surface * util
Creates structure of type observer—specifying the location of and
weather for an observer on the surface of the Earth
make_in_space *
util
Creates structure of type in_space—specifying the position and
velocity of an observer situated on a near-Earth spacecraft
make_on_surface *
util
Creates structure of type on_surface—specifying the location of
and weather for an observer on the surface of the Earth
nutation **
util
Applies nutation to position vector
precession
util
Applies precession to position vector
proper_motion
util
Updates position vector of a star to allow for its space motion
rad_vel *
util
Predicts radial velocity of observed object as would be measured by
spectroscopy
radec2vector
util
Converts RA, dec, and distance to a position vector
spin
util
Rotates vector by specified angle about the z-axis
C-45
Function name
starvectors
Level Purpose
util
Converts a star’s RA, dec, proper motion, etc., to position and
velocity vectors
util
Converts geodetic coordinates to geocentric position vector
util
Converts position vector to RA and dec
util
Adjusts Earth-fixed vector for polar motion
basic Computes calendar date and time, given Julian date
basic Allows for the specification of celestial pole offsets for highprecision applications
basic Returns array of Julian dates and corresponding values of RA of CIO
(in GCRS), given TDB Julian date and number of dates desired
basic Returns location of CIO as RA with respect to either GCRS origin or
true equinox of date, given TDB Julian date
basic Computes true right ascension of the CIO, given TT Julian date
basic Returns complementary terms for equation of the equinoxes
basic Retrieves position and velocity of a solar system body from a
fundamental ephemeris
basic Provides information on orientation of Earth’s axis: obliquity,
nutation parameters, etc.
basic Computes fundamental arguments (mean elements) of the Sun and
Moon
basic Computes intermediate RA of the equinox, given TDB Julian date
basic Computes Julian date, given calendar date and time
basic Computes the mean obliquity of the ecliptic
basic Normalize angle into the range 0 <= angle < (2 * pi)
basic Supervises calculation of nutation parameters and provides nutation
in longitude and obliquity
basic Computes atmospheric refraction in zenith distance
basic Converts Barycentric Dynamical Time (TDB) to Terrestrial Time
(TT)
terra
vector2radec
wobble
cal_date
cel_pole
cio_array *
cio_location *
cio_ra *
ee_ct *
ephemeris
e_tilt **
fund_args
ira_equinox *
julian_date
mean_obliq *
norm_ang *
nutation_angles
refract
tdb2tt **
*
New function in NOVAS C3.0
** Name change from NOVAS C2.0.1
*** New function in NOVAS C3.1
The following functions are contained in file nutation.c:
Function name
iau2000a *
iau2000b *
nu2000k *
*
Level
basic
basic
basic
Purpose
Evaluates high-accuracy nutation series (IAU 2000A model)
Evaluates low-accuracy nutation series (IAU 2000B model)
Evaluates low-accuracy nutation series (2000K, truncated version of
IAU 2000A model)
New function in NOVAS C3.0
C-46
The following functions are contained in the various solsysn.c files, where n is an integer:
Function name
solarsystem
solarsystem_hp *
Level
basic
basic
sun_eph **
basic
*
**
Purpose
Provides position and velocity vectors of a solar system body
Provides position and velocity vectors of a solar system for applications
requiring the highest precision
Computes equatorial spherical coordinates of Sun referred to the mean
equator and equinox of date
New function in NOVAS C3.0
Only present in solsys3.c
4.3 Important Functions
Descriptions of some of the most frequently used NOVAS functions follow. The prologs in
the source code at the beginning of each NOVAS function are intended to provide enough
information for correct usage. They are reproduced here followed by additional discussion
and recommendations.
C-47
place
short int place (double jd_tt, object *cel_object,
observer *location, double delta_t,
short int coord_sys, short int accuracy,
sky_pos *output)
PURPOSE:
This function computes the apparent direction of a star or solar
system body at a specified time and in a specified coordinate
system.
REFERENCES:
Kaplan, G. et al. (1989), Astronomical Journal 97, 1197-1210.
Klioner, S. (2003), Astronomical Journal 125, 1580-1597.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for place.
*cel_object (struct object)
Specifies the celestial object of interest (structure defined
in novas.h).
*location (struct observer)
Specifies the location of the observer (structure defined in
novas.h).
delta_t (double)
Difference TT-UT1 at 'jd_tt', in seconds of time.
coord_sys (short int)
Code specifying coordinate system of the output position.
= 0 ... GCRS or "local GCRS"
= 1 ... true equator and equinox of date
= 2 ... true equator and CIO of date
= 3 ... astrometric coordinates, i.e., without light
deflection or aberration.
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*output (struct sky_pos)
Output data specifying object's place on the sky at time
'jd_tt', with respect to the specified output coordinate system
(struct defined in novas.h).
RETURNED
VALUE:
= 0
= 1
= 2
= 3
> 10, < 40
> 40, < 50
...
...
...
...
No problems.
invalid value of 'coord_sys'
invalid value of 'accuracy'
Earth is the observed object, and the observer is
either at the geocenter or on the Earth's surface
(not permitted)
... 10 + error from function 'ephemeris'
... 40 + error from function 'geo_posvel'
C-48
>
>
>
>
50,
70,
80,
90,
<
<
<
<
70
80
90
100
...
...
...
...
50
70
80
90
+
+
+
+
error
error
error
error
from
from
from
from
function
function
function
function
'light_time'
'grav_def'
'cio_location'
'cio_basis'
Discussion:
Function place computes the apparent direction of a star or solar system body at a specified
time and in a specified coordinate system. The word “star” as used here refers to any object
outside the solar system.
The apparent direction of a star computed by this function takes into account the star’s proper
motion (linear three-dimensional space motion) from the catalog epoch to the date requested,
parallax, gravitational deflection of light by solar system bodies (mostly the Sun), and
aberration. The same effects are computed for solar system bodies, except that the proper
motion calculation is replaced by an algorithm that retrieves the object’s barycentric position
from its ephemeris, as part of an iterative light-time calculation. Extragalactic objects are
treated as stars with zero proper motion and parallax. The result in all cases is an apparent
direction expressed in the GCRS, which is optionally transformed into either of two other
output coordinate systems, as specified by argument coord_sys.
“Astrometric place” is a variant of the above calculation that is appropriate for some types of
differential measurements. Light bending and aberration are ignored under the assumption
that they are the same for all objects within a small area of the sky. Astrometric places are
expressed in the ICRS.
The observer’s location may be at the geocenter, on or near the surface of the Earth, or in
orbit around the Earth, as specified by the where member of the argument location.
Function place does not take into account atmospheric refraction (which would be
appropriate only for observers on, or near, the surface of the Earth), but its effect can be
added by a subsequent call to function equ2hor.
For stars, the required input data, stored in the cel_object->star argument, are the
standard five astrometric quantities from a catalog, together with radial velocity if known.
Any parameter should be set to 0.0 if its value is unknown. All catalog data used as input to
this function must apply to epoch J2000.0 and be expressed with respect to the ICRS. (For
Hipparcos catalog data, see function transform_hip.) Extragalactic objects should be treated
as stars, but with all input parameters set to 0.0 except for the catalog right ascension and
declination. For solar system bodies, the argument cel_object->number must contain the
identification number from the list of objects supported by the ephemeris in use.
The values of location->where and coord_sys for various kinds of place are listed
below.
location->where
0
1
0
1
0
1
coord_sys
0
0
1
1
2
2
C-49
Type of Place
virtual place* = proper place
local place*
apparent place
topocentric place
intermediate place
topocentric intermediate place*
location->where
0
1
coord_sys
3
3
Type of Place
astrometric place
topocentric astrometric place*
*
Place name not widely recognized outside of NOVAS.
NOVAS functions app_star, topo_star, app_planet, topo_planet, etc., are now just specialpurpose front-ends to place.
Important: The input value of ∆T (delta_t) is used only when location->where = 1
or 2 (observer is on surface of Earth or in a near-Earth satellite). An error in ∆T of 1 s can
result in a topocentric place error of up to 0.3 arcsecond for the Moon, but proportionally less
for more distant bodies (e.g., 3 milliarcseconds for Venus at its closest). Distance errors of up
to 500 m (3 × 10-9 AU) can also result, independent of distance. If errors of this magnitude are
important, care needs to be taken in specifying a more accurate value of ∆T. An error in ∆T
of 1 s will not result in a significant error in the topocentric places of stars. Values of ∆T are
published annually in The Astronomical Almanac or can be obtained from the EO web site. 33
output->rv, the radial velocity, is the predicted radial velocity measure (z) times the speed
of light, an inherently spectroscopic quantity. For a star, it includes all effects, such as
gravitational red shift, contained in the catalog barycentric radial velocity measure, which is
assumed given in cel_object->star.radialvelocity. For a solar system body, it
applies to a fictitious emitter at the center of the observed object, assumed to be massless (no
gravitational red shift), and does not in general apply to reflected light.
“Loose” catalog data can be assembled into a structure of type cat_entry by using function
make_cat_entry. Similarly, we recommend using function make_object to create the input
structure cel_object.
(Return to Function List)
33
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
C-50
sidereal_time
short int sidereal_time (double jd_high, double jd_low,
double delta_t,short int gst_type,
short int method, short int accuracy,
double *gst)
PURPOSE:
Computes the Greenwich sidereal time, either mean or apparent, at
Julian date 'jd_high' + 'jd_low'.
REFERENCES:
Kaplan, G. (2005), US Naval Observatory Circular 179.
INPUT
ARGUMENTS:
jd_high (double)
High-order part of UT1 Julian date.
jd_low (double)
Low-order part of UT1 Julian date.
delta_t (double)
Difference TT-UT1 at 'jd_high'+'jd_low', in seconds
of time.
gst_type (short int)
= 0 ... compute Greenwich mean sidereal time
= 1 ... compute Greenwich apparent sidereal time
method (short int)
Selection for method
= 0 ... CIO-based method
= 1 ... equinox-based method
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*gst (double)
Greenwich (mean or apparent) sidereal time, in hours.
RETURNED
VALUE:
(short int)
= 0
= 1
= 2
> 10, < 30
...
...
...
...
everything OK
invalid value of 'accuracy'
invalid value of 'method'
10 + error from function 'cio_rai'
Discussion:
This function computes Greenwich sidereal time, either mean, if gst_type = 0, or
apparent, if gst_type = 1.
The input Julian date, which must be in the UT1 time scale, may be split into two parts to
ensure the highest precision in the computation. For example, set jd_high equal to the
integral part of the Julian date and set jd_low equal to the fractional part. Generally, this
C-51
split will be advantageous only if the low-order part has been treated separately within the
calling program; for example, if the time of day has been stored in its own variable(s), from
which jd_low is constructed.
For many applications, the position of the split is not critical as long as the sum jd_high +
jd_low is correct: in particular, when used with computers providing 16 decimal digits of
precision in double variables, this function will yield values of gst precise to about
0.1 millisecond even if jd_high contains the entire Julian date and jd_low = 0.0.
Values of ∆T (delta_t) are published annually in The Astronomical Almanac or can be
obtained from the EO web site. 34
If gst_type = 1 for apparent sidereal time, the output value of gst will correctly reflect
the celestial pole offset in longitude if function cel_pole has previously been called.
(Return to Function List)
34
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
C-52
ter2cel
short int ter2cel (double jd_ut_high, double jd_ut_low, double delta_t,
short int method, short int accuracy, short int option,
double xp, double yp, double *vec1,
double *vec2)
PURPOSE:
This function rotates a vector from the terrestrial to the
celestial system. Specifically, it transforms a vector in the
ITRS (rotating earth-fixed system) to the GCRS (a local spacefixed system) by applying rotations for polar motion, Earth
rotation, nutation, precession, and the dynamical-to-GCRS
frame tie.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Kaplan, G. H. (2003), 'Another Look at Non-Rotating Origins',
Proceedings of IAU XXV Joint Discussion 16.
INPUT
ARGUMENTS:
jd_ut_high (double)
High-order part of UT1 Julian date.
jd_ut_low (double)
Low-order part of UT1 Julian date.
delta_t (double)
Value of Delta T (= TT - UT1) at the input UT1 Julian date.
method (short int)
Selection for method
= 0 ... CIO-based method
= 1 ... equinox-based method
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
option (short int)
= 0 ... The output vector is referred to GCRS axes.
= 1 ... The output vector is produced with respect to the
equator and equinox of date.
xp (double)
Conventionally-defined x p coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
yp (double)
Conventionally-defined y p coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
vec1[3] (double)
Position vector, geocentric equatorial rectangular coordinates,
referred to ITRS axes (terrestrial system) in the normal case
where 'option' = 0.
OUTPUT
ARGUMENTS:
vec2[3] (double)
Position vector, geocentric equatorial rectangular coordinates,
referred to GCRS axes (celestial system) or with respect to
the equator and equinox of date, depending on 'option'.
C-53
RETURNED
VALUE:
= 0 ... everything is ok.
= 1 ... invalid value of 'accuracy'
= 2 ... invalid value of 'method'
> 10 ... 10 + error from function 'cio_location'
> 20 ... 20 + error from function 'cio_basis'
Discussion:
Function ter2cel rotates a vector from the terrestrial to the celestial system. Specifically, it
transforms a vector in the ITRS (a rotating Earth-fixed system) to the GCRS (a local spacefixed system) by applying rotations for polar motion, Earth rotation, nutation, precession, and
the dynamical-to-GCRS frame tie. The input vector might represent a cardinal direction at
the observer’s position, a geodetic baseline, or some instrumental axis. The units for the
vector components are arbitrary and the output vector will have the same units as the input
vector. Geodetic coordinates in the WGS-84 system, also sometimes called the Earthcentered, Earth-fixed (ECEF) system, can be considered to be compatible with the ITRS.
This function allows for the input UT1 time to be represented as a split Julian date. See the
discussion in the description of function sidereal_time. Both jd_ut_high and jd_ut_low
should be non-negative for normal use; jd_ut_low = 0.0 is acceptable.
Values of ∆T (delta_t) are published annually in The Astronomical Almanac or can be
obtained from the EO web site. 35
The option flag only works for the equinox-based method.
Set xp = yp = 0.0 to omit the polar motion rotation.
Function cel2ter performs the reverse transformation, rotating the vector from the celestial
system (GCRS) to the terrestrial system (ITRS). The arguments are as described above,
except that for cel2ter, vec1 is the vector with respect to the GCRS (in) and vec2 is the
vector with respect to the ITRS (out).
(Return to Function List)
35
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
C-54
equ2hor
void equ2hor (double jd_ut1, double delta_t, short int accuracy,
double xp, double yp, on_surface *location, double ra,
double dec, short int ref_option,
double *zd, double *az, double *rar, double *decr)
PURPOSE:
This function transforms topocentric right ascension and
declination to zenith distance and azimuth. It uses a method
that properly accounts for polar motion, which is significant at
the sub-arcsecond level. This function can also adjust
coordinates for atmospheric refraction.
REFERENCES:
Kaplan, G. (2008). USNO/AA Technical Note of 28 Apr 2008,
"Refraction as a Vector."
INPUT
ARGUMENTS:
jd_ut1 (double)
UT1 Julian date.
delta_t (double)
Difference TT-UT1 at 'jd_ut1', in seconds.
accuracy (short int)
Selection for method and accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
xp (double)
Conventionally-defined x p coordinate of celestial intermediate
pole with respect to ITRS reference pole, in arcseconds.
yp (double)
Conventionally-defined y p coordinate of celestial intermediate
pole with respect to ITRS reference pole, in arcseconds.
*location (struct on_surface)
Pointer to structure containing observer's location (defined
in novas.h).
ra (double)
Topocentric right ascension of object of interest, in hours,
referred to true equator and equinox of date.
dec (double)
Topocentric declination of object of interest, in degrees,
referred to true equator and equinox of date.
ref_option (short int)
= 0 ... no refraction
= 1 ... include refraction, using 'standard' atmospheric
conditions.
= 2 ... include refraction, using atmospheric parameters
input in the 'location' structure.
OUTPUT
ARGUMENTS:
*zd (double)
Topocentric zenith distance in degrees, affected by
refraction if 'ref_option' is non-zero.
*az (double)
Topocentric azimuth (measured east from north) in degrees.
C-55
*rar (double)
Topocentric right ascension of object of interest, in hours,
referred to true equator and equinox of date, affected by
refraction if 'ref_option' is non-zero.
*decr (double)
Topocentric declination of object of interest, in degrees,
referred to true equator and equinox of date, affected by
refraction if 'ref_option' is non-zero.
RETURNED
VALUE:
None.
Discussion:
Function equ2hor takes the topocentric celestial coordinates of an object and computes the
equivalent local horizon coordinates. The function uses a method that properly accounts for
polar motion, which is significant at the sub-arcsecond level. Atmospheric refraction can be
included in the transformation, and, if so, refraction is applied to both sets of coordinates,
which can be useful for telescope pointing. Refraction, when requested, is computed by
function refract.
ra and dec, the input topocentric right ascension and declination, can be obtained from
place (with location->where = 1 and coord_sys = 1), topo_star, or topo_planet.
jd_ut1 is the UT1 time at which the topocentric place was computed. The difference
TT−UT1 (often called ∆T) is passed to the function via argument delta_t. Values of ∆T
are published annually in The Astronomical Almanac or can be obtained from the EO web
site. 36
The coordinates of the pole, xp and yp, can be obtained from IERS Bulletins A and B, 37
although xp and yp can be set to zero (0.0) if sub-arcsecond accuracy is not needed. (If
refraction is requested, sub-arcsecond accuracy is unlikely.)
The height of the observer and meteorological conditions at the observer’s location,
contained in structure location, are used only for refraction, i.e., if ref_option is not
equal to zero. In this function, the directions zd = 0.0 (the zenith) and az = 0.0 (north)
are considered fixed in the terrestrial frame. Specifically, the zenith is along the geodetic
normal, and north is toward the ITRS reference pole.
If ref_option = 0 for no refraction, then rar = ra and decr = dec.
(Return to Function List)
36
37
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
http://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html
C-56
transform_cat
short int transform_cat (short int option, double date_incat,
cat_entry *incat, double date_newcat,
char newcat_id[SIZE_OF_CAT_NAME],
cat_entry *newcat)
PURPOSE:
To transform a star's catalog quantities for a change of epoch
and/or equator and equinox. Also used to rotate catalog
quantities on the dynamical equator and equinox of J2000.0 to the
ICRS or vice versa.
REFERENCES:
None.
INPUT
ARGUMENTS:
option (short int)
Transformation option
= 1 ... change epoch; same equator and equinox
= 2 ... change equator and equinox; same epoch
= 3 ... change equator and equinox and epoch
= 4 ... change equator and equinox J2000.0 to ICRS
= 5 ... change ICRS to equator and equinox of J2000.0
date_incat (double)
TT Julian date, or year, of input catalog data.
*incat (struct cat_entry)
An entry from the input catalog, with units as given in
the struct definition (struct defined in novas.h).
date_newcat (double)
TT Julian date, or year, of transformed catalog data.
newcat_id[SIZE_OF_CAT_NAME] (char)
Catalog identifier ((SIZE_OF_CAT_NAME - 1) characters maximum)
e.g. HIP = Hipparcos, TY2 = Tycho-2.
OUTPUT
ARGUMENTS:
*newcat (struct cat_entry)
The transformed catalog entry, with units as given in
the struct definition (struct defined in novas.h).
RETURNED
VALUE:
= 0 ... Everything OK.
= 1 ... Invalid value of an input date for option 2 or 3.
= 2 ... length of 'newcat_id' out of bounds.
Discussion:
Function transform_cat performs mean place to mean place transformations on star catalog
data. Only catalog reference data, not observed quantities, should be processed by this
function.
C-57
For option = 1, 2, or 3, two dates, date_incat and date_newcat, must be specified:
the input data is associated with the first date, and the output data is associated with the
second date. Two transformations are available:
option = 1: The star’s data is updated to account for the star’s space motion
between the first and second dates, within a fixed reference system. That is,
the epoch of the data is changed, but not the equator and equinox (or other
system).
option = 2: The reference frame within which the star’s coordinates and proper
motion are expressed is rotated corresponding to precession between the first
and second dates. The star’s position in space is not changed. That is, the
equator and equinox of the data are changed, but not the epoch.
Setting option = 3 requests both transformations and is the most common case.
The two date arguments, date_incat and date_newcat, may be specified either as a
Julian date (e.g., 2433282.5) or a Julian year and fraction (e.g., 1950.0). (Values less
than 10000.0 are assumed to represent years.)
The option = 1 and option = 3 transformations are appropriate only for objects with
linear (or no) space motion; do not use them for components of binary stars. Also, this
function cannot be properly used to bring data from old star catalogs into the modern system,
because old catalogs were compiled using a set of constants (in particular, the rate of
precession) that are incompatible with modern values.
The option = 2 and option = 3 transformations involve the dynamical system, that is,
the moving mean equator and equinox. The mean equator and equinox of J2000.0 was the
most common reference system for modern astrometric catalog data before the ICRS was
introduced in 1998. Now, catalog data is usually referred to the ICRS, which is a reference
system fixed with respect to distant extragalactic objects not defined by any Earth motions
and with no associated date.
The option = 4 transformation is used to convert catalog quantities from the mean equator
and equinox of J2000.0 (the “J2000.0 system”) to the ICRS. The option = 5
transformation is the opposite. The arguments date_incat and date_newcat are ignored
for these transformations.
Function frame_tie can be used to transform vectors from the J2000.0 system to the ICRS or
vice versa.
See function transform_hip for transforming Hipparcos catalog data to epoch J2000.0.
SIZE_OF_CAT_NAME is defined in novas.h.
(Return to Function List)
C-58
transform_hip
void transform_hip (cat_entry *hipparcos,
cat_entry *hip_2000)
PURPOSE:
To convert Hipparcos catalog data at epoch J1991.25 to epoch
J2000.0, for use within NOVAS. To be used only for Hipparcos or
Tycho stars with linear space motion. Both input and output data
is in the ICRS.
REFERENCES:
None.
INPUT
ARGUMENTS:
*hipparcos (struct cat_entry)
An entry from the Hipparcos catalog, at epoch J1991.25, with
all members having Hipparcos catalog units. See Note 1
below (struct defined in novas.h).
OUTPUT
ARGUMENTS:
*hip_2000 (struct cat_entry)
The transformed input entry, at epoch J2000.0.
below (struct defined in novas.h).
See Note 2
RETURNED
VALUE:
None.
NOTES:
1. Input (Hipparcos catalog) epoch and units:
Epoch: J1991.25
Right ascension (RA): degrees
Declination (Dec): degrees
Proper motion in RA: milliarcseconds per year
Proper motion in Dec: milliarcseconds per year
Parallax: milliarcseconds
Radial velocity: kilometers per second (not in catalog)
2. Output (modified Hipparcos) epoch and units:
Epoch: J2000.0
Right ascension: hours
Declination: degrees
Proper motion in RA: milliarcseconds per year
Proper motion in Dec: milliarcseconds per year
Parallax: milliarcseconds
Radial velocity: kilometers per second
Discussion:
Function transform_hip takes Hipparcos catalog data, which is published for epoch J1991.25,
and transforms it to epoch J2000.0 for use in NOVAS functions such as place, app_star,
topo_star, virtual_star, etc. The Hipparcos (input) right ascension is expressed in degrees, as
in the catalog, while the J2000.0 (output) right ascension is given in hours, compatible with
C-59
other NOVAS functions. Function transform_cat (with option = 1) is called to perform
the epoch transformation. The reference frame for both input and output is the ICRS.
This function should be used only for Hipparcos stars with linear space motion.
Radial velocity (hipparcos->radialvelocity) is not given in the Hipparcos catalog. If
a value is not known, set hipparcos->radialvelocity = 0.0. The radial velocity is
important for only a small number of nearby, high proper motion stars.
(Return to Function List)
C-60
app_star
short int app_star (double jd_tt, cat_entry *star, short int accuracy,
double *ra, double *dec)
PURPOSE:
Computes the apparent place of a star at date 'jd_tt', given its
catalog mean place, proper motion, parallax, and radial velocity.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992), Ch. 3
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for apparent place.
*star (struct cat_entry)
Pointer to catalog entry structure containing catalog data for
the object in the ICRS (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Apparent right ascension in hours, referred to true equator
and equinox of date 'jd_tt'.
*dec (double)
Apparent declination in degrees, referred to true equator
and equinox of date 'jd_tt'.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
> 10 ... Error code from function 'make_object'.
> 20 ... Error code from function 'place'.
Discussion:
Function app_star computes the apparent place of a star for time jd_tt. As used here, any
object outside the solar system is a “star.” The calling program should set promora,
promodec, parallax, or radialvelocity within structure star to 0.0 if their values
are unknown, if their values are zero within the associated error, or if they describe an
extragalactic object.
Function app_star works by calling place with location->where = 0 and coord_sys =
1.
Function make_cat_entry can assemble “loose” catalog data into a structure of type
cat_entry.
(Return to Function List)
C-61
topo_star
short int topo_star (double jd_tt, double delta_t, cat_entry *star,
on_surface *position, short int accuracy,
double *ra, double *dec)
PURPOSE:
Computes the topocentric place of a star at date 'jd_tt', given its
catalog mean place, proper motion, parallax, and radial velocity.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for topocentric place.
delta_t (double)
Difference TT-UT1 at 'jd_tt', in seconds of time.
*star (struct cat_entry)
Pointer to catalog entry structure containing catalog data for
the object in the ICRS (defined in novas.h).
*position (struct on_surface)
Specifies the position of the observer (structure defined in
novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Topocentric
and equinox
*dec (double)
Topocentric
and equinox
RETURNED
VALUE:
(short int)
= 0 ...
= 1 ...
> 10 ...
> 20 ...
right ascension in hours, referred to true equator
of date 'jd_tt'.
declination in degrees, referred to true equator
of date 'jd_tt'.
Everything OK.
Invalid value of 'where' in structure 'location'.
Error code from function 'make_object'.
Error code from function 'place'.
Discussion:
Function topo_star computes the topocentric place of a star (neglecting atmospheric
refraction) for the location specified by the argument location at time jd_tt. Note that
jd_tt is the TT time at which the topocentric place is to be computed. The word “star” as
used here refers to any object outside the solar system. If the values of promora,
promodec, parallax, or radialvelocity within structure star are unknown (or zero
C-62
within the errors of measurement), the calling program should set them to zero. For
extragalactic objects, these input values should also be set to zero. The difference TT–UT1
(often called ∆T) is passed to the function via argument delta_t. Values of ∆T are
published annually in The Astronomical Almanac or can be obtained from the EO web site. 38
Atmospheric refraction can be subsequently applied to ra and dec by function equ2hor.
Function topo_star works by calling place with location->where = 1 and coord_sys
= 1.
“Loose” catalog data can be assembled into a structure of type cat_entry by using
function make_cat_entry.
(Return to Function List)
38
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
C-63
virtual_star
short int virtual_star (double jd_tt, cat_entry *star,
short int accuracy,
double *ra, double *dec)
PURPOSE:
Computes the virtual place of a star at date 'jd_tt', given its
catalog mean place, proper motion, parallax, and radial velocity.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for virtual place.
*star (struct cat_entry)
Pointer to catalog entry structure containing catalog data for
the object in the ICRS (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Virtual right ascension in hours, referred to the GCRS.
*dec (double)
Virtual declination in degrees, referred to the GCRS.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
> 10 ... Error code from function 'make_object'.
> 20 ... Error code from function 'place'.
Discussion:
See the discussion for function app_star. Function virtual_star is identical to app_star in
input arguments and use. Here, however, the output arguments provide the virtual place
(also called the proper place) of the star. The virtual place (proper place) is essentially the
apparent place expressed in the GCRS.
Function virtual_star works by calling place with location->where = 0 and coord_sys
= 0.
(Return to Function List)
C-64
local_star
short int local_star (double jd_tt, double delta_t, cat_entry *star,
on_surface *position, short int accuracy,
double *ra, double *dec)
PURPOSE:
Computes the local place of a star at date 'jd_tt', given its
catalog mean place, proper motion, parallax, and radial velocity.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992), Ch. 3
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for local place.
delta_t (double)
Difference TT-UT1 at 'jd_tt', in seconds of time.
*star (struct cat_entry)
Pointer to catalog entry structure containing catalog data for
the object in the ICRS (defined in novas.h).
*position (struct on_surface)
Specifies the position of the observer (structure defined in
novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Local right ascension in hours, referred to the 'local GCRS'.
*dec (double)
Local declination in degrees, referred to the 'local GCRS'.
RETURNED
VALUE:
(short int)
= 0 ...
= 1 ...
> 10 ...
> 20 ...
Everything OK.
Invalid value of 'where' in structure 'location'.
Error code from function 'make_object'.
Error code from function 'place'.
Discussion:
See the discussion for function topo_star. Function local_star is identical to topo_star in
input arguments and use. Here, however, the output arguments provide the local place of the
star. The local place is essentially the topocentric place expressed in the “local GCRS”.
Function local_star works by calling place with location->where = 1 and coord_sys
= 0.
(Return to Function List)
C-65
astro_star
short int astro_star (double jd_tt, cat_entry *star, short int accuracy,
double *ra, double *dec)
PURPOSE:
Computes the astrometric place of a star at date 'jd_tt', given
its catalog mean place, proper motion, parallax, and radial
velocity.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for astrometric place.
*star (struct cat_entry)
Pointer to catalog entry structure containing catalog data for
the object in the ICRS (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Astrometric right ascension in hours (referred to the ICRS,
without light deflection or aberration).
*dec (double)
Astrometric declination in degrees (referred to the ICRS,
without light deflection or aberration).
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
> 10 ... Error code from function 'make_object'.
> 20 ... Error code from function 'place'.
Discussion:
See the discussion for function app_star. Function astro_star is identical to app_star in
input arguments and use. Here, however, the output arguments provide the astrometric place
of the star in the ICRS.
Function astro_star works by calling place with location->where = 0 and coord_sys
= 3.
(Return to Function List)
C-66
app_planet
short int app_planet (double jd_tt, object *ss_body, short int accuracy,
double *ra, double *dec, double *dis)
PURPOSE:
Compute the apparent place of a solar system body.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for apparent place.
*ss_body (struct object)
Pointer to structure containing the body designation for the
solar system body (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Apparent right ascension in hours, referred to true equator
and equinox of date.
*dec (double)
Apparent declination in degrees, referred to true equator
and equinox of date.
*dis (double)
True distance from Earth to the body at 'jd_tt' in AU.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'type' in structure 'ss_body'.
> 10 ... Error code from function 'place'.
Discussion:
This function computes the apparent place of a solar system body. Your chosen version of
function solarsystem, accessed from function ephemeris, determines the source of the body’s
barycentric rectangular coordinates used in the calculation.
Function app_planet works by calling place with location->where = 0 and coord_sys
= 1.
(Return to Function List)
C-67
topo_planet
short int topo_planet (double jd_tt, object *ss_body, double delta_t,
on_surface *position, short int accuracy,
double *ra, double *dec, double *dis)
PURPOSE:
Computes the topocentric place of a solar system body.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for topocentric place.
*ss_body (struct object)
Pointer to structure containing the body designation for the
solar system body (defined in novas.h).
delta_t (double)
Difference TT-UT1 at 'jd_tt', in seconds of time.
*position (struct on_surface)
Specifies the position of the observer (structure defined in
novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Topocentric right ascension in hours, referred to true equator
and equinox of date.
*dec (double)
Topocentric declination in degrees, referred to true equator
and equinox of date.
*dis (double)
True distance from Earth to the body at 'jd_tt' in AU.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'where' in structure 'location'.
> 10 ... Error code from function 'place'.
Discussion:
Function topo_planet computes the topocentric place of a solar system body (neglecting
atmospheric refraction) for the location specified by the argument location at the time
specified by the argument jd_tt. The argument jd_tt is the TT time at which the
topocentric place is to be computed. The difference TT–UT1 (often called ∆T) is passed to
C-68
the function via argument delta_t. Values of ∆T are published annually in The
Astronomical Almanac or can be obtained from the EO web site. 39 The user’s choice of
ephemerides determines the values to be used in structure ss_body, which identifies the
solar system object.
Atmospheric refraction can be subsequently applied to ra and dec by function equ2hor.
Function topo_planet works by calling place with location->where = 1 and
coord_sys = 1.
(Return to Function List)
39
http://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term
C-69
virtual_planet
short int virtual_planet (double jd_tt, object *ss_body,
short int accuracy,
double *ra, double *dec, double *dis)
PURPOSE:
Compute the virtual place of a solar system body.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for virtual place.
*ss_body (struct object)
Pointer to structure containing the body designation for the
solar system body (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Virtual right ascension in hours, referred to the GCRS.
*dec (double)
Virtual declination in degrees, referred to the GCRS.
*dis (double)
True distance from Earth to the body in AU.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'type' in structure 'ss_body'.
> 10 ... Error code from function 'place'.
Discussion:
See the discussion for function app_planet. Function virtual_planet is identical to
app_planet in input arguments and use. Here, however, the output arguments provide the
virtual place (also called the proper place) of the body. The virtual place (proper place) is
essentially the apparent place expressed in the GCRS.
Function virtual_planet works by calling place with location->where = 0 and
coord_sys = 0.
(Return to Function List)
C-70
local_planet
short int local_planet (double jd_tt, object *ss_body,
double delta_t, on_surface *position,
short int accuracy,
double *ra, double *dec, double *dis)
PURPOSE:
Computes the local place of a solar system body.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992), Ch. 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for local place.
*ss_body (struct object)
Pointer to structure containing the body designation for the
solar system body (defined in novas.h).
delta_t (double)
Difference TT-UT1 at 'jd_tt', in seconds of time.
*position (struct on_surface)
Specifies the position of the observer (structure defined in
novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Local right ascension in hours, referred to the 'local GCRS'.
*dec (double)
Local declination in degrees, referred to the 'local GCRS'.
*dis (double)
True distance from Earth to the body in AU.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'where' in structure 'location'.
> 10 ... Error code from function 'place'.
Discussion:
See the discussion for function topo_planet. Function local_planet is identical to
topo_planet in input arguments and use. Here, however, the output arguments provide the
local place of the star. The local place is essentially the topocentric place expressed in the
“local GCRS.”
C-71
Function local_planet works by calling place with location->where = 1 and
coord_sys = 0.
(Return to Function List)
C-72
astro_planet
short int astro_planet (double jd_tt, object *ss_body,
short int accuracy,
double *ra, double *dec, double *dis)
PURPOSE:
Compute the astrometric place of a solar system body.
REFERENCES:
Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.
Explanatory Supplement to the Astronomical Almanac (1992), Chap. 3.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date for astrometric place.
*ss_body (struct object)
Pointer to structure containing the body designation for the
solar system body (defined in novas.h).
accuracy (short int)
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra (double)
Astrometric right ascension in hours (referred to the ICRS,
without light deflection or aberration).
*dec (double)
Astrometric declination in degrees (referred to the ICRS,
without light deflection or aberration).
*dis (double)
True distance from Earth to the body in AU.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'type' in structure 'ss_body'.
> 10 ... Error code from function 'place'.
Discussion:
See the discussion for function app_planet. Function astro_planet is identical to app_planet
in input arguments and use. Here, however, the output arguments provide the astrometric
place of the planet in the ICRS.
Function astro_planet works by calling place with location->where = 0 and
coord_sys = 3.
(Return to Function List)
C-73
precession
short int precession (double jd_tdb1, double *pos1, double jd_tdb2,
double *pos2)
PURPOSE:
Precesses equatorial rectangular coordinates from one epoch to
another. One of the two epochs must be J2000.0. The coordinates
are referred to the mean dynamical equator and equinox of the two
respective epochs.
REFERENCES:
Explanatory Supplement To The Astronomical Almanac, pp. 103-104.
Capitaine, N. et al. (2003), Astronomy And Astrophysics 412,
pp. 567-586.
Hilton, J. L. et al. (2006), IAU WG report, Celest. Mech., 94,
pp. 351-367.
INPUT
ARGUMENTS:
jd_tdb1 (double)
TDB Julian date of first epoch.
pos1[3] (double)
Position vector, geocentric equatorial rectangular coordinates,
referred to mean dynamical equator and equinox of first epoch.
jd_tdb2 (double)
TDB Julian date of second epoch.
OUTPUT
ARGUMENTS:
pos2[3] (double)
Position vector, geocentric equatorial rectangular coordinates,
referred to mean dynamical equator and equinox of second epoch.
RETURNED
VALUE:
(short int)
= 0 ... everything OK.
= 1 ... Precession not to or from J2000.0; 'jd_tdb1' or 'jd_tdb2'
not 2451545.0.
Discussion:
This function precesses the input position vector, pos1, from the equator and equinox of
jd_tdb1 to the equator and equinox of jd_tdb2; the resulting vector is pos2.
One of the two input Julian dates must be standard epoch J2000.0—either jd_tdb1 or
jd_tdb2 must be 2451545.0 exactly. To precess a vector from one arbitrary date to
another, call precession twice, using J2000.0 as the “middle” date. That is, in the first call,
jd_tdb1 = first Julian date and jd_tdb2 = 2451545.0; in the second call,
jd_tdb1 = 2451545.0 and jd_tdb2 = second Julian date.
Formally, the current precession algorithm is a function of Barycentric Dynamical Time
(TDB), but using TT as the basis for the input Julian dates results in a maximum error of only
about 3 × 10-9 arcseconds, which is totally negligible. Standard epoch J2000.0, although
C-74
formally defined in the TT time scale, is the same in the TT and TDB time scales to the
precision given by double-precision Julian dates: at J2000.0,
TT − TDB ≈ 10-4 second ≈ 10-9 day.
(Return to Function List)
C-75
equ2ecl
short int equ2ecl (double jd_tt, short int coord_sys,
short int accuracy, double ra, double dec,
double *elon, double *elat)
PURPOSE:
To convert right ascension and declination to ecliptic longitude
and latitude.
REFERENCES:
None.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date of equator, equinox, and ecliptic used for
coordinates.
coord_sys (short int)
Coordinate system selection.
= 0 ... mean equator and equinox of date 'jd_tt'
= 1 ... true equator and equinox of date 'jd_tt'
= 2 ... ICRS
(ecliptic is always the mean plane)
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
ra (double)
Right ascension in hours, referred to specified equator and
equinox of date.
dec (double)
Declination in degrees, referred to specified equator and
equinox of date.
OUTPUT
ARGUMENTS:
*elon (double)
Ecliptic longitude in degrees, referred to specified ecliptic
and equinox of date.
*elat (double)
Ecliptic latitude in degrees, referred to specified ecliptic
and equinox of date.
RETURNED
VALUE:
(short int)
= 0 ... everything OK
= 1 ... invalid value of 'coord_sys'
Discussion:
Function equ2ecl converts the equatorial position of an object into the equivalent ecliptic
position: equatorial coordinates ra and dec are converted to ecliptic coordinates elon and
elat. This function can be used for any kind of barycentric or geocentric coordinates—the
conversion involves a simple rotation and should be regarded as just a formalism. As in
C-76
function precession, the input Julian date can be based on either the TDB or TT time scales
with negligible resulting error.
ra and dec can be expressed with respect to either the mean equator and equinox of date
jd_tt (if coord_sys = 0) or the true equator and equinox of date jd_tt (if
coord_sys = 1).
The representation of the ecliptic used for celestial coordinates is a smoothly moving mean
plane described as part of the precession development. However, the mean and true equators
intersect this ecliptic at different points. Therefore, the equinox, which serves as the origin of
ecliptic longitude as well as the origin of right ascension, is different in the two cases. elon
will be expressed with respect to the same equinox as ra.
If jd_tt = 0.0 and coord_sys = 0, the function assumes ra and dec are expressed
with respect to the ICRS and provides elon and elat with respect to the ecliptic and mean
equinox of J2000.0.
See functions equ2ecl_vec and ecl2equ_vec for the conversion of vectors between equatorial
and ecliptic systems.
(Return to Function List)
C-77
cio_ra
short int cio_ra (double jd_tt, short int accuracy,
double *ra_cio)
PURPOSE:
This function computes the true right ascension of the celestial
intermediate origin (CIO) at a given TT Julian date. This is
-(equation of the origins).
REFERENCES:
Kaplan, G. (2005), US Naval Observatory Circular 179.
INPUT
ARGUMENTS:
jd_tt (double)
TT Julian date.
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*ra_cio (double)
Right ascension of the CIO, with respect to the true equinox
of date, in hours (+ or -).
RETURNED
VALUE:
(short int)
= 0 ...
= 1 ...
> 10 ...
> 20 ...
everything OK.
invalid value of 'accuracy'.
10 + the error code from function 'cio_location'.
20 + the error code from function 'cio_basis'.
Discussion:
This function supplies the true right ascension of the Celestial Intermediate Origin (CIO).
ra_cio = – (equation of the origins)
ra_cio = Greenwich apparent sidereal time – Earth Rotation Angle
where all quantities are expressed in hours.
(Return to Function List)
C-78
era
double era (double jd_high, double jd_low)
PURPOSE:
This function returns the value of the Earth Rotation Angle
(theta) for a given UT1 Julian date. The expression used is
taken from the note to IAU Resolution B1.8 of 2000.
REFERENCES:
IAU Resolution B1.8, adopted at the 2000 IAU General Assembly,
Manchester, UK.
Kaplan, G. (2005), US Naval Observatory Circular 179.
INPUT
ARGUMENTS:
jd_high (double)
High-order part of UT1 Julian date.
jd_low (double)
Low-order part of UT1 Julian date.
OUTPUT
ARGUMENTS:
None.
RETURNED
VALUE:
(double)
The Earth Rotation Angle (theta) in degrees.
Discussion:
This function supplies the Earth Rotation Angle, θ, which is the geocentric angle, in the
instantaneous equatorial plane (true equator), between the directions toward the Terrestrial
Intermediate Origin (TIO) and the Celestial Intermediate Origin (CIO).
This function allows for the input UT1 time to be represented as a split Julian date. See the
discussion in the description of function sidereal_time.
(Return to Function List)
C-79
cel_pole
short int cel_pole (double tjd, short int type, double dpole1,
double dpole2)
PURPOSE:
This function allows for the specification of celestial pole
offsets for high-precision applications. Each set of offsets is
a correction to the modeled position of the pole for a specific
date, derived from observations and published by the IERS.
REFERENCES:
Kaplan, G. (2005), US Naval Observatory Circular 179.
Kaplan, G. (2003), USNO/AA Technical Note 2003-03.
INPUT
ARGUMENTS:
tjd (double)
TDB or TT Julian date for pole offsets.
type (short int)
Type of pole offset
= 1 for corrections to angular coordinates of modeled pole
referred to mean ecliptic of date, that is,
delta-delta-psi and delta-delta-epsilon.
= 2 for corrections to components of modeled pole unit
vector referred to GCRS axes, that is, dx and dy.
dpole1 (double)
Value of celestial pole offset in first coordinate,
(delta-delta-psi or dx) in milliarcseconds.
dpole2 (double)
Value of celestial pole offset in second coordinate,
(delta-delta-epsilon or dy) in milliarcseconds.
OUTPUT
ARGUMENTS:
None.
RETURNED
VALUE:
(short int)
= 0 ... Everything OK.
= 1 ... Invalid value of 'type'.
Discussion:
This function allows for the specification of celestial pole offsets for high-precision
applications. The offsets describe the observed position of the Celestial Intermediate Pole
(CIP) with respect to the position computed from the standard precession and nutation
models. The offsets are subsequently applied as corrections to the nutation in longitude and
nutation in obliquity within e_tilt. Thus, e_tilt output arguments tobl, ee, dpsi, and deps
will be affected. Because other NOVAS functions, such as sidereal_time, call e_tilt to obtain
data related to the Earth’s orientation in space, the celestial pole offsets specified here are
propagated through the data that the various NOVAS functions provide.
C-80
Daily values of the celestial pole offsets are published, for example, in IERS Bulletins A and
B. 40 The celestial pole offsets effectively correct for errors or incompleteness in the standard
precession or nutation models. If you use cel_pole, make sure it is called before any other
functions for a given date. Values of the pole offsets that you specify by a call to cel_pole
will be used by e_tilt until you explicitly change them.
Important: For compatibility with the precession and nutation models used in NOVAS 3.0,
and later, specify type = 2 and use only IERS dX and dY values with respect to “IAU
2000A” (sometimes labeled “IAU 2000”). These pole offset values will generally not exceed
0.5 milliarcsecond and therefore cel_pole would need to be called only when very high
accuracy is required.
(Return to Function List)
40
http://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html
C-81
e_tilt
void e_tilt (double jd_tdb, short int accuracy,
double *mobl, double *tobl, double *ee, double *dpsi,
double *deps)
PURPOSE:
Computes quantities related to the orientation of the Earth's
rotation axis at Julian date 'jd_tdb'.
REFERENCES:
None.
INPUT
ARGUMENTS:
jd_tdb (double)
TDB Julian Date.
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
*mobl (double)
Mean obliquity of the ecliptic in degrees at 'jd_tdb'.
*tobl (double)
True obliquity of the ecliptic in degrees at 'jd_tdb'.
*ee (double)
Equation of the equinoxes in seconds of time at 'jd_tdb'.
*dpsi (double)
Nutation in longitude in arcseconds at 'jd_tdb'.
*deps (double)
Nutation in obliquity in arcseconds at 'jd_tdb'.
RETURNED
VALUE:
None.
Discussion:
This function computes various quantities related to the orientation of the Earth’s rotation
axis (vector toward Celestial Intermediate Pole) with respect to the ecliptic plane at a specific
time. The computation involves a call to function nutation_angles to evaluate the nutation
series.
The output values of the last four arguments will correctly reflect the celestial pole offsets if
function cel_pole has previously been called.
(Return to Function List)
C-82
ephemeris
short int ephemeris (double jd[2], object *cel_obj, short int origin,
short int accuracy,
double *pos, double *vel)
PURPOSE:
Retrieves the position and velocity of a solar system body from
a fundamental ephemeris.
REFERENCES:
None.
INPUT
ARGUMENTS:
jd[2] (double)
TDB Julian date split into two parts, where the sum
jd[0] + jd[1] is the TDB Julian date.
*cel_obj (struct object)
Pointer to structure containing the designation of the body
of interest (defined in novas.h).
origin (short int)
Origin code
= 0 ... solar system barycenter
= 1 ... center of mass of the Sun
accuracy (short int)
Selection for accuracy
= 0 ... full accuracy
= 1 ... reduced accuracy
OUTPUT
ARGUMENTS:
pos[3] (double)
Position vector of the body at 'jd_tdb'; equatorial rectangular
coordinates in AU referred to the ICRS.
vel[3] (double)
Velocity vector of the body at 'jd_tdb'; equatorial rectangular
coordinates in AU/day referred to the ICRS.
RETURNED
VALUE:
(short int)
0
...
1
...
2
...
3
...
10+n ...
20+n ...
Everything OK.
Invalid value of 'origin'.
Invalid value of 'type' in 'cel_obj'.
Unable to allocate memory.
where n is the error code from 'solarsystem'.
where n is the error code from 'readeph'.
Discussion:
Function ephemeris serves as the single interface between NOVAS and ephemerides of solar
system bodies. The version of ephemeris distributed with NOVAS provides direct support
for the JPL ephemerides of major solar system bodies (such as JPL’s DE405, DE406, and
C-83
DE421), and the USNO minor planet ephemerides (USNO/AE98 41). The function ephemeris
calls an appropriate version of function solarsystem (or solarsystem_hp) in order to access an
ephemeris of the “major” bodies (in this context Sun, Moon, and Mercury through Pluto). It
accesses the minor planet ephemerides by calling readeph. Neither the USNO minor planet
ephemerides nor the JPL ephemerides are part of NOVAS and must be obtained elsewhere as
discussed in sections 2.4 and 2.3, respectively.
Modifying function ephemeris to support ephemerides other than the two mentioned above is
relatively easy. In function ephemeris, a switch structure is controlled by the value of type
in a data structure of type object. Currently, two cases within the switch are defined:
type = 0 for major bodies to be handled via a call to solarsystem and type = 1 for minor
planets to be handled via a call to readeph. To support ephemerides of other bodies, simply
define a new value of type and add another case block containing code that accesses the
new ephemeris. Alternate versions of solarsystem can be written to support alternate
ephemerides, i.e., non-JPL, of major solar system bodies.
Additional information concerning function solarsystem is provided in the following
sections.
(Return to Function List)
41
http://www.usno.navy.mil/USNO/astronomical-applications/software-products/usnoae98
C-84
solarsystem
short int solarsystem (double tjd, short int body, short int origin,
double *position, double *velocity)
PURPOSE:
Provides the position and velocity vectors of a planet or other
solar system body at a specific time. The origin of coordinates
may be either the barycenter of the solar system or the center
of mass of the Sun.
REFERENCES:
JPL. 2007, "JPL Planetary and Lunar Ephemerides: Export Information,"
(Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry
Subroutines"; USNO internal document dated 20 Oct 1988;
revised 15 Mar 1990.
INPUT
ARGUMENTS:
tjd (double)
Julian date of the desired time, on the TDB time scale.
body (short int)
Body identification number for the solar system object of
interest; Mercury = 1,...,Pluto = 9, Sun = 10, Moon = 11.
origin (short int)
Origin code
= 0 ... solar system barycenter
= 1 ... center of mass of the Sun
OUTPUT
ARGUMENTS:
position[3] (double)
Position vector of 'body' at tjd; equatorial rectangular
coordinates in AU referred to the ICRS.
velocity[3] (double)
Velocity vector of 'body' at tjd; equatorial rectangular
system referred to the ICRS, in AU/day.
RETURNED
VALUE:
(short int)
0...Everything OK.
Other values depend upon version in use.
Discussion:
Another NOVAS function, ephemeris, calls this function, solarsystem to provide the position
vector pos and velocity vector vel for body at time tjd. The vectors computed by
solarsystem are expressed with respect to ICRS axes, in the BCRS metric. The vectors are
barycentric if origin = 0 and heliocentric if origin = 1.
Three different versions of solarsystem are supplied in NOVAS, each with its own internal
logic. One uses internally-stored data or series expansions while the other two use the JPL
ephemerides, which exist as external data files. Additional documentation (see below) is
C-85
usually required for the proper use of each version. You are, of course, free to supply your
own version(s) of solarsystem, providing that the arguments conform to the above
specifications.
The values of the body identification number, body, will in general differ from one
solarsystem version to another; consult the documentation for the specific version in use.
Usually, body = 1 refers to Mercury, body = 2 refers to Venus, body = 3 refers to the
Earth, etc., but the identification numbers for bodies such as the Sun or Moon differ across
implementations. [Note: The data structure of type object, input to function ephemeris,
specifies the way that NOVAS identifies solar-system bodies. Code within ephemeris does
the “translation” between the body numbers required by ephemeris and the body numbers
required by solarsystem.] Furthermore, some versions of solarsystem support only a subset
of the major solar system bodies. The minimum requirement is support for the Sun and
Earth. Here, “Earth” refers to the geocenter and not the Earth/Moon barycenter.
For highest-precision applications using “split” Julian dates, call solarsystem_hp.
(Return to Function List)
C-86
solarsystem, version 1
(File solsys1.c)
RETURNED
VALUE:
None.
Discussion:
This version of solarsystem provides an “all C” interface between NOVAS and the JPL lunar
and planetary ephemerides. Specifically, it serves as the interface between USNO’s C version
of the JPL ephemeris software (contained in file eph_manager.c) and the main set of
NOVAS functions. This version of solarsystem calls planet_ephemeris (the C version of
JPL’s Fortran subroutine PLEPH), which in turn calls other functions in the ephemeris
software package. The user must set up the binary, random-access ephemeris file (see
Appendix C).
Important: When using this version of solarsystem, the user’s program that calls the
NOVAS functions must make a call to function ephem_open prior to calling the NOVAS
functions. ephem_open opens the binary JPL ephemeris file (DE200, DE403, DE404,
DE405, DE406, and DE421 are supported). Similarly, the user’s program should call
ephem_close to close the binary ephemeris file once ephemeris access is no longer
required. The functions ephem_open and ephem_close are located in eph_manager.c.
The body identification numbers to be used with this version are listed below.
body
10
1
2
3
4
5
6
7
8
9
11
Name
Sun
Mercury
Venus
Earth
Mars
Jupiter
Saturn
Uranus
Neptune
Pluto
Moon
(Return to Function List)
C-87
solarsystem, version 2
(File solsys2.c)
RETURNED
VALUE:
(short int)
0...Everything OK.
1...Invalid value of body or origin.
2...Error detected by JPL software.
Discussion:
This version of solarsystem serves as the interface between the JPL’s own Fortran-based
lunar and planetary ephemeris software and NOVAS. The function contains a single call to
Fortran subroutine jplint_, which in turn calls PLEPH and other Fortran subroutines in the
JPL ephemeris software package. The user is responsible for obtaining the Fortran
ephemeris code and data, setting up the binary, random-access ephemeris file, and linking the
JPL Fortran code with NOVAS. See the implementation notes below.
The body identification numbers to be used with this version are listed below.
body
10
1
2
3
4
5
6
7
8
9
11
Name
Sun
Mercury
Venus
Earth
Mars
Jupiter
Saturn
Uranus
Neptune
Pluto
Moon
Implementation Notes:
In order to use NOVAS with solarsystem version 2, you must first obtain the planetary
ephemeris export package from JPL as discussed in Appendix C. If the verification process
is successful, the ephemeris file is ready to use. The ephemeris data is obtained from the
binary file by calling the access subroutines provided in the JPL export package.
Version 2 of solarsystem obtains ephemeris data from the binary file by calling Fortran
subroutine jplint_, which is contained in NOVAS file jplint.f. Subroutine jplint_, in turn,
calls JPL Fortran subroutine PLEPH and all other supporting Fortran subroutines. The C
function solarsystem has a few features that make it possible for it to exchange data with the
Fortran subroutine jplint_. First, all of the C arguments of the call to jplint_ are addresses,
because Fortran uses call by address instead of call by value for arguments of subroutines.
Second, all of the integer arguments in the call are designated as type long int in the C
C-88
function to match the Fortran INTEGER default. The DOUBLE PRECISION arguments in the
subroutine are designated as type double in the C function.
Probably the biggest hurdle in implementing version 2 of solarsystem involves the proper
compiling and linking of files containing different languages. The procedures will be
specific to your computing platform; therefore, you will have to consult your compiler
manual for detailed instructions. The following instructions are offered only as a guideline;
they provide a specific example of how such files were successfully handled on a PC running
Red Hat Enterprise Linux ES release 4 (Nahant Update 8).
1. Create a single file named jplsubs.f with all of the JPL Fortran ephemeris access
subroutines as discussed in Appendix C.
2. Compile the Fortran files, jplsubs.f and jplint.f, without invoking the linkage
editor to create the object file jplsubs.o and jplint.o. The Fortran compiler/linker
is g77.
g77 -c jplsubs.f jplint.f
3. Compile, again without invoking the linkage editor, the C files main.c, novas.c,
novascon.c, nutation.c, solsys2.c, and readeph0.c that create the object files
main.o, novas.o, novascon.o, nutation.o, solsys2.o, and readeph0.o. In this
example, main.c is the name of the file containing the user’s program. The C
compiler/linker is gcc.
gcc -c main.c novas.c novascon.c nutation.c solsys2.c readeph0.c
4. Finally, link the object files using the Fortran linker:
object files
g77 -o app main.o novas.o novascon.o nutation.o solsys2.o readeph0.o jplsubs.o jplint.o
create executable named "app"
In this example, the resulting executable file is named app.
(Return to Function List)
C-89
solarsystem, version 3
(File solsys3.c)
RETURNED
VALUE:
(short int)
0...Everything OK.
1...Input Julian date ('tjd') out of range.
2...Invalid value of 'body'.
Discussion:
This version of solarsystem provides the position and velocity of the Earth or Sun only
without reference to any external data file. The heliocentric position and velocity of the Earth
are computed by evaluating trigonometric series. When barycentric positions and velocities
are required, a number of additional approximations are involved; therefore, barycentric
positions and velocities computed by this version of solarsystem are less accurate than
heliocentric positions and velocities. This version of solarsystem produces data within the
following error limits (compared to the JPL DE405 ephemeris) for dates within the interval
1800–2050:
Earth heliocentric positions:
Earth heliocentric velocities:
Earth barycentric positions:
Earth barycentric velocities:
840
1.4
2500
1.4
km
m/s
km
m/s
When this version of solarsystem is used in the computation of the apparent place of the Sun,
it should contribute less than 2 arcseconds of error. When used in the computation of
apparent places of stars, it should contribute less than 1.5 milliarcseconds of error. This
assessment applies to the interval 1800–2050.
This version of solarsystem will return ierr = 1 for Julian dates prior to 2340000.5
(August 1694) or Julian dates after 2560000.5 (December 2296).
This version of solarsystem calls NOVAS function precession, and certain expressions in the
solarsystem algorithm have been adjusted to conform to the IAU 2006 precession.
The body identification numbers to be used with this version are listed below.
body
Name
Sun
Sun
Sun
Earth
Earth
0
1
10
2
3
(Return to Function List)
C-90
solarsystem_hp
short int solarsystem_hp (double tjd[2], short int body,
short int origin,
double *position, double *velocity)
PURPOSE:
Provides an interface between the JPL direct-access solar system
ephemerides and NOVAS-C for highest precision applications.
REFERENCES:
JPL. 2007, "JPL Planetary and Lunar Ephemerides: Export
Information," (Pasadena, CA: JPL)
http://ssd.jpl.nasa.gov/?planet_eph_export.
Kaplan, G. H. "NOVAS: Naval Observatory Vector Astrometry
Subroutines"; USNO internal document dated 20 Oct 1988;
revised 15 Mar 1990.
INPUT
ARGUMENTS:
tjd[2] (double)
Two-element array containing the Julian date, which may be
split any way (although the first element is usually the
"integer" part, and the second element is the "fractional"
part). Julian date is on the TDB or "T_eph" time scale.
body (short int)
Body identification number for the solar system object of
interest; Mercury = 1, ..., Pluto= 9, Sun= 10, Moon = 11.
origin (short int)
Origin code
= 0 ... solar system barycenter
= 1 ... center of mass of the Sun
OUTPUT
ARGUMENTS:
position[3] (double)
Position vector of 'body' at tjd; equatorial rectangular
coordinates in AU referred to the ICRS.
velocity[3] (double)
Velocity vector of 'body' at tjd; equatorial rectangular
system referred to the ICRS, in AU/day.
RETURNED
VALUE:
Value depends upon version in use.
Discussion:
Function solarsystem_hp provides positions and velocities for the major bodies of the solar
system when the highest precision is required. This function supports the “split” Julian date
feature for highest precision. The two parts of the input Julian date are stored in the twoelement array, tjd.
(Return to Function List)
C-91
solarsystem_hp, version 1
(File solsys1.c)
RETURNED
VALUE:
None.
Discussion:
This version of solarsystem_hp provides an “all C” interface between NOVAS and the JPL
lunar and planetary ephemerides when the highest precision is required. Specifically, it
serves as the interface between USNO’s C version of the JPL ephemeris software (contained
in file eph_manager.c) and the main set of NOVAS functions. This version of
solarsystem_hp calls planet_ephemeris (the C version of JPL’s Fortran subroutine PLEPH),
which in turn calls other functions in the ephemeris software package. The user must set up
the binary, random-access ephemeris file (see Appendix C).
Important: When using this version of solarsystem_hp, the user’s program that calls the
NOVAS functions must make a call to function ephem_open prior to calling the NOVAS
functions. ephem_open opens the binary JPL ephemeris file (DE200, DE403, DE404,
DE405, DE406, and DE421 are supported). Similarly, the user’s program should call
ephem_close to close the binary ephemeris file once ephemeris access is no longer
required. The functions ephem_open and ephem_close are located in eph_manager.c.
The body identification numbers to be used with this version are listed below.
Body
10
1
2
3
4
5
6
7
8
9
11
Name
Sun
Mercury
Venus
Earth
Mars
Jupiter
Saturn
Uranus
Neptune
Pluto
Moon
(Return to Function List)
C-92
solarsystem_hp, version 2
(File solsys2.c)
RETURNED
VALUE:
(short int)
0...Everything OK.
1...Invalid value of body or origin.
2...Error detected by JPL software.
Discussion:
This version of solarsystem_hp serves as the interface between the JPL’s own Fortran-based
lunar and planetary ephemeris software and NOVAS when the highest precision is required.
The function contains a single call to Fortran subroutine jplihp_, which in turn calls
DPLEPH and other Fortran subroutines in the JPL ephemeris software package. The user is
responsible for obtaining the Fortran ephemeris code and data, setting up the binary, randomaccess ephemeris file, and linking the JPL Fortran code with NOVAS. See the
implementation notes below.
The body identification numbers to be used with this version are listed below.
Body
10
1
2
3
4
5
6
7
8
9
11
Name
Sun
Mercury
Venus
Earth
Mars
Jupiter
Saturn
Uranus
Neptune
Pluto
Moon
Implementation Notes:
In order to use NOVAS with solarsystem_hp version 2, you must first obtain the planetary
ephemeris export package from JPL (see Appendix C for details). If the verification process
is successful, the ephemeris file is ready to use. The ephemeris data is obtained from the
binary file by calling the access subroutines provided in the JPL export package.
Version 2 of solarsystem_hp obtains ephemeris data from the binary file by calling Fortran
subroutine jplihp_, which is in the NOVAS jplint.f file. Subroutine jplihp_, in turn, calls JPL
subroutine DPLEPH (Fortran code) and all other supporting Fortran subroutines. The C
function solarsystem_hp has a few features that make it possible for it to exchange data with
the Fortran subroutine jplihp_. First, all of the C arguments of the call to jplihp_ are
C-93
addresses, because Fortran uses call by address instead of call by value for arguments of
subroutines. Second, all of the integer arguments in the call are designated as type long
int in the C function to match the Fortran INTEGER default. The DOUBLE PRECISION
arguments in the subroutine are designated as type double in the C function.
Probably the biggest hurdle in implementing version 2 of solarsystem_hp involves the proper
compiling and linking of files containing different languages. The procedures will be
specific to your computing platform; therefore, you will have to consult your compiler
manual for detailed instructions. The instructions given for version 2 of solarsystem provide
an example of how such files could be handled.
(Return to Function List)
C-94
solarsystem_hp, version 3
(File solsys3.c)
RETURNED
VALUE:
(short int)
0...Everything OK.
1...Input Julian date ('tjd') out of range.
2...Invalid value of 'body'.
3...This version of 'solarsystem' not valid for use with
NOVAS-C.
Discussion:
NOVAS does not provide a high-precision counterpart of solarsystem version 3 that works
without requiring an external data file. Thus, this version of solarsystem_hp is essentially a
dummy function that acts according to the value of variable action, which is set within the
function itself.
If action = 1 (the default), this function returns an error code of 3 indicating
appropriately that the function does not provide high-precision position and velocity of the
Earth and Sun.
If action = 2 (must be manually set), this function simply calls function solarsystem
(version 3) and returns the low-precision position and velocity. An error code of 0 (no error)
is also returned. This action may be useful for code testing purposes, but is neither
appropriate nor recommended for normal use of NOVAS. Use alternate versions of
solarsystem_hp (located in the various solsysn.c files, where n is an integer) when the highest
precision is needed.
(Return to Function List)
C-95
Nutation Models
(File nutation.c)
The C version of NOVAS provides three implementations of the nutation model, all of which
are found in file nutation.c. Each model computes the nutation angles, ∆ψ and ∆ε, which are
the nutation in longitude and obliquity, respectively. These functions have the following
input and output:
INPUT
ARGUMENTS:
jd_high (double)
High-order part of TT Julian date.
jd_low (double)
Low-order part of TT Julian date.
OUTPUT
ARGUMENTS:
*dpsi (double)
Nutation (luni-solar + planetary) in longitude, in radians.
*deps (double)
Nutation (luni-solar + planetary) in obliquity, in radians.
RETURNED
VALUE:
None.
Discussion:
The nutation model is invoked via function nutation_angles in file novas.c. As previously
mentioned, the nutation model can be the most computationally intensive part of NOVAS. It
makes no sense to evaluate the full IAU 2000A nutation model (1,365 terms) [iau2000a]
unless the highest level of accuracy is needed. Thus, in addition to the full IAU 2000A
model, two reduced-accuracy models—truncated versions of IAU 2000A—are also provided:
IAU 2000B [iau2000b] and 2000K [nu2000k]. Section 1.4 discussed these models in greater
detail. Several higher-level NOVAS functions have an input argument, accuracy, which
specifies whether a full- or reduced-accuracy calculation is desired. Whenever accuracy is
set to 0 (full accuracy), IAU 2000A is used. By default, whenever accuracy is set to 1
(reduced accuracy), 2000K is used. However, a small coding change can be made to
nutation_angles to replace 2000K with IAU 2000B as the reduced-accuracy model. The
prolog and comments in nutation_angles explain how to make this change. A summary of
the models follows.
Nutation
Model
Function
Name
Accuracy
Selection
IAU 2000A
2000K
IAU 2000B
iau2000a
nu2000k
iau2000b
full
reduced (default)
reduced (alternate)
Terms
Accuracy Compared to
IAU 2000A (mas)
1,365
488
77
(Return to Function List)
C-96
…
0.1
1
Time Span
…
1700–2300
1995–2050
Chapter 5
Equinox- and CIO-Based Par adigms Compar ed
5.1 Computing Hour Angles
The equinox- and CIO-based celestial reference systems are part of two computational
schemes for accounting for the Earth’s instantaneous orientation with respect to the stars.
These two methods represent the same phenomena, as they obviously must, but in slightly
different order. The overall matrix that embodies, for a given instant, the terrestrial-tocelestial (ITRS-ICRS) transformation is the same for both schemes. Therefore, the value of
observable quantities will not be affected by the choice of which paradigm is used for the
computations.
In NOVAS, quantities such as declination and hour angle, which are in principle measurable
angles, should have the same values regardless of the way in which they are computed.
Because both the equinox-based and CIO-based paradigms are constructed on the
instantaneous (true) equator of date—the plane orthogonal to the CIP—declinations are, in
fact, completely unaffected.
How are hour angles of celestial objects computed in the old and new paradigms? Assume
that we are considering Greenwich hour angles, that is, hour angles measured from the
meridian of geodetic longitude zero (the X-Z plane of the ITRS) without polar motion. In the
equinox-based scheme, we compute the topocentric place of the object of interest with
respect to the true equator and equinox of date. Then, we compute Greenwich apparent
sidereal time and subtract the object’s apparent right ascension to form the hour angle. In the
CIO-based scheme, we compute the object’s topocentric place with respect to the true
equator and CIO of date. To form the hour angle, we compute the ERA and subtract the
CIO-based right ascension (also called the intermediate right ascension). The two results
should be identical. The computed GHA may have to be reduced to the range −12h to +12h.
The table below summarizes the two equivalent procedures for hour angle and the NOVAS
functions that would be used for each, assuming that polar motion is neglected. The
procedures outlined here provide the Greenwich hour angle (GHA) of a star; only the first step
would be different for a solar system body.
Functions app_star, topo_star, and place require time arguments in the TT time scale
(topo_star also requires ∆T), while sidereal_time and era require time arguments in the UT1
time scale. The two procedures should yield the same value of GHA to within a microarcsecond around the present time and identical values for DEC. To obtain the local hour
angle in either method, simply add to the GHA the observer’s longitude (east positive) in
appropriate units.
C-97
Use
function
…to obtain
Then, use
function
…to obtain
Compute
Greenwich
hour angle
Equinox-Based Method
topo_star
— or —
place with
cel_object (type) = ′2′,
location = 1, and
CIO-Based Method
place with
coord_sys = 1
RA and DEC
cel_object (type) = ′2′, ,
location = 1, and
coord_sys = 2
RA and DEC
topocentric RA and dec of the star
with respect to the true equator and
equinox of date
(in hours and degrees, respectively)
sidereal_time with
topocentric RA and dec of the star
with respect to the true equator and
CIO of date
(in hours and degrees, respectively)
era
gst_type = 1
GST
THETA
Greenwich apparent sidereal time
(in hours)
Earth Rotation Angle, θ
(in degrees)
GHA = GST – RA
GHA = THETA / 15.0 – RA
(in hours)
(in hours)
The common notion of hour angle becomes somewhat problematic when polar motion is
taken into account, because what we usually regard as the Greenwich (or observer’s)
meridian—a plane of constant geodetic longitude—is not, in general, parallel to an hour
circle on the celestial sphere when the geodetic pole and the CIP are not coincident. See the
discussion in section 6.5.4 of USNO Circular 179. 42
5.2 Other Computational Considerations
Three high-level NOVAS functions that involve Earth rotation, sidereal_time, ter2cel, and
cel2ter, can perform their internal calculations using either the equinox-based paradigm or
the CIO-based paradigm. As previously mentioned, sidereal_time computes sidereal time.
ter2cel performs the terrestrial-to-celestial transformation, and cel2ter performs the celestialto-terrestrial transformation. (equ2hor is indirectly involved because it calls ter2cel.) The
method used within the three functions is selected when that function is called. The integer
input argument, method, must be set to either zero (0) to use the CIO-based method or to
one (1) to use the equinox-based method. Because no external difference occurs in how
sidereal_time, ter2cel, or cel2ter are used, and because the two computational paradigms
yield answers that are consistent within a few microarcseconds over many centuries, a
practical basis for choosing seldom arises. However, the equinox method is much more
efficient if mean sidereal time is to be computed.
42
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-98
Finally, another of the new Earth-rotation-related functions is worth mentioning. For a given
TT Julian date, cio_ra provides the right ascension of the CIO with respect to the true
equinox of date. With a sign reversal, this quantity is the equation of the origins, the direction
of the true equinox measured in the equator eastward (+) from the CIO. Because the equinox
and CIO are simply different right ascension origins on the instantaneous equator, cio_ra
provides the angular difference between the origins of these two systems. The equation of
the origins is also the difference, expressed as an angle, between the ERA and Greenwich
apparent sidereal time.
5.3 How NOVAS Implements the CIO-Based Paradigm
The equinox-based paradigm is, of course, the historical basis for NOVAS. One of its key
pieces is the precession algorithm [precession], which uses the equinox as its azimuthal
coordinate; that is, it transforms celestial coordinates from the mean equator and equinox of
one date to the mean equator and equinox of another date. Even though the recommended
precession formulation has been replaced twice over the last half-century, this aspect of it has
remained unchanged. Another key piece is the algorithm for sidereal time [sidereal_time],
which is based on a sidereal day that is defined by successive transits of the equinox. The
sidereal time formula must always be matched to the precession algorithm, because mean
sidereal time must account for the precession of the equinox in right ascension; this has been
consistently done in NOVAS.
To use the CIO-based paradigm, we must know where the CIO is in some well-defined
coordinate system. Unlike the equinox, the CIO is not defined by static geometry but by its
motion, so its position at any time is given by the result of an integral that has been evaluated
either analytically or numerically. In NOVAS, both results are available: the position of the
CIO can be taken from an external file that is the output of a numerical integration, or it can
be obtained from an analytical expression for the equation of the origins [cio_location]. See
sections 6.5.1.1 and 6.5.1.2 of USNO Circular 179. 43
The NOVAS implementation of the CIO-based Earth-rotation paradigm for a given date is
based on the construction of the Celestial Intermediate Reference System for that date, using
vectors toward the CIP and the CIO. These two directions define, respectively, the z-axis
and x-axis of the celestial intermediate system. The direction toward the CIP in the GCRS
can be computed by passing the vector (0,0,1) through functions nutation, precession, and
frame_tie in succession. Given the direction of the CIP, the other piece of required
information is the location of the CIO for the same date, which is provided by cio_location
described below. The basis vectors of the intermediate system, with respect to the GCRS, are
computed by cio_basis (see section 6.5.1 of USNO Circular 179 for the algorithms). Having
these basis vectors available allows NOVAS to easily transform any vector in the GCRS to
the intermediate system. The only other quantity used in the CIO-based paradigm is the
ERA, which is trivial to compute and is provided by era.
Function cio_location obtains the location of the CIO for a given date in one of two ways and
sets an output argument, ref_sys, that indicates which way was used. If an external file of
43
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-99
CIO right ascension values is available (nominally called cio_ra.bin and located in the
current directory) then cio_location will provide the GCRS right ascension of the CIO, and
will set ref_sys to one (1). If this file is not available, then cio_location will provide the
true right ascension of the CIO (the arc on the instantaneous equator from the equinox to the
CIO), obtained from a series expansion, and will set ref_sys to two (2). cio_basis can
work with either coordinate of the CIO. The two methods are equivalent within several
microarcseconds over six centuries centered on the year 2000; it is not clear which method is
more correct.
To do the hard work, cio_location calls either cio_array (for ref_sys = 1) or ira_equinox
(for ref_sys = 2). cio_location always initially checks to see if the external file of CIO
right ascensions is present. If it is, cio_array reads the file, which is the output from a
numerical integration covering years 1700 to 2300, and returns an array to be interpolated;
the interpolation directly provides the right ascension of the CIO in the GCRS. A copy of
CIO_RA.TXT is provided as part of the NOVAS distribution, along with a utility program
called cio_file.c to convert the text file to a binary direct-access file; section 2.5 describes
creating cio_ra.bin (2.9 Mbytes) from CIO_RA.TXT (7.5 Mbytes).
If cio_ra.bin is not present, then cio_location calls ira_equinox to evaluate the equation of
the origins from a closed-form expression that includes the evaluation of nutation in
longitude, a lengthy series of trigonometric terms. The result locates the CIO with respect to
the equinox on the instantaneous equator.
At no point does NOVAS use the CIO locator, s, which is described in IERS documents and
The Astronomical Almanac.
5.4 References
Kaplan, G. H. 2005, The IAU Resolutions on Astronomical Reference Systems, Time Scales,
and Earth Rotation Models, USNO Circular 179 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
(USNO Circular 179)
USNO & HMNAO. 2009, The Astronomical Almanac for the Year 2011, (Washington, DC:
GPO) and subsequent editions
(Return to Table of Contents)
C-100
Appendix A Over view of How NOVAS Has Changed
A detailed list of the changes in the NOVAS C code from the previous versions (C2.0.1 of
2000 and C3.0 of 2009) is given in Appendix B. This appendix provides some perspective
on these changes for people who are already familiar with NOVAS. Most of the
modifications have been made in response to resolutions passed by the IAU in 2000 and
2006 that recommended new models for fundamental astronomy within a new conceptual
framework. To the greatest extent possible, the calling sequences for the highest-level (and
most used) functions from the previous versions of NOVAS have been preserved, but a few
important exceptions exist. Many new calls are now available as well.
A.1
Important Changes in Calls
Probably the most important change to existing NOVAS calls is the change of proper motion
and parallax units in the calls to app_star, virtual_star, astro_star, transform_cat, and
transform_hip, all of which deal with star positions. The units have been changed as follows:
• proper motion in right ascension: from seconds per century to milliarcseconds per year
• proper motion in declination:
from arcseconds per century to milliarcseconds per year
• parallax:
from arcseconds to milliarcseconds
These changes have been made to conform to the units used in most modern star catalogs
(e.g., Hipparcos, Tycho-2, or the FK6), which in turn follow from the observational
techniques now used in the construction of such catalogs. Obviously, star data previously
used with NOVAS must either be replaced or transformed. The transformation equations
from “old” to “new” units are as follows:
pmrnew = pmrold * 150.0 * cos ( dec0 * DEG2RAD ); /* proper motion in RA */
pmdnew = pmdold * 10.0;
/* proper motion in declination */
paxnew = paxold * 1000.0;
/* parallax */
where dec0 is the catalog declination (J2000.0 or ICRS) of the star in degrees and DEG2RAD
is the degrees-to-radians conversion factor (0.01745329…).
Another important change to the high-level functions is that the argument lists of the
traditional “place” functions (app_star, topo_star, app_planet, topo_planet. virtual_star,
etc.) have changed. The earth data structure (type body) has been removed. This structure
is now created within the new place function described in the following section. A new input
parameter, accuracy, has been added to select either full-accuracy or reduced-accuracy
calculations.
Finally, function pnsw has been renamed to ter2cel with a change to its time argument; this
function carries out the terrestrial-to-celestial transformation.
All other changes to existing NOVAS calls involve lower-level functions not frequently
invoked by most users; Appendix B details these changes.
C-101
A.2
place: A New General-Purpose “Place” Function
All computational code to compute apparent, topocentric, virtual, astrometric, etc., places of
stars or planets has now been consolidated into a single new function called place. The
familiar calls to the traditional place functions from earlier versions of NOVAS still work
essentially as before—except for the important changes described in A.1 above—but are now
just “front-ends” to place [app_star, topo_star, app_planet, topo_planet. virtual_star,
local_star, virtual_planet, local_planet, astro_star, astro_planet]. This change eliminated
much duplicate code, provides more flexibility, and allows for possible future additions (such
as binary star orbits or nonlinear terms in proper motion). place can produce star or planet
positions within the Celestial Intermediate Reference System that is part of the new paradigm
for Earth rotation calculations (see below). place provides its output position both in
spherical coordinates (right ascension, declination, and, for solar system bodies, geometric
distance) and as a unit vector. In addition, place furnishes radial velocity. It also allows the
observer to be located at the geocenter, on or near the Earth’s surface, or in a near-Earth
spacecraft. You may want to consider changing your calls to app_star, app_planet, etc., to
the equivalent calls to place; the code for the new versions of the traditional place functions
specifies the appropriate input parameters.
A.3
New Reference Systems
The IAU resolutions of 2000 defined several new reference systems for fundamental
astronomy. The Barycentric Celestial Reference System (BRCS), Geocentric Celestial
Reference System (GCRS), International Celestial Reference System (ICRS), and Celestial
Intermediate Reference System are defined briefly below. More detailed descriptions of these
systems are in section 1.1 of this document and in Chapters 1, 3, and 6 of USNO Circular
179. 44
Barycentric Celestial Reference System (BCRS) replaces the barycentric system based on
the mean equator and equinox of J2000.0. It is used for data tabulated in astrometric catalogs
and fundamental solar system ephemerides.
Geocentric Celestial Reference System (GCRS) replaces the geocentric system based on
the mean equator and equinox of J2000.0. It is used for geocentric apparent positions of
celestial objects, measurements and coordinates in the near-Earth environment, and artificial
Earth satellite ephemerides.
The BCRS and GCRS are nearly parallel systems, related by a relativistic transformation.
International Celestial Reference System (ICRS) is the name applied to the orientation of
the axes of the BCRS, based on the adopted coordinates of several hundred extragalactic
radio sources that are assumed to have no net systematic motion. The resulting orientation is
close to, but not exactly aligned with, the mean equator and equinox of J2000.0. The ICRS is
a “space-fixed” (kinematically non-rotating) system.
44
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-102
Because of their close relationship, the abbreviations “BCRS” and “ICRS” are often used
interchangeably.
Celestial Intermediate Reference System is a system for geocentric apparent positions of
stars and planets based on the true (instantaneous) equator of date and a zero point of right
ascension at the CIO (see section A.5).
The geocentric system based on the true equator and equinox of date is also still used for
geocentric apparent positions of stars and planets.
These reference systems are now used for the input and output arguments to NOVAS
functions. For example, NOVAS 3.0, and later, assume that input reference data, such as
catalog star positions and proper motions, and the basic solar system ephemerides, are
provided in the ICRS (that is, within the BCRS as aligned to the ICRS axes), or at least are
consistent with it to within the data’s inherent accuracy. The distinction between the ICRS
and the system defined by the mean equator and equinox of J2000.0 (the “J2000.0 system”)
becomes important only when an accuracy of 0.02 arcseconds or better is needed.
Nevertheless, because NOVAS is designed for the highest accuracy applications, the ICRS is
given as the reference system of choice for many input arguments to NOVAS functions.
Because the ICRS axes are not precisely aligned to those of the J2000.0 system, a new
function called frame_tie is available to transform vectors between the two systems. This
transformation is a very small fixed rotation. frame_tie is used for both barycentric vectors
(BCRS to or from the barycentric J2000.0 system) and geocentric vectors (GCRS to or from
the geocentric J2000.0 system). frame_tie is called many times, in both directions, within the
NOVAS code. It is needed because precession (and nutation) can properly be applied only to
vectors in a real equatorial system; vectors in the GCRS (geocentric ICRS) must be
transformed, via frame_tie, to the J2000.0 system before precession is used. If your code
only interacts with the highest-level NOVAS functions, all this is transparent to you.
However, if you use precession within your own code, you should precede it by a call to
frame_tie (with the middle argument direction > 0) if your input vector is expressed in the
GCRS, that is, if it is derived from an input source based on the ICRS.
Output data from many of the supervisory-level NOVAS functions can be expressed in the
GCRS or either of two equator-of-date systems: the true equator and equinox of date or the
Celestial Intermediate Reference System. The latter two systems differ only in their right
ascension origins, and, in the new paradigm, they are understood to be derived from the
GCRS by applying a few rotations.
A.4
New Models for Precession and Nutation
As described in section 1.4, new models for both precession and nutation have been adopted
by the IAU and have been incorporated into NOVAS. Although the underlying
developments for these effects are different than in NOVAS 2.0, from a programming point
of view, little has changed. The functions that directly involve precession and nutation
[precession, nutation, nutation_angles, sidereal_time] essentially work the same as before,
but with slightly different results. The new nutation model has more than ten times the
number of trigonometric terms than the previous model. Because evaluation of nutation has
always been the most computationally intensive task in NOVAS, you may notice an increase
C-103
in execution time for some NOVAS applications. However, that extra computation time can
be reduced.
Earth-rotation calculations can be performed in either full- or reduced-accuracy mode as
described in section 2.6. Many functions include an input argument, accuracy, that
determines which mode will be used by that function and by any function it calls. In fullaccuracy mode, the various models are evaluated at the few-microarcsecond level. For
nutation, using this mode means that a 1,365-term trigonometric series is evaluated for each
unique date. However, neither the models nor current observations are accurate at this level,
so much of the increased computational burden is unproductive. Reduced-accuracy mode can
be used when the accuracy requirements are not better than 0.1 milliarcsecond for stars or
3.5 milliarcseconds for solar system bodies. The computation time for these calculations is
thereby reduced by about two-thirds.
A.5
New Model for the Rotation of the Earth about its Axis
IAU resolutions passed in 2000 established a new geometric paradigm for how we describe
the Earth’s spin around its axis. Both the old and new paradigms are based on the
instantaneous (true) equator of date, but they use different fiducial points on the equator as
the origin of right ascension and different time-like quantities (actually, time-dependent
angles) to describe the rotation of the Earth. As described in section 1.4 and Chapter 5, the
conventional scheme is based on the equinox and sidereal time; in the new paradigm, the
reference point is called the CIO and the time-like quantity is called the ERA. A more
complete explanation of the new concepts, along with the algorithms used with them, can be
found in Chapter 6 of USNO Circular 179. 45
NOVAS 3.0, and later, implement both the equinox- and CIO-based computational schemes.
Implementing the CIO-based paradigm has required the addition of many new functions
along with new code added to existing functions. First, the function place is coded to provide
output right ascensions with respect to either the equinox or the CIO; the choice is made
through input argument coord_sys. Function gcrs2equ can similarly convert GCRS right
ascensions and declinations to their equatorial equivalents (for a given date) with output right
ascensions measured with respect to either zero point. cio_ra provides the angle between the
two zero points, that is, the difference between the two right ascension systems. Functions
cio_location, cio_basis, cio_array, ira_equinox provide lower-level support to these
computations. Function era computes the ERA for any instant.
Two high-level NOVAS functions that involve Earth rotation, sidereal_time and ter2cel (the
latter replaces the old pnsw) have been re-coded to perform their internal calculations using
either the equinox-based or CIO-based paradigm. When each function is called, an input
argument, method, is set to either zero (0) for the CIO-based approach or one (1) for the
equinox-based approach. New NOVAS 3.1 function cel2ter works similarly.
45
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-104
A.6
New Features
The functions in this section have been added to NOVAS to increase functionality and
convenience.
place is new general-purpose apparent place function. Section A.2 describes this function in
greater detail.
equ2ecl converts RA and dec to ecliptic longitude and latitude. In addition, equ2ecl_vec and
ecl2equ_vec convert vectors from an equatorial to an ecliptic basis and vice versa,
respectively.
equ2gal converts ICRS RA and dec to galactic longitude and latitude.
gcrs2equ converts GCRS (geocentric ICRS) RA and dec to one of the equatorial systems of
date.
make_object and make_observer are examples of a new set of functions which have been
added to facilitate the construction of important data structures used in NOVAS.
cel2ter (NOVAS 3.1) transforms a vector from the celestial system (GCRS) to the terrestrial
system (ITRS).
A.7
New Terminology
Not surprisingly, the IAU resolutions on reference systems and Earth rotation have required
some new terminology, and an IAU Working Group on Nomenclature for Fundamental
Astronomy was established for the 2003–2006 triennium to systematize the usage. New
terms and abbreviations now appear in the comment statements of many NOVAS functions,
including the prologs where the input and output arguments are described. The most
important terms are described in Chapter 1 of this document and further information can be
found in USNO Circular 179.
A.8
References
Kaplan, G. H. 2005, The IAU Resolutions on Astronomical Reference Systems, Time Scales,
and Earth Rotation Models, USNO Circular 179 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
(USNO Circular 179)
(Return to Table of Contents)
C-105
C-106
Appendix B List of Changes fr om NOVAS C2.0.1 to C3.1
This appendix lists in detail the changes between the current C3.1 version of NOVAS and
earlier versions (C3.0 of 2009 and C2.0.1 of 2000). Appendix A provides some perspective
on these changes for people who are already familiar with NOVAS. Most of the
modifications are in response to resolutions passed by the IAU in 2000 and 2006 that
recommended new models for fundamental astronomy within a new conceptual framework.
To the greatest extent possible, the calling sequences for the highest-level (and most used)
functions from the previous versions of NOVAS have been preserved, but a few important
exceptions exist. Many new calls are now available as well.
B.1
New Functions
B.1.1 New Functions in NOVAS C3.0
cio_array is called from cio_location. It reads and returns a set of values of the GCRS right
ascension of the CIO, near a given TDB Julian date, from an external, binary direct-access
file.
cio_basis returns orthonormal basis vectors for the Celestial Intermediate Reference System
with respect to the GCRS. It requires a prior call to cio_location.
cio_location returns the RA of the CIO at a given TDB Julian date, either with respect to the
GCRS or with respect to the true equator and equinox of date.
cio_ra returns the value of the true RA of the CIO for a given TDB Julian date.
d_light evaluates the difference in light-time to a star between the solar system barycenter
and the Earth.
ecl2equ_vec converts an ecliptic position vector to an equatorial position vector.
ee_ct evaluates a 34-term series for “complementary terms” in the equation of the equinoxes
based on the work of Capitaine, Wallace, and McCarthy (2003), which is also discussed in
Petit and Luzum, eds. (2010).
equ2ecl converts equatorial RA and dec to ecliptic longitude and latitude.
equ2ecl_vec converts an equatorial position vector to an ecliptic position vector.
equ2gal converts ICRS RA and dec to galactic longitude and latitude.
era evaluates the ERA, θ.
frame_tie sets up the frame tie matrix and transforms a vector from the dynamical mean
J2000.0 system to the ICRS, or vice versa. This function implements a first-order matrix
with second-order corrections to the diagonal elements, patterned after the work by Hilton
and Hohenkerk (2004). Given the smallness of the angles involved and their uncertainties,
this approach is quite adequate.
C-107
gcrs2equ transforms GCRS RA and dec to RA and dec on mean or true equator of date. For
true equator of date, either the true equinox or the CIO can be specified as the origin of right
ascension.
geo_posvel is called from place to compute the geocentric position and velocity vectors of an
observer on, or above, the surface of the Earth.
grav_def replaces sun_field; it supervises the evaluation of gravitational deflection of light
due to the Sun, Jupiter, and other solar system bodies. It calls a new function grav_vec to do
the deflection calculation for each body.
grav_vec calculates the gravitational deflection of light due to a solar system body. It is
called by grav_def, a new function that replaces sun_field.
iau2000a evaluates the IAU 2000A nutation series (nutation only) based on IERS code 46
(Wallace 2003a).
iau2000b evaluates the IAU 2000B nutation series based on IERS code (Wallace 2003b).
ira_equinox returns the value of the Equation of the Origins, i.e., the right ascension of the
equinox in the Celestial Intermediate Reference System from an analytical expression. The
Equation of the Origins is the arc on the true equator of date from the CIO to the equinox,
measured positively to the east.
light_time is called from place to antedate the position of a solar system body for light-time.
limb_angle evaluates where an observed object is with respect to the Earth’s limb (horizon),
given the geocentric position vectors of the observer and the object. place calls limb_angle
for the topocentric cases in order to decide whether to include the gravitational deflection of
light due to the Earth itself.
make_observer creates a structure of type observer specifying the location of the observer.
make_observer_at_geocenter creates a structure of type observer specifying an observer at
the geocenter.
make_observer_in_space creates a structure of type observer specifying the position and
velocity of an observer situated on a near-Earth spacecraft.
make_observer_on_surface creates a structure of type observer specifying the location of
and weather for an observer on the surface of the Earth.
make_in_space creates a structure of type in_space specifying the position and velocity of
an observer situated on a near-Earth spacecraft.
make_on_surface creates a structure of type on_surface specifying the location of and
weather for an observer on the surface of the Earth.
mean_obliq is called from e_tilt and cel_pole to compute the mean obliquity of the ecliptic.
norm_ang is called by ee_ct to normalize angles into the range 0 ≤ angle < (2 π).
46
http://tai.bipm.org/iers/conv2003/conv2003_c5.html
C-108
nu2000k is a modification of iau2000a. It evaluates a truncated version (2000K) of the full
IAU 2000A nutation series and uses a consistent set of expressions for the fundamental
arguments, those of Simon et al. (1994). It is more accurate than the IAU 2000B series:
about 0.1 milliarcseconds for Δψ and about 0.04 milliarcseconds for Δε and Δψ sin ε over a
longer interval of time than IAU 2000B.
place is a new, general-purpose function for computing apparent, topocentric, virtual,
astrometric, etc., places of stars and planets. All substantive code for performing these
calculations has been moved from app_star, topo_star, app_planet, etc., into place. In the
call to place, the object requested is specified by the input parameter cel_object. The type
of place requested is specified by two input parameters, one indicating the location of the
observer and the other indicating the coordinate system of the output positions. app_star,
topo_star, app_planet, etc., now are just “front-ends” to place.
rad_vel is called from place to compute the radial velocity of observed object with respect to
the observer.
B.1.2 New Function in NOVAS C3.1
cel2ter transforms a vector from the celestial system (GCRS) to the terrestrial system (ITRS).
B.2
Changes to NOVAS C Structures and Calling Sequences
B.2.1 Changes in Structures and Calling Sequences from C2.0.1 to C3.0
All of the high-level functions (place, app_star, app_planet, etc.) now assume that they are
working with ICRS data, including input RA, dec, and proper motion components for the
stellar functions and position and velocity vectors obtained from solarsystem for both
stellar and planetary functions. virtual_star, local_star, virtual_planet, local_planet,
astro_star, astro_planet, and mean_star produce output positions in the ICRS.
app_star, virtual_star, astro_star, app_planet, virtual_planet, astro_planet, mean_star,
topo_star, topo_planet, local_star, and local_planet have a new accuracy input parameter.
The former earth input parameter was removed from each of these functions.
aberration no longer returns an error code.
bary_to_geo was renamed bary2obs.
cel_pole can now accept input corrections to the pole positions as either (dψ, dε) or
(dX, dY); the choice of correction is specified by a new input parameter type. In either case,
the units of the correction must be in milliarcseconds. In addition, this function now returns
an error code.
earthtilt was renamed e_tilt with a new accuracy input parameter.
ephemeris now returns an error code.
get_earth was eliminated and its functionality moved to place.
C-109
make_cat_entry changed its proper motion units (in both RA and dec) to
milliarcseconds/year and changed its parallax units to milliarcseconds. Proper motion in RA
includes a cos dec factor.
nutate was renamed nutation. It has a new accuracy input parameter, and it no longer
returns an error code.
nutation_angles has a new accuracy input parameter, and it no longer returns an error code.
pnsw was renamed ter2cel (terrestrial-to-celestial transformation) with the former input
argument tjd changed to a UT1 Julian date split into a pair of double-precision words,
jd_ut_high and jd_ut_low, and with a new accuracy input parameter added.
precession can no longer process two arbitrary epochs, because the new precession
expressions are not as flexible as those of Lieske et al. (1977, 1979). Therefore, one of the
input epochs must be 2451545.0 (J2000.0). In addition, this function now returns an error
code.
set_body was renamed make_object.
sidereal_time has new delta_t, gst_type, method, and accuracy input parameters. The
former ee input parameter was removed. In addition, this function now returns an error code.
spin is no longer specifically associated with sidereal time. It now applies a rotation about
the current z-axis with the angle expressed in degrees.
struct body was renamed object with the length of name member shortened to
50 characters and structure cat_entry member added.
struct site_info was renamed on_surface.
sun_field was replaced by grav_def, a more general function that evaluates the gravitational
deflection of light due to several solar system bodies.
tdb2tdt was renamed tdb2tt.
transform_cat has two modified and two new transformation options. Existing option=2
and existing option=3 can no longer process two arbitrary epochs, because the new
precession expressions are not as flexible as those of Lieske et al. (1977, 1979). Therefore,
one of the input epochs for these options must be 2451545.0 (J2000.0). New option=4
rotates data from the dynamical equator and equinox of J2000.0 to the ICRS while new
option=5 does the opposite rotation.
wobble has a new Julian date argument.
B.2.2 Changes in Structures and Calling Sequences from C3.0 to C3.1
To prevent possible array overflows, two new preprocessor constants, SIZE_OF_OBJ_NAME
and SIZE_OF_CAT_NAME have been defined in novas.h. SIZE_OF_OBJ_NAME defines the
length of the starname character array in the cat_entry structure and the length of the
name character array in the object structure. SIZE_OF_CAT_NAME defines the length of
the catalog character array in the cat_entry structure. Although the actual lengths of
C-110
the arrays are unchanged, the make_cat_entry and make_object function prototypes and
definitions now use these new preprocessor constants in their argument lists.
wobble has a new direction input parameter.
Several changes were made to the ephemeris manager code in eph_manager.c and
eph_manager.h.
B.3
•
The function names Ephem_Open, Ephem_Close, Planet_Ephemeris, State,
Interpolate, and Split were all changed to lower case (i.e., ephem_open, ephem_close,
planet_ephemeris, state, interpolate, and split) to conform to internal coding
standards.
•
ephem_open also has an additional output argument, de_number, that indicates the
DE number of the opened ephemeris file.
Significant Internal Changes to Code
B.3.1 Significant Internal Changes to Code from C2.0.1 to C3.0
app_star, topo_star, app_planet, topo_planet, virtual_star, local_star, virtual_planet,
local_planet, astro_star, and astro_planet are now simply “front-ends” to specific calls to
place. All substantive apparent place calculations of the various kinds are now done only in
place. The following changes in the basic algorithms were made.
1. Calls to frame_tie were added in appropriate places to transform between the ICRS
and the dynamical system.
2. In updating a star’s position for proper motion, a correction to the epoch of interest
for the difference in light-time between the solar system barycenter (the reference
point for the input catalog data) and the Earth itself is now included. This change
affects only stars with the greatest proper motions and, then, only at the
0.1-milliarcsecond level. The new function d_light is used to compute the epoch
offset.
3. The “Doppler factor,” k, is included in the computation of stellar space motion
vectors as discussed in the note on starvectors below.
4. Modifications were made related to the change in gravitational deflection algorithms
from sun_field to the more general function grav_def as discussed in the note above.
5. Code has been introduced that allows a place to be expressed in the Celestial
Intermediate Reference System (equator of date with CIO as the right ascension
origin).
6. Code has been added that allows the input of an observer’s instantaneous geocentric
position and velocity vectors (with respect to the true equator and equinox of date) for
a topocentric place calculation; this change supports satellite observations.
e_tilt now evaluates a more complete series for the complementary terms in the equation of
the equinoxes; formerly, it just evaluated the two largest terms. It uses the expression for the
mean obliquity from the P03 precession formulation. Internally, the function works in either
full- or reduced-accuracy mode as set by the accuracy input parameter.
Full-accuracy mode obtains the sum of the terms from IERS function ee_ct.
C-111
Reduced-accuracy obtains the sum of the terms from a nine-term internal series.
equ2hor implements an improved algorithm for refraction geometry.
fund_args now evaluates expressions for the fundamental solar and lunar arguments from
Simon et al. (1994).
nutation_angles now just calls either of the nutation functions, iau2000a (from the IERS) or
nu2000k (a reduced-accuracy version of iau2000a), to do the hard work; it does not contain a
nutation series itself. The nutation function called depends on the value of the accuracy
input parameter. In reduced-accuracy mode, iau2000b may be called instead of nu2000k by
making a small code modification as explained in the prolog to the nutation_angles function.
precession now evaluates the precession-angle polynomials for the Capitaine, Wallace, and
Chapront (2003) P03 model, which was recommended by an IAU resolution in 2006. Some
code changes were made to ensure reversibility of transformation (to/from J2000.0).
sidereal_time returns the value of sidereal time, either mean or apparent. Internally, this
function can work by either of two methods as set by the method input parameter.
Equinox-based method evaluates the expression for mean sidereal time following the
discussion in section 2.6.2 of USNO Circular 179. 47 The ERA, θ, is obtained from era.
For apparent sidereal time, the equation of the equinoxes, including the “complementary
terms,” is obtained from e_tilt.
CIO-based method obtains the sidereal time using the method of section 6.5.4 of USNO
Circular 179. That equation is based on the position of the true equinox of date in the
Celestial Intermediate Reference System, the basis of which is obtained from cio_basis.
The ERA, θ, is obtained from era. Mean sidereal time, when requested, is calculated by
subtracting the equation of the equinoxes, obtained from e_tilt.
In either method, sidereal_time/era evaluates θ using the input UT1 epoch, but other
components of sidereal time are evaluated using TDB (set equal to TT), with
TT=UT1+ΔT where the delta_t input parameter sets the ΔT value.
ter2cel performs the terrestrial-to-celestial transformation on a given vector, i.e., the total
rotation from the ITRS to the GCRS; it includes calls to frame_tie at appropriate places.
Internally, this function can work by either of two methods as set by method input
parameter.
Equinox-based method evaluates the old-style transformation as per the previous function
pnsw, but with a call to frame_tie added at the end to put final vector in GCRS. This
method uses apparent sidereal time, obtained from sidereal_time.
CIO-based method performs the transformation of equations 3 and 4 given by Kaplan
(2003), based on the Celestial Intermediate Reference System. The orthonormal basis of
the system is obtained from cio_basis, and the ERA, θ, is obtained from era.
In either method, the “fast angle” (rotation about z-axis) is evaluated using the input UT1
epoch, but other components of sidereal time are evaluated using TDB (set equal to TT),
with TT=UT1+ΔT where the delta_t input parameter sets the ΔT value.
47
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
C-112
transform_cat, transform_hip, and starvectors were modified to accommodate the new
proper motion and parallax units.
transform_cat and starvectors now use (sin(parallax))-1 to compute distance, rather than
parallax-1; an inconsequential change that just makes the expression formally correct. Also,
the “Doppler Factor,” k, mentioned in the Hipparcos documentation and other papers, is now
applied in computing the space-motion vector. The computational distance used for objects
of zero parallax has been increased to 1 Gpc (2.06 x 1014 AU).
transform_cat calls frame_tie for new transformation option=4 and for the new
transformation option=5, which rotate data between dynamical J2000.0 system and ICRS.
wobble now includes a very tiny (inconsequential for most applications) rotation about the zaxis in the matrix to correct the ITRS longitude origin to TIO. This rotation uses the recently
published approximation to TIO longitude as a function of time, which required that the new
time argument also be added to this function. Essentially, this modification changes a W
rotation to a W´ rotation. Also, the matrix-element expressions changed from first-order
approximations to exact expressions for increased precision.
The following changes were made to constants:
• renamed MAU to AU and updated value
• renamed KMAU to AU_KM and updated value
• added AU_SEC from DE405
• added C_AUDAY
• changed units of C from AU/day to meters/second
• updated value of GS from DE405
• added GE from DE405
• renamed EARTHRAD to ERAD, changed units from kilometers to meters, and updated value
• updated value of F
• renamed OMEGA to ANGVEL
• added RMASS[12]
• updated value of TWOPI
• added ASEC360
• removed RAD2SEC
• added ASEC2RAD
B.3.2 Significant Internal Changes to Code from C3.0 to C3.1
app_star, astro_star, local_star, topo_star, and virtual_star all include a bug fix in the setup
of the local variable obj_name.
make_cat_entry includes a bug fix in the setup of the output structure members
star->starname and star->catalog.
make_object implements SIZE_OF_OBJ_NAME and SIZE_OF_CAT_NAME and checks the
length of name.
C-113
precession includes the static variable first_time to fix a bug that occurs when jd_tdb2
is T0 on the first call to this function.
Additionally, in nutation.c, iau2000a, iau2000b, and nu2000k now use static storage
class for the large const arrays.
In eph_manager.c and eph_manager.h, some variables have been changed from long int
to int to fix a problem on 64-bit Linux and Mac OS X 10.6 (Snow Leopard) systems.
B.4
Other Internal Code Changes
B.4.1 Other Internal Code Changes from C2.0.1 to C3.0
Many minor changes have been made in the code. Obviously, many of the comment
statements had to be revised, and others had to be added; such changes are too numerous to
try to list. Some variable names were changed. For example, the output RA and dec for the
mean_star function was named mra and mdec, the m indicating “mean”; these are now ira
and idec, the i indicating “ICRS.” Many similar trivial changes have been made.
B.4 .2 Other Internal Code Changes from C3.0 to C3.1
For consistency throughout NOVAS and with IERS Conventions, the variables representing
the coordinates of the celestial intermediate pole with respect to the ITRS pole were renamed
to xp and yp. This change is most notable in the input arguments of ter2cel, wobble, and
equ2hor.
ee_ct has additional references and notes.
mean_star uses make_cat_entry to set up the local tempstar structure.
sidereal_time has additional notes on usage.
The ephemeris manager code (eph_manager.c and eph_manager.h) contains many minor
internal updates, including support for JPL’s DE421.
B.5
References
Capitaine, N. Wallace, P. T., & Chapront. J. 2003, A&A, 412, 567 (P03)
Capitaine, N., Wallace, P. T., & McCarthy, D. D. 2003, A&A, 406, 1135
Hilton, J. L. & Hohenkerk, C. Y. 2004, A&A, 413, 765
Kaplan, G. H. 2003, in Proceeding of IAU Gen. Assembly XXV, Joint Discussion 16, The
International Celestial Reference System, Maintenance and Future Realizations, ed.
R. Guame, D. McCarthy, & J. Souchay (Sydney: The Assembly) 196
Kaplan, G. H. 2005, The IAU Resolutions on Astronomical Reference Systems, Time Scales,
and Earth Rotation Models, USNO Circular 179 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-179
(USNO Circular 179)
Lieske, J. H., Lederle, T., Fricke, W., & Morando, B. 1977, A&A, 1
C-114
Lieske, J. H. 1979, A&A, 282
Petit, G. & Luzum, B. (eds.) 2010, Chapter 5, in IERS Conventions, IERS Tech. Not. 36
(Frankfurt: IERS) (Table 5.2e presented in the printed publication is a truncated series. The
full series, which is used in NOVAS, is available on the IERS Conventions Center website in
file tab5.2e.txt.) ftp://tai.bipm.org/iers/conv2010/chapter5/
Simon, J. L., Bretagnon, P., Chapront, J., Chapront-Touze, M., Francou, G., & Laskar, J.
1994, A&A, 282, 663
Standish, E. M. 1998, “JPL Planetary and Lunar Ephemerides, DE405/LE405,” JPL IOM
312.F-98-048 (Pasadena, CA: JPL) http://ssd.jpl.nasa.gov/iau-comm4/relateds.html
Wallace, P. 2003a, NU2000A Subroutine, Subroutines for Chapter 5, in IERS Conventions,
ed. D. McCarthy & G. Petit, IERS Tech. Not. 32 (Frankfurt: IERS)
http://tai.bipm.org/iers/conv2003/conv2003_c5.html
Wallace, P. 2003b, NU2000B Subroutine, Subroutines for Chapter 5, in IERS Conventions,
ed. D. McCarthy & G. Petit, IERS Tech. Not. 32 (Frankfurt: IERS)
http://tai.bipm.org/iers/conv2003/conv2003_c5.html
(Return to Table of Contents)
C-115
C-116
Appendix C How to Set Up the J PL Ephemer ides
C.1
Overview
As described elsewhere in this document, NOVAS requires access to a high-accuracy solar
system ephemeris in order to compute places of solar system bodies and the highest-accuracy
star places. Groups in the U.S., France, and Russia now construct high-accuracy solar system
ephemerides. In NOVAS C, solarsystem version 1 and solarsystem version 2 provide direct
access to the “developmental ephemerides,” designated as “DEnnn,” which are produced by
JPL in the U.S. The former is a front-end to a USNO-supplied C implementation of JPL’s
ephemeris-access software, while the latter is a front-end to the JPL-provided Fortran
software; both versions enable reading and interpolating a binary, direct-access ephemeris
file. The binary ephemeris file is created from ASCII data files and software supplied by JPL.
The JPL software must be tailored for your specific computer architecture.
This appendix describes how to set up the binary ephemeris file and the JPL software that
reads it on your system. After these tasks have been done successfully, the JPL software must
be linked into any NOVAS application that uses solarsystem version 2. Alternatively, the
binary ephemeris file can be used directly with solarsystem version 1 and the software in file
eph_manager.c. The procedures outlined below worked on an Intel-based Mac OS X system
using the open-source gfortran compiler and the JPL software available in February 2009.
The resulting binary, direct-access ephemeris file was successfully transferred to and used on
other Intel-based computers running Microsoft Windows XP and Linux. Thus, our
procedures are tailored for computers containing Intel processors, including many systems
running Microsoft Windows, Mac OS X, and Linux. Providing specific procedures for all
combinations of computer processors, operating systems, and compilers is beyond the scope
of this user’s guide. Furthermore, the procedures in this appendix are intended simply as a
guide; the USNO cannot provide technical support regarding JPL software.
C.2
Step-by-Step Guide
Step 1: Connect to the JPL ftp site. All the files needed to install the JPL ephemerides are
available via anonymous ftp from ssd.jpl.nasa.gov. This can be accomplished through
most modern Web browsers by typing
ftp://ssd.jpl.nasa.gov
in the address (URL) field. When connected, go to the pub/eph/planets/ directory.
Step 2: Download the JPL software, ASCII ephemeris files, and corresponding test data file.
Follow the “CONTENTS TO BE RETRIEVED BY THE USER” instructions in the file
README.txt, which is also available as a webpage. 48 We recommend following the
instructions for “non-UNIX users” regardless of your computer’s operating system. Our
experience at USNO has been that the installation process is more a function of your
computer’s processor (hardware) than its operating system. The test data file, testpo.xxx,
48
http://ssd.jpl.nasa.gov/?planet_eph_export
C-117
may be found in both the same directory as the ASCII ephemeris files and in the separate test
data directory.
The characters used to terminate lines, the end-of-line codes, vary among operating systems.
Some systems use carriage returns (CR), some use line feeds (LF), and some use both. The
end-of-line codes may not be properly translated between operating systems when files are
copied from one system to another, depending on how the files are transferred and on what
options are invoked. If you have trouble reading or using any of the files downloaded from
JPL, check the encoding to ensure it is appropriate to your system.
Step 3: Configure the asc2eph.f file provided by JPL. For computer systems with Intel
processors, select (uncomment) the following statement at the beginning of the program:
PARAMETER ( NRECL = 4 )
Step 4: Split the testeph.f file provided by JPL into two files: jplsubs.f and testeph.f. The
first new file, jplsubs.f, should contain JPL subroutines FSIZER3, PLEPH (including
ENTRY DPLEPH), INTERP, SPLIT, STATE, and CONST extracted from the original JPL test
program. The second revised file, testeph.f, should contain only the main program and no
subroutines. JPL subroutines FSIZER1 and FSIZER2 will not be needed and are not retained
in either file.
The creation of the new file, jplsubs.f, is advantageous for the long-term use of the JPL
subroutines and the binary ephemeris files with NOVAS. The new file contains no
extraneous material and is named descriptively.
Step 5: Configure the new jplsubs.f file.
a. For computer systems with Intel processors, in subroutine FSIZER3 of jplsubs.f,
uncomment and set
NRECL=4
b. In subroutine FSIZER3 of jplsubs.f, identify the binary ephemeris file to be used
by setting
NAMFIL= 'JPLEPH'
You may wish to specify a more complete file name including the appropriate
directories, such as
NAMFIL= '/users/mystuff/ephem/JPLEPH'
to avoid having to keep an alias to this binary file in all your working directories.
c. In subroutine FSIZER3 of jplsubs.f, set KSIZE to the correct value for the
specific ephemeris being used (see the comments in the code); e.g., set
KSIZE = 2036
for DE405 and DE421.
d. In subroutine STATE of jplsubs.f, select (uncomment)
CALL FSIZER3(NRECL,KSIZE,NRFILE,NAMFIL)
leaving the lines containing CALL FSIZER1 and CALL FSIZER2 as comments.
Step 6: Compile and create executables.
a. Create executable application asc2eph by compiling and linking file asc2eph.f.
b. Create executable application testeph by compiling and linking files testeph.f
and jplsubs.f.
C-118
NOTE for Windows systems: Some Fortran compilers may produce files
with an .exe extension, i.e., asc2eph.exe and testeph.exe. If so, ignore the
.exe extension when using those applications in the following steps.
Step 7: Concatenate the ASCII data files and convert the concatenated file to binary form.
Follow the instructions in the “ASCII to BINARY (for non-UNIX users)” section of the
usrguide file, which is located in the pub/eph/planets directory. The resulting binary
ephemeris file will be named JPLEPH, or whatever name you specified in Step 5b.
Step 8: Test the binary ephemeris file. Follow the instructions in the “TESTING THE
BINARY FILE” section of the usrguide file, which is located in pub/eph/planets. You
should have already downloaded the appropriate test data file in Step 2.
NOTE: In testing, jplsubs.f returned different values for some dates when
compiled with Lahey/Fujitsu Fortran 95 and GNU Fortran 4.1.2 under Red
Hat Enterprise Linux ES release 4 (Nahant Update 9).
Step 9: Use the binary ephemeris file with NOVAS. After successfully completing the test,
compile and link NOVAS function solarsystem version 2 (solsys2.c) and the JPL subroutines
contained in jplsubs.f with the remaining relevant parts of NOVAS and your application
code. Alternatively, the binary ephemeris file can be used directly with solarsystem version 1
and the software in file eph_manager.c. Unless you specified otherwise in Step 5b, the
binary JPL ephemeris file, or an alias to it, should reside in the same directory as your
executable application.
(Return to Table of Contents)
C-119
C-120
Appendix D A Compar ison of SOFA and NOVAS C3.0
The Standards of Fundamental Astronomy (IAU 2009a; SOFA) 49 library is the official
collection of approved software for positional astronomy, operating under the auspices of
International Astronomical Union (IAU) Division 1 (Fundamental Astronomy). Both Fortran
and C libraries are available. An international SOFA Reviewing Board manages the
collection.
Generally, NOVAS is independent of SOFA although both software libraries include code
that is similar to two IERS Fortran modules. 50 Function iau2000a, which evaluates the full
1,365-term IAU 2000A nutation series in NOVAS 3.0, is based on the IERS subroutine
NU2000A. Function ee_ct, which evaluates the “complementary terms” in the equation of the
equinoxes, is based on IERS function EECT2000. The corresponding modules in SOFA are,
respectively, iau_NUT00A and iau_EECT00 (Fortran) and iauNut00a and iauEect00 (C).
The document SOFA Tools for Earth Attitude, also known as the “SOFA Cookbook,”
contains several Fortran examples of the transformation between terrestrial and celestial
coordinate systems. This appendix examines how one of those examples plays out in the C
editions of both NOVAS and SOFA.
D.1
Goal
These tests were designed to compare the transformation from GCRS to ITRS using the IAU
2000A/2006 models for precession and nutation. We compared the CIO-based method in
NOVAS C3.0 at full accuracy with a C translation of the example in section 5.5 of the SOFA
Cookbook titled “IAU 2006/2000A, CIO based, using classical angles.” The goal was to
verify that the NOVAS libraries, which are (mostly) independent of SOFA, produced results
that agree with their SOFA counterparts at a level that is at least an order of magnitude better
than the best observational results.
D.2
Procedure
The comparison of the C editions of NOVAS and SOFA was based on an earlier comparison
of the Fortran editions, which is described in Appendix D of the User’s Guide to NOVAS
Version F3.0 51 (Fortran section of this circular). The C test functions were basically a linefor-line transliteration of the Fortran terceltest.f and SOFA-TEST.f using the NOVAS and
SOFA C functions, respectively. User’s Guide to NOVAS Version F3.1 includes complete
code for the full text of the NOVAS test program, terceltest.f and SOFA-TEST.f.
49
http://www.iausofa.org/
http://tai.bipm.org/iers/conv2003/conv2003_c5.html
51
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-180
50
C-121
Function terceltest is provided in the addendum; it was run using the following input
parameters:
•
Universal Time: UT1 = 2400000.5 + 54195.4999991658 days (Julian date)
The UT1 value is divided into two parts, i.e., two separate arguments, because of the
large number of significant digits needed for precise results. The best agreement
between NOVAS and SOFA was obtained when UT1 was split in the exactly the
same place. In the Fortran tests, splitting the date differently produced differences of
about 3 microarcseconds.
•
Difference between TT and UT1: ∆T = 65.25607389 s
SOFA does not use ∆T; this value is the difference between the TT and UT1 Julian
dates in the SOFA example, expressed in seconds.
•
Polar coordinates: XP = 0.0349282, YP = 0.4833163 arcsec
•
CIP offsets: DX = 0.1725, DY = -0.265 arcsec
The SOFA function iauNut06a includes small corrections to the nutation series arising from
the P03 precession that are not used in the NOVAS calculations. The corrections amount to
only a few microarcseconds for current dates.
NOVAS does not directly produce an overall GCRS-to-ITRS rotation matrix as SOFA does.
The NOVAS rotation matrix was constructed simply by passing the three vectors, (1,0,0),
(0,1,0), and (0,0,1), in succession through function ter2cel.
A series of tests was done, with and without corrections for polar motion, precession and
nutation, and the P03 correction in SOFA. The output of the C functions was compared with
output from the corresponding Fortran programs. Both the Fortran and C computations were
executed on a 32-bit Intel Apple Macintosh system running the Leopard (Mac OS X 10.5)
operating system.
D.3
Results
Table D1 shows that the latest C releases of NOVAS and SOFA agree at the submicroarcsecond level in the transformation between the celestial and terrestrial reference
systems when the same Earth orientation parameters and conventions are used. In this case,
including the P03 corrections in the SOFA nutation adds a discrepancy on the order of
1.4 µas. Inclusion of the CIP offsets and polar motion does not significantly add to the
differences in the two formulations, as long as the parameters used are identical in the two
cases. Use of the external CIO_RA file in the NOVAS calculation adds about 0.05 µas to
the difference for the above case, while using the equinox method for the NOVAS
computations does not have a significant effect on the results.
The results presented in Table D1 were obtained by computing the GCRS to ITRS
transformations for the single time discussed in the SOFA Cookbook. Therefore, the values
should be typical.
C-122
Table D1. Comparison of NOVAS C3.0 and SOFA C
Corrections Applied
Other Options
Polar
CIP
P03
External
Equinox
Difference
Motion
Offsets
Terms
method
CIO_RA
(µas)
No
No
No
No
No
0.25814
No
No
Yes
No
No
1.6752
No
Yes
Yes
No
No
1.6728
Yes
Yes
Yes
No
No
1.6735
Yes
Yes
No
No
No
0.28679
Yes
Yes
No
Yes
No
0.34369
Yes
Yes
No
No
Yes
0.28644
D.4
References
Capitaine, N., Wallace, P. T., Chapront, J. 2003, A&A, 412, 567 (P03)
Kaplan, G., Bartlett, J., Monet, A., Bangert, J., & Puatua, W., 2009, User’s Guide to NOVAS
F3.0 (Washington, DC: USNO)
http://www.usno.navy.mil/USNO/astronomical-applications/publications/circ-180
IAU. 2009a, Standards of Fundamental Astronomy, (SOFA) http://www.iausofa.org/
IAU. 2009b, SOFA Tools for Earth Attitude, Software version 4, Document revision 1.1
(SOFA Cookbook) http://www.iausofa.org/sofa_pn.pdf
IERS. 2003, Conventions 2003: Chapter 5 Transformation Between the Celestial and
Terrestrial Systems (Frankfurt, Germany: BKG)
http://tai.bipm.org/iers/conv2003/conv2003_c5.html
Monet, A., Kaplan, G., & Harris, W. Testing Coordinate Frame Transformations
NOVAS vs SOFA, USNO/AA Technical Note 2010-04 (Washington, DC: USNO)
C-123
D.5
Addendum:
NOVAS C3.0 Code
void terceltest ()
{
/* Transform vectors from ITRS to GCRS */
double tjdh, tjdl, xp, yp, delt = 65.25607389, vec1[3], vec2[3], tjd,
dx, dy, mobl, tobl, ee;
short num = 0;
FILE *In_Data = NULL;
dx = +0.1750;
dy = -0.2259;
/* Open the input file of Julian dates,CIO coords,ITRS vector */
In_Data = fopen ("tercel-test-input.dat","r");
while (!feof(In_Data))
{
fscanf(In_Data,"%hi%lf%lf%lf%lf%lf%lf%lf",&num,&tjdh,&tjdl,
&xp,&yp,&vec1[0],&vec1[1],&vec1[2]);
/*
Set transformation method, accuracy level, and ut1-utc. */
tjd = tjdh + tjdl;
/*
celpol (tjd,2,dx,dy);*/
e_tilt (tjd,0, &mobl,&tobl,&ee,&dx,&dy);
/*
Rotate vec1 from ITRS to GCRS = vec2
*/
ter2cel (tjdh,tjdl,delt,1,0,0,xp,yp,vec1, vec2);
printf ("%i
%20.17f
%20.17f
"
" %20.17f\n",num,vec2[0],vec2[1],vec2[2]);
}
fclose (In_Data);
}
(Return to Table of Contents)
C-124
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : Yes Author : John Bangert, Wendy Puatua, George Kaplan, Jennifer Bartlett, William Harris, Amy Fredericks, Alice Monet Category : software documentation Comments : Company : US Naval Observatory Create Date : 2011:03:31 14:40:19-04:00 Manager : Modify Date : 2011:03:31 14:46:34-04:00 Source Modified : D:20110331182555 Subject : Naval Observatory Vector Astrometry Software Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Metadata Date : 2011:03:31 14:46:34-04:00 Creator Tool : Acrobat PDFMaker 9.1 for Word Document ID : uuid:a9637a6a-58e9-489a-bef7-c8ce0283ca60 Instance ID : uuid:0ddc3f33-7475-4a90-a0a2-bbc3e532db7f Format : application/pdf Title : User's Guide to NOVAS Version C3.1 Description : Naval Observatory Vector Astrometry Software Creator : John Bangert, Wendy Puatua, George Kaplan, Jennifer Bartlett, William Harris, Amy Fredericks, Alice Monet Producer : Adobe PDF Library 9.0 Keywords : Headline : Naval Observatory Vector Astrometry Software Page Layout : OneColumn Page Count : 124EXIF Metadata provided by EXIF.tools