This package provides routines to open, read, and interpolate the
JPL Planetary Ephemeris in FITS format. The JPL ephemerides provide
the positions and motions of the major planetary bodies in the solar
system, including the earth, moon and sun, to very high precision.
The JPL ephemerides are provided as blocks of Chebyshev coefficients,
which, when interpolated, reproduce the original JPL numerical
integrations within 1.5 cm.

This package has been tested and verified using the JPL planetary
ephemerides DE200 and DE405. The raw files provided by JPL must be
converted to FITS format using the BINEPH2FITS utility found in the
AXBARY package. For convenience, FITS format ephemerides for the
years 1950-2050 are provided by FTP. Users must also have the IDL
Astronomy Library installed in order to access the FITS files.

Using this package is rather straightforward. There are
essentially two steps involved. First, the ephemeris file is opened
and read with JPLEPHREAD; second, the table is interpolated to the
desired date and time. Here is an example of finding the position of
the earth on New Year's Day, 2000:

Here, the requested date was JD 2451544.5, the julian date of the
new year. The cartesian position of the planet earth is returned in
xearth, yearth and zearth, in astronomical units. Users can also
request other units, and body velocities are also available. By
default the origin of coordinates is the solar system barycenter, but
any body can be chosen for the origin.

The procedure JPLEPHTEST is provided to test the ephemeris
interpolation routines based on test data sets provided by JPL. The
new procedure JPLEPHMAKE can be used to generate new ephemeris tables,
based on tabulated positions and velocities, for use with
JPLEPHINTERP.

Full package -- I am also making a full package available,
which contains programs, FITS-format DE200 and DE405 ephemerides from
1950-2050, and test data provided by JPL. Beware, these files are
more than 16 MB each!

The routines GEOGREAD and GEOGRAV read gravitational potential
model files and interpolate them to the desired position.

GEOGREAD is used to read a geopotential file into memory. The user
must have a description file which contains a description of
the model in IDL syntax. The format of this file is described in the
documentation of GEOGREAD. The actual model coefficients must be in a
file of the same root name. This routine is designed to read
coefficients from standard model files available on the internet; the
description file contains entries which describe which character
columns from the input file contain the appropriate data.

Once the data have been read into memory, the geopotential can be
expanded to any position outside of the body using GEOGRAD. Both the
gravitational potential and the acceleration are computed at the
desired positions. Users can limit the calculation to lower degree or
order than is available. Several choices of units are also
available.

Below are the routines and description files for several popular
gravitational models. Within the description file is the URL where
the original data can be downloaded (I can also supply the models upon
request).

The procedure HPRNUTANG computes values of the earth
orientation-related angles, including precession and nutation, which
are used for high precision earth-based astronomy applications.

It is the goal of this procedure to provide all angles relevant in
determining the position of an earth station, as measured in an
earth-fixed coordinate system, and converting to space-fixed
coordinates. This is useful in applications where observations by a
station in the earth-fixed frame are taken of an astrophysical object
which is in the non-rotating space-fixed frame.

The procedure EOPDATA reads, interpolates and returns Earth
orientation parameters used for precision earth-base astronomy
applications. The values returned are PMX and PMY (series for polar
motion); UT1-UTC (series for earth rotation); and DEPS and DPSI
(corrections to the standard IAU 1980 Earth nutation model). These
quantities are available from the International Earth Rotation Service
web page.

The procedure HPRSTATN computes the coordinates and velocities of
an earth station, whose position is known in the ITRF, in J2000
equatorial earth-centered inertial coordinates (ECI). This may be
useful in any application where an earthbound observatory is used to
collect data on a non-terrestrial phenomenon.

NOTE: The user is responsible for downloading and maintaining an
up-to-date file of earth orientation parameters from the International
Earth Rotation Service. These can be found at one of the IERS web
pages:

The function SRVADD performs addition of velocity 3-vectors
according to special relativity. SRVADD operates in two inertial
frames, a "lab" or stationary frame, and a "rocket" or moving frame
(moving at vector velocity V with respect to the lab). Another body
is moving with vector velocity U1 as measured from the rocket frame.
The function SRVADD computes the vector velocity of the body as seen
from the lab frame.

This routine handles arbitrary 3-vector velocities. None of the
velocities are constrained to lie along the X-axis.

The function SRVDOPP computes the relativistic doppler shift
between two inertial reference frames. SRVDOPP computes the doppler
shift of a photon as observed in the "rocket" frame, whose direction
and frequency are known in the "lab" frame. This routine handles
arbitrary 3-vector velocities and photon propagation directions, and
thus by definition the transverse doppler effect.

The function TDB2TDT computes relativistic corrections that must be
applied when performing high precision absolute timing in the solar
system.

According to general relativity, moving clocks, and clocks at
different gravitational potentials, will run at different rates with
respect to each other. Thus, for the most demanding astrophysical
timing applications, times in the accelerating earth observer's frame
must be corrected to an inertial frame, such as the solar system
barycenter. This function provides the most important correction
term: from clocks at the geocenter (TT) to the solar system barycenter
(TDB), hence the name TDB2TT. The user is responsible for the
observatory-dependent components, described in the documentation.

The method of computation of TDB2TDT in this function is based on
the analytical formulation by Fairhead, Bretagnon & Lestrade, 1988
(so-called FBL model) and Fairhead & Bretagnon 1990, in terms of
sinusoids of various amplitudes. TDB2TDT has a dominant periodic
component of period 1 year and amplitude 1.7 ms. The set of 791
coefficients used here were drawn from the Princeton pulsar timing
program TEMPO version 11.005 (Taylor & Weisberg 1989).

The function TAI_UTC computes the difference between International
Atomic Time (TAI) and Universal Coordinated Time (UTC), in seconds.

After 01 Jan 1972, the two time systems are synchronized, except
for a number of leap seconds added to account for the varying rate of
rotation of the earth. While TAI is a continuous atomic time system,
UTC is a civil time system which may have discontinuities where leap
seconds are introduced. This function computes the differences
between the two time systems.

The function TZOFFSET computes the time zone offset between the
local time zone and GMT for any date.

The time zone offset is defined here as the number of seconds of
time West of the Greenwich Meridian. Equivalently, it is the
number of seconds that must be *added* to local time in order to
transform it to GMT.

The user may input the date, T, as either seconds elapsed since
1970-01-01T00:00:00, or in Julian days (if /JULIAN is set). The
input time may be either expressed in the user's local time zone
(if /LOCAL is set) or in UTC.

The results of TZOFFSET are only as good as your operating system's
timezone information. If your system's timezone tables are
incomplete or erroneous, then so will be TZOFFSET's output.

TZOFFSET computes the timezone offsets for your system's current
time-zone. To compute the offset for another different time zone,
you will need to reset your system's notion of the timezone. On
Unix and Mac OS X systems, this can be done by setting the "TZ"
environment variable with SETENV.

The function JBEPOCH computes the Julian or Besselian Epoch year
number from a given Julian day number. Epochs of this form are often
given in the astronomical literature as B1950.0 or J2000.0, but they
can be different.

Besselian year numbers are measured in tropical years of about
365.2422 days. Julian year numbers are measured in years whose
lengths are exactly 365.25 days of 86400 second lengths. The "/J" or
"/B" keywords identify which year numbering system is being used.

JBEPOCH also computes the inverse transformation, from Julian or
Besselian epoch to Julian Day, by specifying the /TO_DAY keyword.

The procedures LITMSOL and LITMSOL2 solve the light time equation between two
moving bodies in the solar system. Given the time and position of
reception or transmission of a photon, this equation determines the
time of transmission or reception at the other solar system body.
Since both bodies may be moving, the equation must be solved
iteratively.

LITMSOL (OBSOLETE) requires the trajectories of solar system bodies
to be described by either a JPL ephemeris, or by a JPL-like ephemeris
generated by JPLEPHMAKE. This routine calls JPLEPHINTERP.

LITMSOL2 is more flexible and allows the trajectory of the body to
be described by any IDL function. The user is required to define this
function, which could, for example, perform a lookup of a JPL-like
trajectory ephemeris. LITMSOL2 also allows user-defined "extra"
delays, which might include Shapiro delay or spacecraft transponder
delays.